@larksuite/openclaw-lark 2026.3.9

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

@@ -0,0 +1,23 @@
+/** @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>;
+//# sourceMappingURL=shutdown-hooks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown-hooks.d.ts","sourceRoot":"","sources":["../../../src/core/shutdown-hooks.ts"],"names":[],"mappings":"AAWA,mCAAmC;AACnC,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,CAK1F;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,CAAC,EAAE;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACpC,GAAG,OAAO,CAAC,IAAI,CAAC,CA0BhB"}

package/src/core/shutdown-hooks.js

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: MIT
+/**
+ * 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. */
+export 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).
+ */
+export 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.
+ */
+export 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]);
+}
+//# sourceMappingURL=shutdown-hooks.js.map

package/src/core/shutdown-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown-hooks.js","sourceRoot":"","sources":["../../../src/core/shutdown-hooks.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAE/B;;;;;GAKG;AAEH,MAAM,KAAK,GAAG,IAAI,GAAG,EAA+B,CAAC;AAErD,mCAAmC;AACnC,MAAM,UAAU,mBAAmB;IACjC,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAW,EAAE,OAA4B;IAC5E,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACxB,OAAO,GAAG,EAAE;QACV,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAGxC;IACC,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO;IAE7B,MAAM,GAAG,GAAG,IAAI,EAAE,GAAG,CAAC;IACtB,MAAM,QAAQ,GAAG,IAAI,EAAE,UAAU,IAAI,IAAI,CAAC;IAE1C,GAAG,EAAE,CAAC,+BAA+B,KAAK,CAAC,IAAI,kBAAkB,CAAC,CAAC;IAEnE,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IAC5C,KAAK,CAAC,KAAK,EAAE,CAAC;IAEd,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,EAAE;QACpD,IAAI,CAAC;YACH,MAAM,OAAO,EAAE,CAAC;YAChB,GAAG,EAAE,CAAC,4BAA4B,GAAG,QAAQ,CAAC,CAAC;QACjD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,EAAE,CAAC,4BAA4B,GAAG,aAAa,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACnE,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,IAAI,KAAgD,CAAC;IACrD,MAAM,cAAc,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QACnD,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC;AACrG,CAAC"}

package/src/core/targets.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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;
+/**
+ * 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;
+//# sourceMappingURL=targets.d.ts.map

package/src/core/targets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"targets.d.ts","sourceRoot":"","sources":["../../../src/core/targets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAqB5C;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAO5D;AAMD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiBhE;AAMD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,MAAM,CAK1E;AAMD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAKlF;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;AAC9D,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAYtF;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAStD"}

package/src/core/targets.js

@@ -0,0 +1,128 @@
+/**
+ * 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.
+ */
+// ---------------------------------------------------------------------------
+// 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:';
+// ---------------------------------------------------------------------------
+// Detection
+// ---------------------------------------------------------------------------
+/**
+ * Detect the Feishu ID type from a raw identifier string.
+ *
+ * Returns `null` when the string does not match any known pattern.
+ */
+export 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.
+ */
+export function normalizeFeishuTarget(raw) {
+    if (!raw)
+        return null;
+    const trimmed = raw.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;
+}
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+/**
+ * Add the appropriate OpenClaw routing prefix to a bare Feishu identifier.
+ *
+ * When `type` is omitted, the prefix is inferred via `detectIdType`.
+ */
+export 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.
+ */
+export function resolveReceiveIdType(id) {
+    if (id.startsWith(CHAT_PREFIX))
+        return 'chat_id';
+    if (id.startsWith(OPEN_ID_PREFIX))
+        return 'open_id';
+    // Default to open_id for any other pattern (safer for outbound API calls).
+    return 'open_id';
+}
+export 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).
+ */
+export 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));
+}
+//# sourceMappingURL=targets.js.map

package/src/core/targets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"targets.js","sourceRoot":"","sources":["../../../src/core/targets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E,MAAM,WAAW,GAAG,KAAK,CAAC;AAC1B,MAAM,cAAc,GAAG,KAAK,CAAC;AAE7B,uEAAuE;AACvE,MAAM,QAAQ,GAAG,OAAO,CAAC;AACzB,MAAM,QAAQ,GAAG,OAAO,CAAC;AACzB,MAAM,WAAW,GAAG,UAAU,CAAC;AAE/B,kEAAkE;AAClE,MAAM,UAAU,GAAG,SAAS,CAAC;AAE7B,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,EAAU;IACrC,IAAI,CAAC,EAAE;QAAE,OAAO,IAAI,CAAC;IACrB,IAAI,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,SAAS,CAAC;IACjD,IAAI,EAAE,CAAC,UAAU,CAAC,cAAc,CAAC;QAAE,OAAO,SAAS,CAAC;IACpD,yEAAyE;IACzE,IAAI,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IAChD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAW;IAC/C,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IAEtB,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAE1B,mEAAmE;IACnE,IAAI,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QACnC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;QACtD,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC;IAC1B,CAAC;IAED,IAAI,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACxE,IAAI,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACxE,IAAI,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAE9E,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAAU,EAAE,IAAmB;IAChE,MAAM,QAAQ,GAAG,IAAI,IAAI,YAAY,CAAC,EAAE,CAAC,CAAC;IAE1C,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,GAAG,QAAQ,GAAG,EAAE,EAAE,CAAC;IACtD,OAAO,GAAG,QAAQ,GAAG,EAAE,EAAE,CAAC;AAC5B,CAAC;AAED,8EAA8E;AAC9E,4BAA4B;AAC5B,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,EAAU;IAC7C,IAAI,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,SAAS,CAAC;IACjD,IAAI,EAAE,CAAC,UAAU,CAAC,cAAc,CAAC;QAAE,OAAO,SAAS,CAAC;IACpD,2EAA2E;IAC3E,OAAO,SAAS,CAAC;AACnB,CAAC;AAWD,MAAM,UAAU,kBAAkB,CAAC,SAA6B;IAC9D,IAAI,CAAC,SAAS;QAAE,OAAO,SAAS,CAAC;IACjC,MAAM,UAAU,GAAG,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1C,IAAI,UAAU,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;IAC3D,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,IAAI,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IACvB,OAAO,CACL,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC;QACxB,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC;QACxB,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC;QAC3B,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC;QAC3B,GAAG,CAAC,UAAU,CAAC,cAAc,CAAC,CAC/B,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,55 @@
+/**
+ * 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';
+//# sourceMappingURL=token-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"token-store.d.ts","sourceRoot":"","sources":["../../../src/core/token-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAkBH,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAmBD,wEAAwE;AACxE,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAG/C;AAqPD;;;GAGG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAQrG;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxE;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGxF;AAMD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,GAAG,eAAe,GAAG,SAAS,CASvF"}

package/src/core/token-store.js

@@ -0,0 +1,315 @@
+/**
+ * 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
+ */
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+import { mkdir, unlink, readFile, writeFile, chmod } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { randomBytes, createCipheriv, createDecipheriv } from 'node:crypto';
+import { larkLogger } from './lark-logger';
+const log = larkLogger('core/token-store');
+const execFile = promisify(execFileCb);
+// ---------------------------------------------------------------------------
+// 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. */
+export 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 = join(process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share'), 'openclaw-feishu-uat');
+const MASTER_KEY_PATH = 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 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 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 = randomBytes(MASTER_KEY_BYTES);
+    await writeFile(MASTER_KEY_PATH, key, { mode: 0o600 });
+    await 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 = randomBytes(IV_BYTES);
+    const cipher = 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 = 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 readFile(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 = join(LINUX_UAT_DIR, linuxSafeFileName(account));
+        const encrypted = encryptData(data, key);
+        await writeFile(filePath, encrypted, { mode: 0o600 });
+        await chmod(filePath, 0o600);
+    },
+    async remove(_service, account) {
+        try {
+            await unlink(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 = join(process.env.LOCALAPPDATA ?? join(process.env.USERPROFILE ?? homedir(), 'AppData', 'Local'), KEYCHAIN_SERVICE);
+const WIN32_MASTER_KEY_PATH = 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 mkdir(WIN32_UAT_DIR, { recursive: true });
+}
+async function getWin32MasterKey() {
+    try {
+        const key = await 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 = randomBytes(MASTER_KEY_BYTES);
+    await 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 readFile(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 = join(WIN32_UAT_DIR, win32SafeFileName(account));
+        const encrypted = encryptData(data, key);
+        await writeFile(filePath, encrypted);
+    },
+    async remove(_service, account) {
+        try {
+            await unlink(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.
+ */
+export 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).
+ */
+export 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.
+ */
+export 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
+ */
+export 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';
+}
+//# sourceMappingURL=token-store.js.map