@actagent/feishu 2026.6.2

package/src/app-registration.ts

@@ -0,0 +1,355 @@
+// Feishu plugin module implements app registration behavior.
+import { finiteSecondsToTimerSafeMilliseconds } from "actagent/plugin-sdk/number-runtime";
+/**
+ * Feishu app registration via OAuth device-code flow.
+ *
+ * Migrated from feishu-plugin-cli's `feishu-auth.ts` and `install-prompts.ts`.
+ * Replaces axios with native fetch, removes inquirer/ora/chalk in favor of
+ * the actagent WizardPrompter surface.
+ */
+import { fetchWithSsrFGuard } from "actagent/plugin-sdk/ssrf-runtime";
+import { renderQrTerminal } from "./qr-terminal.js";
+import type { FeishuDomain } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const FEISHU_ACCOUNTS_URL = "https://accounts.feishu.cn";
+const LARK_ACCOUNTS_URL = "https://accounts.larksuite.com";
+
+const REGISTRATION_PATH = "/oauth/v1/app/registration";
+
+const REQUEST_TIMEOUT_MS = 10_000;
+const DEFAULT_REGISTRATION_POLL_INTERVAL_SECONDS = 5;
+const DEFAULT_REGISTRATION_EXPIRE_SECONDS = 600;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface AppRegistrationResult {
+  appId: string;
+  appSecret: string;
+  domain: FeishuDomain;
+  openId?: string;
+}
+
+interface InitResponse {
+  nonce: string;
+  supported_auth_methods: string[];
+}
+
+export interface BeginResult {
+  deviceCode: string;
+  qrUrl: string;
+  userCode: string;
+  interval: number;
+  expireIn: number;
+}
+
+interface RawBeginResponse {
+  device_code: string;
+  verification_uri: string;
+  user_code: string;
+  verification_uri_complete: string;
+  interval: number;
+  expire_in: number;
+}
+
+interface PollResponse {
+  client_id?: string;
+  client_secret?: string;
+  user_info?: {
+    open_id?: string;
+    tenant_brand?: "feishu" | "lark";
+  };
+  error?: string;
+  error_description?: string;
+}
+
+export type PollOutcome =
+  | { status: "success"; result: AppRegistrationResult }
+  | { status: "access_denied" }
+  | { status: "expired" }
+  | { status: "timeout" }
+  | { status: "error"; message: string };
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function accountsBaseUrl(domain: FeishuDomain): string {
+  return domain === "lark" ? LARK_ACCOUNTS_URL : FEISHU_ACCOUNTS_URL;
+}
+
+async function postRegistration<T>(baseUrl: string, body: Record<string, string>): Promise<T> {
+  return await fetchFeishuJson<T>({
+    url: `${baseUrl}${REGISTRATION_PATH}`,
+    init: {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams(body).toString(),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    },
+    auditContext: "feishu.app-registration.post",
+  });
+}
+
+async function fetchFeishuJson<T>(params: {
+  url: string;
+  init: RequestInit;
+  auditContext: string;
+}): Promise<T> {
+  const { response, release } = await fetchWithSsrFGuard({
+    url: params.url,
+    init: params.init,
+    policy: { allowedHostnames: [new URL(params.url).hostname] },
+    auditContext: params.auditContext,
+  });
+  try {
+    // Registration poll returns 4xx for pending/error states with a JSON body.
+    return (await response.json()) as T;
+  } finally {
+    await release();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Step 1: Initialize registration and verify the environment supports
+ * `client_secret` auth.
+ *
+ * @throws If the environment does not support `client_secret`.
+ */
+export async function initAppRegistration(domain: FeishuDomain = "feishu"): Promise<void> {
+  const baseUrl = accountsBaseUrl(domain);
+  const res = await postRegistration<InitResponse>(baseUrl, { action: "init" });
+
+  if (!res.supported_auth_methods?.includes("client_secret")) {
+    throw new Error("Current environment does not support client_secret auth method");
+  }
+}
+
+/**
+ * Step 2: Begin the device-code flow. Returns a device code and a QR URL
+ * that the user should scan with Feishu/Lark mobile app.
+ */
+export async function beginAppRegistration(domain: FeishuDomain = "feishu"): Promise<BeginResult> {
+  const baseUrl = accountsBaseUrl(domain);
+  const res = await postRegistration<RawBeginResponse>(baseUrl, {
+    action: "begin",
+    archetype: "PersonalAgent",
+    auth_method: "client_secret",
+    request_user_info: "open_id",
+  });
+
+  const qrUrl = new URL(res.verification_uri_complete);
+  qrUrl.searchParams.set("from", "oc_onboard");
+  qrUrl.searchParams.set("tp", "ob_cli_app");
+
+  return {
+    deviceCode: res.device_code,
+    qrUrl: qrUrl.toString(),
+    userCode: res.user_code,
+    interval:
+      finiteSecondsToTimerSafeMilliseconds(res.interval) === undefined
+        ? DEFAULT_REGISTRATION_POLL_INTERVAL_SECONDS
+        : res.interval,
+    expireIn:
+      finiteSecondsToTimerSafeMilliseconds(res.expire_in) === undefined
+        ? DEFAULT_REGISTRATION_EXPIRE_SECONDS
+        : res.expire_in,
+  };
+}
+
+/**
+ * Step 3: Poll for authorization result until success, denial, expiry, or
+ * timeout. Automatically handles domain switching when `tenant_brand` is
+ * detected as "lark".
+ */
+export async function pollAppRegistration(params: {
+  deviceCode: string;
+  interval: number;
+  expireIn: number;
+  initialDomain?: FeishuDomain;
+  abortSignal?: AbortSignal;
+  /** Registration type parameter. The CLI bot QR flow uses "ob_cli_app". */
+  tp?: string;
+}): Promise<PollOutcome> {
+  const { deviceCode, expireIn, initialDomain = "feishu", abortSignal, tp } = params;
+  let currentInterval = params.interval;
+  let domain: FeishuDomain = initialDomain;
+  let domainSwitched = false;
+
+  const expireInMs =
+    finiteSecondsToTimerSafeMilliseconds(expireIn) ??
+    finiteSecondsToTimerSafeMilliseconds(DEFAULT_REGISTRATION_EXPIRE_SECONDS) ??
+    REQUEST_TIMEOUT_MS;
+  const deadline = Date.now() + expireInMs;
+
+  while (Date.now() < deadline) {
+    if (abortSignal?.aborted) {
+      return { status: "timeout" };
+    }
+
+    const baseUrl = accountsBaseUrl(domain);
+
+    let pollRes: PollResponse;
+    try {
+      pollRes = await postRegistration<PollResponse>(baseUrl, {
+        action: "poll",
+        device_code: deviceCode,
+        ...(tp ? { tp } : {}),
+      });
+    } catch {
+      // Transient network error — keep polling.
+      await sleepRegistrationPollInterval(currentInterval);
+      continue;
+    }
+
+    // Domain auto-detection: switch to lark if tenant_brand says so.
+    if (pollRes.user_info?.tenant_brand) {
+      const isLark = pollRes.user_info.tenant_brand === "lark";
+      if (!domainSwitched && isLark) {
+        domain = "lark";
+        domainSwitched = true;
+        // Retry poll immediately with the correct domain.
+        continue;
+      }
+    }
+
+    // Success.
+    if (pollRes.client_id && pollRes.client_secret) {
+      return {
+        status: "success",
+        result: {
+          appId: pollRes.client_id,
+          appSecret: pollRes.client_secret,
+          domain,
+          openId: pollRes.user_info?.open_id,
+        },
+      };
+    }
+
+    // Error handling.
+    if (pollRes.error) {
+      if (pollRes.error === "authorization_pending") {
+        // Continue waiting.
+      } else if (pollRes.error === "slow_down") {
+        currentInterval += 5;
+      } else if (pollRes.error === "access_denied") {
+        return { status: "access_denied" };
+      } else if (pollRes.error === "expired_token") {
+        return { status: "expired" };
+      } else {
+        return {
+          status: "error",
+          message: `${pollRes.error}: ${pollRes.error_description ?? "unknown"}`,
+        };
+      }
+    }
+
+    await sleepRegistrationPollInterval(currentInterval);
+  }
+
+  return { status: "timeout" };
+}
+
+/**
+ * Print QR code directly to stdout.
+ *
+ * QR codes must be printed without any surrounding box/border decoration,
+ * otherwise the pattern is corrupted and cannot be scanned.
+ */
+export async function printQrCode(url: string): Promise<void> {
+  const output = await renderQrTerminal(url);
+  process.stdout.write(output.endsWith("\n") ? output : `${output}\n`);
+}
+
+/**
+ * Fetch the app owner's open_id using the application.v6.application.get API.
+ *
+ * Used during setup to auto-populate security policy allowlists.
+ * Returns undefined on any failure (fail-open).
+ */
+export async function getAppOwnerOpenId(params: {
+  appId: string;
+  appSecret: string;
+  domain?: FeishuDomain;
+}): Promise<string | undefined> {
+  const baseUrl =
+    params.domain === "lark" ? "https://open.larksuite.com" : "https://open.feishu.cn";
+
+  try {
+    // First, get a tenant_access_token.
+    const tokenData = await fetchFeishuJson<{
+      code?: number;
+      tenant_access_token?: string;
+    }>({
+      url: `${baseUrl}/open-apis/auth/v3/tenant_access_token/internal`,
+      init: {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ app_id: params.appId, app_secret: params.appSecret }),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      },
+      auditContext: "feishu.app-registration.owner-token",
+    });
+    if (!tokenData.tenant_access_token) {
+      return undefined;
+    }
+
+    // Query app info for the owner's open_id.
+    const appData = await fetchFeishuJson<{
+      code?: number;
+      data?: {
+        app?: {
+          owner?: { owner_id?: string; owner_type?: number; type?: number };
+          creator_id?: string;
+        };
+      };
+    }>({
+      url: `${baseUrl}/open-apis/application/v6/applications/${params.appId}?user_id_type=open_id`,
+      init: {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${tokenData.tenant_access_token}`,
+          "Content-Type": "application/json",
+        },
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      },
+      auditContext: "feishu.app-registration.owner-app",
+    });
+    if (appData.code !== 0) {
+      return undefined;
+    }
+
+    const app = appData.data?.app;
+    const owner = app?.owner;
+    const ownerType = owner?.owner_type ?? owner?.type;
+    // owner_type=2 means enterprise member; use owner_id. Otherwise fallback to creator_id.
+    return ownerType === 2 && owner?.owner_id
+      ? owner.owner_id
+      : (app?.creator_id ?? owner?.owner_id);
+  } catch {
+    return undefined;
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+function sleepRegistrationPollInterval(intervalSeconds: number): Promise<void> {
+  const intervalMs =
+    finiteSecondsToTimerSafeMilliseconds(intervalSeconds) ??
+    finiteSecondsToTimerSafeMilliseconds(DEFAULT_REGISTRATION_POLL_INTERVAL_SECONDS) ??
+    REQUEST_TIMEOUT_MS;
+  return sleep(intervalMs);
+}

package/src/approval-auth.test.ts

@@ -0,0 +1,25 @@
+// Feishu tests cover approval auth plugin behavior.
+import { describe, expect, it } from "vitest";
+import { feishuApprovalAuth } from "./approval-auth.js";
+
+describe("feishuApprovalAuth", () => {
+  it("authorizes open_id approvers and ignores user_id-only allowlists", () => {
+    expect(
+      feishuApprovalAuth.authorizeActorAction({
+        cfg: { channels: { feishu: { allowFrom: ["ou_owner"] } } },
+        senderId: "ou_owner",
+        action: "approve",
+        approvalKind: "exec",
+      }),
+    ).toEqual({ authorized: true });
+
+    expect(
+      feishuApprovalAuth.authorizeActorAction({
+        cfg: { channels: { feishu: { allowFrom: ["user_123"] } } },
+        senderId: "ou_attacker",
+        action: "approve",
+        approvalKind: "exec",
+      }),
+    ).toEqual({ authorized: true });
+  });
+});

package/src/approval-auth.ts

@@ -0,0 +1,26 @@
+// Feishu plugin module implements approval auth behavior.
+import {
+  createResolvedApproverActionAuthAdapter,
+  resolveApprovalApprovers,
+} from "actagent/plugin-sdk/approval-auth-runtime";
+import { normalizeOptionalLowercaseString } from "actagent/plugin-sdk/string-coerce-runtime";
+import { resolveFeishuAccount } from "./accounts.js";
+import { normalizeFeishuTarget } from "./targets.js";
+
+function normalizeFeishuApproverId(value: string | number): string | undefined {
+  const normalized = normalizeFeishuTarget(String(value));
+  const trimmed = normalizeOptionalLowercaseString(normalized);
+  return trimmed?.startsWith("ou_") ? trimmed : undefined;
+}
+
+export const feishuApprovalAuth = createResolvedApproverActionAuthAdapter({
+  channelLabel: "Feishu",
+  resolveApprovers: ({ cfg, accountId }) => {
+    const account = resolveFeishuAccount({ cfg, accountId }).config;
+    return resolveApprovalApprovers({
+      allowFrom: account.allowFrom,
+      normalizeApprover: normalizeFeishuApproverId,
+    });
+  },
+  normalizeSenderId: (value) => normalizeFeishuApproverId(value),
+});

package/src/async.test.ts

@@ -0,0 +1,68 @@
+// Feishu tests cover async plugin behavior.
+import { MAX_TIMER_TIMEOUT_MS } from "actagent/plugin-sdk/number-runtime";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { raceWithTimeoutAndAbort, waitForAbortableDelay } from "./async.js";
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+describe("raceWithTimeoutAndAbort", () => {
+  it("normalizes oversized timeouts before arming the watchdog", async () => {
+    const timeoutSpy = vi
+      .spyOn(globalThis, "setTimeout")
+      .mockReturnValue(1 as unknown as ReturnType<typeof setTimeout>);
+    vi.spyOn(globalThis, "clearTimeout").mockImplementation(() => undefined);
+
+    await raceWithTimeoutAndAbort(Promise.resolve("ok"), {
+      timeoutMs: Number.MAX_SAFE_INTEGER,
+    });
+
+    expect(timeoutSpy).toHaveBeenCalledWith(expect.any(Function), MAX_TIMER_TIMEOUT_MS);
+  });
+});
+
+describe("waitForAbortableDelay", () => {
+  it("resolves false immediately when already aborted", async () => {
+    vi.useFakeTimers();
+    const abortController = new AbortController();
+    abortController.abort();
+
+    await expect(waitForAbortableDelay(60_000, abortController.signal)).resolves.toBe(false);
+  });
+
+  it("resolves false immediately when aborted during backoff", async () => {
+    vi.useFakeTimers();
+    const abortController = new AbortController();
+
+    const delay = waitForAbortableDelay(60_000, abortController.signal);
+    abortController.abort();
+
+    await expect(delay).resolves.toBe(false);
+  });
+
+  it("resolves true after the full delay when not aborted", async () => {
+    vi.useFakeTimers();
+
+    const delay = waitForAbortableDelay(500);
+    await vi.advanceTimersByTimeAsync(500);
+
+    await expect(delay).resolves.toBe(true);
+  });
+
+  it("normalizes oversized delays before arming the timer", async () => {
+    const timeoutSpy = vi
+      .spyOn(globalThis, "setTimeout")
+      .mockImplementation((callback: () => void) => {
+        queueMicrotask(callback);
+        return 1 as unknown as ReturnType<typeof setTimeout>;
+      });
+    vi.spyOn(globalThis, "clearTimeout").mockImplementation(() => undefined);
+
+    const delay = waitForAbortableDelay(Number.MAX_SAFE_INTEGER);
+
+    expect(timeoutSpy).toHaveBeenCalledWith(expect.any(Function), MAX_TIMER_TIMEOUT_MS);
+    await expect(delay).resolves.toBe(true);
+  });
+});

package/src/async.ts

@@ -0,0 +1,109 @@
+// Feishu plugin module implements async behavior.
+import { resolveTimerTimeoutMs } from "actagent/plugin-sdk/number-runtime";
+
+const RACE_TIMEOUT = Symbol("race-timeout");
+const RACE_ABORT = Symbol("race-abort");
+
+type RaceWithTimeoutAndAbortResult<T> =
+  | { status: "resolved"; value: T }
+  | { status: "timeout" }
+  | { status: "aborted" };
+
+export async function raceWithTimeoutAndAbort<T>(
+  promise: Promise<T>,
+  options: {
+    timeoutMs?: number;
+    abortSignal?: AbortSignal;
+  } = {},
+): Promise<RaceWithTimeoutAndAbortResult<T>> {
+  if (options.abortSignal?.aborted) {
+    return { status: "aborted" };
+  }
+
+  if (options.timeoutMs === undefined && !options.abortSignal) {
+    return { status: "resolved", value: await promise };
+  }
+
+  let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+  let abortHandler: (() => void) | undefined;
+  const contenders: Array<Promise<T | typeof RACE_TIMEOUT | typeof RACE_ABORT>> = [promise];
+
+  if (options.timeoutMs !== undefined) {
+    const timeoutMs = resolveTimerTimeoutMs(options.timeoutMs, 1);
+    contenders.push(
+      new Promise((resolve) => {
+        timeoutHandle = setTimeout(() => resolve(RACE_TIMEOUT), timeoutMs);
+      }),
+    );
+  }
+
+  if (options.abortSignal) {
+    contenders.push(
+      new Promise((resolve) => {
+        abortHandler = () => resolve(RACE_ABORT);
+        options.abortSignal?.addEventListener("abort", abortHandler, { once: true });
+      }),
+    );
+  }
+
+  try {
+    const result = await Promise.race(contenders);
+    if (result === RACE_TIMEOUT) {
+      return { status: "timeout" };
+    }
+    if (result === RACE_ABORT) {
+      return { status: "aborted" };
+    }
+    return { status: "resolved", value: result };
+  } finally {
+    if (timeoutHandle) {
+      clearTimeout(timeoutHandle);
+    }
+    if (abortHandler) {
+      options.abortSignal?.removeEventListener("abort", abortHandler);
+    }
+  }
+}
+
+export function waitForAbortableDelay(
+  delayMs: number,
+  abortSignal?: AbortSignal,
+): Promise<boolean> {
+  if (abortSignal?.aborted) {
+    return Promise.resolve(false);
+  }
+
+  return new Promise((resolve) => {
+    let settled = false;
+
+    const finish = (value: boolean) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (timer) {
+        clearTimeout(timer);
+      }
+      if (handleAbort) {
+        abortSignal?.removeEventListener("abort", handleAbort);
+      }
+      resolve(value);
+    };
+
+    const handleAbort: (() => void) | undefined = () => {
+      finish(false);
+    };
+
+    abortSignal?.addEventListener("abort", handleAbort, { once: true });
+    if (abortSignal?.aborted) {
+      finish(false);
+      return;
+    }
+
+    const timer: ReturnType<typeof setTimeout> | undefined = setTimeout(
+      () => finish(true),
+      resolveTimerTimeoutMs(delayMs, 1),
+    );
+    timer.unref?.();
+  });
+}

package/src/audio-preflight.runtime.ts

@@ -0,0 +1,10 @@
+// Feishu plugin module implements audio preflight behavior.
+import { transcribeFirstAudio as transcribeFirstAudioImpl } from "actagent/plugin-sdk/media-runtime";
+
+type TranscribeFirstAudio = typeof import("actagent/plugin-sdk/media-runtime").transcribeFirstAudio;
+
+export async function transcribeFirstAudio(
+  ...args: Parameters<TranscribeFirstAudio>
+): ReturnType<TranscribeFirstAudio> {
+  return await transcribeFirstAudioImpl(...args);
+}