@starci/auth 0.4.0 → 0.6.0

package/dist/oidc/issuers/issuer.d.ts

@@ -0,0 +1,79 @@
+import type { JWTPayload } from "jose";
+import type { OidcAlgorithm, OidcOutcome, OidcRefusalReason } from "../../contracts/oidc.js";
+import type { OidcHttp, OidcJwksOptions } from "../options.js";
+import type { OidcClock } from "../primitives.js";
+/** Where an issuer's keys come from: an address the preset pins (Google, GitHub Actions), or the issuer's discovery document (Keycloak). */
+export type IssuerKeys = {
+    readonly kind: "jwks";
+    readonly uri: string;
+} | {
+    readonly kind: "discovery";
+};
+/** The addresses of a test double standing in for an issuer (the fake issuer of `@starci/auth/testing`); a deployment never sets them. */
+export interface IssuerEndpoints {
+    /** The `iss` the double signs with. */
+    readonly issuer: string;
+    /** The double's key set address. */
+    readonly jwksUri: string;
+}
+/**
+ * One identity issuer whose signed tokens an app verifies: who signs (issuer), with what (algorithms, pinned before any key is looked up),
+ * for whom (audience, never empty), where the keys are, which claims a token must carry, and how verified claims become what the app reads
+ * (`identityOf`, which may refuse a token whose claims break the preset's policy). A preset is data plus one mapping; the verifier is the
+ * package's (`createIssuerVerifier`).
+ */
+export interface IssuerPreset<T> {
+    /** The preset name, for a log line (`github-actions`). */
+    readonly name: string;
+    /** The exact issuer. */
+    readonly issuer: string;
+    /** Other spellings of the same issuer the `iss` claim may carry (`accounts.google.com`). */
+    readonly issuerAliases: readonly string[];
+    /** Where the keys come from. */
+    readonly keys: IssuerKeys;
+    /** The algorithms a token may be signed with. */
+    readonly algorithms: readonly OidcAlgorithm[];
+    /** The audience a token must name: one of these. */
+    readonly audience: readonly string[];
+    /** Claims a token must carry beyond `exp` and `sub`. */
+    readonly requiredClaims: readonly string[];
+    /** What the verified claims stand for, or a refusal naming the reason and the claim. */
+    readonly identityOf: (claims: JWTPayload) => IssuerMapping<T>;
+}
+/** The result of a preset's claim mapping. */
+export type IssuerMapping<T> = {
+    readonly kind: "ok";
+    readonly value: T;
+} | {
+    readonly kind: "refused";
+    readonly reason: OidcRefusalReason;
+    readonly claim?: string;
+};
+/** A mapped identity. */
+export declare const mapped: <T>(value: T) => IssuerMapping<T>;
+/** A refused mapping: the reason, and the claim that decided it. */
+export declare const unmapped: (reason: OidcRefusalReason, claim?: string) => IssuerMapping<never>;
+/** The transport and timing of an issuer verifier; the preset decides everything that is trust. */
+export interface IssuerVerifierOptions {
+    /** The outbound HTTP port (the platform `fetch` when absent): the app's bounded client. */
+    readonly http?: OidcHttp | undefined;
+    /** The clock (system time when absent). */
+    readonly clock?: OidcClock | undefined;
+    /** The deadline of every key or discovery request, in milliseconds (10000). */
+    readonly timeoutMs?: number | undefined;
+    /** The clock skew a token's `exp` and `nbf` tolerate, in seconds (5). */
+    readonly clockToleranceSeconds?: number | undefined;
+    /** The key set cache. */
+    readonly jwks?: OidcJwksOptions | undefined;
+    /** Admit `http:` addresses: only for a test double on a developer machine. */
+    readonly allowInsecureHttp?: boolean | undefined;
+}
+/** A verifier of one issuer's tokens. */
+export interface IssuerVerifier<T> {
+    /** The preset it verifies for. */
+    readonly preset: IssuerPreset<T>;
+    /** What a token stands for when it passes the algorithm pin, the signature against the issuer's keys, issuer, audience, expiry, the required claims and the preset's policy; else a refusal. An issuer that cannot be reached throws `Unavailable`. */
+    verify(token: string, now?: Date): Promise<OidcOutcome<T>>;
+}
+/** Builds the verifier of one preset; a preset that does not meet the contract (no audience, an admitted algorithm list, an address) throws `ConfigurationInvalid`. */
+export declare const createIssuerVerifier: <T>(preset: IssuerPreset<T>, options?: IssuerVerifierOptions) => IssuerVerifier<T>;

package/dist/oidc/issuers/issuer.js

@@ -0,0 +1,39 @@
+import { OIDC_ACCESS_TOKEN_INVALID, OIDC_ERROR_CODES } from "../../contracts/oidc.js";
+import { OidcDiscovery } from "../discovery.js";
+import { OidcError } from "../errors.js";
+import { OidcKeys } from "../jwks.js";
+import { isAdmissibleUrl, resolveOptions } from "../options.js";
+import { OidcTokenVerifier } from "../tokens.js";
+/** A mapped identity. */
+export const mapped = (value) => ({ kind: "ok", value });
+/** A refused mapping: the reason, and the claim that decided it. */
+export const unmapped = (reason, claim) => (claim === undefined ? { kind: "refused", reason } : { kind: "refused", reason, claim });
+const refuse = (reason, claim) => ({
+    kind: "refused",
+    code: OIDC_ACCESS_TOKEN_INVALID,
+    detail: claim === undefined ? { reason } : { reason, claim },
+});
+const keySourceOf = (preset, options) => {
+    if (preset.keys.kind === "discovery")
+        return new OidcDiscovery(options);
+    const uri = preset.keys.uri;
+    if (!isAdmissibleUrl(uri, options.allowInsecureHttp))
+        throw new OidcError(OIDC_ERROR_CODES.ConfigurationInvalid, { params: { key: "keys.uri" } });
+    return { get: () => Promise.resolve({ jwksUri: uri }) };
+};
+/** Builds the verifier of one preset; a preset that does not meet the contract (no audience, an admitted algorithm list, an address) throws `ConfigurationInvalid`. */
+export const createIssuerVerifier = (preset, options = {}) => {
+    const resolved = resolveOptions({ ...options, issuer: preset.issuer, audience: preset.audience, algorithms: preset.algorithms });
+    const tokens = new OidcTokenVerifier(resolved, new OidcKeys(resolved, keySourceOf(preset, resolved)));
+    const issuers = [preset.issuer, ...preset.issuerAliases];
+    return {
+        preset,
+        async verify(token, now = resolved.clock.now()) {
+            const verified = await tokens.verify(token, { audience: resolved.audience, issuer: issuers, requiredClaims: preset.requiredClaims }, now);
+            if (verified.kind === "refused")
+                return verified;
+            const identity = preset.identityOf(verified.value);
+            return identity.kind === "ok" ? { kind: "ok", value: identity.value } : refuse(identity.reason, identity.claim);
+        },
+    };
+};

package/dist/oidc/issuers/keycloak.d.ts

@@ -0,0 +1,26 @@
+import type { OidcAlgorithm, OidcPrincipal } from "../../contracts/oidc.js";
+import type { OidcOptions, OidcRoleMapping } from "../options.js";
+import type { IssuerEndpoints, IssuerPreset } from "./issuer.js";
+/** A Keycloak realm and what its access tokens must say. */
+export interface KeycloakIssuerOptions {
+    /** The Keycloak origin (`https://id.example.com`). */
+    readonly origin: string;
+    /** The realm. */
+    readonly realm: string;
+    /** The audience an access token must name: one of these. */
+    readonly audience: string | readonly string[];
+    /** The algorithms (`RS256`, what Keycloak signs with by default). */
+    readonly algorithms?: readonly OidcAlgorithm[] | undefined;
+    /** When set, an access token's `azp` must equal it. */
+    readonly authorizedParty?: string | undefined;
+    /** Which roles become the principal's roles (the realm roles). */
+    readonly roles?: OidcRoleMapping | undefined;
+    /** A test double's issuer (its keys come from its discovery document like Keycloak's). */
+    readonly endpoints?: Pick<IssuerEndpoints, "issuer"> | undefined;
+}
+/** The issuer address of a Keycloak realm: `<origin>/realms/<realm>`. */
+export declare const keycloakIssuerUrl: (origin: string, realm: string) => string;
+/** The trust half of an `OidcModule` registration for a Keycloak realm: spread it with the app's transport (`OidcModule.register({ ...keycloakOptions(o), http, clock })`). */
+export declare const keycloakOptions: (options: KeycloakIssuerOptions) => Pick<OidcOptions, "issuer" | "audience" | "algorithms" | "authorizedParty" | "roles">;
+/** The Keycloak preset: realm access tokens, keys from the realm's discovery document, the principal the module's verifier builds. */
+export declare const keycloakIssuer: (options: KeycloakIssuerOptions) => IssuerPreset<OidcPrincipal>;

package/dist/oidc/issuers/keycloak.js

@@ -0,0 +1,41 @@
+import { OIDC_DEFAULT_ALGORITHMS } from "../../contracts/oidc.js";
+import { principalOf } from "../verifier.js";
+import { mapped, unmapped } from "./issuer.js";
+/** The issuer address of a Keycloak realm: `<origin>/realms/<realm>`. */
+export const keycloakIssuerUrl = (origin, realm) => `${origin.replace(/\/+$/u, "")}/realms/${encodeURIComponent(realm)}`;
+/** The trust half of an `OidcModule` registration for a Keycloak realm: spread it with the app's transport (`OidcModule.register({ ...keycloakOptions(o), http, clock })`). */
+export const keycloakOptions = (options) => ({
+    issuer: options.endpoints?.issuer ?? keycloakIssuerUrl(options.origin, options.realm),
+    audience: options.audience,
+    algorithms: options.algorithms ?? OIDC_DEFAULT_ALGORITHMS,
+    authorizedParty: options.authorizedParty,
+    roles: options.roles,
+});
+/** The Keycloak preset: realm access tokens, keys from the realm's discovery document, the principal the module's verifier builds. */
+export const keycloakIssuer = (options) => {
+    const trust = keycloakOptions(options);
+    const audience = typeof options.audience === "string" ? [options.audience] : options.audience;
+    const rules = {
+        issuer: trust.issuer,
+        authorizedParty: options.authorizedParty,
+        realmRoles: options.roles?.realm ?? true,
+        roleClients: options.roles?.clients ?? [],
+        roleClaims: options.roles?.claims ?? [],
+    };
+    return {
+        name: "keycloak",
+        issuer: trust.issuer,
+        issuerAliases: [],
+        keys: { kind: "discovery" },
+        algorithms: trust.algorithms ?? OIDC_DEFAULT_ALGORITHMS,
+        audience,
+        requiredClaims: [],
+        identityOf: (claims) => {
+            const principal = principalOf(claims, rules);
+            if (principal.kind === "ok")
+                return mapped(principal.value);
+            const reason = principal.detail?.reason;
+            return unmapped(reason === "token-type" || reason === "authorized-party" ? reason : "claims");
+        },
+    };
+};

package/dist/oidc/jwks.d.ts

@@ -0,0 +1,26 @@
+import { createLocalJWKSet } from "jose";
+import type { JSONWebKeySet } from "jose";
+import type { OidcMetadata } from "./discovery.js";
+import type { ResolvedOidcOptions } from "./options.js";
+/** The key set jose selects a verification key from. */
+export type OidcKeySet = ReturnType<typeof createLocalJWKSet>;
+/** Where the key set address comes from: the discovery document (`OidcDiscovery`), or an address an issuer preset pins. */
+export interface OidcKeySource {
+    get(): Promise<Pick<OidcMetadata, "jwksUri">>;
+}
+/**
+ * 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: OidcKeySource);
+    /** The key set to verify a token whose header names `kid` (undefined when it names none). */
+    keysFor(kid: string | undefined): Promise<OidcKeySet>;
+}

package/dist/oidc/jwks.js

@@ -0,0 +1,80 @@
+import { createLocalJWKSet } from "jose";
+import { OIDC_ERROR_CODES } from "../contracts/oidc.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/oidc/oidc.d.ts

@@ -0,0 +1,32 @@
+import { OidcAdminClient } from "./admin.js";
+import { OidcBroker } from "./broker.js";
+import { OidcClient } from "./client.js";
+import { OidcDiscovery } from "./discovery.js";
+import { OidcTokenClient } from "./grants.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;
+    /** The server-side grants (password, refresh, revocation); each call throws a `ConfigurationInvalid` error when the registration declares no client. */
+    readonly tokenClient: OidcTokenClient;
+    /** The provider's admin API as the client's service account; needs a client secret. */
+    readonly admin: OidcAdminClient;
+    /** The facade an app binds its identity port to: grants, social sign-in and account administration. */
+    readonly broker: OidcBroker;
+}
+/** 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;

package/dist/oidc/oidc.js

@@ -0,0 +1,21 @@
+import { OidcAdminClient } from "./admin.js";
+import { OidcBroker } from "./broker.js";
+import { OidcClient } from "./client.js";
+import { OidcDiscovery } from "./discovery.js";
+import { OidcTokenClient } from "./grants.js";
+import { OidcKeys } from "./jwks.js";
+import { resolveOptions } from "./options.js";
+import { OidcTokenVerifier } from "./tokens.js";
+import { OidcPrincipalVerifier } from "./verifier.js";
+/** Builds one registration without Nest: the module uses it, and so can a script or a spec. Invalid options throw a `ConfigurationInvalid` error. */
+export const createOidc = (input) => {
+    const options = resolveOptions(input);
+    const discovery = new OidcDiscovery(options);
+    const keys = new OidcKeys(options, discovery);
+    const tokens = new OidcTokenVerifier(options, keys);
+    const verifier = new OidcPrincipalVerifier(options, tokens);
+    const client = options.client === undefined ? null : new OidcClient(options, discovery, tokens);
+    const tokenClient = new OidcTokenClient(options, discovery, verifier);
+    const admin = new OidcAdminClient(options, discovery);
+    return { options, discovery, keys, tokens, verifier, client, tokenClient, admin, broker: new OidcBroker(tokenClient, client, admin) };
+};

package/dist/oidc/oidc.module.d.ts

@@ -0,0 +1,34 @@
+import type { ConfigurableModuleHost, DynamicModule } from "@nestjs/common";
+import type { OidcOptions } from "./options.js";
+/** The extras every registration sets beside the options. */
+export interface OidcModuleExtras {
+    /** Whether the module is global. */
+    readonly isGlobal: boolean;
+}
+type Host = ConfigurableModuleHost<OidcOptions, "register", "createOidcOptions", OidcModuleExtras>;
+/** The generated base class of the module (its `register` and `registerAsync`). */
+export declare const ConfigurableModuleClass: Host["ConfigurableModuleClass"];
+/** The injection token of the options the registration supplied. */
+export declare const MODULE_OPTIONS_TOKEN: Host["MODULE_OPTIONS_TOKEN"];
+/** Carries the type of the synchronous registration. */
+export declare const OPTIONS_TYPE: Host["OPTIONS_TYPE"];
+/** Carries the type of the asynchronous registration. */
+export declare const ASYNC_OPTIONS_TYPE: Host["ASYNC_OPTIONS_TYPE"];
+/** What `OidcModule.register` takes: the options, plus `isGlobal`. */
+export type OidcRegisterOptions = typeof OPTIONS_TYPE;
+/** What `OidcModule.registerAsync` takes: `imports`, `inject` and one of `useFactory`, `useClass`, `useExisting`, plus `isGlobal`. */
+export type OidcRegisterAsyncOptions = typeof ASYNC_OPTIONS_TYPE;
+/**
+ * The OIDC client of a full app as one Nest capability: the discovery document, the provider's signing keys, the token verifier, the
+ * `PrincipalVerifier` guards inject and, when the registration declares a client, the authorization code flow, the server-side grants, the
+ * admin API of its service account and the `OidcBroker` facade that joins them. Registered once at the api
+ * root; the app parses its settings (the package reads no environment) and passes them as typed options. A registration whose options do
+ * not meet the contract fails the boot with a `ConfigurationInvalid` error.
+ */
+export declare class OidcModule extends ConfigurableModuleClass {
+    /** Registers the module from options known now. */
+    static register(options: OidcRegisterOptions): DynamicModule;
+    /** Registers the module from options a factory, class or existing provider supplies. */
+    static registerAsync(options: OidcRegisterAsyncOptions): DynamicModule;
+}
+export {};

package/dist/oidc/oidc.module.js

@@ -0,0 +1,51 @@
+import { ConfigurableModuleBuilder, Module } from "@nestjs/common";
+import { createOidc } from "./oidc.js";
+import { OIDC_ADMIN_CLIENT, OIDC_BROKER, OIDC_CLIENT, OIDC_DISCOVERY, OIDC_KEYS, OIDC_PRINCIPAL_VERIFIER, OIDC_REGISTRATION, OIDC_TOKEN_CLIENT, OIDC_TOKEN_VERIFIER } from "./oidc.tokens.js";
+const built = new ConfigurableModuleBuilder({ moduleName: "Oidc" })
+    .setClassMethodName("register")
+    .setFactoryMethodName("createOidcOptions")
+    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
+    .build();
+/** The generated base class of the module (its `register` and `registerAsync`). */
+export const ConfigurableModuleClass = built.ConfigurableModuleClass;
+/** The injection token of the options the registration supplied. */
+export const MODULE_OPTIONS_TOKEN = built.MODULE_OPTIONS_TOKEN;
+/** Carries the type of the synchronous registration. */
+export const OPTIONS_TYPE = built.OPTIONS_TYPE;
+/** Carries the type of the asynchronous registration. */
+export const ASYNC_OPTIONS_TYPE = built.ASYNC_OPTIONS_TYPE;
+const providers = [
+    { provide: OIDC_REGISTRATION, inject: [MODULE_OPTIONS_TOKEN], useFactory: (options) => createOidc(options) },
+    { provide: OIDC_DISCOVERY, inject: [OIDC_REGISTRATION], useFactory: (oidc) => oidc.discovery },
+    { provide: OIDC_KEYS, inject: [OIDC_REGISTRATION], useFactory: (oidc) => oidc.keys },
+    { provide: OIDC_TOKEN_VERIFIER, inject: [OIDC_REGISTRATION], useFactory: (oidc) => oidc.tokens },
+    { provide: OIDC_CLIENT, inject: [OIDC_REGISTRATION], useFactory: (oidc) => oidc.client },
+    { provide: OIDC_TOKEN_CLIENT, inject: [OIDC_REGISTRATION], useFactory: (oidc) => oidc.tokenClient },
+    { provide: OIDC_ADMIN_CLIENT, inject: [OIDC_REGISTRATION], useFactory: (oidc) => oidc.admin },
+    { provide: OIDC_BROKER, inject: [OIDC_REGISTRATION], useFactory: (oidc) => oidc.broker },
+    { provide: OIDC_PRINCIPAL_VERIFIER, inject: [OIDC_REGISTRATION], useFactory: (oidc) => oidc.verifier },
+];
+const EXPORTED = [OIDC_DISCOVERY, OIDC_KEYS, OIDC_TOKEN_VERIFIER, OIDC_CLIENT, OIDC_TOKEN_CLIENT, OIDC_ADMIN_CLIENT, OIDC_BROKER, OIDC_PRINCIPAL_VERIFIER];
+const withProviders = (base) => ({
+    ...base,
+    providers: [...(base.providers ?? []), ...providers],
+    exports: [...(base.exports ?? []), ...EXPORTED],
+});
+/**
+ * The OIDC client of a full app as one Nest capability: the discovery document, the provider's signing keys, the token verifier, the
+ * `PrincipalVerifier` guards inject and, when the registration declares a client, the authorization code flow, the server-side grants, the
+ * admin API of its service account and the `OidcBroker` facade that joins them. Registered once at the api
+ * root; the app parses its settings (the package reads no environment) and passes them as typed options. A registration whose options do
+ * not meet the contract fails the boot with a `ConfigurationInvalid` error.
+ */
+export class OidcModule extends ConfigurableModuleClass {
+    /** Registers the module from options known now. */
+    static register(options) {
+        return withProviders(super.register(options));
+    }
+    /** Registers the module from options a factory, class or existing provider supplies. */
+    static registerAsync(options) {
+        return withProviders(super.registerAsync(options));
+    }
+}
+Module({})(OidcModule);

package/dist/oidc/oidc.tokens.d.ts

@@ -0,0 +1,18 @@
+/** Token of the `Oidc` registration (the parts below are its fields). */
+export declare const OIDC_REGISTRATION: unique symbol;
+/** Token of `OidcDiscovery`. */
+export declare const OIDC_DISCOVERY: unique symbol;
+/** Token of `OidcKeys`, the provider's signing keys. */
+export declare const OIDC_KEYS: unique symbol;
+/** Token of `OidcTokenVerifier`. */
+export declare const OIDC_TOKEN_VERIFIER: unique symbol;
+/** Token of `OidcClient`, the authorization code flow; null when the registration declares no client. */
+export declare const OIDC_CLIENT: unique symbol;
+/** Token of `OidcTokenClient`, the server-side password, refresh and revoke grants. */
+export declare const OIDC_TOKEN_CLIENT: unique symbol;
+/** Token of `OidcAdminClient`, the provider's admin API as the client's service account. */
+export declare const OIDC_ADMIN_CLIENT: unique symbol;
+/** Token of `OidcBroker`, the one facade an app binds its identity port to. */
+export declare const OIDC_BROKER: unique symbol;
+/** Token of the `PrincipalVerifier` the identity domain injects. */
+export declare const OIDC_PRINCIPAL_VERIFIER: unique symbol;

package/dist/oidc/oidc.tokens.js

@@ -0,0 +1,18 @@
+/** Token of the `Oidc` registration (the parts below are its fields). */
+export const OIDC_REGISTRATION = Symbol.for("@starci/auth-oidc/registration");
+/** Token of `OidcDiscovery`. */
+export const OIDC_DISCOVERY = Symbol.for("@starci/auth-oidc/discovery");
+/** Token of `OidcKeys`, the provider's signing keys. */
+export const OIDC_KEYS = Symbol.for("@starci/auth-oidc/keys");
+/** Token of `OidcTokenVerifier`. */
+export const OIDC_TOKEN_VERIFIER = Symbol.for("@starci/auth-oidc/token-verifier");
+/** Token of `OidcClient`, the authorization code flow; null when the registration declares no client. */
+export const OIDC_CLIENT = Symbol.for("@starci/auth-oidc/client");
+/** Token of `OidcTokenClient`, the server-side password, refresh and revoke grants. */
+export const OIDC_TOKEN_CLIENT = Symbol.for("@starci/auth-oidc/token-client");
+/** Token of `OidcAdminClient`, the provider's admin API as the client's service account. */
+export const OIDC_ADMIN_CLIENT = Symbol.for("@starci/auth-oidc/admin-client");
+/** Token of `OidcBroker`, the one facade an app binds its identity port to. */
+export const OIDC_BROKER = Symbol.for("@starci/auth-oidc/broker");
+/** Token of the `PrincipalVerifier` the identity domain injects. */
+export const OIDC_PRINCIPAL_VERIFIER = Symbol.for("@starci/auth-oidc/principal-verifier");

package/dist/oidc/options.d.ts

@@ -0,0 +1,119 @@
+import type { OidcAlgorithm } from "../contracts/oidc.js";
+import type { OidcClock, SecretInput } from "./primitives.js";
+/** One outbound request of the provider protocol. */
+export interface OidcHttpRequest {
+    readonly method: "GET" | "POST" | "PUT";
+    readonly url: string;
+    /** The deadline of this request, in milliseconds. */
+    readonly timeoutMs: number;
+    /** A form-encoded body (`application/x-www-form-urlencoded`) for a POST. */
+    readonly form?: Readonly<Record<string, string>>;
+    /** A JSON body (`application/json`) for a POST or a PUT; use either `body` or `form`, not both. The provider's admin API takes JSON. */
+    readonly body?: unknown;
+    /** Extra request headers (`authorization` of the admin API). */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** The answer to an outbound request: the status and the parsed JSON body (`undefined` when the body is not JSON). */
+export interface OidcHttpResponse {
+    readonly status: number;
+    readonly body: unknown;
+    /** The `Location` header of the answer, when it has one and the port reads it (a created user's address); optional, nothing depends on it. */
+    readonly location?: string | undefined;
+}
+/**
+ * The outbound HTTP port. An app passes its own bounded client (`platform/http`) through its glue, so the provider is spoken to
+ * through the one door the app owns; a registration without it uses the platform `fetch` with the request's deadline.
+ */
+export interface OidcHttp {
+    /** Sends one request; a transport failure rejects, any answer resolves. */
+    request(request: OidcHttpRequest): Promise<OidcHttpResponse>;
+}
+/** Which roles of a token become the principal's roles. */
+export interface OidcRoleMapping {
+    /** Read `realm_access.roles` (true when absent). */
+    readonly realm?: boolean | undefined;
+    /** Read `resource_access.<client>.roles` of each of these clients. */
+    readonly clients?: readonly string[] | undefined;
+    /** Read these flat claims, each an array of text (`groups`, `roles`). */
+    readonly claims?: readonly string[] | undefined;
+}
+/** How the JWKS is cached. */
+export interface OidcJwksOptions {
+    /** How long a fetched key set is used without asking again (10 minutes). */
+    readonly ttlMs?: number | undefined;
+    /** The least time between two fetches that an unknown `kid` may cause, so a forged `kid` cannot make the provider a target (30 seconds). */
+    readonly refreshCooldownMs?: number | undefined;
+    /** How long an expired key set is still used when the provider cannot be reached (24 hours). */
+    readonly staleTtlMs?: number | undefined;
+    /** The most keys a set may hold (100). */
+    readonly maxKeys?: number | undefined;
+}
+/** The registered client of the authorization code flow. Absent for an API that only verifies bearer tokens. */
+export interface OidcClientRegistration {
+    /** The client id; the audience of the ID token. */
+    readonly clientId: string;
+    /** The client secret of a confidential client, revealed only for the token request. Absent for a public client. */
+    readonly clientSecret?: SecretInput | undefined;
+    /** The exact registered redirect address. */
+    readonly callbackUri: string;
+    /** The exact registered address the provider returns to after logout. */
+    readonly postLogoutUri: string;
+    /** The requested scope (`openid`). */
+    readonly scope?: string | undefined;
+}
+/** Everything the package needs, typed and parsed by the app (the package reads no environment). */
+export interface OidcOptions {
+    /** The exact issuer: the `iss` claim of every token and the `issuer` of the discovery document. */
+    readonly issuer: string;
+    /** The audience an access token must name: one of these. */
+    readonly audience: string | readonly string[];
+    /** The algorithms a token may be signed with (`RS256`). Asymmetric only. */
+    readonly algorithms?: readonly OidcAlgorithm[] | undefined;
+    /** When set, an access token's `azp` claim must equal it. */
+    readonly authorizedParty?: string | undefined;
+    /** The authorization code flow client; needed to build an authorization address, exchange a code or build a logout address. */
+    readonly client?: OidcClientRegistration | undefined;
+    /** Which roles become the principal's roles (the realm roles). */
+    readonly roles?: OidcRoleMapping | undefined;
+    /** The deadline of every provider request, in milliseconds (10000). */
+    readonly timeoutMs?: number | undefined;
+    /** The clock skew a token's `exp` and `nbf` tolerate, in seconds (5). */
+    readonly clockToleranceSeconds?: number | undefined;
+    /** How long a discovery document is used (1 hour). */
+    readonly discoveryTtlMs?: number | undefined;
+    /** The JWKS cache. */
+    readonly jwks?: OidcJwksOptions | undefined;
+    /** Admit `http:` addresses. Only for a provider on a developer machine or a test double; never in a deployment. */
+    readonly allowInsecureHttp?: boolean | undefined;
+    /** The outbound HTTP port (the platform `fetch` when absent). */
+    readonly http?: OidcHttp | undefined;
+    /** The clock (system time when absent). */
+    readonly clock?: OidcClock | undefined;
+}
+/** The options after validation, with every default applied. */
+export interface ResolvedOidcOptions {
+    readonly issuer: string;
+    readonly audience: readonly string[];
+    readonly algorithms: readonly OidcAlgorithm[];
+    readonly authorizedParty: string | undefined;
+    readonly client: OidcClientRegistration | undefined;
+    readonly realmRoles: boolean;
+    readonly roleClients: readonly string[];
+    readonly roleClaims: readonly string[];
+    readonly timeoutMs: number;
+    readonly clockToleranceSeconds: number;
+    readonly discoveryTtlMs: number;
+    readonly jwksTtlMs: number;
+    readonly jwksCooldownMs: number;
+    readonly jwksStaleMs: number;
+    readonly jwksMaxKeys: number;
+    readonly allowInsecureHttp: boolean;
+    readonly http: OidcHttp;
+    readonly clock: OidcClock;
+}
+/** True when the address is an absolute, credential-free URL on the scheme the registration admits (https; http only when allowed). */
+export declare const isAdmissibleUrl: (value: string, insecure: boolean) => boolean;
+/** The platform `fetch` as the outbound port: JSON answers are parsed, the request's deadline aborts it. */
+export declare const fetchHttp: OidcHttp;
+/** Validates the registration and applies the defaults. A key that does not meet the contract throws a `ConfigurationInvalid` error naming it. */
+export declare const resolveOptions: (options: OidcOptions) => ResolvedOidcOptions;