@xmanrui/dsh-im 0.1.0

package/src/channels/feishu/plugin-config-store.mjs

@@ -0,0 +1,204 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+export const LEGACY_FEISHU_SECRET_REF = 'DSH_FEISHU_APP_SECRET';
+
+function cleanString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function safeId(value) {
+  const id = cleanString(value);
+  return id && /^[A-Za-z0-9_-]{1,128}$/.test(id) ? id : null;
+}
+
+function legacyBotId(appId) {
+  return `bot_${createHash('sha256').update(appId).digest('hex').slice(0, 24)}`;
+}
+
+function normalizeOwners(value) {
+  const candidates = Array.isArray(value.ownerOpenIds)
+    ? value.ownerOpenIds
+    : [value.ownerOpenId];
+  return [...new Set(candidates.map(cleanString).filter(Boolean))];
+}
+
+function normalizeBot(value, { legacy = false } = {}) {
+  if (!value || typeof value !== 'object') return null;
+  const appId = cleanString(value.appId);
+  const ownerOpenIds = normalizeOwners(value);
+  if (!appId || ownerOpenIds.length === 0) return null;
+  const id = safeId(value.id) ?? (legacy ? legacyBotId(appId) : null);
+  const secretRef = cleanString(value.secretRef) ?? (legacy ? LEGACY_FEISHU_SECRET_REF : null);
+  if (!id || !secretRef) return null;
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(secretRef)) return null;
+  const domain = value.domain === 'lark' ? 'lark' : 'feishu';
+  return Object.freeze({
+    id,
+    appId,
+    secretRef,
+    ownerOpenIds: Object.freeze(ownerOpenIds),
+    domain,
+    botName: cleanString(value.botName),
+    botOpenId: cleanString(value.botOpenId),
+    activated: value.activated ?? null,
+    deletionPending: value.deletionPending === true,
+    connectedAt: cleanString(value.connectedAt),
+    createdAt: cleanString(value.createdAt) ?? cleanString(value.connectedAt),
+  });
+}
+
+function normalizeDocument(value) {
+  if (!value || typeof value !== 'object') return null;
+  if (value.version === 2 && Array.isArray(value.bots)) {
+    const bots = value.bots.map((bot) => normalizeBot(bot));
+    if (bots.some((bot) => bot === null)) {
+      throw new Error('dsh-feishu config contains an invalid bot entry');
+    }
+    const ids = new Set();
+    const refs = new Set();
+    const appIds = new Set();
+    for (const bot of bots) {
+      if (ids.has(bot.id) || refs.has(bot.secretRef) || appIds.has(bot.appId)) {
+        throw new Error('dsh-feishu config contains duplicate bot identities');
+      }
+      ids.add(bot.id);
+      refs.add(bot.secretRef);
+      appIds.add(bot.appId);
+    }
+    return { value: Object.freeze({ version: 2, bots: Object.freeze(bots) }), migrated: false };
+  }
+
+  // Version 1 was a single non-secret bot object. Preserve its existing
+  // credential reference so an environment-backed secret remains usable.
+  const legacyBot = normalizeBot(value, { legacy: true });
+  if (!legacyBot) return null;
+  return {
+    value: Object.freeze({ version: 2, bots: Object.freeze([legacyBot]) }),
+    migrated: true,
+  };
+}
+
+/** Stores only non-secret onboarding facts for all Feishu bots. */
+export class PluginConfigStore {
+  #path;
+  #value = Object.freeze({ version: 2, bots: Object.freeze([]) });
+  #writeQueue = Promise.resolve();
+
+  constructor(path) {
+    this.#path = path;
+  }
+
+  async load() {
+    try {
+      const parsed = JSON.parse(await readFile(this.#path, 'utf8'));
+      const normalized = normalizeDocument(parsed);
+      if (!normalized) throw new Error('dsh-feishu config is incomplete or invalid');
+      this.#value = normalized.value;
+      if (normalized.migrated) await this.#writeDocument(this.#value);
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+      this.#value = Object.freeze({ version: 2, bots: Object.freeze([]) });
+    }
+    return this;
+  }
+
+  /** Backward-compatible single-bot view used by the original controller. */
+  get() {
+    const bot = this.#value.bots[0];
+    if (!bot) return null;
+    const result = structuredClone(bot);
+    result.ownerOpenId = result.ownerOpenIds[0];
+    return result;
+  }
+
+  list() {
+    return structuredClone(this.#value.bots);
+  }
+
+  getBot(id) {
+    const bot = this.#value.bots.find((candidate) => candidate.id === id);
+    return bot ? structuredClone(bot) : null;
+  }
+
+  /** Backward-compatible save replaces the original single-bot view. */
+  async save(value) {
+    const fallback = { ...value };
+    if (!fallback.id) fallback.id = legacyBotId(cleanString(fallback.appId) ?? 'invalid');
+    if (!fallback.secretRef) fallback.secretRef = LEGACY_FEISHU_SECRET_REF;
+    const normalized = normalizeBot(fallback);
+    if (!normalized) throw new Error('Refusing to persist incomplete dsh-feishu configuration');
+    await this.#replaceBots([normalized]);
+    return this.get();
+  }
+
+  async saveBot(value) {
+    const normalized = normalizeBot(value);
+    if (!normalized) throw new Error('Refusing to persist incomplete dsh-feishu bot configuration');
+    return this.#mutate((bots) => {
+      const collision = bots.find((bot) => bot.secretRef === normalized.secretRef && bot.id !== normalized.id);
+      if (collision) throw new Error('Refusing to share a credential reference between Feishu bots');
+      const appCollision = bots.find((bot) => bot.appId === normalized.appId && bot.id !== normalized.id);
+      if (appCollision) throw new Error('Refusing to persist the same Feishu app twice');
+      const index = bots.findIndex((bot) => bot.id === normalized.id);
+      if (index === -1) bots.push(normalized);
+      else bots[index] = normalized;
+      return structuredClone(normalized);
+    });
+  }
+
+  async removeBot(id) {
+    if (!safeId(id)) throw new TypeError('Invalid Feishu bot id');
+    return this.#mutate((bots) => {
+      const index = bots.findIndex((bot) => bot.id === id);
+      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 = Object.freeze({ version: 2, bots: Object.freeze([]) });
+    });
+    this.#writeQueue = operation.then(() => undefined, () => undefined);
+    await operation;
+  }
+
+  async #replaceBots(bots) {
+    const document = Object.freeze({ version: 2, bots: Object.freeze([...bots]) });
+    const operation = this.#writeQueue.then(async () => {
+      await this.#writeDocument(document);
+      this.#value = 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: 2, bots: Object.freeze(bots) });
+      await this.#writeDocument(document);
+      this.#value = document;
+    });
+    this.#writeQueue = operation.then(() => undefined, () => undefined);
+    await operation;
+    return result;
+  }
+
+  async #writeDocument(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);
+  }
+}

package/src/channels/feishu/plugin-controller.mjs

@@ -0,0 +1,248 @@
+import { RegistrationManager } from './registration-manager.mjs';
+
+export const FEISHU_SECRET_REF = 'DSH_FEISHU_APP_SECRET';
+
+export const REQUIRED_TENANT_SCOPES = Object.freeze([
+  'im:message.p2p_msg:readonly',
+  'im:message.group_at_msg:readonly',
+  'im:message:send_as_bot',
+  'im:message.reactions:write_only',
+  'im:message:recall',
+  'cardkit:card:write',
+]);
+
+function safeConnectionStatus(runtime) {
+  if (!runtime) return {
+    ready: false,
+    feishuLongConnectionState: 'idle',
+    harnessReachable: false,
+  };
+  return runtime.status;
+}
+
+function publicBot(config) {
+  if (!config) return null;
+  const appIdMasked = config.appId.length > 12
+    ? `${config.appId.slice(0, 8)}••••${config.appId.slice(-4)}`
+    : 'cli_••••';
+  return {
+    name: config.botName,
+    appIdMasked,
+    openId: config.botOpenId,
+    activated: config.activated,
+    domain: config.domain,
+  };
+}
+
+/** Coordinates QR provisioning, durable credentials and the live chat runtime. */
+export class DshFeishuController {
+  #registerApp;
+  #verifyApp;
+  #credentials;
+  #configStore;
+  #createRuntime;
+  #registration;
+  #runtime = null;
+  #lastError = null;
+  #transition = Promise.resolve();
+
+  constructor({ registerApp, verifyApp, credentials, configStore, createRuntime }) {
+    if (typeof registerApp !== 'function') throw new Error('registerApp is required');
+    if (typeof verifyApp !== 'function') throw new Error('verifyApp is required');
+    if (!credentials) throw new Error('credentials service is required');
+    if (!configStore) throw new Error('config store is required');
+    if (typeof createRuntime !== 'function') throw new Error('createRuntime is required');
+
+    this.#registerApp = registerApp;
+    this.#verifyApp = verifyApp;
+    this.#credentials = credentials;
+    this.#configStore = configStore;
+    this.#createRuntime = createRuntime;
+    this.#registration = new RegistrationManager({
+      registerApp: this.#registerApp,
+      onCredentials: (result) => this.#serialize(() => this.#acceptCredentials(result)),
+    });
+  }
+
+  async initialize() {
+    const config = this.#configStore.get();
+    if (!config) return this.status();
+    return this.#serialize(async () => {
+      const resolved = await this.#credentials.resolve(FEISHU_SECRET_REF);
+      if (!resolved?.value) {
+        this.#lastError = {
+          code: 'missing_credentials',
+          message: '机器人凭据缺失，请重新扫码接入。',
+        };
+        return this.status();
+      }
+      try {
+        await this.#startRuntime(config, resolved.value);
+        this.#lastError = null;
+      } catch {
+        this.#lastError = {
+          code: 'connection_failed',
+          message: '机器人暂时无法连接飞书，请重试。',
+        };
+      }
+      return this.status();
+    });
+  }
+
+  startRegistration() {
+    this.#lastError = null;
+    this.#registration.start({
+      source: 'deepseek-harness',
+      createOnly: true,
+      appPreset: {
+        name: '{user} 的北汇星河 AI 助手',
+        desc: '连接飞书与 DeepSeek Harness，在聊天中使用企业 AI 助手。',
+      },
+      addons: {
+        preset: false,
+        scopes: { tenant: [...REQUIRED_TENANT_SCOPES] },
+        events: { items: { tenant: ['im.message.receive_v1'] } },
+      },
+    });
+    return this.status();
+  }
+
+  cancelRegistration() {
+    this.#registration.cancel();
+    return this.status();
+  }
+
+  async reconnect() {
+    return this.#serialize(async () => {
+      const config = this.#configStore.get();
+      const resolved = await this.#credentials.resolve(FEISHU_SECRET_REF);
+      if (!config || !resolved?.value) {
+        this.#lastError = {
+          code: 'missing_credentials',
+          message: '没有可用的机器人凭据，请重新扫码接入。',
+        };
+        return this.status();
+      }
+      try {
+        await this.#startRuntime(config, resolved.value);
+        this.#lastError = null;
+      } catch {
+        this.#lastError = {
+          code: 'connection_failed',
+          message: '机器人暂时无法连接飞书，请重试。',
+        };
+      }
+      return this.status();
+    });
+  }
+
+  async disconnect() {
+    this.#registration.cancel();
+    return this.#serialize(async () => {
+      await this.#stopRuntime();
+      await this.#configStore.clear();
+      try {
+        await this.#credentials.unset(FEISHU_SECRET_REF);
+      } catch {
+        // A read-only environment value may shadow the managed store. Clearing
+        // the non-secret config still prevents automatic reuse of that value.
+      }
+      this.#lastError = null;
+      return this.status();
+    });
+  }
+
+  async close() {
+    this.#registration.cancel();
+    await this.#serialize(() => this.#stopRuntime());
+  }
+
+  status() {
+    const config = this.#configStore.get();
+    const registration = this.#registration.status();
+    const connection = safeConnectionStatus(this.#runtime);
+    const connected = connection.ready === true
+      && connection.feishuLongConnectionState === 'connected'
+      && connection.harnessReachable === true;
+
+    let phase = 'unconfigured';
+    if (connected) phase = 'connected';
+    else if (['starting', 'qr_ready', 'polling', 'slow_down', 'domain_switched'].includes(registration.state)) {
+      phase = 'registering';
+    } else if (registration.state === 'saving') phase = 'connecting';
+    else if (this.#lastError || registration.state === 'error') phase = 'error';
+    else if (config) phase = 'disconnected';
+
+    return {
+      phase,
+      connected,
+      configured: Boolean(config),
+      bot: publicBot(config),
+      registration,
+      connection,
+      error: this.#lastError ?? registration.error ?? null,
+    };
+  }
+
+  async #acceptCredentials(result) {
+    const appId = result.client_id;
+    const appSecret = result.client_secret;
+    const ownerOpenId = result.user_info?.open_id;
+    const domain = result.user_info?.tenant_brand === 'lark' ? 'lark' : 'feishu';
+    if (!ownerOpenId) throw new Error('Feishu registration returned no owner open_id');
+
+    const bot = await this.#verifyApp({ appId, appSecret, domain });
+    await this.#credentials.set(FEISHU_SECRET_REF, appSecret);
+    let config;
+    try {
+      config = await this.#configStore.save({
+        appId,
+        ownerOpenId,
+        domain,
+        botName: bot.name,
+        botOpenId: bot.openId,
+        activated: bot.activated,
+        connectedAt: new Date().toISOString(),
+      });
+    } catch (error) {
+      await this.#credentials.unset(FEISHU_SECRET_REF).catch(() => undefined);
+      throw error;
+    }
+
+    try {
+      await this.#startRuntime(config, appSecret);
+      this.#lastError = null;
+    } catch (error) {
+      this.#lastError = {
+        code: 'connection_failed',
+        message: '机器人已经创建，但长连接未就绪，请点击重试。',
+      };
+      throw error;
+    }
+  }
+
+  async #startRuntime(config, appSecret) {
+    await this.#stopRuntime();
+    const runtime = await this.#createRuntime({ config, appSecret });
+    this.#runtime = runtime;
+    try {
+      await runtime.start();
+    } catch (error) {
+      if (this.#runtime === runtime) this.#runtime = null;
+      await runtime.stop({ preserveError: true }).catch(() => undefined);
+      throw error;
+    }
+  }
+
+  async #stopRuntime() {
+    const runtime = this.#runtime;
+    this.#runtime = null;
+    if (runtime) await runtime.stop();
+  }
+
+  #serialize(operation) {
+    const result = this.#transition.then(operation, operation);
+    this.#transition = result.then(() => undefined, () => undefined);
+    return result;
+  }
+}