@astram/guard 0.1.1 → 0.3.0

package/dist/auth/tokens.js

@@ -0,0 +1,254 @@
+"use strict";
+/**
+ * Phase 0b Auth-surface **DI provider tokens** — the shared injection seams the
+ * three parallel teams bind/consume so they never collide (ADR-0023: composition
+ * is the framework's job; these are the framework's internal wiring points).
+ *
+ * ⛔ FROZEN by this prelude. Team B (composition) PROVIDES these; Team A
+ * (credential store) provides the resolver behind {@link SHIELD_CREDENTIAL_RESOLVER};
+ * Team C (`/auth` controllers) CONSUMES {@link SHIELD_AUTHENTICATOR} +
+ * {@link SHIELD_SESSION_AUTHORITY}. Do not rename these Symbols — a rename is a
+ * breaking change to every team's wiring.
+ *
+ * NOTE — some session/hasher adapters already ship their OWN tokens in
+ * `@astram/guard` (`SHIELD_PASSWORD_HASHER`, `SHIELD_SESSION_RECORD_STORE`,
+ * `SHIELD_HOT_SESSION_STORE`, `SHIELD_TOKEN_GENERATOR`, `SHIELD_REFRESH_HASHER`,
+ * `SHIELD_CLOCK`). Those stay the canonical tokens for those adapters. This file
+ * adds ONLY the NEW seams Phase 0b introduces: the live connections
+ * ({@link SHIELD_DB_POOL} / {@link SHIELD_REDIS}), the credential resolver, and the
+ * two COMPOSED engines ({@link SHIELD_AUTHENTICATOR} / {@link SHIELD_SESSION_AUTHORITY}).
+ * {@link SHIELD_PASSWORD_HASHER} is re-exported from the argon2 adapter for
+ * convenience so a team can import every auth-relevant token from one module.
+ *
+ * ADR-0003: no framework/DB/crypto imports here — just Symbols (+ one re-export).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHIELD_RESET_LIMITER = exports.SHIELD_FORGOT_HINT_LIMITER = exports.SHIELD_FORGOT_LIMITER = exports.SHIELD_RECOVERY_LIMITER = exports.SHIELD_LOGIN_LIMITER = exports.SHIELD_SESSION_FACTS_PROJECTOR = exports.SHIELD_ROOT_IDS = exports.SHIELD_TOTP_VERIFIER_OVERRIDE = exports.SHIELD_TOTP_VERIFIER = exports.SHIELD_RESET_LINK_BASE_URL = exports.SHIELD_SESSION_SWEEPER = exports.SHIELD_MFA_DEVICE_STORE = exports.SHIELD_AUDIT_SINK = exports.SHIELD_PROFILE_WRITER = exports.SHIELD_RECOVERY_CODE_STORE = exports.SHIELD_EMAIL_SENDER = exports.SHIELD_RESET_TOKEN_STORE = exports.SHIELD_CREDENTIAL_WRITER = exports.SHIELD_SESSION_AUTHORITY = exports.SHIELD_AUTHENTICATOR = exports.SHIELD_PROFILE_RESOLVER = exports.SHIELD_CREDENTIAL_RESOLVER = exports.SHIELD_REDIS = exports.SHIELD_DB_POOL = exports.SHIELD_PASSWORD_HASHER = void 0;
+var argon2id_password_hasher_js_1 = require("../authentication/argon2id-password-hasher.js");
+Object.defineProperty(exports, "SHIELD_PASSWORD_HASHER", { enumerable: true, get: function () { return argon2id_password_hasher_js_1.SHIELD_PASSWORD_HASHER; } });
+/**
+ * The ONE live `mariadb` `Pool` (the `shield_core` account — DML on
+ * `shield_identity`, ADR-0013/0014). **Provided by Team B** (the persistence
+ * factory — the single place a live DB connection is created). **Consumed by**
+ * the {@link SHIELD_CREDENTIAL_RESOLVER} factory and the
+ * {@link SHIELD_SESSION_RECORD_STORE} factory. Disposed on app shutdown.
+ */
+exports.SHIELD_DB_POOL = Symbol('SHIELD_DB_POOL');
+/**
+ * The ONE live `ioredis` client (the hot session tier, ADR-0013). **Provided by
+ * Team B** (the persistence factory). **Consumed by** the
+ * {@link SHIELD_HOT_SESSION_STORE} factory. Disposed on app shutdown.
+ */
+exports.SHIELD_REDIS = Symbol('SHIELD_REDIS');
+/**
+ * The `CredentialResolver` (core port) that resolves an identity hint →
+ * `ResolvedCredential | null`. **Provided by Team A** (the
+ * `MariaDbCredentialResolver`, injected with {@link SHIELD_DB_POOL}). **Consumed
+ * by** the {@link SHIELD_AUTHENTICATOR} factory (Team B) as
+ * `createAuthenticator({ resolver })`.
+ */
+exports.SHIELD_CREDENTIAL_RESOLVER = Symbol('SHIELD_CREDENTIAL_RESOLVER');
+/**
+ * The `ProfileResolver` (guard port, see `../auth/profile-resolver.ts`) that turns
+ * an authenticated `Principal` → the current-user display profile for `GET /auth/me`.
+ * OPTIONAL: supplied by the consumer via `ShieldModule.forRoot({ profileResolver })`
+ * and threaded through `AuthModule.forRoot`. When ABSENT the `/auth/me` route returns
+ * an honest "profile unavailable" (the framework is org-schema-agnostic — see the
+ * port header). Consumed by {@link AuthController}'s `me()` handler.
+ */
+exports.SHIELD_PROFILE_RESOLVER = Symbol('SHIELD_PROFILE_RESOLVER');
+/**
+ * The composed `Authenticator` (core engine) — `createAuthenticator({ hasher,
+ * resolver, identityBroker, factorVerifiers:[totp] })`. **Provided by Team B**
+ * (the AuthModule factory). **Consumed by** Team C's `/auth/login` +
+ * `/auth/mfa` controllers.
+ */
+exports.SHIELD_AUTHENTICATOR = Symbol('SHIELD_AUTHENTICATOR');
+/**
+ * The composed `SessionAuthority` (core engine) — `createSessionAuthority({
+ * recordStore, hotStore, tokenGenerator, refreshHasher, clock, lifetimes })`.
+ * **Provided by Team B** (the AuthModule factory). **Consumed by** Team C's
+ * `/auth/login` (establish), `/auth/refresh` (rotate), `/auth/logout` (revoke),
+ * and `/auth/mfa` (establish after factor).
+ */
+exports.SHIELD_SESSION_AUTHORITY = Symbol('SHIELD_SESSION_AUTHORITY');
+// ---------------------------------------------------------------------------
+// Account & credential surface seams (forgot/reset, change-password, MFA
+// enrollment, profile edit). All OPTIONAL, consumer-plugged through
+// `ShieldModule.forRoot({...})` → `AuthModule.forRoot` (exactly like
+// {@link SHIELD_PROFILE_RESOLVER}). Each binds to the supplied port impl, or to
+// `null` when absent so the `@Optional()` injection in the routes resolves to "no
+// seam" → the route returns 501. See `../auth/ports/*.ts` for each contract.
+// ---------------------------------------------------------------------------
+/**
+ * The `CredentialWriter` (guard port, `../auth/ports/credential-writer.ts`) — the
+ * WRITE side of the credential store (set password hash, read the stored hash by
+ * principal id). Consumed by change-password + reset-password. Absent (`null`) →
+ * those routes return 501. (TOTP secrets no longer live here — the multi-device
+ * MFA model stores them in {@link SHIELD_MFA_DEVICE_STORE}.)
+ */
+exports.SHIELD_CREDENTIAL_WRITER = Symbol('SHIELD_CREDENTIAL_WRITER');
+/**
+ * The `ResetTokenStore` (guard port, `../auth/ports/reset-token-store.ts`) — the
+ * single-use, TTL'd password-reset token store (framework hands it a SHA-256 hash,
+ * never the raw token). Consumed by forgot-password + reset-password.
+ */
+exports.SHIELD_RESET_TOKEN_STORE = Symbol('SHIELD_RESET_TOKEN_STORE');
+/**
+ * The `EmailSender` (guard port, `../auth/ports/email-sender.ts`) — the delivery
+ * seam (SendGrid/SMTP/test capturer). The framework builds the message; the
+ * consumer delivers it. Consumed by forgot-password.
+ */
+exports.SHIELD_EMAIL_SENDER = Symbol('SHIELD_EMAIL_SENDER');
+/**
+ * The `RecoveryCodeStore` (guard port, `../auth/ports/recovery-code-store.ts`) —
+ * persists Argon2-hashed one-time MFA recovery codes. Consumed by MFA enrollment.
+ */
+exports.SHIELD_RECOVERY_CODE_STORE = Symbol('SHIELD_RECOVERY_CODE_STORE');
+/**
+ * The `ProfileWriter` (guard port, `../auth/ports/profile-writer.ts`) — the
+ * self-service profile-edit seam (name/email). Consumed by `PATCH /account/profile`.
+ */
+exports.SHIELD_PROFILE_WRITER = Symbol('SHIELD_PROFILE_WRITER');
+/**
+ * The `AuditSink` (guard port, `../auth/ports/audit-sink.ts`) — the auth-surface audit
+ * seam (spec §6.2). `record(event)` persists a framework-built {@link AuthAuditEvent}
+ * (the FIRST auth audit event: the recovery-code login). OPTIONAL, consumer-plugged
+ * exactly like {@link SHIELD_PROFILE_RESOLVER}: supplied → bound app-wide; omitted →
+ * bound `null`, so the `@Optional()` injection in {@link AuthController} resolves to
+ * "no seam" and the best-effort audit call is a no-op (the login still works,
+ * un-audited). Consumed by the `/auth/mfa` recovery branch (fire-and-forget).
+ */
+exports.SHIELD_AUDIT_SINK = Symbol('SHIELD_AUDIT_SINK');
+/**
+ * The `MfaDeviceStore` (guard port, `../auth/ports/mfa-device-store.ts`) — persists
+ * a principal's N TOTP authenticator DEVICES (multi-device MFA). Consumed
+ * by the `/account/mfa/devices/*` routes (list/begin/confirm/rename/remove) + the
+ * consumer's login resolver (which bundles {@link MfaDeviceStore.listConfirmedSecrets}
+ * for the OR-match). Absent (`null`) → the device routes return 501.
+ */
+exports.SHIELD_MFA_DEVICE_STORE = Symbol('SHIELD_MFA_DEVICE_STORE');
+/**
+ * The `SessionSweeper` (guard port, `../auth/ports/session-sweeper.ts`) — revokes a
+ * principal's sessions after a credential change (all, or all-but-current). The core
+ * has no revoke-all-for-principal, so the consumer implements it. Consumed by
+ * change-password (others) + reset-password (all).
+ */
+exports.SHIELD_SESSION_SWEEPER = Symbol('SHIELD_SESSION_SWEEPER');
+/**
+ * The reset-link base URL (a plain `string` value, NOT a port). The framework
+ * composes the emailed reset link as `${base}?token=<rawToken>` so the
+ * {@link SHIELD_EMAIL_SENDER} seam stays a dumb delivery channel (no URL/token
+ * logic). Bound app-wide by `AuthModule` from the environment
+ * (`RESET_LINK_BASE_URL`, default `http://localhost:5173/reset-password`). Consumed
+ * by `POST /auth/forgot-password`.
+ */
+exports.SHIELD_RESET_LINK_BASE_URL = Symbol('SHIELD_RESET_LINK_BASE_URL');
+/**
+ * The core single-secret `FactorVerifier` for TOTP (`createTotpFactorVerifier({
+ * hmacSha1 })`), PROVIDED by `AuthModule` (which loads the core factory lazily — the
+ * CJS↔ESM invariant, same as {@link SHIELD_AUTHENTICATOR}). It is the SAME base
+ * verifier the login default uses, provided pre-built app-wide so the multi-device
+ * MFA routes (Phase 3) can check a presented code against a SPECIFIC device's secret
+ * without importing `@astram/core` at the controller's top level (that becomes a
+ * runtime `require` on the ESM-only core in the built CJS dist). Distinct from the
+ * login OR-verifier the consumer plugs through {@link SHIELD_TOTP_VERIFIER_OVERRIDE}
+ * (Phase 2): this stays single-secret, for per-device checks.
+ */
+exports.SHIELD_TOTP_VERIFIER = Symbol('SHIELD_TOTP_VERIFIER');
+/**
+ * OPTIONAL consumer override for the LOGIN `totp` {@link FactorVerifier} — the
+ * verifier the composed `Authenticator` uses to satisfy a `RequiredFactor` of
+ * factor `'totp'`. Threaded through `ShieldModule.forRoot({ totpVerifier })` →
+ * `AuthModule.forRoot`, `@Optional()` (bound `null` when absent). When supplied it
+ * REPLACES the framework's default `createTotpFactorVerifier({ hmacSha1 })` in the
+ * authenticator's `factorVerifiers` — the seam multi-device MFA needs so a
+ * consumer can plug an OR-matching verifier (one required-factor whose `secret` is a
+ * bundle of the user's N device secrets; the verifier matches ANY). Default absent →
+ * behavior EXACTLY unchanged (single-secret RFC-6238). Distinct from
+ * {@link SHIELD_TOTP_VERIFIER} (the pre-built single-secret verifier the account MFA
+ * routes use for per-device checks — that one is never overridden).
+ */
+exports.SHIELD_TOTP_VERIFIER_OVERRIDE = Symbol('SHIELD_TOTP_VERIFIER_OVERRIDE');
+/**
+ * OPTIONAL root allowlist — the server-side, trusted set of canonical
+ * principal ids that ARE roots on the framework's Internal identity
+ * source. Threaded through `ShieldModule.forRoot({ rootIds })` →
+ * `AuthModule.forRoot` and passed to `createIdentityBroker({ internalRootIds })`,
+ * `@Optional()` (bound `[]` when absent → nobody is a root, default-deny).
+ *
+ * ROOT SAFETY (core `internal-adapter.ts`): the `isRoot` flag is set
+ * `true` iff the authenticated principal's `id` is in THIS allowlist — it is NEVER read
+ * from a caller-supplied claim. So this is the ONLY way a login mints a root, and
+ * an attacker who can influence claim VALUES cannot flip it (they'd have to be in this
+ * server-side list, which they can't write). Default absent → `[]` → default-deny,
+ * exactly the historical behavior (`createIdentityBroker()` with an empty allowlist).
+ */
+exports.SHIELD_ROOT_IDS = Symbol('SHIELD_ROOT_IDS');
+/**
+ * OPTIONAL {@link import('./ports/session-facts-projector.js').SessionFactsProjector}
+ * — the ADR-0011 eager-projection seam. Threaded through
+ * `ShieldModule.forRoot({ sessionFactsProjector })` → `AuthModule.forRoot`, `@Optional()`
+ * (bound `null` when absent). When PRESENT, the auth controller calls `project(...)` at
+ * login + refresh and caches the returned `CoarseGrants` on the session binding, so gate
+ * 5 serves the principal's coarse grants from the request's `cachedFacts` instead of a DB
+ * reload every request. ABSENT → the controller omits `cachedFacts` → today's exact
+ * behavior (DB reload every request). Purely additive + opt-in. Only consulted under
+ * `auth: true`.
+ */
+exports.SHIELD_SESSION_FACTS_PROJECTOR = Symbol('SHIELD_SESSION_FACTS_PROJECTOR');
+// ---------------------------------------------------------------------------
+// Rate-limit seams (anti-brute-force, spec §5) — ONE `AttemptLimiter` class
+// (Redis-backed), provided as TWO instances with independent thresholds under
+// these tokens. Both are always provided under `auth: true` (they need the live
+// {@link SHIELD_REDIS}); the controller injects each `@Optional()` so an absent
+// limiter degrades to "allow" (never a lock-out from missing wiring).
+// ---------------------------------------------------------------------------
+/**
+ * The password-login {@link AttemptLimiter} (spec §5 / IdP-hardening H1) — keyed
+ * `login:<identityHint>`, default 10 failures / 15-min window. Consumed at the TOP
+ * of `POST /auth/login` (`check` → generic 401 when locked) and on the outcome
+ * (`recordFailure` on a rejected wrong-password; `reset` on `authenticated` OR
+ * `mfa_required` — a correct password that merely needs MFA is NOT a failure).
+ */
+exports.SHIELD_LOGIN_LIMITER = Symbol('SHIELD_LOGIN_LIMITER');
+/**
+ * The recovery-code {@link AttemptLimiter} (spec §5) — keyed `recovery:<principalId>`,
+ * default 5 failures / 15-min window (recovery codes are higher-value than a rotating
+ * 30-s TOTP). Consumed in the `/auth/mfa` recovery branch: `check` BEFORE `consume`
+ * (locked → generic 401 without consulting the store), `recordFailure` on a wrong
+ * code, `reset` on success.
+ */
+exports.SHIELD_RECOVERY_LIMITER = Symbol('SHIELD_RECOVERY_LIMITER');
+/**
+ * The forgot-password IP {@link AttemptLimiter} (feature #141) — keyed
+ * `forgot:ip:<clientIp>`, default 5 per 15-min window. Consumed at the TOP of
+ * `POST /auth/forgot-password`. UNLIKE login, forgot-password is ALWAYS 204 (a 429
+ * would itself be an enumeration/probing signal), so this is a request-rate cap: the
+ * handler counts EVERY forgot request against the IP budget and, once the budget is
+ * exceeded, SILENTLY skips the email-send work while STILL returning 204 (the existing
+ * always-204 anti-enumeration posture is preserved). Fail-open on a Redis blip. The
+ * client IP is read from the TRUSTED `req.ip` (the consumer sets `trust proxy` so
+ * X-Forwarded-For can't be spoofed).
+ */
+exports.SHIELD_FORGOT_LIMITER = Symbol('SHIELD_FORGOT_LIMITER');
+/**
+ * The forgot-password PER-HINT {@link AttemptLimiter} (feature #141) — keyed
+ * `forgot:<identityHint>`, default 3 per 60-min window (generous). Caps how often ANY
+ * caller (across IPs) can trigger a reset email for ONE account, so a single victim
+ * can't be email-bombed from a rotating IP pool. Same request-rate-cap + silent-skip-
+ * still-204 semantics as {@link SHIELD_FORGOT_LIMITER}; consumed alongside it in
+ * `POST /auth/forgot-password`.
+ */
+exports.SHIELD_FORGOT_HINT_LIMITER = Symbol('SHIELD_FORGOT_HINT_LIMITER');
+/**
+ * The reset-password IP {@link AttemptLimiter} (feature #141) — keyed
+ * `reset:ip:<clientIp>`, default 10 per 15-min window. Consumed at the TOP of
+ * `POST /auth/reset-password` (`check` BEFORE token work). Reset is token-gated (a
+ * 256-bit single-use token), so this is DoS/abuse throttling, NOT anti-brute-force —
+ * and it MAY return a GENERIC 429 on lockout (a token-gated endpoint is not
+ * enumeration-sensitive). `recordFailure` on a bad/invalid token (the abuse signal);
+ * `reset` on a successful reset (204). Fail-open on a Redis blip. IP is the trusted
+ * `req.ip`.
+ */
+exports.SHIELD_RESET_LIMITER = Symbol('SHIELD_RESET_LIMITER');

package/dist/auth/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/auth/tokens.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;;AAEH,6FAAuF;AAA9E,qIAAA,sBAAsB,OAAA;AAE/B;;;;;;GAMG;AACU,QAAA,cAAc,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;AAEvD;;;;GAIG;AACU,QAAA,YAAY,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;AAEnD;;;;;;GAMG;AACU,QAAA,0BAA0B,GAAG,MAAM,CAAC,4BAA4B,CAAC,CAAC;AAE/E;;;;;;;GAOG;AACU,QAAA,uBAAuB,GAAG,MAAM,CAAC,yBAAyB,CAAC,CAAC;AAEzE;;;;;GAKG;AACU,QAAA,oBAAoB,GAAG,MAAM,CAAC,sBAAsB,CAAC,CAAC;AAEnE;;;;;;GAMG;AACU,QAAA,wBAAwB,GAAG,MAAM,CAAC,0BAA0B,CAAC,CAAC;AAE3E,8EAA8E;AAC9E,yEAAyE;AACzE,oEAAoE;AACpE,qEAAqE;AACrE,gFAAgF;AAChF,kFAAkF;AAClF,6EAA6E;AAC7E,8EAA8E;AAE9E;;;;;;GAMG;AACU,QAAA,wBAAwB,GAAG,MAAM,CAAC,0BAA0B,CAAC,CAAC;AAE3E;;;;GAIG;AACU,QAAA,wBAAwB,GAAG,MAAM,CAAC,0BAA0B,CAAC,CAAC;AAE3E;;;;GAIG;AACU,QAAA,mBAAmB,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAAC;AAEjE;;;GAGG;AACU,QAAA,0BAA0B,GAAG,MAAM,CAAC,4BAA4B,CAAC,CAAC;AAE/E;;;GAGG;AACU,QAAA,qBAAqB,GAAG,MAAM,CAAC,uBAAuB,CAAC,CAAC;AAErE;;;;;;;;GAQG;AACU,QAAA,iBAAiB,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC;AAE7D;;;;;;GAMG;AACU,QAAA,uBAAuB,GAAG,MAAM,CAAC,yBAAyB,CAAC,CAAC;AAEzE;;;;;GAKG;AACU,QAAA,sBAAsB,GAAG,MAAM,CAAC,wBAAwB,CAAC,CAAC;AAEvE;;;;;;;GAOG;AACU,QAAA,0BAA0B,GAAG,MAAM,CAAC,4BAA4B,CAAC,CAAC;AAE/E;;;;;;;;;;GAUG;AACU,QAAA,oBAAoB,GAAG,MAAM,CAAC,sBAAsB,CAAC,CAAC;AAEnE;;;;;;;;;;;;GAYG;AACU,QAAA,6BAA6B,GAAG,MAAM,CAAC,+BAA+B,CAAC,CAAC;AAErF;;;;;;;;;;;;;GAaG;AACU,QAAA,eAAe,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAEzD;;;;;;;;;;GAUG;AACU,QAAA,8BAA8B,GAAG,MAAM,CAAC,gCAAgC,CAAC,CAAC;AAEvF,8EAA8E;AAC9E,4EAA4E;AAC5E,8EAA8E;AAC9E,gFAAgF;AAChF,gFAAgF;AAChF,sEAAsE;AACtE,8EAA8E;AAE9E;;;;;;GAMG;AACU,QAAA,oBAAoB,GAAG,MAAM,CAAC,sBAAsB,CAAC,CAAC;AAEnE;;;;;;GAMG;AACU,QAAA,uBAAuB,GAAG,MAAM,CAAC,yBAAyB,CAAC,CAAC;AAEzE;;;;;;;;;;GAUG;AACU,QAAA,qBAAqB,GAAG,MAAM,CAAC,uBAAuB,CAAC,CAAC;AAErE;;;;;;;GAOG;AACU,QAAA,0BAA0B,GAAG,MAAM,CAAC,4BAA4B,CAAC,CAAC;AAE/E;;;;;;;;;GASG;AACU,QAAA,oBAAoB,GAAG,MAAM,CAAC,sBAAsB,CAAC,CAAC"}

package/dist/auth/totp-enrollment.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Phase 4 MFA-enrollment — the **pure TOTP-enrollment helpers**: generate a fresh
+ * base32 TOTP secret, compose the `otpauth://` provisioning URI an authenticator app
+ * scans, and mint one-time recovery codes.
+ *
+ * ── WHY THIS LIVES IN GUARD (not core) ──────────────────────────────────────
+ * Core owns the TOTP *verifier* (`createTotpFactorVerifier`, RFC 6238) but is
+ * ZERO-dep + node-type-free (ADR-0003), so it cannot mint secrets (needs
+ * `node:crypto.randomBytes`) nor build a URI. Enrollment is the *provisioning* side
+ * — it produces the secret the verifier later checks against. Guard owns node
+ * builtins, so the generation lives here. NO core change: the secret this emits is a
+ * plain base32 string, exactly what `createTotpFactorVerifier` decodes.
+ *
+ * ── SECURITY ─────────────────────────────────────────────────────────────────
+ * The secret + recovery codes are credential material: never logged, returned to the
+ * user exactly ONCE at enrollment, and (recovery codes) stored only Argon2-hashed.
+ * These functions are PURE (no I/O, no storage) — the caller decides what to persist.
+ *
+ * ADR-0003: guard owns `node:crypto`; this file has NO framework/HTTP/DB coupling.
+ */
+/**
+ * Generate a fresh, cryptographically-random base32 TOTP secret (160 bits → 32
+ * chars). This is what the user's authenticator app is provisioned with and what the
+ * core verifier later checks presented codes against.
+ */
+export declare function generateTotpSecret(): string;
+/**
+ * Build the `otpauth://totp/...` provisioning URI an authenticator app scans (or the
+ * user enters manually). `label` identifies the account (shown in the app), `issuer`
+ * names the service. All three URI components are percent-encoded so a label/issuer
+ * with spaces or `:`/`?`/`&` cannot break the URI. Fixed to the defaults the core
+ * verifier uses (SHA-1, 6 digits, 30s period).
+ */
+export declare function buildOtpauthUri(secret: string, label: string, issuer: string): string;
+/**
+ * Mint `count` unique one-time recovery codes (each `xxxxx-xxxxx`, 10 lowercase hex
+ * chars grouped for readability). Returned RAW to the caller ONCE at enrollment; the
+ * store persists them Argon2-hashed. Uniqueness is enforced (a hex collision at this
+ * entropy is astronomically unlikely, but the loop guarantees `count` distinct codes).
+ */
+export declare function generateRecoveryCodes(count?: number): string[];
+//# sourceMappingURL=totp-enrollment.d.ts.map

package/dist/auth/totp-enrollment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"totp-enrollment.d.ts","sourceRoot":"","sources":["../../src/auth/totp-enrollment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA4CH;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAOrF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,GAAE,MAAoC,GAAG,MAAM,EAAE,CAO3F"}

package/dist/auth/totp-enrollment.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * Phase 4 MFA-enrollment — the **pure TOTP-enrollment helpers**: generate a fresh
+ * base32 TOTP secret, compose the `otpauth://` provisioning URI an authenticator app
+ * scans, and mint one-time recovery codes.
+ *
+ * ── WHY THIS LIVES IN GUARD (not core) ──────────────────────────────────────
+ * Core owns the TOTP *verifier* (`createTotpFactorVerifier`, RFC 6238) but is
+ * ZERO-dep + node-type-free (ADR-0003), so it cannot mint secrets (needs
+ * `node:crypto.randomBytes`) nor build a URI. Enrollment is the *provisioning* side
+ * — it produces the secret the verifier later checks against. Guard owns node
+ * builtins, so the generation lives here. NO core change: the secret this emits is a
+ * plain base32 string, exactly what `createTotpFactorVerifier` decodes.
+ *
+ * ── SECURITY ─────────────────────────────────────────────────────────────────
+ * The secret + recovery codes are credential material: never logged, returned to the
+ * user exactly ONCE at enrollment, and (recovery codes) stored only Argon2-hashed.
+ * These functions are PURE (no I/O, no storage) — the caller decides what to persist.
+ *
+ * ADR-0003: guard owns `node:crypto`; this file has NO framework/HTTP/DB coupling.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateTotpSecret = generateTotpSecret;
+exports.buildOtpauthUri = buildOtpauthUri;
+exports.generateRecoveryCodes = generateRecoveryCodes;
+const node_crypto_1 = require("node:crypto");
+/** RFC 4648 base32 alphabet — the standard TOTP secret encoding (no padding here). */
+const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+/**
+ * Bytes of entropy behind a generated TOTP secret. 20 bytes = 160 bits → exactly
+ * 32 base32 characters (20 × 8 / 5 = 32, no remainder → no padding), the RFC 4226
+ * recommended HMAC-SHA1 key length.
+ */
+const SECRET_BYTES = 20;
+/** How many recovery codes to mint by default (industry-standard batch of 10). */
+const DEFAULT_RECOVERY_CODE_COUNT = 10;
+/** Bytes per recovery code → 5 bytes = 10 lowercase hex chars, split into two groups. */
+const RECOVERY_CODE_BYTES = 5;
+/**
+ * Encode raw bytes into an RFC 4648 base32 string (no padding). Used to turn the
+ * random secret into the base32 string an authenticator app + the core verifier both
+ * expect. Pure bit-packing: 5 bits per output char, MSB-first.
+ */
+function base32Encode(bytes) {
+    let bits = 0;
+    let value = 0;
+    let out = '';
+    for (const byte of bytes) {
+        value = (value << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            bits -= 5;
+            out += BASE32_ALPHABET[(value >>> bits) & 0x1f];
+        }
+    }
+    if (bits > 0) {
+        // Flush the remaining <5 bits, left-padded with zeros to a full 5-bit group.
+        out += BASE32_ALPHABET[(value << (5 - bits)) & 0x1f];
+    }
+    return out;
+}
+/**
+ * Generate a fresh, cryptographically-random base32 TOTP secret (160 bits → 32
+ * chars). This is what the user's authenticator app is provisioned with and what the
+ * core verifier later checks presented codes against.
+ */
+function generateTotpSecret() {
+    return base32Encode((0, node_crypto_1.randomBytes)(SECRET_BYTES));
+}
+/**
+ * Build the `otpauth://totp/...` provisioning URI an authenticator app scans (or the
+ * user enters manually). `label` identifies the account (shown in the app), `issuer`
+ * names the service. All three URI components are percent-encoded so a label/issuer
+ * with spaces or `:`/`?`/`&` cannot break the URI. Fixed to the defaults the core
+ * verifier uses (SHA-1, 6 digits, 30s period).
+ */
+function buildOtpauthUri(secret, label, issuer) {
+    const encIssuer = encodeURIComponent(issuer);
+    const encLabel = encodeURIComponent(label);
+    return (`otpauth://totp/${encIssuer}:${encLabel}` +
+        `?secret=${secret}&issuer=${encIssuer}&digits=6&period=30`);
+}
+/**
+ * Mint `count` unique one-time recovery codes (each `xxxxx-xxxxx`, 10 lowercase hex
+ * chars grouped for readability). Returned RAW to the caller ONCE at enrollment; the
+ * store persists them Argon2-hashed. Uniqueness is enforced (a hex collision at this
+ * entropy is astronomically unlikely, but the loop guarantees `count` distinct codes).
+ */
+function generateRecoveryCodes(count = DEFAULT_RECOVERY_CODE_COUNT) {
+    const codes = new Set();
+    while (codes.size < count) {
+        const hex = (0, node_crypto_1.randomBytes)(RECOVERY_CODE_BYTES).toString('hex'); // 10 hex chars
+        codes.add(`${hex.slice(0, 5)}-${hex.slice(5)}`);
+    }
+    return [...codes];
+}

package/dist/auth/totp-enrollment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"totp-enrollment.js","sourceRoot":"","sources":["../../src/auth/totp-enrollment.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;AAiDH,gDAEC;AASD,0CAOC;AAQD,sDAOC;AAhFD,6CAA0C;AAE1C,sFAAsF;AACtF,MAAM,eAAe,GAAG,kCAAkC,CAAC;AAE3D;;;;GAIG;AACH,MAAM,YAAY,GAAG,EAAE,CAAC;AAExB,kFAAkF;AAClF,MAAM,2BAA2B,GAAG,EAAE,CAAC;AAEvC,yFAAyF;AACzF,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAE9B;;;;GAIG;AACH,SAAS,YAAY,CAAC,KAAiB;IACrC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,KAAK,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;QAC5B,IAAI,IAAI,CAAC,CAAC;QACV,OAAO,IAAI,IAAI,CAAC,EAAE,CAAC;YACjB,IAAI,IAAI,CAAC,CAAC;YACV,GAAG,IAAI,eAAe,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IACD,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;QACb,6EAA6E;QAC7E,GAAG,IAAI,eAAe,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,SAAgB,kBAAkB;IAChC,OAAO,YAAY,CAAC,IAAA,yBAAW,EAAC,YAAY,CAAC,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,eAAe,CAAC,MAAc,EAAE,KAAa,EAAE,MAAc;IAC3E,MAAM,SAAS,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAC3C,OAAO,CACL,kBAAkB,SAAS,IAAI,QAAQ,EAAE;QACzC,WAAW,MAAM,WAAW,SAAS,qBAAqB,CAC3D,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAgB,qBAAqB,CAAC,QAAgB,2BAA2B;IAC/E,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,OAAO,KAAK,CAAC,IAAI,GAAG,KAAK,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,IAAA,yBAAW,EAAC,mBAAmB,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,eAAe;QAC7E,KAAK,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC;AACpB,CAAC"}

package/dist/authentication/argon2id-password-hasher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"argon2id-password-hasher.js","sourceRoot":"","sources":["../../src/authentication/argon2id-password-hasher.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0EH,wDAQC;AAhFD,+CAAiC;AAmBjC,MAAM,cAAc,GAA6B;IAC/C,UAAU,EAAE,MAAM;IAClB,QAAQ,EAAE,CAAC;IACX,WAAW,EAAE,CAAC;CACf,CAAC;AAEF,0EAA0E;AAC7D,QAAA,sBAAsB,GAAG,MAAM,CAAC,wBAAwB,CAAC,CAAC;AAEvE;;;;GAIG;AACH,MAAa,sBAAsB;IAChB,OAAO,CAAuC;IAE/D,YAAY,SAAyB,EAAE;QACrC,IAAI,CAAC,OAAO,GAAG;YACb,IAAI,EAAE,MAAM,CAAC,QAAQ;YACrB,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,cAAc,CAAC,UAAU;YAC1D,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,cAAc,CAAC,QAAQ;YACpD,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,cAAc,CAAC,WAAW;SAC9D,CAAC;IACJ,CAAC;IAED,8EAA8E;IAC9E,KAAK,CAAC,IAAI,CAAC,SAAiB;QAC1B,6EAA6E;QAC7E,OAAO,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC9C,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,MAAM,CAAC,IAAY,EAAE,SAAiB;QAC1C,IAAI,CAAC;YACH,OAAO,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAC9C,CAAC;QAAC,MAAM,CAAC;YACP,yEAAyE;YACzE,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF;AA/BD,wDA+BC;AAED;;;;;GAKG;AACH,SAAgB,sBAAsB,CAAC,SAAyB,EAAE;IAIhE,OAAO;QACL,OAAO,EAAE,8BAAsB;QAC/B,QAAQ,EAAE,IAAI,sBAAsB,CAAC,MAAM,CAAC;KAC7C,CAAC;AACJ,CAAC"}

package/dist/authentication/mariadb-credential-resolver.d.ts

@@ -0,0 +1,110 @@
+/**
+ * `MariaDbCredentialResolver` — the framework-DEFAULT concrete
+ * {@link CredentialResolver} (core port) backed by the single
+ * `shield_identity.identity_credential` table. Resolves an `identityHint`
+ * (username / email) → a {@link ResolvedCredential} the Authentication engine
+ * verifies, or `null` for an unknown hint.
+ *
+ * ⛔ PASSWORD-ONLY BY DESIGN. This default resolver reads ONLY the columns the
+ * framework's shipped seed (`infra/mariadb/init/30-identity-credential.sql`)
+ * actually creates: `ic_password_hash, ic_principal_id, ic_tenant_id, ic_roles`.
+ * It therefore ALWAYS returns `requiredFactors: []` — it does NOT provide an
+ * MFA/second-factor challenge. There is no TOTP column here: the multi-device MFA
+ * model moved authenticator secrets out of `identity_credential` into a separate
+ * `mfa_device` table, which the framework ships only as an UNIMPLEMENTED port.
+ *
+ * MFA / required-factors are a CONSUMER concern, delivered by plugging a custom
+ * `credentialResolver` (+ a concrete `MfaDeviceStore`) via `ShieldModule.forRoot`
+ * — NOT by this default. See astram3's `IdentityCredentialResolver`, which reads
+ * this same table AND folds in the consumer's confirmed authenticators via
+ * `listConfirmedSecrets(mfa_device)` to populate `requiredFactors`. That seam is
+ * the supported way to add MFA-at-login on top of this password-only default.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * THE TABLE CONTRACT (infra seed `infra/mariadb/init/30-identity-credential.sql`,
+ * in `shield_identity`; the runtime `shield_core` account already has DML there —
+ * no new grant). Columns per spec §3 (prefix `ic_` to match the repo's
+ * session-table convention):
+ *
+ *   identity_credential
+ *   ┌────────────────────────┬──────────────┬────────────────────────────────────┐
+ *   │ column                 │ type         │ notes                              │
+ *   ├────────────────────────┼──────────────┼────────────────────────────────────┤
+ *   │ ic_identity_hint       │ VARCHAR(255) │ UNIQUE — the login key (user/email)│
+ *   │ ic_password_hash       │ VARCHAR(255) │ Argon2id encoded hash (verify in)  │
+ *   │ ic_principal_id        │ VARCHAR(255) │ → ResolvedCredential.claims.id     │
+ *   │ ic_tenant_id           │ VARCHAR(255) │ → claims.tenantId                  │
+ *   │ ic_roles               │ JSON / TEXT  │ role-id array → claims.roleIds     │
+ *   │ ic_created_at_ms       │ BIGINT       │ UTC epoch ms (platform sets UTC)   │
+ *   │ ic_updated_at_ms       │ BIGINT       │ UTC epoch ms                       │
+ *   └────────────────────────┴──────────────┴────────────────────────────────────┘
+ *   PRIMARY KEY / UNIQUE on ic_identity_hint (single-row resolve by hint).
+ *   (No `ic_totp_secret` column — MFA secrets live in the consumer's `mfa_device`
+ *    table, resolved by a consumer-plugged resolver, not by this default.)
+ *
+ * The resolver's SELECT must:
+ *   1. `SELECT ic_password_hash, ic_principal_id, ic_tenant_id, ic_roles
+ *       FROM shield_identity.identity_credential
+ *       WHERE ic_identity_hint = ? LIMIT 1` (parameterized — NEVER string-built).
+ *   2. Return `null` when NO row matches — the ONLY "not found" signal
+ *      (anti-enumeration; MUST NOT throw for an unknown hint; the engine burns a
+ *      decoy verify on `null` so timing is uniform).
+ *   3. Map a found row → `ResolvedCredential`:
+ *        passwordHash    = ic_password_hash
+ *        claims          = { id: ic_principal_id, tenantId: ic_tenant_id,
+ *                            roleIds: <parsed ic_roles> }   // canonical Internal claims
+ *        requiredFactors = []   // ALWAYS empty — password-only default (see above)
+ *   4. NEVER log the hash or the raw row.
+ *   5. A store outage (connection/query error) MAY throw — the engine treats a
+ *      resolver throw as fail-closed `authentication_unavailable` (never a leak).
+ *      It MUST NOT convert a throw into a `null` (that would make an outage look
+ *      like "unknown user").
+ *
+ * (`claims.kind` is optional — the Internal adapter defaults an absent kind; add
+ *  an `ic_kind` column later if a deployment needs non-`user` principals. Do NOT
+ *  put any root flag in the row — root is the broker's server-side
+ *  allowlist, never a claim, per core/identity.)
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * ADR-0003: the concrete DB lives in guard (Core stays zero-dep). ADR-0013/0014:
+ * reads `shield_identity` via the hot-path `shield_core` account.
+ */
+import type { Pool } from 'mariadb';
+import type { CredentialResolver, ResolvedCredential } from '@astram/core';
+/** DI token for the resolver — re-exported from the shared auth tokens module. */
+export { SHIELD_CREDENTIAL_RESOLVER } from '../auth/tokens.js';
+/**
+ * The concrete MariaDB-backed {@link CredentialResolver}. Constructed with the
+ * live `shield_core` {@link Pool} (via {@link SHIELD_CREDENTIAL_RESOLVER}'s
+ * factory, which injects {@link SHIELD_DB_POOL}). Stateless per call apart from
+ * the injected pool.
+ *
+ * ⛔ SKELETON: `resolve()` throws until Team A implements the SELECT above.
+ */
+export declare class MariaDbCredentialResolver implements CredentialResolver {
+    private readonly pool;
+    constructor(pool: Pool);
+    /**
+     * Resolve `identityHint` → {@link ResolvedCredential}, or `null` when no such
+     * principal exists.
+     *
+     * - Parameterized SELECT (`WHERE ic_identity_hint = ? LIMIT 1`) — never
+     *   string-built, so the hint can never inject SQL.
+     * - **No row ⇒ `null`** — the ONLY "not found" signal (anti-enumeration; the
+     *   engine burns a decoy password verify on `null` so an unknown user is
+     *   indistinguishable from a wrong password by content or timing). We do NOT
+     *   throw for an unknown hint.
+     * - A **query/connection ERROR propagates** (rejects) — an outage is NOT an
+     *   unknown user; the engine treats a resolver throw as fail-closed
+     *   `authentication_unavailable`. We never convert an error into `null` (that
+     *   would mask an outage AND make it look like "no such user").
+     * - The password hash is NEVER logged; the raw row is never logged. On success
+     *   it is returned to the engine as a verify input only.
+     * - **Password-only:** `requiredFactors` is ALWAYS `[]`. This default provides
+     *   no second-factor challenge; MFA-at-login is delivered by a consumer-plugged
+     *   `credentialResolver` (+ `MfaDeviceStore`) — see the class doc header and
+     *   astram3's `IdentityCredentialResolver`.
+     */
+    resolve(identityHint: string): Promise<ResolvedCredential | null>;
+}
+//# sourceMappingURL=mariadb-credential-resolver.d.ts.map

package/dist/authentication/mariadb-credential-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mariadb-credential-resolver.d.ts","sourceRoot":"","sources":["../../src/authentication/mariadb-credential-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EACV,kBAAkB,EAElB,kBAAkB,EACnB,MAAM,cAAc,CAAC;AAEtB,kFAAkF;AAClF,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAqD/D;;;;;;;GAOG;AACH,qBAAa,yBAA0B,YAAW,kBAAkB;IACtD,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,IAAI;IAEvC;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;CAgCxE"}