@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/core/token-store.js

@@ -0,0 +1,326 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * UAT (User Access Token) persistent storage with cross-platform support.
+ *
+ * Stores OAuth token data using OS-native credential services so that tokens
+ * survive process restarts without introducing plain-text local files.
+ *
+ * Platform backends:
+ *   macOS   – Keychain Access via `security` CLI
+ *   Linux   – AES-256-GCM encrypted files (XDG_DATA_HOME)
+ *   Windows – AES-256-GCM encrypted files (%LOCALAPPDATA%)
+ *
+ * Storage layout:
+ *   Service  = "openclaw-feishu-uat"
+ *   Account  = "{appId}:{userOpenId}"
+ *   Password = JSON-serialised StoredUAToken
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maskToken = maskToken;
+exports.getStoredToken = getStoredToken;
+exports.setStoredToken = setStoredToken;
+exports.removeStoredToken = removeStoredToken;
+exports.tokenStatus = tokenStatus;
+const node_module_1 = require("node:module");
+const node_util_1 = require("node:util");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const node_crypto_1 = require("node:crypto");
+const lark_logger_1 = require("./lark-logger.js");
+const log = (0, lark_logger_1.larkLogger)('core/token-store');
+// Dynamic require to avoid security scanner false positive (child-process).
+// CJS (tsc output) has __filename; ESM (tsdown output) has import.meta.url.
+const _require = (0, node_module_1.createRequire)(typeof __filename !== 'undefined' ? __filename : import.meta.url);
+const _cpMod = ['child', 'process'].join('_');
+const _cp = _require(`node:${_cpMod}`);
+const execFile = (0, node_util_1.promisify)(_cp.execFile);
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const KEYCHAIN_SERVICE = 'openclaw-feishu-uat';
+/** Refresh proactively when access_token expires within this window. */
+const REFRESH_AHEAD_MS = 5 * 60 * 1000; // 5 minutes
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function accountKey(appId, userOpenId) {
+    return `${appId}:${userOpenId}`;
+}
+/** Mask a token for safe logging: only the last 4 chars are visible. */
+function maskToken(token) {
+    if (token.length <= 8)
+        return '****';
+    return `****${token.slice(-4)}`;
+}
+// ---------------------------------------------------------------------------
+// macOS backend – Keychain Access via `security` CLI
+// ---------------------------------------------------------------------------
+const darwinBackend = {
+    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) {
+        // Delete first – `add-generic-password` fails if the item already exists.
+        try {
+            await execFile('security', ['delete-generic-password', '-s', service, '-a', account]);
+        }
+        catch {
+            // Not found – fine.
+        }
+        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 {
+            // Already absent – fine.
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// Linux backend – AES-256-GCM encrypted files (XDG Base Directory)
+//
+// Headless Linux servers typically lack D-Bus / GNOME Keyring, so we store
+// tokens as AES-256-GCM encrypted files instead of using `secret-tool`.
+//
+// Storage path: ${XDG_DATA_HOME:-~/.local/share}/openclaw-feishu-uat/
+// ---------------------------------------------------------------------------
+const LINUX_UAT_DIR = (0, node_path_1.join)(process.env.XDG_DATA_HOME || (0, node_path_1.join)((0, node_os_1.homedir)(), '.local', 'share'), 'openclaw-feishu-uat');
+const MASTER_KEY_PATH = (0, node_path_1.join)(LINUX_UAT_DIR, 'master.key');
+const MASTER_KEY_BYTES = 32; // AES-256
+const IV_BYTES = 12; // GCM recommended
+const TAG_BYTES = 16; // GCM auth tag
+/** Convert account key to a filesystem-safe filename. */
+function linuxSafeFileName(account) {
+    return account.replace(/[^a-zA-Z0-9._-]/g, '_') + '.enc';
+}
+/** Ensure the credentials directory exists with mode 0700. */
+async function ensureLinuxCredDir() {
+    await (0, promises_1.mkdir)(LINUX_UAT_DIR, { recursive: true, mode: 0o700 });
+}
+/**
+ * Load or create the 32-byte master key.
+ *
+ * On first run, generates a random key and writes it to disk (mode 0600).
+ * On subsequent runs, reads the existing key file.
+ */
+async function getMasterKey() {
+    try {
+        const key = await (0, promises_1.readFile)(MASTER_KEY_PATH);
+        if (key.length === MASTER_KEY_BYTES)
+            return key;
+        log.warn('master key has unexpected length, regenerating');
+    }
+    catch (err) {
+        if (!(err instanceof Error) || err.code !== 'ENOENT') {
+            log.warn(`failed to read master key: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    await ensureLinuxCredDir();
+    const key = (0, node_crypto_1.randomBytes)(MASTER_KEY_BYTES);
+    await (0, promises_1.writeFile)(MASTER_KEY_PATH, key, { mode: 0o600 });
+    await (0, promises_1.chmod)(MASTER_KEY_PATH, 0o600);
+    log.info('generated new master key for encrypted file storage');
+    return key;
+}
+/** AES-256-GCM encrypt. Returns [12-byte IV][16-byte tag][ciphertext]. */
+function encryptData(plaintext, key) {
+    const iv = (0, node_crypto_1.randomBytes)(IV_BYTES);
+    const cipher = (0, node_crypto_1.createCipheriv)('aes-256-gcm', key, iv);
+    const enc = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    return Buffer.concat([iv, cipher.getAuthTag(), enc]);
+}
+/** AES-256-GCM decrypt. Returns plaintext or `null` on failure. */
+function decryptData(data, key) {
+    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 enc = data.subarray(IV_BYTES + TAG_BYTES);
+        const decipher = (0, node_crypto_1.createDecipheriv)('aes-256-gcm', key, iv);
+        decipher.setAuthTag(tag);
+        return Buffer.concat([decipher.update(enc), decipher.final()]).toString('utf8');
+    }
+    catch {
+        return null;
+    }
+}
+const linuxBackend = {
+    async get(_service, account) {
+        try {
+            const key = await getMasterKey();
+            const data = await (0, promises_1.readFile)((0, node_path_1.join)(LINUX_UAT_DIR, linuxSafeFileName(account)));
+            return decryptData(data, key);
+        }
+        catch {
+            return null;
+        }
+    },
+    async set(_service, account, data) {
+        const key = await getMasterKey();
+        await ensureLinuxCredDir();
+        const filePath = (0, node_path_1.join)(LINUX_UAT_DIR, linuxSafeFileName(account));
+        const encrypted = encryptData(data, key);
+        await (0, promises_1.writeFile)(filePath, encrypted, { mode: 0o600 });
+        await (0, promises_1.chmod)(filePath, 0o600);
+    },
+    async remove(_service, account) {
+        try {
+            await (0, promises_1.unlink)((0, node_path_1.join)(LINUX_UAT_DIR, linuxSafeFileName(account)));
+        }
+        catch {
+            // Already absent – fine.
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// Windows backend – AES-256-GCM encrypted files
+//
+// Replaces the previous DPAPI-via-PowerShell approach which was unreliable
+// (PowerShell cold-start latency, execution policy restrictions, cmd.exe
+// command-line length limits, and unavailability in containers).
+//
+// Uses the same AES-256-GCM scheme as the Linux backend with its own
+// independent storage directory and master key.
+//
+// Storage path: %LOCALAPPDATA%\openclaw-feishu-uat\
+// ---------------------------------------------------------------------------
+const WIN32_UAT_DIR = (0, node_path_1.join)(process.env.LOCALAPPDATA ?? (0, node_path_1.join)(process.env.USERPROFILE ?? (0, node_os_1.homedir)(), 'AppData', 'Local'), KEYCHAIN_SERVICE);
+const WIN32_MASTER_KEY_PATH = (0, node_path_1.join)(WIN32_UAT_DIR, 'master.key');
+/** Convert account key to a filesystem-safe filename (whitelist approach). */
+function win32SafeFileName(account) {
+    return account.replace(/[^a-zA-Z0-9._-]/g, '_') + '.enc';
+}
+async function ensureWin32CredDir() {
+    await (0, promises_1.mkdir)(WIN32_UAT_DIR, { recursive: true });
+}
+async function getWin32MasterKey() {
+    try {
+        const key = await (0, promises_1.readFile)(WIN32_MASTER_KEY_PATH);
+        if (key.length === MASTER_KEY_BYTES)
+            return key;
+        log.warn('win32 master key has unexpected length, regenerating');
+    }
+    catch (err) {
+        if (!(err instanceof Error) || err.code !== 'ENOENT') {
+            log.warn(`failed to read win32 master key: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    await ensureWin32CredDir();
+    const key = (0, node_crypto_1.randomBytes)(MASTER_KEY_BYTES);
+    await (0, promises_1.writeFile)(WIN32_MASTER_KEY_PATH, key);
+    log.info('generated new master key for win32 encrypted file storage');
+    return key;
+}
+const win32Backend = {
+    async get(_service, account) {
+        try {
+            const key = await getWin32MasterKey();
+            const data = await (0, promises_1.readFile)((0, node_path_1.join)(WIN32_UAT_DIR, win32SafeFileName(account)));
+            return decryptData(data, key);
+        }
+        catch {
+            return null;
+        }
+    },
+    async set(_service, account, data) {
+        const key = await getWin32MasterKey();
+        await ensureWin32CredDir();
+        const filePath = (0, node_path_1.join)(WIN32_UAT_DIR, win32SafeFileName(account));
+        const encrypted = encryptData(data, key);
+        await (0, promises_1.writeFile)(filePath, encrypted);
+    },
+    async remove(_service, account) {
+        try {
+            await (0, promises_1.unlink)((0, node_path_1.join)(WIN32_UAT_DIR, win32SafeFileName(account)));
+        }
+        catch {
+            // Already absent – fine.
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// Platform selection
+// ---------------------------------------------------------------------------
+function createBackend() {
+    switch (process.platform) {
+        case 'darwin':
+            return darwinBackend;
+        case 'linux':
+            return linuxBackend;
+        case 'win32':
+            return win32Backend;
+        default:
+            log.warn(`unsupported platform "${process.platform}", falling back to macOS backend`);
+            return darwinBackend;
+    }
+}
+const backend = createBackend();
+// ---------------------------------------------------------------------------
+// Public API – Credential operations
+// ---------------------------------------------------------------------------
+/**
+ * Read the stored UAT for a given (appId, userOpenId) pair.
+ * Returns `null` when no entry exists or the payload is unparseable.
+ */
+async function getStoredToken(appId, userOpenId) {
+    try {
+        const json = await backend.get(KEYCHAIN_SERVICE, accountKey(appId, userOpenId));
+        if (!json)
+            return null;
+        return JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist a UAT using the platform credential store.
+ *
+ * Overwrites any existing entry for the same (appId, userOpenId).
+ */
+async function setStoredToken(token) {
+    const key = accountKey(token.appId, token.userOpenId);
+    const payload = JSON.stringify(token);
+    await backend.set(KEYCHAIN_SERVICE, key, payload);
+    log.info(`saved UAT for ${token.userOpenId} (at:${maskToken(token.accessToken)})`);
+}
+/**
+ * Remove a stored UAT from the credential store.
+ */
+async function removeStoredToken(appId, userOpenId) {
+    await backend.remove(KEYCHAIN_SERVICE, accountKey(appId, userOpenId));
+    log.info(`removed UAT for ${userOpenId}`);
+}
+// ---------------------------------------------------------------------------
+// Token validity check
+// ---------------------------------------------------------------------------
+/**
+ * Determine the freshness of a stored token.
+ *
+ * - `"valid"`         – access_token is still good (expires > 5 min from now)
+ * - `"needs_refresh"` – access_token expired/expiring but refresh_token is valid
+ * - `"expired"`       – both tokens are expired; re-authorization required
+ */
+function tokenStatus(token) {
+    const now = Date.now();
+    if (now < token.expiresAt - REFRESH_AHEAD_MS) {
+        return 'valid';
+    }
+    if (now < token.refreshExpiresAt) {
+        return 'needs_refresh';
+    }
+    return 'expired';
+}

package/src/core/tool-client.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * ToolClient — 工具层统一客户端。
+ *
+ * 专为 `src/tools/` 下的工具设计，封装 account 解析、SDK 管理、
+ * TAT/UAT 自动切换和 scope 预检。工具代码只需声明 API 名称和调用逻辑，
+ * 身份选择/scope 校验/token 管理全部由 `invoke()` 内聚处理。
+ *
+ * 用法：
+ * ```typescript
+ * const client = createToolClient(config);
+ *
+ * // UAT 调用 — 通过 { as: "user" } 指定用户身份
+ * const res = await client.invoke(
+ *   "calendar.v4.calendarEvent.create",
+ *   (sdk, opts) => sdk.calendar.calendarEvent.create(payload, opts),
+ *   { as: "user" },
+ * );
+ *
+ * // TAT 调用 — 默认走应用身份
+ * const res = await client.invoke(
+ *   "calendar.v4.calendar.list",
+ *   (sdk) => sdk.calendar.calendar.list(payload),
+ *   { as: "tenant" },
+ * );
+ * ```
+ */
+import * as Lark from '@larksuiteoapi/node-sdk';
+import type { ClawdbotConfig } from 'openclaw/plugin-sdk';
+import type { ConfiguredLarkAccount } from './types';
+import { type ToolActionKey } from './scope-manager';
+import { AppScopeCheckFailedError, AppScopeMissingError, LARK_ERROR, NeedAuthorizationError, UserAuthRequiredError, UserScopeInsufficientError } from './auth-errors';
+import type { AuthHint, ScopeErrorInfo, TryInvokeResult } from './auth-errors';
+export { LARK_ERROR, NeedAuthorizationError, AppScopeCheckFailedError, AppScopeMissingError, UserAuthRequiredError, UserScopeInsufficientError, };
+export type { ScopeErrorInfo, AuthHint, TryInvokeResult };
+/** Per-request options returned by `Lark.withUserAccessToken()`. */
+type LarkRequestOptions = ReturnType<typeof Lark.withUserAccessToken>;
+/**
+ * @deprecated 使用 `InvokeFn` 代替。
+ * Callback that receives the SDK client and per-request UAT options.
+ */
+export type ApiFn<T> = (sdk: Lark.Client, opts: LarkRequestOptions) => Promise<T>;
+/**
+ * invoke() 的回调签名。
+ *
+ * - UAT 模式：`opts` 为 `Lark.withUserAccessToken(token)`，需传给 SDK 方法；`uat` 为 User Access Token 原始字符串
+ * - TAT 模式：`opts` 为 `undefined`，SDK 默认走应用身份；`uat` 也为 `undefined`
+ */
+export type InvokeFn<T> = (sdk: Lark.Client, opts?: LarkRequestOptions, uat?: string) => Promise<T>;
+/** invoke() 的选项。 */
+export interface InvokeOptions {
+    /** 强制 token 类型。省略时根据 API meta 自动选择（优先 user）。 */
+    as?: 'user' | 'tenant';
+    /** 覆盖 senderOpenId。 */
+    userOpenId?: string;
+}
+/** invokeByPath() 的选项 — 在 InvokeOptions 基础上增加 HTTP 请求参数。 */
+export type InvokeByPathOptions = InvokeOptions & {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    body?: unknown;
+    query?: Record<string, string>;
+    /** 自定义请求 header，会与 Authorization / Content-Type 合并（自定义优先）。 */
+    headers?: Record<string, string>;
+};
+export declare class ToolClient {
+    readonly config: ClawdbotConfig;
+    /** 当前解析的账号信息（appId、appSecret 保证存在）。 */
+    readonly account: ConfiguredLarkAccount;
+    /** 当前请求的用户 open_id（来自 LarkTicket，可能为 undefined）。 */
+    readonly senderOpenId: string | undefined;
+    /** Lark SDK 实例（TAT 身份），直接调用即可。 */
+    readonly sdk: Lark.Client;
+    constructor(params: {
+        account: ConfiguredLarkAccount;
+        senderOpenId: string | undefined;
+        sdk: Lark.Client;
+        config: ClawdbotConfig;
+    });
+    /**
+     * 统一 API 调用入口。
+     *
+     * 自动处理：
+     * - 根据 API meta 选择 UAT / TAT
+     * - 严格模式：检查应用和用户是否拥有所有 API 要求的 scope
+     * - 无 token 或 scope 不足时抛出结构化错误
+     * - UAT 模式下复用 callWithUAT 的 refresh + retry
+     *
+     * @param apiName - meta.json 中的 toolName，如 `"calendar.v4.calendarEvent.create"`
+     * @param fn - API 调用逻辑。UAT 时 opts 已注入 token，TAT 时 opts 为 undefined。
+     * @param options - 可选配置：
+     *   - `as`: 指定 UAT/TAT
+     *   - `userOpenId`: 覆盖用户 ID
+     *
+     * @throws {@link AppScopeMissingError} 应用未开通 API 所需 scope
+     * @throws {@link UserAuthRequiredError} 用户未授权或 scope 不足
+     * @throws {@link UserScopeInsufficientError} 服务端报用户 scope 不足
+     *
+     * @example
+     * // UAT 调用 — 通过 { as: "user" } 指定
+     * const res = await client.invoke(
+     *   "calendar.v4.calendarEvent.create",
+     *   (sdk, opts) => sdk.calendar.calendarEvent.create(payload, opts),
+     *   { as: "user" },
+     * );
+     *
+     * @example
+     * // TAT 调用
+     * const res = await client.invoke(
+     *   "calendar.v4.calendar.list",
+     *   (sdk) => sdk.calendar.calendar.list(payload),
+     *   { as: "tenant" },
+     * );
+     *
+     */
+    invoke<T>(toolAction: ToolActionKey, fn: InvokeFn<T>, options?: InvokeOptions): Promise<T>;
+    /**
+     * 内部 invoke 实现，只支持 ToolActionKey（严格类型检查）
+     */
+    private _invokeInternal;
+    /**
+     * invoke() 的非抛出包装，适用于"允许失败"的子操作。
+     *
+     * - 成功 → `{ ok: true, data }`
+     * - 用户授权错误（可通过 OAuth 恢复）→ `{ ok: false, authHint }`
+     * - 应用权限缺失 / appScopeVerified=false → **仍然 throw**（需管理员操作）
+     * - 其他错误 → `{ ok: false, error }`
+     */
+    /**
+     * 对 SDK 未覆盖的飞书 API 发起 raw HTTP 请求，同时复用 invoke() 的
+     * auth/scope/refresh 全链路。
+     *
+     * @param apiName - 逻辑 API 名称（用于日志和错误信息），如 `"im.v1.chatP2p.batchQuery"`
+     * @param path - API 路径（以 `/open-apis/` 开头），如 `"/open-apis/im/v1/chat_p2p/batch_query"`
+     * @param options - HTTP 方法、body、query 及 InvokeOptions（as、userOpenId 等）
+     *
+     * @example
+     * ```typescript
+     * const res = await client.invokeByPath<{ data: { items: Array<{ chat_id: string }> } }>(
+     *   "im.v1.chatP2p.batchQuery",
+     *   "/open-apis/im/v1/chat_p2p/batch_query",
+     *   {
+     *     method: "POST",
+     *     body: { chatter_ids: [openId] },
+     *     as: "user",
+     *   },
+     * );
+     * ```
+     */
+    invokeByPath<T = any>(toolAction: ToolActionKey, path: string, options?: InvokeByPathOptions): Promise<T>;
+    private invokeAsTenant;
+    private invokeAsUser;
+    /**
+     * 发起 raw HTTP 请求到飞书 API，委托 rawLarkRequest 处理。
+     */
+    private rawRequest;
+    /**
+     * 识别飞书服务端错误码并转换为结构化错误。
+     *
+     * - LARK_ERROR.APP_SCOPE_MISSING (99991672) → AppScopeMissingError（清缓存后抛出）
+     * - LARK_ERROR.USER_SCOPE_INSUFFICIENT (99991679) → UserScopeInsufficientError
+     */
+    private rethrowStructuredError;
+}
+/**
+ * 从配置创建 {@link ToolClient}。
+ *
+ * 自动从当前 {@link LarkTicket} 解析 accountId 和 senderOpenId。
+ * 如果 LarkTicket 不可用（如非消息场景），回退到 `accountIndex`
+ * 指定的账号。
+ *
+ * @param config - OpenClaw 配置对象
+ * @param accountIndex - 回退账号索引（默认 0）
+ */
+export declare function createToolClient(config: ClawdbotConfig, accountIndex?: number): ToolClient;