@zhin.js/adapter-kook 1.1.26 → 1.1.27

package/src/sender-roles.ts

@@ -1,27 +1,48 @@
 /**
- * KOOK 入站发送者角色投影。
+ * KOOK 入站发送者平台身份（ADR 0056 §1）。
  *
  * 事件只携带数字角色 id，无法直接判断群主 / 管理员；这里按服务器缓存
- * guild.view（群主 id）与 guild-role.list（角色权限位），把发送者投影为
- * 跨平台规范角色 owner / admin。原始角色 id 以 `role:<id>` 形式放入 permissions，
- * 不进入 `sender.roles`。
+ * guild.view（群主 id）与 guild-role.list（角色名与权限位），把发送者归一为
+ * `sender.platform`：
+ * - `standing`：服务器主 → `owner`；持有带「管理员」权限位的角色 → `admin`；否则 `member`。
+ *   查询失败、无法判断时不上报（不猜）。
+ * - `roles`：发送者持有的服务器角色（id + 名称）。
+ * - `permissions`：「全体成员」角色（role_id 0，每个成员都持有、事件里不列出）与这些角色权限位的并集，
+ *   按 KOOK 权限名（snake_case）上报；服务器主与持有「管理员」位的成员拥有全部权限，展开为全部权限名。
+ *   机器人自身身份（`inspectSelfStanding`）走同一套规则。
  */
 import { TtlLookupCache } from 'zhin.js/adapter';
+import type { PlatformStanding } from '@zhin.js/im-contract';
 import type { KookClientTransport } from './ws.js';
 
-/** KOOK 角色权限位：0x1 = 管理员。 */
-const KOOK_ROLE_ADMIN_BIT = 1;
 const CACHE_TTL_MS = 60_000;
+/** 「全体成员」：每个成员都持有的基础角色。 */
+const EVERYONE_ROLE_ID = '0';
 
-export interface KookSenderRoleProjection {
-  /** 规范角色：owner / admin；普通成员为 undefined。 */
-  readonly role?: 'owner' | 'admin';
-  readonly permissions: readonly string[];
+/** KOOK 角色权限位（按位序，见 KOOK 开发者文档「权限说明」）。 */
+export const KOOK_ROLE_PERMISSIONS: readonly string[] = Object.freeze([
+  'administrator', 'manage_guild', 'view_audit_log', 'create_invite', 'manage_invite', 'manage_channels',
+  'kick_members', 'ban_members', 'manage_emojis', 'change_nickname', 'manage_roles', 'view_channels',
+  'send_messages', 'manage_messages', 'attach_files', 'connect_voice', 'manage_voice', 'mention_everyone',
+  'add_reaction', 'follow_reaction', 'passive_connect_voice', 'push_to_talk_only', 'free_voice_speak', 'speak',
+  'deafen_members', 'mute_members', 'manage_nicknames', 'play_music',
+]);
+
+/** KOOK 权限位 → 权限名；未知位丢弃。 */
+export function kookPermissionNames(bits: number): string[] {
+  if (!Number.isFinite(bits) || bits <= 0) return [];
+  return KOOK_ROLE_PERMISSIONS.filter((_, index) => Math.floor(bits / 2 ** index) % 2 === 1);
+}
+
+interface GuildRole {
+  readonly name?: string;
+  readonly permissions: number;
 }
 
 interface GuildSnapshot {
   readonly ownerId?: string;
-  readonly adminRoleIds: ReadonlySet<string>;
+  /** `undefined` when the role list lookup failed. */
+  readonly roles?: ReadonlyMap<string, GuildRole>;
 }
 
 export class KookSenderRoleResolver {
@@ -33,19 +54,28 @@ export class KookSenderRoleResolver {
     readonly guildId?: string;
     readonly authorId: string;
     readonly authorRoles?: readonly number[];
-  }): Promise<KookSenderRoleProjection> {
-    const roleIds = (input.authorRoles ?? []).map(String);
-    const permissions = roleIds.map((id) => `role:${id}`);
-    if (!input.guildId) return { permissions };
-
+  }): Promise<PlatformStanding | undefined> {
+    if (!input.guildId) return undefined;
+    const roleIds = [...new Set((input.authorRoles ?? []).map(String))];
     const snapshot = await this.#snapshot(input.guildId);
-    if (snapshot?.ownerId !== undefined && snapshot.ownerId === input.authorId) {
-      return { role: 'owner', permissions: [...permissions, 'guild_owner', 'guild_admin'] };
-    }
-    if (snapshot && roleIds.some((id) => snapshot.adminRoleIds.has(id))) {
-      return { role: 'admin', permissions: [...permissions, 'guild_admin'] };
-    }
-    return { permissions };
+    if (!snapshot) return undefined;
+    const held = roleIds.filter((id) => id !== EVERYONE_ROLE_ID).map((id) => ({ id, role: snapshot.roles?.get(id) }));
+    const everyone = snapshot.roles?.get(EVERYONE_ROLE_ID)?.permissions ?? 0;
+    const bits = held.reduce((sum, { role }) => sum | (role?.permissions ?? 0), everyone);
+    const roles = held.map(({ id, role }) => (role?.name ? { id, name: role.name } : { id }));
+    const isOwner = snapshot.ownerId !== undefined && snapshot.ownerId === input.authorId;
+    const isAdmin = kookPermissionNames(bits).includes('administrator');
+    // The server owner and administrators hold every permission (KOOK ignores per-bit grants for them).
+    const permissions = isOwner || isAdmin ? [...KOOK_ROLE_PERMISSIONS] : kookPermissionNames(bits);
+    // Without the owner id or the role list the standing cannot be decided; an admin role still proves admin.
+    const standing = isOwner ? 'owner' : isAdmin ? 'admin'
+      : snapshot.ownerId !== undefined && snapshot.roles ? 'member' : undefined;
+    if (!standing) return undefined;
+    return {
+      standing,
+      ...(roles.length ? { roles } : {}),
+      ...(permissions.length ? { permissions } : {}),
+    };
   }
 
   async #snapshot(guildId: string): Promise<GuildSnapshot | undefined> {
@@ -58,16 +88,18 @@ export class KookSenderRoleResolver {
     const client = this.getClient();
     if (!client) return undefined;
     let ownerId: string | undefined;
-    const adminRoleIds = new Set<string>();
+    let roles: Map<string, GuildRole> | undefined;
     try {
       const info = await client.getGuildInfo?.(guildId);
       if (info?.user_id != null && String(info.user_id)) ownerId = String(info.user_id);
     } catch { /* 保守：视为无群主信息 */ }
     try {
+      roles = new Map();
       for (const role of await client.pickGuild(guildId).getRoleList()) {
-        if ((Number(role.permissions) & KOOK_ROLE_ADMIN_BIT) !== 0) adminRoleIds.add(String(role.role_id));
+        const name = typeof (role as { name?: unknown }).name === 'string' ? (role as { name: string }).name : undefined;
+        roles.set(String(role.role_id), { ...(name ? { name } : {}), permissions: Number(role.permissions) || 0 });
       }
-    } catch { /* 保守：视为无管理员角色 */ }
-    return { ...(ownerId ? { ownerId } : {}), adminRoleIds };
+    } catch { roles = undefined; /* 保守：视为无角色信息 */ }
+    return { ...(ownerId ? { ownerId } : {}), ...(roles ? { roles } : {}) };
   }
 }

package/src/webhook.ts

@@ -2,7 +2,6 @@ import { endpointSpec, type Endpoint } from 'zhin.js/adapter';
 /**
  * KOOK webhook HTTP: verify → parse → admit.
  */
-import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import {
@@ -34,17 +33,14 @@ export function registerKookWebhookRoutes(
 ): HttpRouteRegistration[] {
   const path = handler.endpointConfig.webhookPath;
   return [
-    http.route('POST', path, async (request, response) => {
-      await handleKookWebhookRequest(request, response, handler);
-    }, { summary: 'KOOK webhook callback', tags: ['kook'] }),
+    http.route('POST', path, (request) => handleKookWebhookRequest(request, handler), { summary: 'KOOK webhook callback', tags: ['kook'] }),
   ];
 }
 
 export async function handleKookWebhookRequest(
-  request: IncomingMessage,
-  response: ServerResponse,
+  request: Request,
   handler: KookWebhookHandler,
-): Promise<void> {
+): Promise<Response> {
   try {
     const rawBody = await readRequestBody(request);
     let frame: KookWebhookFrame;
@@ -56,46 +52,32 @@ export async function handleKookWebhookRequest(
         ok: false,
         error: error instanceof Error ? error.message : String(error),
       }));
-      response.writeHead(400, { 'Content-Type': 'application/json' });
-      response.end(JSON.stringify({ message: 'Invalid webhook payload' }));
-      return;
+      return new Response(JSON.stringify({ message: 'Invalid webhook payload' }), { status: 400, headers: { 'Content-Type': 'application/json' } });
     }
 
     const event = frame.d;
     if (!event || typeof event !== 'object') {
-      response.writeHead(200, { 'Content-Type': 'application/json' });
-      response.end(JSON.stringify({ message: 'OK' }));
-      return;
+      return new Response(JSON.stringify({ message: 'OK' }), { status: 200, headers: { 'Content-Type': 'application/json' } });
     }
 
     if (isKookWebhookChallenge(event)) {
       if (!verifyKookWebhookToken(handler.endpointConfig.verifyToken, event.verify_token)) {
-        response.writeHead(403, { 'Content-Type': 'application/json' });
-        response.end(JSON.stringify({ message: 'Invalid verify_token' }));
-        return;
+        return new Response(JSON.stringify({ message: 'Invalid verify_token' }), { status: 403, headers: { 'Content-Type': 'application/json' } });
       }
-      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' } });
     }
 
     if (!verifyKookWebhookToken(handler.endpointConfig.verifyToken, event.verify_token)) {
-      response.writeHead(403, { 'Content-Type': 'application/json' });
-      response.end(JSON.stringify({ message: 'Invalid verify_token' }));
-      return;
+      return new Response(JSON.stringify({ message: 'Invalid verify_token' }), { status: 403, headers: { 'Content-Type': 'application/json' } });
     }
 
     if (!handler.isOpen) {
-      response.writeHead(503, { 'Content-Type': 'application/json' });
-      response.end(JSON.stringify({ message: 'Endpoint unavailable' }));
-      return;
+      return new Response(JSON.stringify({ message: 'Endpoint unavailable' }), { status: 503, headers: { 'Content-Type': 'application/json' } });
     }
-    await handler[endpointSpec].events.run(async () => {
+    return await handler[endpointSpec].events.run(async () => {
       if (frame.sn != null) {
         if (!handler.checkAndRememberSn(frame.sn)) {
-          response.writeHead(200, { 'Content-Type': 'application/json' });
-          response.end(JSON.stringify({ message: 'OK' }));
-          return;
+          return new Response(JSON.stringify({ message: 'OK' }), { status: 200, headers: { 'Content-Type': 'application/json' } });
         }
       }
 
@@ -103,17 +85,13 @@ export async function handleKookWebhookRequest(
         await handler.admitEvent(event);
       } catch {
         if (frame.sn != null) handler.forgetSn?.(frame.sn);
-        response.writeHead(503, { 'Content-Type': 'application/json' });
-        response.end(JSON.stringify({ message: 'Admission unavailable' }));
-        return;
+        return new Response(JSON.stringify({ message: 'Admission unavailable' }), { status: 503, headers: { 'Content-Type': 'application/json' } });
       }
 
-      response.writeHead(200, { 'Content-Type': 'application/json' });
-      response.end(JSON.stringify({ message: 'OK' }));
+      return new Response(JSON.stringify({ message: 'OK' }), { status: 200, headers: { 'Content-Type': 'application/json' } });
     });
   } catch (error) {
     logger.error('KOOK webhook error:', error);
-    response.writeHead(200, { 'Content-Type': 'application/json' });
-    response.end(JSON.stringify({ message: 'OK' }));
+    return new Response(JSON.stringify({ message: 'OK' }), { status: 200, headers: { 'Content-Type': 'application/json' } });
   }
 }