@7365admin1/core 3.52.19 → 3.53.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@7365admin1/core",
   "license": "MIT",
-  "version": "3.52.19",
+  "version": "3.53.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/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 --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 --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/scripts/organizations-name-index.mjs

@@ -0,0 +1,251 @@
+// organizations-name-index.mjs — one-off maintenance tool, run by hand, never by the app.
+//
+// WHY IT EXISTS
+// The first version of `src/repositories/organization.repo.ts` created a UNIQUE
+// index on `organizations.name` (`36150ea0`). Commit `06ee8915` stopped creating
+// it, but nothing has ever DROPPED the one already built — and an index outlives
+// the code that created it. While that index is still there, renaming an
+// organisation to a name another organisation already uses fails with a duplicate
+// key error (E11000), which is what surfaced as the onboarding 500
+// "Failed to update organization."
+//
+// This script LOOKS for that leftover index and, only when you explicitly ask,
+// drops it. It touches nothing else.
+//
+// HOW TO RUN IT
+// From inside the `iservice365-core` folder, after `yarn install`.
+//
+//   PowerShell (Windows) — LOOK ONLY, changes nothing:
+//     $env:ISERVICE365_MONGO_URI = "<the connection string>"
+//     node scripts/organizations-name-index.mjs
+//
+//   PowerShell (Windows) — DROP the index (asks you to type the database name):
+//     $env:ISERVICE365_MONGO_URI = "<the connection string>"
+//     node scripts/organizations-name-index.mjs --drop
+//
+//   bash / sh — look only, then drop:
+//     ISERVICE365_MONGO_URI='<the connection string>' node scripts/organizations-name-index.mjs
+//     ISERVICE365_MONGO_URI='<the connection string>' node scripts/organizations-name-index.mjs --drop
+//
+// Run it with no flag FIRST. The connection string is read from the environment
+// only — there is no default, it is never printed, and it is stripped out of any
+// error message this script shows.
+
+import { createInterface } from "node:readline/promises";
+import { pathToFileURL } from "node:url";
+import { MongoClient } from "mongodb";
+
+const COLLECTION = "organizations";
+const ENV_VAR = "ISERVICE365_MONGO_URI";
+
+/* ------------------------------------------------------------------ the rule
+ * Every index on `organizations` falls into exactly one bucket. Only "target" is
+ * ever dropped. Anything that touches `name` and is not recognised stops the run,
+ * because guessing at an index somebody else built is how you lose a collection.
+ */
+export function classifyIndex(index) {
+  if (index.name === "_id_") return "protected";
+
+  const key = index.key || {};
+  const fields = Object.keys(key);
+  const isText = "_fts" in key || Object.values(key).includes("text");
+  if (!fields.includes("name") && !isText) return "unrelated";
+
+  if (isText) return "known-text"; // the repo's own createTextIndex()
+
+  if (fields.length === 1 && key.name === 1) {
+    return index.unique === true ? "target" : "known-name-plain";
+  }
+
+  // the repo's own createIndex() compound, which is not unique
+  const compound = ["name", "description", "status", "email"];
+  const isRepoCompound =
+    fields.length === compound.length && compound.every((f, i) => fields[i] === f && key[f] === 1);
+  if (isRepoCompound && index.unique !== true) return "known-compound";
+
+  return "unrecognised";
+}
+
+// Pure decision step: takes the raw output of listIndexes(), returns what to do.
+export function planIndexDrop(indexes) {
+  const buckets = indexes.map((index) => ({ index, bucket: classifyIndex(index) }));
+  const targets = buckets.filter((b) => b.bucket === "target").map((b) => b.index);
+  const unrecognised = buckets.filter((b) => b.bucket === "unrecognised").map((b) => b.index);
+
+  if (unrecognised.length) {
+    return {
+      ok: false,
+      targets: [],
+      unrecognised,
+      reason:
+        `Stopping: ${unrecognised.length} index(es) on \`${COLLECTION}\` involve \`name\` in a ` +
+        `way this script does not recognise (${unrecognised.map((i) => i.name).join(", ")}). ` +
+        "Nothing has been changed.",
+    };
+  }
+  if (!targets.length) {
+    return {
+      ok: false,
+      targets: [],
+      unrecognised: [],
+      reason: `No unique index on \`${COLLECTION}.name\` exists here. There is nothing to drop.`,
+    };
+  }
+  return { ok: true, targets, unrecognised: [], reason: "" };
+}
+
+// Never let the connection string, or any part of it, reach the screen or a log.
+export function redact(text, uri) {
+  let out = String(text ?? "");
+  if (uri) out = out.split(uri).join("<connection string hidden>");
+  return out.replace(/mongodb(\+srv)?:\/\/\S*/gi, "<connection string hidden>");
+}
+
+/* ------------------------------------------------------------------- helpers */
+
+// A collection handle that can ONLY list indexes. Any other call throws here, in
+// this process, before anything at all reaches the database.
+function readOnly(collection) {
+  return new Proxy(collection, {
+    get(target, prop) {
+      if (prop !== "listIndexes") {
+        throw new Error(`Read-only mode: \`${String(prop)}\` is not allowed.`);
+      }
+      return target.listIndexes.bind(target);
+    },
+  });
+}
+
+function describe(index) {
+  const flags = [];
+  if (index.unique === true) flags.push("UNIQUE");
+  if (index.sparse === true) flags.push("sparse");
+  if (index.partialFilterExpression) flags.push("partial");
+  const suffix = flags.length ? `  [${flags.join(", ")}]` : "";
+  return `  ${String(index.name).padEnd(38)} key=${JSON.stringify(index.key)}${suffix}`;
+}
+
+/* ---------------------------------------------------------------------- main */
+
+export async function main() {
+  const drop = process.argv.includes("--drop");
+  const uri = process.env[ENV_VAR];
+
+  if (!uri) {
+    console.error(
+      `\nNothing to connect to.\n\n` +
+        `Set the ${ENV_VAR} environment variable to the connection string of the database\n` +
+        `you want to look at, then run this again. There is deliberately no default — this\n` +
+        `script will never pick a database for you.\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  let host = "(could not be read from the connection string)";
+  let dbName = "";
+  try {
+    const parsed = new URL(uri);
+    host = parsed.host || host;
+    dbName = decodeURIComponent(parsed.pathname.replace(/^\//, ""));
+  } catch {
+    /* a malformed string is the driver's complaint to make, in a moment */
+  }
+  if (!dbName) {
+    console.error(
+      `\nThe ${ENV_VAR} connection string does not name a database.\n` +
+        `Put the database name on the end of it (for example .../iservice365) and run again.\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log("\n----------------------------------------------------------");
+  console.log("  iService365 — organizations.name index check");
+  console.log("----------------------------------------------------------");
+  console.log(`  Cluster host : ${host}`);
+  console.log(`  Database     : ${dbName}`);
+  console.log(`  Collection   : ${COLLECTION}`);
+  console.log(
+    `  Mode         : ${drop ? "DROP — this run can change the database" : "LOOK ONLY — changes nothing"}`,
+  );
+  console.log("----------------------------------------------------------\n");
+  console.log("Check that the cluster host and database above are the ones you meant.\n");
+
+  const client = new MongoClient(uri);
+  try {
+    await client.connect();
+    const collection = client.db(dbName).collection(COLLECTION);
+    const indexes = await readOnly(collection).listIndexes().toArray();
+
+    console.log(`Indexes on \`${COLLECTION}\` right now (${indexes.length}):`);
+    indexes.forEach((index) => console.log(describe(index)));
+    console.log("");
+
+    const plan = planIndexDrop(indexes);
+
+    if (!plan.ok) {
+      console.log(plan.reason + "\n");
+      if (plan.unrecognised.length) {
+        console.log("What to do next: send the list above to a lead before running --drop again.\n");
+        process.exitCode = 1;
+      } else {
+        console.log(
+          "What this means: the leftover unique index is not on this database, so it is not\n" +
+            "the reason a rename failed here. Nothing to do.\n",
+        );
+      }
+      return;
+    }
+
+    const target = plan.targets[0];
+    console.log(
+      `FOUND IT.\n\nAn index named "${target.name}" makes \`${COLLECTION}.name\` UNIQUE, which means\n` +
+        "two organisations are not allowed to share a name. The application no longer wants\n" +
+        "that rule, and it is what makes renaming an organisation fail.\n",
+    );
+
+    if (!drop) {
+      console.log(
+        "Nothing has been changed — this was a look-only run.\n" +
+          "To remove it, run exactly the same command again with --drop on the end.\n",
+      );
+      return;
+    }
+
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const typed = await rl.question(
+      `About to DROP the index "${target.name}" on ${host} / ${dbName}.\n` +
+        `Type the database name (${dbName}) to confirm, or anything else to cancel: `,
+    );
+    rl.close();
+    if (typed.trim() !== dbName) {
+      console.log("\nCancelled. Nothing was changed.\n");
+      process.exitCode = 1;
+      return;
+    }
+
+    console.log(`\nBefore:\n${describe(target)}\n`);
+    await collection.dropIndex(target.name);
+
+    const after = await readOnly(collection).listIndexes().toArray();
+    console.log(`After — indexes on \`${COLLECTION}\` (${after.length}):`);
+    after.forEach((index) => console.log(describe(index)));
+    console.log(
+      `\nDone. "${target.name}" is gone. Two organisations may now share a name, which is what\n` +
+        "the application expects. Ask whoever reported the rename failure to try it again —\n" +
+        "it should save.\n",
+    );
+  } catch (error) {
+    console.error("\nSomething went wrong, and nothing further was attempted:\n");
+    console.error("  " + redact(error?.message || error, uri) + "\n");
+    process.exitCode = 1;
+  } finally {
+    await client.close().catch(() => {});
+  }
+}
+
+// Only run when executed directly, so the test can import the logic above.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await main();
+}

package/test/e2e/guard-invite-scope.e2e.test.mjs

@@ -0,0 +1,368 @@
+// End-to-end proof that a GUARD's invitation is written complete, and only for
+// a site that guard can actually reach.
+//
+// The guard app's Invite Visitor / Invite Contractor screens called the
+// RESIDENT endpoint, `POST /api/visitor-transactions/invite/:inviterId`. Two
+// things were wrong with that and only the first was visible:
+//
+//   1. every request answered 400 - `schemaInviteVisitor` declares no `site`,
+//      `org`, `nric` or `members[].visitorPass`, and validates with no
+//      `allowUnknown`, so Joi refused all four;
+//   2. worse, `site` and `org` were decoration. The resident service reads the
+//      inviter's `site.people` row for the estate. A guard has no such row, so
+//      deleting the refused keys would have turned a visible 400 into an
+//      invitation written with NO site and NO org - an orphan attributed to
+//      nobody, which nothing downstream would ever surface.
+//
+// So this asserts the STORED DOCUMENT, not the status code. A 200 proves
+// nothing here; case 2 is the one that would have caught the orphan write.
+//
+// Cases 10 and 11 are the regression guard: the resident flow still derives its
+// estate from the people row and still refuses a client-supplied site.
+//
+// Everything it talks to is created and thrown away by the harness: an
+// in-process MongoDB replica set, a loopback Redis, a loopback mail sink. No
+// staging or production database is touched. No real identity is used.
+//
+// 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 = "Guard-Invite-Passw0rd!";
+const GUARD = "gi-guard@e2e.example.com";       // reaches site A only
+const OUTSIDER = "gi-outsider@e2e.example.com"; // reaches site C only
+const RESIDENT = "gi-resident@e2e.example.com"; // a real people row on site B
+
+describe("a guard's invitation is complete, and scoped to their own site", { concurrency: 1 }, () => {
+  let h;
+  const id = {};
+  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("--- guard invite: per-case result ---");
+    for (const [verdict, name] of result) console.log(`${verdict}  ${name}`);
+  });
+
+  let guardSid;
+  let outsiderSid;
+  let residentSid;
+
+  const guestBody = (site) => ({
+    type: "guest",
+    expectedCheckIn: "2026-09-10T00:00:00.000Z",
+    arrivalTime: "14:30",
+    duration: "",
+    name: "GI Guest",
+    contact: "00000000",
+    email: "",
+    isOvernightParking: false,
+    numberOfPassengers: 0,
+    purpose: "Delivery",
+    site,
+    // Sent by the app, and DELIBERATELY WRONG here: case 3 proves the server
+    // ignores it and reads the org off the resolved site instead.
+    org: String(id.orgC),
+  });
+
+  record("1 - the guard's own site is accepted", async () => {
+    guardSid = await h.login(GUARD, PASSWORD);
+    outsiderSid = await h.login(OUTSIDER, PASSWORD);
+    residentSid = await h.login(RESIDENT, PASSWORD);
+
+    const res = await h.api("/visitor-transactions/guard-invite", {
+      sid: guardSid,
+      method: "POST",
+      body: guestBody(String(id.siteA)),
+    });
+
+    assert.equal(res.status, 200, JSON.stringify(res.body));
+    assert.ok(res.body.insertedId, "no invitation id came back");
+    id.guestInvite = res.body.insertedId;
+  });
+
+  record("2 - the STORED document carries the right site, org and author", async () => {
+    const row = await h.db
+      .collection("visitor.transactions")
+      .findOne({ _id: new ObjectId(String(id.guestInvite)) });
+
+    assert.ok(row, "the invitation was not written at all");
+
+    // The three fields the resident path would have left empty.
+    assert.equal(String(row.site), String(id.siteA), "wrong or missing site");
+    assert.equal(String(row.org), String(id.orgA), "wrong or missing org");
+    assert.equal(String(row.inviterId), String(id.guard), "wrong author");
+
+    // A gate invitation names no home.
+    assert.equal(row.block, null);
+    assert.equal(row.level, null);
+    assert.equal(row.unit, null);
+    assert.equal(row.unitName, null);
+
+    // And the visitor's own details survived the round trip.
+    assert.equal(row.name, "GI Guest");
+    assert.equal(row.type, "guest");
+    assert.equal(row.status, "approved");
+  });
+
+  record("3 - a wrong `org` in the body is ignored, not written", async () => {
+    const row = await h.db
+      .collection("visitor.transactions")
+      .findOne({ _id: new ObjectId(String(id.guestInvite)) });
+
+    assert.notEqual(
+      String(row.org),
+      String(id.orgC),
+      "the body's org reached the record - a client can misattribute an invitation",
+    );
+  });
+
+  record("4 - a contractor invitation stores nric, company and its members", async () => {
+    const res = await h.api("/visitor-transactions/guard-invite", {
+      sid: guardSid,
+      method: "POST",
+      body: {
+        type: "contractor",
+        expectedCheckIn: "2026-09-10T00:00:00.000Z",
+        contractorType: "home-contractor",
+        name: "GI Contractor",
+        nric: "S0000000A",
+        email: "",
+        contact: "00000000",
+        company: "GI Pte Ltd",
+        plateNumber: "SGX0000A",
+        members: [{ name: "GI Member", nric: "S0000001B", contact: "00000000", visitorPass: "" }],
+        purpose: "Servicing",
+        site: String(id.siteA),
+        org: String(id.orgA),
+      },
+    });
+
+    assert.equal(res.status, 200, JSON.stringify(res.body));
+
+    const row = await h.db
+      .collection("visitor.transactions")
+      .findOne({ _id: new ObjectId(String(res.body.insertedId)) });
+
+    assert.equal(String(row.site), String(id.siteA));
+    assert.equal(String(row.org), String(id.orgA));
+    assert.equal(String(row.inviterId), String(id.guard));
+    assert.equal(row.nric, "S0000000A");
+    assert.equal(row.company, "GI Pte Ltd");
+    assert.equal(row.members[0].name, "GI Member");
+    assert.equal(row.members[0].nric, "S0000001B");
+    // The guard app seeds `visitorPass: ""` and never fills it; the schema
+    // drops it rather than writing an empty string into a field the pass-key
+    // screens read as an array of key references.
+    assert.ok(
+      row.members[0].visitorPass === undefined ||
+        Array.isArray(row.members[0].visitorPass),
+      "an empty string reached the visitorPass field",
+    );
+    // The site does not auto-approve, so a contractor group waits.
+    assert.equal(row.status, "pending");
+  });
+
+  record("5 - a site the guard cannot reach is REFUSED and writes nothing", async () => {
+    const before = await h.db
+      .collection("visitor.transactions")
+      .countDocuments({ site: String(id.siteC) });
+
+    const res = await h.api("/visitor-transactions/guard-invite", {
+      sid: guardSid,
+      method: "POST",
+      body: guestBody(String(id.siteC)),
+    });
+
+    // 404, not 403, and deliberately: `entitleSite` answers for a site outside
+    // the caller's reach exactly as it answers for a site that does not exist,
+    // so site ids cannot be enumerated by watching the difference. Every other
+    // module on this platform refuses the same way.
+    assert.equal(res.status, 404, JSON.stringify(res.body));
+
+    const written = await h.db
+      .collection("visitor.transactions")
+      .countDocuments({ site: String(id.siteC) });
+    assert.equal(written, before, "a refused invitation still wrote a row");
+  });
+
+  record("6 - a site that does not exist is refused identically", async () => {
+    const res = await h.api("/visitor-transactions/guard-invite", {
+      sid: guardSid,
+      method: "POST",
+      body: guestBody(String(new ObjectId())),
+    });
+
+    assert.equal(res.status, 404, JSON.stringify(res.body));
+  });
+
+  record("7 - an unsigned-in caller cannot invite at all", async () => {
+    const res = await h.api("/visitor-transactions/guard-invite", {
+      method: "POST",
+      body: guestBody(String(id.siteA)),
+    });
+
+    assert.equal(res.status, 401);
+  });
+
+  record("8 - a body with no site is refused before any reach check", async () => {
+    const { site, ...noSite } = guestBody(String(id.siteA));
+    const res = await h.api("/visitor-transactions/guard-invite", {
+      sid: guardSid,
+      method: "POST",
+      body: noSite,
+    });
+
+    assert.equal(res.status, 400, JSON.stringify(res.body));
+    assert.match(String(res.body.message ?? ""), /"site" is required/);
+  });
+
+  record("9 - an outsider cannot invite into the guard's estate", async () => {
+    const res = await h.api("/visitor-transactions/guard-invite", {
+      sid: outsiderSid,
+      method: "POST",
+      body: guestBody(String(id.siteA)),
+    });
+
+    assert.equal(res.status, 404, JSON.stringify(res.body));
+  });
+
+  record("10 - REGRESSION: the resident invite still works and still uses the people row", async () => {
+    const res = await h.api(`/visitor-transactions/invite/${String(id.resident)}`, {
+      sid: residentSid,
+      method: "POST",
+      body: {
+        type: "guest",
+        expectedCheckIn: "2026-09-10T00:00:00.000Z",
+        arrivalTime: "10:00",
+        name: "GI Resident Guest",
+        contact: "00000000",
+        purpose: "Visit",
+      },
+    });
+
+    assert.equal(res.status, 200, JSON.stringify(res.body));
+
+    const row = await h.db
+      .collection("visitor.transactions")
+      .findOne({ _id: new ObjectId(String(res.body.insertedId)) });
+
+    // Everything from the people row, exactly as before this change.
+    assert.equal(String(row.site), String(id.siteB));
+    assert.equal(String(row.org), String(id.orgB));
+    assert.equal(String(row.block), String(id.blockB));
+    assert.equal(String(row.level), String(id.levelB));
+    assert.equal(String(row.unit), String(id.unitB));
+    assert.equal(row.unitName, "01-01");
+    assert.equal(String(row.inviterId), String(id.resident));
+  });
+
+  record("11 - REGRESSION: the resident endpoint still refuses a client-supplied site", async () => {
+    const res = await h.api(`/visitor-transactions/invite/${String(id.resident)}`, {
+      sid: residentSid,
+      method: "POST",
+      body: {
+        type: "guest",
+        expectedCheckIn: "2026-09-10T00:00:00.000Z",
+        name: "GI Resident Guest 2",
+        site: String(id.siteA),
+        org: String(id.orgA),
+      },
+    });
+
+    assert.equal(res.status, 400, JSON.stringify(res.body));
+    assert.match(String(res.body.message ?? ""), /"site" is not allowed/);
+  });
+});
+
+async function seed(h) {
+  const now = new Date().toISOString();
+  const orgA = new ObjectId();
+  const orgB = new ObjectId();
+  const orgC = new ObjectId();
+  const siteA = new ObjectId();
+  const siteB = new ObjectId();
+  const siteC = new ObjectId();
+  const roleA = new ObjectId();
+  const roleB = new ObjectId();
+  const roleC = new ObjectId();
+  const blockB = new ObjectId();
+  const levelB = new ObjectId();
+  const unitB = new ObjectId();
+
+  await h.db.collection("organizations").insertMany([
+    { _id: orgA, name: "GI Org A", email: "gia@e2e.example.com", type: "org", nature: "property_management_agency", status: "active", createdAt: now },
+    { _id: orgB, name: "GI Org B", email: "gib@e2e.example.com", type: "org", nature: "property_management_agency", status: "active", createdAt: now },
+    { _id: orgC, name: "GI Org C", email: "gic@e2e.example.com", type: "org", nature: "property_management_agency", status: "active", createdAt: now },
+  ]);
+
+  await h.db.collection("sites").insertMany([
+    { _id: siteA, name: "GI Site A", org: orgA, orgId: orgA, status: "active" },
+    { _id: siteB, name: "GI Site B", org: orgB, orgId: orgB, status: "active" },
+    { _id: siteC, name: "GI Site C", org: orgC, orgId: orgC, status: "active" },
+  ]);
+
+  await h.db.collection("buildings").insertOne({ _id: blockB, name: "Block 1", site: siteB, org: orgB, status: "active" });
+  await h.db.collection("building-levels").insertOne({ _id: levelB, name: "01", block: blockB, site: siteB, org: orgB, status: "active" });
+  await h.db.collection("building-units").insertOne({ _id: unitB, name: "01-01", level: levelB, block: blockB, site: siteB, org: orgB, status: "active" });
+
+  await h.db.collection("roles").insertMany([
+    { _id: roleA, name: "GI Guard A", org: orgA, permissions: ["*"], status: "active" },
+    { _id: roleB, name: "GI Resident B", org: orgB, permissions: ["*"], status: "active" },
+    { _id: roleC, name: "GI Manager C", org: orgC, permissions: ["*"], status: "active" },
+  ]);
+
+  const emails = [GUARD, OUTSIDER, RESIDENT];
+  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 [guard, outsider, resident] = [0, 1, 2].map((i) => users.insertedIds[i]);
+
+  await h.db.collection("members").insertMany([
+    // the guard: pinned to site A, and holding NO site.people row - which is
+    // exactly why the resident invite path cannot serve them
+    { user: guard, org: orgA, siteId: siteA, type: "organization", role: roleA, status: "active" },
+    { user: outsider, org: orgC, siteId: siteC, type: "organization", role: roleC, status: "active" },
+    { user: resident, org: orgB, siteId: siteB, type: "organization", role: roleB, status: "active" },
+  ]);
+
+  // the resident's people row - the estate the resident path copies from
+  await h.db.collection("site.people").insertOne({
+    user: resident,
+    name: "GI Resident",
+    org: orgB,
+    site: siteB,
+    block: blockB,
+    level: levelB,
+    unit: unitB,
+    type: "resident",
+    status: "active",
+    createdAt: now,
+  });
+
+  return { orgA, orgB, orgC, siteA, siteB, siteC, guard, outsider, resident, blockB, levelB, unitB };
+}

package/test/e2e/harness.mjs

@@ -1212,6 +1212,23 @@ function buildApp(nsu, core) {
     siteBillingItems.delete("/id/:id", requireAuth, deleteById);
   }
 
+  // mirrors iservice365-API-core/src/routes/visitor-transaction.route.ts
+  //
+  // `requireInviterScope` lives in API-core and cannot be imported, so the
+  // resident route is mounted with `requireAuth` alone here - the tests on it
+  // are regression tests about what the SERVICE derives, not about that
+  // middleware. The guard route carries no such middleware in API-core either:
+  // its scope check is `requireSiteReach`, inside the controller, which is the
+  // real thing in this process.
+  const visitorTransactions = express.Router();
+  {
+    const { inviteVisitor, inviteVisitorAsGuard } =
+      core.useVisitorTransactionController();
+
+    visitorTransactions.post("/guard-invite", requireAuth, inviteVisitorAsGuard);
+    visitorTransactions.post("/invite/:inviterId", requireAuth, inviteVisitor);
+  }
+
   // mirrors iservice365-API-core/src/routes/guest-management.route.ts
   const visitorGuests = express.Router();
   {
@@ -1499,6 +1516,7 @@ function buildApp(nsu, core) {
   app.use("/api/site-billing-configuration", siteBillingConfiguration);
   app.use("/api/site-billing-items", siteBillingItems);
   app.use("/api/visitor-guests", visitorGuests);
+  app.use("/api/visitor-transactions", visitorTransactions);
   app.use("/api/facility-bookings", facilityBookings);
   app.use("/api/manpower-designations", manpowerDesignations);
   app.use("/api/site-facilities", siteFacilities);