@7365admin1/core 3.80.0 → 3.82.0

package/test/robot-cloud.test.mjs

@@ -0,0 +1,222 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { test } from "node:test";
+
+import {
+  ROBOT_CLOUD_PATHS,
+  ROBOT_STATUS_NAMES,
+  areaColourToHex,
+  hexToAreaColour,
+  isDispatchable,
+  metresToPixel,
+  pixelToMetres,
+  planDayFromJsDay,
+  robotCloudBody,
+  robotCloudSign,
+  robotCloudSigningString,
+  robotCloudTimestamp,
+  robotMode,
+  robotModeFromList,
+} from "./.build/utils/robot-cloud.util.mjs";
+
+/* --------------------------------------------------------------------------
+ * What these guard.
+ *
+ * The cleaning-robot cloud authenticates every request with a SHA-1 over a
+ * string whose field order, separators and url path are all load-bearing: get
+ * any character wrong and every call is rejected with no clue why. And its
+ * status vocabulary is 27 codes deep, where mapping one of them to the wrong
+ * side of "is this robot free?" sends a second job to a robot already cleaning.
+ *
+ * Source: "Robot Cloud API Document (2025.05.27)".
+ * ----------------------------------------------------------------------- */
+
+/* ------------------------------------------------------------------ signing */
+
+test("the signing string is exactly the documented field order", () => {
+  assert.equal(
+    robotCloudSigningString("APPID", "20250520200000", "/portal/x", "SECRET"),
+    "appid=APPID,timestamp=20250520200000,url=/portal/x,secret=SECRET"
+  );
+});
+
+test("the signature is sha1 of that string, in lower-case hex", () => {
+  const expected = createHash("sha1")
+    .update("appid=a,timestamp=20250520200000,url=/portal/x,secret=s")
+    .digest("hex");
+
+  assert.equal(robotCloudSign("a", "20250520200000", "/portal/x", "s"), expected);
+  assert.match(
+    robotCloudSign("a", "20250520200000", "/portal/x", "s"),
+    /^[0-9a-f]{40}$/
+  );
+});
+
+test("the url is part of the hash, so two endpoints never share a signature", () => {
+  // The document's own examples show get-map-list and get-file-url carrying the
+  // SAME sign at the same timestamp, which its own formula makes impossible.
+  // That is a copy-paste in the PDF; this asserts the formula, not the PDF.
+  const a = robotCloudSign("a", "20250520200000", ROBOT_CLOUD_PATHS.mapList, "s");
+  const b = robotCloudSign("a", "20250520200000", ROBOT_CLOUD_PATHS.fileUrl, "s");
+  assert.notEqual(a, b);
+});
+
+test("a path without a leading slash is refused rather than silently signed", () => {
+  assert.throws(
+    () => robotCloudSign("a", "20250520200000", "portal/x", "s"),
+    /must start with/
+  );
+});
+
+test("missing credentials throw instead of signing an empty secret", () => {
+  assert.throws(() => robotCloudSign("", "20250520200000", "/p", "s"), /appid/);
+  assert.throws(() => robotCloudSign("a", "20250520200000", "/p", ""), /secret/);
+});
+
+test("the timestamp is yyyyMMddHHmmss, zero-padded", () => {
+  assert.equal(
+    robotCloudTimestamp(new Date(Date.UTC(2025, 4, 20, 20, 0, 0))),
+    "20250520200000"
+  );
+  // Single-digit month, day, hour, minute and second all pad.
+  assert.equal(
+    robotCloudTimestamp(new Date(Date.UTC(2025, 0, 2, 3, 4, 5))),
+    "20250102030405"
+  );
+});
+
+test("the secret is hashed and never becomes a field in the body", () => {
+  const body = robotCloudBody(
+    "APPID",
+    "SUPER-SECRET",
+    ROBOT_CLOUD_PATHS.robotList,
+    { robotSn: "CASDF03456" },
+    new Date(Date.UTC(2025, 4, 20, 20, 0, 0))
+  );
+
+  assert.deepEqual(Object.keys(body).sort(), [
+    "appid",
+    "robotSn",
+    "sign",
+    "timestamp",
+  ]);
+  assert.equal(
+    JSON.stringify(body).includes("SUPER-SECRET"),
+    false,
+    "the secret must never be transmitted"
+  );
+});
+
+/* ------------------------------------------------------------------ status */
+
+test("an unknown status is UNAVAILABLE, never dispatchable", () => {
+  // The branch that matters: a firmware code we have never seen must not read
+  // as "free, send it a job".
+  for (const unknown of [42, -1, 998, null, undefined, "1", NaN]) {
+    assert.equal(robotMode(unknown), "UNAVAILABLE", `status ${unknown}`);
+    assert.equal(isDispatchable(unknown), false, `status ${unknown}`);
+  }
+});
+
+test("only idle, ready and charged robots are dispatchable", () => {
+  assert.deepEqual(
+    Object.keys(ROBOT_STATUS_NAMES)
+      .map(Number)
+      .filter(isDispatchable)
+      .sort((a, b) => a - b),
+    [1, 9, 24]
+  );
+});
+
+test("every cleaning status is WORKING and refuses a second job", () => {
+  for (const cleaning of [2, 10, 12]) {
+    assert.equal(robotMode(cleaning), "WORKING");
+    assert.equal(isDispatchable(cleaning), false);
+  }
+});
+
+test("switching floor is IN_TRANSIT - the lift case, not an idle robot", () => {
+  assert.equal(robotMode(21), "IN_TRANSIT");
+  assert.equal(isDispatchable(21), false);
+});
+
+test("every documented status has both a name and a mode", () => {
+  for (const code of Object.keys(ROBOT_STATUS_NAMES).map(Number)) {
+    assert.ok(ROBOT_STATUS_NAMES[code], `status ${code} has no name`);
+    assert.notEqual(
+      robotMode(code),
+      undefined,
+      `status ${code} has no mode`
+    );
+  }
+});
+
+test("offline beats a stale cached status", () => {
+  // get-robot-list can report a status from before the robot dropped off.
+  assert.equal(robotModeFromList({ statusFlag: 1, onlineFlag: false }), "UNAVAILABLE");
+  assert.equal(robotModeFromList({ statusFlag: 1, onlineFlag: true }), "IDLE");
+});
+
+/* ------------------------------------------------------------- coordinates */
+
+test("pixels and metres round-trip through the map transform", () => {
+  // The example map from the document.
+  const map = { originX: -49.713, originY: -35.846, resolution: 0.05 };
+  const height = 800;
+
+  const metres = pixelToMetres(504, 416, map, height);
+  const back = metresToPixel(metres.x, metres.y, map, height);
+
+  assert.deepEqual(back, { x: 504, y: 416 });
+});
+
+test("the transform matches the documented formula", () => {
+  const map = { originX: -49.713, originY: -35.846, resolution: 0.05 };
+  const { x, y } = pixelToMetres(100, 200, map, 800);
+
+  assert.equal(Number(x.toFixed(4)), Number((-49.713 + 100 * 0.05).toFixed(4)));
+  assert.equal(
+    Number(y.toFixed(4)),
+    Number((-35.846 + (800 - 200) * 0.05).toFixed(4))
+  );
+});
+
+test("a zero resolution throws rather than dividing by zero", () => {
+  assert.throws(
+    () => metresToPixel(0, 0, { originX: 0, originY: 0, resolution: 0 }, 800),
+    /resolution/
+  );
+});
+
+/* ------------------------------------------------------------------- areas */
+
+test("area colours round-trip between the map's hex and the plan's object", () => {
+  // The two endpoints name the same area two different ways.
+  assert.deepEqual(hexToAreaColour("FF0B0B83"), {
+    r: 255,
+    g: 11,
+    b: 11,
+    a: 131,
+  });
+  assert.equal(areaColourToHex({ r: 255, g: 11, b: 11, a: 131 }), "FF0B0B83");
+  assert.equal(areaColourToHex(hexToAreaColour("B7CAEFFF")), "B7CAEFFF");
+});
+
+test("the plan example's colour survives the round trip", () => {
+  const fromPlan = { r: 186, g: 20, b: 75, a: 255 };
+  assert.deepEqual(hexToAreaColour(areaColourToHex(fromPlan)), fromPlan);
+});
+
+test("a malformed colour is refused, not half-parsed", () => {
+  assert.throws(() => hexToAreaColour("FF0B0B"), /8 hex digits/);
+  assert.throws(() => hexToAreaColour("ZZ0B0B83"), /8 hex digits/);
+  assert.throws(() => areaColourToHex({ r: 256, g: 0, b: 0, a: 0 }), /out of range/);
+});
+
+/* --------------------------------------------------------------- job plans */
+
+test("plan days are 1-7 Monday-Sunday, not JavaScript's 0-6 Sunday-Saturday", () => {
+  assert.equal(planDayFromJsDay(0), 7, "Sunday");
+  assert.equal(planDayFromJsDay(1), 1, "Monday");
+  assert.equal(planDayFromJsDay(6), 6, "Saturday");
+});

package/test/robot-command.test.mjs

@@ -0,0 +1,140 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { parseRobotCommand } from "./.build/utils/robot-cloud.util.mjs";
+
+/* --------------------------------------------------------------------------
+ * POST /robots/:id/command is the only endpoint that makes a physical machine
+ * move, and the vendor API returns no command id - so a command sent wrongly
+ * cannot be identified afterwards, let alone cancelled on its own.
+ *
+ * The rule these guard: fields are REFUSED on the commands that do not use
+ * them, never ignored. Silently dropping a spot polygon from an area command
+ * would send the robot to clean the wrong thing and report success.
+ * ----------------------------------------------------------------------- */
+
+const ok = (body) => {
+  const r = parseRobotCommand(body);
+  assert.equal(r.ok, true, r.ok ? "" : r.message);
+  return r.command;
+};
+const bad = (body, re) => {
+  const r = parseRobotCommand(body);
+  assert.equal(r.ok, false, `expected refusal for ${JSON.stringify(body)}`);
+  if (re) assert.match(r.message, re);
+  return r.message;
+};
+
+const DEFAULTS = { cleanTimes: 1, modeFlag: 1, subModeFlag: 0, levelFlag: 1 };
+
+/* ------------------------------------------------------------- the kinds */
+
+test("a full clean takes the documented defaults", () => {
+  assert.deepEqual(ok({ kind: "full" }), { kind: "full", options: DEFAULTS });
+});
+
+test("an area clean carries its area names", () => {
+  assert.deepEqual(ok({ kind: "area", areas: ["AREA-FF0B0B83"] }), {
+    kind: "area",
+    areas: ["AREA-FF0B0B83"],
+    options: DEFAULTS,
+  });
+});
+
+test("a spot clean carries its polygon", () => {
+  const points = [
+    { x: 504, y: 416 }, { x: 504, y: 480 },
+    { x: 555, y: 480 }, { x: 555, y: 416 },
+  ];
+  assert.deepEqual(ok({ kind: "spot", points }), {
+    kind: "spot", points, options: DEFAULTS,
+  });
+});
+
+test("a return command carries nothing at all", () => {
+  assert.deepEqual(ok({ kind: "return" }), { kind: "return" });
+});
+
+test("an unknown kind is refused", () => {
+  for (const kind of ["mop", "", null, undefined, 1, "FULL"]) {
+    bad({ kind }, /kind must be one of/);
+  }
+  bad(null, /command body is required/);
+  bad("full", /command body is required/);
+});
+
+/* ------------------------------- fields refused where they do not belong */
+
+test("a spot polygon on an area command is REFUSED, not ignored", () => {
+  // Ignoring it would clean the wrong thing and report success.
+  bad({ kind: "area", areas: ["A"], points: [{ x: 1, y: 1 }] }, /points is only valid/);
+});
+
+test("area names on a spot or full command are refused", () => {
+  bad({ kind: "spot", points: [{x:1,y:1},{x:2,y:2},{x:3,y:3}], areas: ["A"] }, /areas is only valid/);
+  bad({ kind: "full", areas: ["A"] }, /areas is only valid/);
+});
+
+test("a return command refuses cleaning options and shapes", () => {
+  // Returning to dock has no mode, no level and no area.
+  for (const extra of [
+    { cleanTimes: 2 }, { modeFlag: 2 }, { subModeFlag: 1 }, { levelFlag: 3 },
+    { areas: ["A"] }, { points: [{ x: 1, y: 1 }] },
+  ]) {
+    bad({ kind: "return", ...extra }, /not valid for a return command/);
+  }
+});
+
+/* --------------------------------------------------------- option ranges */
+
+test("modeFlag, subModeFlag and levelFlag accept only their documented values", () => {
+  // 1 vacuum / 2 washing / 3 dry dust mop — confirmed against the three buttons
+  // on the robot's handlebar.
+  for (const v of [1, 2, 3]) assert.equal(ok({ kind: "full", modeFlag: v }).options.modeFlag, v);
+  for (const v of [0, 4, -1, 1.5, "1", null]) bad({ kind: "full", modeFlag: v }, /modeFlag/);
+
+  for (const v of [0, 1]) assert.equal(ok({ kind: "full", subModeFlag: v }).options.subModeFlag, v);
+  for (const v of [2, -1, "0"]) bad({ kind: "full", subModeFlag: v }, /subModeFlag/);
+
+  for (const v of [1, 2, 3]) assert.equal(ok({ kind: "full", levelFlag: v }).options.levelFlag, v);
+  for (const v of [0, 4, "2"]) bad({ kind: "full", levelFlag: v }, /levelFlag/);
+});
+
+test("cleanTimes accepts 0 (forever) through 99, and nothing else", () => {
+  assert.equal(ok({ kind: "full", cleanTimes: 0 }).options.cleanTimes, 0);
+  assert.equal(ok({ kind: "full", cleanTimes: 99 }).options.cleanTimes, 99);
+  for (const v of [-1, 100, 1.5, "3", null, NaN]) bad({ kind: "full", cleanTimes: v }, /cleanTimes/);
+});
+
+/* ------------------------------------------------------------- the shapes */
+
+test("an area command needs at least one real area name", () => {
+  bad({ kind: "area" }, /areas must be/);
+  bad({ kind: "area", areas: [] }, /areas must be/);
+  bad({ kind: "area", areas: [""] }, /areas must be/);
+  bad({ kind: "area", areas: [1, 2] }, /areas must be/);
+  bad({ kind: "area", areas: "AREA-1" }, /areas must be/);
+});
+
+test("a spot command needs at least 3 points — fewer cannot enclose anything", () => {
+  bad({ kind: "spot" }, /at least 3/);
+  bad({ kind: "spot", points: [{ x: 1, y: 1 }] }, /at least 3/);
+  bad({ kind: "spot", points: [{ x: 1, y: 1 }, { x: 2, y: 2 }] }, /at least 3/);
+});
+
+test("a spot point must be two finite numbers", () => {
+  const three = (p) => [{ x: 1, y: 1 }, { x: 2, y: 2 }, p];
+  for (const p of [
+    { x: 1 }, { y: 1 }, { x: "1", y: 1 }, { x: 1, y: null },
+    { x: 1e999, y: 1 }, null, "1,1", [1, 1],
+  ]) {
+    bad({ kind: "spot", points: three(p) }, /points must be/);
+  }
+});
+
+test("a prototype key cannot masquerade as a command field", () => {
+  // hasOwnProperty, not a bare `in` — otherwise "constructor" reads as present.
+  const cmd = ok({ kind: "full" });
+  assert.deepEqual(cmd.options, DEFAULTS);
+  assert.equal(parseRobotCommand({ kind: "return", constructor: 1 }).ok, true);
+});

package/test/robot-permission.test.mjs

@@ -0,0 +1,133 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  ROBOT_MODULE,
+  ROBOT_PERMISSIONS,
+  allowsRobotAction,
+  allowsRobotListing,
+  robotActionsFor,
+} from "./.build/utils/robot-permission.util.mjs";
+
+/* --------------------------------------------------------------------------
+ * Nothing on the server has ever enforced the five robot permissions - the two
+ * routes carry requireAuth and the estate check, so anybody who can reach an
+ * estate can register a robot into it. This is the missing half.
+ *
+ * The rule that needs the most care is the empty list. Seven365's own staff
+ * role is seeded with `permissions: []`, not `["*"]`, so enforcing an empty
+ * list would refuse the platform owner - while treating EVERY empty list as
+ * "everything" would hand each unconfigured client role the whole module.
+ * ----------------------------------------------------------------------- */
+
+const ALL_ACTIONS = ["seeAll", "add", "update", "seeDetails", "delete"];
+
+test("the permission strings are module:permission, on robot-mgmt", () => {
+  assert.equal(ROBOT_MODULE, "robot-mgmt");
+  assert.deepEqual(ROBOT_PERMISSIONS, {
+    seeAll: "robot-mgmt:see-all-robots",
+    add: "robot-mgmt:add-robot",
+    update: "robot-mgmt:update-robot",
+    seeDetails: "robot-mgmt:see-robot-details",
+    delete: "robot-mgmt:delete-robot",
+  });
+});
+
+/* ------------------------------------------------------------- the wildcard */
+
+test('"*" allows every action', () => {
+  const actor = { permissions: ["*"], roleType: "client" };
+  for (const action of ALL_ACTIONS) {
+    assert.equal(allowsRobotAction(actor, action), true, action);
+  }
+  assert.deepEqual(robotActionsFor(actor), ALL_ACTIONS);
+});
+
+/* -------------------------------------------------- the Seven365 Super Admin */
+
+test("an EMPTY list on a platform-admin role allows everything", () => {
+  // createDefaultUser() seeds Seven365 staff with permissions: [] - and the
+  // owner's requirement is that the Super Admin can do everything, everywhere.
+  const platformStaff = { permissions: [], roleType: "admin" };
+  for (const action of ALL_ACTIONS) {
+    assert.equal(allowsRobotAction(platformStaff, action), true, action);
+  }
+});
+
+test("an empty list on a CLIENT role allows NOTHING", () => {
+  // The other half of the rule. Widening it to every role would hand each
+  // unconfigured client role the whole module.
+  for (const roleType of ["client", "member", "", null, undefined]) {
+    const actor = { permissions: [], roleType };
+    for (const action of ALL_ACTIONS) {
+      assert.equal(
+        allowsRobotAction(actor, action),
+        false,
+        `${String(roleType)} / ${action}`
+      );
+    }
+  }
+});
+
+test("a platform-admin role with a NON-empty list is enforced like any other", () => {
+  // Once somebody has ticked a module, the list means what it says - an admin
+  // role granted only "see" cannot delete.
+  const actor = {
+    permissions: ["robot-mgmt:see-all-robots"],
+    roleType: "admin",
+  };
+  assert.equal(allowsRobotAction(actor, "seeAll"), true);
+  assert.equal(allowsRobotAction(actor, "delete"), false);
+  assert.equal(allowsRobotAction(actor, "add"), false);
+});
+
+/* ------------------------------------------------------------ explicit grant */
+
+test("a non-empty list grants exactly what it names", () => {
+  const actor = {
+    permissions: ["robot-mgmt:see-all-robots", "robot-mgmt:add-robot"],
+    roleType: "client",
+  };
+  assert.deepEqual(robotActionsFor(actor), ["seeAll", "add"]);
+  assert.equal(allowsRobotListing(actor), true);
+  assert.equal(allowsRobotAction(actor, "delete"), false);
+});
+
+test("a permission from another module does not leak across", () => {
+  const actor = {
+    permissions: ["sites:manage-site-modules", "virtual-patrol:see-all-routes"],
+    roleType: "client",
+  };
+  assert.deepEqual(robotActionsFor(actor), []);
+});
+
+test("the bare permission name without its module does not count", () => {
+  // "see-all-robots" is how the catalogue lists it; "robot-mgmt:see-all-robots"
+  // is what a role document holds. Accepting the short form would let a
+  // different module's identically-named permission through.
+  const actor = { permissions: ["see-all-robots"], roleType: "client" };
+  assert.equal(allowsRobotListing(actor), false);
+});
+
+/* ------------------------------------------------------------- fails closed */
+
+test("an unreadable actor is refused", () => {
+  for (const actor of [
+    null,
+    undefined,
+    {},
+    { permissions: null },
+    { permissions: "robot-mgmt:see-all-robots" },
+    { permissions: 5 },
+  ]) {
+    assert.equal(allowsRobotListing(actor), false, JSON.stringify(actor));
+    assert.deepEqual(robotActionsFor(actor), []);
+  }
+});
+
+test("an action that is not one of the five is refused, even with the wildcard", () => {
+  const superuser = { permissions: ["*"], roleType: "admin" };
+  for (const bogus of ["drive", "", null, undefined, "constructor", "toString"]) {
+    assert.equal(allowsRobotAction(superuser, bogus), false, String(bogus));
+  }
+});