@7365admin1/layer-common 4.149.1 → 4.150.0

package/components/MemberMain.vue

@@ -155,7 +155,7 @@
                 :title="r"
                 data-test="member-role-chip"
               >
-                {{ r }}
+                {{ r ? r.charAt(0).toUpperCase() + r.slice(1) : r }}
               </StatusChip>
               <span
                 v-if="memberAccess(item, orgLevel).roles.length > 2"

package/components/OvernightParkingAvailability.vue

@@ -6,17 +6,67 @@
   >
     <v-row no-gutters>
       <v-col cols="12">
-        <v-row no-gutters class="d-flex align-center ga-2 justify-end">
-          <span class="d-flex ga-2 align-center">
-            <p>Allow Opening Barrier via Plate Number?</p>
+        <!-- Which QR code types a resident's visitor invitation can carry. -->
+        <template v-for="option in visitorQrCodes" :key="option.type">
+          <div class="d-flex align-center justify-space-between py-3">
+            <div>
+              <div class="text-body-2 font-weight-medium">{{ visitorQrLabels[option.type].title }}</div>
+              <p class="text-caption text-medium-emphasis mt-1 mb-0">
+                {{ visitorQrLabels[option.type].description }}
+              </p>
+            </div>
             <v-switch
-              v-model="isAllowPlateNumberOpenBarrier"
-              hide-details
+              v-model="option.isEnabled"
               color="success"
-              size="large"
+              inset
+              density="compact"
+              hide-details
+              class="flex-grow-0 ml-4"
             />
-          </span>
-        </v-row>
+          </div>
+          <!-- How long an HID visitor pass lasts. Only asked once HID is on. -->
+          <v-radio-group
+            v-if="option.type === 'hid' && option.isEnabled"
+            v-model="option.usage"
+            inline
+            hide-details
+            density="compact"
+            color="success"
+            class="pb-3"
+          >
+            <v-radio
+              v-for="usage in hidQrUsageOptions"
+              :key="usage.value"
+              :value="usage.value"
+              class="mr-6"
+            >
+              <template #label>
+                <div>
+                  <div class="text-body-2">{{ usage.title }}</div>
+                  <div class="text-caption text-medium-emphasis">{{ usage.description }}</div>
+                </div>
+              </template>
+            </v-radio>
+          </v-radio-group>
+          <v-divider />
+        </template>
+        <div class="d-flex align-center justify-space-between py-3">
+          <div>
+            <div class="text-body-2 font-weight-medium">Allow Opening Barrier via Plate Number?</div>
+            <p class="text-caption text-medium-emphasis mt-1 mb-0">
+              When enabled, the barrier can be opened for visitors by matching their vehicle plate number.
+            </p>
+          </div>
+          <v-switch
+            v-model="isAllowPlateNumberOpenBarrier"
+            color="success"
+            inset
+            density="compact"
+            hide-details
+            class="flex-grow-0 ml-4"
+          />
+        </div>
+        <v-divider class="mb-4" />
         <v-row
           no-gutters
           class="d-flex align-center ga-2 justify-space-between"
@@ -220,6 +270,41 @@ const isAllowPlateNumberOpenBarrier = ref(false);
 const autoApproveOvernightParking = ref(false);
 const isHydrating = ref(true);
 
+const visitorQrLabels: Record<TVisitorQrCodeType, { title: string; description: string }> = {
+  hid: {
+    title: "HID QR Code Visitor Invitation",
+    description: "When enabled, HID QR codes will be generated for visitor invitations instead of standard entry pass QR codes.",
+  },
+  entryPass: {
+    title: "Entry Pass QR Code Visitor Invitation",
+    description: "When enabled, entry pass QR codes will be generated for visitor invitations.",
+  },
+  security: {
+    title: "Security QR Code Visitor Invitation",
+    description: "When enabled, security QR codes will be generated for visitor invitations.",
+  },
+};
+// Whole day until the end of the visit day, or one entry and then it expires.
+// Sites that saved before this existed have none, and read as whole day.
+const DEFAULT_HID_QR_USAGE: TVisitorQrUsage = "wholeDay";
+const hidQrUsageOptions: { value: TVisitorQrUsage; title: string; description: string }[] = [
+  {
+    value: "wholeDay",
+    title: "Whole day usage",
+    description: "The visitor can use the QR code as many times as needed until the end of the visit day.",
+  },
+  {
+    value: "singleUse",
+    title: "Single usage",
+    description: "The QR code expires after the visitor's first entry.",
+  },
+];
+const visitorQrCodes = ref<TVisitorQrCode[]>([
+  { type: "hid", isEnabled: false, usage: DEFAULT_HID_QR_USAGE },
+  { type: "security", isEnabled: false },
+  { type: "entryPass", isEnabled: false },
+]);
+
 const { requiredRule } = useUtils();
 const { generateTimeSlots, generateTimeSlotsFromStart } = useFacilityUtils();
 const { currentUser } = useLocalAuth();
@@ -290,6 +375,16 @@ watch(
     autoApproveOvernightParking.value =
       data?.autoApproveOvernightParking === true ||
       data?.isAutoApproved === true;
+    // Set in place so the toggle watcher only fires on a real change.
+    visitorQrCodes.value.forEach((option) => {
+      const saved = (data?.visitorQrCodes as TVisitorQrCode[] | undefined)?.find(
+        (q) => q.type === option.type
+      );
+      option.isEnabled = saved?.isEnabled === true;
+      if (option.type === "hid") {
+        option.usage = saved?.usage ?? DEFAULT_HID_QR_USAGE;
+      }
+    });
     setTimeout(() => {
       isHydrating.value = false;
     }, 500);
@@ -374,7 +469,7 @@ watch(
   isAllowPlateNumberOpenBarrier,
   (newValue, oldValue) => {
     if (oldValue === newValue || isHydrating.value) return;
-    handleSave("toggle");
+    handleSave("toggle", "Plate number barrier setting updated successfully.");
   },
   { immediate: false }
 );
@@ -388,7 +483,19 @@ watch(
   { immediate: false }
 );
 
-async function handleSave(action: "toggle" | "save") {
+watch(
+  visitorQrCodes,
+  () => {
+    if (isHydrating.value) return;
+    handleSave("toggle", "Visitor QR settings updated successfully.");
+  },
+  { deep: true }
+);
+
+async function handleSave(
+  action: "toggle" | "save",
+  successMessage = "Overnight parking settings updated successfully."
+) {
   if (!isValid.value && action === "save") {
     message.value = "Please fill in all required fields.";
     messageColor.value = "error";
@@ -403,6 +510,11 @@ async function handleSave(action: "toggle" | "save") {
     isAllowPlateNumberOpenBarrier: isAllowPlateNumberOpenBarrier.value,
     autoApproveOvernightParking: autoApproveOvernightParking.value,
     isAutoApproved: autoApproveOvernightParking.value,
+    visitorQrCodes: visitorQrCodes.value.map(({ type, isEnabled, usage }) => ({
+      type,
+      isEnabled,
+      ...(type === "hid" ? { usage: usage ?? DEFAULT_HID_QR_USAGE } : {}),
+    })),
     updatedBy: updatedByValue.value,
   };
 
@@ -414,7 +526,7 @@ async function handleSave(action: "toggle" | "save") {
       userType.value
     );
     refreshAvailability();
-    message.value = "Overnight parking settings updated successfully.";
+    message.value = successMessage;
     messageColor.value = "success";
     messageSnackbar.value = true;
   } catch (error) {

package/components/SiteSettings.vue

@@ -186,10 +186,12 @@
         </v-expansion-panel-text>
       </v-expansion-panel>
 
-      <v-expansion-panel>
+      <!-- HID on or off for the site and the HID QR configuration:
+           `hid-mgmt:manage-hid-settings` (`useHidAccessPermission`). -->
+      <v-expansion-panel v-if="canManageHidSettings">
         <v-expansion-panel-title>
           <v-icon class="mr-2">mdi-face-recognition</v-icon>
-          HID Face Reader
+          HID Reader
         </v-expansion-panel-title>
         <v-expansion-panel-text>
           <HidServiceSettingsPanel
@@ -312,6 +314,7 @@ const { canManageSiteInformation,
   canManageVehicleQr,
   canManageSiteSettings: canManageAnySiteSetting,
 } = useSettingsPermission();
+const { canManageHidSettings } = useHidAccessPermission();
 
 const { getSiteById, updateSitebyId, updateSiteInformation } =
   useSiteSettings();

package/components/VisitorForm.vue

@@ -350,6 +350,7 @@
               :hid-qr-printer-configured="hasHidQrPrinterConfig"
               :hid-reader-name="hidQrReader?.name || ''"
               :hid-portal-name="hidQrReader?.portalName || ''"
+              :hid-qr-usage="hidQrUsage"
               @update:available-qr-count="(val) => availableQrCount = val" />
           </v-col>
 
@@ -838,6 +839,7 @@ import useLocalAuth from "../composables/useLocalAuth";
 import useBuilding from "../composables/useBuilding";
 import useVisitor, { getVisitorFieldSwitches, NRIC_LAST4_HINT, VEHICLE_REQUIRED_MESSAGE } from "../composables/useVisitor";
 import useSiteEntryPassSettings from "../composables/useSiteEntryPassSettings";
+import { hidQrUsageFromSettings, minutesUntilEndOfDay } from "../utils/hid-qr-validity";
 import useAccessManagement from "../composables/useAccessManagement";
 import usePeople from "../composables/usePeople";
 import useHidAmico from "../composables/useHidAmico";
@@ -912,7 +914,7 @@ const currentAutofillSource = ref<AutofillSource>(null);
 
 const { requiredRule, debounce, UTCToLocalTIme, maskNRIC, getImage } = useUtils();
 const { addFile } = useFile();
-const { getSiteById, updateSitebyId } = useSiteSettings();
+const { getSiteById, getOvernightParkingAvailabilityV2, updateSitebyId } = useSiteSettings();
 const { currentUser } = useLocalAuth();
 const { getBlocksSelection, getLevelsSelection, getUnitSelection } =
   useBuilding();
@@ -927,7 +929,7 @@ const {
 const { getBySiteId: getEntryPassSettingsBySiteId } =
   useSiteEntryPassSettings();
 const { createVisitorPass, signQr, visitorCheckout } = useAccessManagement();
-const { getReaders, issueVisitorQr } = useHidAmico();
+const { getEnrollmentReaders, issueVisitorQr } = useHidAmico();
 const { testConnection } = useWebUsb();
 const { findVisitorPeopleAnyType, deletePersonRecords } = usePeople();
 const { getPassKeysByPageSearch } = usePassKey();
@@ -1230,11 +1232,6 @@ const hidQrTemplate = computed(() => {
   return hidQrCodePassConfig.value?.template || {};
 });
 
-const hidQrValidityMinutes = computed(() => {
-  const value = Number(hidQrCodePassConfig.value?.validityMinutes);
-  return Number.isFinite(value) && value > 0 ? value : 60;
-});
-
 const hidQrConfiguredReaderId = computed(() => String(hidQrCodePassConfig.value?.readerId || ""));
 type HidQrReaderSummary = {
   _id: string;
@@ -1256,7 +1253,7 @@ const hidQrReaderId = computed(() => (
  * `hidQrCodePassAllowed`, which is why the switch belongs here and not in each
  * of them.
  */
-const HID_VISITOR_QR_ENABLED = false;
+const HID_VISITOR_QR_ENABLED = true;
 
 const hidQrCodePassAllowed = computed(() => {
   return (
@@ -1266,6 +1263,12 @@ const hidQrCodePassAllowed = computed(() => {
   );
 });
 
+// The site's Whole day / Single usage choice for HID visitor passes, shown
+// under the HID QR Code card as the resident app's invite form shows it.
+// Null until read, and when it cannot be read: then no hint, not a guess.
+// Loaded by the watcher below `siteData`.
+const hidQrUsage = ref<"wholeDay" | "singleUse" | null>(null);
+
 // The entry pass is a contractor's, with the site's NFC pass switch on, as
 // the security mobile app (the web-only HID QR pass, switched off above, keeps
 // its own types).
@@ -2298,8 +2301,14 @@ watch(
     hidQrReader.value = null;
     if (!site) return;
     try {
-      const response = await getReaders({ site, page: 1, limit: 100 });
-      const readers: unknown = response?.items ?? response?.data?.items ?? response?.data?.readers ?? [];
+      /* The member's list, not the admin one. `POST /readers/:id/visitor-qr`
+         asks for membership plus `hid-mgmt:use-hid-access` (API-core #1772),
+         while `GET /readers` asks for the HID view right, so a member who may
+         issue a visitor pass but holds no admin right got the pass route and
+         not the reader it needs. `enrollment-readers` is the site's enabled
+         readers with a portal, `{ data: { items } }`, for any member. */
+      const response = await getEnrollmentReaders(site);
+      const readers: unknown = response?.data?.items ?? [];
       const availableReaders = Array.isArray(readers)
         ? readers.filter((reader: unknown): reader is HidQrReaderSummary => (
             typeof reader === "object"
@@ -2326,6 +2335,23 @@ watch(
   { immediate: true },
 );
 
+// Below `siteData` for the same reason as the reader watcher above:
+// `hidQrCodePassAllowed` reads it. Only fetched where HID QR is offered.
+watch(
+  [hidQrCodePassAllowed, () => prop.site],
+  async ([allowed, site]) => {
+    hidQrUsage.value = null;
+    if (!allowed || !site) return;
+    try {
+      const settings = await getOvernightParkingAvailabilityV2(String(site), "site");
+      hidQrUsage.value = hidQrUsageFromSettings(settings);
+    } catch {
+      hidQrUsage.value = null;
+    }
+  },
+  { immediate: true },
+);
+
 const {
   data: blocksListData,
   refresh: refreshBlockListData,
@@ -3388,7 +3414,9 @@ async function prepareHidQrCodePreview(visitorId: string) {
     hidQrVisitorId.value = visitorId;
     const response = await issueVisitorQr(hidQrReaderId.value, {
       visitorId,
-      validityMinutes: hidQrValidityMinutes.value,
+      // The whole visit day, as the resident app issues it. Worked out per
+      // call so a regenerate later in the day still ends at midnight.
+      validityMinutes: minutesUntilEndOfDay(),
     });
     const credential = "data" in response ? response.data : response;
     hidQrPrintPayload.value = credential.qrValue;

package/composables/useCleaningPermission.ts

@@ -84,6 +84,17 @@ export default function useCleaningPermission() {
         description: "Allows the user to manage and update site settings.",
       },
     },
+    // HID access, user side only (decision of 2026-10-16). The service apps
+    // have no HID admin screens yet, so a role here can be prepared with the
+    // one string that lets a member use their own QR code, face, PIN, card and
+    // intercom. Mirrored from core `src/utils/hid-access.util.ts`.
+    "hid-mgmt": {
+      "use-hid-access": {
+        check: true,
+        description:
+          "Allows the user to see HID Access in the app and use their own QR code, face, PIN, card and intercom at this site.",
+      },
+    },
     toilet_locations: {
       "create-toilet-location": {
         check: true,

package/composables/useHidAccessPermission.ts

@@ -1,124 +1,219 @@
+import { permissionsDenied } from "../utils/module-routes";
+
 /**
- * WHO MAY REACH THE SIX HID `access-mgmt` SCREENS.
- *
- * `pages/[org]/[site]/access-mgmt/{access-logs, administrator, hid-cards,
- * hid-readers, hid-users, intercom}/index.vue` shipped with
- * `middleware: ["01-auth","02-org"], memberOnly: true` and no permission check
- * at all. Every one of the eleven Nuxt apps inherits all six, so that was 66
- * routes on which any member of any organisation could type the URL and reach
- * door access, biometric enrolment, physical cards and the access log. The menu
- * that links five of them (`useHidNavigation`) is gated on
- * `getHidServiceEnabled(site)` -- a SITE SERVICE FLAG, not a permission -- so
- * the menu was never a boundary either.
+ * WHO MAY DO WHAT ON HID: the five flags every HID screen, menu and button asks.
  *
- * ## Why adding this gate cannot lock anybody out
+ * Decision of 2026-10-16. HID has its own permission resource, `hid-mgmt`, with
+ * five actions. Core defines the lists in `src/utils/hid-access.util.ts` and
+ * every `/api/access-management/hid` route reads them; this package does not
+ * depend on `@7365admin1/core`, so the strings are copied here and
+ * `test/hid-access-gate.test.mjs` pins the copy to the five.
  *
- * Every data call these screens make goes through `useHidAmico` to
- * `/api/access-management/hid`, and every route there carries `requireAuth`
- * plus `authorizeView` or `authorizeManage`. Those resolve through
- * `authorizeHidAccess` (`core/services/hid-amico.service.ts`) to the lists in
- * `core/utils/hid-access.util.ts` -- the nine `access-card-mgmt` strings below.
+ *   canUseHid             hid-mgmt:use-hid-access      own QR, face, PIN, card,
+ *                                                       intercom; the HID QR Code page
+ *   canViewHid            hid-mgmt:see-all-hid         open any HID admin screen
+ *   canManageHidReaders   hid-mgmt:manage-hid-readers  add, configure, test, sync,
+ *                                                       remove readers
+ *   canManageHidUsers     hid-mgmt:manage-hid-users    enrol and remove people,
+ *                                                       cards, PINs, access groups
+ *   canManageHidSettings  hid-mgmt:manage-hid-settings HID on or off, QR configuration
  *
- * WARNING: there are TWO different `HID_MANAGE_PERMISSIONS` in `core` and they
- * are NOT the same list. `hid-amico-authz.util.ts` exports
- * `["site-settings:manage-entry-pass"]`; `hid-access.util.ts` exports the
- * `access-card-mgmt` family. `hid-amico.service.ts` imports the one from
- * `hid-access.util.ts` -- and `authorizeSiteForCaller`'s own doc comment is
- * stale and still claims the other. Follow the import, not the name.
+ * ## The rules, in the order each flag applies them
  *
- * So a member holding none of these strings already gets a 401 on every list
- * call on all six screens: the screens are non-functional for them today, and
- * they see chrome plus an error toast. The set this gate refuses is a strict
- * SUBSET of the set the server already refuses in production, which is a
- * stronger guarantee than the usual widen-never-swap argument because it is
- * anchored on live server behaviour rather than on a role census.
+ *   1. No role loaded: false. `userAppRole` is null on the first tick for
+ *      everyone, the `*` owner included; `HidEnabledGate` waits on
+ *      `isAppRoleResolved` before it draws a refusal.
+ *   2. The client's module list (RP-5): `hid-mgmt` denied closes every flag,
+ *      including for a wildcard role. A wildcard role is exactly the role a
+ *      module list exists to narrow, so this is asked BEFORE the `*` check.
+ *   3. `*` passes every flag.
+ *   4. An EMPTY permission list passes nothing. This is deliberately not the
+ *      estate rule `hasPermission` applies (`grantsPermission`: empty means
+ *      everything). The owner's decision for HID is strict on empty, everywhere,
+ *      so the empty list is refused here before `hasPermission` can widen it.
+ *   5. Either manage right implies view: a role holding only
+ *      `manage-hid-readers` could otherwise create a reader and not list them.
+ *      Settings does NOT imply view, and use implies nothing.
  *
- * `site-settings:manage-entry-pass` is unioned in -- it is what
- * `hid-amico-authz.util.ts` enforces on the entry-pass paths and the string the
- * HID menu has always been associated with -- and `*` keeps its short-circuit.
+ * ## The alias period
  *
- * ## Intercom is gated with the other five
+ * Until the live roles are backfilled onto `hid-mgmt`, core still accepts the
+ * Access Cards strings HID borrowed before, at the levels
+ * `HID_LEGACY_VIEW_PERMISSIONS` and `HID_LEGACY_MANAGE_PERMISSIONS` give them:
+ * `see-all-card`, `see-all-qr-tagging` and `view` open the admin screens; the
+ * five card write strings and `manage-hid` manage readers and users; only
+ * `manage-hid` reaches settings. The same strings pass here at the same levels,
+ * so nothing that works today stops working before the backfill. The follow-up
+ * that drops the aliases deletes the `legacy*` branches below and the two
+ * `RETIRED_PERMISSIONS` in `constants/permissions.ts` together.
  *
- * `intercom` was the one screen that might have lived entirely on
- * `authorizeMember` endpoints (`/intercom/status`, `/intercom/call`,
- * `/intercom/hangup`). It does not. `HidIntercomManagement.reload()` opens with
- * `getReaders()` (`GET /readers`, `authorizeView`) and filters its rows out of
- * that response; the contacts tab, the dial-code dialog, the make-call dialog
- * and the web phone are all reached from a row, and `loadSipAccount()` is only
- * ever called from one of those dialogs. Without `authorizeView` the screen is
- * an empty table and an error, so gating it removes nothing that works.
+ * `site-settings:manage-entry-pass` is Entry Pass only again. It opened the HID
+ * screens from 4.2.14 to this release because a core utility of the same name
+ * once listed it; it never opened a HID endpoint.
  *
  * ## Drawing, not securing
  *
- * The server re-decides every HID call on its own. This hides screens that do
- * not work; it does not add protection the API does not already have.
+ * The server re-decides every HID call on its own. These flags hide screens and
+ * buttons that would be refused; they add no protection the API lacks.
  */
 
 /**
- * The nine strings `core/utils/hid-access.util.ts` enforces, view + manage.
- *
- * Written out in full `resource:action` form on purpose. `permission-vocabulary`
- * harvests what this package checks by reading literals out of the source, and a
- * bare action fed through a loop into `hasPermission(role, cat, "access-card-mgmt",
- * action)` is invisible to it. Spelling the strings out keeps all nine visible.
+ * Written out in full `resource:action` form on purpose: `permission-vocabulary`
+ * harvests what this package checks by reading literals out of the source, and
+ * a string built from a loop is invisible to it.
  */
-const HID_PERMISSIONS = [
+export const HID_RESOURCE = "hid-mgmt";
+
+export const HID_PERMISSION_STRINGS = [
+  "hid-mgmt:use-hid-access",
+  "hid-mgmt:see-all-hid",
+  "hid-mgmt:manage-hid-readers",
+  "hid-mgmt:manage-hid-users",
+  "hid-mgmt:manage-hid-settings",
+] as const;
+
+/** Core `HID_LEGACY_VIEW_PERMISSIONS`: open the admin screens during the alias period. */
+export const HID_LEGACY_VIEW_PERMISSIONS = [
   "access-card-mgmt:see-all-card",
   "access-card-mgmt:see-all-qr-tagging",
   "access-card-mgmt:view",
+] as const;
+
+/** Core `HID_LEGACY_MANAGE_PERMISSIONS`: manage readers and users during the alias period. */
+export const HID_LEGACY_MANAGE_PERMISSIONS = [
   "access-card-mgmt:add-access-card",
   "access-card-mgmt:update-access-card",
-  "access-card-mgmt:replace-access-card",
   "access-card-mgmt:delete-access-card",
   "access-card-mgmt:assign-access-card",
+  "access-card-mgmt:replace-access-card",
   "access-card-mgmt:manage-hid",
 ] as const;
 
-const HID_ACTIONS = HID_PERMISSIONS.map((p) => p.split(":")[1]);
+const HID_ACTIONS = HID_PERMISSION_STRINGS.map((p) => p.split(":")[1]);
+const LEGACY_ACTIONS = [...HID_LEGACY_VIEW_PERMISSIONS, ...HID_LEGACY_MANAGE_PERMISSIONS].map(
+  (p) => p.split(":")[1],
+);
 
 export function useHidAccessPermission() {
   const { hasPermission } = usePermission();
-  const { siteSettingsPermissions } = useCommonPermissions();
-  const { userAppRole } = useLocalSetup();
+  const { userAppRole, userAppModulesDenied } = useLocalSetup();
 
-  // `hasPermission` needs BOTH the role's string AND a catalogue entry for it:
-  // a resource missing from the catalogue is a dead gate however the role is
-  // granted. `access-card-mgmt` exists in no shared catalogue composable, so it
-  // is built here, exactly as `useServiceProviderPermission` builds its own.
+  // `hasPermission` needs BOTH the role's string AND a catalogue entry for it.
+  // The property and security catalogues carry `hid-mgmt`, the five service
+  // catalogues (cleaning, landscaping, pest control, pool maintenance and,
+  // since 2026-10-19, M&E) carry only `use-hid-access`, and no catalogue
+  // offers the retired `view` and `manage-hid` any more, so the lookup table
+  // is built here: these flags must answer the same in every app that mounts
+  // a HID screen.
   const permissions: TPermissions = {
+    "hid-mgmt": Object.fromEntries(
+      HID_ACTIONS.map((action) => [action, { check: true, description: `HID: ${action}.` }]),
+    ),
     "access-card-mgmt": Object.fromEntries(
-      HID_ACTIONS.map((action) => [
+      LEGACY_ACTIONS.map((action) => [
         action,
-        {
-          check: true,
-          description: `Allows the user to reach the HID access management screens (${action}).`,
-        },
+        { check: true, description: `HID alias period: access-card-mgmt:${action}.` },
       ]),
     ),
-    "site-settings": siteSettingsPermissions,
   };
 
+  // `?.` on purpose: an app pinned to an older layer-common, or a caller that
+  // stubs `useLocalSetup` without this field, hands back `undefined` here. That
+  // must mean "nothing denied", never a TypeError inside every gate.
+  const moduleDenied = (...modules: string[]) =>
+    permissionsDenied(modules, userAppModulesDenied?.value);
+
   /**
-   * Can this member open a HID `access-mgmt` screen at all? Any single string
-   * the server accepts is enough -- somebody granted only `delete-access-card`
-   * still has to open the screen to use it.
+   * Rules 1 to 4. `null` means "decide from the strings"; a boolean is final.
+   * The empty list is refused HERE because `hasPermission` would admit it.
    */
-  const canAccessHidScreens = computed(() => {
+  function decided(): boolean | null {
     const role = userAppRole.value;
     if (!role) return false;
-    if (role.permissions.includes("*")) return true;
-    if (hasPermission(role, permissions, "site-settings", "manage-entry-pass")) return true;
-    return HID_ACTIONS.some((action) =>
-      hasPermission(role, permissions, "access-card-mgmt", action),
-    );
-  });
-
-  // Only the gate is returned. `isAppRoleResolved` is deliberately NOT
-  // re-exported: `gate-defaults.test.mjs` sweeps every ref a permission
-  // composable returns and requires it to read false for an unresolved role,
-  // which a "has the lookup finished" flag is not. Callers that need it take it
-  // from `useLocalSetup()`, which is where it lives.
-  return { canAccessHidScreens };
+    if (moduleDenied("hid-mgmt")) return false;
+    const held: unknown = role.permissions;
+    if (!Array.isArray(held) || !held.length) return false;
+    if (held.includes("*")) return true;
+    return null;
+  }
+
+  // Only reached once `decided()` has answered `null`, so the role is loaded.
+  const has = (resource: string, action: string) => {
+    const role = userAppRole.value;
+    return Boolean(role) && hasPermission(role, permissions, resource, action);
+  };
+
+  // The alias period, string by string so both source sweeps can see them.
+  const legacyView = () =>
+    has("access-card-mgmt", "see-all-card") ||
+    has("access-card-mgmt", "see-all-qr-tagging") ||
+    has("access-card-mgmt", "view");
+  const legacyManage = () =>
+    has("access-card-mgmt", "add-access-card") ||
+    has("access-card-mgmt", "update-access-card") ||
+    has("access-card-mgmt", "delete-access-card") ||
+    has("access-card-mgmt", "assign-access-card") ||
+    has("access-card-mgmt", "replace-access-card") ||
+    has("access-card-mgmt", "manage-hid");
+  const legacySettings = () => has("access-card-mgmt", "manage-hid");
+
+  // The five, each as a literal `hasPermission` call so the gate sweep
+  // (`gate-defaults.test.mjs`) and the vocabulary sweep both read them.
+  const useHid = () => {
+    const role = userAppRole.value;
+    return Boolean(role) && hasPermission(role, permissions, "hid-mgmt", "use-hid-access");
+  };
+  const viewHid = () => {
+    const role = userAppRole.value;
+    return Boolean(role) && hasPermission(role, permissions, "hid-mgmt", "see-all-hid");
+  };
+  const manageReaders = () => {
+    const role = userAppRole.value;
+    return Boolean(role) && hasPermission(role, permissions, "hid-mgmt", "manage-hid-readers");
+  };
+  const manageUsers = () => {
+    const role = userAppRole.value;
+    return Boolean(role) && hasPermission(role, permissions, "hid-mgmt", "manage-hid-users");
+  };
+  const manageSettings = () => {
+    const role = userAppRole.value;
+    return Boolean(role) && hasPermission(role, permissions, "hid-mgmt", "manage-hid-settings");
+  };
+
+  /** The user side: HID Access in the app, own QR, face, PIN, card, intercom. */
+  const canUseHid = computed(() => decided() ?? useHid());
+
+  /** Any manage right implies view (rule 5). */
+  const canManageHidReaders = computed(() => decided() ?? (manageReaders() || legacyManage()));
+  const canManageHidUsers = computed(() => decided() ?? (manageUsers() || legacyManage()));
+  const canViewHid = computed(
+    () =>
+      decided() ??
+      (viewHid() || legacyView() || manageReaders() || manageUsers() || legacyManage()),
+  );
+
+  /** HID on or off for the site, and the HID QR code configuration. */
+  const canManageHidSettings = computed(() => decided() ?? (manageSettings() || legacySettings()));
+
+  /**
+   * @deprecated The pre 2026-10 single gate: "may this member open a HID admin
+   * screen". Kept for any app on this layer that still reads it; it is
+   * `canViewHid` and nothing else. Use the five flags above.
+   */
+  const canAccessHidScreens = canViewHid;
+
+  // `isAppRoleResolved` is deliberately NOT re-exported: `gate-defaults.test.mjs`
+  // sweeps every ref a permission composable returns and requires it to read
+  // false for an unresolved role, which a "has the lookup finished" flag is not.
+  // Callers that need it take it from `useLocalSetup()`, which is where it lives.
+  return {
+    canUseHid,
+    canViewHid,
+    canManageHidReaders,
+    canManageHidUsers,
+    canManageHidSettings,
+    canAccessHidScreens,
+  };
 }
 
 export default useHidAccessPermission;