@starci/auth-oidc 0.0.0-stage → 0.1.0

package/dist/contracts/index.d.ts

@@ -0,0 +1,137 @@
+/**
+ * What both sides of an OIDC sign-in share: the algorithms a token may be signed with, the wire codes, the claim names and the
+ * shapes of the answers. The server module and the front-end client read these constants, so the two never drift.
+ */
+/** The signature algorithms a verifier may be pinned to: asymmetric only. `none` and every HMAC algorithm are not in the list and are refused at registration. */
+export declare const OIDC_ALGORITHMS: readonly ["RS256", "RS384", "RS512", "PS256", "PS384", "PS512", "ES256", "ES384", "ES512", "EdDSA"];
+/** One admitted signature algorithm. */
+export type OidcAlgorithm = (typeof OIDC_ALGORITHMS)[number];
+/** The algorithm list a registration pins when it names none: what Keycloak signs with by default. */
+export declare const OIDC_DEFAULT_ALGORITHMS: readonly OidcAlgorithm[];
+/** The `role` every verified principal carries, the one `@starci/auth` gives its principals, so a guard reads one value in both editions. */
+export declare const OIDC_ROLE = "authenticated";
+/**
+ * The wire code a verifier refuses a token with: the code `@starci/auth`'s verifier uses, so the guard and the filter that map it
+ * to a 401 are the same in both editions. The specific reason travels in the refusal's `detail.reason`, for the log, never for the client.
+ */
+export declare const OIDC_ACCESS_TOKEN_INVALID = "PASSPORT_ACCESS_TOKEN_INVALID";
+/** The codes of the errors the package throws: a provider that cannot be reached is `Unavailable`, a response that cannot be trusted is `Rejected`. */
+export declare const OIDC_ERROR_CODES: {
+    readonly ConfigurationInvalid: "OIDC_CONFIGURATION_INVALID";
+    readonly Unavailable: "OIDC_UNAVAILABLE";
+    readonly Rejected: "OIDC_REJECTED";
+};
+/** One code a thrown OIDC error carries. */
+export type OidcErrorCode = (typeof OIDC_ERROR_CODES)[keyof typeof OIDC_ERROR_CODES];
+/** How a thrown code travels: the same families as `@starci/auth`'s error kinds. */
+export type OidcErrorKind = "invalid" | "unavailable" | "unauthenticated";
+/** The kind of every thrown code. */
+export declare const OIDC_ERROR_KINDS: Readonly<Record<OidcErrorCode, OidcErrorKind>>;
+/** Why a token was refused: the reason a refusal's detail names. */
+export type OidcRefusalReason = "malformed" | "algorithm" | "unknown-key" | "signature" | "issuer" | "audience" | "authorized-party" | "expired" | "not-yet-valid" | "token-type" | "claims";
+/** The claim names read beyond the registered ones. */
+export declare const OIDC_CLAIMS: {
+    readonly sessionId: "sid";
+    readonly tokenId: "jti";
+    readonly email: "email";
+    readonly emailVerified: "email_verified";
+    readonly name: "name";
+    readonly username: "preferred_username";
+    readonly authorizedParty: "azp";
+    readonly realmAccess: "realm_access";
+    readonly resourceAccess: "resource_access";
+    readonly tokenType: "typ";
+    readonly nonce: "nonce";
+};
+/** The most roles a token may carry and the longest a role may be: a token past either is refused, so a claim cannot grow without bound. */
+export declare const OIDC_ROLE_BOUNDS: {
+    readonly maxRoles: 128;
+    readonly maxLength: 256;
+};
+/** The longest `sub` a principal may have. */
+export declare const OIDC_SUBJECT_MAX_LENGTH = 255;
+/** The principal a verified access token stands for. Assignable to `@starci/auth`'s `AuthPrincipal`, with the roles the issuer granted. */
+export interface OidcPrincipal {
+    /** The account: the `sub` claim. */
+    readonly id: string;
+    /** Always `authenticated`: a guard that checks the role of the lite principal checks this one the same way. */
+    readonly role: typeof OIDC_ROLE;
+    /** The provider session: the `sid` claim, else the token id (`jti`), else the subject. */
+    readonly sessionId: string;
+    /** The verified `email` claim, when the token has one. */
+    readonly email?: string;
+    /** The display name, when the token has one. */
+    readonly name?: string;
+    /** The `preferred_username`, when the token has one. */
+    readonly username?: string;
+    /** The roles the issuer granted, from the realm and from the clients the registration maps, sorted and without repeats. */
+    readonly roles: readonly string[];
+    /** The issuer that signed the token. */
+    readonly issuer: string;
+    /** When the token stops being accepted. */
+    readonly expiresAt: Date;
+}
+/** The refusal of a verifier. */
+export interface OidcRefusal {
+    readonly kind: "refused";
+    readonly code: typeof OIDC_ACCESS_TOKEN_INVALID;
+    readonly detail?: Readonly<Record<string, unknown>>;
+}
+/** The result of a check that can refuse: the same two shapes as `@starci/auth`'s `Outcome`. */
+export type OidcOutcome<T> = {
+    readonly kind: "ok";
+    readonly value: T;
+} | OidcRefusal;
+/**
+ * What a guard asks of an identity source: the principal of a bearer token, or a refusal. The same interface as
+ * `PrincipalVerifier` of `@starci/auth/server` (the package's own specs hold that this verifier is assignable to that one, and its principal to `AuthPrincipal`), so
+ * guards, `@Public` and `@Credential` do not change between editions.
+ */
+export interface PrincipalVerifier {
+    /** Verifies one token at one instant. A provider that cannot be reached throws an `OidcError` of kind `unavailable`; an untrusted token is a refusal. */
+    verify(token: string, now?: Date): Promise<OidcOutcome<OidcPrincipal>>;
+}
+/** What a completed authorization-code flow established, after the ID token passed signature, issuer, audience, expiry and nonce. */
+export interface OidcIdentity {
+    /** The issuer that signed the ID token. */
+    readonly issuer: string;
+    /** The verified account subject. */
+    readonly subject: string;
+    /** The roles the ID token carries. */
+    readonly roles: readonly string[];
+    /** The verified email, when the token has one. */
+    readonly email?: string;
+    /** The provider session, when the token names one. */
+    readonly sessionId?: string;
+    /** The verified token expiry, which bounds a local session. */
+    readonly expiresAt: Date;
+}
+/** The person a front-end session belongs to. */
+export interface OidcSessionUser {
+    /** The subject. */
+    readonly id: string;
+    /** The email, or empty text when the token has none. */
+    readonly email: string;
+}
+/** The kinds of failure a front-end call ends with. */
+export type OidcFailureKind = "refused" | "not-found" | "invalid" | "unavailable";
+/** The outcome of a front-end call: a value, or a failure carrying its kind and a code. The same shape as `AuthOutcome` of `@starci/auth/contracts`. */
+export type OidcClientOutcome<T> = {
+    readonly success: true;
+    readonly message: "ok";
+    readonly data: T;
+} | {
+    readonly success: false;
+    readonly message: OidcFailureKind;
+    readonly error: string;
+};
+/** The codes a front-end failure carries. */
+export declare const OIDC_CLIENT_CODES: {
+    readonly State: "OIDC_STATE_INVALID";
+    readonly Nonce: "OIDC_NONCE_INVALID";
+    readonly Issuer: "OIDC_ISSUER_MISMATCH";
+    readonly Provider: "OIDC_PROVIDER_REFUSED";
+    readonly Token: "OIDC_TOKEN_RESPONSE_INVALID";
+    readonly Transport: "OIDC_TRANSPORT";
+    readonly NoLogout: "OIDC_NO_LOGOUT_ENDPOINT";
+};

package/dist/contracts/index.js

@@ -0,0 +1,55 @@
+/**
+ * What both sides of an OIDC sign-in share: the algorithms a token may be signed with, the wire codes, the claim names and the
+ * shapes of the answers. The server module and the front-end client read these constants, so the two never drift.
+ */
+/** The signature algorithms a verifier may be pinned to: asymmetric only. `none` and every HMAC algorithm are not in the list and are refused at registration. */
+export const OIDC_ALGORITHMS = ["RS256", "RS384", "RS512", "PS256", "PS384", "PS512", "ES256", "ES384", "ES512", "EdDSA"];
+/** The algorithm list a registration pins when it names none: what Keycloak signs with by default. */
+export const OIDC_DEFAULT_ALGORITHMS = ["RS256"];
+/** The `role` every verified principal carries, the one `@starci/auth` gives its principals, so a guard reads one value in both editions. */
+export const OIDC_ROLE = "authenticated";
+/**
+ * The wire code a verifier refuses a token with: the code `@starci/auth`'s verifier uses, so the guard and the filter that map it
+ * to a 401 are the same in both editions. The specific reason travels in the refusal's `detail.reason`, for the log, never for the client.
+ */
+export const OIDC_ACCESS_TOKEN_INVALID = "PASSPORT_ACCESS_TOKEN_INVALID";
+/** The codes of the errors the package throws: a provider that cannot be reached is `Unavailable`, a response that cannot be trusted is `Rejected`. */
+export const OIDC_ERROR_CODES = {
+    ConfigurationInvalid: "OIDC_CONFIGURATION_INVALID",
+    Unavailable: "OIDC_UNAVAILABLE",
+    Rejected: "OIDC_REJECTED",
+};
+/** The kind of every thrown code. */
+export const OIDC_ERROR_KINDS = {
+    [OIDC_ERROR_CODES.ConfigurationInvalid]: "invalid",
+    [OIDC_ERROR_CODES.Unavailable]: "unavailable",
+    [OIDC_ERROR_CODES.Rejected]: "unauthenticated",
+};
+/** The claim names read beyond the registered ones. */
+export const OIDC_CLAIMS = {
+    sessionId: "sid",
+    tokenId: "jti",
+    email: "email",
+    emailVerified: "email_verified",
+    name: "name",
+    username: "preferred_username",
+    authorizedParty: "azp",
+    realmAccess: "realm_access",
+    resourceAccess: "resource_access",
+    tokenType: "typ",
+    nonce: "nonce",
+};
+/** The most roles a token may carry and the longest a role may be: a token past either is refused, so a claim cannot grow without bound. */
+export const OIDC_ROLE_BOUNDS = { maxRoles: 128, maxLength: 256 };
+/** The longest `sub` a principal may have. */
+export const OIDC_SUBJECT_MAX_LENGTH = 255;
+/** The codes a front-end failure carries. */
+export const OIDC_CLIENT_CODES = {
+    State: "OIDC_STATE_INVALID",
+    Nonce: "OIDC_NONCE_INVALID",
+    Issuer: "OIDC_ISSUER_MISMATCH",
+    Provider: "OIDC_PROVIDER_REFUSED",
+    Token: "OIDC_TOKEN_RESPONSE_INVALID",
+    Transport: "OIDC_TRANSPORT",
+    NoLogout: "OIDC_NO_LOGOUT_ENDPOINT",
+};

package/dist/server/client.d.ts

@@ -0,0 +1,48 @@
+import type { OidcIdentity } from "../contracts/index.js";
+import type { OidcDiscovery } from "./discovery.js";
+import type { ResolvedOidcOptions } from "./options.js";
+import type { OidcTokenVerifier } from "./tokens.js";
+/** The proof values the app owns and sends to the authorization endpoint. */
+export interface OidcAuthorization {
+    /** One-use transaction state. */
+    readonly state: string;
+    /** Binds the ID token to the browser transaction. */
+    readonly nonce: string;
+    /** The base64url SHA-256 digest of the retained PKCE verifier (`pkceChallenge`). */
+    readonly challenge: string;
+    /** `none`, `login`, `consent` or `select_account`, when the flow must not (or must) show a login page. */
+    readonly prompt?: "none" | "login" | "consent" | "select_account" | undefined;
+}
+/** A claimed callback, exchanged exactly once. */
+export interface OidcExchange {
+    /** The transient authorization code; never returned to the browser. */
+    readonly code: string;
+    /** The retained PKCE verifier. */
+    readonly verifier: string;
+    /** The nonce retained with the transaction. */
+    readonly nonce: string;
+    /** The `iss` of the authorization response, when the provider sent one; a supplied issuer must equal the configured one. */
+    readonly issuer?: string | undefined;
+}
+/** The address a browser is sent to for RP-initiated logout. */
+export interface OidcLogout {
+    /** Sent as `id_token_hint` when the app retained the ID token. */
+    readonly idTokenHint?: string | undefined;
+    /** Sent as `state`. */
+    readonly state?: string | undefined;
+}
+/**
+ * The authorization code flow of one registered client: it builds the authorization address (S256 PKCE, nonce, state), exchanges a
+ * code once at the token endpoint and verifies the ID token (signature, issuer, audience = the client, expiry, nonce) before it answers
+ * an identity, and builds the RP-initiated logout address. It never returns or logs a provider token.
+ */
+export declare class OidcClient {
+    #private;
+    constructor(options: ResolvedOidcOptions, discovery: OidcDiscovery, tokens: OidcTokenVerifier);
+    /** The address the browser goes to for the registered code flow. */
+    authorization(input: OidcAuthorization): Promise<string>;
+    /** Exchanges a claimed code once, then verifies the ID token and answers the identity it asserts. */
+    exchange(input: OidcExchange): Promise<OidcIdentity>;
+    /** The RP-initiated logout address of the registered client. */
+    logout(input?: OidcLogout): Promise<string>;
+}

package/dist/server/client.js

@@ -0,0 +1,114 @@
+import { OIDC_CLAIMS, OIDC_ERROR_CODES, OIDC_SUBJECT_MAX_LENGTH } from "../contracts/index.js";
+import { OidcError } from "./errors.js";
+import { isRecord, revealed, sameValue } from "./primitives.js";
+import { rolesOf } from "./roles.js";
+const rejected = (cause) => new OidcError(OIDC_ERROR_CODES.Rejected, cause === undefined ? {} : { cause });
+/**
+ * The authorization code flow of one registered client: it builds the authorization address (S256 PKCE, nonce, state), exchanges a
+ * code once at the token endpoint and verifies the ID token (signature, issuer, audience = the client, expiry, nonce) before it answers
+ * an identity, and builds the RP-initiated logout address. It never returns or logs a provider token.
+ */
+export class OidcClient {
+    #options;
+    #discovery;
+    #tokens;
+    constructor(options, discovery, tokens) {
+        this.#options = options;
+        this.#discovery = discovery;
+        this.#tokens = tokens;
+    }
+    /** The address the browser goes to for the registered code flow. */
+    async authorization(input) {
+        const client = this.#registration();
+        const metadata = await this.#discovery.get();
+        const url = new URL(metadata.authorizationEndpoint);
+        url.search = new URLSearchParams({
+            response_type: "code",
+            client_id: client.clientId,
+            redirect_uri: client.callbackUri,
+            scope: client.scope ?? "openid",
+            state: input.state,
+            nonce: input.nonce,
+            code_challenge: input.challenge,
+            code_challenge_method: "S256",
+            ...(input.prompt === undefined ? {} : { prompt: input.prompt }),
+        }).toString();
+        return url.toString();
+    }
+    /** Exchanges a claimed code once, then verifies the ID token and answers the identity it asserts. */
+    async exchange(input) {
+        const client = this.#registration();
+        if (input.issuer !== undefined && input.issuer !== this.#options.issuer)
+            throw rejected();
+        const metadata = await this.#discovery.get();
+        const response = await this.#options.http
+            .request({
+            method: "POST",
+            url: metadata.tokenEndpoint,
+            timeoutMs: this.#options.timeoutMs,
+            form: {
+                grant_type: "authorization_code",
+                client_id: client.clientId,
+                ...(client.clientSecret === undefined ? {} : { client_secret: revealed(client.clientSecret) }),
+                redirect_uri: client.callbackUri,
+                code: input.code,
+                code_verifier: input.verifier,
+            },
+        })
+            .catch((cause) => {
+            throw new OidcError(OIDC_ERROR_CODES.Unavailable, { cause });
+        });
+        if (response.status >= 500)
+            throw new OidcError(OIDC_ERROR_CODES.Unavailable);
+        if (response.status !== 200 || !isRecord(response.body) || typeof response.body.id_token !== "string")
+            throw rejected();
+        return this.#identityOf(response.body.id_token, input.nonce);
+    }
+    /** The RP-initiated logout address of the registered client. */
+    async logout(input = {}) {
+        const client = this.#registration();
+        const { endSessionEndpoint } = await this.#discovery.get();
+        if (endSessionEndpoint === undefined)
+            throw rejected();
+        const url = new URL(endSessionEndpoint);
+        url.search = new URLSearchParams({
+            client_id: client.clientId,
+            post_logout_redirect_uri: client.postLogoutUri,
+            ...(input.idTokenHint === undefined ? {} : { id_token_hint: input.idTokenHint }),
+            ...(input.state === undefined ? {} : { state: input.state }),
+        }).toString();
+        return url.toString();
+    }
+    #registration() {
+        const client = this.#options.client;
+        if (client === undefined)
+            throw new OidcError(OIDC_ERROR_CODES.ConfigurationInvalid, { params: { key: "client" } });
+        return client;
+    }
+    async #identityOf(idToken, nonce) {
+        const client = this.#registration();
+        const verified = await this.#tokens.verify(idToken, { audience: [client.clientId], requiredClaims: [OIDC_CLAIMS.nonce] });
+        if (verified.kind === "refused")
+            throw rejected();
+        const claims = verified.value;
+        const received = claims[OIDC_CLAIMS.nonce];
+        if (typeof received !== "string" || !sameValue(received, nonce))
+            throw rejected();
+        const { sub, exp } = claims;
+        if (typeof sub !== "string" || sub === "" || sub.length > OIDC_SUBJECT_MAX_LENGTH || typeof exp !== "number" || !Number.isSafeInteger(exp))
+            throw rejected();
+        const roles = rolesOf(claims, { realm: this.#options.realmRoles, clients: this.#options.roleClients, claims: this.#options.roleClaims });
+        if (roles === undefined)
+            throw rejected();
+        const email = claims[OIDC_CLAIMS.email];
+        const sessionId = claims[OIDC_CLAIMS.sessionId];
+        return {
+            issuer: this.#options.issuer,
+            subject: sub,
+            roles,
+            ...(typeof email === "string" && email !== "" ? { email } : {}),
+            ...(typeof sessionId === "string" && sessionId !== "" ? { sessionId } : {}),
+            expiresAt: new Date(exp * 1000),
+        };
+    }
+}

package/dist/server/discovery.d.ts

@@ -0,0 +1,21 @@
+import type { ResolvedOidcOptions } from "./options.js";
+/** The endpoints of the discovery document the package uses, each validated against the issuer. */
+export interface OidcMetadata {
+    readonly issuer: string;
+    readonly authorizationEndpoint: string;
+    readonly tokenEndpoint: string;
+    readonly jwksUri: string;
+    /** Absent when the provider offers no RP-initiated logout. */
+    readonly endSessionEndpoint: string | undefined;
+}
+/** The discovery address of an issuer. */
+export declare const discoveryUrl: (issuer: string) => string;
+/** Narrows a discovery document: its `issuer` is the configured issuer exactly, and every endpoint passes `endpointOf`. */
+export declare const readMetadata: (value: unknown, options: ResolvedOidcOptions) => OidcMetadata;
+/** Fetches and caches the discovery document of the issuer; concurrent callers share one request. */
+export declare class OidcDiscovery {
+    #private;
+    constructor(options: ResolvedOidcOptions);
+    /** The metadata: the cached document while it is fresh, else a new one. A provider that cannot be asked throws `Unavailable`; the cached document is never used past its life, so an outage never keeps stale endpoints. */
+    get(): Promise<OidcMetadata>;
+}

package/dist/server/discovery.js

@@ -0,0 +1,63 @@
+import { OIDC_ERROR_CODES } from "../contracts/index.js";
+import { OidcError } from "./errors.js";
+import { isAdmissibleUrl } from "./options.js";
+import { isRecord } from "./primitives.js";
+const DISCOVERY_PATH = "/.well-known/openid-configuration";
+/** The discovery address of an issuer. */
+export const discoveryUrl = (issuer) => `${issuer.replace(/\/$/u, "")}${DISCOVERY_PATH}`;
+const rejected = () => new OidcError(OIDC_ERROR_CODES.Rejected);
+/**
+ * An endpoint the provider advertises is trusted only on the issuer's own origin, over the admitted scheme, without credentials or a
+ * fragment: a discovery document cannot send the client secret or the browser to another host.
+ */
+const endpointOf = (value, options) => {
+    if (typeof value !== "string" || !isAdmissibleUrl(value, options.allowInsecureHttp))
+        throw rejected();
+    if (new URL(value).origin !== new URL(options.issuer).origin)
+        throw rejected();
+    return value;
+};
+/** Narrows a discovery document: its `issuer` is the configured issuer exactly, and every endpoint passes `endpointOf`. */
+export const readMetadata = (value, options) => {
+    if (!isRecord(value) || value.issuer !== options.issuer)
+        throw rejected();
+    return {
+        issuer: options.issuer,
+        authorizationEndpoint: endpointOf(value.authorization_endpoint, options),
+        tokenEndpoint: endpointOf(value.token_endpoint, options),
+        jwksUri: endpointOf(value.jwks_uri, options),
+        endSessionEndpoint: value.end_session_endpoint === undefined ? undefined : endpointOf(value.end_session_endpoint, options),
+    };
+};
+/** Fetches and caches the discovery document of the issuer; concurrent callers share one request. */
+export class OidcDiscovery {
+    #options;
+    #held;
+    #pending;
+    constructor(options) {
+        this.#options = options;
+    }
+    /** The metadata: the cached document while it is fresh, else a new one. A provider that cannot be asked throws `Unavailable`; the cached document is never used past its life, so an outage never keeps stale endpoints. */
+    async get() {
+        const now = this.#options.clock.now().getTime();
+        if (this.#held !== undefined && now - this.#held.at < this.#options.discoveryTtlMs)
+            return this.#held.metadata;
+        this.#pending ??= this.#fetch().finally(() => {
+            this.#pending = undefined;
+        });
+        return this.#pending;
+    }
+    async #fetch() {
+        const options = this.#options;
+        const response = await options.http
+            .request({ method: "GET", url: discoveryUrl(options.issuer), timeoutMs: options.timeoutMs })
+            .catch((cause) => {
+            throw new OidcError(OIDC_ERROR_CODES.Unavailable, { cause });
+        });
+        if (response.status !== 200)
+            throw new OidcError(OIDC_ERROR_CODES.Unavailable);
+        const metadata = readMetadata(response.body, options);
+        this.#held = { metadata, at: options.clock.now().getTime() };
+        return metadata;
+    }
+}

package/dist/server/errors.d.ts

@@ -0,0 +1,11 @@
+import type { OidcErrorCode, OidcErrorKind } from "../contracts/index.js";
+/** The one error class the package throws: a stable code, the kind it travels as, the key a configuration error names and the cause, never provider prose or a token. */
+export declare class OidcError extends Error {
+    readonly code: OidcErrorCode;
+    readonly kind: OidcErrorKind;
+    readonly params: Readonly<Record<string, string>>;
+    constructor(code: OidcErrorCode, options?: {
+        readonly cause?: unknown;
+        readonly params?: Readonly<Record<string, string>>;
+    });
+}

package/dist/server/errors.js

@@ -0,0 +1,14 @@
+import { OIDC_ERROR_KINDS } from "../contracts/index.js";
+/** The one error class the package throws: a stable code, the kind it travels as, the key a configuration error names and the cause, never provider prose or a token. */
+export class OidcError extends Error {
+    code;
+    kind;
+    params;
+    constructor(code, options = {}) {
+        super(code, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "OidcError";
+        this.code = code;
+        this.kind = OIDC_ERROR_KINDS[code];
+        this.params = options.params ?? {};
+    }
+}

package/dist/server/index.d.ts

@@ -0,0 +1,22 @@
+export { OidcClient } from "./client.js";
+export type { OidcAuthorization, OidcExchange, OidcLogout } from "./client.js";
+export { OidcDiscovery, discoveryUrl, readMetadata } from "./discovery.js";
+export type { OidcMetadata } from "./discovery.js";
+export { OidcError } from "./errors.js";
+export { OidcKeys, readKeySet } from "./jwks.js";
+export type { OidcKeySet } from "./jwks.js";
+export { OidcModule, MODULE_OPTIONS_TOKEN as OIDC_OPTIONS } from "./oidc.module.js";
+export type { OidcModuleExtras, OidcRegisterAsyncOptions, OidcRegisterOptions } from "./oidc.module.js";
+export { createOidc } from "./oidc.js";
+export type { Oidc } from "./oidc.js";
+export { OIDC_CLIENT, OIDC_DISCOVERY, OIDC_KEYS, OIDC_PRINCIPAL_VERIFIER, OIDC_REGISTRATION, OIDC_TOKEN_VERIFIER } from "./oidc.tokens.js";
+export { fetchHttp, isAdmissibleUrl, resolveOptions } from "./options.js";
+export type { OidcClientRegistration, OidcHttp, OidcHttpRequest, OidcHttpResponse, OidcJwksOptions, OidcOptions, OidcRoleMapping, ResolvedOidcOptions, } from "./options.js";
+export { isRecord, pkceChallenge, randomReference, sameValue, systemClock } from "./primitives.js";
+export type { OidcClock, Revealable, SecretInput } from "./primitives.js";
+export { rolesOf } from "./roles.js";
+export type { RoleSources } from "./roles.js";
+export { OidcTokenVerifier } from "./tokens.js";
+export type { TokenExpectations } from "./tokens.js";
+export { OidcPrincipalVerifier, refuseSessions } from "./verifier.js";
+export type { OidcOutcome, OidcPrincipal, PrincipalVerifier } from "../contracts/index.js";

package/dist/server/index.js

@@ -0,0 +1,12 @@
+export { OidcClient } from "./client.js";
+export { OidcDiscovery, discoveryUrl, readMetadata } from "./discovery.js";
+export { OidcError } from "./errors.js";
+export { OidcKeys, readKeySet } from "./jwks.js";
+export { OidcModule, MODULE_OPTIONS_TOKEN as OIDC_OPTIONS } from "./oidc.module.js";
+export { createOidc } from "./oidc.js";
+export { OIDC_CLIENT, OIDC_DISCOVERY, OIDC_KEYS, OIDC_PRINCIPAL_VERIFIER, OIDC_REGISTRATION, OIDC_TOKEN_VERIFIER } from "./oidc.tokens.js";
+export { fetchHttp, isAdmissibleUrl, resolveOptions } from "./options.js";
+export { isRecord, pkceChallenge, randomReference, sameValue, systemClock } from "./primitives.js";
+export { rolesOf } from "./roles.js";
+export { OidcTokenVerifier } from "./tokens.js";
+export { OidcPrincipalVerifier, refuseSessions } from "./verifier.js";

package/dist/server/jwks.d.ts

@@ -0,0 +1,22 @@
+import { createLocalJWKSet } from "jose";
+import type { JSONWebKeySet } from "jose";
+import type { OidcDiscovery } from "./discovery.js";
+import type { ResolvedOidcOptions } from "./options.js";
+/** The key set jose selects a verification key from. */
+export type OidcKeySet = ReturnType<typeof createLocalJWKSet>;
+/**
+ * Narrows a fetched document to public signature keys. Keys the provider marks for encryption are dropped (Keycloak publishes
+ * them beside its signing keys); a document with no key left, with more than `maxKeys`, or with a private or symmetric key is rejected.
+ */
+export declare const readKeySet: (value: unknown, maxKeys: number) => JSONWebKeySet;
+/**
+ * The provider's signing keys: fetched from the discovered `jwks_uri`, cached for `ttlMs`, and refreshed when a token names a `kid` the
+ * cache lacks (the provider rotated), at most once per `refreshCooldownMs`. When the provider cannot be reached the expired set is still
+ * used for `staleTtlMs`, so a provider outage does not sign everybody out; past that the call throws `Unavailable`. Concurrent callers share one fetch.
+ */
+export declare class OidcKeys {
+    #private;
+    constructor(options: ResolvedOidcOptions, discovery: OidcDiscovery);
+    /** The key set to verify a token whose header names `kid` (undefined when it names none). */
+    keysFor(kid: string | undefined): Promise<OidcKeySet>;
+}

package/dist/server/jwks.js

@@ -0,0 +1,80 @@
+import { createLocalJWKSet } from "jose";
+import { OIDC_ERROR_CODES } from "../contracts/index.js";
+import { OidcError } from "./errors.js";
+import { isRecord } from "./primitives.js";
+/** The members that make a JWK private or symmetric: a key set carrying one is never verification input. */
+const PRIVATE_MEMBERS = ["d", "p", "q", "dp", "dq", "qi", "k", "oth"];
+const KEY_TYPES = ["RSA", "EC", "OKP"];
+const isPublicKey = (key) => isRecord(key) && typeof key.kty === "string" && KEY_TYPES.includes(key.kty) && PRIVATE_MEMBERS.every((member) => key[member] === undefined);
+/**
+ * Narrows a fetched document to public signature keys. Keys the provider marks for encryption are dropped (Keycloak publishes
+ * them beside its signing keys); a document with no key left, with more than `maxKeys`, or with a private or symmetric key is rejected.
+ */
+export const readKeySet = (value, maxKeys) => {
+    if (!isRecord(value) || !Array.isArray(value.keys) || value.keys.length === 0 || value.keys.length > maxKeys)
+        throw new OidcError(OIDC_ERROR_CODES.Rejected);
+    const keys = value.keys;
+    if (!keys.every(isPublicKey))
+        throw new OidcError(OIDC_ERROR_CODES.Rejected);
+    const signing = keys.filter(isPublicKey).filter((key) => key.use !== "enc");
+    if (signing.length === 0)
+        throw new OidcError(OIDC_ERROR_CODES.Rejected);
+    // Every key was checked above to be public key material of a known type; jose checks the members it needs when it selects a key.
+    return { keys: signing.map((key) => ({ ...key })) };
+};
+/** The key ids a held set publishes. */
+const kidsOf = (set) => new Set(set.keys.flatMap((key) => (typeof key.kid === "string" ? [key.kid] : [])));
+/**
+ * The provider's signing keys: fetched from the discovered `jwks_uri`, cached for `ttlMs`, and refreshed when a token names a `kid` the
+ * cache lacks (the provider rotated), at most once per `refreshCooldownMs`. When the provider cannot be reached the expired set is still
+ * used for `staleTtlMs`, so a provider outage does not sign everybody out; past that the call throws `Unavailable`. Concurrent callers share one fetch.
+ */
+export class OidcKeys {
+    #options;
+    #discovery;
+    #held;
+    #pending;
+    constructor(options, discovery) {
+        this.#options = options;
+        this.#discovery = discovery;
+    }
+    /** The key set to verify a token whose header names `kid` (undefined when it names none). */
+    async keysFor(kid) {
+        const options = this.#options;
+        const now = options.clock.now().getTime();
+        const held = this.#held;
+        if (held !== undefined) {
+            const age = now - held.at;
+            const known = kid === undefined || kidsOf(held.set).has(kid);
+            if (age < options.jwksTtlMs && (known || age < options.jwksCooldownMs))
+                return held.local;
+        }
+        try {
+            return (await this.#refresh()).local;
+        }
+        catch (cause) {
+            if (held !== undefined && now - held.at < options.jwksStaleMs)
+                return held.local;
+            throw cause;
+        }
+    }
+    #refresh() {
+        this.#pending ??= this.#fetch().finally(() => {
+            this.#pending = undefined;
+        });
+        return this.#pending;
+    }
+    async #fetch() {
+        const options = this.#options;
+        const { jwksUri } = await this.#discovery.get();
+        const response = await options.http.request({ method: "GET", url: jwksUri, timeoutMs: options.timeoutMs }).catch((cause) => {
+            throw new OidcError(OIDC_ERROR_CODES.Unavailable, { cause });
+        });
+        if (response.status !== 200)
+            throw new OidcError(OIDC_ERROR_CODES.Unavailable);
+        const set = readKeySet(response.body, options.jwksMaxKeys);
+        const held = { set, local: createLocalJWKSet(set), at: options.clock.now().getTime() };
+        this.#held = held;
+        return held;
+    }
+}

package/dist/server/oidc.d.ts

@@ -0,0 +1,23 @@
+import { OidcClient } from "./client.js";
+import { OidcDiscovery } from "./discovery.js";
+import { OidcKeys } from "./jwks.js";
+import type { OidcOptions, ResolvedOidcOptions } from "./options.js";
+import { OidcTokenVerifier } from "./tokens.js";
+import { OidcPrincipalVerifier } from "./verifier.js";
+/** The parts of one OIDC registration, built from validated options. */
+export interface Oidc {
+    /** The options after validation, defaults applied. */
+    readonly options: ResolvedOidcOptions;
+    /** The discovery document of the issuer. */
+    readonly discovery: OidcDiscovery;
+    /** The provider's signing keys. */
+    readonly keys: OidcKeys;
+    /** The verifier of the provider's signed tokens. */
+    readonly tokens: OidcTokenVerifier;
+    /** The `PrincipalVerifier` guards inject. */
+    readonly verifier: OidcPrincipalVerifier;
+    /** The authorization code flow client; null when the registration declares no client. */
+    readonly client: OidcClient | null;
+}
+/** Builds one registration without Nest: the module uses it, and so can a script or a spec. Invalid options throw a `ConfigurationInvalid` error. */
+export declare const createOidc: (input: OidcOptions) => Oidc;