@astram/guard 0.4.1 → 0.5.0

package/dist/authentication/mariadb-profile-writer.d.ts

@@ -0,0 +1,18 @@
+/**
+ * MariaDbProfileWriter — the framework-DEFAULT ProfileWriter (backs PATCH /account/profile). Updates
+ * ONLY the supplied columns on shield_app.users, then re-reads via MariaDbProfileResolver so the returned
+ * display profile has ONE source of truth (names, never UUIDs). Fail-closed: throws if the re-read is null.
+ */
+import type { Pool } from 'mariadb';
+import type { ProfileWriter } from '../auth/ports/profile-writer.js';
+import type { CurrentUserProfile } from '../auth/profile-resolver.js';
+export declare class MariaDbProfileWriter implements ProfileWriter {
+    private readonly pool;
+    private readonly resolver;
+    constructor(pool: Pool);
+    update(principalId: string, changes: {
+        name?: string;
+        email?: string;
+    }): Promise<CurrentUserProfile>;
+}
+//# sourceMappingURL=mariadb-profile-writer.d.ts.map

package/dist/authentication/mariadb-profile-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mariadb-profile-writer.d.ts","sourceRoot":"","sources":["../../src/authentication/mariadb-profile-writer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAOtE,qBAAa,oBAAqB,YAAW,aAAa;IAE5C,OAAO,CAAC,QAAQ,CAAC,IAAI;IADjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;gBACrB,IAAI,EAAE,IAAI;IAIjC,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC;CA0B3G"}

package/dist/authentication/mariadb-profile-writer.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MariaDbProfileWriter = void 0;
+const mariadb_profile_resolver_js_1 = require("./mariadb-profile-resolver.js");
+class MariaDbProfileWriter {
+    pool;
+    resolver;
+    constructor(pool) {
+        this.pool = pool;
+        this.resolver = new mariadb_profile_resolver_js_1.MariaDbProfileResolver(pool);
+    }
+    async update(principalId, changes) {
+        const sets = [];
+        const params = [];
+        if (changes.name !== undefined) {
+            sets.push('u_username = ?');
+            params.push(changes.name);
+        }
+        if (changes.email !== undefined) {
+            sets.push('u_email = ?');
+            params.push(changes.email);
+        }
+        if (sets.length > 0) {
+            params.push(principalId);
+            await this.pool.query(`UPDATE \`shield_app\`.\`users\` SET ${sets.join(', ')} WHERE u_uuid = ?`, params);
+        }
+        // Resolve the caller's active company so the re-read profile is tenant-correct.
+        const active = (await this.pool.query("SELECT cm_company_uuid FROM `shield_app`.`company_membership` WHERE cm_user_uuid = ? AND cm_is_active = 1 AND cm_status = 'active' LIMIT 1", [principalId]));
+        const tenantId = active[0]?.cm_company_uuid ?? '';
+        const profile = await this.resolver.resolve({ kind: 'user', id: principalId, tenantId, roleIds: [], isRoot: false });
+        if (profile === null)
+            throw new Error('profile_unavailable'); // fail-closed: never a partial write result
+        return profile;
+    }
+}
+exports.MariaDbProfileWriter = MariaDbProfileWriter;

package/dist/authentication/mariadb-recovery-code-store.d.ts

@@ -0,0 +1,47 @@
+/**
+ * MariaDbRecoveryCodeStore — the framework-DEFAULT RecoveryCodeStore (backs
+ * POST /account/mfa/recovery-codes/regenerate + recovery-code login), persisted in
+ * `shield_identity`.`mfa_recovery_code` (one row per Argon2-hashed one-time recovery
+ * code, PK `(mrc_principal_id, mrc_code_hash)`).
+ *
+ * The framework hands this store ALREADY-HASHED codes (Argon2), so `replaceAll` never
+ * sees the raw codes — it only wipes-then-inserts hashes. `consume` receives the RAW
+ * code the user presents; because Argon2 hashes are salted and NOT queryable by
+ * plaintext, it loads the principal's UNCONSUMED rows and verifies the raw code against
+ * each hash with the injected hasher until one matches, then atomically marks THAT row
+ * consumed (single-use). A conditional `UPDATE … WHERE mrc_consumed_at_ms IS NULL` with
+ * an `affectedRows === 1` race guard makes the mark single-winner: two concurrent
+ * consumes of the same code both verify, but only one wins the UPDATE; the loser treats
+ * it as already-consumed → `false`. Every query is parameterized (never string-built).
+ *
+ * SECURITY — never logs the raw code or a hash; a hash mismatch resolves to "not this
+ * code" (fail-closed), never a thrown error. A genuine store outage (the `query` call
+ * rejecting) propagates rather than being swallowed to `false`.
+ */
+import type { Pool } from 'mariadb';
+import type { PasswordHasher } from '@astram/core';
+import type { RecoveryCodeStore } from '../auth/ports/recovery-code-store.js';
+export declare class MariaDbRecoveryCodeStore implements RecoveryCodeStore {
+    private readonly pool;
+    /** The SAME Argon2id hasher the framework uses to hash the codes on enroll. */
+    private readonly hasher;
+    private readonly now;
+    constructor(pool: Pool, 
+    /** The SAME Argon2id hasher the framework uses to hash the codes on enroll. */
+    hasher: PasswordHasher, now?: () => number);
+    /**
+     * Replace the principal's entire recovery-code set with `codeHashes` (already
+     * Argon2-hashed). Wipes any prior codes first, then inserts the new batch. Passing
+     * an empty array simply wipes (used when MFA is disabled).
+     */
+    replaceAll(principalId: string, codeHashes: readonly string[]): Promise<void>;
+    /**
+     * Consume one of the principal's recovery codes by RAW value. Loads the unconsumed
+     * hashes, verifies the raw code against each, and on the first match atomically marks
+     * that row consumed (single-use, `affectedRows === 1` race guard). Returns `true` iff
+     * a code was matched AND won the consume; `false` for empty input, no match, an
+     * already-consumed code, or a lost race.
+     */
+    consume(principalId: string, rawCode: string): Promise<boolean>;
+}
+//# sourceMappingURL=mariadb-recovery-code-store.d.ts.map

package/dist/authentication/mariadb-recovery-code-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mariadb-recovery-code-store.d.ts","sourceRoot":"","sources":["../../src/authentication/mariadb-recovery-code-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAM9E,qBAAa,wBAAyB,YAAW,iBAAiB;IAE9D,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,+EAA+E;IAC/E,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAHH,IAAI,EAAE,IAAI;IAC3B,+EAA+E;IAC9D,MAAM,EAAE,cAAc,EACtB,GAAG,GAAE,MAAM,MAAiB;IAG/C;;;;OAIG;IACG,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBnF;;;;;;OAMG;IACG,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAqBtE"}

package/dist/authentication/mariadb-recovery-code-store.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MariaDbRecoveryCodeStore = void 0;
+class MariaDbRecoveryCodeStore {
+    pool;
+    hasher;
+    now;
+    constructor(pool, 
+    /** The SAME Argon2id hasher the framework uses to hash the codes on enroll. */
+    hasher, now = Date.now) {
+        this.pool = pool;
+        this.hasher = hasher;
+        this.now = now;
+    }
+    /**
+     * Replace the principal's entire recovery-code set with `codeHashes` (already
+     * Argon2-hashed). Wipes any prior codes first, then inserts the new batch. Passing
+     * an empty array simply wipes (used when MFA is disabled).
+     */
+    async replaceAll(principalId, codeHashes) {
+        await this.pool.query(`DELETE FROM \`shield_identity\`.\`mfa_recovery_code\` WHERE mrc_principal_id = ?`, [principalId]);
+        const createdAt = this.now();
+        for (const hash of codeHashes) {
+            await this.pool.query(`INSERT INTO \`shield_identity\`.\`mfa_recovery_code\`
+           (mrc_principal_id, mrc_code_hash, mrc_consumed_at_ms, mrc_created_at_ms)
+         VALUES (?, ?, NULL, ?)`, [principalId, hash, createdAt]);
+        }
+    }
+    /**
+     * Consume one of the principal's recovery codes by RAW value. Loads the unconsumed
+     * hashes, verifies the raw code against each, and on the first match atomically marks
+     * that row consumed (single-use, `affectedRows === 1` race guard). Returns `true` iff
+     * a code was matched AND won the consume; `false` for empty input, no match, an
+     * already-consumed code, or a lost race.
+     */
+    async consume(principalId, rawCode) {
+        if (typeof rawCode !== 'string' || rawCode.length === 0)
+            return false;
+        const rows = (await this.pool.query(`SELECT mrc_code_hash FROM \`shield_identity\`.\`mfa_recovery_code\`
+        WHERE mrc_principal_id = ? AND mrc_consumed_at_ms IS NULL`, [principalId]));
+        for (const row of rows) {
+            if (await this.hasher.verify(row.mrc_code_hash, rawCode)) {
+                const res = (await this.pool.query(`UPDATE \`shield_identity\`.\`mfa_recovery_code\`
+              SET mrc_consumed_at_ms = ?
+            WHERE mrc_principal_id = ? AND mrc_code_hash = ? AND mrc_consumed_at_ms IS NULL`, [this.now(), principalId, row.mrc_code_hash]));
+                // Single-use guard: only the UPDATE that flips NULL→consumed wins.
+                return res.affectedRows === 1;
+            }
+        }
+        return false;
+    }
+}
+exports.MariaDbRecoveryCodeStore = MariaDbRecoveryCodeStore;

package/dist/authentication/mariadb-reset-token-store.d.ts

@@ -0,0 +1,26 @@
+/**
+ * MariaDbResetTokenStore — the framework-DEFAULT ResetTokenStore (backs POST /auth/forgot-password
+ * + /auth/reset-password), persisted in `shield_identity`.`password_reset_token`. The framework
+ * hashes the raw reset token (SHA-256) BEFORE it reaches this store, so the store never sees the
+ * raw token — only its hash (the primary key).
+ *
+ * SINGLE-USE + TTL: `consume` returns the principal id IFF the token is both unexpired AND
+ * unconsumed, then atomically marks it consumed. It is a SELECT-then-conditional-UPDATE with an
+ * `affectedRows` race guard: two concurrent consumes of the same token both pass the SELECT, but
+ * only ONE wins the `UPDATE … WHERE prt_consumed_at_ms IS NULL` (affectedRows === 1); the loser
+ * (affectedRows === 0) is treated as already-consumed → `null`. Unknown/expired/already-consumed
+ * tokens all return `null` too — never a distinguishing throw (anti-enumeration). A genuine store
+ * outage (the `query` call rejecting) propagates rather than being swallowed to `null`. Every
+ * query is parameterized (never string-built); the token hash is never logged.
+ */
+import type { Pool } from 'mariadb';
+import type { ResetTokenStore } from '../auth/ports/reset-token-store.js';
+export declare class MariaDbResetTokenStore implements ResetTokenStore {
+    private readonly pool;
+    private readonly now;
+    constructor(pool: Pool, now?: () => number);
+    issue(principalId: string, tokenHash: string, expiresAtMs: number): Promise<void>;
+    consume(tokenHash: string): Promise<string | null>;
+    invalidateAllForPrincipal(principalId: string): Promise<void>;
+}
+//# sourceMappingURL=mariadb-reset-token-store.d.ts.map

package/dist/authentication/mariadb-reset-token-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mariadb-reset-token-store.d.ts","sourceRoot":"","sources":["../../src/authentication/mariadb-reset-token-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAM1E,qBAAa,sBAAuB,YAAW,eAAe;IAE1D,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBADH,IAAI,EAAE,IAAI,EACV,GAAG,GAAE,MAAM,MAAiB;IAGzC,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASjF,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA0BlD,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAUpE"}

package/dist/authentication/mariadb-reset-token-store.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MariaDbResetTokenStore = void 0;
+class MariaDbResetTokenStore {
+    pool;
+    now;
+    constructor(pool, now = Date.now) {
+        this.pool = pool;
+        this.now = now;
+    }
+    async issue(principalId, tokenHash, expiresAtMs) {
+        await this.pool.query(`INSERT INTO \`shield_identity\`.\`password_reset_token\`
+         (prt_token_hash, prt_principal_id, prt_expires_at_ms, prt_consumed_at_ms, prt_created_at_ms)
+       VALUES (?, ?, ?, NULL, ?)`, [tokenHash, principalId, expiresAtMs, this.now()]);
+    }
+    async consume(tokenHash) {
+        const now = this.now();
+        // 1) Find an unexpired, unconsumed token for this hash.
+        const rows = (await this.pool.query(`SELECT prt_principal_id
+         FROM \`shield_identity\`.\`password_reset_token\`
+        WHERE prt_token_hash = ? AND prt_consumed_at_ms IS NULL AND prt_expires_at_ms > ?
+        LIMIT 1`, [tokenHash, now]));
+        const principalId = rows[0]?.prt_principal_id;
+        if (principalId === undefined)
+            return null;
+        // 2) Atomically claim it (single-use). The `IS NULL` guard + affectedRows check means a
+        //    concurrent consume can never both succeed — the loser sees 0 rows and returns null.
+        const res = (await this.pool.query(`UPDATE \`shield_identity\`.\`password_reset_token\`
+          SET prt_consumed_at_ms = ?
+        WHERE prt_token_hash = ? AND prt_consumed_at_ms IS NULL`, [now, tokenHash]));
+        if (res.affectedRows !== 1)
+            return null; // lost the race → treat as consumed
+        return principalId;
+    }
+    async invalidateAllForPrincipal(principalId) {
+        // Burn every outstanding (unconsumed) token for the principal after a successful reset, so a
+        // second still-valid link cannot re-reset.
+        await this.pool.query(`UPDATE \`shield_identity\`.\`password_reset_token\`
+          SET prt_consumed_at_ms = ?
+        WHERE prt_principal_id = ? AND prt_consumed_at_ms IS NULL`, [this.now(), principalId]);
+    }
+}
+exports.MariaDbResetTokenStore = MariaDbResetTokenStore;

package/dist/authentication/mariadb-session-sweeper.d.ts

@@ -0,0 +1,33 @@
+/**
+ * MariaDbSessionSweeper — the framework-DEFAULT SessionSweeper (backs the best-effort
+ * calls from POST /account/change-password + /auth/reset-password), revoking a
+ * principal's durable sessions in `shield_identity`.`session` after a credential
+ * change.
+ *
+ *  - revokeAllForPrincipal → after a password RESET (kill every session).
+ *  - revokeOthersForPrincipal → after an authenticated CHANGE-password (kill every
+ *    session except the caller's current one, so the actor stays signed in).
+ *
+ * WHY WE ALSO DROP THE REDIS LIVENESS KEY: flipping the durable `session` row to
+ * 'revoked' makes the session non-rotatable (refresh is rejected), but an
+ * outstanding ACCESS token's per-request liveness is gated on the Redis key the
+ * `SessionTokenBinder` owns (see its SESSION-LIVENESS GATE in `resolve()`). The
+ * durable row alone does not reach that key, so a still-valid access token would
+ * survive until its TTL. To make revocation IMMEDIATE, we also drop the liveness
+ * key for each revoked session via `binder.unbindSession` — the SAME mechanism
+ * logout uses.
+ *
+ * The binder is passed in at construction time rather than DI-resolved here (this
+ * class is a plain adapter; wiring lives with the consumer).
+ */
+import type { Pool } from 'mariadb';
+import type { SessionSweeper } from '../auth/ports/session-sweeper.js';
+import type { SessionTokenBinder } from '../request-auth/session-token-binder.js';
+export declare class MariaDbSessionSweeper implements SessionSweeper {
+    private readonly pool;
+    private readonly binder;
+    constructor(pool: Pool, binder: SessionTokenBinder);
+    revokeAllForPrincipal(principalId: string): Promise<void>;
+    revokeOthersForPrincipal(principalId: string, keepSessionId: string): Promise<void>;
+}
+//# sourceMappingURL=mariadb-session-sweeper.d.ts.map

package/dist/authentication/mariadb-session-sweeper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mariadb-session-sweeper.d.ts","sourceRoot":"","sources":["../../src/authentication/mariadb-session-sweeper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAMlF,qBAAa,qBAAsB,YAAW,cAAc;IAExD,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,kBAAkB;IAGvC,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBzD,wBAAwB,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAmB1F"}

package/dist/authentication/mariadb-session-sweeper.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * MariaDbSessionSweeper — the framework-DEFAULT SessionSweeper (backs the best-effort
+ * calls from POST /account/change-password + /auth/reset-password), revoking a
+ * principal's durable sessions in `shield_identity`.`session` after a credential
+ * change.
+ *
+ *  - revokeAllForPrincipal → after a password RESET (kill every session).
+ *  - revokeOthersForPrincipal → after an authenticated CHANGE-password (kill every
+ *    session except the caller's current one, so the actor stays signed in).
+ *
+ * WHY WE ALSO DROP THE REDIS LIVENESS KEY: flipping the durable `session` row to
+ * 'revoked' makes the session non-rotatable (refresh is rejected), but an
+ * outstanding ACCESS token's per-request liveness is gated on the Redis key the
+ * `SessionTokenBinder` owns (see its SESSION-LIVENESS GATE in `resolve()`). The
+ * durable row alone does not reach that key, so a still-valid access token would
+ * survive until its TTL. To make revocation IMMEDIATE, we also drop the liveness
+ * key for each revoked session via `binder.unbindSession` — the SAME mechanism
+ * logout uses.
+ *
+ * The binder is passed in at construction time rather than DI-resolved here (this
+ * class is a plain adapter; wiring lives with the consumer).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MariaDbSessionSweeper = void 0;
+class MariaDbSessionSweeper {
+    pool;
+    binder;
+    constructor(pool, binder) {
+        this.pool = pool;
+        this.binder = binder;
+    }
+    async revokeAllForPrincipal(principalId) {
+        const rows = (await this.pool.query(`SELECT s_session_id
+         FROM \`shield_identity\`.\`session\`
+        WHERE s_principal_id = ? AND s_status = 'active'`, [principalId]));
+        await this.pool.query(`UPDATE \`shield_identity\`.\`session\`
+          SET s_status = 'revoked'
+        WHERE s_principal_id = ? AND s_status = 'active'`, [principalId]);
+        // Drop each revoked session's Redis liveness key so outstanding access tokens die
+        // immediately, not at their TTL.
+        for (const { s_session_id } of rows) {
+            await this.binder.unbindSession(s_session_id);
+        }
+    }
+    async revokeOthersForPrincipal(principalId, keepSessionId) {
+        const rows = (await this.pool.query(`SELECT s_session_id
+         FROM \`shield_identity\`.\`session\`
+        WHERE s_principal_id = ? AND s_status = 'active' AND s_session_id <> ?`, [principalId, keepSessionId]));
+        await this.pool.query(`UPDATE \`shield_identity\`.\`session\`
+          SET s_status = 'revoked'
+        WHERE s_principal_id = ? AND s_status = 'active' AND s_session_id <> ?`, [principalId, keepSessionId]);
+        // Only the OTHER sessions are unbound — the kept (current) session's liveness key
+        // is never touched, so the actor stays signed in after a change-password.
+        for (const { s_session_id } of rows) {
+            await this.binder.unbindSession(s_session_id);
+        }
+    }
+}
+exports.MariaDbSessionSweeper = MariaDbSessionSweeper;

package/dist/identity/auth-facts.controller.d.ts

@@ -0,0 +1,24 @@
+/**
+ * AuthFactsController — the framework-DEFAULT `/identity/auth-facts` + `/identity/permissions-version`
+ * endpoints backing the frontend's permission-gated nav (the SDK's fact projection). Both are
+ * `@Public()` at the route level but SELF-SCOPED: principalId + tenantId come ONLY from the resolved
+ * bearer-token Principal (never a query/body param). Missing/invalid token → 401; an authorization
+ * store outage → 503 (never swallowed into an empty projection / fabricated version — that would
+ * fail-OPEN by letting a stale/empty view read as authoritative).
+ *
+ * FRAMEWORK-OWNED: mounted by the auth surface when `auth: true`; the consumer implements nothing.
+ */
+import type { SessionTokenBinder } from '../request-auth/session-token-binder.js';
+import { type AuthFactProjection, type MariaDbPermissionFactsAdapter } from './permission-facts.adapter.js';
+export declare class AuthFactsController {
+    private readonly tokenBinder;
+    private readonly facts;
+    constructor(tokenBinder: SessionTokenBinder | undefined, facts: MariaDbPermissionFactsAdapter | undefined);
+    getAuthFacts(authorization?: string): Promise<AuthFactProjection>;
+    getPermissionsVersion(authorization?: string): Promise<{
+        version: number;
+    }>;
+    /** Resolve the bearer token → the caller's own Principal, or throw a generic 401. */
+    private authenticate;
+}
+//# sourceMappingURL=auth-facts.controller.d.ts.map

package/dist/identity/auth-facts.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-facts.controller.d.ts","sourceRoot":"","sources":["../../src/identity/auth-facts.controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAGlF,OAAO,EAAiC,KAAK,kBAAkB,EAAE,KAAK,6BAA6B,EAAE,MAAM,+BAA+B,CAAC;AAE3I,qBACa,mBAAmB;IAEqB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK;gBADD,WAAW,EAAE,kBAAkB,GAAG,SAAS,EAC/C,KAAK,EAAE,6BAA6B,GAAG,SAAS;IAK1G,YAAY,CAA2B,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAiB3F,qBAAqB,CAA2B,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAgB3G,qFAAqF;YACvE,YAAY;CAU3B"}

package/dist/identity/auth-facts.controller.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * AuthFactsController — the framework-DEFAULT `/identity/auth-facts` + `/identity/permissions-version`
+ * endpoints backing the frontend's permission-gated nav (the SDK's fact projection). Both are
+ * `@Public()` at the route level but SELF-SCOPED: principalId + tenantId come ONLY from the resolved
+ * bearer-token Principal (never a query/body param). Missing/invalid token → 401; an authorization
+ * store outage → 503 (never swallowed into an empty projection / fabricated version — that would
+ * fail-OPEN by letting a stale/empty view read as authoritative).
+ *
+ * FRAMEWORK-OWNED: mounted by the auth surface when `auth: true`; the consumer implements nothing.
+ */
+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 __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthFactsController = void 0;
+const common_1 = require("@nestjs/common");
+const classification_decorator_js_1 = require("../enforcement/classification.decorator.js");
+const tokens_js_1 = require("../request-auth/tokens.js");
+const request_principal_js_1 = require("../request-auth/request-principal.js");
+const tokens_js_2 = require("../auth/tokens.js");
+const permission_facts_adapter_js_1 = require("./permission-facts.adapter.js");
+let AuthFactsController = class AuthFactsController {
+    tokenBinder;
+    facts;
+    constructor(tokenBinder, facts) {
+        this.tokenBinder = tokenBinder;
+        this.facts = facts;
+    }
+    async getAuthFacts(authorization) {
+        const principal = await this.authenticate(authorization);
+        if (this.facts === undefined || this.facts === null) {
+            throw new common_1.HttpException({ error: 'authorization_unavailable' }, common_1.HttpStatus.SERVICE_UNAVAILABLE);
+        }
+        try {
+            return await this.facts.projectFor(principal.id, principal.tenantId, principal.isRoot);
+        }
+        catch (err) {
+            if (err instanceof permission_facts_adapter_js_1.AuthorizationUnavailableError) {
+                throw new common_1.HttpException({ error: 'authorization_unavailable' }, common_1.HttpStatus.SERVICE_UNAVAILABLE);
+            }
+            throw err;
+        }
+    }
+    async getPermissionsVersion(authorization) {
+        const principal = await this.authenticate(authorization);
+        if (this.facts === undefined || this.facts === null) {
+            throw new common_1.HttpException({ error: 'authorization_unavailable' }, common_1.HttpStatus.SERVICE_UNAVAILABLE);
+        }
+        try {
+            const version = await this.facts.currentVersionFor(principal.id, principal.tenantId);
+            return { version };
+        }
+        catch (err) {
+            if (err instanceof permission_facts_adapter_js_1.AuthorizationUnavailableError) {
+                throw new common_1.HttpException({ error: 'authorization_unavailable' }, common_1.HttpStatus.SERVICE_UNAVAILABLE);
+            }
+            throw err;
+        }
+    }
+    /** Resolve the bearer token → the caller's own Principal, or throw a generic 401. */
+    async authenticate(authorization) {
+        if (this.tokenBinder === undefined || this.tokenBinder === null) {
+            throw new common_1.HttpException({ error: 'unauthorized' }, common_1.HttpStatus.UNAUTHORIZED);
+        }
+        const principal = await (0, request_principal_js_1.resolveRequestPrincipal)(authorization, this.tokenBinder);
+        if (principal === null) {
+            throw new common_1.HttpException({ error: 'unauthorized' }, common_1.HttpStatus.UNAUTHORIZED);
+        }
+        return principal;
+    }
+};
+exports.AuthFactsController = AuthFactsController;
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Get)('auth-facts'),
+    __param(0, (0, common_1.Headers)('authorization')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], AuthFactsController.prototype, "getAuthFacts", null);
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Get)('permissions-version'),
+    __param(0, (0, common_1.Headers)('authorization')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], AuthFactsController.prototype, "getPermissionsVersion", null);
+exports.AuthFactsController = AuthFactsController = __decorate([
+    (0, common_1.Controller)('identity'),
+    __param(0, (0, common_1.Optional)()),
+    __param(0, (0, common_1.Inject)(tokens_js_1.SHIELD_SESSION_TOKEN_BINDER)),
+    __param(1, (0, common_1.Optional)()),
+    __param(1, (0, common_1.Inject)(tokens_js_2.SHIELD_PERMISSION_FACTS)),
+    __metadata("design:paramtypes", [Object, Object])
+], AuthFactsController);

package/dist/identity/identity-actions.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The fixed action vocabulary + module key for the framework's @astram/identity objects.
+ * Engine ObjectTypes carry no action list, so actions are synthesized here — the ONE source
+ * the module-registry bridge derives from. Permission keys are `identity:<typeKey>:<action>`.
+ * (Ported from astram3. `cross_tenant_grant` gets its own override — see below — every other
+ * type uses the CRUD verbs.)
+ */
+export declare const MODULE_KEY = "identity";
+export declare const IDENTITY_ACTIONS: readonly ["read", "create", "update", "delete"];
+export type IdentityAction = (typeof IDENTITY_ACTIONS)[number];
+/**
+ * `cross_tenant_grant`'s action vocabulary — NOT the CRUD verbs above. This is a
+ * framework-owned, authority-only object type (never CRUD'd through the RecordEngine);
+ * its three actions are the who-may-grant lifecycle questions the app's `authorize`
+ * closure answers for `CrossTenantGrantWriter` (offer -> 'share', accept -> 'accept',
+ * revoke -> 'revoke'). Mirrors astram3's `authz/actions.ts`'s `CROSS_TENANT_GRANT_ACTIONS`.
+ */
+export declare const CROSS_TENANT_GRANT_ACTIONS: readonly ["share", "accept", "revoke"];
+export type CrossTenantGrantAction = (typeof CROSS_TENANT_GRANT_ACTIONS)[number];
+/** The action vocabulary for `typeKey` — the per-type override if one exists, else the default. */
+export declare function actionsFor(typeKey: string): readonly string[];
+//# sourceMappingURL=identity-actions.d.ts.map

package/dist/identity/identity-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-actions.d.ts","sourceRoot":"","sources":["../../src/identity/identity-actions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,aAAa,CAAC;AACrC,eAAO,MAAM,gBAAgB,iDAAkD,CAAC;AAChF,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/D;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,wCAAyC,CAAC;AACjF,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,CAAC,CAAC;AAUjF,mGAAmG;AACnG,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAE7D"}

package/dist/identity/identity-actions.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CROSS_TENANT_GRANT_ACTIONS = exports.IDENTITY_ACTIONS = exports.MODULE_KEY = void 0;
+exports.actionsFor = actionsFor;
+/**
+ * The fixed action vocabulary + module key for the framework's @astram/identity objects.
+ * Engine ObjectTypes carry no action list, so actions are synthesized here — the ONE source
+ * the module-registry bridge derives from. Permission keys are `identity:<typeKey>:<action>`.
+ * (Ported from astram3. `cross_tenant_grant` gets its own override — see below — every other
+ * type uses the CRUD verbs.)
+ */
+exports.MODULE_KEY = 'identity';
+exports.IDENTITY_ACTIONS = ['read', 'create', 'update', 'delete'];
+/**
+ * `cross_tenant_grant`'s action vocabulary — NOT the CRUD verbs above. This is a
+ * framework-owned, authority-only object type (never CRUD'd through the RecordEngine);
+ * its three actions are the who-may-grant lifecycle questions the app's `authorize`
+ * closure answers for `CrossTenantGrantWriter` (offer -> 'share', accept -> 'accept',
+ * revoke -> 'revoke'). Mirrors astram3's `authz/actions.ts`'s `CROSS_TENANT_GRANT_ACTIONS`.
+ */
+exports.CROSS_TENANT_GRANT_ACTIONS = ['share', 'accept', 'revoke'];
+/**
+ * Per-type action-vocabulary override. Every type not listed here defaults to
+ * {@link IDENTITY_ACTIONS} (the CRUD verbs).
+ */
+const ACTIONS_BY_TYPE = {
+    cross_tenant_grant: exports.CROSS_TENANT_GRANT_ACTIONS,
+};
+/** The action vocabulary for `typeKey` — the per-type override if one exists, else the default. */
+function actionsFor(typeKey) {
+    return ACTIONS_BY_TYPE[typeKey] ?? exports.IDENTITY_ACTIONS;
+}

package/dist/identity/module-registry.bridge.d.ts

@@ -0,0 +1,4 @@
+import type { ModuleRegistry } from '@astram/core';
+import type { ObjectTypeInput } from '@astram/engine';
+export declare function buildIdentityModuleRegistry(inputs: readonly ObjectTypeInput[]): ModuleRegistry;
+//# sourceMappingURL=module-registry.bridge.d.ts.map

package/dist/identity/module-registry.bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-registry.bridge.d.ts","sourceRoot":"","sources":["../../src/identity/module-registry.bridge.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,cAAc,EAIf,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAc,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAQlE,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,GAAG,cAAc,CA4B9F"}

package/dist/identity/module-registry.bridge.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildIdentityModuleRegistry = buildIdentityModuleRegistry;
+/**
+ * Bridge: engine ObjectTypes → a populated core ModuleRegistry. Ported from astram3 (framework
+ * now owns identity). Engine ObjectTypes describe physical tables; core's gates + the
+ * permission-facts projection need object types + ACTIONS + tiers + planes. ObjectTypes carry no
+ * action list, so we synthesize per-type actions (actionsFor). Every action is `gated` — nothing
+ * open unless reclassified. `register()` throws on duplicate typeKey/permissionKey.
+ */
+const core_1 = require("@astram/core");
+const engine_1 = require("@astram/engine");
+const identity_actions_js_1 = require("./identity-actions.js");
+function toObjectType(input) {
+    return typeof input === 'function' ? (0, engine_1.reflectObjectType)(input) : input;
+}
+function buildIdentityModuleRegistry(inputs) {
+    const regs = inputs.map(toObjectType);
+    const objectTypes = regs.map((r) => {
+        const a = r.access ?? {};
+        const access = {
+            ...(a.owned !== undefined ? { owned: a.owned } : {}),
+            ...(a.tenantScoped !== undefined ? { tenantScoped: a.tenantScoped } : {}),
+            ...(a.system !== undefined ? { system: a.system } : {}),
+        };
+        return {
+            typeKey: r.typeKey,
+            label: r.typeKey,
+            fields: r.fields.map((f) => ({ key: f.key, label: f.key })),
+            ...(Object.keys(access).length > 0 ? { access } : {}),
+        };
+    });
+    const actions = regs.flatMap((r) => (0, identity_actions_js_1.actionsFor)(r.typeKey).map((actionKey) => ({
+        actionKey,
+        typeKey: r.typeKey,
+        tier: 'gated',
+        plane: r.access?.plane ?? 'data',
+    })));
+    const metadata = { moduleKey: identity_actions_js_1.MODULE_KEY, objectTypes, actions };
+    const registry = (0, core_1.createModuleRegistry)();
+    registry.register(metadata);
+    return registry;
+}

package/dist/identity/permission-facts.adapter.d.ts

@@ -0,0 +1,47 @@
+/**
+ * MariaDbPermissionFactsAdapter — the framework-DEFAULT source of a caller's coarse permission
+ * facts, backing `GET /identity/auth-facts` + `/identity/permissions-version`. Reads role ids from
+ * the caller's active in-effect postings (`shield_app`), the granted permission keys for those
+ * roles (`shield_authz.role_permission`), and the per-tenant permission version
+ * (`shield_authz.authz_permission_version`). Projects to `{ action, allowed:true }` facts (an
+ * absent fact is the fail-closed deny). A store outage THROWS AuthorizationUnavailableError —
+ * never a fabricated empty projection (that would silently read as "you have no grants").
+ */
+import type { Pool } from 'mariadb';
+export interface AuthFactDto {
+    readonly action: string;
+    readonly allowed: boolean;
+    readonly resource?: string;
+    readonly reasonCode?: string;
+}
+export interface AuthFactProjection {
+    readonly principalId: string;
+    readonly facts: readonly AuthFactDto[];
+    readonly projectedAt: number;
+    readonly permissionsVersion?: number;
+}
+/** A store/dependency outage while computing facts — the controller maps this to 503. */
+export declare class AuthorizationUnavailableError extends Error {
+    constructor(message?: string);
+}
+export declare class MariaDbPermissionFactsAdapter {
+    private readonly pool;
+    private readonly listActions;
+    private readonly controlPlaneKeys;
+    private readonly now;
+    constructor(pool: Pool, listActions: () => readonly string[], controlPlaneKeys: readonly string[], now?: () => number);
+    projectFor(principalId: string, tenantId: string, isRoot: boolean): Promise<AuthFactProjection>;
+    currentVersionFor(_principalId: string, tenantId: string): Promise<number>;
+    private readRoleIdsForTenant;
+    private readGrantKeys;
+    private readVersion;
+    /**
+     * Expand wildcard grant keys against the registry's declared actions:
+     *   'identity' / 'identity:*'      → every 'identity:' action
+     *   'identity:company:*'           → every 'identity:company:<action>'
+     * Exact keys pass through. Bounded to listActions() so a wildcard can never grant an
+     * action that does not exist.
+     */
+    private expandGrantKeys;
+}
+//# sourceMappingURL=permission-facts.adapter.d.ts.map