@astram/guard 0.2.0 → 0.4.0

package/dist/auth/ports/audit-sink.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * AuditSink — the auth-surface **audit seam** (spec §6.2). The auth surface is
+ * otherwise un-audited (only the @astram/engine pipe audits record CRUD); this port
+ * introduces the FIRST auth audit event. The framework builds the event; the consumer
+ * persists it (astram3 writes `shield_audit.audit_log`).
+ *
+ * OPTIONAL, consumer-plugged through `ShieldModule.forRoot({ auditSink })` and threaded
+ * to `AuthModule.forRoot` exactly like the other account/credential seams. Absent
+ * (`null`) → the route still works, just un-audited (the `@Optional()` injection in
+ * `AuthController` resolves to no seam → the best-effort call is a no-op).
+ *
+ * BEST-EFFORT by contract: `record` is invoked fire-and-forget on the recovery-login
+ * success path — a throwing or slow sink NEVER fails the (legitimate) login. The
+ * consumer's impl should not surface errors into the response path.
+ *
+ * NO SECRET LEAK: the event carries NO password, recovery code, TOTP secret, or token —
+ * only the actor id, tenant, action key, and non-secret attributes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/auth/ports/credential-writer.d.ts

@@ -0,0 +1,23 @@
+/**
+ * CredentialWriter — the seam that WRITES a principal's password credential. The
+ * framework never owns the credential store; the consumer plugs this (like
+ * CredentialResolver, but the write side). Supplied via
+ * ShieldModule.forRoot({ credentialWriter }). Absent → the routes that need it
+ * return 501. Writes HASHES only — never plaintext.
+ *
+ * TOTP secrets are NOT written here — the multi-device MFA model stores
+ * every authenticator secret in the `MfaDeviceStore` (one storage location, one code
+ * path). So this seam is now password-only: `setPassword` + `getPasswordHash`.
+ */
+export interface CredentialWriter {
+    /** Set the principal's password to an already-hashed value. */
+    setPassword(principalId: string, passwordHash: string): Promise<void>;
+    /**
+     * Read the stored password hash by principal id — needed by change-password, which
+     * holds the principal id (from the token), whereas CredentialResolver keys by
+     * identityHint. Null if the principal is unknown. (This is the ONE read on the
+     * writer seam; see Task 5 for why it lives here rather than a separate seam.)
+     */
+    getPasswordHash(principalId: string): Promise<string | null>;
+}
+//# sourceMappingURL=credential-writer.d.ts.map

package/dist/auth/ports/credential-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-writer.d.ts","sourceRoot":"","sources":["../../../src/auth/ports/credential-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE;;;;;OAKG;IACH,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC9D"}

package/dist/auth/ports/credential-writer.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/auth/ports/email-sender.d.ts

@@ -0,0 +1,14 @@
+/**
+ * EmailSender — the delivery seam. The framework builds the message; the consumer
+ * delivers it (SendGrid, SMTP, or a test capturer). Consumer-plugged.
+ */
+export interface EmailMessage {
+    readonly to: string;
+    readonly subject: string;
+    readonly html: string;
+    readonly text: string;
+}
+export interface EmailSender {
+    send(message: EmailMessage): Promise<void>;
+}
+//# sourceMappingURL=email-sender.d.ts.map

package/dist/auth/ports/email-sender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-sender.d.ts","sourceRoot":"","sources":["../../../src/auth/ports/email-sender.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AACD,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5C"}

package/dist/auth/ports/email-sender.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/auth/ports/mfa-device-store.d.ts

@@ -0,0 +1,45 @@
+/**
+ * MfaDeviceStore — the seam that persists a principal's TOTP authenticator DEVICES
+ * (multi-device MFA). The framework never owns the store; the consumer
+ * plugs this (like {@link CredentialWriter}, but for the N-device MFA model).
+ * Each device has its OWN base32 secret; login matches ANY confirmed device (the
+ * OR-match lives in the consumer resolver + a custom TOTP verifier, NOT here — this
+ * port is pure persistence). Supplied via `ShieldModule.forRoot({ mfaDeviceStore })`.
+ * Absent (`null`) → the device routes return 501. A device's `secret` is NEVER
+ * returned to a client (only {@link listConfirmedSecrets} for the login bundle,
+ * server-side) — the display shape {@link MfaDevice} deliberately omits it.
+ */
+/** The DISPLAY shape of one MFA device (NO secret — never leaves the server). */
+export interface MfaDevice {
+    readonly id: string;
+    readonly name: string;
+    readonly createdAtMs: number;
+    readonly lastUsedAtMs: number | null;
+    readonly confirmed: boolean;
+}
+export interface MfaDeviceStore {
+    /** All of the principal's devices incl. pending (internal/debug; routes filter to confirmed for display). */
+    listAll(principalId: string): Promise<MfaDevice[]>;
+    /** Confirmed devices' base32 secrets — for the login requiredFactor bundle + verify. */
+    listConfirmedSecrets(principalId: string): Promise<string[]>;
+    /**
+     * The base32 secret of a SINGLE device the principal owns (confirmed OR pending), or
+     * `null` if not found / not owned. Used ONLY server-side by `confirm` to check the
+     * presented code against the pending device's own secret — the secret is NEVER
+     * returned to a client (the display {@link MfaDevice} deliberately omits it).
+     */
+    getSecret(principalId: string, deviceId: string): Promise<string | null>;
+    /** Create a PENDING device (own id); prunes the caller's stale pending rows first. Returns the deviceId. */
+    begin(principalId: string, name: string, secret: string): Promise<string>;
+    /** Activate a pending device (confirmed). False if not found / not owned / not pending. */
+    confirm(principalId: string, deviceId: string): Promise<boolean>;
+    /** Rename a device. Returns the updated device, or null if not found / not owned. */
+    rename(principalId: string, deviceId: string, name: string): Promise<MfaDevice | null>;
+    /** Delete a device. False if not found / not owned. */
+    remove(principalId: string, deviceId: string): Promise<boolean>;
+    /** Count of CONFIRMED devices (drives "first device" / "mfa enabled"). */
+    countConfirmed(principalId: string): Promise<number>;
+    /** Best-effort: stamp last-used for the device whose secret verified (match by unique secret). */
+    stampUsed(secret: string): Promise<void>;
+}
+//# sourceMappingURL=mfa-device-store.d.ts.map

package/dist/auth/ports/mfa-device-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mfa-device-store.d.ts","sourceRoot":"","sources":["../../../src/auth/ports/mfa-device-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,iFAAiF;AACjF,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,6GAA6G;IAC7G,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IACnD,wFAAwF;IACxF,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7D;;;;;OAKG;IACH,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzE,4GAA4G;IAC5G,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1E,2FAA2F;IAC3F,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjE,qFAAqF;IACrF,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IACvF,uDAAuD;IACvD,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChE,0EAA0E;IAC1E,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,kGAAkG;IAClG,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C"}

package/dist/auth/ports/mfa-device-store.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * MfaDeviceStore — the seam that persists a principal's TOTP authenticator DEVICES
+ * (multi-device MFA). The framework never owns the store; the consumer
+ * plugs this (like {@link CredentialWriter}, but for the N-device MFA model).
+ * Each device has its OWN base32 secret; login matches ANY confirmed device (the
+ * OR-match lives in the consumer resolver + a custom TOTP verifier, NOT here — this
+ * port is pure persistence). Supplied via `ShieldModule.forRoot({ mfaDeviceStore })`.
+ * Absent (`null`) → the device routes return 501. A device's `secret` is NEVER
+ * returned to a client (only {@link listConfirmedSecrets} for the login bundle,
+ * server-side) — the display shape {@link MfaDevice} deliberately omits it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/auth/ports/profile-writer.d.ts

@@ -0,0 +1,12 @@
+import type { CurrentUserProfile } from '../profile-resolver.js';
+/**
+ * ProfileWriter — self-service profile edit (name/email). Returns the refreshed
+ * display profile (names, never UUIDs). Consumer-plugged.
+ */
+export interface ProfileWriter {
+    update(principalId: string, changes: {
+        name?: string;
+        email?: string;
+    }): Promise<CurrentUserProfile>;
+}
+//# sourceMappingURL=profile-writer.d.ts.map

package/dist/auth/ports/profile-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-writer.d.ts","sourceRoot":"","sources":["../../../src/auth/ports/profile-writer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,CACJ,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GACzC,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAChC"}

package/dist/auth/ports/profile-writer.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/auth/ports/recovery-code-store.d.ts

@@ -0,0 +1,10 @@
+/**
+ * RecoveryCodeStore — persists Argon2-hashed one-time MFA recovery codes.
+ * `replaceAll` wipes prior codes on (re-)enroll. `consume` returns true iff a
+ * matching unconsumed code exists, then marks it consumed (single-use).
+ */
+export interface RecoveryCodeStore {
+    replaceAll(principalId: string, codeHashes: readonly string[]): Promise<void>;
+    consume(principalId: string, rawCode: string): Promise<boolean>;
+}
+//# sourceMappingURL=recovery-code-store.d.ts.map

package/dist/auth/ports/recovery-code-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-code-store.d.ts","sourceRoot":"","sources":["../../../src/auth/ports/recovery-code-store.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjE"}

package/dist/auth/ports/recovery-code-store.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/auth/ports/reset-token-store.d.ts

@@ -0,0 +1,12 @@
+/**
+ * ResetTokenStore — persists single-use, TTL'd password-reset tokens. The framework
+ * hashes the raw token (SHA-256) before it reaches this store; the store never sees
+ * the raw token. `consume` returns the principalId iff the token is unexpired AND
+ * unconsumed, then marks it consumed (single-use). Consumer-plugged.
+ */
+export interface ResetTokenStore {
+    issue(principalId: string, tokenHash: string, expiresAtMs: number): Promise<void>;
+    consume(tokenHash: string): Promise<string | null>;
+    invalidateAllForPrincipal(principalId: string): Promise<void>;
+}
+//# sourceMappingURL=reset-token-store.d.ts.map

package/dist/auth/ports/reset-token-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reset-token-store.d.ts","sourceRoot":"","sources":["../../../src/auth/ports/reset-token-store.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClF,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACnD,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D"}

package/dist/auth/ports/reset-token-store.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/auth/ports/session-facts-projector.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The `SessionFactsProjector` PORT (ADR-0011 eager projection) — the OPT-IN seam the
+ * auth surface uses to compute a principal's coarse grants at LOGIN / REFRESH time so
+ * they can be cached on the session binding, letting gate 5 serve them from the
+ * request's `cachedFacts` instead of a DB reload on every request.
+ *
+ * ── WHY A DEDICATED PORT (not the core `PermissionFactsPort` directly) ────────────
+ * The core `PermissionFactsPort` is an authorization-engine dep wired into the record
+ * decision authority (`recordAuthorization`), not something AuthModule injects. Rather
+ * than couple the auth controller to that engine wiring, the consumer supplies a thin
+ * `SessionFactsProjector` — which it typically implements by delegating to the SAME
+ * `DbPermissionFactsAdapter.loadCoarseGrants` it already hands the decision authority.
+ * One tiny interface, one clean seam, no engine coupling in AuthModule.
+ *
+ * ── OPT-IN / ADDITIVE ────────────────────────────────────────────────────────────
+ * ABSENT (the default): the auth controller omits `cachedFacts` when binding the
+ * session → gate 5 sees no cache → DB reload every request = today's exact behavior.
+ * PRESENT: the controller calls `project(...)` at login + refresh and stores the
+ * returned {@link CoarseGrants} on the binding, so subsequent requests hit the cache.
+ * Turning it on NEVER changes a decision — it only removes a DB round-trip when the
+ * cached version is fresh; a stale/absent cache still reloads (gate 5's version gate).
+ *
+ * ── FAIL-CLOSED ──────────────────────────────────────────────────────────────────
+ * `project(...)` returning `null` (or throwing — the caller swallows it best-effort)
+ * means "no facts cached" → the session binds WITHOUT `cachedFacts` → gate 5 DB-reloads.
+ * A projection failure therefore degrades safely to the correct (un-cached) behavior;
+ * it never fabricates or omits a grant that would change a decision.
+ */
+import type { CoarseGrants } from '@astram/core';
+export interface SessionFactsProjector {
+    /**
+     * Project the coarse feature/object-type grants for `principalId` in `tenantId` at
+     * login/refresh time (ADR-0011). Returns the {@link CoarseGrants} to cache on the
+     * session binding, or `null` when nothing should be cached (→ gate 5 DB-reloads).
+     *
+     * A principal with NO grants SHOULD return a {@link CoarseGrants} with an empty
+     * `grantedPermissionKeys` (tagged with the current version) — that is a legitimate
+     * "genuinely no grants" cache, distinct from `null` ("don't cache"). Implementations
+     * typically delegate to the same `PermissionFactsPort.loadCoarseGrants` the decision
+     * authority uses.
+     */
+    project(principalId: string, tenantId: string): Promise<CoarseGrants | null>;
+}
+//# sourceMappingURL=session-facts-projector.d.ts.map

package/dist/auth/ports/session-facts-projector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-facts-projector.d.ts","sourceRoot":"","sources":["../../../src/auth/ports/session-facts-projector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;CAC9E"}

package/dist/auth/ports/session-facts-projector.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * The `SessionFactsProjector` PORT (ADR-0011 eager projection) — the OPT-IN seam the
+ * auth surface uses to compute a principal's coarse grants at LOGIN / REFRESH time so
+ * they can be cached on the session binding, letting gate 5 serve them from the
+ * request's `cachedFacts` instead of a DB reload on every request.
+ *
+ * ── WHY A DEDICATED PORT (not the core `PermissionFactsPort` directly) ────────────
+ * The core `PermissionFactsPort` is an authorization-engine dep wired into the record
+ * decision authority (`recordAuthorization`), not something AuthModule injects. Rather
+ * than couple the auth controller to that engine wiring, the consumer supplies a thin
+ * `SessionFactsProjector` — which it typically implements by delegating to the SAME
+ * `DbPermissionFactsAdapter.loadCoarseGrants` it already hands the decision authority.
+ * One tiny interface, one clean seam, no engine coupling in AuthModule.
+ *
+ * ── OPT-IN / ADDITIVE ────────────────────────────────────────────────────────────
+ * ABSENT (the default): the auth controller omits `cachedFacts` when binding the
+ * session → gate 5 sees no cache → DB reload every request = today's exact behavior.
+ * PRESENT: the controller calls `project(...)` at login + refresh and stores the
+ * returned {@link CoarseGrants} on the binding, so subsequent requests hit the cache.
+ * Turning it on NEVER changes a decision — it only removes a DB round-trip when the
+ * cached version is fresh; a stale/absent cache still reloads (gate 5's version gate).
+ *
+ * ── FAIL-CLOSED ──────────────────────────────────────────────────────────────────
+ * `project(...)` returning `null` (or throwing — the caller swallows it best-effort)
+ * means "no facts cached" → the session binds WITHOUT `cachedFacts` → gate 5 DB-reloads.
+ * A projection failure therefore degrades safely to the correct (un-cached) behavior;
+ * it never fabricates or omits a grant that would change a decision.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/auth/ports/session-sweeper.d.ts

@@ -0,0 +1,12 @@
+/**
+ * SessionSweeper — revokes a principal's sessions after a credential change. The
+ * core has no revoke-all-for-principal, so the consumer implements this over its
+ * session store (there is an s_principal_id column + index). Consumer-plugged.
+ */
+export interface SessionSweeper {
+    /** Revoke ALL of the principal's sessions (used after a password reset). */
+    revokeAllForPrincipal(principalId: string): Promise<void>;
+    /** Revoke all EXCEPT keepSessionId (used after an authenticated change-password). */
+    revokeOthersForPrincipal(principalId: string, keepSessionId: string): Promise<void>;
+}
+//# sourceMappingURL=session-sweeper.d.ts.map

package/dist/auth/ports/session-sweeper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-sweeper.d.ts","sourceRoot":"","sources":["../../../src/auth/ports/session-sweeper.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,qFAAqF;IACrF,wBAAwB,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrF"}

package/dist/auth/ports/session-sweeper.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/auth/profile-resolver.d.ts

@@ -0,0 +1,73 @@
+/**
+ * ProfileResolver — the seam that turns an authenticated `Principal` into the
+ * signed-in user's **display profile** for `GET /auth/me` (the current-user
+ * endpoint). This is the fill for the flagged gap: login/session return only IDs
+ * (`principalId` / `tenantId`), so a UI has no human-readable name/company/role to
+ * show without leaking a raw UUID.
+ *
+ * WHY THIS IS A SEAM (not baked into the framework): the framework owns the
+ * CREDENTIAL store (`shield_identity`) but is deliberately AGNOSTIC to the app's
+ * ORG model — how users, companies (tenants), and roles are named lives in the
+ * consumer's own schema (astram3's `shield_app` tables, another app's users/roles
+ * model, etc.). So the framework opens THIS port and the consumer implements it,
+ * exactly like {@link CredentialResolver}. Zero core changes; the framework never
+ * hard-codes a table or a display-column.
+ *
+ * SECURITY / CONTRACT:
+ *  - Called ONLY after the request-auth layer has resolved a live bearer token to a
+ *    `Principal` (so it always acts as an authenticated caller — never anonymous).
+ *  - Returns display NAMES, never raw UUIDs (the never-show-UUIDs rule): the
+ *    consumer resolves `principal.id` → the user's name/email, `principal.tenantId`
+ *    → the company's display name, `principal.roleIds` → the roles' names.
+ *  - `null` = the principal has no resolvable profile (e.g. the user row was
+ *    deleted since login) — the endpoint returns 404-style "no profile", never the
+ *    ids. A store OUTAGE should THROW (fail-closed) — the endpoint maps it to a
+ *    generic error, not an empty profile.
+ */
+import type { Principal } from '@astram/core';
+/** A role as shown to the user — the display name, plus its id for the UI's keys. */
+export interface ProfileRole {
+    /** The role's stable id (safe in `key=`/`data-*`, never rendered as text). */
+    readonly id: string;
+    /** The role's human-readable display name (what the UI renders). */
+    readonly name: string;
+}
+/** The signed-in user's tenant (company) as shown to the user. */
+export interface ProfileTenant {
+    /** The tenant/company id (safe in machine contexts, never rendered as text). */
+    readonly id: string;
+    /** The company's human-readable display name (what the UI renders). */
+    readonly name: string;
+}
+/**
+ * The current-user display profile returned by `GET /auth/me`. Everything here is
+ * SAFE to render — names, not UUIDs. The bare `id` fields are for the UI's internal
+ * keys/routing only (the never-show-UUIDs rule allows ids in machine contexts).
+ */
+export interface CurrentUserProfile {
+    /** The user's id (machine use only — routing/keys, never rendered as text). */
+    readonly id: string;
+    /** The user's display name (what the header/card renders). */
+    readonly name: string;
+    /** The user's email/username, if the app exposes one (else omit). */
+    readonly email?: string;
+    /** The active tenant/company (the boundary the session is scoped to). */
+    readonly company: ProfileTenant;
+    /** The roles the user holds in the active tenant (display names). */
+    readonly roles: readonly ProfileRole[];
+}
+/**
+ * The port a consumer implements to back `GET /auth/me`. Supplied to the framework
+ * via `ShieldModule.forRoot({ profileResolver })`. Framework-agnostic: the framework
+ * never reads the app's org tables — it calls this seam.
+ */
+export interface ProfileResolver {
+    /**
+     * Resolve an authenticated `Principal` → the display profile, or `null` when no
+     * profile exists for this principal (deleted user, etc.). MUST return display
+     * NAMES (never raw UUIDs) for `name`/`company.name`/`roles[].name`. A store outage
+     * should THROW (fail-closed) rather than return a partial/empty profile.
+     */
+    resolve(principal: Principal): Promise<CurrentUserProfile | null>;
+}
+//# sourceMappingURL=profile-resolver.d.ts.map

package/dist/auth/profile-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-resolver.d.ts","sourceRoot":"","sources":["../../src/auth/profile-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,qFAAqF;AACrF,MAAM,WAAW,WAAW;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;CACxC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,OAAO,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;CACnE"}

package/dist/auth/profile-resolver.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * ProfileResolver — the seam that turns an authenticated `Principal` into the
+ * signed-in user's **display profile** for `GET /auth/me` (the current-user
+ * endpoint). This is the fill for the flagged gap: login/session return only IDs
+ * (`principalId` / `tenantId`), so a UI has no human-readable name/company/role to
+ * show without leaking a raw UUID.
+ *
+ * WHY THIS IS A SEAM (not baked into the framework): the framework owns the
+ * CREDENTIAL store (`shield_identity`) but is deliberately AGNOSTIC to the app's
+ * ORG model — how users, companies (tenants), and roles are named lives in the
+ * consumer's own schema (astram3's `shield_app` tables, another app's users/roles
+ * model, etc.). So the framework opens THIS port and the consumer implements it,
+ * exactly like {@link CredentialResolver}. Zero core changes; the framework never
+ * hard-codes a table or a display-column.
+ *
+ * SECURITY / CONTRACT:
+ *  - Called ONLY after the request-auth layer has resolved a live bearer token to a
+ *    `Principal` (so it always acts as an authenticated caller — never anonymous).
+ *  - Returns display NAMES, never raw UUIDs (the never-show-UUIDs rule): the
+ *    consumer resolves `principal.id` → the user's name/email, `principal.tenantId`
+ *    → the company's display name, `principal.roleIds` → the roles' names.
+ *  - `null` = the principal has no resolvable profile (e.g. the user row was
+ *    deleted since login) — the endpoint returns 404-style "no profile", never the
+ *    ids. A store OUTAGE should THROW (fail-closed) — the endpoint maps it to a
+ *    generic error, not an empty profile.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/auth/rate-limit/attempt-limiter.d.ts

@@ -0,0 +1,91 @@
+/**
+ * `AttemptLimiter` — a guard-owned, Redis-backed sliding-window attempt counter for
+ * anti-brute-force on the auth surface (spec §5). ONE class, used at TWO call sites
+ * with independent thresholds: `/auth/login` (H1 password-login lockout, default
+ * 10/15min, keyed `login:<identityHint>`) and the `/auth/mfa` recovery branch
+ * (default 5/15min, keyed `recovery:<principalId>`).
+ *
+ * ── CONTRACT ─────────────────────────────────────────────────────────────────
+ *   check(key)         → `true`  if the caller is UNDER the threshold (allowed);
+ *                        `false` if AT/over it (locked out for the window).
+ *   recordFailure(key) → increment the counter; on the FIRST failure in a window,
+ *                        set the window TTL (`PEXPIRE windowMs`) so the counter
+ *                        auto-expires (a sliding window that resets on inactivity).
+ *                        RETURNS the new count so a caller can detect the LOCKOUT
+ *                        TRANSITION (count === maxAttempts is the exact edge where
+ *                        the NEXT check() flips to `false`) and act ONCE on it — e.g.
+ *                        emit a single lockout audit event, never one per attempt
+ *                        (feature #140's audit-on-the-edge, anti-flood). On a Redis
+ *                        best-effort miss it returns `0` (an unknown count → the
+ *                        caller simply doesn't treat the miss as a transition).
+ *   reset(key)         → clear the counter (a SUCCESS resets — a legitimate user is
+ *                        never penalized for their earlier fat-fingers).
+ *
+ * ── FAIL-OPEN-WITH-LOG (spec §5, the deliberate posture) ──────────────────────
+ *   A limiter differs from the credential path: a Redis outage must NOT lock out
+ *   every legitimate login/recovery. So `check()` FAILS OPEN on a Redis error —
+ *   it returns `true` (allowed) and LOGS the blip. This never grants access on its
+ *   own (the password / recovery code still gates); it only transiently LOOSENS the
+ *   brute-force ceiling. `recordFailure`/`reset` are best-effort and swallow (a
+ *   count we couldn't write just means the window is a touch more lenient — never a
+ *   thrown error into the request path).
+ *
+ * ── ANTI-ENUMERATION ── the limiter itself is silent; the caller maps a `false`
+ *   from `check()` to the SAME generic 401 as a wrong password / wrong code, so a
+ *   locked-out account is indistinguishable from a bad credential.
+ *
+ * ADR-0023: guard owns the infra adapter (ioredis); the class is a thin, injectable
+ * collaborator the controller consumes via a DI token (`SHIELD_LOGIN_LIMITER` /
+ * `SHIELD_RECOVERY_LIMITER`), each provided with the live Redis + its config.
+ */
+import type Redis from 'ioredis';
+/** Per-limiter tuning: the failure ceiling and the sliding-window length (ms). */
+export interface AttemptLimiterConfig {
+    /** Number of failures within the window that trips the lockout (check → false). */
+    readonly maxAttempts: number;
+    /** The window length in ms; the counter auto-expires after this idle span. */
+    readonly windowMs: number;
+}
+export declare class AttemptLimiter {
+    private readonly redis;
+    private readonly cfg;
+    /** One shared logger — the fail-open path warns so a Redis outage is observable. */
+    private static readonly logger;
+    constructor(redis: Redis, cfg: AttemptLimiterConfig);
+    /**
+     * The failure ceiling for this limiter (read-only). A caller uses it to detect the
+     * lockout TRANSITION: {@link recordFailure} returns the new count, and the caller
+     * acts ONCE when that count first equals `maxAttempts` (the edge where the next
+     * {@link check} flips to `false`) — the audit-on-the-edge / anti-flood contract.
+     */
+    get maxAttempts(): number;
+    /** Namespace every key so the two limiters + other Redis users never collide. */
+    private k;
+    /**
+     * `true` iff the caller is UNDER the threshold (allowed). FAILS OPEN on a Redis
+     * error — returns `true` and logs — so a Redis blip never locks out every login
+     * (spec §5). The credential/recovery check still gates access; this only bounds
+     * brute-force.
+     */
+    check(key: string): Promise<boolean>;
+    /**
+     * Increment the failure counter; set the window TTL on the FIRST failure so the
+     * counter auto-expires after `windowMs` of inactivity. Best-effort — a write we
+     * can't land just makes the window slightly more lenient (never a thrown error).
+     *
+     * RETURNS the new failure count so the caller can detect the lockout TRANSITION
+     * (count === {@link maxAttempts} is the exact edge where the next {@link check}
+     * flips to `false`) and act on it exactly ONCE — feature #140's audit-on-the-edge
+     * (never one audit event per attempt past the threshold). On a Redis best-effort
+     * miss it returns `0`: an unknown count the caller must NOT treat as a transition
+     * (so a Redis blip never spuriously fires — or suppresses — the lockout audit).
+     */
+    recordFailure(key: string): Promise<number>;
+    /**
+     * Clear the counter — a SUCCESS resets the window (the user proved themselves; do
+     * not carry their earlier failures forward). Best-effort; a swallowed error just
+     * leaves the (soon-to-expire) counter in place.
+     */
+    reset(key: string): Promise<void>;
+}
+//# sourceMappingURL=attempt-limiter.d.ts.map

package/dist/auth/rate-limit/attempt-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempt-limiter.d.ts","sourceRoot":"","sources":["../../../src/auth/rate-limit/attempt-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AAEjC,kFAAkF;AAClF,MAAM,WAAW,oBAAoB;IACnC,mFAAmF;IACnF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,qBAAa,cAAc;IAKvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG;IALtB,oFAAoF;IACpF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAmC;gBAG9C,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,oBAAoB;IAG5C;;;;;OAKG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,iFAAiF;IACjF,OAAO,CAAC,CAAC;IAIT;;;;;OAKG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAc1C;;;;;;;;;;;OAWG;IACG,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAmBjD;;;;OAIG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAOxC"}