A local-first multi-agent app development platform, built on PenguinHarness
/**
* The WeChat half of the WeChat connector: the wire protocol of the official claw bot
* channel, behind an injectable seam so tests substitute a fake and never open a socket
* (the shape qq-api.ts and telegram-api.ts share).
*
* ## What this protocol is, and why it is reimplemented here
*
* Tencent publishes the channel as an OpenClaw plugin
* (https://github.com/Tencent/openclaw-weixin, MIT) and there is an independent SDK derived
* from it (https://github.com/wong2/weixin-agent-sdk, MIT, npm `weixin-agent-sdk`). Both are
* readable, and both describe the SAME protocol: plain JSON over HTTPS, no proprietary
* binary, no obfuscated dist. Neither is taken as a dependency, and the reason is shape
* rather than licence: both own the process's message loop (`login()` then `start(agent)`),
* carry ONE account, render the login QR to a TTY with `qrcode-terminal`, and persist their
* state under `~/.openclaw`. This product needs many bindings side by side, each with its
* own stored config document, and a QR that reaches a browser. So the protocol is
* reimplemented against the same endpoints, the way qq-scan.ts reimplements Tencent's
* bind-task protocol rather than taking its npm package.
*
* ## Inbound is a long poll, which is why this channel is possible at all
*
* `getupdates` is held open by the server until a message arrives or the window closes, and
* the client passes back the opaque `get_updates_buf` cursor it was last given. There is no
* webhook and no public URL anywhere in the flow — the same property that made QQ's gateway
* usable and QQ's webhook mode not.
*
* ## Media rides a CDN, encrypted, and the encryption is not optional
*
* A picture or a file is never inline. Outbound: `getuploadurl` issues a pre-signed URL for
* bytes the caller has already AES-128-ECB encrypted under a key it generates, and the CDN
* answers with the `x-encrypted-param` handle that the message item then references.
* Inbound: the item carries a URL and the key, and the bytes are ciphertext until decrypted.
* ECB with a per-file random key is the platform's choice, not one made here — the framing
* is what it is, and the alternative to implementing it is not carrying media at all.
*
* ## `context_token`
*
* Every inbound message carries one, and it is echoed on every outbound send to the same
* user. It is a routing hint rather than an authorization anchor — the platform accepts a
* send without one, which is what a first send after a restart does — so it is threaded
* through where it is known and omitted where it is not, and never persisted: it is derived
* from traffic, and traffic is what re-derives it.
*/
import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
import { MessagingChannelError, httpStatusRecovers } from "./connector.js";
import { MessagingMediaTooLargeError, collectUnderCap } from "./media.js";
/** The platform's fixed entry host: the QR calls, and the default API base before a scan names one. */
export const WECHAT_API_BASE = "https://ilinkai.weixin.qq.com";
/**
* `iLink-App-Id`. Not a per-integration credential — it names the KIND of client, and every
* bot-channel client sends this same literal (it is the `ilink_appid` field of Tencent's own
* plugin manifest). There is nothing to register and nothing to keep secret.
*/
const ILINK_APP_ID = "bot";
/**
* `iLink-App-ClientVersion`: `major<<16 | minor<<8 | patch` in a uint32, which is the
* encoding the header documents. Pinned rather than derived from the product version — this
* names the PROTOCOL client, and it moves when the protocol handling moves, not when the
* product ships a release.
*/
const ILINK_CLIENT_VERSION = (1 << 16) | (0 << 8) | 0;
/**
* `base_info.bot_agent`: the self-declared identity, the protocol's own analogue of a
* `User-Agent`. Observability only — it authenticates and routes nothing — and the grammar
* is `Name/Version`, so a bare name would be dropped by the server's sanitizer.
*/
const BOT_AGENT = "Adelie/1.0";
/** Overall deadline for the short calls (send, upload handle, credential probe). */
const CALL_TIMEOUT_MS = 15_000;
/**
* How long ONE `getupdates` may be held. The protocol's own suggestion is 35s; this is
* shorter on purpose, because the poll loop cannot see a closed connection while it is
* parked in a request — a shorter window bounds how long a disable waits for its poll to
* come back. The abort signal is what actually ends it promptly; this is the backstop for
* a connection that is hung rather than closed.
*/
export const LONG_POLL_TIMEOUT_MS = 30_000;
/**
* Deadline for a media transfer in either direction. Far longer than a method call: these
* move megabytes over whatever link the server has, and a 15s ceiling would fail a picture
* that was on its way perfectly well (the same number telegram-api.ts uses).
*/
const TRANSFER_TIMEOUT_MS = 60_000;
/**
* How long the connection's FIRST poll may take. It is a drain, not a wait: it asks for
* whatever the platform is already holding, and anything that has not arrived by here is a
* live message the loop is about to read properly rather than backlog to discard. Parking it
* for the full long-poll window would drop the first message a user sends after enabling.
*/
export const DRAIN_TIMEOUT_MS = 5_000;
/** The bot-channel `bot_type` the QR calls are made under. */
export const WECHAT_BOT_TYPE = "3";
// ---------------------------------------------------------------------------
// The wire's own vocabulary
// ---------------------------------------------------------------------------
/** `MessageItem.type` — the item kinds this channel carries. */
const ITEM_TEXT = 1;
const ITEM_IMAGE = 2;
const ITEM_VOICE = 3;
const ITEM_FILE = 4;
const ITEM_VIDEO = 5;
/** `WeixinMessage.message_type`: a message this bot is SENDING. */
const MESSAGE_TYPE_BOT = 2;
/** `WeixinMessage.message_state`: the message is complete (nothing is streamed from here). */
const MESSAGE_STATE_FINISH = 2;
/** `GetUploadUrlReq.media_type`. VOICE (4) exists on the wire and is never sent from here. */
const UPLOAD_MEDIA_IMAGE = 1;
const UPLOAD_MEDIA_FILE = 3;
/** AES-128 key length — what both the CDN framing and `getuploadurl`'s `aeskey` expect. */
const AES_KEY_BYTES = 16;
/** One file name for a video, which the wire never names (see the connector's inbound doc). */
export const WECHAT_VIDEO_FILE_NAME = "video.mp4";
// ---------------------------------------------------------------------------
// The seam
// ---------------------------------------------------------------------------
export interface WeChatCredentials {
/** `ilink_bot_id` — the channel-scoped account identity. Never secret. */
botId: string;
/** The bot token a completed scan issued. This is the credential. */
botToken: string;
/**
* The API host this bot was assigned. A scan may hand back an IDC-specific one, and a bot
* polled against the wrong host reads as an authentication failure, so it is stored per
* binding rather than assumed.
*/
baseUrl: string;
/**
* `ilink_user_id` of the person whose scan created the binding. It is what the credential
* probe names — `getconfig` is per-user — and it is not otherwise used: an inbound message
* carries its own sender.
*/
userId: string;
}
/**
* One media object on the wire: where the bytes are, and the key that opens them.
*
* A handle, deliberately — nothing here has fetched anything. The connector turns it into
* the seam's lazy `fetch`, so a redelivered message costs no transfer at all.
*/
export interface WeChatMediaRef {
/**
* The ready-made download URL the server returns. Required: the alternative is rebuilding
* it from a CDN host this protocol does not document, and a guessed host that resolves
* would be worse than one that does not.
*/
url: string;
/**
* The AES-128 key, in the wire's own base64. Absent for the one case the platform sends in
* the clear (an image with no key at all), which then needs no decryption.
*/
aesKey?: string;
}
/** A non-image attachment on an inbound message. */
export interface WeChatInboundFile {
/** The sender's own name for it, or a plain fallback where the wire carries none. */
fileName: string;
media: WeChatMediaRef;
}
/**
* One inbound message, reduced to what the connector consumes. Voice, video and quoted
* messages have already been folded into these three fields — see `normalizeMessage`.
*/
export interface WeChatInboundEvent {
/** `from_user_id`: the sender, the chat, and the send target, which are one id on this channel. */
userId: string;
/** `message_id`, as text. The dedupe key and the reply anchor. */
messageId: string;
/** The message's text, or `""` when it carries none. */
text: string;
/** Echoed on sends to this user while it is known (see the module doc). */
contextToken?: string;
images: WeChatMediaRef[];
files: WeChatInboundFile[];
}
/** One outbound attachment: the bytes, and the name the chat should show. */
export interface WeChatOutboundFile {
fileName: string;
data: Buffer;
}
export interface WeChatSendArgs {
/** `to_user_id` — the chat, which on this channel is the person. */
userId: string;
text: string;
contextToken?: string;
}
/** What one `getupdates` returned: the messages, and the cursor for the next call. */
export interface WeChatUpdates {
messages: WeChatInboundEvent[];
/** Opaque `get_updates_buf`; pass it back verbatim. */
cursor: string;
/**
* The window closed with nothing rather than the platform answering.
*
* Both come back as an empty list with the cursor unchanged, and for an ordinary poll they
* are the same thing. The drain is where they differ: it must not be spent on a window that
* closed without the platform saying where it stands, or the cursor stays at the beginning
* and the next poll relays a whole backlog as live traffic.
*/
timedOut: boolean;
}
export interface WeChatBotClient {
/**
* Credential probe: resolves when the token AUTHENTICATES, and throws when it does not.
*
* What it deliberately does not prove is that the bot can deliver anything. No call on this
* platform can prove both: every authenticated endpoint shares one auth layer and then does
* something with a side condition a freshly-scanned binding cannot satisfy — `getconfig`
* wants a live conversation to mint a typing ticket for, `getuploadurl` wants a peer and a
* file, `sendtyping` wants a ticket, and `getupdates` is a long poll that would park for its
* whole window. So the probe reads the layer that has no side conditions and reports only
* that, which is the honest answer rather than a green light for something it did not test.
*/
checkCredentials(): Promise<void>;
/**
* One poll. `signal` ends it at once, which is what a disable needs.
*
* A window that closes with nothing to report resolves EMPTY rather than throwing: on a long
* poll that is the ordinary quiet case, and treating it as a failure would flap the
* connection into `error` every time a conversation went quiet.
*
* `drain: true` asks for a short deadline instead of the long-poll window — see
* DRAIN_TIMEOUT_MS.
*/
getUpdates(args: {
cursor: string;
signal: AbortSignal;
drain?: boolean;
}): Promise<WeChatUpdates>;
sendText(args: WeChatSendArgs): Promise<void>;
/** Uploads the bytes to the CDN, then sends the item that references them. */
sendImage(args: WeChatSendArgs & { file: WeChatOutboundFile }): Promise<void>;
sendFile(args: WeChatSendArgs & { file: WeChatOutboundFile }): Promise<void>;
/**
* Downloads and decrypts one media handle, refusing at the byte that crosses `maxBytes`.
* `what` names the transfer in a refusal and must never carry a URL: a CDN URL embeds the
* signed parameter that authorizes the read.
*/
fetchMedia(ref: WeChatMediaRef, maxBytes: number, what: string): Promise<Buffer>;
}
/** Factory the connector is built over: the production adapter, or a test fake. */
export interface WeChatTransport {
createClient(creds: WeChatCredentials): WeChatBotClient;
}
/**
* The code the platform answers with when the bot token is stale or revoked. It arrives with
* an HTTP 200 and a non-zero envelope, so it is the one business-level code that has to be
* read as an authentication failure rather than as one of the call behind it.
*
* What it asks of a client is to wait, though: its errmsg is "session timeout", and Tencent's
* own plugin (see the module doc) answers it by pausing the account for an hour and then
* resuming, never by asking for a new scan. So it fails the credential probe while it lasts,
* and still counts as a failure that recovers (see WeChatApiError).
*/
export const WECHAT_STALE_TOKEN_CODE = -14;
/**
* A call the platform answered with a failure of its own, as opposed to one that never
* arrived. `ret` is the protocol's numeric code where it returned one.
*
* `recovers` is set where the failure is read (see `post` and checkEnvelope). A request that
* never completed, an HTTP 408/429/5xx, and every refusal the envelope carries — the session
* pause of WECHAT_STALE_TOKEN_CODE, and whatever the platform declines behind a credential it
* accepted, such as a send's "prepare failed" — go through on a later attempt with nothing
* changed: this channel has no permission and no console setting a person could fix them
* with. An HTTP refusal of the credential (401/403), a wrong host (404) and a body this client
* cannot read do not.
*/
export class WeChatApiError extends MessagingChannelError {
/**
* The request was ACCEPTED — it authenticated, and the failure came from the call behind
* the credential rather than from the credential.
*
* This distinction is the whole of the credential probe: every authenticated endpoint on
* this platform shares one auth layer and then does something that needs state a
* freshly-bound bot does not have, so the only thing a probe can honestly read is which of
* the two layers refused it (see checkCredentials).
*/
readonly authenticated: boolean;
/**
* The request was given up on at a deadline rather than answered or refused. On a long poll
* that is the ordinary quiet case and not a failure at all, which is what `getUpdates` reads
* it for; nothing else here distinguishes it from a network fault.
*/
readonly timedOut: boolean;
constructor(
readonly ret: number | undefined,
message: string,
flags: { authenticated?: boolean; timedOut?: boolean; recovers?: boolean } = {},
) {
super(message, flags.recovers ?? false);
this.name = "WeChatApiError";
this.authenticated = flags.authenticated ?? false;
this.timedOut = flags.timedOut ?? false;
}
}
// ---------------------------------------------------------------------------
// Production adapter over fetch
// ---------------------------------------------------------------------------
/** Whether a fetch rejection is a deadline or a cancellation rather than a transport fault. */
function isAbortLike(err: unknown): boolean {
return err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError");
}
/** Readable failure text out of fetch's throw shapes. Never echoes a URL (see fetchMedia). */
export function wechatFetchErrorText(err: unknown): string {
if (err instanceof Error) {
if (err.name === "TimeoutError" || err.name === "AbortError") return "request timed out";
const cause = (err as { cause?: unknown }).cause;
if (cause instanceof Error && cause.message !== "") return cause.message;
return err.message;
}
return String(err);
}
/**
* `X-WECHAT-UIN`: a random uint32, rendered as its decimal digits and then base64'd. It
* identifies nothing — the protocol wants the header present and the value fresh per
* request, which is exactly what a random one is.
*/
function randomUin(): string {
return Buffer.from(String(randomBytes(4).readUInt32BE(0)), "utf8").toString("base64");
}
function headersFor(token: string): Record<string, string> {
return {
"content-type": "application/json",
AuthorizationType: "ilink_bot_token",
Authorization: `Bearer ${token}`,
"X-WECHAT-UIN": randomUin(),
"iLink-App-Id": ILINK_APP_ID,
"iLink-App-ClientVersion": String(ILINK_CLIENT_VERSION),
};
}
/** The `base_info` every request carries. */
function baseInfo(): Record<string, unknown> {
return { channel_version: "1.0.0", bot_agent: BOT_AGENT };
}
/** Joins an endpoint onto a base whose trailing slash the caller may or may not have kept. */
function endpointUrl(baseUrl: string, path: string): string {
return `${baseUrl.replace(/\/+$/, "")}/${path}`;
}
/** The response envelope the JSON calls share; `ret` is 0 or absent on success. */
interface WeChatEnvelope {
ret?: number;
errcode?: number;
errmsg?: string;
}
/** Raises the platform's own failure, or returns the parsed body. */
function checkEnvelope(label: string, status: number, raw: string): Record<string, unknown> {
let body: Record<string, unknown>;
try {
body = JSON.parse(raw) as Record<string, unknown>;
} catch {
throw new WeChatApiError(undefined, `${label} failed: HTTP ${status} (unparseable response)`);
}
const env = body as WeChatEnvelope;
// `ret` and `errcode` are two spellings of the same thing across these endpoints; either
// being non-zero is a failure, and neither being present is a success.
const code = env.ret !== undefined && env.ret !== 0 ? env.ret : env.errcode;
if (code !== undefined && code !== 0) {
// The request reached the platform and got past its credential check — a stale token
// being the one code that says otherwise.
throw new WeChatApiError(code, `${label} failed: ${env.errmsg ?? `code ${code}`}`, {
authenticated: code !== WECHAT_STALE_TOKEN_CODE,
recovers: true,
});
}
return body;
}
// ---------------------------------------------------------------------------
// AES-128-ECB, which is the CDN's framing
// ---------------------------------------------------------------------------
/** PKCS#7 is node's default for this cipher, so the padded length is always a full block longer. */
function paddedSize(plaintextSize: number): number {
return Math.ceil((plaintextSize + 1) / 16) * 16;
}
function encryptEcb(plaintext: Buffer, key: Buffer): Buffer {
const cipher = createCipheriv("aes-128-ecb", key, null);
return Buffer.concat([cipher.update(plaintext), cipher.final()]);
}
function decryptEcb(ciphertext: Buffer, key: Buffer): Buffer {
const decipher = createDecipheriv("aes-128-ecb", key, null);
return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
}
/**
* Reads the wire's `aes_key` back to 16 raw bytes.
*
* Two encodings appear, and which one arrives depends on the item kind rather than on
* anything a reader can see: an image's key is base64 of the raw bytes, while a file's and a
* video's is base64 of the key's 32 HEX CHARACTERS. Both are accepted by length, because a
* 32-byte decode that is entirely hex digits cannot be a 16-byte key under any reading.
*/
export function parseWeChatAesKey(aesKey: string): Buffer {
const decoded = Buffer.from(aesKey, "base64");
if (decoded.length === AES_KEY_BYTES) return decoded;
const ascii = decoded.toString("ascii");
if (decoded.length === 32 && /^[0-9a-fA-F]{32}$/.test(ascii)) return Buffer.from(ascii, "hex");
throw new Error("wechat media key is neither 16 raw bytes nor 32 hex characters");
}
// ---------------------------------------------------------------------------
// Inbound normalization
// ---------------------------------------------------------------------------
/** One `MessageItem`, in the wire's own field names (only the parts read here). */
interface WireItem {
type?: number;
text_item?: { text?: string };
image_item?: { media?: WireMedia; aeskey?: string };
voice_item?: { media?: WireMedia; text?: string };
file_item?: { media?: WireMedia; file_name?: string };
video_item?: { media?: WireMedia };
ref_msg?: { title?: string; message_item?: WireItem };
}
interface WireMedia {
full_url?: string;
aes_key?: string;
}
interface WireMessage {
message_id?: number | string;
from_user_id?: string;
message_type?: number;
context_token?: string;
item_list?: WireItem[];
}
/** A media handle, or null when the item carries no usable URL. */
function mediaRefOf(media: WireMedia | undefined, aesKeyOverride?: string): WeChatMediaRef | null {
const url = media?.full_url;
if (typeof url !== "string" || url === "") return null;
// `image_item.aeskey` is hex and takes precedence over `media.aes_key` where both are sent;
// it is the one the platform's own client prefers for images.
const aesKey =
typeof aesKeyOverride === "string" && aesKeyOverride !== ""
? Buffer.from(aesKeyOverride, "hex").toString("base64")
: media?.aes_key;
return { url, ...(typeof aesKey === "string" && aesKey !== "" ? { aesKey } : {}) };
}
/**
* The text a message contributes.
*
* A VOICE item's `text` is the platform's OWN transcription of the recording, so a voice
* message that has one is a text message and is carried as one. There is no audio on the
* connector seam — an inbound recording has nowhere to go — and dropping a transcription
* that already exists would answer a spoken question with the not-supported notice.
*
* A quoted message contributes its summary in front of the reply, because the reply usually
* does not repeat what it is answering and the model would otherwise read a bare "yes".
*/
function textOf(items: readonly WireItem[]): string {
const parts: string[] = [];
for (const item of items) {
if (item.type === ITEM_TEXT && typeof item.text_item?.text === "string") {
const quoted = item.ref_msg;
const quotedText =
quoted === undefined
? ""
: [quoted.title, quoted.message_item ? textOf([quoted.message_item]) : ""]
.filter((part): part is string => typeof part === "string" && part !== "")
.join(" | ");
parts.push(
quotedText === "" ? item.text_item.text : `[quote: ${quotedText}]\n${item.text_item.text}`,
);
continue;
}
if (item.type === ITEM_VOICE && typeof item.voice_item?.text === "string") {
parts.push(item.voice_item.text);
}
}
return parts.join("\n").trim();
}
/**
* One wire message as the connector's event, or null for anything it must not act on.
*
* The bot's OWN messages come back on this stream — `message_type` 2 is what this client
* sent — and relaying them would answer every reply with another reply.
*/
export function normalizeWeChatMessage(msg: WireMessage): WeChatInboundEvent | null {
const userId = msg.from_user_id;
if (typeof userId !== "string" || userId === "") return null;
if (msg.message_type === MESSAGE_TYPE_BOT) return null;
const items = Array.isArray(msg.item_list) ? msg.item_list : [];
const images: WeChatMediaRef[] = [];
const files: WeChatInboundFile[] = [];
for (const item of items) {
if (item.type === ITEM_IMAGE) {
const ref = mediaRefOf(item.image_item?.media, item.image_item?.aeskey);
if (ref !== null) images.push(ref);
} else if (item.type === ITEM_FILE) {
const ref = mediaRefOf(item.file_item?.media);
const name = item.file_item?.file_name;
// No name is a plain fallback rather than an invented extension: the name is the whole
// of what tells the model what the bytes are (see connector.ts MessagingInboundFile).
if (ref !== null)
files.push({ fileName: name !== undefined && name !== "" ? name : "file", media: ref });
} else if (item.type === ITEM_VIDEO) {
const ref = mediaRefOf(item.video_item?.media);
// `.mp4` is not a guess: the platform transcodes every video item to it, and its own
// client asserts the type unconditionally. The wire carries no name to prefer over it.
if (ref !== null) files.push({ fileName: WECHAT_VIDEO_FILE_NAME, media: ref });
}
}
const messageId = msg.message_id;
return {
userId,
messageId: messageId === undefined ? "" : String(messageId),
text: textOf(items),
...(typeof msg.context_token === "string" && msg.context_token !== ""
? { contextToken: msg.context_token }
: {}),
images,
files,
};
}
// ---------------------------------------------------------------------------
// The adapter
// ---------------------------------------------------------------------------
export function createWeChatTransport(): WeChatTransport {
return {
createClient(creds: WeChatCredentials): WeChatBotClient {
const post = async (
path: string,
payload: Record<string, unknown>,
opts: { timeoutMs: number; signal?: AbortSignal; label: string },
): Promise<Record<string, unknown>> => {
const url = endpointUrl(creds.baseUrl, path);
let res: Response;
try {
res = await fetch(url, {
method: "POST",
headers: headersFor(creds.botToken),
body: JSON.stringify({ ...payload, base_info: baseInfo() }),
signal: opts.signal ?? AbortSignal.timeout(opts.timeoutMs),
});
} catch (err) {
throw new WeChatApiError(
undefined,
`${opts.label} failed: ${wechatFetchErrorText(err)}`,
{
timedOut: isAbortLike(err),
recovers: true,
},
);
}
const raw = await res.text().catch(() => "");
if (!res.ok) {
// The body is the platform's own diagnosis and is the only thing that distinguishes
// a revoked token from a wrong host; it carries no credential of ours. Every status
// here leaves `authenticated` false: a 401/403 IS the credential being refused, and
// for anything else the request never got far enough to say the credential is good.
throw new WeChatApiError(
undefined,
`${opts.label} failed: HTTP ${res.status}${raw === "" ? "" : ` ${raw.slice(0, 300)}`}`,
{ recovers: httpStatusRecovers(res.status) },
);
}
return checkEnvelope(opts.label, res.status, raw);
};
/**
* One message item on its way out. Every send is its own request with exactly one item:
* the platform pairs a caption with its media as two consecutive messages rather than
* one message with two items, and a two-item list is not a shape it accepts.
*/
const sendItem = async (
args: WeChatSendArgs,
item: Record<string, unknown>,
label: string,
): Promise<void> => {
await post(
"ilink/bot/sendmessage",
{
msg: {
from_user_id: "",
to_user_id: args.userId,
client_id: randomBytes(16).toString("hex"),
message_type: MESSAGE_TYPE_BOT,
message_state: MESSAGE_STATE_FINISH,
item_list: [item],
...(args.contextToken !== undefined ? { context_token: args.contextToken } : {}),
},
},
{ timeoutMs: CALL_TIMEOUT_MS, label },
);
};
/**
* The upload half of an outbound attachment: a fresh key, a pre-signed URL for the
* ciphertext, and the CDN's handle for the message item to reference.
*
* `no_need_thumb` is set because nothing here has a thumbnail to make. The platform
* requires thumbnail sizes for IMAGE and VIDEO only when one is being uploaded, and a
* generated thumbnail would mean decoding every picture the Agent draws.
*/
const upload = async (
userId: string,
file: WeChatOutboundFile,
mediaType: number,
label: string,
): Promise<{ param: string; aesKey: Buffer; rawSize: number; cipherSize: number }> => {
const aesKey = randomBytes(AES_KEY_BYTES);
const rawSize = file.data.length;
const cipherSize = paddedSize(rawSize);
const filekey = randomBytes(AES_KEY_BYTES).toString("hex");
const handle = await post(
"ilink/bot/getuploadurl",
{
filekey,
media_type: mediaType,
to_user_id: userId,
rawsize: rawSize,
rawfilemd5: createHash("md5").update(file.data).digest("hex"),
filesize: cipherSize,
no_need_thumb: true,
aeskey: aesKey.toString("hex"),
},
{ timeoutMs: CALL_TIMEOUT_MS, label: `${label} upload handle` },
);
const uploadUrl = handle.upload_full_url;
if (typeof uploadUrl !== "string" || uploadUrl.trim() === "") {
// The alternative is assembling a URL from a CDN host this protocol never
// documents. A guessed host that happened to resolve would be worse than none.
throw new WeChatApiError(undefined, `${label} failed: the upload URL was not returned`);
}
let res: Response;
try {
res = await fetch(uploadUrl.trim(), {
method: "POST",
headers: { "content-type": "application/octet-stream" },
body: new Uint8Array(encryptEcb(file.data, aesKey)),
signal: AbortSignal.timeout(TRANSFER_TIMEOUT_MS),
});
} catch (err) {
throw new WeChatApiError(undefined, `${label} failed: ${wechatFetchErrorText(err)}`);
}
if (!res.ok) {
const detail = res.headers.get("x-error-message") ?? `HTTP ${res.status}`;
throw new WeChatApiError(undefined, `${label} failed: ${detail}`);
}
const param = res.headers.get("x-encrypted-param");
if (param === null || param === "") {
throw new WeChatApiError(
undefined,
`${label} failed: the CDN returned no download handle`,
);
}
return { param, aesKey, rawSize, cipherSize };
};
return {
async checkCredentials(): Promise<void> {
try {
// The cheapest authenticated call that reads rather than writes, and the only one
// that consumes nothing: `getupdates` would park for its window, and a probe that
// advanced the cursor the poll loop is about to read would eat a user's message.
await post(
"ilink/bot/getconfig",
{ ilink_user_id: creds.userId },
{ timeoutMs: CALL_TIMEOUT_MS, label: "wechat credential check" },
);
} catch (err) {
// The call behind the credential failed, which says nothing about the credential:
// `getconfig` mints a typing ticket for a CONVERSATION, and a bot nobody has
// messaged yet has none — so a binding whose sends work perfectly answers
// "GetTypingTicket rpc failed" here. Reporting that as a bad credential sends the
// user to re-scan a token that was never the problem.
if (err instanceof WeChatApiError && err.authenticated) return;
throw err;
}
},
async getUpdates({ cursor, signal, drain = false }): Promise<WeChatUpdates> {
// Two deadlines, combined: the caller's (a disable, which must end the poll now)
// and this call's own window. Whichever fires first ends the request.
const windowMs = drain ? DRAIN_TIMEOUT_MS : LONG_POLL_TIMEOUT_MS;
let body: Record<string, unknown>;
try {
body = await post(
"ilink/bot/getupdates",
{ get_updates_buf: cursor },
{
timeoutMs: windowMs,
signal: AbortSignal.any([signal, AbortSignal.timeout(windowMs)]),
label: "wechat getUpdates",
},
);
} catch (err) {
// A close is a close and must reach the loop; this window closing is not a
// failure at all. A long poll that has nothing to say holds the request until it
// expires, so treating that as an outage would put the connection into `error`
// every quiet minute — and the cursor is unchanged, so the next call simply asks
// again from where this one started.
if (signal.aborted) throw err;
if (err instanceof WeChatApiError && err.timedOut) {
return { messages: [], cursor, timedOut: true };
}
throw err;
}
const raw = Array.isArray(body.msgs) ? (body.msgs as WireMessage[]) : [];
const messages: WeChatInboundEvent[] = [];
for (const msg of raw) {
const evt = normalizeWeChatMessage(msg);
if (evt !== null) messages.push(evt);
}
// A response that carried no cursor leaves the old one in place: sending `""` back
// means "start over", which would replay everything this poll just consumed.
const next = body.get_updates_buf;
return {
messages,
cursor: typeof next === "string" && next !== "" ? next : cursor,
timedOut: false,
};
},
sendText(args: WeChatSendArgs): Promise<void> {
return sendItem(args, { type: ITEM_TEXT, text_item: { text: args.text } }, "wechat send");
},
async sendImage(args): Promise<void> {
const { param, aesKey, cipherSize } = await upload(
args.userId,
args.file,
UPLOAD_MEDIA_IMAGE,
"wechat image send",
);
if (args.text !== "") await this.sendText(args);
await sendItem(
args,
{
type: ITEM_IMAGE,
image_item: {
media: {
encrypt_query_param: param,
aes_key: aesKey.toString("base64"),
encrypt_type: 1,
},
mid_size: cipherSize,
},
},
"wechat image send",
);
},
async sendFile(args): Promise<void> {
const { param, aesKey, rawSize } = await upload(
args.userId,
args.file,
UPLOAD_MEDIA_FILE,
"wechat file send",
);
if (args.text !== "") await this.sendText(args);
await sendItem(
args,
{
type: ITEM_FILE,
file_item: {
media: {
encrypt_query_param: param,
aes_key: aesKey.toString("base64"),
encrypt_type: 1,
},
file_name: args.file.fileName,
// Plaintext length: the receiving client shows it, and the ciphertext is
// one padding block longer than what the user actually gets.
len: String(rawSize),
},
},
"wechat file send",
);
},
async fetchMedia(ref: WeChatMediaRef, maxBytes: number, what: string): Promise<Buffer> {
let res: Response;
try {
res = await fetch(ref.url, { signal: AbortSignal.timeout(TRANSFER_TIMEOUT_MS) });
} catch (err) {
// The URL never reaches this message: it carries the signed parameter that
// authorizes the read.
throw new Error(`${what} could not be downloaded: ${wechatFetchErrorText(err)}`);
}
if (!res.ok) throw new Error(`${what} could not be downloaded: HTTP ${res.status}`);
if (res.body === null) throw new Error(`${what} could not be downloaded: empty response`);
// The cap is applied to the CIPHERTEXT, which is within one 16-byte block of the
// plaintext — so it still refuses at the byte that crosses, rather than buffering
// a whole oversized transfer and measuring it afterwards.
const bytes = await collectUnderCap(
res.body as AsyncIterable<Uint8Array>,
maxBytes,
what,
);
if (ref.aesKey === undefined) return bytes;
try {
return decryptEcb(bytes, parseWeChatAesKey(ref.aesKey));
} catch (err) {
if (err instanceof MessagingMediaTooLargeError) throw err;
// The cause is a crypto failure over a key the chat has no control of; what the
// user can act on is that the transfer arrived and could not be opened.
throw new Error(`${what} arrived but could not be decrypted`);
}
},
};
},
};
}