@zhin.js/adapter-napcat 1.1.26 → 1.1.28

package/plugin.js

@@ -1,6 +1,5 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { definePlugin } from 'zhin.js';
-import { permissionHostToken, createSceneRolePlatformChecker } from '@zhin.js/permission';
 import { createNapcatConsoleRpc } from "./lib/console.js";
 export default definePlugin({
     name: 'napcat',
@@ -9,12 +8,8 @@ export default definePlugin({
         displayName: 'NapCat Adapter',
     },
     setup(context) {
-        const dispose = context.resources.has(permissionHostToken)
-            ? context.resources.use(permissionHostToken).registerPlatform('napcat', createSceneRolePlatformChecker())
-            : undefined;
         return {
             consoleRpc: createNapcatConsoleRpc(context.resources, () => context.config.get()),
-            ...(dispose ? { dispose } : {}),
         };
     },
 });

package/schema.json

@@ -25,34 +25,6 @@
       "type": "number",
       "default": 30000
     },
-    "master": {
-      "type": [
-        "string",
-        "number"
-      ],
-      "description": "框架 master（QQ uin；AI/工具权限、endpoint 管理）。endpoints[i].master 可逐项覆盖",
-      "x-i18n": {
-        "en": {
-          "description": "Framework masters (QQ uin; AI/tool permissions and endpoint management). endpoints[i].master can override this value."
-        }
-      }
-    },
-    "trusted": {
-      "type": "array",
-      "items": {
-        "type": [
-          "string",
-          "number"
-        ],
-        "description": "Trusted QQ uin"
-      },
-      "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,
@@ -61,34 +33,6 @@
         "type": "object",
         "additionalProperties": false,
         "properties": {
-          "master": {
-            "type": [
-              "string",
-              "number"
-            ],
-            "description": "本 endpoint 的框架 master（QQ uin）；覆盖顶层 master",
-            "x-i18n": {
-              "en": {
-                "description": "Framework masters for this endpoint (QQ uin), overriding the top-level master list."
-              }
-            }
-          },
-          "trusted": {
-            "type": "array",
-            "items": {
-              "type": [
-                "string",
-                "number"
-              ],
-              "description": "Trusted QQ uin"
-            },
-            "description": "本 endpoint 的 trusted 列表",
-            "x-i18n": {
-              "en": {
-                "description": "Trusted users for this endpoint."
-              }
-            }
-          },
           "connection": {
             "type": "string",
             "enum": [

package/src/endpoint-management.ts

@@ -16,16 +16,49 @@ import {
   type EndpointGroupRequest,
   type EndpointGroupNoticeRequest,
 } from 'zhin.js/adapter';
+import { standingFromMemberRole, type PlatformStanding, type SelfStandingRequest } from '@zhin.js/im-contract';
 
 /** 管理面只依赖 endpoint 的 callApi（ws/wss/http 三种传输各自实现）。 */
 export interface NapCatManagementCaller {
   requestApi(request: PendingRpcRequest): Promise<unknown>;
 }
 
+/** How long one `get_login_info` answer is reused (bursts only; see inspectSelfStanding). */
+const SELF_ID_TTL_MS = 5_000;
+
 export function createNapCatEndpointManagement(
   endpoint: NapCatManagementCaller,
 ): EndpointManagement {
+  // The login account can change across reconnects (or a different account on the same
+  // connection), so `get_login_info` is not remembered for the endpoint's lifetime: only briefly,
+  // to coalesce bursts, and never across a failed lookup.
+  let login: { readonly id: string; readonly at: number } | undefined;
+  const loginId = async (signal: AbortSignal | undefined): Promise<string | undefined> => {
+    if (login && Date.now() - login.at < SELF_ID_TTL_MS) return login.id;
+    login = undefined;
+    const info = asRecord(await endpoint.requestApi({ action: 'get_login_info', signal }));
+    const id = info.user_id;
+    const value = (typeof id === 'number' && id > 0) || (typeof id === 'string' && id.trim() !== '' && id !== '0') ? String(id) : undefined;
+    if (value) login = { id: value, at: Date.now() };
+    return value;
+  };
   return Object.freeze<EndpointManagement>({
+    /** ADR 0056 §1: the Bot's own group role (`get_login_info`, then `get_group_member_info` self). */
+    async inspectSelfStanding({ conversation, signal }: SelfStandingRequest): Promise<PlatformStanding | undefined> {
+      if (conversation.kind !== 'group') return undefined;
+      const selfId = await loginId(signal);
+      if (!selfId) return undefined;
+      let data: Record<string, unknown>;
+      try {
+        data = asRecord(await endpoint.requestApi({ action: 'get_group_member_info', signal, params: {
+          group_id: toNumberId(conversation.id, 'group_id'), user_id: toNumberId(selfId, 'user_id'), no_cache: true,
+        } }));
+      } catch (error) {
+        login = undefined;
+        throw error;
+      }
+      return standingFromMemberRole(data.role);
+    },
     async listFriends(request: EndpointManagementRequest = {}): Promise<readonly EndpointFriend[]> {
       const data = await endpoint.requestApi({ action: 'get_friend_list', signal: request.signal });
       return toArray(data).map((value) => {

package/src/http-endpoint.ts

@@ -3,7 +3,6 @@ import { toCanonicalSegments } from '@zhin.js/core';
 /**
  * NapCat HTTP endpoint — POST inbound events + HTTP API outbound.
  */
-import type { IncomingMessage, ServerResponse } from 'node:http';
 import {
   createEndpointSpecification, endpointSpec, type Endpoint, type EndpointSpecification,
   createRecallEndpointControl,
@@ -33,6 +32,7 @@ import {
   napcatInboundConversation,
   napcatOutboundTarget,
   senderNickname,
+  napcatSenderStanding,
   senderUserId,
   type NapCatEvent,
   type NapCatHttpConfig,
@@ -40,7 +40,7 @@ import {
 import { receiveNapCatSideEvent } from './side-event-dispatch.js';
 import { createNapCatContentPort } from './onebot-get-msg.js';
 import { NapcatClient } from './client.js';
-import { readRequestBody } from './webhook.js';
+import { readTextBody } from '@zhin.js/host-http-contract';
 import { verifyNapCatAccessToken } from './wss-auth.js';
 
 export interface NapCatHttpEndpointOptions {
@@ -175,6 +175,7 @@ export class NapCatHttpEndpoint extends NapcatClient implements Endpoint {
     const mentioned = isNapCatBotMentioned(ev);
     const quoteId = extractQuoteId(ev);
     const segments = Array.isArray(ev.message) ? toCanonicalSegments(ev.message) : undefined;
+    const platform = napcatSenderStanding(ev);
     void this[endpointSpec].events.message({
       event: nativeEvent,
       ...(typeof nativeEvent.time === 'number' ? { platformSentAt: nativeEvent.time * 1000 } : {}),
@@ -185,7 +186,7 @@ export class NapCatHttpEndpoint extends NapcatClient implements Endpoint {
       sender: {
         id: senderUserId(ev),
         name: nickname,
-        ...(ev.sender?.role ? { roles: [ev.sender.role] } : {}),
+        ...(platform ? { platform } : {}),
       },
       endpointId: this.#options.config.id,
       ...(mentioned ? { mentioned: true } : {}),
@@ -211,41 +212,31 @@ export class NapCatHttpEndpoint extends NapcatClient implements Endpoint {
   #setupRoutes(): void {
     const path = this.#options.config.post_path;
     this.#routeReleases.push(
-      this.#options.http.route('POST', path, async (request, response) => {
-        await this.#handlePost(request, response);
-      }, { summary: 'NapCat HTTP event callback', tags: ['napcat'] }),
+      this.#options.http.route('POST', path, (request) => this.#handlePost(request), { summary: 'NapCat HTTP event callback', tags: ['napcat'] }),
     );
   }
 
-  async #handlePost(request: IncomingMessage, response: ServerResponse): Promise<void> {
+  async #handlePost(request: Request): Promise<Response> {
     try {
       if (!verifyNapCatAccessToken(this.#options.config.access_token, request)) {
-        response.writeHead(403, { 'Content-Type': 'application/json' });
-        response.end(JSON.stringify({ message: 'Unauthorized' }));
-        return;
+        return new Response(JSON.stringify({ message: 'Unauthorized' }), { status: 403, headers: { 'Content-Type': 'application/json' } });
       }
-      const raw = await readRequestBody(request);
+      const raw = await readTextBody(request);
       let ev: NapCatEvent;
       try {
         ev = JSON.parse(raw) as NapCatEvent;
       } catch {
-        response.writeHead(400, { 'Content-Type': 'application/json' });
-        response.end(JSON.stringify({ message: 'Invalid JSON' }));
-        return;
+        return new Response(JSON.stringify({ message: 'Invalid JSON' }), { status: 400, headers: { 'Content-Type': 'application/json' } });
       }
       if (this.#open) {
         void this[endpointSpec].events.run(() => this.ingest(ev)).catch((error: unknown) => {
           this.#logger.debug(formatCompact({ op: 'napcat_receive_failed', error: error instanceof Error ? error.message : String(error) }));
         });
       }
-      response.writeHead(200, { 'Content-Type': 'application/json' });
-      response.end(JSON.stringify({ status: 'ok' }));
+      return new Response(JSON.stringify({ status: 'ok' }), { status: 200, headers: { 'Content-Type': 'application/json' } });
     } catch (error) {
       this.#logger.error('NapCat HTTP webhook error:', error);
-      if (!response.headersSent) {
-        response.writeHead(500, { 'Content-Type': 'application/json' });
-        response.end(JSON.stringify({ message: 'Internal Server Error' }));
-      }
+      return new Response(JSON.stringify({ message: 'Internal Server Error' }), { status: 500, headers: { 'Content-Type': 'application/json' } });
     }
   }
 }

package/src/index.ts

@@ -73,5 +73,3 @@ export {
 } from './ws-transport.js';
 
 export { verifyNapCatAccessToken } from './wss-auth.js';
-
-export { readRequestBody } from './webhook.js';

package/src/protocol.ts

@@ -4,7 +4,7 @@ import type { EndpointProfileConfiguration } from 'zhin.js/adapter';
  * No legacy Adapter/Endpoint / segment-mapper.
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
-import { EndpointDeliveryError, isMediaRef, type MediaRef, type ConversationRef } from '@zhin.js/im-contract';
+import { EndpointDeliveryError, isMediaRef, type MediaRef, type ConversationRef, type PlatformStanding } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
 const logger = getLogger('napcat');
@@ -273,6 +273,16 @@ function stripCqCodes(input: string): string {
  * 入站 sender 语义：必须是用户 ID（Runtime Message contract）。
  * 显示名走 metadata.nickname，见 senderNickname。
  */
+/**
+ * ADR 0056 §1：群消息 `sender.role`（owner / admin / member）→ `sender.platform.standing`。
+ * 私聊与未知角色词不上报；OneBot / NapCat 没有平台原生角色与权限位。
+ */
+export function napcatSenderStanding(ev: NapCatEvent): PlatformStanding | undefined {
+  if (ev.message_type !== 'group') return undefined;
+  const role = ev.sender?.role;
+  return role === 'owner' || role === 'admin' || role === 'member' ? { standing: role } : undefined;
+}
+
 export function senderUserId(ev: NapCatEvent): string {
   return ev.user_id != null ? String(ev.user_id) : '';
 }
@@ -379,6 +389,9 @@ function canonicalToOneBotSegment(segment: NapCatWireSegment): MessageSegment |
       return oneBotMediaSegment(segment.type, data);
     case 'audio':
       return oneBotMediaSegment('record', data);
+    case 'napcat:node':
+      // Agent-authored merged-forward node (napcat_send_forward_msg); NapCat sends `node` arrays as a forward.
+      return { type: 'node', data };
     default:
       return { type: segment.type, data };
   }

package/src/ws-endpoint.ts

@@ -35,6 +35,7 @@ import {
   napcatInboundConversation,
   napcatOutboundTarget,
   senderNickname,
+  napcatSenderStanding,
   senderUserId,
   type NapCatEvent,
   type NapCatWsConfig,
@@ -194,6 +195,7 @@ export class NapCatWsEndpoint extends NapcatClient implements Endpoint {
     const mentioned = isNapCatBotMentioned(ev);
     const quoteId = extractQuoteId(ev);
     const segments = Array.isArray(ev.message) ? toCanonicalSegments(ev.message) : undefined;
+    const platform = napcatSenderStanding(ev);
     void this[endpointSpec].events.message({
       event: nativeEvent,
       ...(typeof nativeEvent.time === 'number' ? { platformSentAt: nativeEvent.time * 1000 } : {}),
@@ -204,7 +206,7 @@ export class NapCatWsEndpoint extends NapcatClient implements Endpoint {
       sender: {
         id: senderUserId(ev),
         name: nickname,
-        ...(ev.sender?.role ? { roles: [ev.sender.role] } : {}),
+        ...(platform ? { platform } : {}),
       },
       endpointId: this.#options.config.id,
       ...(mentioned ? { mentioned: true } : {}),

package/src/ws-types.ts

@@ -1,3 +1,5 @@
+import type { WsConnection } from '@zhin.js/host-http';
+
 /** Minimal WS surface used by the endpoint (real `ws` or test mock). */
 export interface NapCatWsSocket {
   readonly readyState: number;
@@ -13,3 +15,34 @@ export interface NapCatWsCreateOptions {
 }
 
 export const WS_OPEN = 1;
+
+/**
+ * A Host reverse-WebSocket connection seen through the NapCatWsSocket surface. Protocol
+ * keepalive (ping / pong) belongs to the Host transport, so `ping` is absent.
+ */
+export function socketOfConnection(connection: WsConnection): NapCatWsSocket {
+  let readyState = 1;
+  connection.onClose(() => { readyState = 3; });
+  const subscriptions = new Map<(...args: unknown[]) => void, () => void>();
+  const off = (_event: string, listener: (...args: unknown[]) => void): void => {
+    subscriptions.get(listener)?.();
+    subscriptions.delete(listener);
+  };
+  return {
+    get readyState() { return readyState; },
+    send: (data: string) => connection.send(data),
+    close: (code?: number, reason?: string) => connection.close(code, reason),
+    on(event: string, listener: (...args: unknown[]) => void) {
+      if (event === 'message') {
+        subscriptions.set(listener, connection.onMessage((data) => {
+          listener(typeof data === 'string' ? data : Buffer.from(data));
+        }));
+      } else if (event === 'close') {
+        subscriptions.set(listener, connection.onClose((code, reason) => listener(code, reason)));
+      }
+      // 'error' surfaces as a close on a WsConnection; 'open' already happened.
+    },
+    off,
+    removeListener: off,
+  } as NapCatWsSocket;
+}

package/src/wss-auth.ts

@@ -1,17 +1,10 @@
-import type { IncomingMessage } from 'node:http';
+import { verifyProtocolAccessToken, type ProtocolAuthRequest } from '@zhin.js/host-http';
 
 export function verifyNapCatAccessToken(
   accessToken: string | undefined,
-  request: IncomingMessage,
+  request: ProtocolAuthRequest,
 ): boolean {
+  // Webhook semantics: no configured token admits any caller (reverse sockets use verifyProtocolAccessToken).
   if (!accessToken) return true;
-  const auth = request.headers.authorization ?? '';
-  if (auth === `Bearer ${accessToken}`) return true;
-  try {
-    const url = new URL(request.url ?? '/', 'http://localhost');
-    if (url.searchParams.get('access_token') === accessToken) return true;
-  } catch {
-    /* ignore */
-  }
-  return false;
+  return verifyProtocolAccessToken(accessToken, request);
 }

package/src/wss-endpoint.ts

@@ -13,7 +13,7 @@ import {
   type EndpointSendRequest,
   type EndpointTransportState,
 } from 'zhin.js/adapter';
-import type { HttpHost, WsConnection } from '@zhin.js/host-http';
+import { verifyProtocolAccessToken, type HttpHost, type WsConnection } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
 import { createNapCatEndpointManagement } from './endpoint-management.js';
@@ -33,6 +33,7 @@ import {
   napcatInboundConversation,
   napcatOutboundTarget,
   senderNickname,
+  napcatSenderStanding,
   senderUserId,
   type NapCatEvent,
   type NapCatWssConfig,
@@ -40,10 +41,7 @@ import {
 import { receiveNapCatSideEvent } from './side-event-dispatch.js';
 import { createNapCatContentPort } from './onebot-get-msg.js';
 import { NapcatClient } from './client.js';
-import {
-  type NapCatWsSocket,
-} from './ws-types.js';
-import { verifyNapCatAccessToken } from './wss-auth.js';
+import { socketOfConnection, type NapCatWsSocket } from './ws-types.js';
 
 export interface NapCatWssEndpointOptions {
   readonly id: CapabilityId;
@@ -110,7 +108,17 @@ export class NapCatWssEndpoint extends NapcatClient implements Endpoint {
     if (this.#started) return;
     this.#stopped = false;
     this.#started = true;
-    const handle = this.#options.http.ws(this.#options.config.path);
+    if (!this.#options.config.access_token) {
+      // 未配 access_token 时只接受本机回环连接（verifyProtocolAccessToken）。
+      this.#logger.warn(formatCompact({
+        endpoint: this.#options.config.id,
+        mode: 'wss',
+        ok: false,
+        error: 'missing access_token: only loopback peers are accepted',
+      }));
+    }
+    // The peer authenticates with this endpoint's own access_token, not a Console credential.
+    const handle = this.#options.http.ws(this.#options.config.path, { auth: 'protocol' });
     this.#wsRelease = handle.onConnection((connection) => {
       this.#connectionTask = this.#connectionTask
         .then(() => this.#acceptConnection(connection))
@@ -199,6 +207,7 @@ export class NapCatWssEndpoint extends NapcatClient implements Endpoint {
     const mentioned = isNapCatBotMentioned(ev);
     const quoteId = extractQuoteId(ev);
     const segments = Array.isArray(ev.message) ? toCanonicalSegments(ev.message) : undefined;
+    const platform = napcatSenderStanding(ev);
     void this[endpointSpec].events.message({
       event: nativeEvent,
       ...(typeof nativeEvent.time === 'number' ? { platformSentAt: nativeEvent.time * 1000 } : {}),
@@ -209,7 +218,7 @@ export class NapCatWssEndpoint extends NapcatClient implements Endpoint {
       sender: {
         id: senderUserId(ev),
         name: nickname,
-        ...(ev.sender?.role ? { roles: [ev.sender.role] } : {}),
+        ...(platform ? { platform } : {}),
       },
       endpointId: this.#options.config.id,
       ...(mentioned ? { mentioned: true } : {}),
@@ -234,14 +243,14 @@ export class NapCatWssEndpoint extends NapcatClient implements Endpoint {
 
   async #acceptConnection(connection: WsConnection): Promise<void> {
     if (!this.#started || this.#stopped) {
-      connection.socket.close();
+      connection.close();
       return;
     }
-    if (!verifyNapCatAccessToken(this.#options.config.access_token, connection.request)) {
-      connection.socket.close(4003, 'Unauthorized');
+    if (!verifyProtocolAccessToken(this.#options.config.access_token, connection)) {
+      connection.close(4003, 'Unauthorized');
       return;
     }
-    const socket = connection.socket as unknown as NapCatWsSocket;
+    const socket = socketOfConnection(connection);
     await this.#connectionLifecycle.stop();
     this.rpc.disconnect('Connection replaced');
     await this.#connectionLifecycle.start(async (lifecycleHandle) => {
@@ -257,16 +266,7 @@ export class NapCatWssEndpoint extends NapcatClient implements Endpoint {
           /* ignore */
         }
       });
-      this.#connectionLifecycle.startHeartbeat(() => {
-        try {
-          socket.ping?.();
-        } catch {
-          /* ignore */
-        }
-      }, this.#options.config.heartbeat_interval);
-      socket.on('pong', () => {
-        if (this.transportSocket === socket) this.#connectionLifecycle.notifyHeartbeatAck();
-      });
+      // Dead-peer detection is the Host transport's keepalive (protocol ping / pong).
       socket.on('message', (data) => {
         if (this.transportSocket !== socket || this.#connectionLifecycle.state === 'closed') return;
         this.#connectionLifecycle.notifyHeartbeatAck();
@@ -286,7 +286,7 @@ export class NapCatWssEndpoint extends NapcatClient implements Endpoint {
     this.#logger.debug(formatCompact({
       endpoint: this.#options.config.id,
       mode: 'wss',
-      peer: connection.request.socket.remoteAddress,
+      peer: connection.remoteAddress,
     }));
   }
 }

package/lib/webhook.d.ts

@@ -1,2 +0,0 @@
-import type { IncomingMessage } from 'node:http';
-export declare function readRequestBody(request: IncomingMessage): Promise<string>;

package/lib/webhook.js

@@ -1,14 +0,0 @@
-export async function readRequestBody(request) {
-    const chunks = [];
-    let size = 0;
-    for await (const chunk of request) {
-        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        size += buffer.length;
-        if (size > 1_048_576) {
-            request.destroy();
-            throw new Error('Request body exceeds 1MB');
-        }
-        chunks.push(buffer);
-    }
-    return Buffer.concat(chunks).toString('utf8');
-}

package/src/webhook.ts

@@ -1,16 +0,0 @@
-import type { IncomingMessage } from 'node:http';
-
-export async function readRequestBody(request: IncomingMessage): Promise<string> {
-  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 > 1_048_576) {
-      request.destroy();
-      throw new Error('Request body exceeds 1MB');
-    }
-    chunks.push(buffer);
-  }
-  return Buffer.concat(chunks).toString('utf8');
-}