@sovovs/bycli 2.1.0 → 2.1.2

package/clis/weixin/_wechat/redact.js

@@ -0,0 +1,405 @@
+/** @typedef {{token: string, cookie: string, fingerprint?: string}} WechatCredentials */
+/** @typedef {{value: string, cookieNames: ReadonlySet<string>}} SecretCandidate */
+
+const REDACTION = '[REDACTED]';
+const CIRCULAR = '[CIRCULAR]';
+const FUNCTION = '[FUNCTION]';
+const BIGINT = '[BIGINT]';
+const SYMBOL = '[SYMBOL]';
+const UNDEFINED = '[UNDEFINED]';
+const NON_FINITE_NUMBER = '[NON_FINITE_NUMBER]';
+const LONG_SECRET_LENGTH = 8;
+function isSafeSecret(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function cookieValues(cookie) {
+    return cookie.split(';').flatMap(part => {
+        const separator = part.indexOf('=');
+        if (separator < 0)
+            return [];
+        const name = part.slice(0, separator).trim();
+        const value = part.slice(separator + 1).trim();
+        return isSafeSecret(value) ? [{ name, value }] : [];
+    });
+}
+function normalizeSecrets(secrets) {
+    return [...new Set(secrets.filter(isSafeSecret))].sort((left, right) => {
+        const byLength = right.length - left.length;
+        return byLength === 0 ? left.localeCompare(right) : byLength;
+    });
+}
+/** @param {WechatCredentials} credentials @returns {string[]} */
+export function buildSecretSet(credentials) {
+    const rawSecrets = [
+        credentials.token,
+        credentials.cookie,
+        credentials.fingerprint,
+        ...cookieValues(credentials.cookie).map(({ value }) => value),
+    ].filter(isSafeSecret);
+    return normalizeSecrets(rawSecrets.flatMap(value => [value, encodeURIComponent(value)]));
+}
+function percentCanonical(value) {
+    return value.replace(/%[\da-f]{2}/gi, escape => escape.toUpperCase());
+}
+function matchesAt(value, index, candidate) {
+    if (index + candidate.length > value.length)
+        return false;
+    for (let offset = 0; offset < candidate.length; offset += 1) {
+        if (candidate[offset] === '%' &&
+            offset + 2 < candidate.length &&
+            /^[\da-f]{2}$/i.test(candidate.slice(offset + 1, offset + 3))) {
+            const inputEscape = value.slice(index + offset, index + offset + 3);
+            if (!/^%[\da-f]{2}$/i.test(inputEscape))
+                return false;
+            if (inputEscape.toUpperCase() !== candidate.slice(offset, offset + 3).toUpperCase()) {
+                return false;
+            }
+            offset += 2;
+            continue;
+        }
+        if (value[index + offset] !== candidate[offset])
+            return false;
+    }
+    return true;
+}
+function candidateList(secrets) {
+    const normalized = normalizeSecrets(secrets);
+    const cookieNamesByValue = new Map();
+    for (const secret of normalized) {
+        let representations = [secret];
+        try {
+            const decoded = decodeURIComponent(secret);
+            if (decoded !== secret)
+                representations = [secret, decoded];
+        }
+        catch {
+            // A malformed percent escape is still a valid literal secret.
+        }
+        for (const representation of representations) {
+            for (const { name, value } of cookieValues(representation)) {
+                if (!name)
+                    continue;
+                for (const variant of [value, encodeURIComponent(value)]) {
+                    const canonical = percentCanonical(variant);
+                    const names = cookieNamesByValue.get(canonical) ?? new Set();
+                    names.add(name.toLowerCase());
+                    cookieNamesByValue.set(canonical, names);
+                }
+            }
+        }
+    }
+    const byCanonicalValue = new Map();
+    for (const value of normalized) {
+        const canonical = percentCanonical(value);
+        const cookieNames = cookieNamesByValue.get(canonical) ?? new Set();
+        const existing = byCanonicalValue.get(canonical);
+        if (existing) {
+            byCanonicalValue.set(canonical, {
+                value: existing.value,
+                cookieNames: new Set([...existing.cookieNames, ...cookieNames]),
+            });
+        }
+        else {
+            byCanonicalValue.set(canonical, { value, cookieNames });
+        }
+    }
+    return [...byCanonicalValue.values()].sort((left, right) => {
+        const byLength = right.value.length - left.value.length;
+        return byLength === 0 ? left.value.localeCompare(right.value) : byLength;
+    });
+}
+function isGlobalCandidate(value) {
+    if (value.length >= LONG_SECRET_LENGTH)
+        return true;
+    if (value.length < 4)
+        return false;
+    const classes = [/[a-z]/.test(value), /[A-Z]/.test(value), /\d/.test(value), /[^\w]/.test(value)];
+    return classes.every(Boolean);
+}
+function isSensitiveKey(key) {
+    return /^(?:access[-_.]?token|api[-_.]?key|authorization|cookie|fingerprint|password|secret|token)$/i.test(key);
+}
+function hasTokenBoundaries(value, index, length) {
+    const before = value[index - 1];
+    const after = value[index + length];
+    const isBoundary = (character) => character === undefined || /[\s&;,|()[\]{}<>"']/u.test(character);
+    return isBoundary(before) && isBoundary(after);
+}
+function isCompleteAssignment(candidate) {
+    return /^[\w.-]+(?:=|%3d).+/i.test(candidate);
+}
+function isWhitespace(character) {
+    return character !== undefined && /\s/u.test(character);
+}
+function buildTextContext(input) {
+    let standaloneStart = 0;
+    while (standaloneStart < input.length && isWhitespace(input[standaloneStart])) {
+        standaloneStart += 1;
+    }
+    let standaloneEnd = input.length;
+    while (standaloneEnd > standaloneStart && isWhitespace(input[standaloneEnd - 1])) {
+        standaloneEnd -= 1;
+    }
+    const assignmentKeys = new Map();
+    for (let start = 0; start < input.length; start += 1) {
+        if (start > 0 && !/[?&;,\s]/u.test(input[start - 1]))
+            continue;
+        if (!/[\w.-]/u.test(input[start]))
+            continue;
+        let cursor = start;
+        while (cursor < input.length && /[\w.-]/u.test(input[cursor]))
+            cursor += 1;
+        const key = input.slice(start, cursor).toLowerCase();
+        while (cursor < input.length && isWhitespace(input[cursor]))
+            cursor += 1;
+        if (input[cursor] !== '=' && input[cursor] !== ':')
+            continue;
+        cursor += 1;
+        while (cursor < input.length && isWhitespace(input[cursor]))
+            cursor += 1;
+        assignmentKeys.set(cursor, key);
+    }
+    const cookieValueEnds = new Map();
+    let lineStart = 0;
+    while (lineStart < input.length) {
+        const newline = input.indexOf('\n', lineStart);
+        const lineEnd = newline < 0 ? input.length : newline;
+        const line = input.slice(lineStart, lineEnd);
+        const header = /^\s*(?:cookie|set-cookie)\s*:\s*/iu.exec(line);
+        if (header) {
+            let segmentStart = header[0].length;
+            while (segmentStart < line.length) {
+                const separator = line.indexOf(';', segmentStart);
+                const segmentEnd = separator < 0 ? line.length : separator;
+                const equals = line.indexOf('=', segmentStart);
+                if (equals >= 0 && equals < segmentEnd) {
+                    let valueStart = equals + 1;
+                    while (valueStart < segmentEnd && isWhitespace(line[valueStart]))
+                        valueStart += 1;
+                    let valueEnd = valueStart;
+                    while (valueEnd < segmentEnd &&
+                        !isWhitespace(line[valueEnd]) &&
+                        line[valueEnd] !== ',') {
+                        valueEnd += 1;
+                    }
+                    if (valueEnd > valueStart) {
+                        cookieValueEnds.set(lineStart + valueStart, lineStart + valueEnd);
+                    }
+                }
+                if (separator < 0)
+                    break;
+                segmentStart = separator + 1;
+            }
+        }
+        if (newline < 0)
+            break;
+        lineStart = newline + 1;
+    }
+    return { standaloneStart, standaloneEnd, assignmentKeys, cookieValueEnds };
+}
+function mayRedactCandidate(input, index, candidate, context) {
+    if (isGlobalCandidate(candidate.value))
+        return true;
+    if (index === context.standaloneStart &&
+        index + candidate.value.length === context.standaloneEnd) {
+        return true;
+    }
+    if (context.cookieValueEnds.get(index) === index + candidate.value.length)
+        return true;
+    const assignmentKey = context.assignmentKeys.get(index);
+    if (assignmentKey) {
+        if (isSensitiveKey(assignmentKey))
+            return true;
+        if (candidate.cookieNames.has(assignmentKey))
+            return true;
+    }
+    if (isCompleteAssignment(candidate.value) && hasTokenBoundaries(input, index, candidate.value.length)) {
+        return true;
+    }
+    return false;
+}
+function stringifyWithoutHooks(value) {
+    if ((typeof value === 'object' && value !== null) || typeof value === 'function') {
+        return REDACTION;
+    }
+    return String(value);
+}
+/** @param {unknown} value @param {readonly string[]} secrets @returns {string} */
+export function redactText(value, secrets) {
+    const candidates = candidateList(secrets);
+    return redactTextWithCandidates(value, candidates);
+}
+function redactTextWithCandidates(value, candidates) {
+    const input = stringifyWithoutHooks(value);
+    if (candidates.length === 0)
+        return input;
+    const context = buildTextContext(input);
+    const pieces = [];
+    let unchangedStart = 0;
+    let index = 0;
+    while (index < input.length) {
+        const candidate = candidates.find(item => matchesAt(input, index, item.value) &&
+            mayRedactCandidate(input, index, item, context));
+        if (!candidate) {
+            index += 1;
+            continue;
+        }
+        pieces.push(input.slice(unchangedStart, index), REDACTION);
+        index += candidate.value.length;
+        unchangedStart = index;
+    }
+    pieces.push(input.slice(unchangedStart));
+    return pieces.join('');
+}
+function containsCandidate(value, candidates) {
+    for (let index = 0; index < value.length; index += 1) {
+        if (candidates.some(candidate => matchesAt(value, index, candidate.value)))
+            return true;
+    }
+    return false;
+}
+function collisionSafeKey(target, key) {
+    if (!Object.prototype.hasOwnProperty.call(target, key))
+        return key;
+    if (typeof key === 'symbol')
+        return Symbol();
+    let suffix = 2;
+    let candidate = `${key}_${suffix}`;
+    while (Object.prototype.hasOwnProperty.call(target, candidate)) {
+        suffix += 1;
+        candidate = `${key}_${suffix}`;
+    }
+    return candidate;
+}
+function isCanonicalArrayIndex(target, key) {
+    if (!Array.isArray(target))
+        return false;
+    const index = Number(key);
+    return Number.isInteger(index)
+        && index >= 0
+        && index < target.length
+        && String(index) === key;
+}
+function shouldSanitizeStringKey(target, key, candidates) {
+    if (isCanonicalArrayIndex(target, key))
+        return false;
+    return redactTextWithCandidates(key, candidates) !== key;
+}
+function copyRedactedDescriptors(descriptors, target, candidates, seen, active, skippedKeys = new Set()) {
+    for (const key of Reflect.ownKeys(descriptors)) {
+        if (skippedKeys.has(key))
+            continue;
+        const descriptor = descriptors[key];
+        if (!descriptor)
+            continue;
+        let safeKey = key;
+        if (typeof key === 'string') {
+            if (shouldSanitizeStringKey(target, key, candidates))
+                safeKey = REDACTION;
+        }
+        else if (key.description !== undefined) {
+            if (containsCandidate(key.description, candidates))
+                safeKey = Symbol();
+        }
+        safeKey = collisionSafeKey(target, safeKey);
+        if ('value' in descriptor) {
+            Object.defineProperty(target, safeKey, {
+                configurable: true,
+                enumerable: descriptor.enumerable ?? false,
+                writable: true,
+                value: redactRecursive(descriptor.value, candidates, seen, active),
+            });
+        }
+        else {
+            Object.defineProperty(target, safeKey, {
+                configurable: true,
+                enumerable: descriptor.enumerable ?? false,
+                writable: true,
+                value: REDACTION,
+            });
+        }
+    }
+}
+function hasErrorPrototype(value) {
+    const visited = new Set();
+    let prototype = Object.getPrototypeOf(value);
+    while (prototype !== null && !visited.has(prototype)) {
+        if (prototype === Error.prototype)
+            return true;
+        visited.add(prototype);
+        prototype = Object.getPrototypeOf(prototype);
+    }
+    return false;
+}
+function inheritedErrorString(value, key) {
+    const visited = new Set();
+    let prototype = Object.getPrototypeOf(value);
+    while (prototype !== null && !visited.has(prototype)) {
+        visited.add(prototype);
+        const descriptor = Object.getOwnPropertyDescriptor(prototype, key);
+        if (descriptor && 'value' in descriptor && typeof descriptor.value === 'string') {
+            return descriptor.value;
+        }
+        prototype = Object.getPrototypeOf(prototype);
+    }
+    return '';
+}
+function defineErrorDefaults(source, descriptors, target, candidates) {
+    for (const key of ['name', 'message']) {
+        if (Object.prototype.hasOwnProperty.call(descriptors, key))
+            continue;
+        Object.defineProperty(target, key, {
+            configurable: true,
+            enumerable: false,
+            writable: true,
+            value: redactTextWithCandidates(inheritedErrorString(source, key), candidates),
+        });
+    }
+}
+function redactRecursive(value, candidates, seen, active) {
+    if (typeof value === 'string')
+        return redactTextWithCandidates(value, candidates);
+    if (typeof value === 'function')
+        return FUNCTION;
+    if (typeof value === 'bigint')
+        return BIGINT;
+    if (typeof value === 'symbol')
+        return SYMBOL;
+    if (typeof value === 'undefined')
+        return UNDEFINED;
+    if (typeof value === 'number' && !Number.isFinite(value))
+        return NON_FINITE_NUMBER;
+    if (!value || typeof value !== 'object')
+        return value;
+    if (active.has(value))
+        return CIRCULAR;
+    if (seen.has(value))
+        return seen.get(value);
+    try {
+        const array = Array.isArray(value);
+        const error = !array && hasErrorPrototype(value);
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        const lengthDescriptor = descriptors.length;
+        const arrayLength = array && lengthDescriptor && 'value' in lengthDescriptor && typeof lengthDescriptor.value === 'number'
+            ? lengthDescriptor.value
+            : 0;
+        const output = array ? new Array(arrayLength) : Object.create(null);
+        seen.set(value, output);
+        active.add(value);
+        if (error)
+            defineErrorDefaults(value, descriptors, output, candidates);
+        copyRedactedDescriptors(descriptors, output, candidates, seen, active, array ? new Set(['length']) : undefined);
+        active.delete(value);
+        return output;
+    }
+    catch {
+        active.delete(value);
+        seen.set(value, REDACTION);
+        return REDACTION;
+    }
+}
+/** @param {unknown} value @param {readonly string[]} secrets @returns {unknown} */
+export function redactValue(value, secrets) {
+    const candidates = candidateList(secrets);
+    return redactRecursive(value, candidates, new WeakMap(), new WeakSet());
+}

package/clis/weixin/_wechat/save-service.js

@@ -0,0 +1,175 @@
+import * as defaultFs from 'node:fs';
+import path from 'node:path';
+import { ArgumentError, CommandExecutionError } from '@sovovs/bycli/errors';
+import { cleanMarkdownFilename, wechatArticleToMarkdown } from './markdown.js';
+
+export const MAX_FILENAME_ATTEMPTS = 100;
+
+function commandError(action, error) {
+  return new CommandExecutionError(`Failed to ${action}: ${error instanceof Error ? error.message : String(error)}`);
+}
+
+function assertInside(root, target) {
+  const relative = path.relative(root, target);
+  if (relative === '' || relative.startsWith(`..${path.sep}`) || relative === '..' || path.isAbsolute(relative)) {
+    throw new CommandExecutionError('Refusing to save an article outside the output directory');
+  }
+}
+
+function sameIdentity(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+function assertResolvedPathComponents(root, fsImpl) {
+  const parsed = path.parse(root);
+  let current = parsed.root;
+  for (const part of root.slice(parsed.root.length).split(path.sep).filter(Boolean)) {
+    current = path.join(current, part);
+    const stat = fsImpl.lstatSync(current);
+    if (stat.isSymbolicLink?.()) throw new CommandExecutionError('Refusing to save through a symbolic link');
+  }
+}
+
+function assertRootIdentity(root, rootFd, rootIdentity, fsImpl) {
+  assertResolvedPathComponents(root, fsImpl);
+  const pathStat = fsImpl.lstatSync(root);
+  const fdStat = fsImpl.fstatSync(rootFd);
+  if (!pathStat.isDirectory?.() || !fdStat.isDirectory?.()
+      || !sameIdentity(pathStat, rootIdentity) || !sameIdentity(fdStat, rootIdentity)) {
+    throw new CommandExecutionError('Output directory identity changed during save');
+  }
+}
+
+function cleanupOpenedTarget(target, openedStat, fsImpl) {
+  try {
+    const current = fsImpl.lstatSync(target);
+    if (sameIdentity(current, openedStat) && !current.isSymbolicLink?.()) fsImpl.unlinkSync(target);
+  } catch {
+    // Fail closed; cleanup is best effort after identity mismatch.
+  }
+}
+
+function writeExclusive(root, rootFd, rootIdentity, target, markdown, fsImpl) {
+  const noFollow = defaultFs.constants.O_NOFOLLOW;
+  if (typeof noFollow !== 'number') {
+    throw new CommandExecutionError('Secure article saving is unavailable: O_NOFOLLOW is unsupported');
+  }
+  // The opened root fd plus its dev/ino is the authorization capability.
+  // Path checks detect namespace replacement, but cannot and need not prevent
+  // a same-privilege process from renaming that already-authorized inode.
+  assertRootIdentity(root, rootFd, rootIdentity, fsImpl);
+  let fd;
+  let openedStat;
+  try {
+    fd = fsImpl.openSync(target,
+      defaultFs.constants.O_CREAT | defaultFs.constants.O_EXCL | defaultFs.constants.O_WRONLY | noFollow,
+      0o600);
+    // Once open succeeds, this fd remains bound to that inode; later renames
+    // or symlink swaps cannot redirect its writes into a replacement root.
+    openedStat = fsImpl.fstatSync(fd);
+    if (!openedStat.isFile?.() || openedStat.isSymbolicLink?.()) {
+      throw new CommandExecutionError('Refusing to write a non-regular article target');
+    }
+    assertRootIdentity(root, rootFd, rootIdentity, fsImpl);
+    const body = Buffer.from(markdown, 'utf8');
+    let offset = 0;
+    while (offset < body.length) {
+      const written = fsImpl.writeSync(fd, body, offset, body.length - offset);
+      if (!Number.isInteger(written) || written <= 0) throw new CommandExecutionError('Failed to write article bytes');
+      offset += written;
+    }
+    fsImpl.fsyncSync?.(fd);
+    assertRootIdentity(root, rootFd, rootIdentity, fsImpl);
+  } catch (error) {
+    if (openedStat) cleanupOpenedTarget(target, openedStat, fsImpl);
+    throw error;
+  } finally {
+    if (fd !== undefined) fsImpl.closeSync(fd);
+  }
+}
+
+export async function saveArticles({ articles, accountName, outputDir, fetchArticleHtml, buildMarkdown = wechatArticleToMarkdown, fsImpl = defaultFs }) {
+  if (!Array.isArray(articles) || articles.length > 1000) {
+    throw new ArgumentError('articles must be an array of at most 1000 items');
+  }
+  const requestedRoot = path.resolve(outputDir);
+  try { fsImpl.mkdirSync(requestedRoot, { recursive: true }); } catch (error) { throw commandError('create output directory', error); }
+  let root;
+  try { root = fsImpl.realpathSync(requestedRoot); } catch (error) { throw commandError('resolve output directory', error); }
+  let rootFd;
+  let rootIdentity;
+  try {
+    assertResolvedPathComponents(root, fsImpl);
+    rootIdentity = fsImpl.lstatSync(root);
+    if (!rootIdentity.isDirectory?.() || rootIdentity.isSymbolicLink?.()) throw new Error('not a directory');
+    rootFd = fsImpl.openSync(root, defaultFs.constants.O_RDONLY);
+    const openedRoot = fsImpl.fstatSync(rootFd);
+    if (!openedRoot.isDirectory?.() || !sameIdentity(openedRoot, rootIdentity)) {
+      throw new CommandExecutionError('Output directory identity changed during secure open');
+    }
+    assertRootIdentity(root, rootFd, rootIdentity, fsImpl);
+  } catch (error) {
+    if (rootFd !== undefined) fsImpl.closeSync(rootFd);
+    if (error instanceof CommandExecutionError) throw error;
+    throw commandError('secure output directory', error);
+  }
+  const reserved = new Set();
+  const rows = [];
+
+  try {
+    for (const article of articles) {
+      let articleHtml;
+      try {
+        articleHtml = await fetchArticleHtml(article);
+      } catch {
+        rows.push({ title: article.title || '', url: article.url || '', status: 'failed', stage: 'download', saved: '', error: 'article download failed' });
+        continue;
+      }
+      let markdown;
+      try {
+        markdown = buildMarkdown({ html: articleHtml, title: article.title, accountName,
+          author: article.author, publishedAt: article.publishedAt, digest: article.digest, url: article.url });
+      } catch {
+        rows.push({ title: article.title || '', url: article.url || '', status: 'failed', stage: 'download', saved: '', error: 'invalid article content' });
+        continue;
+      }
+
+      let suffix = 1;
+      let target;
+      while (suffix <= MAX_FILENAME_ATTEMPTS) {
+        const suffixText = suffix === 1 ? '' : `-${suffix}`;
+        const name = `${cleanMarkdownFilename(article.title, 100, suffixText)}${suffixText}`;
+        target = path.resolve(root, `${name}.md`);
+        assertInside(root, target);
+        if (reserved.has(target)) { suffix += 1; continue; }
+        try {
+          const stat = fsImpl.lstatSync(target);
+          if (stat.isSymbolicLink?.()) throw new CommandExecutionError('Refusing to overwrite a symbolic link');
+          suffix += 1;
+          continue;
+        } catch (error) {
+          if (error instanceof CommandExecutionError) throw error;
+          if (error?.code !== 'ENOENT') throw commandError('inspect article target', error);
+        }
+        try {
+          writeExclusive(root, rootFd, rootIdentity, target, markdown, fsImpl);
+          reserved.add(target);
+          break;
+        } catch (error) {
+          if (error?.code === 'EEXIST') {
+            suffix += 1;
+            continue;
+          }
+          throw commandError('write article Markdown', error);
+        }
+      }
+      if (suffix > MAX_FILENAME_ATTEMPTS) {
+        throw new CommandExecutionError(`Failed to reserve an article filename after ${MAX_FILENAME_ATTEMPTS} attempts`);
+      }
+      rows.push({ title: article.title || '', url: article.url || '', status: 'saved', stage: null, saved: target, error: '' });
+    }
+  } finally {
+    fsImpl.closeSync(rootFd);
+  }
+  return rows;
+}

package/clis/weixin/_wechat/search-biz.js

@@ -0,0 +1,102 @@
+import {
+  AuthRequiredError,
+  CommandExecutionError,
+} from '@sovovs/bycli/errors';
+import { buildSecretSet, redactText } from './redact.js';
+
+const DOMAIN = 'mp.weixin.qq.com';
+const ENDPOINT = `https://${DOMAIN}/cgi-bin/searchbiz`;
+
+/** @param {string} token */
+function buildReferer(token) {
+  const params = new URLSearchParams({
+    t: 'media/appmsg_edit_v2', action: 'edit', isNew: '1', type: '10',
+    token, lang: 'zh_CN',
+  });
+  return `https://${DOMAIN}/cgi-bin/appmsg?${params}`;
+}
+
+/** @param {unknown} payload */
+export function mapSearchBizPayload(payload) {
+  if (!payload || typeof payload !== 'object') {
+    throw new CommandExecutionError('WeChat search_biz returned an unreadable response');
+  }
+  const response = /** @type {Record<string, any>} */ (payload);
+  const ret = response.base_resp?.ret;
+  const message = String(response.base_resp?.err_msg ?? response.base_resp?.err_msg_en ?? '');
+  const normalizedMessage = message.trim().toLowerCase().replace(/\s+/g, ' ');
+  if (ret === 200013 && normalizedMessage === 'invalid credential') {
+    throw new AuthRequiredError(DOMAIN, 'WeChat search credentials have expired');
+  }
+  if (ret !== 0) {
+    throw new CommandExecutionError(`WeChat search_biz failed (ret=${String(ret ?? 'unknown')})`);
+  }
+  if (!Array.isArray(response.list)) {
+    throw new CommandExecutionError('WeChat search_biz returned an invalid account list');
+  }
+  return response.list.map((item, index) => {
+    if (!item || typeof item !== 'object'
+      || typeof item.nickname !== 'string' || !item.nickname.trim()
+      || typeof item.fakeid !== 'string' || !item.fakeid.trim()) {
+      throw new CommandExecutionError(`WeChat search_biz returned an invalid account at index ${index}`);
+    }
+    return {
+      nickname: item.nickname,
+      fakeid: item.fakeid,
+      alias: typeof item.alias === 'string' && item.alias.length > 0 ? item.alias : null,
+    };
+  });
+}
+
+/** @param {unknown} error @param {{token:string,cookie:string,fingerprint?:string}} credentials */
+function transportError(error, credentials) {
+  const secrets = buildSecretSet(credentials);
+  const message = error instanceof Error ? error.message : String(error);
+  const hint = error && typeof error === 'object' && 'hint' in error && typeof error.hint === 'string'
+    ? error.hint : undefined;
+  const redactedMessage = redactText(message, secrets);
+  const redactedHint = hint ? redactText(hint, secrets) : undefined;
+  if (error instanceof AuthRequiredError
+    && error.domain === DOMAIN
+    && redactedMessage === message
+    && redactedHint === hint) return error;
+  return new CommandExecutionError(
+    `WeChat search_biz request failed: ${redactedMessage}`,
+    redactedHint,
+  );
+}
+
+/**
+ * @param {{page:any,source:'browser'|'env',credentials:{token:string,cookie:string,fingerprint?:string},query:string,limit:number,fetchImpl?:typeof fetch,timeoutMs?:number}} input
+ */
+export async function executeSearchBiz({ page, source, credentials, query, limit, fetchImpl = fetch, timeoutMs = 30_000 }) {
+  const params = new URLSearchParams({
+    action: 'search_biz', scene: '1', begin: '0', count: String(limit), query,
+    fingerprint: credentials.fingerprint ?? '', token: credentials.token,
+    lang: 'zh_CN', f: 'json', ajax: '1',
+  });
+  const url = `${ENDPOINT}?${params}`;
+  const headers = {
+    Referer: buildReferer(credentials.token),
+    'X-Requested-With': 'XMLHttpRequest',
+  };
+
+  try {
+    let payload;
+    if (source === 'browser') {
+      payload = await page.fetchJson(url, { headers });
+    } else {
+      const response = await fetchImpl(url, {
+        headers: { ...headers, Cookie: credentials.cookie },
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      if (!response.ok) {
+        throw new CommandExecutionError(`WeChat search_biz request failed: HTTP ${response.status}`);
+      }
+      payload = await response.json();
+    }
+    return mapSearchBizPayload(payload);
+  } catch (error) {
+    throw transportError(error, credentials);
+  }
+}