@idp.global/sdk 18.3.1 → 19.1.0

package/ts_relyingparty/classes.relyingpartysessions.ts

@@ -6,6 +6,7 @@ import {
   RelyingPartyRefusal,
 } from './classes.errors.js';
 import {
+  OIDC_PROMPTS,
   OidcCompletionError,
   OidcRefreshRefusedError,
   type IOidcCompletion,
@@ -22,7 +23,9 @@ import type {
   IProviderToken,
   IRelyingPartyEvent,
   IRelyingPartyHooks,
+  IRelyingPartyAdmission,
   IRelyingPartyLiveSession,
+  IRelyingPartyLoginOptions,
   IRelyingPartyLoginStart,
   IRelyingPartySession,
   IRelyingPartySessionOpening,
@@ -41,6 +44,8 @@ const MAX_COOKIE_TOKEN_LENGTH = 256;
 const SESSION_TOUCH_INTERVAL_MS = 60_000;
 /** A sign-in transaction has to survive an interactive login at the provider, not a working day. */
 export const LOGIN_ATTEMPT_MAX_AGE_SECONDS = 10 * 60;
+/** The longest intent a login carries (`IRelyingPartyLoginOptions.intent`), in characters. */
+export const RELYING_PARTY_MAX_INTENT_LENGTH = 4_096;
 /** Attempts are swept once they are this much older than their expiry. */
 const LOGIN_ATTEMPT_SWEEP_GRACE_MS = 60 * 60 * 1_000;
 /** How many of them one sign-in removes; the next sign-in takes the following page. */
@@ -141,7 +146,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
   public readonly loginPathPrefix: string;
   public readonly sessionMaxAgeSeconds: number;
   readonly #models: IRelyingPartyModels;
-  readonly #admit: TRelyingPartyPrincipals<TPrincipal>['admit'];
+  readonly #admit: (completionArg: IOidcCompletion, admissionArg: IRelyingPartyAdmission) => Promise<{ principalId: string }>;
   /** the principal of a session when it may act right now, `null` otherwise */
   readonly #activePrincipal: (principalIdArg: string) => Promise<{ principal: TPrincipal } | null>;
   readonly #provider?: IOidcProvider;
@@ -195,7 +200,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     if ((typeof resolve === 'function') === (typeof isActive === 'function')) {
       throw new Error('principals needs exactly one of isActive and resolve');
     }
-    this.#admit = (completionArg) => principals.admit(completionArg);
+    this.#admit = (completionArg, admissionArg) => principals.admit(completionArg, admissionArg);
     // choose the form by the same test the check above used, so a present but
     // undefined `resolve` (a spread, a widened object) selects `isActive`
     if (typeof resolve === 'function') {
@@ -243,16 +248,22 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
 
   /**
    * Opens a session the application authenticated itself (a local password
-   * login). It carries no provider tokens.
+   * login, a one-time link of its own). It carries no provider tokens.
+   * `maxAgeSeconds` makes it live shorter than `sessionMaxAgeSeconds`, the
+   * cookie with it; it is a whole number of seconds from 1 to that maximum.
    */
-  public async openSession(optionsArg: { principalId: string }): Promise<IRelyingPartySessionOpening> {
+  public async openSession(optionsArg: { principalId: string; maxAgeSeconds?: number }): Promise<IRelyingPartySessionOpening> {
     if (typeof optionsArg?.principalId !== 'string' || optionsArg.principalId.length === 0) {
       throw new Error('openSession needs a principal id');
     }
+    const maxAgeSeconds = optionsArg.maxAgeSeconds ?? this.sessionMaxAgeSeconds;
+    if (!Number.isSafeInteger(maxAgeSeconds) || maxAgeSeconds < 1 || maxAgeSeconds > this.sessionMaxAgeSeconds) {
+      throw new RangeError(`openSession maxAgeSeconds must be a whole number from 1 to ${this.sessionMaxAgeSeconds}`);
+    }
     const token = randomToken(32);
-    const session = this.newSessionDoc(token, optionsArg.principalId);
+    const session = this.newSessionDoc(token, optionsArg.principalId, maxAgeSeconds);
     await session.save();
-    return this.opening(session, token);
+    return this.opening(session, token, maxAgeSeconds);
   }
 
   /** The live session behind the session cookie, or `null`. A read touches it at most once a minute. */
@@ -378,8 +389,15 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
    * sealed next to it, and an intent cookie that binds the callback to this
    * browser.
    */
-  public async startLogin(returnPathArg: unknown): Promise<IRelyingPartyLoginStart> {
+  public async startLogin(returnPathArg: unknown, optionsArg: IRelyingPartyLoginOptions = {}): Promise<IRelyingPartyLoginStart> {
     const provider = this.requireProvider();
+    const { intent, prompt } = optionsArg;
+    if (intent !== undefined && (typeof intent !== 'string' || intent.length === 0 || intent.length > RELYING_PARTY_MAX_INTENT_LENGTH)) {
+      throw new RangeError(`a login intent is text of 1 to ${RELYING_PARTY_MAX_INTENT_LENGTH} characters`);
+    }
+    if (prompt !== undefined && !OIDC_PROMPTS.includes(prompt)) {
+      throw new RangeError(`a login prompt is one of ${OIDC_PROMPTS.join(', ')}`);
+    }
     await this.sweepExpiredAttempts();
     const state = randomToken(32);
     const nonce = randomToken(32);
@@ -394,12 +412,15 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     attempt.sealedPkceVerifier = this.#secretBox.seal(pkceVerifier);
     attempt.nonce = nonce;
     attempt.returnPath = sanitizeReturnPath(returnPathArg, this.publicOrigin, this.loginPathPrefix);
+    if (intent !== undefined) {
+      attempt.sealedIntent = this.#secretBox.seal(intent);
+    }
     attempt.createdAt = now;
     attempt.expiresAt = now + LOGIN_ATTEMPT_MAX_AGE_SECONDS * 1_000;
     await attempt.save();
 
     return {
-      authorizationUrl: await provider.buildAuthorizationUrl({ state, nonce, pkceVerifier }),
+      authorizationUrl: await provider.buildAuthorizationUrl({ state, nonce, pkceVerifier, ...(prompt ? { prompt } : {}) }),
       intentCookie: serializeCookie(this.intentCookieName, bindingToken, {
         httpOnly: true,
         secure: this.secureCookies,
@@ -456,7 +477,10 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
         pkceVerifier: this.#secretBox.open(attempt.sealedPkceVerifier),
       });
       stage = 'principal_admission';
-      const { principalId } = await this.#admit(completion);
+      const { principalId } = await this.#admit(completion, {
+        loginAttemptId: attempt.id,
+        ...(attempt.sealedIntent ? { intent: this.#secretBox.open(attempt.sealedIntent) } : {}),
+      });
       stage = 'session_persistence';
       return await this.createProviderSession(attempt, principalId, completion);
     } catch (error) {
@@ -696,7 +720,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     return this.#provider;
   }
 
-  private newSessionDoc(tokenArg: string, principalIdArg: string): RelyingPartySessionDoc {
+  private newSessionDoc(tokenArg: string, principalIdArg: string, maxAgeSecondsArg: number = this.sessionMaxAgeSeconds): RelyingPartySessionDoc {
     const now = this.#now();
     const session = new this.#models.Session();
     session.id = 'ses_' + randomToken(18);
@@ -704,7 +728,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     session.userId = principalIdArg;
     session.createdAt = now;
     session.lastSeenAt = now;
-    session.expiresAt = now + this.sessionMaxAgeSeconds * 1_000;
+    session.expiresAt = now + maxAgeSecondsArg * 1_000;
     return session;
   }
 
@@ -712,7 +736,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
     return deriveCsrfToken(tokenArg, this.#csrfKey, this.#csrfLabel);
   }
 
-  private opening(sessionArg: RelyingPartySessionDoc, tokenArg: string): IRelyingPartySessionOpening {
+  private opening(sessionArg: RelyingPartySessionDoc, tokenArg: string, maxAgeSecondsArg: number = this.sessionMaxAgeSeconds): IRelyingPartySessionOpening {
     return {
       session: this.snapshot(sessionArg),
       csrfToken: this.csrfTokenOf(tokenArg),
@@ -720,7 +744,7 @@ export class RelyingPartySessions<TPrincipal extends object | undefined = undefi
         httpOnly: true,
         secure: this.secureCookies,
         sameSite: 'Lax',
-        maxAgeSeconds: this.sessionMaxAgeSeconds,
+        maxAgeSeconds: maxAgeSecondsArg,
       }),
     };
   }

package/ts_relyingparty/classes.rpmodels.ts

@@ -86,6 +86,10 @@ export class RelyingPartyLoginAttemptDoc extends plugins.nosqldb.SmartDataDbDoc<
   @plugins.nosqldb.svDb()
   public returnPath: string = '/';
 
+  /** the application's intent for this login, sealed like the verifier (`IRelyingPartyLoginOptions.intent`); absent without one */
+  @plugins.nosqldb.svDb()
+  public sealedIntent?: string;
+
   @plugins.nosqldb.svDb()
   public createdAt: number = 0;
 

package/ts_relyingparty/classes.socketbinding.ts

@@ -1,21 +1,35 @@
-import * as plugins from './plugins.js';
 import type { RelyingPartySessions } from './classes.relyingpartysessions.js';
 import { sha256, timingSafeEqualString } from './helpers.crypto.js';
 import type { IRelyingPartySession } from './interfaces.js';
 
-/** The part of a server `TypedSocket` the binding uses. */
-export type TRelyingPartySocketTransport = Pick<
-  plugins.typedsocket.TypedSocket,
-  'setServerTag' | 'findAllTargetConnectionsByTag'
->;
+/**
+ * The WebSocket peer underneath a connection, as far as the binding reads it:
+ * the headers its upgrade arrived with. A SmartServe peer of any major fits.
+ */
+export type TRelyingPartySocketPeer = {
+  context: { headers: { get(nameArg: string): string | null } };
+};
 
-export type TRelyingPartySocketConnection = plugins.typedsocket.ISmartServeConnectionWrapper;
+/** A server connection as the binding reads it: its peer. A TypedSocket connection wrapper of any major fits. */
+export type TRelyingPartySocketConnection = {
+  peer: TRelyingPartySocketPeer;
+};
 
-/** The SmartServe WebSocket peer underneath a connection, as a TypedSocket server hands it out. */
-export type TRelyingPartySocketPeer = TRelyingPartySocketConnection['peer'];
+/** A connection or its peer; `TypedSocket.setServerTag` takes either. */
+export type TRelyingPartySocketTarget<TConnection extends TRelyingPartySocketConnection = TRelyingPartySocketConnection> =
+  | TConnection
+  | TConnection['peer'];
 
-/** A connection wrapper or its peer; `TypedSocket.setServerTag` takes either. */
-export type TRelyingPartySocketTarget = TRelyingPartySocketConnection | TRelyingPartySocketPeer;
+/**
+ * The part of the application's server `TypedSocket` the binding uses. The
+ * binding names no TypedSocket or SmartServe version: the application's own
+ * transport fits whichever major it runs, and `connectionsOfSession` answers
+ * its own connection type.
+ */
+export type TRelyingPartySocketTransport<TConnection extends TRelyingPartySocketConnection = TRelyingPartySocketConnection> = {
+  setServerTag(targetArg: TRelyingPartySocketTarget<TConnection>, nameArg: string): void;
+  findAllTargetConnectionsByTag(nameArg: string): Promise<TConnection[]>;
+};
 
 const peerOf = (targetArg: TRelyingPartySocketTarget): TRelyingPartySocketPeer =>
   'peer' in targetArg ? targetArg.peer : targetArg;
@@ -37,10 +51,13 @@ export type TRelyingPartySocketRegistration =
   | { registered: true; pinned: IRelyingPartyPinnedSession; expiresAt: number }
   | { registered: false; refusal: IRelyingPartySocketRefusal };
 
-export interface IRelyingPartySocketBindingOptions<TPrincipal extends object | undefined = undefined> {
+export interface IRelyingPartySocketBindingOptions<
+  TPrincipal extends object | undefined = undefined,
+  TConnection extends TRelyingPartySocketConnection = TRelyingPartySocketConnection,
+> {
   sessions: RelyingPartySessions<TPrincipal>;
   /** the transport typedserver created; `undefined` before the server runs */
-  transport: () => TRelyingPartySocketTransport | undefined;
+  transport: () => TRelyingPartySocketTransport<TConnection> | undefined;
   /** the server-owned tag prefix that finds the connections of a session */
   tagPrefix?: string;
 }
@@ -54,12 +71,15 @@ export interface IRelyingPartySocketBindingOptions<TPrincipal extends object | u
  * request. Connection limits, rate limits and sweeps belong to the
  * application's socket gate.
  */
-export class RelyingPartySocketBinding<TPrincipal extends object | undefined = undefined> {
+export class RelyingPartySocketBinding<
+  TPrincipal extends object | undefined = undefined,
+  TConnection extends TRelyingPartySocketConnection = TRelyingPartySocketConnection,
+> {
   readonly #sessions: RelyingPartySessions<TPrincipal>;
-  readonly #transport: () => TRelyingPartySocketTransport | undefined;
+  readonly #transport: () => TRelyingPartySocketTransport<TConnection> | undefined;
   public readonly tagPrefix: string;
 
-  constructor(optionsArg: IRelyingPartySocketBindingOptions<TPrincipal>) {
+  constructor(optionsArg: IRelyingPartySocketBindingOptions<TPrincipal, TConnection>) {
     this.#sessions = optionsArg.sessions;
     this.#transport = optionsArg.transport;
     this.tagPrefix = optionsArg.tagPrefix ?? 'idp_rp_session:';
@@ -112,7 +132,7 @@ export class RelyingPartySocketBinding<TPrincipal extends object | undefined = u
    * Tags a connection — its wrapper or its peer — with its session; throws
    * when the transport is not running or the connection is gone.
    */
-  public tagConnection(targetArg: TRelyingPartySocketTarget, sessionIdArg: string): void {
+  public tagConnection(targetArg: TRelyingPartySocketTarget<TConnection>, sessionIdArg: string): void {
     const transport = this.#transport();
     if (!transport) {
       throw new Error('The socket transport is not running');
@@ -146,7 +166,7 @@ export class RelyingPartySocketBinding<TPrincipal extends object | undefined = u
   }
 
   /** The live connections of one session, for closing them when it ends. */
-  public async connectionsOfSession(sessionIdArg: string): Promise<readonly TRelyingPartySocketConnection[]> {
+  public async connectionsOfSession(sessionIdArg: string): Promise<readonly TConnection[]> {
     const transport = this.#transport();
     if (!transport) {
       return [];

package/ts_relyingparty/interfaces.ts

@@ -1,4 +1,4 @@
-import type { IOidcCompletion, TOidcCompletionFailureStage, TOidcTokenHint } from './classes.idpoidcprovider.js';
+import type { IOidcCompletion, TOidcCompletionFailureStage, TOidcPrompt, TOidcTokenHint } from './classes.idpoidcprovider.js';
 
 /** A session as the application reads it; no token and no sealed value is part of it. */
 export interface IRelyingPartySession {
@@ -35,6 +35,27 @@ export interface IRelyingPartySessionOpening {
   sessionCookie: string;
 }
 
+/**
+ * What `startLogin` carries besides the return path. `intent` is the
+ * application's own text — the invitation a login accepts, the account it
+ * links, the client it authorizes — sealed into the login attempt and handed
+ * to admission (`IRelyingPartyAdmission`) when exactly this login comes back;
+ * it never travels through the browser or the provider.
+ */
+export interface IRelyingPartyLoginOptions {
+  /** at most `RELYING_PARTY_MAX_INTENT_LENGTH` characters, not empty */
+  intent?: string;
+  prompt?: TOidcPrompt;
+}
+
+/** What admission learns about the login besides the provider's completion. */
+export interface IRelyingPartyAdmission {
+  /** the intent `startLogin` was given for this login, opened from its seal; absent when there was none */
+  intent?: string;
+  /** the login attempt the session will name (`IRelyingPartySession.loginAttemptId`) */
+  loginAttemptId: string;
+}
+
 /** The redirect that starts a provider login, and the cookie that binds it to this browser. */
 export interface IRelyingPartyLoginStart {
   authorizationUrl: URL;
@@ -66,7 +87,7 @@ export interface IAuthorityTokenSource {
  * then handed back and the refusal reaches the caller unchanged.
  */
 export interface IRelyingPartyPrincipals {
-  admit(completionArg: IOidcCompletion): Promise<{ principalId: string }>;
+  admit(completionArg: IOidcCompletion, admissionArg: IRelyingPartyAdmission): Promise<{ principalId: string }>;
   /** Whether a principal may act right now; a session of an inactive principal resolves to nothing. */
   isActive(principalIdArg: string): Promise<boolean>;
 }
@@ -78,7 +99,7 @@ export interface IRelyingPartyPrincipals {
  * `principal`. Give either `isActive` or `resolve`, never both.
  */
 export interface IRelyingPartyPrincipalResolver<TPrincipal extends object | undefined> {
-  admit(completionArg: IOidcCompletion): Promise<{ principalId: string }>;
+  admit(completionArg: IOidcCompletion, admissionArg: IRelyingPartyAdmission): Promise<{ principalId: string }>;
   /** The principal object when it may act right now, `null` otherwise; any answer that is not an object (including `false`) resolves the session to nothing. */
   resolve(principalIdArg: string): Promise<TPrincipal | null>;
 }

package/ts_relyingparty/plugins.ts

@@ -4,9 +4,8 @@ import * as crypto from 'node:crypto';
 export { asyncHooks, crypto };
 
 import * as typedrequest from '@api.global/typedrequest';
-import * as typedsocket from '@api.global/typedsocket';
 
-export { typedrequest, typedsocket };
+export { typedrequest };
 
 import * as nosqldb from '@lossless.org/client/nosqldb';
 

package/ts_relyingparty/testing.ts

@@ -0,0 +1,306 @@
+import * as plugins from './plugins.js';
+import {
+  OidcCompletionError,
+  OidcRefreshRefusedError,
+  type IOidcAuthorizationOptions,
+  type IOidcCompletion,
+  type IOidcCompletionOptions,
+  type IOidcOrganizationClaim,
+  type IOidcOrganizationObservation,
+  type IOidcProvider,
+  type IOidcRefreshedTokens,
+  type TOidcTokenHint,
+} from './classes.idpoidcprovider.js';
+
+/**
+ * `@idp.global/sdk/relyingparty/testing`: an in-process idp.global for the
+ * tests of an application built on `RelyingPartySessions`. It is a test
+ * double and nothing else — no socket, no persistence, no check a real
+ * provider makes beyond the ones named here — and belongs in test code only.
+ */
+
+/** A person at the double, with the organizations idp.global reports for them. */
+export interface IProviderDoublePersona {
+  /** the stable `sub` */
+  subject: string;
+  displayName?: string;
+  email?: string;
+  /** `email_verified`; `true` when absent, as for an active idp.global account */
+  emailVerified?: boolean;
+  /** the `organizations` claim, and what introspection answers for each organization */
+  organizations?: IOidcOrganizationClaim[];
+}
+
+export interface IProviderDoubleOptions {
+  /** the issuer origin the authorization URLs point at; `https://idp.test` by default */
+  issuer?: string;
+  /** how long an access token lives, in seconds; 3600 by default, `0` names no lifetime */
+  accessTokenLifetimeSeconds?: number;
+  /** the clock every expiry reads; tests step it instead of sleeping */
+  now?: () => number;
+  requestTimeoutSeconds?: number;
+}
+
+interface IIssuedCode {
+  state: string;
+  nonce: string;
+  subject: string;
+}
+
+interface IIssuedToken {
+  subject: string;
+  family: string;
+  /** epoch milliseconds; `0` for no expiry */
+  expiresAt: number;
+  kind: 'access' | 'refresh';
+  revoked: boolean;
+  /** a refresh token that was rotated: using it again is reuse */
+  used: boolean;
+}
+
+const randomToken = (): string => plugins.crypto.randomBytes(18).toString('base64url');
+
+/**
+ * The provider as `IOidcProvider` sees it. A test adds personas, names the one
+ * the next login signs in as (`signInNextAs`), follows the authorization URL
+ * back with `callbackUrlFor`, and changes what idp.global reports live
+ * (`setOrganizationRoles`, `endLoginsOf`). Codes are single use and bound to
+ * their login's state; access tokens introspect for their subject while they
+ * live; refresh tokens rotate, and a superseded one coming back revokes its
+ * whole family, as idp.global's reuse detection does. Every call is recorded,
+ * and each step can be made to fail.
+ */
+export class RelyingPartyProviderDouble implements IOidcProvider {
+  public readonly requestTimeoutSeconds: number;
+  public readonly issuer: string;
+  public accessTokenLifetimeSeconds: number;
+
+  public readonly authorizations: IOidcAuthorizationOptions[] = [];
+  public readonly completions: Array<{ subject: string; state: string }> = [];
+  public readonly revocations: Array<{ token: string; hint: TOidcTokenHint }> = [];
+  public readonly introspections: Array<{ accessToken: string; subject: string; organizationId: string }> = [];
+  public readonly refreshes: string[] = [];
+
+  /** when set, the completion of a login fails with it (an `OidcCompletionError` names its stage) */
+  public completionFailure?: Error;
+  /** when set, every introspection fails with it (an `OidcAuthorityUnavailableError` for an unreachable provider) */
+  public introspectionFailure?: Error;
+  /** when set, every refresh fails with it */
+  public refreshFailure?: Error;
+  /** when set, every revocation fails with it, after it was recorded */
+  public revocationFailure?: Error;
+  /** runs inside an introspection before it answers: a test holds one open with it */
+  public onIntrospect?: (optionsArg: { accessToken: string; subject: string; organizationId: string }) => Promise<void>;
+  /** runs inside a refresh before it answers: a test races a logout with it */
+  public onRefresh?: (refreshTokenArg: string) => Promise<void>;
+
+  readonly #now: () => number;
+  readonly #personas = new Map<string, IProviderDoublePersona>();
+  readonly #codes = new Map<string, IIssuedCode>();
+  readonly #tokens = new Map<string, IIssuedToken>();
+  #next?: string;
+
+  constructor(optionsArg: IProviderDoubleOptions = {}) {
+    this.issuer = new URL(optionsArg.issuer ?? 'https://idp.test').origin;
+    this.accessTokenLifetimeSeconds = optionsArg.accessTokenLifetimeSeconds ?? 3_600;
+    this.requestTimeoutSeconds = optionsArg.requestTimeoutSeconds ?? 10;
+    this.#now = optionsArg.now ?? (() => Date.now());
+  }
+
+  // ---- personas ----
+
+  /** Adds a persona, or replaces the one with its subject. */
+  public addPersona(personaArg: IProviderDoublePersona): void {
+    this.#personas.set(personaArg.subject, {
+      ...personaArg,
+      organizations: (personaArg.organizations ?? []).map((entryArg) => ({ ...entryArg, roles: [...entryArg.roles] })),
+    });
+  }
+
+  public persona(subjectArg: string): IProviderDoublePersona | undefined {
+    return this.#personas.get(subjectArg);
+  }
+
+  /** The persona the next authorization signs in as; a persona given whole is added first. */
+  public signInNextAs(personaArg: string | IProviderDoublePersona): void {
+    if (typeof personaArg !== 'string') {
+      this.addPersona(personaArg);
+    }
+    const subject = typeof personaArg === 'string' ? personaArg : personaArg.subject;
+    if (!this.#personas.has(subject)) {
+      throw new Error(`RelyingPartyProviderDouble: no persona ${subject}; addPersona first`);
+    }
+    this.#next = subject;
+  }
+
+  /**
+   * What idp.global reports for the persona in an organization from now on:
+   * its roles, or `null` when the persona is no member any more. Introspection
+   * reads it at once; the claims of a login are those of its sign-in.
+   */
+  public setOrganizationRoles(subjectArg: string, organizationIdArg: string, rolesArg: string[] | null): void {
+    const persona = this.requirePersona(subjectArg);
+    const organizations = (persona.organizations ?? []).filter((entryArg) => entryArg.id !== organizationIdArg);
+    if (rolesArg) {
+      const known = persona.organizations?.find((entryArg) => entryArg.id === organizationIdArg);
+      organizations.push({
+        id: organizationIdArg,
+        name: known?.name ?? organizationIdArg,
+        slug: known?.slug ?? organizationIdArg,
+        roles: [...rolesArg],
+      });
+    }
+    persona.organizations = organizations;
+  }
+
+  /** Ends every login of the persona at the provider: its tokens neither introspect nor rotate any more. */
+  public endLoginsOf(subjectArg: string): void {
+    for (const token of this.#tokens.values()) {
+      if (token.subject === subjectArg) {
+        token.revoked = true;
+      }
+    }
+  }
+
+  /** Where the provider would send the browser back after the login this authorization URL started. */
+  public callbackUrlFor(authorizationUrlArg: URL, redirectUriArg: URL | string): URL {
+    const callback = new URL(redirectUriArg);
+    callback.searchParams.set('code', authorizationUrlArg.searchParams.get('code') ?? '');
+    callback.searchParams.set('state', authorizationUrlArg.searchParams.get('state') ?? '');
+    return callback;
+  }
+
+  // ---- IOidcProvider ----
+
+  public async init(): Promise<void> {}
+
+  public async buildAuthorizationUrl(optionsArg: IOidcAuthorizationOptions): Promise<URL> {
+    if (!this.#next) {
+      throw new Error('RelyingPartyProviderDouble: name the persona this login signs in as with signInNextAs');
+    }
+    this.authorizations.push({ ...optionsArg });
+    const code = 'code_' + randomToken();
+    this.#codes.set(code, { state: optionsArg.state, nonce: optionsArg.nonce, subject: this.#next });
+    const url = new URL('/oauth/authorize', this.issuer);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('state', optionsArg.state);
+    url.searchParams.set('nonce', optionsArg.nonce);
+    if (optionsArg.prompt) {
+      url.searchParams.set('prompt', optionsArg.prompt);
+    }
+    // what the double hands back at once; a real provider answers it after the login page
+    url.searchParams.set('code', code);
+    return url;
+  }
+
+  public async completeAuthorization(optionsArg: IOidcCompletionOptions): Promise<IOidcCompletion> {
+    const code = optionsArg.callbackUrl.searchParams.get('code') ?? '';
+    const issued = this.#codes.get(code);
+    this.#codes.delete(code);
+    if (!issued || issued.state !== optionsArg.state) {
+      throw new OidcCompletionError('token_exchange', new Error('unknown, used or foreign code'));
+    }
+    if (issued.nonce !== optionsArg.nonce) {
+      throw new OidcCompletionError('token_validation', new Error('nonce mismatch'));
+    }
+    this.completions.push({ subject: issued.subject, state: issued.state });
+    if (this.completionFailure) {
+      throw this.completionFailure;
+    }
+    const persona = this.requirePersona(issued.subject);
+    const family = randomToken();
+    const access = this.issue('access', issued.subject, family);
+    const refresh = this.issue('refresh', issued.subject, family);
+    return {
+      subject: persona.subject,
+      accessToken: access.token,
+      refreshToken: refresh.token,
+      accessTokenExpiresAt: access.expiresAt,
+      ...(persona.email !== undefined ? { email: persona.email } : {}),
+      emailVerified: persona.emailVerified ?? true,
+      ...(persona.displayName !== undefined ? { displayName: persona.displayName } : {}),
+      organizations: (persona.organizations ?? []).map((entryArg) => ({ ...entryArg, roles: [...entryArg.roles] })),
+    };
+  }
+
+  public async revokeToken(tokenArg: string, hintArg: TOidcTokenHint): Promise<void> {
+    this.revocations.push({ token: tokenArg, hint: hintArg });
+    if (this.revocationFailure) {
+      throw this.revocationFailure;
+    }
+    const token = this.#tokens.get(tokenArg);
+    if (token) {
+      token.revoked = true;
+    }
+  }
+
+  public async introspectOrganization(optionsArg: {
+    accessToken: string;
+    subject: string;
+    organizationId: string;
+  }): Promise<IOidcOrganizationObservation> {
+    this.introspections.push({ ...optionsArg });
+    await this.onIntrospect?.({ ...optionsArg });
+    if (this.introspectionFailure) {
+      throw this.introspectionFailure;
+    }
+    const token = this.#tokens.get(optionsArg.accessToken);
+    const inactive: IOidcOrganizationObservation = { active: false, roles: [], expiresAt: 0 };
+    if (!token || token.kind !== 'access' || !this.isLive(token) || token.subject !== optionsArg.subject) {
+      return inactive;
+    }
+    const membership = this.#personas.get(token.subject)?.organizations?.find((entryArg) => entryArg.id === optionsArg.organizationId);
+    if (!membership) {
+      return inactive;
+    }
+    return { active: true, roles: [...membership.roles].sort(), expiresAt: token.expiresAt };
+  }
+
+  public async refreshTokens(refreshTokenArg: string): Promise<IOidcRefreshedTokens> {
+    this.refreshes.push(refreshTokenArg);
+    await this.onRefresh?.(refreshTokenArg);
+    if (this.refreshFailure) {
+      throw this.refreshFailure;
+    }
+    const token = this.#tokens.get(refreshTokenArg);
+    if (!token || token.kind !== 'refresh' || token.revoked) {
+      throw new OidcRefreshRefusedError(new Error('invalid_grant'));
+    }
+    if (token.used) {
+      // reuse of a superseded refresh token: the family dies
+      for (const entry of this.#tokens.values()) {
+        if (entry.family === token.family) {
+          entry.revoked = true;
+        }
+      }
+      throw new OidcRefreshRefusedError(new Error('invalid_grant'));
+    }
+    token.used = true;
+    const access = this.issue('access', token.subject, token.family);
+    const refresh = this.issue('refresh', token.subject, token.family);
+    return { accessToken: access.token, refreshToken: refresh.token, accessTokenExpiresAt: access.expiresAt };
+  }
+
+  // ---- internals ----
+
+  private requirePersona(subjectArg: string): IProviderDoublePersona {
+    const persona = this.#personas.get(subjectArg);
+    if (!persona) {
+      throw new Error(`RelyingPartyProviderDouble: no persona ${subjectArg}`);
+    }
+    return persona;
+  }
+
+  private issue(kindArg: IIssuedToken['kind'], subjectArg: string, familyArg: string): { token: string; expiresAt: number } {
+    const token = (kindArg === 'access' ? 'at_' : 'rt_') + randomToken();
+    const expiresAt = kindArg === 'access' && this.accessTokenLifetimeSeconds > 0
+      ? this.#now() + this.accessTokenLifetimeSeconds * 1_000
+      : 0;
+    this.#tokens.set(token, { subject: subjectArg, family: familyArg, expiresAt, kind: kindArg, revoked: false, used: false });
+    return { token, expiresAt };
+  }
+
+  private isLive(tokenArg: IIssuedToken): boolean {
+    return !tokenArg.revoked && (tokenArg.expiresAt === 0 || tokenArg.expiresAt > this.#now());
+  }
+}