@twinsearth/w2m-dsh-plugin 0.6.3 → 0.8.2

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

package/src/chatops/ilink-protocol.mjs

@@ -0,0 +1,165 @@
+/**
+ * The WeChat (ClawBot / iLink) wire protocol, as measured (v0.7.1).
+ *
+ * ## Why this file exists
+ *
+ * v0.7.0 shipped an `ilink.mjs` built from *reading* the audited plugin's source, and every
+ * field name in it was wrong. Nine separate mismatches, all of which passed 237 tests, because
+ * those tests drove an injected transport and asserted on the requests we *constructed*
+ * rather than the requests WeChat *accepts*. A self-consistent suite cannot falsify its own
+ * assumptions.
+ *
+ * Everything below came from a live exchange — a real QR scan, a real bot, a real message in
+ * both directions. The comments name the response each constant was read from, so a future
+ * change can be checked against something rather than against a memory.
+ *
+ * ## The two things that cost the most time
+ *
+ * **`AuthorizationType: ilink_bot_token` is mandatory and undocumented.** Without it every
+ * authenticated endpoint answers `{"errcode":-14,"errmsg":"session timeout"}` — *including a
+ * request with no `Authorization` header at all*, because the server rejects on the missing
+ * type header before it ever looks at the credential. That is why the error reads as a dead
+ * session and sends you looking for an expiry bug that does not exist.
+ *
+ * **Business failures arrive as HTTP 200.** A success answers `{"ret":0,…}`; a failure answers
+ * `{"errcode":-14,"errmsg":"session timeout"}` with the same 200. Checking the status code is
+ * therefore not enough, and a client that does has a silent-failure bug in the one place it
+ * matters most.
+ */
+
+/** Where login happens. The only host reachable without a token. */
+export const QR_BASE_URL = 'https://ilinkai.weixin.qq.com/';
+
+/**
+ * Hosts an authenticated request may be sent to.
+ *
+ * Measured: the login response returns exactly `https://ilinkai.weixin.qq.com`. v0.7.0 also
+ * allowed `weixin.qq.com` and `api.weixin.qq.com` on a guess, which weakened the one guarantee
+ * that matters here — that the bot token only ever reaches WeChat's bot endpoint. An
+ * allow-list wider than the measurement is not caution, it is the absence of the check.
+ */
+export const ALLOWED_API_HOSTS = Object.freeze(['ilinkai.weixin.qq.com']);
+
+/** Sent on every request, authenticated or not. `iLink-App-Id: bot` is not the bot's id. */
+export const APP_ID = 'bot';
+/** `(2 << 16) | (4 << 8) | 6` — the reference client reports 2.4.6 as a packed integer. */
+export const CLIENT_VERSION = String((2 << 16) | (4 << 8) | 6); // '132102'
+/** `channel_version` inside `base_info`. */
+export const PROTOCOL_VERSION = '2.4.6';
+/** `bot_type` for the QR request. */
+export const BOT_TYPE = '3';
+/** `AuthorizationType`. Omitting this is the defect described at the top of this file. */
+export const AUTH_TYPE = 'ilink_bot_token';
+
+export const ENDPOINTS = Object.freeze({
+  QRCODE: 'ilink/bot/get_bot_qrcode',
+  QRCODE_STATUS: 'ilink/bot/get_qrcode_status',
+  UPDATES: 'ilink/bot/getupdates',
+  SEND: 'ilink/bot/sendmessage',
+  NOTIFY_START: 'ilink/bot/msg/notifystart',
+  NOTIFY_STOP: 'ilink/bot/msg/notifystop',
+});
+
+/** `base_info`, required in every request body. Measured in every accepted call. */
+export function baseInfo(agent = 'DeepSeekHarness/w2m') {
+  return { channel_version: PROTOCOL_VERSION, bot_agent: agent };
+}
+
+/** Login states, as strings. `scaned` is WeChat's spelling, not a typo here. */
+export const LOGIN_STATUS = Object.freeze({
+  WAIT: 'wait',
+  SCANED: 'scaned',
+  CONFIRMED: 'confirmed',
+  EXPIRED: 'expired',
+  SCANED_BUT_REDIRECT: 'scaned_but_redirect',
+  NEED_VERIFYCODE: 'need_verifycode',
+  VERIFY_CODE_BLOCKED: 'verify_code_blocked',
+  BINDED_REDIRECT: 'binded_redirect',
+});
+
+/** Message types and states, as measured. Inbound is 1; our outbound replies are 2. */
+export const MESSAGE = Object.freeze({
+  TYPE_INBOUND: 1,
+  TYPE_OUTBOUND: 2,
+  STATE: 2,
+  ITEM_TEXT: 1,
+});
+
+/**
+ * Is this response a success?
+ *
+ * Three shapes are accepted, because the server uses three and only one of them is documented
+ * by its own field names:
+ *
+ *   * `{"ret":0, ...}` — the QR, status, notifystart and getupdates calls.
+ *   * `{"message_id":...}` — `sendmessage`. **Measured**: a delivered reply came back with a
+ *     `message_id` and *no* `ret` at all, so a strict `ret === 0` check reports a successful
+ *     send as a failure. That was caught by this suite, which is the point of it.
+ *   * `{"errcode":0}` — an explicit zero, which some WeChat endpoints use.
+ *
+ * A body with none of these is **not** a success: an unknown shape is an unknown outcome, and
+ * guessing in the permissive direction is how a refusal gets counted as a delivery.
+ */
+export function isOk(body) {
+  if (body === null || typeof body !== 'object') return false;
+  if (body.errcode !== undefined && body.errcode !== 0) return false;
+  if (body.ret !== undefined) return body.ret === 0;
+  if (body.errcode === 0) return true;
+  // `sendmessage`'s success shape, measured.
+  return body.message_id !== undefined && body.message_id !== null;
+}
+
+/** The reason a response carries, for a log or an error. Never invented. */
+export function failureOf(body) {
+  if (body === null || typeof body !== 'object') return { errcode: null, errmsg: 'the response was not an object' };
+  return {
+    errcode: body.errcode ?? null,
+    errmsg: body.errmsg ?? body.err_msg ?? body.message ?? null,
+  };
+}
+
+/**
+ * Is this a URL the bot token may be sent to?
+ *
+ * Checked on the parsed hostname, not a string prefix: `ilinkai.weixin.qq.com.attacker.example`
+ * ends with a plausible string and is not WeChat.
+ */
+export function isAllowedApiUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return { ok: false, reason: 'not a url' };
+  }
+  if (parsed.protocol !== 'https:') {
+    return { ok: false, reason: `the base url is ${parsed.protocol}//, and a bearer token goes over https only` };
+  }
+  const host = parsed.hostname.toLowerCase();
+  if (!ALLOWED_API_HOSTS.includes(host)) {
+    return { ok: false, reason: `${host} is not a host this channel will send a token to` };
+  }
+  return { ok: true };
+}
+
+/**
+ * Text out of an inbound message, using the shape a live response actually has:
+ *
+ *     item_list: [{ type: 1, text_item: { text: "..." }, ... }]
+ */
+export function extractText(message) {
+  const items = Array.isArray(message?.item_list) ? message.item_list : [];
+  const parts = [];
+  for (const item of items) {
+    const text = item?.text_item?.text;
+    if (typeof text === 'string' && text !== '') parts.push(text);
+  }
+  return parts.length === 0 ? null : parts.join('\n');
+}
+
+/** The platform's id for a message. Measured as a number in a live response, so it is stringified. */
+export function messageId(message) {
+  const id = message?.message_id ?? message?.msg_id ?? null;
+  if (id === null || id === undefined) return null;
+  const text = String(id);
+  return text === '' ? null : text;
+}

package/src/chatops/ilink-transport.mjs

@@ -0,0 +1,168 @@
+/**
+ * The real HTTP transport for the WeChat channel (v0.7.1).
+ *
+ * v0.7.0 required the host to inject a transport and shipped none, so nothing could ever send
+ * a request. That was a design gap rather than a typo: an adapter with no default client is an
+ * adapter that cannot run. This is the default, and it is still injectable, because the
+ * contract tests need to drive it without a network.
+ *
+ * ## What it does that a bare `fetch` does not
+ *
+ * * **A per-request deadline**, because `getupdates` is a deliberate long poll and `notifystart`
+ *   is not; one timeout for both would either cut the poll short or hang the handshake.
+ * * **`undici`'s `cause` unwrapping.** A bare `fetch` failure is `TypeError: fetch failed` with
+ *   the actual reason (`ECONNRESET`, `ENOTFOUND`, `CERT_*`) on `error.cause`. Reporting only the
+ *   TypeError is how a network problem looks like a protocol problem.
+ * * **The `ret` / `errcode` distinction returned as data.** It does not throw on a business
+ *   failure: `{"errcode":-14}` arrives with HTTP 200 and is a *value*, and a transport that
+ *   turned it into an exception would make the channel's own error handling unreachable.
+ */
+
+import { randomBytes } from 'node:crypto';
+import { APP_ID, CLIENT_VERSION, AUTH_TYPE, isOk, failureOf } from './ilink-protocol.mjs';
+
+/** `X-WECHAT-UIN`: base64 of a random uint32 rendered as decimal text. Measured. */
+export function makeUin() {
+  return Buffer.from(String(randomBytes(4).readUInt32BE(0)), 'utf8').toString('base64');
+}
+
+/**
+ * Headers for one request.
+ *
+ * `AuthorizationType` is the one that is easy to leave out and impossible to debug: without it
+ * every authenticated endpoint answers `-14 session timeout`, including calls with no
+ * credential at all, because the server rejects before it reads the token.
+ */
+export function buildHeaders({ token, uin = makeUin() } = {}) {
+  const headers = {
+    'iLink-App-Id': APP_ID,
+    'iLink-App-ClientVersion': CLIENT_VERSION,
+    'content-type': 'application/json',
+    AuthorizationType: AUTH_TYPE,
+    'X-WECHAT-UIN': uin,
+  };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  return headers;
+}
+
+/**
+ * Return a copy with rounded `message_id` numbers replaced by the exact digits the server sent.
+ *
+ * **Returns** rather than mutates. The first version edited in place, so a caller holding the
+ * body it had passed in saw it change underneath — and in the test suite, where a fixture
+ * constant is shared between cases, the first case silently rewrote it for every case after.
+ * A function whose name says "repair" should not be able to surprise its caller that way, and
+ * the symptom (a later test failing on data it never touched) is expensive to trace.
+ *
+ * Walked in document order: `JSON.parse` preserves key order, and the regex that collected the
+ * ids read them in the same order, so the nth `message_id` encountered is the nth id captured.
+ * Matching by value instead would be circular — the whole problem is that the value is wrong.
+ */
+export function repairMessageIds(node, exactIds) {
+  const remaining = [...exactIds];
+  function walk(current) {
+    if (current === null || typeof current !== 'object') return current;
+    if (Array.isArray(current)) return current.map(walk);
+    const copy = {};
+    for (const [key, value] of Object.entries(current)) {
+      if (key === 'message_id' && typeof value === 'number' && remaining.length > 0) {
+        copy[key] = remaining.shift();
+      } else {
+        copy[key] = walk(value);
+      }
+    }
+    return copy;
+  }
+  return walk(node);
+}
+
+/**
+ * Create a transport.
+ *
+ * @param {object} [options]
+ * @param {typeof fetch} [options.fetch] Injected in tests; the platform's own otherwise.
+ * @param {() => string} [options.mintUin]
+ * @param {(event: string, detail?: object) => void} [options.audit]
+ * @returns {(request: {url: string, body: unknown, token?: string|null, timeoutMs?: number, signal?: AbortSignal}) => Promise<{ok: boolean, http: number, body: object, ms: number, errcode?: number|null, errmsg?: string|null}>}
+ */
+export function createTransport(options = {}) {
+  // `??` would treat an explicit `null` as "not provided" and quietly fall back to the global
+  // fetch, so a test asking for no fetch would silently get the network instead. Presence is
+  // checked rather than nullishness.
+  const hasFetch = Object.prototype.hasOwnProperty.call(options, 'fetch');
+  const doFetch = hasFetch ? options.fetch : globalThis.fetch;
+  if (typeof doFetch !== 'function') {
+    // Named rather than left to fail at the first request with "doFetch is not a function".
+    throw new TypeError('createTransport needs a fetch implementation; Node 20.19+ provides one, or inject options.fetch');
+  }
+  const mintUin = options.mintUin ?? makeUin;
+  const audit = options.audit ?? (() => {});
+
+  return async function request({ url, body, token = null, timeoutMs = 20_000, signal: outer } = {}) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    // Both the caller's cancellation and the deadline apply, so a channel being stopped cuts a
+    // long poll short instead of waiting out its 45 seconds.
+    const signal = outer ? AbortSignal.any([outer, controller.signal]) : controller.signal;
+    const started = Date.now();
+
+    let response;
+    try {
+      response = await doFetch(url, {
+        method: 'POST',
+        headers: buildHeaders({ token, uin: mintUin() }),
+        body: JSON.stringify(body ?? {}),
+        signal,
+      });
+    } catch (error) {
+      clearTimeout(timer);
+      if (error?.name === 'AbortError' || error?.name === 'TimeoutError') {
+        return { ok: false, http: 0, body: {}, ms: Date.now() - started, errcode: null, errmsg: `timed out after ${timeoutMs}ms`, timedOut: true };
+      }
+      // `fetch failed` hides the reason on `cause`; without this a network fault reads as a
+      // protocol fault and sends you debugging field names.
+      const cause = error?.cause;
+      const detail = cause ? `${cause.code ?? ''}${cause.code ? ' ' : ''}${cause.message ?? cause}`.trim() : 'no-cause';
+      audit('transport/network-error', { url, detail });
+      return { ok: false, http: 0, body: {}, ms: Date.now() - started, errcode: null, errmsg: `${error?.message ?? error} [${detail}]` };
+    }
+    clearTimeout(timer);
+
+    const text = await response.text();
+    let json = null;
+    try {
+      json = JSON.parse(text);
+    } catch {
+      // Some endpoints answer with an opaque string; the caller sees it in `errmsg`.
+      json = null;
+    }
+    const ms = Date.now() - started;
+
+    if (json === null) {
+      return { ok: false, http: response.status, body: {}, ms, errcode: null, errmsg: `non-JSON response: ${text.slice(0, 200)}` };
+    }
+
+    // 64-bit ids, recovered as text.
+    //
+    // A live `message_id` is 7515840255213248776 — nineteen digits, and past
+    // `Number.MAX_SAFE_INTEGER` (9007199254740991). `JSON.parse` therefore rounds it, and the
+    // value we hold is *not* the value the server sent. Measured: the constant
+    // `7515840255213248776` came back out of a parse as `7515840255213249000`.
+    //
+    // For de-duplication the rounding is mostly harmless — a re-delivery carries the same
+    // rounded number, so it is still caught. It is not harmless if an id is ever sent back to
+    // the platform or persisted as a key, so the exact digits are recovered here rather than
+    // left to a comment.
+    const exactIds = [...text.matchAll(/"message_id"\s*:\s*(\d{16,})/g)].map((m) => m[1]);
+    if (exactIds.length > 0) json = repairMessageIds(json, exactIds);
+
+    const ok = response.ok && isOk(json);
+    if (!ok) {
+      const { errcode, errmsg } = failureOf(json);
+      audit('transport/refused', { url, http: response.status, errcode, errmsg });
+      return { ok: false, http: response.status, body: json, ms, errcode, errmsg: errmsg ?? `HTTP ${response.status}` };
+    }
+    audit('transport/ok', { url, http: response.status, ms });
+    return { ok: true, http: response.status, body: json, ms, errcode: null, errmsg: null };
+  };
+}