Merge fix/session-subject-required: require readSubject on the external session owner
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -45,23 +45,35 @@ remain opaque to the application and presentation layers.
|
||||
- `external`: delegates to `globalThis.__CA_FRONTEND_AUTH_OWNER__`
|
||||
- missing/invalid external owner: fails closed as `integration-failed`
|
||||
|
||||
An external owner implements `readState`, `subscribe`, `beginSignIn`,
|
||||
`signOut`, `attachCredential`, `recoverSession`, and
|
||||
`notifyUnauthenticated`. It owns token acquisition and storage.
|
||||
An external owner implements `readState`, `readSubject`, `subscribe`,
|
||||
`beginSignIn`, `signOut`, `attachCredential`, `recoverSession`, and
|
||||
`notifyUnauthenticated`. It owns token acquisition and storage. An owner that
|
||||
lacks any of these methods is rejected, and the session fails closed as
|
||||
`integration-failed`.
|
||||
|
||||
The owner may also implement `readSubject()`. The server-state cache is cleared
|
||||
only when the session state or the subject changes, so a token refresh for the
|
||||
same user keeps cached data. `readSubject()` must return:
|
||||
`readSubject()` is required. The server-state cache is cleared only when the
|
||||
session state or the subject changes, so a token refresh for the same user
|
||||
keeps cached data. `readSubject()` must return:
|
||||
|
||||
- an opaque, non-empty string that stays the same for one user across token
|
||||
refreshes and differs between users, such as a hashed account id
|
||||
refreshes and differs between users: the OIDC `sub` claim, Supabase
|
||||
`session.user.id`, or Firebase `user.uid`
|
||||
- `null` when nobody is signed in
|
||||
- never an access token, refresh token, or any other credential
|
||||
|
||||
Without `readSubject()` (or when it returns `null` or `""` while
|
||||
authenticated), the runtime cannot tell a refresh from an account switch, so
|
||||
every notification from an authenticated owner clears server state. This is the
|
||||
safe default. The `demo` adapter reports one fixed demo user as its subject.
|
||||
If `readSubject()` returns `null` or `""` while the owner reports
|
||||
`authenticated`, the runtime cannot tell a refresh from an account switch. It
|
||||
fails closed: every such notification clears server state, and each one records
|
||||
the `cache.operation.failed` diagnostic with `operation: SCOPE_FENCE` and
|
||||
`reason: SUBJECT_MISSING`. Seeing that diagnostic means the owner is not
|
||||
reporting its subject. The `demo` adapter reports one fixed demo user as its
|
||||
subject.
|
||||
|
||||
Migration: `readSubject()` used to be optional. An owner written for an earlier
|
||||
release must add it; without it the owner is rejected at startup (the session
|
||||
becomes `integration-failed`) and a TypeScript owner no longer compiles
|
||||
against `ExternalSessionOwner`. A code path that implements `AuthSessionPort`
|
||||
or `SessionGateway` directly must add `getSubject()` the same way.
|
||||
|
||||
## Extending the starter
|
||||
|
||||
|
||||
Reference in New Issue
Block a user