@7365admin1/core 3.42.1 → 3.42.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@7365admin1/core",
   "license": "MIT",
-  "version": "3.42.1",
+  "version": "3.42.2",
   "author": "7365admin1",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -13,7 +13,8 @@
     "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:e2e": "yarn build && node --test --test-concurrency=1 --test-timeout=600000 \"test/e2e/*.test.mjs\""
+    "test:e2e": "yarn build && node --test --test-concurrency=1 --test-timeout=600000 \"test/e2e/*.test.mjs\"",
+    "test:anpr": "tsup src/utils/camera-alert.util.ts src/utils/dahua-protocol.util.ts --format esm --out-dir test/.build/utils --no-dts --silent && node --test \"test/camera-alert.util.test.mjs\" \"test/dahua-protocol.util.test.mjs\""
   },
   "devDependencies": {
     "@changesets/cli": "^2.26.0",

package/test/camera-alert.util.test.mjs

@@ -0,0 +1,109 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  CAMERA_RECONNECT_MS,
+  cameraCredentialsMessage,
+  cameraRecoveredMessage,
+  cameraUnreachableMessage,
+  describeCamera,
+  shouldAlertOnFailure,
+} from "./.build/utils/camera-alert.util.mjs";
+
+/* --------------------------------------------------------------------------
+ * 1. The label. The reported alert read "[Seventh Condominium-both]" — the
+ *    site's name with the camera's direction enum glued on. No alert may ever
+ *    show a raw enum again.
+ * ----------------------------------------------------------------------- */
+
+test("a direction value is never shown to the operator as a raw enum", () => {
+  for (const direction of ["entry", "exit", "both", "none", "visitors", "residents", ""]) {
+    const text = cameraUnreachableMessage({ siteName: "Seventh Condominium", direction });
+    assert.doesNotMatch(text, /Seventh Condominium-/, `"${direction}" was glued to the site name`);
+    assert.doesNotMatch(text, /\bboth\b|\bvisitors\b|\bresidents\b/);
+  }
+});
+
+test("the exact reported label is gone", () => {
+  assert.equal(
+    describeCamera({ siteName: "Seventh Condominium", direction: "both" }),
+    "The entry and exit ANPR camera at Seventh Condominium"
+  );
+});
+
+test("a camera's own name is preferred over its direction", () => {
+  assert.equal(
+    describeCamera({ name: "Main Gate", siteName: "Seventh Condominium", direction: "both" }),
+    'Camera "Main Gate" at Seventh Condominium'
+  );
+});
+
+test("a camera with neither name nor direction still reads as a sentence", () => {
+  assert.equal(describeCamera({ siteName: "Seventh Condominium" }), "The ANPR camera at Seventh Condominium");
+  assert.equal(describeCamera(null), "The ANPR camera");
+  assert.equal(describeCamera({ name: null, siteName: null, direction: null }), "The ANPR camera");
+});
+
+/* --------------------------------------------------------------------------
+ * 2. The guidance. Telling an operator to deactivate a barrier camera to stop
+ *    a notification is the defect, not a wording preference.
+ * ----------------------------------------------------------------------- */
+
+test("no operator message offers deactivation as the remedy", () => {
+  const camera = { siteName: "Seventh Condominium", direction: "both" };
+  for (const text of [
+    cameraUnreachableMessage(camera),
+    cameraCredentialsMessage(camera),
+    cameraRecoveredMessage(camera),
+  ]) {
+    assert.doesNotMatch(text, /inactive/i);
+    assert.doesNotMatch(text, /deactivat/i);
+  }
+});
+
+test("the fault message says what is broken and who fixes it", () => {
+  const text = cameraUnreachableMessage({ siteName: "Seventh Condominium", direction: "both" });
+  assert.match(text, /not responding/i);
+  assert.match(text, /barrier/i);
+  assert.match(text, /technician|installer/i);
+});
+
+test("a credentials failure sends the operator to the setting, not to the camera", () => {
+  const text = cameraCredentialsMessage({ siteName: "Seventh Condominium", direction: "entry" });
+  assert.match(text, /username or password/i);
+  assert.match(text, /Site Settings/i);
+});
+
+/* --------------------------------------------------------------------------
+ * 3. The pacing. The old code alerted on every reconnect attempt — once per
+ *    10 s, forever, into a 20 s snackbar, so the toast never cleared.
+ * ----------------------------------------------------------------------- */
+
+test("the first failure is always reported", () => {
+  assert.equal(shouldAlertOnFailure(1), true);
+});
+
+test("a camera that stays down does not alert on every reconnect", () => {
+  const alerts = [];
+  for (let n = 1; n <= 360; n++) if (shouldAlertOnFailure(n)) alerts.push(n);
+  // 360 attempts at 10 s is one hour of continuous outage.
+  assert.equal(alerts.length, 7, `one hour of downtime raised ${alerts.length} alerts`);
+  assert.deepEqual(alerts, [1, 6, 30, 90, 180, 270, 360]);
+});
+
+test("alerts never come faster than the snackbar can clear", () => {
+  // The web snackbar shows for 20 s. Two alerts closer together than that would
+  // keep a red toast on screen permanently, which is the reported symptom.
+  let previous = 0;
+  for (let n = 1; n <= 360; n++) {
+    if (!shouldAlertOnFailure(n)) continue;
+    if (previous) assert.ok((n - previous) * CAMERA_RECONNECT_MS > 20_000);
+    previous = n;
+  }
+});
+
+test("nothing is reported while the camera is connected", () => {
+  assert.equal(shouldAlertOnFailure(0), false);
+  assert.equal(shouldAlertOnFailure(-1), false);
+  assert.equal(shouldAlertOnFailure(1.5), false);
+});

package/test/dahua-protocol.util.test.mjs

@@ -0,0 +1,217 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  DAHUA_AUTH_ATTEMPTS_BEFORE_ALERT,
+  DAHUA_LOCK_CHECK_DURATION_SEC,
+  DAHUA_LOCK_LOGIN_TIMES,
+  buildPlateInsertEndpoint,
+  buildPlateRemoveEndpoint,
+  buildPlateUpdateEndpoint,
+  classifyDahuaFailure,
+  classifyDahuaStatus,
+  dahuaAuthBackoffMs,
+  maxAuthAttemptsPerLockWindow,
+} from "./.build/utils/dahua-protocol.util.mjs";
+
+/* --------------------------------------------------------------------------
+ * 1. The reconnect loop must stay inside the device's login-failure budget.
+ *
+ * The old loop retried every 1000 ms up to 10 times, i.e. 10 failed logins
+ * inside 10 seconds, against a device that locks the account after 3 failures
+ * in 30 seconds - for 1800 seconds. These assertions fail on that schedule.
+ * ------------------------------------------------------------------------ */
+
+test("no more than one authentication attempt lands in a lockout window", () => {
+  const worst = maxAuthAttemptsPerLockWindow(20);
+
+  assert.ok(
+    worst < DAHUA_LOCK_LOGIN_TIMES,
+    `${worst} attempts fit in a ${DAHUA_LOCK_CHECK_DURATION_SEC}s window; the device locks out at ${DAHUA_LOCK_LOGIN_TIMES}`,
+  );
+  assert.equal(worst, 1);
+});
+
+test("every authentication backoff outlasts the device's counting window", () => {
+  const windowMs = DAHUA_LOCK_CHECK_DURATION_SEC * 1000;
+
+  for (let failures = 1; failures <= 10; failures++) {
+    assert.ok(
+      dahuaAuthBackoffMs(failures) > windowMs,
+      `backoff after ${failures} failures was ${dahuaAuthBackoffMs(failures)}ms, not longer than ${windowMs}ms`,
+    );
+  }
+});
+
+test("the backoff escalates and then holds at a cap", () => {
+  assert.equal(dahuaAuthBackoffMs(1), 60_000);
+  assert.equal(dahuaAuthBackoffMs(2), 300_000);
+  assert.equal(dahuaAuthBackoffMs(3), 900_000);
+  assert.equal(dahuaAuthBackoffMs(99), 900_000);
+  // Defensive: a caller that has not incremented yet must not get 0ms.
+  assert.equal(dahuaAuthBackoffMs(0), 60_000);
+});
+
+test("we alert the operator while still under the device's failure limit", () => {
+  assert.ok(DAHUA_AUTH_ATTEMPTS_BEFORE_ALERT < DAHUA_LOCK_LOGIN_TIMES);
+});
+
+/* --------------------------------------------------------------------------
+ * 2. 401 and 403 mean what the specification says they mean.
+ *
+ * Spec §3.4: 401 = digest challenge / expired nonce; 403 = wrong credentials.
+ * The old code threw the credentials warning on 401 and killed the listener on
+ * 403 as "account locked" - the opposite of both.
+ * ------------------------------------------------------------------------ */
+
+test("401 is a challenge to answer, not a credentials failure", () => {
+  assert.equal(classifyDahuaStatus(401), "challenge");
+  assert.equal(classifyDahuaFailure("401 Unauthorized"), "challenge");
+  assert.equal(classifyDahuaFailure("Dahua response: invalid authority"), "challenge");
+});
+
+test("403 is a credentials rejection and must stop the listener", () => {
+  assert.equal(classifyDahuaStatus(403), "rejected");
+  assert.equal(classifyDahuaFailure("Request failed with 403 Forbidden"), "rejected");
+});
+
+test("a 403 is never mistaken for a retryable challenge", () => {
+  // "403 Forbidden - unauthorized" contains both markers; the refusal wins.
+  assert.equal(classifyDahuaFailure("403 Forbidden - unauthorized"), "rejected");
+});
+
+test("network faults are transient and keep the ordinary reconnect", () => {
+  assert.equal(classifyDahuaFailure("socket hang up"), "transient");
+  assert.equal(classifyDahuaFailure("Body Timeout Error"), "transient");
+  assert.equal(classifyDahuaFailure("ECONNRESET"), "transient");
+  assert.equal(classifyDahuaFailure(undefined), "transient");
+});
+
+test("other statuses behave as before", () => {
+  assert.equal(classifyDahuaStatus(200), "proceed");
+  assert.equal(classifyDahuaStatus(undefined), "proceed");
+  assert.equal(classifyDahuaStatus(400), "fatal");
+  assert.equal(classifyDahuaStatus(500), "fatal");
+});
+
+/* --------------------------------------------------------------------------
+ * 3. Percent-encoding (spec §3.2).
+ *
+ * The realistic failure is a plate or an owner name with a space or an "&":
+ * unencoded, the "&" ends the value and the remainder is read by the device as
+ * further CGI parameters on an already-authenticated request.
+ * ------------------------------------------------------------------------ */
+
+const SPACED_PLATE = "SGX 1234 A";
+const HOSTILE_OWNER = "Tan & Sons/Co";
+
+test("a plate containing a space is encoded, not split", () => {
+  const url = buildPlateUpdateEndpoint({
+    mode: "TrafficRedList",
+    recno: "42",
+    plateNumber: SPACED_PLATE,
+    start: "2026-08-09 00:00:00",
+    end: "2036-08-09 00:00:00",
+    owner: "Resident",
+    openGate: "true",
+  });
+
+  assert.ok(url.includes("PlateNumber=SGX%201234%20A"));
+  assert.ok(!url.includes("PlateNumber=SGX 1234 A"));
+  assert.ok(url.includes("BeginTime=2026-08-09%2000%3A00%3A00"));
+});
+
+test("an owner name cannot inject extra CGI parameters", () => {
+  const url = buildPlateUpdateEndpoint({
+    mode: "TrafficRedList",
+    recno: "42",
+    plateNumber: "SGX1234A",
+    owner: HOSTILE_OWNER,
+  });
+
+  assert.ok(url.includes("MasterOfCar=Tan%20%26%20Sons%2FCo"));
+
+  // The whole query must still be the parameters we intended, no more.
+  const names = url
+    .split("?")[1]
+    .split("&")
+    .map((pair) => pair.split("=")[0]);
+
+  assert.deepEqual(names, [
+    "action",
+    "name",
+    "recno",
+    "PlateNumber",
+    "BeginTime",
+    "CancelTime",
+    "+OpenGate",
+    "MasterOfCar",
+  ]);
+});
+
+test("bulk insert encodes every interpolated value", () => {
+  const url = buildPlateInsertEndpoint({
+    mode: "TrafficRedList",
+    plateNumber: SPACED_PLATE,
+    vehicleType: "Light Truck",
+    vehicleColor: "Blue & White",
+    start: "2026-08-09 00:00:00",
+    end: "2036-08-09 00:00:00",
+    owner: HOSTILE_OWNER,
+    openGate: "true",
+  });
+
+  assert.ok(url.includes("PlateNumber=SGX%201234%20A"));
+  assert.ok(url.includes("VehicleType=Light%20Truck"));
+  assert.ok(url.includes("VehicleColor=Blue%20%26%20White"));
+  assert.ok(url.includes("MasterOfCar=Tan%20%26%20Sons%2FCo"));
+
+  // One "&" per parameter separator and nothing else.
+  assert.equal(url.split("&").length - 1, 8);
+});
+
+test("remove encodes its identifiers too", () => {
+  const url = buildPlateRemoveEndpoint({ recno: "4 2", mode: "TrafficBlackList" });
+  assert.equal(
+    url,
+    "/cgi-bin/recordUpdater.cgi?action=remove&recno=4%202&name=TrafficBlackList",
+  );
+});
+
+/* --------------------------------------------------------------------------
+ * 4. Regression guard: `+OpenGate` is deliberately untouched.
+ *
+ * The specification names this field AuthorityList.OpenGate but gives no
+ * default for when it is omitted, so correcting it blind could change what a
+ * live barrier does. It stays exactly as it has always gone on the wire until
+ * someone reads one camera's allow-list record. Do not "fix" this test.
+ * ------------------------------------------------------------------------ */
+
+test("+OpenGate is sent byte-for-byte as before, including when unset", () => {
+  const set = buildPlateUpdateEndpoint({
+    mode: "TrafficRedList",
+    recno: "1",
+    plateNumber: "SGX1234A",
+    openGate: "false",
+  });
+  assert.ok(set.includes("&+OpenGate=false&"));
+
+  const unset = buildPlateUpdateEndpoint({
+    mode: "TrafficRedList",
+    recno: "1",
+    plateNumber: "SGX1234A",
+  });
+  assert.ok(unset.includes("&+OpenGate=undefined&"));
+});
+
+test("an absent optional field still renders as it did before", () => {
+  // Previously these were template literals, so undefined became "undefined".
+  // Encoding must not quietly turn that into an empty value.
+  const url = buildPlateUpdateEndpoint({
+    mode: "TrafficRedList",
+    recno: "1",
+    plateNumber: "SGX1234A",
+  });
+  assert.ok(url.includes("BeginTime=undefined"));
+  assert.ok(url.includes("CancelTime=undefined"));
+});