@7365admin1/core 3.63.0 → 3.64.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@7365admin1/core",
   "license": "MIT",
-  "version": "3.63.0",
+  "version": "3.64.1",
   "author": "7365admin1",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -13,7 +13,7 @@
     "build": "tsup src/index.ts --format cjs,esm --dts && shx cp -r src/public dist && shx cp -r src/utils/handlebars dist",
     "release": "yarn run build && changeset publish",
     "lint": "tsc",
-    "test": "tsup src/config.ts src/utils/anpr-revoke.util.ts src/utils/vehicle-request.util.ts src/utils/camera-view.util.ts src/utils/camera-bulk-import.util.ts src/utils/dashboard-metrics.util.ts src/utils/camera-capability.util.ts src/services/camera-device-http.service.ts src/utils/camera-alert.util.ts src/utils/dahua-protocol.util.ts src/utils/site-name.util.ts src/utils/service-provider-invite.util.ts src/utils/notification-category.util.ts src/utils/hid-card.util.ts src/utils/hid-json.util.ts src/utils/hid-access.util.ts src/models/customer-site.model.ts src/models/site-camera.model.ts src/models/member.model.ts src/models/subscription.model.ts src/utils/session-id.util.ts src/utils/occurrence-query.util.ts src/utils/update-result.util.ts src/utils/hid-amico-authz.util.ts src/utils/promo-code-currency.util.ts src/utils/console-audit.util.ts src/utils/org-suspension.util.ts src/utils/session-revoke.util.ts src/models/hid-amico.model.ts src/models/patrol-email.model.ts src/utils/patrol-email-pdf.util.ts src/utils/visitor-status.util.ts src/utils/self-service-email.util.ts src/utils/hid-secret.util.ts src/models/visitor-invite.model.ts src/models/guard-invite.model.ts src/utils/site-timezone.util.ts src/utils/bulletin-service-apps.util.ts src/models/bulletin-board.model.ts src/utils/vehicle-import.util.ts src/utils/expired-vehicle-sweep.util.ts src/models/vehicle.model.ts src/controllers/chat.controller.ts src/utils/file-owner.util.ts src/utils/console-permission.util.ts src/utils/role-scope.util.ts src/utils/org-default-roles.util.ts src/utils/org-modules.util.ts src/utils/site-modules.util.ts src/utils/resident-default-role.util.ts src/utils/invite-role-scope.util.ts src/models/personal-emergency-chain.model.ts src/utils/self-signup-files.util.ts src/models/person.model.ts --format esm --out-dir test/.build --no-dts --silent && node --test test/*.test.mjs",
+    "test": "tsup src/config.ts src/utils/anpr-revoke.util.ts src/utils/vehicle-request.util.ts src/utils/camera-view.util.ts src/utils/camera-bulk-import.util.ts src/utils/dashboard-metrics.util.ts src/utils/camera-capability.util.ts src/services/camera-device-http.service.ts src/utils/camera-alert.util.ts src/utils/dahua-protocol.util.ts src/utils/site-name.util.ts src/utils/service-provider-invite.util.ts src/utils/notification-category.util.ts src/utils/hid-card.util.ts src/utils/hid-json.util.ts src/utils/hid-access.util.ts src/models/customer-site.model.ts src/models/site-camera.model.ts src/models/member.model.ts src/models/subscription.model.ts src/utils/session-id.util.ts src/utils/occurrence-query.util.ts src/utils/update-result.util.ts src/utils/hid-amico-authz.util.ts src/utils/promo-code-currency.util.ts src/utils/console-audit.util.ts src/utils/org-suspension.util.ts src/utils/session-revoke.util.ts src/models/hid-amico.model.ts src/models/patrol-email.model.ts src/utils/patrol-email-pdf.util.ts src/utils/visitor-status.util.ts src/utils/self-service-email.util.ts src/utils/hid-secret.util.ts src/models/visitor-invite.model.ts src/models/guard-invite.model.ts src/utils/site-timezone.util.ts src/utils/bulletin-service-apps.util.ts src/models/bulletin-board.model.ts src/utils/vehicle-import.util.ts src/utils/expired-vehicle-sweep.util.ts src/models/vehicle.model.ts src/controllers/chat.controller.ts src/utils/file-owner.util.ts src/utils/console-permission.util.ts src/utils/role-scope.util.ts src/utils/org-default-roles.util.ts src/utils/org-modules.util.ts src/utils/site-modules.util.ts src/utils/resident-app-modules.util.ts src/utils/resident-default-role.util.ts src/utils/invite-role-scope.util.ts src/models/personal-emergency-chain.model.ts src/utils/self-signup-files.util.ts src/models/person.model.ts --format esm --out-dir test/.build --no-dts --silent && node --test test/*.test.mjs",
     "test:camera": "yarn test",
     "test:e2e": "yarn build && node --test --test-concurrency=1 --test-timeout=600000 \"test/e2e/*.test.mjs\""
   },

package/test/org-modules.test.mjs

@@ -131,9 +131,28 @@ function handler(name) {
 test("setting a client's modules takes the CONSOLE gate", () => {
   const body = handler("updateModules");
   assert.match(body, /await requireConsolePermission\(req, "organizations"\)/);
-  // The write must name only `modules`. Anything else and this becomes a second
-  // way to edit an organisation, with a different gate from the first.
-  assert.match(body, /_update\(orgId, \{ modules \}\)/);
+  /*
+   * The write must name ONLY entitlement fields. Anything else and this
+   * becomes a second way to edit an organisation, with a different gate from
+   * the first.
+   *
+   * There are two now: `modules` (the catalogue) and `residentAppModules`
+   * (R4's resident-app ceiling). Both are the same decision — what did this
+   * client buy — taken by the same actor on the same console screen, which is
+   * why they share an endpoint rather than getting one each.
+   */
+  const write = body.slice(body.indexOf("await _update(orgId, {"));
+  assert.match(write, /modules,/);
+  assert.match(
+    write,
+    /\.\.\.\(residentAppModules === undefined \? \{\} : \{ residentAppModules \}\),/,
+  );
+  // Nothing from the request body reaches the write except those two.
+  const spread = write.slice(0, write.indexOf("});"));
+  assert.ok(
+    !/req\.body\.(?!residentAppModules|modules)/.test(spread),
+    "an unexpected request field reaches the organisation write",
+  );
 });
 
 test("the CLIENT-reachable update still cannot set modules", () => {

package/test/resident-app-modules.test.mjs

@@ -0,0 +1,197 @@
+/*
+ * THE RESIDENT-APP MODULE CASCADE — owner requirement R4, 2026-09-10.
+ *
+ *   Seven365 -> organizations.residentAppModules   (tier one, this adds it)
+ *   the org  -> sites.metadata.residentAppModules  (tier two, already shipped
+ *                and written by property-management's Site Settings panel)
+ *
+ * The whole risk is the DEFAULT. No organisation has the new field and no site
+ * has to have the old one, so a reading of "absent means nothing" empties the
+ * home screen of every resident in the estate the day it deploys. Most of what
+ * follows is about the ways this could fail closed when it must fail open.
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+
+import {
+  effectiveResidentAppModules,
+  residentAppModulesAboveCeiling,
+  residentAppModulesAboveCeilingMessage,
+} from "./.build/utils/resident-app-modules.util.mjs";
+
+const KEYS = [
+  "feedback",
+  "bulletin",
+  "bulletinVideos",
+  "inviteVisitors",
+  "myVisitors",
+  "billingAndSoa",
+  "access",
+  "facilityBooking",
+  "onlineForm",
+  "emergencyContact",
+];
+
+const allOn = () => Object.fromEntries(KEYS.map((key) => [key, true]));
+
+/* ── reading: it must never take a module away by accident ─────────────── */
+
+test("absent at BOTH tiers means every module is ON", () => {
+  for (const org of [undefined, null, {}, [], "junk", 0, true]) {
+    for (const site of [undefined, null, {}, [], "junk", 0, true]) {
+      assert.deepEqual(
+        effectiveResidentAppModules(org, site),
+        allOn(),
+        `${JSON.stringify(org)} / ${JSON.stringify(site)}`,
+      );
+    }
+  }
+});
+
+test("ONLY an explicit false disables — nothing else does", () => {
+  for (const value of [undefined, null, 0, "", "false", NaN, true, {}]) {
+    const result = effectiveResidentAppModules({ feedback: value }, undefined);
+    assert.equal(result.feedback, true, String(value));
+  }
+  // CONTROL: the one value that does disable it.
+  assert.equal(
+    effectiveResidentAppModules({ feedback: false }, undefined).feedback,
+    false,
+  );
+});
+
+test("a site's false turns its own module off", () => {
+  const result = effectiveResidentAppModules(undefined, { bulletin: false });
+  assert.equal(result.bulletin, false);
+  assert.equal(result.feedback, true, "it must not take anything else with it");
+});
+
+test("Seven365's false WINS over a site's true — that is the ceiling", () => {
+  /*
+   * And it keeps winning if Seven365 turns a module off AFTER a site had
+   * already switched it on, which a write-time refusal alone cannot do.
+   */
+  const result = effectiveResidentAppModules(
+    { access: false },
+    { access: true },
+  );
+  assert.equal(result.access, false);
+});
+
+test("an unknown key at either tier changes nothing", () => {
+  const result = effectiveResidentAppModules(
+    { notAModule: false },
+    { alsoNot: false },
+  );
+  assert.deepEqual(result, allOn());
+});
+
+test("every one of the ten keys is always answered", () => {
+  // A missing key reads as `undefined`, and the app's own predicate treats
+  // undefined as ON - but a caller comparing keys would see a shorter object.
+  assert.deepEqual(
+    Object.keys(effectiveResidentAppModules({ feedback: false }, undefined)).sort(),
+    [...KEYS].sort(),
+  );
+});
+
+/* ── writing: a site cannot switch on what the client did not buy ──────── */
+
+test("turning ON a module Seven365 turned OFF is refused, by name", () => {
+  assert.deepEqual(
+    residentAppModulesAboveCeiling({ access: false }, { access: true }),
+    ["access"],
+  );
+  assert.deepEqual(
+    residentAppModulesAboveCeiling(
+      { access: false, onlineForm: false },
+      { access: true, onlineForm: true, feedback: true },
+    ),
+    ["access", "onlineForm"],
+  );
+});
+
+test("an organisation with no ceiling refuses nothing", () => {
+  // Every live organisation is in this state today. If this refused, the Site
+  // Settings panel would stop saving for everybody on deploy.
+  for (const org of [undefined, null, {}, "junk"]) {
+    assert.deepEqual(residentAppModulesAboveCeiling(org, allOn()), []);
+  }
+});
+
+test("turning a module OFF is never refused, whatever the ceiling says", () => {
+  // Switching off is how a site opts out, and it can never exceed a ceiling.
+  assert.deepEqual(
+    residentAppModulesAboveCeiling({ access: false }, { access: false }),
+    [],
+  );
+  assert.deepEqual(
+    residentAppModulesAboveCeiling({ access: false }, {}),
+    [],
+  );
+});
+
+test("a module the ceiling ALLOWS can still be switched on", () => {
+  assert.deepEqual(
+    residentAppModulesAboveCeiling({ access: true }, { access: true }),
+    [],
+  );
+});
+
+test("the refusal names the switches and says what to do", () => {
+  const message = residentAppModulesAboveCeilingMessage(["access", "onlineForm"]);
+  assert.match(message, /access/);
+  assert.match(message, /onlineForm/);
+  assert.match(message, /Ask Seven365/);
+});
+
+/* ── the endpoints ─────────────────────────────────────────────────────── */
+
+const SITE_CONTROLLER = readFileSync(
+  new URL("../src/controllers/site.controller.ts", import.meta.url),
+  "utf8",
+);
+const ORG_CONTROLLER = readFileSync(
+  new URL("../src/controllers/organization.controller.ts", import.meta.url),
+  "utf8",
+);
+
+test("the site read returns the EFFECTIVE set as a second field", () => {
+  /*
+   * A second field, not a narrowing of the saved one. The Site Settings panel
+   * reads back what it writes: narrowing in place would show a property
+   * manager a switch coming back off after they saved it on, which is
+   * indistinguishable from a failed save.
+   */
+  assert.match(SITE_CONTROLLER, /residentAppModulesEffective: effectiveResidentAppModules\(/);
+  assert.match(SITE_CONTROLLER, /res\.json\(await withResidentAppCeiling\(site\)\)/);
+  // CONTROL: the saved field is still returned untouched alongside it.
+  assert.match(SITE_CONTROLLER, /\.\.\.\(site\.metadata \?\? \{\}\)/);
+});
+
+test("the site read fails open — an unreadable organisation cannot blank the app", () => {
+  const start = SITE_CONTROLLER.indexOf("async function withResidentAppCeiling");
+  const body = SITE_CONTROLLER.slice(start, start + 1200);
+  assert.match(body, /\.catch\(\(\) => null\)/);
+  assert.match(body, /catch \{\s*return site;/);
+});
+
+test("the site WRITE refuses only when it actually carries the switches", () => {
+  // Checking unconditionally would cost every site edit an org lookup, and
+  // would refuse a write that never mentioned the resident app.
+  assert.match(SITE_CONTROLLER, /if \(rest\?\.metadata\?\.residentAppModules\) \{/);
+  assert.match(SITE_CONTROLLER, /residentAppModulesAboveCeiling\(/);
+});
+
+test("Seven365 sets the ceiling on the console's own endpoint, and it is optional", () => {
+  // Optional so the existing console screen, which sends only `modules`, keeps
+  // working and leaves the resident-app ceiling exactly as it was.
+  assert.match(ORG_CONTROLLER, /residentAppModules: residentAppModulesSchema\.optional\(\)/);
+  assert.match(
+    ORG_CONTROLLER,
+    /\.\.\.\(residentAppModules === undefined \? \{\} : \{ residentAppModules \}\)/,
+  );
+  // CONTROL: still behind the console permission, not reachable by a client.
+  assert.match(ORG_CONTROLLER, /requireConsolePermission\(req, "organizations"\)/);
+});

package/test/role-scope.test.mjs

@@ -112,6 +112,32 @@ test("/api/roles/v2 is gated too — the same hole with /v2 on the URL", () => {
   );
 });
 
+test("/api/roles/v2 cannot mint a role holding the CONSOLE's own resources", () => {
+  /*
+   * `role.controller createRole` has carried `requireNoPlatformGrant` for a
+   * while; this mount did not. It is a separate controller behind a separate
+   * route and takes any string at all, so the hole was reachable by adding
+   * `/v2` to the URL - the same shape as the two gates above it.
+   *
+   * MEASURED BEFORE ADDING, on production, read-only: NO site-scoped role holds
+   * a platform-only string (6 site-scoped roles read; the 11 roles that do hold
+   * one are org-scoped and already covered by the v1 gate). This mount REQUIRES
+   * a `site`, so the check refuses nothing that exists today.
+   */
+  const body = fn(controllerV2, "createRole");
+  assert.match(body, /requireNoPlatformGrant\(/);
+
+  // It must run BEFORE the write, or it decides nothing.
+  const guard = body.indexOf("requireNoPlatformGrant(");
+  const write = body.indexOf("_createRole(");
+  assert.ok(guard !== -1 && write !== -1);
+  assert.ok(guard < write, "the role is created before the platform check");
+
+  // CONTROL: v1 still has it, so the assertion above is a real comparison and
+  // not a rule that only exists on one side.
+  assert.match(fn(controller, "createRole"), /requireNoPlatformGrant\(/);
+});
+
 /**
  * The four true WRITES now go through `requireRoleWrite`, which is
  * `requireRoleOrg` plus one refusal: a role with no `org` and a non-admin type

package/test/site-modules.test.mjs

@@ -30,6 +30,8 @@ import {
   effectiveSiteModules,
   rejectedSiteModules,
   rejectedSiteModulesMessage,
+  permissionsOutsideModules,
+  requireWithinModules,
 } from "./.build/utils/site-modules.util.mjs";
 
 /* ── reading: it must never return "nothing" ───────────────────────────── */
@@ -147,3 +149,152 @@ test("metadata is MERGED, never replaced", () => {
   const body = handler("updateSiteModules");
   assert.match(body, /metadata: \{ \.\.\.\(site\.metadata \?\? \{\}\), modules \}/);
 });
+
+/* ── TIER THREE: the permissions a role may be GIVEN ───────────────────── */
+
+/*
+ * R1's third clause: whatever Seven365 gives an organisation is the only set
+ * that organisation can give "to its Site Team member". A permission is
+ * `"resource:action"` and the resource IS the module key, so the server refuses
+ * exactly what the editor declines to offer.
+ */
+
+test("no module list means EVERYTHING, so nothing is ever refused", () => {
+  // Every one of the 168 live organisations is in this state today.
+  for (const ceiling of [undefined, null, [], "junk", 0]) {
+    assert.deepEqual(
+      permissionsOutsideModules(ceiling, ["anything:at-all", "console:whatever"]),
+      [],
+      String(ceiling),
+    );
+  }
+});
+
+test("a grant outside the ceiling is refused, by name", () => {
+  assert.deepEqual(
+    permissionsOutsideModules(
+      ["visitor-mgmt"],
+      ["visitor-mgmt:add-visitor", "nfc-patrol:see-all-patrols"],
+    ),
+    ["nfc-patrol:see-all-patrols"],
+  );
+});
+
+test("a grant inside the ceiling is allowed", () => {
+  assert.deepEqual(
+    permissionsOutsideModules(
+      ["visitor-mgmt", "nfc-patrol"],
+      ["visitor-mgmt:add-visitor", "nfc-patrol:see-all-patrols"],
+    ),
+    [],
+  );
+});
+
+test("ONLY what the write ADDS is tested - a role keeps what it already holds", () => {
+  /*
+   * This is what makes the guard safe. A role granted `nfc-patrol` before the
+   * module list existed can still be renamed, and can still have a DIFFERENT
+   * permission removed, without this refusing the write. Refusing those would
+   * turn a narrowing into an outage for every role that predates it - the
+   * 2026-09-07 shape, designed out.
+   */
+  const previous = ["nfc-patrol:see-all-patrols"];
+  assert.deepEqual(
+    permissionsOutsideModules(["visitor-mgmt"], previous, previous),
+    [],
+  );
+  // Removing something it holds is still allowed.
+  assert.deepEqual(
+    permissionsOutsideModules(["visitor-mgmt"], [], previous),
+    [],
+  );
+  // CONTROL: adding a NEW out-of-ceiling string alongside is still refused.
+  assert.deepEqual(
+    permissionsOutsideModules(
+      ["visitor-mgmt"],
+      [...previous, "pool-mgmt:see-all"],
+      previous,
+    ),
+    ["pool-mgmt:see-all"],
+  );
+});
+
+test("both spellings of EVERYTHING are never refused", () => {
+  // An empty list and `["*"]` both mean everything and cannot name a module.
+  assert.deepEqual(permissionsOutsideModules(["visitor-mgmt"], []), []);
+  assert.deepEqual(permissionsOutsideModules(["visitor-mgmt"], ["*"]), []);
+  assert.deepEqual(
+    permissionsOutsideModules(["visitor-mgmt"], ["*", "pool-mgmt:see-all"]),
+    [],
+  );
+});
+
+test("a string with no readable resource fails OPEN", () => {
+  // Four spellings of "work orders" are live. It is not this guard's job to
+  // reject a spelling, and a role write that refuses one is an outage.
+  assert.deepEqual(
+    permissionsOutsideModules(["visitor-mgmt"], [":no-resource", "", "   "]),
+    [],
+  );
+  for (const junk of [null, undefined, 7, {}]) {
+    assert.deepEqual(permissionsOutsideModules(["visitor-mgmt"], [junk]), [], String(junk));
+  }
+});
+
+test("the refusal throws, names the strings, and says what to do", () => {
+  assert.doesNotThrow(() =>
+    requireWithinModules(["visitor-mgmt"], ["visitor-mgmt:add-visitor"]),
+  );
+
+  let thrown;
+  try {
+    requireWithinModules(["visitor-mgmt"], ["pool-mgmt:see-all"]);
+  } catch (error) {
+    thrown = error;
+  }
+  assert.ok(thrown, "an out-of-ceiling grant was allowed through");
+  assert.match(thrown.message, /pool-mgmt:see-all/);
+  assert.match(thrown.message, /Ask Seven365/);
+});
+
+/* ── the four write paths ──────────────────────────────────────────────── */
+
+const ROLE_CONTROLLER = readFileSync(
+  new URL("../src/controllers/role.controller.ts", import.meta.url),
+  "utf8",
+);
+const ROLE_V2_CONTROLLER = readFileSync(
+  new URL("../src/controllers/role-v2.controller.ts", import.meta.url),
+  "utf8",
+);
+
+test("every role write path takes the ceiling, /v2 included", () => {
+  /*
+   * `/api/roles/v2` is a separate mount onto a separate controller, so gating
+   * one and not the other leaves the rule reachable by adding `/v2` to the URL
+   * - the reasoning already written down for the platform-grant gate in that
+   * same file. And v2 is the path this requirement is really about: it REQUIRES
+   * a site, so it is where site roles are created.
+   */
+  assert.equal(
+    (ROLE_CONTROLLER.match(/requireWithinModules\(/g) ?? []).length,
+    3,
+    "role.controller has three write paths: create, update, updatePermissionsById",
+  );
+  assert.equal((ROLE_V2_CONTROLLER.match(/requireWithinModules\(/g) ?? []).length, 1);
+
+  // CONTROL: the established platform gate is still on all three, so the count
+  // above is a real number and not a coincidence.
+  assert.equal((ROLE_CONTROLLER.match(/requireNoPlatformGrant\(/g) ?? []).length, 3);
+});
+
+test("the two EDIT paths pass the existing permissions, so only additions are tested", () => {
+  // Without the third argument every legacy grant would be re-tested on every
+  // edit, and a rename would start failing.
+  const flat = ROLE_CONTROLLER.replace(/\s+/g, " ");
+  const CALL =
+    "requireWithinModules( await moduleCeiling((existing as any)?.org, " +
+    "(existing as any)?.site), permissions, (existing as any)?.permissions, );";
+
+  assert.equal(flat.split(CALL).length - 1, 2);
+});