@ever-works/oidc-identity 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1468 @@
+import { IdentityTokenRejectionCode, JsonSchema, IPlugin, IIdentityProviderPlugin, PluginCategory, PluginContext, IdentityProviderCheck, VerifiedIdTokenClaims, VerifiedAccessTokenClaims, VerifiedLogoutTokenClaims, PluginHealthCheck, PluginManifest } from '@ever-works/plugin';
+import { JWSHeaderParameters, CryptoKey, KeyObject } from 'jose';
+
+/**
+ * APW-12 T6 — the discovery half of the `identity-provider` capability: reading
+ * the provider's OpenID Connect discovery document, and the outbound rule every
+ * call to Ever ID obeys.
+ *
+ * Spec: FR-3 (what **Test connection** reads and reports), FR-14 (the discovery
+ * document is cached for 3,600 seconds; a changed issuer turns sign-in off until
+ * an administrator re-tests), FR-15 (5,000 ms timeout; discovery and key fetches
+ * retry once after 1,000 ms) and FR-16 (nothing here may reach a log with token
+ * material in it). Plan §4.3 is the table these numbers come from.
+ *
+ * ## Why this reads the document itself instead of `openid-client.discovery()`
+ *
+ * Plan §4.2 names `openid-client` as the flow's tool, and it stays that: T7 and
+ * T8 build the `Configuration` (`buildAuthorizationUrl`,
+ * `authorizationCodeGrant`) from the document this module read. The diagnostic
+ * read cannot be that call, for two measured reasons:
+ *
+ *   1. **FR-3 wants a row per check, not an exception.** `openid-client`'s
+ *      `discovery()` rejects when the discovered `issuer` differs from the
+ *      address it fetched (`build/index.js` — "discovered metadata issuer does
+ *      not match the expected issuer"), and that rejection is precisely the
+ *      `issuerMatch` row FR-3 asks **Test connection** to render. A call that
+ *      throws cannot report "the endpoints are present but S256 is missing"
+ *      either: it is all-or-nothing.
+ *   2. **FR-15's retry and testability.** `discovery()` bounds itself with
+ *      `AbortSignal.timeout()` — a native timer a fake clock cannot drive — and
+ *      performs no retry; §4.3 asks for one retry after 1,000 ms.
+ *
+ * Both reasons are about the *diagnostic* path only. Nothing here duplicates a
+ * security decision: the document this module returns is the document T7/T8 feed
+ * to `openid-client`, and the numbers below are the same §4.3 numbers.
+ *
+ * ## The numbers, and the one place they come from
+ *
+ * The constants below mirror `EVER_ID_LIMITS` in
+ * `packages/contracts/src/apps/ever-id.ts` — plan §4.3's single source. This
+ * package does not depend on `@ever-works/contracts` (T5 transcribed the
+ * settings-schema bounds the same way and said so), so the values are
+ * transcribed here rather than imported, and
+ * `src/__tests__/test-connection.spec.ts` reads the contracts source off disk and
+ * asserts the two agree, so a drift on either side reddens a test instead of
+ * shipping.
+ */
+/**
+ * FR-15 — every call to Ever ID times out after 5,000 ms.
+ *
+ * This is the per-attempt bound. For **Test connection** it is also the bound on
+ * the whole run (FR-3, ACC-12-03): `testConnection` passes a deadline so the
+ * retry can never push the answer past 5 seconds.
+ */
+declare const OIDC_OUTBOUND_TIMEOUT_MS = 5000;
+/** FR-15 — discovery and key fetches retry **once** after 1,000 ms. */
+declare const OIDC_OUTBOUND_RETRY_DELAY_MS = 1000;
+/** FR-15 — "retry once": two attempts, never three. */
+declare const OIDC_OUTBOUND_MAX_ATTEMPTS = 2;
+/** FR-14 — the discovery document is cached for 3,600 seconds. */
+declare const OIDC_DISCOVERY_CACHE_SECONDS = 3600;
+/** FR-13 — signing keys are cached for 600 seconds. */
+declare const OIDC_JWKS_CACHE_SECONDS = 600;
+/** FR-13 — an unknown key id triggers at most one refresh per 30 seconds. */
+declare const OIDC_JWKS_UNKNOWN_KID_COOLDOWN_SECONDS = 30;
+/** FR-13 — cached keys stay usable for at most 21,600 seconds, then fail closed. */
+declare const OIDC_JWKS_MAX_STALE_SECONDS = 21600;
+/**
+ * FR-11 / FR-3 — the only signing algorithms Ever ID may use, in one place.
+ *
+ * FR-11 accepts an ID token signed with one of these three; FR-3 reports failure
+ * when the provider advertises none of them. The key cache (§4.3) rejects `none`
+ * and `HS*` **before** it looks a key up, which is this same list read as an
+ * allow-list.
+ */
+declare const OIDC_IDENTITY_SIGNING_ALGS: readonly ["RS256", "ES256", "EdDSA"];
+/** One of {@link OIDC_IDENTITY_SIGNING_ALGS}. */
+type OidcIdentitySigningAlg = (typeof OIDC_IDENTITY_SIGNING_ALGS)[number];
+/**
+ * The subset of the token-rejection vocabulary (`@ever-works/plugin`) this module
+ * can raise.
+ *
+ * `providerUnavailable` is the honest answer when the provider cannot be reached
+ * or its keys can no longer be trusted; T7/T8 rethrow it as
+ * `IdentityTokenRejectedError` with the same code, so the closed set the contract
+ * publishes stays the only vocabulary a caller branches on.
+ */
+type OidcProviderUnavailableCode = Extract<IdentityTokenRejectionCode, 'providerUnavailable'>;
+/**
+ * Why the provider is unavailable — a closed set, never a provider's own text.
+ *
+ * FR-16 forbids a message carrying token material, and the cheapest way to keep
+ * that promise in a path that has a client secret in scope is to have no free
+ * text at all: `OidcProviderUnavailableError.message` **is** the code, and this
+ * reason names which rule failed. T12 maps it onto the facade's
+ * `IdentityProviderUnavailableError`; T32 records it in `availability`.
+ */
+type OidcProviderUnavailableReason = 
+/** FR-2/FR-3 — the integration is not configured, so nothing can be read. */
+'notConfigured'
+/** FR-14 — the discovery document could not be read. */
+ | 'discoveryFailed'
+/** FR-14 — the provider advertises a different issuer than the configured one. */
+ | 'issuerDrift'
+/** FR-3 — discovery answered, but a required capability is missing. */
+ | 'discoveryIncomplete'
+/** FR-13 — no key set has ever been fetched, so nothing may be verified. */
+ | 'keysUnavailable'
+/** FR-13 — the last good key fetch is older than 21,600 seconds: fail closed. */
+ | 'keysStale';
+/**
+ * The single error a discovery or key-set failure raises (FR-14, FR-13).
+ *
+ * `message` is the code and nothing else — no issuer echo, no HTTP body, no
+ * client secret (FR-16). Extending `Error` is load-bearing exactly as it is for
+ * `IdentityTokenRejectedError`: callers catch it as an `Error` and branch on
+ * `code`, and a reason they do not recognise must degrade to "unavailable",
+ * never to a pass.
+ */
+declare class OidcProviderUnavailableError extends Error {
+    readonly reason: OidcProviderUnavailableReason;
+    readonly code: OidcProviderUnavailableCode;
+    constructor(reason: OidcProviderUnavailableReason);
+}
+/**
+ * The discovery document, as far as this package reads it.
+ *
+ * Only the fields FR-3 and T7/T8's flow need are named; the index signature keeps
+ * every other claim (`userinfo_endpoint`, `end_session_endpoint`,
+ * `revocation_endpoint`, `token_endpoint_auth_methods_supported`, …) verbatim, so
+ * a later task reads a claim without re-fetching and without this interface
+ * having to grow first.
+ */
+interface OidcDiscoveryDocument {
+    /** The issuer the provider claims — FR-3 compares it to the configured one, exactly. */
+    issuer: string;
+    authorization_endpoint?: string;
+    token_endpoint?: string;
+    jwks_uri?: string;
+    end_session_endpoint?: string;
+    device_authorization_endpoint?: string;
+    code_challenge_methods_supported?: string[];
+    id_token_signing_alg_values_supported?: string[];
+    backchannel_logout_supported?: boolean;
+    backchannel_logout_session_supported?: boolean;
+    [claim: string]: unknown;
+}
+/** The shape of a response this module needs — a structural subset of `Response`. */
+interface OidcHttpResponse {
+    readonly ok: boolean;
+    readonly status: number;
+    json(): Promise<unknown>;
+}
+/**
+ * What this module hands the fetch seam.
+ *
+ * `signal` and `headers` are what T6 needed; `method` and `body` were added by
+ * **T7**, because the code exchange is the one call that is not a GET — and a
+ * spec that cannot see the request it is asserting on cannot prove FR-15's
+ * `client_secret_basic`, the four form fields of RFC 6749 §4.1.3 or the absence
+ * of a retry. Both are optional and both default to a bodyless GET, so every
+ * T6 fake that ignores them keeps compiling and keeps its behaviour.
+ */
+interface OidcFetchInit {
+    readonly signal: AbortSignal;
+    readonly headers: Record<string, string>;
+    /** The HTTP method; the callers that pass one pass `POST`. Defaults to a GET. */
+    readonly method?: string;
+    /** The already-encoded request body, sent only when present. */
+    readonly body?: string;
+}
+/**
+ * The seam every outbound call goes through.
+ *
+ * Optional everywhere it is used, and defaulting to the runtime's `fetch`: the
+ * platform's plugin loader constructs a plugin with no arguments
+ * (`PluginLoaderService.loadPluginModule`, `plugin-loader.service.ts:364` —
+ * `new PluginClass()`), so an injected fetch is a test's business and never a
+ * production requirement.
+ */
+type OidcFetchImpl = (url: string, init: OidcFetchInit) => Promise<OidcHttpResponse>;
+/** One JSON request. */
+interface OidcOutboundRequest {
+    readonly url: string;
+    /** Extra headers; `accept: application/json` is always sent. */
+    readonly headers?: Record<string, string>;
+    /**
+     * The HTTP method. Absent means a GET — the discovery read and the key fetch
+     * (FR-3, FR-13). T7's code exchange passes `POST`, the one call that is not.
+     */
+    readonly method?: string;
+    /** The request body, encoded by the caller; sent only when present. */
+    readonly body?: string;
+    /**
+     * Sent as `content-type` when a body is sent.
+     *
+     * The token endpoint of RFC 6749 §4.1.3 takes
+     * `application/x-www-form-urlencoded`; a provider that checks the header — as
+     * ZITADEL and Keycloak both do — answers `415` without it.
+     */
+    readonly contentType?: string;
+}
+/** Every injectable knob of an outbound call. */
+interface OidcOutboundOptions {
+    readonly fetchImpl?: OidcFetchImpl;
+    /** The clock, in epoch milliseconds. Defaults to `Date.now`. */
+    readonly now?: () => number;
+    readonly timeoutMs?: number;
+    readonly retryDelayMs?: number;
+    /**
+     * Absolute epoch-ms deadline the **whole** call must fit inside.
+     *
+     * FR-3 gives **Test connection** 5 seconds for every check, while FR-15 gives
+     * discovery one retry after 1 second — with a 5,000 ms per-attempt timeout the
+     * two together would allow 11 seconds. The deadline is how the two are kept:
+     * the retry happens whenever it fits, and the answer is reported at the
+     * deadline either way. Callers with no such bound (the key fetch, FR-13) leave
+     * it undefined and get §4.3 literally.
+     */
+    readonly deadlineAt?: number;
+}
+/** Why a JSON GET did not produce a body. */
+type OidcOutboundFailure = 'timeout' | 'httpStatus' | 'network' | 'invalidBody';
+/** The outcome of {@link fetchJsonWithOneRetry}. */
+interface OidcOutboundResult {
+    readonly ok: boolean;
+    /** Present as soon as a response was received, pass or fail. */
+    readonly status?: number;
+    /** The parsed body, when `ok`. */
+    readonly body?: unknown;
+    /** Why it failed, when not `ok`. */
+    readonly failure?: OidcOutboundFailure;
+    /** How many attempts were started — 1 or 2 (FR-15). */
+    readonly attempts: number;
+}
+/**
+ * One request, **never retried** — FR-15's "the code exchange is never retried".
+ *
+ * Same per-attempt bound as {@link fetchJsonWithOneRetry}
+ * ({@link OIDC_OUTBOUND_TIMEOUT_MS}, on a `setTimeout` so an injected clock and
+ * vitest's fake timers can drive it) and the same never-rejects contract, but a
+ * single attempt by construction rather than by option: a security-relevant
+ * "no second try" is safer as a different function than as a flag a caller can
+ * pass wrongly. FR-15 gives the token endpoint 5,000 ms and one attempt, and
+ * this is that rule.
+ *
+ * `deadlineAt` is honoured when a caller passes one, and reports how many
+ * attempts had started when the bound was reached — `1` once the request is in
+ * flight, `0` if it never was.
+ */
+declare function fetchJsonOnce(request: OidcOutboundRequest, options?: OidcOutboundOptions): Promise<OidcOutboundResult>;
+/** Why a discovery read produced no document. */
+type OidcDiscoveryFailure = OidcOutboundFailure
+/** The configured issuer is not an address a discovery document can be read from. */
+ | 'invalidIssuer'
+/** A 200 answered with a body that is not an object carrying a string `issuer`. */
+ | 'invalidDocument';
+/** The outcome of one discovery read (FR-3, FR-14). */
+type OidcDiscoveryRead = {
+    readonly ok: true;
+    readonly document: OidcDiscoveryDocument;
+    readonly fetchedAt: number;
+    /**
+     * FR-3: whether the document's `issuer` equals the configured issuer
+     * **exactly**. A `false` here is a reported check row, not an exception —
+     * and every other read path in this class refuses to hand the document on
+     * when it is false (FR-14's disable).
+     */
+    readonly issuerMatches: boolean;
+    readonly attempts: number;
+} | {
+    readonly ok: false;
+    readonly failure: OidcDiscoveryFailure;
+    readonly attempts: number;
+    readonly status?: number;
+};
+/** Construction options for {@link OidcDiscoveryReader}. */
+interface OidcDiscoveryOptions extends OidcOutboundOptions {
+    /** The administrator's configured issuer address (FR-2), compared exactly. */
+    readonly issuerUrl: string;
+    /** FR-14's 3,600 seconds; overridable so a spec can pin the boundary. */
+    readonly cacheSeconds?: number;
+}
+/**
+ * The discovery document, read, cached for 3,600 seconds and refused on drift
+ * (FR-14).
+ *
+ * Two entry points, and the difference between them is the point:
+ *
+ *   - {@link read} **always** fetches. It is what **Test connection** calls, because
+ *     an administrator pressing the button is asking the provider a question and a
+ *     cached answer would defeat FR-14's "until an administrator re-tests".
+ *   - {@link get} serves the cache and refreshes it when it has expired. It is what
+ *     the flow calls, and it fails closed — `providerUnavailable` — whenever the
+ *     document could not be read or the provider's issuer has drifted, so a
+ *     sign-in can never proceed against a provider whose identity changed under
+ *     it.
+ */
+declare class OidcDiscoveryReader {
+    private readonly options;
+    private document;
+    private fetchedAtMs;
+    constructor(options: OidcDiscoveryOptions);
+    /** The configured issuer this reader answers for (FR-7: one issuer set per installation). */
+    get issuerUrl(): string;
+    /**
+     * When the last successful read happened, in epoch ms, or `null`.
+     *
+     * This is the in-process source of plan §4.2's `availability.discoveryRefreshedAt`
+     * and of plan §9.1's health view; T32 persists it.
+     */
+    get lastRefreshedAt(): number | null;
+    /** The cached document while FR-14's 3,600 seconds have not elapsed, else `null`. */
+    cachedDocument(): OidcDiscoveryDocument | null;
+    /**
+     * Read the document from the provider now (FR-3's read, FR-14's 3,600-second cache
+     * entry point).
+     *
+     * A successful read replaces the cache even when the issuer drifts: the drift is
+     * what an administrator needs to see, and {@link get} refuses it either way.
+     */
+    read(options?: {
+        deadlineAt?: number;
+    }): Promise<OidcDiscoveryRead>;
+    /**
+     * The document, from the cache while it is fresh and from the provider once it is
+     * not (FR-14). Throws {@link OidcProviderUnavailableError} rather than returning
+     * `null`: every caller of this method is on a path that must not continue without
+     * a document.
+     */
+    get(): Promise<OidcDiscoveryDocument>;
+    /** FR-14: a different issuer turns sign-in off until an administrator re-tests. */
+    private assertIssuerMatches;
+    private now;
+}
+
+/**
+ * APW-12 T5 — the `oidc-identity` plugin settings (plan §4.2, setting key by
+ * setting key; spec FR-2 holds the same list in prose).
+ *
+ * Every constraint below is transcribed from plan §4.2's table — the same
+ * numbers as `EVER_ID_LIMITS` in `packages/contracts/src/apps/ever-id.ts`,
+ * which plan §4.3 makes the single source for the *runtime* checks. Nothing is
+ * invented here: no key, bound, default or requirement appears that the table
+ * does not state, so a tightening of the schema cannot silently refuse a
+ * configuration the plan allows.
+ *
+ * Three properties of this schema are load-bearing, and are pinned by
+ * `src/__tests__/settings.schema.spec.ts` rather than asserted in prose here:
+ *
+ *   - **`clientSecret` is `x-secret`** (Constitution VII, spec FR-16 / ACC-12-03).
+ *     The marker is the only thing that makes the platform treat the value as a
+ *     secret: `packages/plugin/src/api/api-response.types.ts:129` turns it into
+ *     `secret: true` on the descriptor every API response is built from, and
+ *     `packages/agent/src/plugins/services/plugin-operations.service.ts:1792`
+ *     and `:1932` mask exactly those fields. Drop the marker and the secret
+ *     becomes an ordinary setting, readable back out of the settings API.
+ *   - **every key is `x-scope: 'global'`** (plan §4.2, FR-7). One issuer set per
+ *     installation, configured by a platform admin: the schema is admin-tier, so
+ *     `SettingsSchemaValidatorService.filterSchemaByScope`
+ *     (`packages/agent/src/plugins/services/settings-schema-validator.service.ts:247`)
+ *     never offers these keys to a user- or work-scoped read or write.
+ *   - **the issuer rule is split across schema and runtime.** JSON Schema is
+ *     static, so the schema carries the half that does not depend on the
+ *     environment — `https` anywhere, `http` only for `localhost`/`127.0.0.1` —
+ *     while the plan's remaining half (`http` is refused outside development)
+ *     is a `NODE_ENV` check.
+ *
+ *     **That runtime half now exists** (2026-09-21), in
+ *     `oidc-identity.plugin.ts`: `allowsInsecureIssuer` is an allow-list of
+ *     `development` / `test`, applied in `resolveSettings` (the chokepoint every
+ *     public method goes through, so a refused issuer refuses discovery, the key
+ *     fetch, the code exchange, both verifiers and `testConnection` together) and
+ *     again where `allowInsecureRequests` is called. Until then the sentence above
+ *     said T6 owned the check, T6 never wrote it, and a comment at the
+ *     `allowInsecureRequests` call site asserted the gate as though it were in
+ *     place — which is what kept it unnoticed. Do not restate a gate here without
+ *     naming the function that enforces it.
+ *
+ * **A bound in this schema is a write-time check, and for an `x-envVar` key that
+ * is not `x-secret` it never runs.** `PluginSettingsService.filterEnvVarFields`
+ * strips every key that is `x-envVar` and not `x-secret` from settings writes, so
+ * the validator never sees it. (`clientSecret` is both, so it is kept and IS
+ * validated on write.) The value is read from its environment variable by `parseEnvValue`,
+ * which turns an `integer` key into `Number(value)` and checks nothing else. So
+ * `clockSkewSeconds`'s `minimum: 0` / `maximum: 120` (FR-2) does not reach the
+ * value the plugin reads. That bound is enforced at run time by
+ * `isClockSkewInBounds` in `oidc-identity.plugin.ts`, applied in
+ * `resolveSettings` against `OIDC_MAX_CLOCK_SKEW_SECONDS` (2026-09-25). A value
+ * outside it turns the integration off as `notConfigured`, with the field name
+ * logged and the value not logged. `src/__tests__/clock-skew-gate.spec.ts` pins
+ * that constant against this schema's `maximum` and `EVER_ID_LIMITS`. Until then
+ * the plugin applied the stored value unchecked, and an out-of-range, `NaN` or
+ * string value widened or switched off every token time check.
+ */
+/**
+ * `https://…`, or `http://localhost…` / `http://127.0.0.1…` with an optional
+ * port and path (plan §4.2 `issuerUrl`, spec FR-2). Anything else is refused by
+ * the settings validator before it is ever persisted.
+ */
+declare const oidcIdentityIssuerUrlPattern = "^(https://[^\\s]+|http://(localhost|127\\.0\\.0\\.1)(:\\d{1,5})?(/[^\\s]*)?)$";
+/** `https://…` only — the **Manage in Ever ID ↗** target (plan §4.2). */
+declare const oidcIdentityHttpsUrlPattern = "^https://[^\\s]+$";
+/** One local client allowed to exchange an Ever ID token for a session (FR-39). */
+interface OidcIdentityLocalClient {
+    kind: 'cli' | 'node';
+    clientId: string;
+}
+/** A remembered delegated client and the name the card shows it under (FR-48). */
+interface OidcIdentityDelegatedClientName {
+    clientId: string;
+    displayName?: string;
+}
+/**
+ * Platform-written availability state (plan §4.2, §9.2). Stored in the plugin's
+ * own settings row so every replica reads the same state — a re-test on one
+ * replica clears the flag on all of them (FR-5). Never user-writable: the
+ * property is `x-hidden`.
+ */
+interface OidcIdentityAvailability {
+    unavailableSince?: string;
+    discoveryRefreshedAt?: string;
+    jwksRefreshedAt?: string;
+    lastLogoutNoticeAt?: string;
+}
+/** The settings this plugin reads once resolved (plan §4.2). */
+interface OidcIdentitySettings {
+    issuerUrl: string;
+    clientId: string;
+    clientSecret: string;
+    allowedIssuers?: string[];
+    apiAudience?: string;
+    localClients?: OidcIdentityLocalClient[];
+    delegatedClientNames?: OidcIdentityDelegatedClientName[];
+    accountManagementUrl?: string;
+    signUpAllowed?: boolean;
+    clockSkewSeconds?: number;
+    displayName?: string;
+    availability?: OidcIdentityAvailability;
+}
+/** Every top-level key of plan §4.2, in the table's own order. */
+declare const OIDC_IDENTITY_SETTING_KEYS: readonly ["issuerUrl", "clientId", "clientSecret", "allowedIssuers", "apiAudience", "localClients", "delegatedClientNames", "accountManagementUrl", "signUpAllowed", "clockSkewSeconds", "displayName", "availability"];
+/** Union of {@link OIDC_IDENTITY_SETTING_KEYS}. */
+type OidcIdentitySettingKey = (typeof OIDC_IDENTITY_SETTING_KEYS)[number];
+declare const oidcIdentitySettingsSchema: JsonSchema;
+
+/**
+ * FR-9 — the `state` a sign-in carries is **at least 32 random bytes**
+ * (`EVER_ID_LIMITS.stateBytes`; plan §3.5 seals it in the transaction cookie).
+ *
+ * Exported so the number is pinnable by a spec that reads the contract off disk,
+ * exactly as T6 pinned FR-13's three numbers: the behavioural cases in
+ * `src/__tests__/authorization-request.spec.ts` assert against the literals
+ * `32`/`32`/`64` in FR-9's own words, and this constant is asserted against
+ * `EVER_ID_LIMITS` separately.
+ */
+declare const OIDC_STATE_BYTES = 32;
+/** FR-9 — the `nonce` a sign-in carries is **at least 32 random bytes** (`EVER_ID_LIMITS.nonceBytes`). */
+declare const OIDC_NONCE_BYTES = 32;
+/**
+ * FR-9 — the PKCE code verifier is **64 characters** (`EVER_ID_LIMITS.codeVerifierLength`).
+ *
+ * Randomness is drawn as {@link OIDC_CODE_VERIFIER_BYTES} bytes and encoded
+ * base64url, which is 64 characters for 48 bytes. The two constants are separate
+ * because they are two different requirements — "64 characters" is FR-9's, and
+ * the byte count is this package's choice of an encoding that produces exactly
+ * that — and the spec asserts that the encoding of 48 bytes really is 64
+ * characters rather than assuming it.
+ */
+declare const OIDC_CODE_VERIFIER_LENGTH = 64;
+/** How many random bytes base64url encode to {@link OIDC_CODE_VERIFIER_LENGTH} characters. */
+declare const OIDC_CODE_VERIFIER_BYTES = 48;
+/**
+ * FR-2 — the default clock-skew tolerance, in seconds
+ * (`EVER_ID_LIMITS.defaultClockSkewSeconds`; the schema's `clockSkewSeconds`
+ * default is the same number, and the spec asserts the two agree).
+ */
+declare const OIDC_DEFAULT_CLOCK_SKEW_SECONDS = 60;
+/**
+ * FR-2 — the widest clock-skew tolerance an administrator may configure, in
+ * seconds (`EVER_ID_LIMITS.maxClockSkewSeconds`). The schema's `clockSkewSeconds`
+ * maximum is the same number, and `src/__tests__/clock-skew-gate.spec.ts` asserts
+ * that all three agree.
+ *
+ * {@link isClockSkewInBounds} applies it at run time. The schema bound alone never
+ * reaches the value this plugin reads (see that function).
+ */
+declare const OIDC_MAX_CLOCK_SKEW_SECONDS = 120;
+/**
+ * FR-11 — an `iat` may be **no earlier than 600 seconds ago**
+ * (`EVER_ID_LIMITS.idTokenMaxAgeSeconds`; plan §4.3's "ID token times" row).
+ */
+declare const OIDC_ID_TOKEN_MAX_AGE_SECONDS = 600;
+/**
+ * FR-11 — `sub` is **1–255 characters**.
+ *
+ * The bound is asymmetric on purpose: an empty subject identifies nobody, and a
+ * longer one is not a subject any provider's directory would mint — FR-31 stores
+ * the value, so the column's width is a decision this check is allowed to make.
+ */
+declare const OIDC_SUBJECT_MAX_LENGTH = 255;
+/**
+ * FR-2 — the audience a delegated or exchanged access token must carry when an
+ * administrator configured none (`EVER_ID_DEFAULT_API_AUDIENCE`; plan §4.2's
+ * `apiAudience` row, APW-11 §2.4).
+ *
+ * Until T8 this literal lived only inside `getPublicConfig`; it is a constant here
+ * because two methods now read the same default — that projection and
+ * {@link OidcIdentityPlugin.verifyAccessToken}'s audience rule — and a default
+ * spelled twice is a default that can drift between what the web is told and what
+ * a token is checked against.
+ */
+declare const OIDC_DEFAULT_API_AUDIENCE = "ever-works";
+/**
+ * FR-45 — a delegated token's lifetime (`exp` − `iat`) is **at most 3,600 seconds**
+ * (`EVER_ID_LIMITS.delegatedTokenMaxLifetimeSeconds`; plan §4.3's "Access token
+ * (delegated)" row).
+ *
+ * Exported although `verifyAccessToken` takes the ceiling as an argument rather
+ * than applying a constant: the number belongs to the caller's token family, and
+ * this is the value that family is capped at. A client that mints a longer-lived
+ * token is refused with `lifetimeTooLong` (ACC-12-35).
+ */
+declare const OIDC_ACCESS_TOKEN_MAX_LIFETIME_SECONDS = 3600;
+/**
+ * FR-40 — an exchange token's `iat` may be **no older than 300 seconds**
+ * (`EVER_ID_LIMITS.exchangeTokenMaxAgeSeconds`).
+ *
+ * Passed by the local-client exchange as `maxAgeSeconds`; a plain delegated read
+ * (FR-45) passes none, because that row has no age rule — its bound is the
+ * lifetime ceiling above.
+ */
+declare const OIDC_ACCESS_TOKEN_MAX_AGE_SECONDS = 300;
+/**
+ * FR-33 — a sign-out notice's `iat` may be **no older than 300 seconds**
+ * (`EVER_ID_LIMITS.logoutTokenMaxAgeSeconds`).
+ *
+ * Unlike the two numbers above this one is not a caller's choice: FR-33 fixes it
+ * for every back-channel logout notice, so {@link OidcIdentityPlugin.verifyLogoutToken}
+ * applies it itself.
+ */
+declare const OIDC_LOGOUT_TOKEN_MAX_AGE_SECONDS = 300;
+/**
+ * FR-33 — a `jti` must not have been seen in the last **600 seconds**
+ * (`EVER_ID_LIMITS.replayWindowSeconds`).
+ *
+ * Exported although this plugin deliberately does **not** enforce it: the window
+ * needs a store, plan §4.1 leaves it with the caller ("the caller keeps the
+ * 600-second replay window, not the plugin"), and T13's replay service is where it
+ * lives. The constant is here so the one number has one spelling in this package
+ * — the alternative is a literal in the API that nothing cross-checks.
+ */
+declare const OIDC_LOGOUT_TOKEN_REPLAY_WINDOW_SECONDS = 600;
+/**
+ * FR-33 — the `events` member a back-channel logout notice must carry
+ * (OpenID Connect Back-Channel Logout 1.0 §2.4's event identifier).
+ *
+ * One spelling, because three things have to agree on it: this plugin's
+ * acceptance rule, the fake provider that mints notices, and any future caller
+ * that has to explain a refusal.
+ */
+declare const OIDC_BACKCHANNEL_LOGOUT_EVENT = "http://schemas.openid.net/event/backchannel-logout";
+/**
+ * The seams a spec (or a future caller) may inject.
+ *
+ * All three are optional and all three default to the runtime: the plugin loader
+ * constructs a plugin with no arguments (`PluginLoaderService.loadPluginModule`,
+ * `plugin-loader.service.ts:364`), so nothing here is a production requirement.
+ * They exist because T6's two properties — FR-3's 5-second bound and FR-13's
+ * 600/30/21,600-second ladder — are only provable against a clock and a socket the
+ * test owns; a spec that really waited 21,600 seconds is not a spec.
+ *
+ * `randomBytes` is T7's addition, and for the same reason: FR-9's "fresh `state`
+ * and `nonce` of at least 32 random bytes each" is a claim about *freshness* and
+ * *byte count*, and neither can be asserted against a value the spec cannot see
+ * the source of. With the seam injected, a case can pin the exact bytes the
+ * request was built from; with it left alone, the default is the platform
+ * CSPRNG and the case asserts what can be asserted of any output — that two
+ * calls never agree, and that each value decodes to 32 bytes.
+ */
+interface OidcIdentityPluginOptions {
+    /** The outbound HTTP seam; defaults to the runtime `fetch` (see `discovery.ts`). */
+    readonly fetchImpl?: OidcFetchImpl;
+    /** The clock, in epoch milliseconds; defaults to `Date.now`. */
+    readonly now?: () => number;
+    /** The randomness seam, in bytes; defaults to `node:crypto`'s `randomBytes`. */
+    readonly randomBytes?: (length: number) => Uint8Array;
+    /**
+     * The deployment environment, for the ONE rule that depends on it: whether a
+     * non-TLS (`http://localhost`) issuer is usable at all
+     * ({@link allowsInsecureIssuer}). Defaults to `process.env.NODE_ENV` read at call
+     * time, so a spec that flips the variable does not have to construct the
+     * plugin again. A spec that wants the refusing branch passes any value that is
+     * not in {@link NON_PRODUCTION_NODE_ENVS} — `nodeEnv: 'production'` is the
+     * readable one.
+     */
+    readonly nodeEnv?: string;
+}
+/**
+ * APW-12 T5 — the `oidc-identity` plugin, scaffolded as an identity and completed
+ * by T6, T7 and T8 (see the history paragraph below).
+ *
+ * What the scaffold itself had to get right, and what every later task kept:
+ *
+ *   - the manifest the `everworks.plugin` block in `package.json` also declares
+ *     (they must agree — `packages/agent/src/plugins/services/plugin-manifest-validator.service.ts`
+ *     extracts the block from disk and `PluginClassValidatorService` compares the
+ *     loaded class against it);
+ *   - the settings schema of plan §4.2;
+ *   - the two lifecycle hooks the loader calls. Both are **prototype methods on
+ *     purpose**: `PluginClassValidatorService.isPluginClass`
+ *     (`packages/agent/src/plugins/services/plugin-class-validator.service.ts:42-55`)
+ *     accepts a class only when `onLoad` and `onUnload` sit on its prototype, so
+ *     an arrow-function property would make this plugin undiscoverable.
+ *
+ * What did NOT exist before **T8**, and why the docstring is kept as history: three
+ * of the seven methods of `IIdentityProviderPlugin` — `verifyAccessToken`,
+ * `verifyLogoutToken` and `buildEndSessionUrl` — and `healthCheck`. T6 landed the
+ * two configuration methods — `testConnection` (FR-3) and `getPublicConfig`
+ * (FR-2) — plus the discovery reader and the key cache they and the flow share
+ * (`src/discovery.ts`, `src/jwks-cache.ts`); **T7** landed the two sign-in
+ * methods, `buildAuthorizationRequest` (FR-8/FR-9/FR-10) and
+ * `exchangeAuthorizationCode` (FR-11/FR-12/FR-19's single completion is the
+ * caller's), plus `src/scopes.ts`. **T8** landed the three token/sign-out methods
+ * (FR-40/FR-45's access tokens, FR-33's sign-out notice, FR-36's end-session
+ * address) and `healthCheck`, so the class now claims the interface below rather
+ * than five of its seven methods — and
+ * `isIdentityProviderPlugin` (`packages/plugin/src/contracts/capabilities/identity-provider.interface.ts:284`)
+ * answers `true` for it, which is what it was written to answer once every method
+ * exists.
+ *
+ * Claiming `IIdentityProviderPlugin` in the `implements` clause is not decoration:
+ * it makes `tsc` refuse a member whose name, arity or nullability has drifted from
+ * plan §4.1, which is the failure the guard above cannot see. What it does **not**
+ * change is the plugin's posture: `autoEnable: false`, so the installation still
+ * opts in explicitly (FR-5's kill switch is the plugin toggle, plan §9.2).
+ */
+declare class OidcIdentityPlugin implements IPlugin, IIdentityProviderPlugin {
+    readonly id = "oidc-identity";
+    readonly name = "OpenID Connect identity (Ever ID)";
+    readonly version = "1.0.0";
+    /**
+     * The plan §4.2 category, `'identity'`.
+     *
+     * The assertion is needed only because this package lands **before T4**,
+     * which appends `'identity'` to `PLUGIN_CATEGORIES`
+     * (`packages/plugin/src/contracts/plugin-manifest.types.ts:5-117` — the tuple
+     * currently closes with `'build'`). Until that append lands the loader's own
+     * `isPluginCategory` check rejects the manifest, so this plugin is
+     * discoverable only after T4; the value itself is already exact, and the
+     * assertion is the one place the type union is narrower than the plan.
+     *
+     * **Landed 2026-09-18 (T4).** `'identity'` is now the **last** member of
+     * `PLUGIN_CATEGORIES`, so the loader's `isPluginCategory` accepts this
+     * manifest and discovery finds the package instead of skipping it with
+     * `Invalid category` (T4's report measures it: 103 → 104 plugins). The
+     * paragraph above is kept because that is what this file had to say while
+     * the append was missing, and the cast below stays — it resolves to the
+     * same member, and dropping it would remove an assertion for nothing.
+     */
+    readonly category: PluginCategory;
+    /** Plan §4.2: exactly one capability, `identity-provider`. */
+    readonly capabilities: readonly string[];
+    /** One issuer set per installation, configured by a platform admin (FR-7, FR-2). */
+    readonly configurationMode = "admin-only";
+    readonly settingsSchema: JsonSchema;
+    /**
+     * The context `onLoad` was handed — the only way this plugin reads its own
+     * resolved settings (plan §4.1: no method takes a configuration object, so a
+     * caller cannot hand the plugin a different issuer, client id or secret than the
+     * one an administrator saved; FR-7).
+     */
+    private context?;
+    /** The discovery reader for the currently configured issuer (FR-14's cache lives in it). */
+    private discoveryReader?;
+    /** Which issuer {@link discoveryReader} was built for — a settings change replaces it. */
+    private discoveryIssuerUrl?;
+    /** The key cache for the currently configured `jwks_uri` (FR-13's ladder lives in it). */
+    private jwksCache?;
+    /** Which `jwks_uri` {@link jwksCache} was built for — a provider that moves its keys replaces it. */
+    private jwksUri?;
+    /** FR-13 / plan §9.2: when the key set was last fetched successfully, in epoch ms. T32 persists it. */
+    private jwksRefreshedAtMs;
+    /** FR-14/FR-5: when the provider was first seen unusable, in epoch ms. T32 persists it. */
+    private unavailableSinceMs;
+    /** Which rule made it unusable — a closed set, never a provider's own text (FR-16). */
+    private unavailableReason;
+    private readonly fetchImpl?;
+    private readonly now;
+    private readonly randomBytes?;
+    private readonly nodeEnv?;
+    constructor(options?: OidcIdentityPluginOptions);
+    onLoad(context: PluginContext): Promise<void>;
+    onUnload(): Promise<void>;
+    /**
+     * FR-3 — read the provider's discovery document and report every check.
+     *
+     * The rules this method exists to keep, in the order they matter:
+     *
+     *   - **5 seconds, always** (FR-3, ACC-12-03). The read is handed a deadline
+     *     computed when the run starts, so FR-15's single retry can only ever fit
+     *     inside that budget, and the answer is reported at the deadline whether or
+     *     not the provider answered in time.
+     *   - **A row per check, always** — the same seven ids in FR-3's order, an
+     *     unconfigured integration and an unreachable provider included. A short or
+     *     varying list would make spec §6.7's admin surface render differently
+     *     depending on what went wrong.
+     *   - **Never the secret** (FR-16). No `detail` quotes a value the provider sent
+     *     except a numeric HTTP status; every one of them names a field, and the
+     *     settings object — which is where `clientSecret` lives — is never returned,
+     *     logged or embedded.
+     *
+     * The run also writes the availability record plan §4.2 keeps: the five checks
+     * of {@link FR3_REQUIRED_CHECK_IDS} passing clears `unavailableSince`, any of them
+     * failing sets it (FR-14's "until an administrator re-tests"). T32 persists it;
+     * {@link getAvailability} is the in-process view until then.
+     */
+    testConnection(): Promise<IdentityProviderCheck[]>;
+    /**
+     * FR-2's non-secret projection — what the web needs to render the button and
+     * what a local client needs before it can sign in.
+     *
+     * The contract's five fields and nothing else: the client secret is not among
+     * them (FR-16), and neither is anything that would let a caller address the
+     * provider differently from the configuration an administrator saved (FR-7). The
+     * defaults are FR-2's: display name `Ever ID`, audience `ever-works`, sign-up on.
+     */
+    getPublicConfig(): Promise<{
+        issuer: string;
+        displayName: string;
+        localClients: OidcIdentityLocalClient[];
+        apiAudience: string;
+        signUpAllowed: boolean;
+    }>;
+    /**
+     * FR-8/FR-9/FR-10/FR-12's first half — the authorization request a browser is
+     * sent to, and the three secrets the transaction cookie carries.
+     *
+     * What this method is responsible for, and what it is deliberately not:
+     *
+     *   - **PKCE S256 only** (FR-8). `code_challenge_method=S256` is a literal in
+     *     the parameters below and the challenge is the SHA-256 of the verifier,
+     *     computed by `openid-client`'s `calculatePKCECodeChallenge` — the same
+     *     transformation the provider will apply to the verifier at the token
+     *     endpoint. `plain` is never offered and never sent; a provider that
+     *     advertises only `plain` is refused by FR-3's check row and by the
+     *     availability record, not by this method.
+     *   - **Fresh `state` and `nonce` of 32 random bytes, and a 64-character
+     *     verifier, per call** (FR-9). Every call draws new bytes from
+     *     {@link OidcIdentityPluginOptions.randomBytes} (the platform CSPRNG by
+     *     default) and encodes them base64url: 32 bytes → a 43-character value
+     *     whose decoded length is exactly the 32 FR-9 asks for, 48 bytes → exactly
+     *     the 64 characters FR-9 asks of the verifier. Nothing is reused between
+     *     calls and nothing is derived from the clock, the issuer or the client
+     *     id — a `state` an attacker can predict is a `state` that binds nothing.
+     *   - **The exact redirect address, never rebuilt** (FR-10). `redirectUri` is
+     *     copied into the query parameter byte-for-byte: no trailing-slash
+     *     normalisation, no parsing and re-serialising, no default. Deriving that
+     *     address from the configured public web address — and refusing anything
+     *     that came from request input — is the caller's rule (plan §5.1's
+     *     `POST /authorize`), and this method cannot enforce it because the
+     *     address is not part of the plugin's settings (plan §4.2 has no redirect
+     *     key: the one address per deployment lives in platform configuration).
+     *   - **`openid email profile`, and never `offline_access`** (plan §4.2,
+     *     FR-38) — the scope comes from `src/scopes.ts` as one constant rather
+     *     than being assembled here.
+     *
+     * The endpoint comes from the discovery document this plugin already read
+     * (FR-14's 3,600-second cache, and its issuer-drift refusal): a request is
+     * never built against an issuer whose document advertises a different issuer,
+     * so a provider cannot move this installation's sign-in by publishing a
+     * document somewhere else.
+     *
+     * Errors are T6's availability vocabulary rather than token rejections —
+     * nothing here verifies a token, and a caller needs to know *which*
+     * configuration or document problem stopped the sign-in from starting:
+     * `notConfigured`, `discoveryFailed`, `issuerDrift` or `discoveryIncomplete`
+     * (a document with no `authorization_endpoint`). Every one of them maps to
+     * plan §5.2's `404 everIdDisabled` / `503 providerUnavailable` at the façade.
+     */
+    buildAuthorizationRequest(input: {
+        redirectUri: string;
+        prompt?: 'login';
+        maxAgeSeconds?: number;
+    }): Promise<{
+        url: string;
+        state: string;
+        nonce: string;
+        codeVerifier: string;
+    }>;
+    /**
+     * FR-11/FR-12 — redeem an authorization code and answer the ID token's claims,
+     * or refuse.
+     *
+     * The order below is the spec's order, and each step is load-bearing:
+     *
+     *   1. **the settings resolve** — an unconfigured integration cannot exchange
+     *      anything, and this method has no way to say so except
+     *      `providerUnavailable` (see the error contract below);
+     *   2. **FR-12's `iss` equality, before anything is redeemed.** When the
+     *      authorization response carries `iss`, it must equal the configured
+     *      issuer exactly. Checking it first is not an optimisation: a code whose
+     *      response named another issuer is a code this installation must not
+     *      spend, and a refusal here touches the network zero times;
+     *   3. **the discovery document** (FR-14's cache, and its issuer-drift
+     *      refusal) — the token endpoint and `jwks_uri` come from it;
+     *   4. **the code exchange** — one POST, `client_secret_basic`, 5,000 ms, and
+     *      **no retry** (FR-15's "the code exchange is never retried": a second
+     *      attempt would be a second redemption of a single-use code, which is
+     *      FR-19's "a sign-in transaction completes at most once" seen from the
+     *      provider's side);
+     *   5. **the signature and the algorithm**, through T6's key cache
+     *      (`jwks-cache.ts`), whose three codes and whose 21,600-second
+     *      fail-closed end are reported with the same codes here;
+     *   6. **FR-11's claim rules** (plan §4.3), against the injected clock and the
+     *      administrator's `clockSkewSeconds` (default
+     *      {@link OIDC_DEFAULT_CLOCK_SKEW_SECONDS}).
+     *
+     * ## The error contract, and why it differs from {@link buildAuthorizationRequest}
+     *
+     * **Everything this method throws is an `IdentityTokenRejectedError`** — the
+     * contract's single refusal type, `message` equal to `code` and nothing else
+     * (FR-16). That includes the provider-unavailable conditions: T6's discovery
+     * and key-cache errors are caught below and rethrown as
+     * `providerUnavailable`, and any `jwks-cache` refusal keeps its own code
+     * (`badAlg`, `badSignature`). The reason is the caller: the callback handler
+     * has one decision to make — plan §5.2's "ID token rejected → 401" versus
+     * "endpoint unavailable → 503" — and one error type with a closed code set is
+     * the shape that decision is written against. The builder, which answers a
+     * question rather than a verdict, keeps the precise availability reason
+     * instead.
+     *
+     * A refusal never partially succeeds: nothing is returned, nothing is stored,
+     * and no claim of a refused token reaches the caller.
+     *
+     * ## `maxAuthAgeSeconds` (FR-25)
+     *
+     * Supplied, it applies FR-25's rule — `auth_time` no older than 300 seconds
+     * plus the skew — and answers `tooOld`, including when the token carries no
+     * `auth_time` at all: a connect flow that cannot show the authentication was
+     * recent must re-authenticate rather than proceed. Absent (a plain sign-in),
+     * `auth_time` is not required and is passed through as `null` when missing.
+     */
+    exchangeAuthorizationCode(input: {
+        code: string;
+        redirectUri: string;
+        codeVerifier: string;
+        expectedNonce: string;
+        receivedIssuer?: string;
+        maxAuthAgeSeconds?: number;
+    }): Promise<VerifiedIdTokenClaims>;
+    /**
+     * FR-40 (the local-client exchange) and FR-45 (the App Launcher's delegated
+     * read) — verify an Ever ID access token and answer the claims both callers
+     * branch on.
+     *
+     * The rules, in the order they are applied, and where each one comes from:
+     *
+     *   1. **the settings resolve** — as in {@link exchangeAuthorizationCode}, an
+     *      unconfigured integration answers `providerUnavailable`, the only code
+     *      this method has for "the plugin cannot ask the provider anything";
+     *   2. **the discovery document** (FR-14's cache and issuer-drift refusal) and
+     *      its `jwks_uri` — the same read the exchange performs, and the same
+     *      `providerUnavailable` when the document names no key set;
+     *   3. **the signature and the algorithm** through T6's key cache, including
+     *      FR-13's ladder and its fail-closed end (`badAlg`, `badSignature`,
+     *      `providerUnavailable`);
+     *   4. **FR-11's issuer rule**, which FR-45 makes a rule for access tokens too:
+     *      `iss` equals the discovery issuer **and** is allow-listed (`badIssuer`);
+     *   5. **the audience** — `aud` contains the configured API audience, or plan
+     *      §4.2's `ever-works` default (`badAudience`);
+     *   6. **the scopes** — every entry of `requiredScopes` is present (`missingScope`,
+     *      FR-46's code: a valid token that lacks the scope its caller needs);
+     *   7. **the times** — a readable `exp` that has not passed (with the skew), an
+     *      `iat` no later than now plus the skew, and an `iat` no older than
+     *      `maxAgeSeconds` when the caller gives one (`expired`, `notYetValid`,
+     *      `tooOld`);
+     *   8. **the lifetime ceiling** — `exp − iat ≤ maxLifetimeSeconds`
+     *      (`lifetimeTooLong`; ACC-12-35's "lifetime over 3,600 seconds");
+     *   9. **the authorised party** — when `allowedAuthorizedParties` is given (the
+     *      exchange path, FR-40), `azp` must be one of them
+     *      (`badAuthorizedParty`); absent, the claim is not read at all, which is
+     *      FR-45's rule set exactly.
+     *
+     * ## The two arguments that make one method serve both token families
+     *
+     * The contract has one `verifyAccessToken` and two rules of §4.3: the delegated
+     * read passes `{ requiredScopes: ['apps:read'], maxLifetimeSeconds: 3_600 }`
+     * (FR-44/FR-45), the exchange passes
+     * `{ requiredScopes: ['ever-works:session'], maxLifetimeSeconds: 3_600, maxAgeSeconds: 300, allowedAuthorizedParties: <the configured local client ids> }`
+     * (FR-40). Nothing here decides which family a token belongs to — that is the
+     * caller's, and it is a decision about *why* the token is being presented, not
+     * about the token.
+     *
+     * ## What is deliberately left to the caller
+     *
+     * **The `jti` replay window** (FR-40/FR-33's 600 seconds). The parsed `jti` is
+     * returned and never enforced: it needs a store with a unique index, which is
+     * T13's `ever-id-replay.service.ts`, and a plugin that held that state in
+     * process memory would enforce a different window per replica. Plan §4.1 says
+     * the same thing from the contract side ("the caller keeps the 600-second replay
+     * window, not the plugin").
+     *
+     * **Whether the subject is a connected identity of an active account** — FR-40's
+     * last clause and FR-45's. That is a database question and it belongs to the
+     * services that own those rows.
+     *
+     * A refusal never partially succeeds: no claim of a refused token is returned.
+     */
+    verifyAccessToken(token: string, input: {
+        requiredScopes: string[];
+        maxLifetimeSeconds: number;
+        maxAgeSeconds?: number;
+        allowedAuthorizedParties?: string[];
+    }): Promise<VerifiedAccessTokenClaims>;
+    /**
+     * FR-33 — verify a back-channel logout notice and answer the three claims the
+     * session teardown keys on.
+     *
+     * Validated exactly like an ID token (FR-33's "validated like FR-11 and FR-13":
+     * the algorithm allow-list, the signature against Ever ID's published keys,
+     * FR-13's ladder, FR-11's issuer rule, and the times), plus FR-33's own five:
+     *
+     *   - the **back-channel logout event** is present ({@link OIDC_BACKCHANNEL_LOGOUT_EVENT});
+     *   - **no `nonce`** — the claim's mere presence is refused
+     *     (`nonceInLogoutToken`), because a notice is not an authentication and a
+     *     token that can be replayed as one is a token that should never verify;
+     *   - **`sid` or `sub`**, at least one, or there is no session to end
+     *     (`badLogoutEvent`);
+     *   - **`jti` required** (`badLogoutEvent`) — without it the 600-second replay
+     *     window has no key, and a notice that cannot be bounded must be refused
+     *     rather than treated as new;
+     *   - **`iat` within the skew and no older than 300 seconds** (`notYetValid`,
+     *     `tooOld`).
+     *
+     * ## `exp`, and the one place a logout token differs from an ID token
+     *
+     * Plan §4.3's ID-token row requires a readable `exp`; FR-33's logout-token row
+     * does not mention one, and OpenID Connect Back-Channel Logout 1.0 §2.4 does not
+     * put `exp` in the claim set a logout token **must** carry (`iss`, `aud`, `iat`,
+     * `jti`, `events`). FR-53 makes that difference load-bearing: a provider that
+     * publishes a standards-compliant notice would have every sign-out refused as
+     * `expired` if this method demanded an `exp` the provider never promised, and a
+     * refused sign-out is a session that stays open. So `exp` is **checked when it
+     * is there** and not required, and the freshness bound FR-33 does state — `iat`
+     * within the skew and no older than 300 seconds — is enforced either way. This
+     * is a deliberate reading and is pinned by a case in
+     * `src/__tests__/logout-token.spec.ts` in both directions.
+     *
+     * ## What is deliberately left to the caller
+     *
+     * The `jti` **replay window** (FR-33's 600 seconds; see
+     * {@link verifyAccessToken}) and everything that happens to a session once this
+     * method has answered — FR-34's "ends the sessions carrying it", FR-35's "never
+     * ends a session opened by another method" and the 5-second bound are the
+     * API's, not a token verifier's.
+     */
+    verifyLogoutToken(token: string): Promise<VerifiedLogoutTokenClaims>;
+    /**
+     * FR-36 — the address that ends the person's Ever ID session, or **`null`** when
+     * the provider publishes no end-session endpoint.
+     *
+     * The `null` is the one answer in this plugin that is neither a set of claims
+     * nor a refusal, and it means one thing only: the discovery document the plugin
+     * already read has no `end_session_endpoint`, so there is nowhere to send the
+     * person and the caller renders "sign out of Ever Works" alone. It is **not**
+     * an error path — inventing a URL, or answering the issuer's address and hoping,
+     * would send a browser somewhere the provider never agreed to serve.
+     *
+     * What is sent, and what is not:
+     *
+     *   - `client_id` — how the provider knows which relying party is asking. The
+     *     alternative identifier, `id_token_hint`, is deliberately **not** sent:
+     *     FR-31 forbids this platform from storing an Ever ID token, so there is no
+     *     ID token to hint with, and OpenID Connect RP-Initiated Logout 1.0 names
+     *     `client_id` as the parameter to use in exactly that case.
+     *   - `post_logout_redirect_uri` — copied **byte for byte**, the same rule
+     *     FR-10 puts on the authorization request's `redirect_uri` and for the same
+     *     reason: the address an administrator registered is the address that
+     *     travels, never one this package rebuilt.
+     *   - `state` — carried verbatim. "Validated" in FR-36 is about the value the
+     *     API sealed into the sign-out transaction (plan §3.4/§3.5, T13's seal
+     *     service) being the value that comes back; the plugin neither mints nor
+     *     checks it, and must not, because it holds no per-session state.
+     *
+     * Errors are {@link OidcProviderUnavailableError} — T6's availability
+     * vocabulary, exactly as in {@link buildAuthorizationRequest} — rather than an
+     * `IdentityTokenRejectedError`: nothing here verifies a token, and a caller
+     * needs to know which configuration or document problem stopped the sign-out:
+     * `notConfigured`, `discoveryFailed`, `issuerDrift`, or `discoveryIncomplete`
+     * (an `end_session_endpoint` that is published but is not a URL).
+     */
+    buildEndSessionUrl(input: {
+        postLogoutRedirectUri: string;
+        state: string;
+    }): Promise<string | null>;
+    /**
+     * Plan §9.2's plugin health view, in the platform's own lifecycle shape
+     * (`PluginHealthCheck`, `packages/plugin/src/contracts/lifecycle.types.ts:24`).
+     *
+     * The three states, and why each one is the honest answer:
+     *
+     *   - **`unhealthy`** — an administrator's configuration could not be read (a
+     *     required setting is missing or blank, or `resolveSettings` refused a set
+     *     value: a non-TLS issuer outside development, or a `clockSkewSeconds`
+     *     outside FR-2's bound — the `configuration` row names the field, never the
+     *     value), or FR-14/FR-5's availability record
+     *     says the provider was last seen unusable. The second is a real outage of
+     *     this capability: sign-in is off until a **Test connection** passes.
+     *   - **`healthy`** — the settings resolve and this process has successfully
+     *     read the discovery document or the key set.
+     *   - **`unknown`** — the settings resolve but nothing has been read yet. A
+     *     plugin that has not been called is not a broken plugin, and reporting
+     *     `unhealthy` for it would make every installation that does not use Ever ID
+     *     render a red health row (the plugin ships `autoEnable: false`).
+     *
+     * Everything it answers is a **name, a closed code or a number** (FR-16): the
+     * check ids are this file's own, the unavailability reason is
+     * {@link OidcProviderUnavailableReason}'s closed set, the timestamps are epoch
+     * milliseconds, and no message carries the issuer, the client id, the client
+     * secret or any part of a token. `duration` is measured on the injected clock
+     * around the one await this method performs, so a caller (and a spec) can see
+     * how long the settings read took.
+     */
+    healthCheck(): Promise<PluginHealthCheck>;
+    /**
+     * The in-process availability record plan §4.2 stores under `availability`.
+     *
+     * Additive surface for T32, which persists these into the plugin's settings row so
+     * every replica agrees within 60 seconds (FR-5): this is the same record one
+     * process holds, exposed so the persistence task does not have to re-derive when a
+     * run passed.
+     *
+     * `jwksRefreshedAt` is T7's addition — plan §9.2's health view has carried the
+     * field since T5 wrote it into the settings schema
+     * (`settings.schema.ts:262`) and nothing produced it until the key cache was
+     * wired to the flow; it is `null` until a key set has been fetched, which is
+     * exactly what plan §9.2's admin surface renders as "unknown".
+     */
+    getAvailability(): {
+        unavailableSince: string | null;
+        unavailableReason: OidcProviderUnavailableReason | null;
+        discoveryRefreshedAt: string | null;
+        jwksRefreshedAt: string | null;
+        discoveryCacheSeconds: number;
+    };
+    /**
+     * The settings this plugin reads, or the field names that are missing.
+     *
+     * `context.getSettings()` resolves the admin-tier values, secrets included
+     * (`SettingsSchemaValidatorService`, plan §4.2); a throw from the platform is
+     * treated exactly like an absent configuration, because the fail-closed answer is
+     * the same and neither path may surface the platform's own error text (FR-16).
+     */
+    private resolveSettings;
+    /** One reader per configured issuer: a settings change starts a fresh cache (FR-14). */
+    private readerFor;
+    /**
+     * The discovery document the exchange and T8's two verifiers run against, with
+     * T6's availability errors translated to the one refusal type their callers
+     * branch on (see {@link exchangeAuthorizationCode}'s error contract).
+     *
+     * Named for the verification path rather than the exchange since T8: the read is
+     * the same one FR-14's cache and issuer-drift refusal describe, and an access
+     * token or a sign-out notice needs the same document for the same reason — the
+     * `jwks_uri` and the issuer its claims are compared against.
+     */
+    private discoveryForVerification;
+    /**
+     * The one POST of the sign-in flow (FR-15, FR-19).
+     *
+     * `client_secret_basic` is plan §4.2's authentication method for this provider,
+     * and `ClientSecretBasic` from `openid-client` is what produces the header —
+     * the same function the library's own grant calls use, so the encoding of the
+     * credentials (`application/x-www-form-urlencoded` then base64, RFC 6749
+     * §2.3.1) is not re-implemented here. `client_id` is therefore **not** in the
+     * body: RFC 6749 §4.1.3 requires it only "if the client is not authenticating
+     * with the authorization server", and sending it twice is a habit providers
+     * tolerate rather than a requirement they state.
+     *
+     * The response is read as JSON and the `id_token` taken from it. Every way the
+     * call can fail is one code — `providerUnavailable` — because the closed
+     * vocabulary has no code for "the provider refused the grant" and a precise
+     * code with the wrong meaning is worse than a coarse one that is right (see the
+     * report for T4/T25: an `invalid_grant` therefore reaches the API as 503 today).
+     */
+    private redeemAuthorizationCode;
+    /**
+     * FR-11's first two clauses, through T6's key cache: the algorithm allow-list
+     * and the signature, with the cache's own ladder (600 s, 30 s, 21,600 s) and
+     * its `providerUnavailable` end.
+     *
+     * **One implementation for all three token kinds.** T7 wrote it for the ID token
+     * and named it for one; T8's `verifyAccessToken` and `verifyLogoutToken` call the
+     * same method, because "the algorithm is one of RS256/ES256/EdDSA and the
+     * signature verifies against a key Ever ID published, inside FR-13's ladder" is
+     * one rule and FR-45/FR-33 both adopt it by reference ("validated like FR-11 and
+     * FR-13"). A second copy would be a second place for the ladder to drift.
+     *
+     * Both of T6's error types become `IdentityTokenRejectedError`: `badAlg` and
+     * `badSignature` keep their code, and anything the cache could not answer
+     * because the provider is unreachable or its keys are stale is
+     * `providerUnavailable`. An error that is neither is a bug in this package
+     * rather than a verdict about a token, so it propagates instead of being
+     * disguised as a provider outage — no claims are returned either way, which is
+     * what fail-closed means here.
+     */
+    private verifyProviderSignature;
+    /** One key cache per resolved `jwks_uri`; a provider that moves its keys starts a fresh one (FR-13). */
+    private jwksFor;
+    /**
+     * The `openid-client` configuration for one document and one resolved settings
+     * object — used for `buildAuthorizationUrl`, which is a pure URL builder (no
+     * socket, no timer), and for nothing else.
+     *
+     * The rest of the flow does not go through `openid-client`'s `authorizationCodeGrant`,
+     * and that is a measured decision rather than an omission: that call validates
+     * the ID token itself against its own remote key set, which caches for 600
+     * seconds and **keeps using a stale set indefinitely** — the opposite of FR-13's
+     * 21,600-second fail-closed end that `jwks-cache.ts` exists to enforce — and it
+     * applies its own `clockTolerance` to the time claims, which would decide
+     * FR-11's skew edges instead of the administrator's configured
+     * `clockSkewSeconds`. Plan §4.2 names the library for this flow; where its
+     * built-in policy contradicts the spec, the spec's own module wins and the
+     * library keeps the parts that are exactly right (`buildAuthorizationUrl`,
+     * `calculatePKCECodeChallenge`, `ClientSecretBasic`) — the same trade T6
+     * documented for `discovery()`.
+     */
+    private configurationFor;
+    /** Exactly `length` random bytes, from the injected seam or the platform CSPRNG (FR-9). */
+    private random;
+    /** Set or clear plan §4.2's `unavailableSince` from the five checks that gate it. */
+    private applyAvailability;
+    /** FR-14/FR-5: the provider is off from the first failing run until a passing one. */
+    private recordUnavailable;
+    /**
+     * One log line per run, and it carries counts and check **ids** only.
+     *
+     * Ids come from the closed contract set, never from the provider, so nothing a
+     * provider chose to send can reach a log through this path (FR-16).
+     */
+    private logChecks;
+    getManifest(): PluginManifest;
+}
+
+/**
+ * APW-12 T7 — the scopes a sign-in asks Ever ID for, and the one it never asks for.
+ *
+ * Plan §4.2: "`src/scopes.ts`: sign-in scopes `openid email profile`; the plugin
+ * never requests `offline_access` (spec FR-38)."
+ *
+ * Both halves of that sentence are requirements, and they are not symmetrical:
+ *
+ *   - **`openid email profile`** is what a sign-in needs. `openid` is what makes
+ *     the response an OpenID Connect authentication (and what obliges the
+ *     provider to return an ID token at all, FR-11); `email` and `profile` carry
+ *     `email`, `email_verified` and `name`, which FR-23/FR-24/FR-25 branch on
+ *     when an unknown pair is offered account creation or a connection. Asking
+ *     for anything else would be asking for access the sign-in path does not
+ *     read.
+ *   - **`offline_access` is never requested.** FR-38 states the reason in one
+ *     line — "Ever Works never stores Ever ID refresh tokens in P1" — and the
+ *     cheapest way to keep that promise is not to be able to receive one: a
+ *     provider only issues a refresh token to a client that asked for
+ *     `offline_access`, so a request that never carries the scope can never
+ *     produce a token this platform would have to decide what to do with.
+ *
+ * ## Why this is its own module
+ *
+ * The scope string is a wire value three separate places need to agree on: the
+ * authorization request this package builds (T7), the `GET /client-config`
+ * answer a local client reads before it signs in (FR-39, plan §5.1) and the
+ * documentation that tells a person what Ever Works asks for. It is a constant
+ * rather than a literal because a second spelling of `'openid email profile'`
+ * is a second thing that can drift.
+ *
+ * **T8** added the two scopes on the verifying side —
+ * {@link OIDC_DELEGATED_READ_SCOPE} (`apps:read`, FR-44) and
+ * {@link OIDC_SESSION_EXCHANGE_SCOPE} (`ever-works:session`, FR-39/FR-40) — for
+ * the same reason, one step further along the flow: `verifyAccessToken` is handed
+ * `requiredScopes` by its caller, and the caller and the provider's registration
+ * have to spell them identically.
+ *
+ * Nothing here is a secret and nothing here is provider-specific: the same three
+ * sign-in scopes are what any OpenID Connect relying party asks for, which is why
+ * this file names no issuer.
+ */
+/**
+ * The three sign-in scopes, in the order the authorization request sends them.
+ *
+ * The order is fixed rather than incidental: the request is asserted
+ * byte-for-byte against this list by `src/__tests__/authorization-request.spec.ts`,
+ * so a reordering is a visible change rather than a silent one.
+ */
+declare const OIDC_SIGN_IN_SCOPES: readonly ["openid", "email", "profile"];
+/** Union of {@link OIDC_SIGN_IN_SCOPES}. */
+type OidcSignInScope = (typeof OIDC_SIGN_IN_SCOPES)[number];
+/**
+ * The `scope` parameter of every authorization request: `openid email profile`.
+ *
+ * Space-delimited, per RFC 6749 §3.3 — and `buildAuthorizationRequest` sends
+ * **this** string, never one assembled at the call site.
+ */
+declare const OIDC_SIGN_IN_SCOPE: string;
+/**
+ * The scopes Ever Works never asks for (FR-38).
+ *
+ * Named rather than inlined so the refusal is testable: `isSignInScope` answers
+ * `false` for a request that carries one, and the spec asserts both that a
+ * built request does not, and that the guard refuses a string that does.
+ */
+declare const OIDC_NEVER_REQUESTED_SCOPES: readonly ["offline_access"];
+/** One of {@link OIDC_NEVER_REQUESTED_SCOPES}. */
+type OidcNeverRequestedScope = (typeof OIDC_NEVER_REQUESTED_SCOPES)[number];
+/**
+ * APW-12 **T8** — the two scopes Ever Works *verifies* rather than requests.
+ *
+ * They are the other side of the same wire vocabulary: a sign-in **asks** for
+ * `openid email profile`, and a token that arrives from Ever ID is **checked**
+ * against one of these. Both spellings live in this file because a scope string
+ * three components have to agree on is exactly the thing that should have one
+ * definition — FR-40's exchange scope is read by the local client, by the API
+ * endpoint that verifies the token and by the provider's own registration, and
+ * FR-44's delegated scope by the App Launcher, the marked endpoint and the
+ * provider.
+ *
+ * The values are `EVER_ID_SCOPES` in `packages/contracts/src/apps/ever-id.ts`,
+ * transcribed rather than imported for the reason this package depends on
+ * `@ever-works/plugin` alone (see `discovery.ts`), and
+ * `src/__tests__/access-token.spec.ts` reads that file off disk and asserts the
+ * two agree.
+ */
+declare const OIDC_DELEGATED_READ_SCOPE = "apps:read";
+/**
+ * FR-39/FR-40 — the scope a local client's access token must carry to be
+ * exchanged for an Ever Works session (`EVER_ID_SCOPES.SESSION_EXCHANGE`).
+ */
+declare const OIDC_SESSION_EXCHANGE_SCOPE = "ever-works:session";
+/** The two scopes {@link OIDC_DELEGATED_READ_SCOPE} and {@link OIDC_SESSION_EXCHANGE_SCOPE} name, in one list. */
+declare const OIDC_TOKEN_SCOPES: readonly ["apps:read", "ever-works:session"];
+/** Union of {@link OIDC_TOKEN_SCOPES}. */
+type OidcTokenScope = (typeof OIDC_TOKEN_SCOPES)[number];
+/**
+ * Is `value` exactly the sign-in scope set — the three of
+ * {@link OIDC_SIGN_IN_SCOPES}, and nothing else?
+ *
+ * Deliberately an equality rather than a "contains" test: a request carrying an
+ * extra scope (a refresh-token scope, a delegated-read scope, a scope a caller
+ * appended) is not the sign-in request this package means to send, and the
+ * honest answer for it is `false`. It is exported so the spec — and any future
+ * caller that has a scope string in hand rather than the constant — can ask the
+ * question the plugin answers by construction.
+ */
+declare function isSignInScope(value: string): boolean;
+
+/**
+ * APW-12 T6 — the signing-key cache of the `identity-provider` capability.
+ *
+ * Spec FR-13, in its own words and in one place, because every number below is
+ * one of its clauses:
+ *
+ *   - "Signing keys are cached for **600 seconds**";
+ *   - "An unknown key ID triggers **at most one refresh per 30 seconds**";
+ *   - "While Ever ID is unreachable, cached keys stay usable for at most
+ *     **21,600 seconds** after the last successful refresh; after that,
+ *     validation **fails closed**";
+ *   - "A key Ever ID removes stops validating at the next successful refresh."
+ *
+ * FR-15 adds the shape of the fetch itself: 5,000 ms timeout, one retry after
+ * 1,000 ms. Plan §4.3 is the same table; `EVER_ID_LIMITS.jwksCacheSeconds`,
+ * `.jwksUnknownKidCooldownSeconds` and `.jwksMaxStaleSeconds` are the same numbers
+ * in `packages/contracts/src/apps/ever-id.ts`, and
+ * `src/__tests__/jwks-cache.spec.ts` reads that file off disk and asserts the two
+ * agree (this package deliberately does not depend on `@ever-works/contracts` —
+ * see `discovery.ts`).
+ *
+ * ## What is deliberately *not* here
+ *
+ * Claim validation. `iss`, `aud`, `azp`, `exp`, `iat`, `nonce` and the scope rules
+ * of §4.3 belong to the methods that know which kind of token they were handed
+ * (T7's `exchangeAuthorizationCode`, T8's `verifyAccessToken` /
+ * `verifyLogoutToken`). This class answers one question — "is this signature good
+ * under a key Ever ID published, and may we still trust the set we have?" — and
+ * answers it with the three codes of the closed vocabulary those methods rethrow:
+ * `badAlg`, `badSignature` and `providerUnavailable`.
+ *
+ * ## Why the ladder is implemented here rather than left to `jose`
+ *
+ * `jose`'s `createRemoteJWKSet` already defaults to a 600-second cache and a
+ * 30-second cooldown, but it *keeps using a stale set indefinitely* when the
+ * refetch fails — the opposite of FR-13's 21,600-second fail-closed end. It also
+ * owns its own timer, which FR-15's 5,000 ms bound and a fake clock both need to
+ * see. So the fetch, the clock and the ladder are ours, and `jose` does the two
+ * things it is the dependency for: selecting a key from a JWK Set
+ * (`createLocalJWKSet`) and verifying a compact JWS (`compactVerify`).
+ */
+/**
+ * Every code this class can raise, taken from the contract's closed set.
+ *
+ * Typed as a subset of `IdentityTokenRejectionCode` on purpose: T7/T8 rethrow
+ * these as `IdentityTokenRejectedError` with the same code, so a code invented
+ * here would not compile.
+ */
+type OidcJwksFailureCode = Extract<IdentityTokenRejectionCode, 'badAlg' | 'badSignature'>;
+/**
+ * The error a refused token raises (FR-11's signature and algorithm rules).
+ *
+ * `message` is the code and nothing else (FR-16). `providerUnavailable` is not
+ * here because it is not about the token: {@link OidcProviderUnavailableError}
+ * already carries it, with the reason that produced it.
+ */
+declare class OidcJwksVerificationError extends Error {
+    readonly code: OidcJwksFailureCode;
+    constructor(code: OidcJwksFailureCode);
+}
+/** Construction options for {@link OidcJwksCache}. */
+interface OidcJwksCacheOptions {
+    /** `jwks_uri` from the discovery document (FR-3's third endpoint check). */
+    readonly jwksUri: string;
+    /** The fetch seam, defaulting to the runtime `fetch` (see `discovery.ts`). */
+    readonly fetchImpl?: OidcFetchImpl;
+    /** The clock, in epoch milliseconds. Defaults to `Date.now`. */
+    readonly now?: () => number;
+    /** FR-15's 5,000 ms per attempt. */
+    readonly timeoutMs?: number;
+    /** FR-15's 1,000 ms before the single retry. */
+    readonly retryDelayMs?: number;
+    /** FR-13's 600 seconds. */
+    readonly cacheSeconds?: number;
+    /** FR-13's 30 seconds, applied to the unknown-`kid` refetch. */
+    readonly unknownKidCooldownSeconds?: number;
+    /** FR-13's 21,600 seconds: the point past which validation fails closed. */
+    readonly maxStaleSeconds?: number;
+    /** FR-11's algorithm allow-list; `none` and `HS*` are refused before any lookup. */
+    readonly algorithms?: readonly string[];
+    /**
+     * Called after every **successful** key fetch, with the epoch-ms instant.
+     *
+     * This is the in-process source of plan §4.2's `availability.jwksRefreshedAt`
+     * (plan §9.2's health view); T32 persists it, and the plugin owns the wiring.
+     */
+    readonly onRefreshed?: (refreshedAt: number) => void;
+}
+/** What {@link OidcJwksCache.verify} answers: the header it verified and the claims it carried. */
+interface OidcJwksVerification {
+    readonly header: JWSHeaderParameters;
+    readonly payload: Record<string, unknown>;
+    /** The `kid` the signature was verified with, when the token named one. */
+    readonly kid: string | null;
+}
+/**
+ * The cached signing keys, and the rules that decide when they may still be used
+ * (FR-13).
+ *
+ * One instance per resolved `jwks_uri`. Everything is per-process by design: keys
+ * are public material a provider republishes on demand, so a replica that has not
+ * fetched yet fetches on first use rather than sharing cache state (contrast the
+ * *availability* record, which plan §9.2 keeps in persisted settings precisely
+ * because replicas must agree on it).
+ */
+declare class OidcJwksCache {
+    private readonly options;
+    private jwks;
+    private resolveKey;
+    private refreshedAtMs;
+    private lastAttemptAtMs;
+    private lastUnknownKidRefreshAtMs;
+    private lastFailure;
+    private availableKeyCount;
+    constructor(options: OidcJwksCacheOptions);
+    /**
+     * When the last **successful** fetch happened, in epoch ms, or `null`.
+     *
+     * FR-13's staleness clock starts here: an attempt that failed does not move
+     * this value, which is exactly why cached keys survive a provider outage.
+     */
+    get lastRefreshedAt(): number | null;
+    /** When the last fetch was **attempted**, successful or not, or `null`. */
+    get lastAttemptAt(): number | null;
+    /** Why the last fetch failed, or `null` when the last one succeeded. */
+    get lastFetchFailure(): OidcOutboundFailure | 'invalidDocument' | null;
+    /** How many keys the cached set holds; `0` until the first successful fetch. */
+    get keyCount(): number;
+    /**
+     * Verify a compact JWS against the cached key set, and answer its claims.
+     *
+     * The order is the plan §4.3 order and each step is load-bearing:
+     *
+     *   1. the protected header must parse (a truncated token is `badSignature`);
+     *   2. `alg` must be one of FR-11's three — `none` and `HS256` are refused
+     *      **before** any key lookup, so a token can never talk us into treating a
+     *      public key as a shared secret;
+     *   3. the key comes from the cache, refreshing once under FR-13's rules;
+     *   4. `compactVerify` checks the signature, with the same allow-list handed to
+     *      it so the two can never disagree.
+     *
+     * Claim rules are the caller's (see the class docstring).
+     */
+    verify(token: string): Promise<OidcJwksVerification>;
+    /**
+     * The key for a token's header, refreshing at most once when the `kid` is unknown
+     * (FR-13).
+     *
+     * A `kid` nobody published cannot be served from the cache, and the two ways out
+     * are ranked: refresh if FR-13's cooldown allows it, and otherwise refuse. A
+     * refusal is `badSignature` — never `providerUnavailable` — while the cached set
+     * is still inside its 21,600 seconds, because the set *is* trustworthy and the
+     * token is simply not signed by anything in it.
+     */
+    resolveSigningKey(header: JWSHeaderParameters, token: string): Promise<CryptoKey | KeyObject | Uint8Array>;
+    /**
+     * Fetch the key set now, replacing the cache **only** on success.
+     *
+     * Answers whether a usable set is in place afterwards. A failed fetch leaves the
+     * previous set exactly as it was, which is what FR-13's 21,600-second window
+     * describes; it never clears the cache and it never throws to a caller that has a
+     * token to refuse.
+     */
+    refresh(): Promise<boolean>;
+    /**
+     * Make sure the cache is fresh enough to answer from (FR-13's 600 seconds).
+     *
+     * An expired cache is refreshed; a cache that cannot be refreshed stays usable
+     * while {@link assertTrusted} allows it, and throws `providerUnavailable` once it
+     * does not.
+     */
+    private ensureUsableKeySet;
+    /** FR-13's 600 seconds: `age < cacheSeconds`. */
+    private isCacheFresh;
+    /**
+     * FR-13's 21,600 seconds, and the fail-closed end of the ladder.
+     *
+     * Two distinct refusals, because they are two distinct operational facts: no key
+     * set has ever been fetched (`keysUnavailable` — usually a provider that has
+     * never answered), or the last good fetch is older than plan §4.3's window
+     * (`keysStale` — plan §9.2's "JWKS stale beyond 21,600 s: every validation fails
+     * closed").
+     */
+    private assertTrusted;
+    /**
+     * FR-13's "at most one refresh per 30 seconds" for an unknown key id.
+     *
+     * Read as the rule it protects: the unknown-`kid` refetch is the one an attacker
+     * can trigger at will by presenting a token with a made-up `kid`, so that trigger
+     * is the one the cooldown bounds. A *successful* cache refresh is not counted
+     * against it, because the 600-second cache already bounds those — counting them
+     * would refuse the first token signed by a freshly rotated key for up to 30
+     * seconds after any refresh, which is the opposite of ACC-12-08 ("a token signed
+     * with a newly rotated key validates after one key refresh").
+     */
+    private canRefreshForUnknownKid;
+    /**
+     * Ask jose for the key matching a header, or `null` when nothing matches.
+     *
+     * `JWKSNoMatchingKey` is the expected "unknown kid" answer and becomes `null` so
+     * the caller can try FR-13's one refresh. Every other jose failure — a malformed
+     * set, several keys matching one header — is a refusal, and none of them ever
+     * surfaces with jose's message attached (FR-16).
+     */
+    private findKey;
+    private algorithms;
+    private cacheSeconds;
+    private maxStaleSeconds;
+    private unknownKidCooldownSeconds;
+    private now;
+}
+
+export { OIDC_ACCESS_TOKEN_MAX_AGE_SECONDS, OIDC_ACCESS_TOKEN_MAX_LIFETIME_SECONDS, OIDC_BACKCHANNEL_LOGOUT_EVENT, OIDC_CODE_VERIFIER_BYTES, OIDC_CODE_VERIFIER_LENGTH, OIDC_DEFAULT_API_AUDIENCE, OIDC_DEFAULT_CLOCK_SKEW_SECONDS, OIDC_DELEGATED_READ_SCOPE, OIDC_DISCOVERY_CACHE_SECONDS, OIDC_IDENTITY_SETTING_KEYS, OIDC_IDENTITY_SIGNING_ALGS, OIDC_ID_TOKEN_MAX_AGE_SECONDS, OIDC_JWKS_CACHE_SECONDS, OIDC_JWKS_MAX_STALE_SECONDS, OIDC_JWKS_UNKNOWN_KID_COOLDOWN_SECONDS, OIDC_LOGOUT_TOKEN_MAX_AGE_SECONDS, OIDC_LOGOUT_TOKEN_REPLAY_WINDOW_SECONDS, OIDC_MAX_CLOCK_SKEW_SECONDS, OIDC_NEVER_REQUESTED_SCOPES, OIDC_NONCE_BYTES, OIDC_OUTBOUND_MAX_ATTEMPTS, OIDC_OUTBOUND_RETRY_DELAY_MS, OIDC_OUTBOUND_TIMEOUT_MS, OIDC_SESSION_EXCHANGE_SCOPE, OIDC_SIGN_IN_SCOPE, OIDC_SIGN_IN_SCOPES, OIDC_STATE_BYTES, OIDC_SUBJECT_MAX_LENGTH, OIDC_TOKEN_SCOPES, type OidcDiscoveryDocument, type OidcDiscoveryFailure, type OidcDiscoveryRead, OidcDiscoveryReader, type OidcFetchImpl, type OidcFetchInit, type OidcHttpResponse, type OidcIdentityAvailability, type OidcIdentityDelegatedClientName, type OidcIdentityLocalClient, OidcIdentityPlugin, type OidcIdentitySettingKey, type OidcIdentitySettings, type OidcIdentitySigningAlg, OidcJwksCache, type OidcJwksCacheOptions, type OidcJwksFailureCode, type OidcJwksVerification, OidcJwksVerificationError, type OidcNeverRequestedScope, type OidcOutboundFailure, OidcProviderUnavailableError, type OidcProviderUnavailableReason, type OidcSignInScope, type OidcTokenScope, OidcIdentityPlugin as default, fetchJsonOnce, isSignInScope, oidcIdentityHttpsUrlPattern, oidcIdentityIssuerUrlPattern, oidcIdentitySettingsSchema };