@powercess/qq-mcp 0.2.0

package/src/offline.ts

@@ -0,0 +1,422 @@
+/**
+ * Offline access to NTQQ (Windows QQ NT) databases.
+ *
+ * Finds the local `nt_qq/nt_db` directories, resolves the device passphrase,
+ * decrypts a database on demand into a cached plaintext SQLite file, and turns
+ * it into chat/contact queries. This replaces the earlier in-memory scrape:
+ * the on-disk databases yield exact, schema-accurate records.
+ */
+import { DatabaseSync } from "node:sqlite";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseNtqqHeader, pageCount, readSalt, reconstructDatabase, verifyPassphrase } from "./sqlcipher.js";
+import { toMessageRecord, type MessageRecord, type RawMessageRow } from "./messages.js";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+/**
+ * Per-user directory holding the device key file and the plaintext cache.
+ * Kept out of the package directory so an installed copy does not write
+ * gigabytes (or a device key) into `node_modules`.
+ */
+export const QQ_MCP_HOME = process.env.QQ_MCP_HOME ?? join(homedir(), ".qq-mcp");
+/** Where decrypted plaintext databases are cached. */
+export const DEFAULT_CACHE_DIR = process.env.QQ_MCP_CACHE_DIR ?? join(QQ_MCP_HOME, "plain");
+/** Device key file written by `capture_offline_key` when asked to persist. */
+export const KEY_FILE = join(QQ_MCP_HOME, "qqkey");
+/** Bundled memory scanner, shipped next to the compiled server. */
+export const SCANNER_SCRIPT = join(ROOT, "scripts", "scan_memory.py");
+
+export interface DataSource {
+  name: string;
+  dbPath: string;
+  bytes: number;
+  pages: number;
+  saltHex: string;
+  /** Schema/format version advertised by the NTQQ header, e.g. `1.1.0.1`. */
+  formatVersion: string;
+  /** `<db>-first.material` companion, when present (independent offline key oracle). */
+  materialPath?: string;
+  mtimeMs: number;
+}
+
+/** Candidate `nt_db` directories for the current machine. */
+export function findQQDataDirs(): string[] {
+  const dirs: string[] = [];
+  const seen = new Set<string>();
+  const push = (dir: string): void => {
+    if (!dir || seen.has(dir) || !existsSync(dir)) return;
+    seen.add(dir);
+    dirs.push(dir);
+  };
+  const override = process.env.QQ_MCP_DATA_DIR;
+  if (override) for (const part of override.split(";")) push(part.trim());
+  const docs = join(process.env.USERPROFILE ?? "", "Documents", "Tencent Files");
+  if (existsSync(docs)) {
+    for (const entry of safeReaddir(docs)) {
+      push(join(docs, entry, "nt_qq", "nt_db"));
+    }
+    push(join(docs, "nt_qq", "global", "nt_db"));
+  }
+  return dirs;
+}
+
+function safeReaddir(dir: string): string[] {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}
+
+/** Lists NTQQ databases found in the given directories (defaults to {@link findQQDataDirs}). */
+export function listDataSources(dirs: string[] = findQQDataDirs()): DataSource[] {
+  const out: DataSource[] = [];
+  for (const dir of dirs) {
+    for (const entry of safeReaddir(dir)) {
+      if (!entry.endsWith(".db")) continue;
+      const dbPath = join(dir, entry);
+      try {
+        const stats = statSync(dbPath);
+        const header = parseNtqqHeader(dbPath);
+        const materialPath = `${dbPath}-first.material`;
+        out.push({
+          name: entry,
+          dbPath,
+          bytes: stats.size,
+          pages: pageCount(dbPath),
+          saltHex: readSalt(dbPath).toString("hex"),
+          formatVersion: header.formatVersion,
+          materialPath: existsSync(materialPath) ? materialPath : undefined,
+          mtimeMs: stats.mtimeMs,
+        });
+      } catch {
+        // Not an NTQQ database (stub files, unrelated sqlite) — skip.
+      }
+    }
+  }
+  return out;
+}
+
+/** Passphrase from an explicit argument, `QQ_MCP_PASSPHRASE`, or the `qqkey` file in {@link QQ_MCP_HOME}. */
+export function resolvePassphrase(explicit?: string): string | undefined {
+  if (explicit) return explicit;
+  const env = process.env.QQ_MCP_PASSPHRASE;
+  if (env) return env;
+  try {
+    const file = readFileSync(KEY_FILE, "utf8").trim();
+    if (file.length) return file;
+  } catch {
+    // No cached key file.
+  }
+  return undefined;
+}
+
+export function requirePassphrase(explicit?: string): string {
+  const passphrase = resolvePassphrase(explicit);
+  if (!passphrase) {
+    throw new Error(
+      `no device passphrase: pass \`passphrase\`, set QQ_MCP_PASSPHRASE, write ${KEY_FILE}, ` +
+        "or run capture_offline_key while QQ is logged in"
+    );
+  }
+  return passphrase;
+}
+
+/** Cache path for the decrypted form of `dbPath`; keyed by size+mtime so QQ writes invalidate it. */
+export function plaintextCachePath(dbPath: string, cacheDir = DEFAULT_CACHE_DIR): string {
+  const stats = statSync(dbPath);
+  const name = dbPath.split(/[\\/]/).pop() ?? "db";
+  return join(cacheDir, `${name}.${stats.size}.${Math.floor(stats.mtimeMs)}.plain.db`);
+}
+
+export interface EnsureResult {
+  path: string;
+  /** True when an existing cache entry was reused instead of re-decrypting. */
+  reused: boolean;
+  durationMs: number;
+}
+
+/** Decrypts `dbPath` into the cache (or reuses a fresh cache entry). */
+export function ensurePlaintext(
+  dbPath: string,
+  passphrase: string,
+  opts: { cacheDir?: string; force?: boolean; onProgress?: (done: number, total: number) => void } = {}
+): EnsureResult {
+  if (!verifyPassphrase(dbPath, passphrase)) {
+    throw new Error(`passphrase does not decrypt ${dbPath} (wrong key or not an NTQQ database)`);
+  }
+  const cacheDir = opts.cacheDir ?? DEFAULT_CACHE_DIR;
+  mkdirSync(cacheDir, { recursive: true });
+  const target = plaintextCachePath(dbPath, cacheDir);
+  const started = Date.now();
+  if (!opts.force && existsSync(target)) {
+    return { path: target, reused: true, durationMs: 0 };
+  }
+  const result = reconstructDatabase({ dbPath, passphrase, outPath: target, onProgress: opts.onProgress });
+  pruneCache(cacheDir, dbPath);
+  return { path: result.outPath, reused: false, durationMs: Date.now() - started };
+}
+
+/** Keeps at most two plaintext copies per source database, newest first. */
+function pruneCache(cacheDir: string, dbPath: string): void {
+  const name = dbPath.split(/[\\/]/).pop() ?? "db";
+  try {
+    const entries = safeReaddir(cacheDir)
+      .filter((e) => e.startsWith(`${name}.`) && e.endsWith(".plain.db"))
+      .map((e) => ({ e, mtimeMs: statSync(join(cacheDir, e)).mtimeMs }))
+      .sort((a, b) => b.mtimeMs - a.mtimeMs);
+    for (const stale of entries.slice(2)) rmSync(join(cacheDir, stale.e), { force: true });
+  } catch {
+    // Cache pruning is best-effort.
+  }
+}
+
+export interface OfflineOptions {
+  passphrase?: string;
+  cacheDir?: string;
+  /** Skip decryption entirely and use this plaintext file. */
+  plaintextPath?: string;
+  force?: boolean;
+}
+
+export interface OfflineDatabase {
+  db: DatabaseSync;
+  plaintextPath: string;
+  sourcePath: string;
+}
+
+/** Opens a decrypted NTQQ database read-only. */
+export function openOffline(dbPath: string, opts: OfflineOptions = {}): OfflineDatabase {
+  const plaintextPath = opts.plaintextPath ?? ensurePlaintext(dbPath, requirePassphrase(opts.passphrase), opts).path;
+  return { db: new DatabaseSync(plaintextPath, { readOnly: true, readBigInts: true }), plaintextPath, sourcePath: dbPath };
+}
+
+const MSG_SELECT = `[40001] AS msgId, [40011] AS msgType, [40013] AS direction, [40020] AS senderUid,
+  [40021] AS peerUid, [40033] AS senderQq, [40030] AS peerQq, [40027] AS conversationId,
+  [40050] AS timestamp, [40093] AS senderName, [40800] AS body`;
+
+export interface MessageQuery {
+  /** `c2c`, `group`, or both. */
+  chat?: "c2c" | "group" | "all";
+  /** For c2c: the other party's QQ number. */
+  peerQq?: number;
+  /** For group: the group number. */
+  groupQq?: number;
+  since?: number;
+  until?: number;
+  /** Substring match on decoded text (case-sensitive). */
+  keyword?: string;
+  limit?: number;
+  /** Newest first by default. */
+  order?: "asc" | "desc";
+  /** Stop after this many rows scanned without keyword matches; guards full scans. */
+  maxScan?: number;
+}
+
+export interface MessageQueryResult {
+  messages: MessageRecord[];
+  scanned: number;
+  truncated: boolean;
+}
+
+/**
+ * Queries chat messages. Text lives inside protobuf, so keyword filtering
+ * happens after decoding; rows are paged by primary key (keyset) rather than by
+ * an index, because some QQ databases ship damaged index pages while the table
+ * b-trees stay readable. `maxScan` bounds how deep a keyword search may go.
+ */
+export function queryMessages(offline: OfflineDatabase, query: MessageQuery = {}): MessageQueryResult {
+  const { db } = offline;
+  const limit = Math.min(Math.max(query.limit ?? 100, 1), 5000);
+  const order = query.order === "asc" ? "ASC" : "DESC";
+  const comparator = order === "ASC" ? "<" : ">";
+  const maxScan = query.maxScan ?? 200_000;
+  const pageSize = 1000;
+  const chats: Array<"c2c" | "group"> =
+    query.chat === "all" || query.chat === undefined ? ["c2c", "group"] : [query.chat];
+
+  const messages: MessageRecord[] = [];
+  let scanned = 0;
+  for (const chatType of chats) {
+    if (messages.length >= limit || scanned >= maxScan) break;
+    const table = chatType === "c2c" ? "c2c_msg_table" : "group_msg_table";
+    const filters: string[] = [];
+    if (chatType === "c2c" && query.peerQq !== undefined) {
+      filters.push(`([40030] = ${Number(query.peerQq)} OR [40033] = ${Number(query.peerQq)})`);
+    }
+    if (chatType === "group" && query.groupQq !== undefined) {
+      filters.push(`[40027] = ${Number(query.groupQq)}`);
+    }
+    if (query.since !== undefined) filters.push(`[40050] >= ${Number(query.since)}`);
+    if (query.until !== undefined) filters.push(`[40050] <= ${Number(query.until)}`);
+    let cursor: string | undefined;
+    for (;;) {
+      const where = [...filters];
+      if (cursor) where.push(`[40001] ${comparator} '${cursor}'`);
+      const sql = `SELECT ${MSG_SELECT} FROM ${table} ${
+        where.length ? `WHERE ${where.join(" AND ")}` : ""
+      } ORDER BY [40001] ${order} LIMIT ${pageSize}`;
+      let rows: RawMessageRow[];
+      try {
+        rows = db.prepare(sql).all() as unknown as RawMessageRow[];
+      } catch (error) {
+        throw new Error(`query failed on ${table}: ${(error as Error).message}`);
+      }
+      if (rows.length === 0) break;
+      for (const row of rows) {
+        scanned++;
+        cursor = String(row.msgId);
+        const record = toMessageRecord(row, chatType);
+        if (query.keyword && !record.text.includes(query.keyword)) continue;
+        if (messages.length >= limit) {
+          return finish(messages, scanned, order);
+        }
+        messages.push(record);
+      }
+      if (rows.length < pageSize || scanned >= maxScan) break;
+    }
+  }
+  const truncated = scanned >= maxScan && messages.length < limit;
+  return finish(messages, scanned, order, truncated);
+}
+
+function finish(messages: MessageRecord[], scanned: number, order: "ASC" | "DESC", truncated = false): MessageQueryResult {
+  messages.sort((a, b) => (order === "DESC" ? b.timestamp - a.timestamp : a.timestamp - b.timestamp));
+  return { messages, scanned, truncated };
+}
+
+export interface ContactRecord {
+  kind: "friend" | "group";
+  qq?: number;
+  uid?: string;
+  name?: string;
+  remark?: string;
+  lastActive?: number;
+  source: "recent_contact" | "group_info" | "uid_mapping";
+}
+
+export interface ContactsResult {
+  friends: ContactRecord[];
+  groups: ContactRecord[];
+  uidMappings: Array<{ qq: number; uid: string }>;
+}
+
+/**
+ * Contact book: friends from `recent_contact_v3_table`, groups from
+ * `group_info.db.group_list` when available, plus the QQ↔NT-UID mapping table.
+ */
+export function listContacts(offline: OfflineDatabase, opts: { groupInfoPath?: string; passphrase?: string; limit?: number } = {}): ContactsResult {
+  const limit = Math.min(Math.max(opts.limit ?? 500, 1), 5000);
+  const friends = readFriends(offline.db, limit);
+  const uidMappings = readUidMappings(offline.db, limit);
+  const groups = opts.groupInfoPath ? readGroups(opts.groupInfoPath, opts.passphrase, limit) : [];
+  return { friends, groups, uidMappings };
+}
+
+function readFriends(db: DatabaseSync, limit: number): ContactRecord[] {
+  const rows = db
+    .prepare(
+      `SELECT [40020] AS uid, [40033] AS qq, [40090] AS name1, [40093] AS name2, [40050] AS lastActive
+       FROM recent_contact_v3_table
+       WHERE cast([40020] AS TEXT) GLOB 'u_*'
+       ORDER BY [40050] DESC LIMIT ${limit}`
+    )
+    .all() as Array<Record<string, unknown>>;
+  return rows.map((row) => ({
+    kind: "friend" as const,
+    qq: Number(row.qq) || undefined,
+    uid: String(row.uid ?? "") || undefined,
+    name: String(row.name1 ?? "") || String(row.name2 ?? "") || undefined,
+    lastActive: Number(row.lastActive) || undefined,
+    source: "recent_contact" as const,
+  }));
+}
+
+function readUidMappings(db: DatabaseSync, limit: number): Array<{ qq: number; uid: string }> {
+  const rows = db
+    .prepare(`SELECT [1002] AS qq, [48902] AS uid FROM nt_uid_mapping_table LIMIT ${limit}`)
+    .all() as Array<Record<string, unknown>>;
+  return rows
+    .map((row) => ({ qq: Number(row.qq), uid: String(row.uid ?? "") }))
+    .filter((r) => Number.isFinite(r.qq) && r.uid.length > 0);
+}
+
+function readGroups(groupInfoPath: string, passphrase: string | undefined, limit: number): ContactRecord[] {
+  const { db } = openOffline(groupInfoPath, { passphrase });
+  const rows = db
+    .prepare(
+      `SELECT [60001] AS qq, [60007] AS name, [60006] AS members, [60004] AS owner, [60008] AS notice
+       FROM group_list WHERE cast([60001] AS TEXT) GLOB '[0-9]*' ORDER BY [60006] DESC LIMIT ${limit}`
+    )
+    .all() as Array<Record<string, unknown>>;
+  return rows.map((row) => ({
+    kind: "group" as const,
+    qq: Number(row.qq) || undefined,
+    name: String(row.name ?? "") || undefined,
+    remark: String(row.notice ?? "") || undefined,
+    source: "group_info" as const,
+  }));
+}
+
+export interface GroupMemberRecord {
+  groupQq: number;
+  qq?: number;
+  uid?: string;
+  nickname?: string;
+  card?: string;
+  lastSpeakTs?: number;
+}
+
+/** Group member roster from `group_info.db.group_member3`. */
+export function listGroupMembers(groupInfoPath: string, opts: { passphrase?: string; groupQq?: number; limit?: number } = {}): GroupMemberRecord[] {
+  const limit = Math.min(Math.max(opts.limit ?? 200, 1), 5000);
+  const { db } = openOffline(groupInfoPath, { passphrase: opts.passphrase });
+  const where = opts.groupQq !== undefined ? `WHERE [60001] = ${Number(opts.groupQq)}` : "";
+  const rows = db
+    .prepare(
+      `SELECT [60001] AS groupQq, [1002] AS qq, [1000] AS uid, [20002] AS nickname, [64003] AS card,
+        [64008] AS lastSpeakTs FROM group_member3 ${where} ORDER BY [64008] DESC LIMIT ${limit}`
+    )
+    .all() as Array<Record<string, unknown>>;
+  return rows.map((row) => ({
+    groupQq: Number(row.groupQq),
+    qq: Number(row.qq) || undefined,
+    uid: String(row.uid ?? "") || undefined,
+    nickname: String(row.nickname ?? "") || undefined,
+    card: String(row.card ?? "") || undefined,
+    lastSpeakTs: Number(row.lastSpeakTs) || undefined,
+  }));
+}
+
+export interface ChatStats {
+  c2cMessages: number;
+  groupMessages: number;
+  contacts: number;
+  groups: number;
+  firstTimestamp?: number;
+  lastTimestamp?: number;
+}
+
+/** Row counts and time span of a decrypted `nt_msg.db`. */
+export function chatStats(offline: OfflineDatabase): ChatStats {
+  const { db } = offline;
+  const one = (sql: string): number => {
+    try {
+      const row = db.prepare(sql).get() as { v?: unknown } | undefined;
+      return Number(row?.v ?? 0);
+    } catch {
+      return 0;
+    }
+  };
+  return {
+    c2cMessages: one("SELECT count(*) AS v FROM c2c_msg_table"),
+    groupMessages: one("SELECT count(*) AS v FROM group_msg_table"),
+    contacts: one("SELECT count(*) AS v FROM recent_contact_v3_table"),
+    groups: one("SELECT count(DISTINCT [40027]) AS v FROM group_msg_table"),
+    firstTimestamp: one("SELECT min([40050]) AS v FROM c2c_msg_table") || undefined,
+    lastTimestamp: one("SELECT max([40050]) AS v FROM c2c_msg_table") || undefined,
+  };
+}

package/src/schema.ts

@@ -0,0 +1,101 @@
+/**
+ * QQNT database schema extraction from the `<db>.material` key-material files.
+ *
+ * Reverse-engineered on the local Windows NTQQ 9.9.35 install:
+ *   - The material file layout is: [16B salt][AES-256-CBC ciphertext]
+ *   - enc_key = PBKDF2-HMAC-SHA512(passphrase, salt, 4000, 32), IV = zero block
+ *   - Decrypted payload is a plaintext stream of SQL DDL (CREATE TABLE / CREATE INDEX)
+ *     describing the full schema of the corresponding SQLCipher database.
+ *
+ * Pure Node.js (node:crypto), works fully offline once passphrase + material path
+ * are known (passphrase can be captured from a running QQ via the debugger helper
+ * in scripts/ — see README).
+ */
+import { createDecipheriv, pbkdf2Sync } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+export const DEFAULT_KDF_ITER = 4000;
+
+export interface DecryptedMaterial {
+  /** 16-byte KDF salt (matches the first 16 bytes of the .material file and the SQLCipher salt at offset 1024). */
+  salt: Buffer;
+  /** Full decrypted payload (DDL stream + embedded table names). */
+  plaintext: Buffer;
+}
+
+/**
+ * Decrypts a QQNT `.material` file into its plaintext payload.
+ */
+export function decryptMaterial(path: string, passphrase: string | Buffer, kdfIter = DEFAULT_KDF_ITER): DecryptedMaterial {
+  const data = readFileSync(path);
+  if (data.length < 32) throw new Error(`material file too small: ${data.length} bytes`);
+  const salt = data.subarray(0, 16);
+  const body = data.subarray(16);
+  if (body.length % 16 !== 0) throw new Error(`material ciphertext not block aligned: ${body.length}`);
+
+  const key = pbkdf2Sync(passphrase, salt, kdfIter, 32, "sha512");
+  const decipher = createDecipheriv("aes-256-cbc", key, Buffer.alloc(16, 0));
+  decipher.setAutoPadding(false);
+  const plain = Buffer.concat([decipher.update(body), decipher.final()]);
+  return { salt, plaintext: plain };
+}
+
+export interface SchemaTable {
+  /** Extracted name (e.g. `c2c_msg_table`). */
+  name: string;
+  /** The CREATE TABLE statement if found. */
+  statement?: string;
+  /** Column definitions extracted from the statement. */
+  columns?: string[];
+}
+
+const CREATE_RE = /CREATE(?: UNIQUE)? (TABLE|INDEX)\s+([A-Za-z0-9_]+)\s*\(([^)]*)\)/g;
+
+/**
+ * Extracts table/DDL definitions from the decrypted material payload.
+ */
+export function extractSchema(plain: Buffer, maxStatements = 2000): SchemaTable[] {
+  const text = plain.toString("utf8");
+  const out: SchemaTable[] = [];
+  const seen = new Set<string>();
+
+  const re = /CREATE(?: UNIQUE)? (TABLE|INDEX)\s+([A-Za-z0-9_]+)/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(text)) !== null) {
+    const kind = m[1] as "TABLE" | "INDEX";
+    const name = m[2];
+    if (seen.has(name)) continue;
+    seen.add(name);
+
+    // Try to capture the full statement up to the closing paren.
+    let statement: string | undefined;
+    const start = m.index;
+    const close = findStatementEnd(text, start);
+    if (close > start) statement = text.substring(start, close);
+    else statement = text.substring(start, start + Math.min(200, text.length - start));
+
+    const entry: SchemaTable = { name };
+    if (kind === "TABLE" && statement) {
+      entry.statement = statement;
+      const cols = statement.match(/[\[\]]([0-9]{3,5})[\[\]]\s+(INTEGER|TEXT|BLOB|REAL|NUMERIC)/g);
+      if (cols) entry.columns = [...new Set(cols)];
+    }
+    out.push(entry);
+    if (out.length >= maxStatements) break;
+  }
+  return out;
+}
+
+/** Finds the index of the balanced closing parenthesis after `start`, or -1. */
+function findStatementEnd(text: string, start: number): number {
+  let depth = 0;
+  for (let i = start; i < text.length; i++) {
+    const c = text[i];
+    if (c === "(") depth++;
+    else if (c === ")") {
+      depth--;
+      if (depth === 0) return i + 1;
+    }
+  }
+  return -1;
+}