@twinsearth/w2m-dsh-plugin 0.8.0 → 0.8.2

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: '既没有已登录的账号，也没有舰队密钥，无法确定属于哪条舰队。',
+  };
+}

package/src/chatops/fleet-wiring.mjs

@@ -34,6 +34,8 @@
  */
 
 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({
@@ -174,13 +176,70 @@ export function fleetForPairingCode(codeRecord) {
  * 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.
  */
-export function deviceFleetFields({ codeRecord, requestedFleet }) {
+/**
+ * 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) return { fleet_id: fromCode, fleet_source: 'pairing_code' };
+  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 !== '') {
-    // Reachable only when the relay has no fleet of its own and an operator passed one explicitly.
     // 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.
+    // `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 };

package/src/chatops/ilink-fleet-bridge.mjs

@@ -0,0 +1,197 @@
+/**
+ * The bridge: a WeChat message becomes a fleet task, and the verdict goes back (v0.7.12).
+ *
+ * ## Every field name here was measured, not guessed
+ *
+ * Four separate wrong guesses about this protocol made a working feature look broken — including a
+ * false conclusion that the login token lived only 30 seconds. So the wire shapes are recorded with
+ * where they came from, and a test asserts them rather than the documentation:
+ *
+ * | shape | measured value |
+ * |---|---|
+ * | poll response | `{ msgs, sync_buf, get_updates_buf }` — the cursor is `get_updates_buf`, **not** `buf` |
+ * | message text | `item_list[0].text_item.text` — **not** `content` |
+ * | sender | `from_user_id` |
+ * | reply success | `{ message_id }` with **no** `ret` and **no** `errcode` |
+ * | login confirmation | status `confirmed`, **not** `scaned` |
+ *
+ * ## What this module does not do
+ *
+ * It does not decide authorisation. `parseInvocation` reports which **capability** a form needs, and
+ * the caller supplies an `authorize` function — because the rule "authorisation is checked before
+ * the handler runs, never inside it" is what stops a handler becoming reachable by forgetting its
+ * own guard, and a bridge that checked its own permission would be exactly that mistake.
+ */
+
+import { parseInvocation, renderVerdict, renderDispatchFailure } from './run-command.mjs';
+
+/** The header every authenticated call needs; undocumented and mandatory. */
+export const AUTH_TYPE = 'ilink_bot_token';
+export const APP_ID = 'bot';
+/** 2.4.6, as the reference client sends. */
+export const CLIENT_VERSION = String((2 << 16) | (4 << 8) | 6);
+
+/** Message item types. Only text is dispatched; the rest are acknowledged and ignored. */
+export const ITEM_TYPE = Object.freeze({ TEXT: 1 });
+/** `2` is BOT-originated, which is what our replies are. */
+export const MESSAGE_TYPE = Object.freeze({ USER: 1, BOT: 2 });
+/** `2` is FINISH — a complete message rather than a streaming fragment. */
+export const MESSAGE_STATE_FINISH = 2;
+
+/**
+ * Build the request headers.
+ *
+ * `X-WECHAT-UIN` is a fresh random uint32 as a decimal string, base64-encoded, on **every** request.
+ * It is not a session id and must not be cached.
+ *
+ * @param {object} input
+ * @param {string} [input.token]
+ * @param {() => string} [input.makeUin]
+ */
+export function buildHeaders({ token, makeUin }) {
+  const headers = {
+    'content-type': 'application/json',
+    'iLink-App-Id': APP_ID,
+    'iLink-App-ClientVersion': CLIENT_VERSION,
+    AuthorizationType: AUTH_TYPE,
+  };
+  if (typeof makeUin === 'function') headers['X-WECHAT-UIN'] = makeUin();
+  if (typeof token === 'string' && token !== '') headers.authorization = `Bearer ${token}`;
+  return headers;
+}
+
+/** The text of a message, or null when it carries none. */
+export function textOf(message) {
+  const items = Array.isArray(message?.item_list) ? message.item_list : [];
+  for (const item of items) {
+    if (item?.type === ITEM_TYPE.TEXT) {
+      const text = item?.text_item?.text;
+      if (typeof text === 'string') return text;
+    }
+  }
+  return null;
+}
+
+/**
+ * The reply envelope.
+ *
+ * `context_token` is **mandatory and comes from the inbound message**: without it the reply is not
+ * associated with the conversation. `message_state: 2` is FINISH — a first version omitted it and
+ * the endpoint answered `ret: -2, invalid arguments` for eight different payload shapes before the
+ * documented envelope was found.
+ */
+export function buildReply({ toUserId, contextToken, text }) {
+  return {
+    msg: {
+      to_user_id: toUserId,
+      message_type: MESSAGE_TYPE.BOT,
+      message_state: MESSAGE_STATE_FINISH,
+      context_token: contextToken,
+      item_list: [{ type: ITEM_TYPE.TEXT, text_item: { text } }],
+    },
+  };
+}
+
+/** Whether a send succeeded. Success carries a `message_id` and **no** `ret`. */
+export function sendSucceeded(response) {
+  if (response === null || typeof response !== 'object') return false;
+  if (typeof response.message_id !== 'undefined' && response.message_id !== null) return true;
+  return response.ret === 0 || response.errcode === 0;
+}
+
+/**
+ * Decide what to do with one inbound message.
+ *
+ * Returns a **plan** rather than performing it, so the decision is testable without a relay, a
+ * socket, or a clock — and so the caller can see authorisation checked in one place.
+ *
+ * @param {object} input
+ * @param {object} input.message One `msgs[]` entry.
+ * @param {(capability: string) => boolean} input.authorize
+ * @returns {{act: 'ignore', why: string}
+ *          | {act: 'reply', to: string, contextToken: string, text: string}
+ *          | {act: 'dispatch', to: string, contextToken: string, argv: string[], flags: object, ack: string}}
+ */
+export function planMessage({ message, authorize }) {
+  const from = message?.from_user_id;
+  const contextToken = message?.context_token;
+  const text = textOf(message);
+
+  if (typeof from !== 'string' || from === '') return { act: 'ignore', why: 'no sender' };
+  if (typeof contextToken !== 'string' || contextToken === '') return { act: 'ignore', why: 'no context_token' };
+  if (text === null) return { act: 'ignore', why: 'not a text message' };
+
+  const trimmed = text.trim();
+  // Only the exact `/run` prefix is an action. Everything else is conversation, which is what keeps
+  // a typo from becoming a fleet execution.
+  if (!/^\/run(\s|$)/i.test(trimmed)) return { act: 'ignore', why: 'not a /run line' };
+
+  const body = trimmed.replace(/^\/run\s*/i, '');
+  const invocation = parseInvocation(body);
+
+  if (invocation.kind === 'refused') {
+    return { act: 'reply', to: from, contextToken, text: invocation.text };
+  }
+
+  const capability = invocation.capability;
+  if (typeof authorize === 'function' && authorize(capability) !== true) {
+    return {
+      act: 'reply',
+      to: from,
+      contextToken,
+      text: `这个窗口没有 ${capability} 权限，不能执行。`,
+    };
+  }
+
+  if (invocation.kind === 'ask') {
+    /**
+     * The beginner form is answered, not executed.
+     *
+     * It does **not** reach the fleet from here: the request is a sentence, and turning a sentence
+     * into a command inside the bridge would reintroduce exactly the inference `/run --ask` exists
+     * to avoid. The reply says what to send instead, so the low-privilege path stays a path to a
+     * *proposal* rather than to an execution.
+     */
+    return {
+      act: 'reply',
+      to: from,
+      contextToken,
+      text:
+        `收到你的请求：${invocation.text}\n\n`
+        + '这是低权限的「提问」模式，我不会直接执行。\n'
+        + '如果要真的运行，请把确切的命令发给我，例如：\n'
+        + `  /run ${invocation.text.split(/\s+/).slice(0, 3).join(' ')}`,
+    };
+  }
+
+  return {
+    act: 'dispatch',
+    to: from,
+    contextToken,
+    argv: invocation.argv,
+    flags: invocation.flags,
+    // Acknowledged before dispatch: a fleet run can take a minute, and silence reads as "broken".
+    ack: `已派发：${invocation.argv.join(' ')}\n模式：${invocation.flags.mode}\n等我回报结果…`,
+  };
+}
+
+/**
+ * Render a completed task for the chat window.
+ *
+ * Reuses `renderVerdict`, which already caps the machine list and states the truncation — a list
+ * that silently stops at ten reads as "ten machines" rather than "ten shown".
+ */
+export function renderTaskOutcome({ taskId, body }) {
+  const verdict = body?.aggregate?.status ?? body?.status ?? body?.verdict ?? 'unknown';
+  const rows = body?.machines ?? body?.leases ?? body?.results ?? [];
+  return `${renderVerdict({ taskId, verdict, machines: rows }).text}`;
+}
+
+/** Render a dispatch that never became a task. */
+export function renderFailure(error) {
+  return renderDispatchFailure({
+    code: error?.code ?? error?.error?.code,
+    reason: error?.detail?.reason ?? error?.error?.detail?.reason,
+    detail: error?.detail?.hint ?? error?.error?.detail?.hint ?? error?.message,
+  });
+}