chrome-tools 1.1.10 → 1.1.11

package/README.md

@@ -1,3 +1,34 @@
 # chrome-tools
 
 CLI & Node.js library for Chrome browser data, including passwords, bookmarks, history, cookies, and localStorage.
+
+## Requirements
+
+**Node.js >= 22.16.0.** Chrome's stores are read through the built-in
+[`node:sqlite`](https://nodejs.org/api/sqlite.html) module rather than a native
+dependency, so there is nothing to compile at install time. 22.16.0 is the floor
+because that is the release where the connection `timeout` option began to be
+honoured — on 22.15 and earlier it is accepted and silently ignored, which is
+worse than rejected.
+
+### The experimental warning
+
+Node prints this to **stderr** on the first `node:sqlite` load, once per process:
+
+```
+(node:12345) ExperimentalWarning: SQLite is an experimental feature and might change at any time
+```
+
+Measured across releases, it is emitted on **22.16 through 25.6**, and is silent
+from **25.7.0**, where `node:sqlite` moved to Node's "release candidate"
+stability index. So on current LTS you should expect to see it.
+
+It is a warning, not an error: stdout stays clean, so piping JSON out of the CLI
+is unaffected. If you drive this from a harness that treats *any* stderr output
+as failure, set `NODE_NO_WARNINGS=1` (or run node with `--no-warnings`) in that
+harness. This package deliberately does not suppress the warning for you — a
+library silencing process-wide warnings would hide unrelated ones too.
+
+Because the module is still pre-stable, its API may change between major Node
+releases. The surface used here — `prepare`, `all`, `run`, `close`,
+`setReadBigInts`, and `VACUUM INTO` — has been present since 22.5.0.

package/dist/src/core/db.js

@@ -1,13 +1,95 @@
 import { copyFileSync, existsSync, mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, basename } from "node:path";
-import Database from "better-sqlite3";
-/** Whether a failure is "another process owns this database", not a broken one. */
+import { DatabaseSync } from "node:sqlite";
+/** SQLite result codes meaning "someone else owns this database right now". */
+const SQLITE_BUSY = 5;
+const SQLITE_LOCKED = 6;
+/**
+ * Whether a failure is "another process owns this database", not a broken one.
+ *
+ * `node:sqlite` reports *every* failure as `code: "ERR_SQLITE_ERROR"` and puts
+ * the SQLite result code in `errcode`, so the `code` property is useless as a
+ * discriminator here — reading it is what an obvious port of this function from
+ * `better-sqlite3` (which set `code: "SQLITE_BUSY"`) would do, and it would call
+ * every locked store a corrupt one.
+ *
+ * Masked to the low byte because SQLite may report an *extended* code — 517
+ * (`SQLITE_BUSY_SNAPSHOT`) and 262 (`SQLITE_LOCKED_SHAREDCACHE`) are the same
+ * two conditions with detail attached, and both must take the copy path.
+ *
+ * The message check stays as the fallback: it is what caught this before
+ * `errcode` existed, and it costs nothing to keep for a build that leaves the
+ * field unset.
+ */
 function isLocked(err) {
-    const code = err?.code;
+    const errcode = err?.errcode;
+    if (typeof errcode === "number") {
+        const primary = errcode & 0xff;
+        if (primary === SQLITE_BUSY || primary === SQLITE_LOCKED)
+            return true;
+    }
     const message = err instanceof Error ? err.message : String(err);
-    return ((typeof code === "string" && code.startsWith("SQLITE_BUSY")) ||
-        /database is locked|database is busy/i.test(message));
+    return /database is locked|database is busy/i.test(message);
+}
+/**
+ * Puts a row back into the shape callers have always been handed: an ordinary
+ * object, holding plain numbers, with `Buffer` for a BLOB.
+ *
+ * `queryDatabase` is exported from the package root, so all three of these are
+ * public API rather than internal detail — a caller running its own SQL against
+ * `Login Data` gets whatever this returns.
+ *
+ * **The object itself.** `node:sqlite` builds each row with a null prototype,
+ * where better-sqlite3 returned an ordinary object. `Object.keys`, `in`, and
+ * `JSON.stringify` all still work, which is why this hides so well — but
+ * `row.hasOwnProperty(…)` is a `TypeError`, and so is anything that coerces the
+ * row to a string, including `String(row)` and dropping it in a template
+ * literal. Rebuilt here rather than re-prototyped: the loop that has to visit
+ * every cell anyway is the cheapest place to do it.
+ *
+ * **Integers.** This is the whole reason the statement is put in BigInt mode.
+ * `node:sqlite` does not quietly lose precision past `Number.MAX_SAFE_INTEGER`
+ * the way better-sqlite3 did — it **throws** `ERR_OUT_OF_RANGE` partway through
+ * reading the row. Chrome writes every timestamp as microseconds since 1601,
+ * which lands around 1.3e16 and is therefore *always* past that line, so in the
+ * default number mode a `History`, `Login Data`, or `Cookies` row cannot be read
+ * at all. Not an edge case: it is every row with a time on it. BigInt mode is
+ * the only mode that can read those columns, and this undoes the widening so
+ * nothing downstream has to learn a second numeric type. The precision that
+ * costs is precision better-sqlite3 was already dropping — sub-2-microsecond
+ * detail on a 400-year-old epoch.
+ *
+ * **Blobs.** `node:sqlite` hands back a bare `Uint8Array` where better-sqlite3
+ * gave a `Buffer`, and the difference is not a type-checking nicety: it fails
+ * *silently*. `Buffer` is a `Uint8Array`, so an `instanceof` guard still passes
+ * and nothing throws — but `blob.toString("utf-8")` on the bare array ignores
+ * the encoding and returns the decimal bytes joined by commas, so a caller
+ * decoding `password_value` or `encrypted_value` gets `"118,49,48,…"` and no
+ * error to notice. `Buffer.isBuffer` also flips to false, and the read helpers
+ * (`readUInt32BE`, `equals`, …) are simply absent.
+ *
+ * Wrapped rather than copied: each row owns its own `ArrayBuffer` here, so
+ * re-using the memory is safe and a large blob is not duplicated to change its
+ * prototype. An actual `Buffer` is left alone.
+ */
+function toCallerTypes(rows) {
+    return rows.map((row) => {
+        const plain = {};
+        for (const key of Object.keys(row)) {
+            const value = row[key];
+            if (typeof value === "bigint") {
+                plain[key] = Number(value);
+            }
+            else if (value instanceof Uint8Array && !Buffer.isBuffer(value)) {
+                plain[key] = Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+            }
+            else {
+                plain[key] = value;
+            }
+        }
+        return plain;
+    });
 }
 /**
  * Copies a database SQLite will not open, alongside the sidecars that make it
@@ -44,9 +126,16 @@ export function queryDatabase(dbFilePath, sql, params = []) {
     const tmpDb = join(tmpDir, basename(dbFilePath));
     let sourceDb;
     try {
-        sourceDb = new Database(dbFilePath, {
-            readonly: true,
-            fileMustExist: true,
+        sourceDb = new DatabaseSync(dbFilePath, {
+            // `readOnly`, not `readonly`. An unrecognized option is *ignored* rather
+            // than rejected, so the lowercase spelling — which is what better-sqlite3
+            // called it, and what this line used to say — silently hands back a
+            // writable handle onto the user's live browser profile.
+            readOnly: true,
+            // No `fileMustExist` equivalent, and none needed: a read-only open will
+            // not create the file, and the `existsSync` guard above is the explicit
+            // check that turns a missing store into a message worth reading.
+            //
             // No wait. A running Chrome holds these stores in `locking_mode =
             // EXCLUSIVE` for as long as it is open, so a busy timeout here buys
             // nothing that waiting longer would win — the lock is not transient, and
@@ -90,9 +179,12 @@ export function queryDatabase(dbFilePath, sql, params = []) {
     }
     let db;
     try {
-        db = new Database(tmpDb, { readonly: true, timeout: 5000 });
+        db = new DatabaseSync(tmpDb, { readOnly: true, timeout: 5000 });
         const stmt = db.prepare(sql);
-        return params.length > 0 ? stmt.all(...params) : stmt.all();
+        // Read wide, hand back narrow. See `toCallerTypes` — without this, every
+        // query that touches a Chrome timestamp throws instead of returning rows.
+        stmt.setReadBigInts(true);
+        return toCallerTypes(params.length > 0 ? stmt.all(...params) : stmt.all());
     }
     catch (err) {
         throw new Error(`Database query failed on '${basename(dbFilePath)}': ${err.message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-tools",
-  "version": "1.1.10",
+  "version": "1.1.11",
   "description": "CLI & Node.js library for chrome",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -52,16 +52,14 @@
   "license": "MIT",
   "packageManager": "pnpm@11.9.0",
   "dependencies": {
-    "better-sqlite3": "^13.0.3",
     "chalk": "^6.0.0",
     "cli-table3": "^0.6.5",
     "commander": "^15.0.0"
   },
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=22.16.0"
   },
   "devDependencies": {
-    "@types/better-sqlite3": "^9.6.0",
     "@types/node": "^26.1.2",
     "oxlint": "1.77.0",
     "typescript": "^7.0.2"