wangxuming/makelore
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
46fbae9dec70ee1bbfae671d458a81fd1d8a1c28
makelore/.project-docs/10-decisions/adr-004-square-auth-lifecycle-boundary.md
brother7 eedd20d061
Some checks failed
Electron E2E / Electron E2E (macos-latest) (push) Has been cancelled
Details
Electron E2E / Electron E2E (ubuntu-latest) (push) Has been cancelled
Details
Electron E2E / Electron E2E (windows-latest) (push) Has been cancelled
Details
docs(integration): record remember password boundary
2026-08-20 23:45:13 +08:00

2.5 KiB
Raw Blame History

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.
  • Optional remembered username/password data is a separate Electron Main record. Packaged builds encrypt it with OS-protected storage; it is never Renderer-persisted or stored by Works Square.
  • 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.
  • Logout and mobile login preserve remembered-password data. A successful password login with the option cleared removes the previous record; unavailable secure storage disables the option.

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.
  • Remembered-password persistence is convenience behavior rather than session authority. Its failure must not grant authentication or move password persistence to Works Square/Renderer.
  • Packaged Windows and signed macOS still require a smoke covering save, restart restore, unchecked-login clear, and the absence of a development Keychain prompt.

Evidence

  • Source commit: dc776ff
  • Integration merge: f52c2c8
  • Feature verification: 2,190 client tests passed, typecheck passed, Vite build passed, and lint reported no errors.
  • Remember-password source/integration: 990639f / 2b9f84e; 79 focused tests, typecheck, scoped lint, and Renderer/Main/Preload/utility build passed.