@gakr-gakr/qqbot 0.1.0

package/src/engine/commands/slash-command-auth.ts

@@ -0,0 +1,88 @@
+/**
+ * Pre-dispatch authorization for requireAuth slash commands.
+ *
+ * Unlike the inbound message ingress command projection (which permits
+ * open-policy chat senders), this function requires the sender to appear in an
+ * **explicit non-wildcard** allowFrom list.
+ *
+ * Rationale: sensitive operations (log export, file deletion, approval
+ * config changes) must be gated behind a deliberate operator decision.
+ * A wide-open DM policy means "anyone can chat", not "anyone can run
+ * admin commands".
+ */
+
+import { createQQBotSenderMatcher, normalizeQQBotAllowFrom } from "../access/index.js";
+
+type SlashCommandAuthEntry = string | number;
+
+function isSlashCommandAuthEntry(value: unknown): value is SlashCommandAuthEntry {
+  return typeof value === "string" || typeof value === "number";
+}
+
+function readSlashCommandAuthList(value: unknown): SlashCommandAuthEntry[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  return value.filter(isSlashCommandAuthEntry);
+}
+
+/**
+ * Resolve the command-specific QQBot allowlist from the root AutoBot config.
+ *
+ * `commands.allowFrom.qqbot` takes precedence over the global
+ * `commands.allowFrom["*"]`, matching the framework command authorization
+ * contract used by registered plugin commands.
+ */
+export function resolveQQBotCommandsAllowFrom(cfg: unknown): SlashCommandAuthEntry[] | undefined {
+  if (!cfg || typeof cfg !== "object") {
+    return undefined;
+  }
+  const commands = (cfg as { commands?: unknown }).commands;
+  if (!commands || typeof commands !== "object") {
+    return undefined;
+  }
+  const allowFrom = (commands as { allowFrom?: unknown }).allowFrom;
+  if (!allowFrom || typeof allowFrom !== "object" || Array.isArray(allowFrom)) {
+    return undefined;
+  }
+  const byProvider = allowFrom as Record<string, unknown>;
+  return readSlashCommandAuthList(byProvider.qqbot) ?? readSlashCommandAuthList(byProvider["*"]);
+}
+
+/**
+ * Determine whether `senderId` is authorized to execute `requireAuth`
+ * slash commands for the given account configuration.
+ *
+ * Authorization rules:
+ * - `commands.allowFrom.qqbot` / `commands.allowFrom["*"]` configured →
+ *   use that command-specific list instead of channel allowFrom
+ * - `allowFrom` not configured / empty / only `["*"]` → **false**
+ *   (wildcard means "open to everyone", not explicit authorization)
+ * - `allowFrom` contains at least one concrete entry AND sender
+ *   matches a concrete entry → **true**
+ * - Group messages use `groupAllowFrom` when present, falling back
+ *   to `allowFrom`.
+ */
+export function resolveSlashCommandAuth(params: {
+  senderId: string;
+  isGroup: boolean;
+  allowFrom?: Array<string | number>;
+  groupAllowFrom?: Array<string | number>;
+  commandsAllowFrom?: Array<string | number>;
+}): boolean {
+  const rawList =
+    params.commandsAllowFrom ??
+    (params.isGroup && params.groupAllowFrom && params.groupAllowFrom.length > 0
+      ? params.groupAllowFrom
+      : params.allowFrom);
+
+  const normalized = normalizeQQBotAllowFrom(rawList);
+
+  // Require and match only explicit (non-wildcard) entries.
+  const explicitEntries = normalized.filter((entry) => entry !== "*");
+  if (explicitEntries.length === 0) {
+    return false;
+  }
+
+  return createQQBotSenderMatcher(params.senderId)(explicitEntries);
+}

package/src/engine/commands/slash-command-handler.ts

@@ -0,0 +1,168 @@
+/**
+ * Slash command handler — intercept slash commands before message queue.
+ *
+ * Extracted from gateway.ts to keep the gateway connection logic thin.
+ * Handles urgent commands, normal slash commands, and file delivery.
+ */
+
+import type { QueuedMessage } from "../gateway/message-queue.js";
+import type { GatewayAccount, EngineLogger } from "../gateway/types.js";
+import { sendDocument } from "../messaging/outbound.js";
+import {
+  sendText as senderSendText,
+  buildDeliveryTarget,
+  accountToCreds,
+} from "../messaging/sender.js";
+import { resolveQQBotCommandsAllowFrom, resolveSlashCommandAuth } from "./slash-command-auth.js";
+import { matchSlashCommand } from "./slash-commands-impl.js";
+import type { SlashCommandContext, QueueSnapshot } from "./slash-commands.js";
+
+// ============ Types ============
+
+export interface SlashCommandHandlerContext {
+  account: GatewayAccount;
+  cfg?: unknown;
+  log?: EngineLogger;
+  getMessagePeerId: (msg: QueuedMessage) => string;
+  getQueueSnapshot: (peerId: string) => QueueSnapshot;
+  resolveCommandAuthorized?: (params: {
+    isGroup: boolean;
+    senderId: string;
+    conversationId: string;
+    allowFrom?: Array<string | number>;
+    groupAllowFrom?: Array<string | number>;
+    commandsAllowFrom?: Array<string | number>;
+  }) => boolean | Promise<boolean>;
+}
+
+// ============ Constants ============
+
+const URGENT_COMMANDS = ["/stop"];
+
+// ============ trySlashCommandOrEnqueue ============
+
+/**
+ * Check if the message is a slash command and handle it.
+ *
+ * @returns `true` if handled (command executed or enqueued as urgent),
+ *          `false` if the message should be queued for normal processing.
+ */
+export async function trySlashCommand(
+  msg: QueuedMessage,
+  ctx: SlashCommandHandlerContext,
+): Promise<"handled" | "urgent" | "enqueue"> {
+  const { account, log } = ctx;
+  const content = (msg.content ?? "").trim();
+
+  if (!content.startsWith("/")) {
+    return "enqueue";
+  }
+
+  // Urgent command detection — bypass queue and execute immediately.
+  const contentLower = content.toLowerCase();
+  const isUrgentCommand = URGENT_COMMANDS.some(
+    (cmd) => contentLower === cmd.toLowerCase() || contentLower.startsWith(cmd.toLowerCase() + " "),
+  );
+  if (isUrgentCommand) {
+    log?.info(`Urgent command detected: ${content.slice(0, 20)}`);
+    return "urgent";
+  }
+
+  // Normal slash command — try to match and execute.
+  const receivedAt = Date.now();
+  const peerId = ctx.getMessagePeerId(msg);
+  const isGroup = msg.type === "group" || msg.type === "guild";
+  const commandsAllowFrom = resolveQQBotCommandsAllowFrom(ctx.cfg);
+  const commandAuthorized = ctx.resolveCommandAuthorized
+    ? await ctx.resolveCommandAuthorized({
+        isGroup,
+        senderId: msg.senderId,
+        conversationId: msg.groupOpenid ?? msg.channelId ?? msg.senderId,
+        allowFrom: account.config?.allowFrom,
+        groupAllowFrom: account.config?.groupAllowFrom,
+        commandsAllowFrom,
+      })
+    : resolveSlashCommandAuth({
+        senderId: msg.senderId,
+        isGroup,
+        allowFrom: account.config?.allowFrom,
+        groupAllowFrom: account.config?.groupAllowFrom,
+        commandsAllowFrom,
+      });
+  const cmdCtx: SlashCommandContext = {
+    type: msg.type,
+    senderId: msg.senderId,
+    senderName: msg.senderName,
+    messageId: msg.messageId,
+    eventTimestamp: msg.timestamp,
+    receivedAt,
+    rawContent: content,
+    args: "",
+    channelId: msg.channelId,
+    groupOpenid: msg.groupOpenid,
+    accountId: account.accountId,
+    appId: account.appId,
+    accountConfig: account.config,
+    commandAuthorized,
+    queueSnapshot: ctx.getQueueSnapshot(peerId),
+  };
+
+  try {
+    const reply = await matchSlashCommand(cmdCtx);
+    if (reply === null) {
+      return "enqueue";
+    }
+
+    log?.debug?.(`Slash command matched: ${content}`);
+
+    const isFileResult = typeof reply === "object" && reply !== null && "filePath" in reply;
+    const replyText = isFileResult ? (reply as { text: string }).text : reply;
+    const replyFile = isFileResult ? (reply as { filePath: string }).filePath : null;
+
+    // Send text reply.
+    if (msg.type === "c2c" || msg.type === "group" || msg.type === "dm" || msg.type === "guild") {
+      const slashTarget = buildDeliveryTarget(msg);
+      const slashCreds = accountToCreds(account);
+      await senderSendText(slashTarget, replyText, slashCreds, { msgId: msg.messageId });
+    }
+
+    // Send file attachment if present.
+    if (replyFile) {
+      try {
+        const targetType =
+          msg.type === "group"
+            ? "group"
+            : msg.type === "dm"
+              ? "dm"
+              : msg.type === "c2c"
+                ? "c2c"
+                : "channel";
+        const targetId =
+          msg.type === "group"
+            ? msg.groupOpenid || msg.senderId
+            : msg.type === "dm"
+              ? msg.guildId || msg.senderId
+              : msg.type === "c2c"
+                ? msg.senderId
+                : msg.channelId || msg.senderId;
+        await sendDocument(
+          {
+            targetType,
+            targetId,
+            account,
+            replyToId: msg.messageId,
+          },
+          replyFile,
+          { allowQQBotDataDownloads: true },
+        );
+      } catch (fileErr) {
+        log?.error(`Failed to send slash command file: ${String(fileErr)}`);
+      }
+    }
+
+    return "handled";
+  } catch (err) {
+    log?.error(`Slash command error: ${String(err)}`);
+    return "enqueue";
+  }
+}

package/src/engine/commands/slash-command-test-support.ts

@@ -0,0 +1,39 @@
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import type { CommandsPort } from "../adapter/commands.port.js";
+import { initCommands } from "./slash-commands-impl.js";
+
+type RuntimeConfigApi = ReturnType<NonNullable<CommandsPort["approveRuntimeGetter"]>>["config"];
+type ReplaceConfigFile = RuntimeConfigApi["replaceConfigFile"];
+type ReplaceConfigFileResult = Awaited<ReturnType<ReplaceConfigFile>>;
+
+export type WrittenQQBotConfig = {
+  streaming?: unknown;
+  accounts?: { default?: { streaming?: unknown } };
+};
+
+export function installCommandRuntime(
+  currentConfig: AutoBotConfig,
+  writes: AutoBotConfig[],
+): void {
+  const replaceConfigFile: ReplaceConfigFile = async (params) => {
+    writes.push(params.nextConfig);
+    return undefined as unknown as ReplaceConfigFileResult;
+  };
+
+  initCommands({
+    resolveVersion: () => "test",
+    pluginVersion: "0.0.0-test",
+    approveRuntimeGetter: () => ({
+      config: {
+        current: () => currentConfig,
+        replaceConfigFile,
+      },
+    }),
+  });
+}
+
+export function getWrittenQQBotConfig(
+  write: AutoBotConfig | undefined,
+): WrittenQQBotConfig | undefined {
+  return write?.channels?.qqbot as WrittenQQBotConfig | undefined;
+}

package/src/engine/commands/slash-commands-impl.ts

@@ -0,0 +1,61 @@
+/**
+ * QQBot plugin-level slash command handler.
+ *
+ * Type definitions and the command registry/dispatcher are in
+ * `./slash-commands.ts`. Built-in command bodies live under `./builtin/`.
+ */
+
+import type { CommandsPort } from "../adapter/commands.port.js";
+import { debugLog } from "../utils/log.js";
+import { registerBuiltinSlashCommands } from "./builtin/register-all.js";
+import {
+  getFrameworkVersionString,
+  getPluginVersionString,
+  initSlashCommandDeps,
+} from "./builtin/state.js";
+import {
+  SlashCommandRegistry,
+  type SlashCommandContext,
+  type SlashCommandResult,
+  type QQBotFrameworkCommand,
+} from "./slash-commands.js";
+
+const registry = new SlashCommandRegistry();
+registerBuiltinSlashCommands(registry);
+
+/**
+ * Initialize command dependencies from the EngineAdapters.commands port.
+ * Called once by the bridge layer during startup.
+ */
+export function initCommands(port: CommandsPort): void {
+  initSlashCommandDeps(port);
+}
+
+/**
+ * Return commands that may be registered with the framework via
+ * api.registerCommand() in registerFull().
+ */
+export function getFrameworkCommands(): QQBotFrameworkCommand[] {
+  return registry.getFrameworkCommands();
+}
+
+// Slash command entry point — delegates to core/ registry.
+
+/**
+ * Try to match and execute a plugin-level slash command.
+ *
+ * @returns A reply when matched, or null when the message should continue through normal routing.
+ */
+export async function matchSlashCommand(ctx: SlashCommandContext): Promise<SlashCommandResult> {
+  return registry.matchSlashCommand(ctx, { info: debugLog });
+}
+
+/** Return the plugin version for external callers. */
+export function getPluginVersion(): string {
+  return getPluginVersionString();
+}
+
+/** Return the framework version for external callers. */
+export function getFrameworkVersion(): string {
+  return getFrameworkVersionString();
+}

package/src/engine/commands/slash-commands.ts

@@ -0,0 +1,202 @@
+/**
+ * Slash command registration and dispatch framework.
+ *
+ * This module provides the type definitions, command registry, and
+ * `matchSlashCommand` dispatcher that both plugin versions share.
+ *
+ * Concrete command implementations (e.g. `/bot-ping`, `/bot-logs`) are
+ * registered by the upper-layer bootstrap code, NOT defined here.
+ *
+ * Zero external dependencies.
+ */
+
+// ============ Types ============
+
+/** Slash command context (message metadata plus runtime state). */
+export interface SlashCommandContext {
+  /** Message type. */
+  type: "c2c" | "guild" | "dm" | "group";
+  /** Sender ID. */
+  senderId: string;
+  /** Sender display name. */
+  senderName?: string;
+  /** Message ID used for passive replies. */
+  messageId: string;
+  /** Event timestamp from QQ as an ISO string. */
+  eventTimestamp: string;
+  /** Local receipt timestamp in milliseconds. */
+  receivedAt: number;
+  /** Raw message content. */
+  rawContent: string;
+  /** Command arguments after stripping the command name. */
+  args: string;
+  /** Channel ID for guild messages. */
+  channelId?: string;
+  /** Group openid for group messages. */
+  groupOpenid?: string;
+  /** Account ID. */
+  accountId: string;
+  /** Bot App ID. */
+  appId: string;
+  /** Account config available to the command handler. */
+  accountConfig?: Record<string, unknown>;
+  /** Whether the sender is authorized per the allowFrom config. */
+  commandAuthorized: boolean;
+  /** Queue snapshot for the current sender. */
+  queueSnapshot: QueueSnapshot;
+}
+
+/** Queue status snapshot. */
+export interface QueueSnapshot {
+  totalPending: number;
+  activeUsers: number;
+  maxConcurrentUsers: number;
+  senderPending: number;
+}
+
+/** Slash command result: text, a text+file result, or null to skip handling. */
+export type SlashCommandResult = string | SlashCommandFileResult | null;
+
+/** Slash command result that sends text first and then a local file. */
+interface SlashCommandFileResult {
+  text: string;
+  /** Local file path to send. */
+  filePath: string;
+}
+
+/** Slash command definition. */
+interface SlashCommand {
+  /** Command name without the leading slash. */
+  name: string;
+  /** Short description. */
+  description: string;
+  /** Detailed usage text shown by `/command ?`. */
+  usage?: string;
+  /** When true, the command requires the sender to pass the allowFrom authorization check. */
+  requireAuth?: boolean;
+  /** When true, the command is only available in c2c (private) chat. Group invocations are rejected automatically. */
+  c2cOnly?: boolean;
+  /** Command handler. */
+  handler: (ctx: SlashCommandContext) => SlashCommandResult | Promise<SlashCommandResult>;
+}
+
+/** Framework command definition for commands that require authorization. */
+export interface QQBotFrameworkCommand {
+  name: string;
+  description: string;
+  usage?: string;
+  c2cOnly?: boolean;
+  handler: (ctx: SlashCommandContext) => SlashCommandResult | Promise<SlashCommandResult>;
+}
+
+// ============ Command Registry ============
+
+/** Lowercase and trim a string. */
+function lc(s: string): string {
+  return (s ?? "").toLowerCase().trim();
+}
+
+/**
+ * Slash command registry.
+ *
+ * Maintains two maps:
+ * - `commands` — QQBot message-flow commands
+ * - `frameworkCommands` — auth-gated commands that are safe on the framework surface
+ */
+export class SlashCommandRegistry {
+  private readonly commands = new Map<string, SlashCommand>();
+  private readonly frameworkCommands = new Map<string, SlashCommand>();
+
+  /** Register one command. */
+  register(cmd: SlashCommand): void {
+    const key = lc(cmd.name);
+    // Always register in the pre-dispatch map so QQ message-flow slash
+    // commands can match and execute directly (with requireAuth gating).
+    this.commands.set(key, cmd);
+    // Auth-gated commands are exposed to the framework command surface.
+    // Private-chat-only metadata is preserved so the bridge can enforce the
+    // same routing restriction before dispatching handlers.
+    if (cmd.requireAuth) {
+      this.frameworkCommands.set(key, cmd);
+    }
+  }
+
+  /** Return all commands that may be registered on the framework surface. */
+  getFrameworkCommands(): QQBotFrameworkCommand[] {
+    return Array.from(this.frameworkCommands.values()).map((cmd) => ({
+      name: cmd.name,
+      description: cmd.description,
+      usage: cmd.usage,
+      c2cOnly: cmd.c2cOnly,
+      handler: cmd.handler,
+    }));
+  }
+
+  /** Return all pre-dispatch commands. */
+  getPreDispatchCommands(): Map<string, SlashCommand> {
+    return this.commands;
+  }
+
+  /** Return all registered commands (both maps) for help listing. */
+  getAllCommands(): Map<string, SlashCommand> {
+    const all = new Map<string, SlashCommand>();
+    for (const [k, v] of this.commands) {
+      all.set(k, v);
+    }
+    for (const [k, v] of this.frameworkCommands) {
+      all.set(k, v);
+    }
+    return all;
+  }
+
+  /**
+   * Try to match and execute a pre-dispatch slash command.
+   *
+   * @returns A reply when matched, or null when the message should continue
+   *          through normal routing.
+   */
+  async matchSlashCommand(
+    ctx: SlashCommandContext,
+    log?: { info?: (msg: string) => void },
+  ): Promise<SlashCommandResult> {
+    const content = ctx.rawContent.trim();
+    if (!content.startsWith("/")) {
+      return null;
+    }
+
+    const spaceIdx = content.indexOf(" ");
+    const cmdName = lc(spaceIdx === -1 ? content.slice(1) : content.slice(1, spaceIdx));
+    const args = spaceIdx === -1 ? "" : content.slice(spaceIdx + 1).trim();
+
+    const cmd = this.commands.get(cmdName);
+    if (!cmd) {
+      return null;
+    }
+
+    // Reject c2cOnly commands when invoked outside private chat.
+    if (cmd.c2cOnly && ctx.type !== "c2c") {
+      return `💡 请在私聊中使用此指令`;
+    }
+
+    // Gate sensitive commands behind the allowFrom authorization check.
+    if (cmd.requireAuth && !ctx.commandAuthorized) {
+      log?.info?.(
+        `[qqbot] Slash command /${cmd.name} rejected: sender ${ctx.senderId} is not authorized`,
+      );
+      const isGroup = ctx.type === "group" || ctx.type === "guild";
+      const configHint = isGroup ? "groupAllowFrom" : "allowFrom";
+      return `⛔ 权限不足：请先在 channels.qqbot.${configHint} 中配置明确的发送者列表后再使用 /${cmd.name}。`;
+    }
+
+    // `/command ?` returns usage help.
+    if (args === "?") {
+      if (cmd.usage) {
+        return `📖 /${cmd.name} 用法：\n\n${cmd.usage}`;
+      }
+      return `/${cmd.name} - ${cmd.description}`;
+    }
+
+    ctx.args = args;
+    return await cmd.handler(ctx);
+  }
+}

package/src/engine/config/credential-backup.ts

@@ -0,0 +1,108 @@
+/**
+ * Credential backup & recovery.
+ * 凭证暂存与恢复。
+ *
+ * Solves the "hot-upgrade interrupted, appId/secret vanished from
+ * autobot.json" failure mode.
+ *
+ * Mechanics:
+ *   - After each successful gateway start we snapshot the currently
+ *     resolved `appId` / `clientSecret` to a per-account backup file.
+ *   - During plugin startup, if the live config has an empty appId or
+ *     secret, the gateway consults the backup and restores the values
+ *     via the config mutation API.
+ *   - Backups live under `~/.autobot/qqbot/data/` so they survive
+ *     plugin directory replacement.
+ *
+ * Safety notes:
+ *   - Only restore when credentials are **actually empty** — never
+ *     overwrite a user's intentional config change.
+ *   - Atomic write (temp file + rename) to avoid torn files.
+ *   - Per-account file: `credential-backup-<accountId>.json`. We do
+ *     **not** also key by appId because recovery happens precisely
+ *     when appId is unknown.
+ *   - Legacy single `credential-backup.json` is migrated automatically
+ *     when the stored accountId matches the caller.
+ */
+
+import fs from "node:fs";
+import { loadJsonFile } from "autobot/plugin-sdk/json-store";
+import { replaceFileAtomicSync } from "autobot/plugin-sdk/security-runtime";
+import { getCredentialBackupFile, getLegacyCredentialBackupFile } from "../utils/data-paths.js";
+
+interface CredentialBackup {
+  accountId: string;
+  appId: string;
+  clientSecret: string;
+  savedAt: string;
+}
+
+/** Persist a credential snapshot (called once gateway reaches READY). */
+export function saveCredentialBackup(accountId: string, appId: string, clientSecret: string): void {
+  if (!appId || !clientSecret) {
+    return;
+  }
+  try {
+    const backupPath = getCredentialBackupFile(accountId);
+    const data: CredentialBackup = {
+      accountId,
+      appId,
+      clientSecret,
+      savedAt: new Date().toISOString(),
+    };
+    replaceFileAtomicSync({
+      filePath: backupPath,
+      content: `${JSON.stringify(data, null, 2)}\n`,
+      tempPrefix: ".qqbot-credential-backup",
+    });
+  } catch {
+    /* best-effort — ignore */
+  }
+}
+
+/**
+ * Load a credential snapshot for `accountId`.
+ *
+ * Consults the new per-account file first; falls back to the legacy
+ * global backup file and migrates it when the embedded `accountId`
+ * matches the request. Returns `null` when no usable backup exists.
+ */
+export function loadCredentialBackup(accountId?: string): CredentialBackup | null {
+  try {
+    if (accountId) {
+      const newPath = getCredentialBackupFile(accountId);
+      const data = loadJsonFile<CredentialBackup>(newPath);
+      if (data?.appId && data.clientSecret) {
+        return data;
+      }
+    }
+
+    const legacy = getLegacyCredentialBackupFile();
+    const data = loadJsonFile<CredentialBackup>(legacy);
+    if (data) {
+      if (!data?.appId || !data?.clientSecret) {
+        return null;
+      }
+      if (accountId && data.accountId !== accountId) {
+        return null;
+      }
+      if (data.accountId) {
+        try {
+          const backupPath = getCredentialBackupFile(data.accountId);
+          replaceFileAtomicSync({
+            filePath: backupPath,
+            content: `${JSON.stringify(data, null, 2)}\n`,
+            tempPrefix: ".qqbot-credential-backup",
+          });
+          fs.unlinkSync(legacy);
+        } catch {
+          /* ignore migration errors */
+        }
+      }
+      return data;
+    }
+  } catch {
+    /* corrupt file — ignore */
+  }
+  return null;
+}