chrome-tools 1.1.7 → 1.1.9

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.
@@ -30,8 +52,24 @@ export function queryDatabase(dbFilePath, sql, params = []) {
         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,5 +1,7 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
-import { resolveTargetProfiles } from "../core/chrome.js";
+import { discoverProfiles, resolveTargetProfiles, } from "../core/chrome.js";
 import { deriveEncryptionKey, decryptValue } from "../core/platform/index.js";
 import { chromeTimeToDate } from "../core/crypto.js";
 import { queryDatabase } from "../core/db.js";
@@ -14,6 +16,113 @@ const PASSWORD_STORES = [
     { file: "Login Data", source: "device" },
     { file: "Login Data For Account", source: "account" },
 ];
+/** Where a CDP launcher keeps the User Data directory it drives Chrome with. */
+const AUTOMATION_DIR = join(homedir(), ".chrome_cdp_profile");
+/** …and where it records a relocated one. */
+const AUTOMATION_CONFIG = join(homedir(), ".config", "chrome-cdp-manager", "config.json");
+/** `CHROME_AUTOMATION_DIR` values meaning "do not look there at all". */
+const AUTOMATION_OFF = ["0", "off", "none", "false"];
+/**
+ * The automation profile tree, on a machine that has one.
+ *
+ * Most machines do not: no CDP launcher is installed, the directory was never
+ * created, or it exists but holds no profile yet. All three answer undefined,
+ * which leaves the search exactly as it was before this existed — the everyday
+ * profile, alone. Nothing here is required for a plain Chrome install.
+ *
+ * `CHROME_AUTOMATION_DIR` names the tree explicitly, and `off` (or `0`, `none`,
+ * `false`) skips it even where one exists.
+ */
+function automationChromeDir() {
+    const override = process.env.CHROME_AUTOMATION_DIR?.trim();
+    if (override && AUTOMATION_OFF.includes(override.toLowerCase()))
+        return undefined;
+    const dir = override || configuredAutomationDir() || AUTOMATION_DIR;
+    // Holding a profile is what makes it a tree worth reading — an absent or
+    // empty directory would otherwise add a root every lookup searches for
+    // nothing, and turn a missing `--profile` into a spurious refusal.
+    return discoverProfiles(dir).length > 0 ? dir : undefined;
+}
+/** The profile directory a CDP launcher was configured with, if it says. */
+function configuredAutomationDir() {
+    try {
+        const stored = JSON.parse(readFileSync(AUTOMATION_CONFIG, "utf-8"));
+        return typeof stored.profileDir === "string" && stored.profileDir ? stored.profileDir : undefined;
+    }
+    catch {
+        // No launcher config, or an unreadable one: fall back to its default path.
+        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
@@ -24,41 +133,59 @@ const PASSWORD_STORES = [
  */
 export function getPasswords({ chromeDir, profilePath, profile, search, browser, decryptionKey, } = {}) {
     const userDataDir = profilePath || chromeDir;
-    const profiles = resolveTargetProfiles({ chromeDir, profilePath, profile, browser });
-    // Pass user-data dir so Windows reads Local State from the same tree as the profiles.
-    let derivedKey = decryptionKey;
+    const roots = passwordRoots(userDataDir, browser);
     const results = [];
     const term = search?.toLowerCase();
-    for (const p of profiles) {
-        for (const store of PASSWORD_STORES) {
-            const dbPath = join(p.path, store.file);
-            try {
-                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 = {
-                        profile: p.name,
-                        source: store.source,
-                        url: row.origin_url,
-                        username: row.username_value,
-                        password: row.password_value?.length > 0
-                            ? decryptValue(row.password_value, derivedKey ??= deriveEncryptionKey(userDataDir, 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;
+    // A named profile missing from one tree is not a failure while another is
+    // still to come — but a profile in none of them is still an error, so the
+    // first refusal is kept and raised if no tree resolved at all.
+    let refusal;
+    let resolved = false;
+    for (const root of roots) {
+        let profiles;
+        try {
+            profiles = resolveTargetProfiles({ chromeDir: root, profile, browser });
+        }
+        catch (error) {
+            refusal ??= error;
+            continue;
+        }
+        resolved = true;
+        // Per root: on Windows the key comes from that tree's own Local State.
+        let derivedKey = decryptionKey;
+        for (const p of profiles) {
+            for (const store of PASSWORD_STORES) {
+                const dbPath = join(p.path, store.file);
+                try {
+                    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 = {
+                            profile: p.name,
+                            source: store.source,
+                            url: row.origin_url,
+                            username: row.username_value,
+                            password: row.password_value?.length > 0
+                                ? 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);
                     }
-                    results.push(entry);
                 }
-            }
-            catch {
-                // Skip missing or unreadable stores and continue with the others.
+                catch {
+                    // Skip missing or unreadable stores and continue with the others.
+                }
             }
         }
     }
+    if (!resolved && refusal)
+        throw refusal;
     return results;
 }

package/package.json

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