@astram/guard 0.1.1 → 0.3.0

package/dist/auth/persistence.module.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * `PersistenceModule` — the ONE place live infra connections are created (spec
+ * §4). Provides the live `mariadb` {@link Pool} ({@link SHIELD_DB_POOL}) and the
+ * live `ioredis` client ({@link SHIELD_REDIS}) from {@link AppConfig}, with
+ * graceful shutdown. Everything auth persists (sessions, credentials, hot state)
+ * flows through these two connections.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Team B (connection + composition) OWNS this file. The two factories create the
+ * real driver objects; the {@link ConnectionLifecycle} provider (a class Nest
+ * invokes `onModuleDestroy` on) closes them on shutdown — a value provider is not
+ * itself lifecycle-aware, so the teardown lives in that holder (see
+ * `connections.ts`). Both connections are exported so AuthModule can inject the
+ * pool (credential resolver + session record store) and the redis (hot store).
+ *
+ *   SHIELD_DB_POOL  — {@link createDbPool}: `mariadb.createPool` for the
+ *     `shield_core` account from `config.db`, `connectionLimit` from the ADR-0018
+ *     budget (`config.pool.perAccountMax.shield_core`). NOT a duplicate pool knob.
+ *   SHIELD_REDIS    — {@link createRedisClient}: `new Redis(config.redis.url)`
+ *     (ioredis). The hot tier (ADR-0013).
+ *
+ * Neither factory reads the HMAC key (that is the session/hasher composition in
+ * AuthModule). A blank `db.password` is allowed — it fails LOUD at connect time,
+ * which is correct for a runtime credential. Nothing here logs a credential.
+ *
+ * ⛔ OPT-IN: like AuthModule, this module opens LIVE connections, so it must only
+ * be imported when a deployment actually wants auth (AuthModule imports it). An
+ * enforcement-only app that never imports AuthModule never opens a pool/redis and
+ * keeps the no-`.env` boot. See auth.module.ts for the opt-in mechanism.
+ *
+ * ADR-0003: the real `mariadb`/`ioredis` live in guard (Core stays zero-dep).
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var PersistenceModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PersistenceModule = void 0;
+const common_1 = require("@nestjs/common");
+const config_module_js_1 = require("../config/config.module.js");
+const tokens_js_1 = require("./tokens.js");
+const connections_js_1 = require("./connections.js");
+/**
+ * The live MariaDB pool provider. Creates the ONE `shield_core` pool from config
+ * via {@link createDbPool}. `inject: [APP_CONFIG]` so the factory sees the resolved
+ * config. Teardown is handled by {@link ConnectionLifecycle}.
+ */
+const dbPoolProvider = {
+    provide: tokens_js_1.SHIELD_DB_POOL,
+    useFactory: (config) => (0, connections_js_1.createDbPool)(config),
+    inject: [config_module_js_1.APP_CONFIG],
+};
+/**
+ * The live Redis client provider. Creates the ONE hot-tier client from
+ * `config.redis.url` via {@link createRedisClient}. Teardown via
+ * {@link ConnectionLifecycle}.
+ */
+const redisProvider = {
+    provide: tokens_js_1.SHIELD_REDIS,
+    useFactory: (config) => (0, connections_js_1.createRedisClient)(config),
+    inject: [config_module_js_1.APP_CONFIG],
+};
+/**
+ * The lifecycle holder — injects the two connections and closes them on shutdown
+ * (`onModuleDestroy`). A value-provider connection gets no lifecycle callback, so
+ * this class is where graceful teardown happens.
+ */
+const lifecycleProvider = {
+    provide: connections_js_1.ConnectionLifecycle,
+    useFactory: (pool, redis) => new connections_js_1.ConnectionLifecycle(pool, redis),
+    inject: [tokens_js_1.SHIELD_DB_POOL, tokens_js_1.SHIELD_REDIS],
+};
+/**
+ * The persistence module. `forRoot()` returns the two connection providers (both
+ * exported so AuthModule can inject them) plus the shutdown holder. Opt-in: only
+ * imported when auth is wired.
+ */
+let PersistenceModule = PersistenceModule_1 = class PersistenceModule {
+    static forRoot() {
+        return {
+            module: PersistenceModule_1,
+            providers: [dbPoolProvider, redisProvider, lifecycleProvider],
+            exports: [tokens_js_1.SHIELD_DB_POOL, tokens_js_1.SHIELD_REDIS],
+        };
+    }
+};
+exports.PersistenceModule = PersistenceModule;
+exports.PersistenceModule = PersistenceModule = PersistenceModule_1 = __decorate([
+    (0, common_1.Module)({})
+], PersistenceModule);

package/dist/auth/persistence.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.module.js","sourceRoot":"","sources":["../../src/auth/persistence.module.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;;;;;;;;;;AAEH,2CAA2E;AAI3E,iEAAwD;AACxD,2CAA2D;AAC3D,qDAAwF;AAExF;;;;GAIG;AACH,MAAM,cAAc,GAAa;IAC/B,OAAO,EAAE,0BAAc;IACvB,UAAU,EAAE,CAAC,MAAiB,EAAQ,EAAE,CAAC,IAAA,6BAAY,EAAC,MAAM,CAAC;IAC7D,MAAM,EAAE,CAAC,6BAAU,CAAC;CACrB,CAAC;AAEF;;;;GAIG;AACH,MAAM,aAAa,GAAa;IAC9B,OAAO,EAAE,wBAAY;IACrB,UAAU,EAAE,CAAC,MAAiB,EAAS,EAAE,CAAC,IAAA,kCAAiB,EAAC,MAAM,CAAC;IACnE,MAAM,EAAE,CAAC,6BAAU,CAAC;CACrB,CAAC;AAEF;;;;GAIG;AACH,MAAM,iBAAiB,GAAa;IAClC,OAAO,EAAE,oCAAmB;IAC5B,UAAU,EAAE,CAAC,IAAU,EAAE,KAAY,EAAuB,EAAE,CAC5D,IAAI,oCAAmB,CAAC,IAAI,EAAE,KAAK,CAAC;IACtC,MAAM,EAAE,CAAC,0BAAc,EAAE,wBAAY,CAAC;CACvC,CAAC;AAEF;;;;GAIG;AAEI,IAAM,iBAAiB,yBAAvB,MAAM,iBAAiB;IAC5B,MAAM,CAAC,OAAO;QACZ,OAAO;YACL,MAAM,EAAE,mBAAiB;YACzB,SAAS,EAAE,CAAC,cAAc,EAAE,aAAa,EAAE,iBAAiB,CAAC;YAC7D,OAAO,EAAE,CAAC,0BAAc,EAAE,wBAAY,CAAC;SACxC,CAAC;IACJ,CAAC;CACF,CAAA;AARY,8CAAiB;4BAAjB,iBAAiB;IAD7B,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,iBAAiB,CAQ7B"}

package/dist/auth/ports/audit-sink.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+/**
+ * A framework-built auth audit event. `type` is the audit category (`'authentication'`
+ * for the auth surface); `action` is the specific event key (e.g. `'mfa.recovery_used'`).
+ * `attributes` carries non-secret structured detail (never a code/token/secret).
+ */
+export interface AuthAuditEvent {
+    /** The audit category. Always `'authentication'` for auth-surface events. */
+    readonly type: 'authentication';
+    /** When the event occurred (epoch ms). */
+    readonly occurredAtMs: number;
+    /** The acting principal's id (the account the event is about). */
+    readonly actorId: string;
+    /** The active tenant/company the event is scoped to, if known. */
+    readonly tenantId?: string;
+    /** The specific event key, e.g. `'mfa.recovery_used'`. */
+    readonly action: string;
+    /** Non-secret structured detail. NEVER a code / token / secret. */
+    readonly attributes?: Record<string, unknown>;
+}
+/**
+ * The port a consumer implements to persist auth audit events. Supplied to the
+ * framework via `ShieldModule.forRoot({ auditSink })`. Best-effort: `record` is called
+ * fire-and-forget, so an impl error must not propagate into the login response.
+ */
+export interface AuditSink {
+    /** Persist one auth audit event. Best-effort — never fails the caller's flow. */
+    record(event: AuthAuditEvent): Promise<void>;
+}
+//# sourceMappingURL=audit-sink.d.ts.map

package/dist/auth/ports/audit-sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-sink.d.ts","sourceRoot":"","sources":["../../../src/auth/ports/audit-sink.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,0CAA0C;IAC1C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/C;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,iFAAiF;IACjF,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C"}

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/audit-sink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-sink.js","sourceRoot":"","sources":["../../../src/auth/ports/audit-sink.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG"}

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/credential-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-writer.js","sourceRoot":"","sources":["../../../src/auth/ports/credential-writer.ts"],"names":[],"mappings":""}

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/email-sender.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-sender.js","sourceRoot":"","sources":["../../../src/auth/ports/email-sender.ts"],"names":[],"mappings":""}

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/mfa-device-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mfa-device-store.js","sourceRoot":"","sources":["../../../src/auth/ports/mfa-device-store.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG"}

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/profile-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-writer.js","sourceRoot":"","sources":["../../../src/auth/ports/profile-writer.ts"],"names":[],"mappings":""}

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/recovery-code-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-code-store.js","sourceRoot":"","sources":["../../../src/auth/ports/recovery-code-store.ts"],"names":[],"mappings":""}

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/reset-token-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reset-token-store.js","sourceRoot":"","sources":["../../../src/auth/ports/reset-token-store.ts"],"names":[],"mappings":""}

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-facts-projector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-facts-projector.js","sourceRoot":"","sources":["../../../src/auth/ports/session-facts-projector.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG"}

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/ports/session-sweeper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-sweeper.js","sourceRoot":"","sources":["../../../src/auth/ports/session-sweeper.ts"],"names":[],"mappings":""}

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/profile-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-resolver.js","sourceRoot":"","sources":["../../src/auth/profile-resolver.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG"}