@ever-works/oidc-identity 1.0.0

package/dist/testing/fake-oidc-provider.d.cts

@@ -0,0 +1,321 @@
+/**
+ * APW-12 T8 — a **fake OpenID Connect provider**, published only through this
+ * package's `./testing` subpath (plan §10.4).
+ *
+ * The API integration spec (`apps/api/src/auth/ever-id.flow.integration.spec.ts`,
+ * T20/T25) and the Playwright lanes both need a provider that answers the way Ever
+ * ID will: a discovery document, a key set, an authorization endpoint that
+ * approves a configured person, a token endpoint that **checks PKCE**, device
+ * authorization with FR-41's polling rules, an end-session endpoint, and helpers
+ * that mint the access and logout tokens the verifiers are given. One fake, in one
+ * place, because a second one would be a second set of provider behaviours to keep
+ * in step.
+ *
+ * ## Why the subpath, and why that is load-bearing
+ *
+ * Plan §10.4: "published only through a `./testing` subpath export, never from the
+ * main entry". The main entry (`src/index.ts`) is what the plugin loader imports in
+ * production, and a fake provider that reached it would be dead weight in every
+ * API process — and, worse, an HTTP server behind a class the platform already
+ * instantiates. `package.json`'s `exports["./testing"]` and `tsup`'s second entry
+ * are what make that separation real; `src/__tests__/fake-oidc-provider.spec.ts`
+ * asserts it from both the source side and (when a build exists) the built side.
+ *
+ * ## What it is not
+ *
+ * It is not a security reference. It signs with ES256 keys it generates
+ * (`node:crypto`, plan §10.4 — not `jose`, so a bug in the library under test
+ * cannot hide a bug in the fake), it keeps device grants and authorization codes
+ * in memory, and it makes no attempt to be a *correct* provider in the corners the
+ * epic does not read. Where it deliberately *is* strict — PKCE S256, single-use
+ * codes, `client_secret_basic`, FR-41's poll interval — the strictness is the
+ * point: those are the behaviours the relying party has to get right, and a fake
+ * that accepted anything would prove nothing about them.
+ *
+ * ## Time
+ *
+ * Every clock read goes through the injected `now` (epoch **milliseconds**,
+ * defaulting to `Date.now`), and every minted claim is stamped from it. A spec
+ * therefore drives token lifetimes, the device-poll interval and `iat`/`exp` with
+ * literal values and an injected clock rather than by sleeping — the rule this
+ * package learned the hard way in T6.
+ */
+/**
+ * The `events` member of a back-channel logout notice — OpenID Connect
+ * Back-Channel Logout 1.0 §2.4's event identifier.
+ *
+ * Spelled here rather than imported from the plugin on purpose: this module stands
+ * in for an **external** provider, and a provider does not read the relying
+ * party's constants. `fake-oidc-provider.spec.ts` asserts that this literal and
+ * `OIDC_BACKCHANNEL_LOGOUT_EVENT` are the same string, so the two cannot drift
+ * without a red test.
+ */
+declare const FAKE_BACKCHANNEL_LOGOUT_EVENT = "http://schemas.openid.net/event/backchannel-logout";
+/** The public client an exchange token names by default. */
+declare const FAKE_DEFAULT_LOCAL_CLIENT_ID = "ever-works-cli";
+/** The person the provider approves when a spec configures nobody (§10.4). */
+declare const FAKE_DEFAULT_USER: {
+    readonly subject: "ever-id-subject-1";
+    readonly email: "person@example.com";
+    readonly emailVerified: true;
+    readonly name: "A Person";
+};
+/** The document fields a spec may ask the fake to leave out (FR-3's rows, FR-36's `null`). */
+type FakeOidcOmittableField = 'authorization_endpoint' | 'token_endpoint' | 'jwks_uri' | 'end_session_endpoint' | 'device_authorization_endpoint' | 'code_challenge_methods_supported' | 'backchannel_logout_supported';
+/** The person this provider signs in. */
+interface FakeOidcUser {
+    readonly subject: string;
+    readonly email: string;
+    readonly emailVerified?: boolean;
+    readonly name?: string;
+}
+/** Construction options for {@link FakeOidcProvider.start}. */
+interface FakeOidcProviderOptions {
+    /** The person auto-approved at `/authorize` and at device authorization. */
+    readonly user?: FakeOidcUser;
+    /** The relying party's client id. Default `ever-works-web`. */
+    readonly clientId?: string;
+    /**
+     * The `client_secret_basic` secret the token endpoint requires, or `null` to
+     * accept any (a spec that is not exercising client authentication).
+     */
+    readonly clientSecret?: string | null;
+    /** The audience a minted access token carries. Default `ever-works`. */
+    readonly apiAudience?: string;
+    /** The public clients an exchange token may name in `azp`. */
+    readonly localClients?: readonly {
+        readonly kind: 'cli' | 'node';
+        readonly clientId: string;
+    }[];
+    /** FR-44's scope a delegated access token carries. Default `apps:read`. */
+    readonly delegatedScope?: string;
+    /** FR-39/FR-40's scope an exchange access token carries. Default `ever-works:session`. */
+    readonly exchangeScope?: string;
+    /** How long a minted access token lives when the caller does not say. Default 300. */
+    readonly accessTokenLifetimeSeconds?: number;
+    /** FR-41's poll interval the device endpoint returns, in seconds. Default 5. */
+    readonly devicePollIntervalSeconds?: number;
+    /** How long a device code lives. Default 900 (FR-41). */
+    readonly deviceCodeLifetimeSeconds?: number;
+    /** How long an authorization code lives. Default 60. */
+    readonly authorizationCodeLifetimeSeconds?: number;
+    /** Document fields to leave out, so a spec can drive the rows and the `null` answers. */
+    readonly omit?: readonly FakeOidcOmittableField[];
+    /** The clock, in epoch milliseconds. Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/** One request the provider received, so a spec can assert on what actually went out. */
+interface FakeOidcCall {
+    readonly method: string;
+    readonly path: string;
+    /** The query string, as a plain object (a repeated key keeps its first value). */
+    readonly query: Record<string, string>;
+    /** The `application/x-www-form-urlencoded` body, as a plain object. */
+    readonly form: Record<string, string>;
+    /** The request headers, lower-cased. */
+    readonly headers: Record<string, string>;
+}
+/** What a device-code poll answered. */
+interface FakeDevicePoll {
+    readonly status: number;
+    readonly body: Record<string, unknown>;
+}
+/** What {@link FakeOidcProvider.start} resolves to. */
+type FakeOidcProviderStarted = FakeOidcProvider;
+/**
+ * A local OpenID Connect provider, for specs.
+ *
+ * `start()` binds an ephemeral port on the loopback interface and answers on
+ * `http://localhost:<port>` — the one non-TLS issuer `settings.schema.ts` accepts
+ * and the one the plugin's configuration tells `openid-client` about
+ * (`isInsecureIssuer`). The issuer therefore depends on the port and is only known
+ * after the server is listening, which is why construction goes through `start()`.
+ */
+declare class FakeOidcProvider {
+    /** Every request, in order — method, path, query, form and headers. */
+    readonly calls: FakeOidcCall[];
+    private readonly options;
+    private readonly keys;
+    private readonly codes;
+    private readonly devices;
+    private server;
+    private issuerUrl;
+    private keySequence;
+    /** The person approved from now on, when a spec changed it after start (see {@link setUser}). */
+    private userOverride;
+    /** Extra claims every ID token minted from now on carries (see {@link setIdTokenClaims}). */
+    private extraIdTokenClaims;
+    /** The provider session id (`sid`) the next tokens carry (see {@link setSessionId}). */
+    private sessionId;
+    private constructor();
+    /** Bind a port and answer the discovery document a relying party will read. */
+    static start(options?: FakeOidcProviderOptions): Promise<FakeOidcProvider>;
+    /**
+     * Bind an ephemeral loopback port and answer `/…/.well-known/openid-configuration`.
+     *
+     * Kept additive and public so a caller that wants a provider on a **fixed** port
+     * (a Playwright lane that must tell the API where to find it before the process
+     * starts) can build one; `start()` is the ordinary entry point.
+     */
+    listen(port?: number): Promise<void>;
+    /** The issuer the discovery document advertises, and the settings' `issuerUrl`. */
+    get issuer(): string;
+    /** The bound port. */
+    get port(): number;
+    get discoveryUrl(): string;
+    get jwksUri(): string;
+    get authorizationEndpoint(): string;
+    get tokenEndpoint(): string;
+    get endSessionEndpoint(): string;
+    get deviceAuthorizationEndpoint(): string;
+    /** The relying party's client id the token endpoint expects. */
+    get clientId(): string;
+    /** The `client_secret_basic` secret the token endpoint expects, or `null` for "any". */
+    get clientSecret(): string | null;
+    /** The API audience a minted access token carries. */
+    get apiAudience(): string;
+    /** The `azp` a minted access token carries when the caller does not say. */
+    get defaultAuthorizedParty(): string;
+    /** The document this provider publishes, with the fields `omit` removed. */
+    discoveryDocument(): Record<string, unknown>;
+    /** FR-44's delegated scope this provider mints. */
+    get delegatedScope(): string;
+    /** FR-39/FR-40's exchange scope this provider mints. */
+    get exchangeScope(): string;
+    /** The current clock, in epoch milliseconds. */
+    now(): number;
+    /** The current clock, in whole seconds — the unit every JWT time claim uses. */
+    nowSeconds(): number;
+    /**
+     * Replace the signing key, the way a provider rotates one (FR-13, ACC-12-08).
+     *
+     * `keepPrevious` publishes the old key alongside the new one, which is what a
+     * rollover looks like while tokens signed with it are still in flight; the
+     * default is the harder case, where the old key is **gone** and a token signed
+     * with it must stop validating.
+     */
+    rotateKeys(options?: {
+        keepPrevious?: boolean;
+    }): Promise<void>;
+    /** The current key id, so a spec can name what it is signing with. */
+    /**
+     * Change the person the provider approves from now on — so one running fake
+     * can sign in a connected identity, a new one and one whose e-mail an account
+     * already uses, in turn. Additive test seam; the constructor option still sets
+     * the first person.
+     */
+    setUser(user: FakeOidcUser): void;
+    /**
+     * Extra claims every ID token minted from now on carries (for example the
+     * optional `urn:ever:` hint claims). Pass `{}` to stop adding any.
+     */
+    setIdTokenClaims(claims: Record<string, unknown>): void;
+    /** The provider session id (`sid`) the next ID tokens and logout tokens carry. */
+    setSessionId(sid: string): void;
+    /** The provider session id the next tokens carry. */
+    get currentSessionId(): string;
+    get currentKeyId(): string;
+    /**
+     * Sign an ID token for the configured person — what the token endpoint answers
+     * with, and what a spec can use to drive `exchangeAuthorizationCode` directly.
+     */
+    mintIdToken(overrides?: Record<string, unknown>): Promise<string>;
+    /**
+     * Sign an access token — the artifact FR-40's exchange and FR-45's delegated read
+     * are handed.
+     *
+     * The defaults are a **valid** token for the configured installation: `aud` is
+     * the API audience, `azp` is the first configured local client,
+     * `scope` is the exchange scope, `iat` is now and `exp` is now plus
+     * {@link FakeOidcProviderOptions.accessTokenLifetimeSeconds}. Every case in a
+     * spec is therefore "everything is valid, except this", and the literal numbers
+     * a case wants are passed in rather than derived from the plugin.
+     */
+    mintAccessToken(overrides?: {
+        readonly scopes?: readonly string[];
+        readonly authorizedParty?: string | null;
+        readonly audience?: string | readonly string[];
+        readonly subject?: string;
+        readonly issuedAt?: number;
+        readonly expiresAt?: number;
+        readonly jti?: string | null;
+        readonly claims?: Record<string, unknown>;
+    }): Promise<string>;
+    /**
+     * Sign a back-channel logout notice (FR-33).
+     *
+     * The default is a **valid** notice about the configured person's session:
+     * the event member, an `iat` of now, a fresh `jti`, `sid` and no `nonce`, `exp`
+     * or `sub`. `extraClaims` is how a spec adds the claims FR-33 forbids (or
+     * removes the ones it requires), so every case reads as one deliberate change.
+     */
+    mintLogoutToken(overrides?: {
+        readonly subject?: string | null;
+        readonly sid?: string | null;
+        readonly jti?: string | null;
+        readonly issuedAt?: number;
+        readonly expiresAt?: number | null;
+        readonly events?: Record<string, unknown> | null;
+        readonly extraClaims?: Record<string, unknown>;
+    }): Promise<string>;
+    /**
+     * Post a signed notice to a relying party's back-channel endpoint, the way the
+     * provider does (FR-33's "one public endpoint", form-encoded).
+     *
+     * Answers the status and the body text rather than throwing, so a spec can assert
+     * FR-34's "an invalid notice answers 400" — and FR-34's "200 with
+     * `Cache-Control: no-store`" — on a real HTTP exchange. A token is minted first
+     * when the caller does not pass one.
+     */
+    postBackchannelLogout(url: string, token?: string, overrides?: Parameters<FakeOidcProvider['mintLogoutToken']>[0]): Promise<{
+        readonly status: number;
+        readonly body: string;
+        readonly cacheControl: string | null;
+    }>;
+    /**
+     * Approve a pending device grant — what the person does in the browser at
+     * `verification_uri` (FR-39).
+     *
+     * With no argument every pending grant is approved, which is what a spec that has
+     * just asked for one wants; the `userCode` form is there for the case that reads
+     * the code off the wire.
+     */
+    approveDeviceAuthorization(userCode?: string): number;
+    /** Every device grant this provider has issued, approved or not. */
+    get deviceGrants(): readonly {
+        readonly userCode: string;
+        readonly deviceCode: string;
+        readonly approved: boolean;
+    }[];
+    /** The last authorization request's query, or `null` when none has been made. */
+    lastAuthorizationRequest(): Record<string, string> | null;
+    /** Stop listening. Safe to call twice, and safe to call after a failed start. */
+    stop(): Promise<void>;
+    private user;
+    /**
+     * Whether `clientId` is one of the PUBLIC local clients (CLI, node) — RFC 8628
+     * public clients authenticate with their `client_id` alone, no secret.
+     */
+    private isLocalClient;
+    private rotateKeysSync;
+    private currentKey;
+    private sign;
+    private handle;
+    /** §10.4's "authorize (auto-approve a configured user)", with S256 required. */
+    private handleAuthorize;
+    /** RFC 6749 §4.1.3 and RFC 8628 §3.4–3.5: two grants, both checked. */
+    private handleToken;
+    private handleAuthorizationCodeGrant;
+    private handleDeviceCodeGrant;
+    /** RFC 8628 §3.2's device authorization response. */
+    private handleDeviceAuthorization;
+    /** RP-Initiated Logout 1.0 §2: back to the relying party, with `state` preserved. */
+    private handleEndSession;
+    private tokensFor;
+    /** `client_secret_basic` (RFC 6749 §2.3.1), which is what plan §4.2 registers. */
+    private credentialsAccepted;
+}
+/** S256: `BASE64URL(SHA256(ASCII(code_verifier)))` (RFC 7636 §4.6). */
+declare function s256(codeVerifier: string): string;
+
+export { FAKE_BACKCHANNEL_LOGOUT_EVENT, FAKE_DEFAULT_LOCAL_CLIENT_ID, FAKE_DEFAULT_USER, type FakeDevicePoll, type FakeOidcCall, type FakeOidcOmittableField, FakeOidcProvider, type FakeOidcProviderOptions, type FakeOidcProviderStarted, type FakeOidcUser, s256 };

package/dist/testing/fake-oidc-provider.d.ts

@@ -0,0 +1,321 @@
+/**
+ * APW-12 T8 — a **fake OpenID Connect provider**, published only through this
+ * package's `./testing` subpath (plan §10.4).
+ *
+ * The API integration spec (`apps/api/src/auth/ever-id.flow.integration.spec.ts`,
+ * T20/T25) and the Playwright lanes both need a provider that answers the way Ever
+ * ID will: a discovery document, a key set, an authorization endpoint that
+ * approves a configured person, a token endpoint that **checks PKCE**, device
+ * authorization with FR-41's polling rules, an end-session endpoint, and helpers
+ * that mint the access and logout tokens the verifiers are given. One fake, in one
+ * place, because a second one would be a second set of provider behaviours to keep
+ * in step.
+ *
+ * ## Why the subpath, and why that is load-bearing
+ *
+ * Plan §10.4: "published only through a `./testing` subpath export, never from the
+ * main entry". The main entry (`src/index.ts`) is what the plugin loader imports in
+ * production, and a fake provider that reached it would be dead weight in every
+ * API process — and, worse, an HTTP server behind a class the platform already
+ * instantiates. `package.json`'s `exports["./testing"]` and `tsup`'s second entry
+ * are what make that separation real; `src/__tests__/fake-oidc-provider.spec.ts`
+ * asserts it from both the source side and (when a build exists) the built side.
+ *
+ * ## What it is not
+ *
+ * It is not a security reference. It signs with ES256 keys it generates
+ * (`node:crypto`, plan §10.4 — not `jose`, so a bug in the library under test
+ * cannot hide a bug in the fake), it keeps device grants and authorization codes
+ * in memory, and it makes no attempt to be a *correct* provider in the corners the
+ * epic does not read. Where it deliberately *is* strict — PKCE S256, single-use
+ * codes, `client_secret_basic`, FR-41's poll interval — the strictness is the
+ * point: those are the behaviours the relying party has to get right, and a fake
+ * that accepted anything would prove nothing about them.
+ *
+ * ## Time
+ *
+ * Every clock read goes through the injected `now` (epoch **milliseconds**,
+ * defaulting to `Date.now`), and every minted claim is stamped from it. A spec
+ * therefore drives token lifetimes, the device-poll interval and `iat`/`exp` with
+ * literal values and an injected clock rather than by sleeping — the rule this
+ * package learned the hard way in T6.
+ */
+/**
+ * The `events` member of a back-channel logout notice — OpenID Connect
+ * Back-Channel Logout 1.0 §2.4's event identifier.
+ *
+ * Spelled here rather than imported from the plugin on purpose: this module stands
+ * in for an **external** provider, and a provider does not read the relying
+ * party's constants. `fake-oidc-provider.spec.ts` asserts that this literal and
+ * `OIDC_BACKCHANNEL_LOGOUT_EVENT` are the same string, so the two cannot drift
+ * without a red test.
+ */
+declare const FAKE_BACKCHANNEL_LOGOUT_EVENT = "http://schemas.openid.net/event/backchannel-logout";
+/** The public client an exchange token names by default. */
+declare const FAKE_DEFAULT_LOCAL_CLIENT_ID = "ever-works-cli";
+/** The person the provider approves when a spec configures nobody (§10.4). */
+declare const FAKE_DEFAULT_USER: {
+    readonly subject: "ever-id-subject-1";
+    readonly email: "person@example.com";
+    readonly emailVerified: true;
+    readonly name: "A Person";
+};
+/** The document fields a spec may ask the fake to leave out (FR-3's rows, FR-36's `null`). */
+type FakeOidcOmittableField = 'authorization_endpoint' | 'token_endpoint' | 'jwks_uri' | 'end_session_endpoint' | 'device_authorization_endpoint' | 'code_challenge_methods_supported' | 'backchannel_logout_supported';
+/** The person this provider signs in. */
+interface FakeOidcUser {
+    readonly subject: string;
+    readonly email: string;
+    readonly emailVerified?: boolean;
+    readonly name?: string;
+}
+/** Construction options for {@link FakeOidcProvider.start}. */
+interface FakeOidcProviderOptions {
+    /** The person auto-approved at `/authorize` and at device authorization. */
+    readonly user?: FakeOidcUser;
+    /** The relying party's client id. Default `ever-works-web`. */
+    readonly clientId?: string;
+    /**
+     * The `client_secret_basic` secret the token endpoint requires, or `null` to
+     * accept any (a spec that is not exercising client authentication).
+     */
+    readonly clientSecret?: string | null;
+    /** The audience a minted access token carries. Default `ever-works`. */
+    readonly apiAudience?: string;
+    /** The public clients an exchange token may name in `azp`. */
+    readonly localClients?: readonly {
+        readonly kind: 'cli' | 'node';
+        readonly clientId: string;
+    }[];
+    /** FR-44's scope a delegated access token carries. Default `apps:read`. */
+    readonly delegatedScope?: string;
+    /** FR-39/FR-40's scope an exchange access token carries. Default `ever-works:session`. */
+    readonly exchangeScope?: string;
+    /** How long a minted access token lives when the caller does not say. Default 300. */
+    readonly accessTokenLifetimeSeconds?: number;
+    /** FR-41's poll interval the device endpoint returns, in seconds. Default 5. */
+    readonly devicePollIntervalSeconds?: number;
+    /** How long a device code lives. Default 900 (FR-41). */
+    readonly deviceCodeLifetimeSeconds?: number;
+    /** How long an authorization code lives. Default 60. */
+    readonly authorizationCodeLifetimeSeconds?: number;
+    /** Document fields to leave out, so a spec can drive the rows and the `null` answers. */
+    readonly omit?: readonly FakeOidcOmittableField[];
+    /** The clock, in epoch milliseconds. Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/** One request the provider received, so a spec can assert on what actually went out. */
+interface FakeOidcCall {
+    readonly method: string;
+    readonly path: string;
+    /** The query string, as a plain object (a repeated key keeps its first value). */
+    readonly query: Record<string, string>;
+    /** The `application/x-www-form-urlencoded` body, as a plain object. */
+    readonly form: Record<string, string>;
+    /** The request headers, lower-cased. */
+    readonly headers: Record<string, string>;
+}
+/** What a device-code poll answered. */
+interface FakeDevicePoll {
+    readonly status: number;
+    readonly body: Record<string, unknown>;
+}
+/** What {@link FakeOidcProvider.start} resolves to. */
+type FakeOidcProviderStarted = FakeOidcProvider;
+/**
+ * A local OpenID Connect provider, for specs.
+ *
+ * `start()` binds an ephemeral port on the loopback interface and answers on
+ * `http://localhost:<port>` — the one non-TLS issuer `settings.schema.ts` accepts
+ * and the one the plugin's configuration tells `openid-client` about
+ * (`isInsecureIssuer`). The issuer therefore depends on the port and is only known
+ * after the server is listening, which is why construction goes through `start()`.
+ */
+declare class FakeOidcProvider {
+    /** Every request, in order — method, path, query, form and headers. */
+    readonly calls: FakeOidcCall[];
+    private readonly options;
+    private readonly keys;
+    private readonly codes;
+    private readonly devices;
+    private server;
+    private issuerUrl;
+    private keySequence;
+    /** The person approved from now on, when a spec changed it after start (see {@link setUser}). */
+    private userOverride;
+    /** Extra claims every ID token minted from now on carries (see {@link setIdTokenClaims}). */
+    private extraIdTokenClaims;
+    /** The provider session id (`sid`) the next tokens carry (see {@link setSessionId}). */
+    private sessionId;
+    private constructor();
+    /** Bind a port and answer the discovery document a relying party will read. */
+    static start(options?: FakeOidcProviderOptions): Promise<FakeOidcProvider>;
+    /**
+     * Bind an ephemeral loopback port and answer `/…/.well-known/openid-configuration`.
+     *
+     * Kept additive and public so a caller that wants a provider on a **fixed** port
+     * (a Playwright lane that must tell the API where to find it before the process
+     * starts) can build one; `start()` is the ordinary entry point.
+     */
+    listen(port?: number): Promise<void>;
+    /** The issuer the discovery document advertises, and the settings' `issuerUrl`. */
+    get issuer(): string;
+    /** The bound port. */
+    get port(): number;
+    get discoveryUrl(): string;
+    get jwksUri(): string;
+    get authorizationEndpoint(): string;
+    get tokenEndpoint(): string;
+    get endSessionEndpoint(): string;
+    get deviceAuthorizationEndpoint(): string;
+    /** The relying party's client id the token endpoint expects. */
+    get clientId(): string;
+    /** The `client_secret_basic` secret the token endpoint expects, or `null` for "any". */
+    get clientSecret(): string | null;
+    /** The API audience a minted access token carries. */
+    get apiAudience(): string;
+    /** The `azp` a minted access token carries when the caller does not say. */
+    get defaultAuthorizedParty(): string;
+    /** The document this provider publishes, with the fields `omit` removed. */
+    discoveryDocument(): Record<string, unknown>;
+    /** FR-44's delegated scope this provider mints. */
+    get delegatedScope(): string;
+    /** FR-39/FR-40's exchange scope this provider mints. */
+    get exchangeScope(): string;
+    /** The current clock, in epoch milliseconds. */
+    now(): number;
+    /** The current clock, in whole seconds — the unit every JWT time claim uses. */
+    nowSeconds(): number;
+    /**
+     * Replace the signing key, the way a provider rotates one (FR-13, ACC-12-08).
+     *
+     * `keepPrevious` publishes the old key alongside the new one, which is what a
+     * rollover looks like while tokens signed with it are still in flight; the
+     * default is the harder case, where the old key is **gone** and a token signed
+     * with it must stop validating.
+     */
+    rotateKeys(options?: {
+        keepPrevious?: boolean;
+    }): Promise<void>;
+    /** The current key id, so a spec can name what it is signing with. */
+    /**
+     * Change the person the provider approves from now on — so one running fake
+     * can sign in a connected identity, a new one and one whose e-mail an account
+     * already uses, in turn. Additive test seam; the constructor option still sets
+     * the first person.
+     */
+    setUser(user: FakeOidcUser): void;
+    /**
+     * Extra claims every ID token minted from now on carries (for example the
+     * optional `urn:ever:` hint claims). Pass `{}` to stop adding any.
+     */
+    setIdTokenClaims(claims: Record<string, unknown>): void;
+    /** The provider session id (`sid`) the next ID tokens and logout tokens carry. */
+    setSessionId(sid: string): void;
+    /** The provider session id the next tokens carry. */
+    get currentSessionId(): string;
+    get currentKeyId(): string;
+    /**
+     * Sign an ID token for the configured person — what the token endpoint answers
+     * with, and what a spec can use to drive `exchangeAuthorizationCode` directly.
+     */
+    mintIdToken(overrides?: Record<string, unknown>): Promise<string>;
+    /**
+     * Sign an access token — the artifact FR-40's exchange and FR-45's delegated read
+     * are handed.
+     *
+     * The defaults are a **valid** token for the configured installation: `aud` is
+     * the API audience, `azp` is the first configured local client,
+     * `scope` is the exchange scope, `iat` is now and `exp` is now plus
+     * {@link FakeOidcProviderOptions.accessTokenLifetimeSeconds}. Every case in a
+     * spec is therefore "everything is valid, except this", and the literal numbers
+     * a case wants are passed in rather than derived from the plugin.
+     */
+    mintAccessToken(overrides?: {
+        readonly scopes?: readonly string[];
+        readonly authorizedParty?: string | null;
+        readonly audience?: string | readonly string[];
+        readonly subject?: string;
+        readonly issuedAt?: number;
+        readonly expiresAt?: number;
+        readonly jti?: string | null;
+        readonly claims?: Record<string, unknown>;
+    }): Promise<string>;
+    /**
+     * Sign a back-channel logout notice (FR-33).
+     *
+     * The default is a **valid** notice about the configured person's session:
+     * the event member, an `iat` of now, a fresh `jti`, `sid` and no `nonce`, `exp`
+     * or `sub`. `extraClaims` is how a spec adds the claims FR-33 forbids (or
+     * removes the ones it requires), so every case reads as one deliberate change.
+     */
+    mintLogoutToken(overrides?: {
+        readonly subject?: string | null;
+        readonly sid?: string | null;
+        readonly jti?: string | null;
+        readonly issuedAt?: number;
+        readonly expiresAt?: number | null;
+        readonly events?: Record<string, unknown> | null;
+        readonly extraClaims?: Record<string, unknown>;
+    }): Promise<string>;
+    /**
+     * Post a signed notice to a relying party's back-channel endpoint, the way the
+     * provider does (FR-33's "one public endpoint", form-encoded).
+     *
+     * Answers the status and the body text rather than throwing, so a spec can assert
+     * FR-34's "an invalid notice answers 400" — and FR-34's "200 with
+     * `Cache-Control: no-store`" — on a real HTTP exchange. A token is minted first
+     * when the caller does not pass one.
+     */
+    postBackchannelLogout(url: string, token?: string, overrides?: Parameters<FakeOidcProvider['mintLogoutToken']>[0]): Promise<{
+        readonly status: number;
+        readonly body: string;
+        readonly cacheControl: string | null;
+    }>;
+    /**
+     * Approve a pending device grant — what the person does in the browser at
+     * `verification_uri` (FR-39).
+     *
+     * With no argument every pending grant is approved, which is what a spec that has
+     * just asked for one wants; the `userCode` form is there for the case that reads
+     * the code off the wire.
+     */
+    approveDeviceAuthorization(userCode?: string): number;
+    /** Every device grant this provider has issued, approved or not. */
+    get deviceGrants(): readonly {
+        readonly userCode: string;
+        readonly deviceCode: string;
+        readonly approved: boolean;
+    }[];
+    /** The last authorization request's query, or `null` when none has been made. */
+    lastAuthorizationRequest(): Record<string, string> | null;
+    /** Stop listening. Safe to call twice, and safe to call after a failed start. */
+    stop(): Promise<void>;
+    private user;
+    /**
+     * Whether `clientId` is one of the PUBLIC local clients (CLI, node) — RFC 8628
+     * public clients authenticate with their `client_id` alone, no secret.
+     */
+    private isLocalClient;
+    private rotateKeysSync;
+    private currentKey;
+    private sign;
+    private handle;
+    /** §10.4's "authorize (auto-approve a configured user)", with S256 required. */
+    private handleAuthorize;
+    /** RFC 6749 §4.1.3 and RFC 8628 §3.4–3.5: two grants, both checked. */
+    private handleToken;
+    private handleAuthorizationCodeGrant;
+    private handleDeviceCodeGrant;
+    /** RFC 8628 §3.2's device authorization response. */
+    private handleDeviceAuthorization;
+    /** RP-Initiated Logout 1.0 §2: back to the relying party, with `state` preserved. */
+    private handleEndSession;
+    private tokensFor;
+    /** `client_secret_basic` (RFC 6749 §2.3.1), which is what plan §4.2 registers. */
+    private credentialsAccepted;
+}
+/** S256: `BASE64URL(SHA256(ASCII(code_verifier)))` (RFC 7636 §4.6). */
+declare function s256(codeVerifier: string): string;
+
+export { FAKE_BACKCHANNEL_LOGOUT_EVENT, FAKE_DEFAULT_LOCAL_CLIENT_ID, FAKE_DEFAULT_USER, type FakeDevicePoll, type FakeOidcCall, type FakeOidcOmittableField, FakeOidcProvider, type FakeOidcProviderOptions, type FakeOidcProviderStarted, type FakeOidcUser, s256 };