@xmanrui/dsh-im 4.14.0 → 4.16.0

package/src/channels/wecom-app/callback-server.mjs

@@ -0,0 +1,471 @@
+import { createServer } from 'node:http';
+import { timingSafeEqual } from 'node:crypto';
+
+import {
+  WECOM_APP_STREAM_PLACEHOLDER,
+  buildEncryptedReply,
+  createUserCrypto,
+  isXmlFormat,
+  parseWecomAppPlainMessage,
+  parseWecomAppXmlBody,
+} from './wecom-app-api.mjs';
+
+const DEFAULT_STREAM_TTL_MS = 15 * 60_000;
+const DEFAULT_MAX_STREAMS = 256;
+const DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
+
+function safeEqualHex(expected, provided) {
+  const a = Buffer.from(String(expected ?? ''), 'utf8');
+  const b = Buffer.from(String(provided ?? ''), 'utf8');
+  if (a.length === 0 || a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+function writeBody(res, status, body, headers = {}) {
+  if (res.writableEnded || res.destroyed) return;
+  res.writeHead(status, {
+    'content-length': String(Buffer.byteLength(body)),
+    'cache-control': 'no-store',
+    ...headers,
+  });
+  res.end(body);
+}
+
+function writeText(res, status, text, headers = {}) {
+  writeBody(res, status, text, { 'content-type': 'text/plain; charset=utf-8', ...headers });
+}
+
+function writeEmpty(res) {
+  if (res.writableEnded || res.destroyed) return;
+  res.statusCode = 200;
+  res.end();
+}
+
+// One shared HTTP listener for every wecom-app bot. Each bot registers a route
+// keyed by its full callback path; the per-bot random path segment doubles as
+// the first gate before the WeCom signature check.
+export class WecomAppCallbackServer {
+  #host;
+  #port;
+  #logger;
+  #streamTtlMs;
+  #maxStreams;
+  #maxBodyBytes;
+  #server = null;
+  #routes = new Map();
+  #streams = new Map();
+  #streamByMsgId = new Map();
+
+  constructor({
+    host = '127.0.0.1',
+    port = 30987,
+    logger = console,
+    streamTtlMs = DEFAULT_STREAM_TTL_MS,
+    maxStreams = DEFAULT_MAX_STREAMS,
+    maxBodyBytes = DEFAULT_MAX_BODY_BYTES,
+  } = {}) {
+    this.#host = String(host ?? '127.0.0.1');
+    this.#port = Number(port);
+    if (!Number.isInteger(this.#port) || this.#port < 0 || this.#port > 65_535) {
+      throw new TypeError('WecomAppCallbackServer requires an integer port between 0 and 65535');
+    }
+    this.#logger = logger;
+    this.#streamTtlMs = streamTtlMs;
+    this.#maxStreams = maxStreams;
+    this.#maxBodyBytes = maxBodyBytes;
+  }
+
+  get listening() {
+    return this.#server !== null && this.#server.listening === true;
+  }
+
+  get address() {
+    return { host: this.#host, port: this.#port };
+  }
+
+  // The OS-assigned port after listen(0); falls back to the configured port.
+  get actualPort() {
+    const bound = this.#server?.address?.();
+    return typeof bound?.port === 'number' ? bound.port : this.#port;
+  }
+
+  routePath({ botId, callbackSecret }) {
+    // Keep the callback prefix distinct from the GUI RPC channel path
+    // (/wecom-app/...): the reverse-proxy location must forward ONLY the
+    // callback prefix to this listener and leave RPC traffic to dsh web.
+    return `/wecom-app-callback/${botId}/${callbackSecret}`;
+  }
+
+  registerRoute(route) {
+    if (!route?.botId || !route.callbackSecret || typeof route.cryptoFor !== 'function' || typeof route.onInbound !== 'function') {
+      throw new TypeError('A wecom-app route requires botId, callbackSecret, cryptoFor, and onInbound');
+    }
+    // Keyed by the full callback path: WeCom requests are dispatched on it.
+    this.#routes.set(this.routePath(route), Object.freeze({ ...route }));
+    return this;
+  }
+
+  unregisterRoute(botId) {
+    for (const [path, route] of this.#routes.entries()) {
+      if (route.botId === botId) this.#routes.delete(path);
+    }
+    for (const [streamId, stream] of this.#streams.entries()) {
+      if (stream.botId === botId) {
+        this.#streams.delete(streamId);
+        if (stream.msgid) this.#streamByMsgId.delete(this.#msgKey(stream.botId, stream.msgid));
+      }
+    }
+    return this;
+  }
+
+  async start() {
+    if (this.#server) return this.address;
+    const server = createServer((request, response) => {
+      this.#handleRequest(request, response).catch((error) => {
+        this.#logger.warn?.('[dsh-im:wecom-app] callback request failed:', error);
+        writeText(response, 500, 'internal error');
+      });
+    });
+    server.on('clientError', (_error, socket) => {
+      if (socket.writable) socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
+    });
+    await new Promise((resolve, reject) => {
+      const onceError = (error) => {
+        server.removeListener('listening', onceListening);
+        reject(error);
+      };
+      const onceListening = () => {
+        server.removeListener('error', onceError);
+        resolve();
+      };
+      server.once('error', onceError);
+      server.once('listening', onceListening);
+      server.listen(this.#port, this.#host);
+    });
+    this.#server = server;
+    return this.address;
+  }
+
+  async stop() {
+    const server = this.#server;
+    this.#server = null;
+    this.#routes.clear();
+    this.#streams.clear();
+    this.#streamByMsgId.clear();
+    if (!server) return;
+    await new Promise((resolve) => {
+      server.close(() => resolve());
+      server.closeAllConnections?.();
+    });
+  }
+
+  routeCount() {
+    return this.#routes.size;
+  }
+
+  // Stream dedup and lookup are scoped per bot: two self-built apps can share
+  // a MsgId, and a refresh signed by app B must never read app A's stream.
+  #msgKey(botId, msgid) {
+    return botId + ':' + msgid;
+  }
+
+  createStream({ botId, msgid }) {
+    this.#pruneStreams();
+    if (this.#streams.size >= this.#maxStreams) {
+      const oldest = this.#streams.keys().next().value;
+      const evicted = this.#streams.get(oldest);
+      this.#streams.delete(oldest);
+      if (evicted?.msgid) this.#streamByMsgId.delete(this.#msgKey(evicted.botId, evicted.msgid));
+    }
+    const streamId = `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
+    const state = {
+      botId,
+      streamId,
+      msgid: msgid ?? null,
+      content: '',
+      finished: false,
+      error: null,
+      refreshes: 0,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    };
+    this.#streams.set(streamId, state);
+    if (msgid) this.#streamByMsgId.set(this.#msgKey(botId, msgid), streamId);
+    return state;
+  }
+
+  getStream(streamId) {
+    return this.#streams.get(streamId) ?? null;
+  }
+
+  appendStream(streamId, chunk, { replace = false } = {}) {
+    const stream = this.#streams.get(streamId);
+    if (!stream || stream.finished) return false;
+    stream.content = replace ? String(chunk ?? '') : stream.content + String(chunk ?? '');
+    stream.updatedAt = Date.now();
+    return true;
+  }
+
+  finishStream(streamId, { error } = {}) {
+    const stream = this.#streams.get(streamId);
+    if (!stream) return false;
+    if (error) stream.error = String(error);
+    stream.finished = true;
+    stream.updatedAt = Date.now();
+    return true;
+  }
+
+  streamSnapshot(streamId) {
+    const stream = this.#streams.get(streamId);
+    if (!stream) return null;
+    return {
+      id: stream.streamId,
+      finish: stream.finished,
+      content: stream.content,
+    };
+  }
+
+  async #handleRequest(request, response) {
+    if (request.method !== 'GET' && request.method !== 'POST') {
+      writeText(response, 405, 'method not allowed', { allow: 'GET, POST' });
+      return;
+    }
+    const url = new URL(request.url ?? '/', `http://${request.headers.host ?? 'localhost'}`);
+    const route = this.#routes.get(url.pathname) ?? null;
+    if (!route) {
+      writeText(response, 404, 'not found');
+      return;
+    }
+    const query = url.searchParams;
+    if (request.method === 'GET') {
+      this.#verifyUrl(route, query, response);
+      return;
+    }
+    await this.#handlePost(route, query, request, response);
+  }
+
+  #verifyUrl(route, query, response) {
+    const timestamp = query.get('timestamp') ?? '';
+    const nonce = query.get('nonce') ?? '';
+    const echostr = query.get('echostr') ?? '';
+    const signature = query.get('msg_signature') ?? query.get('msgsignature') ?? query.get('signature') ?? '';
+    this.#logger.info?.('[dsh-im:wecom-app] URL verification attempt', route.botId, { timestamp, nonce });
+    if (!timestamp || !nonce || !echostr || !signature) {
+      this.#logger.warn?.('[dsh-im:wecom-app] URL verification rejected: missing query params', route.botId);
+      writeText(response, 400, 'missing query params');
+      return;
+    }
+    let crypto;
+    try {
+      crypto = route.cryptoFor();
+    } catch (error) {
+      this.#logger.warn?.('[dsh-im:wecom-app] route credentials are incomplete:', error);
+      writeText(response, 503, 'route not ready');
+      return;
+    }
+    try {
+      if (!safeEqualHex(crypto.computeSignature(timestamp, nonce, echostr), signature)) {
+        this.#logger.warn?.('[dsh-im:wecom-app] URL verification signature mismatch', route.botId);
+        writeText(response, 401, 'unauthorized');
+        return;
+      }
+      const plaintext = crypto.decrypt(echostr);
+      this.#logger.info?.('[dsh-im:wecom-app] URL verification succeeded', route.botId);
+      writeText(response, 200, plaintext);
+    } catch (error) {
+      this.#logger.warn?.('[dsh-im:wecom-app] URL verification failed:', error);
+      writeText(response, 400, 'verification failed');
+    }
+  }
+
+  async #handlePost(route, query, request, response) {
+    const body = await this.#readBody(request, response);
+    if (body === null) return;
+    let envelope = {};
+    if (isXmlFormat(body.raw)) {
+      const xml = parseWecomAppXmlBody(body.raw);
+      envelope = {
+        encrypt: xml.Encrypt ?? '',
+        signature: xml.MsgSignature ?? query.get('msg_signature') ?? query.get('msgsignature') ?? '',
+        timestamp: xml.TimeStamp ?? query.get('timestamp') ?? '',
+        nonce: xml.Nonce ?? query.get('nonce') ?? '',
+        format: 'xml',
+      };
+    } else {
+      let parsed = {};
+      try {
+        parsed = JSON.parse(body.raw);
+      } catch {
+        writeText(response, 400, 'invalid payload');
+        return;
+      }
+      envelope = {
+        encrypt: parsed.encrypt ?? '',
+        signature: parsed.msgsignature ?? parsed.MsgSignature ?? query.get('msg_signature') ?? '',
+        timestamp: String(parsed.timestamp ?? parsed.TimeStamp ?? query.get('timestamp') ?? ''),
+        nonce: String(parsed.nonce ?? parsed.Nonce ?? query.get('nonce') ?? ''),
+        format: 'json',
+      };
+    }
+    if (!envelope.encrypt || !envelope.signature || !envelope.timestamp || !envelope.nonce) {
+      writeText(response, 400, 'missing encrypted payload');
+      return;
+    }
+    this.#logger.info?.('[dsh-im:wecom-app] callback POST received', route.botId, { format: envelope.format, bytes: body.raw.length });
+    let crypto;
+    try {
+      crypto = route.cryptoFor();
+    } catch (error) {
+      this.#logger.warn?.('[dsh-im:wecom-app] route credentials are incomplete:', error);
+      writeText(response, 503, 'route not ready');
+      return;
+    }
+    let plaintext;
+    try {
+      if (!safeEqualHex(crypto.computeSignature(envelope.timestamp, envelope.nonce, envelope.encrypt), envelope.signature)) {
+        this.#logger.warn?.('[dsh-im:wecom-app] callback signature mismatch', route.botId);
+        writeText(response, 401, 'unauthorized');
+        return;
+      }
+      plaintext = crypto.decrypt(envelope.encrypt);
+    } catch (error) {
+      this.#logger.warn?.('[dsh-im:wecom-app] callback signature or decryption failed:', error);
+      writeText(response, 401, 'unauthorized');
+      return;
+    }
+    const message = parseWecomAppPlainMessage(plaintext);
+    if (!message) {
+      writeText(response, 400, 'invalid message');
+      return;
+    }
+    this.#logger.info?.('[dsh-im:wecom-app] callback message accepted', route.botId, { msgtype: message.msgtype ?? null, msgid: message.msgid ?? null });
+    this.#dispatch(route, message, envelope, response);
+  }
+
+  #readBody(request, response) {
+    return new Promise((resolve) => {
+      const chunks = [];
+      let length = 0;
+      request.on('data', (chunk) => {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        length += buffer.length;
+        if (length > this.#maxBodyBytes) {
+          writeText(response, 413, 'payload too large');
+          request.destroy();
+          resolve(null);
+          return;
+        }
+        chunks.push(buffer);
+      });
+      request.on('end', () => {
+        const raw = Buffer.concat(chunks, length).toString('utf8');
+        if (!raw.trim()) {
+          writeText(response, 400, 'empty payload');
+          resolve(null);
+          return;
+        }
+        resolve({ raw });
+      });
+      request.on('error', () => {
+        resolve(null);
+      });
+    });
+  }
+
+  #dispatch(route, message, envelope, response) {
+    const msgid = typeof message.msgid === 'string' ? message.msgid : null;
+    const isStreamRefresh = message.msgtype === 'stream' || message.event === 'stream_refresh';
+    if (isStreamRefresh) {
+      const streamId = message.stream?.id ?? null;
+      const stream = streamId ? this.#streams.get(streamId) : null;
+      const snapshot = stream && stream.botId === route.botId ? this.streamSnapshot(streamId) : null;
+      if (!snapshot) {
+        writeEmpty(response);
+        return;
+      }
+      stream.refreshes += 1;
+      stream.updatedAt = Date.now();
+      this.#replyEncrypted(route, envelope, response, {
+        msgtype: 'stream',
+        stream: snapshot,
+      });
+      return;
+    }
+    // WeCom retries an unanswered POST with the same MsgId; reply with the
+    // current stream snapshot (including the final frame) so a client that
+    // lost an earlier response can still settle on the finished content.
+    const retryStreamId = msgid ? this.#streamByMsgId.get(this.#msgKey(route.botId, msgid)) : null;
+    if (retryStreamId) {
+      const snapshot = this.streamSnapshot(retryStreamId);
+      if (snapshot) {
+        this.#replyEncrypted(route, envelope, response, { msgtype: 'stream', stream: snapshot });
+        return;
+      }
+      writeEmpty(response);
+      return;
+    }
+    if (message.msgtype === 'event') {
+      writeEmpty(response);
+      route.onInbound({ kind: 'event', message }).catch((error) => {
+        this.#logger.warn?.('[dsh-im:wecom-app] event handling failed:', error);
+      });
+      return;
+    }
+    let streamState = null;
+    let streamEnabled = false;
+    try {
+      streamEnabled = route.streamEnabled?.() === true;
+    } catch {
+      streamEnabled = false;
+    }
+    if (streamEnabled && msgid && (message.msgtype === 'text' || message.msgtype === 'image')) {
+      streamState = this.createStream({ botId: route.botId, msgid });
+      this.#replyEncrypted(route, envelope, response, {
+        msgtype: 'stream',
+        stream: {
+          id: streamState.streamId,
+          finish: false,
+          content: WECOM_APP_STREAM_PLACEHOLDER(),
+        },
+      });
+    } else {
+      writeEmpty(response);
+    }
+    route.onInbound({ kind: 'message', message, stream: streamState }).catch((error) => {
+      this.#logger.warn?.('[dsh-im:wecom-app] message handling failed:', error);
+      if (streamState) this.finishStream(streamState.streamId, { error: error?.message ?? String(error) });
+    });
+  }
+
+  #replyEncrypted(route, envelope, response, payload) {
+    let body;
+    try {
+      body = buildEncryptedReply({
+        format: envelope.format,
+        crypto: route.cryptoFor(),
+        plaintext: payload,
+        timestamp: envelope.timestamp,
+        nonce: envelope.nonce,
+      });
+    } catch (error) {
+      this.#logger.warn?.('[dsh-im:wecom-app] failed to encrypt the passive reply:', error);
+      writeEmpty(response);
+      return;
+    }
+    writeBody(response, 200, body, {
+      'content-type': envelope.format === 'json'
+        ? 'application/json; charset=utf-8'
+        : 'application/xml; charset=utf-8',
+    });
+  }
+
+  #pruneStreams() {
+    const cutoff = Date.now() - this.#streamTtlMs;
+    for (const [streamId, stream] of this.#streams.entries()) {
+      if (stream.updatedAt < cutoff) {
+        this.#streams.delete(streamId);
+        if (stream.msgid) this.#streamByMsgId.delete(this.#msgKey(stream.botId, stream.msgid));
+      }
+    }
+  }
+}

package/src/channels/wecom-app/config-store.mjs

@@ -0,0 +1,240 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+import { t } from '../shared/i18n.mjs';
+
+const EMPTY_DOCUMENT = Object.freeze({ version: 1, bots: Object.freeze([]) });
+
+function cleanString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function safeIntegrationId(value) {
+  const id = cleanString(value);
+  return id && /^wecomapp_[a-f0-9]{24}$/.test(id) ? id : null;
+}
+
+function safeRef(value, prefix) {
+  const ref = cleanString(value);
+  return ref && new RegExp('^' + prefix + '[A-F0-9]{24}$').test(ref) ? ref : null;
+}
+
+// A bot identity is stable per (corpId, agentId) pair so re-binding the same
+// application replaces its credentials in place instead of piling up bots.
+export function deriveWecomAppIdentity({ corpId, agentId }) {
+  const id = cleanString(corpId);
+  const agent = cleanString(agentId);
+  if (!id || !agent) throw new TypeError('Enterprise WeChat corpId and agentId are required');
+  const digest = createHash('sha256').update(`${id}:${agent}`).digest('hex').slice(0, 24);
+  return {
+    botId: `wecomapp_${digest}`,
+    secretRef: `DSH_WECOM_APP_SECRET_${digest.toUpperCase()}`,
+    callbackTokenRef: `DSH_WECOM_APP_TOKEN_${digest.toUpperCase()}`,
+    callbackKeyRef: `DSH_WECOM_APP_AESKEY_${digest.toUpperCase()}`,
+  };
+}
+
+export function generateCallbackSecret() {
+  return randomBytes(16).toString('hex');
+}
+
+export function maskCorpId(corpId) {
+  const value = cleanString(corpId) ?? '';
+  if (!value) return t('企业微信应用');
+  if (value.length <= 10) return `${value.slice(0, 3)}•••`;
+  return `${value.slice(0, 6)}••••${value.slice(-4)}`;
+}
+
+export function validCorpId(value) {
+  const id = cleanString(value);
+  return Boolean(id && /^[A-Za-z][A-Za-z0-9_-]{2,127}$/.test(id));
+}
+
+export function validAgentId(value) {
+  const agent = cleanString(value);
+  return Boolean(agent && /^\d{1,32}$/.test(agent) && Number(agent) > 0);
+}
+
+export function validApiBaseUrl(value) {
+  const raw = cleanString(value);
+  return raw === null || /^https?:\/\//iu.test(raw);
+}
+
+function normalizeBot(value) {
+  if (!value || typeof value !== 'object') return null;
+  const botId = safeIntegrationId(value.botId);
+  const corpId = cleanString(value.corpId);
+  const agentId = cleanString(value.agentId);
+  const secretRef = safeRef(value.secretRef, 'DSH_WECOM_APP_SECRET_');
+  const callbackTokenRef = safeRef(value.callbackTokenRef, 'DSH_WECOM_APP_TOKEN_');
+  const callbackKeyRef = safeRef(value.callbackKeyRef, 'DSH_WECOM_APP_AESKEY_');
+  const callbackSecret = cleanString(value.callbackSecret);
+  if (!botId || !corpId || !agentId || !secretRef || !callbackTokenRef || !callbackKeyRef) return null;
+  if (!validCorpId(corpId) || !validAgentId(agentId)) return null;
+  if (!callbackSecret || !/^[a-f0-9]{32}$/.test(callbackSecret)) return null;
+  if (!validApiBaseUrl(value.apiBaseUrl ?? undefined)) return null;
+  if (!validApiBaseUrl(value.callbackBaseUrl ?? undefined)) return null;
+  const derived = deriveWecomAppIdentity({ corpId, agentId });
+  if (derived.botId !== botId || derived.secretRef !== secretRef
+    || derived.callbackTokenRef !== callbackTokenRef || derived.callbackKeyRef !== callbackKeyRef) return null;
+  return Object.freeze({
+    botId,
+    corpId,
+    agentId,
+    secretRef,
+    callbackTokenRef,
+    callbackKeyRef,
+    callbackSecret,
+    apiBaseUrl: cleanString(value.apiBaseUrl) ?? undefined,
+    callbackBaseUrl: cleanString(value.callbackBaseUrl) ?? undefined,
+    streamEnabled: value.streamEnabled !== false,
+    createdAt: cleanString(value.createdAt) ?? new Date().toISOString(),
+    connectedAt: cleanString(value.connectedAt),
+  });
+}
+
+function normalizeDocument(value) {
+  if (!value || value.version !== 1 || !Array.isArray(value.bots)) return null;
+  const bots = value.bots.map(normalizeBot);
+  if (bots.some((bot) => bot === null)) return null;
+  const ids = new Set();
+  const corpAgents = new Set();
+  const secrets = new Set();
+  const callbackSecrets = new Set();
+  for (const bot of bots) {
+    const corpAgent = `${bot.corpId}:${bot.agentId}`;
+    if (ids.has(bot.botId) || corpAgents.has(corpAgent)
+      || secrets.has(bot.secretRef) || callbackSecrets.has(bot.callbackSecret)) return null;
+    ids.add(bot.botId);
+    corpAgents.add(corpAgent);
+    secrets.add(bot.secretRef);
+    callbackSecrets.add(bot.callbackSecret);
+  }
+  return Object.freeze({ version: 1, bots: Object.freeze(bots) });
+}
+
+export class WecomAppConfigStore {
+  #path;
+  #value = EMPTY_DOCUMENT;
+  #writeQueue = Promise.resolve();
+
+  constructor(path) {
+    this.#path = path;
+  }
+
+  async load() {
+    try {
+      const normalized = normalizeDocument(JSON.parse(await readFile(this.#path, 'utf8')));
+      if (!normalized) throw new Error('dsh-im Enterprise WeChat app config contains invalid bot data');
+      this.#value = normalized;
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+      this.#value = EMPTY_DOCUMENT;
+    }
+    return this;
+  }
+
+  list() {
+    return structuredClone(this.#value.bots);
+  }
+
+  get(botId) {
+    const bot = this.#value.bots.find((candidate) => candidate.botId === botId);
+    return bot ? structuredClone(bot) : null;
+  }
+
+  getByCorpAgent(corpId, agentId) {
+    const bot = this.#value.bots.find((candidate) => candidate.corpId === corpId && candidate.agentId === agentId);
+    return bot ? structuredClone(bot) : null;
+  }
+
+  async save(value) {
+    const normalized = normalizeBot(value);
+    if (!normalized) throw new Error('Refusing to persist incomplete Enterprise WeChat app bot data');
+    return this.#mutate((bots) => {
+      const corpAgent = `${normalized.corpId}:${normalized.agentId}`;
+      const collision = bots.find((bot) =>
+        (bot.botId === normalized.botId || `${bot.corpId}:${bot.agentId}` === corpAgent
+          || bot.secretRef === normalized.secretRef || bot.callbackSecret === normalized.callbackSecret)
+        && bot.botId !== normalized.botId);
+      if (collision) throw new Error('Duplicate Enterprise WeChat app bot identity');
+      const index = bots.findIndex((bot) => bot.botId === normalized.botId);
+      if (index === -1) bots.push(normalized);
+      else bots[index] = normalized;
+      return structuredClone(normalized);
+    });
+  }
+
+  async update(botId, patch = {}) {
+    const existing = this.get(botId);
+    if (!existing) throw new Error('Unknown Enterprise WeChat app bot');
+    const merged = { ...existing };
+    if (patch.apiBaseUrl !== undefined) {
+      merged.apiBaseUrl = cleanString(patch.apiBaseUrl) ?? null;
+      if (!validApiBaseUrl(merged.apiBaseUrl ?? undefined)) {
+        throw new Error('代理地址必须是 http(s) 地址');
+      }
+    }
+    if (patch.callbackBaseUrl !== undefined) {
+      merged.callbackBaseUrl = cleanString(patch.callbackBaseUrl) ?? null;
+      if (!validApiBaseUrl(merged.callbackBaseUrl ?? undefined)) {
+        throw new Error('回调基址必须是 http(s) 地址');
+      }
+    }
+    if (patch.streamEnabled !== undefined) merged.streamEnabled = patch.streamEnabled === true;
+    if (patch.callbackSecret !== undefined) {
+      const secret = cleanString(patch.callbackSecret);
+      if (!secret || !/^[a-f0-9]{32}$/.test(secret)) throw new Error('回调密钥格式不正确');
+      merged.callbackSecret = secret;
+    }
+    return this.save(merged);
+  }
+
+  async remove(botId) {
+    if (!safeIntegrationId(botId)) throw new TypeError('Invalid Enterprise WeChat app bot ID');
+    return this.#mutate((bots) => {
+      const index = bots.findIndex((candidate) => candidate.botId === botId);
+      if (index === -1) return null;
+      const [removed] = bots.splice(index, 1);
+      return structuredClone(removed);
+    });
+  }
+
+  async clear() {
+    const operation = this.#writeQueue.then(async () => {
+      try {
+        await unlink(this.#path);
+      } catch (error) {
+        if (error?.code !== 'ENOENT') throw error;
+      }
+      this.#value = EMPTY_DOCUMENT;
+    });
+    this.#writeQueue = operation.then(() => undefined, () => undefined);
+    await operation;
+  }
+
+  async #mutate(mutator) {
+    let result;
+    const operation = this.#writeQueue.then(async () => {
+      const bots = [...this.#value.bots];
+      result = mutator(bots);
+      const document = Object.freeze({ version: 1, bots: Object.freeze(bots) });
+      await this.#write(document);
+      this.#value = document;
+    });
+    this.#writeQueue = operation.then(() => undefined, () => undefined);
+    await operation;
+    return result;
+  }
+
+  async #write(document) {
+    await mkdir(dirname(this.#path), { recursive: true, mode: 0o700 });
+    const temporary = `${this.#path}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(document, null, 2)}\n`, {
+      encoding: 'utf8',
+      mode: 0o600,
+    });
+    await rename(temporary, this.#path);
+  }
+}