@astram/identity 0.1.2 → 0.2.0

package/dist/features/authz/catalog-bootstrap.provider.js

@@ -0,0 +1,85 @@
+"use strict";
+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.CatalogBootstrapProvider = void 0;
+// Ported from astram3 `server/src/features/authz/catalog-bootstrap.provider.ts`.
+// Faithful port; imports repointed to the framework's guard/engine + local jobs. The
+// astram3 `./module-registry.bridge` import is repointed to `buildIdentityModuleRegistry`
+// exported from @astram/guard.
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const guard_1 = require("@astram/guard");
+const engine_1 = require("@astram/engine");
+const catalog_reconcile_job_js_1 = require("./catalog-reconcile.job.js");
+const access_bundle_reconcile_job_js_1 = require("./access-bundle-reconcile.job.js");
+const MODULE_KEY = 'identity';
+const RECONCILE_INTERVAL_MS = 60 * 60 * 1000; // hourly; honors DISABLE_ALL_CRONS below
+/**
+ * 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.
+ */
+let CatalogBootstrapProvider = class CatalogBootstrapProvider {
+    discovery;
+    scanner;
+    reflector;
+    job;
+    accessBundleJob;
+    registrations;
+    timer = null;
+    constructor(discovery, scanner, reflector, job, accessBundleJob, registrations) {
+        this.discovery = discovery;
+        this.scanner = scanner;
+        this.reflector = reflector;
+        this.job = job;
+        this.accessBundleJob = accessBundleJob;
+        this.registrations = registrations;
+    }
+    async onApplicationBootstrap() {
+        const registry = (0, guard_1.buildIdentityModuleRegistry)(this.registrations);
+        const inventoryScanner = new guard_1.OperationInventoryScanner(this.discovery, this.scanner, this.reflector);
+        const inventory = inventoryScanner.scan(MODULE_KEY);
+        // Fail-closed (ADR-0002): a route that can't be gated aborts boot.
+        new guard_1.CatalogReconciler().verifyGatable(inventory, registry);
+        // Mutating reconcile runs AFTER boot (not blocking, not fail-closed).
+        const nowIso = new Date().toISOString();
+        await this.job.runOnce(nowIso);
+        // Bundles reconcile AFTER permissions (same post-boot pass): a bundle validates
+        // its keys against the live permission catalog, so permissions must reconcile first.
+        await this.accessBundleJob.runOnce(nowIso);
+        if (process.env.DISABLE_ALL_CRONS !== 'true') {
+            this.timer = setInterval(() => {
+                const tickIso = new Date().toISOString();
+                void this.job.runOnce(tickIso).then(() => this.accessBundleJob.runOnce(tickIso));
+            }, RECONCILE_INTERVAL_MS);
+            this.timer.unref?.();
+        }
+    }
+};
+exports.CatalogBootstrapProvider = CatalogBootstrapProvider;
+exports.CatalogBootstrapProvider = CatalogBootstrapProvider = __decorate([
+    (0, common_1.Injectable)(),
+    __param(5, (0, common_1.Inject)(engine_1.ENGINE_ALL_REGISTRATIONS)),
+    __metadata("design:paramtypes", [core_1.DiscoveryService,
+        core_1.MetadataScanner,
+        core_1.Reflector,
+        catalog_reconcile_job_js_1.CatalogReconcileJob,
+        access_bundle_reconcile_job_js_1.AccessBundleReconcileJob, Array])
+], CatalogBootstrapProvider);

package/dist/features/authz/catalog-reconcile.job.d.ts

@@ -0,0 +1,23 @@
+import type { Pool } from 'mariadb';
+import { type ReconcileReport } from '@astram/guard';
+import type { ModuleRegistry } from '@astram/core';
+/**
+ * Single-runner wrapper around the framework CatalogReconciler.reconcile (the mutating
+ * half). Called once shortly after boot and on a cron. Holds the latest report for
+ * /health/catalog. NOT run at boot (boot only does the read-only verifyGatable).
+ *
+ * Timestamp is supplied by the caller (policy: pass new Date().toISOString() from the
+ * scheduler, not inside the reconciler — keeps the framework fn pure).
+ */
+export declare class CatalogReconcileJob {
+    private readonly registry;
+    private readonly reconciler;
+    private readonly store;
+    private latest;
+    private running;
+    constructor(pool: Pool, registry: ModuleRegistry);
+    /** Idempotent single pass. Guarded so overlapping ticks don't double-run. */
+    runOnce(nowIso: string): Promise<ReconcileReport | null>;
+    getLatest(): ReconcileReport | null;
+}
+//# sourceMappingURL=catalog-reconcile.job.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-reconcile.job.d.ts","sourceRoot":"","sources":["../../../src/features/authz/catalog-reconcile.job.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGnD;;;;;;;GAOG;AACH,qBAAa,mBAAmB;IAMN,OAAO,CAAC,QAAQ,CAAC,QAAQ;IALjD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA2B;IACtD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;IAC5C,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,OAAO,CAAS;gBAEZ,IAAI,EAAE,IAAI,EAAmB,QAAQ,EAAE,cAAc;IAIjE,6EAA6E;IACvE,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAmB9D,SAAS,IAAI,eAAe,GAAG,IAAI;CAGpC"}

package/dist/features/authz/catalog-reconcile.job.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CatalogReconcileJob = void 0;
+const guard_1 = require("@astram/guard");
+const mariadb_catalog_store_js_1 = require("./mariadb-catalog-store.js");
+/**
+ * Single-runner wrapper around the framework CatalogReconciler.reconcile (the mutating
+ * half). Called once shortly after boot and on a cron. Holds the latest report for
+ * /health/catalog. NOT run at boot (boot only does the read-only verifyGatable).
+ *
+ * Timestamp is supplied by the caller (policy: pass new Date().toISOString() from the
+ * scheduler, not inside the reconciler — keeps the framework fn pure).
+ */
+class CatalogReconcileJob {
+    registry;
+    reconciler = new guard_1.CatalogReconciler();
+    store;
+    latest = null;
+    running = false;
+    constructor(pool, registry) {
+        this.registry = registry;
+        this.store = new mariadb_catalog_store_js_1.MariaDbCatalogStore(pool);
+    }
+    /** Idempotent single pass. Guarded so overlapping ticks don't double-run. */
+    async runOnce(nowIso) {
+        if (this.running)
+            return this.latest;
+        this.running = true;
+        try {
+            const report = await this.reconciler.reconcile(this.registry, this.store, nowIso);
+            this.latest = report;
+            const orphanNote = report.orphaned.length
+                ? ` — ORPHANED: ${report.orphaned.join(', ')}`
+                : '';
+            console.log(`[catalog] reconcile: +${report.added.length} added, ${report.orphaned.length} orphaned, ` +
+                `${report.reactivated.length} reactivated${orphanNote}`);
+            return report;
+        }
+        finally {
+            this.running = false;
+        }
+    }
+    getLatest() {
+        return this.latest;
+    }
+}
+exports.CatalogReconcileJob = CatalogReconcileJob;

package/dist/features/authz/db-permission-facts.adapter.d.ts

@@ -0,0 +1,60 @@
+/**
+ * PermissionFactsPort adapter — resolves a principal's coarse grants (the set of exact
+ * permission keys it holds via its roles) for core's object-type gate.
+ *
+ * roleIds → role_permission rows (exact OR wildcard strings) → expand wildcards against the
+ * registry's real action universe → de-duplicated exact keys. Core then does exact `.includes`.
+ *
+ * FAIL-CLOSED (ADR-0016): a store OUTAGE throws AuthorizationUnavailableError (→ 503).
+ * Data-absence ("no roles"/"no grants") returns EMPTY keys — a legitimate deny input.
+ * NEVER return empty to mask an outage; NEVER fabricate a key.
+ *
+ * Ported from astram3 `server/src/features/authz/permission-facts.adapter.ts`.
+ */
+import type { Pool } from 'mariadb';
+import type { PermissionFactsPort, CoarseGrants, ModuleRegistry } from '@astram/core';
+/**
+ * Expand raw grant strings (exact or wildcard) to the set of EXACT registered keys.
+ * Bounded to `allKeys` — a wildcard can never yield a key that isn't registered.
+ *   exact `identity:company:view`  → itself (if registered)
+ *   `identity:company:*`           → every registered `identity:company:<action>`
+ *   `identity:*` / bare `identity` → every registered `identity:<type>:<action>`
+ */
+export declare function expandGrantKeys(rawKeys: string[], allKeys: string[]): string[];
+/**
+ * The principal's role uuids from its ACTIVE membership's in-effect postings in
+ * `tenantId` — the SAME in-effect-posting window query `DbPermissionFactsAdapter` uses,
+ * extracted so any OTHER caller that needs a principal's roleIds for a tenant reuses this
+ * ONE timezone-safe epoch-ms window read instead of re-inlining the SQL.
+ *
+ * @param now injectable clock (epoch-ms), defaults to `Date.now` — bound as a `?`
+ *   integer against the BIGINT `mp_effective_*_ms` columns (timezone-immune).
+ */
+export declare function readRoleIdsForTenant(pool: Pool, principalId: string, tenantId: string, now?: () => number): Promise<string[]>;
+export declare class DbPermissionFactsAdapter implements PermissionFactsPort {
+    private readonly pool;
+    private readonly registry;
+    /**
+     * Injectable clock (epoch-ms) for the posting effective-window compare. Defaults to
+     * `Date.now`. Bound as a `?` integer against the BIGINT `_ms` columns — timezone-immune.
+     * Injectable so a test can fix the clock relative to a seeded expired/active posting.
+     */
+    private readonly now;
+    constructor(pool: Pool, registry: ModuleRegistry, 
+    /**
+     * Injectable clock (epoch-ms) for the posting effective-window compare. Defaults to
+     * `Date.now`. Bound as a `?` integer against the BIGINT `_ms` columns — timezone-immune.
+     * Injectable so a test can fix the clock relative to a seeded expired/active posting.
+     */
+    now?: () => number);
+    currentPermissionsVersion(_principalId: string, tenantId: string): Promise<number>;
+    loadCoarseGrants(principalId: string, tenantId: string): Promise<CoarseGrants>;
+    private readVersion;
+    /**
+     * The principal's role uuids from its ACTIVE membership's in-effect postings in this
+     * tenant — delegates to the shared {@link readRoleIdsForTenant} (single source).
+     */
+    private readRoleIds;
+    private readGrantKeys;
+}
+//# sourceMappingURL=db-permission-facts.adapter.d.ts.map

package/dist/features/authz/db-permission-facts.adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-permission-facts.adapter.d.ts","sourceRoot":"","sources":["../../../src/features/authz/db-permission-facts.adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAKtF;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAe9E;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,IAAI,EACV,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,GAAE,MAAM,MAAiB,GAC3B,OAAO,CAAC,MAAM,EAAE,CAAC,CAYnB;AAED,qBAAa,wBAAyB,YAAW,mBAAmB;IAEhE,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAPH,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,cAAc;IACzC;;;;OAIG;IACc,GAAG,GAAE,MAAM,MAAiB;IAGzC,yBAAyB,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAalF,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;YAgBtE,WAAW;IASzB;;;OAGG;YACW,WAAW;YAIX,aAAa;CAS5B"}

package/dist/features/authz/db-permission-facts.adapter.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DbPermissionFactsAdapter = void 0;
+exports.expandGrantKeys = expandGrantKeys;
+exports.readRoleIdsForTenant = readRoleIdsForTenant;
+const core_1 = require("@astram/core");
+const MODULE_PREFIX = 'identity';
+/**
+ * Expand raw grant strings (exact or wildcard) to the set of EXACT registered keys.
+ * Bounded to `allKeys` — a wildcard can never yield a key that isn't registered.
+ *   exact `identity:company:view`  → itself (if registered)
+ *   `identity:company:*`           → every registered `identity:company:<action>`
+ *   `identity:*` / bare `identity` → every registered `identity:<type>:<action>`
+ */
+function expandGrantKeys(rawKeys, allKeys) {
+    const out = new Set();
+    for (const raw of rawKeys) {
+        if (raw === MODULE_PREFIX || raw === `${MODULE_PREFIX}:*`) {
+            for (const k of allKeys)
+                if (k.startsWith(`${MODULE_PREFIX}:`))
+                    out.add(k);
+            continue;
+        }
+        if (raw.endsWith(':*')) {
+            const prefix = raw.slice(0, -1); // keep trailing ':' → 'identity:company:'
+            for (const k of allKeys)
+                if (k.startsWith(prefix))
+                    out.add(k);
+            continue;
+        }
+        if (allKeys.includes(raw))
+            out.add(raw); // exact, only if real
+    }
+    return [...out];
+}
+/**
+ * The principal's role uuids from its ACTIVE membership's in-effect postings in
+ * `tenantId` — the SAME in-effect-posting window query `DbPermissionFactsAdapter` uses,
+ * extracted so any OTHER caller that needs a principal's roleIds for a tenant reuses this
+ * ONE timezone-safe epoch-ms window read instead of re-inlining the SQL.
+ *
+ * @param now injectable clock (epoch-ms), defaults to `Date.now` — bound as a `?`
+ *   integer against the BIGINT `mp_effective_*_ms` columns (timezone-immune).
+ */
+async function readRoleIdsForTenant(pool, principalId, tenantId, now = Date.now) {
+    const nowMs = now();
+    const rows = (await pool.query(`SELECT DISTINCT mp.mp_role_uuid AS role_uuid
+       FROM \`shield_app\`.\`company_membership\` cm
+       JOIN \`shield_app\`.\`membership_posting\` mp ON mp.mp_membership_uuid = cm.cm_uuid
+      WHERE cm.cm_user_uuid = ? AND cm.cm_company_uuid = ? AND cm.cm_is_active = 1
+        AND (mp.mp_effective_from_ms IS NULL OR mp.mp_effective_from_ms <= ?)
+        AND (mp.mp_effective_until_ms IS NULL OR mp.mp_effective_until_ms > ?)`, [principalId, tenantId, nowMs, nowMs]));
+    return rows.map((r) => r.role_uuid);
+}
+class DbPermissionFactsAdapter {
+    pool;
+    registry;
+    now;
+    constructor(pool, registry, 
+    /**
+     * Injectable clock (epoch-ms) for the posting effective-window compare. Defaults to
+     * `Date.now`. Bound as a `?` integer against the BIGINT `_ms` columns — timezone-immune.
+     * Injectable so a test can fix the clock relative to a seeded expired/active posting.
+     */
+    now = Date.now) {
+        this.pool = pool;
+        this.registry = registry;
+        this.now = now;
+    }
+    async currentPermissionsVersion(_principalId, tenantId) {
+        try {
+            const rows = (await this.pool.query(`SELECT apv_version FROM \`shield_authz\`.\`authz_permission_version\`
+          WHERE apv_tenant_uuid = ? LIMIT 1`, [tenantId]));
+            return rows.length > 0 ? Number(rows[0]?.apv_version) : 0;
+        }
+        catch (cause) {
+            throw new core_1.AuthorizationUnavailableError('permission version store unavailable', cause);
+        }
+    }
+    async loadCoarseGrants(principalId, tenantId) {
+        let version;
+        let roleIds;
+        let rawKeys;
+        try {
+            version = await this.readVersion(tenantId);
+            roleIds = await this.readRoleIds(principalId, tenantId);
+            rawKeys = roleIds.length === 0 ? [] : await this.readGrantKeys(roleIds);
+        }
+        catch (cause) {
+            if (cause instanceof core_1.AuthorizationUnavailableError)
+                throw cause;
+            throw new core_1.AuthorizationUnavailableError('permission facts store unavailable', cause);
+        }
+        const allKeys = this.registry.listActions().map((a) => a.permissionKey);
+        return { permissionsVersion: version, grantedPermissionKeys: expandGrantKeys(rawKeys, allKeys) };
+    }
+    async readVersion(tenantId) {
+        const rows = (await this.pool.query(`SELECT apv_version FROM \`shield_authz\`.\`authz_permission_version\`
+        WHERE apv_tenant_uuid = ? LIMIT 1`, [tenantId]));
+        return rows.length > 0 ? Number(rows[0]?.apv_version) : 0;
+    }
+    /**
+     * The principal's role uuids from its ACTIVE membership's in-effect postings in this
+     * tenant — delegates to the shared {@link readRoleIdsForTenant} (single source).
+     */
+    async readRoleIds(principalId, tenantId) {
+        return readRoleIdsForTenant(this.pool, principalId, tenantId, this.now);
+    }
+    async readGrantKeys(roleIds) {
+        const placeholders = roleIds.map(() => '?').join(', ');
+        const rows = (await this.pool.query(`SELECT rp_perm_key FROM \`shield_authz\`.\`role_permission\`
+        WHERE rp_role_uuid IN (${placeholders})`, roleIds));
+        return rows.map((r) => r.rp_perm_key);
+    }
+}
+exports.DbPermissionFactsAdapter = DbPermissionFactsAdapter;

package/dist/features/authz/grant-admin.controller.d.ts

@@ -0,0 +1,96 @@
+import type { Principal } from '@astram/engine';
+import { GrantAdminService } from './grant-admin.service.js';
+/** The request shape after the enforcement guard attaches the resolved principal. */
+interface AuthedRequest {
+    principal: Principal;
+}
+/**
+ * Grant administration — list/grant/revoke a role's permission keys. Gated purely on
+ * `@Classified({ typeKey: 'role', ... })` + `decide()` (G1: no handler-level root
+ * check). Managing grants IS role administration, so it keys to the `role` object type:
+ * read routes need `identity:role:read`, mutating routes need `identity:role:update`.
+ * `role` is a CONTROL-plane type, so the capped root is allowed without an explicit
+ * grant; a non-root caller needs the grant. (`role_permission` itself is not a
+ * registered object type — it is administered THROUGH `role`, never classified directly.)
+ *
+ * Mutating routes pass `req.principal.id` as the grantor so `role_permission` records
+ * who granted what (surfaced by the grants-summary listing as "by <name>").
+ */
+export declare class GrantAdminController {
+    private readonly grants;
+    constructor(grants: GrantAdminService);
+    /**
+     * Per-role access summary for the Access listing: every role that holds ≥1 grant, with
+     * its object/permission counts, access chips, covering preset, and last-modified date +
+     * grantor NAME (resolved server-side — no raw uuid). Gated `role:read`.
+     *
+     * ⚠️ Path is `access/role-grants` (NOT under `roles/...`) on purpose: a `roles/<x>` path
+     * would be captured by IdentityController's `@Get('roles/:uuid')` (registered first),
+     * routing this to getRole('role-grants') → a 500. Keep it off the `roles/:uuid` shape.
+     */
+    grantsSummary(query: {
+        page?: string;
+        limit?: string;
+        search?: string;
+        sortBy?: string;
+        sortOrder?: string;
+    }): Promise<{
+        rows: import("./grant-admin.service.js").RoleGrantSummary[];
+        total: number;
+        page: number;
+        limit: number;
+    }>;
+    /** List all grantable permission keys + wildcards. */
+    catalog(): Promise<{
+        catalog: {
+            key: string;
+            label: string;
+            module: string;
+            typeKey: string;
+            action: string;
+        }[];
+        wildcards: string[];
+    }>;
+    /** List a role's current grants. */
+    list(uuid: string): Promise<{
+        grants: string[];
+    }>;
+    /** Grant one permission key to a role. */
+    grant(req: AuthedRequest, uuid: string, body: {
+        key?: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+    /** Revoke one permission key from a role. `:key` is URL-encoded (contains ':'). */
+    revoke(uuid: string, key: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * List all active access bundles (named, admin-grantable key sets) + their resolved
+     * atomic keys, for the Access UI. Bundles are identified by `key` — no `ab_uuid` is
+     * ever exposed. Gated `role:read` (managing/reading grants is role administration).
+     */
+    bundles(): Promise<{
+        bundles: import("./grant-admin.service.js").BundleView[];
+    }>;
+    /**
+     * Grant an access bundle to a role — expands the bundle to its atomic keys in
+     * `role_permission` (idempotent, one transaction, one version bump). Body: `{ key }`
+     * (the bundle slug). Unknown bundle → 400. Gated `role:update`.
+     */
+    grantBundle(req: AuthedRequest, uuid: string, body: {
+        key?: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Revoke an access bundle from a role — removes exactly the bundle's atomic keys from
+     * `role_permission` (see design §5.1 caveat re: shared keys). `:key` is the bundle slug.
+     * Unknown bundle → 400. Gated `role:update`.
+     */
+    revokeBundle(uuid: string, key: string): Promise<{
+        success: boolean;
+    }>;
+}
+export {};
+//# sourceMappingURL=grant-admin.controller.d.ts.map

package/dist/features/authz/grant-admin.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grant-admin.controller.d.ts","sourceRoot":"","sources":["../../../src/features/authz/grant-admin.controller.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAe,MAAM,0BAA0B,CAAC;AAE1E,qFAAqF;AACrF,UAAU,aAAa;IACrB,SAAS,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;GAWG;AACH,qBACa,oBAAoB;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,iBAAiB;IAEtD;;;;;;;;OAQG;IAGG,aAAa,CAEjB,KAAK,EAAE;QACL,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB;;;;;;IAcH,sDAAsD;IAGhD,OAAO;;;;;;;;;;IAIb,oCAAoC;IAG9B,IAAI,CAAgB,IAAI,EAAE,MAAM;;;IAItC,0CAA0C;IAGpC,KAAK,CAAQ,GAAG,EAAE,aAAa,EAAiB,IAAI,EAAE,MAAM,EAAU,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAYlG,mFAAmF;IAG7E,MAAM,CAAgB,IAAI,EAAE,MAAM,EAAgB,GAAG,EAAE,MAAM;;;IAOnE;;;;OAIG;IAGG,OAAO;;;IAIb;;;;OAIG;IAGG,WAAW,CAAQ,GAAG,EAAE,aAAa,EAAiB,IAAI,EAAE,MAAM,EAAU,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAYxG;;;;OAIG;IAGG,YAAY,CAAgB,IAAI,EAAE,MAAM,EAAgB,GAAG,EAAE,MAAM;;;CAS1E"}

package/dist/features/authz/grant-admin.controller.js

@@ -0,0 +1,209 @@
+"use strict";
+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.GrantAdminController = void 0;
+// Ported from astram3 `server/src/features/authz/grant-admin.controller.ts`.
+// Faithful port: same routes, same gating, same error mapping. Imports repointed to the
+// framework's guard/engine building blocks + the local grant-admin.service.
+const common_1 = require("@nestjs/common");
+const guard_1 = require("@astram/guard");
+const grant_admin_service_js_1 = require("./grant-admin.service.js");
+/**
+ * Grant administration — list/grant/revoke a role's permission keys. Gated purely on
+ * `@Classified({ typeKey: 'role', ... })` + `decide()` (G1: no handler-level root
+ * check). Managing grants IS role administration, so it keys to the `role` object type:
+ * read routes need `identity:role:read`, mutating routes need `identity:role:update`.
+ * `role` is a CONTROL-plane type, so the capped root is allowed without an explicit
+ * grant; a non-root caller needs the grant. (`role_permission` itself is not a
+ * registered object type — it is administered THROUGH `role`, never classified directly.)
+ *
+ * Mutating routes pass `req.principal.id` as the grantor so `role_permission` records
+ * who granted what (surfaced by the grants-summary listing as "by <name>").
+ */
+let GrantAdminController = class GrantAdminController {
+    grants;
+    constructor(grants) {
+        this.grants = grants;
+    }
+    /**
+     * Per-role access summary for the Access listing: every role that holds ≥1 grant, with
+     * its object/permission counts, access chips, covering preset, and last-modified date +
+     * grantor NAME (resolved server-side — no raw uuid). Gated `role:read`.
+     *
+     * ⚠️ Path is `access/role-grants` (NOT under `roles/...`) on purpose: a `roles/<x>` path
+     * would be captured by IdentityController's `@Get('roles/:uuid')` (registered first),
+     * routing this to getRole('role-grants') → a 500. Keep it off the `roles/:uuid` shape.
+     */
+    async grantsSummary(query) {
+        const page = Number.parseInt(query?.page ?? '', 10);
+        const limit = Number.parseInt(query?.limit ?? '', 10);
+        const params = {
+            sortOrder: query?.sortOrder === 'desc' ? 'desc' : 'asc',
+        };
+        if (Number.isFinite(page))
+            params.page = page;
+        if (Number.isFinite(limit))
+            params.limit = limit;
+        if (typeof query?.search === 'string')
+            params.search = query.search;
+        if (typeof query?.sortBy === 'string')
+            params.sortBy = query.sortBy;
+        return this.grants.listGrantsSummary(params);
+    }
+    /** List all grantable permission keys + wildcards. */
+    async catalog() {
+        return this.grants.listCatalog();
+    }
+    /** List a role's current grants. */
+    async list(uuid) {
+        return this.grants.listRoleGrants(uuid);
+    }
+    /** Grant one permission key to a role. */
+    async grant(req, uuid, body) {
+        const key = body?.key;
+        if (!key)
+            throw new common_1.BadRequestException('key required');
+        try {
+            await this.grants.grant(uuid, key, req.principal?.id);
+        }
+        catch (e) {
+            if (e instanceof grant_admin_service_js_1.BadKeyError)
+                throw new common_1.BadRequestException(e.message);
+            throw e;
+        }
+        return { success: true };
+    }
+    /** Revoke one permission key from a role. `:key` is URL-encoded (contains ':'). */
+    async revoke(uuid, key) {
+        await this.grants.revoke(uuid, decodeURIComponent(key));
+        return { success: true };
+    }
+    // ── Access bundles ────────────────────────────────────────────────────────
+    /**
+     * List all active access bundles (named, admin-grantable key sets) + their resolved
+     * atomic keys, for the Access UI. Bundles are identified by `key` — no `ab_uuid` is
+     * ever exposed. Gated `role:read` (managing/reading grants is role administration).
+     */
+    async bundles() {
+        return this.grants.listBundles();
+    }
+    /**
+     * Grant an access bundle to a role — expands the bundle to its atomic keys in
+     * `role_permission` (idempotent, one transaction, one version bump). Body: `{ key }`
+     * (the bundle slug). Unknown bundle → 400. Gated `role:update`.
+     */
+    async grantBundle(req, uuid, body) {
+        const key = body?.key;
+        if (!key)
+            throw new common_1.BadRequestException('key required');
+        try {
+            await this.grants.grantBundle(uuid, key, req.principal?.id);
+        }
+        catch (e) {
+            if (e instanceof grant_admin_service_js_1.BadKeyError)
+                throw new common_1.BadRequestException(e.message);
+            throw e;
+        }
+        return { success: true };
+    }
+    /**
+     * Revoke an access bundle from a role — removes exactly the bundle's atomic keys from
+     * `role_permission` (see design §5.1 caveat re: shared keys). `:key` is the bundle slug.
+     * Unknown bundle → 400. Gated `role:update`.
+     */
+    async revokeBundle(uuid, key) {
+        try {
+            await this.grants.revokeBundle(uuid, decodeURIComponent(key));
+        }
+        catch (e) {
+            if (e instanceof grant_admin_service_js_1.BadKeyError)
+                throw new common_1.BadRequestException(e.message);
+            throw e;
+        }
+        return { success: true };
+    }
+};
+exports.GrantAdminController = GrantAdminController;
+__decorate([
+    (0, common_1.Get)('access/role-grants'),
+    (0, guard_1.Classified)({ typeKey: 'role', action: 'read' }),
+    __param(0, (0, common_1.Query)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], GrantAdminController.prototype, "grantsSummary", null);
+__decorate([
+    (0, common_1.Get)('permission-catalog'),
+    (0, guard_1.Classified)({ typeKey: 'role', action: 'read' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], GrantAdminController.prototype, "catalog", null);
+__decorate([
+    (0, common_1.Get)('roles/:uuid/permissions'),
+    (0, guard_1.Classified)({ typeKey: 'role', action: 'read' }),
+    __param(0, (0, common_1.Param)('uuid')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], GrantAdminController.prototype, "list", null);
+__decorate([
+    (0, common_1.Post)('roles/:uuid/permissions'),
+    (0, guard_1.Classified)({ typeKey: 'role', action: 'update' }),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Param)('uuid')),
+    __param(2, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, String, Object]),
+    __metadata("design:returntype", Promise)
+], GrantAdminController.prototype, "grant", null);
+__decorate([
+    (0, common_1.Delete)('roles/:uuid/permissions/:key'),
+    (0, guard_1.Classified)({ typeKey: 'role', action: 'update' }),
+    __param(0, (0, common_1.Param)('uuid')),
+    __param(1, (0, common_1.Param)('key')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String]),
+    __metadata("design:returntype", Promise)
+], GrantAdminController.prototype, "revoke", null);
+__decorate([
+    (0, common_1.Get)('access-bundles'),
+    (0, guard_1.Classified)({ typeKey: 'role', action: 'read' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], GrantAdminController.prototype, "bundles", null);
+__decorate([
+    (0, common_1.Post)('roles/:uuid/access-bundles'),
+    (0, guard_1.Classified)({ typeKey: 'role', action: 'update' }),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Param)('uuid')),
+    __param(2, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, String, Object]),
+    __metadata("design:returntype", Promise)
+], GrantAdminController.prototype, "grantBundle", null);
+__decorate([
+    (0, common_1.Delete)('roles/:uuid/access-bundles/:key'),
+    (0, guard_1.Classified)({ typeKey: 'role', action: 'update' }),
+    __param(0, (0, common_1.Param)('uuid')),
+    __param(1, (0, common_1.Param)('key')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String]),
+    __metadata("design:returntype", Promise)
+], GrantAdminController.prototype, "revokeBundle", null);
+exports.GrantAdminController = GrantAdminController = __decorate([
+    (0, common_1.Controller)('identity'),
+    __metadata("design:paramtypes", [grant_admin_service_js_1.GrantAdminService])
+], GrantAdminController);