@astram/identity 0.4.0 → 0.6.0

package/dist/features/membership/posting.service.js

@@ -7,18 +7,19 @@
  * diffs current-vs-desired and applies the minimal change — delete only what's removed,
  * create only what's added, keep the rest untouched.
  *
- * ── Atomicity / mid-op safety (why delete-then-create is safe here) ──────────────────
- * The engine's feature-facing surface (`RecordsService`) exposes NO cross-call transaction
- * — each of its methods (create/update/delete/list/get) runs in its OWN transaction, and
- * no `externalQueryRunner` seam is handed to features. So `replacePostings` cannot wrap
- * the whole diff in a single DB transaction. Instead it is safe BY CONSTRUCTION:
- *   - Deletes target ONLY rows absent from `desired` (the "removed" set). A KEPT posting
- *     is never a delete target, so it is never removed.
- *   - Creates target ONLY rows absent from `current` (the "added" set).
- * Therefore the membership NEVER lands empty mid-op: even if a create fails after the
- * delete phase, every kept posting is still present (never deleted). Ordering is
- * delete-first, then create; a failure surfaces to the caller (fail-closed) with the
- * kept set intact. (Covered by the mid-op-safety tests in posting.service.spec.ts.)
+ * ── Authority (security hardening #11) ─────────────────────────────────────────────────
+ * A posting IS a role assignment, so before ANY write the actor (the request principal) must:
+ *   - reach the membership (a walled `records.get` → null ⇒ 404; the engine's ADR-0034 create
+ *     wall re-checks the posting's membership company inside the transaction);
+ *   - for every ADDED role: the role is bound within the actor's subtree or not bound at all
+ *     (`GrantCeiling.assertRoleAssignable` — a role also used elsewhere is never assignable),
+ *     and the role's keys are all held by the actor (`assertCanAssignRoles`, ADR-0029 applied to
+ *     assignment). Removals need no ceiling: self-demotion stays allowed.
+ *
+ * ── Atomicity (KI #16) ────────────────────────────────────────────────────────────────
+ * The diff runs inside ONE `records.transaction` (ADR-0034): creates FIRST, then deletes, so a
+ * failure at any point rolls back every posting write of the replace (no partial set, no
+ * window where a removed role is gone but its replacement was refused).
  */
 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;
@@ -37,8 +38,18 @@ exports.PostingService = void 0;
 const common_1 = require("@nestjs/common");
 const engine_1 = require("@astram/engine");
 const posting_version_bump_js_1 = require("./posting-version-bump.js");
+const grant_ceiling_js_1 = require("../authz/grant-ceiling.js");
+const identity_errors_js_1 = require("../shared/identity-errors.js");
 /** The field keys whose values are effective-window epoch-ms bounds (normalized on write). */
 const WINDOW_KEYS = new Set(['effectiveFrom', 'effectiveUntil']);
+/** The ONLY keys a client posting entry may set (review F4) — never `membershipUuid`. */
+const POSTING_KEYS = [
+    'roleUuid',
+    'departmentUuid',
+    'branchUuid',
+    'effectiveFrom',
+    'effectiveUntil',
+];
 /**
  * Normalize an effective-window bound to epoch-ms (a `number`), or `null` if empty/unparseable.
  * The membership_posting object declares these fields as `number` (BIGINT epoch-ms) so the
@@ -79,7 +90,13 @@ function naturalKey(p) {
  */
 function stripEmpty(input) {
     const out = {};
-    for (const [k, v] of Object.entries(input)) {
+    // Security review F4: only the posting's own fields are taken from the client entry — a
+    // client `membershipUuid` (or `createdBy`, or any unknown key) never reaches the engine; the
+    // caller sets `membershipUuid` from the PATH.
+    for (const k of POSTING_KEYS) {
+        if (!(k in input))
+            continue;
+        const v = input[k];
         if (WINDOW_KEYS.has(k)) {
             const ms = toEpochMs(v);
             if (ms !== null)
@@ -93,9 +110,14 @@ function stripEmpty(input) {
 }
 let PostingService = class PostingService {
     records;
+    ceiling;
     versionBump;
-    constructor(records, versionBump) {
+    constructor(records, 
+    // The role-assignment ceiling + binding rule (security hardening #11). REQUIRED: a missing
+    // ceiling must fail DI at boot, never silently skip the check.
+    ceiling, versionBump) {
         this.records = records;
+        this.ceiling = ceiling;
         this.versionBump = versionBump;
     }
     /** List a membership's postings (tenant-scoped by the pipe). */
@@ -106,45 +128,75 @@ let PostingService = class PostingService {
     /**
      * Replace a membership's full posting set with `desired`, applying the minimal diff.
      * Compares current vs desired by the natural key `roleUuid|departmentUuid|branchUuid`:
-     * deletes removed rows, creates added rows, leaves kept rows untouched. See the file
-     * header for the atomicity / mid-op-safety reasoning (delete-then-create is safe because
-     * kept postings are never delete targets, so the membership never lands empty).
+     * creates added rows, deletes removed rows, leaves kept rows untouched. Every authority check
+     * runs BEFORE any write; the writes run in one transaction (see the file header).
      */
-    async replacePostings(membershipUuid, desired) {
-        const current = (await this.records.list('membership_posting', { where: { membershipUuid } })).rows;
+    async replacePostings(actor, membershipUuid, desired) {
+        for (const d of desired) {
+            if (typeof d?.roleUuid !== 'string' || d.roleUuid.length === 0) {
+                throw new identity_errors_js_1.IdentityBadRequestError('Every assignment needs a role.');
+            }
+        }
+        // 1) Reach: the membership must be visible through the subtree read wall (else 404).
+        const membership = await this.records.get('company_membership', membershipUuid);
+        if (membership === null)
+            throw new identity_errors_js_1.IdentityNotFoundError('Membership not found.');
+        const tenantUuid = typeof membership.fields?.companyUuid === 'string' && membership.fields.companyUuid.length > 0
+            ? membership.fields.companyUuid
+            : null;
+        const current = (await this.records.list('membership_posting', { where: { membershipUuid } }))
+            .rows;
         const desiredKeys = new Set(desired.map(naturalKey));
         const currentKeys = new Set(current.map((r) => naturalKey(r.fields)));
-        // Track whether the diff actually changed anything — only a real add/remove of a role
-        // assignment need invalidate cached permission facts (a no-op replace must not bump).
-        let changed = false;
-        // Delete removed: rows in current whose key is not in desired. Kept rows are skipped.
-        for (const r of current) {
-            const key = naturalKey(r.fields);
-            if (!desiredKeys.has(key)) {
-                await this.records.delete('membership_posting', r.id);
-                changed = true;
-            }
+        const removed = current.filter((r) => !desiredKeys.has(naturalKey(r.fields)));
+        const seenAdded = new Set();
+        const added = desired.filter((d) => {
+            const k = naturalKey(d);
+            if (currentKeys.has(k) || seenAdded.has(k))
+                return false;
+            seenAdded.add(k);
+            return true;
+        });
+        // 2) Authority for every ADDED role, before any write: binding rule, then the ceiling.
+        const addedRoles = [...new Set(added.map((d) => d.roleUuid))];
+        for (const roleUuid of addedRoles) {
+            await this.ceiling.assertRoleAssignable(actor, roleUuid);
         }
-        // Create added: desired rows whose key is not already present. Only real fields are
-        // sent (undefined/null/empty optionals are dropped so the engine gets a clean field map).
-        for (const d of desired) {
-            if (!currentKeys.has(naturalKey(d))) {
-                await this.records.create('membership_posting', {
-                    fields: { membershipUuid, ...stripEmpty(d) },
-                });
-                changed = true;
-            }
+        await this.ceiling.assertCanAssignRoles(actor, addedRoles);
+        // Removing a PEER's postings strips their authority: the actor must dominate the member
+        // (security review). Removing your OWN postings (self-demotion) stays allowed.
+        const memberUuid = typeof membership.fields?.userUuid === 'string' ? membership.fields.userUuid : '';
+        if (removed.length > 0 && memberUuid !== actor.id) {
+            await this.ceiling.assertDominates(actor, memberUuid);
         }
+        if (added.length === 0 && removed.length === 0)
+            return; // no-op replace: no write, no bump
+        // 3) Write atomically: creates first, then deletes (KI #16). Only whitelisted fields are sent,
+        //    and `membershipUuid` always comes from the path (review F4).
+        await this.records.transaction(async (tx) => {
+            // Review F2: serialise against a concurrent grant/posting of the same role. Lock each
+            // added role row on THIS transaction (grant administration locks the same row), then
+            // re-run the binding rule: a binding another tenant committed while we waited is now
+            // visible, and a role that became shared is refused before the INSERT (rolled back).
+            for (const roleUuid of addedRoles) {
+                await tx.lockForUpdate('role', roleUuid);
+                await this.ceiling.assertRoleAssignable(actor, roleUuid);
+            }
+            for (const d of added) {
+                await tx.create('membership_posting', { fields: { ...stripEmpty(d), membershipUuid } });
+            }
+            for (const r of removed) {
+                await tx.delete('membership_posting', r.id);
+            }
+        });
         // ADR-0011 STALENESS FIX: a posting add/remove changes the effective roles (→ coarse
         // grants) of the membership's user in that company, so bump the tenant's permission
         // version — every live session in that tenant then reloads its cached facts on the next
-        // request (a role gain/loss lands within the version bound). Only when something actually
-        // changed, and only when the bump collaborator is wired (absent in unit tests → no-op).
-        // Best-effort + fail-safe: the posting write already succeeded, so a bump failure must
-        // NOT surface as a 500 that hides a successful assignment change — the cache is instead
-        // invalidated by the next legit bump / the facts' natural TTL. We log-swallow it.
-        if (changed && this.versionBump) {
-            const tenantUuid = await this.resolveMembershipTenant(membershipUuid);
+        // request (a role gain/loss lands within the version bound). Only when the bump collaborator
+        // is wired (absent in unit tests → no-op). Best-effort + fail-safe: the posting write already
+        // committed, so a bump failure must NOT surface as a 500 that hides a successful assignment
+        // change — the cache is instead invalidated by the next legit bump / the facts' natural TTL.
+        if (this.versionBump) {
             if (tenantUuid) {
                 try {
                     await this.versionBump.bumpTenant(tenantUuid);
@@ -155,27 +207,12 @@ let PostingService = class PostingService {
             }
         }
     }
-    /**
-     * Resolve the tenant (company uuid) a membership belongs to — the tenant whose permission
-     * version a posting change must bump. Reads the parent `company_membership` through the
-     * pipe (tenant-scoped, no raw SQL), returning `companyUuid` or `null` if unresolvable
-     * (then no bump — fail-safe; never guesses a tenant).
-     */
-    async resolveMembershipTenant(membershipUuid) {
-        try {
-            const m = await this.records.get('company_membership', membershipUuid);
-            const companyUuid = m?.fields?.companyUuid;
-            return typeof companyUuid === 'string' && companyUuid.length > 0 ? companyUuid : null;
-        }
-        catch {
-            return null;
-        }
-    }
 };
 exports.PostingService = PostingService;
 exports.PostingService = PostingService = __decorate([
     (0, common_1.Injectable)(),
-    __param(1, (0, common_1.Optional)()),
-    __param(1, (0, common_1.Inject)(posting_version_bump_js_1.POSTING_VERSION_BUMP)),
-    __metadata("design:paramtypes", [engine_1.RecordsService, Object])
+    __param(2, (0, common_1.Optional)()),
+    __param(2, (0, common_1.Inject)(posting_version_bump_js_1.POSTING_VERSION_BUMP)),
+    __metadata("design:paramtypes", [engine_1.RecordsService,
+        grant_ceiling_js_1.GrantCeiling, Object])
 ], PostingService);

package/dist/features/org-structure/org-catalog.controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"org-catalog.controller.d.ts","sourceRoot":"","sources":["../../../src/features/org-structure/org-catalog.controller.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAU7D,qBACa,oBAAoB;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,iBAAiB;IAEvD,kFAAkF;IAG5E,sBAAsB,CAAuB,WAAW,EAAE,MAAM;;;IAKtE,+EAA+E;IAGzE,mBAAmB,CAAuB,WAAW,EAAE,MAAM;;;CAIpE"}
+{"version":3,"file":"org-catalog.controller.d.ts","sourceRoot":"","sources":["../../../src/features/org-structure/org-catalog.controller.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAU7D,qBAEa,oBAAoB;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,iBAAiB;IAEvD,kFAAkF;IAG5E,sBAAsB,CAAuB,WAAW,EAAE,MAAM;;;IAKtE,+EAA+E;IAGzE,mBAAmB,CAAuB,WAAW,EAAE,MAAM;;;CAIpE"}

package/dist/features/org-structure/org-catalog.controller.js

@@ -14,6 +14,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OrgCatalogController = void 0;
 const common_1 = require("@nestjs/common");
+const identity_error_interceptor_js_1 = require("../shared/identity-error.interceptor.js");
 const guard_1 = require("@astram/guard");
 const org_catalog_service_js_1 = require("./org-catalog.service.js");
 // ── Company-scoped catalogs (dept/branch option lists for the posting editor) ──
@@ -58,5 +59,6 @@ __decorate([
 ], OrgCatalogController.prototype, "listCompanyBranches", null);
 exports.OrgCatalogController = OrgCatalogController = __decorate([
     (0, common_1.Controller)('identity'),
+    (0, common_1.UseInterceptors)(identity_error_interceptor_js_1.IdentityErrorInterceptor),
     __metadata("design:paramtypes", [org_catalog_service_js_1.OrgCatalogService])
 ], OrgCatalogController);

package/dist/features/org-structure/org-catalog.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"org-catalog.service.d.ts","sourceRoot":"","sources":["../../../src/features/org-structure/org-catalog.service.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,qBACa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAEpD,kFAAkF;IAClF,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAInE,+EAA+E;IAC/E,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAIhE,qFAAqF;YACvE,kBAAkB;CAiBjC"}
+{"version":3,"file":"org-catalog.service.d.ts","sourceRoot":"","sources":["../../../src/features/org-structure/org-catalog.service.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,qBACa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAEpD,kFAAkF;IAClF,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IASnE,+EAA+E;IAC/E,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAIhE,qFAAqF;YACvE,kBAAkB;CAoBjC"}

package/dist/features/org-structure/org-catalog.service.js

@@ -41,7 +41,10 @@ let OrgCatalogService = class OrgCatalogService {
                 continue;
             const view = await this.records.get(catalogTypeKey, refUuid);
             const name = view?.fields?.name;
-            options.push({ uuid: refUuid, name: typeof name === 'string' && name.length > 0 ? name : '(unknown)' });
+            options.push({
+                uuid: refUuid,
+                name: typeof name === 'string' && name.length > 0 ? name : '(unknown)',
+            });
         }
         return options;
     }

package/dist/features/policy/policy.controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policy.controller.d.ts","sourceRoot":"","sources":["../../../src/features/policy/policy.controller.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EACL,aAAa,EAId,MAAM,qBAAqB,CAAC;AAE7B,qFAAqF;AACrF,UAAU,aAAa;IACrB,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,qBACa,gBAAgB;IACf,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,aAAa;IAEpD;;;;;;;;OAQG;IAGG,MAAM,CAAmB,OAAO,CAAC,EAAE,MAAM;IAY/C;;;OAGG;IAGG,IAAI,CAAQ,GAAG,EAAE,aAAa,EAAoB,OAAO,CAAC,EAAE,MAAM;;;IAQxE;;;;;OAKG;IAGG,MAAM,CAAQ,GAAG,EAAE,aAAa,EAAU,IAAI,EAAE,YAAY;;;IAWlE;;;;OAIG;IAGG,MAAM,CAAQ,GAAG,EAAE,aAAa,EAAe,EAAE,EAAE,MAAM;;;CAShE"}
+{"version":3,"file":"policy.controller.d.ts","sourceRoot":"","sources":["../../../src/features/policy/policy.controller.ts"],"names":[],"mappings":"AAkCA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EACL,aAAa,EAId,MAAM,qBAAqB,CAAC;AAE7B,qFAAqF;AACrF,UAAU,aAAa;IACrB,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,qBAEa,gBAAgB;IACf,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,aAAa;IAEpD;;;;;;;;OAQG;IAGG,MAAM,CAAmB,OAAO,CAAC,EAAE,MAAM;IAY/C;;;OAGG;IAGG,IAAI,CAAQ,GAAG,EAAE,aAAa,EAAoB,OAAO,CAAC,EAAE,MAAM;;;IAQxE;;;;;OAKG;IAGG,MAAM,CAAQ,GAAG,EAAE,aAAa,EAAU,IAAI,EAAE,YAAY;;;IAWlE;;;;OAIG;IAGG,MAAM,CAAQ,GAAG,EAAE,aAAa,EAAe,EAAE,EAAE,MAAM;;;CAShE"}

package/dist/features/policy/policy.controller.js

@@ -33,6 +33,7 @@ exports.PolicyController = void 0;
  */
 const common_1 = require("@nestjs/common");
 const guard_1 = require("@astram/guard");
+const identity_error_interceptor_js_1 = require("../shared/identity-error.interceptor.js");
 const policy_service_js_1 = require("./policy.service.js");
 let PolicyController = class PolicyController {
     policies;
@@ -146,5 +147,6 @@ __decorate([
 ], PolicyController.prototype, "delete", null);
 exports.PolicyController = PolicyController = __decorate([
     (0, common_1.Controller)('identity'),
+    (0, common_1.UseInterceptors)(identity_error_interceptor_js_1.IdentityErrorInterceptor),
     __metadata("design:paramtypes", [policy_service_js_1.PolicyService])
 ], PolicyController);

package/dist/features/role/role.controller.d.ts

@@ -1,5 +1,6 @@
 import { RoleService } from './role.service.js';
 import { type ListQueryDto } from '../shared/list-query.js';
+import type { AuthedRequest } from '../shared/http.js';
 export declare class RoleController {
     private readonly roles;
     constructor(roles: RoleService);
@@ -24,13 +25,13 @@ export declare class RoleController {
      *  administrator, may read roles). */
     getRole(uuid: string): Promise<import("packages/engine/dist/types.js").RecordView | null>;
     /** Update a role — gated on `identity:role:update`. */
-    updateRole(uuid: string, body: {
+    updateRole(req: AuthedRequest, uuid: string, body: {
         name?: string;
     }): Promise<{
         success: boolean;
     }>;
     /** Delete a role — gated on `identity:role:delete`. */
-    deleteRole(uuid: string): Promise<{
+    deleteRole(req: AuthedRequest, uuid: string): Promise<{
         success: boolean;
     }>;
 }

package/dist/features/role/role.controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"role.controller.d.ts","sourceRoot":"","sources":["../../../src/features/role/role.controller.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAK5E,qBACa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,WAAW;IAE/C;;;;OAIG;IAGG,SAAS,CAAU,KAAK,EAAE,YAAY;;;;;;IAM5C,uDAAuD;IAGjD,UAAU,CAAS,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAKhD;0CACsC;IAGtC,OAAO,CAAgB,IAAI,EAAE,MAAM;IAInC,uDAAuD;IAGjD,UAAU,CAAgB,IAAI,EAAE,MAAM,EAAU,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAK7E,uDAAuD;IAGjD,UAAU,CAAgB,IAAI,EAAE,MAAM;;;CAI7C"}
+{"version":3,"file":"role.controller.d.ts","sourceRoot":"","sources":["../../../src/features/role/role.controller.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAOvD,qBAEa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,WAAW;IAE/C;;;;OAIG;IAGG,SAAS,CAAU,KAAK,EAAE,YAAY;;;;;;IAM5C,uDAAuD;IAGjD,UAAU,CAAS,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAKhD;0CACsC;IAGtC,OAAO,CAAgB,IAAI,EAAE,MAAM;IAInC,uDAAuD;IAGjD,UAAU,CACP,GAAG,EAAE,aAAa,EACV,IAAI,EAAE,MAAM,EACnB,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAMjC,uDAAuD;IAGjD,UAAU,CAAQ,GAAG,EAAE,aAAa,EAAiB,IAAI,EAAE,MAAM;;;CAIxE"}

package/dist/features/role/role.controller.js

@@ -17,9 +17,11 @@ const common_1 = require("@nestjs/common");
 const guard_1 = require("@astram/guard");
 const role_service_js_1 = require("./role.service.js");
 const list_query_js_1 = require("../shared/list-query.js");
+const identity_error_interceptor_js_1 = require("../shared/identity-error.interceptor.js");
 // Role management is gated on `identity:role:<action>` grants. `role` is CONTROL-plane
 // for ALL actions — including read: the capped root is the identity administrator (the
-// identity-administrator model), so it may list/read roles AND manage them.
+// identity-administrator model), so it may list/read roles AND manage them. Update/delete
+// also pass the role-binding rule (a role used outside the caller's subtree is root-only).
 let RoleController = class RoleController {
     roles;
     constructor(roles) {
@@ -46,13 +48,13 @@ let RoleController = class RoleController {
         return this.roles.getRole(uuid);
     }
     /** Update a role — gated on `identity:role:update`. */
-    async updateRole(uuid, body) {
-        await this.roles.updateRole(uuid, body ?? {});
+    async updateRole(req, uuid, body) {
+        await this.roles.updateRole(req.principal, uuid, { name: body?.name });
         return { success: true };
     }
     /** Delete a role — gated on `identity:role:delete`. */
-    async deleteRole(uuid) {
-        await this.roles.deleteRole(uuid);
+    async deleteRole(req, uuid) {
+        await this.roles.deleteRole(req.principal, uuid);
         return { success: true };
     }
 };
@@ -84,21 +86,24 @@ __decorate([
 __decorate([
     (0, common_1.Put)('roles/:uuid'),
     (0, guard_1.Classified)({ typeKey: 'role', action: 'update' }),
-    __param(0, (0, common_1.Param)('uuid')),
-    __param(1, (0, common_1.Body)()),
+    __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", [String, Object]),
+    __metadata("design:paramtypes", [Object, String, Object]),
     __metadata("design:returntype", Promise)
 ], RoleController.prototype, "updateRole", null);
 __decorate([
     (0, common_1.Delete)('roles/:uuid'),
     (0, guard_1.Classified)({ typeKey: 'role', action: 'delete' }),
-    __param(0, (0, common_1.Param)('uuid')),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Param)('uuid')),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [String]),
+    __metadata("design:paramtypes", [Object, String]),
     __metadata("design:returntype", Promise)
 ], RoleController.prototype, "deleteRole", null);
 exports.RoleController = RoleController = __decorate([
     (0, common_1.Controller)('identity'),
+    (0, common_1.UseInterceptors)(identity_error_interceptor_js_1.IdentityErrorInterceptor),
     __metadata("design:paramtypes", [role_service_js_1.RoleService])
 ], RoleController);

package/dist/features/role/role.service.d.ts

@@ -1,24 +1,55 @@
 import { RecordsService, type RecordId } from '@astram/engine';
+import type { Principal } from '@astram/core';
 import { type ListParams } from '../shared/list-query.js';
+import { GrantCeiling } from '../authz/grant-ceiling.js';
+import { GrantAdminService } from '../authz/grant-admin.service.js';
+import { type PostingVersionBump } from '../membership/posting-version-bump.js';
 /**
  * RoleService — role CRUD on the paved road, via the framework's RecordsService
- * facade. The facade supplies the acting identity (the request principal) —
- * this service never threads a Principal. No raw SQL, no RECORD_ENGINE.
+ * facade. The facade supplies the acting identity (the request principal) for the pipe;
+ * no raw SQL, no RECORD_ENGINE.
+ *
+ * Roles are a GLOBAL catalog, so renaming or deleting one changes every tenant that uses it (a
+ * delete cascades its postings). Security hardening #1 (D1 interim rule): update/delete first pass
+ * `GrantCeiling.assertRoleAdministrable` — the role must be bound inside the actor's subtree and
+ * nowhere outside it (a shared role is root-only). The engine's write wall still applies after.
  */
 export declare class RoleService {
     private readonly records;
-    constructor(records: RecordsService);
+    private readonly ceiling;
+    private readonly versionBump?;
+    private readonly grants?;
+    constructor(records: RecordsService, ceiling: GrantCeiling, versionBump?: (PostingVersionBump | null) | undefined, grants?: (GrantAdminService | null) | undefined);
     /** Create a role. */
     createRole(name: string): Promise<RecordId>;
     /** List roles (tenant-scoped by the pipe), with paging/search/sort. */
     listRoles(params?: ListParams): Promise<import("@astram/engine").RecordPage>;
     /** Read a single role. */
     getRole(uuid: string): Promise<import("@astram/engine").RecordView | null>;
-    /** Update a role. */
-    updateRole(uuid: string, patch: {
-        name?: string;
+    /** Rename a role — only a role the actor may administer (binding rule). Patch whitelisted. */
+    updateRole(actor: Principal, uuid: string, patch: {
+        name?: unknown;
     }): Promise<void>;
-    /** Delete a role. */
-    deleteRole(uuid: string): Promise<void>;
+    /**
+     * Delete a role — only a role the actor may administer (binding rule) AND whose every holder the
+     * actor dominates (Phase 8 #2: the delete cascades the holders' postings, stripping their
+     * authority). In ONE transaction: lock the role row (the posting and grant paths lock the same
+     * row first), re-check the binding rule and holder dominance against what is committed now, read
+     * the holder tenants (before the cascade removes the postings), then delete. After the commit,
+     * every holder tenant's permission version is bumped so cached roles drop at the next request.
+     * The bump runs after the commit, never before: an earlier bump would let a session reload the
+     * pre-delete roles under the new version. A bump failure throws (503) rather than leave holders'
+     * cached grants silently stale.
+     *
+     * The role's `role_permission` rows (shield_authz, no FK) and its place in every service
+     * account's `sa_role_ids` (read live by the API-key store) do not cascade, so before the delete,
+     * still under the role lock, `GrantAdminService.purgeRole` removes both in its own committed
+     * authz transaction — checking first that the actor may change each holding account, and
+     * bumping every tenant that used the role (account tenants included). Order is fail-closed: a
+     * failure after the purge leaves a role with no grants and no agents, never live grants or an
+     * agent carrying a deleted role. A re-created role gets a fresh uuid (the engine mints it), so
+     * it can never pick up anything left behind.
+     */
+    deleteRole(actor: Principal, uuid: string): Promise<void>;
 }
 //# sourceMappingURL=role.service.d.ts.map

package/dist/features/role/role.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"role.service.d.ts","sourceRoot":"","sources":["../../../src/features/role/role.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAK1E;;;;GAIG;AACH,qBACa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAEpD,qBAAqB;IACrB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI3C,uEAAuE;IACvE,SAAS,CAAC,MAAM,CAAC,EAAE,UAAU;IAI7B,0BAA0B;IAC1B,OAAO,CAAC,IAAI,EAAE,MAAM;IAIpB,qBAAqB;IACrB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjE,qBAAqB;IACrB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGxC"}
+{"version":3,"file":"role.service.d.ts","sourceRoot":"","sources":["../../../src/features/role/role.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uCAAuC,CAAC;AAK/C;;;;;;;;;GASG;AACH,qBACa,WAAW;IAEpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAKxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAK7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;gBAXP,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,YAAY,EAKrB,WAAW,CAAC,GAAE,kBAAkB,GAAG,IAAI,aAAA,EAKvC,MAAM,CAAC,GAAE,iBAAiB,GAAG,IAAI,aAAA;IAGpD,qBAAqB;IACrB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI3C,uEAAuE;IACvE,SAAS,CAAC,MAAM,CAAC,EAAE,UAAU;IAI7B,0BAA0B;IAC1B,OAAO,CAAC,IAAI,EAAE,MAAM;IAIpB,8FAA8F;IACxF,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO1F;;;;;;;;;;;;;;;;;;;OAmBG;IACG,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAoBhE"}

package/dist/features/role/role.service.js

@@ -8,22 +8,40 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 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.RoleService = void 0;
 const common_1 = require("@nestjs/common");
 const engine_1 = require("@astram/engine");
+const core_1 = require("@astram/core");
 const list_query_js_1 = require("../shared/list-query.js");
+const grant_ceiling_js_1 = require("../authz/grant-ceiling.js");
+const grant_admin_service_js_1 = require("../authz/grant-admin.service.js");
+const posting_version_bump_js_1 = require("../membership/posting-version-bump.js");
 const ROLE_SEARCH_FIELDS = ['name'];
 const ROLE_SORT_FIELDS = ['name', 'createdAt'];
 /**
  * RoleService — role CRUD on the paved road, via the framework's RecordsService
- * facade. The facade supplies the acting identity (the request principal) —
- * this service never threads a Principal. No raw SQL, no RECORD_ENGINE.
+ * facade. The facade supplies the acting identity (the request principal) for the pipe;
+ * no raw SQL, no RECORD_ENGINE.
+ *
+ * Roles are a GLOBAL catalog, so renaming or deleting one changes every tenant that uses it (a
+ * delete cascades its postings). Security hardening #1 (D1 interim rule): update/delete first pass
+ * `GrantCeiling.assertRoleAdministrable` — the role must be bound inside the actor's subtree and
+ * nowhere outside it (a shared role is root-only). The engine's write wall still applies after.
  */
 let RoleService = class RoleService {
     records;
-    constructor(records) {
+    ceiling;
+    versionBump;
+    grants;
+    constructor(records, ceiling, versionBump, grants) {
         this.records = records;
+        this.ceiling = ceiling;
+        this.versionBump = versionBump;
+        this.grants = grants;
     }
     /** Create a role. */
     createRole(name) {
@@ -37,17 +55,66 @@ let RoleService = class RoleService {
     getRole(uuid) {
         return this.records.get('role', uuid);
     }
-    /** Update a role. */
-    updateRole(uuid, patch) {
-        return this.records.update('role', uuid, { fields: patch });
+    /** Rename a role — only a role the actor may administer (binding rule). Patch whitelisted. */
+    async updateRole(actor, uuid, patch) {
+        await this.ceiling.assertRoleAdministrable(actor, uuid);
+        const fields = {};
+        if (typeof patch?.name === 'string')
+            fields.name = patch.name;
+        await this.records.update('role', uuid, { fields });
     }
-    /** Delete a role. */
-    deleteRole(uuid) {
-        return this.records.delete('role', uuid);
+    /**
+     * Delete a role — only a role the actor may administer (binding rule) AND whose every holder the
+     * actor dominates (Phase 8 #2: the delete cascades the holders' postings, stripping their
+     * authority). In ONE transaction: lock the role row (the posting and grant paths lock the same
+     * row first), re-check the binding rule and holder dominance against what is committed now, read
+     * the holder tenants (before the cascade removes the postings), then delete. After the commit,
+     * every holder tenant's permission version is bumped so cached roles drop at the next request.
+     * The bump runs after the commit, never before: an earlier bump would let a session reload the
+     * pre-delete roles under the new version. A bump failure throws (503) rather than leave holders'
+     * cached grants silently stale.
+     *
+     * The role's `role_permission` rows (shield_authz, no FK) and its place in every service
+     * account's `sa_role_ids` (read live by the API-key store) do not cascade, so before the delete,
+     * still under the role lock, `GrantAdminService.purgeRole` removes both in its own committed
+     * authz transaction — checking first that the actor may change each holding account, and
+     * bumping every tenant that used the role (account tenants included). Order is fail-closed: a
+     * failure after the purge leaves a role with no grants and no agents, never live grants or an
+     * agent carrying a deleted role. A re-created role gets a fresh uuid (the engine mints it), so
+     * it can never pick up anything left behind.
+     */
+    async deleteRole(actor, uuid) {
+        await this.ceiling.assertRoleAdministrable(actor, uuid);
+        const grants = this.grants;
+        if (!grants)
+            throw new core_1.AuthorizationUnavailableError('role grant purge is not configured');
+        const tenants = await this.records.transaction(async (tx) => {
+            await tx.lockForUpdate('role', uuid);
+            await this.ceiling.assertRoleAdministrable(actor, uuid);
+            await this.ceiling.assertDominatesRoleHolders(actor, uuid);
+            const affected = (await this.versionBump?.tenantsForRole?.(uuid)) ?? [];
+            await grants.purgeRole(uuid, actor);
+            await tx.delete('role', uuid);
+            return affected;
+        });
+        if (!this.versionBump)
+            return;
+        try {
+            for (const tenant of tenants)
+                await this.versionBump.bumpTenant(tenant);
+        }
+        catch (cause) {
+            throw new core_1.AuthorizationUnavailableError('permission version bump failed', cause);
+        }
     }
 };
 exports.RoleService = RoleService;
 exports.RoleService = RoleService = __decorate([
     (0, common_1.Injectable)(),
-    __metadata("design:paramtypes", [engine_1.RecordsService])
+    __param(2, (0, common_1.Optional)()),
+    __param(2, (0, common_1.Inject)(posting_version_bump_js_1.POSTING_VERSION_BUMP)),
+    __param(3, (0, common_1.Optional)()),
+    __param(3, (0, common_1.Inject)(grant_admin_service_js_1.GrantAdminService)),
+    __metadata("design:paramtypes", [engine_1.RecordsService,
+        grant_ceiling_js_1.GrantCeiling, Object, Object])
 ], RoleService);