@botcord/daemon 0.2.36 → 0.2.37

package/dist/gateway/channels/url-guard.d.ts

@@ -0,0 +1,18 @@
+/**
+ * W9: SSRF guard for user-supplied `baseUrl` values that flow into
+ * authenticated daemon-side fetches (Telegram getMe, WeChat iLink).
+ *
+ * Policy: scheme MUST be `https`; the hostname MUST match one of the
+ * explicitly-allowed well-known API hosts (case-insensitive exact match).
+ * Switching from blocklist to allowlist closes the GCP/AWS metadata hostname
+ * pivot vector — blocklists miss names like `metadata.google.internal`,
+ * `*.svc.cluster.local`, etc.
+ *
+ * The test host `botcord-test.local` is added only when
+ * NODE_ENV === "test" to keep unit tests working without relaxing production
+ * policy.
+ */
+export declare class UnsafeBaseUrlError extends Error {
+    constructor(reason: string);
+}
+export declare function assertSafeBaseUrl(value: string | undefined | null): void;

package/dist/gateway/channels/url-guard.js

@@ -0,0 +1,53 @@
+/**
+ * W9: SSRF guard for user-supplied `baseUrl` values that flow into
+ * authenticated daemon-side fetches (Telegram getMe, WeChat iLink).
+ *
+ * Policy: scheme MUST be `https`; the hostname MUST match one of the
+ * explicitly-allowed well-known API hosts (case-insensitive exact match).
+ * Switching from blocklist to allowlist closes the GCP/AWS metadata hostname
+ * pivot vector — blocklists miss names like `metadata.google.internal`,
+ * `*.svc.cluster.local`, etc.
+ *
+ * The test host `botcord-test.local` is added only when
+ * NODE_ENV === "test" to keep unit tests working without relaxing production
+ * policy.
+ */
+export class UnsafeBaseUrlError extends Error {
+    constructor(reason) {
+        super(`unsafe_base_url: ${reason}`);
+        this.name = "UnsafeBaseUrlError";
+    }
+}
+function allowedHosts() {
+    const hosts = new Set(["api.telegram.org", "ilinkai.weixin.qq.com"]);
+    if (process.env.NODE_ENV === "test") {
+        hosts.add("botcord-test.local");
+    }
+    return hosts;
+}
+export function assertSafeBaseUrl(value) {
+    if (value === undefined || value === null || value === "") {
+        // Caller handles the "no baseUrl supplied → use default" path.
+        return;
+    }
+    if (typeof value !== "string") {
+        throw new UnsafeBaseUrlError("not a string");
+    }
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new UnsafeBaseUrlError("not a valid URL");
+    }
+    if (parsed.protocol !== "https:") {
+        throw new UnsafeBaseUrlError(`scheme "${parsed.protocol}" is not https`);
+    }
+    const host = parsed.hostname.toLowerCase();
+    if (!host) {
+        throw new UnsafeBaseUrlError("empty host");
+    }
+    if (!allowedHosts().has(host)) {
+        throw new UnsafeBaseUrlError(`host "${host}" is not in the allowlist`);
+    }
+}

package/dist/gateway/channels/wechat-http.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared HTTP plumbing for the iLink WeChat adapter and its login helper.
+ *
+ * Centralises the four mandatory headers (`AuthorizationType`,
+ * `Authorization`, `X-WECHAT-UIN`, `Content-Type`) so the adapter and the
+ * login flow can't drift on header shape — the iLink server rejects requests
+ * that omit any of them.
+ */
+export type { FetchLike } from "./http-types.js";
+/** `X-WECHAT-UIN: base64(str(random uint32))` — fresh per request, anti-replay. */
+export declare function wechatUinHeader(): string;
+/** Build the canonical iLink request headers. Token is optional for login calls. */
+export declare function wechatHeaders(botToken?: string): Record<string, string>;
+/** iLink `base_info` block required on every authenticated POST body. */
+export declare const WECHAT_CHANNEL_VERSION = "1.0.2";
+export declare const WECHAT_BASE_INFO: {
+    readonly channel_version: "1.0.2";
+};

package/dist/gateway/channels/wechat-http.js

@@ -0,0 +1,28 @@
+/**
+ * Shared HTTP plumbing for the iLink WeChat adapter and its login helper.
+ *
+ * Centralises the four mandatory headers (`AuthorizationType`,
+ * `Authorization`, `X-WECHAT-UIN`, `Content-Type`) so the adapter and the
+ * login flow can't drift on header shape — the iLink server rejects requests
+ * that omit any of them.
+ */
+import { randomBytes } from "node:crypto";
+/** `X-WECHAT-UIN: base64(str(random uint32))` — fresh per request, anti-replay. */
+export function wechatUinHeader() {
+    const n = randomBytes(4).readUInt32BE(0);
+    return Buffer.from(String(n), "utf8").toString("base64");
+}
+/** Build the canonical iLink request headers. Token is optional for login calls. */
+export function wechatHeaders(botToken) {
+    const h = {
+        "Content-Type": "application/json",
+        AuthorizationType: "ilink_bot_token",
+        "X-WECHAT-UIN": wechatUinHeader(),
+    };
+    if (botToken)
+        h["Authorization"] = `Bearer ${botToken}`;
+    return h;
+}
+/** iLink `base_info` block required on every authenticated POST body. */
+export const WECHAT_CHANNEL_VERSION = "1.0.2";
+export const WECHAT_BASE_INFO = { channel_version: WECHAT_CHANNEL_VERSION };

package/dist/gateway/channels/wechat-login.d.ts

@@ -0,0 +1,36 @@
+/**
+ * iLink WeChat QR-code login helpers.
+ *
+ * Co-located with the channel adapter so the small set of unauthenticated
+ * iLink endpoints (`get_bot_qrcode`, `get_qrcode_status`) used during the
+ * scan-confirm flow stay alongside the authenticated calls in `wechat.ts`.
+ *
+ * This module deliberately exports ONLY the two HTTP calls. Login session
+ * persistence (mapping `loginId` → `{accountId, gatewayId, botToken, ...}`)
+ * is owned by the control-plane layer and is out of scope here.
+ */
+import { type FetchLike } from "./wechat-http.js";
+export declare const DEFAULT_WECHAT_BASE_URL = "https://ilinkai.weixin.qq.com";
+export interface WechatQrcode {
+    qrcode: string;
+    qrcodeUrl?: string;
+    raw: Record<string, unknown>;
+}
+export interface WechatQrcodeStatus {
+    status: string;
+    botToken?: string;
+    baseUrl?: string;
+    raw: Record<string, unknown>;
+}
+export interface WechatLoginOptions {
+    baseUrl?: string;
+    fetchImpl?: FetchLike;
+}
+/** `GET /ilink/bot/get_bot_qrcode?bot_type=3` — fetch a fresh login QR. */
+export declare function getBotQrcode(opts?: WechatLoginOptions): Promise<WechatQrcode>;
+/**
+ * `GET /ilink/bot/get_qrcode_status?qrcode=...` — poll for scan/confirm.
+ * Caller is responsible for backoff and TTL; this just returns the parsed
+ * server response.
+ */
+export declare function getQrcodeStatus(qrcode: string, opts?: WechatLoginOptions): Promise<WechatQrcodeStatus>;

package/dist/gateway/channels/wechat-login.js

@@ -0,0 +1,62 @@
+/**
+ * iLink WeChat QR-code login helpers.
+ *
+ * Co-located with the channel adapter so the small set of unauthenticated
+ * iLink endpoints (`get_bot_qrcode`, `get_qrcode_status`) used during the
+ * scan-confirm flow stay alongside the authenticated calls in `wechat.ts`.
+ *
+ * This module deliberately exports ONLY the two HTTP calls. Login session
+ * persistence (mapping `loginId` → `{accountId, gatewayId, botToken, ...}`)
+ * is owned by the control-plane layer and is out of scope here.
+ */
+import { wechatHeaders } from "./wechat-http.js";
+import { assertSafeBaseUrl } from "./url-guard.js";
+export const DEFAULT_WECHAT_BASE_URL = "https://ilinkai.weixin.qq.com";
+/** `GET /ilink/bot/get_bot_qrcode?bot_type=3` — fetch a fresh login QR. */
+export async function getBotQrcode(opts = {}) {
+    // W1: defense-in-depth SSRF guard at the fetch boundary.
+    assertSafeBaseUrl(opts.baseUrl);
+    const base = (opts.baseUrl ?? DEFAULT_WECHAT_BASE_URL).replace(/\/+$/, "");
+    const fetcher = opts.fetchImpl ?? globalThis.fetch;
+    const res = await fetcher(`${base}/ilink/bot/get_bot_qrcode?bot_type=3`, {
+        method: "GET",
+        headers: wechatHeaders(),
+    });
+    const data = (await safeJson(res)) ?? {};
+    const qrcode = typeof data.qrcode === "string" ? data.qrcode : "";
+    if (!qrcode) {
+        throw new Error(`wechat get_bot_qrcode: missing qrcode in response`);
+    }
+    const qrcodeUrl = (typeof data.qrcode_url === "string" && data.qrcode_url) ||
+        (typeof data.qrcode_img_content === "string" && data.qrcode_img_content) ||
+        undefined;
+    return { qrcode, qrcodeUrl, raw: data };
+}
+/**
+ * `GET /ilink/bot/get_qrcode_status?qrcode=...` — poll for scan/confirm.
+ * Caller is responsible for backoff and TTL; this just returns the parsed
+ * server response.
+ */
+export async function getQrcodeStatus(qrcode, opts = {}) {
+    // W1: defense-in-depth SSRF guard at the fetch boundary.
+    assertSafeBaseUrl(opts.baseUrl);
+    const base = (opts.baseUrl ?? DEFAULT_WECHAT_BASE_URL).replace(/\/+$/, "");
+    const fetcher = opts.fetchImpl ?? globalThis.fetch;
+    const res = await fetcher(`${base}/ilink/bot/get_qrcode_status?qrcode=${encodeURIComponent(qrcode)}`, { method: "GET", headers: wechatHeaders() });
+    const data = (await safeJson(res)) ?? {};
+    const status = typeof data.status === "string" ? data.status : "unknown";
+    const botToken = typeof data.bot_token === "string" ? data.bot_token : undefined;
+    const baseUrl = typeof data.baseurl === "string" ? data.baseurl : undefined;
+    return { status, botToken, baseUrl, raw: data };
+}
+async function safeJson(res) {
+    try {
+        const raw = await res.text();
+        if (!raw)
+            return null;
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/gateway/channels/wechat.d.ts

@@ -0,0 +1,40 @@
+import type { ChannelAdapter } from "../types.js";
+import { type FetchLike } from "./wechat-http.js";
+/** Options accepted by {@link createWechatChannel}. */
+export interface WechatChannelOptions {
+    id: string;
+    accountId: string;
+    /** iLink bot token. When omitted, the adapter loads it from the secret-store on start. */
+    botToken?: string;
+    baseUrl?: string;
+    /** Empty / missing list = default-deny (per security doc §"入站白名单"). */
+    allowedSenderIds?: string[];
+    splitAt?: number;
+    secretFile?: string;
+    stateFile?: string;
+    /** Test hook: override `globalThis.fetch`. */
+    fetchImpl?: FetchLike;
+    /** Test hook: synchronous state writes (`debounceMs: 0`). */
+    stateDebounceMs?: number;
+    /** Test hook: override Date.now() for trace cache TTL assertions. */
+    now?: () => number;
+}
+/**
+ * WeChat (iLink Bot API) channel adapter.
+ *
+ *   - long-polls `POST /ilink/bot/getupdates` (cursor = `get_updates_buf`,
+ *     persisted via state-store)
+ *   - normalizes `message_type === 1` text into a `GatewayInboundEnvelope`
+ *     with `conversation.id = "wechat:user:${fromUserId}"` and trace id
+ *     `wechat:${fromUserId}:${receivedAt}` (or `client_id` when present)
+ *   - per-trace cache binds `traceId → context_token`; `send()` looks up by
+ *     `GatewayOutboundMessage.traceId` and rejects if missing/expired
+ *     (no conversation-level fallback — see doc §"WeChat channel adapter")
+ *   - `send()` splits long replies at `splitAt` (default 1800), preferring
+ *     newline boundaries; `typing()` caches the per-user `typing_ticket`
+ *     fetched via `getconfig`.
+ *
+ * Allowlist is default-deny: an empty (or missing) `allowedSenderIds` rejects
+ * every inbound message.
+ */
+export declare function createWechatChannel(opts: WechatChannelOptions): ChannelAdapter;