@endora-commerce/mod-admin-roles 0.100.0

package/dist/backend/index.js

@@ -0,0 +1,114 @@
+import { lazyPort } from '@endora-commerce/platform/kernel';
+import { effectiveState } from '@endora-commerce/platform/kernel';
+import { AdminRoleService } from './services/admin-role-service.js';
+import { createAdminRolePort, createSystemRoleCodePort } from './services/admin-role-ports.js';
+import { PermissionCatalogueService } from './services/permission-catalogue.service.js';
+import { PermissionService } from './services/permission-service.js';
+import { AdminRole } from './entities/admin-role.entity.js';
+export function registerModule(ctx) {
+    /**
+     * Who holds a role, and who an admin id belongs to (feature 075, Phase C).
+     *
+     * Both services used to run `em.findOne(AdminUser, …)` against a table
+     * `admin_users` owns. Held as a lazy proxy rather than resolved here: the
+     * resolution happens per call, so a singleton service never captures the
+     * registration.
+     */
+    const adminUsers = lazyPort(ctx, 'adminUserReadPort');
+    ctx.di.register({
+        permissionCatalogueService: ctx
+            .asFunction(({ resolvedModuleRegistry }) => new PermissionCatalogueService({
+            registryEntries: [...resolvedModuleRegistry],
+            // Issue #213 — the presence predicate is the module's own to read,
+            // not a knob a root turns on its behalf. Both roots used to wire
+            // `registryCache.enabledIds()` here through a setter, which is
+            // composition-checklist item 6's "a knob a root resolves on the
+            // module's behalf is a knob that drifts between the two roots" —
+            // and it had drifted onto the wrong axis in both copies at once.
+            // `effectiveState` is the kernel's one place where the two axes are
+            // combined, and reading it directly is what the other twenty
+            // modules that need presence already do.
+            isModulePresent: (moduleId) => effectiveState.isPresent(moduleId),
+        }))
+            .singleton(),
+        adminRoleService: ctx
+            .asFunction(({ emFactory, permissionCatalogueService, auditLogService }) => new AdminRoleService(emFactory, permissionCatalogueService, adminUsers, auditLogService))
+            .singleton(),
+    });
+    // A port: `auth` resolves it from another module, so its availability is a
+    // cross-module question and answers on the effective state.
+    ctx.di.providePort('permissionService', ctx
+        .asFunction(({ emFactory }) => new PermissionService(emFactory, adminUsers))
+        .singleton());
+    // ---------------------------------------------------------------------------
+    // Feature 075, Phase P — the published surface.
+    //
+    // `adminRoleService` and `permissionCatalogueService` above are plain
+    // registrations that three other modules resolve; these three ports are what
+    // they rewire to, and `adminRolePort` is the one that stops handing the
+    // `AdminRole` entity across.
+    //
+    // `systemRoleCodePort` is a **contribution seam** and stays one: `blog`
+    // registers its seeded code from a boot hook, so a gate would throw during
+    // composition — and, worse, would let an operator delete a protected role by
+    // switching its owner off for a moment. It is `providePort` all the same
+    // because reading the list back is a call rather than a contribution, and
+    // the gate is unreachable in the direction that matters: nothing in the tree
+    // registers a code after boot.
+    // ---------------------------------------------------------------------------
+    ctx.di.providePort('adminRolePort', ctx
+        .asFunction(({ emFactory }) => createAdminRolePort(emFactory, () => ctx.cradle().adminRoleService))
+        .singleton());
+    ctx.di.providePort('permissionCataloguePort', ctx
+        .asFunction(({ permissionCatalogueService }) => permissionCatalogueService)
+        .singleton());
+    ctx.di.register({
+        systemRoleCodePort: ctx.asFunction(() => createSystemRoleCodePort()).singleton(),
+    });
+}
+/**
+ * The module's persisted entity classes, on the `./backend` subpath, as one
+ * array and **no named class export** (D-168).
+ *
+ * This is the shape the platform reads when the package is *installed*: the
+ * boot-time loader (`src/packages/package-runtime.ts`, `exported['entities']`)
+ * and the static declaration reader (`scripts/lib/package-declarations.ts`),
+ * which is the third source of `check:module-boundary`'s `table->owner` map and
+ * the package pass of `check-entity-tenant-classification`. A missing array is
+ * answered with `[]` — zero entities registered, no error anywhere.
+ *
+ * The order is the one `db/entities-registry.generated.ts` declared before this
+ * module became a package, so the registered set is the same list in the same
+ * sequence.
+ */
+export const entities = [
+    AdminRole,
+];
+/**
+ * The permission catalogue and the inventory scanner, published **by name**.
+ *
+ * Three host programs read them — the acceptance instance probe,
+ * `check:action-route-permissions`, and the permission-inventory contract test
+ * — and each of those processes also holds this package's published artefact,
+ * so a filesystem path into this module's source would give them a second copy
+ * of everything on that file's graph (D-160.6.1). None of these is an entity,
+ * which is the one thing D-168 keeps off this door; what they are is the
+ * host-facing half of the permission estate, and it has to be the same half the
+ * platform composed or a scanner reports on a catalogue nobody enforces.
+ */
+/**
+ * The permission list the demo's `sales_representative` role carries (feature
+ * 113, T222).
+ *
+ * It was `backend/src/seeds/seeded-role-permissions.ts`, and it is published
+ * here because six `test/contract/*\/permission-authority.test.ts` files assert
+ * what that role may reach and must read **the list the seed actually writes**,
+ * not a copy of it. Since T222 the seed that writes it is this module's own
+ * demo body, so this is where the list lives and this is the door those tests
+ * name. It is a `readonly string[]` of catalogue codes — no entity, so D-168
+ * does not bar it — and `demo/rows.ts` carries nothing else on its graph.
+ */
+export { SALES_REPRESENTATIVE_PERMISSIONS } from './demo/rows.js';
+export { PermissionCatalogueService, listAssignablePermissionCodes } from './services/permission-catalogue.service.js';
+export { ConstantResolver, defaultScanRoots, scanEnforcedPermissionCodes, scanEnforcedPermissionGates } from './permission-inventory.js';
+//# sourceMappingURL=index.js.map

package/dist/backend/index.js.map

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

package/dist/backend/permission-inventory.d.ts

@@ -0,0 +1,117 @@
+/** How a gate site resolves to a permission code. */
+export type GateResolution = 
+/** The argument resolved to one or more literal permission codes. */
+'code'
+/** `requireAdmin()` — any authenticated admin, no code to check. */
+ | 'authenticated-admin'
+/**
+ * The argument is a value bound at runtime — a guard implementation consuming
+ * its own parameter, a delegating re-registration forwarding one, or a
+ * registry entry supplying a code its contributing module writes elsewhere.
+ * There is no literal to check here; the literal is checked where it is
+ * written, which is a site this scan also reads.
+ */
+ | 'runtime-value'
+/** An argument the scanner could not resolve — reported, never dropped. */
+ | 'unresolved';
+export interface EnforcedGateSite {
+    /** Path relative to `backend/src`, for a failure message that can be acted on. */
+    readonly file: string;
+    /** The module directory owning the file, or `null` outside a module tree. */
+    readonly moduleId: string | null;
+    /** The raw argument text, normalised to a single line. */
+    readonly expression: string;
+    readonly resolution: GateResolution;
+    /** Codes this site enforces; empty unless `resolution === 'code'`. */
+    readonly codes: readonly string[];
+}
+export interface PermissionScanResult {
+    readonly codes: Set<string>;
+    readonly sites: readonly EnforcedGateSite[];
+    readonly unresolved: readonly EnforcedGateSite[];
+    readonly runtimeValue: readonly EnforcedGateSite[];
+    readonly authenticatedAdminOnly: readonly EnforcedGateSite[];
+}
+/**
+ * One directory the scan walks.
+ *
+ * `moduleId` is set when the directory **is** one module's — a module that has
+ * become a workspace package (feature 080, T040b). Its internal layout is its
+ * own, so `src/backend/routes.admin.ts` carries no `modules/<id>/` segment for
+ * {@link moduleIdFor} to read, and the id comes off the declaration that put the
+ * root in the list (D-142) rather than off the path.
+ */
+export interface PermissionScanRoot {
+    readonly dir: string;
+    readonly moduleId?: string;
+}
+/**
+ * The roots a bare-core build enforces gates in, plus the active deployment's
+ * overlay modules (feature 057 — an overlay module is an ordinary lifecycle
+ * participant, so its gates count for that deployment and for no other).
+ *
+ * `src/apps` is skipped during the walk rather than excluded by name: a
+ * deployment that is not the selected one is not part of this build, and its
+ * permissions are not assignable here.
+ *
+ * **A module that is a workspace package is not here, and is the caller's to
+ * supply.** This scanner has no runtime caller — its two callers are
+ * `test/contract/admin_users/permission-inventory.test.ts` and the scanner's own
+ * unit test — and the module layout is derived by `scripts/lib/module-roots.ts`,
+ * which a module may not import (`check:module-boundary`, and it is right to
+ * refuse: this file belongs to `admin_roles`). So the root list is an input, and
+ * the caller that already resolves the layout passes it. Leaving a packaged
+ * module out silently reports its codes as *"grantable but enforced by no
+ * gate"* — a checkbox `/admin-roles` says grants nothing while the gate is
+ * there — which is what the contract test caught the day `blog` moved.
+ *
+ * **The overlay root is an input for the same reason** (feature 080, T051). It
+ * used to be computed here, from `overlay/overlay-roots.js` — a file
+ * `contracts/host-package.md` §1.4l classifies **A**, because `overlay/*` is
+ * how the platform *discovers* overlays and a module reading it as an installed
+ * package would be an artefact enumerating its own siblings (O3's cycle). The
+ * answer is the same one this paragraph already gives for a packaged module:
+ * the caller resolves the layout, and there is no runtime caller to inconvenience.
+ * `null` means a bare-core build, which is what a deployment-less environment
+ * has always produced.
+ */
+export declare function defaultScanRoots(applicationSourceRoot: string, overlayModulesRoot: string | null): string[];
+/**
+ * Distinct permission codes referenced by an enforcement site under the scan
+ * roots. Kept for callers that only need the set (SC-001).
+ */
+export declare function scanEnforcedPermissionCodes(roots: readonly (string | PermissionScanRoot)[]): Set<string>;
+/**
+ * Every enforcement site under `roots`, classified.
+ *
+ * `roots` is required. It used to default to `defaultScanRoots()`, which
+ * resolved the active deployment for itself; that resolution is the caller's
+ * now (see {@link defaultScanRoots}), and a default of "bare core" would be a
+ * scan that silently covered less than it was asked for.
+ *
+ * Each site's `file` is reported relative to the **first bare-string root**,
+ * which is the application's own source root by construction of
+ * {@link defaultScanRoots} — a module package is passed as an object carrying
+ * its `moduleId`. It used to be relative to a `backend/src` this file computed
+ * by climbing out of its own directory, which answered a different directory
+ * the day `admin_roles` became a package (feature 080, T040b).
+ */
+export declare function scanEnforcedPermissionGates(roots: readonly (string | PermissionScanRoot)[]): PermissionScanResult;
+/**
+ * Resolves a constant argument to its literal, following at most a few hops:
+ * module-local, a relative import, or `@endora-commerce/contracts`. Deeper indirection has
+ * never appeared, and pretending to resolve it would hide the same gate the
+ * `unresolved` bucket is there to surface.
+ *
+ * Exported for `scripts/check-action-route-permissions.ts` (issue #232), which
+ * asks the third direction — is an action's `requiredPermission` the code
+ * enforced on **its own** target route — and needs the same argument shapes read
+ * the same way. A second resolver would answer the same question differently the
+ * first time either of them learned a shape.
+ */
+export declare class ConstantResolver {
+    #private;
+    sourceOf(file: string): string | null;
+    lookup(file: string, name: string, property: string | null, depth?: number): string | null;
+}
+//# sourceMappingURL=permission-inventory.d.ts.map

package/dist/backend/permission-inventory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-inventory.d.ts","sourceRoot":"","sources":["../../src/backend/permission-inventory.ts"],"names":[],"mappings":"AA6CA,qDAAqD;AACrD,MAAM,MAAM,cAAc;AACxB,qEAAqE;AACnE,MAAM;AACR,oEAAoE;GAClE,qBAAqB;AACvB;;;;;;GAMG;GACD,eAAe;AACjB,2EAA2E;GACzE,YAAY,CAAC;AAEjB,MAAM,WAAW,gBAAgB;IAC/B,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC5C,QAAQ,CAAC,UAAU,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACjD,QAAQ,CAAC,YAAY,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACnD,QAAQ,CAAC,sBAAsB,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAC9D;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,gBAAgB,CAC9B,qBAAqB,EAAE,MAAM,EAC7B,kBAAkB,EAAE,MAAM,GAAG,IAAI,GAChC,MAAM,EAAE,CAIV;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,SAAS,CAAC,MAAM,GAAG,kBAAkB,CAAC,EAAE,GAC9C,GAAG,CAAC,MAAM,CAAC,CAEb;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,SAAS,CAAC,MAAM,GAAG,kBAAkB,CAAC,EAAE,GAC9C,oBAAoB,CAoBtB;AA8PD;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAgB;;IAI3B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIrC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,SAAI,GAAG,MAAM,GAAG,IAAI;CAmEtF"}