@openclaw/feishu 2026.3.13 → 2026.5.2-beta.1

package/src/app-registration.ts

@@ -0,0 +1,331 @@
+/**
+ * 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 openclaw WizardPrompter surface.
+ */
+import { fetchWithSsrFGuard } from "openclaw/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;
+
+// ---------------------------------------------------------------------------
+// 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: res.interval || 5,
+    expireIn: res.expire_in || 600,
+  };
+}
+
+/**
+ * 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: "ob_user" for user mode, "ob_app" for bot mode. */
+  tp?: string;
+}): Promise<PollOutcome> {
+  const { deviceCode, expireIn, initialDomain = "feishu", abortSignal, tp } = params;
+  let currentInterval = params.interval;
+  let domain: FeishuDomain = initialDomain;
+  let domainSwitched = false;
+
+  const deadline = Date.now() + expireIn * 1000;
+
+  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 sleep(currentInterval * 1000);
+      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 sleep(currentInterval * 1000);
+  }
+
+  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, { small: true });
+  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));
+}

package/src/approval-auth.test.ts

@@ -0,0 +1,24 @@
+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,25 @@
+import {
+  createResolvedApproverActionAuthAdapter,
+  resolveApprovalApprovers,
+} from "openclaw/plugin-sdk/approval-auth-runtime";
+import { normalizeOptionalLowercaseString } from "openclaw/plugin-sdk/text-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,35 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { waitForAbortableDelay } from "./async.js";
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+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);
+  });
+});

package/src/async.ts

@@ -1,7 +1,7 @@
 const RACE_TIMEOUT = Symbol("race-timeout");
 const RACE_ABORT = Symbol("race-abort");
 
-export type RaceWithTimeoutAndAbortResult<T> =
+type RaceWithTimeoutAndAbortResult<T> =
   | { status: "resolved"; value: T }
   | { status: "timeout" }
   | { status: "aborted" };
@@ -60,3 +60,45 @@ export async function raceWithTimeoutAndAbort<T>(
     }
   }
 }
+
+export function waitForAbortableDelay(
+  delayMs: number,
+  abortSignal?: AbortSignal,
+): Promise<boolean> {
+  if (abortSignal?.aborted) {
+    return Promise.resolve(false);
+  }
+
+  return new Promise((resolve) => {
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let handleAbort: (() => void) | undefined;
+
+    const finish = (value: boolean) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (timer) {
+        clearTimeout(timer);
+      }
+      if (handleAbort) {
+        abortSignal?.removeEventListener("abort", handleAbort);
+      }
+      resolve(value);
+    };
+
+    handleAbort = () => {
+      finish(false);
+    };
+
+    abortSignal?.addEventListener("abort", handleAbort, { once: true });
+    if (abortSignal?.aborted) {
+      finish(false);
+      return;
+    }
+
+    timer = setTimeout(() => finish(true), delayMs);
+    timer.unref?.();
+  });
+}

package/src/audio-preflight.runtime.ts

@@ -0,0 +1,9 @@
+import { transcribeFirstAudio as transcribeFirstAudioImpl } from "openclaw/plugin-sdk/media-runtime";
+
+type TranscribeFirstAudio = typeof import("openclaw/plugin-sdk/media-runtime").transcribeFirstAudio;
+
+export async function transcribeFirstAudio(
+  ...args: Parameters<TranscribeFirstAudio>
+): ReturnType<TranscribeFirstAudio> {
+  return await transcribeFirstAudioImpl(...args);
+}

package/src/bitable.test.ts

@@ -0,0 +1,131 @@
+import type * as Lark from "@larksuiteoapi/node-sdk";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { OpenClawPluginApi } from "../runtime-api.js";
+import { createToolFactoryHarness } from "./tool-factory-test-harness.js";
+
+const createFeishuClientMock = vi.hoisted(() => vi.fn());
+
+vi.mock("./client.js", () => ({
+  createFeishuClient: createFeishuClientMock,
+}));
+
+import { registerFeishuBitableTools } from "./bitable.js";
+
+type MockRecord = {
+  record_id?: string;
+  fields?: Record<string, unknown>;
+};
+
+function createConfig(): OpenClawPluginApi["config"] {
+  return {
+    channels: {
+      feishu: {
+        enabled: true,
+        accounts: {
+          default: {
+            appId: "cli_default",
+            appSecret: "secret_default", // pragma: allowlist secret
+          },
+        },
+      },
+    },
+  } as OpenClawPluginApi["config"];
+}
+
+function createBitableClient(records: MockRecord[]) {
+  const batchDelete = vi.fn(async () => ({ code: 0 }));
+  const client = {
+    bitable: {
+      app: {
+        create: vi.fn(async () => ({
+          code: 0,
+          data: {
+            app: {
+              app_token: "app_token",
+              name: "Project Tracker",
+              url: "https://example.feishu.cn/base/app_token",
+            },
+          },
+        })),
+      },
+      appTable: {
+        list: vi.fn(async () => ({
+          code: 0,
+          data: { items: [{ table_id: "tbl_main", name: "Table 1" }] },
+        })),
+      },
+      appTableField: {
+        list: vi.fn(async () => ({ code: 0, data: { items: [] } })),
+        update: vi.fn(async () => ({ code: 0 })),
+        delete: vi.fn(async () => ({ code: 0 })),
+      },
+      appTableRecord: {
+        list: vi.fn(async () => ({ code: 0, data: { items: records } })),
+        batchDelete,
+        delete: vi.fn(async () => ({ code: 0 })),
+      },
+    },
+  } as unknown as Lark.Client;
+
+  return { batchDelete, client };
+}
+
+describe("feishu bitable create app cleanup", () => {
+  beforeEach(() => {
+    createFeishuClientMock.mockReset();
+  });
+
+  it("deletes placeholder rows whose fields contain only default empty values", async () => {
+    const { batchDelete, client } = createBitableClient([
+      { record_id: "rec_missing_fields" },
+      { record_id: "rec_empty_fields", fields: {} },
+      {
+        record_id: "rec_empty_defaults",
+        fields: {
+          Name: "",
+          Status: [],
+          Attachments: [],
+          Started: null,
+          EmptyObject: {},
+        },
+      },
+      {
+        record_id: "rec_empty_rich_text",
+        fields: { Notes: [{ type: "text", text: "" }] },
+      },
+      {
+        record_id: "rec_empty_nested",
+        fields: { Notes: { value: "", segments: [{ type: "text", text: "" }] } },
+      },
+      { record_id: "rec_text", fields: { Name: "Milestone" } },
+      { record_id: "rec_number", fields: { Estimate: 0 } },
+      { record_id: "rec_boolean", fields: { Done: false } },
+      { record_id: "rec_link", fields: { Link: { text: "", link: "https://example.com" } } },
+      { record_id: "rec_attachment", fields: { Attachments: [{ file_token: "boxcn_token" }] } },
+      { record_id: "rec_user", fields: { Assignee: [{ id: "ou_1", name: "" }] } },
+      { record_id: "rec_location", fields: { Location: { name: "", location: "116,39" } } },
+    ]);
+    createFeishuClientMock.mockReturnValue(client);
+
+    const { api, resolveTool } = createToolFactoryHarness(createConfig());
+    registerFeishuBitableTools(api);
+
+    const result = await resolveTool("feishu_bitable_create_app").execute("call", {
+      name: "Project Tracker",
+    });
+
+    expect(result.details.cleaned_placeholder_rows).toBe(5);
+    expect(batchDelete).toHaveBeenCalledWith({
+      path: { app_token: "app_token", table_id: "tbl_main" },
+      data: {
+        records: [
+          "rec_missing_fields",
+          "rec_empty_fields",
+          "rec_empty_defaults",
+          "rec_empty_rich_text",
+          "rec_empty_nested",
+        ],
+      },
+    });
+  });
+});