@twinsearth/w2m-dsh-plugin 0.6.3 → 0.8.2

package/src/chatops/fleet-scope.mjs

@@ -0,0 +1,176 @@
+/**
+ * Which devices a request may reach, and which fleet a pairing code admits to (v0.7.6).
+ *
+ * ## The defect this replaces, in one line
+ *
+ * `src/relay/state.mjs` L1259-1262:
+ *
+ *     const all = [...this.devices.values()];
+ *     const targets = Array.isArray(input.target_machines) && input.target_machines.length > 0
+ *       ? all.filter((d) => input.target_machines.includes(d.machine_id))
+ *       : all;
+ *
+ * `targets` is **every device on the relay**. No filter, because until now there was nothing to
+ * filter by: a device had a random `machine_id` and the `user_id` the relay stored was never read.
+ * So every account on a relay shares one pool, and any caller holding a valid operator token
+ * broadcasts to all of them. That is the finding this release fixes.
+ *
+ * ## Why the decision lives here rather than inline
+ *
+ * The relay is a large stateful object where a mistake is expensive to find. The rule "which
+ * devices may this request reach" is a **pure function of (requester's fleet, device's fleet,
+ * explicitly named targets)**, so it is expressed here, at that shape, and tested exhaustively.
+ * The relay calls it; it does not reimplement it.
+ *
+ * ## The three rules, and the reasoning that is not obvious
+ *
+ * **1. A request reaches only its own fleet.** Not "only its own fleet by default" — there is no
+ * parameter to widen it. A cross-fleet read is never legitimate, so it is not expressible.
+ *
+ * **2. An empty fleet matches nothing.** `fleet_id: undefined` on both sides must **not** compare
+ * equal. This is the failure that would silently undo everything: two ungrouped devices would
+ * match each other, which is exactly the "everything in one pool" behaviour being removed. So an
+ * absent fleet is a device that belongs to no fleet, and it is reachable by nobody.
+ *
+ * **3. A cross-fleet target is refused rather than ignored.** Silently dropping a named target
+ * leaves the caller believing it dispatched somewhere. The refusal **does not say whether the
+ * target exists** — a caller must not be able to probe another account's device ids.
+ */
+
+/** Why a request reached nobody, or was refused outright. */
+export const SCOPE_REFUSAL = Object.freeze({
+  /** The requester has no fleet, so it reaches no devices. */
+  NO_FLEET: 'no_fleet',
+  /** The fleet exists but holds no online device. */
+  NO_DEVICE_IN_FLEET: 'no_device_in_fleet',
+  /** A named target belongs to another fleet. Deliberately unspecific about which. */
+  TARGET_OUTSIDE_FLEET: 'target_outside_fleet',
+  /** The named target is not a device this relay holds at all. */
+  TARGET_UNKNOWN: 'target_unknown',
+});
+
+/**
+ * Does this device belong to this fleet?
+ *
+ * **Absent is not a wildcard.** Both sides must be a non-empty string and equal. A helper that
+ * treated `undefined === undefined` as a match would put every ungrouped device in one pool — the
+ * precise defect being removed — and it would pass every test that only ever sets a fleet.
+ */
+export function inFleet(deviceFleet, requesterFleet) {
+  if (typeof deviceFleet !== 'string' || deviceFleet === '') return false;
+  if (typeof requesterFleet !== 'string' || requesterFleet === '') return false;
+  return deviceFleet === requesterFleet;
+}
+
+/**
+ * The devices a request may reach.
+ *
+ * @param {object} input
+ * @param {Array<{machine_id: string, fleet_id?: string, online?: boolean}>} input.devices
+ * @param {string|null} input.fleetId The requester's fleet, from its verified statement.
+ * @param {string[]} [input.targetMachines] Explicit targets, if any.
+ * @param {boolean} [input.requireOnline] Skip devices the relay believes are offline.
+ * @returns {{ok: true, targets: object[], skippedOffline: string[]}
+ *          | {ok: false, reason: string, text: string}}
+ */
+export function selectTargets({ devices, fleetId, targetMachines, requireOnline = true }) {
+  if (typeof fleetId !== 'string' || fleetId === '') {
+    // A requester with no fleet reaches nothing. Not "everything", and not an error the caller can
+    // retry differently — it needs an account.
+    return { ok: false, reason: SCOPE_REFUSAL.NO_FLEET, text: '这个请求没有舰队身份，所以它不能到达任何设备。' };
+  }
+
+  const mine = devices.filter((d) => inFleet(d.fleet_id, fleetId));
+
+  if (Array.isArray(targetMachines) && targetMachines.length > 0) {
+    const byId = new Map(mine.map((d) => [d.machine_id, d]));
+    const chosen = [];
+    for (const id of targetMachines) {
+      const device = byId.get(id);
+      if (device === undefined) {
+        // Two different worlds, deliberately reported as one answer. Saying "that machine exists
+        // but is not yours" would let a caller enumerate another account's fleet by trying ids.
+        return {
+          ok: false,
+          reason: SCOPE_REFUSAL.TARGET_OUTSIDE_FLEET,
+          text: '指定的目标不在这条舰队里。',
+        };
+      }
+      chosen.push(device);
+    }
+    return finish(chosen, requireOnline);
+  }
+
+  return finish(mine, requireOnline);
+}
+
+function finish(devices, requireOnline) {
+  const skippedOffline = [];
+  const targets = [];
+  for (const device of devices) {
+    if (requireOnline && device.online === false) {
+      // Counted, not dropped silently: "we tried and it was offline" and "we never considered it"
+      // produce the same empty result and different fixes.
+      skippedOffline.push(device.machine_id);
+      continue;
+    }
+    targets.push(device);
+  }
+  if (targets.length === 0) {
+    return {
+      ok: false,
+      reason: SCOPE_REFUSAL.NO_DEVICE_IN_FLEET,
+      text:
+        skippedOffline.length > 0
+          ? '这条舰队里的机器当前都不在线。'
+          : '这条舰队里没有机器。',
+    };
+  }
+  return { ok: true, targets, skippedOffline };
+}
+
+/**
+ * Which fleet a pairing code admits to.
+ *
+ * **The fleet comes from the code, never from the device.** This is the whole of the isolation
+ * argument: if a device could name its own fleet it would join any account, and every signature in
+ * `auth.mjs` would faithfully attest to a lie. A code with no fleet admits to no fleet, and the
+ * pairing is refused rather than defaulted.
+ *
+ * @param {object} input
+ * @param {{fleet_id?: string, used?: boolean, exp?: number}|null} input.code The pairing code record.
+ * @param {number} [input.now]
+ */
+export function fleetFromPairingCode({ code, now = Date.now() }) {
+  if (code === null || code === undefined || typeof code !== 'object') {
+    return { ok: false, reason: 'unknown_code', text: '配对码无效。' };
+  }
+  if (code.used === true) return { ok: false, reason: 'code_used', text: '这个配对码已经被使用过了。' };
+  if (typeof code.exp === 'number' && Number.isFinite(code.exp) && now >= code.exp) {
+    return { ok: false, reason: 'code_expired', text: '配对码已过期。' };
+  }
+  if (typeof code.fleet_id !== 'string' || code.fleet_id === '') {
+    // A relay that issued a fleetless code would be handing out access to a pool with no owner.
+    return { ok: false, reason: 'code_has_no_fleet', text: '这个配对码没有绑定舰队，拒绝配对。' };
+  }
+  return { ok: true, fleetId: code.fleet_id };
+}
+
+/**
+ * The statement a relay issues for a device that has just paired.
+ *
+ * Kept here rather than inline in the relay so the fleet that goes into the signature is visibly
+ * the fleet that came from the code — one function, one place where that binding is made.
+ */
+export function statementForDevice({ device, fleetId, sn, now = Date.now(), ttlMs }) {
+  return {
+    algorithm: 'ed25519',
+    // From the pairing code. Not from `device.fleet_id`, which would be the device's own claim.
+    fleet_id: fleetId,
+    machine_id: device.machineId,
+    sn,
+    public_key: device.publicKeyPem,
+    issued_at_ms: now,
+    expires_at_ms: now + (Number.isFinite(ttlMs) ? ttlMs : 90 * 24 * 60 * 60 * 1000),
+  };
+}

package/src/chatops/fleet-wiring.mjs

@@ -0,0 +1,258 @@
+/**
+ * Wiring fleet scoping into the relay's decisions (v0.7.7).
+ *
+ * ## What this file is, and what it is not
+ *
+ * `fleet-scope.mjs` answers *"which devices may this request reach"*. This answers the two
+ * questions the relay needs answered **before** it can ask that one:
+ *
+ * 1. **What fleet is this requester in?** A relay receives a device token, not a fleet. The token
+ *    maps to a device, and the device has a `fleet_id` — or does not, because it paired before
+ *    fleets existed.
+ * 2. **What happens to a device that has no fleet?**
+ *
+ * ## The migration question, and why the answer is not "refuse"
+ *
+ * The shared relay holds four devices that paired under v0.6.3. None of them has a `fleet_id`.
+ * Refusing fleetless requests would take the whole fleet down at the moment of deployment — for a
+ * safety feature, that is the wrong trade.
+ *
+ * So there are two modes, and the relay's operator chose between them by configuring a fleet:
+ *
+ * | relay has | fleetless device | reaches |
+ * |---|---|---|
+ * | **no fleet configured** | legacy | every device, as before |
+ * | **a fleet configured** | `fleet_id: null` | **nothing** |
+ *
+ * That second row is the one that matters. Once an operator says *"this relay is for fleet X"*, a
+ * device with no fleet is not silently granted the run of it — it reaches nothing, and
+ * `scopeFleetId` says why. The transition is therefore **opt-in and visible**, rather than a
+ * background behaviour change that arrives with a version bump.
+ *
+ * A device with a `fleet_id` always reaches its own fleet and nothing else, in both modes. That is
+ * the isolation, and it does not depend on the relay's configuration.
+ */
+
+import { selectTargets, SCOPE_REFUSAL } from './fleet-scope.mjs';
+// v0.8.1: the account-derived fleet key, so a machine can join its own fleet with no human step.
+import { planJoin } from './fleet-join.mjs';
+
+/** Why a request reached nothing, before target selection even runs. */
+export const WIRING_REFUSAL = Object.freeze({
+  /** The token belongs to no device this relay knows. */
+  UNKNOWN_TOKEN: 'unknown_token',
+  /** The relay is scoped to a fleet and this requester is not in one. */
+  REQUESTER_HAS_NO_FLEET: 'requester_has_no_fleet',
+});
+
+/**
+ * Which fleet the requester acts as.
+ *
+ * The value comes from **the device record**, which the relay wrote at pairing time from the
+ * pairing code — never from anything in the request. A request that could name its own fleet
+ * would be able to reach any fleet, and every signature would faithfully attest to it.
+ *
+ * @param {object} input
+ * @param {{machine_id?: string, fleet_id?: string|null}|null} input.device The requester's record.
+ * @param {string|null} [input.relayFleetId] The fleet this relay is scoped to, if the operator set one.
+ * @returns {{ok: true, fleetId: string|null, legacy: boolean}
+ *          | {ok: false, reason: string, text: string}}
+ */
+export function scopeFleetId({ device, relayFleetId = null }) {
+  if (device === null || device === undefined || typeof device !== 'object') {
+    return { ok: false, reason: WIRING_REFUSAL.UNKNOWN_TOKEN, text: '这个 token 不属于本 relay 已知的任何设备。' };
+  }
+
+  const deviceFleet = typeof device.fleet_id === 'string' && device.fleet_id !== '' ? device.fleet_id : null;
+
+  // Already grouped: it reaches its own fleet, whatever the relay is configured for.
+  if (deviceFleet !== null) return { ok: true, fleetId: deviceFleet, legacy: false };
+
+  // Not grouped, and the relay has not been claimed for a fleet: the pre-v0.7.7 behaviour, which
+  // is what keeps a deployment from being an outage. `legacy: true` is reported so a caller can
+  // log it rather than having to infer it.
+  if (relayFleetId === null || relayFleetId === '') return { ok: true, fleetId: null, legacy: true };
+
+  // Not grouped, and the relay *is* claimed. A fleetless device is not handed the run of someone
+  // else's fleet — it reaches nothing, and says so.
+  return {
+    ok: false,
+    reason: WIRING_REFUSAL.REQUESTER_HAS_NO_FLEET,
+    text: '这个 relay 已绑定到一条舰队，而这台设备不属于任何舰队，因此它不能派发到任何地方。',
+  };
+}
+
+/**
+ * The devices a request may reach, given a device list and a requester.
+ *
+ * The single entry point the relay needs. It applies `scopeFleetId`, then `selectTargets`, and
+ * then — only in legacy mode — falls back to the unfiltered list, because that is exactly what
+ * the pre-v0.7.7 code did and a migration must not change behaviour for devices that were never
+ * asked to change.
+ *
+ * ## The case a first version got wrong
+ *
+ * `POST /v1/task` authenticates with the **operator token**, and an operator is not a device:
+ * `authorizeTaskDispatch` returns `{ role: 'operator', machine_id: null }`. So `requester` is
+ * routinely absent on the most common path, and an earlier version of this function refused it as
+ * `unknown_token` — which turned every operator-token dispatch into an error and broke 74 relay
+ * tests at once.
+ *
+ * An **absent** requester and an **unknown** one are therefore different things:
+ *
+ *   * absent, on an unscoped relay → the legacy rule, which is what an operator has always had;
+ *   * absent, on a scoped relay → refused, because there is no fleet to attribute the request to
+ *     and handing it the run of the fleet is the silent grant this work exists to remove;
+ *   * unknown (a machine id that is not in the device table) → refused, always, because a token
+ *     that maps to nothing is a broken caller rather than a legitimate operator.
+ *
+ * @param {object} input
+ * @param {Array<object>} input.devices Every device the relay holds.
+ * @param {object|null|undefined} input.requester The requester's device record, or absent for an
+ *        operator-token dispatch.
+ * @param {string[]} [input.targetMachines]
+ * @param {string|null} [input.relayFleetId]
+ * @param {boolean} [input.requireOnline]
+ */
+export function targetsFor({ devices, requester, targetMachines, relayFleetId = null, requireOnline = true }) {
+  const relayScoped = typeof relayFleetId === 'string' && relayFleetId !== '';
+
+  // An operator-token caller has no device at all, which is a legitimate identity rather than a
+  // broken one. On an unscoped relay it gets exactly the pre-v0.7.7 rule.
+  if (requester === null || requester === undefined) {
+    if (!relayScoped) return legacyTargets({ devices, targetMachines, requireOnline, reason: 'operator' });
+    return {
+      ok: false,
+      reason: WIRING_REFUSAL.REQUESTER_HAS_NO_FLEET,
+      text: '这个 relay 已绑定到一条舰队，而这个请求没有可以归属的设备身份，因此不能派发。',
+      legacy: false,
+    };
+  }
+
+  const scope = scopeFleetId({ device: requester, relayFleetId });
+  if (!scope.ok) return { ok: false, reason: scope.reason, text: scope.text, legacy: false };
+
+  if (scope.legacy) return legacyTargets({ devices, targetMachines, requireOnline, reason: 'fleetless' });
+
+  const result = selectTargets({ devices, fleetId: scope.fleetId, targetMachines, requireOnline });
+  return result.ok ? { ...result, legacy: false } : { ...result, legacy: false };
+}
+
+/** The pre-v0.7.7 rule, in one place so both callers cannot drift apart. */
+function legacyTargets({ devices, targetMachines, requireOnline, reason }) {
+  const all = Array.isArray(devices) ? devices : [];
+  const chosen = Array.isArray(targetMachines) && targetMachines.length > 0
+    ? all.filter((d) => targetMachines.includes(d.machine_id))
+    : all;
+  const offline = chosen.filter((d) => d.online === false).map((d) => d.machine_id);
+  const targets = requireOnline ? chosen.filter((d) => d.online !== false) : chosen;
+  if (targets.length === 0) {
+    return {
+      ok: false,
+      reason: SCOPE_REFUSAL.NO_DEVICE_IN_FLEET,
+      text: offline.length > 0 ? '没有在线设备。' : 'relay 上没有任何设备。',
+      legacy: true,
+    };
+  }
+  return { ok: true, targets, skippedOffline: offline, legacy: true, legacyReason: reason };
+}
+
+/**
+ * The `fleet_id` a pairing code admits to, in the shape `state.mjs` stores.
+ *
+ * Returns `null` for a code that predates fleets, which is what keeps an existing relay working:
+ * a code issued before this release pairs a device into no fleet, and the relay's own mode decides
+ * what that means.
+ */
+export function fleetForPairingCode(codeRecord) {
+  if (codeRecord === null || typeof codeRecord !== 'object') return null;
+  const fleet = codeRecord.fleet_id;
+  return typeof fleet === 'string' && fleet !== '' ? fleet : null;
+}
+
+/**
+ * The device fields that carry fleet membership, for a record the relay is about to write.
+ *
+ * Kept as a function so the "the fleet came from the code" rule lives in one place: a caller that
+ * builds a device literal by hand is the way a device ends up choosing its own fleet.
+ */
+/**
+ * The `fleet_id` a device joins, and **where that fact came from**.
+ *
+ * Three sources, in order of authority, and the order is the whole security argument:
+ *
+ * | source | who decided | why |
+ * |---|---|---|
+ * | `pairing_code` | the operator, by issuing the code | explicit intent, and the only source that can place a device in a fleet it could not compute |
+ * | `fleet_key` | the account, by derivation | the auto-join path: the device proves membership by holding the key |
+ * | `request` | the relay operator, via `--fleet` | a relay that serves one fleet and is told which |
+ *
+ * ## Why the key is *derived from* rather than *compared against*
+ *
+ * A device presenting a `fleet_key` is **assigned** the fleet id computed from that key —
+ * `SHA-256(key)`. The relay does not decide whether to believe a claimed fleet id; it computes one.
+ * So a device can only ever land in the fleet whose key it holds, there is no trust-on-first-use to
+ * get wrong, and nothing to forge: a device without the key forms a different, empty fleet rather
+ * than joining somebody else's.
+ *
+ * This is what lets a second machine on one account join with **no human step and no relay
+ * configuration** — the gap that let a new PC sit invisible next to its own fleet.
+ *
+ * @param {object} input
+ * @param {object|null} input.codeRecord The pairing code's record, if one was used.
+ * @param {string|null} [input.fleetKeyEncoded] The account-derived key, if the device offered one.
+ * @param {string|null} [input.requestedFleet] An explicit fleet from the relay's own configuration.
+ * @returns {{fleet_id: string|null, fleet_source: string|null, fleet_reason?: string}}
+ */
+export function deviceFleetFields({ codeRecord, fleetKeyEncoded = null, requestedFleet = null }) {
+  const fromCode = fleetForPairingCode(codeRecord);
+  if (fromCode !== null) {
+    /**
+     * The provenance has to say *how* the fleet was established, and a first version did not: it
+     * reported `pairing_code` for a device that never presented one, because the relay builds a
+     * synthetic code record for the key path so the binding reads from a single place.
+     *
+     * That mattered. `fleet_source` is what an operator reads in `devices.json` to answer *"how did
+     * this machine get into my fleet?"* — and answering "a pairing code" when there was none sends
+     * them looking for a code that was never issued. Found by a live pairing test, not by reading.
+     */
+    if (codeRecord?.from_fleet_key === true) return { fleet_id: fromCode, fleet_source: 'fleet_key' };
+    return { fleet_id: fromCode, fleet_source: 'pairing_code' };
+  }
+
+  /**
+   * The auto-join path. Tried before the operator's `--fleet` so that a device which knows its own
+   * account lands in its own fleet rather than being absorbed into whatever fleet the relay serves —
+   * a relay configured for one account must not silently become the wrong fleet for a device whose
+   * account says otherwise.
+   */
+  if (typeof fleetKeyEncoded === 'string' && fleetKeyEncoded !== '') {
+    const join = planJoin({ fleetKeyEncoded });
+    if (join.ok) return { fleet_id: join.fleetId, fleet_source: 'fleet_key' };
+    /**
+     * A malformed key does **not** pair the device into the relay's own fleet. Falling through would
+     * be the silent wrong answer: a device that meant to join its account would instead be placed in
+     * an unrelated fleet and told nothing.
+     */
+    return { fleet_id: null, fleet_source: null, fleet_reason: join.reason };
+  }
+
+  if (typeof requestedFleet === 'string' && requestedFleet !== '') {
+    // Recorded with its provenance so a fleet that arrived from a request is visible as such in
+    // `devices.json` rather than looking identical to one that came from a code or a key.
+    return { fleet_id: requestedFleet, fleet_source: 'request' };
+  }
+  return { fleet_id: null, fleet_source: null };
+}
+
+/**
+ * A one-line description of the scoping decision, for a log.
+ *
+ * Deliberately includes the legacy flag: an operator reading logs during a migration needs to see
+ * *which* rule applied, and "4 targets" alone does not say whether isolation is on.
+ */
+export function describeScope({ scope, targetCount }) {
+  if (!scope.ok) return `scoped: refused (${scope.reason})`;
+  if (scope.legacy) return `scoped: legacy (no fleet on this relay), ${targetCount} target(s)`;
+  return `scoped: fleet ${scope.fleetId}, ${targetCount} target(s)`;
+}