@xmanrui/dsh-im 0.1.0

package/src/channels/feishu/registration-manager.mjs

@@ -0,0 +1,345 @@
+const ACTIVE_STATES = new Set([
+  'starting',
+  'qr_ready',
+  'polling',
+  'slow_down',
+  'domain_switched',
+  'saving',
+]);
+
+const SDK_POLLING_STATES = new Set([
+  'polling',
+  'slow_down',
+  'domain_switched',
+]);
+
+export const REGISTRATION_STATES = Object.freeze({
+  IDLE: 'idle',
+  STARTING: 'starting',
+  QR_READY: 'qr_ready',
+  POLLING: 'polling',
+  SLOW_DOWN: 'slow_down',
+  DOMAIN_SWITCHED: 'domain_switched',
+  SAVING: 'saving',
+  SUCCEEDED: 'succeeded',
+  EXPIRED: 'expired',
+  CANCELLED: 'cancelled',
+  ERROR: 'error',
+});
+
+function errorCode(error) {
+  if (['access_denied', 'expired_token', 'abort'].includes(error?.code)) return error.code;
+  return 'registration_failed';
+}
+
+function publicError(error) {
+  const code = errorCode(error);
+  const messages = {
+    access_denied: 'Registration was denied.',
+    abort: 'Registration was cancelled.',
+    expired_token: 'The registration QR code expired.',
+  };
+
+  // SDK/network errors are deliberately not copied verbatim. Besides keeping
+  // the API stable, this prevents a downstream error from reflecting a secret
+  // into a status response.
+  return {
+    code,
+    message: messages[code] ?? 'Unable to register the Feishu app.',
+  };
+}
+
+function expirySeconds(value) {
+  const seconds = Number(value);
+  if (!Number.isFinite(seconds) || seconds <= 0) {
+    throw new TypeError('registerApp onQRCodeReady returned an invalid expireIn');
+  }
+  return seconds;
+}
+
+function copyUserInfo(userInfo) {
+  if (userInfo === undefined) return undefined;
+  if (userInfo === null || typeof userInfo !== 'object' || Array.isArray(userInfo)) {
+    throw new TypeError('registerApp returned invalid user_info');
+  }
+  return { ...userInfo };
+}
+
+/**
+ * Owns one Feishu device-registration attempt at a time.
+ *
+ * `start()` intentionally does not await the long-running SDK poll. Consumers
+ * start an attempt and then poll `status()` until it reaches a terminal state.
+ * The App Secret never becomes manager state and is only handed to the injected
+ * `onCredentials` callback.
+ */
+export class RegistrationManager {
+  #registerApp;
+  #onCredentials;
+  #now;
+  #setTimeout;
+  #clearTimeout;
+  #attempt = 0;
+  #active = null;
+  #snapshot;
+
+  constructor({
+    registerApp,
+    onCredentials,
+    now = Date.now,
+    setTimeout: setTimeoutFn = globalThis.setTimeout,
+    clearTimeout: clearTimeoutFn = globalThis.clearTimeout,
+  } = {}) {
+    if (typeof registerApp !== 'function') {
+      throw new TypeError('RegistrationManager requires a registerApp function');
+    }
+    if (typeof onCredentials !== 'function') {
+      throw new TypeError('RegistrationManager requires an onCredentials function');
+    }
+    if (typeof now !== 'function' || typeof setTimeoutFn !== 'function' || typeof clearTimeoutFn !== 'function') {
+      throw new TypeError('RegistrationManager clock dependencies must be functions');
+    }
+
+    this.#registerApp = registerApp;
+    this.#onCredentials = onCredentials;
+    this.#now = now;
+    this.#setTimeout = setTimeoutFn;
+    this.#clearTimeout = clearTimeoutFn;
+    this.#snapshot = this.#makeSnapshot(null, REGISTRATION_STATES.IDLE);
+  }
+
+  start(registerOptions = {}) {
+    if (registerOptions === null || typeof registerOptions !== 'object' || Array.isArray(registerOptions)) {
+      throw new TypeError('Registration options must be an object');
+    }
+
+    this.#supersedeActiveAttempt();
+
+    const run = {
+      id: ++this.#attempt,
+      controller: new AbortController(),
+      qrCodeUrl: null,
+      expiresAt: null,
+      pollIntervalSeconds: null,
+      expiryTimer: null,
+    };
+    this.#active = run;
+    this.#snapshot = this.#makeSnapshot(run, REGISTRATION_STATES.STARTING);
+
+    const options = {
+      ...registerOptions,
+      signal: run.controller.signal,
+      onQRCodeReady: (info) => this.#onQRCodeReady(run, info),
+      onStatusChange: (info) => this.#onStatusChange(run, info),
+    };
+
+    // Put the SDK invocation on a microtask so a synchronous throw and a
+    // Promise rejection follow the same path without making start() blocking.
+    const registration = Promise.resolve().then(() => this.#registerApp(options));
+    void registration.then(
+      (result) => this.#onRegistrationSucceeded(run, result),
+      (error) => this.#onRegistrationFailed(run, error),
+    );
+
+    return this.status();
+  }
+
+  status() {
+    this.#expireIfNeeded();
+
+    const snapshot = { ...this.#snapshot };
+    if (snapshot.error) snapshot.error = { ...snapshot.error };
+
+    const run = this.#active;
+    if (run && run.expiresAt !== null && ACTIVE_STATES.has(snapshot.state)) {
+      snapshot.remainingSeconds = Math.max(0, Math.ceil((run.expiresAt - this.#now()) / 1000));
+    }
+    return snapshot;
+  }
+
+  cancel() {
+    const run = this.#active;
+    if (!run) return this.status();
+
+    this.#finishRun(run, REGISTRATION_STATES.CANCELLED, {
+      error: {
+        code: 'abort',
+        message: 'Registration was cancelled.',
+      },
+    });
+    run.controller.abort();
+    return this.status();
+  }
+
+  #isCurrent(run) {
+    return this.#active === run;
+  }
+
+  #makeSnapshot(run, state, extra = {}) {
+    const snapshot = {
+      state,
+      attempt: run?.id ?? this.#attempt,
+      updatedAt: this.#now(),
+      ...extra,
+    };
+
+    if (run?.qrCodeUrl && ACTIVE_STATES.has(state)) {
+      snapshot.qrCodeUrl = run.qrCodeUrl;
+      snapshot.expiresAt = run.expiresAt;
+    }
+    if (run?.pollIntervalSeconds !== null && ACTIVE_STATES.has(state)) {
+      snapshot.pollIntervalSeconds = run.pollIntervalSeconds;
+    }
+    return snapshot;
+  }
+
+  #setRunState(run, state, extra = {}) {
+    if (!this.#isCurrent(run)) return;
+    this.#snapshot = this.#makeSnapshot(run, state, extra);
+  }
+
+  #onQRCodeReady(run, info) {
+    if (!this.#isCurrent(run)) return;
+    if (typeof info?.url !== 'string' || !info.url) {
+      throw new TypeError('registerApp onQRCodeReady returned an invalid URL');
+    }
+
+    const seconds = expirySeconds(info.expireIn);
+    run.qrCodeUrl = info.url;
+    run.expiresAt = this.#now() + (seconds * 1000);
+    this.#clearExpiryTimer(run);
+    run.expiryTimer = this.#setTimeout(() => this.#expireRun(run), seconds * 1000);
+    run.expiryTimer?.unref?.();
+    this.#setRunState(run, REGISTRATION_STATES.QR_READY);
+  }
+
+  #onStatusChange(run, info) {
+    if (!this.#isCurrent(run) || !SDK_POLLING_STATES.has(info?.status)) return;
+    if (info.status === REGISTRATION_STATES.SLOW_DOWN && Number.isFinite(Number(info.interval))) {
+      run.pollIntervalSeconds = Number(info.interval);
+    }
+    this.#setRunState(run, info.status);
+  }
+
+  async #onRegistrationSucceeded(run, result) {
+    if (!this.#isCurrent(run)) return;
+
+    const clientId = result?.client_id;
+    const clientSecret = result?.client_secret;
+    if (typeof clientId !== 'string' || !clientId || typeof clientSecret !== 'string' || !clientSecret) {
+      this.#finishRun(run, REGISTRATION_STATES.ERROR, {
+        error: {
+          code: 'invalid_credentials',
+          message: 'Feishu registration returned invalid credentials.',
+        },
+      });
+      return;
+    }
+
+    let userInfo;
+    try {
+      userInfo = copyUserInfo(result.user_info);
+    } catch {
+      this.#finishRun(run, REGISTRATION_STATES.ERROR, {
+        error: {
+          code: 'invalid_credentials',
+          message: 'Feishu registration returned invalid credentials.',
+        },
+      });
+      return;
+    }
+
+    // Once the SDK has returned credentials, QR expiry no longer applies.
+    // Remove the device URL before awaiting persistence so it also disappears
+    // from the public `saving` status.
+    this.#clearExpiryTimer(run);
+    run.qrCodeUrl = null;
+    run.expiresAt = null;
+    run.pollIntervalSeconds = null;
+    this.#setRunState(run, REGISTRATION_STATES.SAVING);
+    try {
+      await this.#onCredentials({
+        client_id: clientId,
+        client_secret: clientSecret,
+        user_info: userInfo,
+      });
+    } catch {
+      if (this.#isCurrent(run)) {
+        this.#finishRun(run, REGISTRATION_STATES.ERROR, {
+          error: {
+            code: 'credentials_callback_failed',
+            message: 'Unable to store the Feishu credentials.',
+          },
+        });
+      }
+      return;
+    }
+
+    if (this.#isCurrent(run)) {
+      this.#finishRun(run, REGISTRATION_STATES.SUCCEEDED);
+    }
+  }
+
+  #onRegistrationFailed(run, error) {
+    if (!this.#isCurrent(run)) return;
+
+    const code = errorCode(error);
+    if (code === 'expired_token') {
+      this.#finishRun(run, REGISTRATION_STATES.EXPIRED, {
+        error: publicError(error),
+      });
+      return;
+    }
+    if (code === 'abort') {
+      this.#finishRun(run, REGISTRATION_STATES.CANCELLED, {
+        error: publicError(error),
+      });
+      return;
+    }
+    this.#finishRun(run, REGISTRATION_STATES.ERROR, {
+      error: publicError(error),
+    });
+  }
+
+  #expireIfNeeded() {
+    const run = this.#active;
+    if (run && run.expiresAt !== null && this.#now() >= run.expiresAt) {
+      this.#expireRun(run);
+    }
+  }
+
+  #expireRun(run) {
+    if (!this.#isCurrent(run)) return;
+    this.#finishRun(run, REGISTRATION_STATES.EXPIRED, {
+      error: {
+        code: 'expired_token',
+        message: 'The registration QR code expired.',
+      },
+    });
+    run.controller.abort();
+  }
+
+  #finishRun(run, state, extra = {}) {
+    if (!this.#isCurrent(run)) return;
+    this.#clearExpiryTimer(run);
+    this.#snapshot = this.#makeSnapshot(run, state, extra);
+    this.#active = null;
+  }
+
+  #clearExpiryTimer(run) {
+    if (run.expiryTimer !== null) {
+      this.#clearTimeout(run.expiryTimer);
+      run.expiryTimer = null;
+    }
+  }
+
+  #supersedeActiveAttempt() {
+    const previous = this.#active;
+    if (!previous) return;
+    this.#clearExpiryTimer(previous);
+    this.#active = null;
+    previous.controller.abort();
+  }
+}
+
+export default RegistrationManager;

package/src/channels/feishu/state-store.mjs

@@ -0,0 +1,71 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+const EMPTY_STATE = Object.freeze({ version: 1, sessions: {}, seenMessageIds: [] });
+
+export class StateStore {
+  #path;
+  #state = structuredClone(EMPTY_STATE);
+  #writeQueue = Promise.resolve();
+
+  constructor(path) {
+    this.#path = path;
+  }
+
+  async load() {
+    try {
+      const parsed = JSON.parse(await readFile(this.#path, 'utf8'));
+      this.#state = {
+        version: 1,
+        sessions: parsed.sessions && typeof parsed.sessions === 'object' ? parsed.sessions : {},
+        seenMessageIds: Array.isArray(parsed.seenMessageIds) ? parsed.seenMessageIds.slice(-1000) : [],
+      };
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+      await this.#persist();
+    }
+    return this;
+  }
+
+  sessionFor(key) {
+    return this.#state.sessions[key] ?? null;
+  }
+
+  async setSession(key, sessionId) {
+    this.#state.sessions[key] = sessionId;
+    await this.#persist();
+  }
+
+  async clearSession(key) {
+    delete this.#state.sessions[key];
+    await this.#persist();
+  }
+
+  hasSeen(messageId) {
+    return this.#state.seenMessageIds.includes(messageId);
+  }
+
+  async markSeen(messageId) {
+    if (this.hasSeen(messageId)) return;
+    this.#state.seenMessageIds.push(messageId);
+    if (this.#state.seenMessageIds.length > 1000) {
+      this.#state.seenMessageIds.splice(0, this.#state.seenMessageIds.length - 1000);
+    }
+    await this.#persist();
+  }
+
+  snapshot() {
+    return structuredClone(this.#state);
+  }
+
+  async #persist() {
+    const snapshot = JSON.stringify(this.#state, null, 2) + '\n';
+    this.#writeQueue = this.#writeQueue.then(async () => {
+      await mkdir(dirname(this.#path), { recursive: true, mode: 0o700 });
+      const temporary = `${this.#path}.tmp`;
+      await writeFile(temporary, snapshot, { encoding: 'utf8', mode: 0o600 });
+      await rename(temporary, this.#path);
+    });
+    await this.#writeQueue;
+  }
+}

package/src/channels/qq/config-store.mjs

@@ -0,0 +1,171 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+const EMPTY_DOCUMENT = Object.freeze({ version: 1, bots: Object.freeze([]) });
+
+function cleanString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function safeBotId(value) {
+  const id = cleanString(value);
+  return id && /^qq_[a-f0-9]{24}$/.test(id) ? id : null;
+}
+
+function safeSecretRef(value) {
+  const ref = cleanString(value);
+  return ref && /^DSH_QQBOT_APP_SECRET_[A-F0-9]{24}$/.test(ref) ? ref : null;
+}
+
+export function deriveQqBotIdentity(appId) {
+  const raw = cleanString(appId);
+  if (!raw) throw new TypeError('appId is required');
+  const digest = createHash('sha256').update(raw).digest('hex').slice(0, 24);
+  return {
+    botId: `qq_${digest}`,
+    secretRef: `DSH_QQBOT_APP_SECRET_${digest.toUpperCase()}`,
+  };
+}
+
+export function maskQqAppId(appId) {
+  const value = cleanString(appId) ?? '';
+  if (value.length <= 10) return value ? `${value.slice(0, 3)}•••` : 'QQ机器人';
+  return `${value.slice(0, 6)}••••${value.slice(-4)}`;
+}
+
+function normalizeBot(value) {
+  if (!value || typeof value !== 'object') return null;
+  const appId = cleanString(value.appId);
+  const ownerUserOpenid = cleanString(value.ownerUserOpenid);
+  const botId = safeBotId(value.botId);
+  const secretRef = safeSecretRef(value.secretRef);
+  if (!appId || !ownerUserOpenid || !botId || !secretRef) return null;
+  const derived = deriveQqBotIdentity(appId);
+  if (derived.botId !== botId || derived.secretRef !== secretRef) return null;
+  return Object.freeze({
+    botId,
+    appId,
+    secretRef,
+    ownerUserOpenid,
+    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 appIds = new Set();
+  const refs = new Set();
+  for (const bot of bots) {
+    if (ids.has(bot.botId) || appIds.has(bot.appId) || refs.has(bot.secretRef)) return null;
+    ids.add(bot.botId);
+    appIds.add(bot.appId);
+    refs.add(bot.secretRef);
+  }
+  return Object.freeze({ version: 1, bots: Object.freeze(bots) });
+}
+
+export class QqConfigStore {
+  #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 QQ 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;
+  }
+
+  getByAppId(appId) {
+    const bot = this.#value.bots.find((candidate) => candidate.appId === appId);
+    return bot ? structuredClone(bot) : null;
+  }
+
+  async save(value) {
+    const normalized = normalizeBot(value);
+    if (!normalized) throw new Error('Refusing to persist incomplete QQ bot data');
+    return this.#mutate((bots) => {
+      const appCollision = bots.find(
+        (bot) => bot.appId === normalized.appId && bot.botId !== normalized.botId,
+      );
+      const refCollision = bots.find(
+        (bot) => bot.secretRef === normalized.secretRef && bot.botId !== normalized.botId,
+      );
+      if (appCollision || refCollision) throw new Error('Duplicate QQ 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 remove(botId) {
+    if (!safeBotId(botId)) throw new TypeError('Invalid QQ bot id');
+    return this.#mutate((bots) => {
+      const index = bots.findIndex((bot) => bot.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);
+  }
+}

package/src/channels/qq/harness-client.mjs

@@ -0,0 +1,3 @@
+import { HarnessClient } from '../weixin/harness-client.mjs';
+
+export class QqHarnessClient extends HarnessClient {}