@starci/auth-oidc 0.0.0-stage → 0.1.0

package/dist/server/oidc.js

@@ -0,0 +1,21 @@
+import { OidcClient } from "./client.js";
+import { OidcDiscovery } from "./discovery.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);
+    return {
+        options,
+        discovery,
+        keys,
+        tokens,
+        verifier: new OidcPrincipalVerifier(options, tokens),
+        client: options.client === undefined ? null : new OidcClient(options, discovery, tokens),
+    };
+};

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

@@ -0,0 +1,33 @@
+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. 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/server/oidc.module.js

@@ -0,0 +1,47 @@
+import { ConfigurableModuleBuilder, Module } from "@nestjs/common";
+import { createOidc } from "./oidc.js";
+import { OIDC_CLIENT, OIDC_DISCOVERY, OIDC_KEYS, OIDC_PRINCIPAL_VERIFIER, OIDC_REGISTRATION, 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_PRINCIPAL_VERIFIER, inject: [OIDC_REGISTRATION], useFactory: (oidc) => oidc.verifier },
+];
+const EXPORTED = [OIDC_DISCOVERY, OIDC_KEYS, OIDC_TOKEN_VERIFIER, OIDC_CLIENT, 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. 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/server/oidc.tokens.d.ts

@@ -0,0 +1,12 @@
+/** 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 the `PrincipalVerifier` the identity domain injects. */
+export declare const OIDC_PRINCIPAL_VERIFIER: unique symbol;

package/dist/server/oidc.tokens.js

@@ -0,0 +1,12 @@
+/** 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 the `PrincipalVerifier` the identity domain injects. */
+export const OIDC_PRINCIPAL_VERIFIER = Symbol.for("@starci/auth-oidc/principal-verifier");

package/dist/server/options.d.ts

@@ -0,0 +1,113 @@
+import type { OidcAlgorithm } from "../contracts/index.js";
+import type { OidcClock, SecretInput } from "./primitives.js";
+/** One outbound request of the provider protocol. */
+export interface OidcHttpRequest {
+    readonly method: "GET" | "POST";
+    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>>;
+}
+/** 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 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;

package/dist/server/options.js

@@ -0,0 +1,91 @@
+import { OIDC_ALGORITHMS, OIDC_DEFAULT_ALGORITHMS, OIDC_ERROR_CODES } from "../contracts/index.js";
+import { OidcError } from "./errors.js";
+import { systemClock } from "./primitives.js";
+const MINUTE_MS = 60_000;
+const HOUR_MS = 3_600_000;
+const invalid = (key) => new OidcError(OIDC_ERROR_CODES.ConfigurationInvalid, { params: { key } });
+/** True when the address is an absolute, credential-free URL on the scheme the registration admits (https; http only when allowed). */
+export const isAdmissibleUrl = (value, insecure) => {
+    if (!URL.canParse(value))
+        return false;
+    const url = new URL(value);
+    const scheme = url.protocol === "https:" || (insecure && url.protocol === "http:");
+    return scheme && url.username === "" && url.password === "" && url.hash === "";
+};
+const positive = (value, fallback, key) => {
+    const chosen = value ?? fallback;
+    if (!Number.isFinite(chosen) || chosen <= 0)
+        throw invalid(key);
+    return chosen;
+};
+const toleranceOf = (value) => {
+    const chosen = value ?? 5;
+    if (!Number.isFinite(chosen) || chosen < 0)
+        throw invalid("clockToleranceSeconds");
+    return chosen;
+};
+const audiencesOf = (audience) => {
+    const list = typeof audience === "string" ? [audience] : audience;
+    if (list.length === 0 || list.some((entry) => entry === ""))
+        throw invalid("audience");
+    return list;
+};
+const algorithmsOf = (algorithms) => {
+    const list = algorithms ?? OIDC_DEFAULT_ALGORITHMS;
+    const admitted = OIDC_ALGORITHMS;
+    if (list.length === 0 || list.some((algorithm) => !admitted.includes(algorithm)))
+        throw invalid("algorithms");
+    return list;
+};
+const checkClient = (client, insecure) => {
+    if (client.clientId === "")
+        throw invalid("client.clientId");
+    for (const key of ["callbackUri", "postLogoutUri"]) {
+        const value = client[key];
+        if (!isAdmissibleUrl(value, insecure) || new URL(value).search !== "")
+            throw invalid(`client.${key}`);
+    }
+};
+/** The platform `fetch` as the outbound port: JSON answers are parsed, the request's deadline aborts it. */
+export const fetchHttp = {
+    async request(request) {
+        const response = await fetch(request.url, {
+            method: request.method,
+            redirect: "manual",
+            signal: AbortSignal.timeout(request.timeoutMs),
+            headers: request.form === undefined ? { accept: "application/json" } : { accept: "application/json", "content-type": "application/x-www-form-urlencoded" },
+            ...(request.form === undefined ? {} : { body: new URLSearchParams(request.form).toString() }),
+        });
+        const body = await response.json().catch(() => undefined);
+        return { status: response.status, body };
+    },
+};
+/** Validates the registration and applies the defaults. A key that does not meet the contract throws a `ConfigurationInvalid` error naming it. */
+export const resolveOptions = (options) => {
+    const insecure = options.allowInsecureHttp ?? false;
+    if (!isAdmissibleUrl(options.issuer, insecure) || new URL(options.issuer).search !== "")
+        throw invalid("issuer");
+    if (options.client !== undefined)
+        checkClient(options.client, insecure);
+    const jwks = options.jwks;
+    return {
+        issuer: options.issuer,
+        audience: audiencesOf(options.audience),
+        algorithms: algorithmsOf(options.algorithms),
+        authorizedParty: options.authorizedParty,
+        client: options.client,
+        realmRoles: options.roles?.realm ?? true,
+        roleClients: options.roles?.clients ?? [],
+        roleClaims: options.roles?.claims ?? [],
+        timeoutMs: positive(options.timeoutMs, 10_000, "timeoutMs"),
+        clockToleranceSeconds: toleranceOf(options.clockToleranceSeconds),
+        discoveryTtlMs: positive(options.discoveryTtlMs, HOUR_MS, "discoveryTtlMs"),
+        jwksTtlMs: positive(jwks?.ttlMs, 10 * MINUTE_MS, "jwks.ttlMs"),
+        jwksCooldownMs: positive(jwks?.refreshCooldownMs, MINUTE_MS / 2, "jwks.refreshCooldownMs"),
+        jwksStaleMs: positive(jwks?.staleTtlMs, 24 * HOUR_MS, "jwks.staleTtlMs"),
+        jwksMaxKeys: positive(jwks?.maxKeys, 100, "jwks.maxKeys"),
+        allowInsecureHttp: insecure,
+        http: options.http ?? fetchHttp,
+        clock: options.clock ?? systemClock,
+    };
+};

package/dist/server/primitives.d.ts

@@ -0,0 +1,22 @@
+/** A value read out of a secret holder (the app's `Secret` class has this shape). */
+export interface Revealable {
+    reveal(): string;
+}
+/** A secret given as text or as a holder the app already keeps. */
+export type SecretInput = string | Revealable;
+/** The text of a secret input; called only where the secret is sent. */
+export declare const revealed: (secret: SecretInput) => string;
+/** A record: a non-null object that is not an array. */
+export declare const isRecord: (value: unknown) => value is Readonly<Record<string, unknown>>;
+/** True when two texts are equal, compared in constant time over equal-length buffers. */
+export declare const sameValue: (given: string, expected: string) => boolean;
+/** 256 unpredictable bits as base64url: a state, a nonce, a PKCE verifier or an opaque reference. */
+export declare const randomReference: () => string;
+/** The S256 challenge of a PKCE verifier: base64url(SHA-256(verifier)). */
+export declare const pkceChallenge: (verifier: string) => string;
+/** The clock the package reads. */
+export interface OidcClock {
+    now(): Date;
+}
+/** The system clock. */
+export declare const systemClock: OidcClock;

package/dist/server/primitives.js

@@ -0,0 +1,17 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+/** The text of a secret input; called only where the secret is sent. */
+export const revealed = (secret) => (typeof secret === "string" ? secret : secret.reveal());
+/** A record: a non-null object that is not an array. */
+export const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** True when two texts are equal, compared in constant time over equal-length buffers. */
+export const sameValue = (given, expected) => {
+    const left = Buffer.from(given);
+    const right = Buffer.from(expected);
+    return left.length === right.length && timingSafeEqual(left, right);
+};
+/** 256 unpredictable bits as base64url: a state, a nonce, a PKCE verifier or an opaque reference. */
+export const randomReference = () => randomBytes(32).toString("base64url");
+/** The S256 challenge of a PKCE verifier: base64url(SHA-256(verifier)). */
+export const pkceChallenge = (verifier) => createHash("sha256").update(verifier).digest("base64url");
+/** The system clock. */
+export const systemClock = { now: () => new Date() };

package/dist/server/roles.d.ts

@@ -0,0 +1,12 @@
+/** Which claims hold roles. */
+export interface RoleSources {
+    readonly realm: boolean;
+    readonly clients: readonly string[];
+    readonly claims: readonly string[];
+}
+/**
+ * The roles a verified token grants: `realm_access.roles` (when the mapping reads the realm), `resource_access.<client>.roles` of each
+ * mapped client and each mapped flat claim. Sorted, without repeats. A claim of the wrong shape, or past the bounds, makes the whole
+ * token untrusted (`undefined`): a role is an authorization input, so it is never guessed from a malformed claim.
+ */
+export declare const rolesOf: (payload: Readonly<Record<string, unknown>>, sources: RoleSources) => readonly string[] | undefined;

package/dist/server/roles.js

@@ -0,0 +1,51 @@
+import { OIDC_CLAIMS, OIDC_ROLE_BOUNDS } from "../contracts/index.js";
+import { isRecord } from "./primitives.js";
+/** The roles of a claim value shaped `{ roles: string[] }`, or undefined when the shape is wrong. */
+const rolesOfContainer = (value) => {
+    if (value === undefined)
+        return [];
+    return isRecord(value) ? rolesOfList(value.roles) : undefined;
+};
+/** The roles of a claim value shaped `string[]`, or undefined when it is not one of bounded text. */
+const rolesOfList = (value) => {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > OIDC_ROLE_BOUNDS.maxRoles)
+        return undefined;
+    const list = value;
+    const texts = list.filter((role) => typeof role === "string" && role.length > 0 && role.length <= OIDC_ROLE_BOUNDS.maxLength);
+    return texts.length === list.length ? texts : undefined;
+};
+/**
+ * The roles a verified token grants: `realm_access.roles` (when the mapping reads the realm), `resource_access.<client>.roles` of each
+ * mapped client and each mapped flat claim. Sorted, without repeats. A claim of the wrong shape, or past the bounds, makes the whole
+ * token untrusted (`undefined`): a role is an authorization input, so it is never guessed from a malformed claim.
+ */
+export const rolesOf = (payload, sources) => {
+    const granted = new Set();
+    const add = (roles) => {
+        if (roles === undefined)
+            return false;
+        for (const role of roles)
+            granted.add(role);
+        return true;
+    };
+    if (sources.realm && !add(rolesOfContainer(payload[OIDC_CLAIMS.realmAccess])))
+        return undefined;
+    if (sources.clients.length > 0) {
+        const access = payload[OIDC_CLAIMS.resourceAccess];
+        if (access !== undefined && !isRecord(access))
+            return undefined;
+        for (const client of sources.clients) {
+            if (!add(rolesOfContainer(access === undefined ? undefined : access[client])))
+                return undefined;
+        }
+    }
+    for (const claim of sources.claims) {
+        if (!add(rolesOfList(payload[claim])))
+            return undefined;
+    }
+    if (granted.size > OIDC_ROLE_BOUNDS.maxRoles)
+        return undefined;
+    return [...granted].sort();
+};

package/dist/server/tokens.d.ts

@@ -0,0 +1,24 @@
+import type { JWTPayload } from "jose";
+import type { OidcAlgorithm, OidcOutcome } from "../contracts/index.js";
+import type { OidcKeys } from "./jwks.js";
+import type { ResolvedOidcOptions } from "./options.js";
+/** What one verification expects beyond the issuer and the pinned algorithms. */
+export interface TokenExpectations {
+    /** The audience: the token must name one of these. */
+    readonly audience: readonly string[];
+    /** Claims the token must carry. */
+    readonly requiredClaims?: readonly string[] | undefined;
+}
+/**
+ * The one verifier of the provider's signed tokens (access tokens and ID tokens). The algorithm is pinned to the registration's list
+ * before any key is looked up (so `none` and a symmetric algorithm never reach a key), the key comes from the provider's JWKS by `kid`,
+ * and the issuer, audience, expiry and not-before are checked against the registration and the clock.
+ */
+export declare class OidcTokenVerifier {
+    #private;
+    constructor(options: ResolvedOidcOptions, keys: OidcKeys);
+    /** The algorithms this verifier admits. */
+    get algorithms(): readonly OidcAlgorithm[];
+    /** The claims of a token that passed every check, or a refusal naming why. A provider that cannot be reached throws `Unavailable`. */
+    verify(token: string, expectations: TokenExpectations, now?: Date): Promise<OidcOutcome<JWTPayload>>;
+}

package/dist/server/tokens.js

@@ -0,0 +1,79 @@
+import { decodeProtectedHeader, errors, jwtVerify } from "jose";
+import { OIDC_ACCESS_TOKEN_INVALID } from "../contracts/index.js";
+const refuse = (reason) => ({ kind: "refused", code: OIDC_ACCESS_TOKEN_INVALID, detail: { reason } });
+/** The reason a jose error stands for. */
+const reasonOf = (error) => {
+    if (error instanceof errors.JWTExpired)
+        return "expired";
+    if (error instanceof errors.JWSSignatureVerificationFailed || error instanceof errors.JWKSNoMatchingKey || error instanceof errors.JWKSMultipleMatchingKeys)
+        return "signature";
+    if (error instanceof errors.JOSEAlgNotAllowed)
+        return "algorithm";
+    if (error instanceof errors.JWTClaimValidationFailed) {
+        switch (error.claim) {
+            case "iss":
+                return "issuer";
+            case "aud":
+                return "audience";
+            case "nbf":
+            case "iat":
+                return "not-yet-valid";
+            case "exp":
+                return "expired";
+            default:
+                return "claims";
+        }
+    }
+    return error instanceof errors.JWTInvalid || error instanceof errors.JWSInvalid ? "malformed" : "signature";
+};
+/** The header of a token read without trusting it, only to pick the verification key; `undefined` when it is not a JWS header. */
+const headerOf = (token) => {
+    try {
+        const header = decodeProtectedHeader(token);
+        return { alg: header.alg, kid: header.kid };
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * The one verifier of the provider's signed tokens (access tokens and ID tokens). The algorithm is pinned to the registration's list
+ * before any key is looked up (so `none` and a symmetric algorithm never reach a key), the key comes from the provider's JWKS by `kid`,
+ * and the issuer, audience, expiry and not-before are checked against the registration and the clock.
+ */
+export class OidcTokenVerifier {
+    #options;
+    #keys;
+    constructor(options, keys) {
+        this.#options = options;
+        this.#keys = keys;
+    }
+    /** The algorithms this verifier admits. */
+    get algorithms() {
+        return this.#options.algorithms;
+    }
+    /** The claims of a token that passed every check, or a refusal naming why. A provider that cannot be reached throws `Unavailable`. */
+    async verify(token, expectations, now = this.#options.clock.now()) {
+        const header = headerOf(token);
+        if (header === undefined)
+            return refuse("malformed");
+        const admitted = this.#options.algorithms;
+        if (header.alg === undefined || !admitted.includes(header.alg))
+            return refuse("algorithm");
+        const keys = await this.#keys.keysFor(header.kid);
+        try {
+            const { payload } = await jwtVerify(token, keys, {
+                algorithms: [...this.#options.algorithms],
+                issuer: this.#options.issuer,
+                audience: [...expectations.audience],
+                currentDate: now,
+                clockTolerance: this.#options.clockToleranceSeconds,
+                requiredClaims: ["exp", "sub", ...(expectations.requiredClaims ?? [])],
+            });
+            return { kind: "ok", value: payload };
+        }
+        catch (error) {
+            return refuse(reasonOf(error));
+        }
+    }
+}

package/dist/server/verifier.d.ts

@@ -0,0 +1,15 @@
+import type { OidcOutcome, OidcPrincipal, PrincipalVerifier } from "../contracts/index.js";
+import type { ResolvedOidcOptions } from "./options.js";
+import type { OidcTokenVerifier } from "./tokens.js";
+/**
+ * The `PrincipalVerifier` of the full edition: a bearer access token of the provider, checked against the discovered issuer's JWKS
+ * (algorithm pinned, issuer, audience, expiry), becomes the principal a guard reads. The principal has the shape of `@starci/auth`'s, with
+ * the roles the issuer granted added, so guards, `@Public` and `@Credential` do not change between editions.
+ */
+export declare class OidcPrincipalVerifier implements PrincipalVerifier {
+    #private;
+    constructor(options: ResolvedOidcOptions, tokens: OidcTokenVerifier);
+    verify(token: string, now?: Date): Promise<OidcOutcome<OidcPrincipal>>;
+}
+/** The verifier of an app that serves no user session: every token is refused, so the default-deny guard admits only its public and credential doors. */
+export declare const refuseSessions: PrincipalVerifier;

package/dist/server/verifier.js

@@ -0,0 +1,58 @@
+import { OIDC_ACCESS_TOKEN_INVALID, OIDC_CLAIMS, OIDC_ROLE, OIDC_SUBJECT_MAX_LENGTH } from "../contracts/index.js";
+import { rolesOf } from "./roles.js";
+/** The `typ` claim of an access token Keycloak issues. An ID token (`ID`) or a refresh token presented as a bearer is not one. */
+const ACCESS_TOKEN_TYPE = "Bearer";
+const refuse = (reason) => ({ kind: "refused", code: OIDC_ACCESS_TOKEN_INVALID, detail: { reason } });
+const text = (value) => (typeof value === "string" && value !== "" ? value : undefined);
+/**
+ * The `PrincipalVerifier` of the full edition: a bearer access token of the provider, checked against the discovered issuer's JWKS
+ * (algorithm pinned, issuer, audience, expiry), becomes the principal a guard reads. The principal has the shape of `@starci/auth`'s, with
+ * the roles the issuer granted added, so guards, `@Public` and `@Credential` do not change between editions.
+ */
+export class OidcPrincipalVerifier {
+    #options;
+    #tokens;
+    constructor(options, tokens) {
+        this.#options = options;
+        this.#tokens = tokens;
+    }
+    async verify(token, now = this.#options.clock.now()) {
+        const verified = await this.#tokens.verify(token, { audience: this.#options.audience }, now);
+        if (verified.kind === "refused")
+            return verified;
+        const claims = verified.value;
+        const subject = text(claims.sub);
+        if (subject === undefined || subject.length > OIDC_SUBJECT_MAX_LENGTH || typeof claims.exp !== "number")
+            return refuse("claims");
+        const type = claims[OIDC_CLAIMS.tokenType];
+        if (type !== undefined && type !== ACCESS_TOKEN_TYPE)
+            return refuse("token-type");
+        const party = this.#options.authorizedParty;
+        if (party !== undefined && claims[OIDC_CLAIMS.authorizedParty] !== party)
+            return refuse("authorized-party");
+        const roles = rolesOf(claims, { realm: this.#options.realmRoles, clients: this.#options.roleClients, claims: this.#options.roleClaims });
+        if (roles === undefined)
+            return refuse("claims");
+        const email = text(claims[OIDC_CLAIMS.email]);
+        const name = text(claims[OIDC_CLAIMS.name]);
+        const username = text(claims[OIDC_CLAIMS.username]);
+        return {
+            kind: "ok",
+            value: {
+                id: subject,
+                role: OIDC_ROLE,
+                sessionId: text(claims[OIDC_CLAIMS.sessionId]) ?? text(claims[OIDC_CLAIMS.tokenId]) ?? subject,
+                ...(email === undefined ? {} : { email }),
+                ...(name === undefined ? {} : { name }),
+                ...(username === undefined ? {} : { username }),
+                roles,
+                issuer: this.#options.issuer,
+                expiresAt: new Date(claims.exp * 1000),
+            },
+        };
+    }
+}
+/** The verifier of an app that serves no user session: every token is refused, so the default-deny guard admits only its public and credential doors. */
+export const refuseSessions = {
+    verify: () => Promise.resolve(refuse("claims")),
+};