@kin-tio/cli 0.6.0

package/dist/src/ilink/inbound-image.js

@@ -0,0 +1,310 @@
+import { createDecipheriv } from 'node:crypto';
+import { detectImageFormat, MAX_WECHAT_IMAGE_BYTES, } from '../lib/image-format.js';
+const ILINK_CDN_ORIGIN = 'https://novac2c.cdn.weixin.qq.com';
+const ILINK_CDN_DOWNLOAD_PATH = '/c2c/download';
+const ILINK_CDN_HOSTNAME = 'novac2c.cdn.weixin.qq.com';
+const MAX_LOCATOR_CHARACTERS = 32 * 1024;
+const MAX_ENCRYPTED_IMAGE_BYTES = MAX_WECHAT_IMAGE_BYTES + 16;
+const MAX_IMAGE_DIMENSION = 10_000;
+const MAX_IMAGE_PIXELS = 25_000_000;
+export const DEFAULT_ILINK_IMAGE_TIMEOUT_MS = 10_000;
+export class IlinkInboundImageError extends Error {
+    kind;
+    constructor(kind, message) {
+        // Deliberately do not retain a cause: fetch and crypto errors can contain
+        // the signed CDN URL or other provider-controlled values.
+        super(message);
+        this.name = 'IlinkInboundImageError';
+        this.kind = kind;
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function invalidLocator() {
+    return new IlinkInboundImageError('invalid_locator', 'iLink image contains an invalid or missing CDN locator');
+}
+function invalidKey() {
+    return new IlinkInboundImageError('invalid_key', 'iLink image contains an invalid or missing AES key');
+}
+function parseHexKey(value) {
+    if (typeof value !== 'string' || !/^[0-9a-fA-F]{32}$/u.test(value)) {
+        throw invalidKey();
+    }
+    return Buffer.from(value, 'hex');
+}
+function parseBase64Key(value) {
+    if (typeof value !== 'string' ||
+        value.length < 1 ||
+        value.length > 64 ||
+        value.length % 4 === 1 ||
+        !/^[A-Za-z0-9+/]+={0,2}$/u.test(value)) {
+        throw invalidKey();
+    }
+    const unpadded = value.replace(/=+$/u, '');
+    const decoded = Buffer.from(value, 'base64');
+    if (decoded.toString('base64').replace(/=+$/u, '') !== unpadded) {
+        throw invalidKey();
+    }
+    if (decoded.length === 16)
+        return decoded;
+    if (decoded.length === 32 &&
+        /^[0-9a-fA-F]{32}$/u.test(decoded.toString('ascii'))) {
+        return Buffer.from(decoded.toString('ascii'), 'hex');
+    }
+    throw invalidKey();
+}
+function validateDownloadUrl(raw) {
+    if (!raw ||
+        raw !== raw.trim() ||
+        raw.length > MAX_LOCATOR_CHARACTERS ||
+        /[\u0000-\u001f\u007f]/u.test(raw)) {
+        throw invalidLocator();
+    }
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw invalidLocator();
+    }
+    if (url.protocol !== 'https:' ||
+        url.hostname !== ILINK_CDN_HOSTNAME ||
+        url.username ||
+        url.password ||
+        url.port ||
+        url.hash) {
+        throw invalidLocator();
+    }
+    return url.href;
+}
+function buildDownloadUrl(queryParam) {
+    if (typeof queryParam !== 'string' ||
+        !queryParam ||
+        queryParam !== queryParam.trim() ||
+        queryParam.length > MAX_LOCATOR_CHARACTERS ||
+        /[\u0000-\u001f\u007f]/u.test(queryParam)) {
+        throw invalidLocator();
+    }
+    const query = new URLSearchParams({ encrypted_query_param: queryParam });
+    return `${ILINK_CDN_ORIGIN}${ILINK_CDN_DOWNLOAD_PATH}?${query}`;
+}
+/**
+ * Extract only the original-image CDN URL and AES key. `url`, `thumb_media`,
+ * and all non-image media fields are intentionally ignored.
+ */
+export function extractIlinkInboundImageLocator(imageItem) {
+    if (!isRecord(imageItem) || !isRecord(imageItem.media)) {
+        throw invalidLocator();
+    }
+    const media = imageItem.media;
+    const downloadUrl = media.full_url !== undefined
+        ? validateDownloadUrl(typeof media.full_url === 'string' ? media.full_url : '')
+        : buildDownloadUrl(media.encrypt_query_param);
+    // The official 2.4.6 implementation observes two key encodings. The
+    // image-level raw hex key takes precedence and an invalid preferred key is
+    // rejected rather than silently falling back to another field.
+    const aesKey = imageItem.aeskey !== undefined
+        ? parseHexKey(imageItem.aeskey)
+        : parseBase64Key(media.aes_key);
+    return Object.freeze({ downloadUrl, aesKey });
+}
+function normalizeTimeout(value) {
+    const timeoutMs = value ?? DEFAULT_ILINK_IMAGE_TIMEOUT_MS;
+    if (!Number.isSafeInteger(timeoutMs) ||
+        timeoutMs < 1 ||
+        timeoutMs > DEFAULT_ILINK_IMAGE_TIMEOUT_MS) {
+        throw new IlinkInboundImageError('download_failed', `iLink image timeout must be between 1 and ${DEFAULT_ILINK_IMAGE_TIMEOUT_MS} ms`);
+    }
+    return timeoutMs;
+}
+function declaredContentLength(response) {
+    const raw = response.headers.get('content-length');
+    if (raw === null)
+        return undefined;
+    if (!/^\d+$/u.test(raw)) {
+        throw new IlinkInboundImageError('download_failed', 'iLink image CDN returned an invalid response');
+    }
+    const length = Number(raw);
+    if (!Number.isSafeInteger(length)) {
+        throw new IlinkInboundImageError('response_too_large', 'iLink encrypted image exceeds the response size limit');
+    }
+    return length;
+}
+async function readBoundedBody(response) {
+    const length = declaredContentLength(response);
+    if (length !== undefined && length > MAX_ENCRYPTED_IMAGE_BYTES) {
+        throw new IlinkInboundImageError('response_too_large', 'iLink encrypted image exceeds the response size limit');
+    }
+    const reader = response.body?.getReader();
+    if (!reader) {
+        throw new IlinkInboundImageError('download_failed', 'iLink image CDN returned an empty response');
+    }
+    const chunks = [];
+    let total = 0;
+    while (true) {
+        const result = await reader.read();
+        if (result.done)
+            break;
+        const chunk = Buffer.from(result.value);
+        total += chunk.length;
+        if (total > MAX_ENCRYPTED_IMAGE_BYTES) {
+            void reader.cancel().catch(() => undefined);
+            throw new IlinkInboundImageError('response_too_large', 'iLink encrypted image exceeds the response size limit');
+        }
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks, total);
+}
+async function fetchEncryptedImage(downloadUrl, fetchImpl, signal) {
+    let response;
+    try {
+        response = await fetchImpl(downloadUrl, {
+            method: 'GET',
+            redirect: 'error',
+            signal,
+        });
+    }
+    catch {
+        if (signal.aborted) {
+            throw new IlinkInboundImageError('download_timeout', 'iLink image download timed out');
+        }
+        throw new IlinkInboundImageError('download_failed', 'iLink image CDN request failed');
+    }
+    if (response.redirected) {
+        throw new IlinkInboundImageError('download_failed', 'iLink image CDN redirect was rejected');
+    }
+    if (!response.ok) {
+        throw new IlinkInboundImageError('download_failed', `iLink image CDN request failed with HTTP ${response.status}`);
+    }
+    return readBoundedBody(response);
+}
+async function fetchWithTimeout(downloadUrl, fetchImpl, timeoutMs) {
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            reject(new IlinkInboundImageError('download_timeout', 'iLink image download timed out'));
+        }, timeoutMs);
+        timer.unref();
+    });
+    try {
+        return await Promise.race([
+            fetchEncryptedImage(downloadUrl, fetchImpl, controller.signal),
+            timeout,
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+function decryptImage(ciphertext, aesKey) {
+    if (ciphertext.length === 0 || ciphertext.length % 16 !== 0) {
+        throw new IlinkInboundImageError('decryption_failed', 'iLink image ciphertext is invalid');
+    }
+    try {
+        const decipher = createDecipheriv('aes-128-ecb', aesKey, null);
+        return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    }
+    catch {
+        throw new IlinkInboundImageError('decryption_failed', 'iLink image decryption failed');
+    }
+}
+function validateDimensions(width, height) {
+    if (width < 1 || height < 1 ||
+        width > MAX_IMAGE_DIMENSION || height > MAX_IMAGE_DIMENSION ||
+        width * height > MAX_IMAGE_PIXELS) {
+        throw new IlinkInboundImageError('unsupported_image', 'iLink image dimensions exceed the safe decode limit');
+    }
+}
+function validatePng(bytes) {
+    if (bytes.length < 45 || bytes.readUInt32BE(8) !== 13 ||
+        bytes.subarray(12, 16).toString('ascii') !== 'IHDR' ||
+        bytes.subarray(bytes.length - 8, bytes.length - 4).toString('ascii') !== 'IEND') {
+        throw new IlinkInboundImageError('unsupported_image', 'iLink PNG structure is incomplete');
+    }
+    validateDimensions(bytes.readUInt32BE(16), bytes.readUInt32BE(20));
+}
+function validateJpeg(bytes) {
+    if (bytes.length < 12 || bytes.readUInt16BE(0) !== 0xffd8) {
+        throw new IlinkInboundImageError('unsupported_image', 'iLink JPEG structure is incomplete');
+    }
+    let offset = 2;
+    let imageEnd = 0;
+    let dimensions;
+    while (offset + 3 < bytes.length) {
+        if (bytes[offset] !== 0xff)
+            break;
+        while (bytes[offset] === 0xff)
+            offset += 1;
+        const marker = bytes[offset++];
+        if (marker === undefined || marker === 0xd9)
+            break;
+        if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7))
+            continue;
+        if (offset + 2 > bytes.length)
+            break;
+        const length = bytes.readUInt16BE(offset);
+        if (length < 2 || offset + length > bytes.length)
+            break;
+        if ([
+            0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7,
+            0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf,
+        ].includes(marker)) {
+            if (length < 7)
+                break;
+            dimensions = {
+                height: bytes.readUInt16BE(offset + 3),
+                width: bytes.readUInt16BE(offset + 5),
+            };
+        }
+        if (marker === 0xda) {
+            const eoi = bytes.indexOf(Buffer.from([0xff, 0xd9]), offset + length);
+            if (eoi >= 0)
+                imageEnd = eoi + 2;
+            break;
+        }
+        offset += length;
+    }
+    if (!imageEnd) {
+        throw new IlinkInboundImageError('unsupported_image', 'iLink JPEG structure is incomplete');
+    }
+    if (!dimensions) {
+        throw new IlinkInboundImageError('unsupported_image', 'iLink JPEG dimensions are missing');
+    }
+    validateDimensions(dimensions.width, dimensions.height);
+    bytes.fill(0, imageEnd);
+    return bytes.subarray(0, imageEnd);
+}
+/**
+ * Download and decrypt one iLink image entirely in memory. No URL, key, or
+ * provider error body is retained in thrown errors.
+ */
+export async function downloadIlinkInboundImage(imageItem, options = {}) {
+    const locator = extractIlinkInboundImageLocator(imageItem);
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    if (typeof fetchImpl !== 'function') {
+        locator.aesKey.fill(0);
+        throw new IlinkInboundImageError('download_failed', 'iLink image download is unavailable');
+    }
+    try {
+        const ciphertext = await fetchWithTimeout(locator.downloadUrl, fetchImpl, normalizeTimeout(options.timeoutMs));
+        const bytes = decryptImage(ciphertext, locator.aesKey);
+        if (bytes.length > MAX_WECHAT_IMAGE_BYTES) {
+            throw new IlinkInboundImageError('image_too_large', 'iLink image exceeds the 2 MiB image size limit');
+        }
+        const format = detectImageFormat(bytes);
+        if (format?.mimeType !== 'image/png' && format?.mimeType !== 'image/jpeg') {
+            throw new IlinkInboundImageError('unsupported_image', 'iLink image must be PNG or JPEG');
+        }
+        if (format.mimeType === 'image/png')
+            validatePng(bytes);
+        const sanitized = format.mimeType === 'image/jpeg' ? validateJpeg(bytes) : bytes;
+        return Object.freeze({ bytes: sanitized, contentType: format.mimeType });
+    }
+    finally {
+        locator.aesKey.fill(0);
+    }
+}

package/dist/src/ilink/listener.js

@@ -0,0 +1,306 @@
+import { normalizeIlinkInboundMessage, } from './message.js';
+import { IlinkClient, IlinkProtocolError } from './protocol/client.js';
+const DEFAULT_BACKOFF_MIN_MS = 250;
+const DEFAULT_BACKOFF_MAX_MS = 10_000;
+function abortableSleep(milliseconds, signal) {
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(done, milliseconds);
+        function done() {
+            signal.removeEventListener('abort', aborted);
+            resolve();
+        }
+        function aborted() {
+            clearTimeout(timeout);
+            signal.removeEventListener('abort', aborted);
+            reject(signal.reason);
+        }
+        signal.addEventListener('abort', aborted, { once: true });
+    });
+}
+function validRuntimeAccount(account) {
+    return Boolean(account &&
+        typeof account.accountKey === 'string' &&
+        typeof account.providerAccountId === 'string' &&
+        account.providerAccountId &&
+        typeof account.ownerPeerId === 'string' &&
+        account.ownerPeerId &&
+        Number.isSafeInteger(account.generation) &&
+        account.generation > 0 &&
+        typeof account.cursor === 'string' &&
+        typeof account.botToken === 'string' &&
+        account.botToken &&
+        typeof account.baseUrl === 'string' &&
+        account.baseUrl);
+}
+function sameRuntime(running, desired) {
+    const current = running.account;
+    return current.accountKey === desired.accountKey &&
+        current.providerAccountId === desired.providerAccountId &&
+        current.ownerPeerId === desired.ownerPeerId &&
+        current.generation === desired.generation &&
+        running.cursor === desired.cursor &&
+        current.botToken === desired.botToken &&
+        current.baseUrl === desired.baseUrl;
+}
+function fenceRejection(error) {
+    if (!error || typeof error !== 'object' || !('code' in error))
+        return false;
+    return [
+        'account_not_found',
+        'account_not_active',
+        'generation_conflict',
+        'cursor_conflict',
+    ].includes(String(error.code));
+}
+function defaultClientFactory(account) {
+    return new IlinkClient({
+        token: account.botToken,
+        baseUrl: account.baseUrl,
+    });
+}
+export class IlinkListenerManager {
+    #host;
+    #createClient;
+    #logger;
+    #sleep;
+    #backoffMinMs;
+    #backoffMaxMs;
+    #listeners = new Map();
+    #tasks = new Set();
+    #refreshTail = Promise.resolve();
+    #started = false;
+    #closed = false;
+    #backlogReadyNotified = false;
+    constructor({ host, createClient = defaultClientFactory, logger = console, sleep = abortableSleep, backoffMinMs = DEFAULT_BACKOFF_MIN_MS, backoffMaxMs = DEFAULT_BACKOFF_MAX_MS, }) {
+        if (!Number.isSafeInteger(backoffMinMs) ||
+            !Number.isSafeInteger(backoffMaxMs) ||
+            backoffMinMs < 1 ||
+            backoffMaxMs < backoffMinMs) {
+            throw new Error('Invalid iLink listener backoff configuration');
+        }
+        this.#host = host;
+        this.#createClient = createClient;
+        this.#logger = logger;
+        this.#sleep = sleep;
+        this.#backoffMinMs = backoffMinMs;
+        this.#backoffMaxMs = backoffMaxMs;
+    }
+    start() {
+        if (this.#closed) {
+            return Promise.reject(new Error('iLink listener manager is closed'));
+        }
+        this.#started = true;
+        return this.refresh();
+    }
+    refresh() {
+        if (!this.#started) {
+            return Promise.reject(new Error('iLink listener manager is not started'));
+        }
+        if (this.#closed)
+            return Promise.resolve();
+        const refresh = this.#refreshTail.then(() => this.#reconcile());
+        this.#refreshTail = refresh.catch(() => undefined);
+        return refresh;
+    }
+    async #reconcile() {
+        if (this.#closed)
+            return;
+        const desired = new Map();
+        for (const account of this.#host.listActiveRuntimeAccounts()) {
+            if (!validRuntimeAccount(account) || desired.has(account.accountKey)) {
+                throw new Error('Invalid iLink runtime account list');
+            }
+            desired.set(account.accountKey, account);
+        }
+        const retiring = [];
+        for (const [accountKey, running] of this.#listeners) {
+            const account = desired.get(accountKey);
+            if (!account || !sameRuntime(running.state, account)) {
+                this.#listeners.delete(accountKey);
+                running.state.controller.abort();
+                retiring.push(running);
+            }
+        }
+        await Promise.allSettled(retiring.map((running) => running.task));
+        if (this.#closed)
+            return;
+        for (const [accountKey, account] of desired) {
+            if (!this.#listeners.has(accountKey))
+                this.#startAccount(account);
+        }
+        await this.#notifyBacklogReadyIfAll();
+    }
+    #startAccount(account) {
+        this.#backlogReadyNotified = false;
+        const state = {
+            account,
+            controller: new AbortController(),
+            client: this.#createClient(account),
+            cursor: account.cursor,
+            pendingMessageKeys: Object.freeze([]),
+            startedAt: Date.now(),
+            catchingUp: true,
+        };
+        const task = this.#run(state).finally(() => {
+            this.#tasks.delete(task);
+            if (this.#listeners.get(account.accountKey)?.state === state) {
+                this.#listeners.delete(account.accountKey);
+            }
+            void this.#notifyBacklogReadyIfAll();
+        });
+        this.#tasks.add(task);
+        this.#listeners.set(account.accountKey, { state, task });
+    }
+    async #run(state) {
+        try {
+            try {
+                await state.client.notifyStart?.();
+            }
+            catch {
+                if (!state.controller.signal.aborted && !this.#closed) {
+                    this.#logger.warn?.('[ilink-listener] notifyStart failed; continuing');
+                }
+            }
+            if (!state.controller.signal.aborted && !this.#closed) {
+                await this.#poll(state);
+            }
+        }
+        finally {
+            try {
+                // Deliberately do not pass the listener AbortSignal. notifyStop must be
+                // able to finish after the in-flight long poll has been cancelled.
+                await state.client.notifyStop?.();
+            }
+            catch {
+                this.#logger.warn?.('[ilink-listener] notifyStop failed; ignored');
+            }
+        }
+    }
+    async #poll(state) {
+        let failures = 0;
+        const { signal } = state.controller;
+        while (!this.#closed && !signal.aborted) {
+            try {
+                if (state.pendingMessageKeys.length > 0) {
+                    this.#host.enqueue(state.pendingMessageKeys);
+                    state.pendingMessageKeys = Object.freeze([]);
+                }
+                const expectedCursor = state.cursor;
+                const response = await state.client.getUpdates({ get_updates_buf: expectedCursor }, { signal });
+                if (signal.aborted || this.#closed)
+                    return;
+                const nextCursor = typeof response.get_updates_buf === 'string'
+                    ? response.get_updates_buf
+                    : expectedCursor;
+                if ((response.msgs?.length || 0) > 0 && nextCursor === expectedCursor) {
+                    throw new Error('iLink getUpdates returned messages without cursor progress');
+                }
+                const pair = {
+                    accountKey: state.account.accountKey,
+                    botId: state.account.providerAccountId,
+                    ownerUserId: state.account.ownerPeerId,
+                };
+                const messages = (response.msgs ?? []).flatMap((message, index) => {
+                    const normalized = normalizeIlinkInboundMessage(message, pair, { cursor: expectedCursor, index });
+                    return normalized ? [normalized] : [];
+                });
+                let committed;
+                try {
+                    committed = this.#host.commitPage({
+                        accountKey: state.account.accountKey,
+                        expectedGeneration: state.account.generation,
+                        expectedCursor,
+                        nextCursor,
+                        messages,
+                        deferredBefore: state.startedAt,
+                    });
+                }
+                catch (error) {
+                    if (fenceRejection(error))
+                        return;
+                    throw error;
+                }
+                state.cursor = committed.cursor;
+                state.pendingMessageKeys = Object.freeze([
+                    ...committed.insertedMessageKeys,
+                ]);
+                if (state.pendingMessageKeys.length > 0) {
+                    this.#host.enqueue(state.pendingMessageKeys);
+                    state.pendingMessageKeys = Object.freeze([]);
+                }
+                if (state.catchingUp &&
+                    ((response.msgs?.length || 0) === 0 ||
+                        messages.some(({ message }) => message.sentAt >= state.startedAt))) {
+                    state.catchingUp = false;
+                    await this.#notifyBacklogReadyIfAll();
+                }
+                else if ((committed.deferredMessageCount || 0) > 0 &&
+                    ![...this.#listeners.values()].some(({ state: other }) => other.catchingUp)) {
+                    await this.#host.backlogReady?.();
+                }
+                failures = 0;
+            }
+            catch (error) {
+                if (signal.aborted || this.#closed)
+                    return;
+                const sessionExpired = error instanceof IlinkProtocolError &&
+                    error.kind === 'business' &&
+                    (error.errcode === -14 || error.ret === -14);
+                if (state.catchingUp) {
+                    state.catchingUp = false;
+                    await this.#notifyBacklogReadyIfAll();
+                }
+                const delay = Math.min(this.#backoffMaxMs, this.#backoffMinMs * 2 ** Math.min(failures, 30));
+                failures += 1;
+                this.#logger.warn?.(`[ilink-listener] poll cycle failed; retry_ms=${delay}`);
+                try {
+                    await this.#sleep(delay, signal);
+                }
+                catch {
+                    if (signal.aborted || this.#closed)
+                        return;
+                }
+                if (sessionExpired && !signal.aborted && !this.#closed) {
+                    try {
+                        await state.client.notifyStart?.();
+                        failures = 0;
+                    }
+                    catch {
+                        this.#logger.warn?.('[ilink-listener] expired session refresh failed; retrying');
+                    }
+                }
+            }
+        }
+    }
+    async #notifyBacklogReadyIfAll() {
+        if (this.#closed || this.#backlogReadyNotified ||
+            [...this.#listeners.values()].some(({ state }) => state.catchingUp)) {
+            return;
+        }
+        this.#backlogReadyNotified = true;
+        await this.#host.backlogReady?.();
+    }
+    async waitForIdle() {
+        while (this.#tasks.size > 0) {
+            await Promise.allSettled([...this.#tasks]);
+        }
+    }
+    async close() {
+        if (this.#closed) {
+            await this.waitForIdle();
+            return;
+        }
+        this.#closed = true;
+        for (const running of this.#listeners.values()) {
+            running.state.controller.abort();
+        }
+        await this.#refreshTail;
+        for (const running of this.#listeners.values()) {
+            running.state.controller.abort();
+        }
+        await this.waitForIdle();
+        this.#listeners.clear();
+    }
+}