84 lines
5.0 KiB
Markdown
84 lines
5.0 KiB
Markdown
# @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
|
|
|