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

Tempo Accounts SDK

import { type Handler, from } from '../../Handler.js';
import * as Kv from '../../Kv.js';
import * as Session from './session.js';
/**
 * Session payload persisted in the session store and surfaced via
 * `getSession`. Mirrors the shape of the WebAuthn login response so
 * downstream handlers can identify the authenticated credential without
 * an extra round-trip.
 */
export type SessionPayload = {
    /** Credential ID returned by the authenticator. */
    credentialId: string;
    /** Credential public key (hex). */
    publicKey: string;
    /** Optional `userHandle` returned by the authenticator. */
    userId?: string | undefined;
    /** Unix timestamp (seconds) when the session was issued. */
    issuedAt: number;
    /** Unix timestamp (seconds) when the session expires. */
    expiresAt: number;
};
/**
 * Instantiates a WebAuthn ceremony handler that manages registration and
 * authentication flows server-side.
 *
 * Mounts five POST endpoints under `path`:
 * - `POST {path}/register/options` — generate credential creation options
 * - `POST {path}/register` — verify registration and store credential
 * - `POST {path}/login/options` — generate credential request options
 * - `POST {path}/login` — verify authentication and issue a session
 *   (cookie via `Set-Cookie`, or `{ token }` body when `cookie: false`
 *   or the request opts in via `returnToken: true`)
 * - `POST {path}/logout` — revoke the session and clear the cookie
 *
 * The returned handler also exposes `getSession(req)` for resolving the
 * current session from a follow-up request's cookie or `Authorization:
 * Bearer` header.
 *
 * @example
 * ```ts
 * import { Handler, Kv } from 'accounts/server'
 *
 * const handler = Handler.webAuthn({
 *   kv: Kv.memory(),
 *   origin: 'https://example.com',
 *   rpId: 'example.com',
 * })
 *
 * export default handler
 * ```
 *
 * @param options - Options.
 * @returns Request handler.
 */
export declare function webAuthn(options: webAuthn.Options): webAuthn.ReturnType;
export declare namespace webAuthn {
    /** Return type of `webAuthn()` — a `Handler` extended with `getSession`. */
    type ReturnType = Handler & {
        getSession: getSession;
    };
    /** Resolves the current session from a request's cookie or bearer token. */
    type getSession = (req: Session.SessionRequest) => Promise<SessionPayload | undefined>;
    type Options = from.Options & {
        /**
         * Whether to issue a session cookie on successful login. When
         * `false`, the login response always contains `{ token }` in the
         * body, no `Set-Cookie` header is sent, logout does not clear a
         * cookie, and `getSession` ignores any incoming cookie — only
         * `Authorization: Bearer <token>` is honored. Use this when the SDK
         * lives in a non-browser context or the host app already manages
         * its own auth cookies.
         * @default true
         */
        cookie?: boolean | undefined;
        /** Cookie name for the session token. @default "accounts_webauthn" */
        cookieName?: string | undefined;
        /** Key-value store for challenges, credentials, and sessions. */
        kv: Kv.Kv;
        /** Called after a successful registration. The returned response is merged onto the default JSON response. */
        onRegister?: (parameters: {
            credentialId: string;
            /** The name provided during `/register/options` (e.g. user email). */
            name: string;
            publicKey: string;
            request: Request;
            /** The `userId` provided during `/register/options`, if any. */
            userId?: string | undefined;
        }) => Response | Promise<Response> | void | Promise<void>;
        /**
         * Called after a successful authentication, before the session
         * token is issued. Returning a `Response` merges its JSON body and
         * status onto the default login response (legacy contract).
         * Throwing rejects the request with `401` — the thrown error's
         * `message` is surfaced as the response `error` field — and no
         * session is issued.
         */
        onAuthenticate?: (parameters: {
            credentialId: string;
            publicKey: string;
            userId?: string | undefined;
            request: Request;
        }) => Response | Promise<Response> | void | Promise<void>;
        /** Expected origin(s) (e.g. `"https://example.com"` or `["https://a.com", "https://b.com"]`). */
        origin: string | readonly string[];
        /** Path prefix for the WebAuthn endpoints (e.g. `"/webauthn"`). @default "" */
        path?: string | undefined;
        /** Relying Party ID (e.g. `"example.com"`). */
        rpId: string;
        /**
         * Whether to issue a session on successful login. When `false`,
         * login acts as a stateless WebAuthn verification — no token is
         * generated, no entry is written to the kv, and no cookie is sent.
         * The login response still carries `{ credentialId, publicKey,
         * userId? }`. `getSession` always returns `undefined` and `/logout`
         * is a no-op (still returns `204`). Use this when the host
         * application mints its own session token (e.g. a JWT inside
         * `onAuthenticate`).
         * @default true
         */
        session?: boolean | undefined;
        /** TTLs in seconds. */
        ttl?: {
            /** Challenge TTL. @default 300 (5m) */
            challenge?: number | undefined;
            /** Session TTL. @default 86400 (24h) */
            session?: number | undefined;
        } | undefined;
    };
}
//# sourceMappingURL=webAuthn.d.ts.map