@twinsearth/w2m-dsh-plugin 0.6.3 → 0.8.2

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-join.mjs

@@ -0,0 +1,164 @@
+/**
+ * Joining a fleet by account, with no human copying a code (v0.8.1).
+ *
+ * ## The bug this fixes
+ *
+ * A new machine signed into the same DeepSeek account did **not** join the same fleet. The plugin
+ * computed its SN, derived `fleet` from the account code, logged it — and then never used it for
+ * anything. Membership still required a one-time pairing code typed by a human, so a second machine
+ * on the same account was invisible to the fleet.
+ *
+ * ## Why the account code could not simply be used as the credential
+ *
+ * `accountCode` is `sha256(userId)` truncated to **8 hex characters — 32 bits**. The module that
+ * defines it documents the trade honestly ("the cost of 32 bits, stated rather than hidden"), and
+ * for its purpose — grouping and display — the cost is fine.
+ *
+ * As a **credential** it is not fine: 2^32 is brute-forceable, so treating it as the thing that
+ * authorises joining would let anyone enumerate their way into any fleet. The bug was a
+ * conflation: a *grouping identifier* was doing duty as a *secret*.
+ *
+ * ## What actually works
+ *
+ * The machines of one account share something an outsider cannot obtain: the ability to **read
+ * `userId`** from the signed-in account. So the fleet secret is derived from it:
+ *
+ * ```
+ * fleetKey = HMAC-SHA256(userId, "w2m-fleet-v1")     256 bits, only same-account machines can compute
+ * fleetId  = SHA-256(fleetKey)                       what the relay groups by
+ * ```
+ *
+ * ## Why the relay needs to know nothing about accounts
+ *
+ * This is the property that makes the design simple: **presenting the key *is* the proof.** The
+ * relay derives `fleetId` from the key it is given, so a device can only ever land in the fleet
+ * whose key it holds. There is no trust-on-first-use to get wrong, no operator configuration, no
+ * account lookup, and nothing to forge — a device that does not know the key simply forms a
+ * different, empty fleet rather than joining somebody else's.
+ *
+ * It also means the wire carries a **derived** value rather than `userId`, so a relay (or anyone
+ * reading its state) learns a fleet's identity without learning the account's.
+ */
+
+import { createHmac, createHash, timingSafeEqual } from 'node:crypto';
+
+/** The derivation label. Changing it changes every fleet id, so it is versioned. */
+export const FLEET_KEY_LABEL = 'w2m-fleet-v1';
+
+/** `userId` is a UUID; anything shorter is not one, and deriving from it would weaken the key. */
+export const MIN_ACCOUNT_MATERIAL = 16;
+
+/**
+ * Derive the fleet key for an account.
+ *
+ * @param {string} userId The raw account id from the signed-in account, **not** the account code.
+ * @returns {Buffer} 32 bytes.
+ */
+export function deriveAccountFleetKey(userId) {
+  if (typeof userId !== 'string' || userId.trim() === '') {
+    throw new TypeError('deriveAccountFleetKey needs the account userId; the 32-bit account code is not a secret and will not do');
+  }
+  const material = userId.trim();
+  if (material.length < MIN_ACCOUNT_MATERIAL) {
+    /**
+     * Refused rather than accepted-and-weakened.
+     *
+     * A short value here is almost always the account *code* being passed by mistake, and deriving
+     * from 32 bits would produce a key that looks strong and is not — the failure would be silent,
+     * which is the worst kind for a credential.
+     */
+    throw new TypeError(
+      `the account material is ${material.length} characters, which is too short to derive a fleet key from. `
+      + 'This is usually the 8-hex account code rather than the account userId.',
+    );
+  }
+  return createHmac('sha256', material).update(FLEET_KEY_LABEL, 'utf8').digest();
+}
+
+/** The key as it travels: base64url, so it survives a header, a JSON string and a URL. */
+export function encodeFleetKey(key) {
+  return Buffer.from(key).toString('base64url');
+}
+
+/** Parse a transported key back to bytes. Returns null rather than throwing, for a network path. */
+export function decodeFleetKey(encoded) {
+  if (typeof encoded !== 'string' || encoded === '') return null;
+  try {
+    const buf = Buffer.from(encoded, 'base64url');
+    // A key is exactly 32 bytes; anything else is not one, and accepting a short buffer would
+    // silently weaken every comparison that follows.
+    return buf.length === 32 ? buf : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The id the relay groups by.
+ *
+ * Derived from the key rather than sent alongside it, so the two can never disagree — and so a
+ * device cannot claim a fleet id it does not hold the key for.
+ */
+export function fleetIdFromKey(key) {
+  if (!Buffer.isBuffer(key) || key.length !== 32) throw new TypeError('fleetIdFromKey needs a 32-byte key');
+  return createHash('sha256').update(key).digest('hex');
+}
+
+/**
+ * The relay-side check: does this key belong to the fleet it claims?
+ *
+ * Constant-time, because a comparison that leaks timing on a secret is a comparison that can be
+ * walked one byte at a time.
+ */
+export function fleetKeyMatches(expectedKey, presentedKey) {
+  if (!Buffer.isBuffer(expectedKey) || !Buffer.isBuffer(presentedKey)) return false;
+  if (expectedKey.length !== presentedKey.length) return false;
+  return timingSafeEqual(expectedKey, presentedKey);
+}
+
+/**
+ * Whether a fleet key is well-formed, for a relay that is about to store one.
+ *
+ * Deliberately shape-only: the relay has no way to know whether a key corresponds to a real
+ * account, and pretending otherwise would be a check that cannot fail honestly. What it *can* check
+ * is that the key is the right size, which is what stops a truncated or empty value becoming a
+ * fleet's identity.
+ */
+export function isWellFormedFleetKey(encoded) {
+  return decodeFleetKey(encoded) !== null;
+}
+
+/**
+ * The whole join decision, in one function, so the client and the relay cannot disagree.
+ *
+ * @param {object} input
+ * @param {string} input.userId The signed-in account id, when the caller is a client.
+ * @param {string} input.fleetKeyEncoded A key presented on the wire, when the caller is a relay.
+ * @returns {{ok: true, fleetId: string, fleetKey: string}
+ *          | {ok: false, reason: string, text: string}}
+ */
+export function planJoin({ userId = null, fleetKeyEncoded = null } = {}) {
+  if (typeof fleetKeyEncoded === 'string' && fleetKeyEncoded !== '') {
+    const key = decodeFleetKey(fleetKeyEncoded);
+    if (key === null) {
+      return { ok: false, reason: 'malformed_fleet_key', text: '这个舰队密钥格式不对（应为 32 字节的 base64url）。' };
+    }
+    return { ok: true, fleetId: fleetIdFromKey(key), fleetKey: encodeFleetKey(key) };
+  }
+
+  if (typeof userId === 'string' && userId.trim() !== '') {
+    let key;
+    try {
+      key = deriveAccountFleetKey(userId);
+    } catch (error) {
+      return { ok: false, reason: 'bad_account_material', text: error.message };
+    }
+    return { ok: true, fleetId: fleetIdFromKey(key), fleetKey: encodeFleetKey(key) };
+  }
+
+  return {
+    ok: false,
+    reason: 'no_identity',
+    text: '既没有已登录的账号，也没有舰队密钥，无法确定属于哪条舰队。',
+  };
+}