@clowder-ai/connector-wecom-agent 0.0.0-stage → 0.1.0-alpha.7

package/README.en.md

@@ -0,0 +1,56 @@
+# WeCom Agent Connector
+
+[Chinese](README.md) · English
+
+`@clowder-ai/connector-wecom-agent` packages WeCom custom-application callback verification, AES-256-CBC
+decryption, normalized text/media ingress, token refresh, message sending, media transfer, and byte-bounded
+reply chunking for a Clowder AI Host.
+
+## Configuration
+
+- `corpId` and `agentId`: WeCom enterprise and application identifiers.
+- `agentSecret`: secret used only to obtain short-lived provider access tokens.
+- `callbackToken`: secret used to authenticate callback signatures.
+- `encodingAesKey`: secret used to decrypt callback bodies and URL-verification challenges.
+
+The package does not read repository `.env` files or ambient Host configuration.
+
+## Security and authority
+
+The Host owns installation, grants, configuration, secrets, webhook admission, connector bindings, wake
+policy, delivery, and durable state. Callback bodies are accepted only after signature, decryption, and corp
+identity verification. Ordinary message text, including `@`, cannot mint a binding or wake an Agent.
+
+## Lifecycle and recovery
+
+Provider access tokens are short-lived process caches. Host webhook routing must drain before rollback so
+the package and preserved Core callback handler never consume the same event concurrently. The package does
+not persist callback bodies or credentials.
+
+The Host-loadable builtin runtime is implemented in this package and uses only the existing authenticated
+binding and declared configuration/secret surfaces. No package-local environment or persistence fallback is
+provided.
+
+Inbound provider media IDs remain in manifest-declared private plugin state. Public messages expose only a
+`pmr_*` reference plus `sourceEventId`; the declared media source returns bounded chunks and settlement
+deletes the private locator.
+
+## Supported messaging
+
+The connector supports authenticated WeCom webhooks, messages and media. It does not provide audio/AI
+services or custom UI extensions.
+
+## Commands and configuration
+
+The builtin entrypoint intercepts `/where`, `/new`, `/threads`, `/use`, `/thread`, `/commands`, `/cats`,
+`/status`, `/history`, `/unbind`, `/allow-group`, `/deny-group`, `/focus`, and `/ask` before ordinary ingress.
+Commands reply through the provider and keep their audit quiet. Only an explicit body in `/thread` or
+`/ask` requests Agent invocation; successful delivery is acknowledged only after the Host accepts it.
+`/use` traverses the owner-visible live thread inventory beyond the first 50 rows, deduplicates IDs and
+rejects a non-progressing or exhausted traversal instead of selecting from an incomplete list.
+
+This adapter supports direct conversations only. Configure the original account/login fields and receive messages;
+there is no group-permission page, permission initialization or legacy-import step. Group management commands
+do not grant a direct-message sender administrator authority. Existing stored data is not deleted.
+
+The Host owns installation, grants, credentials and lifecycle; saving configuration preserves enable intent. The language link opens a separate document and does not imply automatic language selection.

package/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# 企业微信应用连接器
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+简体中文 · [English](README.en.md)
+
+将企业微信自建应用接入 Clowder AI，支持回调验证、加密消息解密、私聊文本与媒体消息以及分段回复。
+
+## 开始使用
+
+1. 创建企业微信自建应用，在插件设置填写企业标识 `corpId` 和应用标识 `agentId`。
+2. 保存应用密钥 `agentSecret`、回调令牌 `callbackToken` 和加密密钥 `encodingAesKey`。
+3. 按宿主提供的回调地址完成企业微信端配置，然后启用插件并发送私聊消息。
+
+仅在签名、解密和企业身份校验通过后接收回调。此连接器只支持私聊，不提供群设置或权限初始化。
+
+## 消息与恢复
+
+短期访问令牌只缓存在当前进程。媒体标识保存在私有状态，对话只携带受限媒体引用。停用或切换实现时先停止回调消费，避免同一事件被两份连接器处理。包不从仓库环境文件读取凭据，也不保存原始回调正文。
+
+## 对话命令
+
+可使用 `/where`、`/new`、`/threads`、`/use`、`/thread`、`/commands`、`/cats`、`/status`、`/history`、`/unbind`、`/focus` 和 `/ask` 查看位置、切换对话或发起请求。`/thread`、`/ask` 只有显式携带正文时才请求猫执行，宿主接受投递后才确认成功。`/use` 会遍历可见对话，列表不完整时不猜测选择。
+
+`/allow-group`、`/deny-group` 仅适用于支持群聊且已配置管理员的连接器，不能通过普通私聊文本取得管理权。
+
+宿主管理安装、授权、凭据和启停；配置保存不自动改变启用意图。英文文档是独立文件，互链不代表页面已支持自动语言切换。

package/assets/icon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="WeCom agent connector">
+  <rect width="64" height="64" rx="14" fill="#7C3AED"/>
+  <path d="M17 21h30v18H31l-9 7v-7h-5z" fill="#fff"/>
+  <circle cx="26" cy="30" r="2" fill="#7C3AED"/>
+  <circle cx="38" cy="30" r="2" fill="#7C3AED"/>
+</svg>

package/dist/WeComAgentAdapter.d.ts

@@ -0,0 +1,149 @@
+/**
+ * WeCom Agent (企微自建应用) Adapter
+ * Inbound:  HTTP callback with AES-256-CBC encrypted XML → parse text/image/voice/video/file
+ * Outbound: message/send API (text/markdown/textcard) — final-only, no streaming
+ *
+ * F132 DingTalk + WeCom Chat Gateway — Phase C
+ */
+import type { ConnectorLogger, MessageEnvelope } from './types.js';
+export interface WeComAgentAttachment {
+    type: 'image' | 'file' | 'audio' | 'video';
+    /** WeCom media_id for download via /media/get */
+    mediaId: string;
+    fileName?: string;
+}
+export interface WeComAgentInboundMessage {
+    /** FromUserName (企微 userid) */
+    chatId: string;
+    text: string;
+    messageId: string;
+    senderId: string;
+    attachments?: WeComAgentAttachment[];
+}
+export interface WeComAgentAdapterOptions {
+    corpId: string;
+    agentId: string;
+    agentSecret: string;
+    /** 回调 Token for SHA1 signature verification */
+    token: string;
+    /** 回调 EncodingAESKey (43 chars, no trailing =) */
+    encodingAesKey: string;
+}
+/**
+ * Compute SHA1 signature for WeCom callback verification.
+ * sig = sha1(sort([token, timestamp, nonce, encrypt]).join(''))
+ */
+export declare function computeSignature(token: string, timestamp: string, nonce: string, encrypt: string): string;
+/**
+ * Decrypt an AES-256-CBC encrypted WeCom message.
+ * Returns { message, corpId } after PKCS7 unpadding.
+ *
+ * Layout after decryption:
+ *   [16 bytes random] [4 bytes msg_len BE] [msg_len bytes XML] [corpId bytes]
+ */
+export declare function decryptMessage(encryptedBase64: string, aesKey: Buffer, iv: Buffer): {
+    message: string;
+    receivedCorpId: string;
+};
+/**
+ * Encrypt a plaintext message for WeCom callback response.
+ * Used for echostr challenge response.
+ */
+export declare function encryptMessage(plaintext: string, aesKey: Buffer, iv: Buffer, corpId: string): string;
+export declare class WeComAgentAdapter {
+    readonly connectorId = "wecom-agent";
+    private readonly log;
+    private readonly corpId;
+    private readonly agentId;
+    private readonly agentSecret;
+    private readonly token;
+    private readonly aesKey;
+    private readonly iv;
+    private accessToken;
+    private tokenExpiresAt;
+    private fetchFn;
+    constructor(log: ConnectorLogger, options: WeComAgentAdapterOptions);
+    /**
+     * Handle GET echostr challenge for URL verification.
+     * WeCom sends: ?msg_signature=X&timestamp=T&nonce=N&echostr=E
+     * We decrypt echostr and return plaintext if signature matches.
+     */
+    verifyCallback(query: {
+        msg_signature: string;
+        timestamp: string;
+        nonce: string;
+        echostr: string;
+    }): string | null;
+    /**
+     * Verify signature and decrypt an incoming POST body (encrypted XML).
+     * Returns the decrypted XML string, or null if verification fails.
+     */
+    decryptInbound(body: string, query: {
+        msg_signature: string;
+        timestamp: string;
+        nonce: string;
+    }): string | null;
+    /**
+     * Parse decrypted XML into a normalized inbound message.
+     * Supports text, image, voice, video, file (location is logged and skipped).
+     */
+    parseEvent(decryptedXml: string): WeComAgentInboundMessage | null;
+    /**
+     * Get a valid access_token, refreshing if expired.
+     * WeCom access_token has 7200s (2h) TTL.
+     */
+    getAccessToken(): Promise<string>;
+    /** Force token refresh on next call (e.g., after 401/40001 error). */
+    invalidateToken(): void;
+    /**
+     * Send a text reply via message/send API.
+     * Long messages are chunked at TEXT_BODY_LIMIT_BYTES (2048 bytes).
+     * AC-C6: final-only mode, long reply chunking.
+     */
+    sendReply(externalChatId: string, content: string, _metadata?: Record<string, unknown>): Promise<void>;
+    /**
+     * Send a formatted reply as markdown (body) or textcard (with link).
+     * AC-C4: markdown + textcard + 图文卡片
+     */
+    sendFormattedReply(externalChatId: string, envelope: MessageEnvelope, _metadata?: Record<string, unknown>): Promise<void>;
+    /**
+     * Send a media message (image/file/audio) via temporary material upload.
+     * AC-C5: 临时素材 API 收发
+     */
+    sendMedia(externalChatId: string, payload: {
+        type: 'image' | 'file' | 'audio';
+        content: AsyncIterable<Uint8Array>;
+        fileName?: string;
+    }): Promise<void>;
+    /**
+     * Download a media file by media_id via /media/get API.
+     * AC-C5: inbound media download
+     */
+    downloadMedia(mediaId: string): Promise<Buffer>;
+    /**
+     * Upload a temporary material via /media/upload.
+     * Returns media_id on success, null on failure.
+     */
+    private uploadMedia;
+    /**
+     * Send a message via /message/send API.
+     * Handles token refresh on 40001/42001 errors.
+     */
+    private messageSend;
+    /**
+     * Split text into chunks respecting byte limit, breaking at newlines/spaces.
+     * AC-C6: long reply chunking at 2048 bytes.
+     */
+    chunkMessage(text: string, maxBytes: number): string[];
+    /** @internal */
+    _injectFetch(fn: typeof fetch): void;
+    /** @internal */
+    _injectAccessToken(token: string, expiresAt?: number): void;
+    /** @internal — expose crypto params for testing */
+    _getCryptoParams(): {
+        aesKey: Buffer;
+        iv: Buffer;
+        token: string;
+    };
+}
+//# sourceMappingURL=WeComAgentAdapter.d.ts.map

package/dist/WeComAgentAdapter.d.ts.map

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