@astram/identity 0.18.1 → 0.19.0

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

@@ -1 +1 @@
-{"version":3,"file":"branch.object.d.ts","sourceRoot":"","sources":["../src/branch.object.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,qBAQa,MAAM;IAEjB,IAAI,EAAG,MAAM,CAAC;IAGd,IAAI,EAAG,MAAM,CAAC;IAGd,WAAW,EAAG,MAAM,CAAC;CACtB"}
+{"version":3,"file":"branch.object.d.ts","sourceRoot":"","sources":["../src/branch.object.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,qBA4Ba,MAAM;IAEjB,IAAI,EAAG,MAAM,CAAC;IAGd,IAAI,EAAG,MAAM,CAAC;IAGd,WAAW,EAAG,MAAM,CAAC;CACtB"}

package/dist/branch.object.js

@@ -45,6 +45,26 @@ exports.Branch = Branch = __decorate([
         schema: schema_1.SCHEMA,
         access: { plane: 'control', system: true },
         readScope: { kind: 'nodeColumn', column: 'b_company_uuid' },
+        // G-027: permission catalog text, read by every tenant's administrators (no tenant names).
+        label: 'Branch',
+        permissions: {
+            read: {
+                label: 'Branches: view',
+                description: 'See the branches of the companies they can reach.',
+            },
+            create: {
+                label: 'Branches: create',
+                description: 'Add branches to the companies they can reach.',
+            },
+            update: {
+                label: 'Branches: edit',
+                description: 'Rename branches.',
+            },
+            delete: {
+                label: 'Branches: delete',
+                description: 'Delete branches.',
+            },
+        },
     }),
     (0, engine_1.PrimaryKey)({ kind: 'uuid', column: 'b_uuid' })
 ], Branch);

package/dist/company-branch.object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"company-branch.object.d.ts","sourceRoot":"","sources":["../src/company-branch.object.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,qBAQa,aAAa;IAExB,WAAW,EAAG,MAAM,CAAC;IAGrB,UAAU,EAAG,MAAM,CAAC;CACrB"}
+{"version":3,"file":"company-branch.object.d.ts","sourceRoot":"","sources":["../src/company-branch.object.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,qBA4Ba,aAAa;IAExB,WAAW,EAAG,MAAM,CAAC;IAGrB,UAAU,EAAG,MAAM,CAAC;CACrB"}

package/dist/company-branch.object.js

@@ -39,6 +39,26 @@ exports.CompanyBranch = CompanyBranch = __decorate([
         schema: schema_1.SCHEMA,
         access: { plane: 'control', system: true },
         readScope: { kind: 'nodeColumn', column: 'cb_company_uuid' },
+        // G-027: permission catalog text, read by every tenant's administrators (no tenant names).
+        label: 'Company branch link',
+        permissions: {
+            read: {
+                label: 'Company branches: view',
+                description: 'See which branches belong to each of the companies they can reach.',
+            },
+            create: {
+                label: 'Company branches: create',
+                description: 'Link a branch to its company, as happens when a branch is added.',
+            },
+            update: {
+                label: 'Company branches: edit',
+                description: 'Change the links between companies and their branches.',
+            },
+            delete: {
+                label: 'Company branches: delete',
+                description: 'Remove the link between a company and a branch.',
+            },
+        },
     }),
     (0, engine_1.PrimaryKey)({ kind: 'composite', columns: ['cb_company_uuid', 'cb_branch_uuid'] })
 ], CompanyBranch);

package/dist/company-department.object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"company-department.object.d.ts","sourceRoot":"","sources":["../src/company-department.object.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,qBAQa,iBAAiB;IAE5B,WAAW,EAAG,MAAM,CAAC;IAGrB,cAAc,EAAG,MAAM,CAAC;CACzB"}
+{"version":3,"file":"company-department.object.d.ts","sourceRoot":"","sources":["../src/company-department.object.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,qBA4Ba,iBAAiB;IAE5B,WAAW,EAAG,MAAM,CAAC;IAGrB,cAAc,EAAG,MAAM,CAAC;CACzB"}

package/dist/company-department.object.js

@@ -40,6 +40,26 @@ exports.CompanyDepartment = CompanyDepartment = __decorate([
         schema: schema_1.SCHEMA,
         access: { plane: 'control', system: true },
         readScope: { kind: 'nodeColumn', column: 'cd_company_uuid' },
+        // G-027: permission catalog text, read by every tenant's administrators (no tenant names).
+        label: 'Company department link',
+        permissions: {
+            read: {
+                label: 'Company departments: view',
+                description: 'See which departments belong to each of the companies they can reach.',
+            },
+            create: {
+                label: 'Company departments: create',
+                description: 'Link a department to its company, as happens when a department is added.',
+            },
+            update: {
+                label: 'Company departments: edit',
+                description: 'Change the links between companies and their departments.',
+            },
+            delete: {
+                label: 'Company departments: delete',
+                description: 'Remove the link between a company and a department.',
+            },
+        },
     }),
     (0, engine_1.PrimaryKey)({ kind: 'composite', columns: ['cd_company_uuid', 'cd_department_uuid'] })
 ], CompanyDepartment);

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

@@ -1 +1 @@
-{"version":3,"file":"company-membership.object.d.ts","sourceRoot":"","sources":["../src/company-membership.object.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,qBAca,iBAAiB;IAE5B,IAAI,EAAG,MAAM,CAAC;IAId,QAAQ,EAAG,MAAM,CAAC;IAGlB,WAAW,EAAG,MAAM,CAAC;IAGrB,QAAQ,EAAG,OAAO,CAAC;IAGnB,MAAM,EAAG,MAAM,CAAC;IAGhB,SAAS,EAAG,MAAM,CAAC;CACpB"}
+{"version":3,"file":"company-membership.object.d.ts","sourceRoot":"","sources":["../src/company-membership.object.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,qBAkCa,iBAAiB;IAE5B,IAAI,EAAG,MAAM,CAAC;IAId,QAAQ,EAAG,MAAM,CAAC;IAGlB,WAAW,EAAG,MAAM,CAAC;IAGrB,QAAQ,EAAG,OAAO,CAAC;IAGnB,MAAM,EAAG,MAAM,CAAC;IAGhB,SAAS,EAAG,MAAM,CAAC;CACpB"}

package/dist/company-membership.object.js

@@ -66,6 +66,26 @@ exports.CompanyMembership = CompanyMembership = __decorate([
         // admin's OWN node, breaking adding a user to a SUB-company (a legit hierarchy op). This
         // filters reads only. Root spans all.
         readScope: { kind: 'nodeColumn', column: 'cm_company_uuid' },
+        // G-027: permission catalog text, read by every tenant's administrators (no tenant names).
+        label: 'Company membership',
+        permissions: {
+            read: {
+                label: 'Memberships: view',
+                description: 'See which of the companies they can reach each user belongs to.',
+            },
+            create: {
+                label: 'Memberships: create',
+                description: 'Add users to the companies they can reach.',
+            },
+            update: {
+                label: 'Memberships: edit',
+                description: "Change a membership's status or make it the user's active company.",
+            },
+            delete: {
+                label: 'Memberships: delete',
+                description: 'Remove users from companies, together with their postings there.',
+            },
+        },
     }),
     (0, engine_1.PrimaryKey)({ kind: 'uuid', column: 'cm_uuid' })
 ], CompanyMembership);

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

@@ -1 +1 @@
-{"version":3,"file":"company.object.d.ts","sourceRoot":"","sources":["../src/company.object.ts"],"names":[],"mappings":"AAGA,kFAAkF;AAClF,qBAsBa,OAAO;IAElB,IAAI,EAAG,MAAM,CAAC;IAGd,IAAI,EAAG,MAAM,CAAC;IAKd,UAAU,EAAG,MAAM,CAAC;IAGpB,IAAI,EAAG,MAAM,CAAC;IAGd,MAAM,EAAG,MAAM,CAAC;IAGhB,SAAS,EAAG,MAAM,CAAC;CACpB"}
+{"version":3,"file":"company.object.d.ts","sourceRoot":"","sources":["../src/company.object.ts"],"names":[],"mappings":"AAGA,kFAAkF;AAClF,qBA4Ca,OAAO;IAElB,IAAI,EAAG,MAAM,CAAC;IAGd,IAAI,EAAG,MAAM,CAAC;IAKd,UAAU,EAAG,MAAM,CAAC;IAGpB,IAAI,EAAG,MAAM,CAAC;IAGd,MAAM,EAAG,MAAM,CAAC;IAGhB,SAAS,EAAG,MAAM,CAAC;CACpB"}

package/dist/company.object.js

@@ -69,6 +69,27 @@ exports.Company = Company = __decorate([
         // scope closure lists it, so the post-insert create wall would deny every create. Opted out
         // explicitly; the company service owns where a non-root create may attach (parent stamping).
         readScope: { kind: 'nodeColumn', column: 'c_uuid', create: 'unscoped' },
+        // G-027: permission catalog text, read by every tenant's administrators (no tenant names).
+        label: 'Company',
+        permissions: {
+            read: {
+                label: 'Companies: view',
+                description: 'See the companies in their part of the organisation.',
+            },
+            create: {
+                label: 'Companies: create',
+                description: 'Add new companies under the companies they can reach.',
+            },
+            update: {
+                label: 'Companies: edit',
+                description: 'Rename companies, change their status or move them under another parent company.',
+                caution: 'Moving a company changes which administrators above it can reach it and its data.',
+            },
+            delete: {
+                label: 'Companies: delete',
+                description: 'Remove companies that have no sub-companies.',
+            },
+        },
     }),
     (0, engine_1.PrimaryKey)({ kind: 'uuid', column: 'c_uuid' })
 ], Company);

package/dist/cross-tenant-grant.object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cross-tenant-grant.object.d.ts","sourceRoot":"","sources":["../src/cross-tenant-grant.object.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBASa,gBAAgB;IAE3B,IAAI,EAAG,MAAM,CAAC;IAGd,gBAAgB,EAAG,MAAM,CAAC;IAG1B,iBAAiB,EAAG,MAAM,CAAC;CAC5B"}
+{"version":3,"file":"cross-tenant-grant.object.d.ts","sourceRoot":"","sources":["../src/cross-tenant-grant.object.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBA2Ba,gBAAgB;IAE3B,IAAI,EAAG,MAAM,CAAC;IAGd,gBAAgB,EAAG,MAAM,CAAC;IAG1B,iBAAiB,EAAG,MAAM,CAAC;CAC5B"}

package/dist/cross-tenant-grant.object.js

@@ -63,6 +63,23 @@ exports.CrossTenantGrant = CrossTenantGrant = __decorate([
         access: { plane: 'control', system: true },
         crudActions: false,
         actions: guard_1.CROSS_TENANT_GRANT_ACTIONS,
+        // G-027: permission catalog text, read by every tenant's administrators (no tenant names).
+        label: 'Cross-tenant grant',
+        permissions: {
+            share: {
+                label: 'Cross-tenant grants: offer',
+                description: "Offer another tenant access to one type of their own tenant's records.",
+                caution: "Once accepted, people in the other tenant can reach this tenant's records of that type.",
+            },
+            accept: {
+                label: 'Cross-tenant grants: accept',
+                description: "Accept another tenant's offer of access to its records.",
+            },
+            revoke: {
+                label: 'Cross-tenant grants: revoke',
+                description: 'End a cross-tenant grant, or decline an offer, from either side.',
+            },
+        },
     }),
     (0, engine_1.PrimaryKey)({ kind: 'uuid', column: 'ctg_uuid' })
 ], CrossTenantGrant);

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

@@ -1 +1 @@
-{"version":3,"file":"department.object.d.ts","sourceRoot":"","sources":["../src/department.object.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,qBAQa,UAAU;IAErB,IAAI,EAAG,MAAM,CAAC;IAGd,IAAI,EAAG,MAAM,CAAC;IAGd,WAAW,EAAG,MAAM,CAAC;CACtB"}
+{"version":3,"file":"department.object.d.ts","sourceRoot":"","sources":["../src/department.object.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,qBA4Ba,UAAU;IAErB,IAAI,EAAG,MAAM,CAAC;IAGd,IAAI,EAAG,MAAM,CAAC;IAGd,WAAW,EAAG,MAAM,CAAC;CACtB"}

package/dist/department.object.js

@@ -45,6 +45,26 @@ exports.Department = Department = __decorate([
         schema: schema_1.SCHEMA,
         access: { plane: 'control', system: true },
         readScope: { kind: 'nodeColumn', column: 'd_company_uuid' },
+        // G-027: permission catalog text, read by every tenant's administrators (no tenant names).
+        label: 'Department',
+        permissions: {
+            read: {
+                label: 'Departments: view',
+                description: 'See the departments of the companies they can reach.',
+            },
+            create: {
+                label: 'Departments: create',
+                description: 'Add departments to the companies they can reach.',
+            },
+            update: {
+                label: 'Departments: edit',
+                description: 'Rename departments.',
+            },
+            delete: {
+                label: 'Departments: delete',
+                description: 'Delete departments.',
+            },
+        },
     }),
     (0, engine_1.PrimaryKey)({ kind: 'uuid', column: 'd_uuid' })
 ], Department);

package/dist/features/authz/app-release.d.ts

@@ -0,0 +1,12 @@
+/**
+ * G-027 (permission-notification spec §5H): the app release name stamped on a permission key's
+ * first catalogue insert (`perm_first_seen_version`), read ONCE by `IdentityFeatureModule.forRoot`.
+ *
+ *  - `APP_RELEASE` unset or blank ⇒ `null` (the version stays NULL).
+ *  - Otherwise the trimmed value, 1–64 characters of letters, digits, `.`, `_`, `+`, `-`
+ *    (a git sha or tag fits).
+ *  - Anything else refuses boot with an error naming the variable, never echoing the value.
+ */
+export declare const APP_RELEASE_ERROR = "APP_RELEASE must be 1\u201364 characters of letters, digits, . _ + -";
+export declare function loadAppRelease(env?: NodeJS.ProcessEnv): string | null;
+//# sourceMappingURL=app-release.d.ts.map

package/dist/features/authz/app-release.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-release.d.ts","sourceRoot":"","sources":["../../../src/features/authz/app-release.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,eAAO,MAAM,iBAAiB,yEAAoE,CAAC;AAEnG,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,IAAI,CAOlF"}

package/dist/features/authz/app-release.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * G-027 (permission-notification spec §5H): the app release name stamped on a permission key's
+ * first catalogue insert (`perm_first_seen_version`), read ONCE by `IdentityFeatureModule.forRoot`.
+ *
+ *  - `APP_RELEASE` unset or blank ⇒ `null` (the version stays NULL).
+ *  - Otherwise the trimmed value, 1–64 characters of letters, digits, `.`, `_`, `+`, `-`
+ *    (a git sha or tag fits).
+ *  - Anything else refuses boot with an error naming the variable, never echoing the value.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APP_RELEASE_ERROR = void 0;
+exports.loadAppRelease = loadAppRelease;
+const APP_RELEASE_PATTERN = /^[A-Za-z0-9._+-]{1,64}$/;
+exports.APP_RELEASE_ERROR = 'APP_RELEASE must be 1–64 characters of letters, digits, . _ + -';
+function loadAppRelease(env = process.env) {
+    const raw = env.APP_RELEASE;
+    if (raw === undefined)
+        return null;
+    const value = raw.trim();
+    if (value === '')
+        return null;
+    if (!APP_RELEASE_PATTERN.test(value))
+        throw new Error(exports.APP_RELEASE_ERROR);
+    return value;
+}

package/dist/features/authz/catalog-bootstrap.provider.d.ts

@@ -39,8 +39,24 @@ export declare class CatalogBootstrapProvider implements OnApplicationBootstrap,
      * that fires after this is a no-op. Never throws.
      */
     onModuleDestroy(): Promise<void>;
+    /**
+     * G-027 (spec §5I): one `warn` for the app's catalogued keys (types the registry knows, outside
+     * the framework's identity objects) without declared text: those without a declared label
+     * (they get the generated one), and those with a declared label but no description. Either
+     * list is omitted when empty; nothing is logged when every app key has both. Public-tier
+     * actions are skipped (they are never catalogued).
+     */
+    private warnMissingPermissionText;
     /** One scheduled reconcile pass (catalog, then bundles, then the scope closure). */
     private tick;
+    /**
+     * One catalog reconcile pass. G-027 spec §13: a DB error (an insert losing a race with another
+     * instance, a text UPDATE, an unreachable DB) is logged and retried on the next tick; it never
+     * aborts boot or the tick chain. Fail closed: a key the pass could not insert is not grantable
+     * (grants validate against the catalog). Logs the error's class and driver code only, never its
+     * message (it can carry SQL and values).
+     */
+    private reconcileCatalog;
     /** Rebuild the scope closure; a failure is logged loudly (never silently swallowed) but does
      *  not abort boot or a cron tick — the reconcile is idempotent and retried next interval. */
     private reconcileScopeClosure;

package/dist/features/authz/catalog-bootstrap.provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog-bootstrap.provider.d.ts","sourceRoot":"","sources":["../../../src/features/authz/catalog-bootstrap.provider.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC5E,OAAO,EAKL,KAAK,yBAAyB,EAC/B,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAKxE;;;;;;;;;;GAUG;AACH,qBACa,wBAAyB,YAAW,sBAAsB,EAAE,eAAe;IAQpF,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,YAAY;IAE7B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAE9B,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IAhBtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6C;IACpE,OAAO,CAAC,KAAK,CAA+B;IAC5C,wFAAwF;IACxF,OAAO,CAAC,iBAAiB,CAA8B;IACvD,OAAO,CAAC,SAAS,CAAS;gBAGP,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,mBAAmB,EACxB,eAAe,EAAE,wBAAwB,EACzC,YAAY,EAAE,mBAAmB,EAEjC,aAAa,EAAE,SAAS,UAAU,EAAE,EAEpC,mBAAmB,EAAE,yBAAyB;IAG3D,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAmE7C;;;;;OAKG;IACG,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAUtC,oFAAoF;IACpF,OAAO,CAAC,IAAI;IAaZ;iGAC6F;YAC/E,qBAAqB;CAOpC"}
+{"version":3,"file":"catalog-bootstrap.provider.d.ts","sourceRoot":"","sources":["../../../src/features/authz/catalog-bootstrap.provider.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC5E,OAAO,EAKL,KAAK,yBAAyB,EAC/B,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAaxE;;;;;;;;;;GAUG;AACH,qBACa,wBAAyB,YAAW,sBAAsB,EAAE,eAAe;IAQpF,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,YAAY;IAE7B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAE9B,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IAhBtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6C;IACpE,OAAO,CAAC,KAAK,CAA+B;IAC5C,wFAAwF;IACxF,OAAO,CAAC,iBAAiB,CAA8B;IACvD,OAAO,CAAC,SAAS,CAAS;gBAGP,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,mBAAmB,EACxB,eAAe,EAAE,wBAAwB,EACzC,YAAY,EAAE,mBAAmB,EAEjC,aAAa,EAAE,SAAS,UAAU,EAAE,EAEpC,mBAAmB,EAAE,yBAAyB;IAG3D,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAsE7C;;;;;OAKG;IACG,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAUtC;;;;;;OAMG;IACH,OAAO,CAAC,yBAAyB;IAiCjC,oFAAoF;IACpF,OAAO,CAAC,IAAI;IAYZ;;;;;;OAMG;YACW,gBAAgB;IAY9B;iGAC6F;YAC/E,qBAAqB;CAOpC"}

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

@@ -22,10 +22,15 @@ const common_1 = require("@nestjs/common");
 const core_1 = require("@nestjs/core");
 const guard_1 = require("@astram/guard");
 const engine_1 = require("@astram/engine");
+const objects_js_1 = require("../../objects.js");
 const catalog_reconcile_job_js_1 = require("./catalog-reconcile.job.js");
 const access_bundle_reconcile_job_js_1 = require("./access-bundle-reconcile.job.js");
 const scope_closure_service_js_1 = require("../scope/scope-closure.service.js");
 const MODULE_KEY = 'identity';
+/** The framework's own types (their text is declared by identity, never named in the warning). */
+function frameworkTypeKeys() {
+    return new Set(objects_js_1.identityObjects.map((input) => typeof input === 'function' ? (0, engine_1.reflectObjectType)(input).typeKey : input.typeKey));
+}
 const RECONCILE_INTERVAL_MS = 60 * 60 * 1000; // hourly; honors DISABLE_ALL_CRONS below
 /**
  * Boot: read-only verifyGatable (fail-closed — a stranded/unclassified route aborts
@@ -94,9 +99,11 @@ let CatalogBootstrapProvider = CatalogBootstrapProvider_1 = class CatalogBootstr
         }
         // Fail-closed (ADR-0002): a route that can't be gated aborts boot.
         new guard_1.CatalogReconciler().verifyGatable(inventory, registry);
+        // G-027 (spec §5I): ONE warning naming the app keys that lack declared text (never fails boot).
+        this.warnMissingPermissionText(registry);
         // Mutating reconcile runs AFTER boot (not blocking, not fail-closed).
         const nowIso = new Date().toISOString();
-        await this.job.runOnce(nowIso);
+        await this.reconcileCatalog(nowIso);
         // Bundles reconcile AFTER permissions (same post-boot pass): a bundle validates
         // its keys against the live permission catalog, so permissions must reconcile first.
         await this.accessBundleJob.runOnce(nowIso);
@@ -128,13 +135,53 @@ let CatalogBootstrapProvider = CatalogBootstrapProvider_1 = class CatalogBootstr
         if (running !== null)
             await running.catch(() => undefined);
     }
+    /**
+     * G-027 (spec §5I): one `warn` for the app's catalogued keys (types the registry knows, outside
+     * the framework's identity objects) without declared text: those without a declared label
+     * (they get the generated one), and those with a declared label but no description. Either
+     * list is omitted when empty; nothing is logged when every app key has both. Public-tier
+     * actions are skipped (they are never catalogued).
+     */
+    warnMissingPermissionText(registry) {
+        const catalogued = new Set(registry
+            .listActions()
+            .filter((a) => a.tier !== 'public')
+            .map((a) => `${a.action.typeKey}:${a.action.actionKey}`));
+        const noLabel = [];
+        const noDescription = [];
+        const framework = frameworkTypeKeys();
+        for (const reg of this.registrations) {
+            if (framework.has(reg.typeKey))
+                continue;
+            if (registry.resolveObjectType(reg.typeKey) === undefined)
+                continue;
+            for (const t of (0, engine_1.permissionTextOf)(reg)) {
+                const name = `${reg.typeKey}:${t.action}`;
+                if (!catalogued.has(name))
+                    continue;
+                if (!t.declared)
+                    noLabel.push(name);
+                else if (t.description === null)
+                    noDescription.push(name);
+            }
+        }
+        const parts = [];
+        if (noLabel.length > 0) {
+            parts.push(`${noLabel.length} permission(s) have no declared label: ${noLabel.join(', ')}`);
+        }
+        if (noDescription.length > 0) {
+            parts.push(`${noDescription.length}${parts.length > 0 ? '' : ' permission(s)'} have no description: ` +
+                noDescription.join(', '));
+        }
+        if (parts.length > 0)
+            this.logger.warn(`[catalog] ${parts.join('; ')}`);
+    }
     /** One scheduled reconcile pass (catalog, then bundles, then the scope closure). */
     tick() {
         if (this.destroyed)
             return;
         const tickIso = new Date().toISOString();
-        const run = this.job
-            .runOnce(tickIso)
+        const run = this.reconcileCatalog(tickIso)
             .then(() => this.accessBundleJob.runOnce(tickIso))
             .then(() => this.reconcileScopeClosure());
         // Kept so onModuleDestroy can drain it. Storing the reference attaches no handler, so a
@@ -142,6 +189,23 @@ let CatalogBootstrapProvider = CatalogBootstrapProvider_1 = class CatalogBootstr
         this.inFlightReconcile = run;
         void run;
     }
+    /**
+     * One catalog reconcile pass. G-027 spec §13: a DB error (an insert losing a race with another
+     * instance, a text UPDATE, an unreachable DB) is logged and retried on the next tick; it never
+     * aborts boot or the tick chain. Fail closed: a key the pass could not insert is not grantable
+     * (grants validate against the catalog). Logs the error's class and driver code only, never its
+     * message (it can carry SQL and values).
+     */
+    async reconcileCatalog(nowIso) {
+        try {
+            await this.job.runOnce(nowIso);
+        }
+        catch (cause) {
+            const name = cause instanceof Error ? cause.name : typeof cause;
+            const code = cause?.code;
+            this.logger.error(`[catalog] reconcile failed (${name}${typeof code === 'string' ? ` ${code}` : ''}); retried next interval`);
+        }
+    }
     /** Rebuild the scope closure; a failure is logged loudly (never silently swallowed) but does
      *  not abort boot or a cron tick — the reconcile is idempotent and retried next interval. */
     async reconcileScopeClosure() {

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

@@ -1,5 +1,5 @@
 import type { Pool } from 'mariadb';
-import { type ReconcileReport } from '@astram/guard';
+import { type PermissionText, type ReconcileReport } from '@astram/guard';
 import type { ModuleRegistry } from '@astram/core';
 import type { IdentitySchemaNames } from '../../schema.js';
 /**
@@ -12,12 +12,20 @@ import type { IdentitySchemaNames } from '../../schema.js';
  */
 export declare class CatalogReconcileJob {
     private readonly registry;
+    private readonly text?;
+    private readonly release;
     private readonly reconciler;
     private readonly store;
     private latest;
     private running;
-    /** @param schemas resolved framework names for the catalog store (absent ⇒ from the namespace). */
-    constructor(pool: Pool, registry: ModuleRegistry, schemas?: IdentitySchemaNames);
+    /**
+     * @param schemas resolved framework names for the catalog store (absent ⇒ from the namespace).
+     * @param text G-027: permission key → code text (`permissionTextByKey` over the registry's
+     *   types); absent ⇒ generated labels and no relabelling.
+     * @param release G-027: the app release (`loadAppRelease`) stamped as first-seen version on
+     *   insert; absent ⇒ null.
+     */
+    constructor(pool: Pool, registry: ModuleRegistry, schemas?: IdentitySchemaNames, text?: ReadonlyMap<string, PermissionText> | undefined, release?: string | null);
     /** Idempotent single pass. Guarded so overlapping ticks don't double-run. */
     runOnce(nowIso: string): Promise<ReconcileReport | null>;
     getLatest(): ReconcileReport | null;

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

@@ -1 +1 @@
-{"version":3,"file":"catalog-reconcile.job.d.ts","sourceRoot":"","sources":["../../../src/features/authz/catalog-reconcile.job.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE3D;;;;;;;GAOG;AACH,qBAAa,mBAAmB;IAS5B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAR3B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA2B;IACtD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;IAC5C,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,OAAO,CAAS;IAExB,mGAAmG;gBAEjG,IAAI,EAAE,IAAI,EACO,QAAQ,EAAE,cAAc,EACzC,OAAO,CAAC,EAAE,mBAAmB;IAK/B,6EAA6E;IACvE,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAiB9D,SAAS,IAAI,eAAe,GAAG,IAAI;CAGpC"}
+{"version":3,"file":"catalog-reconcile.job.d.ts","sourceRoot":"","sources":["../../../src/features/authz/catalog-reconcile.job.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAqB,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAC7F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE3D;;;;;;;GAOG;AACH,qBAAa,mBAAmB;IAe5B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAEzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAjB1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA2B;IACtD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;IAC5C,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,OAAO,CAAS;IAExB;;;;;;OAMG;gBAED,IAAI,EAAE,IAAI,EACO,QAAQ,EAAE,cAAc,EACzC,OAAO,CAAC,EAAE,mBAAmB,EACZ,IAAI,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,YAAA,EAC1C,OAAO,GAAE,MAAM,GAAG,IAAW;IAKhD,6EAA6E;IACvE,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAoB9D,SAAS,IAAI,eAAe,GAAG,IAAI;CAGpC"}

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

@@ -13,13 +13,23 @@ const mariadb_catalog_store_js_1 = require("./mariadb-catalog-store.js");
  */
 class CatalogReconcileJob {
     registry;
+    text;
+    release;
     reconciler = new guard_1.CatalogReconciler();
     store;
     latest = null;
     running = false;
-    /** @param schemas resolved framework names for the catalog store (absent ⇒ from the namespace). */
-    constructor(pool, registry, schemas) {
+    /**
+     * @param schemas resolved framework names for the catalog store (absent ⇒ from the namespace).
+     * @param text G-027: permission key → code text (`permissionTextByKey` over the registry's
+     *   types); absent ⇒ generated labels and no relabelling.
+     * @param release G-027: the app release (`loadAppRelease`) stamped as first-seen version on
+     *   insert; absent ⇒ null.
+     */
+    constructor(pool, registry, schemas, text, release = null) {
         this.registry = registry;
+        this.text = text;
+        this.release = release;
         this.store = new mariadb_catalog_store_js_1.MariaDbCatalogStore(pool, schemas);
     }
     /** Idempotent single pass. Guarded so overlapping ticks don't double-run. */
@@ -28,11 +38,14 @@ class CatalogReconcileJob {
             return this.latest;
         this.running = true;
         try {
-            const report = await this.reconciler.reconcile(this.registry, this.store, nowIso);
+            const report = await this.reconciler.reconcile(this.registry, this.store, nowIso, {
+                ...(this.text !== undefined ? { text: this.text } : {}),
+                release: this.release,
+            });
             this.latest = report;
             const orphanNote = report.orphaned.length ? ` — ORPHANED: ${report.orphaned.join(', ')}` : '';
             console.log(`[catalog] reconcile: +${report.added.length} added, ${report.orphaned.length} orphaned, ` +
-                `${report.reactivated.length} reactivated${orphanNote}`);
+                `${report.reactivated.length} reactivated, ${report.relabelled.length} relabelled${orphanNote}`);
             return report;
         }
         finally {

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

@@ -51,6 +51,10 @@ export declare class GrantAdminController {
             module: string;
             typeKey: string;
             action: string;
+            description: string | null;
+            caution: string | null;
+            firstSeenAt: string | null;
+            firstSeenVersion: string | null;
         }[];
         wildcards: string[];
     }>;

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

@@ -1 +1 @@
-{"version":3,"file":"grant-admin.controller.d.ts","sourceRoot":"","sources":["../../../src/features/authz/grant-admin.controller.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAe,MAAM,0BAA0B,CAAC;AAI1E,qFAAqF;AACrF,UAAU,aAAa;IACrB,SAAS,EAAE,SAAS,CAAC;CACtB;AAaD;;;;;;;;;;;;;;GAcG;AACH,qBAEa,oBAAoB;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,iBAAiB;IAEtD;;;;;;;;OAQG;IAGG,aAAa,CACV,GAAG,EAAE,aAAa,EAEzB,KAAK,EAAE;QACL,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB;;;;;;IAcH,sDAAsD;IAGhD,OAAO;;;;;;;;;;IAIb;kGAC8F;IAGxF,IAAI,CAAQ,GAAG,EAAE,aAAa,EAA2B,IAAI,EAAE,MAAM;;;IAI3E,0CAA0C;IAGpC,KAAK,CACF,GAAG,EAAE,aAAa,EACA,IAAI,EAAE,MAAM,EAC7B,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAahC,mFAAmF;IAG7E,MAAM,CACH,GAAG,EAAE,aAAa,EACA,IAAI,EAAE,MAAM,EACvB,GAAG,EAAE,MAAM;;;IAQ3B;;;;OAIG;IAGG,OAAO;;;IAIb;;;;OAIG;IAGG,WAAW,CACR,GAAG,EAAE,aAAa,EACA,IAAI,EAAE,MAAM,EAC7B,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAahC;;;;OAIG;IAGG,YAAY,CACT,GAAG,EAAE,aAAa,EACA,IAAI,EAAE,MAAM,EACvB,GAAG,EAAE,MAAM;;;CAU5B"}
+{"version":3,"file":"grant-admin.controller.d.ts","sourceRoot":"","sources":["../../../src/features/authz/grant-admin.controller.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAe,MAAM,0BAA0B,CAAC;AAI1E,qFAAqF;AACrF,UAAU,aAAa;IACrB,SAAS,EAAE,SAAS,CAAC;CACtB;AAaD;;;;;;;;;;;;;;GAcG;AACH,qBAEa,oBAAoB;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,iBAAiB;IAEtD;;;;;;;;OAQG;IAGG,aAAa,CACV,GAAG,EAAE,aAAa,EAEzB,KAAK,EAAE;QACL,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB;;;;;;IAcH,sDAAsD;IAGhD,OAAO;;;;;;;;;;;;;;IAIb;kGAC8F;IAGxF,IAAI,CAAQ,GAAG,EAAE,aAAa,EAA2B,IAAI,EAAE,MAAM;;;IAI3E,0CAA0C;IAGpC,KAAK,CACF,GAAG,EAAE,aAAa,EACA,IAAI,EAAE,MAAM,EAC7B,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAahC,mFAAmF;IAG7E,MAAM,CACH,GAAG,EAAE,aAAa,EACA,IAAI,EAAE,MAAM,EACvB,GAAG,EAAE,MAAM;;;IAQ3B;;;;OAIG;IAGG,OAAO;;;IAIb;;;;OAIG;IAGG,WAAW,CACR,GAAG,EAAE,aAAa,EACA,IAAI,EAAE,MAAM,EAC7B,IAAI,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAahC;;;;OAIG;IAGG,YAAY,CACT,GAAG,EAAE,aAAa,EACA,IAAI,EAAE,MAAM,EACvB,GAAG,EAAE,MAAM;;;CAU5B"}

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

@@ -21,12 +21,21 @@ export interface SubtreeScope {
 export declare class BadKeyError extends Error {
     constructor(key: string);
 }
+/**
+ * One `GET /identity/permission-catalog` row. G-027 (spec §5J): `description`/`caution` are the
+ * declared plain text (null when absent); `firstSeenAt` is ISO (null ⇒ the key existed before
+ * tracking began), `firstSeenVersion` the `APP_RELEASE` at first insert (null when unset).
+ */
 type CatalogRow = {
     key: string;
     label: string;
     module: string;
     typeKey: string;
     action: string;
+    description: string | null;
+    caution: string | null;
+    firstSeenAt: string | null;
+    firstSeenVersion: string | null;
 };
 /** A bundle as returned by the list API — identified by `key`, NEVER by `ab_uuid`. */
 export interface BundleView {

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

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

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

@@ -7,6 +7,7 @@ const access_bundle_store_js_1 = require("./access-bundle-store.js");
 const db_permission_facts_adapter_js_1 = require("./db-permission-facts.adapter.js");
 const grant_ceiling_js_1 = require("./grant-ceiling.js");
 const role_binding_js_1 = require("./role-binding.js");
+const mariadb_catalog_store_js_1 = require("./mariadb-catalog-store.js");
 const identity_errors_js_1 = require("../shared/identity-errors.js");
 const lock_service_accounts_js_1 = require("../service-account/lock-service-accounts.js");
 const schema_js_1 = require("../../schema.js");
@@ -66,7 +67,9 @@ class GrantAdminService {
     async listCatalog() {
         let rows;
         try {
-            rows = (await this.pool.query(`SELECT perm_key, perm_label, perm_module, perm_type_key, perm_action
+            // First seen as epoch seconds (timezone-independent; see `isoFromEpochSeconds`).
+            rows = (await this.pool.query(`SELECT perm_key, perm_label, perm_module, perm_type_key, perm_action, perm_description,
+                perm_caution, UNIX_TIMESTAMP(perm_first_seen_at) AS perm_first_seen_at, perm_first_seen_version
            FROM \`${this.schemas.authz}\`.\`permission\`
           WHERE perm_status = 'active'
           ORDER BY perm_type_key, perm_action`));
@@ -80,6 +83,10 @@ class GrantAdminService {
             module: r.perm_module,
             typeKey: r.perm_type_key,
             action: r.perm_action,
+            description: r.perm_description ?? null,
+            caution: r.perm_caution ?? null,
+            firstSeenAt: (0, mariadb_catalog_store_js_1.isoFromEpochSeconds)(r.perm_first_seen_at),
+            firstSeenVersion: r.perm_first_seen_version ?? null,
         }));
         // Wildcards: module-wide + one per distinct type key.
         const modules = [...new Set(catalog.map((c) => c.module))];

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

@@ -1,10 +1,16 @@
 import type { Pool } from 'mariadb';
-import type { CatalogStore, CatalogPermissionRow } from '@astram/guard';
+import type { CatalogStore, CatalogPermissionRow, CatalogTextUpdate } from '@astram/guard';
 import { type IdentitySchemaNames } from '../../schema.js';
+/** `UNIX_TIMESTAMP(col)` as the driver returns it (number, bigint or string) → ISO; NULL ⇒ null. */
+export declare function isoFromEpochSeconds(value: unknown): string | null;
 /**
  * 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.
  */
 export declare class MariaDbCatalogStore implements CatalogStore {
     private readonly pool;
@@ -12,8 +18,12 @@ export declare class MariaDbCatalogStore implements CatalogStore {
     /** @param schemas resolved framework names (absent ⇒ resolved from the namespace, once). */
     constructor(pool: Pool, schemas?: IdentitySchemaNames);
     listPermissions(): Promise<CatalogPermissionRow[]>;
+    /** Insert-only: a key that already exists matches no row (`WHERE NOT EXISTS`) and is untouched. */
     upsertPermission(row: Omit<CatalogPermissionRow, 'status'>): Promise<boolean>;
     markOrphaned(keys: readonly string[]): Promise<void>;
-    markActive(keys: readonly string[]): Promise<void>;
+    /** Orphaned → active; with `nowIso` also stamps `perm_last_activated_at` (never first seen). */
+    markActive(keys: readonly string[], nowIso?: string): Promise<void>;
+    /** G-027: the code's text replaces the stored text, one parameterized UPDATE per key. */
+    updateText(rows: readonly CatalogTextUpdate[]): Promise<void>;
 }
 //# sourceMappingURL=mariadb-catalog-store.d.ts.map