@nextclaw/channel-plugin-feishu 0.2.16 → 0.2.17

package/src/token-store.ts

@@ -0,0 +1,211 @@
+import { execFile as execFileCb } from "node:child_process";
+import { mkdir, unlink, readFile, writeFile, chmod } from "node:fs/promises";
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+const execFile = promisify(execFileCb);
+
+export type StoredUAToken = {
+  userOpenId: string;
+  appId: string;
+  accessToken: string;
+  refreshToken: string;
+  expiresAt: number;
+  refreshExpiresAt: number;
+  scope: string;
+  grantedAt: number;
+};
+
+const KEYCHAIN_SERVICE = "nextclaw-feishu-uat";
+const REFRESH_AHEAD_MS = 5 * 60 * 1000;
+
+function accountKey(appId: string, userOpenId: string): string {
+  return `${appId}:${userOpenId}`;
+}
+
+export function maskToken(token: string): string {
+  if (token.length <= 8) {
+    return "****";
+  }
+  return `****${token.slice(-4)}`;
+}
+
+type KeychainBackend = {
+  get(service: string, account: string): Promise<string | null>;
+  set(service: string, account: string, data: string): Promise<void>;
+  remove(service: string, account: string): Promise<void>;
+};
+
+const darwinBackend: KeychainBackend = {
+  async get(service, account) {
+    try {
+      const { stdout } = await execFile("security", [
+        "find-generic-password",
+        "-s",
+        service,
+        "-a",
+        account,
+        "-w",
+      ]);
+      return stdout.trim() || null;
+    } catch {
+      return null;
+    }
+  },
+
+  async set(service, account, data) {
+    try {
+      await execFile("security", ["delete-generic-password", "-s", service, "-a", account]);
+    } catch {
+      // no-op
+    }
+    await execFile("security", [
+      "add-generic-password",
+      "-s",
+      service,
+      "-a",
+      account,
+      "-w",
+      data,
+    ]);
+  },
+
+  async remove(service, account) {
+    try {
+      await execFile("security", ["delete-generic-password", "-s", service, "-a", account]);
+    } catch {
+      // no-op
+    }
+  },
+};
+
+const STORAGE_DIR = join(
+  process.platform === "win32"
+    ? process.env.LOCALAPPDATA ?? join(process.env.USERPROFILE ?? homedir(), "AppData", "Local")
+    : process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share"),
+  KEYCHAIN_SERVICE,
+);
+const MASTER_KEY_PATH = join(STORAGE_DIR, "master.key");
+const MASTER_KEY_BYTES = 32;
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+
+function safeFileName(account: string): string {
+  return account.replace(/[^a-zA-Z0-9._-]/g, "_") + ".enc";
+}
+
+async function ensureStorageDir(): Promise<void> {
+  await mkdir(STORAGE_DIR, { recursive: true, mode: 0o700 });
+}
+
+async function getMasterKey(): Promise<Buffer> {
+  try {
+    const key = await readFile(MASTER_KEY_PATH);
+    if (key.length === MASTER_KEY_BYTES) {
+      return key;
+    }
+  } catch {
+    // ignore
+  }
+
+  await ensureStorageDir();
+  const key = randomBytes(MASTER_KEY_BYTES);
+  await writeFile(MASTER_KEY_PATH, key, { mode: 0o600 });
+  if (process.platform !== "win32") {
+    await chmod(MASTER_KEY_PATH, 0o600);
+  }
+  return key;
+}
+
+function encryptData(plaintext: string, key: Buffer): Buffer {
+  const iv = randomBytes(IV_BYTES);
+  const cipher = createCipheriv("aes-256-gcm", key, iv);
+  const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  return Buffer.concat([iv, cipher.getAuthTag(), encrypted]);
+}
+
+function decryptData(data: Buffer, key: Buffer): string | null {
+  if (data.length < IV_BYTES + TAG_BYTES) {
+    return null;
+  }
+  try {
+    const iv = data.subarray(0, IV_BYTES);
+    const tag = data.subarray(IV_BYTES, IV_BYTES + TAG_BYTES);
+    const encrypted = data.subarray(IV_BYTES + TAG_BYTES);
+    const decipher = createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(encrypted), decipher.final()]).toString("utf8");
+  } catch {
+    return null;
+  }
+}
+
+const encryptedFileBackend: KeychainBackend = {
+  async get(_service, account) {
+    try {
+      const key = await getMasterKey();
+      const data = await readFile(join(STORAGE_DIR, safeFileName(account)));
+      return decryptData(data, key);
+    } catch {
+      return null;
+    }
+  },
+
+  async set(_service, account, data) {
+    const key = await getMasterKey();
+    await ensureStorageDir();
+    const filePath = join(STORAGE_DIR, safeFileName(account));
+    const encrypted = encryptData(data, key);
+    await writeFile(filePath, encrypted, { mode: 0o600 });
+    if (process.platform !== "win32") {
+      await chmod(filePath, 0o600);
+    }
+  },
+
+  async remove(_service, account) {
+    try {
+      await unlink(join(STORAGE_DIR, safeFileName(account)));
+    } catch {
+      // no-op
+    }
+  },
+};
+
+const backend =
+  process.platform === "darwin"
+    ? darwinBackend
+    : encryptedFileBackend;
+
+export async function getStoredToken(
+  appId: string,
+  userOpenId: string,
+): Promise<StoredUAToken | null> {
+  try {
+    const json = await backend.get(KEYCHAIN_SERVICE, accountKey(appId, userOpenId));
+    return json ? (JSON.parse(json) as StoredUAToken) : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function setStoredToken(token: StoredUAToken): Promise<void> {
+  const payload = JSON.stringify(token);
+  await backend.set(KEYCHAIN_SERVICE, accountKey(token.appId, token.userOpenId), payload);
+}
+
+export async function removeStoredToken(appId: string, userOpenId: string): Promise<void> {
+  await backend.remove(KEYCHAIN_SERVICE, accountKey(appId, userOpenId));
+}
+
+export function tokenStatus(token: StoredUAToken): "valid" | "needs_refresh" | "expired" {
+  const now = Date.now();
+  if (now < token.expiresAt - REFRESH_AHEAD_MS) {
+    return "valid";
+  }
+  if (now < token.refreshExpiresAt) {
+    return "needs_refresh";
+  }
+  return "expired";
+}

package/src/tool-account-routing.test.ts

@@ -2,6 +2,7 @@ import type { OpenClawPluginApi } from "./nextclaw-sdk/feishu.js";
 import { beforeEach, describe, expect, test, vi } from "vitest";
 import { registerFeishuBitableTools } from "./bitable.js";
 import { registerFeishuDriveTools } from "./drive.js";
+import { withTicket } from "./lark-ticket.js";
 import { registerFeishuPermTools } from "./perm.js";
 import { createToolFactoryHarness } from "./tool-factory-test-harness.js";
 import { registerFeishuWikiTools } from "./wiki.js";
@@ -126,4 +127,22 @@ describe("feishu tool account routing", () => {
     expect(createFeishuClientMock.mock.calls[0]?.[0]?.appId).toBe("app-b");
     expect(createFeishuClientMock.mock.calls[1]?.[0]?.appId).toBe("app-a");
   });
+
+  test("ticket account id overrides inherited tool account selection", async () => {
+    const { api, resolveTool } = createToolFactoryHarness(createConfig({}));
+    registerFeishuBitableTools(api);
+
+    const tool = resolveTool("feishu_bitable_get_meta");
+    await withTicket(
+      {
+        accountId: "b",
+        chatId: "oc_test",
+        messageId: "om_test",
+        startTime: Date.now(),
+      },
+      () => tool.execute("call-ticket", { url: "invalid-url" }),
+    );
+
+    expect(createFeishuClientMock.mock.calls.at(-1)?.[0]?.appId).toBe("app-b");
+  });
 });

package/src/tool-account.ts

@@ -2,6 +2,7 @@ import type * as Lark from "@larksuiteoapi/node-sdk";
 import type { OpenClawPluginApi } from "./nextclaw-sdk/feishu.js";
 import { resolveFeishuAccount } from "./accounts.js";
 import { createFeishuClient } from "./client.js";
+import { getTicket } from "./lark-ticket.js";
 import { resolveToolsConfig } from "./tools-config.js";
 import type { FeishuToolsConfig, ResolvedFeishuAccount } from "./types.js";
 
@@ -21,6 +22,10 @@ function readConfiguredDefaultAccountId(config: OpenClawPluginApi["config"]): st
   return normalizeOptionalAccountId(value);
 }
 
+function readTicketAccountId(): string | undefined {
+  return normalizeOptionalAccountId(getTicket()?.accountId);
+}
+
 export function resolveFeishuToolAccount(params: {
   api: Pick<OpenClawPluginApi, "config">;
   executeParams?: AccountAwareParams;
@@ -33,6 +38,7 @@ export function resolveFeishuToolAccount(params: {
     cfg: params.api.config,
     accountId:
       normalizeOptionalAccountId(params.executeParams?.accountId) ??
+      readTicketAccountId() ??
       readConfiguredDefaultAccountId(params.api.config) ??
       normalizeOptionalAccountId(params.defaultAccountId),
   });
@@ -56,6 +62,11 @@ export function resolveAnyEnabledFeishuToolsConfig(
     drive: false,
     perm: false,
     scopes: false,
+    calendar: false,
+    task: false,
+    sheets: false,
+    oauth: false,
+    identity: false,
   };
   for (const account of accounts) {
     const cfg = resolveToolsConfig(account.config.tools);
@@ -65,6 +76,11 @@ export function resolveAnyEnabledFeishuToolsConfig(
     merged.drive = merged.drive || cfg.drive;
     merged.perm = merged.perm || cfg.perm;
     merged.scopes = merged.scopes || cfg.scopes;
+    merged.calendar = merged.calendar || cfg.calendar;
+    merged.task = merged.task || cfg.task;
+    merged.sheets = merged.sheets || cfg.sheets;
+    merged.oauth = merged.oauth || cfg.oauth;
+    merged.identity = merged.identity || cfg.identity;
   }
   return merged;
 }

package/src/tool-scopes.ts

@@ -0,0 +1,102 @@
+export type ToolActionKey =
+  | "feishu_get_user.default"
+  | "feishu_search_user.default"
+  | "feishu_calendar_calendar.list"
+  | "feishu_calendar_calendar.get"
+  | "feishu_calendar_calendar.primary"
+  | "feishu_calendar_event.create"
+  | "feishu_calendar_event.list"
+  | "feishu_calendar_event.get"
+  | "feishu_calendar_event.patch"
+  | "feishu_calendar_event.delete"
+  | "feishu_calendar_event.instance_view"
+  | "feishu_calendar_event_attendee.create"
+  | "feishu_calendar_event_attendee.list"
+  | "feishu_calendar_freebusy.list"
+  | "feishu_task_task.create"
+  | "feishu_task_task.get"
+  | "feishu_task_task.list"
+  | "feishu_task_task.patch"
+  | "feishu_task_tasklist.create"
+  | "feishu_task_tasklist.get"
+  | "feishu_task_tasklist.list"
+  | "feishu_task_tasklist.tasks"
+  | "feishu_task_tasklist.patch"
+  | "feishu_task_tasklist.add_members"
+  | "feishu_task_comment.create"
+  | "feishu_task_comment.get"
+  | "feishu_task_comment.list"
+  | "feishu_task_subtask.create"
+  | "feishu_task_subtask.list"
+  | "feishu_sheet.info"
+  | "feishu_sheet.read"
+  | "feishu_sheet.write"
+  | "feishu_sheet.append"
+  | "feishu_sheet.find"
+  | "feishu_sheet.create"
+  | "feishu_sheet.export";
+
+export const TOOL_SCOPES: Record<ToolActionKey, string[]> = {
+  "feishu_get_user.default": ["contact:contact.base:readonly", "contact:user.base:readonly"],
+  "feishu_search_user.default": ["contact:user:search"],
+  "feishu_calendar_calendar.list": ["calendar:calendar:read"],
+  "feishu_calendar_calendar.get": ["calendar:calendar:read"],
+  "feishu_calendar_calendar.primary": ["calendar:calendar:read"],
+  "feishu_calendar_event.create": [
+    "calendar:calendar.event:create",
+    "calendar:calendar.event:update",
+  ],
+  "feishu_calendar_event.list": ["calendar:calendar.event:read"],
+  "feishu_calendar_event.get": ["calendar:calendar.event:read"],
+  "feishu_calendar_event.patch": ["calendar:calendar.event:update"],
+  "feishu_calendar_event.delete": ["calendar:calendar.event:delete"],
+  "feishu_calendar_event.instance_view": ["calendar:calendar.event:read"],
+  "feishu_calendar_event_attendee.create": ["calendar:calendar.event:update"],
+  "feishu_calendar_event_attendee.list": ["calendar:calendar.event:read"],
+  "feishu_calendar_freebusy.list": ["calendar:calendar.free_busy:read"],
+  "feishu_task_task.create": ["task:task:write", "task:task:writeonly"],
+  "feishu_task_task.get": ["task:task:read", "task:task:write"],
+  "feishu_task_task.list": ["task:task:read", "task:task:write"],
+  "feishu_task_task.patch": ["task:task:write", "task:task:writeonly"],
+  "feishu_task_tasklist.create": ["task:tasklist:write"],
+  "feishu_task_tasklist.get": ["task:tasklist:read", "task:tasklist:write"],
+  "feishu_task_tasklist.list": ["task:tasklist:read", "task:tasklist:write"],
+  "feishu_task_tasklist.tasks": ["task:tasklist:read", "task:tasklist:write"],
+  "feishu_task_tasklist.patch": ["task:tasklist:write"],
+  "feishu_task_tasklist.add_members": ["task:tasklist:write"],
+  "feishu_task_comment.create": ["task:comment:write"],
+  "feishu_task_comment.get": ["task:comment:read", "task:comment:write"],
+  "feishu_task_comment.list": ["task:comment:read", "task:comment:write"],
+  "feishu_task_subtask.create": ["task:task:write"],
+  "feishu_task_subtask.list": ["task:task:read", "task:task:write"],
+  "feishu_sheet.info": ["sheets:spreadsheet.meta:read", "sheets:spreadsheet:read"],
+  "feishu_sheet.read": ["sheets:spreadsheet.meta:read", "sheets:spreadsheet:read"],
+  "feishu_sheet.write": [
+    "sheets:spreadsheet.meta:read",
+    "sheets:spreadsheet:read",
+    "sheets:spreadsheet:create",
+    "sheets:spreadsheet:write_only",
+  ],
+  "feishu_sheet.append": [
+    "sheets:spreadsheet.meta:read",
+    "sheets:spreadsheet:read",
+    "sheets:spreadsheet:create",
+    "sheets:spreadsheet:write_only",
+  ],
+  "feishu_sheet.find": ["sheets:spreadsheet.meta:read", "sheets:spreadsheet:read"],
+  "feishu_sheet.create": [
+    "sheets:spreadsheet.meta:read",
+    "sheets:spreadsheet:read",
+    "sheets:spreadsheet:create",
+    "sheets:spreadsheet:write_only",
+  ],
+  "feishu_sheet.export": ["docs:document:export"],
+};
+
+export function getRequiredScopes(toolAction: ToolActionKey): string[] {
+  return TOOL_SCOPES[toolAction] ?? [];
+}
+
+export function getAllKnownScopes(): string[] {
+  return Array.from(new Set(Object.values(TOOL_SCOPES).flat())).sort();
+}

package/src/tools-config.test.ts

@@ -8,14 +8,33 @@ describe("feishu tools config", () => {
     expect(resolved.chat).toBe(true);
   });
 
+  it("enables newly synced user tools by default", () => {
+    const resolved = resolveToolsConfig(undefined);
+    expect(resolved.calendar).toBe(true);
+    expect(resolved.task).toBe(true);
+    expect(resolved.sheets).toBe(true);
+    expect(resolved.oauth).toBe(true);
+    expect(resolved.identity).toBe(true);
+  });
+
   it("accepts tools.chat in config schema", () => {
     const parsed = FeishuConfigSchema.parse({
       enabled: true,
       tools: {
         chat: false,
+        calendar: false,
+        task: false,
+        sheets: false,
+        oauth: false,
+        identity: false,
       },
     });
 
     expect(parsed.tools?.chat).toBe(false);
+    expect(parsed.tools?.calendar).toBe(false);
+    expect(parsed.tools?.task).toBe(false);
+    expect(parsed.tools?.sheets).toBe(false);
+    expect(parsed.tools?.oauth).toBe(false);
+    expect(parsed.tools?.identity).toBe(false);
   });
 });

package/src/tools-config.ts

@@ -12,6 +12,11 @@ export const DEFAULT_TOOLS_CONFIG: Required<FeishuToolsConfig> = {
   drive: true,
   perm: false,
   scopes: true,
+  calendar: true,
+  task: true,
+  sheets: true,
+  oauth: true,
+  identity: true,
 };
 
 /**

package/src/types.ts

@@ -93,6 +93,11 @@ export type FeishuToolsConfig = {
   drive?: boolean;
   perm?: boolean;
   scopes?: boolean;
+  calendar?: boolean;
+  task?: boolean;
+  sheets?: boolean;
+  oauth?: boolean;
+  identity?: boolean;
 };
 
 export type DynamicAgentCreationConfig = {

package/src/uat-client.ts

@@ -0,0 +1,159 @@
+import { NeedAuthorizationError, REFRESH_TOKEN_RETRYABLE, TOKEN_RETRY_CODES } from "./auth-errors.js";
+import { resolveOAuthEndpoints } from "./device-flow.js";
+import { feishuFetch } from "./feishu-fetch.js";
+import {
+  getStoredToken,
+  removeStoredToken,
+  setStoredToken,
+  tokenStatus,
+  type StoredUAToken,
+} from "./token-store.js";
+import type { FeishuDomain } from "./types.js";
+
+export type UATCallOptions = {
+  userOpenId: string;
+  appId: string;
+  appSecret: string;
+  domain: FeishuDomain;
+};
+
+const refreshLocks = new Map<string, Promise<StoredUAToken | null>>();
+
+async function doRefreshToken(
+  opts: UATCallOptions,
+  stored: StoredUAToken,
+): Promise<StoredUAToken | null> {
+  if (Date.now() >= stored.refreshExpiresAt) {
+    await removeStoredToken(opts.appId, opts.userOpenId);
+    return null;
+  }
+
+  const endpoints = resolveOAuthEndpoints(opts.domain);
+  const requestBody = new URLSearchParams({
+    grant_type: "refresh_token",
+    refresh_token: stored.refreshToken,
+    client_id: opts.appId,
+    client_secret: opts.appSecret,
+  }).toString();
+
+  const callEndpoint = async () => {
+    const response = await feishuFetch(endpoints.token, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: requestBody,
+    });
+    return (await response.json()) as Record<string, unknown>;
+  };
+
+  let data = await callEndpoint();
+  const code = typeof data.code === "number" ? data.code : undefined;
+  const error = typeof data.error === "string" ? data.error : undefined;
+
+  if ((code !== undefined && code !== 0) || error) {
+    if (code !== undefined && REFRESH_TOKEN_RETRYABLE.has(code)) {
+      data = await callEndpoint();
+      const retryCode = typeof data.code === "number" ? data.code : undefined;
+      const retryError = typeof data.error === "string" ? data.error : undefined;
+      if ((retryCode !== undefined && retryCode !== 0) || retryError) {
+        await removeStoredToken(opts.appId, opts.userOpenId);
+        return null;
+      }
+    } else {
+      await removeStoredToken(opts.appId, opts.userOpenId);
+      return null;
+    }
+  }
+
+  if (!data.access_token) {
+    throw new Error("Token refresh returned no access_token");
+  }
+
+  const now = Date.now();
+  const updated: StoredUAToken = {
+    userOpenId: stored.userOpenId,
+    appId: opts.appId,
+    accessToken: String(data.access_token),
+    refreshToken: String(data.refresh_token ?? stored.refreshToken),
+    expiresAt: now + Number(data.expires_in ?? 7200) * 1000,
+    refreshExpiresAt: data.refresh_token_expires_in
+      ? now + Number(data.refresh_token_expires_in) * 1000
+      : stored.refreshExpiresAt,
+    scope: String(data.scope ?? stored.scope),
+    grantedAt: stored.grantedAt,
+  };
+  await setStoredToken(updated);
+  return updated;
+}
+
+async function refreshWithLock(
+  opts: UATCallOptions,
+  stored: StoredUAToken,
+): Promise<StoredUAToken | null> {
+  const key = `${opts.appId}:${opts.userOpenId}`;
+  const existing = refreshLocks.get(key);
+  if (existing) {
+    await existing;
+    return getStoredToken(opts.appId, opts.userOpenId);
+  }
+
+  const promise = doRefreshToken(opts, stored);
+  refreshLocks.set(key, promise);
+  try {
+    return await promise;
+  } finally {
+    refreshLocks.delete(key);
+  }
+}
+
+export async function getValidAccessToken(opts: UATCallOptions): Promise<string> {
+  const stored = await getStoredToken(opts.appId, opts.userOpenId);
+  if (!stored) {
+    throw new NeedAuthorizationError(opts.userOpenId);
+  }
+
+  const status = tokenStatus(stored);
+  if (status === "valid") {
+    return stored.accessToken;
+  }
+  if (status === "needs_refresh") {
+    const refreshed = await refreshWithLock(opts, stored);
+    if (!refreshed) {
+      throw new NeedAuthorizationError(opts.userOpenId);
+    }
+    return refreshed.accessToken;
+  }
+
+  await removeStoredToken(opts.appId, opts.userOpenId);
+  throw new NeedAuthorizationError(opts.userOpenId);
+}
+
+export async function callWithUAT<T>(
+  opts: UATCallOptions,
+  apiCall: (accessToken: string) => Promise<T>,
+): Promise<T> {
+  const accessToken = await getValidAccessToken(opts);
+  try {
+    return await apiCall(accessToken);
+  } catch (error) {
+    const code =
+      (error as { code?: number; response?: { data?: { code?: number } } }).code ??
+      (error as { response?: { data?: { code?: number } } }).response?.data?.code;
+    if (!TOKEN_RETRY_CODES.has(Number(code))) {
+      throw error;
+    }
+
+    const stored = await getStoredToken(opts.appId, opts.userOpenId);
+    if (!stored) {
+      throw new NeedAuthorizationError(opts.userOpenId);
+    }
+    const refreshed = await refreshWithLock(opts, stored);
+    if (!refreshed) {
+      throw new NeedAuthorizationError(opts.userOpenId);
+    }
+    return apiCall(refreshed.accessToken);
+  }
+}
+
+export async function revokeUAT(appId: string, userOpenId: string): Promise<void> {
+  await removeStoredToken(appId, userOpenId);
+}