@astram/identity 0.18.1 → 0.19.0

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

@@ -1 +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;AACxE,OAAO,EAA2B,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEpF;;;;GAIG;AACH,qBAAa,mBAAoB,YAAW,YAAY;IAGpD,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAH1B,4FAA4F;gBAEzE,IAAI,EAAE,IAAI,EACV,OAAO,GAAE,mBAA+C;IAGrE,eAAe,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAwBlD,gBAAgB,CAAC,GAAG,EAAE,IAAI,CAAC,oBAAoB,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAmB7E,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"}
+{"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,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAC3F,OAAO,EAA2B,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AASpF,oGAAoG;AACpG,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAKjE;AAUD;;;;;;;;GAQG;AACH,qBAAa,mBAAoB,YAAW,YAAY;IAGpD,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAH1B,4FAA4F;gBAEzE,IAAI,EAAE,IAAI,EACV,OAAO,GAAE,mBAA+C;IAGrE,eAAe,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAqCxD,mGAAmG;IAC7F,gBAAgB,CAAC,GAAG,EAAE,IAAI,CAAC,oBAAoB,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAyB7E,YAAY,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAS1D,gGAAgG;IAC1F,UAAU,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBzE,yFAAyF;IACnF,UAAU,CAAC,IAAI,EAAE,SAAS,iBAAiB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAUpE"}

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

@@ -1,11 +1,40 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MariaDbCatalogStore = void 0;
+exports.isoFromEpochSeconds = isoFromEpochSeconds;
 const schema_js_1 = require("../../schema.js");
+/*
+ * TIMESTAMP columns cross the driver as epoch seconds (`FROM_UNIXTIME(?)` in, `UNIX_TIMESTAMP(col)`
+ * out), never as a JS `Date`: the authz pool sets no driver `timezone`, so a `Date` would be sent as
+ * Node's local wall-clock and stored shifted whenever the process TZ differs from the DB session
+ * `time_zone` (a same-driver read would hide it). Epoch seconds are timezone-independent.
+ */
+/** `UNIX_TIMESTAMP(col)` as the driver returns it (number, bigint or string) → ISO; NULL ⇒ null. */
+function isoFromEpochSeconds(value) {
+    if (value === null || value === undefined)
+        return null;
+    const seconds = Number(value);
+    if (!Number.isFinite(seconds))
+        return null;
+    return new Date(seconds * 1000).toISOString();
+}
+/** An ISO timestamp from the reconciler as whole epoch seconds for `FROM_UNIXTIME(?)`; absent ⇒ NULL. */
+function epochSecondsParam(iso) {
+    if (iso === null || iso === undefined)
+        return null;
+    const ms = Date.parse(iso);
+    if (Number.isNaN(ms))
+        throw new Error('catalog store: invalid timestamp');
+    return Math.floor(ms / 1000);
+}
 /**
  * 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).
+ *
+ * G-027: `perm_first_seen_at` / `perm_first_seen_version` are written ONLY by the insert in
+ * {@link upsertPermission} (insert-only, `INSERT … SELECT … WHERE NOT EXISTS`); no other
+ * statement here names them, so an existing row keeps its first values for good.
  */
 class MariaDbCatalogStore {
     pool;
@@ -16,7 +45,10 @@ class MariaDbCatalogStore {
         this.schemas = schemas;
     }
     async listPermissions() {
-        const rows = (await this.pool.query(`SELECT perm_key, perm_module, perm_type_key, perm_action, perm_label, perm_tier, perm_status
+        const rows = (await this.pool.query(`SELECT perm_key, perm_module, perm_type_key, perm_action, perm_label, perm_tier, perm_status,
+              perm_description, perm_caution,
+              UNIX_TIMESTAMP(perm_first_seen_at) AS perm_first_seen_at, perm_first_seen_version,
+              UNIX_TIMESTAMP(perm_last_activated_at) AS perm_last_activated_at
          FROM \`${this.schemas.authz}\`.\`permission\``));
         return rows.map((r) => ({
             permissionKey: r.perm_key,
@@ -26,12 +58,19 @@ class MariaDbCatalogStore {
             label: r.perm_label,
             tier: r.perm_tier,
             status: r.perm_status === 'orphaned' ? 'orphaned' : 'active',
+            description: r.perm_description ?? null,
+            caution: r.perm_caution ?? null,
+            firstSeenAt: isoFromEpochSeconds(r.perm_first_seen_at),
+            firstSeenVersion: r.perm_first_seen_version ?? null,
+            lastActivatedAt: isoFromEpochSeconds(r.perm_last_activated_at),
         }));
     }
+    /** Insert-only: a key that already exists matches no row (`WHERE NOT EXISTS`) and is untouched. */
     async upsertPermission(row) {
         const res = (await this.pool.query(`INSERT INTO \`${this.schemas.authz}\`.\`permission\`
-         (perm_uuid, perm_key, perm_module, perm_type_key, perm_action, perm_label, perm_tier, perm_status)
-         SELECT UUID(), ?, ?, ?, ?, ?, ?, 'active'
+         (perm_uuid, perm_key, perm_module, perm_type_key, perm_action, perm_label, perm_tier, perm_status,
+          perm_description, perm_caution, perm_first_seen_at, perm_first_seen_version, perm_last_activated_at)
+         SELECT UUID(), ?, ?, ?, ?, ?, ?, 'active', ?, ?, FROM_UNIXTIME(?), ?, FROM_UNIXTIME(?)
           WHERE NOT EXISTS (SELECT 1 FROM \`${this.schemas.authz}\`.\`permission\` WHERE perm_key = ?)`, [
             row.permissionKey,
             row.moduleKey,
@@ -39,6 +78,11 @@ class MariaDbCatalogStore {
             row.action,
             row.label,
             row.tier,
+            row.description ?? null,
+            row.caution ?? null,
+            epochSecondsParam(row.firstSeenAt),
+            row.firstSeenVersion ?? null,
+            epochSecondsParam(row.lastActivatedAt),
             row.permissionKey,
         ]));
         return Number(res?.affectedRows ?? 0) > 0;
@@ -49,11 +93,26 @@ class MariaDbCatalogStore {
         const ph = keys.map(() => '?').join(', ');
         await this.pool.query(`UPDATE \`${this.schemas.authz}\`.\`permission\` SET perm_status = 'orphaned' WHERE perm_key IN (${ph})`, [...keys]);
     }
-    async markActive(keys) {
+    /** Orphaned → active; with `nowIso` also stamps `perm_last_activated_at` (never first seen). */
+    async markActive(keys, nowIso) {
         if (keys.length === 0)
             return;
         const ph = keys.map(() => '?').join(', ');
-        await this.pool.query(`UPDATE \`${this.schemas.authz}\`.\`permission\` SET perm_status = 'active' WHERE perm_key IN (${ph})`, [...keys]);
+        if (nowIso === undefined) {
+            await this.pool.query(`UPDATE \`${this.schemas.authz}\`.\`permission\` SET perm_status = 'active' WHERE perm_key IN (${ph})`, [...keys]);
+            return;
+        }
+        await this.pool.query(`UPDATE \`${this.schemas.authz}\`.\`permission\`
+          SET perm_status = 'active', perm_last_activated_at = FROM_UNIXTIME(?)
+        WHERE perm_key IN (${ph})`, [epochSecondsParam(nowIso), ...keys]);
+    }
+    /** G-027: the code's text replaces the stored text, one parameterized UPDATE per key. */
+    async updateText(rows) {
+        for (const row of rows) {
+            await this.pool.query(`UPDATE \`${this.schemas.authz}\`.\`permission\`
+            SET perm_label = ?, perm_description = ?, perm_caution = ?
+          WHERE perm_key = ?`, [row.label, row.description ?? null, row.caution ?? null, row.permissionKey]);
+        }
     }
 }
 exports.MariaDbCatalogStore = MariaDbCatalogStore;

package/dist/features/identity-feature.module.d.ts

@@ -2,6 +2,7 @@ import { type DynamicModule } from '@nestjs/common';
 import { type FrameworkSchemas } from '@astram/core';
 import { type EngineDbConfig, type ObjectTypeInput } from '@astram/engine';
 import { type InviteOptions } from './user/invite.config.js';
+import { type TypeSchemaSource } from './policy/policy.service.js';
 /**
  * The boot check behind {@link IDENTITY_DECISION_AUTHORITY_CHECK}: with this module wired, the
  * request path must decide with the authority guard built from this module's inputs. A missing
@@ -31,6 +32,13 @@ export declare function assertFrameworkDatabaseAgrees(identityDatabase: string,
         readonly database?: string;
     };
 } | null | undefined): true;
+/**
+ * The guided rule-builder schema source (`GET /identity/record-policies/schema`): per registered
+ * type its label (G-027 spec §5K2: the declared `ObjectType.label`, else the `typeKey`), its
+ * action vocabulary and its fields (engine `reflectObjectType` keeps field `type`, which the core
+ * registry descriptor drops). Field labels stay `f.key` (not in G-027 step 1).
+ */
+export declare function policySchemaSourceOf(inputs: readonly ObjectTypeInput[], actionsByType: (typeKey: string) => readonly string[] | undefined): TypeSchemaSource[];
 /**
  * Map guard's DbConfig → the engine's EngineDbConfig (adds the pool cap the engine needs). The
  * database and default user follow `schemas` (the names `forRoot` resolved or was given); an

package/dist/features/identity-feature.module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"identity-feature.module.d.ts","sourceRoot":"","sources":["../../src/features/identity-feature.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,EAGL,KAAK,gBAAgB,EAEtB,MAAM,cAAc,CAAC;AACtB,OAAO,EAaL,KAAK,cAAc,EAGnB,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AAyDxB,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,yBAAyB,CAAC;AA2G/E;;;;;;GAMG;AACH,wBAAgB,0CAA0C,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAUnF;AAKD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GACzC,IAAI,CAwBN;AAKD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,gBAAgB,EAAE,MAAM,EACxB,WAAW,EAAE;IAAE,QAAQ,CAAC,EAAE,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GAC/E,IAAI,CAQN;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,gBAAgB,EACzB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,cAAc,CAyBhB;AA2BD,qBACa,qBAAqB;IAChC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,MAAM,CAAC,OAAO,CAAC,EACb,OAAO,EACP,YAAiB,EACjB,OAAO,EAAE,YAAY,EACrB,MAAM,GACP,GAAE;QACD,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAC5B,YAAY,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;QAC1C,OAAO,CAAC,EAAE,gBAAgB,CAAC;QAC3B,MAAM,CAAC,EAAE,aAAa,CAAC;KACnB,GAAG,aAAa;CAmqBvB"}
+{"version":3,"file":"identity-feature.module.d.ts","sourceRoot":"","sources":["../../src/features/identity-feature.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,EAGL,KAAK,gBAAgB,EAEtB,MAAM,cAAc,CAAC;AACtB,OAAO,EAaL,KAAK,cAAc,EAGnB,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AA0DxB,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,yBAAyB,CAAC;AA0C/E,OAAO,EAAiB,KAAK,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAkElF;;;;;;GAMG;AACH,wBAAgB,0CAA0C,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAUnF;AAKD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GACzC,IAAI,CAwBN;AAKD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,gBAAgB,EAAE,MAAM,EACxB,WAAW,EAAE;IAAE,QAAQ,CAAC,EAAE,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GAC/E,IAAI,CAQN;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,GAAG,SAAS,GAChE,gBAAgB,EAAE,CAapB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,gBAAgB,EACzB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,cAAc,CAyBhB;AA2BD,qBACa,qBAAqB;IAChC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,MAAM,CAAC,OAAO,CAAC,EACb,OAAO,EACP,YAAiB,EACjB,OAAO,EAAE,YAAY,EACrB,MAAM,GACP,GAAE;QACD,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAC5B,YAAY,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;QAC1C,OAAO,CAAC,EAAE,gBAAgB,CAAC;QAC3B,MAAM,CAAC,EAAE,aAAa,CAAC;KACnB,GAAG,aAAa;CAgqBvB"}

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

@@ -11,6 +11,7 @@ exports.IdentityFeatureModule = void 0;
 exports.assertRequestPathUsesIdentityAuthorization = assertRequestPathUsesIdentityAuthorization;
 exports.assertFrameworkSchemasAgree = assertFrameworkSchemasAgree;
 exports.assertFrameworkDatabaseAgrees = assertFrameworkDatabaseAgrees;
+exports.policySchemaSourceOf = policySchemaSourceOf;
 exports.engineDbFromEnv = engineDbFromEnv;
 const common_1 = require("@nestjs/common");
 const core_1 = require("@nestjs/core");
@@ -64,6 +65,7 @@ const service_account_store_js_1 = require("./service-account/service-account.st
 const service_account_service_js_1 = require("./service-account/service-account.service.js");
 const service_account_controller_js_1 = require("./service-account/service-account.controller.js");
 const catalog_reconcile_job_js_1 = require("./authz/catalog-reconcile.job.js");
+const app_release_js_1 = require("./authz/app-release.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 authz_pool_lifecycle_js_1 = require("./authz/authz-pool-lifecycle.js");
@@ -180,6 +182,26 @@ function assertFrameworkDatabaseAgrees(identityDatabase, guardConfig) {
         `${guardDatabase}. Pass the same names (or none) to ShieldModule and ` +
         'IdentityFeatureModule, and one APP_DB_NAME.');
 }
+/**
+ * The guided rule-builder schema source (`GET /identity/record-policies/schema`): per registered
+ * type its label (G-027 spec §5K2: the declared `ObjectType.label`, else the `typeKey`), its
+ * action vocabulary and its fields (engine `reflectObjectType` keeps field `type`, which the core
+ * registry descriptor drops). Field labels stay `f.key` (not in G-027 step 1).
+ */
+function policySchemaSourceOf(inputs, actionsByType) {
+    return inputs.map((input) => {
+        const reg = typeof input === 'function' ? (0, engine_1.reflectObjectType)(input) : input;
+        return {
+            typeKey: reg.typeKey,
+            label: reg.label ?? reg.typeKey,
+            actions: actionsByType(reg.typeKey) ?? [],
+            fields: reg.fields.map((f) => {
+                const ref = (0, engine_1.referencedTypeOf)(f);
+                return { key: f.key, type: f.type, ...(ref ? { references: ref } : {}) };
+            }),
+        };
+    });
+}
 /**
  * Map guard's DbConfig → the engine's EngineDbConfig (adds the pool cap the engine needs). The
  * database and default user follow `schemas` (the names `forRoot` resolved or was given); an
@@ -440,18 +462,7 @@ let IdentityFeatureModule = IdentityFeatureModule_1 = class IdentityFeatureModul
         // 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).
         // Include the consumer's `extraObjects` so their OWNED types are policy-authorable too.
-        const schemaSource = [...objects_js_1.identityObjects, ...extraObjects].map((input) => {
-            const reg = typeof input === 'function' ? (0, engine_1.reflectObjectType)(input) : input;
-            return {
-                typeKey: reg.typeKey,
-                label: reg.typeKey,
-                actions: actionsByType(reg.typeKey) ?? [],
-                fields: reg.fields.map((f) => {
-                    const ref = (0, engine_1.referencedTypeOf)(f);
-                    return { key: f.key, type: f.type, ...(ref ? { references: ref } : {}) };
-                }),
-            };
-        });
+        const schemaSource = policySchemaSourceOf([...objects_js_1.identityObjects, ...extraObjects], actionsByType);
         const policyService = new policy_service_js_1.PolicyService({
             // The shared registry (KI #57): the schema below already offers the consumer's types, so
             // the author must know their actions too.
@@ -766,7 +777,9 @@ let IdentityFeatureModule = IdentityFeatureModule_1 = class IdentityFeatureModul
                 // ceiling know, so a consumer type's keys are grantable and its rows are not orphaned.
                 {
                     provide: catalog_reconcile_job_js_1.CatalogReconcileJob,
-                    useValue: new catalog_reconcile_job_js_1.CatalogReconcileJob(authzPool, recordAuthorization.registry, schemas),
+                    // G-027: the code's permission text over the SAME types as the registry (keys match
+                    // it exactly), and `APP_RELEASE` (read once; an invalid value refuses boot).
+                    useValue: new catalog_reconcile_job_js_1.CatalogReconcileJob(authzPool, recordAuthorization.registry, schemas, (0, guard_1.permissionTextByKey)([...objects_js_1.identityObjects, ...extraObjects]), (0, app_release_js_1.loadAppRelease)(process.env)),
                 },
                 // The bundle half: reconciles the merged AccessBundleSpec[] (ENGINE_ALL_ACCESS_BUNDLES,
                 // reflected by the engine from identityAccessBundles) into shield_authz.access_bundle.

package/dist/membership-posting.object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"membership-posting.object.d.ts","sourceRoot":"","sources":["../src/membership-posting.object.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,qBAiBa,iBAAiB;IAE5B,IAAI,EAAG,MAAM,CAAC;IAKd,cAAc,EAAG,MAAM,CAAC;IAGxB,QAAQ,EAAG,MAAM,CAAC;IAGlB,cAAc,EAAG,MAAM,CAAC;IAGxB,UAAU,EAAG,MAAM,CAAC;IAQpB,aAAa,EAAG,MAAM,CAAC;IAGvB,cAAc,EAAG,MAAM,CAAC;IAGxB,SAAS,EAAG,MAAM,CAAC;CACpB"}
+{"version":3,"file":"membership-posting.object.d.ts","sourceRoot":"","sources":["../src/membership-posting.object.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,qBAwCa,iBAAiB;IAE5B,IAAI,EAAG,MAAM,CAAC;IAKd,cAAc,EAAG,MAAM,CAAC;IAGxB,QAAQ,EAAG,MAAM,CAAC;IAGlB,cAAc,EAAG,MAAM,CAAC;IAGxB,UAAU,EAAG,MAAM,CAAC;IAQpB,aAAa,EAAG,MAAM,CAAC;IAGvB,cAAc,EAAG,MAAM,CAAC;IAGxB,SAAS,EAAG,MAAM,CAAC;CACpB"}

package/dist/membership-posting.object.js

@@ -83,6 +83,28 @@ exports.MembershipPosting = MembershipPosting = __decorate([
             pkColumn: 'mp_membership_uuid',
             subquerySql: `SELECT cm_uuid FROM \`${schema_1.SCHEMA}\`.\`company_membership\` WHERE cm_company_uuid IN (${engine_1.READ_SCOPE_NODES_TOKEN})`,
         },
+        // G-027: permission catalog text, read by every tenant's administrators (no tenant names).
+        label: 'Membership posting',
+        permissions: {
+            read: {
+                label: 'Postings: view',
+                description: "See each membership's postings: its role, department, branch and the dates they apply.",
+            },
+            create: {
+                label: 'Postings: create',
+                description: 'Add postings to memberships, giving users a role in a company.',
+                caution: 'Giving someone a role gives them everything that role allows.',
+            },
+            update: {
+                label: 'Postings: edit',
+                description: "Replace a membership's postings: its roles, departments, branches and dates.",
+                caution: 'Giving someone a role gives them everything that role allows.',
+            },
+            delete: {
+                label: 'Postings: delete',
+                description: 'Remove postings from memberships, taking those roles away.',
+            },
+        },
     }),
     (0, engine_1.PrimaryKey)({ kind: 'uuid', column: 'mp_uuid' })
 ], MembershipPosting);

package/dist/record-share.object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"record-share.object.d.ts","sourceRoot":"","sources":["../src/record-share.object.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;GAiBG;AACH,qBASa,WAAW;IAEtB,IAAI,EAAG,MAAM,CAAC;IAGd,UAAU,EAAG,MAAM,CAAC;IAGpB,UAAU,EAAG,MAAM,CAAC;CACrB"}
+{"version":3,"file":"record-share.object.d.ts","sourceRoot":"","sources":["../src/record-share.object.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAqBa,WAAW;IAEtB,IAAI,EAAG,MAAM,CAAC;IAGd,UAAU,EAAG,MAAM,CAAC;IAGpB,UAAU,EAAG,MAAM,CAAC;CACrB"}

package/dist/record-share.object.js

@@ -59,6 +59,18 @@ exports.RecordShare = RecordShare = __decorate([
         access: { plane: 'control', system: true },
         crudActions: false,
         actions: guard_1.RECORD_SHARE_ACTIONS,
+        // G-027: permission catalog text, read by every tenant's administrators (no tenant names).
+        label: 'Record share',
+        permissions: {
+            share: {
+                label: 'Record shares: share',
+                description: 'Share records they own with other users or roles, and stop sharing them.',
+            },
+            read: {
+                label: 'Record shares: view',
+                description: 'See who the records they own are shared with.',
+            },
+        },
     }),
     (0, engine_1.PrimaryKey)({ kind: 'uuid', column: 'rs_uuid' })
 ], RecordShare);

package/dist/role.object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"role.object.d.ts","sourceRoot":"","sources":["../src/role.object.ts"],"names":[],"mappings":"AAGA,uFAAuF;AACvF,qBAWa,IAAI;IAEf,IAAI,EAAG,MAAM,CAAC;IAGd,IAAI,EAAG,MAAM,CAAC;IAMd,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAGjC,SAAS,EAAG,MAAM,CAAC;CACpB"}
+{"version":3,"file":"role.object.d.ts","sourceRoot":"","sources":["../src/role.object.ts"],"names":[],"mappings":"AAGA,uFAAuF;AACvF,qBAiCa,IAAI;IAEf,IAAI,EAAG,MAAM,CAAC;IAGd,IAAI,EAAG,MAAM,CAAC;IAMd,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAGjC,SAAS,EAAG,MAAM,CAAC;CACpB"}

package/dist/role.object.js

@@ -49,6 +49,27 @@ exports.Role = Role = __decorate([
         // the caller's reachable subtree. Walled create (ADR-0034, no `create` key): the owner is a
         // reached company, so the post-insert wall holds. NULL owner ⇒ root only. Root spans all.
         readScope: { kind: 'nodeColumn', column: 'r_owner_company_uuid' },
+        // G-027: permission catalog text, read by every tenant's administrators (no tenant names).
+        label: 'Role',
+        permissions: {
+            read: {
+                label: 'Roles: view',
+                description: 'See roles and what they allow, the permission list, record policies, cross-tenant grants and the audit log.',
+            },
+            create: {
+                label: 'Roles: create',
+                description: 'Create new roles for the companies they can reach.',
+            },
+            update: {
+                label: 'Roles: edit',
+                description: 'Rename roles and change their permissions, access bundles and record policies.',
+                caution: 'Holders can give a role any permission they hold themselves.',
+            },
+            delete: {
+                label: 'Roles: delete',
+                description: 'Delete roles.',
+            },
+        },
     }),
     (0, engine_1.PrimaryKey)({ kind: 'uuid', column: 'r_uuid' })
 ], Role);

package/dist/security-policy.object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"security-policy.object.d.ts","sourceRoot":"","sources":["../src/security-policy.object.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAQa,cAAc;IAEzB,IAAI,EAAG,MAAM,CAAC;IAEd,2FAA2F;IAE3F,aAAa,EAAG,MAAM,GAAG,IAAI,CAAC;IAE9B,wCAAwC;IAExC,QAAQ,EAAG,OAAO,CAAC;IAEnB,wCAAwC;IAExC,UAAU,EAAG,MAAM,CAAC;IAEpB,iEAAiE;IAEjE,WAAW,EAAG,MAAM,GAAG,IAAI,CAAC;IAE5B,wBAAwB;IAExB,SAAS,EAAG,MAAM,CAAC;IAEnB;;;OAGG;IAEH,aAAa,EAAG,MAAM,GAAG,IAAI,CAAC;IAE9B,gFAAgF;IAEhF,SAAS,EAAG,MAAM,CAAC;IAEnB,wCAAwC;IAExC,WAAW,EAAG,MAAM,CAAC;IAErB,uDAAuD;IAEvD,WAAW,EAAG,MAAM,CAAC;CACtB"}
+{"version":3,"file":"security-policy.object.d.ts","sourceRoot":"","sources":["../src/security-policy.object.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH,qBA+Ba,cAAc;IAEzB,IAAI,EAAG,MAAM,CAAC;IAEd,2FAA2F;IAE3F,aAAa,EAAG,MAAM,GAAG,IAAI,CAAC;IAE9B,wCAAwC;IAExC,QAAQ,EAAG,OAAO,CAAC;IAEnB,wCAAwC;IAExC,UAAU,EAAG,MAAM,CAAC;IAEpB,iEAAiE;IAEjE,WAAW,EAAG,MAAM,GAAG,IAAI,CAAC;IAE5B,wBAAwB;IAExB,SAAS,EAAG,MAAM,CAAC;IAEnB;;;OAGG;IAEH,aAAa,EAAG,MAAM,GAAG,IAAI,CAAC;IAE9B,gFAAgF;IAEhF,SAAS,EAAG,MAAM,CAAC;IAEnB,wCAAwC;IAExC,WAAW,EAAG,MAAM,CAAC;IAErB,uDAAuD;IAEvD,WAAW,EAAG,MAAM,CAAC;CACtB"}

package/dist/security-policy.object.js

@@ -102,6 +102,27 @@ exports.SecurityPolicy = SecurityPolicy = __decorate([
         schema: schema_1.SCHEMA,
         access: { plane: 'control', system: true },
         readScope: { kind: 'nodeColumn', column: 'sp_scope_node_uuid' },
+        // G-027: permission catalog text, read by every tenant's administrators (no tenant names).
+        label: 'Security policy',
+        permissions: {
+            read: {
+                label: 'Security policies: view',
+                description: 'See which companies, roles and permissions require two-factor sign-in, in the companies they can reach.',
+            },
+            create: {
+                label: 'Security policies: create',
+                description: 'Require two-factor sign-in for a company, for a role, or for holders of chosen permissions.',
+            },
+            update: {
+                label: 'Security policies: edit',
+                description: "Change a two-factor policy's target or its grace period.",
+            },
+            delete: {
+                label: 'Security policies: delete',
+                description: 'Remove two-factor policies.',
+                caution: 'People a removed policy covered no longer have to use two-factor sign-in.',
+            },
+        },
     }),
     (0, engine_1.PrimaryKey)({ kind: 'uuid', column: 'sp_uuid' })
 ], SecurityPolicy);

package/dist/service-account.object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service-account.object.d.ts","sourceRoot":"","sources":["../src/service-account.object.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBASa,cAAc;IAEzB,EAAE,EAAG,MAAM,CAAC;IAGZ,QAAQ,EAAG,MAAM,CAAC;IAGlB,KAAK,EAAG,MAAM,CAAC;IAGf,MAAM,EAAG,MAAM,CAAC;IAGhB,WAAW,EAAG,MAAM,CAAC;CACtB"}
+{"version":3,"file":"service-account.object.d.ts","sourceRoot":"","sources":["../src/service-account.object.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAoCa,cAAc;IAEzB,EAAE,EAAG,MAAM,CAAC;IAGZ,QAAQ,EAAG,MAAM,CAAC;IAGlB,KAAK,EAAG,MAAM,CAAC;IAGf,MAAM,EAAG,MAAM,CAAC;IAGhB,WAAW,EAAG,MAAM,CAAC;CACtB"}

package/dist/service-account.object.js

@@ -72,6 +72,31 @@ exports.ServiceAccount = ServiceAccount = __decorate([
         access: { plane: 'control', system: true },
         actions: ['manage_keys'],
         readScope: { kind: 'nodeColumn', column: 'sa_tenant_id' },
+        // G-027: permission catalog text, read by every tenant's administrators (no tenant names).
+        label: 'Service account',
+        permissions: {
+            read: {
+                label: 'Service accounts: view',
+                description: 'See the service accounts (sign-ins for scripts and AI agents) of their tenant.',
+            },
+            create: {
+                label: 'Service accounts: create',
+                description: 'Create service accounts and choose the roles and companies they act in.',
+            },
+            update: {
+                label: 'Service accounts: edit',
+                description: "Change a service account's name, roles, companies or status, including disabling it.",
+            },
+            delete: {
+                label: 'Service accounts: delete',
+                description: 'Delete service accounts. The framework has no delete route; disable an account by editing its status.',
+            },
+            manage_keys: {
+                label: 'Service accounts: manage keys',
+                description: 'Issue, rotate and revoke the API keys service accounts sign in with.',
+                caution: 'Anyone holding a key can act as the service account until the key is revoked.',
+            },
+        },
     }),
     (0, engine_1.PrimaryKey)({ kind: 'uuid', column: 'sa_id' })
 ], ServiceAccount);

package/dist/shared-resource.object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shared-resource.object.d.ts","sourceRoot":"","sources":["../src/shared-resource.object.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAOa,cAAc;IAEzB,IAAI,EAAG,MAAM,CAAC;IAEd,yFAAyF;IAEzF,QAAQ,EAAG,MAAM,CAAC;IAGlB,KAAK,EAAG,MAAM,CAAC;CAChB"}
+{"version":3,"file":"shared-resource.object.d.ts","sourceRoot":"","sources":["../src/shared-resource.object.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBA+Ba,cAAc;IAEzB,IAAI,EAAG,MAAM,CAAC;IAEd,yFAAyF;IAEzF,QAAQ,EAAG,MAAM,CAAC;IAGlB,KAAK,EAAG,MAAM,CAAC;CAChB"}

package/dist/shared-resource.object.js

@@ -58,6 +58,26 @@ exports.SharedResource = SharedResource = __decorate([
         table: 'shared_resource',
         schema: schema_1.SCHEMA,
         access: { tenantScoped: true, plane: 'data' },
+        // G-027: permission catalog text, read by every tenant's administrators (no tenant names).
+        label: 'Shared resource',
+        permissions: {
+            read: {
+                label: 'Shared resources: view',
+                description: "See their tenant's shared resources, the sample type cross-tenant grants offer.",
+            },
+            create: {
+                label: 'Shared resources: create',
+                description: 'Add shared resources to their tenant (the sample type cross-tenant grants offer; the framework has no route for it).',
+            },
+            update: {
+                label: 'Shared resources: edit',
+                description: "Rename their tenant's shared resources (sample type; the framework has no route for it).",
+            },
+            delete: {
+                label: 'Shared resources: delete',
+                description: "Delete their tenant's shared resources (sample type; the framework has no route for it).",
+            },
+        },
     }),
     (0, engine_1.PrimaryKey)({ kind: 'uuid', column: 'sr_uuid' })
 ], SharedResource);

package/dist/stored-file.object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stored-file.object.d.ts","sourceRoot":"","sources":["../src/stored-file.object.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,qBAOa,UAAU;IAErB,IAAI,EAAG,MAAM,CAAC;IAEd,yFAAyF;IAEzF,QAAQ,EAAG,MAAM,CAAC;IAElB,6FAA6F;IAE7F,OAAO,EAAG,MAAM,CAAC;IAEjB,yEAAyE;IAEzE,UAAU,EAAG,MAAM,CAAC;IAEpB,iDAAiD;IAEjD,MAAM,EAAG,MAAM,CAAC;IAEhB,yEAAyE;IAEzE,WAAW,EAAG,MAAM,CAAC;IAGrB,SAAS,EAAG,MAAM,CAAC;IAEnB,8BAA8B;IAE9B,YAAY,EAAG,MAAM,CAAC;IAEtB,wCAAwC;IAExC,SAAS,EAAG,MAAM,CAAC;CACpB"}
+{"version":3,"file":"stored-file.object.d.ts","sourceRoot":"","sources":["../src/stored-file.object.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,qBA2Ba,UAAU;IAErB,IAAI,EAAG,MAAM,CAAC;IAEd,yFAAyF;IAEzF,QAAQ,EAAG,MAAM,CAAC;IAElB,6FAA6F;IAE7F,OAAO,EAAG,MAAM,CAAC;IAEjB,yEAAyE;IAEzE,UAAU,EAAG,MAAM,CAAC;IAEpB,iDAAiD;IAEjD,MAAM,EAAG,MAAM,CAAC;IAEhB,yEAAyE;IAEzE,WAAW,EAAG,MAAM,CAAC;IAGrB,SAAS,EAAG,MAAM,CAAC;IAEnB,8BAA8B;IAE9B,YAAY,EAAG,MAAM,CAAC;IAEtB,wCAAwC;IAExC,SAAS,EAAG,MAAM,CAAC;CACpB"}

package/dist/stored-file.object.js

@@ -89,6 +89,26 @@ exports.StoredFile = StoredFile = __decorate([
         table: 'stored_file',
         schema: schema_1.SCHEMA,
         access: { tenantScoped: true, owned: true, plane: 'data' },
+        // G-027: permission catalog text, read by every tenant's administrators (no tenant names).
+        label: 'File',
+        permissions: {
+            read: {
+                label: 'Files: view',
+                description: 'Download the uploaded files they have access to.',
+            },
+            create: {
+                label: 'Files: upload',
+                description: 'Upload files.',
+            },
+            update: {
+                label: 'Files: edit',
+                description: "Edit a file's record. The file's content, name and type cannot be changed.",
+            },
+            delete: {
+                label: 'Files: delete',
+                description: 'Delete the uploaded files they have access to.',
+            },
+        },
     }),
     (0, engine_1.PrimaryKey)({ kind: 'uuid', column: 'sf_uuid' })
 ], StoredFile);

package/dist/user.object.d.ts

@@ -11,6 +11,7 @@ export declare class User {
      * The sign-in handle (auth capabilities R1.2, migration 103): lower-case `[a-z0-9._-]{3,64}`,
      * globally unique, NULL = none (sign in by email only). Set only by an admin (dominance,
      * `UserService`) or `bootstrap:org`; never by `/account/*`. Not the display name (`username`).
+     * `nullable` so an admin's `null` clears it (G-031: the engine refuses NULL otherwise).
      */
     loginName?: string | null;
     status: string;

package/dist/user.object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"user.object.d.ts","sourceRoot":"","sources":["../src/user.object.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,qBA4Ba,IAAI;IAEf,IAAI,EAAG,MAAM,CAAC;IAGd,QAAQ,EAAG,MAAM,CAAC;IAGlB,KAAK,EAAG,MAAM,CAAC;IAEf;;;;OAIG;IAEH,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAG1B,MAAM,EAAG,MAAM,CAAC;IAGhB,SAAS,EAAG,MAAM,CAAC;CACpB"}
+{"version":3,"file":"user.object.d.ts","sourceRoot":"","sources":["../src/user.object.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,qBAoEa,IAAI;IAEf,IAAI,EAAG,MAAM,CAAC;IAGd,QAAQ,EAAG,MAAM,CAAC;IAGlB,KAAK,EAAG,MAAM,CAAC;IAEf;;;;;OAKG;IAEH,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAG1B,MAAM,EAAG,MAAM,CAAC;IAGhB,SAAS,EAAG,MAAM,CAAC;CACpB"}

package/dist/user.object.js

@@ -25,6 +25,7 @@ let User = class User {
      * The sign-in handle (auth capabilities R1.2, migration 103): lower-case `[a-z0-9._-]{3,64}`,
      * globally unique, NULL = none (sign in by email only). Set only by an admin (dominance,
      * `UserService`) or `bootstrap:org`; never by `/account/*`. Not the display name (`username`).
+     * `nullable` so an admin's `null` clears it (G-031: the engine refuses NULL otherwise).
      */
     loginName;
     status;
@@ -44,7 +45,7 @@ __decorate([
     __metadata("design:type", String)
 ], User.prototype, "email", void 0);
 __decorate([
-    (0, engine_1.Field)({ column: 'u_login_name', type: 'string' }),
+    (0, engine_1.Field)({ column: 'u_login_name', type: 'string', nullable: true }),
     __metadata("design:type", Object)
 ], User.prototype, "loginName", void 0);
 __decorate([
@@ -82,6 +83,43 @@ exports.User = User = __decorate([
             pkColumn: 'u_uuid',
             subquerySql: `SELECT cm_user_uuid FROM \`${schema_1.SCHEMA}\`.\`company_membership\` WHERE cm_company_uuid IN (${engine_1.READ_SCOPE_NODES_TOKEN})`,
         },
+        // G-027: permission catalog text, read by every tenant's administrators (no tenant names).
+        label: 'User',
+        permissions: {
+            read: {
+                label: 'Users: view',
+                description: 'See the users who belong to the companies they can reach.',
+            },
+            create: {
+                label: 'Users: create',
+                description: 'Add new user accounts, each with a first company membership.',
+            },
+            update: {
+                label: 'Users: edit',
+                description: "Change a user's name, email, sign-in name or status, including disabling them.",
+            },
+            delete: {
+                label: 'Users: delete',
+                description: 'Delete user accounts.',
+            },
+            invite: {
+                label: 'Users: invite',
+                description: 'Email a user who has not set a password yet a link to set one.',
+            },
+            reset_mfa: {
+                label: 'Users: reset two-factor sign-in',
+                description: "Remove a user's two-factor devices and recovery codes and sign them out, so they set up two-factor sign-in again.",
+                caution: "Confirm the person's identity first: until they set up two-factor sign-in again, their password alone signs them in.",
+            },
+            unlock: {
+                label: 'Users: unlock sign-in',
+                description: 'Clear the lock that failed sign-in attempts put on a user, so they can try again.',
+            },
+            end_sessions: {
+                label: 'Users: sign out everywhere',
+                description: 'Sign a user out on every device.',
+            },
+        },
     }),
     (0, engine_1.PrimaryKey)({ kind: 'uuid', column: 'u_uuid' })
 ], User);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astram/identity",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "license": "MIT",
   "description": "Astram framework — the framework-owned identity + tenancy model. Hosts the identity @ObjectType classes (user, company, membership, posting), framework-authored identity migrations, and the identity resolver. Top of the dependency graph: depends on @astram/engine (for @ObjectType/@Field decorators) + @astram/guard / @astram/core (for the auth ports).",
   "type": "commonjs",
@@ -37,8 +37,8 @@
   "dependencies": {
     "mariadb": "^3.5.4",
     "@astram/core": "1.12.0",
-    "@astram/guard": "0.22.0",
-    "@astram/engine": "0.15.0"
+    "@astram/guard": "0.23.0",
+    "@astram/engine": "0.16.0"
   },
   "peerDependencies": {
     "@nestjs/common": "^11",