accounts/dist/server/internal/handlers/oidcProvider.d.ts

Tempo Accounts SDK

import * as z from 'zod/mini';
import { type Handler, from } from '../../Handler.js';
/** Zod schemas for the OIDC provider's request and response payloads. */
export declare namespace schema {
    /** Schemas for `POST {path}/token`. */
    namespace token {
        /** Request body schema. */
        const parameters: z.ZodMiniObject<{
            audience: z.ZodMiniString<string>;
            nonce: z.ZodMiniOptional<z.ZodMiniString<string>>;
            subject: z.ZodMiniOptional<z.ZodMiniString<string>>;
        }, z.core.$strip>;
        /** Response body schema. */
        const returns: z.ZodMiniObject<{
            idToken: z.ZodMiniString<string>;
        }, z.core.$strip>;
    }
}
/**
 * OpenID Connect provider (issuer) request handler. Mounts three routes
 * under `path`:
 *
 * - `POST {path}/token` → mints + signs an EdDSA id_token, returns `{ idToken }`
 * - `GET {path}/.well-known/openid-configuration` → OIDC discovery document
 * - `GET {path}/.well-known/jwks.json` → public signing keys (JWKS)
 *
 * The handler owns the OIDC protocol mechanics (claim set, EdDSA signing,
 * discovery + JWKS shape); a deployment supplies its key material and the
 * claim source via callbacks, so nothing here is deployment-specific:
 *
 * - `authenticate(request)` resolves the authenticated subject (e.g. mapping
 *   a session cookie to an account address). When omitted, the request body's
 *   `subject` is trusted instead — only safe behind an authenticating gateway.
 * - `getClaims({ subject, audience, nonce, request })` returns the claim set
 *   embedded into the token (e.g. `{ email, email_verified: true }`). Throwing
 *   rejects issuance (e.g. no verified email) with `400`.
 *
 * Tokens carry `iss`, `aud`, `sub`, `iat`, `exp`, an optional `nonce`, and any
 * claims returned by `getClaims`. They are signed EdDSA (Ed25519) with the
 * provided `signingKey`; the public counterpart is served at the JWKS route so
 * relying parties can verify them.
 */
export declare function oidcProvider(options: oidcProvider.Options): oidcProvider.ReturnType;
export declare namespace oidcProvider {
    /** Return type of `oidcProvider()` — a `Handler`. */
    type ReturnType = Handler;
    /**
     * Resolves the authenticated subject for a token request — e.g. mapping a
     * session cookie to an account address. Throwing rejects issuance with
     * `401`. When omitted, the request body's `subject` is used instead.
     */
    type authenticate = (request: Request) => string | Promise<string>;
    /**
     * Returns the claim set embedded into the minted token. The deployment owns
     * the verification policy (e.g. only return `email` when verified, and set
     * `email_verified: true`). Throwing rejects issuance with `400`.
     */
    type getClaims = (params: {
        /** Audience the token is minted for. */
        audience: string;
        /** OIDC `nonce`, when supplied by the caller. */
        nonce: string | undefined;
        /** Underlying request — useful for headers, IP, etc. */
        request: Request;
        /** Resolved subject the token is minted for. */
        subject: string;
    }) => Record<string, unknown> | Promise<Record<string, unknown>>;
    type Options = from.Options & {
        /**
         * Resolves the authenticated subject from the request (e.g. session
         * cookie → account address). When omitted, the request body's `subject`
         * is trusted — only safe behind an authenticating gateway.
         */
        authenticate?: authenticate | undefined;
        /**
         * Claim names advertised in the discovery document's `claims_supported`.
         * Append the deployment's own claims (e.g. `email`, `email_verified`) to
         * the protocol defaults.
         * @default ["iss", "aud", "sub", "iat", "exp", "nonce"]
         */
        claimsSupported?: readonly string[] | undefined;
        /** Returns the claim set embedded into the minted token. */
        getClaims: getClaims;
        /**
         * Issuer identifier — set as the token `iss` and the discovery `issuer`.
         * Must be an absolute URL (e.g. `'https://wallet.tempo.xyz'`). OIDC serves
         * discovery at `{issuer}/.well-known/openid-configuration`, so `issuer` must
         * equal the mount's public URL — i.e. `{origin}{path}` when mounted under a
         * `path` (e.g. `'https://wallet.tempo.xyz/api/oidc'` for `path: '/api/oidc'`).
         */
        issuer: string;
        /**
         * Absolute URL advertised as the discovery `jwks_uri`. Defaults to the
         * mounted JWKS route under `issuer`. Set this when JWKS is served
         * elsewhere (e.g. an existing `/.well-known/jwks.json`).
         */
        jwksUri?: string | undefined;
        /** Key id set on the JWKS entry. @default "oidc-1" */
        kid?: string | undefined;
        /** Path prefix for the provider endpoints. @default "/" */
        path?: string | undefined;
        /** Public signing key (JWK string), served at the JWKS route. */
        publicKey: string;
        /** Private signing key (JWK string), used to sign tokens (EdDSA). */
        signingKey: string;
        /** Token lifetime in seconds. @default 300 */
        ttl?: number | undefined;
    };
}
//# sourceMappingURL=oidcProvider.d.ts.map