@astram/guard 0.2.0 → 0.3.0

package/dist/auth/dto.d.ts

@@ -56,6 +56,14 @@ export interface SessionTokensView {
 export interface SessionSuccess {
     readonly session: SessionView;
     readonly tokens: SessionTokensView;
+    /**
+     * Set to `true` ONLY when the session was completed via a RECOVERY CODE at the
+     * `/auth/mfa` step (the lost-device escape hatch). Absent on every normal
+     * password / TOTP / refresh success, so those paths are byte-for-byte
+     * unaffected. The frontend keys off this to route the recovered session into
+     * the enforced re-enroll flow. Carries NO secret — a pure signal flag.
+     */
+    readonly mfaRecoveryUsed?: boolean;
 }
 /** `POST /auth/login` request body. */
 export interface LoginRequest {
@@ -85,16 +93,18 @@ export interface MfaChallengeResponse {
 export type LoginResponse = SessionSuccess | MfaChallengeResponse;
 /**
  * `POST /auth/mfa` request body — completes a pending MFA challenge. `factor` is
- * `'totp'` in Phase 0b (the only real factor; WebAuthn/recovery are contract slots
- * only). `code` is the presented one-time code (digits). ⛔ `code` is single-use
- * material — never logged.
+ * `'totp'` (an authenticator code) or `'recovery_code'` (the lost-device escape
+ * hatch — a pre-issued single-use recovery code, verified in a separate branch,
+ * see `auth.controller.ts`). WebAuthn remains a contract slot only. `code` is the
+ * presented one-time code / recovery code. ⛔ `code` is single-use material —
+ * never logged.
  */
 export interface MfaRequest {
     /** The opaque handle from {@link MfaChallengeResponse}. Short-TTL, single-use. */
     readonly challengeToken: string;
-    /** The second-factor class being satisfied (Phase 0b: `'totp'`). */
-    readonly factor: 'totp';
-    /** The presented one-time code. NEVER logged. */
+    /** The second-factor class being satisfied (`'totp'` or `'recovery_code'`). */
+    readonly factor: 'totp' | 'recovery_code';
+    /** The presented one-time code / recovery code. NEVER logged. */
     readonly code: string;
 }
 /**

package/dist/auth/dto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dto.d.ts","sourceRoot":"","sources":["../../src/auth/dto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AASH;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAC9D,oBAAoB;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,oBAAoB;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACpC;AAMD,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,oBAAoB,CAAC;AAMlE;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,kFAAkF;IAClF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,cAAc,CAAC;AAMzC;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,eAAe,GAAG,cAAc,CAAC;AAM7C;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;CACxB"}
+{"version":3,"file":"dto.d.ts","sourceRoot":"","sources":["../../src/auth/dto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AASH;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IAC9D,oBAAoB;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,oBAAoB;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAMD,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,oBAAoB,CAAC;AAMlE;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,kFAAkF;IAClF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAAC;IAC1C,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,cAAc,CAAC;AAMzC;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,eAAe,GAAG,cAAc,CAAC;AAM7C;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;CACxB"}

package/dist/auth/dto.js.map

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

package/dist/auth/pending-mfa-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-mfa-store.js","sourceRoot":"","sources":["../../src/auth/pending-mfa-store.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;;;AAEH,6CAA0C;AAW1C,uEAAuE;AACvE,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAErC,wFAAwF;AACxF,MAAM,WAAW,GAAG,EAAE,CAAC;AAEvB;;;GAGG;AACH,MAAa,eAAe;IAIP;IAEA;IALF,OAAO,GAAG,IAAI,GAAG,EAAwB,CAAC;IAE3D,YACmB,QAAgB,cAAc;IAC/C,iEAAiE;IAChD,QAAsB,IAAI,CAAC,GAAG;QAF9B,UAAK,GAAL,KAAK,CAAyB;QAE9B,UAAK,GAAL,KAAK,CAAyB;IAC9C,CAAC;IAEJ;;;;OAIG;IACH,KAAK,CAAC,YAAoB,EAAE,QAAgB;QAC1C,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,MAAM,KAAK,GAAG,IAAA,yBAAW,EAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACvD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE;YACtB,YAAY;YACZ,QAAQ;YACR,WAAW,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,KAAK;SACvC,CAAC,CAAC;QACH,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,KAAa;QACnB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACjE,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACtC,4EAA4E;QAC5E,+EAA+E;QAC/E,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC3B,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACrC,IAAI,IAAI,CAAC,KAAK,EAAE,IAAI,KAAK,CAAC,WAAW;YAAE,OAAO,IAAI,CAAC;QACnD,OAAO,EAAE,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;IACxE,CAAC;IAED,mFAAmF;IAC3E,KAAK;QACX,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QACzB,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAC1C,IAAI,GAAG,IAAI,KAAK,CAAC,WAAW;gBAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;CACF;AAlDD,0CAkDC"}

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"}