@7365admin1/core 3.32.2-staging.110 → 3.32.2-staging.111

package/.changeset/hid-card-pin-authorization.md

@@ -0,0 +1,35 @@
+---
+"@7365admin1/core": patch
+---
+
+HID Amico: authorise the card, PIN, discovery and visitor-QR endpoints
+
+Ten HID Amico handlers required a session and nothing else. The reader id in
+the URL was the only thing selecting the device, and `GET /readers` returns
+every reader in the estate when no `site` is supplied, so any signed-in account
+could act on any reader at any site of any organisation — assign or delete a
+physical access card, set or clear a keypad PIN, put a reader into card
+enrolment, list a user's stored card values, or revoke a visitor's QR pass.
+
+Each of the ten now authorises before it does anything:
+
+- `listUserCards`, `assignUserCard`, `enrollUserCard`, `cancelUserCardEnrollment`,
+  `deleteUserCard` and `revokeVisitorQr` require `site-settings:manage-entry-pass`
+  at the site of the **stored** reader.
+- `getUserPinStatus`, `setUserPin` and `deleteUserPin` allow either that same
+  administrator, or the person whose own device user it is — entitlement to the
+  reader's site plus an ownership check on `hidUserId`, so the resident and MA
+  mobile apps' "Access PIN" screen keeps working while a neighbour's PIN cannot
+  be rewritten.
+- `discoverReader` now takes the `site` the reader is being added to and
+  authorises it, and the address it may be pointed at is constrained: an
+  `http(s)` origin only, no credentials, no path, and never the API host itself
+  or the instance-metadata range. `HID_DISCOVERY_ALLOWED_HOSTS` optionally pins
+  it to named hosts; unset, nothing changes operationally.
+
+A reader that is not yours answers exactly like a reader that does not exist, so
+reader ids cannot be enumerated by watching the difference.
+
+**Consumer change required:** `POST /access-management/hid/readers/discover` now
+requires `site` in the body. `HidReaderForm.vue` in `@7365admin1/layer-common` is
+the only caller and must be updated to send it.

package/dist/index.d.ts

@@ -3630,6 +3630,13 @@ declare function useCameraViewService(): {
          * different, narrower right and passes its own list.
          */
         permissions?: Array<string>;
+        /**
+         * What to say when the permission is missing. The rule this function
+         * applies — membership of the site, then the granting role's permissions —
+         * is not camera-specific, and the HID module now asks the same question of
+         * the same data; only the sentence a refused caller reads differs.
+         */
+        message?: string;
     }) => Promise<{
         site: mongodb.WithId<bson.Document> | null;
         siteObjectId: ObjectId;
@@ -9554,6 +9561,13 @@ declare const schemaHidAmicoLogQuery: Joi.ObjectSchema<any>;
 declare const schemaHidAmicoIdentityQuery: Joi.ObjectSchema<any>;
 declare const schemaHidAmicoSync: Joi.ObjectSchema<any>;
 declare const schemaHidAmicoVisitorQr: Joi.ObjectSchema<any>;
+/**
+ * Discovery is the only HID call that names no reader, so before this there was
+ * nothing on the request to authorise against. `site` is the site the reader is
+ * being added to — the same field `schemaHidAmicoReader` already requires when
+ * the reader is actually created — and it is what the caller's entitlement is
+ * checked against.
+ */
 declare const schemaDiscoverHidAmicoReader: Joi.ObjectSchema<any>;
 declare const schemaHidAmicoVisitorImageParams: Joi.ObjectSchema<any>;
 declare const schemaHidAmicoUserPinParams: Joi.ObjectSchema<any>;
@@ -9818,6 +9832,15 @@ type HidObjectMutation = {
     where?: UnknownRecord;
 };
 declare function useHidAmicoService(): {
+    authorizeReader: (readerId: string, userId: string, options?: {
+        includePassword?: boolean;
+    }) => Promise<THidAmicoReader>;
+    authorizeReaderUser: (readerId: string, hidUserIdValue: string | number, userId: string) => Promise<THidAmicoReader>;
+    authorizeSiteForCaller: (siteId: string, userId: string) => Promise<{
+        site: mongodb.WithId<bson.Document> | null;
+        siteObjectId: bson.ObjectId;
+        db: mongodb.Db;
+    }>;
     listReaders: (value: {
         site?: string;
         page?: number;

package/dist/index.js

@@ -37328,7 +37328,7 @@ function useCameraViewService() {
     const required = params.permissions ?? CAMERA_VIEW_PERMISSIONS;
     if (!hasAnyPermission(permissions, required)) {
       throw new import_node_server_utils107.UnauthorizedError(
-        required === CAMERA_VIEW_PERMISSIONS ? "You do not have permission to view these cameras." : "You do not have permission to set up cameras on this site."
+        params.message ?? (required === CAMERA_VIEW_PERMISSIONS ? "You do not have permission to view these cameras." : "You do not have permission to set up cameras on this site.")
       );
     }
     return { site, siteObjectId, db };
@@ -41655,6 +41655,7 @@ var schemaHidAmicoVisitorQr = import_joi63.default.object({
   qrFormat: import_joi63.default.string().valid("0", "1", "2").optional()
 });
 var schemaDiscoverHidAmicoReader = import_joi63.default.object({
+  site: objectIdSchema2.required(),
   baseUrl: import_joi63.default.string().uri({ scheme: ["http", "https"] }).required(),
   username: import_joi63.default.string().trim().required(),
   password: import_joi63.default.string().required()
@@ -42546,6 +42547,82 @@ function useHidAmicoRepo() {
   };
 }
 
+// src/utils/hid-amico-authz.util.ts
+var HID_MANAGE_PERMISSIONS = ["site-settings:manage-entry-pass"];
+var HID_DISCOVERY_ALLOWED_SCHEMES = ["http:", "https:"];
+function isBlockedDiscoveryHost(hostname) {
+  const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  if (host === "localhost" || host.endsWith(".localhost"))
+    return true;
+  if (host.includes(":")) {
+    if (host === "::" || host === "::1")
+      return true;
+    if (/^fe[89ab]/.test(host) || /^fe[c-f]/.test(host))
+      return true;
+    const mapped = host.match(/^::ffff:([0-9a-f:.]+)$/);
+    if (mapped) {
+      const value = mapped[1];
+      if (value.includes("."))
+        return isBlockedDiscoveryHost(value);
+      const [high, low] = value.split(":");
+      const octets2 = [
+        parseInt(high.padStart(4, "0").slice(0, 2), 16),
+        parseInt(high.padStart(4, "0").slice(2), 16),
+        parseInt((low ?? "0").padStart(4, "0").slice(0, 2), 16),
+        parseInt((low ?? "0").padStart(4, "0").slice(2), 16)
+      ];
+      if (octets2.every((octet) => Number.isInteger(octet))) {
+        return isBlockedDiscoveryHost(octets2.join("."));
+      }
+    }
+    return false;
+  }
+  const octets = host.split(".");
+  if (octets.length !== 4 || !octets.every((octet) => /^\d{1,3}$/.test(octet))) {
+    return false;
+  }
+  const [first, second] = octets.map(Number);
+  if (first === 0)
+    return true;
+  if (first === 127)
+    return true;
+  if (first === 169 && second === 254)
+    return true;
+  if (first >= 224)
+    return true;
+  return false;
+}
+function discoveryAllowedHosts(raw = process.env.HID_DISCOVERY_ALLOWED_HOSTS) {
+  return String(raw || "").split(",").map((entry) => entry.trim().toLowerCase()).filter(Boolean);
+}
+function discoveryUrlRefusalReason(baseUrl, allowedHosts = discoveryAllowedHosts()) {
+  if (typeof baseUrl !== "string" || !baseUrl.trim()) {
+    return "A reader address is required.";
+  }
+  let url;
+  try {
+    url = new URL(baseUrl.trim());
+  } catch {
+    return "The reader address is not a valid URL.";
+  }
+  if (!HID_DISCOVERY_ALLOWED_SCHEMES.includes(url.protocol)) {
+    return "The reader address must be an http or https URL.";
+  }
+  if (url.username || url.password) {
+    return "The reader address must not carry credentials.";
+  }
+  if (url.pathname && url.pathname !== "/" || url.search || url.hash) {
+    return "The reader address must be a host and optional port only.";
+  }
+  if (isBlockedDiscoveryHost(url.hostname)) {
+    return "The reader address is not a permitted reader location.";
+  }
+  if (allowedHosts.length && !allowedHosts.includes(url.hostname.toLowerCase())) {
+    return "The reader address is not a permitted reader location.";
+  }
+  return null;
+}
+
 // src/utils/hid-card.util.ts
 var HID_CARD_VALUE_FACTOR = 2 ** 32;
 function requireSafeNonNegativeInteger(value, label) {
@@ -42590,6 +42667,7 @@ function resolveHidPhysicalCardValue(input) {
 // src/services/hid-amico.service.ts
 var PASSWORD_PREFIX = "v1";
 var remoteCardEnrollmentReaders = /* @__PURE__ */ new Set();
+var HID_READER_NOT_FOUND = "HID Amico reader not found.";
 var PJSIP_CONFIGURATION_KEYS = [
   "enabled",
   "server_ip",
@@ -43635,6 +43713,58 @@ function useHidAmicoService() {
   const visitorRepo = useVisitorTransactionRepo();
   const memberRepo = useMemberRepo();
   const userRepo = useUserRepo();
+  async function authorizeSiteForCaller(siteId, userId) {
+    return useCameraViewService().authorizeSite({
+      siteId,
+      userId,
+      permissions: HID_MANAGE_PERMISSIONS,
+      message: "You do not have permission to manage HID readers on this site."
+    });
+  }
+  async function authorizeReader(readerId, userId, options = {}) {
+    let reader;
+    try {
+      reader = await repo.getById(readerId, options);
+    } catch {
+      throw new import_node_server_utils126.NotFoundError(HID_READER_NOT_FOUND);
+    }
+    try {
+      await authorizeSiteForCaller(String(reader.site || ""), userId);
+    } catch (error) {
+      if (error instanceof import_node_server_utils126.UnauthorizedError)
+        throw error;
+      throw new import_node_server_utils126.NotFoundError(HID_READER_NOT_FOUND);
+    }
+    return reader;
+  }
+  async function entitleReaderForSelf(readerId, userId) {
+    let reader;
+    try {
+      reader = await repo.getById(readerId);
+    } catch {
+      throw new import_node_server_utils126.NotFoundError(HID_READER_NOT_FOUND);
+    }
+    try {
+      await useCameraViewService().entitleSite({
+        siteId: String(reader.site || ""),
+        userId
+      });
+    } catch {
+      throw new import_node_server_utils126.NotFoundError(HID_READER_NOT_FOUND);
+    }
+    return reader;
+  }
+  async function callersOwnHidUserId(readerId, userId) {
+    const identity = await repo.findProfileIdentity(readerId, userId);
+    return identity?.hidUserId ? Number(identity.hidUserId) : createStableHidId(`profile:${readerId}:${userId}`);
+  }
+  async function authorizeReaderUser(readerId, hidUserIdValue, userId) {
+    const reader = await entitleReaderForSelf(readerId, userId);
+    const own = await callersOwnHidUserId(readerId, userId);
+    if (Number(hidUserIdValue) === own)
+      return reader;
+    return authorizeReader(readerId, userId);
+  }
   async function getActiveReader(id) {
     const reader = await repo.getById(id, { includePassword: true });
     if (reader.enabled === false || reader.status === "inactive" || reader.status === "deleted") {
@@ -43769,6 +43899,9 @@ function useHidAmicoService() {
     };
   }
   async function discoverReader(value) {
+    const refusal = discoveryUrlRefusalReason(value.baseUrl);
+    if (refusal)
+      throw new import_node_server_utils126.BadRequestError(refusal);
     const client = new HidAmicoClient({
       ...value,
       baseUrl: value.baseUrl.replace(/\/+$/, "")
@@ -45323,6 +45456,9 @@ function useHidAmicoService() {
     return sipAccountResponse(account);
   }
   return {
+    authorizeReader,
+    authorizeReaderUser,
+    authorizeSiteForCaller,
     listReaders,
     discoverReader,
     createReader,
@@ -81257,6 +81393,9 @@ function getAuthenticatedUserId(req) {
 }
 function useHidAmicoController() {
   const service = useHidAmicoService();
+  const authorizeReader = (req, readerId) => service.authorizeReader(readerId, getAuthenticatedUserId(req));
+  const authorizeReaderUser = (req, readerId, hidUserId) => service.authorizeReaderUser(readerId, hidUserId, getAuthenticatedUserId(req));
+  const authorizeSite = (req, siteId) => service.authorizeSiteForCaller(siteId, getAuthenticatedUserId(req));
   async function listReaders(req, res, next) {
     const { error, value } = schemaHidAmicoReaderListQuery.validate(req.query);
     if (error) {
@@ -81575,6 +81714,7 @@ function useHidAmicoController() {
       return;
     }
     try {
+      await authorizeSite(req, value.site);
       res.json({ data: await service.discoverReader(value) });
     } catch (error2) {
       next(error2);
@@ -81587,6 +81727,7 @@ function useHidAmicoController() {
       return;
     }
     try {
+      await authorizeReaderUser(req, value.readerId, value.hidUserId);
       res.json({ data: await service.getUserPinStatus(value.readerId, value.hidUserId) });
     } catch (error2) {
       next(error2);
@@ -81599,6 +81740,7 @@ function useHidAmicoController() {
       return;
     }
     try {
+      await authorizeReader(req, value.readerId);
       res.json({ data: await service.listUserCards(value.readerId, value.hidUserId) });
     } catch (requestError) {
       next(requestError);
@@ -81612,6 +81754,7 @@ function useHidAmicoController() {
       return;
     }
     try {
+      await authorizeReader(req, params.value.readerId);
       res.status(201).json({
         data: await service.assignUserCard(
           params.value.readerId,
@@ -81631,6 +81774,7 @@ function useHidAmicoController() {
       return;
     }
     try {
+      await authorizeReader(req, params.value.readerId);
       res.status(201).json({
         data: await service.enrollUserCard(
           params.value.readerId,
@@ -81650,6 +81794,7 @@ function useHidAmicoController() {
       return;
     }
     try {
+      await authorizeReader(req, value.readerId);
       res.json({ data: await service.cancelUserCardEnrollment(value.readerId) });
     } catch (requestError) {
       next(requestError);
@@ -81662,6 +81807,7 @@ function useHidAmicoController() {
       return;
     }
     try {
+      await authorizeReader(req, value.readerId);
       res.json({
         data: await service.deleteUserCard(
           value.readerId,
@@ -81681,6 +81827,7 @@ function useHidAmicoController() {
       return;
     }
     try {
+      await authorizeReaderUser(req, params.value.readerId, params.value.hidUserId);
       res.json({
         data: await service.setUserPin(
           params.value.readerId,
@@ -81699,6 +81846,7 @@ function useHidAmicoController() {
       return;
     }
     try {
+      await authorizeReaderUser(req, value.readerId, value.hidUserId);
       res.json({ data: await service.deleteUserPin(value.readerId, value.hidUserId) });
     } catch (error2) {
       next(error2);
@@ -81711,6 +81859,7 @@ function useHidAmicoController() {
       return;
     }
     try {
+      await authorizeReader(req, value.readerId);
       res.json({
         data: await service.revokeVisitorQr(value.readerId, value.visitorId)
       });