@idp.global/sdk 18.0.1 → 18.2.0

package/readme.md

@@ -2,7 +2,7 @@
 
 Reusable TypeScript SDK for building against idp.global from both sides of the wire: browser apps that need SSO, JWT housekeeping, transfer-token handoff, and typed IdP requests; and server apps that need explicit account storage, local password auth, optional idp.global password verification, and confidential OIDC membership introspection.
 
-The package is intentionally split by runtime. Use `@idp.global/sdk/browser` in browser bundles and `@idp.global/sdk/server` in Node.js services. The root `@idp.global/sdk` export does not expose application APIs.
+The package is intentionally split by runtime. Use `@idp.global/sdk/browser` in browser bundles, `@idp.global/sdk/server` in Node.js services and `@idp.global/sdk/relyingparty` for a server application that signs its users in through idp.global. The root `@idp.global/sdk` export does not expose application APIs.
 
 ## Issue Reporting and Security
 
@@ -14,6 +14,7 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 | --- | --- | --- |
 | Browser | `@idp.global/sdk/browser` | SSO client, JWT and refresh-token storage, login redirects, logout, transfer-token exchange, and typed request shortcuts for user, organization, billing, OIDC, and admin flows. |
 | Server | `@idp.global/sdk/server` | NoSQL-backed account store, scrypt password hashing, local/idp.global account authentication, a server-side typed-socket client for idp.global password login, and confidential OIDC introspection. |
+| Relying party | `@idp.global/sdk/relyingparty` | The OIDC relying-party session layer: authorization code flow with PKCE on `openid-client`, login attempts and HttpOnly cookie sessions with CSRF tokens on NoSQL, sealed provider tokens rotated under a cross-replica lock, live organization authority, HTTP login routes, a TypedRouter actor scope and TypedSocket session binding. |
 
 ## Install
 
@@ -21,8 +22,9 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 pnpm add @idp.global/sdk
 ```
 
-The server subpath additionally requires the peer dependency `@lossless.org/client`,
-which provides the `SmartdataDb` the account store persists through:
+The server and relying-party subpaths additionally require the peer dependency
+`@lossless.org/client`, which provides the `SmartdataDb` the account store and the
+session models persist through:
 
 ```bash
 pnpm add @lossless.org/client
@@ -349,6 +351,16 @@ existing login and principal binding and make a fresh observation for each
 operation requiring live authority. The response contains no identity profile
 or email-based organization inference.
 
+`AuthorityObserver` in `@idp.global/sdk/relyingparty` follows this contract by
+default: `positiveTtlMs` and `negativeTtlMs` are `0`, so every operation is
+observed freshly. An application may opt into reusing a positive observation for
+a bounded time (`positiveTtlMs`) and, separately, a refusal (`negativeTtlMs`),
+per login session and organization. The trade-off is explicit: a membership
+removed, a role lowered or an app connection revoked at idp.global takes effect
+in that application only once the reused answer expires — up to the configured
+TTL — while ending the login session in the application drops its reused answers
+at once. A failure to observe is never reused.
+
 ### Server-held OIDC UserInfo
 
 Use `OidcUserInfoClient` to obtain current profile and organization picker data
@@ -421,6 +433,205 @@ The server export includes these TypeScript types:
 | `IIdpGlobalServerClientOptions` | Server client configuration with optional `baseUrl` and `backendToken`; defaults to `https://app.idp.global`. |
 | `IIdpPasswordAuthResult` | Privacy-safe current-user DTO, JWT, and refresh-token result. |
 
+## Relying-Party Sessions
+
+`@idp.global/sdk/relyingparty` is the session layer of a server application that
+signs its users in through idp.global. The application supplies its database,
+its keys and what a verified subject means to it; the module runs everything in
+between.
+
+```ts
+import * as nosqldb from '@lossless.org/client/nosqldb';
+import {
+  AuthorityObserver,
+  createRelyingPartyModels,
+  IdpOidcProvider,
+  RelyingPartyRoutes,
+  RelyingPartySessions,
+  decodeSecretKey,
+} from '@idp.global/sdk/relyingparty';
+
+const provider = new IdpOidcProvider({
+  issuer: new URL('https://idp.global'),
+  clientId: process.env.IDP_CLIENT_ID!,
+  clientSecret: process.env.IDP_CLIENT_SECRET!,
+  redirectUri: new URL('/auth/callback', 'https://app.example'),
+});
+await provider.init();
+
+const models = createRelyingPartyModels({ db: smartdataDb });
+await models.Session.ensureInitialized();
+await models.LoginAttempt.ensureInitialized();
+
+let authority: AuthorityObserver<'manage' | 'read'>;
+const sessions = new RelyingPartySessions({
+  models,
+  provider,
+  publicOrigin: 'https://app.example',
+  sessionEncryptionKey: decodeSecretKey(process.env.SESSION_ENCRYPTION_KEY!, 'SESSION_ENCRYPTION_KEY'),
+  csrfKey: decodeSecretKey(process.env.CSRF_HMAC_KEY!, 'CSRF_HMAC_KEY'),
+  principals: {
+    // create or update the local user; throw RelyingPartyRefusal to refuse the login
+    admit: async (completion) => ({ principalId: await users.upsertFromIdp(completion) }),
+    isActive: async (principalId) => users.isActive(principalId),
+  },
+  hooks: {
+    onSessionEnded: ({ sessionId, revokedHere }) => {
+      authority.forgetSession(sessionId);
+      if (revokedHere) socketGate.closeSession(sessionId);
+    },
+  },
+});
+
+authority = new AuthorityObserver({
+  provider,
+  tokens: sessions,
+  project: (roles) => (roles.includes('owner') ? 'manage' : roles.includes('viewer') ? 'read' : undefined),
+});
+
+const routes = new RelyingPartyRoutes({ sessions, failureLocation: '/?auth=error' });
+typedServer.addRoute('/auth/*', 'ALL', routes.handle);
+```
+
+What it does:
+
+- **Login**: `GET /auth/login?return=/path` stores one login attempt (state and
+  browser binding stored as SHA-256, PKCE verifier sealed) and redirects to the
+  provider. `GET /auth/callback` consumes the attempt exactly once, exchanges
+  the code, reads UserInfo with a subject check, calls `principals.admit` and
+  opens a session; a provider `error` abandons the attempt. `GET /auth/finalize`
+  releases the return path only to the browser holding the session that attempt
+  created. Return paths stay on the public origin and outside the login routes.
+  Expired attempts are swept when the next login starts.
+- **Sessions**: an HttpOnly, `SameSite=Lax` cookie whose token is stored as a
+  hash, touched at most once a minute, with a CSRF token derived per request as
+  an HMAC of the cookie token. `GET /auth/session` answers the session and
+  `POST /auth/logout` needs the public origin and the CSRF token; its body is
+  cancelled as soon as it passes `maxBodyBytes`. Every end of a session is one
+  conditional update; its provider tokens go back to idp.global within a
+  three-second budget afterwards, and so do the tokens of a login that failed
+  after the code exchange.
+- **Provider tokens**: sealed with AES-256-GCM (`SecretBox`) and rotated shortly
+  before they expire, once per process and under a lock stored on the session,
+  so two replicas never spend one refresh token. A refused refresh ends the
+  session; an unreachable provider fails closed.
+- **Live authority**: `AuthorityObserver.observe({ loginSessionId, principalId,
+  idpOrganizationId })` introspects the organization with the session's live
+  token and projects the role keys through the application's table. It answers
+  a grant or throws `AuthorityRefusedError` (with `firstRefusal` once per
+  transition, for an audit trail) or `AuthorityTokenError`.
+- **Transports**: `createActorScope()` gives a TypedRouter request scope
+  (`addRequestScope`) that runs every dispatch as the actor its trusted local
+  data names. `RelyingPartySocketBinding` registers a TypedSocket connection
+  from its upgrade `Origin` and `Cookie` plus the page's CSRF token, pins it to
+  the session, re-validates it per request and finds a session's connections by
+  a server-owned tag. Connection limits and sweeps stay with the application.
+
+Nothing runs on a timer, and no token, cookie or sealed value ever reaches a
+log line or an error message.
+
+Application hooks never stand in the way of that cleanup. A throwing (or
+rejecting) `onSessionEnded` or `onEvent` is reported as a `hook_failed` event —
+`onEvent`'s own failure on `console.error` — and the provider tokens go back
+regardless. A throwing `onProviderSessionOpened` fails the login: the session it
+opened is revoked, its tokens are handed back and the hook's error is the
+login's cause. Custom `cookieNames` with a `__Host-` or `__Secure-` prefix need
+an https `publicOrigin`; on http the constructor refuses them, because browsers
+would silently drop those cookies.
+
+**Adopting existing session data.** The persisted fields and index declarations
+are those nevermind.finance has stored since mainapp 0b693cb. An application
+that already holds such collections binds the models to them and passes its own
+cookie names and CSRF label, so live sessions and sealed tokens keep working:
+
+```ts
+const models = createRelyingPartyModels({
+  db: smartdataDb,
+  collectionNames: { sessions: 'SessionDoc', loginAttempts: 'LoginAttemptDoc' },
+});
+const sessions = new RelyingPartySessions({
+  models,
+  cookieNames: { session: 'nm_session', intent: '__Host-nm_oidc_intent' },
+  csrfLabel: 'nevermind.finance:csrf:v1\u0000',
+  // …
+});
+```
+
+A deployment without a provider (`provider` omitted) keeps the same session
+store for sessions it opens itself with `openSession({ principalId })`, for
+example after a local password check.
+
+**Building before the database connects.** `db` may be a function that answers
+the database once it exists. It is called on every use of a model, the way
+`@Collection(() => db)` resolves it, and never while the models,
+`RelyingPartySessions`, `RelyingPartyRoutes` or `RelyingPartySocketBinding` are
+constructed — none of them does I/O in its constructor. A use before the
+function answers a `SmartdataDb` (or while it throws) rejects with
+`RelyingPartyDatabaseUnavailableError`, whose `cause` is the function's error:
+
+```ts
+const models = createRelyingPartyModels({ db: () => appDatabase.db });
+const sessions = new RelyingPartySessions({ models, /* … */ });
+// later, at startup
+await appDatabase.init();
+await models.Session.ensureInitialized();
+await models.LoginAttempt.ensureInitialized();
+```
+
+**Reading the principal once.** `principals.isActive` answers a yes or no, so a
+request that needs the user reads it a second time. Principals may give
+`resolve` instead: it answers the principal when it may act right now and
+`null` otherwise, and every live session carries that answer as `principal` —
+on `resolveCookieSession`, `revalidateLiveSession`, `RelyingPartySocketBinding.revalidate`
+and the routes' `sessionAnswer`. The principal type is inferred from `resolve`;
+with `isActive` it is `undefined`. Give exactly one of the two; the constructor
+refuses both or neither.
+
+```ts
+const sessions = new RelyingPartySessions({
+  // …
+  principals: {
+    admit: async (completion) => ({ principalId: await users.upsertFromIdp(completion) }),
+    resolve: async (principalId) => {
+      const user = await users.get(principalId);
+      return user?.status === 'active' ? user : null;
+    },
+  },
+});
+const resolved = await sessions.resolveCookieSession(cookieHeader);
+resolved?.principal.displayName; // typed as the user
+```
+
+**Recording a logout.** `RelyingPartyRoutes` takes
+`onLogout({ session, endedLiveSession })`. It runs only for a `POST
+<prefix>logout` that passed the origin and CSRF checks, after the session was
+ended, and the answer waits for it, so an audit record is written before the
+browser learns the logout is done. `endedLiveSession` is `true` only when this
+call ended a live session: a logout that lost a race to another end gets
+`false`, and a repeated logout finds no session and does not call it. A hook
+that throws or rejects never keeps the session alive and never changes the
+answer — the session is already over — and is reported as a `hook_failed`
+route event (`hook: 'onLogout'`) through `onRouteEvent`. The hook runs without
+a deadline of its own; bound a slow audit store inside it.
+
+**Socket peers.** `RelyingPartySocketBinding.tagConnection` and `upgradeOf` take
+the connection wrapper or the bare SmartServe peer (`TRelyingPartySocketPeer`),
+the two forms `TypedSocket.setServerTag` accepts.
+
+### Relying-Party API Surface
+
+| API | Description |
+| --- | --- |
+| `IdpOidcProvider` | Discovery, PKCE authorization URL, code exchange with UserInfo, refresh, revocation and organization introspection for idp.global. Implements `IOidcProvider`. |
+| `createRelyingPartyModels()` | Binds the session and login-attempt models to one `SmartdataDb`, or to a function asked for it on every use, optionally under existing collection names. |
+| `RelyingPartySessions<TPrincipal>` | Login start/complete/abandon/finalize, `openSession`, `resolveCookieSession`, `revalidateSession`, `revalidateLiveSession`, `isSessionLive`, `validateCsrf`, `logout`/`endSession`, `endSessionsOfPrincipal`, `liveProviderToken`. Principals give `isActive` or `resolve` (`IRelyingPartyPrincipals`, `IRelyingPartyPrincipalResolver<TPrincipal>`); with `resolve`, live sessions carry `principal`. |
+| `AuthorityObserver` | Live organization authority with opt-in positive and negative reuse. |
+| `RelyingPartyRoutes` | `handle(ctx)` for `/auth/login`, `/auth/callback`, `/auth/finalize`, `/auth/session` and `/auth/logout`; `null` for anything else. Takes a typedserver route context. `onLogout` is awaited after a CSRF-checked logout ended the session. |
+| `createActorScope()` | AsyncLocalStorage actor context with a TypedRouter request scope. |
+| `RelyingPartySocketBinding` | TypedSocket browser registration, per-request re-validation and session tags; takes a connection wrapper or its peer. |
+| `SecretBox`, `deriveCsrfToken()`, `decodeSecretKey()`, `parseCookies()`, `serializeCookie()`, `sanitizeReturnPath()` | The primitives underneath. |
+| `RelyingPartyError`, `RelyingPartyRefusal`, `LoginCallbackError`, `AuthorityTokenError`, `AuthorityRefusedError`, `RelyingPartyDatabaseUnavailableError` | Errors with stable codes; none carries token material. |
+
 ## Runtime Notes
 
 Use the explicit subpath imports. They keep browser bundles free of Node-only code and keep server processes free of browser storage dependencies.
@@ -438,7 +649,7 @@ The SDK uses typed sockets and typed requests from `@api.global/*`, shared idp.g
 pnpm test
 ```
 
-The test suite covers the server account store and auth service, browser transfer-token handling, typed administrative request names, and the exact backend JWT keyset and blocklist contracts.
+The test suite covers the server account store and auth service, browser transfer-token handling, typed administrative request names, the exact backend JWT keyset and blocklist contracts, and the relying-party layer: its primitives, the OIDC provider against a fetch-level issuer double, sessions and two-replica token rotation on an in-memory NoSQL engine with an injected clock, the persisted shape, the authority observer, the HTTP routes, the actor scope and the socket binding.
 
 ## License and Legal Information
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@idp.global/sdk',
-  version: '18.0.1',
+  version: '18.2.0',
   description: 'Reusable browser and server SDK for idp.global authentication.'
 }

package/ts_relyingparty/classes.actorscope.ts

@@ -0,0 +1,39 @@
+import * as plugins from './plugins.js';
+
+export interface IActorScope<TContext> {
+  /** Runs `operationArg` and everything it awaits as this actor. */
+  run<T>(contextArg: TContext, operationArg: () => T): T;
+  /** The actor of the operation in flight, or `undefined` outside one. */
+  current(): TContext | undefined;
+  /** Runs `operationArg` without any actor, for background work entered from a request. */
+  exit<T>(operationArg: () => T): T;
+  /**
+   * The request scope of a `TypedRouter` (`addRequestScope`): middleware and
+   * handler of every dispatch run as the actor the transport's trusted local
+   * data names. A dispatch without one runs without an actor.
+   */
+  readonly requestScope: plugins.typedrequest.TTypedRouterRequestScope;
+}
+
+/**
+ * An AsyncLocalStorage-backed actor context. The application decides what an
+ * actor is and how it is read from the trusted local data its transports set;
+ * nothing a handler can reach decides it.
+ */
+export const createActorScope = <TContext>(optionsArg: {
+  fromLocalData(localDataArg: Readonly<Record<string, unknown>>): TContext | undefined;
+}): IActorScope<TContext> => {
+  const storage = new plugins.asyncHooks.AsyncLocalStorage<TContext>();
+  return {
+    run: (contextArg, operationArg) => storage.run(contextArg, operationArg),
+    current: () => storage.getStore(),
+    exit: (operationArg) => storage.exit(operationArg),
+    requestScope: (_typedRequestArg, nextArg, contextArg) => {
+      const actor = optionsArg.fromLocalData(contextArg.localData);
+      if (actor === undefined) {
+        return nextArg();
+      }
+      return storage.run(actor, nextArg);
+    },
+  };
+};

package/ts_relyingparty/classes.authorityobserver.ts

@@ -0,0 +1,253 @@
+import { AuthorityTokenError } from './classes.errors.js';
+import { OidcAuthorityUnavailableError, type IOidcProvider } from './classes.idpoidcprovider.js';
+import type { IAuthorityTokenSource } from './interfaces.js';
+
+/** Why an observation refused: no membership at all, or roles the application maps to nothing. */
+export type TAuthorityRefusalReason = 'idp_membership_absent' | 'idp_roles_unmapped';
+
+/**
+ * idp.global no longer reports a usable membership of the organization.
+ * `firstRefusal` is `true` exactly once per transition from access to refusal
+ * for one login session and organization, so an audit trail records the
+ * transition and not every refused request.
+ */
+export class AuthorityRefusedError extends Error {
+  public readonly code = 'organization_access_revoked';
+  public readonly status = 403;
+
+  constructor(
+    public readonly reason: TAuthorityRefusalReason,
+    public readonly firstRefusal: boolean,
+  ) {
+    super('organization_access_revoked');
+    this.name = 'AuthorityRefusedError';
+  }
+}
+
+/** One live observation, as the caller reads it. */
+export interface IAuthorityObservation<TGrant> {
+  /** what the application's projection made of the roles */
+  grant: TGrant;
+  /** the idp role keys the provider reported, sorted */
+  roles: readonly string[];
+  /** the observation's own `exp` in epoch milliseconds */
+  tokenExpiresAt: number;
+  observedAt: number;
+}
+
+export interface IAuthorityObserverOptions<TGrant> {
+  provider: IOidcProvider;
+  tokens: IAuthorityTokenSource;
+  /** the application's role table: what the provider's role keys grant here, `undefined` for nothing */
+  project(rolesArg: readonly string[]): TGrant | undefined;
+  /**
+   * How long a positive observation answers later requests of the same login
+   * session and organization. `0` (the default) observes freshly for every
+   * operation, which is the provider's contract; a positive value is an
+   * explicit opt-in under which a revocation at idp.global takes effect here
+   * only once the cached answer expires.
+   */
+  positiveTtlMs?: number;
+  /** How long a refusal is reused; `0` (the default) never reuses one. */
+  negativeTtlMs?: number;
+  /** the bound of remembered observations */
+  maxEntries?: number;
+  now?: () => number;
+}
+
+const DEFAULT_MAX_ENTRIES = 2_000;
+/** how much room an eviction makes, so it does not run on every insert */
+const EVICTION_HEADROOM = 0.1;
+
+interface ICachedObservation<TGrant> {
+  outcome: 'active' | 'inactive';
+  grant?: TGrant;
+  reason?: TAuthorityRefusalReason;
+  roles: readonly string[];
+  tokenExpiresAt: number;
+  observedAt: number;
+  /** an entry at or past it never answers a request */
+  expiresAt: number;
+  /** the refusal whose transition was already reported */
+  reported: boolean;
+}
+
+const assertTtl = (valueArg: number, labelArg: string): number => {
+  if (!Number.isSafeInteger(valueArg) || valueArg < 0) {
+    throw new Error(labelArg + ' must be a non-negative integer of milliseconds');
+  }
+  return valueArg;
+};
+
+/**
+ * Live organization authority through idp.global: one `POST /oauth/introspect`
+ * observation of a login session's subject in one organization, projected by
+ * the application's role table.
+ *
+ * Observations of one key run once however many callers ask at the same time.
+ * A failure to observe is never remembered, so the caller fails closed on
+ * every attempt while the provider is unreachable. A session that is forgotten
+ * while its observation is in flight never stores a positive answer. Nothing
+ * runs on a timer: the cache is pruned when it is written to.
+ */
+export class AuthorityObserver<TGrant> {
+  readonly #cache = new Map<string, ICachedObservation<TGrant>>();
+  readonly #inFlight = new Map<string, Promise<ICachedObservation<TGrant>>>();
+  readonly #forgotten = new Set<string>();
+  readonly #provider: IOidcProvider;
+  readonly #tokens: IAuthorityTokenSource;
+  readonly #project: (rolesArg: readonly string[]) => TGrant | undefined;
+  readonly #positiveTtlMs: number;
+  readonly #negativeTtlMs: number;
+  readonly #maxEntries: number;
+  readonly #now: () => number;
+
+  constructor(optionsArg: IAuthorityObserverOptions<TGrant>) {
+    this.#provider = optionsArg.provider;
+    this.#tokens = optionsArg.tokens;
+    this.#project = optionsArg.project;
+    this.#positiveTtlMs = assertTtl(optionsArg.positiveTtlMs ?? 0, 'positiveTtlMs');
+    this.#negativeTtlMs = assertTtl(optionsArg.negativeTtlMs ?? 0, 'negativeTtlMs');
+    this.#maxEntries = optionsArg.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    if (!Number.isSafeInteger(this.#maxEntries) || this.#maxEntries < 1) {
+      throw new Error('maxEntries must be a positive integer');
+    }
+    this.#now = optionsArg.now ?? (() => Date.now());
+  }
+
+  /** How many observations are remembered right now. */
+  public get size(): number {
+    return this.#cache.size;
+  }
+
+  /**
+   * The grant of `principalId`'s login session in one organization at
+   * idp.global, or a throw: `AuthorityRefusedError` for a refusal,
+   * `AuthorityTokenError` when there is no live login to observe with or the
+   * provider could not be observed.
+   */
+  public async observe(optionsArg: {
+    loginSessionId: string;
+    principalId: string;
+    idpOrganizationId: string;
+  }): Promise<IAuthorityObservation<TGrant>> {
+    const key = `${optionsArg.loginSessionId} ${optionsArg.idpOrganizationId}`;
+    const cached = this.liveEntry(key);
+    const observation = cached ?? (await this.observeOnce(key, optionsArg));
+    if (observation.outcome !== 'active' || observation.grant === undefined) {
+      const firstRefusal = cached === undefined && !observation.reported;
+      observation.reported = true;
+      throw new AuthorityRefusedError(observation.reason ?? 'idp_membership_absent', firstRefusal);
+    }
+    return {
+      grant: observation.grant,
+      roles: observation.roles,
+      tokenExpiresAt: observation.tokenExpiresAt,
+      observedAt: observation.observedAt,
+    };
+  }
+
+  /** Drops every observation of a session; wire it to the session layer's `onSessionEnded`. */
+  public forgetSession(sessionIdArg: string): void {
+    const prefix = `${sessionIdArg} `;
+    for (const key of this.#cache.keys()) {
+      if (key.startsWith(prefix)) {
+        this.#cache.delete(key);
+      }
+    }
+    for (const key of this.#inFlight.keys()) {
+      if (key.startsWith(prefix)) {
+        this.#forgotten.add(key);
+      }
+    }
+  }
+
+  private liveEntry(keyArg: string): ICachedObservation<TGrant> | undefined {
+    const entry = this.#cache.get(keyArg);
+    return entry && entry.expiresAt > this.#now() ? entry : undefined;
+  }
+
+  private async observeOnce(
+    keyArg: string,
+    optionsArg: { loginSessionId: string; principalId: string; idpOrganizationId: string },
+  ): Promise<ICachedObservation<TGrant>> {
+    const running = this.#inFlight.get(keyArg);
+    if (running) {
+      return running;
+    }
+    const pending = this.makeObservation(keyArg, optionsArg).finally(() => {
+      this.#inFlight.delete(keyArg);
+      this.#forgotten.delete(keyArg);
+    });
+    this.#inFlight.set(keyArg, pending);
+    return pending;
+  }
+
+  private async makeObservation(
+    keyArg: string,
+    optionsArg: { loginSessionId: string; principalId: string; idpOrganizationId: string },
+  ): Promise<ICachedObservation<TGrant>> {
+    const token = await this.#tokens.liveProviderToken(optionsArg.loginSessionId, optionsArg.principalId);
+    let answer: Awaited<ReturnType<IOidcProvider['introspectOrganization']>>;
+    try {
+      answer = await this.#provider.introspectOrganization({
+        accessToken: token.accessToken,
+        subject: token.subject,
+        organizationId: optionsArg.idpOrganizationId,
+      });
+    } catch (error) {
+      if (error instanceof OidcAuthorityUnavailableError) {
+        throw new AuthorityTokenError('authority_unavailable', error);
+      }
+      throw error;
+    }
+    const grant = answer.active ? this.#project(answer.roles) : undefined;
+    const active = answer.active && grant !== undefined;
+    const previous = this.#cache.get(keyArg);
+    const entry: ICachedObservation<TGrant> = {
+      outcome: active ? 'active' : 'inactive',
+      ...(active ? { grant } : { reason: answer.active ? 'idp_roles_unmapped' : 'idp_membership_absent' }),
+      roles: answer.roles,
+      tokenExpiresAt: answer.expiresAt,
+      observedAt: this.#now(),
+      expiresAt: this.#now() + (active ? this.#positiveTtlMs : this.#negativeTtlMs),
+      // a refusal after a reported refusal is the same transition
+      reported: !active && previous?.outcome === 'inactive' && previous.reported,
+    };
+    if (active && this.#forgotten.has(keyArg)) {
+      // the request holding this answer finishes — it was authorized before
+      // the session ended — and every later one observes again
+      entry.expiresAt = 0;
+      return entry;
+    }
+    // a refusal is kept even when it answers nothing (`negativeTtlMs` 0): it is
+    // what reports one transition instead of one per refused request
+    this.#cache.delete(keyArg);
+    this.#cache.set(keyArg, entry);
+    this.prune();
+    return entry;
+  }
+
+  /** Expired entries go first; if that is not enough, the oldest do. */
+  private prune(): void {
+    if (this.#cache.size <= this.#maxEntries) {
+      return;
+    }
+    const now = this.#now();
+    for (const [key, entry] of this.#cache) {
+      if (entry.expiresAt <= now) {
+        this.#cache.delete(key);
+      }
+    }
+    if (this.#cache.size <= this.#maxEntries) {
+      return;
+    }
+    const target = Math.floor(this.#maxEntries * (1 - EVICTION_HEADROOM));
+    for (const key of this.#cache.keys()) {
+      if (this.#cache.size <= target) {
+        break;
+      }
+      this.#cache.delete(key);
+    }
+  }
+}

package/ts_relyingparty/classes.errors.ts

@@ -0,0 +1,77 @@
+import type { TLoginCallbackStage } from './interfaces.js';
+
+export type TRelyingPartyErrorCode =
+  | 'login_method_unavailable'
+  | 'invalid_login_callback'
+  | 'missing_login_intent'
+  | 'invalid_or_replayed_login'
+  | 'invalid_login_finalize';
+
+const RELYING_PARTY_ERROR_STATUS: Readonly<Record<TRelyingPartyErrorCode, number>> = {
+  login_method_unavailable: 404,
+  invalid_login_callback: 400,
+  missing_login_intent: 400,
+  invalid_or_replayed_login: 400,
+  invalid_login_finalize: 400,
+};
+
+/** A request the login flow refuses; the code is safe to answer, the browser learns nothing more. */
+export class RelyingPartyError extends Error {
+  public readonly status: number;
+
+  constructor(public readonly code: TRelyingPartyErrorCode) {
+    super(code);
+    this.name = 'RelyingPartyError';
+    this.status = RELYING_PARTY_ERROR_STATUS[code];
+  }
+}
+
+/**
+ * The application refuses a verified provider login (a disabled account, a
+ * subject of another issuer, no organization it serves). Thrown from
+ * `IRelyingPartyPrincipals.admit`; it reaches the caller unchanged.
+ */
+export class RelyingPartyRefusal extends Error {
+  constructor(
+    public readonly code: string,
+    public readonly status: number,
+  ) {
+    super(code);
+    this.name = 'RelyingPartyRefusal';
+  }
+}
+
+/** A login callback that failed for a reason other than a refusal; the stage is for the log only. */
+export class LoginCallbackError extends Error {
+  constructor(
+    public readonly stage: TLoginCallbackStage,
+    causeArg: unknown,
+  ) {
+    super('The login callback could not be completed', { cause: causeArg });
+    this.name = 'LoginCallbackError';
+  }
+}
+
+export type TAuthorityTokenErrorCode =
+  /** there is no live provider login this credential could be observed with */
+  | 'authority_login_required'
+  /** the provider could not be reached; the caller fails closed */
+  | 'authority_unavailable';
+
+export class AuthorityTokenError extends Error {
+  public readonly status: number;
+
+  constructor(public readonly code: TAuthorityTokenErrorCode, causeArg?: unknown) {
+    super(code, { cause: causeArg });
+    this.name = 'AuthorityTokenError';
+    this.status = code === 'authority_login_required' ? 403 : 503;
+  }
+}
+
+/** A relying-party model was used before the database it is bound to exists. */
+export class RelyingPartyDatabaseUnavailableError extends Error {
+  constructor(causeArg?: unknown) {
+    super('The relying-party models were used before their database exists', { cause: causeArg });
+    this.name = 'RelyingPartyDatabaseUnavailableError';
+  }
+}