@zhin.js/adapter-lark 1.1.26 → 1.1.28

package/schema.json

@@ -14,34 +14,6 @@
       "type": "boolean",
       "default": true
     },
-    "master": {
-      "type": [
-        "string",
-        "number"
-      ],
-      "description": "框架 master（Lark/Feishu open_id or user_id；AI/工具权限、endpoint 管理）。endpoints[i].master 可逐项覆盖",
-      "x-i18n": {
-        "en": {
-          "description": "Framework masters (Lark/Feishu open_id or user_id; AI/tool permissions and endpoint management). endpoints[i].master can override this value."
-        }
-      }
-    },
-    "trusted": {
-      "type": "array",
-      "items": {
-        "type": [
-          "string",
-          "number"
-        ],
-        "description": "Trusted Lark/Feishu open_id or user_id"
-      },
-      "description": "框架 trusted 用户列表（弱于 master）。endpoints[i].trusted 可逐项追加",
-      "x-i18n": {
-        "en": {
-          "description": "Framework trusted users, below master authority. endpoints[i].trusted can add users."
-        }
-      }
-    },
     "endpoints": {
       "type": "array",
       "minItems": 1,
@@ -50,34 +22,6 @@
         "type": "object",
         "additionalProperties": false,
         "properties": {
-          "master": {
-            "type": [
-              "string",
-              "number"
-            ],
-            "description": "本 endpoint 的框架 master（Lark/Feishu open_id or user_id）；覆盖顶层 master",
-            "x-i18n": {
-              "en": {
-                "description": "Framework masters for this endpoint (Lark/Feishu open_id or user_id), overriding the top-level master list."
-              }
-            }
-          },
-          "trusted": {
-            "type": "array",
-            "items": {
-              "type": [
-                "string",
-                "number"
-              ],
-              "description": "Trusted Lark/Feishu open_id or user_id"
-            },
-            "description": "本 endpoint 的 trusted 列表",
-            "x-i18n": {
-              "en": {
-                "description": "Trusted users for this endpoint."
-              }
-            }
-          },
           "appId": {
             "type": "string",
             "description": "Lark app ID"

package/src/client.ts

@@ -2,7 +2,7 @@ import { Client as SdkClient, LoggerLevel, DefaultCache } from '@larksuiteoapi/n
 import { createLarkSdkHttpInstance } from './sdk-http.js';
 import { createLarkWebApiTransport } from './web-api-proxy.js';
 import type { LarkCardAction } from './cards.js';
-import { EndpointDeliveryError, type ConversationRef } from '@zhin.js/im-contract';
+import { EndpointDeliveryError, type ConversationRef, type PlatformStanding, type SelfStandingRequest } from '@zhin.js/im-contract';
 /**
  * LarkEndpoint — lifecycle, outbound, admit, OpenAPI helpers for agent tools.
  */
@@ -43,7 +43,6 @@ import {
   type LarkMessage,
   type ResolvedLarkConfig,
 } from './protocol.js';
-import { normalizeLarkSenderForPermit } from './platform-permit.js';
 import { registerLarkWebhookRoutes } from './webhook.js';
 import { createLarkLongConnection, type LarkLongConnectionFactory } from './long-connection.js';
 import { openLarkReplyStream, supportsLarkReplyStream } from './reply-stream.js';
@@ -93,6 +92,7 @@ export interface LarkClientApi {
 /** Feishu/Lark OpenAPI client surface carried by every Endpoint event. */
 
 const LARK_CHAT_MANAGER_CACHE_TTL_MS = 60_000;
+const LARK_CHAT_MANAGER_FAILURE_TTL_MS = 10_000;
 
 export class LarkClient extends SdkClient {
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
@@ -125,6 +125,23 @@ export class LarkClient extends SdkClient {
       `/im/v1/chats/${encodeURIComponent(groupId)}/members`,
       { params: { member_id_type: 'open_id' }, signal },
     ),
+    /**
+     * ADR 0056 §1：机器人自身在群里的地位（chat.get：群主为本应用 → owner；在 bot_manager_id_list →
+     * admin；有 owner_id 且都不是 → member）。查询失败或缺 owner_id 为未知。
+     */
+    inspectSelfStanding: async ({ conversation, signal }: SelfStandingRequest): Promise<PlatformStanding | undefined> => {
+      if (conversation.kind !== 'group') return undefined;
+      const appId = this.#options.config.appId;
+      const data = await createEndpointOperation({ signal }).run(() => this.#request(`/im/v1/chats/${encodeURIComponent(conversation.id)}`, { method: 'GET' }));
+      const info = data?.data as { owner_id?: unknown; owner_id_type?: unknown; bot_manager_id_list?: unknown } | undefined;
+      if (!info || !appId) return undefined;
+      if (info.owner_id_type === 'app_id' && info.owner_id === appId) return { standing: 'owner' };
+      const managers = Array.isArray(info.bot_manager_id_list) ? info.bot_manager_id_list.map(String) : [];
+      if (managers.includes(appId)) return { standing: 'admin' };
+      // chat.get may omit owner_id (e.g. when this app owns the group): without it the Bot is not
+      // provably a plain member, so the standing stays unknown.
+      return typeof info.owner_id === 'string' && info.owner_id ? { standing: 'member' } : undefined;
+    },
   });
   protected readonly endpointControl: EndpointControl = createRecallEndpointControl((id, signal) => this.recallMessage(id, { signal }));
   protected get endpointStreaming(): import('zhin.js/adapter').EndpointStreaming | undefined {
@@ -141,9 +158,11 @@ export class LarkClient extends SdkClient {
   readonly #lifecycle: EndpointLifecycle;
   readonly #cardSources = new Map<string, { conversation: ConversationRef; time: number }>();
   readonly #seen = new InboundDeduper({ ttlMs: 300_000, maxEntries: 10_000 });
-  readonly #chatManagers = new TtlLookupCache<string, { owner?: string; admins: ReadonlySet<string> }>({
+  readonly #chatManagers = new TtlLookupCache<string, { owner?: string; admins: ReadonlySet<string> } | undefined>({
     ttlMs: LARK_CHAT_MANAGER_CACHE_TTL_MS,
   });
+  /** chat.get failures: the standing stays unknown for a short while instead of retrying every message. */
+  readonly #chatManagerFailures = new TtlLookupCache<string, true>({ ttlMs: LARK_CHAT_MANAGER_FAILURE_TTL_MS });
   #startupGeneration = 0;
   readonly #pendingInbound: { message: LarkMessage; event: unknown }[] = [];
 
@@ -370,11 +389,10 @@ export class LarkClient extends SdkClient {
   async #emitInbound(msg: LarkMessage, conversation: ConversationRef, nativeEvent: unknown): Promise<void> {
     const chatType = resolveChatType(msg.chat_id, msg.chat_type);
     const senderId = resolveSender(msg);
-    const permit = senderId && chatType === 'group' && msg.chat_id
-      ? normalizeLarkSenderForPermit(await this.#resolveChatRole(msg.chat_id, senderId))
+    // ADR 0056 §1：群主 / 群管理员 / 成员 → sender.platform.standing（飞书群无原生角色与权限位）；未知不上报。
+    const role = senderId && chatType === 'group' && msg.chat_id
+      ? await this.#resolveChatRole(msg.chat_id, senderId)
       : undefined;
-    // 规范角色 owner / admin 进 roles；细粒度能力放 senderPermissions
-    const role = permit?.role === 'owner' || permit?.role === 'admin' ? permit.role : undefined;
     const mentioned = isLarkBotMentioned(msg);
     const replyToId = msg.parent_id || msg.root_id;
     await this.publishEvent('message.receive', {
@@ -382,36 +400,43 @@ export class LarkClient extends SdkClient {
       conversation,
       message: { conversation, id: generateMessageId(msg) },
       content: formatInboundContent(msg),
-      ...(senderId ? { sender: { id: senderId, ...(role ? { roles: [role] } : {}) } } : {}),
+      ...(senderId ? { sender: { id: senderId, ...(role ? { platform: { standing: role } } : {}) } } : {}),
       endpointId: this.#options.config.id,
       ...(mentioned ? { mentioned: true } : {}),
       ...(replyToId ? { replyTo: { id: replyToId } } : {}),
       metadata: Object.freeze({
         messageType: msg.message_type,
         chatType,
-        ...(role ? { senderRole: role } : {}),
-        ...(role && permit?.permissions?.length ? { senderPermissions: [...permit.permissions] } : {}),
       }),
     });
   }
 
-  /** 群主 / 群管理员来自 chat.get（owner_id + 管理员列表），按群缓存；失败时保守地视为普通成员。 */
-  async #resolveChatRole(chatId: string, senderId: string): Promise<{ isOwner: boolean; isAdmin: boolean }> {
+  /**
+   * 群主 / 群管理员来自 chat.get（owner_id + 管理员列表），按群缓存 60 秒。chat.get 失败时地位未知
+   * （负缓存 10 秒，不报确定的 member）；未返回 owner_id（如群主是机器人应用）时只能确认管理员，
+   * 其余发送者地位未知。
+   */
+  async #resolveChatRole(chatId: string, senderId: string): Promise<'owner' | 'admin' | 'member' | undefined> {
+    if (this.#chatManagerFailures.get(chatId)) return undefined;
     const entry = await this.#chatManagers.getOrLoad(chatId, async () => {
       const info = await this.getChatInfo(chatId) as {
         owner_id?: unknown;
         user_manager_id_list?: unknown;
       } | null;
-      const admins = Array.isArray(info?.user_manager_id_list) ? info.user_manager_id_list.map(String) : [];
+      if (!info) {
+        this.#chatManagerFailures.set(chatId, true);
+        return undefined;
+      }
+      const admins = Array.isArray(info.user_manager_id_list) ? info.user_manager_id_list.map(String) : [];
       return {
-        ...(typeof info?.owner_id === 'string' && info.owner_id ? { owner: info.owner_id } : {}),
+        ...(typeof info.owner_id === 'string' && info.owner_id ? { owner: info.owner_id } : {}),
         admins: new Set(admins) as ReadonlySet<string>,
       };
-    });
-    return {
-      isOwner: entry.owner !== undefined && entry.owner === senderId,
-      isAdmin: entry.admins.has(senderId),
-    };
+    }, { cacheWhen: entry => entry !== undefined });
+    if (!entry) return undefined;
+    if (entry.owner !== undefined && entry.owner === senderId) return 'owner';
+    if (entry.admins.has(senderId)) return 'admin';
+    return entry.owner !== undefined ? 'member' : undefined;
   }
 
   /** Only correlate callbacks to a card actually sent by this endpoint. */

package/src/index.ts

@@ -5,10 +5,10 @@ export {
   headerValue,
   larkInboundConversation,
   normalizeWebhookPath,
-  readTextBody,
   resolveChatType,
   resolveLarkConfig,
   resolveSender,
+  decryptLarkEvent,
   verifySignature,
   type AccessToken,
   type LarkEndpointConfig,
@@ -22,12 +22,7 @@ export {
 
 export { type LarkClientEventMap } from './client.js';
 
-export {
-  checkLarkPlatformPermit,
-  larkGroupPermitResolver,
-  normalizeLarkSenderForPermit,
-  platformPermit,
-} from './platform-permit.js';
+export { platformPermit } from './platform-permit.js';
 
 export {
   LarkEndpoint,

package/src/platform-permit.ts

@@ -1,50 +1,10 @@
 /**
- * 飞书 Lark platform permit
+ * 飞书 Lark platform permit helper（ADR 0056 §5）。
+ *
+ * 平台身份由适配器上报到 `sender.platform`，permit 由内置评估器（`@zhin.js/permission`）判断；
+ * 适配器不再导出自有的 permit 解析器或检查函数。
  */
-import type { PermissionSubject } from '@zhin.js/permission';
-
-const ADAPTER = 'lark';
 
 export function platformPermit(perm: string): string {
-  return `platform(${ADAPTER},${perm})`;
-}
-
-const FACTORY_PERM_MAP: Record<string, string> = {
-  scene_admin: 'chat_admin',
-  scene_owner: 'chat_owner',
-};
-
-export function larkGroupPermitResolver(logicalPerm: string): string {
-  return platformPermit(FACTORY_PERM_MAP[logicalPerm] ?? logicalPerm);
-}
-
-export function normalizeLarkSenderForPermit(input: {
-  isOwner?: boolean;
-  isAdmin?: boolean;
-}): { role?: string; permissions?: string[] } {
-  if (input.isOwner) {
-    return { role: 'owner', permissions: ['chat_owner', 'chat_admin', 'manage_managers'] };
-  }
-  if (input.isAdmin) {
-    return { role: 'admin', permissions: ['chat_admin'] };
-  }
-  return { role: 'member', permissions: [] };
+  return `platform-permission:${perm}`;
 }
-
-export function checkLarkPlatformPermit(perm: string, subject: PermissionSubject): boolean {
-  const role = subject.sender?.role?.[0];
-  const permissions = subject.sender?.permissions ?? [];
-  const has = (t: string) => permissions.includes(t);
-
-  switch (perm) {
-    case 'chat_owner':
-      return role === 'owner' || has('chat_owner');
-    case 'chat_admin':
-      return role === 'owner' || role === 'admin' || has('chat_admin') || has('chat_owner');
-    case 'manage_managers':
-      return role === 'owner' || has('chat_owner');
-    default:
-      return false;
-  }
-}
-

package/src/protocol.ts

@@ -6,8 +6,7 @@ import { validateLarkWebApiProxy } from './web-api-proxy.js';
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
 
-import { createHash, timingSafeEqual } from 'node:crypto';
-import type { IncomingMessage } from 'node:http';
+import { createDecipheriv, createHash, timingSafeEqual } from 'node:crypto';
 import { EndpointDeliveryError, isMediaRef, type ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
@@ -88,6 +87,8 @@ export interface LarkEventBody {
   readonly ts?: string;
   readonly type?: string;
   readonly challenge?: string;
+  /** Present instead of every other field when the app has an Encrypt Key. */
+  readonly encrypt?: string;
   readonly event?: {
     readonly sender?: LarkMessage['sender'];
     readonly message?: LarkMessage;
@@ -273,6 +274,22 @@ export function verifySignature(
   }
 }
 
+/**
+ * Decrypt an `{"encrypt": "..."}` webhook payload (Lark/Feishu open-platform
+ * spec): key = SHA-256(Encrypt Key), base64 payload = 16-byte IV followed by
+ * AES-256-CBC ciphertext with PKCS#7 padding. Throws when the payload cannot
+ * be decrypted with this key.
+ */
+export function decryptLarkEvent(encryptKey: string, encrypted: string): string {
+  const payload = Buffer.from(encrypted, 'base64');
+  if (payload.length <= 16 || (payload.length - 16) % 16 !== 0) {
+    throw new Error('Malformed encrypted Lark event');
+  }
+  const key = createHash('sha256').update(encryptKey).digest();
+  const decipher = createDecipheriv('aes-256-cbc', key, payload.subarray(0, 16));
+  return Buffer.concat([decipher.update(payload.subarray(16)), decipher.final()]).toString('utf8');
+}
+
 /** timing-safe 比较 webhook verification token（长度不同快速失败）。 */
 export function verifyToken(token: string, expected: string): boolean {
   try {
@@ -439,29 +456,9 @@ export function formatOutboundBody(payload: unknown, locale?: Locale): LarkSendB
 }
 
 export function headerValue(
-  headers: IncomingMessage['headers'],
+  headers: Headers,
   name: string,
 ): string {
-  const value = headers[name] ?? headers[name.toLowerCase()];
-  if (Array.isArray(value)) return value[0] ?? '';
-  return value ?? '';
+  return headers.get(name) ?? '';
 }
 
-export async function readTextBody(
-  request: IncomingMessage,
-  options: { readonly limit?: number } = {},
-): Promise<string> {
-  const limit = options.limit ?? 1_048_576;
-  const chunks: Buffer[] = [];
-  let size = 0;
-  for await (const chunk of request) {
-    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-    size += buffer.length;
-    if (size > limit) {
-      request.destroy();
-      throw new Error(`Request body exceeds ${limit} bytes`);
-    }
-    chunks.push(buffer);
-  }
-  return Buffer.concat(chunks).toString('utf8');
-}

package/src/webhook.ts

@@ -1,13 +1,13 @@
 /**
- * Lark/Feishu webhook HTTP: verification → signature → challenge/event → admit.
+ * Lark/Feishu webhook HTTP: signature → decrypt → verification token → challenge/event → admit.
  */
 import type { LarkCardAction } from './cards.js';
-import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import { readTextBody } from '@zhin.js/host-http-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import {
+  decryptLarkEvent,
   headerValue,
-  readTextBody,
   verifySignature,
   verifyToken,
   type LarkEventBody,
@@ -31,17 +31,14 @@ export function registerLarkWebhookRoutes(
 ): HttpRouteRegistration[] {
   const path = handler.config.webhookPath;
   return [
-    http.route('POST', path, async (request, response) => {
-      await handleLarkWebhookRequest(request, response, handler);
-    }, { summary: 'Lark/Feishu event webhook', tags: ['lark'] }),
+    http.route('POST', path, (request) => handleLarkWebhookRequest(request, handler), { summary: 'Lark/Feishu event webhook', tags: ['lark'] }),
   ];
 }
 
 export async function handleLarkWebhookRequest(
-  request: IncomingMessage,
-  response: ServerResponse,
+  request: Request,
   handler: LarkWebhookHandler,
-): Promise<void> {
+): Promise<Response> {
   try {
     const rawBody = await readTextBody(request);
 
@@ -49,22 +46,10 @@ export async function handleLarkWebhookRequest(
     try {
       event = JSON.parse(rawBody) as LarkEventBody;
     } catch {
-      response.writeHead(200, { 'Content-Type': 'application/json' });
-      response.end(JSON.stringify({ code: 0, msg: 'success' }));
-      return;
-    }
-
-    if (handler.config.verificationToken) {
-      const bodyToken = (event as LarkEventBody & { header?: { token?: unknown } }).header?.token ?? event.token;
-      const token = typeof bodyToken === 'string' ? bodyToken : headerValue(request.headers, 'x-lark-request-token');
-      if (!verifyToken(token, handler.config.verificationToken)) {
-        logger.warn(formatCompact({ op: 'webhook', ok: false, error: 'invalid verification token' }));
-        response.writeHead(403, { 'Content-Type': 'text/plain' });
-        response.end('Forbidden');
-        return;
-      }
+      return new Response(JSON.stringify({ code: 0, msg: 'success' }), { status: 200, headers: { 'Content-Type': 'application/json' } });
     }
 
+    // Signature first: it covers the raw (possibly encrypted) body.
     if (handler.config.encryptKey) {
       const timestamp = headerValue(request.headers, 'x-lark-request-timestamp');
       const nonce = headerValue(request.headers, 'x-lark-request-nonce');
@@ -76,12 +61,36 @@ export async function handleLarkWebhookRequest(
         || !verifySignature(handler.config.encryptKey, timestamp, nonce, rawBody, signature)
       ) {
         logger.warn(formatCompact({ op: 'webhook', ok: false, error: 'invalid signature' }));
-        response.writeHead(403, { 'Content-Type': 'text/plain' });
-        response.end('Forbidden');
-        return;
+        return new Response('Forbidden', { status: 403, headers: { 'Content-Type': 'text/plain' } });
       }
     }
 
+    if (typeof event?.encrypt === 'string') {
+      if (!handler.config.encryptKey) {
+        logger.warn(formatCompact({ op: 'webhook', ok: false, error: 'encrypted event received but encryptKey is not configured' }));
+        return new Response(JSON.stringify({ code: -1, msg: 'Encrypt key is not configured' }), { status: 400, headers: { 'Content-Type': 'application/json' } });
+      }
+      try {
+        event = JSON.parse(decryptLarkEvent(handler.config.encryptKey, event.encrypt)) as LarkEventBody;
+      } catch {
+        logger.warn(formatCompact({ op: 'webhook', ok: false, error: 'event decryption failed' }));
+        return new Response(JSON.stringify({ code: -1, msg: 'Decryption failed' }), { status: 400, headers: { 'Content-Type': 'application/json' } });
+      }
+    }
+
+    if (!event || typeof event !== 'object') {
+      return new Response(JSON.stringify({ code: 0, msg: 'success' }), { status: 200, headers: { 'Content-Type': 'application/json' } });
+    }
+
+    // Token and challenge live inside the decrypted event.
+    if (handler.config.verificationToken) {
+      const bodyToken = (event as LarkEventBody & { header?: { token?: unknown } }).header?.token ?? event.token;
+      const token = typeof bodyToken === 'string' ? bodyToken : headerValue(request.headers, 'x-lark-request-token');
+      if (!verifyToken(token, handler.config.verificationToken)) {
+        logger.warn(formatCompact({ op: 'webhook', ok: false, error: 'invalid verification token' }));
+        return new Response('Forbidden', { status: 403, headers: { 'Content-Type': 'text/plain' } });
+      }
+    }
 
     if (handler.isOpen) {
       const eventName = event.type === 'event_callback'
@@ -91,9 +100,7 @@ export async function handleLarkWebhookRequest(
     }
 
     if (event.type === 'url_verification') {
-      response.writeHead(200, { 'Content-Type': 'application/json' });
-      response.end(JSON.stringify({ challenge: event.challenge }));
-      return;
+      return new Response(JSON.stringify({ challenge: event.challenge }), { status: 200, headers: { 'Content-Type': 'application/json' } });
     }
 
     const headerEventType = (event as LarkEventBody & { header?: { event_type?: string } }).header?.event_type;
@@ -107,11 +114,9 @@ export async function handleLarkWebhookRequest(
       handler.admit(message, event);
     }
 
-    response.writeHead(200, { 'Content-Type': 'application/json' });
-    response.end(JSON.stringify({ code: 0, msg: 'success' }));
+    return new Response(JSON.stringify({ code: 0, msg: 'success' }), { status: 200, headers: { 'Content-Type': 'application/json' } });
   } catch (error) {
     logger.error('Webhook error:', error);
-    response.writeHead(500, { 'Content-Type': 'application/json' });
-    response.end(JSON.stringify({ code: -1, msg: 'Internal Server Error' }));
+    return new Response(JSON.stringify({ code: -1, msg: 'Internal Server Error' }), { status: 500, headers: { 'Content-Type': 'application/json' } });
   }
 }