chrome-tools 1.1.18 → 1.2.1

package/README.md

@@ -6,10 +6,7 @@ CLI & Node.js library for Chrome browser data, including passwords, bookmarks, h
 
 **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.
+dependency, so consumers can install the package without a compiler.
 
 ### The experimental warning
 
@@ -29,6 +26,35 @@ 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.
+## Reading profiles
+
+Profile files are read as source data. SQLite opens and recovers journals only
+inside a private temporary directory. The LevelDB reader also works from a
+private copy. If a required file is locked or changes during copying, close the
+browser and retry, or point the tool at a quiescent profile backup.
+
+Use `--diagnostics` to print store failures to stderr alongside normal CLI
+output. For example, `chrome-tools addresses --json --diagnostics` returns an
+address array on stdout and reports unsupported schemas or missing stores on
+stderr. Library readers accept an `onDiagnostic` callback with the profile,
+store, issue code, and message.
+
+Windows App-Bound Encryption can make protected values unavailable to the
+bundled helper. The tool reports this with a placeholder and a diagnostic when
+requested. The helper runs from the package directory.
+
+## Development
+
+- `npm test` builds and tests with synthetic profiles and isolated home directories.
+- `npm run test:package` installs the built tarball into a temporary directory and checks its entry points.
+- `npm run test:chrome` uses the executable specified by `CHROME_FOR_TESTING_BINARY` to generate and read a disposable profile. The test compares the profile's file hashes before and after reading it.
+
+The compatibility workflow checks Chrome for Testing Stable on pushes and pull
+requests and checks Beta on scheduled and manual runs. Package tests run across
+macOS, Linux, and Windows on the minimum supported Node version and current LTS.
+
+The Windows CI job builds and tests the native helper and publishes it as a
+workflow artifact for that commit. For a release, place the matching artifact at
+`native/windows/chrome_abe_decrypt.exe` or build it from the same source revision
+with `native/windows/build.bat`. Release packaging includes the helper alongside
+the bundled CLI and library.

package/dist/chromium/addresses.d.ts

@@ -0,0 +1,2 @@
+import type { AddressEntry } from "../modules/autofill.js";
+export declare function readAddresses(path: string, profile: string): AddressEntry[];

package/dist/chromium/browsers.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Chromium-browser registry — the single source of truth for what differs
+ * between Chromium-based browsers (Chrome, Edge, Brave, Comet, …).
+ *
+ * Every supported browser is a Chromium fork, so the *decryption* is identical
+ * per OS (AES-128-CBC + PBKDF2 on macOS/Linux, AES-256-GCM + DPAPI on Windows).
+ * Only two things vary by browser:
+ *   1. the default profile data directory, and
+ *   2. the OS-keystore "Safe Storage" label (macOS Keychain service name /
+ *      Linux Secret Service application).
+ *
+ * "Browser" is therefore a small dimension orthogonal to "platform": the
+ * platform backends (darwin/win32/linux) receive a browser descriptor and stay
+ * otherwise unchanged.
+ */
+export type BrowserId = "chrome" | "chrome-beta" | "chrome-canary" | "chromium" | "edge" | "brave" | "comet" | "vivaldi" | "opera";
+/** Subpaths to a browser's User Data dir, relative to each OS's app-data base. */
+export interface BrowserDirs {
+    /** Under `~/Library/Application Support`. */
+    darwin: string;
+    /** Under the selected Windows app-data root. Includes any `User Data` segment. */
+    win32: string;
+    /** Windows application-data root. Chromium browsers normally use Local. */
+    win32Base?: "local" | "roaming";
+    /** Under `$XDG_CONFIG_HOME` (or `~/.config`). */
+    linux: string;
+}
+export interface BrowserDescriptor {
+    /** Stable identifier used on the CLI (`--browser <id>`) and in the API. */
+    readonly id: BrowserId;
+    /** Human-readable display name, e.g. "Microsoft Edge". */
+    readonly name: string;
+    /** Extra names accepted on the CLI (case-insensitive), e.g. "msedge". */
+    readonly aliases?: readonly string[];
+    /**
+     * macOS Keychain service name (a.k.a. the "<Browser> Safe Storage" item) used
+     * as the basis for the AES key. Also reused as a human label in messages.
+     */
+    readonly safeStorageLabel: string;
+    /** Linux Secret Service `application` attribute used by `secret-tool lookup`. */
+    readonly linuxSecretApp?: string;
+    /** Per-OS User Data subpaths. */
+    readonly dirs: BrowserDirs;
+}
+/**
+ * Supported browsers. macOS paths/labels are verified; a few Windows/Linux
+ * paths for niche browsers (Comet, Opera) are best-effort and easy to correct —
+ * each is a single edit here, with no other code change required.
+ */
+export declare const BROWSERS: Record<BrowserId, BrowserDescriptor>;
+/** All supported browsers, in a stable display order. */
+export declare function listBrowsers(): BrowserDescriptor[];
+/**
+ * Resolves a browser by id, display name, or alias (case-insensitive).
+ * @returns The descriptor, or `null` if unrecognized.
+ */
+export declare function resolveBrowser(idOrName: string): BrowserDescriptor | null;
+/** Resolves a browser or throws an actionable error without changing global state. */
+export declare function requireBrowser(idOrName: string): BrowserDescriptor;
+/** The browser currently targeted by dir/key lookups. Defaults to Chrome. */
+export declare function getActiveBrowser(): BrowserDescriptor;
+/**
+ * Sets the active browser for subsequent dir/key lookups.
+ *
+ * Caches in the platform backends are keyed by their real inputs (Keychain
+ * service label, chromeDir, Linux secret app), so switching browsers never
+ * returns a stale key — no cache flush is needed here.
+ *
+ * @param idOrName - Browser id/name/alias. Empty/undefined resets to Chrome.
+ * @returns The now-active descriptor.
+ * @throws If `idOrName` is non-empty but unrecognized.
+ */
+export declare function setActiveBrowser(idOrName?: string): BrowserDescriptor;

package/dist/chromium/local-storage.d.ts

@@ -0,0 +1,7 @@
+interface LocalStorageRecord {
+    origin: string;
+    key: string;
+    value: string;
+}
+export declare function readLocalStorage(profilePath: string): Iterable<LocalStorageRecord>;
+export {};

package/dist/chromium/profiles.d.ts

@@ -0,0 +1,130 @@
+import type { ProfileReadReporter } from "../storage/errors.js";
+import { type BrowserDescriptor } from "./browsers.js";
+/**
+ * Resolves the Cookies database for a Chromium profile.
+ *
+ * Current Chromium releases keep it under `Network/Cookies`; older releases
+ * and a few Chromium-based browsers used `<profile>/Cookies`. Prefer the
+ * current location when both exist, while retaining compatibility with the
+ * legacy layout.
+ */
+export declare function resolveCookiesDatabasePath(profilePath: string): string;
+export interface DiscoveredProfile {
+    name: string;
+    path: string;
+}
+export interface ProfileMetadata {
+    directory: string;
+    name: string;
+    gaiaName: string;
+    userName: string;
+    email: string;
+    avatarIcon: string;
+    isUsingDefaultName: boolean;
+    isEphemeral: boolean;
+    activeTime: number;
+}
+export interface ProfileState {
+    directory: string;
+    path: string;
+    displayName: string;
+    gaiaName: string;
+    email: string;
+    avatarIcon: string;
+    isEphemeral: boolean;
+    activeTime: number;
+    dataFiles: Record<string, boolean>;
+}
+export interface ResolveProfilesOptions {
+    profilePath?: string;
+    chromeDir?: string;
+    profile?: string;
+    /** Target a specific browser (id/name/alias). Applied only when provided. */
+    browser?: string;
+    /** Reports profile and store failures while preserving the usual array result. */
+    onDiagnostic?: ProfileReadReporter;
+}
+/**
+ * Returns the default Chrome User Data directory for the current OS.
+ * Delegates to the active platform backend (macOS/Windows/Linux).
+ * @returns The absolute path to Chrome's User Data.
+ */
+export declare function getDefaultChromeDir(browser?: string | BrowserDescriptor): string;
+export interface InstalledBrowser {
+    /** Registry descriptor for the detected browser. */
+    browser: BrowserDescriptor;
+    /** Absolute path to this browser's default User Data directory. */
+    chromeDir: string;
+    /** Whether the data directory exists on disk. */
+    installed: boolean;
+    /** Number of discovered profiles (0 when not installed). */
+    profileCount: number;
+}
+/**
+ * Probes every supported browser for an on-disk profile directory.
+ *
+ * @param options.includeMissing - When true, also returns browsers with no data
+ *   directory (installed: false). Defaults to false (installed browsers only).
+ * @returns One entry per matching browser.
+ */
+export declare function detectInstalledBrowsers({ includeMissing }?: {
+    includeMissing?: boolean;
+}): InstalledBrowser[];
+/**
+ * Scans the Chrome User Data directory for profile subdirectories.
+ * A directory is considered a profile if it contains at least one known data file.
+ *
+ * Also handles "flat" layouts (e.g. some Opera installs, or when `chromeDir`
+ * already points at a single profile folder): if no child profiles are found
+ * but the user-data directory itself has profile indicators, it is returned
+ * as a single profile.
+ *
+ * @param chromeDir - Chrome User Data path. Defaults to standard macOS location.
+ * @param options.reportAccessDenied - Throw when the directory cannot be read due to permissions.
+ * @returns Discovered profiles with name and absolute path.
+ */
+export declare function discoverProfiles(chromeDir?: string, { reportAccessDenied }?: {
+    reportAccessDenied?: boolean;
+}): DiscoveredProfile[];
+/**
+ * Parses the Chrome "Local State" JSON file to extract profile metadata.
+ * Returns enriched profile info including display name, email, avatar, etc.
+ *
+ * @param chromeDir - Chrome User Data path.
+ * @returns Profile metadata objects.
+ */
+export declare function getProfileMetadata(chromeDir?: string): ProfileMetadata[];
+/**
+ * Combines filesystem profile discovery with Local State metadata
+ * to provide a comprehensive view of each profile's state.
+ *
+ * @param chromeDir - Chrome User Data path.
+ * @returns Enriched profile state objects.
+ */
+export declare function getProfileStates(chromeDir?: string): ProfileState[];
+/**
+ * Recursively computes the total size, in bytes, of a directory's contents.
+ * Symbolic links are not followed and unreadable entries are skipped so the
+ * walk never throws on a single permission error.
+ *
+ * @param dirPath - Absolute path to the directory to measure.
+ * @returns Total size of all contained files in bytes (0 if missing/unreadable).
+ */
+export declare function getDirectorySize(dirPath: string): number;
+/**
+ * Resolves a profile name to its directory path.
+ *
+ * @param chromeDir - Chrome User Data path.
+ * @param profileName - Profile directory name (e.g., "Default", "Profile 1").
+ * @returns Absolute path to profile directory, or null if not found.
+ */
+export declare function resolveProfilePath(chromeDir: string, profileName: string): string | null;
+/**
+ * Helper to get the profiles to operate on based on options.
+ * If a specific profile is specified, returns only that one.
+ * Otherwise returns all discovered profiles.
+ *
+ * @param options - Resolution options.
+ * @returns Array of targeted profiles.
+ */
+export declare function resolveTargetProfiles({ profilePath, chromeDir, profile, browser, onDiagnostic, }?: ResolveProfilesOptions): DiscoveredProfile[];