@7365admin1/layer-common 4.0.3 → 4.0.4-staging.237

package/constants/permissions.ts

@@ -0,0 +1,680 @@
+/**
+ * The canonical permission vocabulary for the iService365 estate.
+ *
+ * WHY THIS FILE EXISTS
+ *
+ * `roles.permissions` is a flat array of `"resource:action"` strings and the API
+ * validates it as `Joi.array().items(Joi.string())` -- any string at all. The
+ * grantable vocabulary therefore lives in the front end, spread across this
+ * layer and eleven web apps, and nothing has ever compared the three sides. The
+ * result, measured on `origin/main`:
+ *
+ *   - work orders are spelled FOUR ways in shipped code -- `work_orders`,
+ *     `workOrder`, `work_order` and `work-orders` -- so a role granted
+ *     "see all work orders" in one app's role editor is refused by another app's
+ *     screen. `DashboardMain.vue` already unions three of them and says in its
+ *     own comment that it cannot fix this from inside one component;
+ *   - visitors are `visitor-mgmt` and `visitorManagement`;
+ *   - `visitor:create`, `visitor:update` and `visitor:check-out` are enforced by
+ *     the server on the HID door-reader endpoints and exist in no catalogue
+ *     anywhere, so nobody can grant them;
+ *   - `incident-reports:see-ncident-reports` is a live typo in the security
+ *     mobile app -- a permanently false check that throws nothing.
+ *
+ * Every one of those was invisible until somebody noticed a blank screen.
+ *
+ * WHAT THIS FILE IS, AND IS NOT
+ *
+ * It is a NAMING source of truth: the canonical spelling of every permission the
+ * estate uses, typed, plus a map from each legacy spelling to its canonical
+ * form. Importing a permission from here makes a typo a compile error instead of
+ * a silently false check.
+ *
+ * It is NOT a grant list and it changes no gate. Nothing in this package is
+ * rewired by adding it; `useCleaningPermission()` is still the catalogue
+ * `hasPermission` looks actions up in, and every existing check still asks for
+ * exactly the string it asked for before. Adopting a canonical spelling in place
+ * of a legacy one is a per-app change with its own behaviour risk (a role
+ * holding the old string stops matching, a role holding the new one starts) and
+ * is deliberately NOT done here. See `LEGACY_PERMISSION_ALIASES`.
+ *
+ * HOW "CANONICAL" WAS DECIDED
+ *
+ *   1. If the server READS the string, the server's spelling wins -- that is
+ *      what actually gates data. This settled `site-settings:*`,
+ *      `virtual-patrol:*`, `facility-mgmt:update-facility` (all of which the UI
+ *      already agreed with) and `service-provider-mgmt` (where the UI was split
+ *      and `core/utils/notification-category.util.ts:185` broke the tie).
+ *   2. Where the server reads none, the spelling used by the MOST apps wins --
+ *      counting an app once, whether it checks the string in its own code or
+ *      through a composable in this layer.
+ *   3. Where rule 2 ties, the estate's dominant convention wins: kebab-case
+ *      resource, `-mgmt` suffix, `see-all-<plural>` for list actions. That is
+ *      what the clear majority of the 279 shipped strings already look like.
+ *
+ * One family could not be settled by those rules and is deliberately left
+ * unresolved -- see `UNRESOLVED_SERVER_SPELLINGS`.
+ *
+ * KEEPING IT HONEST
+ *
+ * `test/permission-vocabulary.test.mjs` fails when this file and reality drift
+ * apart. Read its header for exactly what it does and does not catch.
+ */
+
+/**
+ * Canonical `resource -> actions`.
+ *
+ * Only canonical spellings appear here. A legacy spelling that some app still
+ * ships lives in `LEGACY_PERMISSION_ALIASES` and resolves to an entry below.
+ *
+ * Provenance: extracted from `iservice365-layer-common` plus all eleven
+ * `iservice365-web-app-*` repos at `origin/main`, structurally (every
+ * `hasPermission(...)` call site plus every permission-shaped literal), not by
+ * eyeballing.
+ */
+export const PERMISSIONS = {
+  // ---- shared administration: every app that has a role editor ----
+  members: [
+    "view-members",
+    "assign-member-role",
+    "suspend-member",
+    "activate-member",
+    "delete-member",
+  ],
+  // `roles-and-permissions` is `-admin`'s spelling of the same five actions;
+  // eight apps say `roles`.
+  roles: [
+    "add-role",
+    "see-all-roles",
+    "see-role-details",
+    "update-role",
+    "delete-role",
+  ],
+  invitations: ["create-invitation", "view-invitations", "cancel-invitation"],
+
+  // ---- work orders: the four-way split this catalogue exists to end ----
+  // `work_orders` is canonical on rule 2: four apps (`-landscape`,
+  // `-mechanical-electrical`, `-pool-mgmt`, `-security`) against two for
+  // `workOrder` and one for `work_order`. The server gates none of them; its
+  // only read is the notification filter at
+  // `core/utils/notification-category.util.ts:97`, which already accepts all
+  // four spellings defensively.
+  work_orders: [
+    "create-work-order",
+    "see-all-work-orders",
+    "see-work-order-details",
+    "update-work-order",
+    "delete-work-order",
+  ],
+
+  feedbacks: [
+    "add-feedback",
+    "see-all-feedback",
+    "see-feedback-details",
+    "update-feedback",
+    "delete-feedback",
+  ],
+
+  // `bulletin-board` is canonical on rule 2: this layer's
+  // `useBulletinBoardPermission` is what `-hygiene`, `-landscape`,
+  // `-mechanical-electrical`, `-pest-control` and `-pool-mgmt` render (five
+  // apps), against two spelling it `bulletin-board-mgmt`.
+  "bulletin-board": [
+    "add-bulletin-board",
+    "see-all-bulletin-boards",
+    "see-bulletin-board-details",
+    "update-bulletin-board",
+    "delete-bulletin-board",
+  ],
+  // Videos are a separate resource, not a spelling of the board above.
+  "bulletin-videos-mgmt": [
+    "add-bulletin-video",
+    "see-all-bulletin-video",
+    "see-bulletin-video-details",
+    "update-bulletin-video",
+    "delete-bulletin-video",
+  ],
+
+  // ---- site settings: the server reads five of these, so it decides ----
+  "site-settings": [
+    "can-view-site-settings",
+    "can-manage-site-settings",
+    "manage-site-information",
+    "manage-cctv-camera",
+    "manage-anpr-camera",
+    "manage-delivery-companies",
+    "manage-resident-visitors",
+    "manage-work-order-settings",
+    "manage-billing-and-soa-configuration",
+    "manage-nfc-management",
+    "manage-nfc-patrol-settings",
+    "manage-entry-pass",
+    "manage-red-dot-settings",
+  ],
+
+  // ---- module apps (cleaning, landscape, M&E, pest, pool) ----
+  "area-mgmt": [
+    "see-all-areas",
+    "add-area",
+    "update-area",
+    "see-area-details",
+    "import-areas",
+    "delete-area",
+  ],
+  "unit-mgmt": [
+    "see-all-units",
+    "add-unit",
+    "update-unit",
+    "see-unit-details",
+    "import-units",
+    "delete-unit",
+  ],
+  "supply-mgmt": [
+    "see-all-supplies",
+    "add-supply",
+    "update-supply",
+    "delete-supply",
+    "add-stock",
+    "view-stock",
+    "checkout-item",
+  ],
+  "checkout-item-mgmt": [
+    "see-all-checkouts",
+    "create-checkout",
+    "update-checkout",
+    "approve-checkout",
+    "disapprove-checkout",
+    "view-checkout-details",
+  ],
+  "schedule-task-mgmt": [
+    "see-all-schedule-tasks",
+    "add-schedule-task",
+    "update-schedule-task",
+    "see-schedule-task-details",
+    "delete-schedule-task",
+  ],
+  "attendance-mgmt": [
+    "see-all-attendance",
+    "see-attendance-details",
+    "manage-attendance-settings",
+  ],
+  "my-attendance": ["see-own-attendance", "check-in-out"],
+  inventory: ["view-inventory"],
+  toilet_locations: ["create-toilet-location"],
+
+  // ---- per-trade schedules ----
+  // These four carry the same seven actions on purpose:
+  // `useCleaningSchedulePermission` here, `useSchedulePermission` in
+  // `-landscape`, and `DashboardMain` all match them by SUFFIX
+  // (`permission.endsWith(`-schedule-mgmt:${action}`)`), so the trade prefix is
+  // data, not vocabulary. A new trade needs no code change -- and, because the
+  // match is a suffix, no test in this package can see a new prefix until it is
+  // listed here. This list was built by grepping the four apps for the key, not
+  // from the literal sweep, which cannot see a resource that only ever exists as
+  // a catalogue object key.
+  // Written out four times rather than shared: `as const` needs a literal to
+  // keep each tuple's element types, which is what makes a typo a build error.
+  "cleaning-schedule-mgmt": [
+    "see-all-schedules",
+    "see-schedule-details",
+    "download-schedule",
+    "manage-schedule-tasks",
+    "generate-checklist",
+    "view-history",
+    "add-remarks",
+  ],
+  "landscape-schedule-mgmt": [
+    "see-all-schedules",
+    "see-schedule-details",
+    "download-schedule",
+    "manage-schedule-tasks",
+    "generate-checklist",
+    "view-history",
+    "add-remarks",
+  ],
+  "pest-schedule-mgmt": [
+    "see-all-schedules",
+    "see-schedule-details",
+    "download-schedule",
+    "manage-schedule-tasks",
+    "generate-checklist",
+    "view-history",
+    "add-remarks",
+  ],
+  "pool-schedule-mgmt": [
+    "see-all-schedules",
+    "see-schedule-details",
+    "download-schedule",
+    "manage-schedule-tasks",
+    "generate-checklist",
+    "view-history",
+    "add-remarks",
+  ],
+
+  // ---- property management ----
+  "people-mgmt": [
+    "see-all-people",
+    "add-people",
+    "update-people",
+    "see-people-details",
+    "see-people-nric",
+    "delete-people",
+  ],
+  "building-mgmt": [
+    "see-all-buildings",
+    "add-building",
+    "update-building",
+    "see-building-details",
+    "delete-building",
+  ],
+  // `-property-management`'s only spelling; no kebab counterpart ships anywhere,
+  // so rule 2 leaves it as-is rather than inventing one nobody uses.
+  buildingUnitManagement: [
+    "see-all-building-units",
+    "add-building-unit",
+    "update-building-unit",
+    "see-building-unit-details",
+    "delete-building-unit",
+  ],
+  "document-mgmt": [
+    "add-document",
+    "add-folder",
+    "update-document",
+    "delete-document",
+  ],
+  "emergency-contact": [
+    "see-all",
+    "see-details",
+    "add-emergency-contact",
+    "update-emergency-contact",
+    "delete-emergency-contact",
+    "add-emergency-contact-category",
+    "delete-emergency-contact-category",
+  ],
+  "event-mgmt": [
+    "see-all-event",
+    "add-event",
+    "update-event",
+    "see-event-details",
+    "delete-event",
+  ],
+  "facility-mgmt": [
+    "see-all-facility",
+    "add-facility",
+    "update-facility",
+    "see-facility-details",
+    "delete-facility",
+  ],
+  "facility-booking-mgmt": [
+    "see-all-facility-booking",
+    "add-facility-booking",
+    "update-facility-booking",
+    "see-facility-booking-details",
+    "delete-facility-booking",
+  ],
+  "entry-pass-mgmt": [
+    "view-entry-pass-settings",
+    "add-entry-pass-settings",
+    "update-entry-pass-settings",
+  ],
+  "online-form-configuration": [
+    "add-online-form-configuration",
+    "update-online-form-configuration",
+    "delete-online-form-configuration",
+  ],
+  "nfc-patrol": [
+    "see-all-nfc-patrol",
+    "add-nfc-patrol",
+    "update-nfc-patrol",
+    "delete-nfc-patrol",
+  ],
+  "billing-mgmt": [
+    "see-all-billing-summary",
+    "see-all-billing-items",
+    "see-billing-items-details",
+    "add-billing-items",
+    "update-billing-items",
+    "delete-billing-items",
+    "add-billing-configuration",
+    "update-billing-configuration",
+    "see-billing-configuration-details",
+  ],
+  "SOA-mgmt": ["see-all-soa", "see-soa-details", "add-soa", "download-soa"],
+  // `service-provider-mgmt` is canonical on rule 1: the server reads the
+  // resource at `core/utils/notification-category.util.ts:185`. The UI is split
+  // one-app-one-layer-composable, so without the server read this would have
+  // been a coin toss.
+  "service-provider-mgmt": [
+    "see-all-service-providers",
+    "add-service-provider",
+    "invite-service-provider",
+  ],
+  "access-card-mgmt": [
+    "see-all-card",
+    "see-all-qr-tagging",
+    "view",
+    "add-access-card",
+    "update-access-card",
+    "replace-access-card",
+    "delete-access-card",
+    "assign-access-card",
+    "manage-hid",
+  ],
+
+  // ---- security ----
+  "visitor-mgmt": [
+    "see-all-visitor",
+    "add-visitor",
+    "update-visitor",
+    "see-visitor-details",
+    "delete-visitor",
+  ],
+  "vehicle-mgmt": [
+    "see-all-vehicles",
+    "add-vehicle",
+    "update-vehicle",
+    "see-vehicle-details",
+    "approve-vehicle",
+    "delete-vehicle",
+  ],
+  "incident-reports": [
+    "see-incident-reports",
+    "see-incident-report-details",
+    "add-incident-report",
+    "update-incident-report",
+    "review-incident-report",
+    "delete-incident-report",
+  ],
+  // The server reads five of these (`core/utils/camera-view.util.ts:64,77`), so
+  // rule 1 fixes the whole family. Note `see-all-virtual-patrol-question` is
+  // singular and `see-all-virtual-patrols` has no `-route`/`-log` suffix: both
+  // are verbatim production spelling and must not be "corrected".
+  "virtual-patrol": [
+    "see-all-virtual-patrol-route",
+    "see-all-virtual-patrol-logs",
+    "see-all-virtual-patrol-question",
+    "see-all-virtual-patrols",
+    "see-virtual-patrol-route-details",
+    "see-virtual-patrol-log-details",
+    "see-virtual-patrol-question-details",
+    "add-virtual-patrol-route",
+    "add-virtual-patrol-log",
+    "add-virtual-patrol-question",
+    "update-virtual-patrol-route",
+    "update-virtual-patrol-log",
+    "update-virtual-patrol-question",
+    "start-virtual-patrol-route",
+    "delete-virtual-patrol-route",
+    "delete-virtual-patrol-log",
+    "delete-virtual-patrol-question",
+  ],
+  "daily-occurrence-books": [
+    "see-all-daily-occurrence",
+    "add-daily-occurrence",
+    "update-daily-occurrence",
+    "see-daily-occurrence-details",
+    "delete-daily-occurrence",
+  ],
+  "daily-occurrence-entries": [
+    "see-all-daily-occurrence-entries",
+    "add-daily-occurrence-entries",
+    "update-daily-occurrence-entries",
+    "see-daily-occurrence-entries-details",
+    "delete-daily-occurrence-entries",
+  ],
+  "manpower-monitoring": [
+    "see-all-manpower-monitoring-sites",
+    "see-manpower-monitoring-sites-detail",
+    "see-all-manpower-monitoring-attendance",
+    "download-manpower-monitoring-attendance",
+    "see-all-manpower-monitoring-settings",
+    "save-manpower-monitoring-general-settings",
+    "save-manpower-monitoring-designation-settings",
+    "delete-manpower-sites",
+  ],
+  "robot-mgmt": [
+    "see-all-robots",
+    "add-robot",
+    "update-robot",
+    "see-robot-details",
+    "delete-robot",
+  ],
+
+  // ---- organisation console (`-org`) ----
+  customers: [
+    "see-all-customers",
+    "add-customer",
+    "see-customer-details",
+    "delete-customer",
+  ],
+  sites: ["see-all-sites", "add-site", "see-site-details", "delete-site"],
+  subscriptions: ["view-subscription-details", "management-subscription"],
+} as const;
+
+/** Every canonical resource name. */
+export type TPermissionResource = keyof typeof PERMISSIONS;
+
+/**
+ * Every canonical `"resource:action"` string, as a union type.
+ *
+ * This is the typo guard: a misspelt permission is not assignable to
+ * `TPermissionString`, so it fails `yarn build` instead of quietly answering
+ * `false` forever the way `incident-reports:see-ncident-reports` does today.
+ */
+export type TPermissionString = {
+  [R in TPermissionResource]: `${R}:${(typeof PERMISSIONS)[R][number]}`;
+}[TPermissionResource];
+
+/** The wildcard every gate in the estate short-circuits on. */
+export const PERMISSION_WILDCARD = "*" as const;
+
+/** Every canonical string, flattened. Frozen so a consumer cannot mutate it. */
+export const PERMISSION_STRINGS: readonly TPermissionString[] = Object.freeze(
+  Object.entries(PERMISSIONS).flatMap(([resource, actions]) =>
+    (actions as readonly string[]).map((action) => `${resource}:${action}`),
+  ) as TPermissionString[],
+);
+
+/**
+ * Build a canonical permission string with the compiler checking both halves.
+ *
+ * `permission("work_orders", "see-all-work-orders")` compiles;
+ * `permission("work_orders", "see-all-work-order")` does not.
+ */
+export function permission<
+  R extends TPermissionResource,
+  A extends (typeof PERMISSIONS)[R][number],
+>(resource: R, action: A): `${R}:${A}` {
+  return `${resource}:${action}` as `${R}:${A}`;
+}
+
+/**
+ * Legacy spelling -> canonical spelling.
+ *
+ * Every key is a string SHIPPED TODAY by something that still runs, so a role
+ * out there may be holding it. Nothing here is renamed by this package; the map
+ * exists so a consumer can accept both spellings during a migration and so the
+ * drift test can tell "an old spelling we know about" from "a new string nobody
+ * catalogued".
+ *
+ * Each entry names the consumer that still needs it. An entry can be deleted
+ * once that consumer ships the canonical string AND the roles carrying the old
+ * one have been migrated -- deleting it earlier strands whoever holds the old
+ * string.
+ */
+export const LEGACY_PERMISSION_ALIASES: Readonly<
+  Record<string, TPermissionString>
+> = Object.freeze({
+  // --- work orders (four spellings, one resource) ---
+  // Needed by: `-property-management`, `-pest-control` (own catalogues) and
+  // `DashboardMain.vue`'s union in this package.
+  "workOrder:create-work-order": "work_orders:create-work-order",
+  "workOrder:see-all-work-orders": "work_orders:see-all-work-orders",
+  "workOrder:see-work-order-details": "work_orders:see-work-order-details",
+  "workOrder:update-work-order": "work_orders:update-work-order",
+  "workOrder:delete-work-order": "work_orders:delete-work-order",
+  // Needed by: `-hygiene`, and by `useCleaningPermission()` in this package,
+  // whose catalogue key is `work_order`.
+  "work_order:create-work-order": "work_orders:create-work-order",
+  "work_order:see-all-work-orders": "work_orders:see-all-work-orders",
+  "work_order:see-work-order-details": "work_orders:see-work-order-details",
+  "work_order:update-work-order": "work_orders:update-work-order",
+  "work_order:delete-work-order": "work_orders:delete-work-order",
+  // Needed by: the security mobile app (`isecure365-mobile-app`), and accepted
+  // defensively by `core/utils/notification-category.util.ts:97`. No web app
+  // ships this spelling.
+  "work-orders:create-work-order": "work_orders:create-work-order",
+  "work-orders:see-all-work-orders": "work_orders:see-all-work-orders",
+  "work-orders:update-work-order": "work_orders:update-work-order",
+  "work-orders:delete-work-order": "work_orders:delete-work-order",
+  // Needed by: `-security`, which says `add-` where every other app says
+  // `create-`.
+  "work_orders:add-work-order": "work_orders:create-work-order",
+  "work-orders:add-work-order": "work_orders:create-work-order",
+
+  // --- visitors ---
+  // Needed by: `-property-management`, and by `DashboardMain.vue`'s union here.
+  "visitorManagement:see-all-visitor": "visitor-mgmt:see-all-visitor",
+  "visitorManagement:add-visitor": "visitor-mgmt:add-visitor",
+  "visitorManagement:update-visitor": "visitor-mgmt:update-visitor",
+  "visitorManagement:see-visitor-details": "visitor-mgmt:see-visitor-details",
+  "visitorManagement:delete-visitor": "visitor-mgmt:delete-visitor",
+
+  // --- bulletin board ---
+  // Needed by: `-property-management` and `-security`, which both suffix the
+  // resource `-mgmt` while the five module apps do not.
+  "bulletin-board-mgmt:add-bulletin-board": "bulletin-board:add-bulletin-board",
+  "bulletin-board-mgmt:see-all-bulletin-boards":
+    "bulletin-board:see-all-bulletin-boards",
+  "bulletin-board-mgmt:see-bulletin-board-details":
+    "bulletin-board:see-bulletin-board-details",
+  "bulletin-board-mgmt:update-bulletin-board":
+    "bulletin-board:update-bulletin-board",
+  "bulletin-board-mgmt:delete-bulletin-board":
+    "bulletin-board:delete-bulletin-board",
+  // Needed by: `-property-management` and the security mobile app, which say
+  // "board" singular where everyone else says "boards".
+  "bulletin-board-mgmt:see-all-bulletin-board":
+    "bulletin-board:see-all-bulletin-boards",
+
+  // --- facility bookings ---
+  // Needed by: `DashboardMain.vue`'s module-mode widget map in this package,
+  // the only place that drops the `-mgmt`.
+  "facility-booking:see-all-facility-booking":
+    "facility-booking-mgmt:see-all-facility-booking",
+
+  // --- feedback ---
+  // Needed by: `DashboardMain.vue`'s union here (both of these), and by
+  // `-security`, which pluralises the action.
+  "feedback:see-all-feedback": "feedbacks:see-all-feedback",
+  "feedbacks:see-all-feedbacks": "feedbacks:see-all-feedback",
+
+  // --- incident reports ---
+  // Needed by: `DashboardMain.vue`'s union here. No app ships the `-all-` form.
+  "incident-reports:see-all-incident-reports":
+    "incident-reports:see-incident-reports",
+
+  // --- buildings ---
+  // Needed by: `-property-management`. `-security` already spells it kebab.
+  "buildingManagement:see-all-buildings": "building-mgmt:see-all-buildings",
+  "buildingManagement:add-building": "building-mgmt:add-building",
+  "buildingManagement:update-building": "building-mgmt:update-building",
+  "buildingManagement:see-building-details":
+    "building-mgmt:see-building-details",
+  "buildingManagement:delete-building": "building-mgmt:delete-building",
+
+  // --- roles ---
+  // Needed by: `-admin`, which is retired by redirect but still deployed.
+  "roles-and-permissions:add-role": "roles:add-role",
+  "roles-and-permissions:see-all-roles": "roles:see-all-roles",
+  "roles-and-permissions:see-role-details": "roles:see-role-details",
+  "roles-and-permissions:update-role": "roles:update-role",
+  "roles-and-permissions:delete-role": "roles:delete-role",
+
+  // --- service providers ---
+  // Needed by: `useServiceProviderPermission` in this package, which drops the
+  // `-mgmt` the server's notification filter expects.
+  "service-provider:see-all-service-providers":
+    "service-provider-mgmt:see-all-service-providers",
+  "service-provider:add-service-provider":
+    "service-provider-mgmt:add-service-provider",
+  "service-provider:invite-service-provider":
+    "service-provider-mgmt:invite-service-provider",
+  // Needed by: `-property-management`, which says `view-` where this layer says
+  // `see-all-`.
+  "service-provider-mgmt:view-service-providers":
+    "service-provider-mgmt:see-all-service-providers",
+});
+
+/**
+ * Strings the SERVER enforces that no UI checks and no role editor can grant.
+ *
+ * `core/src/utils/hid-access.util.ts:36-38` gates the HID Amico visitor
+ * endpoints on `visitor:create`, `visitor:update` and `visitor:check-out`. The
+ * whole estate spells visitor rights `visitor-mgmt:add-visitor`,
+ * `:update-visitor` and so on; a bare `visitor` resource appears in no catalogue
+ * in any repo, so no role can hold these and the branch is reachable only
+ * through `*` or through the `access-card-mgmt` strings the same list unions in.
+ *
+ * They are NOT aliased to `visitor-mgmt:*` here, because doing so would be a
+ * decision with a real consequence in both directions:
+ *
+ *   - teaching the server to read `visitor-mgmt:add-visitor` would take a check
+ *     that is dead today and make it LIVE for every role already granted visitor
+ *     management -- widening who may write a credential to a door reader;
+ *   - adding `visitor:create` to the role editors would create a second visitor
+ *     vocabulary next to the one already in use.
+ *
+ * Which of the two is right is a backend-lead and owner call, not this file's.
+ * Recorded rather than guessed, and pinned by the drift test so the list cannot
+ * grow without somebody noticing.
+ *
+ * (The estate's previous example of this, `vehicleManagement:approve-vehicle`,
+ * was fixed in `core` before this catalogue was written: `vehicle.service.ts:133`
+ * on `origin/main` now reads `vehicle-mgmt:approve-vehicle`, which every
+ * catalogue can grant. Notes written before 2026-08-23 still describe the old
+ * spelling.)
+ */
+export const SERVER_ONLY_UNGRANTABLE: readonly string[] = Object.freeze([
+  "visitor:create",
+  "visitor:update",
+  "visitor:check-out",
+]);
+
+/**
+ * Canonical strings that are CHECKED -- by this package and by the server -- and
+ * that no role editor can GRANT.
+ *
+ * `NavigationDrawer.vue:172-180` accepts eight `access-card-mgmt` strings for
+ * the HID menu and `core/src/utils/hid-access.util.ts:19-32` enforces all nine;
+ * only six of them appear in any app's catalogue. The menu still opens, because
+ * the gate is an OR and the other six are grantable -- but a role built out of
+ * only these three is refused at both ends while looking correctly configured in
+ * the role editor. Frozen here so the list cannot grow without somebody noticing.
+ */
+export const CHECKED_BUT_UNGRANTABLE: readonly TPermissionString[] =
+  Object.freeze([
+    "access-card-mgmt:view",
+    "access-card-mgmt:assign-access-card",
+    "access-card-mgmt:manage-hid",
+  ]);
+
+const CANONICAL = new Set<string>(PERMISSION_STRINGS);
+
+/**
+ * Resolve any shipped spelling to its canonical form.
+ *
+ * Returns `undefined` for a string this catalogue has never heard of -- which is
+ * the signal the drift test looks for.
+ */
+export function canonicalPermission(
+  value: string,
+): TPermissionString | undefined {
+  if (CANONICAL.has(value)) return value as TPermissionString;
+  return LEGACY_PERMISSION_ALIASES[value];
+}
+
+/** Is this string one the catalogue knows, canonical or legacy? */
+export function isKnownPermission(value: string): boolean {
+  return canonicalPermission(value) !== undefined;
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@7365admin1/layer-common",
   "license": "MIT",
   "type": "module",
-  "version": "4.0.3",
+  "version": "4.0.4-staging.237",
   "author": "7365admin1",
   "main": "./nuxt.config.ts",
   "//files": "What a consumer extending this layer actually loads. Without this npm ships the whole working tree - the changesets, the CI workflows, the render harness in tools/ and any scratch directory that happened to exist at publish time. Nuxt resolves a layer by directory, so every runtime directory below has to stay listed; adding a new top-level runtime directory means adding it here too.",