7e22f1260b
Extract the post-verify orchestration shared across passkey register-finish, passkey login-finish, magic-link verify-code, and magic-link click-through into a single completeAuth function. Two ADRs record the decision: - ADR-0004: centralize web auth completion (record terms + create session + redirect) in apps/journal/app/lib/auth/completion.ts. - ADR-0005: explicitly no AuthMethod polymorphism. Passkey + magic- link is the entire identity surface; OAuth2/PKCE is session transport, not a peer method. Recorded as a negative decision so future architecture passes don't re-suggest extracting the interface. CONTEXT.md gains an Authentication section covering completeAuth, the two methods, the OAuth2-as-transport distinction, and where the Terms gate enforcement lives (root loader for web, requireApiUser for API per the just-merged mobile-terms-gate). OpenSpec change unify-auth-completion captures the proposal, design (5 decisions including the negative-scope choices), spec delta on authentication-methods, and 14 tasks. Implementation follows on this branch. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
40 lines
2.3 KiB
Markdown
40 lines
2.3 KiB
Markdown
# No `AuthMethod` polymorphism — passkey + magic-link is the entire surface
|
|
|
|
A natural temptation when reshaping auth is to extract an
|
|
`AuthMethod` interface (analogous to the connected-services
|
|
`Importer` / `RoutePusher` / `WebhookReceiver` capability seams) so
|
|
passkey and magic-link become two adapters of a common shape, with
|
|
future Google/Apple/SAML/etc. as additional adapters. We are
|
|
explicitly **not** doing that, and recording the negative decision
|
|
here so future architecture passes don't re-suggest it.
|
|
|
|
Two reasons. First, the *number of adapters is fixed*: passkey is
|
|
trails.cool's preferred identity method and magic-link is its
|
|
fallback for browsers without WebAuthn support and cross-device sign-
|
|
in. There are no plans for additional methods. Social sign-in (Google,
|
|
Apple) would conflict with the privacy-first ethos in `CLAUDE.md`
|
|
(third-party identity providers see every login), would fight the
|
|
ActivityPub federation model (centralized OIDC vs.
|
|
`user@domain` identity), and would add account-linking edge cases
|
|
without a UX win — passkeys already deliver the one-tap convenience
|
|
that justifies social sign-in elsewhere. With two adapters and no
|
|
forecast third, an `AuthMethod` interface is theoretical
|
|
polymorphism with no future second customer; the deletion test fails.
|
|
|
|
Second, the *interface shape would be shallow*. WebAuthn is a
|
|
multi-step ceremony (start → finish, with challenge persistence
|
|
between calls); magic-link is a request-then-verify flow with a
|
|
15-minute token in the database. Forcing both into a unified
|
|
`startAuth(input) → finishAuth(response)` interface produces an
|
|
adapter where each implementation barely shares a type signature —
|
|
the two flows have genuinely different shapes, and the seam would
|
|
fill with optional methods and discriminated unions. The real
|
|
repetition lives in the *post-verify orchestration* (record terms,
|
|
mint session, redirect), which ADR-0004 addresses with a single
|
|
`completeAuth` function — no polymorphism required.
|
|
|
|
OAuth2/PKCE in the `mobile-app` change is sometimes mistaken for a
|
|
third auth method. It isn't: mobile users still authenticate via
|
|
passkey or magic-link in a WebView, and OAuth2 only exchanges the
|
|
resulting code for long-lived bearer tokens. OAuth2 is **session
|
|
transport** (peer of: HTTP-only cookie), not identity proof.
|