@larksuite/openclaw-lark 2026.3.9

package/src/messaging/outbound/forward.js

@@ -0,0 +1,49 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Message forwarding for the Feishu/Lark channel plugin.
+ *
+ * Provides a function to forward an existing message to another chat
+ * or user using the IM Message Forward API.
+ */
+import { LarkClient } from '../../core/lark-client';
+import { normalizeFeishuTarget, resolveReceiveIdType } from '../../core/targets';
+// ---------------------------------------------------------------------------
+// forwardMessageFeishu
+// ---------------------------------------------------------------------------
+/**
+ * Forward an existing message to another chat or user.
+ *
+ * @param params.cfg       - Plugin configuration with Feishu credentials.
+ * @param params.messageId - The message ID to forward.
+ * @param params.to        - Target identifier (chat_id, open_id, or user_id).
+ * @param params.accountId - Optional account identifier for multi-account setups.
+ * @returns The send result containing the new forwarded message ID.
+ */
+export async function forwardMessageFeishu(params) {
+    const { cfg, messageId, to, accountId } = params;
+    const client = LarkClient.fromCfg(cfg, accountId).sdk;
+    const target = normalizeFeishuTarget(to);
+    if (!target) {
+        throw new Error(`[feishu-forward] Invalid target: "${to}"`);
+    }
+    const receiveIdType = resolveReceiveIdType(target);
+    const response = await client.im.message.forward({
+        path: {
+            message_id: messageId,
+        },
+        params: {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            receive_id_type: receiveIdType,
+        },
+        data: {
+            receive_id: target,
+        },
+    });
+    return {
+        messageId: response?.data?.message_id ?? '',
+        chatId: response?.data?.chat_id ?? '',
+    };
+}
+//# sourceMappingURL=forward.js.map

package/src/messaging/outbound/forward.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forward.js","sourceRoot":"","sources":["../../../../src/messaging/outbound/forward.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAEjF,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,MAK1C;IACC,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;IAEjD,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,GAAG,CAAC;IAEtD,MAAM,MAAM,GAAG,qBAAqB,CAAC,EAAE,CAAC,CAAC;IACzC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,qCAAqC,EAAE,GAAG,CAAC,CAAC;IAC9D,CAAC;IAED,MAAM,aAAa,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAEnD,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC;QAC/C,IAAI,EAAE;YACJ,UAAU,EAAE,SAAS;SACtB;QACD,MAAM,EAAE;YACN,8DAA8D;YAC9D,eAAe,EAAE,aAAoB;SACtC;QACD,IAAI,EAAE;YACJ,UAAU,EAAE,MAAM;SACnB;KACF,CAAC,CAAC;IAEH,OAAO;QACL,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,IAAI,EAAE;QAC3C,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,IAAI,EAAE;KACtC,CAAC;AACJ,CAAC"}

package/src/messaging/outbound/media-url-utils.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+export declare function normalizeMediaUrlInput(value: string): string;
+export declare function isWindowsAbsolutePath(value: string): boolean;
+export declare function isLocalMediaPath(value: string): boolean;
+export declare function safeFileUrlToPath(fileUrl: string): string;
+/**
+ * Validate that a resolved local file path falls under one of the
+ * allowed root directories.  Prevents path-traversal attacks when
+ * the AI or an external payload supplies a local media path.
+ *
+ * Semantics:
+ * - **`undefined`** — caller has not opted in to restriction; the
+ *   function is a no-op so existing behaviour is preserved.  The
+ *   caller should log a warning independently.
+ * - **`[]` (empty array)** — explicitly configured with no allowed
+ *   roots → all local access is denied.
+ * - **Non-empty array** — standard allowlist check.
+ *
+ * @param filePath   - Resolved absolute path to validate.
+ * @param localRoots - Allowed root directories.
+ * @throws {Error} When the path is not under any allowed root, or
+ *                 when `localRoots` is an empty array.
+ */
+export declare function validateLocalMediaRoots(filePath: string, localRoots: readonly string[] | undefined): void;
+export declare function resolveBaseNameFromPath(value: string): string | undefined;
+export declare function resolveFileNameFromMediaUrl(mediaUrl: string): string | undefined;
+//# sourceMappingURL=media-url-utils.d.ts.map

package/src/messaging/outbound/media-url-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-url-utils.d.ts","sourceRoot":"","sources":["../../../../src/messaging/outbound/media-url-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAmB5D;AAMD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGvD;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAOzD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,IAAI,CAwCzG;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQzE;AAED,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAwBhF"}

package/src/messaging/outbound/media-url-utils.js

@@ -0,0 +1,131 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+export function normalizeMediaUrlInput(value) {
+    let raw = value.trim();
+    // Common wrappers from markdown/chat payloads.
+    if (raw.startsWith('<') && raw.endsWith('>') && raw.length >= 2) {
+        raw = raw.slice(1, -1).trim();
+    }
+    // Strip matching surrounding quotes/backticks.
+    const first = raw[0];
+    const last = raw[raw.length - 1];
+    if (raw.length >= 2 &&
+        ((first === '"' && last === '"') || (first === "'" && last === "'") || (first === '`' && last === '`'))) {
+        raw = raw.slice(1, -1).trim();
+    }
+    return raw;
+}
+function stripQueryAndHash(value) {
+    return value.split(/[?#]/, 1)[0] ?? value;
+}
+export function isWindowsAbsolutePath(value) {
+    return /^[A-Za-z]:[\\/]/.test(value) || value.startsWith('\\\\');
+}
+export function isLocalMediaPath(value) {
+    const raw = normalizeMediaUrlInput(value);
+    return raw.startsWith('file://') || path.isAbsolute(raw) || isWindowsAbsolutePath(raw);
+}
+export function safeFileUrlToPath(fileUrl) {
+    const raw = normalizeMediaUrlInput(fileUrl);
+    try {
+        return fileURLToPath(raw);
+    }
+    catch {
+        return new URL(raw).pathname;
+    }
+}
+/**
+ * Validate that a resolved local file path falls under one of the
+ * allowed root directories.  Prevents path-traversal attacks when
+ * the AI or an external payload supplies a local media path.
+ *
+ * Semantics:
+ * - **`undefined`** — caller has not opted in to restriction; the
+ *   function is a no-op so existing behaviour is preserved.  The
+ *   caller should log a warning independently.
+ * - **`[]` (empty array)** — explicitly configured with no allowed
+ *   roots → all local access is denied.
+ * - **Non-empty array** — standard allowlist check.
+ *
+ * @param filePath   - Resolved absolute path to validate.
+ * @param localRoots - Allowed root directories.
+ * @throws {Error} When the path is not under any allowed root, or
+ *                 when `localRoots` is an empty array.
+ */
+export function validateLocalMediaRoots(filePath, localRoots) {
+    // Not configured — skip validation (backwards-compatible).
+    if (localRoots === undefined)
+        return;
+    if (localRoots.length === 0) {
+        throw new Error(`[feishu-media] Local file access denied for "${filePath}": ` +
+            `mediaLocalRoots is configured as an empty array, which blocks all local access. ` +
+            `Add allowed directories to mediaLocalRoots or use a remote URL instead.`);
+    }
+    // Resolve symlinks to prevent traversal via symlinked paths.
+    // Fall back to path.resolve when the file does not exist yet — the
+    // subsequent readFileSync will report a clear "file not found" error.
+    let resolved;
+    try {
+        resolved = fs.realpathSync(path.resolve(filePath));
+    }
+    catch {
+        resolved = path.resolve(filePath);
+    }
+    const isAllowed = localRoots.some((root) => {
+        let resolvedRoot;
+        try {
+            resolvedRoot = fs.realpathSync(path.resolve(root));
+        }
+        catch {
+            resolvedRoot = path.resolve(root);
+        }
+        // Must be exactly the root or strictly inside it (with separator).
+        return resolved === resolvedRoot || resolved.startsWith(resolvedRoot + path.sep);
+    });
+    if (!isAllowed) {
+        throw new Error(`[feishu-media] Local file access denied for "${filePath}": ` +
+            `path is not under any allowed mediaLocalRoots (${localRoots.join(', ')}). ` +
+            `Move the file to an allowed directory or use a remote URL instead.`);
+    }
+}
+export function resolveBaseNameFromPath(value) {
+    const raw = normalizeMediaUrlInput(value);
+    const cleanPath = stripQueryAndHash(raw);
+    const fileName = isWindowsAbsolutePath(cleanPath) ? path.win32.basename(cleanPath) : path.basename(cleanPath);
+    if (fileName && fileName !== '/' && fileName !== '.' && fileName !== '\\') {
+        return fileName;
+    }
+    return undefined;
+}
+export function resolveFileNameFromMediaUrl(mediaUrl) {
+    const raw = normalizeMediaUrlInput(mediaUrl);
+    if (!raw)
+        return undefined;
+    if (isLocalMediaPath(raw)) {
+        if (raw.startsWith('file://')) {
+            const fromFileUrlPath = safeFileUrlToPath(raw);
+            const fromFileUrlName = resolveBaseNameFromPath(fromFileUrlPath);
+            if (fromFileUrlName)
+                return fromFileUrlName;
+        }
+        return resolveBaseNameFromPath(raw);
+    }
+    try {
+        const parsed = new URL(raw);
+        if (parsed.protocol === 'http:' || parsed.protocol === 'https:') {
+            const fromUrlPath = path.posix.basename(parsed.pathname);
+            if (fromUrlPath && fromUrlPath !== '/')
+                return fromUrlPath;
+        }
+    }
+    catch {
+        // Not a valid URL. Continue with file path fallback.
+    }
+    return resolveBaseNameFromPath(raw);
+}
+//# sourceMappingURL=media-url-utils.js.map

package/src/messaging/outbound/media-url-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-url-utils.js","sourceRoot":"","sources":["../../../../src/messaging/outbound/media-url-utils.ts"],"names":[],"mappings":"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"}

package/src/messaging/outbound/media.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Media handling for the Feishu/Lark channel plugin.
+ *
+ * Provides functions for downloading images and file resources from
+ * Feishu messages, uploading media to the Feishu IM storage, and
+ * sending image / file messages to chats.
+ */
+import type { OpenClawConfig } from 'openclaw/plugin-sdk';
+/**
+ * Result of downloading an image from Feishu.
+ */
+export interface DownloadImageResult {
+    /** The raw image bytes. */
+    buffer: Buffer;
+    /** The MIME type of the image (e.g. "image/png"), if known. */
+    contentType?: string;
+}
+/**
+ * Result of downloading a message resource (image or file) from Feishu.
+ */
+export interface DownloadMessageResourceResult {
+    /** The raw file bytes. */
+    buffer: Buffer;
+    /** The MIME type of the resource, if known. */
+    contentType?: string;
+    /** The original file name, if available. */
+    fileName?: string;
+}
+/**
+ * Result of uploading an image to Feishu.
+ */
+export interface UploadImageResult {
+    /** The image_key assigned by Feishu, used to reference the image. */
+    imageKey: string;
+}
+/**
+ * Result of uploading a file to Feishu.
+ */
+export interface UploadFileResult {
+    /** The file_key assigned by Feishu, used to reference the file. */
+    fileKey: string;
+}
+/**
+ * Result of sending a media (image or file) message.
+ */
+export interface SendMediaResult {
+    /** Platform-assigned message ID. */
+    messageId: string;
+    /** Chat ID where the media was sent. */
+    chatId: string;
+}
+/**
+ * Download a resource (image or file) attached to a specific message.
+ *
+ * @param params.cfg       - Plugin configuration.
+ * @param params.messageId - The message the resource belongs to.
+ * @param params.fileKey   - The file_key or image_key of the resource.
+ * @param params.type      - Whether the resource is an "image" or "file".
+ * @param params.accountId - Optional account identifier.
+ * @returns The resource buffer, content type, and file name.
+ */
+export declare function downloadMessageResourceFeishu(params: {
+    cfg: OpenClawConfig;
+    messageId: string;
+    fileKey: string;
+    type: 'image' | 'file';
+    accountId?: string;
+}): Promise<DownloadMessageResourceResult>;
+/**
+ * Upload an image to Feishu IM storage.
+ *
+ * Accepts either a Buffer containing the raw image bytes or a file
+ * system path to read from.
+ *
+ * @param params.cfg       - Plugin configuration.
+ * @param params.image     - A Buffer or local file path for the image.
+ * @param params.imageType - The image usage type: "message" (default) or "avatar".
+ * @param params.accountId - Optional account identifier.
+ * @returns The assigned image_key.
+ */
+export declare function uploadImageLark(params: {
+    cfg: OpenClawConfig;
+    image: Buffer | string;
+    imageType?: 'message' | 'avatar';
+    accountId?: string;
+}): Promise<UploadImageResult>;
+/**
+ * Upload a file to Feishu IM storage.
+ *
+ * @param params.cfg       - Plugin configuration.
+ * @param params.file      - A Buffer or local file path.
+ * @param params.fileName  - The display name of the file.
+ * @param params.fileType  - Feishu file type: "opus" | "mp4" | "pdf" | "doc" | "xls" | "ppt" | "stream".
+ * @param params.duration  - Duration in milliseconds (for audio/video files).
+ * @param params.accountId - Optional account identifier.
+ * @returns The assigned file_key.
+ */
+export declare function uploadFileLark(params: {
+    cfg: OpenClawConfig;
+    file: Buffer | string;
+    fileName: string;
+    fileType: 'opus' | 'mp4' | 'pdf' | 'doc' | 'xls' | 'ppt' | 'stream';
+    duration?: number;
+    accountId?: string;
+}): Promise<UploadFileResult>;
+/**
+ * Send an image message to a chat or user.
+ *
+ * @param params.cfg              - Plugin configuration.
+ * @param params.to               - Target identifier.
+ * @param params.imageKey         - The image_key from a previous upload.
+ * @param params.replyToMessageId - Optional message ID for threaded reply.
+ * @param params.replyInThread    - When true, reply appears in thread.
+ * @param params.accountId        - Optional account identifier.
+ * @returns The send result.
+ */
+export declare function sendImageLark(params: {
+    cfg: OpenClawConfig;
+    to: string;
+    imageKey: string;
+    replyToMessageId?: string;
+    replyInThread?: boolean;
+    accountId?: string;
+}): Promise<SendMediaResult>;
+/**
+ * Send a file message to a chat or user.
+ *
+ * @param params.cfg              - Plugin configuration.
+ * @param params.to               - Target identifier.
+ * @param params.fileKey          - The file_key from a previous upload.
+ * @param params.replyToMessageId - Optional message ID for threaded reply.
+ * @param params.replyInThread    - When true, reply appears in thread.
+ * @param params.accountId        - Optional account identifier.
+ * @returns The send result.
+ */
+export declare function sendFileLark(params: {
+    cfg: OpenClawConfig;
+    to: string;
+    fileKey: string;
+    replyToMessageId?: string;
+    replyInThread?: boolean;
+    accountId?: string;
+}): Promise<SendMediaResult>;
+/**
+ * Send a video message to a chat or user.
+ *
+ * Uses `msg_type: "media"` so Feishu renders the message as a playable
+ * video instead of a file attachment.
+ *
+ * @param params.cfg              - Plugin configuration.
+ * @param params.to               - Target identifier.
+ * @param params.fileKey          - The file_key from a previous upload.
+ * @param params.replyToMessageId - Optional message ID for threaded reply.
+ * @param params.replyInThread    - When true, reply appears in thread.
+ * @param params.accountId        - Optional account identifier.
+ * @returns The send result.
+ */
+export declare function sendVideoLark(params: {
+    cfg: OpenClawConfig;
+    to: string;
+    fileKey: string;
+    replyToMessageId?: string;
+    replyInThread?: boolean;
+    accountId?: string;
+}): Promise<SendMediaResult>;
+/**
+ * Send an audio message to a chat or user.
+ *
+ * Uses `msg_type: "audio"` so Feishu renders the message as a playable
+ * voice bubble instead of a file attachment.
+ *
+ * @param params.cfg              - Plugin configuration.
+ * @param params.to               - Target identifier.
+ * @param params.fileKey          - The file_key from a previous upload.
+ * @param params.replyToMessageId - Optional message ID for threaded reply.
+ * @param params.replyInThread    - When true, reply appears in thread.
+ * @param params.accountId        - Optional account identifier.
+ * @returns The send result.
+ */
+export declare function sendAudioLark(params: {
+    cfg: OpenClawConfig;
+    to: string;
+    fileKey: string;
+    replyToMessageId?: string;
+    replyInThread?: boolean;
+    accountId?: string;
+}): Promise<SendMediaResult>;
+/**
+ * Detect the Feishu file type from a file name extension.
+ *
+ * Returns one of the Feishu-supported file type strings, or "stream"
+ * as a catch-all for unrecognised extensions.
+ *
+ * @param fileName - The file name (with extension).
+ * @returns The detected file type.
+ */
+export declare function detectFileType(fileName: string): 'opus' | 'mp4' | 'pdf' | 'doc' | 'xls' | 'ppt' | 'stream';
+/**
+ * Parse the duration (in milliseconds) from an OGG/Opus audio buffer.
+ *
+ * Scans backward from the end of the buffer to find the last OggS page
+ * header, reads the granule position (absolute sample count), and divides
+ * by 48 000 (the Opus standard sample rate) then converts to milliseconds.
+ *
+ * Returns `undefined` when the buffer cannot be parsed (e.g. truncated or
+ * not actually OGG).  This is intentionally lenient so callers can fall
+ * back gracefully.
+ */
+export declare function parseOggOpusDuration(buffer: Buffer): number | undefined;
+/**
+ * Parse the duration (in milliseconds) from an MP4 video buffer.
+ *
+ * Scans top-level boxes to locate the `moov` container, then finds the
+ * `mvhd` (Movie Header) box inside it.  The `mvhd` box stores:
+ *   - **timescale**: number of time-units per second
+ *   - **duration**: total duration in those time-units
+ *
+ * Supports both version-0 (32-bit fields) and version-1 (64-bit fields)
+ * of the `mvhd` box.
+ *
+ * Returns `undefined` when the buffer cannot be parsed (e.g. truncated,
+ * `moov` at end of a huge file not fully buffered, or not actually MP4).
+ */
+export declare function parseMp4Duration(buffer: Buffer): number | undefined;
+/**
+ * Upload and send a media file (image or general file) in one step.
+ *
+ * Accepts either a URL (remote or local `file://`) or a raw Buffer.
+ * The function determines whether the media is an image (by extension)
+ * and uses the appropriate upload/send path.
+ *
+ * @param params.cfg              - Plugin configuration.
+ * @param params.to               - Target identifier.
+ * @param params.mediaUrl         - URL of the media (http/https or local path).
+ * @param params.mediaBuffer      - Raw bytes of the media (alternative to URL).
+ * @param params.fileName         - File name (used for type detection and display).
+ * @param params.replyToMessageId - Optional message ID for threaded reply.
+ * @param params.accountId        - Optional account identifier.
+ * @returns The send result.
+ */
+export declare function uploadAndSendMediaLark(params: {
+    cfg: OpenClawConfig;
+    to: string;
+    mediaUrl?: string;
+    mediaBuffer?: Buffer;
+    fileName?: string;
+    replyToMessageId?: string;
+    replyInThread?: boolean;
+    accountId?: string;
+    /** Allowed root directories for local file access (SSRF prevention). */
+    mediaLocalRoots?: readonly string[];
+}): Promise<SendMediaResult>;
+//# sourceMappingURL=media.d.ts.map

package/src/messaging/outbound/media.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.d.ts","sourceRoot":"","sources":["../../../../src/messaging/outbound/media.ts"],"names":[],"mappings":"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"}