@endora-commerce/mod-admin-roles 0.100.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Endora sp. z o.o. and the Endora Commerce contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+<!-- Generated by `pnpm --filter backend run manifests:generate`. Delete this line to take the file over; a README without it is never regenerated. -->
+
+# @endora-commerce/mod-admin-roles
+
+Admin RBAC — roles, permissions, and policy enforcement for admin sessions.
+
+## What this is
+
+An **Endora Commerce module package**. Its module id is `admin_roles` — the identity of record in the platform's registries, in its migrations and in its setting, permission and translation codes.
+
+A module is not imported by application code. The platform discovers the extension packages an instance has installed, reads the manifest on the root subpath and composes the module from it, so installing this package and starting the instance is the whole integration.
+
+## Entry points
+
+| Import | Contents |
+| --- | --- |
+| `@endora-commerce/mod-admin-roles` | the module manifest — its id, version, dependencies, settings and activation |
+| `@endora-commerce/mod-admin-roles/admin` | the Admin UI contribution: the screens, navigation and palette actions it adds |
+| `@endora-commerce/mod-admin-roles/backend` | the composition root the platform calls, with the entities, services, routes and workers it registers |
+| `@endora-commerce/mod-admin-roles/tailwind.css` | the Tailwind source declaration for the admin code above |
+
+## Depends on
+
+Everything below is a **peer** dependency, so the application resolves exactly one copy of each — two copies of a host or of React are a runtime failure rather than a type error. An entry marked *optional* is needed only by the layers that use it.
+
+**Endora packages**
+
+- `@endora-commerce/admin-kit` — *optional*
+- `@endora-commerce/contracts`
+- `@endora-commerce/platform`
+
+**Third-party**
+
+- `@mikro-orm/core` ^6
+- `@mikro-orm/postgresql` ^6
+
+## What the tarball carries
+
+- `dist/` — the compiled JavaScript and its type declarations
+- `i18n/` — the translation bundles this package ships (`en`, `pl`), loaded by the platform
+- `docs/` — the package’s own pages in the Endora Commerce documentation site
+- `tailwind.css` — the Tailwind source declaration
+
+## Install
+
+```bash
+pnpm add @endora-commerce/mod-admin-roles
+```
+
+## Licence
+
+MIT — the text is in `LICENSE`, beside this file.

package/dist/admin/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `admin_roles`' admin surface — **one sidebar entry and no route of its own**,
+ * declared by the module that owns it (feature 091, Phase 4, batch four;
+ * `specs/091-module-owned-admin-surfaces/contracts/admin-contribution.md`).
+ *
+ * **This module ships a nav entry pointing at a route another module
+ * declares**, which the registry supports by design —
+ * `AdminContributions`' three arrays are each optional, and
+ * `admin/test/lib/module-registry.test.ts` reads *"a module that contributes
+ * only nav as contributing no route"* as legal. It is not a shortcut taken to
+ * make a move cheap; it is the honest shape of a screen the two hand-written
+ * registries have disagreed about since it was written: `App.tsx` imported
+ * `AdminRolesPage` out of `admin_users`' surface directory while
+ * `AppShell.tsx`'s row declared `module: 'admin_roles'`, and
+ * `backend/scripts/ledgers/admin-registrations.ts` records both facts rather
+ * than picking one.
+ *
+ * `plan.md`'s open question 3 recommended keeping exactly that attribution and
+ * this is where the recommendation is made explicit. The **route** belongs to
+ * `admin_users`, because the screen is served by
+ * `GET /api/v1/admin/admin-roles` in that module's `routes.admin.ts` and the
+ * component lives in its package; the **sidebar entry and the palette action**
+ * belong here, because they advertise the roles capability, which is this
+ * module's whole subject. Both modules declare `nonDeactivatable`, so nothing
+ * an operator can do makes the split observable today. It stops being inert the
+ * day either is unlocked: switching `admin_roles` off would withdraw the
+ * advertisement and leave the deep link working, which is the right answer for
+ * a module that owns the *roles* capability and not the screen that edits it.
+ *
+ * **`admin_users:manage`, not an `admin_roles:*` code.** This module registers
+ * no admin route and declares no permission of its own, and the endpoints the
+ * screen calls all enforce that one code
+ * (`packages/modules/admin_users/src/backend/routes.admin.ts`). The comment the
+ * hand-written NAV entry carried said so, and it survives the move rather than
+ * being re-derived by whoever reads the declaration next. The module
+ * attribution and the permission answer two different questions here, which is
+ * why they are two fields.
+ *
+ * **This entry exports data and nothing else** (R2), like every `./admin`
+ * layer: `check:module-boundary`'s D-171 rule designates a subpath as contract
+ * surface when it emits no runtime binding, and `./admin` deliberately does not
+ * qualify, so a consumer reaching into another module's `./admin` stays a
+ * counted boundary reach.
+ */
+import type { AdminContributions } from '@endora-commerce/admin-kit/contributions';
+export declare const contributions: AdminContributions;
+//# sourceMappingURL=index.d.ts.map

package/dist/admin/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/admin/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0CAA0C,CAAC;AAKnF,eAAO,MAAM,aAAa,EAAE,kBAuB3B,CAAC"}

package/dist/admin/index.js

@@ -0,0 +1,27 @@
+/** The roles editor. `admin_users` declares the route; this is where it goes. */
+const ROLES_PATH = '/admin-roles';
+export const contributions = {
+    nav: [
+        {
+            to: ROLES_PATH,
+            // Module-relative (R8), resolved in this module's own namespace out of
+            // `packages/modules/admin_roles/i18n/`. It was `appShell.nav.roles` in
+            // the shared `_i18n` bundle, one of the four shared files a module author
+            // had to edit.
+            labelKey: 'nav.adminRoles.label',
+            // The icon the hand-written NAV entry carried. It joins
+            // `KnownIconNameSchema` and `icon-map.ts` in this merge request: a nav
+            // entry names its glyph now, so keeping the one the sidebar already drew
+            // meant adding the name rather than substituting one already on the list.
+            icon: 'ShieldCheck',
+            section: 'system',
+            // The hand-written table's position times a hundred — see the note in
+            // `packages/modules/audit_logs/src/admin/index.ts`. `/admin-roles` was
+            // third of thirteen, directly after `/admin-users` (200), and that
+            // relative order is preserved.
+            weight: 300,
+            requiredPermission: 'admin_users:manage',
+        },
+    ],
+};
+//# sourceMappingURL=index.js.map

package/dist/admin/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/admin/index.ts"],"names":[],"mappings":"AA8CA,iFAAiF;AACjF,MAAM,UAAU,GAAG,cAAc,CAAC;AAElC,MAAM,CAAC,MAAM,aAAa,GAAuB;IAC/C,GAAG,EAAE;QACH;YACE,EAAE,EAAE,UAAU;YACd,uEAAuE;YACvE,uEAAuE;YACvE,0EAA0E;YAC1E,eAAe;YACf,QAAQ,EAAE,sBAAsB;YAChC,wDAAwD;YACxD,uEAAuE;YACvE,yEAAyE;YACzE,0EAA0E;YAC1E,IAAI,EAAE,aAAa;YACnB,OAAO,EAAE,QAAQ;YACjB,sEAAsE;YACtE,uEAAuE;YACvE,mEAAmE;YACnE,+BAA+B;YAC/B,MAAM,EAAE,GAAG;YACX,kBAAkB,EAAE,oBAAoB;SACzC;KACF;CACF,CAAC"}

package/dist/backend/demo/reset.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Withdraw `admin_roles`' demo data (feature 113, T222 — contract §2.5).
+ *
+ * By the fixed codes `seed` assigns, never by a predicate over the table. That
+ * is not a precaution here, it is a measured one: `blog` and `cms` seed a
+ * `blog_manager` and a `content_manager` role from their own boot hooks, and an
+ * operator's own role is indistinguishable from a demo one by every other
+ * column. This is the withdrawal that replaces `admin_roles`' line in the host's
+ * `truncate … cascade`, which took all four with it — and, through the cascade,
+ * the `admin_users` rows pointing at them.
+ *
+ * The demo administrators' **assignment** to these roles is withdrawn first, by
+ * the composition: `reset` runs the composition's withdrawal before any module's
+ * (§5.5), which is also what leaves no `admin_users` row referencing a role
+ * deleted below.
+ */
+import type { DemoResetResult, ModuleDemoContext } from '@endora-commerce/contracts';
+import type { ModuleContext } from '@endora-commerce/platform/kernel';
+export declare function resetDemo(context: ModuleDemoContext<ModuleContext>): Promise<DemoResetResult>;
+//# sourceMappingURL=reset.d.ts.map

package/dist/backend/demo/reset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reset.d.ts","sourceRoot":"","sources":["../../../src/backend/demo/reset.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACrF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAStE,wBAAsB,SAAS,CAC7B,OAAO,EAAE,iBAAiB,CAAC,aAAa,CAAC,GACxC,OAAO,CAAC,eAAe,CAAC,CAS1B"}

package/dist/backend/demo/reset.js

@@ -0,0 +1,13 @@
+import { AdminRole } from '../entities/admin-role.entity.js';
+import { DEMO_ADMIN_ROLE_CODES } from './rows.js';
+export async function resetDemo(context) {
+    // command-coverage-ignore: the withdrawal half of the demo data above. Same
+    // entry point, same `mustBeNonProduction()` guard, same absence of an
+    // operator to attribute the write to (contract §2.7).
+    const em = context.ctx.cradle().emFactory();
+    const removed = await em.nativeDelete(AdminRole, {
+        code: { $in: [...DEMO_ADMIN_ROLE_CODES] },
+    });
+    return { removed: [{ entity: 'AdminRole', count: removed }] };
+}
+//# sourceMappingURL=reset.js.map

package/dist/backend/demo/reset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reset.js","sourceRoot":"","sources":["../../../src/backend/demo/reset.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAMlD,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,OAAyC;IAEzC,4EAA4E;IAC5E,sEAAsE;IACtE,sDAAsD;IACtD,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAwB,CAAC,SAAS,EAAE,CAAC;IAClE,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,YAAY,CAAC,SAAS,EAAE;QAC/C,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,GAAG,qBAAqB,CAAC,EAAE;KAC1C,CAAC,CAAC;IACH,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;AAChE,CAAC"}

package/dist/backend/demo/rows.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The admin roles this module's demo data creates (feature 113, T222).
+ *
+ * One place holding the data, imported by both bodies: `seed.ts` creates these
+ * roles and `reset.ts` withdraws exactly them, by the `code` they are keyed on
+ * (contract §2.5). A predicate over the table would take `blog_manager` and
+ * `content_manager` with it — two roles `blog` and `cms` seed from their own
+ * boot hooks, which share this table with the demo and are not the demo's.
+ *
+ * The values are the host seed's verbatim, moved rather than rewritten. The
+ * frozen copy the parity comparison read them against is deleted with that
+ * comparison (T226); what holds them now is
+ * `test/integration/demo/demo-shop.test.ts`' recorded delta.
+ *
+ * ## Why the sales representative's permission list is here and is exported
+ *
+ * It was `backend/src/seeds/seeded-role-permissions.ts`, and it is a constant
+ * rather than eight lines inside a seed for a reason that survives the move
+ * unchanged: `platform_admin` and the bootstrap admin hold `['*']`, which
+ * short-circuits in `PermissionService.hasPermission` before any code is
+ * compared, and the two content roles hold their own module's codes. So a change
+ * to what a catalogue code grants is felt by exactly this list, and the six
+ * `permission-authority` contract tests that assert what the seeded sales
+ * representative may reach have to read **the list the seed
+ * actually writes** rather than a copy of it — a copy agrees with the seed on
+ * the day it is written and never again.
+ *
+ * Which list that is moved with this batch. The composed path writes this one,
+ * so it is re-exported from `../index.js` — the package's own `./backend`
+ * subpath — and the six tests name it there. The frozen reference under
+ * `backend/src/seeds/` keeps a literal copy of its own on purpose: the two sides
+ * of the parity comparison have to be different code, or the comparison cannot
+ * see a change to either.
+ */
+/** One demo admin role, in `AdminRole`'s own field names. */
+export interface DemoAdminRoleRow {
+    readonly code: string;
+    readonly name: string;
+    readonly permissions: readonly string[];
+}
+/**
+ * What the seeded `sales_representative` role may reach.
+ *
+ * Assignment-scoped visibility (feature 008): the quickstart signs in as this
+ * role to exercise it.
+ */
+export declare const SALES_REPRESENTATIVE_PERMISSIONS: readonly string[];
+/**
+ * The two roles the demo shop has.
+ *
+ * `['*']` on `platform_admin` is the wildcard `PermissionService` answers before
+ * it compares a code, which is what makes the demo administrator able to open
+ * every screen a fresh install ships.
+ *
+ * **Which account holds which role is not here.** An `admin_users` row carrying
+ * an `admin_roles` id is two modules' rows in one statement, so the assignment
+ * is a composition step (contract §5.1) and lives in
+ * `backend/src/seeds/demo-composition.ts`. This body creates the roles that step
+ * assigns.
+ */
+export declare const DEMO_ADMIN_ROLES: readonly DemoAdminRoleRow[];
+/** The codes `reset` withdraws — derived from the rows, never a second list. */
+export declare const DEMO_ADMIN_ROLE_CODES: readonly string[];
+//# sourceMappingURL=rows.d.ts.map

package/dist/backend/demo/rows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rows.d.ts","sourceRoot":"","sources":["../../../src/backend/demo/rows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,6DAA6D;AAC7D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,EAAE,SAAS,MAAM,EAS7D,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,gBAAgB,EAOvD,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAA4C,CAAC"}

package/dist/backend/demo/rows.js

@@ -0,0 +1,74 @@
+/**
+ * The admin roles this module's demo data creates (feature 113, T222).
+ *
+ * One place holding the data, imported by both bodies: `seed.ts` creates these
+ * roles and `reset.ts` withdraws exactly them, by the `code` they are keyed on
+ * (contract §2.5). A predicate over the table would take `blog_manager` and
+ * `content_manager` with it — two roles `blog` and `cms` seed from their own
+ * boot hooks, which share this table with the demo and are not the demo's.
+ *
+ * The values are the host seed's verbatim, moved rather than rewritten. The
+ * frozen copy the parity comparison read them against is deleted with that
+ * comparison (T226); what holds them now is
+ * `test/integration/demo/demo-shop.test.ts`' recorded delta.
+ *
+ * ## Why the sales representative's permission list is here and is exported
+ *
+ * It was `backend/src/seeds/seeded-role-permissions.ts`, and it is a constant
+ * rather than eight lines inside a seed for a reason that survives the move
+ * unchanged: `platform_admin` and the bootstrap admin hold `['*']`, which
+ * short-circuits in `PermissionService.hasPermission` before any code is
+ * compared, and the two content roles hold their own module's codes. So a change
+ * to what a catalogue code grants is felt by exactly this list, and the six
+ * `permission-authority` contract tests that assert what the seeded sales
+ * representative may reach have to read **the list the seed
+ * actually writes** rather than a copy of it — a copy agrees with the seed on
+ * the day it is written and never again.
+ *
+ * Which list that is moved with this batch. The composed path writes this one,
+ * so it is re-exported from `../index.js` — the package's own `./backend`
+ * subpath — and the six tests name it there. The frozen reference under
+ * `backend/src/seeds/` keeps a literal copy of its own on purpose: the two sides
+ * of the parity comparison have to be different code, or the comparison cannot
+ * see a change to either.
+ */
+/**
+ * What the seeded `sales_representative` role may reach.
+ *
+ * Assignment-scoped visibility (feature 008): the quickstart signs in as this
+ * role to exercise it.
+ */
+export const SALES_REPRESENTATIVE_PERMISSIONS = [
+    'rfqs:handle',
+    'organizations:read.assigned',
+    'catalog:read',
+    // D-173 — the RFQ create screen prefills the agreed unit price from
+    // `GET /admin/products/:id/resolved-price`, which is `price_lists`' own
+    // endpoint and is gated on `price_lists:read` rather than on
+    // `rfqs:handle`. Without this code the prefill answers 403.
+    'price_lists:read',
+];
+/**
+ * The two roles the demo shop has.
+ *
+ * `['*']` on `platform_admin` is the wildcard `PermissionService` answers before
+ * it compares a code, which is what makes the demo administrator able to open
+ * every screen a fresh install ships.
+ *
+ * **Which account holds which role is not here.** An `admin_users` row carrying
+ * an `admin_roles` id is two modules' rows in one statement, so the assignment
+ * is a composition step (contract §5.1) and lives in
+ * `backend/src/seeds/demo-composition.ts`. This body creates the roles that step
+ * assigns.
+ */
+export const DEMO_ADMIN_ROLES = [
+    { code: 'platform_admin', name: 'Platform Admin', permissions: ['*'] },
+    {
+        code: 'sales_representative',
+        name: 'Sales representative',
+        permissions: SALES_REPRESENTATIVE_PERMISSIONS,
+    },
+];
+/** The codes `reset` withdraws — derived from the rows, never a second list. */
+export const DEMO_ADMIN_ROLE_CODES = DEMO_ADMIN_ROLES.map((row) => row.code);
+//# sourceMappingURL=rows.js.map

package/dist/backend/demo/rows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rows.js","sourceRoot":"","sources":["../../../src/backend/demo/rows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AASH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAsB;IACjE,aAAa;IACb,6BAA6B;IAC7B,cAAc;IACd,oEAAoE;IACpE,wEAAwE;IACxE,6DAA6D;IAC7D,4DAA4D;IAC5D,kBAAkB;CACnB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAgC;IAC3D,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,gBAAgB,EAAE,WAAW,EAAE,CAAC,GAAG,CAAC,EAAE;IACtE;QACE,IAAI,EAAE,sBAAsB;QAC5B,IAAI,EAAE,sBAAsB;QAC5B,WAAW,EAAE,gCAAgC;KAC9C;CACF,CAAC;AAEF,gFAAgF;AAChF,MAAM,CAAC,MAAM,qBAAqB,GAAsB,gBAAgB,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC"}

package/dist/backend/demo/seed.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `admin_roles`' demo data (feature 113, T222 — contract §2).
+ *
+ * The two roles the demo shop signs in with, in the module that owns the table.
+ * It writes `admin_roles` and nothing else (§2.1), reads no other module's table
+ * and resolves no port (§2.2), so declaring it added no entry to this module's
+ * manifest `dependencies` (§2.3).
+ *
+ * **Who holds which role is not this body's.** An `admin_users` row carrying an
+ * `admin_roles` id is two modules' rows in one statement — a composition step
+ * (§5.1), in `backend/src/seeds/demo-composition.ts`, which runs after every
+ * module's `seed` and so finds both sides of the assignment already there.
+ *
+ * Idempotent by an existence probe on the natural key (§2.4): a second run
+ * creates nothing and reports the same count.
+ */
+import type { DemoSeedResult, ModuleDemoContext } from '@endora-commerce/contracts';
+import type { ModuleContext } from '@endora-commerce/platform/kernel';
+export declare function seedDemo(context: ModuleDemoContext<ModuleContext>): Promise<DemoSeedResult>;
+//# sourceMappingURL=seed.d.ts.map

package/dist/backend/demo/seed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed.d.ts","sourceRoot":"","sources":["../../../src/backend/demo/seed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAUtE,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,iBAAiB,CAAC,aAAa,CAAC,GACxC,OAAO,CAAC,cAAc,CAAC,CA0BzB"}

package/dist/backend/demo/seed.js

@@ -0,0 +1,29 @@
+import { AdminRole } from '../entities/admin-role.entity.js';
+import { DEMO_ADMIN_ROLES } from './rows.js';
+export async function seedDemo(context) {
+    // command-coverage-ignore: demo data, reached only by `endora demo seed`,
+    // whose entry point calls `mustBeNonProduction()` as its first statement and
+    // outside every `try` (contract §2.7, §3.3). The guard is the enforcement:
+    // this write has no operator, no tenant and no audit reader, and the command
+    // refuses to run against a production database at all.
+    const em = context.ctx.cradle().emFactory();
+    for (const row of DEMO_ADMIN_ROLES) {
+        const existing = await em.findOne(AdminRole, { code: row.code });
+        // Present already: left exactly as it is. An operator may have narrowed
+        // what the demo sales representative may reach, and overwriting it here
+        // would be this body deciding its own literal outranks their change —
+        // which is `reset`'s question, not `seed`'s.
+        if (existing)
+            continue;
+        em.create(AdminRole, {
+            code: row.code,
+            name: row.name,
+            permissions: [...row.permissions],
+        });
+    }
+    await em.flush();
+    // What the demo *holds* after the run, not what this call inserted: seeding
+    // twice must report the same counts (`DemoEntityCount`).
+    return { created: [{ entity: 'AdminRole', count: DEMO_ADMIN_ROLES.length }] };
+}
+//# sourceMappingURL=seed.js.map

package/dist/backend/demo/seed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed.js","sourceRoot":"","sources":["../../../src/backend/demo/seed.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAO7C,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,OAAyC;IAEzC,0EAA0E;IAC1E,6EAA6E;IAC7E,2EAA2E;IAC3E,6EAA6E;IAC7E,uDAAuD;IACvD,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAwB,CAAC,SAAS,EAAE,CAAC;IAElE,KAAK,MAAM,GAAG,IAAI,gBAAgB,EAAE,CAAC;QACnC,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;QACjE,wEAAwE;QACxE,wEAAwE;QACxE,sEAAsE;QACtE,6CAA6C;QAC7C,IAAI,QAAQ;YAAE,SAAS;QACvB,EAAE,CAAC,MAAM,CAAC,SAAS,EAAE;YACnB,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,WAAW,EAAE,CAAC,GAAG,GAAG,CAAC,WAAW,CAAC;SAClC,CAAC,CAAC;IACL,CAAC;IACD,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;IAEjB,4EAA4E;IAC5E,yDAAyD;IACzD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,gBAAgB,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;AAChF,CAAC"}

package/dist/backend/entities/admin-role.entity.d.ts

@@ -0,0 +1,20 @@
+import { OptionalProps } from '@mikro-orm/core';
+/**
+ * AdminRole — a named permission bundle assigned to AdminUsers. Permissions
+ * are screaming-snake `module:action` strings (e.g. `catalog:write`,
+ * `orders:read`, `customers:impersonate`). Stored as JSONB array.
+ *
+ * `requiresTwoFactor` flips the requireAdmin pre-handler into a strict mode
+ * (T188 hook) — accounts mapped to such a Role MUST have 2FA confirmed.
+ */
+export declare class AdminRole {
+    [OptionalProps]?: 'id' | 'createdAt' | 'updatedAt' | 'requiresTwoFactor' | 'permissions';
+    id: string;
+    code: string;
+    name: string;
+    permissions: string[];
+    requiresTwoFactor: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+//# sourceMappingURL=admin-role.entity.d.ts.map

package/dist/backend/entities/admin-role.entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-role.entity.d.ts","sourceRoot":"","sources":["../../../src/backend/entities/admin-role.entity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,aAAa,EAAgC,MAAM,iBAAiB,CAAC;AAItF;;;;;;;GAOG;AACH,qBAEa,SAAS;IACpB,CAAC,aAAa,CAAC,CAAC,EACZ,IAAI,GACJ,WAAW,GACX,WAAW,GACX,mBAAmB,GACnB,aAAa,CAAC;IAGlB,EAAE,EAAE,MAAM,CAAgB;IAI1B,IAAI,EAAG,MAAM,CAAC;IAGd,IAAI,EAAG,MAAM,CAAC;IAGd,WAAW,EAAE,MAAM,EAAE,CAAM;IAG3B,iBAAiB,EAAE,OAAO,CAAS;IAGnC,SAAS,EAAE,IAAI,CAAc;IAG7B,SAAS,EAAE,IAAI,CAAc;CAC9B"}

package/dist/backend/entities/admin-role.entity.js

@@ -0,0 +1,65 @@
+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);
+};
+import { Entity, OptionalProps, PrimaryKey, Property, Unique } from '@mikro-orm/core';
+import { GlobalEntity } from '@endora-commerce/platform/tenancy';
+import { randomUUID } from 'crypto';
+/**
+ * AdminRole — a named permission bundle assigned to AdminUsers. Permissions
+ * are screaming-snake `module:action` strings (e.g. `catalog:write`,
+ * `orders:read`, `customers:impersonate`). Stored as JSONB array.
+ *
+ * `requiresTwoFactor` flips the requireAdmin pre-handler into a strict mode
+ * (T188 hook) — accounts mapped to such a Role MUST have 2FA confirmed.
+ */
+let AdminRole = class AdminRole {
+    [OptionalProps];
+    id = randomUUID();
+    code;
+    name;
+    permissions = [];
+    requiresTwoFactor = false;
+    createdAt = new Date();
+    updatedAt = new Date();
+};
+__decorate([
+    PrimaryKey({ type: 'uuid' }),
+    __metadata("design:type", String)
+], AdminRole.prototype, "id", void 0);
+__decorate([
+    Property({ type: 'string', length: 64 }),
+    Unique(),
+    __metadata("design:type", String)
+], AdminRole.prototype, "code", void 0);
+__decorate([
+    Property({ type: 'string', length: 160 }),
+    __metadata("design:type", String)
+], AdminRole.prototype, "name", void 0);
+__decorate([
+    Property({ type: 'json' }),
+    __metadata("design:type", Array)
+], AdminRole.prototype, "permissions", void 0);
+__decorate([
+    Property({ type: 'boolean' }),
+    __metadata("design:type", Boolean)
+], AdminRole.prototype, "requiresTwoFactor", void 0);
+__decorate([
+    Property({ type: 'datetime', onCreate: () => new Date() }),
+    __metadata("design:type", Date)
+], AdminRole.prototype, "createdAt", void 0);
+__decorate([
+    Property({ type: 'datetime', onUpdate: () => new Date() }),
+    __metadata("design:type", Date)
+], AdminRole.prototype, "updatedAt", void 0);
+AdminRole = __decorate([
+    GlobalEntity(),
+    Entity({ tableName: 'admin_roles' })
+], AdminRole);
+export { AdminRole };
+//# sourceMappingURL=admin-role.entity.js.map

package/dist/backend/entities/admin-role.entity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-role.entity.js","sourceRoot":"","sources":["../../../src/backend/entities/admin-role.entity.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACtF,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEpC;;;;;;;GAOG;AAGI,IAAM,SAAS,GAAf,MAAM,SAAS;IACpB,CAAC,aAAa,CAAC,CAKG;IAGlB,EAAE,GAAW,UAAU,EAAE,CAAC;IAI1B,IAAI,CAAU;IAGd,IAAI,CAAU;IAGd,WAAW,GAAa,EAAE,CAAC;IAG3B,iBAAiB,GAAY,KAAK,CAAC;IAGnC,SAAS,GAAS,IAAI,IAAI,EAAE,CAAC;IAG7B,SAAS,GAAS,IAAI,IAAI,EAAE,CAAC;CAC9B,CAAA;AApBC;IADC,UAAU,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;;qCACH;AAI1B;IAFC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IACxC,MAAM,EAAE;;uCACK;AAGd;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;;uCAC5B;AAGd;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;;8CACA;AAG3B;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;;oDACK;AAGnC;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;8BAChD,IAAI;4CAAc;AAG7B;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;8BAChD,IAAI;4CAAc;AA5BlB,SAAS;IAFrB,YAAY,EAAE;IACd,MAAM,CAAC,EAAE,SAAS,EAAE,aAAa,EAAE,CAAC;GACxB,SAAS,CA6BrB"}

package/dist/backend/index.d.ts

@@ -0,0 +1,96 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { AuditPort } from '@endora-commerce/platform/kernel';
+import type { ModuleManifest, SystemRoleCodePort } from '@endora-commerce/contracts';
+import type { ModuleContext } from '@endora-commerce/platform/kernel';
+import { AdminRoleService } from './services/admin-role-service.js';
+import { PermissionCatalogueService } from './services/permission-catalogue.service.js';
+import { AdminRole } from './entities/admin-role.entity.js';
+/**
+ * `admin_roles` — the permission model behind every admin guard (feature 072,
+ * wave 1).
+ *
+ * It owns no routes. Its admin surface is registered by `admin_users`, which is
+ * shape D's usual shape seen from the other side: the module that owns the
+ * behaviour and the module that owns the URL are different, and only the second
+ * one has a `plugin.ts`. Converting it needs no route seam, because there is
+ * nothing to gate here — what moves is which composition root constructs the
+ * three services, and the answer is now "neither".
+ *
+ * `permissionService` is the reason this module goes first in wave 1. `auth`
+ * resolves it to build `requireAdmin`, and until now both composition roots
+ * registered it as a **host value** on `admin_roles`' behalf — a declared edge
+ * (D-32) standing in for a registration. That entry leaves
+ * `HOST_REGISTERED_PORTS` with this commit.
+ *
+ * The catalogue takes the **resolved** registry — core manifests plus the
+ * active deployment's overlay modules — which is a composition-root input, not
+ * something this module can see. It stays a host value for that reason, and the
+ * reason is durable rather than temporary: which modules a deployment ships is
+ * exactly the kind of thing a module must not decide for itself.
+ */
+export interface AdminRolesCradle {
+    readonly emFactory: () => EntityManager;
+    readonly auditLogService: AuditPort;
+    /**
+     * Core manifests + this deployment's overlay modules (feature 057).
+     *
+     * Typed by what this module reads rather than by `_lifecycle`'s
+     * `RegisteredManifestEntry` (feature 075, Phase C). The entries the root
+     * contributes carry a `filePath` and the install hooks as well, and none of
+     * that is any of this module's business: the catalogue walks
+     * `manifest.permissions` and nothing else, and it already declared that
+     * shape for itself.
+     */
+    readonly resolvedModuleRegistry: ReadonlyArray<{
+        manifest: ModuleManifest;
+    }>;
+    readonly permissionCatalogueService: PermissionCatalogueService;
+    readonly adminRoleService: AdminRoleService;
+    /** Feature 075, Phase P — the deletion-protection contribution seam. */
+    readonly systemRoleCodePort: SystemRoleCodePort;
+}
+export declare function registerModule(ctx: ModuleContext): void;
+/**
+ * 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 declare const entities: (typeof 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.d.ts.map

package/dist/backend/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/backend/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,KAAK,EAGV,cAAc,EAGd,kBAAkB,EACnB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAGtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEpE,OAAO,EAAE,0BAA0B,EAAE,MAAM,4CAA4C,CAAC;AAExF,OAAO,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,aAAa,CAAC;IACxC,QAAQ,CAAC,eAAe,EAAE,SAAS,CAAC;IACpC;;;;;;;;;OASG;IACH,QAAQ,CAAC,sBAAsB,EAAE,aAAa,CAAC;QAAE,QAAQ,EAAE,cAAc,CAAA;KAAE,CAAC,CAAC;IAC7E,QAAQ,CAAC,0BAA0B,EAAE,0BAA0B,CAAC;IAChE,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAC5C,wEAAwE;IACxE,QAAQ,CAAC,kBAAkB,EAAE,kBAAkB,CAAC;CACjD;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CA2FvD;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ,sBAEpB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,gCAAgC,EAAE,MAAM,gBAAgB,CAAC;AAElE,OAAO,EAAE,0BAA0B,EAAE,6BAA6B,EAAE,MAAM,4CAA4C,CAAC;AACvH,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,2BAA2B,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC"}