# @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`.

<!-- begin:auto-docs -->
## Documentation tree

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

## Why

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

## Install

```bash
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

```ts
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:

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

## License

MIT