dsh-im-ops/plugin-src/host/channels/feishu/rpc.mjs

import QRCode from 'qrcode';
import { resolveRpcAuthority } from '../../rpc-authority.mjs';
import { publicWorkspaceError, validWorkspacePayload } from '../shared/workspace-rpc.mjs';
import {
  FEISHU_ENDPOINTS,
  FEISHU_RPC_CHANNEL,
} from '../../../client/channels/feishu/api.js';

export { FEISHU_ENDPOINTS, FEISHU_RPC_CHANNEL };
export const FEISHU_MULTI_ENDPOINTS = Object.freeze({
  reconnectBot: 'bot.reconnect',
  disconnectBot: 'bot.disconnect',
  deleteBot: 'bot.delete',
});
export const FEISHU_RPC_ENDPOINTS = Object.freeze([
  ...new Set([...Object.values(FEISHU_ENDPOINTS), ...Object.values(FEISHU_MULTI_ENDPOINTS)]),
]);

const REGISTRATION_STATES = new Set([
  'idle', 'starting', 'qr_ready', 'polling', 'slow_down',
  'domain_switched', 'saving', 'succeeded', 'expired', 'cancelled', 'error',
]);
const SAFE_ID = /^[A-Za-z0-9_-]{1,128}$/;

const PUBLIC_ERROR_MESSAGES = Object.freeze({
  abort: 'Registration was cancelled.',
  access_denied: 'Registration was denied.',
  expired_token: 'The registration QR code expired.',
  invalid_credentials: 'Feishu returned invalid app credentials.',
  credentials_callback_failed: 'Unable to activate the Feishu connection.',
  registration_failed: 'Unable to register the Feishu app.',
  connection_failed: 'The bot was created, but its connection could not be started.',
  credential_removal_failed: 'Unable to remove the Feishu credentials.',
  state_cleanup_failed: 'Unable to remove the bot session data. Please retry.',
  deletion_pending: 'Bot deletion is incomplete. Retry removal to finish cleanup.',
  missing_credentials: 'The bot credentials are missing. Delete it and scan again.',
});

const POLL_STATUS_BY_REGISTRATION = Object.freeze({
  idle: 'pending', starting: 'pending', qr_ready: 'pending', polling: 'pending',
  slow_down: 'pending', domain_switched: 'pending', saving: 'connecting',
  succeeded: 'connected', expired: 'expired', cancelled: 'failed', error: 'failed',
});

function isPlainObject(value) {
  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
  const prototype = Object.getPrototypeOf(value);
  return prototype === Object.prototype || prototype === null;
}

function hasOnlyKeys(value, allowed) {
  return isPlainObject(value)
    && Reflect.ownKeys(value).every((key) => typeof key === 'string' && allowed.has(key));
}

function finiteNumber(value) {
  return Number.isFinite(value) ? value : undefined;
}

function safeOpaqueId(value) {
  return typeof value === 'string' && SAFE_ID.test(value);
}

function validCredential(value, maxLength) {
  return typeof value === 'string' && value.trim().length > 0 && value.length <= maxLength;
}

function publicError(error) {
  if (!error || typeof error !== 'object') return null;
  const code = typeof error.code === 'string' && Object.hasOwn(PUBLIC_ERROR_MESSAGES, error.code)
    ? error.code
    : 'registration_failed';
  return { code, message: PUBLIC_ERROR_MESSAGES[code] };
}

function publicRegistration(registration) {
  if (!registration || typeof registration !== 'object') return { state: 'idle', attempt: 0 };
  const state = REGISTRATION_STATES.has(registration.state) ? registration.state : 'error';
  const attempt = safeOpaqueId(registration.attempt)
    ? registration.attempt
    : (finiteNumber(registration.attempt) ?? 0);
  const result = { state, attempt };
  const updatedAt = finiteNumber(registration.updatedAt);
  const expiresAt = finiteNumber(registration.expiresAt);
  const remainingSeconds = finiteNumber(registration.remainingSeconds);
  const pollIntervalSeconds = finiteNumber(registration.pollIntervalSeconds);
  if (updatedAt !== undefined) result.updatedAt = updatedAt;
  if (typeof registration.qrCodeUrl === 'string' && registration.qrCodeUrl.length > 0) {
    result.qrCodeUrl = registration.qrCodeUrl;
  }
  if (expiresAt !== undefined) result.expiresAt = expiresAt;
  if (remainingSeconds !== undefined) result.remainingSeconds = remainingSeconds;
  if (pollIntervalSeconds !== undefined) result.pollIntervalSeconds = pollIntervalSeconds;
  if (safeOpaqueId(registration.botId)) result.botId = registration.botId;
  const error = publicError(registration.error);
  if (error) result.error = error;
  return result;
}

function connectionFacts(connection) {
  const source = connection && typeof connection === 'object' ? connection : {};
  const connected = source.connected === true
    || (source.ready === true
      && source.feishuLongConnectionState === 'connected'
      && source.harnessReachable === true);
  return {
    connected,
    ready: source.ready === true,
    harnessReachable: source.harnessReachable === true,
  };
}

function publicBot(bot) {
  const source = bot && typeof bot === 'object' ? bot : {};
  const result = {
    name: typeof source.name === 'string' && source.name.length > 0 ? source.name : '飞书机器人',
  };
  if (typeof source.avatarUrl === 'string') result.avatarUrl = source.avatarUrl;
  if (typeof source.appIdMasked === 'string') result.appIdMasked = source.appIdMasked;
  if (typeof source.tenantName === 'string') result.tenantName = source.tenantName;
  if (source.domain === 'feishu' || source.domain === 'lark') result.domain = source.domain;
  if (typeof source.activated === 'boolean' || typeof source.activated === 'number') {
    result.activated = source.activated;
  }
  return result;
}

function publicHealth(status, connected) {
  if (connected) return { status: 'healthy', summary: '长连接运行正常', lastCheckedAt: Date.now() };
  if (status?.configured === true) {
    return { status: 'offline', summary: '机器人尚未连接', lastCheckedAt: Date.now() };
  }
  return { status: 'offline', summary: '尚未接入飞书机器人', lastCheckedAt: Date.now() };
}

function connectionState(status, registration, connected) {
  if (connected) return 'connected';
  if (status?.phase === 'error' || registration.state === 'error') return 'error';
  if (status?.phase === 'connecting' || registration.state === 'saving') return 'connecting';
  if (status?.phase === 'registering'
    || ['starting', 'qr_ready', 'polling', 'slow_down', 'domain_switched'].includes(registration.state)) {
    return 'provisioning';
  }
  return 'disconnected';
}

async function qrCodeDataUrl(verificationUrl) {
  return QRCode.toDataURL(verificationUrl, {
    errorCorrectionLevel: 'M', margin: 1, width: 320, type: 'image/png',
  });
}

async function publicProvisioning(registration, encodeQr) {
  if (!registration.qrCodeUrl) return undefined;
  return {
    attemptId: String(registration.attempt),
    verificationUrl: registration.qrCodeUrl,
    qrCodeDataUrl: await encodeQr(registration.qrCodeUrl),
    expiresAt: registration.expiresAt ?? Date.now() + (5 * 60_000),
    pollIntervalMs: Math.max(800, Math.min(10_000, (registration.pollIntervalSeconds ?? 1.8) * 1000)),
  };
}

function publicBotEntry(entry) {
  const source = entry && typeof entry === 'object' ? entry : {};
  if (!safeOpaqueId(source.botId)) return null;
  const facts = connectionFacts(source.connection);
  const connected = source.connected === true || facts.connected;
  const registration = { state: 'idle' };
  const result = {
    botId: source.botId,
    state: connectionState(source, registration, connected),
    connected,
    configured: source.configured === true,
    bot: publicBot(source.bot),
    health: publicHealth(source, connected),
  };
  if (typeof source.workspace === 'string' && source.workspace) result.workspace = source.workspace;
  const error = publicError(source.error);
  if (error) result.error = error;
  return result;
}

/** Exact redacted browser contract consumed by the Feishu settings client. */
export async function toPublicFeishuStatus(status, { encodeQr = qrCodeDataUrl } = {}) {
  const source = status && typeof status === 'object' ? status : {};
  const registration = publicRegistration(source.registration);
  const facts = connectionFacts(source.connection);
  const connected = source.connected === true || facts.connected;
  const provisioning = await publicProvisioning(registration, encodeQr);
  const error = publicError(source.error) ?? registration.error ?? null;
  const bots = Array.isArray(source.bots)
    ? source.bots.map(publicBotEntry).filter(Boolean)
    : [];
  const snapshot = {
    schemaVersion: source.schemaVersion === 2 ? 2 : 1,
    revision: Number.isSafeInteger(source.revision) && source.revision >= 0 ? source.revision : 0,
    state: connectionState(source, registration, connected),
    connected,
    configured: source.configured === true,
    bot: publicBot(source.bot),
    health: publicHealth(source, connected),
    bots,
    totals: {
      configured: bots.length || (source.configured === true ? 1 : 0),
      connected: bots.length ? bots.filter((bot) => bot.connected).length : (connected ? 1 : 0),
    },
  };
  if (provisioning) snapshot.provisioning = provisioning;
  if (error) snapshot.error = error;
  return snapshot;
}

function badRequest(message) {
  return { ok: false, error: { code: 'bad-request', message, details: { issues: [] } } };
}

function cancelled() {
  return { ok: false, error: { code: 'cancelled', message: 'The Feishu request was cancelled.', details: {} } };
}

function internalFailure() {
  return { ok: false, error: { code: 'internal', message: 'The Feishu integration operation failed.', details: {} } };
}

function validPayload(endpoint, payload) {
  if (endpoint === FEISHU_ENDPOINTS.status) {
    return hasOnlyKeys(payload, new Set()) ? null : 'This endpoint accepts an empty payload only.';
  }
  if (endpoint === FEISHU_ENDPOINTS.testConnection) {
    return hasOnlyKeys(payload, new Set()) ? null : 'This endpoint accepts an empty payload only.';
  }
  if (endpoint === FEISHU_ENDPOINTS.beginProvisioning) {
    if (!hasOnlyKeys(payload, new Set(['locale', 'replaceAttemptId']))) {
      return 'Provisioning accepts locale and replaceAttemptId only.';
    }
    if (payload.locale !== undefined && payload.locale !== 'zh-CN') return 'The provisioning locale must be zh-CN.';
    if (payload.replaceAttemptId !== undefined && !safeOpaqueId(payload.replaceAttemptId)) {
      return 'replaceAttemptId must be a valid opaque id.';
    }
    return null;
  }
  if (endpoint === FEISHU_ENDPOINTS.bindCredentials) {
    return hasOnlyKeys(payload, new Set(['appId', 'appSecret']))
      && validCredential(payload.appId, 256)
      && validCredential(payload.appSecret, 1024)
      ? null
      : 'Credential binding requires App ID and App Secret.';
  }
  if (endpoint === FEISHU_ENDPOINTS.pollProvisioning
    || endpoint === FEISHU_ENDPOINTS.cancelProvisioning) {
    return hasOnlyKeys(payload, new Set(['attemptId'])) && safeOpaqueId(payload.attemptId)
      ? null
      : 'A single valid attemptId is required.';
  }
  if (endpoint === FEISHU_ENDPOINTS.disconnect) {
    return hasOnlyKeys(payload, new Set(['removeCredentials'])) && payload.removeCredentials === true
      ? null
      : 'Disconnect requires removeCredentials=true.';
  }
  if (endpoint === FEISHU_MULTI_ENDPOINTS.reconnectBot
    || endpoint === FEISHU_MULTI_ENDPOINTS.disconnectBot) {
    return hasOnlyKeys(payload, new Set(['botId'])) && safeOpaqueId(payload.botId)
      ? null
      : 'A single valid botId is required.';
  }
  if (endpoint === FEISHU_MULTI_ENDPOINTS.deleteBot) {
    return hasOnlyKeys(payload, new Set(['botId', 'confirm']))
      && safeOpaqueId(payload.botId) && payload.confirm === true
      ? null
      : 'Deleting a bot requires a valid botId and confirm=true.';
  }
  if (endpoint === FEISHU_ENDPOINTS.setWorkspace) {
    return validWorkspacePayload(payload)
      ? null : '请输入工作区绝对路径。';
  }
  return 'Unknown Feishu endpoint.';
}

function abortableDelay(milliseconds, signal) {
  return new Promise((resolve, reject) => {
    if (signal?.aborted) {
      reject(signal.reason ?? new Error('aborted'));
      return;
    }
    const timer = setTimeout(done, milliseconds);
    timer.unref?.();
    function done() {
      signal?.removeEventListener('abort', aborted);
      resolve();
    }
    function aborted() {
      clearTimeout(timer);
      reject(signal.reason ?? new Error('aborted'));
    }
    signal?.addEventListener('abort', aborted, { once: true });
  });
}

async function statusForRegistration(controller, attemptId) {
  if (typeof controller.registrationStatus === 'function') {
    return controller.registrationStatus(attemptId);
  }
  return controller.status();
}

async function waitForQr(controller, initial, attemptId, signal) {
  let current = initial;
  const deadline = Date.now() + 15_000;
  for (;;) {
    const registration = publicRegistration(current?.registration);
    if (registration.qrCodeUrl) return current;
    if (['error', 'expired', 'cancelled'].includes(registration.state)) {
      throw new Error('Provisioning stopped before the QR code was ready.');
    }
    if (Date.now() >= deadline) throw new Error('Provisioning QR code timed out.');
    await abortableDelay(50, signal);
    current = await statusForRegistration(controller, attemptId);
    if (!current) throw new Error('The provisioning attempt is no longer active.');
  }
}

function sameAttempt(status, attemptId) {
  return String(publicRegistration(status?.registration).attempt) === attemptId;
}

function pollStatus(status) {
  const registration = publicRegistration(status?.registration);
  if (registration.state === 'succeeded') {
    const connected = registration.botId
      && (status?.connected === true || connectionFacts(status?.connection).connected);
    return connected ? 'connected' : 'connecting';
  }
  return POLL_STATUS_BY_REGISTRATION[registration.state] ?? 'failed';
}

function assertController(controller) {
  if (!controller
    || typeof controller.status !== 'function'
    || typeof controller.startRegistration !== 'function'
    || typeof controller.cancelRegistration !== 'function'
    || typeof controller.disconnect !== 'function') {
    throw new TypeError('A Feishu controller with status/start/cancel/disconnect is required');
  }
}

/** DSH rc.6 handler: (endpoint, payload, signal) => Promise<RpcResult>. */
export function createFeishuRpcHandler(controller, { encodeQr = qrCodeDataUrl } = {}) {
  assertController(controller);
  const qrCache = new Map();
  const attemptQr = new Map();
  const cachedEncodeQr = (url) => {
    let encoded = qrCache.get(url);
    if (!encoded) {
      if (qrCache.size >= 32) qrCache.delete(qrCache.keys().next().value);
      encoded = Promise.resolve().then(() => encodeQr(url));
      qrCache.set(url, encoded);
    }
    return encoded;
  };

  return async (endpoint, payload, signal) => {
    if (signal?.aborted) return cancelled();
    if (!FEISHU_RPC_ENDPOINTS.includes(endpoint)) return badRequest('Unknown Feishu endpoint.');
    const payloadFailure = validPayload(endpoint, payload);
    if (payloadFailure) return badRequest(payloadFailure);

    try {
      let value;
      if (endpoint === FEISHU_ENDPOINTS.status) {
        value = await toPublicFeishuStatus(await controller.status(), { encodeQr: cachedEncodeQr });
      } else if (endpoint === FEISHU_ENDPOINTS.beginProvisioning) {
        if (payload.replaceAttemptId) {
          await controller.cancelRegistration(payload.replaceAttemptId);
        }
        const started = await controller.startRegistration({ locale: payload.locale });
        const attemptId = String(publicRegistration(started?.registration).attempt);
        const ready = await waitForQr(controller, started, attemptId, signal);
        value = (await toPublicFeishuStatus(ready, { encodeQr: cachedEncodeQr })).provisioning;
        if (!value) throw new Error('Provisioning did not produce a QR code.');
        attemptQr.set(attemptId, value.verificationUrl);
      } else if (endpoint === FEISHU_ENDPOINTS.pollProvisioning) {
        const current = await statusForRegistration(controller, payload.attemptId);
        if (!current || !sameAttempt(current, payload.attemptId)) {
          return badRequest('The provisioning attempt is no longer active.');
        }
        const registration = publicRegistration(current.registration);
        const connection = await toPublicFeishuStatus(current, { encodeQr: cachedEncodeQr });
        value = {
          status: pollStatus(current),
          ...(registration.botId ? { botId: registration.botId } : {}),
          ...(connection.provisioning ? { provisioning: connection.provisioning } : {}),
          ...(registration.botId && connection.connected ? { connection } : {}),
          ...(connection.error ? { message: connection.error.message } : {}),
        };
        if (['connected', 'expired', 'failed'].includes(value.status)) {
          const url = attemptQr.get(payload.attemptId);
          if (url) qrCache.delete(url);
          attemptQr.delete(payload.attemptId);
        }
      } else if (endpoint === FEISHU_ENDPOINTS.cancelProvisioning) {
        const current = await statusForRegistration(controller, payload.attemptId);
        if (!current || !sameAttempt(current, payload.attemptId)) {
          return badRequest('The provisioning attempt is no longer active.');
        }
        const multi = typeof controller.registrationStatus === 'function';
        const registration = publicRegistration(current.registration);
        if (!multi && registration.state === 'saving') await controller.disconnect();
        else await controller.cancelRegistration(payload.attemptId);
        const url = attemptQr.get(payload.attemptId);
        if (url) qrCache.delete(url);
        attemptQr.delete(payload.attemptId);
        value = { status: 'failed', message: 'Registration was cancelled.' };
      } else if (endpoint === FEISHU_ENDPOINTS.bindCredentials) {
        if (typeof controller.bindCredentials !== 'function') {
          throw new Error('Credential binding is unavailable');
        }
        value = await toPublicFeishuStatus(
          await controller.bindCredentials(payload),
          { encodeQr: cachedEncodeQr },
        );
      } else if (endpoint === FEISHU_ENDPOINTS.testConnection) {
        const current = await controller.status();
        const alreadyConnected = current?.connected === true
          || connectionFacts(current?.connection).connected;
        const checked = alreadyConnected || typeof controller.reconnect !== 'function'
          ? current
          : await controller.reconnect();
        value = await toPublicFeishuStatus(checked, { encodeQr: cachedEncodeQr });
      } else if (endpoint === FEISHU_ENDPOINTS.disconnect) {
        value = await toPublicFeishuStatus(await controller.disconnect(), { encodeQr: cachedEncodeQr });
      } else if (endpoint === FEISHU_MULTI_ENDPOINTS.reconnectBot) {
        if (typeof controller.reconnectBot !== 'function') throw new Error('Multi-bot reconnect is unavailable');
        value = await toPublicFeishuStatus(await controller.reconnectBot(payload.botId), { encodeQr: cachedEncodeQr });
      } else if (endpoint === FEISHU_MULTI_ENDPOINTS.disconnectBot) {
        if (typeof controller.disconnectBot !== 'function') throw new Error('Multi-bot disconnect is unavailable');
        value = await toPublicFeishuStatus(await controller.disconnectBot(payload.botId), { encodeQr: cachedEncodeQr });
      } else if (endpoint === FEISHU_ENDPOINTS.setWorkspace) {
        if (typeof controller.updateWorkspace !== 'function') throw new Error('Workspace update is unavailable');
        value = await toPublicFeishuStatus(
          await controller.updateWorkspace(payload.botId, payload.workspace),
          { encodeQr: cachedEncodeQr },
        );
      } else {
        if (typeof controller.deleteBot !== 'function') throw new Error('Multi-bot delete is unavailable');
        value = await toPublicFeishuStatus(await controller.deleteBot(payload.botId), { encodeQr: cachedEncodeQr });
      }
      if (signal?.aborted) return cancelled();
      return { ok: true, value };
    } catch (error) {
      const workspaceError = publicWorkspaceError(error);
      return signal?.aborted ? cancelled() : workspaceError
        ? { ok: false, error: { ...workspaceError, details: {} } }
        : internalFailure();
    }
  };
}

/** Register the `/feishu` logical channel with its configured browser authority. */
export function installFeishuRpc(ctx, controller, options, authority) {
  if (!ctx?.connection?.rpc || typeof ctx.connection.rpc.handle !== 'function') {
    throw new TypeError('DSH Host Connection RPC is required');
  }
  return ctx.connection.rpc.handle(
    FEISHU_RPC_CHANNEL,
    createFeishuRpcHandler(controller, options),
    { authority: resolveRpcAuthority(authority) },
  );
}