diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md index fb548969..ab757891 100644 --- a/docs/architecture/starter-experience.md +++ b/docs/architecture/starter-experience.md @@ -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 diff --git a/src/application/ports/auth-session-port.ts b/src/application/ports/auth-session-port.ts index 818b6bc5..f3ae46f5 100644 --- a/src/application/ports/auth-session-port.ts +++ b/src/application/ports/auth-session-port.ts @@ -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;