chrome-tools 1.1.8 → 1.1.10

package/dist/bin/cli.js

@@ -12,7 +12,7 @@ import chalk from "chalk";
 import Table from "cli-table3";
 import { discoverProfiles, getProfileMetadata, getProfileStates, getDirectorySize, detectInstalledBrowsers } from "../src/core/chrome.js";
 import { setActiveBrowser, getActiveBrowser, isKeychainAccessDenied } from "../src/core/platform/index.js";
-import { getPasswords } from "../src/modules/passwords.js";
+import { describePasswordStores, getPasswords } from "../src/modules/passwords.js";
 import { getBookmarks } from "../src/modules/bookmarks.js";
 import { getHistory, getSearchTerms } from "../src/modules/history.js";
 import { getCookies } from "../src/modules/cookies.js";
@@ -364,8 +364,12 @@ function handleProfileStates(opts) {
 }
 // ─── Passwords Command ──────────────────────────────────────────────────────
 const passwordsCmd = program.command("passwords").description("List saved passwords");
-addSearchOption(addCommonOptions(passwordsCmd)).action((opts, cmd) => dispatch(handlePasswords, scopeFromCli(cmd)));
+addSearchOption(addCommonOptions(passwordsCmd))
+    .option("--diagnose", "Report the stores that would be read — profile, file, row count, and any read error — instead of the passwords themselves")
+    .action((opts, cmd) => dispatch(handlePasswords, scopeFromCli(cmd)));
 function handlePasswords(opts) {
+    if (opts.diagnose)
+        return diagnosePasswords(opts);
     const results = getPasswords(opts);
     if (emit(opts, results))
         return;
@@ -398,6 +402,35 @@ function handlePasswords(opts) {
     console.log(table.toString());
     printCount("password(s)", results.length);
 }
+/**
+ * Explains an empty listing. A store that cannot be opened is skipped silently
+ * during a normal read, which leaves "no passwords found" meaning either
+ * "none saved" or "none readable" — this separates the two. Counts and errors
+ * only: nothing here is decrypted.
+ */
+function diagnosePasswords(opts) {
+    const reports = describePasswordStores(opts);
+    if (emit(opts, reports))
+        return;
+    if (reports.length === 0) {
+        console.log(chalk.yellow("\n⚠ No profiles found to read.\n"));
+        return;
+    }
+    console.log(chalk.bold("\n🔎 Password stores:\n"));
+    const table = makeTable(["Root", "Profile", "Store", "Exists", "Rows", "Error"], [34, 12, 24, 7, 6, 40]);
+    for (const r of reports) {
+        table.push([
+            chalk.dim(r.root),
+            r.profile,
+            chalk.blue(r.file),
+            r.exists ? "yes" : chalk.yellow("no"),
+            r.rows === null ? chalk.red("?") : String(r.rows),
+            r.error ? chalk.red(r.error) : "",
+        ]);
+    }
+    console.log(table.toString());
+    console.log();
+}
 // ─── Bookmarks Command ──────────────────────────────────────────────────────
 const bookmarksCmd = program.command("bookmarks").description("List bookmarks");
 addSearchOption(addCommonOptions(bookmarksCmd))

package/dist/src/core/db.d.ts

@@ -2,7 +2,8 @@
  * Creates a transactionally consistent snapshot of a Chrome SQLite database,
  * executes a query against it, and cleans up. `VACUUM INTO` reads through
  * SQLite itself, so live WAL contents are included without racing raw file
- * copies while Chrome is writing.
+ * copies while Chrome is writing. A store the browser holds exclusively cannot
+ * be opened that way at all, and falls back to a file copy (see below).
  *
  * @param dbFilePath - Absolute path to the Chrome database file.
  * @param sql - SQL query to execute.

package/dist/src/core/db.js

@@ -1,12 +1,34 @@
-import { existsSync, mkdtempSync, rmSync } from "node:fs";
+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. */
+function isLocked(err) {
+    const code = err?.code;
+    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));
+}
+/**
+ * Copies a database SQLite will not open, alongside the sidecars that make it
+ * readable: `-wal` holds commits not yet folded into the main file, and `-shm`
+ * is its index. Copying the main file alone would silently drop the most recent
+ * writes — a password saved a minute ago being exactly the kind that matters.
+ */
+function copyLockedDatabase(dbFilePath, tmpDb) {
+    copyFileSync(dbFilePath, tmpDb);
+    for (const suffix of ["-wal", "-shm"]) {
+        const sidecar = `${dbFilePath}${suffix}`;
+        if (existsSync(sidecar))
+            copyFileSync(sidecar, `${tmpDb}${suffix}`);
+    }
+}
 /**
  * Creates a transactionally consistent snapshot of a Chrome SQLite database,
  * executes a query against it, and cleans up. `VACUUM INTO` reads through
  * SQLite itself, so live WAL contents are included without racing raw file
- * copies while Chrome is writing.
+ * copies while Chrome is writing. A store the browser holds exclusively cannot
+ * be opened that way at all, and falls back to a file copy (see below).
  *
  * @param dbFilePath - Absolute path to the Chrome database file.
  * @param sql - SQL query to execute.
@@ -25,13 +47,36 @@ export function queryDatabase(dbFilePath, sql, params = []) {
         sourceDb = new Database(dbFilePath, {
             readonly: true,
             fileMustExist: true,
-            timeout: 5000,
+            // 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
+            // the copy below is the answer to it either way. Five seconds *per store*
+            // was the whole cost of reading a saved login while the browser was up:
+            // two stores, ten seconds, spent to arrive at the fallback that then
+            // succeeded instantly.
+            timeout: 0,
         });
         sourceDb.prepare("VACUUM INTO ?").run(tmpDb);
     }
     catch (err) {
-        cleanupTmp(tmpDir);
-        throw new Error(`Failed to snapshot database file '${basename(dbFilePath)}': ${err.message}`);
+        // A running Chrome holds its stores in `locking_mode = EXCLUSIVE`, which
+        // refuses every other connection — SQLite cannot even open them to read.
+        // That is not a corrupt or missing database, it is a browser that happens
+        // to be open, and it made a profile with saved passwords in it report none.
+        // Falling back to the file itself is what a locked store leaves: the OS
+        // copies bytes regardless of an advisory lock the copier never takes.
+        if (!isLocked(err)) {
+            cleanupTmp(tmpDir);
+            throw new Error(`Failed to snapshot database file '${basename(dbFilePath)}': ${err.message}`);
+        }
+        try {
+            copyLockedDatabase(dbFilePath, tmpDb);
+        }
+        catch (copyErr) {
+            cleanupTmp(tmpDir);
+            throw new Error(`Failed to snapshot database file '${basename(dbFilePath)}': ${err.message} ` +
+                `(copying it instead also failed: ${copyErr.message})`);
+        }
     }
     finally {
         if (sourceDb) {

package/dist/src/modules/passwords.d.ts

@@ -15,6 +15,30 @@ export interface PasswordEntry {
     lastUsed?: string;
     error?: string;
 }
+/** What a single password store looked like when it was read. */
+export interface PasswordStoreReport {
+    /** The User Data directory searched; "default" when the platform picked it. */
+    root: string;
+    profile: string;
+    /** "Login Data" (device) or "Login Data For Account" (synced). */
+    file: string;
+    source: PasswordSource;
+    exists: boolean;
+    /** Rows in `logins`, before any search filter. Null when the read failed. */
+    rows: number | null;
+    /** Why the read failed, when it did. No credential value is ever included. */
+    error?: string;
+}
+/**
+ * Reports what a `getPasswords` call would read, and what it could not.
+ *
+ * `getPasswords` skips a store it cannot open — a missing file, a schema it does
+ * not know, a database another process is holding — and an empty result cannot
+ * tell "nothing saved here" from "could not look". This runs the same profile
+ * resolution and opens the same databases, and answers with row counts and
+ * errors only. It decrypts nothing, so no password value can escape through it.
+ */
+export declare function describePasswordStores({ chromeDir, profilePath, profile, browser, }?: PasswordOptions): PasswordStoreReport[];
 /**
  * Extracts and decrypts saved passwords from Chrome's password databases.
  * Reads both the device-local and account-synced stores, labelling each entry

package/dist/src/modules/passwords.js

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { discoverProfiles, resolveTargetProfiles, } from "../core/chrome.js";
@@ -54,6 +54,75 @@ function configuredAutomationDir() {
         return undefined;
     }
 }
+/**
+ * The User Data directories a lookup reads, in order.
+ *
+ * The automation tree first, then the everyday one. A Chrome driven over CDP
+ * keeps its own profile tree, so a login saved while signing in to that window
+ * is stored there and nowhere else — looking only at the everyday tree could
+ * not find it. Naming a directory or a browser answers "which tree?" outright,
+ * and is used as given.
+ */
+function passwordRoots(userDataDir, browser) {
+    const roots = [];
+    const automation = userDataDir || browser ? undefined : automationChromeDir();
+    if (automation)
+        roots.push(automation);
+    roots.push(userDataDir);
+    return roots;
+}
+/**
+ * Reports what a `getPasswords` call would read, and what it could not.
+ *
+ * `getPasswords` skips a store it cannot open — a missing file, a schema it does
+ * not know, a database another process is holding — and an empty result cannot
+ * tell "nothing saved here" from "could not look". This runs the same profile
+ * resolution and opens the same databases, and answers with row counts and
+ * errors only. It decrypts nothing, so no password value can escape through it.
+ */
+export function describePasswordStores({ chromeDir, profilePath, profile, browser, } = {}) {
+    const userDataDir = profilePath || chromeDir;
+    const reports = [];
+    for (const root of passwordRoots(userDataDir, browser)) {
+        let profiles;
+        try {
+            profiles = resolveTargetProfiles({ chromeDir: root, profile, browser });
+        }
+        catch (error) {
+            reports.push({
+                root: root ?? "default",
+                profile: profile ?? "*",
+                file: "*",
+                source: "device",
+                exists: false,
+                rows: null,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            continue;
+        }
+        for (const p of profiles) {
+            for (const store of PASSWORD_STORES) {
+                const dbPath = join(p.path, store.file);
+                const report = {
+                    root: root ?? "default",
+                    profile: p.name,
+                    file: store.file,
+                    source: store.source,
+                    exists: existsSync(dbPath),
+                    rows: null,
+                };
+                try {
+                    report.rows = queryDatabase(dbPath, "SELECT COUNT(*) AS n FROM logins")[0]?.n ?? 0;
+                }
+                catch (error) {
+                    report.error = error instanceof Error ? error.message : String(error);
+                }
+                reports.push(report);
+            }
+        }
+    }
+    return reports;
+}
 /**
  * Extracts and decrypts saved passwords from Chrome's password databases.
  * Reads both the device-local and account-synced stores, labelling each entry
@@ -64,16 +133,7 @@ function configuredAutomationDir() {
  */
 export function getPasswords({ chromeDir, profilePath, profile, search, browser, decryptionKey, } = {}) {
     const userDataDir = profilePath || chromeDir;
-    // The automation User Data directory first, then the everyday one. A Chrome
-    // driven over CDP keeps its own profile tree, so a login saved while signing
-    // in to that window is stored there and nowhere else — looking only at the
-    // everyday tree could not find it. Naming a directory or a browser answers
-    // "which tree?" outright, and is used as given.
-    const roots = [];
-    const automation = userDataDir || browser ? undefined : automationChromeDir();
-    if (automation)
-        roots.push(automation);
-    roots.push(userDataDir);
+    const roots = passwordRoots(userDataDir, browser);
     const results = [];
     const term = search?.toLowerCase();
     // A named profile missing from one tree is not a failure while another is
@@ -100,7 +160,21 @@ export function getPasswords({ chromeDir, profilePath, profile, search, browser,
                     const rows = queryDatabase(dbPath, `SELECT origin_url, username_value, password_value, date_last_used
              FROM logins ORDER BY origin_url`);
                     for (const row of rows) {
-                        const entry = {
+                        // Matched before anything is decrypted. Both columns the search
+                        // looks at — the origin and the username — are stored in the clear,
+                        // so a row that cannot match never needs its password read at all.
+                        //
+                        // Decrypting first cost one platform decryption per stored login on
+                        // the way to finding one: a store with a few hundred entries spent
+                        // upwards of ten seconds answering "what is the password for this
+                        // one site", and every one of those decryptions was thrown away by
+                        // the filter immediately below.
+                        if (term &&
+                            !(row.origin_url && row.origin_url.toLowerCase().includes(term)) &&
+                            !(row.username_value && row.username_value.toLowerCase().includes(term))) {
+                            continue;
+                        }
+                        results.push({
                             profile: p.name,
                             source: store.source,
                             url: row.origin_url,
@@ -109,14 +183,7 @@ export function getPasswords({ chromeDir, profilePath, profile, search, browser,
                                 ? decryptValue(row.password_value, derivedKey ??= deriveEncryptionKey(root, browser))
                                 : "",
                             lastUsed: chromeTimeToDate(row.date_last_used || 0),
-                        };
-                        if (term) {
-                            if (!(entry.url && entry.url.toLowerCase().includes(term)) &&
-                                !(entry.username && entry.username.toLowerCase().includes(term))) {
-                                continue;
-                            }
-                        }
-                        results.push(entry);
+                        });
                     }
                 }
                 catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-tools",
-  "version": "1.1.8",
+  "version": "1.1.10",
   "description": "CLI & Node.js library for chrome",
   "type": "module",
   "main": "./dist/src/index.js",