@7365admin1/core 3.42.2 → 3.43.0

package/test/camera-device-http.test.mjs

@@ -0,0 +1,792 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createHash } from "node:crypto";
+import { createServer } from "node:http";
+
+import {
+  AUTH_FAILURE_LIMIT,
+  AUTH_FAILURE_WINDOW_MS,
+  AUTH_LOCKOUT_MS,
+  EVENT_HEALTH_CODES,
+  MEDIA_FIND_CREATE,
+  PTZ_MOVE_CODES,
+  buildDigestAuthorization,
+  clampPtzSpeed,
+  createAuthFailureBudget,
+  createDeviceHttpAdapter,
+  eventAttachPath,
+  gotoPresetPath,
+  loadFileByTimePath,
+  mediaFindClosePath,
+  mediaFindFilePath,
+  mediaFindNextPath,
+  parseDigestChallenge,
+  parseEventBody,
+  parseKeyValues,
+  parseMediaFindResults,
+  parsePresets,
+  parsePtzCapability,
+  presetListPath,
+  probeDeviceCapabilities,
+  ptzAbsolutePath,
+  ptzCapabilityPath,
+  ptzMovePath,
+  query,
+  snapshotPath,
+} from "./.build/services/camera-device-http.service.mjs";
+
+/**
+ * **No device or recorder is contacted by this file.** Everything below runs
+ * against a mock HTTP server on 127.0.0.1 that imitates the digest handshake and
+ * the response bodies documented in V3.37. The credential is an obvious fake.
+ */
+const USER = "not-a-real-user";
+const PASS = "not-a-real-password";
+const REALM = "Login to TEST";
+const NONCE = "fixednonce0123456789";
+
+function md5(value) {
+  return createHash("md5").update(value, "utf8").digest("hex");
+}
+
+/* -------------------------------------------------------------------------- */
+/* An in-memory budget store and a controllable clock                          */
+/* -------------------------------------------------------------------------- */
+
+function memoryStore() {
+  const map = new Map();
+  return {
+    map,
+    get: async (key) => map.get(key) ?? null,
+    set: async (key, value) => void map.set(key, value),
+  };
+}
+
+function fakeClock(start = 1_770_000_000_000) {
+  let at = start;
+  return {
+    now: () => at,
+    advance: (ms) => {
+      at += ms;
+    },
+  };
+}
+
+function budgetFor(store = memoryStore(), clock = fakeClock()) {
+  return { budget: createAuthFailureBudget(store, clock.now), store, clock };
+}
+
+/* -------------------------------------------------------------------------- */
+/* The mock device                                                             */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * A Dahua-shaped device.
+ *
+ * `routes` maps a path prefix to `{status, body, headers}`. `credentials`
+ * decides whether a correct digest response is accepted, so "wrong password" is
+ * testable without changing anything on our side.
+ */
+async function startDevice(options = {}) {
+  const hits = [];
+  const accept = options.accept ?? true;
+
+  const server = createServer((req, res) => {
+    hits.push(req.url);
+
+    const authorization = req.headers.authorization;
+    if (!authorization) {
+      res.writeHead(401, {
+        "WWW-Authenticate": `Digest realm="${REALM}", qop="auth", nonce="${NONCE}", opaque="op4qu3"`,
+      });
+      res.end();
+      return;
+    }
+
+    if (!accept || !isDigestValid(authorization, req.method)) {
+      res.writeHead(options.rejectWith ?? 403).end();
+      return;
+    }
+
+    const route = Object.entries(options.routes ?? {}).find(([prefix]) =>
+      req.url.startsWith(prefix),
+    );
+    if (!route) {
+      res.writeHead(404).end();
+      return;
+    }
+
+    const reply = route[1];
+    if (typeof reply === "function") {
+      reply(req, res);
+      return;
+    }
+    res.writeHead(reply.status ?? 200, reply.headers ?? {});
+    res.end(reply.body ?? "OK");
+  });
+
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const { port } = server.address();
+
+  return {
+    hits,
+    baseUrl: `http://127.0.0.1:${port}`,
+    async close() {
+      await new Promise((resolve) => server.close(resolve));
+    },
+  };
+}
+
+/** Recomputes the response the way a real device would, per RFC 2617. */
+function isDigestValid(header, method) {
+  const parts = parseDigestChallenge(header);
+  const ha1 = md5(`${USER}:${REALM}:${PASS}`);
+  const ha2 = md5(`${method}:${parts.uri}`);
+  const expected = parts.qop
+    ? md5(`${ha1}:${NONCE}:${parts.nc}:${parts.cnonce}:${parts.qop}:${ha2}`)
+    : md5(`${ha1}:${NONCE}:${ha2}`);
+  return parts.username === USER && parts.response === expected;
+}
+
+function targetFor(device, overrides = {}) {
+  return {
+    authority: "relay.example.net",
+    baseUrl: device.baseUrl,
+    username: USER,
+    password: PASS,
+    enabled: true,
+    controlEnabled: false,
+    timeoutMs: 4000,
+    probeTtlSeconds: 900,
+    ...overrides,
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+/* Digest                                                                      */
+/* -------------------------------------------------------------------------- */
+
+test("a challenge is parsed, including a quoted value containing a comma", () => {
+  const parsed = parseDigestChallenge(
+    'Digest realm="Login to X", qop="auth,auth-int", nonce=abc123, opaque="o", algorithm=MD5',
+  );
+  assert.equal(parsed.realm, "Login to X");
+  assert.equal(parsed.qop, "auth,auth-int");
+  assert.equal(parsed.nonce, "abc123");
+  assert.equal(parsed.algorithm, "MD5");
+});
+
+test("a Basic challenge yields nothing, so we never answer one with a password", () => {
+  assert.deepEqual(parseDigestChallenge('Basic realm="X"'), {});
+  assert.deepEqual(parseDigestChallenge(""), {});
+});
+
+test("the digest response matches the RFC 2617 §3.5 worked example", () => {
+  // The canonical vector, so an arithmetic slip in HA1/HA2/response is caught
+  // without a device: user "Mufasa", password "Circle Of Life".
+  const header = buildDigestAuthorization({
+    username: "Mufasa",
+    password: "Circle Of Life",
+    method: "GET",
+    uri: "/dir/index.html",
+    challenge: {
+      realm: "testrealm@host.com",
+      qop: "auth,auth-int",
+      nonce: "dcd98b7102dd2f0e8b11d0f600bfb0c093",
+      opaque: "5ccc069c403ebaf9f0171e9517f40e41",
+    },
+    nc: "00000001",
+    cnonce: "0a4f113b",
+  });
+  assert.match(header, /response="6629fae49393a05397450978507c4ef1"/);
+  assert.match(header, /qop=auth, nc=00000001, cnonce="0a4f113b"/);
+  assert.match(header, /opaque="5ccc069c403ebaf9f0171e9517f40e41"/);
+});
+
+test("MD5-sess and a challenge with no qop are both handled", () => {
+  const sess = buildDigestAuthorization({
+    username: "u",
+    password: "p",
+    method: "GET",
+    uri: "/x",
+    challenge: { realm: "r", nonce: "n", algorithm: "MD5-sess", qop: "auth" },
+    cnonce: "c",
+  });
+  const plain = buildDigestAuthorization({
+    username: "u",
+    password: "p",
+    method: "GET",
+    uri: "/x",
+    challenge: { realm: "r", nonce: "n" },
+  });
+
+  const ha1 = md5(`${md5("u:r:p")}:n:c`);
+  assert.match(sess, new RegExp(`response="${md5(`${ha1}:n:00000001:c:auth:${md5("GET:/x")}`)}"`));
+  assert.ok(!plain.includes("qop="));
+  assert.match(plain, new RegExp(`response="${md5(`${md5("u:r:p")}:n:${md5("GET:/x")}`)}"`));
+});
+
+/* -------------------------------------------------------------------------- */
+/* The lockout budget — the mandatory guard                                    */
+/* -------------------------------------------------------------------------- */
+
+test("the budget stops one attempt short of the device's own limit", () => {
+  // The device locks at 3 failures in 30 s (§4.7.x). Stopping at 2 leaves a
+  // slot: for a lost update, and for an installer standing at the recorder.
+  assert.equal(AUTH_FAILURE_LIMIT, 2);
+  assert.equal(AUTH_FAILURE_WINDOW_MS, 30_000);
+  assert.equal(AUTH_LOCKOUT_MS, 1_800_000);
+});
+
+test("two failures spend the budget and further attempts are refused, not retried", async () => {
+  const { budget, clock } = budgetFor();
+
+  assert.deepEqual(await budget.check("dev"), { allowed: true });
+  assert.equal((await budget.recordFailure("dev")).allowed, true);
+  assert.equal((await budget.recordFailure("dev")).allowed, false);
+
+  const verdict = await budget.check("dev");
+  assert.equal(verdict.allowed, false);
+  assert.equal(verdict.reason, "device-http-locked-out");
+  assert.equal(verdict.retryAfterSeconds, 1800);
+
+  // Still refused most of the way through the cooldown…
+  clock.advance(AUTH_LOCKOUT_MS - 1000);
+  assert.equal((await budget.check("dev")).allowed, false);
+  // …and open again after it, matching the device's own LoginFailLockTime.
+  clock.advance(2000);
+  assert.equal((await budget.check("dev")).allowed, true);
+});
+
+test("failures older than the device's 30 s window do not accumulate", async () => {
+  const { budget, clock } = budgetFor();
+  await budget.recordFailure("dev");
+  clock.advance(AUTH_FAILURE_WINDOW_MS + 1);
+  // A second failure half an hour later must not lock anything out.
+  assert.equal((await budget.recordFailure("dev")).allowed, true);
+  assert.equal((await budget.check("dev")).allowed, true);
+});
+
+test("the budget is per device, so one bad recorder cannot lock out another", async () => {
+  const { budget } = budgetFor();
+  await budget.recordFailure("a");
+  await budget.recordFailure("a");
+  assert.equal((await budget.check("a")).allowed, false);
+  assert.equal((await budget.check("b")).allowed, true);
+});
+
+test("a success clears the window but never unlocks a spent budget", async () => {
+  const { budget } = budgetFor();
+  await budget.recordFailure("dev");
+  await budget.recordSuccess("dev");
+  assert.equal((await budget.recordFailure("dev")).allowed, true, "window cleared");
+
+  await budget.recordFailure("dev");
+  assert.equal((await budget.check("dev")).allowed, false);
+  await budget.recordSuccess("dev");
+  assert.equal(
+    (await budget.check("dev")).allowed,
+    false,
+    "a lockout must not be clearable by a later success",
+  );
+});
+
+test("an unreadable budget fails CLOSED", async () => {
+  const store = { get: async () => "{not json", set: async () => {} };
+  const budget = createAuthFailureBudget(store, fakeClock().now);
+  assert.equal((await budget.check("dev")).allowed, false);
+});
+
+test("the budget survives a restart: it is written to the store, not held in memory", async () => {
+  const store = memoryStore();
+  const clock = fakeClock();
+  await createAuthFailureBudget(store, clock.now).recordFailure("dev");
+  await createAuthFailureBudget(store, clock.now).recordFailure("dev");
+  // A brand-new instance, as a redeployed process would be.
+  const fresh = createAuthFailureBudget(store, clock.now);
+  assert.equal((await fresh.check("dev")).allowed, false);
+});
+
+/* -------------------------------------------------------------------------- */
+/* The adapter cannot exist, let alone fire, while it is switched off           */
+/* -------------------------------------------------------------------------- */
+
+test("the adapter is null when device access is disabled", () => {
+  const { budget } = budgetFor();
+  const adapter = createDeviceHttpAdapter({
+    target: targetFor({ baseUrl: "http://127.0.0.1:1" }, { enabled: false }),
+    budget,
+  });
+  // Not a disabled object with guarded methods — nothing to call at all.
+  assert.equal(adapter, null);
+});
+
+test("control is null unless control is explicitly enabled", () => {
+  const { budget } = budgetFor();
+  const reads = createDeviceHttpAdapter({
+    target: targetFor({ baseUrl: "http://127.0.0.1:1" }),
+    budget,
+  });
+  assert.equal(reads.control, null, "reads on must not arm motors");
+  assert.equal(typeof reads.getDeviceInfo, "function");
+
+  const armed = createDeviceHttpAdapter({
+    target: targetFor({ baseUrl: "http://127.0.0.1:1" }, { controlEnabled: true }),
+    budget,
+  });
+  for (const name of ["ptzContinuous", "ptzStop", "ptzAbsolute", "gotoPreset"]) {
+    assert.equal(typeof armed.control[name], "function", name);
+  }
+});
+
+test("a spent budget means no request leaves the process at all", async () => {
+  const device = await startDevice({ routes: { "/cgi-bin": { body: "version=1" } } });
+  try {
+    const { budget } = budgetFor();
+    await budget.recordFailure(device.baseUrl);
+    await budget.recordFailure(device.baseUrl);
+
+    const adapter = createDeviceHttpAdapter({ target: targetFor(device), budget });
+    await assert.rejects(() => adapter.getDeviceInfo(), (error) => {
+      assert.equal(error.code, "device-http-locked-out");
+      assert.equal(error.retryAfterSeconds, 1800);
+      return true;
+    });
+    assert.deepEqual(device.hits, [], "the device must not have been touched");
+  } finally {
+    await device.close();
+  }
+});
+
+/* -------------------------------------------------------------------------- */
+/* The handshake, end to end, against the mock                                 */
+/* -------------------------------------------------------------------------- */
+
+test("a 401 challenge is the handshake working and costs nothing", async () => {
+  const device = await startDevice({
+    routes: {
+      "/cgi-bin/magicBox.cgi?action=getSoftwareVersion": {
+        body: "version=3.140.0000000.0\r\nBuildDate=2024-01-01\r\n",
+      },
+      "/cgi-bin/magicBox.cgi?action=getDeviceType": { body: "type=IPC-TEST\r\n" },
+      "/cgi-bin/IntervideoManager.cgi": { body: "version=3.37\r\n" },
+    },
+  });
+  try {
+    const { budget, store } = budgetFor();
+    const adapter = createDeviceHttpAdapter({ target: targetFor(device), budget });
+    const info = await adapter.getDeviceInfo();
+
+    assert.equal(info.softwareVersion, "3.140.0000000.0");
+    assert.equal(info.deviceType, "IPC-TEST");
+    assert.equal(info.apiVersion, "3.37");
+    // Three calls, each a 401 then a 200 — and not one counted as a failure.
+    assert.equal(device.hits.length, 6);
+    assert.equal(store.map.size, 0, "an ordinary challenge must not spend the budget");
+  } finally {
+    await device.close();
+  }
+});
+
+test("bad credentials are one failure, and the second one closes the budget", async () => {
+  const device = await startDevice({ accept: false, rejectWith: 403 });
+  try {
+    const { budget } = budgetFor();
+    const adapter = createDeviceHttpAdapter({ target: targetFor(device), budget });
+
+    await assert.rejects(
+      () => adapter.getDeviceTime(),
+      (error) => error.code === "device-auth-failed",
+    );
+    // The second attempt spends the budget, and the caller is told THAT rather
+    // than being handed a generic failure it might retry.
+    await assert.rejects(
+      () => adapter.getDeviceTime(),
+      (error) => error.code === "device-http-locked-out",
+    );
+    // The third does not reach the network.
+    const before = device.hits.length;
+    await assert.rejects(
+      () => adapter.getDeviceTime(),
+      (error) => error.code === "device-http-locked-out",
+    );
+    assert.equal(device.hits.length, before);
+  } finally {
+    await device.close();
+  }
+});
+
+test("a repeated 401 after we answered is a failure too, not an endless handshake", async () => {
+  const device = await startDevice({ accept: false, rejectWith: 401 });
+  try {
+    const { budget } = budgetFor();
+    const adapter = createDeviceHttpAdapter({ target: targetFor(device), budget });
+    await assert.rejects(
+      () => adapter.getDeviceTime(),
+      (error) => error.code === "device-auth-failed",
+    );
+    assert.equal(device.hits.length, 2, "exactly one attempt, no retry loop");
+  } finally {
+    await device.close();
+  }
+});
+
+test("an unreachable device is reported as unreachable, and never as bad credentials", async () => {
+  const { budget, store } = budgetFor();
+  const adapter = createDeviceHttpAdapter({
+    // Port 1 on loopback: nothing listens, so the connection is refused.
+    target: targetFor({ baseUrl: "http://127.0.0.1:1" }),
+    budget,
+  });
+  await assert.rejects(
+    () => adapter.getDeviceTime(),
+    (error) => error.code === "device-http-unreachable",
+  );
+  assert.equal(store.map.size, 0, "a network failure is not a login failure");
+});
+
+test("a snapshot comes back as bytes", async () => {
+  const jpeg = Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0x00, 0x10, 0xff, 0xd9]);
+  const device = await startDevice({
+    routes: {
+      "/cgi-bin/snapshot.cgi": (req, res) => {
+        res.writeHead(200, { "Content-Type": "image/jpeg" });
+        res.end(jpeg);
+      },
+    },
+  });
+  try {
+    const { budget } = budgetFor();
+    const adapter = createDeviceHttpAdapter({ target: targetFor(device), budget });
+    const bytes = await adapter.getSnapshot(4);
+    assert.deepEqual([...bytes], [...jpeg]);
+    assert.ok(device.hits.some((url) => url.includes("channel=4&type=0")));
+  } finally {
+    await device.close();
+  }
+});
+
+/* -------------------------------------------------------------------------- */
+/* Recorded files — and the handle is always released                          */
+/* -------------------------------------------------------------------------- */
+
+test("a recording search runs the four-call session and closes the handle", async () => {
+  const device = await startDevice({
+    routes: {
+      "/cgi-bin/mediaFileFind.cgi?action=factory.create": { body: "result=1234\r\n" },
+      "/cgi-bin/mediaFileFind.cgi?action=findFile": { body: "OK\r\n" },
+      "/cgi-bin/mediaFileFind.cgi?action=findNextFile": {
+        body: [
+          "found=2",
+          "items[0].Channel=4",
+          "items[0].StartTime=2026-08-10 09:00:00",
+          "items[0].EndTime=2026-08-10 09:15:00",
+          "items[0].FilePath=/mnt/dvr/2026-08-10/4/dav/09.00.00-09.15.00.dav",
+          "items[0].Length=104857600",
+          "items[0].Type=dav",
+          "items[1].Channel=4",
+          "items[1].StartTime=2026-08-10 09:15:00",
+          "items[1].EndTime=2026-08-10 09:30:00",
+          "items[1].FilePath=/mnt/dvr/2026-08-10/4/dav/09.15.00-09.30.00.dav",
+          "items[1].Type=dav",
+          "",
+        ].join("\r\n"),
+      },
+      "/cgi-bin/mediaFileFind.cgi?action=close": { body: "OK" },
+      "/cgi-bin/mediaFileFind.cgi?action=destroy": { body: "OK" },
+    },
+  });
+  try {
+    const { budget } = budgetFor();
+    const adapter = createDeviceHttpAdapter({ target: targetFor(device), budget });
+    const files = await adapter.findRecordings({
+      channel: 4,
+      startTime: "2026-08-10 09:00:00",
+      endTime: "2026-08-10 10:00:00",
+    });
+
+    assert.equal(files.length, 2);
+    assert.equal(files[0].channel, 4);
+    assert.equal(files[0].bytes, 104857600);
+    assert.equal(files[1].bytes, null, "a missing Length is null, not 0");
+    assert.ok(device.hits.some((url) => url.includes("action=close")));
+    assert.ok(device.hits.some((url) => url.includes("action=destroy")));
+  } finally {
+    await device.close();
+  }
+});
+
+test("the handle is released even when the search itself fails", async () => {
+  const device = await startDevice({
+    routes: {
+      "/cgi-bin/mediaFileFind.cgi?action=factory.create": { body: "result=99\r\n" },
+      "/cgi-bin/mediaFileFind.cgi?action=findFile": { status: 500, body: "" },
+      "/cgi-bin/mediaFileFind.cgi?action=close": { body: "OK" },
+      "/cgi-bin/mediaFileFind.cgi?action=destroy": { body: "OK" },
+    },
+  });
+  try {
+    const { budget } = budgetFor();
+    const adapter = createDeviceHttpAdapter({ target: targetFor(device), budget });
+    await assert.rejects(() =>
+      adapter.findRecordings({
+        channel: 1,
+        startTime: "2026-08-10 09:00:00",
+        endTime: "2026-08-10 10:00:00",
+      }),
+    );
+    assert.ok(device.hits.some((url) => url.includes("action=close&object=99")));
+  } finally {
+    await device.close();
+  }
+});
+
+/* -------------------------------------------------------------------------- */
+/* Presets and PTZ capability                                                  */
+/* -------------------------------------------------------------------------- */
+
+test("a preset list is parsed in order and rows with no index are dropped", () => {
+  const presets = parsePresets(
+    [
+      "presets[0].Index=1",
+      "presets[0].Name=Main Gate",
+      "presets[2].Index=5",
+      "presets[2].Name=Car Park",
+      "presets[1].Name=nameless",
+      "",
+    ].join("\r\n"),
+  );
+  assert.deepEqual(presets, [
+    { index: 1, name: "Main Gate" },
+    { index: 5, name: "Car Park" },
+  ]);
+});
+
+test("PTZ capability: a missing field is unknown, never a silent no", () => {
+  const full = parsePtzCapability(
+    "caps.Pan=true\r\ncaps.Tilt=true\r\ncaps.Zoom=true\r\ncaps.Preset=true\r\ncaps.PresetNumber=80\r\n",
+  );
+  assert.deepEqual(full, { ptz: true, presets: true, presetCount: 80 });
+
+  const fixed = parsePtzCapability("caps.Pan=false\r\ncaps.Tilt=false\r\ncaps.Zoom=false\r\n");
+  assert.equal(fixed.ptz, false);
+
+  // The case that must not become `false`: firmware that answers nothing useful.
+  const silent = parsePtzCapability("result=OK\r\n");
+  assert.equal(silent.ptz, null);
+  assert.equal(silent.presets, null);
+
+  // Presets inferred from the count when the flag is absent.
+  assert.equal(parsePtzCapability("caps.PresetNumber=0\r\n").presets, false);
+  assert.equal(parsePtzCapability("caps.PresetNumber=80\r\n").presets, true);
+});
+
+/* -------------------------------------------------------------------------- */
+/* Events                                                                      */
+/* -------------------------------------------------------------------------- */
+
+test("an event body is parsed, and a heartbeat is not an event", () => {
+  const event = parseEventBody(
+    'Code=VideoBlind;action=Start;index=0;data={"Channel":4,"Name":"GYM"}',
+  );
+  assert.deepEqual(event, {
+    code: "VideoBlind",
+    action: "Start",
+    index: 0,
+    data: { Channel: 4, Name: "GYM" },
+  });
+
+  // A heartbeat treated as an event raises an alarm every 20 seconds.
+  assert.equal(parseEventBody("Heartbeat"), null);
+  assert.equal(parseEventBody(""), null);
+  assert.equal(parseEventBody("nonsense"), null);
+  assert.equal(parseEventBody("Code=NetAbort;action=Start;index=0;data={oops").data, null);
+});
+
+test("a multipart event stream is read until the subscriber aborts", async () => {
+  const boundary = "myboundary";
+  const device = await startDevice({
+    routes: {
+      "/cgi-bin/eventManager.cgi": (req, res) => {
+        res.writeHead(200, {
+          "Content-Type": `multipart/x-mixed-replace; boundary=${boundary}`,
+        });
+        const part = (payload) =>
+          `--${boundary}\r\nContent-Type: text/plain\r\nContent-Length: ${payload.length}\r\n\r\n${payload}\r\n`;
+        res.write(part("Heartbeat"));
+        res.write(part('Code=VideoBlind;action=Start;index=0;data={"Channel":4}'));
+        res.write(part("Code=StorageLowSpace;action=Start;index=0"));
+        res.write(`--${boundary}\r\n`);
+      },
+    },
+  });
+
+  try {
+    const { budget } = budgetFor();
+    const adapter = createDeviceHttpAdapter({ target: targetFor(device), budget });
+    const controller = new AbortController();
+    const seen = [];
+
+    const done = adapter
+      .subscribeEvents({
+        onEvent: (event) => {
+          seen.push(event.code);
+          if (seen.length === 2) controller.abort();
+        },
+        signal: controller.signal,
+      })
+      .catch(() => undefined);
+
+    await done;
+    assert.deepEqual(seen, ["VideoBlind", "StorageLowSpace"]);
+  } finally {
+    await device.close();
+  }
+});
+
+/* -------------------------------------------------------------------------- */
+/* Probing degrades to "unknown" instead of failing a caller                   */
+/* -------------------------------------------------------------------------- */
+
+test("a probe of a null adapter is unreachable, not a crash", async () => {
+  const probe = await probeDeviceCapabilities({ adapter: null });
+  assert.equal(probe.reachable, false);
+  assert.ok(probe.probedAt);
+});
+
+test("a probe reports what the device said, in two read-only calls", async () => {
+  const device = await startDevice({
+    routes: {
+      "/cgi-bin/magicBox.cgi?action=getSoftwareVersion": { body: "version=3.140\r\n" },
+      "/cgi-bin/magicBox.cgi?action=getDeviceType": { body: "type=SD-TEST\r\n" },
+      "/cgi-bin/IntervideoManager.cgi": { status: 404, body: "" },
+      "/cgi-bin/ptz.cgi?action=getCurrentProtocolCaps": {
+        body: "caps.Pan=true\r\ncaps.Tilt=true\r\ncaps.PresetNumber=80\r\n",
+      },
+    },
+  });
+  try {
+    const { budget } = budgetFor();
+    const adapter = createDeviceHttpAdapter({ target: targetFor(device), budget });
+    const probe = await probeDeviceCapabilities({ adapter, channel: 4 });
+
+    assert.equal(probe.reachable, true);
+    assert.equal(probe.ptz, true);
+    assert.equal(probe.presets, true);
+    assert.equal(probe.softwareVersion, "3.140");
+    // Nothing but GETs, and no ptz.cgi?action=start anywhere near it.
+    assert.ok(!device.hits.some((url) => url.includes("action=start")));
+  } finally {
+    await device.close();
+  }
+});
+
+test("a probe never throws: an unreachable device and a spent budget both return a result", async () => {
+  const { budget } = budgetFor();
+  const unreachable = createDeviceHttpAdapter({
+    target: targetFor({ baseUrl: "http://127.0.0.1:1" }),
+    budget,
+  });
+  assert.deepEqual(
+    { reachable: (await probeDeviceCapabilities({ adapter: unreachable })).reachable },
+    { reachable: false },
+  );
+
+  await budget.recordFailure("http://127.0.0.1:1");
+  await budget.recordFailure("http://127.0.0.1:1");
+  const locked = await probeDeviceCapabilities({ adapter: unreachable });
+  assert.equal(locked.lockedOut, true);
+  assert.equal(locked.reachable, false);
+});
+
+/* -------------------------------------------------------------------------- */
+/* Paths: §3.2 encoding, and the codes we refuse to send                       */
+/* -------------------------------------------------------------------------- */
+
+test("every value is percent-encoded and keys are left literal", () => {
+  assert.equal(
+    query({ action: "findFile", "condition.Types[0]": "dav", t: "2026-08-10 09:00:00" }),
+    // Keys literal (Dahua expects `condition.Types[0]` as written), values
+    // encoded — §3.2.
+    "action=findFile&condition.Types[0]=dav&t=2026-08-10%2009%3A00%3A00",
+  );
+  assert.equal(query({ a: 1, b: undefined }), "a=1");
+});
+
+test("snapshot, capability and preset paths are the documented ones", () => {
+  assert.equal(snapshotPath(4), "/cgi-bin/snapshot.cgi?channel=4&type=0");
+  assert.equal(
+    ptzCapabilityPath(4),
+    "/cgi-bin/ptz.cgi?action=getCurrentProtocolCaps&channel=4",
+  );
+  assert.equal(presetListPath(4), "/cgi-bin/ptz.cgi?action=getPresets&channel=4");
+  assert.equal(MEDIA_FIND_CREATE, "/cgi-bin/mediaFileFind.cgi?action=factory.create");
+});
+
+test("movement is an allow-list: tours, patterns and preset WRITES are not sendable", () => {
+  assert.match(
+    ptzMovePath({ action: "start", channel: 4, code: "Left", speed: 3 }),
+    /action=start&channel=4&code=Left&arg1=0&arg2=3&arg3=0/,
+  );
+  assert.match(ptzMovePath({ action: "stop", code: "Left" }), /action=stop/);
+
+  for (const forbidden of [
+    "SetPreset",
+    "ClearPreset",
+    "StartTour",
+    "AddTour",
+    "SetLimit",
+    "Reboot",
+  ]) {
+    assert.ok(!PTZ_MOVE_CODES.includes(forbidden), forbidden);
+    assert.throws(() => ptzMovePath({ action: "start", code: forbidden }));
+  }
+  assert.throws(() => ptzMovePath({ action: "reboot", code: "Left" }));
+});
+
+test("speeds and absolute positions are clamped, never passed through", () => {
+  assert.equal(clampPtzSpeed(99), 8);
+  assert.equal(clampPtzSpeed(0), 1);
+  assert.equal(clampPtzSpeed("nonsense"), 4);
+
+  assert.match(
+    ptzAbsolutePath({ channel: 1, pan: 99999, tilt: -5, zoom: 999 }),
+    /code=PositionABS&arg1=3600&arg2=0&arg3=128/,
+  );
+  assert.match(gotoPresetPath({ preset: 500 }), /code=GotoPreset&arg1=0&arg2=255/);
+  assert.match(gotoPresetPath({ preset: 0 }), /arg2=1/);
+});
+
+test("the event subscription names health codes rather than asking for everything", () => {
+  const path = eventAttachPath();
+  for (const code of EVENT_HEALTH_CODES) assert.ok(path.includes(code), code);
+  assert.match(path, /heartbeat=20/);
+  assert.match(eventAttachPath({ heartbeatSeconds: 9999 }), /heartbeat=60/);
+});
+
+test("the media-find and load-file paths carry the object handle and the time range", () => {
+  assert.match(
+    mediaFindFilePath({
+      object: "7",
+      channel: 4,
+      startTime: "2026-08-10 09:00:00",
+      endTime: "2026-08-10 10:00:00",
+    }),
+    /object=7&condition.Channel=4/,
+  );
+  assert.match(mediaFindNextPath({ object: "7", count: 5000 }), /count=100/);
+  assert.equal(
+    mediaFindClosePath("7", true),
+    "/cgi-bin/mediaFileFind.cgi?action=destroy&object=7",
+  );
+  assert.match(
+    loadFileByTimePath({ channel: 4, startTime: "a b", endTime: "c d" }),
+    /action=startLoad&channel=4&startTime=a%20b&endTime=c%20d&subtype=0/,
+  );
+});
+
+test("key=value parsing tolerates CRLF, blank lines and values containing '='", () => {
+  const parsed = parseKeyValues("a=1\r\n\r\nb=x=y\r\nnokey\r\n=novalue\r\n");
+  assert.deepEqual(parsed, { a: "1", b: "x=y" });
+  assert.deepEqual(parseMediaFindResults("found=0\r\n"), []);
+});