@7365admin1/core 3.64.5 → 3.65.1

package/test/e2e/organization-record-reach.e2e.test.mjs

@@ -0,0 +1,241 @@
+// End-to-end proof that `GET /api/organizations/id/:id` hands the WHOLE
+// organisation record only to somebody with a real relationship to it.
+//
+// It returned any client's full document — business e-mail, contact number, UEN,
+// `modules`, `residentAppModules` — to every signed-in account on the platform.
+// Now a caller with no relationship gets the same name-only projection the
+// anonymous twin (`/org/id/:id`) already gives out. Never a 401/403: the RN apps
+// (`src/actions/organization.ts`) sign the user out on a 401 from this read.
+//
+// Relationships that get the whole record, each with a case below:
+//   staff · a live member · an invitee · the owner mid-onboarding (by e-mail) ·
+//   an ACTIVE resident account (members row, users.site, users.unitId, an
+//   active/approved site.people row, or the org's defaultSite being their site) ·
+//   an engaged service provider. A rejected/resubmit applicant gets the name.
+//
+// Everything runs against the harness's in-process MongoDB replica set. No
+// staging or production database, Redis, device or endpoint is touched. Seeded
+// values are obviously fake; assertions are on the presence of keys.
+//
+// Run with: yarn test:e2e
+
+import { after, before, describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { ObjectId } from "mongodb";
+
+import { startHarness } from "./harness.mjs";
+
+const PASSWORD = "OrgReach-Passw0rd!";
+const U = {
+  STRANGER: "or-stranger@e2e.example.com",
+  MEMBER_A: "or-member-a@e2e.example.com",
+  MEMBER_B: "or-member-b@e2e.example.com",
+  RES_MEMBER: "or-res-member@e2e.example.com",
+  RES_SITE: "or-res-site@e2e.example.com",
+  RES_UNIT: "or-res-unit@e2e.example.com",
+  RES_PEOPLE: "or-res-people@e2e.example.com",
+  RES_DEFAULT: "or-res-default@e2e.example.com",
+  APPLICANT: "or-applicant@e2e.example.com",
+  REJECTED: "or-rejected@e2e.example.com",
+  RESUBMIT: "or-resubmit@e2e.example.com",
+  RES_LEGACY: "or-res-legacy@e2e.example.com",
+  PROVIDER: "or-provider@e2e.example.com",
+  EX_PROVIDER: "or-ex-provider@e2e.example.com",
+  OWNER: "or-owner@e2e.example.com",
+  INVITEE: "or-invitee@e2e.example.com",
+  STAFF: "or-sevenadmin@e2e.example.com",
+};
+const PRIVATE = ["email", "contact", "busInst", "residentAppModules", "defaultSite"];
+
+describe("the whole organisation record goes only to a real relationship", { concurrency: 1 }, () => {
+  let h;
+  const id = {};
+  const sid = {};
+  const result = [];
+
+  const record = (name, fn) =>
+    it(name, async () => {
+      try {
+        await fn();
+        result.push(["PASS", name]);
+      } catch (error) {
+        result.push(["FAIL", name]);
+        throw error;
+      }
+    });
+
+  before(async () => {
+    h = await startHarness();
+    Object.assign(id, await seed(h));
+  }, { timeout: 300000 });
+
+  after(async () => {
+    if (h) await h.stop();
+    console.log("\n--- organisation record reach: per-case result ---");
+    for (const [verdict, name] of result) console.log(`${verdict}  ${name}`);
+  });
+
+  const read = (who, org = id.orgB) => h.api(`/organizations/id/${org}`, { sid: sid[who] });
+
+  const nameOnly = async (who) => {
+    const res = await read(who);
+    assert.equal(res.status, 200, `${who}: never a 401/403 - ${JSON.stringify(res.status)}`);
+    assert.deepEqual(Object.keys(res.body ?? {}).sort(), ["_id", "name"], who);
+    assert.equal(res.body.name, "OR Org B");
+  };
+
+  const whole = async (who) => {
+    const res = await read(who);
+    assert.equal(res.status, 200, `${who}: ${JSON.stringify(res.body)}`);
+    for (const key of PRIVATE) assert.ok(key in (res.body ?? {}), `${who} must get ${key}`);
+  };
+
+  record("0. baseline - everybody signs in", async () => {
+    for (const [k, e] of Object.entries(U)) {
+      if (k === "REJECTED") continue; // gets no session at all - case 18
+      sid[k] = await h.login(e, PASSWORD);
+    }
+  });
+
+  // ---- no relationship: the name, and only the name ------------------------
+
+  record("1. a signed-in stranger gets the name only", async () => nameOnly("STRANGER"));
+  record("2. a member of ANOTHER client gets the name only", async () => nameOnly("MEMBER_A"));
+  record("3. a pending applicant's site.people row buys nothing", async () => nameOnly("APPLICANT"));
+  record("4. a provider whose engagement was deleted gets the name only", async () => nameOnly("EX_PROVIDER"));
+
+  // ---- every real relationship: the whole record ----------------------------
+
+  record("5. a live member", async () => whole("MEMBER_B"));
+  record("6. a resident with a members row", async () => whole("RES_MEMBER"));
+  record("7. a resident with no membership, by users.site", async () => whole("RES_SITE"));
+  record("8. a resident with no membership, by users.unitId", async () => whole("RES_UNIT"));
+  record("9. a resident by an approved site.people row", async () => whole("RES_PEOPLE"));
+  record("10. a resident whose site is the org's defaultSite", async () => whole("RES_DEFAULT"));
+  record("11. an engaged service provider", async () => whole("PROVIDER"));
+  record("12. the owner mid-onboarding, before any membership", async () => whole("OWNER"));
+  record("13. an invitee, before any membership", async () => whole("INVITEE"));
+  record("14. Seven365 staff", async () => whole("STAFF"));
+
+  // ---- unchanged edges --------------------------------------------------------
+
+  record("15. no session: /id/ is still 401, /org/id/ still the name", async () => {
+    assert.equal((await h.api(`/organizations/id/${id.orgB}`)).status, 401);
+    const anon = await h.api(`/organizations/org/id/${id.orgB}`);
+    assert.equal(anon.status, 200);
+    assert.deepEqual(Object.keys(anon.body ?? {}).sort(), ["_id", "name"]);
+  });
+
+  record("16. the anonymous /org/id/ mount is name-only even when a session is sent", async () => {
+    // It carries no `requireAuth`, so no session is resolved on it: a sent `sid`
+    // (layer-common `$api` always attaches one) buys nothing there. Its callers
+    // read `org.name` only.
+    for (const who of ["STRANGER", "MEMBER_B"]) {
+      const res = await h.api(`/organizations/org/id/${id.orgB}`, { sid: sid[who] });
+      assert.equal(res.status, 200);
+      assert.deepEqual(Object.keys(res.body ?? {}).sort(), ["_id", "name"], who);
+    }
+  });
+
+  record("17. unknown id is 404 and malformed id is 400, for anybody", async () => {
+    assert.equal((await h.api("/organizations/id/0123456789abcdef01234567", { sid: sid.STRANGER })).status, 404);
+    assert.equal((await h.api("/organizations/id/not-hex", { sid: sid.STRANGER })).status, 400);
+  });
+
+  // ---- a reviewed applicant can sign in, with the site they applied for ------
+
+  record("18. a REJECTED applicant gets no session at all (assertAccountLive)", async () => {
+    await assert.rejects(h.login(U.REJECTED, PASSWORD));
+  });
+  record("19. a RESUBMIT applicant (site, unit AND self-signup's resident members row) gets the name only", async () =>
+    nameOnly("RESUBMIT"));
+  record("20. an older resident account with a BLANK status still gets the whole record", async () =>
+    whole("RES_LEGACY"));
+});
+
+async function seed(h) {
+  const now = new Date().toISOString();
+  const [orgA, orgB, orgP, orgQ, orgX] = [0, 1, 2, 3, 4].map(() => new ObjectId());
+  const [siteB, siteStray] = [new ObjectId(), new ObjectId()];
+  const unitB = new ObjectId();
+  const staffRole = new ObjectId();
+
+  await h.db.collection("organizations").insertMany([
+    { _id: orgA, name: "OR Org A", email: "or-a@e2e.example.com", type: "org", nature: "property_management_agency", status: "active", createdAt: now },
+    {
+      _id: orgB,
+      name: "OR Org B",
+      email: U.OWNER, // the owner's own account address: `hasOrgOwnership`
+      contact: "+650000001",
+      busInst: "E2E-OR-UEN",
+      residentAppModules: { feedback: false },
+      defaultSite: siteStray, // the staging shape: a default site owned elsewhere
+      type: "org",
+      nature: "property_management_agency",
+      status: "active",
+      createdAt: now,
+    },
+    { _id: orgP, name: "OR Provider", email: "or-p@e2e.example.com", type: "org", nature: "security_agency", status: "active", createdAt: now },
+    { _id: orgQ, name: "OR Ex Provider", email: "or-q@e2e.example.com", type: "org", nature: "cleaning_services", status: "active", createdAt: now },
+    { _id: orgX, name: "OR Org X", email: "or-x@e2e.example.com", type: "org", nature: "property_management_agency", status: "active", createdAt: now },
+  ]);
+
+  await h.db.collection("sites").insertMany([
+    { _id: siteB, name: "OR Site B", orgId: orgB, status: "active" },
+    { _id: siteStray, name: "OR Stray Site", orgId: orgX, status: "active" },
+  ]);
+  await h.db.collection("building-units").insertOne({ _id: unitB, name: "OR #01-01", site: siteB, status: "active" });
+  await h.db.collection("roles").insertOne({ _id: staffRole, name: "Super Admin", type: "admin", default: true, permissions: [], status: "active" });
+
+  const emails = Object.values(U);
+  const users = await h.db.collection("users").insertMany(
+    emails.map((email) => ({ email, name: email.split("@")[0], status: "active", createdAt: now })),
+  );
+  const hashed = await h.hashPassword(PASSWORD);
+  await h.db.collection("users").updateMany({ email: { $in: emails } }, { $set: { password: hashed } });
+  const uid = Object.fromEntries(Object.keys(U).map((k, i) => [k, users.insertedIds[i]]));
+
+  await h.db.collection("users").updateOne({ _id: uid.RES_SITE }, { $set: { site: siteB } });
+  await h.db.collection("users").updateOne({ _id: uid.RES_UNIT }, { $set: { unitId: unitB } });
+  await h.db.collection("users").updateOne({ _id: uid.RES_DEFAULT }, { $set: { site: siteStray } });
+  for (const who of ["REJECTED", "RESUBMIT"]) {
+    await h.db.collection("users").updateOne(
+      { _id: uid[who] },
+      { $set: { site: siteB, unitId: unitB, status: who.toLowerCase() } },
+    );
+  }
+  await h.db.collection("users").updateOne({ _id: uid.RES_LEGACY }, { $set: { site: siteB, status: "" } });
+
+  await h.db.collection("members").insertMany([
+    { user: uid.MEMBER_A, org: orgA, type: "organization", status: "active" },
+    { user: uid.MEMBER_B, org: orgB, type: "organization", status: "active" },
+    { user: uid.RES_MEMBER, org: orgB, siteId: siteB, type: "resident", status: "active" },
+    // self-signup writes this row, defaulting to active, and review never changes it
+    { user: uid.RESUBMIT, org: orgB, siteId: siteB, type: "resident", status: "active" },
+    { user: uid.PROVIDER, org: orgP, type: "security_agency", status: "active" },
+    { user: uid.EX_PROVIDER, org: orgQ, type: "cleaning_services", status: "active" },
+    { user: uid.STAFF, type: "admin", role: staffRole, status: "active" },
+  ]);
+
+  await h.db.collection("site.people").insertMany([
+    { user: uid.RES_PEOPLE, site: siteB, unit: unitB, status: "approved", createdAt: now },
+    { user: uid.APPLICANT, site: siteB, unit: unitB, status: "pending", createdAt: now },
+    { user: uid.REJECTED, site: siteB, unit: unitB, status: "rejected", createdAt: now },
+    { user: uid.RESUBMIT, site: siteB, unit: unitB, status: "resubmit", createdAt: now },
+  ]);
+
+  await h.db.collection("customer.sites").insertMany([
+    { name: "OR Site B", site: siteB, siteOrg: orgB, org: orgP, status: "active", deletedAt: "", createdAt: now },
+    { name: "OR Site B", site: siteB, siteOrg: orgB, org: orgQ, status: "deleted", deletedAt: now, createdAt: now },
+  ]);
+
+  await h.db.collection("verifications").insertOne({
+    type: "member-invite",
+    email: U.INVITEE,
+    status: "pending",
+    metadata: { org: orgB, app: "organization" },
+    createdAt: now,
+  });
+
+  return { orgA, orgB, orgP, orgQ, orgX, siteB, siteStray, unitB };
+}

package/test/e2e/user-field-self-allowlist.e2e.test.mjs

@@ -0,0 +1,172 @@
+// End-to-end proof that a person can change only harmless profile fields on
+// their own account through `PATCH /api/users/field/:id` (and the v2 twin).
+//
+// The route's allow-list includes `status`, and self-service took every field
+// except `email`, so any signed-in account could rewrite its own `status` -
+// un-suspend, un-reject or self-approve - and login trusts that column.
+//
+// Self-service now: name, contact, nric, dateOfBirth, profile, gender; and
+// `defaultOrg` only to an organisation the caller reaches (member, invitee,
+// owner) - the web-app-main sign-up flows set it to the org just created or
+// joined. Everything else (`status`, `email`, `plateNumber`) is staff-only.
+//
+// Everything runs against the harness's in-process MongoDB replica set. No
+// staging or production database, Redis, device or endpoint is touched.
+//
+// Run with: yarn test:e2e
+
+import { after, before, describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { ObjectId } from "mongodb";
+
+import { startHarness } from "./harness.mjs";
+
+const PASSWORD = "UserField-Passw0rd!";
+const U = {
+  MEMBER: "uf-member@e2e.example.com", // member of org A
+  INVITEE: "uf-invitee@e2e.example.com", // invited into org B
+  OWNER: "uf-owner@e2e.example.com", // org C is registered under this address
+  APPLICANT: "uf-applicant@e2e.example.com", // status "resubmit": can sign in, not yet approved
+  STAFF: "uf-sevenadmin@e2e.example.com",
+};
+
+describe("self-service user fields are an allow-list", { concurrency: 1 }, () => {
+  let h;
+  const id = {};
+  const sid = {};
+  const result = [];
+
+  const record = (name, fn) =>
+    it(name, async () => {
+      try {
+        await fn();
+        result.push(["PASS", name]);
+      } catch (error) {
+        result.push(["FAIL", name]);
+        throw error;
+      }
+    });
+
+  before(async () => {
+    h = await startHarness();
+    Object.assign(id, await seed(h));
+  }, { timeout: 300000 });
+
+  after(async () => {
+    if (h) await h.stop();
+    console.log("\n--- users/field self allow-list: per-case result ---");
+    for (const [verdict, name] of result) console.log(`${verdict}  ${name}`);
+  });
+
+  const patch = (who, target, field, value, base = "/users/field") =>
+    h.api(`${base}/${id.users[target]}`, { method: "PATCH", sid: sid[who], body: { field, value } });
+
+  const stored = async (key) => h.db.collection("users").findOne({ _id: id.users[key] });
+
+  record("0. baseline - everybody signs in", async () => {
+    for (const [k, e] of Object.entries(U)) sid[k] = await h.login(e, PASSWORD);
+  });
+
+  // ---- refused ----------------------------------------------------------------
+
+  record("1. an applicant cannot approve themselves by setting their own status", async () => {
+    // "resubmit" can sign in (it is not session-blocking); "active" is approval.
+    const res = await patch("APPLICANT", "APPLICANT", "status", "active");
+    assert.equal(res.status, 401, JSON.stringify(res.body));
+    assert.equal((await stored("APPLICANT")).status, "resubmit", "status must be unchanged");
+  });
+
+  record("2. nor their own plateNumber", async () => {
+    const res = await patch("MEMBER", "MEMBER", "plateNumber", "SXX1234Z");
+    assert.equal(res.status, 401, JSON.stringify(res.body));
+  });
+
+  record("3. nor point defaultOrg at an organisation they do not reach", async () => {
+    const res = await patch("MEMBER", "MEMBER", "defaultOrg", id.orgB.toString());
+    assert.equal(res.status, 401, JSON.stringify(res.body));
+    assert.equal(String((await stored("MEMBER")).defaultOrg ?? ""), "");
+  });
+
+  record("4. and the v2 twin refuses the same defaultOrg", async () => {
+    const res = await patch("MEMBER", "MEMBER", "defaultOrg", id.orgB.toString(), "/users/v2/field");
+    assert.equal(res.status, 401, JSON.stringify(res.body));
+  });
+
+  record("5. UNCHANGED: email is still staff-only", async () => {
+    const res = await patch("MEMBER", "MEMBER", "email", "uf-other@e2e.example.com");
+    assert.equal(res.status, 401, JSON.stringify(res.body));
+  });
+
+  // ---- still works ------------------------------------------------------------
+
+  record("6. every profile field the apps send is still self-service", async () => {
+    for (const [field, value] of [
+      ["name", "UF Member"],
+      ["contact", "61234567"],
+      ["gender", "female"],
+      ["profile", "e2e-profile-file-id"],
+      ["nric", "S0000000A"],
+      ["dateOfBirth", "1990-01-01"],
+    ]) {
+      const res = await patch("MEMBER", "MEMBER", field, value);
+      assert.equal(res.status, 200, `${field}: ${JSON.stringify(res.body)}`);
+    }
+  });
+
+  record("7. defaultOrg to your own member organisation", async () => {
+    const res = await patch("MEMBER", "MEMBER", "defaultOrg", id.orgA.toString());
+    assert.equal(res.status, 200, JSON.stringify(res.body));
+  });
+
+  record("8. defaultOrg to the organisation you were invited into (sign-up flow)", async () => {
+    const res = await patch("INVITEE", "INVITEE", "defaultOrg", id.orgB.toString());
+    assert.equal(res.status, 200, JSON.stringify(res.body));
+  });
+
+  record("9. defaultOrg to the organisation you just created (owner sign-up)", async () => {
+    const res = await patch("OWNER", "OWNER", "defaultOrg", id.orgC.toString(), "/users/v2/field");
+    assert.equal(res.status, 200, JSON.stringify(res.body));
+  });
+
+  record("10. Seven365 staff can still set somebody's status", async () => {
+    const res = await patch("STAFF", "MEMBER", "status", "active");
+    assert.equal(res.status, 200, JSON.stringify(res.body));
+  });
+
+  record("11. UNCHANGED: nobody edits another person's profile", async () => {
+    const res = await patch("INVITEE", "MEMBER", "name", "renamed");
+    assert.equal(res.status, 401, JSON.stringify(res.body));
+  });
+});
+
+async function seed(h) {
+  const now = new Date().toISOString();
+  const [orgA, orgB, orgC] = [0, 1, 2].map(() => new ObjectId());
+  const staffRole = new ObjectId();
+
+  await h.db.collection("organizations").insertMany([
+    { _id: orgA, name: "UF Org A", email: "uf-a@e2e.example.com", type: "org", nature: "property_management_agency", status: "active", createdAt: now },
+    { _id: orgB, name: "UF Org B", email: "uf-b@e2e.example.com", type: "org", nature: "property_management_agency", status: "active", createdAt: now },
+    { _id: orgC, name: "UF Org C", email: U.OWNER, type: "org", nature: "property_management_agency", status: "active", createdAt: now },
+  ]);
+  await h.db.collection("roles").insertOne({ _id: staffRole, name: "Super Admin", type: "admin", default: true, permissions: [], status: "active" });
+
+  const emails = Object.values(U);
+  const inserted = await h.db.collection("users").insertMany(
+    emails.map((email) => ({ email, name: email.split("@")[0], status: "active", createdAt: now })),
+  );
+  const hashed = await h.hashPassword(PASSWORD);
+  await h.db.collection("users").updateMany({ email: { $in: emails } }, { $set: { password: hashed } });
+  const users = Object.fromEntries(Object.keys(U).map((k, i) => [k, inserted.insertedIds[i]]));
+  await h.db.collection("users").updateOne({ _id: users.APPLICANT }, { $set: { status: "resubmit" } });
+
+  await h.db.collection("members").insertMany([
+    { user: users.MEMBER, org: orgA, type: "organization", status: "active" },
+    { user: users.STAFF, type: "admin", role: staffRole, status: "active" },
+  ]);
+  await h.db.collection("verifications").insertOne({
+    type: "member-invite", email: U.INVITEE, status: "pending", metadata: { org: orgB, app: "organization" }, createdAt: now,
+  });
+
+  return { orgA, orgB, orgC, users };
+}

package/test/member-direct-role-org.test.mjs

@@ -0,0 +1,33 @@
+/*
+ * POST /api/members/direct only hands out a role of the organisation being
+ * joined (or one the caller already holds there). Proved end to end in
+ * test/e2e/member-direct-role-org (needs a local mongod, so CI does not run
+ * it); these source checks keep the wiring in the suite CI does run.
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+
+const SERVICE = readFileSync("src/services/member.service.ts", "utf8");
+const ACTOR = readFileSync("src/utils/invite-actor.util.ts", "utf8");
+
+test("createMemberDirect refuses another organisation's role before any write", () => {
+  const start = SERVICE.indexOf("async function createMemberDirect(");
+  const fn = SERVICE.slice(start, start + 4000);
+  // Lower-cased: Joi's .hex() accepts upper-case, and an ObjectId prints lower.
+  const check = fn.indexOf('roleOrg !== (orgId?.toString() ?? "").toLowerCase()');
+  const exception = fn.indexOf("!(await holdsRole(callerId, roleId, orgId))");
+  const refusal = fn.indexOf('"That role belongs to a different organisation."');
+  const tx = fn.indexOf("startTransaction()");
+  assert.ok(check > 0 && exception > check && refusal > exception, "org check missing");
+  assert.ok(tx > refusal, "the refusal must come before the transaction opens");
+  // CONTROL: an org-less template role has no roleOrg and is left alone.
+  assert.match(fn, /roleOrg &&\s*roleOrg !== \(orgId/);
+});
+
+test("holdsRole takes an optional organisation and matches both id shapes", () => {
+  const start = ACTOR.indexOf("export async function holdsRole(");
+  const fn = ACTOR.slice(start, start + 1400);
+  assert.match(fn, /orgId\?: string \| ObjectId \| null/);
+  assert.match(fn, /org: \{ \$in: \[new ObjectId\(org\), org\] \}/);
+});

package/test/member-self-enrol-role.test.mjs

@@ -0,0 +1,43 @@
+/*
+ * Self-enrolment through POST /api/members/direct is limited to a role the
+ * caller may give themselves. Proved end to end in
+ * test/e2e/member-direct-self-enrol-role (needs a local mongod, so CI does not
+ * run it); these source checks keep the wiring in the suite CI does run.
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+
+const CONTROLLER = readFileSync("src/controllers/member.controller.ts", "utf8");
+const AUTHZ = readFileSync("src/utils/console-authz.util.ts", "utf8");
+const ACTOR = readFileSync("src/utils/invite-actor.util.ts", "utf8");
+
+const slice = (src, from, len) => src.slice(src.indexOf(from), src.indexOf(from) + len);
+
+test("the SELF branch of createMemberDirect asks for the role as well as the org", () => {
+  const fn = slice(CONTROLLER, "async function createMemberDirect(", 3000);
+  const self = fn.indexOf("if (userId === callerId(req)) {");
+  const reach = fn.indexOf("await requireOrgReach(req, orgId);", self);
+  const role = fn.indexOf("await requireSelfEnrolRole(req, orgId, roleId);", self);
+  const other = fn.indexOf("} else {", self);
+  assert.ok(self > 0 && reach > self && role > reach && other > role, "self-enrol role gate missing");
+});
+
+test("the four roads, in the order the comment names them, then a refusal", () => {
+  const fn = slice(AUTHZ, "export async function requireSelfEnrolRole(", 900);
+  const order = [
+    "(await resolveInviteActor(id)).isSuperAdmin",
+    "await hasOrgOwnership(id, org)",
+    "await holdsRole(id, role, org)",
+    "await invitationOffersRole(id, org, role)",
+    'throw new UnauthorizedError("Not authorized.")',
+  ].map((s) => fn.indexOf(s));
+  assert.ok(order.every((i, n) => i > 0 && (n === 0 || i > order[n - 1])), String(order));
+});
+
+test("a cancelled invitation offers nothing; a role-less one only its app's type in its org", () => {
+  const fn = slice(ACTOR, "export async function invitationOffersRole(", 2200);
+  assert.match(fn, /status: \{ \$ne: "cancelled" \}/);
+  assert.match(fn, /stored\.org\?\.toString\?\.\(\) === org/);
+  assert.match(fn, /v\.metadata\.app === stored\.type/);
+});

package/test/module-access.test.mjs

@@ -0,0 +1,128 @@
+/*
+ * Q3 (owner, 2026-09-11): the server also refuses modules a client has not
+ * been given. Shipped in LOG-ONLY mode: it never refuses, it logs. `enforce`
+ * refuses only listed keys. Every error allows. Work done while the person
+ * still had access (an offline item's frozen timestamp) is accepted.
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  moduleDeniedForCaller,
+  moduleGateEnforceKeys,
+  moduleGateMode,
+} from "./.build/utils/module-access.util.mjs";
+import {
+  ORG,
+  SITE,
+  USER,
+  CLIENT_SAVE,
+  SAVED_AT,
+  ackRow,
+  oldRow,
+  member,
+  fakeGate,
+  withEnv,
+} from "./module-gate.fixtures.mjs";
+
+const SITE_DOC = { _id: SITE, orgId: ORG, metadata: {} };
+const LIST = ["visitor-mgmt"];
+const enforced = (over = {}) =>
+  fakeGate({
+    rows: [member()],
+    orgs: { [ORG]: { _id: ORG, modules: LIST } },
+    sites: { [SITE]: SITE_DOC },
+    saves: { [`${CLIENT_SAVE}|${ORG}`]: ackRow(LIST) },
+    ...over,
+  });
+const check = (data, over = {}) =>
+  moduleDeniedForCaller({ userId: USER, site: SITE, module: "workOrder", ...over }, data);
+const ENFORCE = { MODULE_GATE_MODE: "enforce", MODULE_GATE_ENFORCE_KEYS: "work_orders", MODULE_LIST_GATE: undefined };
+const ALLOW = { refuse: false, denied: false };
+
+test("the code default is LOG; enforce keys are read in any spelling", () => {
+  assert.equal(moduleGateMode({}), "log");
+  assert.equal(moduleGateMode({ MODULE_GATE_MODE: "nonsense" }), "log");
+  assert.equal(moduleGateMode({ MODULE_GATE_MODE: "ENFORCE" }), "enforce");
+  assert.ok(moduleGateEnforceKeys({ MODULE_GATE_ENFORCE_KEYS: "work_orders, visitorManagement" }).includes("workOrder"));
+  assert.deepEqual(moduleGateEnforceKeys({}), []);
+});
+
+test("LOG never refuses: the denial is reported, the request goes through", async () => {
+  const result = await withEnv({ MODULE_GATE_MODE: undefined }, () => check(enforced().data));
+  assert.deepEqual(result, { refuse: false, denied: true });
+});
+
+test("ENFORCE refuses only a listed key", async () => {
+  assert.deepEqual(await withEnv(ENFORCE, () => check(enforced().data)), { refuse: true, denied: true });
+  const unlisted = await withEnv({ ...ENFORCE, MODULE_GATE_ENFORCE_KEYS: "nfc-patrol" }, () => check(enforced().data));
+  assert.deepEqual(unlisted, { refuse: false, denied: true });
+  // CONTROL: a module the list gives is allowed.
+  assert.deepEqual(await withEnv(ENFORCE, () => check(enforced().data, { module: "visitor-mgmt" })), ALLOW);
+});
+
+test("the kill switch and OFF allow everything and read nothing", async () => {
+  for (const env of [{ ...ENFORCE, MODULE_LIST_GATE: "off" }, { ...ENFORCE, MODULE_GATE_MODE: "off" }]) {
+    const { data, calls } = enforced();
+    assert.deepEqual(await withEnv(env, () => check(data)), ALLOW);
+    assert.deepEqual(calls, {}, JSON.stringify(env));
+  }
+});
+
+test("ungoverned modules, staff, residents and strangers are allowed", async () => {
+  await withEnv(ENFORCE, async () => {
+    const quiet = enforced();
+    assert.deepEqual(await check(quiet.data, { module: "dashboard" }), ALLOW);
+    assert.deepEqual(quiet.calls, {}, "an ungoverned module reads nothing");
+    assert.deepEqual(await check(enforced({ rows: [member(), member({ type: "admin", org: "" })] }).data), ALLOW);
+    assert.deepEqual(await check(enforced({ rows: [member({ type: "resident", siteId: SITE })] }).data), ALLOW);
+    assert.deepEqual(await check(enforced({ rows: [] }).data), ALLOW);
+  });
+});
+
+test("allowed when ANY membership at the site allows it", async () => {
+  const provider = member({ _id: "p", org: "9".repeat(24), siteId: SITE });
+  assert.deepEqual(await withEnv(ENFORCE, () => check(enforced({ rows: [member(), provider] }).data)), ALLOW);
+});
+
+test("an old, never-acknowledged list refuses nothing", async () => {
+  const { data } = enforced({ saves: { [`${CLIENT_SAVE}|${ORG}`]: oldRow(LIST) } });
+  assert.deepEqual(await withEnv(ENFORCE, () => check(data)), ALLOW);
+});
+
+test("every error allows, even in ENFORCE", async () => {
+  for (const broken of ["membershipsOf", "site", "org", "latestSave"]) {
+    const { data } = enforced({ throwOn: [broken] });
+    assert.deepEqual(await withEnv(ENFORCE, () => check(data)), ALLOW, broken);
+  }
+});
+
+test("OFFLINE: work stamped before the acknowledged save is accepted; after it, refused", async () => {
+  await withEnv(ENFORCE, async () => {
+    const before = new Date(Date.parse(SAVED_AT) - 60_000).toISOString();
+    const after = new Date(Date.parse(SAVED_AT) + 60_000).toISOString();
+    assert.deepEqual(await check(enforced().data, { at: before }), ALLOW, "done while it was still given");
+    assert.deepEqual(await check(enforced().data, { at: Date.parse(before) }), ALLOW, "epoch ms too");
+    assert.deepEqual(await check(enforced().data, { at: after }), { refuse: true, denied: true });
+    // No timestamp, an unreadable one, or one in the future: treated as now.
+    for (const at of [undefined, "not-a-date", "2999-01-01T00:00:00.000Z"]) {
+      assert.deepEqual(await check(enforced().data, { at }), { refuse: true, denied: true }, String(at));
+    }
+  });
+});
+
+test("OFFLINE: when the save time is unknown, stamped work is accepted", async () => {
+  const noTime = { after: ackRow(LIST).after, createdAt: null };
+  const { data } = enforced({ saves: { [`${CLIENT_SAVE}|${ORG}`]: noTime } });
+  await withEnv(ENFORCE, async () => {
+    assert.deepEqual(await check(data, { at: SAVED_AT }), ALLOW);
+    assert.deepEqual(await check(data), { refuse: true, denied: true }, "control: live work is refused");
+  });
+});
+
+test("a site document passed in is used as is", async () => {
+  const { data, calls } = enforced();
+  const result = await withEnv(ENFORCE, () => check(data, { site: SITE_DOC }));
+  assert.deepEqual(result, { refuse: true, denied: true });
+  assert.equal(calls.site ?? 0, 0);
+});