@twinsearth/w2m-dsh-plugin 0.6.3 → 0.8.0

package/src/chatops/durability.mjs

@@ -0,0 +1,202 @@
+/**
+ * Durability policy: how many copies exist, where, and what happens as the fleet grows (v0.7.12).
+ *
+ * ## The requirement, and the trap inside it
+ *
+ * The stated requirement is **"tolerate losing 90% of nodes and still recover"**, described as
+ * "10× redundancy". Those are two different claims, and conflating them produces a system that
+ * *looks* compliant and is not:
+ *
+ *   * **10 replicas** is a property of the *storage layout* — each object is written to 10 places.
+ *     It is **impossible** below 10 nodes: there are not 10 places to write to.
+ *   * **Surviving 90% loss** is a property of the *whole system*, counting every copy including the
+ *     authoritative one. It is achievable below 10 nodes **only because the server holds a complete
+ *     copy**.
+ *
+ * So with 3 machines and a nominal 10× target, the honest statement is:
+ *
+ * > the devices hold at most 3 copies, and **the 90% guarantee is met by the server's full copy,
+ * > not by device redundancy.**
+ *
+ * That distinction is not pedantry — it changes the design. It means the server is **not "one more
+ * replica"** that can be dropped when devices are plentiful; it is the authority, and the tier
+ * policy below keeps it complete at every stage.
+ *
+ * ## The tiers, as specified
+ *
+ * | devices | primary | server's role |
+ * |---|---|---|
+ * | < 100 | the server | authority and sole complete copy |
+ * | 100 – 1000 | the server, with devices holding copies | authority, refreshed from devices |
+ * | > 1000 | the devices | **fallback**, must never be deleted |
+ *
+ * The thresholds are inclusive-at-the-bottom, so 100 devices is already the middle tier and 1000 is
+ * already distributed-primary. Stated because an off-by-one here silently changes where the
+ * authority lives.
+ */
+
+/** The requirement, as one number: lose this fraction of *all* copies and still recover. */
+export const REQUIRED_LOSS_TOLERANCE = 0.9;
+
+/** The nominal replication target. A layout goal, **not** achievable below this many nodes. */
+export const NOMINAL_REPLICATION = 10;
+
+/** Where the authority lives. */
+export const TIER = Object.freeze({
+  /** Fewer than `deviceThreshold` devices: the server is the only complete copy. */
+  SERVER: 'server',
+  /** Devices keep copies, the server stays authoritative. */
+  HYBRID: 'hybrid',
+  /** Devices are primary; the server is a fallback that must not be deleted from. */
+  DISTRIBUTED: 'distributed',
+});
+
+export const DEFAULT_THRESHOLDS = Object.freeze({
+  /** At or above this many devices, devices start holding copies. */
+  hybridAt: 100,
+  /** At or above this many devices, devices are primary and the server is a fallback. */
+  distributedAt: 1000,
+});
+
+/**
+ * Which tier a fleet of `deviceCount` devices is in.
+ *
+ * `deviceCount` is **live, paired devices**, not a configured maximum: a fleet of 1000 that is
+ * currently 3 machines online is a 3-machine fleet for the purpose of where the authority sits.
+ * Using the configured size would move the authority to devices that are not there.
+ */
+export function tierFor(deviceCount, thresholds = DEFAULT_THRESHOLDS) {
+  const n = Number.isFinite(deviceCount) && deviceCount > 0 ? Math.floor(deviceCount) : 0;
+  const { hybridAt, distributedAt } = { ...DEFAULT_THRESHOLDS, ...thresholds };
+  if (n >= distributedAt) return TIER.DISTRIBUTED;
+  if (n >= hybridAt) return TIER.HYBRID;
+  return TIER.SERVER;
+}
+
+/**
+ * The replication factor actually achievable, which is **bounded by the node count**.
+ *
+ * This is the function the "10×" claim needs and usually does not have: asking for 10 replicas
+ * across 3 nodes is not 10 copies, it is 3 copies and a log line. Returning the achievable number
+ * means a caller can report the truth instead of the target.
+ *
+ * @param {object} input
+ * @param {number} input.deviceCount Live devices.
+ * @param {number} [input.withServer] Whether the server's own copy counts toward the total.
+ * @param {number} [input.target] The nominal goal.
+ */
+export function achievableReplication({ deviceCount, withServer = true, target = NOMINAL_REPLICATION }) {
+  const n = Number.isFinite(deviceCount) && deviceCount > 0 ? Math.floor(deviceCount) : 0;
+  const places = n + (withServer ? 1 : 0);
+  return { requested: target, achievable: Math.min(target, places), places, limitedByNodes: places < target };
+}
+
+/**
+ * How much of the fleet can be lost while the data is still recoverable.
+ *
+ * **The recoverable condition is a surviving complete copy**, not "one replica left standing": a
+ * replica set is only as good as its ability to reconstruct the whole object. So this counts the
+ * server as one complete copy and devices as *partial* copies unless the device set itself holds
+ * `target` replicas of every object.
+ *
+ * Returns a fraction, so the caller compares against `REQUIRED_LOSS_TOLERANCE` rather than
+ * re-deriving the arithmetic.
+ *
+ * @param {object} input
+ * @param {number} input.deviceCount Live devices holding copies.
+ * @param {boolean} [input.serverComplete] Whether the server holds a complete copy. Defaults true,
+ *        and the tier policy requires it at every tier.
+ * @param {number} [input.target] Nominal replication goal.
+ */
+export function lossTolerance({ deviceCount, serverComplete = true, target = NOMINAL_REPLICATION }) {
+  const n = Number.isFinite(deviceCount) && deviceCount > 0 ? Math.floor(deviceCount) : 0;
+  const { achievable, limitedByNodes } = achievableReplication({ deviceCount: n, withServer: false, target });
+
+  /**
+   * The server alone survives the loss of **every** device: it is a complete copy, so 100%.
+   *
+   * This is what makes the 90% requirement satisfiable at any fleet size — and it is also why the
+   * server must never be deleted from. If the server's copy were dropped to save space once devices
+   * held copies, the guarantee would vanish exactly when the fleet looked big enough to trust.
+   */
+  if (serverComplete) {
+    return {
+      tolerate: 1,
+      reason: 'server_complete',
+      deviceReplicas: achievable,
+      limitedByNodes,
+      /** The guarantee holds regardless of device loss, because the server copy is complete. */
+      independentOfDevices: true,
+    };
+  }
+
+  // No complete server copy: the devices must reconstruct from their own replicas, so the fraction
+  // that can be lost is bounded by how many copies actually exist.
+  if (achievable <= 1) {
+    return { tolerate: 0, reason: 'single_copy', deviceReplicas: achievable, limitedByNodes, independentOfDevices: false };
+  }
+  const tolerate = 1 - 1 / achievable;
+  return {
+    tolerate,
+    reason: 'device_replicas_only',
+    deviceReplicas: achievable,
+    limitedByNodes,
+    independentOfDevices: false,
+    /** True when this arrangement actually meets the stated requirement on its own. */
+    meetsRequirement: tolerate >= REQUIRED_LOSS_TOLERANCE,
+  };
+}
+
+/**
+ * The whole answer for one fleet, in the shape an operator or a health endpoint wants.
+ *
+ * Deliberately reports **where the guarantee comes from**. "health: 100%" with no provenance is the
+ * reading that lets someone delete the server copy and discover the problem later.
+ */
+export function durabilityReport({ deviceCount, thresholds = DEFAULT_THRESHOLDS, serverComplete = true, target = NOMINAL_REPLICATION }) {
+  const tier = tierFor(deviceCount, thresholds);
+  const loss = lossTolerance({ deviceCount, serverComplete, target });
+  const replication = achievableReplication({ deviceCount, withServer: false, target });
+  return {
+    device_count: Number.isFinite(deviceCount) ? Math.floor(deviceCount) : 0,
+    tier,
+    /** The nominal goal and what the fleet can actually do, side by side. */
+    replication_target: target,
+    replication_device_copies: replication.achievable,
+    replication_limited_by_nodes: replication.limitedByNodes,
+    loss_tolerated: loss.tolerate,
+    required_loss_tolerance: REQUIRED_LOSS_TOLERANCE,
+    meets_required_tolerance: loss.tolerate >= REQUIRED_LOSS_TOLERANCE,
+    guarantee_basis: loss.reason,
+    server_copy_required: true,
+    /** Named so the health number can never be read without its provenance. */
+    note:
+      loss.reason === 'server_complete'
+        ? `the guarantee is the server's complete copy, not device redundancy: with ${Number.isFinite(deviceCount) ? Math.floor(deviceCount) : 0} device(s) `
+          + `only ${replication.achievable} device copies exist${replication.limitedByNodes ? `, short of the nominal ${target}` : ''}. `
+          + 'Deleting the server copy would remove the guarantee.'
+        : 'there is no complete server copy, so recovery depends on the device replicas alone',
+  };
+}
+
+/**
+ * How refreshing should be routed for a tier.
+ *
+ * The tier decides **who is asked first**, not who is trusted: the server is authoritative in every
+ * tier, so a disagreement is resolved by the server rather than by a quorum of devices.
+ */
+export function refreshPlan({ tier, serverHealthy = true }) {
+  if (!serverHealthy) {
+    // The server is a fallback that must never be deleted from, so an unhealthy server still gets
+    // written to and read from once it returns — the plan says "degraded", not "skip".
+    return { order: ['devices', 'server'], degraded: true, reason: 'server_unhealthy' };
+  }
+  if (tier === TIER.DISTRIBUTED) {
+    // Devices are primary for *serving*, the server still receives every write.
+    return { order: ['devices', 'server'], degraded: false, reason: 'distributed_primary' };
+  }
+  if (tier === TIER.HYBRID) {
+    return { order: ['server', 'devices'], degraded: false, reason: 'server_primary_with_device_copies' };
+  }
+  return { order: ['server'], degraded: false, reason: 'server_only' };
+}

package/src/chatops/file-safety.mjs

@@ -0,0 +1,282 @@
+/**
+ * Reading a file out of the project, safely (v0.7.0).
+ *
+ * ## The two defects this file exists to make impossible
+ *
+ * **1. A lexical fence is not a fence.** `dsh-chatops` 0.1.0 resolved the requested
+ * path and compared prefixes:
+ *
+ *     const abs = resolve(cwd, relPath)
+ *     if (abs !== cwd && !abs.startsWith(cwd + sep)) { refuse }
+ *
+ * `resolve()` normalises `..` but does **not** resolve symlinks, and `statSync` and
+ * `readFile` both follow them. A symlink *inside* the project pointing anywhere
+ * readable — `~/.dsh/.credentials.yaml` on the machine this was audited against —
+ * resolves to a path that still begins with the project root, so the check passes and
+ * `/send` ships the target's contents to a chat platform. The containment check has to
+ * be performed on the **real** path, which means resolving symlinks on both sides and
+ * re-checking after resolution, because the target itself may be a link.
+ *
+ * **2. A delivery that failed must not be reported as delivered.** Only one of that
+ * plugin's four channels re-threw a failed send; the other three logged, told the user
+ * "❌ 发送失败", and then returned normally — so the caller counted the file as sent and
+ * the model was told `已发送到 N 个 IM 窗口`. The read side here returns a discriminated
+ * result rather than throwing, and the send side is required to turn a failure into a
+ * failed result. Neither layer is allowed to guess.
+ *
+ * ## What this module is
+ *
+ * Pure I/O with injected `stat`/`realpath`/`readFile`, so every refusal is testable
+ * without a real filesystem and without a symlink that has to exist on the host running
+ * the tests. Nothing here knows about chat platforms.
+ */
+
+/**
+ * Path arithmetic is done in **posix** terms, on every platform.
+ *
+ * Two reasons, and the second is the one that matters. A relay, a Linux VPS and a
+ * container image all speak `/`; and a fence whose containment logic depends on
+ * `node:path`'s platform-specific `sep` cannot be tested for symlink escapes on Windows,
+ * which is where the fence is most needed and where the plugin that got this wrong was
+ * developed. Choosing one separator makes the logic identical everywhere and testable
+ * from a POSIX-only fixture, which is what the suite does.
+ */
+import { resolve, sep, isAbsolute, basename, extname } from 'node:path/posix';
+
+/** Why a file was not sent. Reported, never thrown: a refusal is a normal answer. */
+export const FILE_REFUSAL = Object.freeze({
+  /** The path escaped the project root, after symlinks were resolved. */
+  ESCAPED: 'escaped_project',
+  /** The path is absolute, or otherwise not project-relative. */
+  NOT_RELATIVE: 'not_relative',
+  /** Nothing is there. */
+  MISSING: 'missing',
+  /** It exists and is not a regular file. */
+  NOT_A_FILE: 'not_a_file',
+  /** Larger than the configured ceiling. */
+  TOO_LARGE: 'too_large',
+  /** The extension is one the fleet refuses to move through a chat platform. */
+  TYPE_REFUSED: 'type_refused',
+  /** The path is structurally unusable. */
+  MALFORMED: 'malformed',
+});
+
+/**
+ * Extensions that are never sent, whatever the operator asks for.
+ *
+ * A chat platform is a third-party service and a message is not a filesystem. This is
+ * deliberately a **deny-list of shapes** rather than an allow-list of extensions: the
+ * useful case is "send me the log / the screenshot / the report", and an allow-list
+ * would refuse the perfectly ordinary file someone actually wanted. What is refused is
+ * the set whose contents are credentials or executable code, where "I asked for it" is
+ * not a good enough reason.
+ */
+export const REFUSED_EXTENSIONS = Object.freeze([
+  '.pem', '.key', '.p12', '.pfx', '.jks', '.keystore',
+  '.env', '.credentials', '.secret', '.secrets',
+  '.exe', '.dll', '.so', '.dylib', '.msi', '.bat', '.cmd', '.ps1', '.sh', '.app',
+]);
+
+/** Name fragments refused regardless of extension: `.env.local`, `id_rsa`, `foo.pem.bak`. */
+const REFUSED_NAME_PATTERNS = Object.freeze([
+  /^\.env(\..*)?$/i,
+  /^id_(rsa|dsa|ecdsa|ed25519)(\..*)?$/i,
+  /(^|[._-])(secret|credential|password|passwd|token)s?([._-]|$)/i,
+]);
+
+/**
+ * Default ceiling. A chat platform will refuse a large file anyway, and the failure
+ * should be ours, named, before the upload starts — not the platform's, after it has
+ * half-sent something.
+ */
+export const DEFAULT_MAX_BYTES = 100 * 1024 * 1024;
+
+/**
+ * Create a reader bound to one project root.
+ *
+ * @param {object} options
+ * @param {string} options.projectRoot Absolute project root. The fence is this directory.
+ * @param {number} [options.maxBytes]
+ * @param {string[]} [options.extraRefusedExtensions]
+ * @param {string[]} [options.allowExtensions] Escape hatch: these are permitted even if refused above.
+ * @param {(p: string) => Promise<{isFile: () => boolean, size: number, isSymbolicLink?: () => boolean}>} [options.lstat]
+ * @param {(p: string) => Promise<string>} [options.realpath]
+ * @param {(p: string) => Promise<Buffer>} [options.readFile]
+ * @param {(event: string, detail?: object) => void} [options.audit]
+ */
+export function createFileReader(options) {
+  const { projectRoot } = options;
+  if (typeof projectRoot !== 'string' || projectRoot === '') {
+    throw new TypeError('createFileReader requires a projectRoot');
+  }
+  const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+  const audit = options.audit ?? (() => {});
+  const refusedExtensions = new Set(
+    [...REFUSED_EXTENSIONS, ...(options.extraRefusedExtensions ?? [])].map((e) => e.toLowerCase()),
+  );
+  const allowedExtensions = new Set((options.allowExtensions ?? []).map((e) => e.toLowerCase()));
+
+  const lstat = options.lstat ?? (async (p) => (await import('node:fs/promises')).lstat(p));
+  const realpath = options.realpath ?? (async (p) => (await import('node:fs/promises')).realpath(p));
+  const readFile = options.readFile ?? (async (p) => (await import('node:fs/promises')).readFile(p));
+
+  /**
+   * The real project root.
+   *
+   * A failure is **not** cached. Caching one would turn a transient problem — the
+   * workspace briefly unreadable during a checkout, say — into a reader that refuses
+   * every path for the rest of the process, with a stale reason.
+   */
+  let realRootCache = null;
+  async function realRoot() {
+    if (realRootCache !== null) return realRootCache;
+    const resolved = await realpath(projectRoot);
+    realRootCache = resolved;
+    return resolved;
+  }
+
+  /** Is `candidate` the root itself or inside it? Compared after symlink resolution. */
+  function contains(root, candidate) {
+    if (candidate === root) return true;
+    return candidate.startsWith(root.endsWith(sep) ? root : root + sep);
+  }
+
+  /**
+   * Read one project-relative file.
+   *
+   * @param {string} relPath
+   * @returns {Promise<{ok: true, path: string, name: string, bytes: number, data: Buffer}
+   *                  | {ok: false, reason: string, detail?: string}>}
+   */
+  async function read(relPath) {
+    if (typeof relPath !== 'string' || relPath.trim() === '') {
+      return refuse(FILE_REFUSAL.MALFORMED, 'empty path');
+    }
+    // An absolute path is not a project-relative one, and treating it as one is how a
+    // "relative to the project" API quietly becomes an arbitrary-read API.
+    if (isAbsolute(relPath)) return refuse(FILE_REFUSAL.NOT_RELATIVE, relPath);
+    // NUL bytes cannot appear in a real path and truncate in some syscalls.
+    if (relPath.includes('\u0000')) return refuse(FILE_REFUSAL.MALFORMED, 'NUL in path');
+
+    const root = await realRoot();
+    const lexical = resolve(root, relPath);
+
+    // Cheap refusal first, so a traversal never even reaches the filesystem.
+    if (!contains(root, lexical)) return refuse(FILE_REFUSAL.ESCAPED, `lexical: ${lexical}`);
+
+    let stats;
+    try {
+      stats = await lstat(lexical);
+    } catch {
+      return refuse(FILE_REFUSAL.MISSING, relPath);
+    }
+
+    // The real check. `realpath` follows every link in every component, so a symlinked
+    // directory halfway down the path is caught as surely as a symlinked leaf.
+    let real;
+    try {
+      real = await realpath(lexical);
+    } catch {
+      return refuse(FILE_REFUSAL.MISSING, relPath);
+    }
+    if (!contains(root, real)) {
+      // The one that 0.1.0 shipped: a link inside the project pointing out of it.
+      return refuse(FILE_REFUSAL.ESCAPED, `resolved: ${real}`);
+    }
+
+    const name = basename(real);
+    const ext = extname(name).toLowerCase();
+    if (!allowedExtensions.has(ext)) {
+      if (refusedExtensions.has(ext)) return refuse(FILE_REFUSAL.TYPE_REFUSED, ext);
+      if (REFUSED_NAME_PATTERNS.some((re) => re.test(name))) return refuse(FILE_REFUSAL.TYPE_REFUSED, name);
+    }
+
+    // `lstat` above describes the link; what matters for "is this a file" is the target.
+    let target;
+    try {
+      target = await lstat(real);
+    } catch {
+      return refuse(FILE_REFUSAL.MISSING, relPath);
+    }
+    if (!target.isFile()) return refuse(FILE_REFUSAL.NOT_A_FILE, relPath);
+    if (target.size > maxBytes) {
+      return refuse(FILE_REFUSAL.TOO_LARGE, `${target.size} > ${maxBytes}`);
+    }
+
+    const data = await readFile(real);
+    audit('file/read', { name, bytes: data.length });
+    return { ok: true, path: real, name, bytes: data.length, data };
+  }
+
+  function refuse(reason, detail) {
+    audit('file/refused', { reason, detail: detail ?? null });
+    return { ok: false, reason, detail };
+  }
+
+  return { read, get projectRoot() { return projectRoot; }, maxBytes };
+}
+
+/**
+ * Send one file to one destination, and be honest about whether it worked.
+ *
+ * The `send` callback is the channel's own upload. This wrapper exists so that the
+ * **only** way to report success is for `send` to have resolved: a rejected send
+ * becomes `{ok: false}` here, and the caller has no way to count it as delivered. That
+ * is the whole fix for "the tool told the model it sent four files and sent two".
+ *
+ * @param {object} options
+ * @param {(file: {name: string, bytes: number, data: Buffer}, caption: string) => Promise<void>} options.send
+ * @param {(event: string, detail?: object) => void} [options.audit]
+ */
+export function createFileSender(options) {
+  const send = options.send;
+  if (typeof send !== 'function') throw new TypeError('createFileSender requires a send()');
+  const audit = options.audit ?? (() => {});
+
+  /**
+   * @param {{name: string, bytes: number, data: Buffer}} file
+   * @param {string} [caption]
+   * @returns {Promise<{ok: true} | {ok: false, reason: string, detail?: string}>}
+   */
+  async function deliver(file, caption = '') {
+    try {
+      await send(file, caption);
+      audit('file/sent', { name: file.name, bytes: file.bytes });
+      return { ok: true };
+    } catch (error) {
+      // Named, not swallowed. A channel that logged this and returned would make the
+      // count in the caller's reply a lie.
+      const detail = error instanceof Error ? error.message : String(error);
+      audit('file/send-failed', { name: file.name, detail });
+      return { ok: false, reason: 'send_failed', detail };
+    }
+  }
+
+  return { deliver };
+}
+
+/**
+ * Fan one file out to several destinations and report the count truthfully.
+ *
+ * Returns the outcomes rather than a sentence, because the sentence 0.1.0 produced —
+ * "已发送到 N 个 IM 窗口" — was composed from the number of windows it *tried*, not the
+ * number that succeeded.
+ *
+ * @param {object} options
+ * @param {Array<{window: string, deliver: (file: object, caption: string) => Promise<{ok: boolean, [k: string]: unknown}>}>} options.targets
+ */
+export async function fanOutFile({ targets, file, caption = '' }) {
+  const results = await Promise.all(
+    targets.map(async (target) => ({ window: target.window, ...(await target.deliver(file, caption)) })),
+  );
+  const sent = results.filter((r) => r.ok).length;
+  const failed = results.filter((r) => !r.ok);
+  return {
+    sent,
+    attempted: results.length,
+    failed: failed.map((r) => ({ window: r.window, reason: r.reason, detail: r.detail })),
+    // Exactly true, and the caller is expected to use this rather than `attempted`.
+    allSent: sent === results.length && results.length > 0,
+    results,
+  };
+}

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),
+  };
+}