@astram/identity 0.1.2 → 0.2.1

package/dist/features/audit/directory-label-resolver.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DirectoryLabelResolver = void 0;
+const APP = 'shield_app';
+/**
+ * The id->human-label chokepoint (ADR-0012, design §2.2). A deleted/unknown
+ * entity resolves to a FALLBACK label (never the id); a directory OUTAGE throws
+ * (fail-closed — a transient must not masquerade as a deletion).
+ */
+class DirectoryLabelResolver {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async resolve(kind, id, _tenantId) {
+        if (!id)
+            return this.fallback(kind);
+        switch (kind) {
+            case 'principal': {
+                const rows = (await this.db.query(`SELECT u_username AS label FROM \`${APP}\`.\`users\` WHERE u_uuid = ? LIMIT 1`, [id]));
+                return rows[0]?.label ?? this.fallback(kind);
+            }
+            case 'tenant': {
+                const rows = (await this.db.query(`SELECT c_name AS label FROM \`${APP}\`.\`companies\` WHERE c_uuid = ? LIMIT 1`, [id]));
+                return rows[0]?.label ?? this.fallback(kind);
+            }
+            case 'role': {
+                const rows = (await this.db.query(`SELECT r_name AS label FROM \`${APP}\`.\`roles\` WHERE r_uuid = ? LIMIT 1`, [id]));
+                return rows[0]?.label ?? this.fallback(kind);
+            }
+            default:
+                // service_account / object_type / permission not shown in v1 columns → safe fallback.
+                return '(unknown)';
+        }
+    }
+    fallback(kind) {
+        if (kind === 'principal')
+            return 'Deleted user';
+        if (kind === 'tenant')
+            return 'Deleted tenant';
+        if (kind === 'role')
+            return 'Deleted role';
+        return '(unknown)';
+    }
+}
+exports.DirectoryLabelResolver = DirectoryLabelResolver;

package/dist/features/audit/mariadb-audit-reader.d.ts

@@ -0,0 +1,46 @@
+import type { AuditReader, AuditEvent } from '@astram/core';
+export interface AuditQueryable {
+    query(sql: string, params?: readonly unknown[]): Promise<unknown>;
+}
+/**
+ * The astram3 AuditReader over `shield_audit.audit_log` (design §2.2). Newest-first,
+ * tenant-scoped unless the root sentinel `'*'` is passed (the service sets that
+ * ONLY for a root). `[]` on no match (normal); THROWS on a store failure
+ * (fail-closed — never masks an outage as empty).
+ */
+export declare class MariaDbAuditReader implements AuditReader {
+    private readonly db;
+    private readonly schema;
+    constructor(db: AuditQueryable, opts?: {
+        schema?: string;
+    });
+    read(query: {
+        tenantId: string;
+        type?: AuditEvent['type'];
+        actorId?: string;
+        limit?: number;
+        offset?: number;
+        before?: string;
+    }): Promise<readonly AuditEvent[]>;
+    /**
+     * `SELECT COUNT(*)` over the SAME tenant/type/actorId scope `read` applies — used by the
+     * viewer for numbered (offset+total) pagination. Deliberately excludes `before` and any
+     * limit/offset (a total must not be windowed). Tenant scope is built by the SAME helper
+     * `read` uses, so the count can never widen past the page's tenant boundary (fail-closed
+     * isolation — see security invariant #4). THROWS on a store failure (fail-closed).
+     */
+    count(query: {
+        tenantId: string;
+        type?: string;
+        actorId?: string;
+    }): Promise<number>;
+    /**
+     * Shared tenant/type/actorId scope-building for `read` and `count`. Both MUST resolve the
+     * same scope for the same query shape — a count that diverged from its page's WHERE would
+     * leak another tenant's total (invariant #4: tenant isolation). `before`/`limit`/`offset`
+     * are NOT part of this shared scope — they stay in `read` only.
+     */
+    private buildScopeClause;
+    private toEvent;
+}
+//# sourceMappingURL=mariadb-audit-reader.d.ts.map

package/dist/features/audit/mariadb-audit-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mariadb-audit-reader.d.ts","sourceRoot":"","sources":["../../../src/features/audit/mariadb-audit-reader.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE5D,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE;AAgBD;;;;;GAKG;AACH,qBAAa,kBAAmB,YAAW,WAAW;IACpD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAiB;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,EAAE,EAAE,cAAc,EAAE,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO;IAKxD,IAAI,CAAC,KAAK,EAAE;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;QAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC;IAgClC;;;;;;OAMG;IACG,KAAK,CAAC,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAY1F;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAwBxB,OAAO,CAAC,OAAO;CA+BhB"}

package/dist/features/audit/mariadb-audit-reader.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MariaDbAuditReader = void 0;
+const DEFAULT_SCHEMA = 'shield_audit';
+const ALL_TENANTS = '*';
+/**
+ * The astram3 AuditReader over `shield_audit.audit_log` (design §2.2). Newest-first,
+ * tenant-scoped unless the root sentinel `'*'` is passed (the service sets that
+ * ONLY for a root). `[]` on no match (normal); THROWS on a store failure
+ * (fail-closed — never masks an outage as empty).
+ */
+class MariaDbAuditReader {
+    db;
+    schema;
+    constructor(db, opts = {}) {
+        this.db = db;
+        this.schema = opts.schema ?? DEFAULT_SCHEMA;
+    }
+    async read(query) {
+        const { where, params } = this.buildScopeClause(query);
+        if (query.before !== undefined) {
+            const beforeMs = Number(query.before);
+            if (Number.isFinite(beforeMs)) {
+                where.push('al_occurred_at_ms < ?');
+                params.push(beforeMs);
+            }
+        }
+        const whereSql = where.length > 0 ? ` WHERE ${where.join(' AND ')}` : '';
+        let limitOffsetSql = '';
+        if (query.limit !== undefined) {
+            params.push(query.limit);
+            limitOffsetSql = ' LIMIT ?';
+            if (query.offset !== undefined) {
+                params.push(query.offset);
+                limitOffsetSql += ' OFFSET ?';
+            }
+        }
+        const rows = (await this.db.query(`SELECT al_type, al_occurred_at_ms, al_actor_id, al_tenant_id,` +
+            `       al_action_key, al_attributes_json` +
+            ` FROM \`${this.schema}\`.\`audit_log\`` +
+            `${whereSql} ORDER BY al_occurred_at_ms DESC${limitOffsetSql}`, params));
+        return rows.map((r) => this.toEvent(r));
+    }
+    /**
+     * `SELECT COUNT(*)` over the SAME tenant/type/actorId scope `read` applies — used by the
+     * viewer for numbered (offset+total) pagination. Deliberately excludes `before` and any
+     * limit/offset (a total must not be windowed). Tenant scope is built by the SAME helper
+     * `read` uses, so the count can never widen past the page's tenant boundary (fail-closed
+     * isolation — see security invariant #4). THROWS on a store failure (fail-closed).
+     */
+    async count(query) {
+        const { where, params } = this.buildScopeClause(query);
+        const whereSql = where.length > 0 ? ` WHERE ${where.join(' AND ')}` : '';
+        const rows = (await this.db.query(`SELECT COUNT(*) AS n FROM \`${this.schema}\`.\`audit_log\`${whereSql}`, params));
+        return Number(rows[0]?.n ?? 0);
+    }
+    /**
+     * Shared tenant/type/actorId scope-building for `read` and `count`. Both MUST resolve the
+     * same scope for the same query shape — a count that diverged from its page's WHERE would
+     * leak another tenant's total (invariant #4: tenant isolation). `before`/`limit`/`offset`
+     * are NOT part of this shared scope — they stay in `read` only.
+     */
+    buildScopeClause(query) {
+        const where = [];
+        const params = [];
+        if (query.tenantId !== ALL_TENANTS) {
+            where.push('al_tenant_id = ?');
+            params.push(query.tenantId);
+        }
+        // `query.type` carries the ACTION-KEY filter from the service (al_type is always
+        // 'authentication'; we filter/label by al_action_key — design §3.2).
+        if (query.type !== undefined) {
+            where.push('al_action_key = ?');
+            params.push(query.type);
+        }
+        if (query.actorId !== undefined) {
+            where.push('al_actor_id = ?');
+            params.push(query.actorId);
+        }
+        return { where, params };
+    }
+    toEvent(r) {
+        let attributes = {};
+        const rawAttrs = r.al_attributes_json;
+        if (rawAttrs && typeof rawAttrs === 'object' && !Array.isArray(rawAttrs)) {
+            // The mariadb driver auto-parses a JSON column → already an object.
+            attributes = rawAttrs;
+        }
+        else if (typeof rawAttrs === 'string' && rawAttrs.length > 0) {
+            // Defensive: a driver/config that returns the raw JSON string.
+            try {
+                const parsed = JSON.parse(rawAttrs);
+                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    attributes = parsed;
+                }
+            }
+            catch {
+                attributes = {};
+            }
+        }
+        // `action` is the framework `Action` type; the viewer only reads its key. The spec's
+        // first test asserts `events[0].action === 'mfa.recovery_used'` (a bare string), so set
+        // `action` to the action-key STRING here. (Design note: downstream AuditReadService reads
+        // `action.key` OR a bare string — Task 3 handles both. For THIS task, satisfy the test:
+        // set `action` to the raw action-key string.)
+        return {
+            type: r.al_type,
+            occurredAtMs: Number(r.al_occurred_at_ms),
+            actorId: r.al_actor_id,
+            tenantId: r.al_tenant_id,
+            ...(r.al_action_key ? { action: r.al_action_key } : {}),
+            attributes,
+        };
+    }
+}
+exports.MariaDbAuditReader = MariaDbAuditReader;

package/dist/features/authz/access-bundle-reconcile.job.d.ts

@@ -0,0 +1,35 @@
+import type { Pool } from 'mariadb';
+import type { AccessBundleSpec } from '@astram/engine';
+/** The outcome of one reconcile pass. */
+export interface AccessBundleReconcileReport {
+    readonly added: number;
+    readonly updated: number;
+    readonly orphaned: number;
+    readonly skippedKeys: readonly string[];
+}
+/**
+ * Reconciles the developer-declared `AccessBundleSpec[]` (from
+ * `ENGINE_ALL_ACCESS_BUNDLES`) into `shield_authz.access_bundle` (+ `_permission`),
+ * mirroring `catalog-reconcile.job.ts`.
+ *
+ * Runs AFTER the permission catalog reconcile so the live catalog exists to validate
+ * against. For each spec: filter its `permissionKeys` down to keys that are ACTIVE in
+ * `shield_authz.permission`; `console.warn` the skipped (unknown) ones (fail-loud — a
+ * mis-declared bundle is a bug, not a silent ghost-grant); upsert the bundle + sync its
+ * validated keys. Then orphan-mark (NEVER delete) any bundle in the table whose
+ * `(module, key)` is not in the declared set.
+ *
+ * Timestamp is supplied by the caller (keeps the pass deterministic).
+ */
+export declare class AccessBundleReconcileJob {
+    private readonly pool;
+    private readonly bundles;
+    private readonly store;
+    private running;
+    constructor(pool: Pool, bundles: readonly AccessBundleSpec[]);
+    /** Idempotent single pass. Guarded so overlapping ticks don't double-run. */
+    runOnce(_nowIso: string): Promise<AccessBundleReconcileReport>;
+    /** The set of permission keys that are ACTIVE in the live catalog. */
+    private loadActivePermissionKeys;
+}
+//# sourceMappingURL=access-bundle-reconcile.job.d.ts.map

package/dist/features/authz/access-bundle-reconcile.job.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-bundle-reconcile.job.d.ts","sourceRoot":"","sources":["../../../src/features/authz/access-bundle-reconcile.job.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAKvD,yCAAyC;AACzC,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,wBAAwB;IAKjC,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,OAAO,CAAS;gBAGL,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,SAAS,gBAAgB,EAAE;IAKvD,6EAA6E;IACvE,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,2BAA2B,CAAC;IAuDpE,sEAAsE;YACxD,wBAAwB;CAMvC"}

package/dist/features/authz/access-bundle-reconcile.job.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccessBundleReconcileJob = void 0;
+const access_bundle_store_js_1 = require("./access-bundle-store.js");
+const AUTHZ = 'shield_authz';
+/**
+ * Reconciles the developer-declared `AccessBundleSpec[]` (from
+ * `ENGINE_ALL_ACCESS_BUNDLES`) into `shield_authz.access_bundle` (+ `_permission`),
+ * mirroring `catalog-reconcile.job.ts`.
+ *
+ * Runs AFTER the permission catalog reconcile so the live catalog exists to validate
+ * against. For each spec: filter its `permissionKeys` down to keys that are ACTIVE in
+ * `shield_authz.permission`; `console.warn` the skipped (unknown) ones (fail-loud — a
+ * mis-declared bundle is a bug, not a silent ghost-grant); upsert the bundle + sync its
+ * validated keys. Then orphan-mark (NEVER delete) any bundle in the table whose
+ * `(module, key)` is not in the declared set.
+ *
+ * Timestamp is supplied by the caller (keeps the pass deterministic).
+ */
+class AccessBundleReconcileJob {
+    pool;
+    bundles;
+    store;
+    running = false;
+    constructor(pool, bundles) {
+        this.pool = pool;
+        this.bundles = bundles;
+        this.store = new access_bundle_store_js_1.AccessBundleStore(pool);
+    }
+    /** Idempotent single pass. Guarded so overlapping ticks don't double-run. */
+    async runOnce(_nowIso) {
+        if (this.running) {
+            return { added: 0, updated: 0, orphaned: 0, skippedKeys: [] };
+        }
+        this.running = true;
+        try {
+            const activeKeys = await this.loadActivePermissionKeys();
+            let added = 0;
+            let updated = 0;
+            const skippedKeys = [];
+            for (const spec of this.bundles) {
+                const known = [];
+                for (const key of spec.permissionKeys) {
+                    if (activeKeys.has(key))
+                        known.push(key);
+                    else
+                        skippedKeys.push(key);
+                }
+                const outcome = await this.store.upsertBundle(spec);
+                if (outcome === 'inserted')
+                    added++;
+                else if (outcome === 'updated')
+                    updated++;
+                const uuid = await this.store.resolveBundleUuid(spec.module, spec.key);
+                if (uuid)
+                    await this.store.syncBundlePermissions(uuid, known);
+            }
+            // Orphan-mark bundles present in the table but no longer declared.
+            const declared = new Set(this.bundles.map((b) => `${b.module}:${b.key}`));
+            const present = await this.store.listBundles();
+            const toOrphan = present
+                .filter((b) => b.status === 'active' && !declared.has(`${b.module}:${b.key}`))
+                .map((b) => [b.module, b.key]);
+            await this.store.markOrphaned(toOrphan);
+            const orphaned = toOrphan.length;
+            if (skippedKeys.length > 0) {
+                console.warn(`[access-bundle] SKIPPED ${skippedKeys.length} unknown permission key(s) ` +
+                    `(not in the active catalog): ${[...new Set(skippedKeys)].join(', ')}`);
+            }
+            console.log(`[access-bundle] reconcile: +${added} ~${updated} -${orphaned} ` +
+                `(${skippedKeys.length} skipped)`);
+            return { added, updated, orphaned, skippedKeys };
+        }
+        finally {
+            this.running = false;
+        }
+    }
+    /** The set of permission keys that are ACTIVE in the live catalog. */
+    async loadActivePermissionKeys() {
+        const rows = (await this.pool.query(`SELECT perm_key FROM \`${AUTHZ}\`.\`permission\` WHERE perm_status = 'active'`));
+        return new Set(rows.map((r) => r.perm_key));
+    }
+}
+exports.AccessBundleReconcileJob = AccessBundleReconcileJob;

package/dist/features/authz/access-bundle-store.d.ts

@@ -0,0 +1,65 @@
+import type { Pool } from 'mariadb';
+import type { AccessBundleSpec } from '@astram/engine';
+/** A row from `shield_authz.access_bundle`, resolved to camelCase. */
+export interface AccessBundleRow {
+    readonly uuid: string;
+    readonly key: string;
+    readonly module: string;
+    readonly label: string;
+    readonly description: string | null;
+    readonly status: 'active' | 'orphaned';
+}
+/**
+ * Raw-SQL (parameterized, NO ORM) CRUD over `shield_authz.access_bundle` +
+ * `access_bundle_permission`, mirroring `mariadb-catalog-store.ts`.
+ *
+ * All identity is resolved by BUSINESS KEY (`(ab_module, ab_key)`) — bundle UUIDs are
+ * generated per-DB and are NEVER hard-coded or assumed by the caller.
+ */
+export declare class AccessBundleStore {
+    private readonly pool;
+    constructor(pool: Pool);
+    /** All bundles (active + orphaned), for the reconciler's declared-vs-present diff. */
+    listBundles(): Promise<AccessBundleRow[]>;
+    /** Resolve a bundle's UUID by its business key. `null` when absent. */
+    resolveBundleUuid(module: string, key: string): Promise<string | null>;
+    /**
+     * Resolve an ACTIVE bundle (by its `key`, unique-per-module) to its atomic permission
+     * keys. Returns `null` when no active bundle matches the key (unknown / orphaned) so the
+     * caller can raise `BadKeyError`. Bundle `key` alone is the admin-facing identifier;
+     * there is exactly one active bundle per key across the identity module today, so the
+     * lookup is by `ab_key` + `ab_status='active'`.
+     */
+    resolveActiveBundleKeys(bundleKey: string): Promise<readonly string[] | null>;
+    /**
+     * All ACTIVE bundles with their resolved atomic key sets, for the grant-admin list API.
+     * NEVER exposes `ab_uuid` — the admin surface identifies a bundle by its `key`.
+     */
+    listActiveBundlesWithKeys(): Promise<Array<{
+        key: string;
+        module: string;
+        label: string;
+        description?: string;
+        permissionKeys: string[];
+    }>>;
+    /**
+     * Insert-or-update a bundle by `(ab_module, ab_key)`. Sets status back to 'active'
+     * (a re-declared bundle that had been orphaned is revived). Returns:
+     * - `'inserted'` — a new row was created,
+     * - `'updated'`  — an existing row's label/description/status actually changed,
+     * - `'unchanged'` — the row already matched (idempotent no-op).
+     */
+    upsertBundle(spec: AccessBundleSpec): Promise<'inserted' | 'updated' | 'unchanged'>;
+    /**
+     * Sync a bundle's atomic key set to exactly `keys`: delete rows not in the set,
+     * insert the missing ones. Idempotent — a re-sync with the same set is a no-op.
+     */
+    syncBundlePermissions(bundleUuid: string, keys: readonly string[]): Promise<void>;
+    /**
+     * Mark bundles whose `(module, key)` is NOT in the declared set as orphaned
+     * (never deleted — a granted role may reference it). `modKeysNotDeclared` is the
+     * list of `[module, key]` pairs to orphan.
+     */
+    markOrphaned(modKeysNotDeclared: ReadonlyArray<readonly [string, string]>): Promise<void>;
+}
+//# sourceMappingURL=access-bundle-store.d.ts.map

package/dist/features/authz/access-bundle-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-bundle-store.d.ts","sourceRoot":"","sources":["../../../src/features/authz/access-bundle-store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAIvD,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,UAAU,CAAC;CACxC;AAED;;;;;;GAMG;AACH,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,IAAI;IAEvC,sFAAsF;IAChF,WAAW,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAsB/C,uEAAuE;IACjE,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAS5E;;;;;;OAMG;IACG,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IAuBnF;;;OAGG;IACG,yBAAyB,IAAI,OAAO,CACxC,KAAK,CAAC;QACJ,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,cAAc,EAAE,MAAM,EAAE,CAAC;KAC1B,CAAC,CACH;IA4CD;;;;;;OAMG;IACG,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,GAAG,WAAW,CAAC;IAuCzF;;;OAGG;IACG,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BvF;;;;OAIG;IACG,YAAY,CAAC,kBAAkB,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAUhG"}

package/dist/features/authz/access-bundle-store.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccessBundleStore = void 0;
+const AUTHZ = 'shield_authz';
+/**
+ * Raw-SQL (parameterized, NO ORM) CRUD over `shield_authz.access_bundle` +
+ * `access_bundle_permission`, mirroring `mariadb-catalog-store.ts`.
+ *
+ * All identity is resolved by BUSINESS KEY (`(ab_module, ab_key)`) — bundle UUIDs are
+ * generated per-DB and are NEVER hard-coded or assumed by the caller.
+ */
+class AccessBundleStore {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    /** All bundles (active + orphaned), for the reconciler's declared-vs-present diff. */
+    async listBundles() {
+        const rows = (await this.pool.query(`SELECT ab_uuid, ab_key, ab_module, ab_label, ab_description, ab_status
+         FROM \`${AUTHZ}\`.\`access_bundle\``));
+        return rows.map((r) => ({
+            uuid: r.ab_uuid,
+            key: r.ab_key,
+            module: r.ab_module,
+            label: r.ab_label,
+            description: r.ab_description,
+            status: r.ab_status === 'orphaned' ? 'orphaned' : 'active',
+        }));
+    }
+    /** Resolve a bundle's UUID by its business key. `null` when absent. */
+    async resolveBundleUuid(module, key) {
+        const rows = (await this.pool.query(`SELECT ab_uuid FROM \`${AUTHZ}\`.\`access_bundle\`
+        WHERE ab_module = ? AND ab_key = ? LIMIT 1`, [module, key]));
+        return rows[0]?.ab_uuid ?? null;
+    }
+    /**
+     * Resolve an ACTIVE bundle (by its `key`, unique-per-module) to its atomic permission
+     * keys. Returns `null` when no active bundle matches the key (unknown / orphaned) so the
+     * caller can raise `BadKeyError`. Bundle `key` alone is the admin-facing identifier;
+     * there is exactly one active bundle per key across the identity module today, so the
+     * lookup is by `ab_key` + `ab_status='active'`.
+     */
+    async resolveActiveBundleKeys(bundleKey) {
+        const rows = (await this.pool.query(`SELECT abp.abp_perm_key AS perm_key
+         FROM \`${AUTHZ}\`.\`access_bundle\` ab
+         JOIN \`${AUTHZ}\`.\`access_bundle_permission\` abp
+           ON abp.abp_bundle_uuid = ab.ab_uuid
+        WHERE ab.ab_key = ? AND ab.ab_status = 'active'
+        ORDER BY abp.abp_perm_key`, [bundleKey]));
+        if (rows.length === 0) {
+            // Distinguish "no such active bundle" from "active bundle with zero keys".
+            const exists = (await this.pool.query(`SELECT 1 FROM \`${AUTHZ}\`.\`access_bundle\`
+          WHERE ab_key = ? AND ab_status = 'active' LIMIT 1`, [bundleKey]));
+            if (exists.length === 0)
+                return null;
+            return [];
+        }
+        return rows.map((r) => r.perm_key);
+    }
+    /**
+     * All ACTIVE bundles with their resolved atomic key sets, for the grant-admin list API.
+     * NEVER exposes `ab_uuid` — the admin surface identifies a bundle by its `key`.
+     */
+    async listActiveBundlesWithKeys() {
+        const rows = (await this.pool.query(`SELECT ab.ab_key AS bundle_key, ab.ab_module AS module, ab.ab_label AS label,
+              ab.ab_description AS description, abp.abp_perm_key AS perm_key
+         FROM \`${AUTHZ}\`.\`access_bundle\` ab
+         LEFT JOIN \`${AUTHZ}\`.\`access_bundle_permission\` abp
+           ON abp.abp_bundle_uuid = ab.ab_uuid
+        WHERE ab.ab_status = 'active'
+        ORDER BY ab.ab_module, ab.ab_key, abp.abp_perm_key`));
+        const byKey = new Map();
+        for (const r of rows) {
+            let bundle = byKey.get(r.bundle_key);
+            if (!bundle) {
+                bundle = {
+                    key: r.bundle_key,
+                    module: r.module,
+                    label: r.label,
+                    permissionKeys: [],
+                    ...(r.description != null ? { description: r.description } : {}),
+                };
+                byKey.set(r.bundle_key, bundle);
+            }
+            if (r.perm_key != null)
+                bundle.permissionKeys.push(r.perm_key);
+        }
+        return [...byKey.values()];
+    }
+    /**
+     * Insert-or-update a bundle by `(ab_module, ab_key)`. Sets status back to 'active'
+     * (a re-declared bundle that had been orphaned is revived). Returns:
+     * - `'inserted'` — a new row was created,
+     * - `'updated'`  — an existing row's label/description/status actually changed,
+     * - `'unchanged'` — the row already matched (idempotent no-op).
+     */
+    async upsertBundle(spec) {
+        const description = spec.description ?? null;
+        const existing = (await this.pool.query(`SELECT ab_uuid, ab_label, ab_description, ab_status
+         FROM \`${AUTHZ}\`.\`access_bundle\`
+        WHERE ab_module = ? AND ab_key = ? LIMIT 1`, [spec.module, spec.key]));
+        const cur = existing[0];
+        if (cur) {
+            const same = cur.ab_label === spec.label &&
+                (cur.ab_description ?? null) === description &&
+                cur.ab_status === 'active';
+            if (same)
+                return 'unchanged';
+            await this.pool.query(`UPDATE \`${AUTHZ}\`.\`access_bundle\`
+            SET ab_label = ?, ab_description = ?, ab_status = 'active'
+          WHERE ab_uuid = ?`, [spec.label, description, cur.ab_uuid]);
+            return 'updated';
+        }
+        await this.pool.query(`INSERT INTO \`${AUTHZ}\`.\`access_bundle\`
+         (ab_uuid, ab_key, ab_module, ab_label, ab_description, ab_status)
+         VALUES (UUID(), ?, ?, ?, ?, 'active')`, [spec.key, spec.module, spec.label, description]);
+        return 'inserted';
+    }
+    /**
+     * Sync a bundle's atomic key set to exactly `keys`: delete rows not in the set,
+     * insert the missing ones. Idempotent — a re-sync with the same set is a no-op.
+     */
+    async syncBundlePermissions(bundleUuid, keys) {
+        const existing = (await this.pool.query(`SELECT abp_perm_key FROM \`${AUTHZ}\`.\`access_bundle_permission\`
+        WHERE abp_bundle_uuid = ?`, [bundleUuid]));
+        const have = new Set(existing.map((r) => r.abp_perm_key));
+        const want = new Set(keys);
+        const toDelete = [...have].filter((k) => !want.has(k));
+        const toInsert = [...want].filter((k) => !have.has(k));
+        if (toDelete.length > 0) {
+            const ph = toDelete.map(() => '?').join(', ');
+            await this.pool.query(`DELETE FROM \`${AUTHZ}\`.\`access_bundle_permission\`
+          WHERE abp_bundle_uuid = ? AND abp_perm_key IN (${ph})`, [bundleUuid, ...toDelete]);
+        }
+        for (const key of toInsert) {
+            await this.pool.query(`INSERT INTO \`${AUTHZ}\`.\`access_bundle_permission\`
+           (abp_uuid, abp_bundle_uuid, abp_perm_key)
+           VALUES (UUID(), ?, ?)`, [bundleUuid, key]);
+        }
+    }
+    /**
+     * Mark bundles whose `(module, key)` is NOT in the declared set as orphaned
+     * (never deleted — a granted role may reference it). `modKeysNotDeclared` is the
+     * list of `[module, key]` pairs to orphan.
+     */
+    async markOrphaned(modKeysNotDeclared) {
+        for (const [module, key] of modKeysNotDeclared) {
+            await this.pool.query(`UPDATE \`${AUTHZ}\`.\`access_bundle\`
+            SET ab_status = 'orphaned'
+          WHERE ab_module = ? AND ab_key = ?`, [module, key]);
+        }
+    }
+}
+exports.AccessBundleStore = AccessBundleStore;

package/dist/features/authz/catalog-bootstrap.provider.d.ts

@@ -0,0 +1,28 @@
+import { type OnApplicationBootstrap } from '@nestjs/common';
+import { DiscoveryService, MetadataScanner, Reflector } from '@nestjs/core';
+import type { ObjectType } from '@astram/engine';
+import { CatalogReconcileJob } from './catalog-reconcile.job.js';
+import { AccessBundleReconcileJob } from './access-bundle-reconcile.job.js';
+/**
+ * Boot: read-only verifyGatable (fail-closed — a stranded/unclassified route aborts
+ * boot). Post-boot: kick the mutating reconcile once, then on an interval (single
+ * process = single runner in dev; a clustered deploy would gate this behind a leader
+ * lock — deferred). DISABLE_ALL_CRONS disables the interval (boot verify still runs).
+ *
+ * The mutating half (the `CatalogReconcileJob`, holding the latest report for
+ * /health/catalog) is supplied by DI via the module factory — the SAME instance the
+ * health controller injects — so verify, the post-boot pass, and the endpoint all share
+ * one job. This provider owns only the boot verify + the schedule.
+ */
+export declare class CatalogBootstrapProvider implements OnApplicationBootstrap {
+    private readonly discovery;
+    private readonly scanner;
+    private readonly reflector;
+    private readonly job;
+    private readonly accessBundleJob;
+    private readonly registrations;
+    private timer;
+    constructor(discovery: DiscoveryService, scanner: MetadataScanner, reflector: Reflector, job: CatalogReconcileJob, accessBundleJob: AccessBundleReconcileJob, registrations: readonly ObjectType[]);
+    onApplicationBootstrap(): Promise<void>;
+}
+//# sourceMappingURL=catalog-bootstrap.provider.d.ts.map

package/dist/features/authz/catalog-bootstrap.provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-bootstrap.provider.d.ts","sourceRoot":"","sources":["../../../src/features/authz/catalog-bootstrap.provider.ts"],"names":[],"mappings":"AAIA,OAAO,EAAsB,KAAK,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACjF,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAO5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAK5E;;;;;;;;;;GAUG;AACH,qBACa,wBAAyB,YAAW,sBAAsB;IAInE,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,eAAe;IAEhC,OAAO,CAAC,QAAQ,CAAC,aAAa;IAThC,OAAO,CAAC,KAAK,CAA+B;gBAGzB,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,mBAAmB,EACxB,eAAe,EAAE,wBAAwB,EAEzC,aAAa,EAAE,SAAS,UAAU,EAAE;IAGjD,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;CA2B9C"}