skills/plugins/document-navigator/docs/api-stack/api/api-auth-rolled/README.md

@suaveplan/api-auth-rolled — rolled-our-own auth provider. Implements both auth.session and auth.provider capability contracts. Session tokens are RS256-signed JWTs (via @suaveplan/crypto-rsa + @suaveplan/jws) with rotating kid for non-disruptive key rotation. Passwords are hashed via Argon2id (@suaveplan/crypto-hash), gated by @suaveplan/password-strength and @suaveplan/hibp at registration. Provider mounts the canonical 9-route PROVIDER_ROUTE_SURFACE under a configurable path prefix. DB access via injected @suaveplan/types DatabaseLike — shares the host's main connection per design §2.3. Projects DB rows onto the @suaveplan/api-types Principal shape. Contributes cookie + bearer OpenAPI security schemes.

Stage-8.12 rolled session-token resolver for @suaveplan/api. Issues RS256-signed JWTs with rotating kid slots, verifies tokens through the rotator's active + retired-non-revoked key set, projects DB rows onto the @suaveplan/api-types Principal contract, and contributes cookie

• bearer OpenAPI security schemes.

This milestone ships the session-resolver half of the eventual dual contract (auth.session). The matching AuthProviderAdapter (account-lifecycle routes, password gating, MFA, OAuth) is deferred to a successor change api-auth-rolled-provider.

Documentation tree

• composition — Top-level factory createRolledAuthAdapter that wires the four sub-modules (token-rotator, session, `principal-pro…
  • composition — Top-level factory createRolledAuthAdapter that wires the four sub-modules (token-rotator, session, `principal-pro…
• error-codes — Stable error-code registry for @suaveplan/api-auth-rolled. Every code is namespaced under AUTH_ROLLED.* so cross-pa…
  • error-codes — Stable error-code registry for @suaveplan/api-auth-rolled. Every code is namespaced under AUTH_ROLLED.* so cross-pa…
• options — Defines the configuration shape accepted by createRolledAuthAdapter and the Zod schema that validates it. Operators w…
  • options — Defines the configuration shape accepted by createRolledAuthAdapter and the Zod schema that validates it. Operators w…
• principal-projection — Projects the package's internal UserRow storage shape onto the abstract Principal contract published by `@suaveplan…
  • principal-projection — Projects the package's internal UserRow storage shape onto the abstract Principal contract published by `@suaveplan…
• security-schemes — Contributes OpenAPI 3.1 securitySchemes entries describing both transports the rolled session resolver accepts — `Aut…
  • security-schemes — Contributes OpenAPI 3.1 securitySchemes entries describing both transports the rolled session resolver accepts — `Aut…
• session — The rolling-JWT session resolver — the keystone of the rolled auth adapter. Builds a SessionResolver (per `@suaveplan…
  • session — The rolling-JWT session resolver — the keystone of the rolled auth adapter. Builds a SessionResolver (per `@suaveplan…
• token-rotator — Owns the rotating-keyset state for the rolled session-token resolver. The active key signs new JWTs; retired-but-non-re…
  • token-rotator — Owns the rotating-keyset state for the rolled session-token resolver. The active key signs new JWTs; retired-but-non-re…

Why

This package gives operators a session-auth path that owns zero third-party runtime dependencies.

Install

bun add @suaveplan/api-auth-rolled

Modules

Module	What it owns
composition/	createRolledAuthAdapter — the public factory.
error-codes/	The 4-code AUTH_ROLLED.* registry.
options/	Zod-validated options + named defaults.
principal-projection/	UserRow → Principal projection.
security-schemes/	Cookie + bearer OpenAPI contributions.
session/	RS256 sign/verify, cookie+bearer extraction, Set-Cookie.
token-rotator/	Rotating-key state machine.

Quick start

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

const adapter = createRolledAuthAdapter({
    store: hostStore,
    keys: [{ kid: "k1", privateJwk, publicJwk, active: true }],
    issuer: "https://api.example.com",
    audience: "example-front",
});

host.registerAuthSession(adapter);

Rotation cron:

setInterval(async () => {
    if (!adapter.rotator.decide().shouldRotate) return;
    adapter.rotator.setKeys(await kms.nextKeyset());
}, 60_000);

License

MIT