@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/core/security-check.js

@@ -0,0 +1,184 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Multi-account isolation checks.
+ *
+ * Detects potentially unsafe configurations where multiple Feishu accounts
+ * belonging to different tenants (different appId) share the default agent
+ * without proper isolation via agents + bindings.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkMultiAccountIsolation = checkMultiAccountIsolation;
+exports.needsDmScopeFix = needsDmScopeFix;
+exports.getDmScopeFixCommand = getDmScopeFixCommand;
+exports.formatIsolationWarning = formatIsolationWarning;
+exports.generateIsolationFixCommands = generateIsolationFixCommands;
+exports.generateSharedAgentCommands = generateSharedAgentCommands;
+exports.collectIsolationWarnings = collectIsolationWarnings;
+exports.emitSecurityWarnings = emitSecurityWarnings;
+const accounts_1 = require("./accounts.js");
+// ---------------------------------------------------------------------------
+// Check logic
+// ---------------------------------------------------------------------------
+/**
+ * Diagnose whether multiple enabled accounts from different tenants
+ * are properly isolated via agent bindings.
+ */
+function checkMultiAccountIsolation(cfg) {
+    const accounts = (0, accounts_1.getEnabledLarkAccounts)(cfg);
+    if (accounts.length <= 1)
+        return { mode: 'not-applicable' };
+    const appIds = new Set(accounts.map((a) => (a.configured ? a.appId : undefined)).filter((id) => !!id));
+    if (appIds.size <= 1)
+        return { mode: 'not-applicable' };
+    const feishuBindings = cfg.bindings?.filter((b) => b.match?.channel === 'feishu' && b.match?.accountId);
+    if (!feishuBindings || feishuBindings.length === 0) {
+        return { mode: 'shared-implicit', accounts, unboundAccounts: accounts };
+    }
+    const boundAccountIds = new Set(feishuBindings.map((b) => b.match.accountId));
+    const unboundAccounts = accounts.filter((a) => !boundAccountIds.has(a.accountId));
+    if (unboundAccounts.length > 0) {
+        return { mode: 'shared-implicit', accounts, unboundAccounts };
+    }
+    const agentIds = new Set(feishuBindings.map((b) => b.agentId));
+    if (agentIds.size === 1) {
+        return {
+            mode: 'shared-explicit',
+            accounts,
+            sharedAgentId: agentIds.values().next().value,
+        };
+    }
+    return { mode: 'isolated', accounts };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function accountNames(accounts) {
+    return accounts.map((a) => a.name ?? a.accountId).join('、');
+}
+function isMultiTenant(cfg) {
+    const accounts = (0, accounts_1.getEnabledLarkAccounts)(cfg);
+    if (accounts.length <= 1)
+        return false;
+    const appIds = new Set(accounts.map((a) => (a.configured ? a.appId : undefined)).filter((id) => !!id));
+    return appIds.size > 1;
+}
+// ---------------------------------------------------------------------------
+// Session dmScope
+// ---------------------------------------------------------------------------
+const RECOMMENDED_DM_SCOPE = 'per-account-channel-peer';
+/**
+ * Check whether `session.dmScope` is set to per-account isolation.
+ *
+ * Without this setting, different bots talking to the same user share
+ * the same session — even if agent bindings are configured.
+ */
+function needsDmScopeFix(cfg) {
+    if (!isMultiTenant(cfg))
+        return false;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return cfg.session?.dmScope !== RECOMMENDED_DM_SCOPE;
+}
+/** Return the fix command string, or null if not needed. */
+function getDmScopeFixCommand(cfg) {
+    if (!needsDmScopeFix(cfg))
+        return null;
+    return `openclaw config set session.dmScope "${RECOMMENDED_DM_SCOPE}"`;
+}
+/** User-facing dmScope warning block (markdown). */
+function formatDmScopeWarning() {
+    return ('⚠️ **私聊消息串混**\n\n' +
+        '当同一个用户同时使用多个机器人时，不同机器人的私聊消息会混在同一段对话里，' +
+        '导致 AI 无法区分用户在跟哪个机器人说话。');
+}
+// ---------------------------------------------------------------------------
+// Warning text for /feishu doctor & /feishu start
+// ---------------------------------------------------------------------------
+/**
+ * Generate a combined warning block for doctor / start.
+ * Returns null when everything is fine.
+ */
+function formatIsolationWarning(status, cfg) {
+    const sections = [];
+    // Agent sharing warning
+    if (status.mode === 'shared-implicit') {
+        const names = accountNames(status.accounts);
+        sections.push(`⚠️ **多个机器人共用记忆，对话内容可能互相可见**\n\n` +
+            `当前 ${status.accounts.length} 个飞书机器人（${names}）共用同一个 AI 记忆。\n` +
+            `用户 A 跟机器人「${status.accounts[0].name ?? status.accounts[0].accountId}」说的话，` +
+            `可能出现在机器人「${status.accounts[1]?.name ?? status.accounts[1]?.accountId ?? '...'}」的回复中。\n\n` +
+            `👉 发送 **/feishu isolate** 一键查看修复方案`);
+    }
+    // dmScope warning
+    if (cfg && needsDmScopeFix(cfg)) {
+        sections.push(formatDmScopeWarning() + '\n\n' + '👉 发送 **/feishu isolate** 一键查看修复方案');
+    }
+    if (sections.length === 0)
+        return null;
+    return sections.join('\n\n---\n\n');
+}
+// ---------------------------------------------------------------------------
+// Fix command generation
+// ---------------------------------------------------------------------------
+/**
+ * Generate `openclaw config set` commands for per-account isolation.
+ */
+function generateIsolationFixCommands(cfg) {
+    const status = checkMultiAccountIsolation(cfg);
+    if (status.mode !== 'shared-implicit')
+        return null;
+    const accounts = status.accounts;
+    const commands = [];
+    const agentsList = accounts.map((a) => ({
+        id: `feishu-${a.accountId}`,
+        name: `飞书 ${a.name ?? a.accountId}`,
+    }));
+    commands.push(`openclaw config set agents.list '${JSON.stringify(agentsList)}' --json`);
+    const bindings = accounts.map((a) => ({
+        match: { channel: 'feishu', accountId: a.accountId },
+        agentId: `feishu-${a.accountId}`,
+    }));
+    commands.push(`openclaw config set bindings '${JSON.stringify(bindings)}' --json`);
+    const dmScopeCmd = getDmScopeFixCommand(cfg);
+    if (dmScopeCmd)
+        commands.push(dmScopeCmd);
+    commands.push('openclaw gateway restart');
+    const previewLines = accounts.map((a) => `  ${a.name ?? a.accountId}  →  独立记忆（feishu-${a.accountId}）`);
+    return { commands, preview: previewLines.join('\n') };
+}
+/**
+ * Generate commands for explicitly sharing the same agent across accounts.
+ */
+function generateSharedAgentCommands(cfg) {
+    const status = checkMultiAccountIsolation(cfg);
+    if (status.mode !== 'shared-implicit')
+        return null;
+    const accounts = status.accounts;
+    const commands = [];
+    const bindings = accounts.map((a) => ({
+        match: { channel: 'feishu', accountId: a.accountId },
+        agentId: 'default',
+    }));
+    commands.push(`openclaw config set bindings '${JSON.stringify(bindings)}' --json`);
+    const dmScopeCmd = getDmScopeFixCommand(cfg);
+    if (dmScopeCmd)
+        commands.push(dmScopeCmd);
+    commands.push('openclaw gateway restart');
+    const previewLines = accounts.map((a) => `  ${a.name ?? a.accountId}  →  共用记忆（default）`);
+    return { commands, preview: previewLines.join('\n') };
+}
+// ---------------------------------------------------------------------------
+// collectWarnings adapter (for SDK security.collectWarnings)
+// ---------------------------------------------------------------------------
+function collectIsolationWarnings(_cfg) {
+    // TODO: 产品明确多账号隔离方案后再透出告警
+    return [];
+}
+// ---------------------------------------------------------------------------
+// Startup log
+// ---------------------------------------------------------------------------
+function emitSecurityWarnings(_cfg, _logger) {
+    // TODO: 产品明确多账号隔离方案后再透出告警
+}

package/src/core/shutdown-hooks.d.ts

@@ -0,0 +1,22 @@
+/** @internal — test-only reset. */
+export declare function _resetShutdownHooks(): void;
+/**
+ * Register a cleanup callback to run during graceful shutdown.
+ *
+ * @param key - Unique identifier for this hook (duplicate keys overwrite).
+ * @param cleanup - Async function to execute on shutdown.
+ * @returns An unregister function — call it when the resource is
+ *          released normally (e.g. card streaming completes).
+ */
+export declare function registerShutdownHook(key: string, cleanup: () => Promise<void>): () => void;
+/**
+ * Drain all registered shutdown hooks (best-effort, bounded by deadline).
+ *
+ * @param opts - Optional configuration.
+ * @param opts.deadlineMs - Maximum time to wait for all hooks (default 5000).
+ * @param opts.log - Logger function for progress/error output.
+ */
+export declare function drainShutdownHooks(opts?: {
+    deadlineMs?: number;
+    log?: (...args: unknown[]) => void;
+}): Promise<void>;

package/src/core/shutdown-hooks.js

@@ -0,0 +1,61 @@
+"use strict";
+// SPDX-License-Identifier: MIT
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._resetShutdownHooks = _resetShutdownHooks;
+exports.registerShutdownHook = registerShutdownHook;
+exports.drainShutdownHooks = drainShutdownHooks;
+/**
+ * Process-level graceful shutdown hook registry.
+ *
+ * Provides a singleton Map of async cleanup callbacks, drained
+ * during graceful shutdown by the channel monitor.
+ */
+const hooks = new Map();
+/** @internal — test-only reset. */
+function _resetShutdownHooks() {
+    hooks.clear();
+}
+/**
+ * Register a cleanup callback to run during graceful shutdown.
+ *
+ * @param key - Unique identifier for this hook (duplicate keys overwrite).
+ * @param cleanup - Async function to execute on shutdown.
+ * @returns An unregister function — call it when the resource is
+ *          released normally (e.g. card streaming completes).
+ */
+function registerShutdownHook(key, cleanup) {
+    hooks.set(key, cleanup);
+    return () => {
+        hooks.delete(key);
+    };
+}
+/**
+ * Drain all registered shutdown hooks (best-effort, bounded by deadline).
+ *
+ * @param opts - Optional configuration.
+ * @param opts.deadlineMs - Maximum time to wait for all hooks (default 5000).
+ * @param opts.log - Logger function for progress/error output.
+ */
+async function drainShutdownHooks(opts) {
+    if (hooks.size === 0)
+        return;
+    const log = opts?.log;
+    const deadline = opts?.deadlineMs ?? 5000;
+    log?.(`graceful shutdown: draining ${hooks.size} cleanup hook(s)`);
+    const entries = Array.from(hooks.entries());
+    hooks.clear();
+    const promises = entries.map(async ([key, cleanup]) => {
+        try {
+            await cleanup();
+            log?.(`graceful shutdown: hook "${key}" done`);
+        }
+        catch (err) {
+            log?.(`graceful shutdown: hook "${key}" failed: ${String(err)}`);
+        }
+    });
+    let timer;
+    const timeoutPromise = new Promise((resolve) => {
+        timer = setTimeout(resolve, deadline);
+    });
+    await Promise.race([Promise.allSettled(promises).then(() => clearTimeout(timer)), timeoutPromise]);
+}

package/src/core/synthetic-target.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Synthetic IM target utilities.
+ *
+ * Some inbound flows (VC meeting-invited, other service-triggered events)
+ * do not map to a real IM chat — there is no chat_id / open_id the agent
+ * should send messages into. To keep the dispatch pipeline uniform we give
+ * these flows a sentinel chatId ("synthetic:<kind>") and teach outbound
+ * deliverers to short-circuit whenever they see this prefix. This is the
+ * same pattern used by `core/comment-target.ts` for Drive comment threads.
+ */
+/** Sentinel chatId for VC `vc.bot.meeting_invited_v1` synthetic inbound. */
+export declare const SYNTHETIC_VC_CHAT_ID = "synthetic:vc-invited";
+/**
+ * The `chatType` stamped on synthetic VC contexts.
+ *
+ * `MessageContext.chatType` is currently typed as `'p2p' | 'group'` across
+ * the plugin and widening that union touches every downstream signature.
+ * 'p2p' is the closest match (single-peer, non-group) and the outbound
+ * short-circuit gates on the sentinel chatId — not the chatType — so this
+ * choice does not produce any DMs on its own.
+ *
+ * TODO(synthetic-target): widen MessageContext.chatType to include
+ * `synthetic` once downstream signatures are audited.
+ */
+export declare const SYNTHETIC_VC_CHAT_TYPE: "p2p";
+/**
+ * Return `true` when `target` is a synthetic sentinel that outbound
+ * deliverers should not try to send an IM message to.
+ */
+export declare function isSyntheticTarget(target: string | undefined | null): boolean;

package/src/core/synthetic-target.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Synthetic IM target utilities.
+ *
+ * Some inbound flows (VC meeting-invited, other service-triggered events)
+ * do not map to a real IM chat — there is no chat_id / open_id the agent
+ * should send messages into. To keep the dispatch pipeline uniform we give
+ * these flows a sentinel chatId ("synthetic:<kind>") and teach outbound
+ * deliverers to short-circuit whenever they see this prefix. This is the
+ * same pattern used by `core/comment-target.ts` for Drive comment threads.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SYNTHETIC_VC_CHAT_TYPE = exports.SYNTHETIC_VC_CHAT_ID = void 0;
+exports.isSyntheticTarget = isSyntheticTarget;
+const SYNTHETIC_PREFIX = 'synthetic:';
+/** Sentinel chatId for VC `vc.bot.meeting_invited_v1` synthetic inbound. */
+exports.SYNTHETIC_VC_CHAT_ID = 'synthetic:vc-invited';
+/**
+ * The `chatType` stamped on synthetic VC contexts.
+ *
+ * `MessageContext.chatType` is currently typed as `'p2p' | 'group'` across
+ * the plugin and widening that union touches every downstream signature.
+ * 'p2p' is the closest match (single-peer, non-group) and the outbound
+ * short-circuit gates on the sentinel chatId — not the chatType — so this
+ * choice does not produce any DMs on its own.
+ *
+ * TODO(synthetic-target): widen MessageContext.chatType to include
+ * `synthetic` once downstream signatures are audited.
+ */
+exports.SYNTHETIC_VC_CHAT_TYPE = 'p2p';
+/**
+ * Return `true` when `target` is a synthetic sentinel that outbound
+ * deliverers should not try to send an IM message to.
+ */
+function isSyntheticTarget(target) {
+    return Boolean(target && target.startsWith(SYNTHETIC_PREFIX));
+}

package/src/core/targets.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Feishu target ID parsing and formatting utilities.
+ *
+ * Feishu uses several namespaced identifier prefixes:
+ *   - `oc_*`  -- chat (group / DM) IDs
+ *   - `ou_*`  -- open user IDs
+ *   - plain alphanumeric strings -- user IDs from the tenant directory
+ *
+ * This module provides helpers to detect, normalise, and format these IDs
+ * for both internal routing and outbound Feishu API calls.
+ */
+import type { FeishuIdType } from './types';
+/**
+ * Detect the Feishu ID type from a raw identifier string.
+ *
+ * Returns `null` when the string does not match any known pattern.
+ */
+export declare function detectIdType(id: string): FeishuIdType | null;
+/**
+ * Strip OpenClaw routing prefixes (`chat:`, `user:`, `open_id:`) from a
+ * raw target string, returning the bare Feishu identifier.
+ *
+ * Returns `null` when the input is empty or falsy.
+ */
+export declare function normalizeFeishuTarget(raw: string): string | null;
+export interface FeishuRouteTarget {
+    target: string;
+    replyToMessageId?: string;
+    threadId?: string;
+}
+export declare function parseFeishuRouteTarget(raw: string): FeishuRouteTarget;
+export declare function encodeFeishuRouteTarget(params: {
+    target: string;
+    replyToMessageId?: string;
+    threadId?: string | number | null;
+}): string;
+/**
+ * Add the appropriate OpenClaw routing prefix to a bare Feishu identifier.
+ *
+ * When `type` is omitted, the prefix is inferred via `detectIdType`.
+ */
+export declare function formatFeishuTarget(id: string, type?: FeishuIdType): string;
+/**
+ * Determine the `receive_id_type` query parameter for the Feishu send-message
+ * API based on the target identifier.
+ */
+export declare function resolveReceiveIdType(id: string): 'chat_id' | 'open_id' | 'user_id';
+/**
+ * 规范化 message_id，去除合成后缀（如 `om_xxx:auth-complete` → `om_xxx`）。
+ */
+export declare function normalizeMessageId(messageId: string): string;
+export declare function normalizeMessageId(messageId: string | undefined): string | undefined;
+/**
+ * Return `true` when a raw string looks like it could be a Feishu target
+ * (either an OpenClaw-tagged form or a native prefix).
+ */
+export declare function looksLikeFeishuId(raw: string): boolean;

package/src/core/targets.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Feishu target ID parsing and formatting utilities.
+ *
+ * Feishu uses several namespaced identifier prefixes:
+ *   - `oc_*`  -- chat (group / DM) IDs
+ *   - `ou_*`  -- open user IDs
+ *   - plain alphanumeric strings -- user IDs from the tenant directory
+ *
+ * This module provides helpers to detect, normalise, and format these IDs
+ * for both internal routing and outbound Feishu API calls.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectIdType = detectIdType;
+exports.normalizeFeishuTarget = normalizeFeishuTarget;
+exports.parseFeishuRouteTarget = parseFeishuRouteTarget;
+exports.encodeFeishuRouteTarget = encodeFeishuRouteTarget;
+exports.formatFeishuTarget = formatFeishuTarget;
+exports.resolveReceiveIdType = resolveReceiveIdType;
+exports.normalizeMessageId = normalizeMessageId;
+exports.looksLikeFeishuId = looksLikeFeishuId;
+// ---------------------------------------------------------------------------
+// Known prefix patterns
+// ---------------------------------------------------------------------------
+const CHAT_PREFIX = 'oc_';
+const OPEN_ID_PREFIX = 'ou_';
+// Canonical routing prefixes used inside OpenClaw (not Feishu-native).
+const TAG_CHAT = 'chat:';
+const TAG_USER = 'user:';
+const TAG_OPEN_ID = 'open_id:';
+// Feishu channel prefix (used by SDK for some routing scenarios).
+const TAG_FEISHU = 'feishu:';
+const ROUTE_META_FRAGMENT_REPLY_TO = '__feishu_reply_to';
+const ROUTE_META_FRAGMENT_THREAD_ID = '__feishu_thread_id';
+// ---------------------------------------------------------------------------
+// Detection
+// ---------------------------------------------------------------------------
+/**
+ * Detect the Feishu ID type from a raw identifier string.
+ *
+ * Returns `null` when the string does not match any known pattern.
+ */
+function detectIdType(id) {
+    if (!id)
+        return null;
+    if (id.startsWith(CHAT_PREFIX))
+        return 'chat_id';
+    if (id.startsWith(OPEN_ID_PREFIX))
+        return 'open_id';
+    // Plain alphanumeric strings (no prefix) are treated as tenant user IDs.
+    if (/^[a-zA-Z0-9]+$/.test(id))
+        return 'user_id';
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Normalisation
+// ---------------------------------------------------------------------------
+/**
+ * Strip OpenClaw routing prefixes (`chat:`, `user:`, `open_id:`) from a
+ * raw target string, returning the bare Feishu identifier.
+ *
+ * Returns `null` when the input is empty or falsy.
+ */
+function normalizeFeishuTarget(raw) {
+    if (!raw)
+        return null;
+    const trimmed = parseFeishuRouteTarget(raw).target.trim();
+    if (!trimmed)
+        return null;
+    // Handle Feishu channel prefix (e.g., "feishu:ou_xxx" -> "ou_xxx")
+    if (trimmed.startsWith(TAG_FEISHU)) {
+        const inner = trimmed.slice(TAG_FEISHU.length).trim();
+        if (inner)
+            return inner;
+    }
+    if (trimmed.startsWith(TAG_CHAT))
+        return trimmed.slice(TAG_CHAT.length);
+    if (trimmed.startsWith(TAG_USER))
+        return trimmed.slice(TAG_USER.length);
+    if (trimmed.startsWith(TAG_OPEN_ID))
+        return trimmed.slice(TAG_OPEN_ID.length);
+    return trimmed;
+}
+function parseFeishuRouteTarget(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return { target: '' };
+    const hashIndex = trimmed.indexOf('#');
+    if (hashIndex < 0)
+        return { target: trimmed };
+    const target = trimmed.slice(0, hashIndex).trim();
+    const fragment = trimmed.slice(hashIndex + 1).trim();
+    if (!fragment)
+        return { target };
+    const params = new URLSearchParams(fragment);
+    const replyToMessageId = normalizeMessageId(params.get(ROUTE_META_FRAGMENT_REPLY_TO)?.trim() || undefined);
+    const threadId = params.get(ROUTE_META_FRAGMENT_THREAD_ID)?.trim() || undefined;
+    return {
+        target,
+        ...(replyToMessageId ? { replyToMessageId } : {}),
+        ...(threadId ? { threadId } : {}),
+    };
+}
+function encodeFeishuRouteTarget(params) {
+    const target = params.target.trim();
+    if (!target)
+        return target;
+    const replyToMessageId = normalizeMessageId(params.replyToMessageId?.trim() || undefined);
+    const threadId = params.threadId != null && String(params.threadId).trim() !== '' ? String(params.threadId).trim() : undefined;
+    if (!replyToMessageId && !threadId)
+        return target;
+    const fragment = new URLSearchParams();
+    if (replyToMessageId)
+        fragment.set(ROUTE_META_FRAGMENT_REPLY_TO, replyToMessageId);
+    if (threadId)
+        fragment.set(ROUTE_META_FRAGMENT_THREAD_ID, threadId);
+    return `${target}#${fragment.toString()}`;
+}
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+/**
+ * Add the appropriate OpenClaw routing prefix to a bare Feishu identifier.
+ *
+ * When `type` is omitted, the prefix is inferred via `detectIdType`.
+ */
+function formatFeishuTarget(id, type) {
+    const resolved = type ?? detectIdType(id);
+    if (resolved === 'chat_id')
+        return `${TAG_CHAT}${id}`;
+    return `${TAG_USER}${id}`;
+}
+// ---------------------------------------------------------------------------
+// API receive-ID resolution
+// ---------------------------------------------------------------------------
+/**
+ * Determine the `receive_id_type` query parameter for the Feishu send-message
+ * API based on the target identifier.
+ */
+function resolveReceiveIdType(id) {
+    if (id.startsWith(CHAT_PREFIX))
+        return 'chat_id';
+    if (id.startsWith(OPEN_ID_PREFIX))
+        return 'open_id';
+    return 'open_id';
+}
+function normalizeMessageId(messageId) {
+    if (!messageId)
+        return undefined;
+    const colonIndex = messageId.indexOf(':');
+    if (colonIndex >= 0)
+        return messageId.slice(0, colonIndex);
+    return messageId;
+}
+// ---------------------------------------------------------------------------
+// Quick predicate
+// ---------------------------------------------------------------------------
+/**
+ * Return `true` when a raw string looks like it could be a Feishu target
+ * (either an OpenClaw-tagged form or a native prefix).
+ */
+function looksLikeFeishuId(raw) {
+    if (!raw)
+        return false;
+    return (raw.startsWith(TAG_CHAT) ||
+        raw.startsWith(TAG_USER) ||
+        raw.startsWith(TAG_OPEN_ID) ||
+        raw.startsWith(CHAT_PREFIX) ||
+        raw.startsWith(OPEN_ID_PREFIX));
+}

package/src/core/token-store.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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
+ */
+export interface StoredUAToken {
+    userOpenId: string;
+    appId: string;
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+    refreshExpiresAt: number;
+    scope: string;
+    grantedAt: number;
+}
+/** Mask a token for safe logging: only the last 4 chars are visible. */
+export declare function maskToken(token: string): string;
+/**
+ * Read the stored UAT for a given (appId, userOpenId) pair.
+ * Returns `null` when no entry exists or the payload is unparseable.
+ */
+export declare function getStoredToken(appId: string, userOpenId: string): Promise<StoredUAToken | null>;
+/**
+ * Persist a UAT using the platform credential store.
+ *
+ * Overwrites any existing entry for the same (appId, userOpenId).
+ */
+export declare function setStoredToken(token: StoredUAToken): Promise<void>;
+/**
+ * Remove a stored UAT from the credential store.
+ */
+export declare function removeStoredToken(appId: string, userOpenId: string): Promise<void>;
+/**
+ * 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
+ */
+export declare function tokenStatus(token: StoredUAToken): 'valid' | 'needs_refresh' | 'expired';