@onlyne/im-qq 3.1.0 → 3.2.0

package/src/port.ts

@@ -1,242 +0,0 @@
-/**
- * The HTTP boundary: every platform call the connector makes goes through this port, so the
- * translation logic runs against a fake in tests and the real QQ OpenAPI in production. The only
- * injected seams are `fetch` and `now`.
- */
-
-export const QQ_API_BASE = 'https://api.bot.qq.com';
-
-/** The token is refreshed this long before the platform's own expiry. */
-const TOKEN_REFRESH_WINDOW_MS = 60_000;
-/** What the platform answers when it omits `expires_in`; QQ documents 7200 seconds. */
-const DEFAULT_TOKEN_LIFETIME_SECONDS = 7200;
-
-export interface QqHttpRequest {
-  method: string;
-  headers: Record<string, string>;
-  body?: string;
-}
-
-export interface QqHttpResponse {
-  readonly status: number;
-  text(): Promise<string>;
-}
-
-export type QqFetch = (url: string, init: QqHttpRequest) => Promise<QqHttpResponse>;
-
-export interface QqPortErrorInit {
-  /** The HTTP status; `0` when the request never reached the platform. */
-  status: number;
-  /** The platform's own error code, when its body carried one. */
-  code?: string | number;
-  /** The platform's own error text, verbatim. */
-  detail?: string;
-}
-
-/** A platform refusal or a transport failure, with what the platform said kept apart from the summary. */
-export class QqPortError extends Error {
-  readonly status: number;
-  readonly code?: string | number;
-  readonly detail?: string;
-
-  constructor(message: string, init: QqPortErrorInit) {
-    super(message);
-    this.name = 'QqPortError';
-    this.status = init.status;
-    if (init.code !== undefined) this.code = init.code;
-    if (init.detail !== undefined) this.detail = init.detail;
-  }
-}
-
-/** A QQ conversation coordinate as the platform addresses it. */
-export interface QqSendTarget {
-  kind: 'c2c' | 'group';
-  openid: string;
-}
-
-/** The message body QQ v2 accepts; the connector fills only what it sends. */
-export interface QqMessageBody {
-  msg_type: number;
-  content?: string;
-  markdown?: { content: string };
-  /** The passive reply id from the inbound event. */
-  msg_id?: string;
-  msg_seq?: number;
-  message_reference?: { message_id: string };
-  input_notify?: { input_type: 1; input_second: number };
-}
-
-export interface QqSendResult {
-  id?: string;
-  timestamp?: string;
-  ext_info?: { ref_idx?: string };
-}
-
-export interface QqPortStatus {
-  state: string;
-  connected: boolean;
-  rate_limits: number;
-}
-
-export interface QqPort {
-  start(): Promise<void>;
-  stop(): Promise<void>;
-  /** The access token, fetched on demand and cached until shortly before it expires. */
-  token(): Promise<string>;
-  request<T>(method: string, path: string, body?: unknown): Promise<T>;
-  send(target: QqSendTarget, body: QqMessageBody): Promise<QqSendResult>;
-  status(): QqPortStatus;
-}
-
-export interface QqPortOptions {
-  appId: string;
-  appSecret: string;
-  baseUrl?: string;
-  fetch?: QqFetch;
-  now?: () => number;
-}
-
-/** The message endpoint for one conversation; `messageId` narrows it to that message (retract). */
-export function messagePath(target: QqSendTarget, messageId?: string): string {
-  const scope = target.kind === 'group' ? 'groups' : 'users';
-  const base = `/v2/${scope}/${encodeURIComponent(target.openid)}/messages`;
-  return messageId === undefined ? base : `${base}/${encodeURIComponent(messageId)}`;
-}
-
-function recordOf(value: unknown): Record<string, unknown> | undefined {
-  return value !== null && typeof value === 'object' && !Array.isArray(value)
-    ? value as Record<string, unknown>
-    : undefined;
-}
-
-function codeOf(body: unknown): string | number | undefined {
-  const code = recordOf(body)?.code;
-  if (typeof code === 'number') return code;
-  if (typeof code === 'string' && /^\d+$/.test(code)) return Number(code);
-  return undefined;
-}
-
-function messageOf(body: unknown): string | undefined {
-  const record = recordOf(body);
-  const message = record?.message ?? record?.errmsg;
-  return typeof message === 'string' && message.length > 0 ? message : undefined;
-}
-
-function detailOf(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-export function createQqPort(options: QqPortOptions): QqPort {
-  const baseUrl = (options.baseUrl ?? QQ_API_BASE).replace(/\/+$/, '');
-  const fetchImpl: QqFetch = options.fetch ?? ((url, init) => globalThis.fetch(url, init));
-  const now = options.now ?? Date.now;
-
-  let cached: { token: string; expiresAt: number } | undefined;
-  let inflight: Promise<string> | undefined;
-  let state = 'idle';
-  let rateLimits = 0;
-
-  /**
-   * A 2xx body can still be a refusal: the QQ error envelope is `{code, message}` and some
-   * endpoints answer it with HTTP 200, so a non-zero `code` is read as a rejection.
-   */
-  function rejection(method: string, path: string, status: number, body: unknown, raw: string): QqPortError {
-    const code = codeOf(body);
-    const detail = messageOf(body) ?? (raw.trim().length > 0 ? raw.trim() : 'no body');
-    const label = code === undefined ? detail : `${code} ${detail}`;
-    const summary = status >= 500
-      ? `The QQ platform failed ${method} ${path} with HTTP ${status}: ${label}`
-      : `The platform rejected ${method} ${path}: ${label}`;
-    return new QqPortError(summary, { status, ...(code === undefined ? {} : { code }), detail });
-  }
-
-  async function call(method: string, path: string, body: unknown, authorized: boolean): Promise<unknown> {
-    const headers: Record<string, string> = { 'content-type': 'application/json' };
-    if (authorized) headers.authorization = `QQBot ${await token()}`;
-    const init: QqHttpRequest = { method, headers, ...(body === undefined ? {} : { body: JSON.stringify(body) }) };
-    let response: QqHttpResponse;
-    try {
-      response = await fetchImpl(`${baseUrl}${path}`, init);
-    } catch (error) {
-      throw new QqPortError(`The QQ request ${method} ${path} did not complete: ${detailOf(error)}`, { status: 0 });
-    }
-    const raw = await response.text();
-    if (response.status === 429) rateLimits += 1;
-    let parsed: unknown;
-    try {
-      parsed = raw.length === 0 ? undefined : JSON.parse(raw);
-    } catch {
-      parsed = undefined;
-    }
-    if (response.status < 200 || response.status >= 300) {
-      throw rejection(method, path, response.status, parsed, raw);
-    }
-    const code = codeOf(parsed);
-    if (code !== undefined && code !== 0) throw rejection(method, path, response.status, parsed, raw);
-    return parsed ?? {};
-  }
-
-  async function fetchToken(): Promise<string> {
-    try {
-      const body = await call(
-        'POST',
-        '/app/getAppAccessToken',
-        { appId: options.appId, clientSecret: options.appSecret },
-        false,
-      );
-      const record = recordOf(body);
-      const token = record?.access_token;
-      if (typeof token !== 'string' || token.length === 0) {
-        throw new QqPortError('The QQ token endpoint answered without an access_token.', { status: 200 });
-      }
-      const lifetime = Number(record?.expires_in);
-      const seconds = Number.isFinite(lifetime) && lifetime > 0 ? lifetime : DEFAULT_TOKEN_LIFETIME_SECONDS;
-      cached = { token, expiresAt: now() + seconds * 1000 };
-      state = 'connected';
-      return token;
-    } catch (error) {
-      state = 'error';
-      throw error;
-    }
-  }
-
-  async function token(): Promise<string> {
-    if (cached !== undefined && now() < cached.expiresAt - TOKEN_REFRESH_WINDOW_MS) return cached.token;
-    if (inflight !== undefined) return inflight;
-    const pending = fetchToken();
-    inflight = pending;
-    try {
-      return await pending;
-    } finally {
-      if (inflight === pending) inflight = undefined;
-    }
-  }
-
-  return {
-    async start(): Promise<void> {
-      // No long connection to open: QQ delivers events to the webhook, and the token is fetched
-      // on the first authorized call.
-      state = cached === undefined ? 'idle' : 'connected';
-    },
-
-    async stop(): Promise<void> {
-      cached = undefined;
-      inflight = undefined;
-      state = 'stopped';
-    },
-
-    token,
-
-    async request<T>(method: string, path: string, body?: unknown): Promise<T> {
-      return await call(method, path, body, true) as T;
-    },
-
-    async send(target: QqSendTarget, body: QqMessageBody): Promise<QqSendResult> {
-      return await call('POST', messagePath(target), body, true) as QqSendResult;
-    },
-
-    status(): QqPortStatus {
-      return { state, connected: state === 'connected', rate_limits: rateLimits };
-    },
-  };
-}

package/src/send.ts

@@ -1,121 +0,0 @@
-/**
- * One outbound message, translated into a QQ v2 message body. QQ carries no attachments and no
- * cards through this connector, so a request that has them is settled locally instead of being
- * half-sent.
- */
-
-import type { SendOutcome, SendRequest } from '@onlyne/im-core';
-import { QqPortError, type QqMessageBody, type QqSendResult, type QqSendTarget } from './port.js';
-
-const UNSUPPORTED = 'unsupported by @onlyne/im-qq: the connector sends text and markdown only, so attachments/cards were not sent.';
-
-/** How many passive ids keep their `msg_seq`; beyond this the oldest is dropped. */
-const SEQUENCE_LIMIT = 1024;
-
-/** The port slice `send` needs; `QqPort` satisfies it as it stands. */
-export interface QqMessagePort {
-  send(target: QqSendTarget, body: QqMessageBody): Promise<QqSendResult>;
-}
-
-/**
- * `msg_seq` is per passive message id: QQ rejects a second message with the same `msg_id` and
- * `msg_seq`, so the connector counts how many answers it already sent into one event.
- */
-export interface SendState {
-  readonly sequences: Map<string, number>;
-}
-
-export function createSendState(): SendState {
-  return { sequences: new Map() };
-}
-
-export function parseConversation(conversation: string): QqSendTarget | undefined {
-  const separator = conversation.indexOf(':');
-  if (separator <= 0) return undefined;
-  const scope = conversation.slice(0, separator);
-  const openid = conversation.slice(separator + 1);
-  if (openid.length === 0) return undefined;
-  if (scope === 'c2c') return { kind: 'c2c', openid };
-  if (scope === 'group') return { kind: 'group', openid };
-  return undefined;
-}
-
-/** The platform's answer as the bridge needs it: a refusal is settled, an unclear transport is not. */
-export function outcomeOf(error: unknown, subject: 'send' | 'operation'): SendOutcome {
-  if (error instanceof QqPortError) {
-    // QQ answers some refusals with HTTP 200 and a non-zero `code`; either form is settled.
-    const refused = (error.status >= 400 && error.status < 500)
-      || (error.status >= 200 && error.status < 300 && error.code !== undefined);
-    if (refused) {
-      const label = [error.code === undefined ? '' : String(error.code), error.detail ?? '']
-        .filter(part => part.length > 0)
-        .join(' ');
-      return { state: 'committed', error: `The platform rejected the ${subject}: ${label.length > 0 ? label : error.message}` };
-    }
-    return { state: 'unknown', error: error.message };
-  }
-  return { state: 'unknown', error: error instanceof Error ? error.message : String(error) };
-}
-
-export async function sendMessage(port: QqMessagePort, request: SendRequest, state: SendState): Promise<SendOutcome> {
-  if (request.attachments.length > 0 || request.card !== undefined) {
-    return { state: 'committed', error: UNSUPPORTED };
-  }
-  const target = parseConversation(request.conversation);
-  if (target === undefined) {
-    return {
-      state: 'unknown',
-      error: `The QQ connector addresses c2c:<openid> or group:<openid>, not ${request.conversation}.`,
-    };
-  }
-  if (request.text.trim().length === 0) {
-    return { state: 'unknown', error: 'nothing to send: the QQ connector sends text or markdown only.' };
-  }
-  try {
-    const result = await port.send(target, messageBody(request, state));
-    const id = typeof result.id === 'string' && result.id.length > 0 ? result.id : undefined;
-    const ref = result.ext_info?.ref_idx;
-    return {
-      state: 'committed',
-      ...(id === undefined ? {} : { message_id: id }),
-      ...(typeof ref === 'string' && ref.length > 0 ? { ref_handle: ref } : {}),
-    };
-  } catch (error) {
-    return outcomeOf(error, 'send');
-  }
-}
-
-function messageBody(request: SendRequest, state: SendState): QqMessageBody {
-  // msg_type 2 carries `markdown` and no `content`: QQ renders whichever field matches the type.
-  const body: QqMessageBody = request.format === 'markdown'
-    ? { msg_type: 2, markdown: { content: request.text } }
-    : { msg_type: 0, content: request.text };
-  return { ...body, ...passiveReply(request.reply_to, state) };
-}
-
-/**
- * `reply_to` is `msg_id|REFIDX`: the passive reply id, and the quote reference when the inbound
- * event carried one. A single part answers passively without quoting anything.
- */
-function passiveReply(replyTo: string | undefined, state: SendState): Partial<QqMessageBody> {
-  if (replyTo === undefined || replyTo.length === 0) return {};
-  const separator = replyTo.indexOf('|');
-  const messageId = separator < 0 ? replyTo : replyTo.slice(0, separator);
-  const quote = separator < 0 ? '' : replyTo.slice(separator + 1);
-  if (messageId.length === 0) return {};
-  const sequence = (state.sequences.get(messageId) ?? 0) + 1;
-  state.sequences.set(messageId, sequence);
-  if (state.sequences.size > SEQUENCE_LIMIT) {
-    for (const key of state.sequences.keys()) {
-      if (key === messageId) continue;
-      state.sequences.delete(key);
-      break;
-    }
-  }
-  return {
-    msg_id: messageId,
-    msg_seq: sequence,
-    ...(quote.length === 0 ? {} : { message_reference: { message_id: quote } }),
-  };
-}
-

package/src/webhook.ts

@@ -1,90 +0,0 @@
-/**
- * QQ's callback authentication: Ed25519 over an app-secret-derived seed. The platform derives the
- * same key pair from the AppSecret, which is why the secret alone both signs the `op 13` challenge
- * and verifies every `op 0` dispatch.
- */
-
-import { createPrivateKey, createPublicKey, sign, verify, type KeyObject } from 'node:crypto';
-
-/** PKCS#8 header for an Ed25519 private key: the 32-byte seed follows it. */
-const PKCS8_ED25519_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex');
-const SEED_LENGTH = 32;
-/** An Ed25519 SPKI ends with the 32-byte public key after this many header bytes. */
-const SPKI_HEADER_LENGTH = 12;
-const SIGNATURE_LENGTH = 64;
-const CACHE_LIMIT = 8;
-
-export interface QqEd25519Keys {
-  privateKey: KeyObject;
-  publicKey: KeyObject;
-  /** The raw 32-byte public key, hex: what QQ's console shows for the app. */
-  publicHex: string;
-}
-
-/** Key derivation costs a scalar multiplication, so one secret's pair is derived once. */
-const cache = new Map<string, QqEd25519Keys>();
-
-export function deriveEd25519(secret: string): QqEd25519Keys {
-  const cached = cache.get(secret);
-  if (cached !== undefined) return cached;
-  if (secret.length === 0) throw new Error('The QQ app secret is empty; no Ed25519 key can be derived.');
-  const seed = Buffer.from(secret.repeat(Math.ceil(SEED_LENGTH / secret.length)), 'utf8').subarray(0, SEED_LENGTH);
-  const privateKey = createPrivateKey({
-    key: Buffer.concat([PKCS8_ED25519_PREFIX, seed]),
-    format: 'der',
-    type: 'pkcs8',
-  });
-  const publicKey = createPublicKey(privateKey);
-  const publicHex = publicKey.export({ format: 'der', type: 'spki' }).subarray(SPKI_HEADER_LENGTH).toString('hex');
-  const keys: QqEd25519Keys = { privateKey, publicKey, publicHex };
-  if (cache.size >= CACHE_LIMIT) {
-    const oldest = cache.keys().next();
-    if (!oldest.done) cache.delete(oldest.value);
-  }
-  cache.set(secret, keys);
-  return keys;
-}
-
-export function signHex(secret: string, message: string | Buffer): string {
-  // The platform signs the raw body bytes; QQ messages are UTF-8, so the string form must encode
-  // the same way. For the ASCII-only challenge the two encodings agree byte for byte.
-  const data = typeof message === 'string' ? Buffer.from(message, 'utf8') : message;
-  return sign(null, data, deriveEd25519(secret).privateKey).toString('hex');
-}
-
-export function verifyHex(secret: string, message: string | Buffer, signatureHex: string): boolean {
-  const signature = Buffer.from(signatureHex, 'hex');
-  // A malformed hex string decodes short rather than throwing; the length is the real check.
-  if (signature.length !== SIGNATURE_LENGTH) return false;
-  const data = typeof message === 'string' ? Buffer.from(message, 'utf8') : message;
-  try {
-    return verify(null, data, deriveEd25519(secret).publicKey, signature);
-  } catch {
-    return false;
-  }
-}
-
-/**
- * The `op 13` callback validation: QQ asks the bot to prove it holds the AppSecret by signing
- * `event_ts + plain_token`. The answer echoes the token with the signature.
- */
-export function challenge(secret: string, bodyJson: string): { plain_token: string; signature: string } | undefined {
-  let payload: unknown;
-  try {
-    payload = JSON.parse(bodyJson);
-  } catch {
-    return undefined;
-  }
-  if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) return undefined;
-  const envelope = payload as Record<string, unknown>;
-  if (envelope.op !== 13) return undefined;
-  const d = envelope.d;
-  if (d === null || typeof d !== 'object' || Array.isArray(d)) return undefined;
-  const fields = d as Record<string, unknown>;
-  const plainToken = fields.plain_token;
-  const eventTs = fields.event_ts;
-  if (typeof plainToken !== 'string' || plainToken.length === 0) return undefined;
-  const timestamp = typeof eventTs === 'string' ? eventTs : typeof eventTs === 'number' ? String(eventTs) : undefined;
-  if (timestamp === undefined || timestamp.length === 0) return undefined;
-  return { plain_token: plainToken, signature: signHex(secret, `${timestamp}${plainToken}`) };
-}