@endora-commerce/mod-admin-roles 0.100.0

package/dist/backend/services/admin-role-ports.js

@@ -0,0 +1,72 @@
+import { AdminRole } from '../entities/admin-role.entity.js';
+import { listSystemRoleCodes, registerSystemRoleCode, } from './admin-role-service.js';
+/**
+ * The published face of `admin_roles` (feature 075, Phase P).
+ *
+ * Fourteen inbound sites: `admin_users` reads a role beside its user and
+ * enforces `requiresTwoFactor` at login, `admin_actions` filters the command
+ * palette by a user's permissions, `blog` protects the role it seeds, and the
+ * dev seed creates one.
+ *
+ * `findByCode` is the method with no direct predecessor. `admin_users`'
+ * service and the dev seed both look a role up by code with
+ * `em.findOne(AdminRole, { code })`, which is the read it replaces.
+ */
+export class AdminRoleReadService {
+    emFactory;
+    constructor(emFactory) {
+        this.emFactory = emFactory;
+    }
+    async findByCode(code) {
+        const role = await this.emFactory().findOne(AdminRole, { code });
+        return role ? toAdminRoleRecord(role) : null;
+    }
+}
+/**
+ * The full role port, adapting `AdminRoleService` and adding the by-code
+ * lookup. The service arrives as a getter so the adapter resolves it per call
+ * rather than capturing it.
+ */
+export function createAdminRolePort(emFactory, getService) {
+    const read = new AdminRoleReadService(emFactory);
+    return {
+        async list() {
+            return (await getService().list()).map(toAdminRoleRecord);
+        },
+        async getById(id) {
+            return toAdminRoleRecord(await getService().getById(id));
+        },
+        findByCode: (code) => read.findByCode(code),
+        async upsertByCode(input) {
+            return toAdminRoleRecord(await getService().upsertByCode(input));
+        },
+        remove: (id) => getService().remove(id),
+    };
+}
+/**
+ * The contribution seam for deletion-protected role codes.
+ *
+ * Deliberately a plain object over the module-level set rather than anything
+ * gated: `blog` registers its seeded code from a boot hook, and a gate would
+ * both throw during composition and — worse — let an operator delete a
+ * protected role by switching its owner off for a moment. See the port's
+ * contract for the full reasoning.
+ */
+export function createSystemRoleCodePort() {
+    return {
+        register: (code) => registerSystemRoleCode(code),
+        list: () => listSystemRoleCodes(),
+    };
+}
+export function toAdminRoleRecord(role) {
+    return {
+        id: role.id,
+        code: role.code,
+        name: role.name,
+        permissions: role.permissions ?? [],
+        requiresTwoFactor: role.requiresTwoFactor,
+        createdAt: role.createdAt,
+        updatedAt: role.updatedAt,
+    };
+}
+//# sourceMappingURL=admin-role-ports.js.map

package/dist/backend/services/admin-role-ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-role-ports.js","sourceRoot":"","sources":["../../../src/backend/services/admin-role-ports.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAC7D,OAAO,EAEL,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,oBAAoB;IACF;IAA7B,YAA6B,SAA8B;QAA9B,cAAS,GAAT,SAAS,CAAqB;IAAG,CAAC;IAE/D,KAAK,CAAC,UAAU,CAAC,IAAY;QAC3B,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;QACjE,OAAO,IAAI,CAAC,CAAC,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/C,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAA8B,EAC9B,UAAkC;IAElC,MAAM,IAAI,GAAG,IAAI,oBAAoB,CAAC,SAAS,CAAC,CAAC;IACjD,OAAO;QACL,KAAK,CAAC,IAAI;YACR,OAAO,CAAC,MAAM,UAAU,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;QAC5D,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,EAAE;YACd,OAAO,iBAAiB,CAAC,MAAM,UAAU,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;QAC3D,CAAC;QACD,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAC3C,KAAK,CAAC,YAAY,CAAC,KAAK;YACtB,OAAO,iBAAiB,CAAC,MAAM,UAAU,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;QACnE,CAAC;QACD,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,UAAU,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;KACxC,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB;IACtC,OAAO;QACL,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,sBAAsB,CAAC,IAAI,CAAC;QAChD,IAAI,EAAE,GAAG,EAAE,CAAC,mBAAmB,EAAE;KAClC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAe;IAC/C,OAAO;QACL,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,EAAE;QACnC,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;QACzC,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,SAAS,EAAE,IAAI,CAAC,SAAS;KAC1B,CAAC;AACJ,CAAC"}

package/dist/backend/services/admin-role-service.d.ts

@@ -0,0 +1,77 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import { type AdminUserReadPort } from '@endora-commerce/contracts';
+import { HttpError } from '@endora-commerce/platform/http';
+import type { AuditPort } from '@endora-commerce/platform/kernel';
+import { AdminRole } from '../entities/admin-role.entity.js';
+import type { PermissionCatalogueService } from './permission-catalogue.service.js';
+export interface UpsertAdminRoleInput {
+    code: string;
+    name: string;
+    permissions: string[];
+    requiresTwoFactor?: boolean;
+}
+/**
+ * Module-level registration for seeded role codes that should be
+ * deletion-protected. Idempotent. Exposed as a top-level function so
+ * modules can call it from their plugin without holding an
+ * AdminRoleService instance.
+ */
+export declare function registerSystemRoleCode(code: string): void;
+/**
+ * The protected codes, in registration order. Published through
+ * `SystemRoleCodePort` (feature 075, Phase P) so a contributor can read back
+ * what the platform is protecting without reaching into this file.
+ */
+export declare function listSystemRoleCodes(): readonly string[];
+/** Test helper — clears the protected-codes registry between suites. */
+export declare function _resetSystemRoleCodesForTests(): void;
+/**
+ * The refusal a role deletion earns from its assignees, or `null` when it has
+ * none (issue #168).
+ *
+ * Exported and pure so the sentence's `{placeholders}` can be checked against
+ * the `details` a real refusal carries — the agreement issue #161 found nothing
+ * was checking, one code family over. `check:error-translations` sees that a
+ * code *has* a sentence; only a test that renders one can see that the sentence
+ * has anything to fill it.
+ *
+ * The token in `details.code` chooses the sentence, and the count fills it.
+ * Both populations refuse, and they are separated because the remedy differs:
+ * reassign a live admin; restore-and-reassign or purge a deleted one.
+ */
+export declare function roleInUseRefusal(live: number, deleted: number): HttpError | null;
+/**
+ * The refusal a seeded role's deletion earns, with the role's own code on it.
+ *
+ * Exported and pure for the reason {@link roleInUseRefusal} is: the sentence
+ * that replaces this message carries a `{role}` placeholder, and only a test
+ * that renders a **real** refusal against the bundle can see that the
+ * placeholder has something to fill it (issue #161, and !1181's finding that a
+ * translated sentence with no placeholder loses an interpolated value silently).
+ *
+ * `details.role`, never `details.code`: the latter is the refusal token the
+ * envelope keys `errors.<CODE>.<token>` on, so putting a role code there would
+ * send it looking for a sentence named after the role.
+ */
+export declare function protectedRoleRefusal(code: string): HttpError;
+export declare class AdminRoleService {
+    #private;
+    private readonly emFactory;
+    private readonly permissionCatalogue;
+    /** `adminUserReadPort` — who still holds a role (feature 075, Phase C). */
+    private readonly adminUsers;
+    private readonly auditLog?;
+    constructor(emFactory: () => EntityManager, permissionCatalogue: PermissionCatalogueService, 
+    /** `adminUserReadPort` — who still holds a role (feature 075, Phase C). */
+    adminUsers: AdminUserReadPort, auditLog?: AuditPort | undefined);
+    /**
+     * Register a role code as system-protected. Called by modules at
+     * plugin startup for their seeded roles. Idempotent.
+     */
+    registerSystemRoleCode(code: string): void;
+    list(): Promise<AdminRole[]>;
+    getById(id: string): Promise<AdminRole>;
+    upsertByCode(input: UpsertAdminRoleInput): Promise<AdminRole>;
+    remove(id: string): Promise<void>;
+}
+//# sourceMappingURL=admin-role-service.d.ts.map

package/dist/backend/services/admin-role-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-role-service.d.ts","sourceRoot":"","sources":["../../../src/backend/services/admin-role-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,EAAe,KAAK,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACjF,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAE3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAC7D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AA0BpF,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAWD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,SAAS,MAAM,EAAE,CAEvD;AAED,wEAAwE;AACxE,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAmBhF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAO5D;AAED,qBAAa,gBAAgB;;IAEzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IACpC,2EAA2E;IAC3E,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBAJT,SAAS,EAAE,MAAM,aAAa,EAC9B,mBAAmB,EAAE,0BAA0B;IAChE,2EAA2E;IAC1D,UAAU,EAAE,iBAAiB,EAC7B,QAAQ,CAAC,EAAE,SAAS,YAAA;IASvC;;;OAGG;IACH,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIpC,IAAI,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAK5B,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAOvC,YAAY,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,SAAS,CAAC;IAwC7D,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAoDxC"}

package/dist/backend/services/admin-role-service.js

@@ -0,0 +1,219 @@
+import { UniqueConstraintViolationException } from '@mikro-orm/core';
+import { ERROR_CODES } from '@endora-commerce/contracts';
+import { HttpError } from '@endora-commerce/platform/http';
+import { recordAuditFromContext } from '@endora-commerce/platform/commands';
+import { AdminRole } from '../entities/admin-role.entity.js';
+/**
+ * AdminRoleService (T193). CRUD over AdminRole rows. Invariants:
+ *
+ *   - permissions referenced in `permissions` MUST be in the merged assignable
+ *     catalogue (`PermissionCatalogueService`), OR be the wildcard `*` which
+ *     grants full access. When `*` is present the permission set is normalised
+ *     to exactly `['*']` (a role is either "full access" or an explicit list).
+ *   - the bootstrap `platform_admin` role is locked to `['*']`: it always has
+ *     full access and its permission set cannot be downgraded from the UI.
+ *   - a Role with assigned AdminUsers cannot be deleted (409); reassign or
+ *     deactivate the users first. A **soft-deleted** admin still counts
+ *     (issue #168): restoring the account restores its role, so the assignment
+ *     survives the deletion and the role is still in use.
+ */
+/** Wildcard permission — grants access to every gated admin route. */
+const WILDCARD = '*';
+/**
+ * The bootstrap super-admin role. Its permission set is forced to the wildcard
+ * on every upsert so it can never be locked out of the panel.
+ */
+const PLATFORM_ADMIN_CODE = 'platform_admin';
+/**
+ * Codes of seeded roles that other modules register as
+ * deletion-protected. Modules call `registerSystemRoleCode(...)` from
+ * their plugin to add their seeded codes to this set; once registered,
+ * `remove` refuses to delete a role whose `code` is in the set with a
+ * 409 ADMIN_ROLE_PROTECTED envelope (feature 016 / FR-025).
+ */
+const SYSTEM_ROLE_CODES = new Set();
+/**
+ * Module-level registration for seeded role codes that should be
+ * deletion-protected. Idempotent. Exposed as a top-level function so
+ * modules can call it from their plugin without holding an
+ * AdminRoleService instance.
+ */
+export function registerSystemRoleCode(code) {
+    SYSTEM_ROLE_CODES.add(code);
+}
+/**
+ * The protected codes, in registration order. Published through
+ * `SystemRoleCodePort` (feature 075, Phase P) so a contributor can read back
+ * what the platform is protecting without reaching into this file.
+ */
+export function listSystemRoleCodes() {
+    return [...SYSTEM_ROLE_CODES];
+}
+/** Test helper — clears the protected-codes registry between suites. */
+export function _resetSystemRoleCodesForTests() {
+    SYSTEM_ROLE_CODES.clear();
+}
+/**
+ * The refusal a role deletion earns from its assignees, or `null` when it has
+ * none (issue #168).
+ *
+ * Exported and pure so the sentence's `{placeholders}` can be checked against
+ * the `details` a real refusal carries — the agreement issue #161 found nothing
+ * was checking, one code family over. `check:error-translations` sees that a
+ * code *has* a sentence; only a test that renders one can see that the sentence
+ * has anything to fill it.
+ *
+ * The token in `details.code` chooses the sentence, and the count fills it.
+ * Both populations refuse, and they are separated because the remedy differs:
+ * reassign a live admin; restore-and-reassign or purge a deleted one.
+ */
+export function roleInUseRefusal(live, deleted) {
+    if (live > 0) {
+        return new HttpError(409, ERROR_CODES.ADMIN_ROLE_IN_USE, `Cannot delete role: ${live} admin user(s) still assigned.`, { code: 'assigned', assigned: live });
+    }
+    if (deleted > 0) {
+        return new HttpError(409, ERROR_CODES.ADMIN_ROLE_IN_USE, `Cannot delete role: ${deleted} deleted admin account(s) still hold it, ` +
+            `and restoring one restores the assignment.`, { code: 'assigned_to_deleted', deleted });
+    }
+    return null;
+}
+/**
+ * The refusal a seeded role's deletion earns, with the role's own code on it.
+ *
+ * Exported and pure for the reason {@link roleInUseRefusal} is: the sentence
+ * that replaces this message carries a `{role}` placeholder, and only a test
+ * that renders a **real** refusal against the bundle can see that the
+ * placeholder has something to fill it (issue #161, and !1181's finding that a
+ * translated sentence with no placeholder loses an interpolated value silently).
+ *
+ * `details.role`, never `details.code`: the latter is the refusal token the
+ * envelope keys `errors.<CODE>.<token>` on, so putting a role code there would
+ * send it looking for a sentence named after the role.
+ */
+export function protectedRoleRefusal(code) {
+    return new HttpError(409, ERROR_CODES.ADMIN_ROLE_PROTECTED, `Cannot delete the system-protected role "${code}". Modules' seeded roles are immutable.`, { role: code });
+}
+export class AdminRoleService {
+    emFactory;
+    permissionCatalogue;
+    adminUsers;
+    auditLog;
+    constructor(emFactory, permissionCatalogue, 
+    /** `adminUserReadPort` — who still holds a role (feature 075, Phase C). */
+    adminUsers, auditLog) {
+        this.emFactory = emFactory;
+        this.permissionCatalogue = permissionCatalogue;
+        this.adminUsers = adminUsers;
+        this.auditLog = auditLog;
+    }
+    #audit(em, action, objectId, stateBefore, stateAfter) {
+        if (this.auditLog) {
+            recordAuditFromContext(this.auditLog, em, { action, objectType: 'admin_role', objectId, stateBefore, stateAfter });
+        }
+    }
+    /**
+     * Register a role code as system-protected. Called by modules at
+     * plugin startup for their seeded roles. Idempotent.
+     */
+    registerSystemRoleCode(code) {
+        SYSTEM_ROLE_CODES.add(code);
+    }
+    async list() {
+        const em = this.emFactory();
+        return em.find(AdminRole, {}, { orderBy: { name: 'asc' } });
+    }
+    async getById(id) {
+        const em = this.emFactory();
+        const row = await em.findOne(AdminRole, { id });
+        if (!row)
+            throw new HttpError(404, ERROR_CODES.NOT_FOUND, 'Admin role not found.');
+        return row;
+    }
+    async upsertByCode(input) {
+        // The platform_admin role is always full-access; ignore any narrower
+        // payload so the bootstrap super-admin can never be downgraded. Every
+        // other role may opt into the wildcard or carry an explicit list.
+        const permissions = input.code === PLATFORM_ADMIN_CODE
+            ? [WILDCARD]
+            : this.#normalizePermissions(input.permissions);
+        const em = this.emFactory();
+        let role = await em.findOne(AdminRole, { code: input.code });
+        if (role) {
+            role.name = input.name;
+            role.permissions = permissions;
+            role.requiresTwoFactor = input.requiresTwoFactor ?? role.requiresTwoFactor;
+            this.#audit(em, 'admin_role.upsert', role.id, null, { code: role.code, name: role.name });
+            await em.flush();
+            return role;
+        }
+        role = em.create(AdminRole, {
+            code: input.code,
+            name: input.name,
+            permissions,
+            requiresTwoFactor: input.requiresTwoFactor ?? false,
+        });
+        this.#audit(em, 'admin_role.upsert', role.id, null, { code: role.code, name: role.name });
+        try {
+            await em.persistAndFlush(role);
+        }
+        catch (err) {
+            if (err instanceof UniqueConstraintViolationException) {
+                throw new HttpError(409, ERROR_CODES.ADMIN_ROLE_CODE_TAKEN, 'A role with that code already exists.');
+            }
+            throw err;
+        }
+        return role;
+    }
+    async remove(id) {
+        const em = this.emFactory();
+        const role = await em.findOne(AdminRole, { id });
+        if (!role)
+            throw new HttpError(404, ERROR_CODES.NOT_FOUND, 'Admin role not found.');
+        if (SYSTEM_ROLE_CODES.has(role.code))
+            throw protectedRoleRefusal(role.code);
+        // Every assignee a restore returns, live or binned (issue #168).
+        //
+        // A soft delete does not release the assignment: the row keeps its
+        // `admin_role_id`, and restoring the account restores the role with it. So
+        // counting live assignees only made the guard pass on a role that was still
+        // held — and the delete it let through hit `admin_users_admin_role_fk`
+        // (`on delete restrict`) and answered 500. The operator was told the role
+        // was unused, confirmed, and got a server error.
+        //
+        // The two populations are still counted apart, because the remedy differs:
+        // reassign a live admin, purge or restore-and-reassign a deleted one. Each
+        // refusal carries its token in `details.code` — that is what keys the
+        // sentence — and its count, which the sentence interpolates.
+        const assignees = await this.adminUsers.listByRoleId(role.id);
+        const live = assignees.filter((admin) => admin.deletedAt === null).length;
+        const refusal = roleInUseRefusal(live, assignees.length - live);
+        if (refusal)
+            throw refusal;
+        this.#audit(em, 'admin_role.delete', role.id, { code: role.code }, null);
+        await em.removeAndFlush(role);
+    }
+    /**
+     * Validate an explicit permission list and collapse the wildcard. A list
+     * containing `*` is "full access" — it normalises to exactly `['*']` and the
+     * catalogue check is skipped. Otherwise every code must exist in the merged
+     * catalogue, else a 400 VALIDATION_FAILED is raised.
+     *
+     * Issue #213 — validated against the **known** vocabulary, not the grantable
+     * set. Since the grantable set became presence-filtered, the two differ
+     * exactly while a module is off, and validating against the narrower one
+     * would refuse to save any role that still holds a switched-off module's
+     * code. Off is non-destructive and reversible; a 400 on an unrelated rename
+     * is neither. See `PermissionCatalogueService.listKnownCodes`.
+     */
+    #normalizePermissions(permissions) {
+        if (permissions.includes(WILDCARD))
+            return [WILDCARD];
+        const known = new Set(this.permissionCatalogue.listKnownCodes());
+        const invalid = permissions.filter((p) => !known.has(p));
+        if (invalid.length > 0) {
+            throw new HttpError(400, ERROR_CODES.VALIDATION_FAILED, `Unknown permission(s): ${invalid.join(', ')}`);
+        }
+        return permissions;
+    }
+}
+//# sourceMappingURL=admin-role-service.js.map

package/dist/backend/services/admin-role-service.js.map

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

package/dist/backend/services/permission-catalogue.service.d.ts

@@ -0,0 +1,130 @@
+import { type ModuleManifest, type PermissionCatalogueEntry } from '@endora-commerce/contracts';
+export interface PermissionCatalogueServiceOptions {
+    registryEntries: ReadonlyArray<{
+        manifest: ModuleManifest;
+    }>;
+    /**
+     * **The effective presence of a module — both axes, not one** (issue #213).
+     *
+     * This used to be `getEnabledModuleIds`, wired by both composition roots to
+     * `registryCache.enabledIds()`. That set is the **platform** axis alone: an
+     * operator deactivation leaves the id in it, so every one of the 65 modules
+     * kept contributing its permission codes to `/admin-roles` after the operator
+     * switched it off — the exact conflation Constitution XVII exists to prevent,
+     * shipped.
+     *
+     * The catalogue answers "may an operator grant this today?", and presence is
+     * the conjunction of platform availability and operator activation, so this
+     * predicate is `effectiveState.isPresent` and nothing narrower. It is spelled
+     * out here rather than left to the wiring because the two axes are the thing
+     * people conflate, and a predicate named after one of them invites it back.
+     *
+     * **The two off states are not distinguished on this surface, deliberately.**
+     * Principle XVII item 5 asks a platform-*unavailable* module to render as
+     * absent or blocked-with-a-reason rather than merely "switched off" — that
+     * distinction is about a module's *own* surfaces, where an operator can act on
+     * the reason. `/admin-roles` renders a flat list of grantable codes: it has no
+     * per-module row to carry a reason, and no action an operator could take from
+     * there differs between the two cases. Absent is the whole answer. The screen
+     * that owes the distinction is `/platform/modules`, and it renders it.
+     *
+     * Omitted ⇒ every registered module counts as present. That is the
+     * pre-composition path (the CI helper below, unit tests), not a fall-open: a
+     * presence read before the registry cache is loaded throws
+     * `ModulePresenceNotLoadedError` rather than answering, so an unwired
+     * catalogue cannot be mistaken for a loaded one that found nothing.
+     */
+    isModulePresent?: (moduleId: string) => boolean;
+}
+/**
+ * Merges the core `PERMISSION_CATALOGUE` with the `permissions` arrays of every
+ * registered module manifest. Powers `GET /admin/permissions` and role upsert
+ * validation (feature 026).
+ *
+ * **There is no memo, and that is the design** (issue #213). `listAssignable()`
+ * cached its result into a field that only an explicit `invalidate()` cleared,
+ * and the two things that had to call it — a Redis pub/sub listener in each
+ * composition root — were a duplicated wiring step rather than a property of the
+ * service. That is the shape of issue #33 (an admin "clear cache" action that
+ * missed the per-process LRU) and issue #45 (an invalidation that depended on
+ * subscriber registration order) for the third time. Now that the value tracks a
+ * Setting an operator flips from the Admin UI at runtime, a per-process memo can
+ * only be wrong between the flip and whatever drops it.
+ *
+ * Nothing is lost by dropping it: every input is already in memory — the
+ * manifests are fixed at composition and the presence predicate reads the
+ * registry cache, which does its own refreshing — so a call is a map build and a
+ * sort over a few hundred rows, on two admin-only paths. There is no ordering
+ * trap to test because there is no invalidation to order.
+ */
+export declare class PermissionCatalogueService {
+    #private;
+    private readonly options;
+    private readonly isModulePresent;
+    constructor(options: PermissionCatalogueServiceOptions);
+    /**
+     * The grantable set: what `/admin-roles` renders and what an operator may
+     * newly grant. Presence-filtered, so a module that is off contributes nothing
+     * (Constitution XVII item 5).
+     */
+    listAssignable(): PermissionCatalogueEntry[];
+    listAssignableCodes(): string[];
+    /**
+     * Every code the platform knows, present or not — the **vocabulary**, not the
+     * grantable set.
+     *
+     * Role upsert validates against this rather than against `listAssignable()`,
+     * and the difference is what keeps "off is non-destructive and reversible"
+     * true. An "Editor" role holds `blog.read`; the operator switches `blog` off
+     * and then renames the role. Validating the submitted list against the
+     * grantable set would answer 400 `Unknown permission(s): blog.read` — the
+     * operator either loses the role or silently drops a grant that must come back
+     * when `blog` does. A code of an absent module grants access to nothing anyway:
+     * the routes behind it answer 503 `MODULE_DISABLED` at their own seam.
+     *
+     * This is what the role editor already relies on: `AdminRolesPage` seeds its
+     * selection from the **role's** codes and renders a checkbox only for the ones
+     * the catalogue offers, so an absent module's grant is carried through the
+     * round trip untouched and simply has no checkbox to un-tick while the module
+     * is off. Narrowing this method would turn that into a silent revocation.
+     */
+    listKnownCodes(): string[];
+    /**
+     * Every code the platform knows, mapped to the modules whose presence keeps
+     * it grantable — {@link MergedRow.owners}, published.
+     *
+     * D-173's sweep reads it, and it is a method rather than a derivation of its
+     * own because the whole question is *"does `/admin-roles` still offer this
+     * code when its owner is switched off?"* — a question only the merge this
+     * class performs can answer. A second implementation over
+     * `PERMISSION_CATALOGUE` plus the manifests would be right on the day it was
+     * written and would drift the first time the merge learns a rule: a shared
+     * code with two owners, or a catalogue row a manifest re-declares, is exactly
+     * where the two would disagree, and exactly the shape the sweep exists for.
+     */
+    listOwnersByCode(): Map<string, ReadonlySet<string>>;
+    /**
+     * The codes `moduleId` contributes, whether or not it is present.
+     *
+     * Exists for the off-state harness: proving a module's codes leave the
+     * grantable set needs to know which codes are its, and deriving that from the
+     * `module` display field would silently measure nothing for `_lifecycle`.
+     */
+    listOwnedCodes(moduleId: string): string[];
+    /**
+     * Every declared requirement, as `code -> the codes a role holding it needs`
+     * (D-175, feature 080 T057).
+     *
+     * The **vocabulary's** view, not the grantable set's: the advisory has to
+     * survive its target's owner being switched off, or it would go quiet at
+     * exactly the moment an operator most needs to know why a screen came back
+     * incomplete. Empty requirement sets are omitted, so `size` is the number of
+     * codes that declare one.
+     */
+    listRequirementsByCode(): Map<string, readonly string[]>;
+}
+/** Test / CI helper — build assignable codes without wiring composition. */
+export declare function listAssignablePermissionCodes(registryEntries: ReadonlyArray<{
+    manifest: ModuleManifest;
+}>, presentModuleIds?: readonly string[]): string[];
+//# sourceMappingURL=permission-catalogue.service.d.ts.map

package/dist/backend/services/permission-catalogue.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-catalogue.service.d.ts","sourceRoot":"","sources":["../../../src/backend/services/permission-catalogue.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,wBAAwB,EAC9B,MAAM,4BAA4B,CAAC;AAEpC,MAAM,WAAW,iCAAiC;IAChD,eAAe,EAAE,aAAa,CAAC;QAAE,QAAQ,EAAE,cAAc,CAAA;KAAE,CAAC,CAAC;IAC7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;CACjD;AAqBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,0BAA0B;;IAGzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAgC;gBAEnC,OAAO,EAAE,iCAAiC;IAIvE;;;;OAIG;IACH,cAAc,IAAI,wBAAwB,EAAE;IAM5C,mBAAmB,IAAI,MAAM,EAAE;IAI/B;;;;;;;;;;;;;;;;;;OAkBG;IACH,cAAc,IAAI,MAAM,EAAE;IAI1B;;;;;;;;;;;;OAYG;IACH,gBAAgB,IAAI,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAIpD;;;;;;OAMG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE;IAwE1C;;;;;;;;;OASG;IACH,sBAAsB,IAAI,GAAG,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAOzD;AAED,4EAA4E;AAC5E,wBAAgB,6BAA6B,CAC3C,eAAe,EAAE,aAAa,CAAC;IAAE,QAAQ,EAAE,cAAc,CAAA;CAAE,CAAC,EAC5D,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,GACnC,MAAM,EAAE,CAMV"}