docs(auth): document what readSubject must return and the fail-closed default (R3-3)
readSubject/getSubject must be an opaque, non-empty id that is stable per user and never a token. Without it, every authenticated notification clears server state. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
55721f075a
commit
e0b20f50db
@@ -53,6 +53,20 @@ An external owner implements `readState`, `subscribe`, `beginSignIn`,
|
||||
`signOut`, `attachCredential`, `recoverSession`, and
|
||||
`notifyUnauthenticated`. It owns token acquisition and storage.
|
||||
|
||||
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:
|
||||
|
||||
- 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
|
||||
- `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.
|
||||
|
||||
## Extending the starter
|
||||
|
||||
The steps below describe the current extension path. New platform work should follow
|
||||
|
||||
@@ -9,8 +9,11 @@ export type SessionGateway = Readonly<{
|
||||
/**
|
||||
* Optional opaque identifier of the signed-in subject. The server-state scope
|
||||
* fences only when (state, subject) changes, so a token refresh does not clear
|
||||
* the cache. An authenticated session that returns `null` or omits this is
|
||||
* treated as possibly switched and still fences on every notification.
|
||||
* the cache. Return a non-empty string that is stable for one user across
|
||||
* refreshes and differs between users (for example a hashed account id), or
|
||||
* `null` when nobody is signed in. Never return a token or other credential.
|
||||
* An authenticated session that returns `null`, `""` or omits this is treated
|
||||
* as possibly switched: every notification fences and clears server state.
|
||||
*/
|
||||
getSubject?(): string | null;
|
||||
subscribe(listener: () => void): () => void;
|
||||
|
||||
Reference in New Issue
Block a user