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

package/CHANGELOG.md

@@ -1,5 +1,268 @@
 # @iservice365/layer-common
 
+## 4.0.3
+
+### Patch Changes
+
+- 02e84c5: Default AccessCardPreviewDialog's Update, Replace and Delete gates to refused
+
+  The three remaining fail-open prop defaults in this package. They qualified for
+  the sweep in #1277 but sat inside #1276's own diff hunk, so they were deliberately
+  deferred until #1276 landed. It has, so they are flipped now.
+
+  `canUpdate`, `canReplaceAccessCard` and `canDeleteAccessCard` declared
+  `default: true`, so a caller that omitted one was handed the Update, Replace or
+  Delete control by the shared layer itself.
+
+  `AccessManagement` is the only caller anywhere — the layer and all eleven web
+  apps at `origin/staging` — and it binds all three to its own props, each of which
+  is declared with an explicit `default: false`. The bound expressions therefore
+  always resolve to a defined value, so the child default never fires and **no user
+  loses access**. This closes the trap for the next caller.
+
+  The contract in `test/gate-defaults.test.mjs` now covers 54 props across 22
+  components, up from 51 across 21.
+
+- 6ba8bba: BulletinBoardManagement now derives canViewBulletinBoardDetails from its own permission gate when the caller omits it
+
+  `canViewBulletinBoardDetails` declared `default: true`. Six of the seven apps
+  that render this component (`-hygiene`, `-landscape`, `-mechanical-electrical`,
+  `-pest-control`, `-pool-mgmt`, `-security`) never bind it, so every user in
+  those apps could open the bulletin-board details/edit dialog regardless of
+  permission. `useBulletinBoardPermission().canViewBulletinBoardDetails` already
+  computed this gate correctly and failed closed -- it just was never called by
+  the component.
+
+  The component now reads that composable itself as the fallback when the prop
+  is unbound (`props.canViewBulletinBoardDetails ?? derived.value`). An app that
+  already passes the prop explicitly (`-property-management`) is unaffected --
+  its value still wins. This closes the gap in-package; no app-side PR needed
+  for this one prop.
+
+- 3ac2550: Stop the still-frame refusal from blacking out the Virtual Patrol camera wall
+
+  On production every tile on the CCTV wall drew "Not set up yet" with "No recorder
+  is configured for this camera's relay.", while staging — the same build — played
+  live pictures. The difference was a recorder entry on the API host, and the live
+  picture never touches a recorder: `CameraWallTile.vue` embeds `camera.host`, the
+  relay's own player page, browser to relay, with no Seven365 server in the path.
+
+  `tileView` returned the dead tile on `camera.unavailableReason` before it ever
+  consulted `capabilities.liveVideo`. `unavailableReason` is the server's
+  **still-frame** refusal (`snapshotRefusalReason`), which genuinely does need a
+  recorder; live video does not. So a picture that was available the whole time was
+  never asked for.
+
+  The `liveVideo` capability is now read first, and the refusal only kills the tile
+  when the server has not said live video is supported. A camera that genuinely
+  cannot show anything — `unsupported`, or a server that never declared the
+  capability at all — still renders the honest "Not set up yet" tile with the
+  server's own sentence, unchanged.
+
+  When a tile draws past an outstanding still-frame refusal it carries
+  `RELAY_ONLY_NOTE` on its note, so a moving picture above a "Recorder not checked"
+  recorder line reads as two separate facts rather than a contradiction. The note
+  is used rather than `detail` because `detail` is drawn across the whole tile and
+  would cover the picture it is explaining.
+
+- 6f9a69d: Make the dashboard's work-order and visitor widgets honour the spelling each app actually grants, and fail closed before the role loads
+
+  The three apps that render `DashboardMain` spell their resources differently:
+  work orders are `work_orders` in `-security`, `workOrder` in
+  `-property-management` and `work_order` in this layer's `useCleaningPermission`;
+  visitors are `visitor-mgmt` in `-security` and `visitorManagement` in
+  `-property-management`. The widget map asked for one spelling apiece, so a
+  property-management role granted "see all work orders" and "see all visitors"
+  through its own role editor got neither widget. Every spelling in use is now
+  listed, the same defensive union the feedback and incident widgets already had.
+
+  `canViewWidget` also returned `true` when no role was loaded, so the dashboard
+  drew every widget and then removed some -- and a failed role fetch left them all
+  drawn. It now returns `false`, matching every other gate in the package.
+
+- 0ac386f: Forward two permission gates that were declared, passed by the apps, and then dropped
+
+  `BuildingManagement/units` declares `canUpdateUnit` and `canDeleteUnit`, and both
+  `-property-management` and `-security` bind them — but the component never handed
+  them to `BuildingUnitFormEdit`, which draws the Update and Delete items. That child
+  defaulted both to `true`, so a role denied update-unit or delete-unit still got both
+  actions inside the unit preview dialog.
+
+  `AccessManagement` never passed `can-assign-to-person` to `AccessCardPreviewDialog`,
+  which gates the Assign control and also defaulted to `true`. The list view in the
+  same file gates its own Assign on `canUpdateAccessCard && canAssignAccessCard`, so
+  the dialog was strictly looser than the list beside it. It now applies the same rule.
+
+  The three child defaults are flipped from `true` to `false` so a caller that forgets
+  the prop is refused rather than granted.
+
+  User-visible effect, and this one takes access away: in `-property-management` and
+  `-security`, a role without update-unit or delete-unit no longer sees Update or
+  Delete in the unit preview dialog, and a role without update-access-card or
+  assign-access-card no longer sees Assign in the card preview dialog. Those controls
+  were never meant to be there. Roles that hold the permissions are unchanged.
+
+- b4e5dd5: Default every permission-shaped prop to refused instead of allowed
+
+  51 gate-shaped props across 21 shared components declared `default: true`. A
+  permission prop that defaults open means the shared layer answers "yes" on an
+  app's behalf whenever that app forgets to bind it — the same fail-open class
+  found in `web-app-org` and in the 25 `web-app-hygiene` gates, expressed as a
+  prop default instead of `if (!userAppRole.value) return true`.
+
+  All 51 are flipped to `default: false`. Every one was first confirmed bound at
+  every existing call site — all eleven web apps read at `origin/staging`, plus
+  every layer-internal parent — and the bound expression confirmed to resolve on
+  that page, because Vue falls back to the default when a bound value is
+  `undefined`. 154 bindings checked, none unresolved.
+
+  **No user loses access from this change.** Every current call site passes an
+  explicit value, so the default never fires today; the flip closes the trap for
+  the next caller. Props that some app does not bind are deliberately left open —
+  flipping those would take a control away from a real user — and are listed in
+  the PR as cross-repo follow-ups.
+
+  The package's 66 runtime permission gates across its 10 permission composables
+  were audited in the same sweep and already fail closed; a regression test now
+  drives all of them with real non-wildcard role documents to keep it that way.
+
+- 050df56: Show the Members row menu when the only permission granted is Assign Role
+
+  The menu's `v-if` tested suspend, activate and delete only, while the Assign
+  Role item inside it tested `assignRole`. A role granted
+  `members:assign-member-role` and nothing else therefore got no row menu at all:
+  the permission was granted, the item existed, and there was no way to reach it.
+  The menu now opens for `assignRole` as well, and still fails closed when none of
+  the four is granted.
+
+- f7cafee: Stop shipping this layer's own unit-test files in the published package. The
+  `files` list included `utils` wholesale, so seventeen `utils/*.test.ts` files
+  went out in every tarball. Consuming applications scan the installed layer's
+  `utils` folder for route references, and the fixture strings inside
+  `utils/breadcrumb.test.ts` were being read as ten real route names that no page
+  produces. Excluding `**/*.test.ts` removes the false readings and drops the
+  fixtures from what every application downloads. No runtime code changes.
+- 4f69c0e: Add the missing `site-settings` and `toilet_locations` families to the cleaning permission catalogue
+
+  `useCleaningPermission()`'s catalogue had no `site-settings` key and no
+  `toilet_locations` key at all. `hasPermission` resolves an action as
+  `catalogue[resource][action]`, so both families answered `false` for every role
+  that did not hold `"*"` — on the published `4.0.1` and on `@staging` alike. This
+  is the same class as the earlier flat-catalogue fix but a different root cause:
+  the resource was missing rather than wrongly shaped, so that fix did not cover it.
+
+  Action names and nesting are copied from the sibling module catalogues that
+  already work — `usePoolMaintenancePermission` and `useLandscapingPermission` both
+  spell site settings exactly this way.
+
+  User-visible effect: in `web-app-hygiene`, a role granted "view site settings" or
+  "manage site settings" now actually reaches the Site Settings screen, and
+  "create toilet location" is grantable instead of permanently refused. Nobody
+  loses access — a full-access role behaved correctly before and is unchanged, and
+  a role that was never granted the permission is still refused.
+
+- a9bd126: Fix site-settings and bulletin-board permission gates, which only ever opened for a full-access role
+
+  `useSettingsPermission` and `useBulletinBoardPermission` passed `hasPermission` a
+  flat `{action: ...}` map where it looks the action up as `catalogue[resource][action]`.
+  `catalogue["site-settings"]` was therefore `undefined` and all eleven site-settings
+  gates plus all five bulletin-board gates answered `false` for every role — the only
+  way through was the `"*"` short-circuit. Both now wrap the group under its resource
+  key, matching the nine composables that were already nested and working.
+
+  User-visible effect: ticking a site-settings or bulletin-board box in the role
+  editor now actually shows the matching panel or control. Previously the Site
+  Settings screen came up with only the one ungated panel no matter what was granted.
+
+- 7574d24: Keep the Edit/Create Plan dialog's Cancel and Save buttons on screen
+- 51aac24: Remove seven unread gate-shaped props left over from the fail-open sweep
+
+  While auditing the 26 remaining `default: true` gate props tracked after #1276/#1277/#1278,
+  seven were found declared but never read anywhere in their own component — no template
+  binding, no `v-if`, no computed, no method body, no forwarding:
+
+  - `AccessManagement.vue`: `canUpdate`, `canDelete`
+  - `BuildingManagement/buildings.vue`: `canDelete`
+  - `BuildingManagement/units.vue`: `canUpdate`, `canDelete`
+  - `DocumentManagement.vue`: `canUpdate`, `canDelete`
+
+  Each of these four components separately declares specific, actually-used gates for the
+  same actions (e.g. `canUpdateBuilding` / `canDeleteBuilding` on `buildings.vue`, alongside
+  the dead bare `canDelete`), so the dead prop was never wired to anything on screen. Deleting
+  it changes no behaviour for any caller — it was already inert — and removes a prop whose
+  `default: true` looked like a live fail-open gate on a quick read.
+
+  This is unrelated to the `test/gate-defaults.test.mjs` contract (54 props / 22 components,
+  landed in #1277/#1278): none of these seven appear in that list, since that sweep only
+  covers props confirmed to be both bound by every caller AND actually read by the component.
+  `yarn test` still reports 279 passing, 0 failing.
+
+- e9931aa: Remove twelve inert `definePageMeta` calls from components
+
+  `definePageMeta` is a pages-only compiler macro. In a component it is a no-op,
+  so these twelve calls set neither `middleware` nor `memberOnly` — they only read
+  as though the component secured itself. `memberOnly` is what makes
+  `plugins/secure-member.client.ts` populate `userAppRole`, and without it every
+  `can*` gate in the package answers `false`; the flag has to be on the consuming
+  page. Deleting the calls changes no behaviour and stops them being mistaken for
+  protection that is already in place.
+
+- f2f594b: Resolve `userAppRole` once per signed-in session, on every authenticated route
+
+  The `secure-member` plugin is the only writer of `userAppRole` in the whole
+  system, and it returned early unless the route carried `memberOnly: true`. On
+  every other page the role stayed `null` for the life of the page, so permission
+  gates that default open granted controls to accounts that had no such
+  permission, and gates that fail closed denied them to real staff permanently.
+
+  Role resolution now runs for any authenticated route and is awaited before the
+  navigation completes, so no gate is evaluated against an unresolved role. A new
+  `userAppRoleStatus` (`"idle" | "loading" | "resolved"`) and `isAppRoleResolved`
+  on `useLocalSetup()` let an app tell "not loaded yet" apart from "loaded, and
+  this account genuinely holds no member document" — the second is the correct
+  final answer for Seven365 staff-console accounts and residents, and is no
+  longer a reason to redirect. A failed request stays unresolved and retries on
+  the next navigation instead of denying for the rest of the session.
+
+  The `memberOnly` redirects are unchanged, and no permission gate was touched.
+
+- eaa8500: Wire the three dead role permissions, and stop a refused roles list looking like an empty one
+
+  `RolePermissionMain` declared `canViewRole`, `canViewByRole` and `canUpdateRole`
+  and referenced none of them. Ten pages across the estate pass them in good faith,
+  so "See all roles", "See role details" and "Update role" were switches that did
+  nothing: the row click was ungated and `RolePermissionFormPreviewUpdate` had no
+  permission prop at all, showing Edit to everybody. `canViewRole` and
+  `canViewByRole` now default to `true`, which is exactly the behaviour the nine
+  pages that do not pass them have always had.
+
+  The roles table also rendered "No data available" for three different situations
+  -- you may not see roles, the request failed, and this organisation has none. It
+  now says which. And both role forms read `error.response._data.message`
+  unguarded, so a network or timeout failure threw inside its own catch and showed
+  the user nothing; the message the preview dialog does show was also duplicated in
+  the template and printed twice.
+
+- 159aa53: ServiceProviderMain now derives its add/invite/view gates from a real permission catalogue entry when the caller omits them
+
+  `canAddServiceProvider`, `canInviteServiceProvider` and `canViewServiceProviders` all
+  declared `default: true`, and no app bound any of the three -- there was no permission
+  catalogue key anywhere in the package for an app to bind them to, so every signed-in user
+  in every consumer could add, invite and view service providers regardless of role.
+
+  Added a `service-provider` family (`add-service-provider`, `invite-service-provider`,
+  `see-all-service-providers`) to `useCommonPermission`'s catalogue and a new
+  `useServiceProviderPermission` composable that reads it, the same shape as the existing
+  `useBulletinBoardPermission` / `useSettingsPermission` gates. `ServiceProviderMain` now
+  reads that composable as the fallback when a prop is unbound
+  (`props.canAddServiceProvider ?? derived.value`, etc.) -- an app that already passes a
+  prop explicitly still wins.
+
+  This closes the gap in-package. It does not add server-side enforcement:
+  `service-provider.route.ts` only requires an authenticated session today, the same as
+  `bulletin-board.route.ts` -- this catalogue key is the same frontend-only enforcement
+  layer the rest of this family already relies on, not a new pattern.
+
 ## 4.0.2
 
 ### Patch Changes
@@ -17,11 +280,11 @@
   `utils/console-tier.ts` + `composables/useConsoleTier.ts` mirror the server's
   own rule from two endpoints the console already calls, unprojected:
 
-      GET /api/members/user/:user/app/admin    the Seven365 staff membership
-      GET /api/roles/id/:role                  that membership's role document
+        GET /api/members/user/:user/app/admin    the Seven365 staff membership
+        GET /api/roles/id/:role                  that membership's role document
 
-      owner  = member.type === "admin" && role.type === "admin" && role.default === true
-      staff  = member.type === "admin" && role.type === "admin"
+        owner  = member.type === "admin" && role.type === "admin" && role.default === true
+        staff  = member.type === "admin" && role.type === "admin"
 
   `role.default` is the marker because it is the only property of a platform
   staff role no API caller can set - `role.controller.ts` validates create and

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-staging.236",
+  "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.",