@powercess/qq-mcp 0.2.0

package/src/sqlcipher.ts

@@ -0,0 +1,326 @@
+/**
+ * Offline decryption of NTQQ (Windows QQ NT) SQLCipher databases — pure Node,
+ * no sqlcipher native dependency.
+ *
+ * Reverse-engineered layout, verified byte-exact against SQLCipher 4.12 on
+ * NTQQ 9.9.35.52892 (see docs/reverse-engineering.md):
+ *
+ *   file  = [1024-byte NTQQ header][salt 16B][page 2][page 3]...
+ *   page  = [16B salt, page 1 only][ciphertext][16B IV][32B tag]
+ *           ciphertext = AES-256-CBC(plaintext) with IV from the page tail
+ *   key   = PBKDF2-HMAC-SHA512(passphrase, salt, 4000, 32)
+ *   plaintext page 1 = [16B salt][SQLite header from offset 16 onward]
+ *
+ * The 32-byte tail tag is NOT authenticated here: no standard HMAC layout
+ * matched, and decryption does not need it (decrypted pages are validated by
+ * their SQLite structure instead).
+ */
+import { createDecipheriv, createCipheriv, pbkdf2Sync, createHash } from "node:crypto";
+import { closeSync, openSync, readSync, statSync, writeSync } from "node:fs";
+
+/** NTQQ custom header preceding the SQLCipher salt. */
+export const NTQQ_HEADER_SIZE = 1024;
+/** SQLite page size used by every NTQQ database. */
+export const DEFAULT_PAGE_SIZE = 4096;
+/** Bytes after the ciphertext: 16-byte IV followed by a 32-byte unchecked tag. */
+export const CRYPTO_TAIL_SIZE = 48;
+/** SQLCipher default KDF iteration count for this key size. */
+export const DEFAULT_KDF_ITER = 4000;
+const SQLITE_MAGIC = Buffer.from("SQLite format 3\0", "latin1");
+
+export interface NtqqHeader {
+  /** Page size parsed from the NTQQ header (always 4096 in practice). */
+  pageSize: number;
+  /** 32-byte device-level blob embedded in every NTQQ database header. */
+  deviceBlob: Buffer;
+  /** SQLCipher HMAC algorithm string advertised in the header, e.g. `HMAC_SHA1`. */
+  hmacAlgorithm: string;
+  /** Schema/format version string, e.g. `1.1.0.1`. */
+  formatVersion: string;
+}
+
+export interface DatabaseLayout {
+  /** Byte length of the NTQQ header: ciphertext pages start here. */
+  headerSize: number;
+  pageSize: number;
+  /** Size of the trailing crypto area inside each page. */
+  tailSize: number;
+}
+
+export const DEFAULT_LAYOUT: DatabaseLayout = {
+  headerSize: NTQQ_HEADER_SIZE,
+  pageSize: DEFAULT_PAGE_SIZE,
+  tailSize: CRYPTO_TAIL_SIZE,
+};
+
+function readAt(path: string, offset: number, length: number): Buffer {
+  const fd = openSync(path, "r");
+  try {
+    const buf = Buffer.alloc(length);
+    const n = readSync(fd, buf, 0, length, offset);
+    return buf.subarray(0, n);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** Parses the 1024-byte NTQQ header (magic, page size, device blob, algorithms). */
+export function parseNtqqHeader(path: string): NtqqHeader {
+  const buf = readAt(path, 0, NTQQ_HEADER_SIZE);
+  if (buf.length < NTQQ_HEADER_SIZE) throw new Error(`${path}: too small for an NTQQ header`);
+  if (buf.subarray(0, 15).toString("latin1") !== "SQLite header 3") {
+    throw new Error(`${path}: not an NTQQ database (bad magic ${JSON.stringify(buf.subarray(0, 15).toString("latin1"))})`);
+  }
+  const pageSize = buf.readUInt16BE(18);
+  const blobHex = buf.subarray(0x2f, 0xaf).toString("latin1");
+  if (!/^[0-9a-f]{128}$/i.test(blobHex)) throw new Error(`${path}: device blob missing`);
+  const text = buf.toString("latin1");
+  return {
+    pageSize: pageSize >= 512 && (pageSize & (pageSize - 1)) === 0 ? pageSize : DEFAULT_PAGE_SIZE,
+    deviceBlob: Buffer.from(blobHex, "hex"),
+    hmacAlgorithm: /HMAC_[A-Z0-9]+/.exec(text)?.[0] ?? "HMAC_SHA1",
+    formatVersion: /(\d+\.\d+\.\d+\.\d+)/.exec(text)?.[1] ?? "unknown",
+  };
+}
+
+/** Reads the 16-byte SQLCipher salt stored after the NTQQ header. */
+export function readSalt(path: string, layout: DatabaseLayout = DEFAULT_LAYOUT): Buffer {
+  const salt = readAt(path, layout.headerSize, 16);
+  if (salt.length !== 16) throw new Error(`${path}: missing salt at ${layout.headerSize}`);
+  return Buffer.from(salt);
+}
+
+export interface KeyOptions {
+  kdfIter?: number;
+  /** PBKDF2 PRF; SQLCipher 4 uses SHA-512 for the NTQQ key size. */
+  prf?: "sha512" | "sha256" | "sha1";
+}
+
+/** Derives the 32-byte AES key from the device passphrase and the database salt. */
+export function deriveKey(passphrase: string | Buffer, salt: Buffer, opts: KeyOptions = {}): Buffer {
+  const pass = typeof passphrase === "string" ? Buffer.from(passphrase, "utf8") : passphrase;
+  return pbkdf2Sync(pass, salt, opts.kdfIter ?? DEFAULT_KDF_ITER, 32, opts.prf ?? "sha512");
+}
+
+/** Decrypts one 4096-byte encrypted page into its SQLite plaintext form. */
+export function decryptPage(encrypted: Buffer, key: Buffer, pgno: number, layout: DatabaseLayout = DEFAULT_LAYOUT): Buffer {
+  const { pageSize, tailSize } = layout;
+  if (encrypted.length !== pageSize) throw new Error(`page ${pgno}: expected ${pageSize} bytes, got ${encrypted.length}`);
+  // Page 1 prefers the salt over the SQLite magic, so its first 16 bytes are not ciphertext.
+  const ctStart = pgno === 1 ? 16 : 0;
+  const ctEnd = pageSize - tailSize;
+  const ivStart = ctEnd;
+  const decipher = createDecipheriv("aes-256-cbc", key, encrypted.subarray(ivStart, ivStart + 16));
+  decipher.setAutoPadding(false);
+  const plain = Buffer.concat([decipher.update(encrypted.subarray(ctStart, ctEnd)), decipher.final()]);
+  const page = Buffer.alloc(pageSize);
+  plain.copy(page, ctStart);
+  return page;
+}
+
+/** Inverse of {@link decryptPage}; used to build round-trip fixtures and repacked databases. */
+export function encryptPage(plain: Buffer, key: Buffer, pgno: number, layout: DatabaseLayout = DEFAULT_LAYOUT): Buffer {
+  const { pageSize, tailSize } = layout;
+  if (plain.length !== pageSize) throw new Error(`page ${pgno}: expected ${pageSize} bytes, got ${plain.length}`);
+  const ctStart = pgno === 1 ? 16 : 0;
+  const ctEnd = pageSize - tailSize;
+  const page = Buffer.alloc(pageSize);
+  plain.subarray(ctStart, ctEnd).copy(page, ctStart);
+  // Deterministic IV: hash of the plaintext page, so encryption stays reproducible.
+  const iv = createHash("sha256").update(plain).digest().subarray(0, 16);
+  iv.copy(page, ctEnd);
+  const cipher = createCipheriv("aes-256-cbc", key, iv);
+  cipher.setAutoPadding(false);
+  cipher.update(page.subarray(ctStart, ctEnd)).copy(page, ctStart);
+  cipher.final();
+  return page;
+}
+
+export interface WalFrame {
+  pgno: number;
+  /** Database size after this frame when non-zero (commit marker). */
+  dbSize: number;
+  page: Buffer;
+}
+
+export interface WalContents {
+  frames: WalFrame[];
+  /** Frame count excluding frames past the last commit. */
+  committedFrames: number;
+  /** Database page count recorded by the last commit frame. */
+  dbSize?: number;
+}
+
+/**
+ * Reads a `-wal` file, verifying the WAL checksum chain, and returns only the
+ * frames up to the last committed transaction.
+ */
+export function readWal(walPath: string, layout: DatabaseLayout = DEFAULT_LAYOUT): WalContents {
+  const { pageSize } = layout;
+  const size = statSync(walPath).size;
+  const frameSize = 24 + pageSize;
+  if (size < 32 + frameSize) return { frames: [], committedFrames: 0 };
+  const fd = openSync(walPath, "r");
+  const buf = Buffer.alloc(size);
+  try {
+    readSync(fd, buf, 0, size, 0);
+  } finally {
+    closeSync(fd);
+  }
+  const walPageSize = buf.readUInt32BE(8);
+  if (walPageSize !== pageSize) return { frames: [], committedFrames: 0 };
+  const bigEndian = (buf.readUInt32BE(0) & 1) === 1;
+  const salt1 = buf.readUInt32BE(16);
+  const salt2 = buf.readUInt32BE(20);
+  const checksum = (data: Buffer, s0: number, s1: number): [number, number] => {
+    for (let i = 0; i + 8 <= data.length; i += 8) {
+      const a = bigEndian ? data.readUInt32BE(i) : data.readUInt32LE(i);
+      const b = bigEndian ? data.readUInt32BE(i + 4) : data.readUInt32LE(i + 4);
+      s0 = (s0 + a + s1) >>> 0;
+      s1 = (s1 + b + s0) >>> 0;
+    }
+    return [s0, s1];
+  };
+  let [s0, s1] = checksum(buf.subarray(0, 24), 0, 0);
+  const raw: WalFrame[] = [];
+  const count = Math.floor((size - 32) / frameSize);
+  for (let i = 0; i < count; i++) {
+    const off = 32 + i * frameSize;
+    const head = buf.subarray(off, off + 24);
+    if (head.readUInt32BE(8) !== salt1 || head.readUInt32BE(12) !== salt2) break;
+    [s0, s1] = checksum(head.subarray(0, 8), s0, s1);
+    [s0, s1] = checksum(buf.subarray(off + 24, off + 24 + pageSize), s0, s1);
+    if (s0 !== head.readUInt32BE(16) || s1 !== head.readUInt32BE(20)) break;
+    raw.push({ pgno: head.readUInt32BE(0), dbSize: head.readUInt32BE(4), page: buf.subarray(off + 24, off + 24 + pageSize) });
+  }
+  let lastCommit = -1;
+  raw.forEach((f, i) => {
+    if (f.dbSize !== 0) lastCommit = i;
+  });
+  if (lastCommit < 0) return { frames: [], committedFrames: 0 };
+  return { frames: raw.slice(0, lastCommit + 1), committedFrames: lastCommit + 1, dbSize: raw[lastCommit].dbSize };
+}
+
+export interface ReconstructOptions {
+  /** Database file; defaults to `<nt_msg.db>` semantics — any NTQQ database. */
+  dbPath: string;
+  /** Device passphrase, or a 32-byte raw key. */
+  passphrase?: string | Buffer;
+  /** Pre-derived 32-byte key (skips PBKDF2). */
+  key?: Buffer;
+  /** Output path for the plaintext SQLite file. */
+  outPath: string;
+  /** Replay `<dbPath>-wal` frames (default true). */
+  wal?: boolean;
+  layout?: DatabaseLayout;
+  kdf?: KeyOptions;
+  onProgress?: (done: number, total: number) => void;
+}
+
+export interface ReconstructResult {
+  outPath: string;
+  pageCount: number;
+  /** Pages replaced by committed WAL frames. */
+  walPages: number;
+  bytes: number;
+  durationMs: number;
+}
+
+/** Page count of an NTQQ database file. */
+export function pageCount(dbPath: string, layout: DatabaseLayout = DEFAULT_LAYOUT): number {
+  const size = statSync(dbPath).size;
+  if (size < layout.headerSize + layout.pageSize) return 0;
+  return Math.floor((size - layout.headerSize) / layout.pageSize);
+}
+
+/**
+ * Decrypts a whole NTQQ database (optionally replaying its WAL) into a plain
+ * SQLite file. Streaming: memory use is bounded by the batch size, not the
+ * database size.
+ */
+export function reconstructDatabase(opts: ReconstructOptions): ReconstructResult {
+  const layout = opts.layout ?? DEFAULT_LAYOUT;
+  const { dbPath, outPath } = opts;
+  const { pageSize, headerSize } = layout;
+  const total = pageCount(dbPath, layout);
+  if (total === 0) throw new Error(`${dbPath}: no pages (file too small or wrong layout)`);
+  const key = opts.key ?? deriveKey(opts.passphrase ?? "", readSalt(dbPath, layout), opts.kdf);
+
+  const walPages = new Map<number, Buffer>();
+  let walDBSize: number | undefined;
+  if (opts.wal !== false) {
+    try {
+      const wal = readWal(`${dbPath}-wal`, layout);
+      if (wal.dbSize) {
+        walDBSize = wal.dbSize;
+        for (const f of wal.frames) walPages.set(f.pgno, f.page);
+      }
+    } catch {
+      // A missing or unreadable WAL only costs us the newest frames.
+    }
+  }
+  const effectiveTotal = walDBSize ? Math.min(walDBSize, total) : total;
+
+  const src = openSync(dbPath, "r");
+  const dst = openSync(outPath, "w");
+  const started = Date.now();
+  try {
+    const batch = 256;
+    const inBuf = Buffer.alloc(pageSize * batch);
+    const outBuf = Buffer.alloc(pageSize * batch);
+    let done = 0;
+    while (done < effectiveTotal) {
+      const n = Math.min(batch, effectiveTotal - done);
+      const got = readSync(src, inBuf, 0, n * pageSize, headerSize + done * pageSize);
+      if (got < n * pageSize) throw new Error(`${dbPath}: short read at page ${done + 1}`);
+      for (let i = 0; i < n; i++) {
+        const pgno = done + i + 1;
+        const encrypted = walPages.get(pgno) ?? inBuf.subarray(i * pageSize, (i + 1) * pageSize);
+        const plain = decryptPage(encrypted, key, pgno, layout);
+        if (pgno === 1) {
+          // SQLite needs its magic; the salt it replaces is not used by readers.
+          SQLITE_MAGIC.copy(plain, 0);
+        }
+        plain.copy(outBuf, i * pageSize);
+      }
+      writeSync(dst, outBuf, 0, n * pageSize);
+      done += n;
+      opts.onProgress?.(done, effectiveTotal);
+    }
+    return {
+      outPath,
+      pageCount: effectiveTotal,
+      walPages: walPages.size,
+      bytes: effectiveTotal * pageSize,
+      durationMs: Date.now() - started,
+    };
+  } finally {
+    closeSync(src);
+    closeSync(dst);
+  }
+}
+
+/**
+ * True when `passphrase` decrypts page 1 of `dbPath` into a plausible page:
+ * a SQLite header carrying the expected page size, plus a valid b-tree header
+ * for the `sqlite_schema` root page. The salt occupies bytes 0..16, the rest of
+ * the header keeps its standard offsets.
+ */
+export function verifyPassphrase(dbPath: string, passphrase: string | Buffer, layout: DatabaseLayout = DEFAULT_LAYOUT): boolean {
+  try {
+    const key = deriveKey(passphrase, readSalt(dbPath, layout), {});
+    const page = readAt(dbPath, layout.headerSize, layout.pageSize);
+    if (page.length !== layout.pageSize) return false;
+    const plain = decryptPage(page, key, 1, layout);
+    if (plain.readUInt16BE(16) !== layout.pageSize) return false;
+    const pageType = plain[100];
+    const freeblock = plain.readUInt16BE(101);
+    const cellCount = plain.readUInt16BE(103);
+    if (![2, 5, 10, 13].includes(pageType)) return false;
+    if (freeblock !== 0 && (freeblock < 100 || freeblock >= layout.pageSize)) return false;
+    if (cellCount > layout.pageSize / 4) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/verify-worker.ts

@@ -0,0 +1,18 @@
+/**
+ * Worker that tests a slice of candidate passphrases against an NTQQ key
+ * oracle. Candidate checking is PBKDF2-bound (~1 ms each), so the parent fans
+ * the work out across cores instead of blocking the event loop.
+ */
+import { parentPort, workerData } from "node:worker_threads";
+import { verifyKeyCandidate, type KeyOracle } from "./keyscan.js";
+
+const { oracle, candidates } = workerData as { oracle: KeyOracle; candidates: string[] };
+let tested = 0;
+for (const candidate of candidates) {
+  tested++;
+  if (verifyKeyCandidate(oracle, candidate)) {
+    parentPort?.postMessage({ passphrase: candidate, tested });
+    break;
+  }
+}
+parentPort?.postMessage({ passphrase: undefined, tested });