`options`

(no submodules)

Purpose

Defines the configuration shape accepted by createRolledAuthAdapter and the Zod schema that validates it. Operators wire this from host.json or build it programmatically; everything the rest of the package needs flows from a single validated RolledAuthOptions value, which keeps invariants (active-key count, prefix shape, TTL positivity) in one place.

The schema deliberately validates injected functions and the store adapter as unknown and then refines them later — Zod cannot verify function-argument shapes statically, and TypeScript already does that work at the call boundary.

Features

Zod schema RolledAuthOptionsSchema covering every operator-facing knob.
A superRefine cross-field invariant that exactly one key is both active: true and non-revoked — keeps sign-time semantics ambiguity-free.
Stable named defaults (DEFAULT_COOKIE_NAME, DEFAULT_ROUTE_PREFIX, TTLs, rotation period, minimum strength score) so consumers can reference the defaults without re-reading the source.
Two distinct error codes for failures: DATABASE_REQUIRED when store is missing (operator hooked up nothing), SIGNING_KEY_NOT_CONFIGURED for every other schema failure (Zod issues attached as context).

Usage: Basic

import { parseRolledAuthOptions } from "@suaveplan/api-auth-rolled";

const opts = parseRolledAuthOptions({
    store: myStore,
    keys: [{ kid: "k1", privateJwk, publicJwk, active: true }],
    issuer: "https://api.example.com",
    audience: "example-frontend",
});

Usage: Advanced

import {
    DEFAULT_ROTATION_PERIOD_MS,
    parseRolledAuthOptions,
} from "@suaveplan/api-auth-rolled";

const opts = parseRolledAuthOptions({
    store,
    keys,
    issuer: "https://api.example.com",
    audience: "example-frontend",
    routePrefix: "/api/auth",
    cookieName: "acme.session",
    cookieSameSite: "strict",
    cookieSecure: true,
    sessionTtlSec: 1800,
    refreshTtlSec: 7 * 24 * 60 * 60,
    rotationPeriodMs: DEFAULT_ROTATION_PERIOD_MS / 2,
    minPasswordStrength: 4,
    strength: { async score(pw) { return 4; } },
    breach: { async isBreached() { return false; } },
});

API Reference

parseRolledAuthOptions(raw): RolledAuthOptions — throws AuthRolledError on bad input.
RolledAuthOptionsSchema — the Zod schema, re-exported for advanced consumers that want to layer their own refinements.
DEFAULT_* constants — every operator-facing default exposed as a named export.

Implementation Notes

The schema is strictObject so unknown keys produce a Zod error rather than silently passing through. The keys[] active invariant is enforced in superRefine rather than as a transform so the invariant message appears in the validation issue list instead of as a thrown exception mid-parse. Cross-field invariants that cross the option/store boundary (e.g. "every kid actually resolves to a JWK") are checked later inside the session/token-rotator modules so the options layer remains synchronous and pure.

3.1 KiB Raw Blame History

options