ADR-004: Works Square Owns The Desktop Authentication Lifecycle Boundary

Status

Accepted and implemented on 2026-08-19.

Context

The desktop client obtained tokens from Works Square but refreshed them directly against the custom identity service with an embedded OAuth client secret. That mixed issuer/client boundary made rotation dependent on two independently configured clients and could turn an otherwise valid persisted session into invalid_grant, returning the user to the login page hours later.

Decision

Renderer sends authentication operations only to Electron Main.
Electron Main owns access/refresh tokens, encrypted persistence, refresh rotation, terminal failure cleanup, and the seven-day inactivity policy.
Desktop login, mobile login, refresh, and logout use fixed Works Square /api/auth/* endpoints.
Works Square owns the confidential upstream OAuth client configuration and proxies the lifecycle to the identity service.
The desktop bundle must not contain an OAuth client secret or call the custom identity service directly.

Consequences

The matching Works Square server endpoints must be deployed before this client is released.
OAuth credential rotation or upstream endpoint changes are server-side configuration changes rather than desktop releases.
A terminal refresh 400 or 401 still fails closed and clears the local session; transient failures preserve the established retry behavior.

Evidence

Source commit: dc776ff
Integration merge: f52c2c8
Feature verification: 2,190 client tests passed, typecheck passed, Vite build passed, and lint reported no errors.

1.6 KiB Raw Blame History