@7365admin1/core 3.59.1 → 3.60.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@7365admin1/core",
   "license": "MIT",
-  "version": "3.59.1",
+  "version": "3.60.0",
   "author": "7365admin1",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/test/e2e/resident-self-signup-pinning.e2e.test.mjs

@@ -309,6 +309,104 @@ describe("pre-login resident sign-up cannot manufacture access", { concurrency:
     assert.equal(person?.status, "active");
     assert.equal(person?.remarks, "e2e staff may set this");
   });
+
+  // ---- a document that never uploaded is dropped, AND reported -------------
+
+  record("13. a sign-up whose document upload failed still completes", async () => {
+    // Exactly what the wizard sends after a failed upload: the file is named
+    // and listed, and has no `id` because the upload never returned one.
+    const email = "pin-unsent@e2e.example.com";
+    const res = await h.api("/people/resident/create", {
+      method: "POST",
+      body: {
+        ...genuine(id, email),
+        files: [{ name: "tenancy-agreement.pdf", mimeType: "application/pdf" }],
+      },
+    });
+
+    assert.equal(res.status, 201, JSON.stringify(res.status));
+
+    const person = await stored(email);
+    assert.ok(person, "the applicant must not be lost over an attachment we never received");
+    assert.deepEqual(person.files, []);
+    // ...and the reviewer can now tell this apart from "attached nothing".
+    assert.deepEqual(person.filesNotUploaded, ["tenancy-agreement.pdf"]);
+  });
+
+  record("14. a sign-up whose uploads all landed carries no report at all", async () => {
+    const email = "pin-uploaded@e2e.example.com";
+    const fileId = new ObjectId();
+    await h.db.collection("files").insertOne({
+      _id: fileId,
+      name: "tenancy-agreement.pdf",
+      status: "draft",
+    });
+
+    const res = await h.api("/people/resident/create", {
+      method: "POST",
+      body: {
+        ...genuine(id, email),
+        files: [{ id: fileId.toString(), name: "tenancy-agreement.pdf", mimeType: "application/pdf" }],
+      },
+    });
+
+    assert.equal(res.status, 201, JSON.stringify(res.status));
+
+    const person = await stored(email);
+    assert.equal(person.files?.length, 1);
+    assert.equal(person.files[0].id?.toString(), fileId.toString());
+    // Absent, not empty: a normal registration is written exactly as before.
+    assert.equal("filesNotUploaded" in person, false);
+    // And the document was linked - its status flipped out of draft.
+    const file = await h.db.collection("files").findOne({ _id: fileId });
+    assert.equal(file.status, "active");
+  });
+
+  record("D. a double-tapped Confirm cannot damage the registration that won", async () => {
+    // Defect 4 in the field: nothing disabled the Confirm button, so every tap
+    // sent another POST. This measures what the SECOND one actually does.
+    const email = "pin-double@e2e.example.com";
+    const fileId = new ObjectId();
+    await h.db.collection("files").insertOne({ _id: fileId, name: "lease.pdf", status: "draft" });
+
+    const body = {
+      ...genuine(id, email),
+      files: [{ id: fileId.toString(), name: "lease.pdf", mimeType: "application/pdf" }],
+    };
+
+    const first = await h.api("/people/resident/create", { method: "POST", body });
+    const second = await h.api("/people/resident/create", { method: "POST", body });
+    const third = await h.api("/people/resident/create", { method: "POST", body });
+
+    assert.equal(first.status, 201, JSON.stringify(first.status));
+    // Every later tap dies on the duplicate-account check...
+    assert.equal(second.status, 400, JSON.stringify(second.body));
+    assert.equal(third.status, 400, JSON.stringify(third.body));
+    assert.match(JSON.stringify(second.body), /User already exists/);
+
+    // ...and the registration that won is untouched: one row, its document
+    // still linked and still active. A double submit is NOT what empties Files.
+    const rows = await h.db.collection("site.people").find({ email }).toArray();
+    assert.equal(rows.length, 1);
+    assert.equal(rows[0].files?.length, 1);
+    assert.equal(rows[0].files[0].id?.toString(), fileId.toString());
+    assert.equal("filesNotUploaded" in rows[0], false);
+    assert.equal((await h.db.collection("files").findOne({ _id: fileId })).status, "active");
+    assert.equal(await h.db.collection("users").countDocuments({ email }), 1);
+  });
+
+  record("15. the caller cannot plant the report itself", async () => {
+    const email = "pin-planted@e2e.example.com";
+    const res = await h.api("/people/resident/create", {
+      method: "POST",
+      body: { ...genuine(id, email), filesNotUploaded: ["planted-by-the-caller.pdf"] },
+    });
+
+    assert.equal(res.status, 201, JSON.stringify(res.status));
+
+    const person = await stored(email);
+    assert.equal("filesNotUploaded" in person, false);
+  });
 });
 
 async function seed(h) {

package/test/org-role-selfheal.test.mjs

@@ -0,0 +1,282 @@
+/**
+ * The default-role SELF-HEAL: a write triggered by a read.
+ *
+ * `seedDefaultOrgRoles` only runs when an organisation is CREATED, so the 73
+ * organisations that were created before it shipped still hold not one role.
+ * `healOrgDefaultRoles` gives them the same two roles the first time somebody
+ * reads their empty roles list.
+ *
+ * That is an insert on a read path in a live multi-tenant system running on
+ * more than one instance, so every property that makes it safe is asserted
+ * here, and each one is a way this could take the platform down:
+ *
+ *   1. it fires ONLY on an organisation holding zero roles — one role means
+ *      skip, no exceptions, the same rule the backfill tool uses;
+ *   2. two simultaneous readers of the same organisation produce TWO roles, not
+ *      four — the claim is the guard, not a non-atomic read;
+ *   3. it never emits an `org`-less role: that is a CLIENT TEMPLATE, one
+ *      document shared by every client invited with it, and one of those is
+ *      what took every client's modules away on 2026-09-07;
+ *   4. it cannot fail the read it hangs off — a claim, count, nature lookup or
+ *      insert that throws returns 0 and throws nothing;
+ *   5. it is insert-only: no role, member, invitation, user or organisation is
+ *      updated, deleted or repointed.
+ *
+ * Nothing here opens a socket or a database. Every dependency is passed in,
+ * which is also how the production code is written.
+ */
+
+import { strict as assert } from "node:assert";
+import test from "node:test";
+import { readFileSync } from "node:fs";
+
+import { healOrgDefaultRoles } from "./.build/utils/org-default-roles.util.mjs";
+
+const ORG = "68b0c1d2e3f4a5b6c7d8e9f0";
+
+const tick = () => new Promise((resolve) => setImmediate(resolve));
+
+/**
+ * A stand-in for `org-role-seed.repo.ts`.
+ *
+ * `claimSeed` is an `insertOne` of a row whose `_id` IS the organisation id, so
+ * MongoDB decides the winner atomically, inside the collection's `_id` index,
+ * before any caller can observe anything. The fake therefore decides and
+ * records SYNCHRONOUSLY and only then yields — modelling the database, not a
+ * read-then-write in application code, which is precisely the thing that would
+ * not be safe.
+ */
+function fakeWorld({
+  roleCount = 0,
+  nature = "security_agency",
+  failOn = null,
+} = {}) {
+  const claimed = new Set();
+  const written = [];
+  const released = [];
+
+  const boom = (name) => {
+    if (failOn === name) throw new Error(`${name} exploded`);
+  };
+
+  return {
+    written,
+    released,
+    claimed,
+    deps: {
+      async claim(org) {
+        boom("claim");
+        const key = String(org);
+        const won = !claimed.has(key);
+        claimed.add(key);
+        await tick();
+        return won;
+      },
+      async release(org) {
+        released.push(String(org));
+        claimed.delete(String(org));
+      },
+      async countRoles() {
+        boom("countRoles");
+        await tick();
+        return roleCount;
+      },
+      async getNature() {
+        boom("getNature");
+        await tick();
+        return nature;
+      },
+      async addRole(role) {
+        boom("addRole");
+        await tick();
+        written.push(role);
+        return role;
+      },
+    },
+  };
+}
+
+test("an organisation holding zero roles gets the same two roles a new one gets", async () => {
+  const world = fakeWorld();
+
+  const seeded = await healOrgDefaultRoles(world.deps, ORG);
+
+  assert.equal(seeded, 2, "two roles, exactly as a paid signup writes");
+  assert.equal(world.written.length, 2);
+
+  for (const role of world.written) {
+    assert.equal(role.name, "owner");
+    assert.deepEqual(role.permissions, ["*"]);
+    assert.equal(role.default, true, "the repository path writes `default: true`");
+    assert.equal(role.org, ORG, "every seeded role carries the organisation");
+  }
+
+  assert.deepEqual(
+    world.written.map((r) => r.type).sort(),
+    ["organization", "security_agency"],
+    "one organisation role and one typed by the organisation's nature",
+  );
+});
+
+test("an organisation holding one role is left completely alone", async () => {
+  const world = fakeWorld({ roleCount: 1 });
+
+  const seeded = await healOrgDefaultRoles(world.deps, ORG);
+
+  assert.equal(seeded, 0, "one role means skip — no exceptions");
+  assert.deepEqual(world.written, [], "nothing was written");
+});
+
+test("the count is re-read UNDER the claim, so a role created meanwhile still stops it", async () => {
+  // The caller's empty list can be up to 15 minutes stale (Redis), and a role
+  // can be created between that list and this insert. The count that decides
+  // is the one taken after the claim is won, straight from the collection.
+  let roles = 0;
+  const world = fakeWorld();
+  world.deps.countRoles = async () => {
+    await tick();
+    return roles;
+  };
+  roles = 1;
+
+  assert.equal(await healOrgDefaultRoles(world.deps, ORG), 0);
+  assert.deepEqual(world.written, []);
+});
+
+test("a second load of the same organisation is a no-op", async () => {
+  const world = fakeWorld();
+
+  assert.equal(await healOrgDefaultRoles(world.deps, ORG), 2);
+  assert.equal(await healOrgDefaultRoles(world.deps, ORG), 0, "the claim is already held");
+  assert.equal(world.written.length, 2, "still two roles, not four");
+});
+
+test("two simultaneous loads of the same organisation do not create four roles", async () => {
+  // Both callers see a count of zero — the exact race the claim exists for.
+  const world = fakeWorld({ roleCount: 0 });
+
+  const results = await Promise.all([
+    healOrgDefaultRoles(world.deps, ORG),
+    healOrgDefaultRoles(world.deps, ORG),
+  ]);
+
+  assert.deepEqual(
+    results.sort(),
+    [0, 2],
+    "exactly one caller seeded; the other did nothing at all",
+  );
+  assert.equal(world.written.length, 2, "two roles in total, not four");
+});
+
+test("ten simultaneous loads still produce exactly one set", async () => {
+  const world = fakeWorld({ roleCount: 0 });
+
+  const results = await Promise.all(
+    Array.from({ length: 10 }, () => healOrgDefaultRoles(world.deps, ORG)),
+  );
+
+  assert.equal(
+    results.filter((n) => n > 0).length,
+    1,
+    "one winner out of ten",
+  );
+  assert.equal(world.written.length, 2);
+});
+
+test("it never emits an org-less role", async () => {
+  for (const org of [null, undefined, ""]) {
+    const world = fakeWorld();
+
+    assert.equal(await healOrgDefaultRoles(world.deps, org), 0);
+    assert.deepEqual(world.written, [], "no organisation, no role — ever");
+    assert.equal(world.claimed.size, 0, "it does not even take a claim");
+  }
+});
+
+test("a nature that is not an app produces the organisation role only, still org-scoped", async () => {
+  const world = fakeWorld({ nature: "property_owner" });
+
+  assert.equal(await healOrgDefaultRoles(world.deps, ORG), 1);
+  assert.equal(world.written[0].type, "organization");
+  assert.equal(world.written[0].org, ORG);
+});
+
+test("an insert that fails does not break the read, and gives the claim back", async () => {
+  const world = fakeWorld({ failOn: "addRole" });
+
+  const seeded = await healOrgDefaultRoles(world.deps, ORG);
+
+  assert.equal(seeded, 0, "it resolves rather than rejecting");
+  assert.deepEqual(world.released, [ORG], "the claim is released so a later read may retry");
+});
+
+test("a count that fails does not break the read", async () => {
+  const world = fakeWorld({ failOn: "countRoles" });
+
+  assert.equal(await healOrgDefaultRoles(world.deps, ORG), 0);
+  assert.deepEqual(world.written, []);
+  assert.deepEqual(world.released, [ORG]);
+});
+
+test("a claim that fails does not break the read, and nothing is released", async () => {
+  const world = fakeWorld({ failOn: "claim" });
+
+  assert.equal(await healOrgDefaultRoles(world.deps, ORG), 0);
+  assert.deepEqual(world.written, []);
+  assert.deepEqual(world.released, [], "no claim was taken, so there is none to give back");
+});
+
+test("a nature lookup that fails does not break the read", async () => {
+  const world = fakeWorld({ failOn: "getNature" });
+
+  assert.equal(await healOrgDefaultRoles(world.deps, ORG), 0);
+  assert.deepEqual(world.written, []);
+});
+
+test("a release that itself fails is still swallowed", async () => {
+  const world = fakeWorld({ failOn: "addRole" });
+  world.deps.release = async () => {
+    throw new Error("release exploded");
+  };
+
+  assert.equal(
+    await healOrgDefaultRoles(world.deps, ORG),
+    0,
+    "the read survives even when the cleanup cannot run",
+  );
+});
+
+test("the trigger fires on a type-filtered list, and not on a search, a site or page two", () => {
+  // The write hangs off `role.controller.ts getRoles`.
+  //
+  // `type` is deliberately ALLOWED. Every live call site passes one —
+  // `RolePermissionMain type="organization"`, `InvitationForm props.app`,
+  // `MemberMain props.type` — so a trigger that required an unfiltered list
+  // would never fire in production, and the whole self-heal would be dead code
+  // that reads exactly like a working one. An empty type-filtered page is not
+  // proof of zero roles, and it is not asked to be: the unfiltered count taken
+  // UNDER the claim is what decides, and that is asserted above.
+  //
+  // A search miss is user-driven and high-cardinality, a site-scoped page is
+  // empty for organisation-wide roles that plainly exist, and page two of
+  // anything is empty by arithmetic. None of those may trigger a write.
+  const source = readFileSync(
+    new URL("../src/controllers/role.controller.ts", import.meta.url),
+    "utf8",
+  );
+
+  const guard = source.slice(
+    source.indexOf("const listIsWholeOrg ="),
+    source.indexOf("const seeded = await healDefaultRoles("),
+  );
+
+  assert.ok(guard.includes("org &&"), "only when an organisation was named");
+  assert.ok(guard.includes("!search"), "not a search result");
+  assert.ok(guard.includes("!site"), "not a site-scoped list");
+  assert.ok(guard.includes("page === 1"), "not page two of a list");
+  assert.ok(guard.includes("?.length === 0"), "only when the page is empty");
+  assert.ok(
+    !guard.includes("!type"),
+    "a type filter must NOT block the heal - every live call site sends one",
+  );
+});

package/test/self-signup-files.test.mjs

@@ -3,8 +3,13 @@ import test from "node:test";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
-import { dropUnsentFiles } from "./.build/utils/self-signup-files.util.mjs";
-import { schemaResidentSelfSignUp, schemaPerson } from "./.build/models/person.model.mjs";
+import {
+  dropUnsentFiles,
+  unsentFileNames,
+  MAX_UNSENT_FILE_NAMES,
+  MAX_UNSENT_FILE_NAME_LENGTH,
+} from "./.build/utils/self-signup-files.util.mjs";
+import { schemaResidentSelfSignUp, schemaPerson, MPerson } from "./.build/models/person.model.mjs";
 
 /**
  * Resident sign-up outage, 2026-09-08.
@@ -150,5 +155,122 @@ test("the filter runs on the self-signup path, before validation, and nowhere el
   // authenticated `add`/`updateById` paths, staff stop being told about a
   // client that is silently losing their attachments.
   assert.equal(controller.match(/dropUnsentFiles\(/g)?.length, 1);
-  assert.match(controller, /import \{ dropUnsentFiles \} from "\.\.\/utils\/self-signup-files\.util"/);
+  // Both helpers come from that one module, whatever shape the import takes.
+  const importBlock = controller.match(/import \{[\s\S]*?\} from "\.\.\/utils\/self-signup-files\.util";/);
+  assert.ok(importBlock, "self-signup-files.util is no longer imported by the controller");
+  assert.ok(importBlock[0].includes("dropUnsentFiles"));
+  assert.ok(importBlock[0].includes("unsentFileNames"));
+});
+
+/**
+ * 2026-09-08, second report. The fix above kept the applicant, and then hid the
+ * problem: `Files:` renders empty whether the resident attached nothing or
+ * attached something we never received. The owner's own registration was
+ * APPROVED in that state, without its tenancy agreement. So the entries we drop
+ * are now recorded on the person as `filesNotUploaded`, and the console has
+ * something to show.
+ */
+
+test("what was dropped is reported, by name, in order", () => {
+  const second = { name: "vehicle-registration.pdf", mimeType: "application/pdf" };
+  const body = { ...base(), files: [validFile, unsentFile, second] };
+
+  assert.deepEqual(unsentFileNames(body), [unsentFile.name, second.name]);
+  // And the two halves agree: what is kept plus what is reported is the input.
+  assert.deepEqual(dropUnsentFiles(body).files, [validFile]);
+});
+
+test("a registration where every upload landed reports nothing", () => {
+  assert.deepEqual(unsentFileNames({ ...base(), files: [validFile] }), []);
+  assert.deepEqual(unsentFileNames({ ...base(), files: [] }), []);
+  assert.deepEqual(unsentFileNames(base()), []);
+  assert.deepEqual(unsentFileNames({ ...base(), files: null }), []);
+  assert.deepEqual(unsentFileNames({ ...base(), files: "nonsense" }), []);
+  assert.deepEqual(unsentFileNames(undefined), []);
+});
+
+test("an unnamed dropped entry still reports something a reviewer can read", () => {
+  assert.deepEqual(unsentFileNames({ files: [{ mimeType: "application/pdf" }] }), ["Unnamed document"]);
+  assert.deepEqual(unsentFileNames({ files: [{ name: "   " }] }), ["Unnamed document"]);
+  assert.deepEqual(unsentFileNames({ files: [{ name: 42 }] }), ["Unnamed document"]);
+  // A null entry is not an unsent file, it is nonsense - and must not crash.
+  assert.deepEqual(unsentFileNames({ files: [null, undefined] }), []);
+});
+
+test("the caller cannot use it as free storage: bounded in count and in length", () => {
+  const many = Array.from({ length: MAX_UNSENT_FILE_NAMES + 5 }, (_, i) => ({ name: `doc-${i}.pdf` }));
+  assert.equal(unsentFileNames({ files: many }).length, MAX_UNSENT_FILE_NAMES);
+
+  const long = unsentFileNames({ files: [{ name: "x".repeat(5000) }] });
+  assert.equal(long[0].length, MAX_UNSENT_FILE_NAME_LENGTH);
+});
+
+test("the report is display text only - it is not accepted from the caller", () => {
+  // stripUnknown means a caller who sends `filesNotUploaded` has it dropped,
+  // exactly like `status` and `platform`. Only the controller sets it.
+  const { error, value } = selfSignUp({ ...base(), filesNotUploaded: ["planted.pdf"] });
+  assert.equal(error, undefined);
+  assert.equal("filesNotUploaded" in value, false);
+
+  // But the finished payload the controller builds must survive MPerson, which
+  // runs schemaPerson over it and refuses unknown keys.
+  const finished = { ...base(), isOwner: true, status: "pending", platform: "mobile", filesNotUploaded: ["a.pdf"] };
+  assert.equal(schemaPerson.validate(finished, { abortEarly: false }).error, undefined);
+});
+
+test("the controller records the dropped names from the ORIGINAL body, and only when there are some", () => {
+  const selfSignUpFn = controller.slice(
+    controller.indexOf("async function addResidentSelfSignUp"),
+    controller.indexOf("async function add("),
+  );
+
+  assert.match(selfSignUpFn, /unsentFileNames\(req\.body\)/);
+  // Read from req.body, not from the already-filtered `body` - which would
+  // always be empty and make the whole thing a silent no-op.
+  assert.equal(selfSignUpFn.includes("unsentFileNames(body)"), false);
+  assert.match(selfSignUpFn, /filesNotUploaded: notUploaded/);
+  assert.match(selfSignUpFn, /notUploaded\.length > 0 \?/);
+
+  // Self-signup only. The authenticated staff path must not start writing it.
+  assert.equal(controller.match(/unsentFileNames\(/g)?.length, 1);
+});
+
+/**
+ * `MPerson` does not return the object it was given: it returns an explicit
+ * whitelist, and anything not named there is dropped on the way to the
+ * database. Every unit test above passed with `filesNotUploaded` never reaching
+ * Mongo at all - only the end-to-end run caught it. Pin it here so the next
+ * field added to the payload is not lost the same way.
+ */
+test("MPerson carries the report through to the document it writes", () => {
+  const person = {
+    name: "Resident Test",
+    email: "resident@example.com",
+    isOwner: true,
+    site: "0123456789abcdef01234567",
+    status: "pending",
+    platform: "mobile",
+    files: [],
+    filesNotUploaded: ["tenancy-agreement.pdf"],
+  };
+
+  assert.deepEqual(MPerson(person).filesNotUploaded, ["tenancy-agreement.pdf"]);
+});
+
+test("a person with nothing to report gets no key at all, not an undefined one", () => {
+  // A fresh object each time: MPerson rewrites `site` into an ObjectId in
+  // place, so a second call on the same literal fails on "site must be a string".
+  const person = (extra) => ({
+    name: "Resident Test",
+    email: "resident@example.com",
+    isOwner: true,
+    site: "0123456789abcdef01234567",
+    files: [],
+    ...extra,
+  });
+
+  // `filesNotUploaded: undefined` would be written into every person document
+  // ever created, on every path, which is exactly what the conditional avoids.
+  assert.equal("filesNotUploaded" in MPerson(person()), false);
+  assert.equal("filesNotUploaded" in MPerson(person({ filesNotUploaded: [] })), false);
 });