@learncard/lca-api-service 1.3.2 → 1.5.0

package/src/helpers/learnCard.signingAuthority.test.ts

@@ -0,0 +1,194 @@
+import { KMSClient, GenerateDataKeyCommand } from '@aws-sdk/client-kms';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+    read: vi.fn(),
+    init: vi.fn(),
+    nativeInit: vi.fn(async () => ({})),
+    keys: [] as string[],
+}));
+vi.mock('@accesslayer/signing-authority/read', () => ({ getSigningAuthorityForDid: mocks.read }));
+vi.mock('@learncard/init', () => ({ initLearnCard: mocks.init }));
+vi.mock('@learncard/didkit-plugin-node', () => ({ getDidKitPlugin: mocks.nativeInit }));
+vi.mock('@cache/in-memory-lru', async importOriginal => {
+    const actual = await importOriginal<typeof import('@cache/in-memory-lru')>();
+    return {
+        getLRUCache: <T>() => {
+            const cache = actual.getLRUCache<T>();
+            return {
+                ...cache,
+                add: (key: string, value: T) => {
+                    mocks.keys.push(key);
+                    return cache.add(key, value);
+                },
+            };
+        },
+    };
+});
+vi.mock('@environment', async importOriginal => {
+    const actual = await importOriginal<typeof import('@environment')>();
+    return {
+        environment: {
+            ...actual.environment,
+            SKIP_DIDKIT_NAPI: false,
+            SA_SEED_KMS_KEY_ARN:
+                'arn:aws:kms:us-east-1:123456789012:key/11111111-1111-1111-1111-111111111111',
+        },
+    };
+});
+
+import { environment } from '@environment';
+import { seedEncryption } from './seedEncryption.helpers';
+import { getEphemeralLearnCard, getSigningAuthorityLearnCard } from './learnCard.helpers';
+
+const spyOnKms = () => vi.spyOn(KMSClient.prototype, 'send');
+let send: ReturnType<typeof spyOnKms>;
+beforeEach(() => {
+    vi.restoreAllMocks();
+    mocks.read.mockReset();
+    mocks.init.mockReset().mockImplementation(async options => ({ options }));
+    mocks.keys.length = 0;
+    send = vi.spyOn(KMSClient.prototype, 'send').mockImplementation(async command => ({
+        Plaintext: Buffer.alloc(32, 7),
+        KeyId: environment.SA_SEED_KMS_KEY_ARN,
+        ...(command instanceof GenerateDataKeyCommand
+            ? { CiphertextBlob: Buffer.from('wrapped') }
+            : {}),
+        $metadata: {},
+    }));
+    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+});
+
+const authority = async (id: string, ownerDid = 'did:example:owner', seed = 'a'.repeat(64)) => {
+    const identity = { _id: id, ownerDid, name: 'main', did: 'did:key:example' };
+    return { ...identity, ...(await seedEncryption.encrypt(seed, identity)) };
+};
+
+describe('SA signing cache', () => {
+    it('waits for engine setup before decrypting the seed', async () => {
+        const sa = await authority('engine-setup', 'did:example:engine-setup');
+        mocks.read.mockResolvedValue(sa);
+        let finishEngineSetup!: () => void;
+        mocks.nativeInit.mockImplementationOnce(
+            () =>
+                new Promise(resolve => {
+                    finishEngineSetup = () => resolve({});
+                })
+        );
+        send.mockClear();
+
+        const initialization = getSigningAuthorityLearnCard(sa.ownerDid, sa.name);
+        await vi.waitFor(() => expect(finishEngineSetup).toBeTypeOf('function'));
+        expect(send).not.toHaveBeenCalled();
+        expect(mocks.init).not.toHaveBeenCalled();
+
+        finishEngineSetup();
+        await initialization;
+        expect(send).toHaveBeenCalledTimes(1);
+    });
+
+    it.each(['did:example:seed-lifetime', 'did:web:seed-lifetime.example'])(
+        'releases initialization options after success for %s',
+        async ownerDid => {
+            const seed = 'c'.repeat(64);
+            const sa = await authority(ownerDid, ownerDid, seed);
+            mocks.read.mockResolvedValue(sa);
+            let finishInitialization!: () => void;
+            let initializationOptions: { seed: string; didWeb?: string } | undefined;
+            const card = {};
+            mocks.init.mockImplementationOnce(options => {
+                initializationOptions = options;
+                return new Promise(resolve => {
+                    finishInitialization = () => resolve(card);
+                });
+            });
+
+            const initialization = getSigningAuthorityLearnCard(sa.ownerDid, sa.name);
+            await vi.waitFor(() => expect(initializationOptions?.seed).toBe(seed));
+            expect(initializationOptions?.didWeb).toBe(
+                ownerDid.startsWith('did:web:') ? ownerDid : undefined
+            );
+            expect(mocks.keys).toEqual([]);
+
+            finishInitialization();
+            expect(await initialization).toBe(card);
+            expect(initializationOptions?.seed).toBe('');
+            expect(await getSigningAuthorityLearnCard(sa.ownerDid, sa.name)).toBe(card);
+            expect(mocks.init).toHaveBeenCalledTimes(1);
+        }
+    );
+
+    it('releases initialization options after failure and does not cache a failed signer', async () => {
+        const sa = await authority('init-failure', 'did:example:init-failure');
+        mocks.read.mockResolvedValue(sa);
+        let initializationOptions: { seed: string } | undefined;
+        const failure = new Error('Signer initialization failed');
+        mocks.init.mockImplementationOnce(async options => {
+            initializationOptions = options;
+            expect(options.seed).toBe('a'.repeat(64));
+            throw failure;
+        });
+
+        await expect(getSigningAuthorityLearnCard(sa.ownerDid, sa.name)).rejects.toBe(failure);
+        expect(initializationOptions?.seed).toBe('');
+        expect(mocks.keys).toEqual([]);
+
+        await getSigningAuthorityLearnCard(sa.ownerDid, sa.name);
+        expect(mocks.init).toHaveBeenCalledTimes(2);
+    });
+
+    it('makes one KMS call when cold and zero when warm, retaining no seed in cache keys', async () => {
+        const sa = await authority('warm');
+        mocks.read.mockResolvedValue(sa);
+        send.mockClear();
+        const first = await getSigningAuthorityLearnCard(sa.ownerDid, sa.name);
+        expect(send).toHaveBeenCalledTimes(1);
+        expect(await getSigningAuthorityLearnCard(sa.ownerDid, sa.name)).toBe(first);
+        expect(send).toHaveBeenCalledTimes(1);
+        expect(mocks.read).toHaveBeenCalledTimes(2);
+        expect(mocks.keys).toEqual([`${sa.ownerDid}|${sa.name}`]);
+        await getEphemeralLearnCard('b'.repeat(64));
+        expect(mocks.keys).toEqual([`${sa.ownerDid}|${sa.name}`]);
+    });
+
+    it('does not reuse a deleted/recreated authority under the same owner and name', async () => {
+        const firstRecord = await authority('old');
+        const replacement = await authority('replacement', firstRecord.ownerDid, 'b'.repeat(64));
+        mocks.read
+            .mockResolvedValueOnce(firstRecord)
+            .mockResolvedValueOnce(null)
+            .mockResolvedValueOnce(replacement);
+        send.mockClear();
+        const first = await getSigningAuthorityLearnCard(firstRecord.ownerDid, firstRecord.name);
+        await expect(
+            getSigningAuthorityLearnCard(firstRecord.ownerDid, firstRecord.name)
+        ).rejects.toThrow();
+        const second = await getSigningAuthorityLearnCard(replacement.ownerDid, replacement.name);
+        expect(first).not.toBe(second);
+        expect(send).toHaveBeenCalledTimes(2);
+    });
+
+    it('does not serve a warm wallet after its envelope is tampered with', async () => {
+        const sa = await authority('tamper');
+        mocks.read.mockResolvedValue(sa);
+        await getSigningAuthorityLearnCard(sa.ownerDid, sa.name);
+        const bytes = Buffer.from(sa.encryptedSeed, 'base64');
+        bytes[15] = bytes[15]! ^ 1;
+        mocks.read.mockResolvedValue({ ...sa, encryptedSeed: bytes.toString('base64') });
+        await expect(getSigningAuthorityLearnCard(sa.ownerDid, sa.name)).rejects.toMatchObject({
+            category: 'authentication_failed',
+        });
+    });
+
+    it('keeps did:web initialization behavior and does not cache failed decrypts', async () => {
+        const sa = await authority('did-web', 'did:web:issuer.example');
+        mocks.read.mockResolvedValue(sa);
+        send.mockRejectedValueOnce({ name: 'AccessDeniedException' });
+        await expect(getSigningAuthorityLearnCard(sa.ownerDid, sa.name)).rejects.toThrow();
+        expect(mocks.keys).toEqual([]);
+        await getSigningAuthorityLearnCard(sa.ownerDid, sa.name);
+        expect(mocks.init).toHaveBeenLastCalledWith(
+            expect.objectContaining({ didWeb: sa.ownerDid })
+        );
+    });
+});

package/src/helpers/login-ticket.helpers.test.ts

@@ -0,0 +1,45 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import cache from '@cache';
+import { issueLoginTicket } from '@cache/login-tickets';
+import { storeAccessToken, storeAuthorizationCode } from './login-ticket.helpers';
+
+vi.mock('@environment', () => ({ environment: {} }));
+
+afterEach(() => vi.restoreAllMocks());
+
+describe('authentication artifact persistence', () => {
+    const writers = [
+        {
+            name: 'login ticket',
+            write: () =>
+                issueLoginTicket({ subject: 'subject', identityKey: 'email:test@example.com' }),
+        },
+        {
+            name: 'authorization code',
+            write: () =>
+                storeAuthorizationCode({
+                    subject: 'subject',
+                    code: 'code',
+                    scope: 'openid',
+                    clientId: 'broker',
+                    redirectUri: 'https://broker.test/callback',
+                    createdAt: Date.now(),
+                }),
+        },
+        {
+            name: 'access token',
+            write: () =>
+                storeAccessToken('access-token', { subject: 'subject', createdAt: Date.now() }),
+        },
+    ];
+
+    it.each(writers)('rejects a swallowed $name write failure', async ({ name, write }) => {
+        vi.spyOn(cache, 'set').mockResolvedValueOnce(undefined);
+        await expect(write()).rejects.toThrow(`Failed to persist ${name}`);
+    });
+
+    it.each(writers)('propagates a rejected $name write', async ({ write }) => {
+        vi.spyOn(cache, 'set').mockRejectedValueOnce(new Error('Redis unavailable'));
+        await expect(write()).rejects.toThrow('Redis unavailable');
+    });
+});

package/src/helpers/login-ticket.helpers.ts

@@ -0,0 +1,91 @@
+/**
+ * Login tickets, authorization codes, and opaque access tokens for the lca-api
+ * OIDC provider (AD-2).
+ *
+ * Three short-lived, one-time-use artifacts back the "silent hop" login:
+ *  - A **login ticket** is minted after lca-api proves ownership of a contact
+ *    method / federated identity (email code, native Google/Apple). It carries
+ *    the verified claims and the stable subject id.
+ *  - An **authorization code** is minted by `/oidc/authorize` when it redeems a
+ *    login ticket (passed by Keycloak as `login_hint`). Keycloak exchanges the
+ *    code at `/oidc/token` for the signed `id_token`. The code is bound to the
+ *    client + redirect URI it was issued for.
+ *  - An **opaque access token** is minted alongside the id_token so Keycloak's
+ *    broker can call `/oidc/userinfo`. It maps to the same verified claims.
+ *
+ * All live in the cache (Redis in prod, in-memory mock in tests) with short
+ * TTLs. Tickets and codes are consumed (read-then-delete) so neither can be
+ * replayed; the access token is read-only for its short life.
+ */
+
+import crypto from 'node:crypto';
+
+import cache from '@cache';
+import { getDel } from '@cache/getDel';
+
+export const AUTH_CODE_PREFIX = 'oidc-code:';
+export const ACCESS_TOKEN_PREFIX = 'oidc:access:';
+
+export const AUTH_CODE_TTL_SECONDS = 60;
+export const ACCESS_TOKEN_TTL_SECONDS = 300;
+
+export interface SubjectClaims {
+    subject: string;
+    email?: string;
+    emailVerified?: boolean;
+    phoneNumber?: string;
+    phoneNumberVerified?: boolean;
+    name?: string;
+    picture?: string;
+}
+
+export interface AuthorizationCodeData extends SubjectClaims {
+    scope: string;
+    code: string;
+    clientId: string;
+    redirectUri: string;
+    nonce?: string;
+    state?: string;
+    createdAt: number;
+}
+
+export interface AccessTokenData extends SubjectClaims {
+    createdAt: number;
+}
+
+const codeKey = (code: string): string => `${AUTH_CODE_PREFIX}${code}`;
+const accessKey = (accessToken: string): string => `${ACCESS_TOKEN_PREFIX}${accessToken}`;
+
+export const generateAuthorizationCode = (): string => crypto.randomBytes(32).toString('base64url');
+export const generateAccessToken = (): string => crypto.randomBytes(32).toString('base64url');
+
+export const storeAuthorizationCode = async (
+    data: AuthorizationCodeData,
+    ttl = AUTH_CODE_TTL_SECONDS
+): Promise<void> => {
+    const result = await cache.set(codeKey(data.code), JSON.stringify(data), ttl);
+    if (result !== 'OK') throw new Error('Failed to persist authorization code');
+};
+
+export const consumeAuthorizationCode = async (
+    code: string
+): Promise<AuthorizationCodeData | null> => {
+    const raw = await getDel(codeKey(code));
+    if (!raw) return null;
+    return JSON.parse(raw) as AuthorizationCodeData;
+};
+
+export const storeAccessToken = async (
+    accessToken: string,
+    data: AccessTokenData,
+    ttl = ACCESS_TOKEN_TTL_SECONDS
+): Promise<void> => {
+    const result = await cache.set(accessKey(accessToken), JSON.stringify(data), ttl);
+    if (result !== 'OK') throw new Error('Failed to persist access token');
+};
+
+export const getAccessToken = async (accessToken: string): Promise<AccessTokenData | null> => {
+    const raw = await cache.get(accessKey(accessToken));
+    if (!raw) return null;
+    return JSON.parse(raw) as AccessTokenData;
+};

package/src/helpers/oidc.helpers.ts

@@ -0,0 +1,354 @@
+/**
+ * Minimal OIDC provider primitives for lca-api (AD-2 of the Keycloak
+ * auth-provider migration).
+ *
+ * lca-api exposes a minimal OpenID Connect provider that Keycloak trusts as an
+ * upstream Identity Provider (alias `lca-api`). This module owns the signing
+ * key material, the discovery / JWKS documents, and the mint / verify
+ * primitives for the `id_token` returned from the `/oidc/token` endpoint.
+ *
+ * Design notes (per the design of record):
+ *  - The signing key is **separate from `SEED`** and rotated independently.
+ *    Deployed Lambdas fetch a JSON RSA private JWK using `OIDC_SIGNING_KEY_SECRET_ID`.
+ *    Local/Docker/CI can still set `OIDC_SIGNING_KEY_JWK`. When unset in production the provider fails closed
+ *    (503) — it never falls back to a forgeable key. In dev/CI an ephemeral
+ *    RSA keypair is generated once per process (random, never deterministic,
+ *    never a function of `SEED`) so local Keycloak can round-trip.
+ *  - RS256 is used because Keycloak's OIDC identity-provider brokering expects
+ *    RSA signing keys by default.
+ *  - Nothing here touches Mongo; it is pure crypto + config so it can be
+ *    unit-tested in isolation (see `test/oidc.spec.ts`).
+ */
+
+import crypto from 'node:crypto';
+import { GetSecretValueCommand, SecretsManagerClient } from '@aws-sdk/client-secrets-manager';
+
+import { environment } from '@config/oidcEnvironment';
+import { TRPCError } from '@trpc/server';
+import { SignJWT, calculateJwkThumbprint, exportJWK, importJWK } from 'jose';
+import type { CryptoKey, JWK, JWTPayload } from 'jose';
+
+/** The signing algorithm for self-issued OIDC tokens (Keycloak expects RSA). */
+export const OIDC_SIGNING_ALG = 'RS256' as const;
+
+/** Default lifetime (seconds) of a minted ID token. */
+export const DEFAULT_ID_TOKEN_TTL_SECONDS = 300;
+
+/** Default confidential relying-party client Keycloak brokers through. */
+export const DEFAULT_OIDC_CLIENT_ID = 'keycloak-broker';
+
+/** Claims carried by a self-issued OIDC ID token. */
+export interface OidcIdTokenClaims extends JWTPayload {
+    sub: string;
+    iss: string;
+    aud: string | string[];
+    email?: string;
+    email_verified?: boolean;
+    phone_number?: string;
+    phone_number_verified?: boolean;
+    name?: string;
+    picture?: string;
+}
+
+interface OidcSigningKey {
+    privateKey: CryptoKey;
+    publicKey: CryptoKey;
+    publicJwk: JWK;
+    kid: string;
+}
+
+let cachedKey: Promise<OidcSigningKey> | undefined;
+let cachedKeyMaterial: string | undefined;
+let ephemeralDevJwk: JWK | undefined;
+
+/**
+ * True when the service is running as a real deployment. `serverless.yml` does
+ * not set `NODE_ENV`, but it always sets `LAMBDA_STAGE`, so either signal counts;
+ * an ephemeral per-container key would otherwise be minted on every cold start.
+ */
+const isProduction = (): boolean =>
+    (environment.NODE_ENV === 'production' || Boolean(environment.LAMBDA_STAGE)) &&
+    !environment.IS_OFFLINE &&
+    !environment.IS_E2E_TEST;
+
+/** Parse both configured sources without exposing key material in errors. */
+const parseSigningJwk = (configured: string): JWK => {
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(configured);
+    } catch {
+        throw new TRPCError({
+            code: 'INTERNAL_SERVER_ERROR',
+            message: 'OIDC signing key must be a JSON RSA private JWK',
+        });
+    }
+    const jwk = parsed as JWK;
+    if (
+        !jwk ||
+        jwk.kty !== 'RSA' ||
+        typeof jwk.d !== 'string' ||
+        !jwk.d ||
+        typeof jwk.kid !== 'string' ||
+        !jwk.kid ||
+        jwk.alg !== 'RS256'
+    ) {
+        throw new TRPCError({
+            code: 'INTERNAL_SERVER_ERROR',
+            message: 'OIDC signing key must be an RSA private JWK with d, kid and alg=RS256',
+        });
+    }
+    return jwk;
+};
+
+/** Prefer the local override, then Secrets Manager; deployed instances fail closed. */
+const resolveSigningJwk = async (configured?: string, secretId?: string): Promise<JWK> => {
+    if (configured) return parseSigningJwk(configured);
+    if (secretId) {
+        let secretString: string | undefined;
+        try {
+            const client = new SecretsManagerClient({});
+            const result = await client.send(new GetSecretValueCommand({ SecretId: secretId }));
+            secretString = result.SecretString;
+        } catch {
+            throw new TRPCError({
+                code: 'INTERNAL_SERVER_ERROR',
+                message: 'OIDC signing key could not be fetched',
+            });
+        }
+        if (!secretString) {
+            throw new TRPCError({
+                code: 'INTERNAL_SERVER_ERROR',
+                message: 'OIDC signing key secret has no SecretString value',
+            });
+        }
+        return parseSigningJwk(secretString);
+    }
+
+    if (isProduction()) {
+        throw new TRPCError({
+            code: 'INTERNAL_SERVER_ERROR',
+            message: 'OIDC signing key is not configured',
+        });
+    }
+
+    if (!ephemeralDevJwk) {
+        const { privateKey } = crypto.generateKeyPairSync('rsa', { modulusLength: 2048 });
+        ephemeralDevJwk = privateKey.export({ format: 'jwk' }) as JWK;
+        process.emitWarning('OIDC is using an ephemeral development signing key.');
+    }
+    return ephemeralDevJwk;
+};
+
+/**
+ * Resolve (and memoize) the OIDC signing key.
+ *
+ * Cache the entire in-flight load by configuration; failures can be retried.
+ * Changing the local JWK or secret id transparently loads a fresh key.
+ */
+export const getOidcSigningKey = async (): Promise<OidcSigningKey> => {
+    const configured = environment.OIDC_SIGNING_KEY_JWK?.trim();
+    const secretId = environment.OIDC_SIGNING_KEY_SECRET_ID?.trim();
+    const material = configured
+        ? `configured:${configured}`
+        : secretId
+          ? `secret:${secretId}`
+          : isProduction()
+            ? 'unconfigured-production'
+            : 'ephemeral-dev';
+    if (cachedKey && cachedKeyMaterial === material) return cachedKey;
+
+    const pending = (async (): Promise<OidcSigningKey> => {
+        const jwk = await resolveSigningJwk(configured, secretId);
+        try {
+            const privateKey = (await importJWK(jwk, OIDC_SIGNING_ALG)) as CryptoKey;
+            const publicComponents: JWK = {
+                kty: 'RSA',
+                n: jwk.n,
+                e: jwk.e,
+            };
+            const publicKey = (await importJWK(publicComponents, OIDC_SIGNING_ALG)) as CryptoKey;
+
+            const publicJwk = await exportJWK(publicKey);
+            const kid = jwk.kid ?? (await calculateJwkThumbprint(publicJwk));
+
+            publicJwk.kid = kid;
+            publicJwk.alg = jwk.alg ?? OIDC_SIGNING_ALG;
+            publicJwk.use = 'sig';
+
+            return { privateKey, publicKey, publicJwk, kid };
+        } catch {
+            throw new TRPCError({
+                code: 'INTERNAL_SERVER_ERROR',
+                message: 'OIDC signing key could not be imported',
+            });
+        }
+    })();
+    cachedKey = pending;
+    cachedKeyMaterial = material;
+
+    try {
+        return await pending;
+    } catch (error) {
+        if (cachedKey === pending) resetOidcSigningKeyForTests();
+        throw error;
+    }
+};
+
+/** Clear the memoized signing key. Intended for isolated tests only. */
+export const resetOidcSigningKeyForTests = (): void => {
+    cachedKey = undefined;
+    cachedKeyMaterial = undefined;
+};
+
+/**
+ * The configured issuer identifier for this provider. Required — there is no
+ * default, so a misconfigured production deployment fails closed rather than
+ * minting tokens under a wrong issuer.
+ */
+export const getOidcIssuer = (): string => {
+    const issuer = environment.OIDC_ISSUER;
+    if (!issuer) {
+        throw new TRPCError({
+            code: 'INTERNAL_SERVER_ERROR',
+            message: 'OIDC issuer is not configured',
+        });
+    }
+    return issuer;
+};
+
+/**
+ * The confidential relying-party client Keycloak uses at the token endpoint.
+ * `id_token`s are minted with this client id as their audience so a token can
+ * only be consumed by the intended relying party.
+ */
+export const getOidcClientId = (): string => environment.OIDC_CLIENT_ID || DEFAULT_OIDC_CLIENT_ID;
+
+const splitCsv = (value: string | undefined): string[] =>
+    (value ?? '')
+        .split(',')
+        .map(entry => entry.trim())
+        .filter(Boolean);
+
+/**
+ * The exact redirect URIs the authorization endpoint will honor. `OIDC_REDIRECT_URIS`
+ * overrides; otherwise each `KEYCLOAK_ISSUERS` entry resolves to its single fixed
+ * broker callback `${issuer}/broker/lca-api/endpoint`. Prefixes are never accepted.
+ */
+export const getOidcRedirectUris = (): string[] => {
+    const explicit = splitCsv(environment.OIDC_REDIRECT_URIS);
+    if (explicit.length > 0) return explicit;
+    return splitCsv(environment.KEYCLOAK_ISSUERS).map(
+        issuer => `${issuer.replace(/\/+$/, '')}/broker/lca-api/endpoint`
+    );
+};
+
+/**
+ * Validate the confidential client's credentials at the token endpoint using a
+ * timing-safe comparison. In production `OIDC_CLIENT_SECRET` MUST be set; when
+ * it is unset (dev/CI only) the token endpoint refuses client authentication.
+ */
+export const verifyOidcClientCredentials = (clientId: string, clientSecret: string): boolean => {
+    const expectedSecret = environment.OIDC_CLIENT_SECRET;
+    if (!expectedSecret) return false;
+    if (clientId !== getOidcClientId()) return false;
+
+    const provided = Buffer.from(clientSecret);
+    const expected = Buffer.from(expectedSecret);
+    if (provided.length !== expected.length) return false;
+    return crypto.timingSafeEqual(provided, expected);
+};
+
+/**
+ * Require exact string equality; an empty allowlist rejects every redirect.
+ */
+export const isAllowedRedirectUri = (redirectUri: string): boolean => {
+    let candidate: URL;
+    try {
+        candidate = new URL(redirectUri);
+    } catch {
+        return false;
+    }
+    if (candidate.protocol !== 'https:' && candidate.protocol !== 'http:') return false;
+
+    return getOidcRedirectUris().includes(redirectUri);
+};
+
+/** The public JWKS document (single active signing key). */
+export const getOidcJwks = async (): Promise<{ keys: JWK[] }> => {
+    const { publicJwk } = await getOidcSigningKey();
+    return { keys: [publicJwk] };
+};
+
+/** The OIDC discovery document served at `/.well-known/openid-configuration`. */
+export const getOidcDiscoveryDocument = (): Record<string, unknown> => {
+    const issuer = getOidcIssuer();
+    return {
+        issuer,
+        authorization_endpoint: `${issuer}/oidc/authorize`,
+        token_endpoint: `${issuer}/oidc/token`,
+        jwks_uri: `${issuer}/oidc/jwks`,
+        userinfo_endpoint: `${issuer}/oidc/userinfo`,
+        response_types_supported: ['code'],
+        subject_types_supported: ['public'],
+        id_token_signing_alg_values_supported: [OIDC_SIGNING_ALG],
+        scopes_supported: ['openid', 'email', 'phone', 'profile'],
+        token_endpoint_auth_methods_supported: ['client_secret_post', 'client_secret_basic'],
+        grant_types_supported: ['authorization_code'],
+        claims_supported: [
+            'sub',
+            'iss',
+            'aud',
+            'exp',
+            'iat',
+            'email',
+            'email_verified',
+            'phone_number',
+            'phone_number_verified',
+            'name',
+            'picture',
+        ],
+    };
+};
+
+/** Mint a signed OIDC ID token whose audience is the confidential client. */
+export const mintIdToken = async (params: {
+    subject: string;
+    nonce?: string;
+    ttlSeconds?: number;
+    email?: string;
+    emailVerified?: boolean;
+    phoneNumber?: string;
+    phoneNumberVerified?: boolean;
+    name?: string;
+    picture?: string;
+}): Promise<{ token: string; expiresAt: number }> => {
+    const { privateKey, kid } = await getOidcSigningKey();
+    const issuer = getOidcIssuer();
+    const audience = getOidcClientId();
+    const now = Math.floor(Date.now() / 1000);
+    const ttl = params.ttlSeconds ?? DEFAULT_ID_TOKEN_TTL_SECONDS;
+    const expiresAt = now + ttl;
+
+    const claims: OidcIdTokenClaims = {
+        sub: params.subject,
+        iss: issuer,
+        aud: audience,
+    };
+    if (params.nonce !== undefined) claims.nonce = params.nonce;
+    if (params.email !== undefined) claims.email = params.email;
+    if (params.emailVerified !== undefined) claims.email_verified = params.emailVerified;
+    if (params.phoneNumber !== undefined) claims.phone_number = params.phoneNumber;
+    if (params.phoneNumberVerified !== undefined) {
+        claims.phone_number_verified = params.phoneNumberVerified;
+    }
+    if (params.name !== undefined) claims.name = params.name;
+    if (params.picture !== undefined) claims.picture = params.picture;
+
+    const token = await new SignJWT(claims)
+        .setProtectedHeader({ alg: OIDC_SIGNING_ALG, kid, typ: 'JWT' })
+        .setIssuedAt(now)
+        .setExpirationTime(expiresAt)
+        .sign(privateKey);
+
+    return { token, expiresAt };
+};