An external owner without readSubject made every authenticated
notification (every token refresh) abort requests and clear the
server-state cache. readSubject is now a required owner method and
getSubject a required SessionGateway method.
- ExternalSessionOwner.readSubject(): required; the host owner check
(EXTERNAL_OWNER_METHODS) rejects an owner without it, so the session
fails closed as integration-failed like any other missing method.
- SessionGateway.getSubject(): required. Anonymous and unavailable
adapters return null; demo already returned its fixed user.
- Scope runtime: same (state, subject) still skips the fence; a state
or subject change still fences. An authenticated session with a
null/empty subject still fences (fail closed) and now records
cache.operation.failed {operation: SCOPE_FENCE, reason:
SUBJECT_MISSING} once per fence. Bootstrap passes diagnostics in.
- Docs: starter-experience external owner section and port comments
describe what readSubject returns, the fail-closed diagnostic and a
migration note.
RED before the change (vitest tests/unit/server-state-scope-runtime.test.ts
tests/unit/runtime-adapters.test.ts): 4 failed | 31 passed
- fails closed when the owner lacks readSubject:
expected 'authenticated' to be 'integration-failed'
- fences and reports SUBJECT_MISSING ... null / empty subject, and the
external owner whose readSubject returns null:
expected [] to deeply equal [[{ level: 'warn', ... }]]
- type level: an owner literal without readSubject compiled (tsc exit
0). The new @ts-expect-error pin fails check:types:test with TS2578
if readSubject becomes optional again.
Pins that stayed green: same-subject token refresh keeps the cache,
subject change fences, sign-out fences, owner missing readState is
rejected.
GREEN: check:architecture, check:types:app, check:types:test, lint,
test:unit (2084), test:component (182), test:reference-feature (59),
test:integration (151), verify:documentation, check:diagnostics,
check:ci all pass.
BREAKING: external auth owners must implement readSubject(); code that
implements AuthSessionPort/SessionGateway directly must implement
getSubject().
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
65 lines
2.2 KiB
TypeScript
65 lines
2.2 KiB
TypeScript
export type SessionState =
|
|
| "authenticated"
|
|
| "unauthenticated"
|
|
| "recovery-pending"
|
|
| "integration-failed";
|
|
|
|
export type SessionGateway = Readonly<{
|
|
getState(): SessionState;
|
|
/**
|
|
* 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. Return a non-empty string that is stable for one user across
|
|
* refreshes and differs between users (OIDC `sub`, Supabase
|
|
* `session.user.id`, Firebase `user.uid`), or `null` when nobody is signed
|
|
* in. Never return a token or other credential. An authenticated session that
|
|
* returns `null` or `""` is treated as possibly switched: every notification
|
|
* fences, clears server state and records `cache.operation.failed` with
|
|
* reason `SUBJECT_MISSING`.
|
|
*/
|
|
getSubject(): string | null;
|
|
subscribe(listener: () => void): () => void;
|
|
beginSignIn(returnTo?: string): Promise<void>;
|
|
signOut(): Promise<void>;
|
|
/**
|
|
* LEG-01. Recovery is part of a request's lifetime, so it receives the same
|
|
* context a credential attach does. The context is optional for one release
|
|
* to keep existing owners working; the transport races the signal either way,
|
|
* and a recovery that answers after the request already ended is observed but
|
|
* never turned into a user-visible sign-out.
|
|
*/
|
|
recover(
|
|
context?: CredentialOperationContext,
|
|
): Promise<"restored" | "no-session">;
|
|
}>;
|
|
|
|
export type CredentialRequestBinding = Readonly<{
|
|
origin: string;
|
|
method: string;
|
|
operationId: string;
|
|
}>;
|
|
|
|
export type CredentialPatch = Readonly<{
|
|
headers: Readonly<Record<string, string>>;
|
|
}>;
|
|
|
|
/**
|
|
* §8.5. The transport lifetime handed to a credential owner. A cooperative
|
|
* owner abandons its own work on abort; a non-cooperative one is still bounded
|
|
* because the transport races the same signal.
|
|
*/
|
|
export type CredentialOperationContext = Readonly<{
|
|
signal: AbortSignal;
|
|
deadlineAtMonotonicMs: number;
|
|
}>;
|
|
|
|
export type CredentialAttacher = Readonly<{
|
|
credentialPatch(
|
|
binding: CredentialRequestBinding,
|
|
context?: CredentialOperationContext,
|
|
): Promise<CredentialPatch>;
|
|
onUnauthenticated(): void;
|
|
}>;
|
|
|
|
export type AuthSessionPort = SessionGateway & CredentialAttacher;
|