@xmanrui/dsh-im 0.1.0

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

@@ -0,0 +1,282 @@
+import { createHash, randomUUID } 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([]) });
+const STORED_BOT_KEYS = new Set(['clientId', 'secretRef', 'approvedSenders']);
+
+function cleanString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function digest(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function safeBotId(value) {
+  const id = cleanString(value);
+  return id && /^dt_[a-f0-9]{24}$/.test(id) ? id : null;
+}
+
+function safeSecretRef(value) {
+  const ref = cleanString(value);
+  return ref && /^DSH_DINGTALK_BOT_SECRET_[A-F0-9]{24}$/.test(ref) ? ref : null;
+}
+
+function safeSenderKey(value) {
+  const key = cleanString(value);
+  return key && /^dt_sender_[a-f0-9]{32}$/.test(key) ? key : null;
+}
+
+function normalizeApprovedSender(value) {
+  const record = typeof value === 'string' ? { staffId: value } : value;
+  if (!record || typeof record !== 'object' || Array.isArray(record)) return null;
+  const senderKey = safeSenderKey(record.senderKey);
+  const staffId = cleanString(record.staffId);
+  if (!senderKey || !staffId) return null;
+  return Object.freeze({
+    senderKey,
+    staffId,
+    displayName: cleanString(record.displayName),
+    approvedAt: cleanString(record.approvedAt),
+  });
+}
+
+function normalizeApprovedSenders(value) {
+  if (!Array.isArray(value)) return null;
+  const senders = value.map(normalizeApprovedSender);
+  if (senders.some((sender) => sender === null)) return null;
+  const ids = new Set();
+  const keys = new Set();
+  for (const sender of senders) {
+    if (ids.has(sender.staffId) || keys.has(sender.senderKey)) return null;
+    ids.add(sender.staffId);
+    keys.add(sender.senderKey);
+  }
+  return Object.freeze(senders);
+}
+
+/**
+ * Derives stable non-secret identifiers for a DingTalk bot credential.
+ * @param {string} clientId DingTalk application client ID.
+ * @returns {{botId: string, secretRef: string}} Derived identifiers.
+ */
+export function deriveDingtalkBotIdentity(clientId) {
+  const value = cleanString(clientId);
+  if (!value) throw new TypeError('clientId is required');
+  const valueDigest = digest(value).slice(0, 24);
+  return Object.freeze({
+    botId: `dt_${valueDigest}`,
+    secretRef: `DSH_DINGTALK_BOT_SECRET_${valueDigest.toUpperCase()}`,
+  });
+}
+
+/**
+ * Creates a random browser-safe key for an approved DingTalk sender.
+ * @returns {string} Opaque sender key.
+ */
+export function deriveDingtalkSenderKey() {
+  return `dt_sender_${randomUUID().replaceAll('-', '')}`;
+}
+
+/**
+ * Redacts a DingTalk sender ID for display.
+ * @param {string} staffId DingTalk staff ID.
+ * @returns {string} Partially redacted identifier.
+ */
+export function maskDingtalkSenderId(staffId) {
+  const value = cleanString(staffId);
+  if (!value) return '钉钉用户';
+  return '身份已隐藏';
+}
+
+/**
+ * Redacts a DingTalk client ID for display.
+ * @param {string} clientId DingTalk application client ID.
+ * @returns {string} Partially redacted client ID.
+ */
+export function maskDingtalkClientId(clientId) {
+  const value = cleanString(clientId);
+  if (!value) return '钉钉机器人';
+  if (value.length <= 8) return `${value.slice(0, 2)}••••`;
+  return `${value.slice(0, 4)}••••${value.slice(-4)}`;
+}
+
+function normalizeBot(value, { stored = false } = {}) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  if ('clientSecret' in value || 'client_secret' in value || 'deviceCode' in value) return null;
+  if (stored && Object.keys(value).some((key) => !STORED_BOT_KEYS.has(key))) return null;
+  const clientId = cleanString(value.clientId);
+  const secretRef = safeSecretRef(value.secretRef);
+  const approvedSenders = normalizeApprovedSenders(value.approvedSenders ?? []);
+  if (!clientId || !secretRef || !approvedSenders) return null;
+  const identity = deriveDingtalkBotIdentity(clientId);
+  if (identity.secretRef !== secretRef) return null;
+  const suppliedBotId = value.botId === undefined ? identity.botId : safeBotId(value.botId);
+  if (suppliedBotId !== identity.botId) return null;
+  return Object.freeze({
+    botId: identity.botId,
+    clientId,
+    secretRef,
+    approvedSenders,
+  });
+}
+
+function normalizeDocument(value) {
+  if (!value || value.version !== 1 || !Array.isArray(value.bots)) return null;
+  const bots = value.bots.map((bot) => normalizeBot(bot, { stored: true }));
+  if (bots.some((bot) => bot === null)) return null;
+  const botIds = new Set();
+  const clientIds = new Set();
+  const secretRefs = new Set();
+  for (const bot of bots) {
+    if (botIds.has(bot.botId) || clientIds.has(bot.clientId) || secretRefs.has(bot.secretRef)) {
+      return null;
+    }
+    botIds.add(bot.botId);
+    clientIds.add(bot.clientId);
+    secretRefs.add(bot.secretRef);
+  }
+  return Object.freeze({ version: 1, bots: Object.freeze(bots) });
+}
+
+function storedDocument(document) {
+  return {
+    version: 1,
+    bots: document.bots.map((bot) => ({
+      clientId: bot.clientId,
+      secretRef: bot.secretRef,
+      approvedSenders: bot.approvedSenders.map((sender) => ({
+        senderKey: sender.senderKey,
+        staffId: sender.staffId,
+        displayName: sender.displayName,
+        approvedAt: sender.approvedAt,
+      })),
+    })),
+  };
+}
+
+/** Atomic non-secret DingTalk bot configuration store. */
+export class DingtalkConfigStore {
+  #path;
+  #value = EMPTY_DOCUMENT;
+  #writeQueue = Promise.resolve();
+
+  /** @param {string} path Absolute or process-relative configuration file path. */
+  constructor(path) {
+    if (!cleanString(path)) throw new TypeError('config path is required');
+    this.#path = path;
+  }
+
+  /** @returns {Promise<DingtalkConfigStore>} Loaded store. */
+  async load() {
+    try {
+      const normalized = normalizeDocument(JSON.parse(await readFile(this.#path, 'utf8')));
+      if (!normalized) throw new Error('dsh-dingtalk config contains invalid bot data');
+      this.#value = normalized;
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+      this.#value = EMPTY_DOCUMENT;
+    }
+    return this;
+  }
+
+  /** @returns {Array<object>} Cloned bot configurations with derived bot IDs. */
+  list() {
+    return structuredClone(this.#value.bots);
+  }
+
+  /** @param {string} botId Derived bot ID. @returns {object|null} Bot configuration. */
+  get(botId) {
+    const found = this.#value.bots.find((bot) => bot.botId === botId);
+    return found ? structuredClone(found) : null;
+  }
+
+  /** @param {string} clientId DingTalk client ID. @returns {object|null} Bot configuration. */
+  getByClientId(clientId) {
+    const found = this.#value.bots.find((bot) => bot.clientId === clientId);
+    return found ? structuredClone(found) : null;
+  }
+
+  /** @param {object} value Bot configuration without a client secret. @returns {Promise<object>} Saved config. */
+  async save(value) {
+    const normalized = normalizeBot(value);
+    if (!normalized) throw new Error('Refusing to persist invalid dsh-dingtalk bot data');
+    return this.#mutate((bots) => {
+      const collision = bots.find(
+        (bot) => (bot.clientId === normalized.clientId || bot.secretRef === normalized.secretRef)
+          && bot.botId !== normalized.botId,
+      );
+      if (collision) throw new Error('Duplicate DingTalk bot identity');
+      const index = bots.findIndex((bot) => bot.botId === normalized.botId);
+      if (index === -1) bots.push(normalized);
+      else bots[index] = normalized;
+      return structuredClone(normalized);
+    });
+  }
+
+  /** @param {string} botId Derived bot ID. @returns {Promise<object|null>} Removed config. */
+  async remove(botId) {
+    if (!safeBotId(botId)) throw new TypeError('Invalid DingTalk 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);
+    });
+  }
+
+  /** Removes the configuration file and resets the in-memory store. */
+  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}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+      await writeFile(temporary, `${JSON.stringify(storedDocument(document), null, 2)}\n`, {
+        encoding: 'utf8',
+        flag: 'wx',
+        mode: 0o600,
+      });
+      await rename(temporary, this.#path);
+    } catch (error) {
+      try {
+        await unlink(temporary);
+      } catch (cleanupError) {
+        if (cleanupError?.code !== 'ENOENT') throw new AggregateError([error, cleanupError]);
+      }
+      throw error;
+    }
+  }
+}
+
+export { deriveDingtalkBotIdentity as deriveDingTalkBotIdentity };
+export { deriveDingtalkSenderKey as deriveDingTalkSenderKey };
+export { maskDingtalkClientId as maskDingTalkClientId };
+export { maskDingtalkSenderId as maskDingTalkSenderId };
+export { DingtalkConfigStore as DingTalkConfigStore };

package/src/channels/dingtalk/device-auth.mjs

@@ -0,0 +1,237 @@
+const DEFAULT_REGISTRATION_BASE_URL = 'https://oapi.dingtalk.com';
+const REGISTRATION_SOURCE = 'DING_DWS_CLAW';
+
+function cleanString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function positiveNumber(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? number : fallback;
+}
+
+function normalizeBaseUrl(value) {
+  let url;
+  try {
+    url = new URL(cleanString(value) ?? DEFAULT_REGISTRATION_BASE_URL);
+  } catch {
+    throw new TypeError('DingTalk registration base URL must be a valid HTTPS URL');
+  }
+  const isDingtalkHost = url.hostname === 'dingtalk.com' || url.hostname.endsWith('.dingtalk.com');
+  if (url.protocol !== 'https:'
+    || url.port
+    || !isDingtalkHost
+    || url.username
+    || url.password
+    || url.search
+    || url.hash) {
+    throw new TypeError('DingTalk registration base URL must be a valid HTTPS URL');
+  }
+  url.pathname = url.pathname.replace(/\/+$/, '');
+  return url.href.replace(/\/$/, '');
+}
+
+function readNow(clock) {
+  const value = typeof clock?.now === 'function' ? clock.now() : clock();
+  if (!Number.isFinite(value)) throw new TypeError('clock must return a finite timestamp');
+  return value;
+}
+
+function assertRecord(value, action) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new DingtalkDeviceAuthError(
+      'invalid-response',
+      `DingTalk ${action} returned an invalid response`,
+      action,
+    );
+  }
+  if (Number(value.errcode) !== 0) {
+    throw new DingtalkDeviceAuthError(
+      'api-error',
+      `DingTalk ${action} request was rejected`,
+      action,
+    );
+  }
+  return value;
+}
+
+/** A sanitized DingTalk device-registration failure. */
+export class DingtalkDeviceAuthError extends Error {
+  /**
+   * @param {string} code Stable failure code.
+   * @param {string} message Safe diagnostic that does not include response credentials.
+   * @param {string} action Registration stage that failed.
+   * @param {{cause?: unknown}} [options] Optional underlying error.
+   */
+  constructor(code, message, action, options = {}) {
+    super(message, options);
+    this.name = 'DingtalkDeviceAuthError';
+    this.code = code;
+    this.action = action;
+  }
+}
+
+/** Host-only client for DingTalk's QR device-registration flow. */
+export class DingtalkDeviceAuth {
+  #fetch;
+  #clock;
+  #baseUrl;
+  #timeoutMs;
+
+  /**
+   * @param {{fetch?: typeof globalThis.fetch, clock?: {now(): number}|(()=>number), baseUrl?: string, timeoutMs?: number}} [options]
+   * Device-registration dependencies.
+   */
+  constructor({
+    fetch = globalThis.fetch,
+    clock = Date,
+    baseUrl = DEFAULT_REGISTRATION_BASE_URL,
+    timeoutMs = 15_000,
+  } = {}) {
+    if (typeof fetch !== 'function') throw new TypeError('fetch is required');
+    if (typeof clock !== 'function' && typeof clock?.now !== 'function') {
+      throw new TypeError('clock must be a function or expose now()');
+    }
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+      throw new TypeError('timeoutMs must be a positive number');
+    }
+    this.#fetch = fetch;
+    this.#clock = clock;
+    this.#baseUrl = normalizeBaseUrl(baseUrl);
+    this.#timeoutMs = timeoutMs;
+  }
+
+  /**
+   * Starts a QR registration and returns the host-only device code with QR metadata.
+   * @param {{signal?: AbortSignal}} [options] Optional cancellation signal.
+   * @returns {Promise<object>} Device registration details.
+   */
+  async start({ signal } = {}) {
+    const initialized = await this.#post(
+      '/app/registration/init',
+      { source: REGISTRATION_SOURCE },
+      'initialization',
+      signal,
+    );
+    const nonce = cleanString(initialized.nonce);
+    if (!nonce) {
+      throw new DingtalkDeviceAuthError(
+        'missing-nonce',
+        'DingTalk registration initialization did not return a nonce',
+        'initialization',
+      );
+    }
+
+    const begun = await this.#post(
+      '/app/registration/begin',
+      { nonce },
+      'begin',
+      signal,
+    );
+    const deviceCode = cleanString(begun.device_code);
+    const verificationUrl = cleanString(begun.verification_uri_complete);
+    if (!deviceCode || !verificationUrl) {
+      throw new DingtalkDeviceAuthError(
+        'incomplete-registration',
+        'DingTalk registration did not return complete QR metadata',
+        'begin',
+      );
+    }
+
+    const expiresInSeconds = positiveNumber(begun.expires_in, 7_200);
+    const pollIntervalMs = positiveNumber(begun.interval, 5) * 1_000;
+    return Object.freeze({
+      deviceCode,
+      verificationUrl,
+      verificationUri: cleanString(begun.verification_uri),
+      userCode: cleanString(begun.user_code),
+      expiresAt: readNow(this.#clock) + expiresInSeconds * 1_000,
+      pollIntervalMs,
+    });
+  }
+
+  /**
+   * Polls one registration attempt.
+   * @param {{deviceCode: string, signal?: AbortSignal}|string} request Host-only device code.
+   * @returns {Promise<object>} Normalized registration state and credentials on success.
+   */
+  async poll(request) {
+    const deviceCode = cleanString(typeof request === 'string' ? request : request?.deviceCode);
+    const signal = typeof request === 'object' ? request?.signal : undefined;
+    if (!deviceCode) throw new TypeError('deviceCode is required');
+    const response = await this.#post(
+      '/app/registration/poll',
+      { device_code: deviceCode },
+      'poll',
+      signal,
+    );
+    const rawStatus = cleanString(response.status)?.toUpperCase();
+    const status = ['WAITING', 'SUCCESS', 'FAIL', 'EXPIRED'].includes(rawStatus)
+      ? rawStatus
+      : 'UNKNOWN';
+    return Object.freeze({
+      status,
+      clientId: cleanString(response.client_id),
+      clientSecret: cleanString(response.client_secret),
+      failReason: cleanString(response.fail_reason),
+    });
+  }
+
+  async #post(path, body, action, signal) {
+    let response;
+    const timeoutSignal = AbortSignal.timeout(this.#timeoutMs);
+    const requestSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+    try {
+      response = await this.#fetch(`${this.#baseUrl}${path}`, {
+        method: 'POST',
+        headers: {
+          accept: 'application/json',
+          'content-type': 'application/json',
+        },
+        body: JSON.stringify(body),
+        redirect: 'error',
+        signal: requestSignal,
+      });
+    } catch (error) {
+      if (signal?.aborted) throw signal.reason ?? error;
+      if (timeoutSignal.aborted) {
+        throw new DingtalkDeviceAuthError(
+          'timeout',
+          `DingTalk ${action} request timed out`,
+          action,
+          { cause: error },
+        );
+      }
+      if (error?.name === 'AbortError') throw error;
+      throw new DingtalkDeviceAuthError(
+        'network-error',
+        `DingTalk ${action} request could not be completed`,
+        action,
+        { cause: error },
+      );
+    }
+    if (!response || response.ok === false || typeof response.json !== 'function') {
+      throw new DingtalkDeviceAuthError(
+        'http-error',
+        `DingTalk ${action} request failed`,
+        action,
+      );
+    }
+    let value;
+    try {
+      value = await response.json();
+    } catch (error) {
+      throw new DingtalkDeviceAuthError(
+        'invalid-json',
+        `DingTalk ${action} returned invalid JSON`,
+        action,
+        { cause: error },
+      );
+    }
+    return assertRecord(value, action);
+  }
+}
+
+export { DEFAULT_REGISTRATION_BASE_URL, REGISTRATION_SOURCE };
+export { DingtalkDeviceAuth as DingTalkDeviceAuth };
+export { DingtalkDeviceAuthError as DingTalkDeviceAuthError };