@astram/identity 0.1.2 → 0.2.1

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

@@ -0,0 +1,107 @@
+import type { Pool } from 'mariadb';
+import { PermissionVersionBumper } from './permission-version.bumper.js';
+import { AccessBundleStore } from './access-bundle-store.js';
+/** A granted key was not in the catalog and is not a recognized wildcard. The
+ *  controller maps this to HTTP 400 (distinct from a store outage → 503). */
+export declare class BadKeyError extends Error {
+    constructor(key: string);
+}
+type CatalogRow = {
+    key: string;
+    label: string;
+    module: string;
+    typeKey: string;
+    action: string;
+};
+/** A bundle as returned by the list API — identified by `key`, NEVER by `ab_uuid`. */
+export interface BundleView {
+    key: string;
+    module: string;
+    label: string;
+    description?: string;
+    permissionKeys: string[];
+}
+/**
+ * A granted role's access summary for the Access listing. `roleUuid` is a key/arg ONLY —
+ * the UI shows `roleName`. `grantedByName` is resolved server-side (NEVER a raw uuid).
+ */
+export interface RoleGrantSummary {
+    roleUuid: string;
+    roleName: string;
+    objectCount: number;
+    permCount: number;
+    chips: string[];
+    preset: string | null;
+    grantedAt: string | null;
+    grantedByName: string | null;
+}
+export declare class GrantAdminService {
+    private readonly pool;
+    private readonly bumper;
+    private readonly bundles;
+    constructor(pool: Pool, bumper: PermissionVersionBumper, bundleStore?: AccessBundleStore);
+    /** All grantable exact keys (from the catalog) + the computed wildcard set. */
+    listCatalog(): Promise<{
+        catalog: CatalogRow[];
+        wildcards: string[];
+    }>;
+    listRoleGrants(roleUuid: string): Promise<{
+        grants: string[];
+    }>;
+    /** Validate the key against the catalog + wildcard set. Throws BadKeyError if unknown. */
+    private assertValidKey;
+    /**
+     * Grant a key to a role (idempotent) + bump the version, atomically. `actorUuid`, when
+     * given, stamps `rp_granted_at`/`rp_granted_by` on a NEWLY-inserted row (a duplicate is a
+     * no-op and its existing stamp is left as-is).
+     */
+    grant(roleUuid: string, key: string, actorUuid?: string): Promise<void>;
+    /** Revoke a key from a role (no-op if absent) + bump the version, atomically. */
+    revoke(roleUuid: string, key: string): Promise<void>;
+    /** All active bundles + their resolved atomic keys, for the Access UI. */
+    listBundles(): Promise<{
+        bundles: BundleView[];
+    }>;
+    /**
+     * Grant a bundle to a role: resolve the bundle → its atomic keys, then INSERT each
+     * into `role_permission` idempotently in ONE transaction with ONE version bump.
+     * An unknown / orphaned bundle → `BadKeyError` (mapped to 400 by the controller).
+     */
+    grantBundle(roleUuid: string, bundleKey: string, actorUuid?: string): Promise<void>;
+    /**
+     * Revoke a bundle from a role: resolve → DELETE each of the bundle's atomic keys, in
+     * ONE transaction with ONE version bump. Caveat (design §5.1): this removes exactly the
+     * bundle's keys even if a manual grant or another bundle shares one — the model is
+     * key-based, not bundle-membership-based. Unknown bundle → `BadKeyError`.
+     */
+    revokeBundle(roleUuid: string, bundleKey: string): Promise<void>;
+    /** Resolve a bundle key → its atomic keys; throw BadKeyError when unknown/orphaned. */
+    private resolveBundleKeysOrThrow;
+    /**
+     * Access-listing summary — SERVER-PAGED. One row per role that holds ≥1 grant, with its
+     * access summary (chips/counts), the covering preset (if any), and last-modified date +
+     * the GRANTOR'S NAME (resolved from `rp_granted_by` → `users.u_username`, never a raw
+     * uuid). Wildcard grants are expanded against the live catalog so counts/chips reflect
+     * the REAL effective set.
+     *
+     * Paging model: page over the DISTINCT granted roles (name search + sort + LIMIT/OFFSET
+     * + a COUNT for total), then compute the summary only for the page's roles. `sortBy` ∈
+     * {name, grantedAt, permCount}; name/grantedAt sort in SQL, permCount sorts the computed
+     * page (a per-role aggregate not cheaply sortable in SQL). Defaults: page 1, limit 25,
+     * sort name asc.
+     */
+    listGrantsSummary(params?: {
+        page?: number;
+        limit?: number;
+        search?: string;
+        sortBy?: string;
+        sortOrder?: 'asc' | 'desc';
+    }): Promise<{
+        rows: RoleGrantSummary[];
+        total: number;
+        page: number;
+        limit: number;
+    }>;
+}
+export {};
+//# sourceMappingURL=grant-admin.service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grant-admin.service.d.ts","sourceRoot":"","sources":["../../../src/features/authz/grant-admin.service.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,297 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GrantAdminService = exports.BadKeyError = void 0;
+const core_1 = require("@astram/core");
+const access_bundle_store_js_1 = require("./access-bundle-store.js");
+const db_permission_facts_adapter_js_1 = require("./db-permission-facts.adapter.js");
+const AUTHZ = 'shield_authz';
+/** A granted key was not in the catalog and is not a recognized wildcard. The
+ *  controller maps this to HTTP 400 (distinct from a store outage → 503). */
+class BadKeyError extends Error {
+    constructor(key) {
+        super(`unknown permission key: ${key}`);
+        this.name = 'BadKeyError';
+    }
+}
+exports.BadKeyError = BadKeyError;
+class GrantAdminService {
+    pool;
+    bumper;
+    bundles;
+    constructor(pool, bumper, bundleStore) {
+        this.pool = pool;
+        this.bumper = bumper;
+        this.bundles = bundleStore ?? new access_bundle_store_js_1.AccessBundleStore(pool);
+    }
+    /** All grantable exact keys (from the catalog) + the computed wildcard set. */
+    async listCatalog() {
+        let rows;
+        try {
+            rows = (await this.pool.query(`SELECT perm_key, perm_label, perm_module, perm_type_key, perm_action
+           FROM \`${AUTHZ}\`.\`permission\`
+          WHERE perm_status = 'active'
+          ORDER BY perm_type_key, perm_action`));
+        }
+        catch (cause) {
+            throw new core_1.AuthorizationUnavailableError('permission catalog unavailable', cause);
+        }
+        const catalog = rows.map((r) => ({
+            key: r.perm_key, label: r.perm_label, module: r.perm_module,
+            typeKey: r.perm_type_key, action: r.perm_action,
+        }));
+        // Wildcards: module-wide + one per distinct type key.
+        const modules = [...new Set(catalog.map((c) => c.module))];
+        const typeKeys = [...new Set(catalog.map((c) => c.typeKey))];
+        const wildcards = [
+            ...modules.map((m) => `${m}:*`),
+            ...typeKeys.map((t) => `${catalog.find((c) => c.typeKey === t).module}:${t}:*`),
+        ];
+        return { catalog, wildcards };
+    }
+    async listRoleGrants(roleUuid) {
+        try {
+            const rows = (await this.pool.query(`SELECT rp_perm_key FROM \`${AUTHZ}\`.\`role_permission\` WHERE rp_role_uuid = ? ORDER BY rp_perm_key`, [roleUuid]));
+            return { grants: rows.map((r) => r.rp_perm_key) };
+        }
+        catch (cause) {
+            throw new core_1.AuthorizationUnavailableError('role grants unavailable', cause);
+        }
+    }
+    /** Validate the key against the catalog + wildcard set. Throws BadKeyError if unknown. */
+    async assertValidKey(key) {
+        const { catalog, wildcards } = await this.listCatalog();
+        const known = new Set([...catalog.map((c) => c.key), ...wildcards]);
+        if (!known.has(key))
+            throw new BadKeyError(key);
+    }
+    /**
+     * Grant a key to a role (idempotent) + bump the version, atomically. `actorUuid`, when
+     * given, stamps `rp_granted_at`/`rp_granted_by` on a NEWLY-inserted row (a duplicate is a
+     * no-op and its existing stamp is left as-is).
+     */
+    async grant(roleUuid, key, actorUuid) {
+        await this.assertValidKey(key); // throws BadKeyError (400) before touching the store
+        const conn = await this.pool.getConnection();
+        try {
+            await conn.beginTransaction();
+            // Idempotent insert — UNIQUE (rp_role_uuid, rp_perm_key); a duplicate is a no-op.
+            await conn.query(`INSERT INTO \`${AUTHZ}\`.\`role_permission\`
+           (rp_uuid, rp_role_uuid, rp_perm_key, rp_granted_at, rp_granted_by)
+           SELECT UUID(), ?, ?, UTC_TIMESTAMP(), ?
+            WHERE NOT EXISTS (
+              SELECT 1 FROM \`${AUTHZ}\`.\`role_permission\` WHERE rp_role_uuid = ? AND rp_perm_key = ?
+            )`, [roleUuid, key, actorUuid ?? null, roleUuid, key]);
+            await this.bumper.bumpForRole(roleUuid, conn);
+            await conn.commit();
+        }
+        catch (cause) {
+            await conn.rollback();
+            if (cause instanceof BadKeyError)
+                throw cause;
+            throw new core_1.AuthorizationUnavailableError('grant failed', cause);
+        }
+        finally {
+            await conn.release();
+        }
+    }
+    /** Revoke a key from a role (no-op if absent) + bump the version, atomically. */
+    async revoke(roleUuid, key) {
+        const conn = await this.pool.getConnection();
+        try {
+            await conn.beginTransaction();
+            await conn.query(`DELETE FROM \`${AUTHZ}\`.\`role_permission\` WHERE rp_role_uuid = ? AND rp_perm_key = ?`, [roleUuid, key]);
+            await this.bumper.bumpForRole(roleUuid, conn);
+            await conn.commit();
+        }
+        catch (cause) {
+            await conn.rollback();
+            throw new core_1.AuthorizationUnavailableError('revoke failed', cause);
+        }
+        finally {
+            await conn.release();
+        }
+    }
+    // ── Access bundles ────────────────────────────────────────────────────────
+    /** All active bundles + their resolved atomic keys, for the Access UI. */
+    async listBundles() {
+        try {
+            const bundles = await this.bundles.listActiveBundlesWithKeys();
+            return { bundles };
+        }
+        catch (cause) {
+            throw new core_1.AuthorizationUnavailableError('access bundles unavailable', cause);
+        }
+    }
+    /**
+     * Grant a bundle to a role: resolve the bundle → its atomic keys, then INSERT each
+     * into `role_permission` idempotently in ONE transaction with ONE version bump.
+     * An unknown / orphaned bundle → `BadKeyError` (mapped to 400 by the controller).
+     */
+    async grantBundle(roleUuid, bundleKey, actorUuid) {
+        const keys = await this.resolveBundleKeysOrThrow(bundleKey);
+        const conn = await this.pool.getConnection();
+        try {
+            await conn.beginTransaction();
+            for (const key of keys) {
+                // Idempotent — UNIQUE (rp_role_uuid, rp_perm_key); a duplicate is a no-op.
+                await conn.query(`INSERT INTO \`${AUTHZ}\`.\`role_permission\`
+             (rp_uuid, rp_role_uuid, rp_perm_key, rp_granted_at, rp_granted_by)
+             SELECT UUID(), ?, ?, UTC_TIMESTAMP(), ?
+              WHERE NOT EXISTS (
+                SELECT 1 FROM \`${AUTHZ}\`.\`role_permission\` WHERE rp_role_uuid = ? AND rp_perm_key = ?
+              )`, [roleUuid, key, actorUuid ?? null, roleUuid, key]);
+            }
+            await this.bumper.bumpForRole(roleUuid, conn);
+            await conn.commit();
+        }
+        catch (cause) {
+            await conn.rollback();
+            throw new core_1.AuthorizationUnavailableError('grant bundle failed', cause);
+        }
+        finally {
+            await conn.release();
+        }
+    }
+    /**
+     * Revoke a bundle from a role: resolve → DELETE each of the bundle's atomic keys, in
+     * ONE transaction with ONE version bump. Caveat (design §5.1): this removes exactly the
+     * bundle's keys even if a manual grant or another bundle shares one — the model is
+     * key-based, not bundle-membership-based. Unknown bundle → `BadKeyError`.
+     */
+    async revokeBundle(roleUuid, bundleKey) {
+        const keys = await this.resolveBundleKeysOrThrow(bundleKey);
+        const conn = await this.pool.getConnection();
+        try {
+            await conn.beginTransaction();
+            for (const key of keys) {
+                await conn.query(`DELETE FROM \`${AUTHZ}\`.\`role_permission\` WHERE rp_role_uuid = ? AND rp_perm_key = ?`, [roleUuid, key]);
+            }
+            await this.bumper.bumpForRole(roleUuid, conn);
+            await conn.commit();
+        }
+        catch (cause) {
+            await conn.rollback();
+            throw new core_1.AuthorizationUnavailableError('revoke bundle failed', cause);
+        }
+        finally {
+            await conn.release();
+        }
+    }
+    /** Resolve a bundle key → its atomic keys; throw BadKeyError when unknown/orphaned. */
+    async resolveBundleKeysOrThrow(bundleKey) {
+        let keys;
+        try {
+            keys = await this.bundles.resolveActiveBundleKeys(bundleKey);
+        }
+        catch (cause) {
+            throw new core_1.AuthorizationUnavailableError('access bundle lookup failed', cause);
+        }
+        if (keys === null)
+            throw new BadKeyError(bundleKey);
+        return keys;
+    }
+    /**
+     * Access-listing summary — SERVER-PAGED. One row per role that holds ≥1 grant, with its
+     * access summary (chips/counts), the covering preset (if any), and last-modified date +
+     * the GRANTOR'S NAME (resolved from `rp_granted_by` → `users.u_username`, never a raw
+     * uuid). Wildcard grants are expanded against the live catalog so counts/chips reflect
+     * the REAL effective set.
+     *
+     * Paging model: page over the DISTINCT granted roles (name search + sort + LIMIT/OFFSET
+     * + a COUNT for total), then compute the summary only for the page's roles. `sortBy` ∈
+     * {name, grantedAt, permCount}; name/grantedAt sort in SQL, permCount sorts the computed
+     * page (a per-role aggregate not cheaply sortable in SQL). Defaults: page 1, limit 25,
+     * sort name asc.
+     */
+    async listGrantsSummary(params) {
+        const page = Math.max(1, Math.trunc(params?.page ?? 1));
+        const limit = Math.min(200, Math.max(1, Math.trunc(params?.limit ?? 25)));
+        const offset = (page - 1) * limit;
+        const search = (params?.search ?? '').trim();
+        const dir = params?.sortOrder === 'desc' ? 'DESC' : 'ASC';
+        const sortBy = params?.sortBy ?? 'name';
+        try {
+            const { catalog } = await this.listCatalog();
+            const allKeys = catalog.map((c) => c.key);
+            const { bundles } = await this.listBundles();
+            // Distinct granted roles (a role appears iff it has ≥1 role_permission row), filtered
+            // by name search. Bind the LIKE term as a param (wildcards escaped).
+            const likeClause = search ? `AND r.r_name LIKE ?` : '';
+            const likeArgs = search ? [`%${search.replace(/[%_\\]/g, '\\$&')}%`] : [];
+            const [{ total = 0 } = {}] = (await this.pool.query(`SELECT COUNT(DISTINCT rp.rp_role_uuid) AS total
+           FROM \`${AUTHZ}\`.\`role_permission\` rp
+           JOIN \`shield_app\`.\`roles\` r ON r.r_uuid = rp.rp_role_uuid
+          WHERE 1 = 1 ${likeClause}`, likeArgs));
+            // The page of role uuids + name + latest-grant metadata. name/grantedAt sort in SQL;
+            // permCount falls back to a stable name sort here (re-sorted after aggregation).
+            const orderCol = sortBy === 'grantedAt' ? 'latest_at' : 'r.r_name';
+            const pageRoles = (await this.pool.query(`SELECT rp.rp_role_uuid AS role_uuid,
+                r.r_name        AS role_name,
+                MAX(rp.rp_granted_at) AS latest_at
+           FROM \`${AUTHZ}\`.\`role_permission\` rp
+           JOIN \`shield_app\`.\`roles\` r ON r.r_uuid = rp.rp_role_uuid
+          WHERE 1 = 1 ${likeClause}
+          GROUP BY rp.rp_role_uuid, r.r_name
+          ORDER BY ${orderCol} ${dir}, r.r_name ASC
+          LIMIT ? OFFSET ?`, [...likeArgs, limit, offset]));
+            if (pageRoles.length === 0) {
+                return { rows: [], total: Number(total), page, limit };
+            }
+            // Fetch grant keys + grantor names for JUST the page's roles.
+            const roleUuids = pageRoles.map((r) => r.role_uuid);
+            const ph = roleUuids.map(() => '?').join(', ');
+            const grantRows = (await this.pool.query(`SELECT rp.rp_role_uuid  AS role_uuid,
+                rp.rp_perm_key   AS perm_key,
+                rp.rp_granted_at AS granted_at,
+                u.u_username     AS granted_by_name
+           FROM \`${AUTHZ}\`.\`role_permission\` rp
+           LEFT JOIN \`shield_app\`.\`users\` u ON u.u_uuid = rp.rp_granted_by
+          WHERE rp.rp_role_uuid IN (${ph})`, roleUuids));
+            const byRole = new Map();
+            for (const row of grantRows) {
+                let e = byRole.get(row.role_uuid);
+                if (!e) {
+                    e = { rawKeys: [], latestAt: -1, latestBy: null };
+                    byRole.set(row.role_uuid, e);
+                }
+                e.rawKeys.push(row.perm_key);
+                const ts = row.granted_at ? new Date(row.granted_at).getTime() : -1;
+                if (ts > e.latestAt) {
+                    e.latestAt = ts;
+                    e.latestBy = row.granted_by_name ?? null;
+                }
+            }
+            const summaries = pageRoles.map((pr) => {
+                const e = byRole.get(pr.role_uuid) ?? { rawKeys: [], latestAt: -1, latestBy: null };
+                const effective = new Set((0, db_permission_facts_adapter_js_1.expandGrantKeys)(e.rawKeys, allKeys));
+                const typeKeys = new Set();
+                for (const key of effective) {
+                    const parts = key.split(':');
+                    const typeKey = parts.length === 3 ? parts[1] : undefined;
+                    if (typeKey)
+                        typeKeys.add(typeKey);
+                }
+                const preset = bundles.find((b) => b.permissionKeys.length > 0 && b.permissionKeys.every((k) => effective.has(k)))?.label ?? null;
+                return {
+                    roleUuid: pr.role_uuid,
+                    roleName: pr.role_name,
+                    objectCount: typeKeys.size,
+                    permCount: effective.size,
+                    chips: [...typeKeys].sort(),
+                    preset,
+                    grantedAt: e.latestAt >= 0 ? new Date(e.latestAt).toISOString() : null,
+                    grantedByName: e.latestBy,
+                };
+            });
+            // permCount isn't SQL-sortable (per-role aggregate) — sort the page here when asked.
+            if (sortBy === 'permCount') {
+                summaries.sort((a, b) => dir === 'DESC' ? b.permCount - a.permCount : a.permCount - b.permCount);
+            }
+            return { rows: summaries, total: Number(total), page, limit };
+        }
+        catch (cause) {
+            throw new core_1.AuthorizationUnavailableError('grants summary unavailable', cause);
+        }
+    }
+}
+exports.GrantAdminService = GrantAdminService;

package/dist/features/authz/mariadb-catalog-store.d.ts

@@ -0,0 +1,16 @@
+import type { Pool } from 'mariadb';
+import type { CatalogStore, CatalogPermissionRow } from '@astram/guard';
+/**
+ * CatalogStore impl over shield_authz.permission (raw parameterized SQL, mirroring
+ * permission-facts.adapter). The reconciler (framework) calls this; guard does no DB
+ * itself (ADR-0003).
+ */
+export declare class MariaDbCatalogStore implements CatalogStore {
+    private readonly pool;
+    constructor(pool: Pool);
+    listPermissions(): Promise<CatalogPermissionRow[]>;
+    upsertPermission(row: Omit<CatalogPermissionRow, 'status'>): Promise<boolean>;
+    markOrphaned(keys: readonly string[]): Promise<void>;
+    markActive(keys: readonly string[]): Promise<void>;
+}
+//# sourceMappingURL=mariadb-catalog-store.d.ts.map

package/dist/features/authz/mariadb-catalog-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mariadb-catalog-store.d.ts","sourceRoot":"","sources":["../../../src/features/authz/mariadb-catalog-store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAIxE;;;;GAIG;AACH,qBAAa,mBAAoB,YAAW,YAAY;IAC1C,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,IAAI;IAEjC,eAAe,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAelD,gBAAgB,CAAC,GAAG,EAAE,IAAI,CAAC,oBAAoB,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAW7E,YAAY,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IASpD,UAAU,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAQzD"}

package/dist/features/authz/mariadb-catalog-store.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MariaDbCatalogStore = void 0;
+const AUTHZ = 'shield_authz';
+/**
+ * CatalogStore impl over shield_authz.permission (raw parameterized SQL, mirroring
+ * permission-facts.adapter). The reconciler (framework) calls this; guard does no DB
+ * itself (ADR-0003).
+ */
+class MariaDbCatalogStore {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async listPermissions() {
+        const rows = (await this.pool.query(`SELECT perm_key, perm_module, perm_type_key, perm_action, perm_label, perm_tier, perm_status
+         FROM \`${AUTHZ}\`.\`permission\``));
+        return rows.map((r) => ({
+            permissionKey: r.perm_key, moduleKey: r.perm_module, typeKey: r.perm_type_key,
+            action: r.perm_action, label: r.perm_label, tier: r.perm_tier,
+            status: r.perm_status === 'orphaned' ? 'orphaned' : 'active',
+        }));
+    }
+    async upsertPermission(row) {
+        const res = (await this.pool.query(`INSERT INTO \`${AUTHZ}\`.\`permission\`
+         (perm_uuid, perm_key, perm_module, perm_type_key, perm_action, perm_label, perm_tier, perm_status)
+         SELECT UUID(), ?, ?, ?, ?, ?, ?, 'active'
+          WHERE NOT EXISTS (SELECT 1 FROM \`${AUTHZ}\`.\`permission\` WHERE perm_key = ?)`, [row.permissionKey, row.moduleKey, row.typeKey, row.action, row.label, row.tier, row.permissionKey]));
+        return Number(res?.affectedRows ?? 0) > 0;
+    }
+    async markOrphaned(keys) {
+        if (keys.length === 0)
+            return;
+        const ph = keys.map(() => '?').join(', ');
+        await this.pool.query(`UPDATE \`${AUTHZ}\`.\`permission\` SET perm_status = 'orphaned' WHERE perm_key IN (${ph})`, [...keys]);
+    }
+    async markActive(keys) {
+        if (keys.length === 0)
+            return;
+        const ph = keys.map(() => '?').join(', ');
+        await this.pool.query(`UPDATE \`${AUTHZ}\`.\`permission\` SET perm_status = 'active' WHERE perm_key IN (${ph})`, [...keys]);
+    }
+}
+exports.MariaDbCatalogStore = MariaDbCatalogStore;

package/dist/features/authz/permission-version.bumper.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The minimal query surface this writer needs — a `mariadb` `Pool` (or `PoolConnection`)
+ * satisfies it structurally, but the type itself stays framework-agnostic so this signature
+ * doesn't force `mariadb` on callers (mirrors `RuleQueryable` in `@astram/guard`).
+ */
+export interface Queryable {
+    query(sql: string, params?: readonly unknown[]): Promise<unknown>;
+}
+/**
+ * PermissionVersionBumper — the WRITER side of ADR-0011: increments a tenant's
+ * `shield_authz.authz_permission_version` so `loadCoarseGrants` marks cached facts stale →
+ * gate 5 reloads → a role gain/loss (from a posting change) lands WITHOUT re-login. Runs the
+ * INSERT-or-increment over a supplied connection (the sealed authz pool, or a transaction
+ * connection so the bump joins the caller's write). Fail-safe: the caller wraps a bump failure
+ * so it never fails the membership/posting write. Never logs the tenant or the query.
+ *
+ * NOTE — the two bump methods do NOT share an error contract:
+ *  - `bumpForTenant` propagates the raw underlying error unwrapped; it is up to ITS caller
+ *    (the Phase 3 membership/posting write) to swallow it fail-safe, per the paragraph above.
+ *  - `bumpForRole` wraps a failure in `AuthorizationUnavailableError` and THROWS (see its own
+ *    doc comment below) — do not assume it is also fail-safe.
+ */
+export declare class PermissionVersionBumper {
+    /**
+     * Increment the permission version for a SINGLE tenant — for events that change a
+     * principal's EFFECTIVE grants without touching `role_permission` directly (a
+     * MEMBERSHIP/POSTING change: a user gaining or losing a role in a company).
+     */
+    bumpForTenant(tenantUuid: string, conn: Queryable): Promise<void>;
+    /**
+     * Increment the permission version for EVERY tenant where the role is ACTIVELY posted —
+     * for a role↔permission GRANT/REVOKE (which changes the effective grants of every principal
+     * holding that role in a company). Finds the tenants via the active membership+posting join,
+     * bumps each. Returns the bumped tenant uuids. A role with no active postings bumps nothing.
+     *
+     * NOTE — unlike `bumpForTenant` (which propagates its error raw and relies on the caller to
+     * swallow it fail-safe), THIS method wraps any failure in `AuthorizationUnavailableError` and
+     * THROWS: a role grant/revoke MUST fail loudly if the version bump can't be applied — a
+     * silently-stale bump would leave a removed grant still honored. The grant-admin caller
+     * decides how to handle it (ideally in the same transaction as the `role_permission` write,
+     * so both roll back together).
+     */
+    bumpForRole(roleUuid: string, conn: Queryable): Promise<string[]>;
+    /** The raw per-tenant increment (INSERT-or-increment). */
+    private bumpTenant;
+}
+//# sourceMappingURL=permission-version.bumper.d.ts.map

package/dist/features/authz/permission-version.bumper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-version.bumper.d.ts","sourceRoot":"","sources":["../../../src/features/authz/permission-version.bumper.ts"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,uBAAuB;IAClC;;;;OAIG;IACG,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvE;;;;;;;;;;;;OAYG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAmBvE,0DAA0D;YAC5C,UAAU;CAQzB"}

package/dist/features/authz/permission-version.bumper.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PermissionVersionBumper = void 0;
+const core_1 = require("@astram/core");
+/** Schema the `authz_permission_version` table lives in (ADR-0011). */
+const AUTHZ = 'shield_authz';
+/** Schema the membership/posting tables live in — the join `bumpForRole` walks. */
+const APP = 'shield_app';
+/**
+ * PermissionVersionBumper — the WRITER side of ADR-0011: increments a tenant's
+ * `shield_authz.authz_permission_version` so `loadCoarseGrants` marks cached facts stale →
+ * gate 5 reloads → a role gain/loss (from a posting change) lands WITHOUT re-login. Runs the
+ * INSERT-or-increment over a supplied connection (the sealed authz pool, or a transaction
+ * connection so the bump joins the caller's write). Fail-safe: the caller wraps a bump failure
+ * so it never fails the membership/posting write. Never logs the tenant or the query.
+ *
+ * NOTE — the two bump methods do NOT share an error contract:
+ *  - `bumpForTenant` propagates the raw underlying error unwrapped; it is up to ITS caller
+ *    (the Phase 3 membership/posting write) to swallow it fail-safe, per the paragraph above.
+ *  - `bumpForRole` wraps a failure in `AuthorizationUnavailableError` and THROWS (see its own
+ *    doc comment below) — do not assume it is also fail-safe.
+ */
+class PermissionVersionBumper {
+    /**
+     * Increment the permission version for a SINGLE tenant — for events that change a
+     * principal's EFFECTIVE grants without touching `role_permission` directly (a
+     * MEMBERSHIP/POSTING change: a user gaining or losing a role in a company).
+     */
+    async bumpForTenant(tenantUuid, conn) {
+        await this.bumpTenant(tenantUuid, conn);
+    }
+    /**
+     * Increment the permission version for EVERY tenant where the role is ACTIVELY posted —
+     * for a role↔permission GRANT/REVOKE (which changes the effective grants of every principal
+     * holding that role in a company). Finds the tenants via the active membership+posting join,
+     * bumps each. Returns the bumped tenant uuids. A role with no active postings bumps nothing.
+     *
+     * NOTE — unlike `bumpForTenant` (which propagates its error raw and relies on the caller to
+     * swallow it fail-safe), THIS method wraps any failure in `AuthorizationUnavailableError` and
+     * THROWS: a role grant/revoke MUST fail loudly if the version bump can't be applied — a
+     * silently-stale bump would leave a removed grant still honored. The grant-admin caller
+     * decides how to handle it (ideally in the same transaction as the `role_permission` write,
+     * so both roll back together).
+     */
+    async bumpForRole(roleUuid, conn) {
+        try {
+            const rows = (await conn.query(`SELECT DISTINCT cm.cm_company_uuid AS tenant
+           FROM \`${APP}\`.\`company_membership\` cm
+           JOIN \`${APP}\`.\`membership_posting\` mp ON mp.mp_membership_uuid = cm.cm_uuid
+          WHERE mp.mp_role_uuid = ? AND cm.cm_is_active = 1`, [roleUuid]));
+            const tenants = rows.map((r) => r.tenant);
+            for (const tenant of tenants) {
+                await this.bumpTenant(tenant, conn);
+            }
+            return tenants;
+        }
+        catch (cause) {
+            throw new core_1.AuthorizationUnavailableError('permission version bump failed', cause);
+        }
+    }
+    /** The raw per-tenant increment (INSERT-or-increment). */
+    async bumpTenant(tenantUuid, conn) {
+        await conn.query(`INSERT INTO \`${AUTHZ}\`.\`authz_permission_version\` (apv_tenant_uuid, apv_version)
+         VALUES (?, 1)
+       ON DUPLICATE KEY UPDATE apv_version = apv_version + 1`, [tenantUuid]);
+    }
+}
+exports.PermissionVersionBumper = PermissionVersionBumper;

package/dist/features/authz/record-authorization.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Assemble the record-tier authorization wiring for `@astram/identity`: the lean grant-read
+ * pool factory + the `recordAuthorization` inputs the consumer passes to
+ * `ShieldModule.forRoot({ recordAuthorization })`. Once wired, `decide()` becomes REAL (the
+ * framework's four record-tier adapters are built internally over the supplied pool) instead
+ * of the deny-everything stub.
+ *
+ * Modeled on astram3's `buildAuthorizationInputs` (`server/src/features/authz/authz.wiring.ts`),
+ * adapted to `@astram/identity`'s own registrations (`identityObjects`) and env prefix
+ * (`APP_DB_*`, per the Task-7 rename).
+ */
+import { type Pool } from 'mariadb';
+import { type RecordAuthorizationInputs } from '@astram/guard';
+/**
+ * A lean `mariadb` pool for the authz grant-reads (built from `APP_DB_*` env via guard's
+ * `loadDbConfig`). Kept small — these are pre-gate coarse-grant reads, not the main CRUD pool.
+ * Opens the pool at CALL time (never at import) — the consumer (app lifecycle) owns closing it.
+ */
+export declare function createIdentityAuthzPool(): Pool;
+/**
+ * Build the `RecordAuthorizationInputs` the consumer passes to
+ * `ShieldModule.forRoot({ recordAuthorization })`. The framework owns the four record-tier
+ * adapters internally; `@astram/identity` supplies only the app-schema ports:
+ *   - `permissionFacts` — coarse grants over `shield_authz.role_permission` +
+ *     `company_membership`/`membership_posting`,
+ *   - `sessionFacts` — the ADR-0011 ALS-backed per-request reader,
+ *   - `registry` — bridged from `identityObjects`,
+ *   - `operationManifest` — empty (identity declares no trusted delegated operations).
+ */
+export declare function buildIdentityRecordAuthorization(pool: Pool): RecordAuthorizationInputs;
+//# sourceMappingURL=record-authorization.d.ts.map

package/dist/features/authz/record-authorization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-authorization.d.ts","sourceRoot":"","sources":["../../../src/features/authz/record-authorization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAgB,EAAE,KAAK,IAAI,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,EAA6C,KAAK,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAK1G;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAU9C;AAED;;;;;;;;;GASG;AACH,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,IAAI,GAAG,yBAAyB,CAStF"}