@astram/identity 0.2.1 → 0.3.0

package/dist/features/identity-feature.module.js

@@ -33,9 +33,14 @@ const db_permission_facts_adapter_js_1 = require("./authz/db-permission-facts.ad
 const access_bundle_store_js_1 = require("./authz/access-bundle-store.js");
 const grant_admin_service_js_1 = require("./authz/grant-admin.service.js");
 const grant_admin_controller_js_1 = require("./authz/grant-admin.controller.js");
+const policy_service_js_1 = require("./policy/policy.service.js");
+const policy_controller_js_1 = require("./policy/policy.controller.js");
+const share_service_js_1 = require("./share/share.service.js");
+const share_controller_js_1 = require("./share/share.controller.js");
 const catalog_reconcile_job_js_1 = require("./authz/catalog-reconcile.job.js");
 const access_bundle_reconcile_job_js_1 = require("./authz/access-bundle-reconcile.job.js");
 const catalog_bootstrap_provider_js_1 = require("./authz/catalog-bootstrap.provider.js");
+const scope_closure_service_js_1 = require("./scope/scope-closure.service.js");
 const mariadb_audit_reader_js_1 = require("./audit/mariadb-audit-reader.js");
 const directory_label_resolver_js_1 = require("./audit/directory-label-resolver.js");
 const audit_read_service_js_1 = require("./audit/audit-read.service.js");
@@ -91,6 +96,12 @@ let IdentityFeatureModule = IdentityFeatureModule_1 = class IdentityFeatureModul
         // postingVersionBump closure pattern above).
         const accessBundleStore = new access_bundle_store_js_1.AccessBundleStore(authzPool);
         const grantAdminService = new grant_admin_service_js_1.GrantAdminService(authzPool, bumper, accessBundleStore);
+        // Scope closure (Task 1.2 of the scoped-hierarchy program): the reconciler + node
+        // move/delete maintenance, over the SAME shared authzPool (it reaches BOTH shield_app —
+        // companies — and shield_authz — scope_closure). Reuses the SAME `bumper` instance so a
+        // moveNode's session-invalidation joins the move's transaction. reconcileClosure() is
+        // kicked post-boot by the CatalogBootstrapProvider (mirrors the catalog reconcile).
+        const scopeClosureService = new scope_closure_service_js_1.ScopeClosureService(authzPool, bumper);
         // The core ModuleRegistry the catalog reconcile job needs, built from the identity
         // object registrations (guard's bridge reflects decorated classes → registry).
         const identityRegistry = (0, guard_1.buildIdentityModuleRegistry)([...objects_js_1.identityObjects]);
@@ -113,6 +124,14 @@ let IdentityFeatureModule = IdentityFeatureModule_1 = class IdentityFeatureModul
         // same record-authorization inputs (matches astram3): the route guard's own decide() is the
         // first; this one backs the writer's server-side re-verification.
         const crossTenantAuthority = (0, guard_1.buildRecordAuthorization)((0, record_authorization_js_1.buildIdentityRecordAuthorization)(authzPool));
+        // Record-level LIST SCOPE (Task 3.1, Invariant #8): the engine-facing fn the engine's
+        // `list()` ANDs into BOTH the data SELECT and the COUNT — the in-query visible-set filter.
+        // Built HERE, over the SAME shared authzPool (guard constructs the un-overridable scope
+        // adapter inside `buildListScopeFn`, mirroring the four record-tier read adapters). Wired
+        // out-of-the-box into `EngineModule.forRoot({ listScope })` below (ADR-0003 injection seam —
+        // the engine never imports guard). Fail-closed: a store outage propagates and `list()` fails
+        // rather than returning unscoped rows.
+        const listScope = (0, guard_1.buildListScopeFn)((0, record_authorization_js_1.buildIdentityRecordAuthorization)(authzPool));
         // The writer's `GrantAuthorizeFn`: decide()-backed, fail-closed (no try/catch — a throw
         // propagates and the writer maps it to a retryable 503). isRoot ← the SAME rootIds the
         // consumer passes to ShieldModule.forRoot (root-correctness for control-plane grants).
@@ -168,6 +187,101 @@ let IdentityFeatureModule = IdentityFeatureModule_1 = class IdentityFeatureModul
         // The read side (inbox/mine/incoming/offerable-types) over the same pool + the merged object
         // set (offerable = tenantScoped types only) + the per-type action vocabulary.
         const crossTenantGrantReadService = new cross_tenant_grant_read_service_js_1.CrossTenantGrantReadService(authzPool, [...objects_js_1.identityObjects], guard_1.actionsFor);
+        // ── GUIDED RULE-BUILDER (list-scoping engine Phase 5, §9.1) ──────────────────────────────
+        // The policy-authoring surface over the guard `MariaDbPolicyStore` + core `makeAuthorPolicy`.
+        // Reuses the SAME `identityRegistry` + `crossTenantAuthority` (a DecisionAuthority over the
+        // shared authzPool — the delegated-admin ceiling's decide()) as the cross-tenant writer. The
+        // core AuditSink is one-arg (`record(event)`); the engine `MariaDbAuditSink` is two-arg
+        // (`record(event, query)`) — so bind the query to the shared authzPool (mirrors the
+        // `grantAudit` bridge above). Best-effort audit (a sink throw must not fail the author).
+        const policyAuditSink = new engine_1.MariaDbAuditSink({}); // shield_audit.audit_log defaults
+        const policyAudit = {
+            record: async (event) => {
+                try {
+                    await policyAuditSink.record(event, (sql, params) => authzPool.query(sql, params));
+                }
+                catch {
+                    // Best-effort: an audit failure must not fail a legitimate policy author.
+                }
+            },
+        };
+        const policyStore = new guard_1.MariaDbPolicyStore(authzPool);
+        // The guided-builder SCHEMA source — the authorable field/action metadata, reflected from the
+        // registered identity object types (engine `reflectObjectType` yields fields WITH their
+        // `type`, which the core registry descriptor drops). Only tenantScoped, owned DATA-plane types
+        // are meaningfully policy-authorable in v1; but we expose every registered type's fields and
+        // let the delegated-admin ceiling + validateGuidedPolicy gate what a caller may actually
+        // author. A consumer's own types (extraObjects) would extend this the same way (future).
+        const schemaSource = [...objects_js_1.identityObjects].map((input) => {
+            const reg = typeof input === 'function' ? (0, engine_1.reflectObjectType)(input) : input;
+            return {
+                typeKey: reg.typeKey,
+                label: reg.typeKey,
+                actions: (0, guard_1.actionsFor)(reg.typeKey),
+                fields: reg.fields.map((f) => ({ key: f.key, type: f.type })),
+            };
+        });
+        const policyService = new policy_service_js_1.PolicyService({
+            registry: identityRegistry,
+            policyStore,
+            decide: crossTenantAuthority,
+            audit: policyAudit,
+            schemaSource,
+        });
+        // ── OWNER-SHARE surface (list-scoping engine Phase 6, §9.2) ──────────────────────────────
+        // The framework-owned RecordShareWriter (the who-may-share bound) + a ShareTypeResolver over
+        // the reflected identity object types (so guard never imports @astram/engine — the consumer
+        // resolves the physical share info here). Only `owned` types are shareable; the resolver
+        // surfaces `owned`/table/schema/pk/owner/tenant columns via the engine helpers. The writer's
+        // audit reuses the SAME shield_audit sink pattern (best-effort). The ShareService adds
+        // name-resolution (no raw uuid) via the existing DirectoryLabelResolver (`auditLabels`).
+        const shareTypeInfoByKey = new Map();
+        for (const input of objects_js_1.identityObjects) {
+            const reg = typeof input === 'function' ? (0, engine_1.reflectObjectType)(input) : input;
+            const owner = (0, engine_1.ownerColumn)(reg);
+            const pk = reg.primaryKey.kind === 'uuid' ? (0, engine_1.uuidPkColumn)(reg.primaryKey) : null;
+            // Only OWNED types with a uuid PK + an owner column are shareable; others are omitted (the
+            // writer rejects an unknown/non-owned type anyway — this map only lists real candidates).
+            if (!(0, engine_1.isOwned)(reg) || owner === null || pk === null)
+                continue;
+            const tenantCol = (0, engine_1.tenantColumnOf)(reg);
+            shareTypeInfoByKey.set(reg.typeKey, {
+                table: reg.table,
+                ...(reg.schema ? { schema: reg.schema } : {}),
+                pkColumn: pk,
+                ownerColumn: owner,
+                ...(tenantCol ? { tenantColumn: tenantCol } : {}),
+                owned: true,
+            });
+        }
+        const shareTypeResolver = {
+            resolve: (typeKey) => shareTypeInfoByKey.get(typeKey),
+        };
+        const shareAuditSink = new engine_1.MariaDbAuditSink({}); // shield_audit.audit_log
+        const recordShareWriter = new guard_1.RecordShareWriter({
+            db: authzPool,
+            types: shareTypeResolver,
+            audit: {
+                record: async (event) => {
+                    try {
+                        await shareAuditSink.record({
+                            // A share/unshare is access administration → 'admin_action' (a valid AuditEventType;
+                            // 'record_share' is the writer's own event tag, carried in `action`/attributes).
+                            type: 'admin_action',
+                            occurredAtMs: event.occurredAtMs,
+                            actorId: event.actorId,
+                            tenantId: event.tenantId,
+                            action: { key: event.action }, // 'share.created' | 'share.removed'
+                            attributes: { ...event.attributes, eventType: 'record_share' },
+                        }, (sql, params) => authzPool.query(sql, params));
+                    }
+                    catch {
+                        // Best-effort — an audit failure must never fail a legitimate share/unshare.
+                    }
+                },
+            },
+        });
+        const shareService = new share_service_js_1.ShareService(recordShareWriter, auditLabels);
         return {
             module: IdentityFeatureModule_1,
             imports: [
@@ -179,7 +293,11 @@ let IdentityFeatureModule = IdentityFeatureModule_1 = class IdentityFeatureModul
                 // snapshot is empty and no bundles reconcile into shield_authz.access_bundle.
                 engine_1.EngineModule.forFeature([], { accessBundles: index_js_1.identityAccessBundles }),
                 // The engine's runtime CRUD pipe + the identity object registrations.
-                engine_1.EngineModule.forRoot({ db: engineDbFromEnv(), registrations: [...objects_js_1.identityObjects] }),
+                engine_1.EngineModule.forRoot({
+                    db: engineDbFromEnv(),
+                    registrations: [...objects_js_1.identityObjects],
+                    listScope,
+                }),
                 // NestJS DiscoveryService/MetadataScanner — the boot bootstrap provider reflects the
                 // live controllers through this to build the OperationInventory.
                 core_1.DiscoveryModule,
@@ -200,6 +318,10 @@ let IdentityFeatureModule = IdentityFeatureModule_1 = class IdentityFeatureModul
                 // controller's own method order keeps the static sub-paths (/inbox, /offerable-types)
                 // ahead of `/:uuid/*`. Appended after the existing controllers.
                 cross_tenant_grant_controller_js_1.CrossTenantGrantController,
+                // Guided rule-builder (Phase 5) — `record-policies/*` collides with nothing. Appended last.
+                policy_controller_js_1.PolicyController,
+                // Owner shares (Phase 6) — `record-shares` collides with nothing. Appended last.
+                share_controller_js_1.ShareController,
             ],
             providers: [
                 company_service_js_1.CompanyService,
@@ -221,6 +343,12 @@ let IdentityFeatureModule = IdentityFeatureModule_1 = class IdentityFeatureModul
                 // wiring (the out-of-the-box acceptance bar).
                 { provide: guard_1.SHIELD_CROSS_TENANT_GRANT_WRITER, useValue: crossTenantGrantWriter },
                 { provide: cross_tenant_grant_read_service_js_1.CrossTenantGrantReadService, useValue: crossTenantGrantReadService },
+                // Guided rule-builder (Phase 5) — the PolicyService over the shared authzPool + registry
+                // + the SAME DecisionAuthority (delegated-admin ceiling). useValue like GrantAdminService.
+                { provide: policy_service_js_1.PolicyService, useValue: policyService },
+                // Owner shares (Phase 6) — the ShareService over the framework RecordShareWriter + the
+                // DirectoryLabelResolver (name resolution). useValue, all over the shared authzPool.
+                { provide: share_service_js_1.ShareService, useValue: shareService },
                 // The mutating half of auto-catalog: a single CatalogReconcileJob (post-boot pass +
                 // cron), over the shared pool + the identity registry.
                 { provide: catalog_reconcile_job_js_1.CatalogReconcileJob, useValue: new catalog_reconcile_job_js_1.CatalogReconcileJob(authzPool, identityRegistry) },
@@ -231,10 +359,14 @@ let IdentityFeatureModule = IdentityFeatureModule_1 = class IdentityFeatureModul
                     useFactory: (bundles) => new access_bundle_reconcile_job_js_1.AccessBundleReconcileJob(authzPool, bundles),
                     inject: [engine_1.ENGINE_ALL_ACCESS_BUNDLES],
                 },
+                // Scope closure reconciler + node move/delete maintenance (Task 1.2), built at forRoot()
+                // over the shared authzPool + the shared bumper, provided useValue so the bootstrap
+                // provider (and any future controller) injects the SAME instance.
+                { provide: scope_closure_service_js_1.ScopeClosureService, useValue: scopeClosureService },
                 // Boot: read-only verifyGatable (fail-closed). Post-boot: kicks the jobs once (catalog
-                // THEN bundles) + schedules them (DISABLE_ALL_CRONS-gated). Injects DiscoveryService/
-                // MetadataScanner/Reflector (from DiscoveryModule above), the two jobs, and
-                // ENGINE_ALL_REGISTRATIONS (exported by EngineModule).
+                // THEN bundles, THEN the scope-closure reconcile) + schedules them (DISABLE_ALL_CRONS-
+                // gated). Injects DiscoveryService/MetadataScanner/Reflector (from DiscoveryModule
+                // above), the jobs, the ScopeClosureService, and ENGINE_ALL_REGISTRATIONS.
                 catalog_bootstrap_provider_js_1.CatalogBootstrapProvider,
             ],
             exports: [company_service_js_1.CompanyService, role_service_js_1.RoleService, user_service_js_1.UserService],

package/dist/features/membership/membership-checker.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `DbMembershipChecker` — the identity-side implementation of the guard-defined
+ * `MembershipChecker` port (Task 5.2 of the scoped-hierarchy tenancy program,
+ * ADR-0027 / ADR-0024). It answers ONE question the scope-switch gate asks: does a
+ * principal HOLD an ACTIVE membership at a target node? A `true` is the ONLY thing
+ * that lets `POST /auth/scope-switch` re-bind the session to that node; anything else
+ * (a `false`, or a thrown store outage the guard swallows) is a fail-closed DENY.
+ *
+ * The answer is a SINGLE existence read over `shield_app.company_membership`:
+ *
+ *     SELECT 1 FROM shield_app.company_membership
+ *      WHERE cm_user_uuid = ? AND cm_company_uuid = ?
+ *        AND cm_is_active = 1 AND cm_status = 'active' LIMIT 1
+ *
+ * `cm_is_active = 1` is the first-class active-membership flag (a user has at most one
+ * active membership per company); `cm_status = 'active'` is the lifecycle status. BOTH
+ * are required — a de-activated OR non-active-status membership is NOT a valid switch
+ * target (least privilege: the switch confers the node's subtree + authority, so the
+ * binding must be genuinely live).
+ *
+ * ── LAYERING ────────────────────────────────────────────────────────────────────────
+ * The PORT (`MembershipChecker`) is defined in `@astram/guard`; this IMPLEMENTATION
+ * lives in `@astram/identity` (which owns the app schema + `company_membership`). The
+ * consumer injects an instance through `ShieldModule.forRoot({ membershipChecker })` —
+ * the same sanctioned direction as `DbScopeSubtreeResolver`. Guard never imports identity.
+ *
+ * ── FAIL-CLOSED ─────────────────────────────────────────────────────────────────────
+ * Returns `true` ONLY when the existence row is present. A store OUTAGE THROWS (the
+ * guard's scope-switch handler catches it → DENY): a check failure NEVER silently allows
+ * a switch. All SQL values are `?`-bound (never interpolated).
+ */
+import type { Pool } from 'mariadb';
+export declare class DbMembershipChecker {
+    private readonly pool;
+    constructor(pool: Pool);
+    /**
+     * Does `principalId` hold an ACTIVE membership at `nodeId`? A single existence read —
+     * `true` iff a row with `cm_is_active = 1 AND cm_status = 'active'` exists. Throws on a
+     * store outage (the guard's scope-switch gate catches it → fail-closed DENY).
+     */
+    hasActiveMembership(principalId: string, nodeId: string): Promise<boolean>;
+}
+//# sourceMappingURL=membership-checker.d.ts.map

package/dist/features/membership/membership-checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"membership-checker.d.ts","sourceRoot":"","sources":["../../../src/features/membership/membership-checker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAKpC,qBAAa,mBAAmB;IAClB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,IAAI;IAEvC;;;;OAIG;IACG,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAWjF"}

package/dist/features/membership/membership-checker.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DbMembershipChecker = void 0;
+/** Schema the membership table lives in (the app schema). */
+const APP = 'shield_app';
+class DbMembershipChecker {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    /**
+     * Does `principalId` hold an ACTIVE membership at `nodeId`? A single existence read —
+     * `true` iff a row with `cm_is_active = 1 AND cm_status = 'active'` exists. Throws on a
+     * store outage (the guard's scope-switch gate catches it → fail-closed DENY).
+     */
+    async hasActiveMembership(principalId, nodeId) {
+        const rows = (await this.pool.query(`SELECT 1 AS ok
+         FROM \`${APP}\`.\`company_membership\`
+        WHERE cm_user_uuid = ? AND cm_company_uuid = ?
+          AND cm_is_active = 1 AND cm_status = 'active'
+        LIMIT 1`, [principalId, nodeId]));
+        return rows.length > 0;
+    }
+}
+exports.DbMembershipChecker = DbMembershipChecker;

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

@@ -0,0 +1,46 @@
+import type { GuidedPolicy, Principal } from '@astram/core';
+import { PolicyService } from './policy.service.js';
+/** The request shape after the enforcement guard attaches the resolved principal. */
+interface AuthedRequest {
+    principal: Principal;
+}
+export declare class PolicyController {
+    private readonly policies;
+    constructor(policies: PolicyService);
+    /**
+     * The guided-builder SCHEMA for a type — its authorable fields (each with the operators the
+     * builder should offer, split into array/nullary families) + the type's actions.
+     * `GET /identity/record-policies/schema?typeKey=<key>`. Gated `role:read`. Server-derived so the
+     * builder's dropdowns never drift from enforcement. Unknown/non-authorable type → 404.
+     *
+     * ⚠️ Registered BEFORE `record-policies` (the `/schema` static sub-path) — Nest matches the
+     * first, and `record-policies/schema` is more specific than the bare `record-policies` GET.
+     */
+    schema(typeKey?: string): Promise<import("./policy.service.js").PolicyTypeSchema>;
+    /**
+     * List the record-access policies governing a type in the caller's tenant.
+     * `GET /identity/record-policies?typeKey=<key>`. Gated `role:read`.
+     */
+    list(req: AuthedRequest, typeKey?: string): Promise<{
+        policies: readonly import("@astram/core").Policy[];
+    }>;
+    /**
+     * Author a guided policy. `POST /identity/record-policies` with a {@link GuidedPolicy} body
+     * (typeKey, action, effect, structured conditions — NO raw expressions). Gated `role:update`;
+     * the delegated-admin ceiling + structural validation run inside the service. The target tenant
+     * is `req.principal.tenantId` — a body tenant is ignored.
+     */
+    author(req: AuthedRequest, body: GuidedPolicy): Promise<{
+        policy: import("@astram/core").Policy;
+    }>;
+    /**
+     * Delete a policy the caller owns. `DELETE /identity/record-policies/:id`. Gated `role:update`.
+     * TENANT-SCOPED: a foreign tenant's policy id → NotFound (the service can never delete another
+     * tenant's policy).
+     */
+    delete(req: AuthedRequest, id: string): Promise<{
+        success: boolean;
+    }>;
+}
+export {};
+//# sourceMappingURL=policy.controller.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,150 @@
+"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.PolicyController = void 0;
+/**
+ * `PolicyController` — the §9.1 GUIDED RULE-BUILDER authoring API (list-scoping engine Phase 5).
+ *
+ * Three routes over {@link PolicyService}; gated purely by `@Classified` + `decide()` (no
+ * handler-level root check). Authoring a record-access policy IS access administration — the same
+ * authority as managing grants — so it keys to the `role` object type (chosen 2026-07-23): 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 a grant; a non-root admin needs it.
+ * On TOP of the route gate, the delegated-admin ceiling (only-author-what-you-can-grant) is
+ * enforced INSIDE the service (core `makeAuthorPolicy` → `checkDelegatedAdmin`).
+ *
+ * ⚠️ Path is `record-policies` (NOT under `roles/...`) so it never collides with
+ * IdentityController's `roles/:uuid` or GrantAdminController's `access/*` routes.
+ *
+ * Authority is ALWAYS `req.principal` (the enforcement guard attached it) — a tenant in the body
+ * is IGNORED by the service (the target is `actor.tenantId`), so cross-tenant authoring is
+ * impossible by construction.
+ */
+const common_1 = require("@nestjs/common");
+const guard_1 = require("@astram/guard");
+const policy_service_js_1 = require("./policy.service.js");
+let PolicyController = class PolicyController {
+    policies;
+    constructor(policies) {
+        this.policies = policies;
+    }
+    /**
+     * The guided-builder SCHEMA for a type — its authorable fields (each with the operators the
+     * builder should offer, split into array/nullary families) + the type's actions.
+     * `GET /identity/record-policies/schema?typeKey=<key>`. Gated `role:read`. Server-derived so the
+     * builder's dropdowns never drift from enforcement. Unknown/non-authorable type → 404.
+     *
+     * ⚠️ Registered BEFORE `record-policies` (the `/schema` static sub-path) — Nest matches the
+     * first, and `record-policies/schema` is more specific than the bare `record-policies` GET.
+     */
+    async schema(typeKey) {
+        if (!typeKey || typeof typeKey !== 'string') {
+            throw new common_1.BadRequestException('typeKey required');
+        }
+        try {
+            return this.policies.schema(typeKey);
+        }
+        catch (e) {
+            if (e instanceof policy_service_js_1.PolicyNotFoundError)
+                throw new common_1.NotFoundException(e.message);
+            throw e;
+        }
+    }
+    /**
+     * List the record-access policies governing a type in the caller's tenant.
+     * `GET /identity/record-policies?typeKey=<key>`. Gated `role:read`.
+     */
+    async list(req, typeKey) {
+        if (!typeKey || typeof typeKey !== 'string') {
+            throw new common_1.BadRequestException('typeKey required');
+        }
+        const policies = await this.policies.list(req.principal, typeKey);
+        return { policies };
+    }
+    /**
+     * Author a guided policy. `POST /identity/record-policies` with a {@link GuidedPolicy} body
+     * (typeKey, action, effect, structured conditions — NO raw expressions). Gated `role:update`;
+     * the delegated-admin ceiling + structural validation run inside the service. The target tenant
+     * is `req.principal.tenantId` — a body tenant is ignored.
+     */
+    async author(req, body) {
+        try {
+            const policy = await this.policies.author(req.principal, body);
+            return { policy };
+        }
+        catch (e) {
+            if (e instanceof policy_service_js_1.InvalidPolicyError)
+                throw new common_1.BadRequestException(e.message);
+            if (e instanceof policy_service_js_1.PolicyAuthorDeniedError)
+                throw new common_1.ForbiddenException(e.message);
+            throw e; // transient (store/authority outage) → propagates → 503
+        }
+    }
+    /**
+     * Delete a policy the caller owns. `DELETE /identity/record-policies/:id`. Gated `role:update`.
+     * TENANT-SCOPED: a foreign tenant's policy id → NotFound (the service can never delete another
+     * tenant's policy).
+     */
+    async delete(req, id) {
+        try {
+            await this.policies.delete(req.principal, id);
+            return { success: true };
+        }
+        catch (e) {
+            if (e instanceof policy_service_js_1.PolicyNotFoundError)
+                throw new common_1.NotFoundException(e.message);
+            throw e;
+        }
+    }
+};
+exports.PolicyController = PolicyController;
+__decorate([
+    (0, common_1.Get)('record-policies/schema'),
+    (0, guard_1.Classified)({ typeKey: 'role', action: 'read' }),
+    __param(0, (0, common_1.Query)('typeKey')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], PolicyController.prototype, "schema", null);
+__decorate([
+    (0, common_1.Get)('record-policies'),
+    (0, guard_1.Classified)({ typeKey: 'role', action: 'read' }),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Query)('typeKey')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, String]),
+    __metadata("design:returntype", Promise)
+], PolicyController.prototype, "list", null);
+__decorate([
+    (0, common_1.Post)('record-policies'),
+    (0, guard_1.Classified)({ typeKey: 'role', action: 'update' }),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], PolicyController.prototype, "author", null);
+__decorate([
+    (0, common_1.Delete)('record-policies/:id'),
+    (0, guard_1.Classified)({ typeKey: 'role', action: 'update' }),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Param)('id')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, String]),
+    __metadata("design:returntype", Promise)
+], PolicyController.prototype, "delete", null);
+exports.PolicyController = PolicyController = __decorate([
+    (0, common_1.Controller)('identity'),
+    __metadata("design:paramtypes", [policy_service_js_1.PolicyService])
+], PolicyController);

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

@@ -0,0 +1,129 @@
+/**
+ * `PolicyService` — the backend of the §9.1 GUIDED RULE-BUILDER (list-scoping engine Phase 5).
+ *
+ * A thin authoring surface over the core `makeAuthorPolicy` command + the guard
+ * `MariaDbPolicyStore`. The core command already provides — and this service NEVER re-implements
+ * — validation (`validateGuidedPolicy`: known field, operator-valid-for-field-type, well-formed
+ * value; NO raw expressions), the delegated-admin ceiling (`checkDelegatedAdmin`: a non-root
+ * admin may author a policy ONLY over an `(action, typeKey)` they THEMSELVES hold — reusing the
+ * ONE decision authority), and the immutable audit record. This service:
+ *   • builds the `AdminMutation` from the SERVER-resolved principal — the target tenant is
+ *     ALWAYS `actor.tenantId`, NEVER the request body (a body tenant is ignored → a cross-tenant
+ *     author is impossible by construction);
+ *   • maps the core `CommandResult` deny reasons to typed errors the controller renders as
+ *     4xx/5xx (invalid → 400, denied/exceeds-authority → 403, outage → 503);
+ *   • lists policies TENANT-SCOPED (`listPolicies(typeKey, actor.tenantId)`);
+ *   • deletes policies TENANT-SCOPED (`deletePolicyForTenant` — a foreign tenant's policy id can
+ *     NEVER be deleted; absent/foreign → NotFound, never a false success).
+ *
+ * FAIL-CLOSED: a transient store/authority throw PROPAGATES (the controller maps it to 503) —
+ * NEVER swallowed into a success. The delegated-admin check and validation run BEFORE any write.
+ */
+import type { AuditSink, DecisionAuthority, GuidedPolicy, ModuleRegistry, Policy, Principal } from '@astram/core';
+import type { MariaDbPolicyStore } from '@astram/guard';
+/** A guided policy could not be authored because it is structurally invalid (→ 400). */
+export declare class InvalidPolicyError extends Error {
+    constructor(message?: string);
+}
+/** The acting admin exceeds their authority (delegated-admin ceiling) — author denied (→ 403). */
+export declare class PolicyAuthorDeniedError extends Error {
+    constructor(message?: string);
+}
+/** A policy id was not found in the acting admin's tenant (absent OR another tenant's) (→ 404). */
+export declare class PolicyNotFoundError extends Error {
+    constructor(message?: string);
+}
+/** The minimal store surface the service uses (the concrete guard adapter satisfies it). */
+export interface PolicyStoreLike {
+    savePolicy(tenantId: string, policy: GuidedPolicy): Promise<Policy>;
+    listPolicies(typeKey: string, tenantId: string): Promise<readonly Policy[]>;
+    deletePolicyForTenant(policyId: string, tenantId: string): Promise<number>;
+}
+/** The physical/logical type of a field, as the engine declares it. */
+export type FieldTypeName = 'string' | 'number' | 'boolean' | 'uuid' | 'timestamp' | 'json';
+/** One authorable field of a type, with the operators the guided builder should OFFER. */
+export interface PolicyFieldSchema {
+    readonly key: string;
+    readonly label: string;
+    readonly type: FieldTypeName;
+    /** The operators VALID for this field type (the UI's dropdown; server validation is authority). */
+    readonly validOperators: readonly PolicyOperatorName[];
+    /** Operators requiring an array operand (in/not_in) — the UI renders a multi-value input. */
+    readonly arrayOperators: readonly PolicyOperatorName[];
+    /** Operators taking NO operand (is_null/is_not_null) — the UI hides the value input. */
+    readonly nullaryOperators: readonly PolicyOperatorName[];
+}
+/** The guided-builder schema for a type: its authorable fields + the type's actions. */
+export interface PolicyTypeSchema {
+    readonly typeKey: string;
+    readonly label: string;
+    readonly actions: readonly string[];
+    readonly fields: readonly PolicyFieldSchema[];
+}
+/** The closed operator vocabulary — mirrors core `PolicyOperator`. */
+export type PolicyOperatorName = 'eq' | 'ne' | 'in' | 'not_in' | 'gt' | 'lt' | 'gte' | 'lte' | 'contains' | 'not_contains' | 'is_null' | 'is_not_null';
+/** A field descriptor the schema source hands the service (from the reflected object type). */
+export interface FieldDef {
+    readonly key: string;
+    readonly type: FieldTypeName;
+}
+/** Per-type field + action metadata the service reads to build the guided-builder schema. */
+export interface TypeSchemaSource {
+    readonly typeKey: string;
+    readonly label: string;
+    readonly actions: readonly string[];
+    readonly fields: readonly FieldDef[];
+}
+/**
+ * The operators the guided builder offers for a FIELD TYPE. Equality + null apply to every type;
+ * relational (gt/lt/…) only to numeric + timestamp (the recorded v1 limit — lexical vs numeric
+ * ordering on a VARCHAR diverges, so relational is NOT offered on string/uuid); text
+ * (contains/…) only to string. boolean/json get equality + null only. This is INTENTIONALLY a
+ * subset the builder shows; the server accepts anything `operatorValidForField` allows.
+ */
+export declare function validOperatorsForFieldType(type: FieldTypeName): readonly PolicyOperatorName[];
+/** The dependencies the service wires (all constructed in the identity module). */
+export interface PolicyServiceDeps {
+    readonly registry: ModuleRegistry;
+    readonly policyStore: MariaDbPolicyStore | PolicyStoreLike;
+    readonly decide: DecisionAuthority;
+    readonly audit: AuditSink;
+    /**
+     * The authorable-type field/action metadata (built in the module from the reflected object
+     * types). Drives `schema()` — the guided builder's field + operator dropdowns. A type absent
+     * here is NOT authorable via the builder (schema → NotFound).
+     */
+    readonly schemaSource?: readonly TypeSchemaSource[];
+    readonly now?: () => number;
+}
+export declare class PolicyService {
+    private readonly store;
+    private readonly authorPolicy;
+    private readonly schemaByType;
+    constructor(deps: PolicyServiceDeps);
+    /**
+     * The guided-builder SCHEMA for a type: its authorable fields (each with its type + the
+     * operators the builder offers, split into array/nullary families the UI renders differently)
+     * + the type's actions. Server-derived from the registered object type so the builder's
+     * dropdowns are ONE source of truth with enforcement (no client-side operator table to drift).
+     * A type not in the schema source → PolicyNotFoundError (not authorable via the builder).
+     */
+    schema(typeKey: string): PolicyTypeSchema;
+    /**
+     * Author a guided policy in the acting admin's OWN tenant. The target tenant is
+     * `actor.tenantId` — a `tenantId` in the body is IGNORED (cross-tenant author impossible).
+     * Runs the core pipeline (delegated-admin ceiling → validate → write → audit). Maps deny
+     * reasons to typed errors; a transient throw PROPAGATES (→ 503).
+     */
+    author(actor: Principal, policy: GuidedPolicy): Promise<Policy>;
+    /** List the policies governing `typeKey` in the acting admin's tenant (tenant-scoped read). */
+    list(actor: Principal, typeKey: string): Promise<readonly Policy[]>;
+    /**
+     * Delete a policy the acting admin owns. TENANT-SCOPED: `deletePolicyForTenant` removes rows
+     * only when they belong to `actor.tenantId`, so a foreign tenant's policy id can never be
+     * deleted. Zero rows removed ⇒ the policy is absent OR another tenant's ⇒ NotFound (never a
+     * false "deleted someone else's").
+     */
+    delete(actor: Principal, policyId: string): Promise<void>;
+}
+//# sourceMappingURL=policy.service.d.ts.map

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

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