chrome-tools 1.1.18 → 1.2.1

package/dist/modules/autofill.d.ts

@@ -0,0 +1,68 @@
+import { type ResolveProfilesOptions } from "../chromium/profiles.js";
+export interface AutofillOptions extends ResolveProfilesOptions {
+    search?: string;
+    limit?: number;
+}
+export interface AutofillEntry {
+    profile: string;
+    name: string;
+    value: string;
+    dateCreated: string;
+    dateLastUsed: string;
+    count: number;
+}
+export interface CreditCardOptions extends ResolveProfilesOptions {
+    decryptionKey?: Buffer;
+}
+export interface CreditCardEntry {
+    profile: string;
+    guid: string;
+    nameOnCard: string;
+    expirationMonth: number;
+    expirationYear: number;
+    cardNumber: string;
+    nickname: string;
+    origin: string;
+    useCount: number;
+    dateModified: string;
+}
+export interface AddressOptions extends ResolveProfilesOptions {
+}
+export interface AddressEntry {
+    profile: string;
+    guid: string;
+    fullName: string;
+    email: string;
+    phone: string;
+    companyName: string;
+    streetAddress: string;
+    city: string;
+    state: string;
+    zipcode: string;
+    countryCode: string;
+    origin: string;
+    useCount: number;
+    dateModified: string;
+}
+/**
+ * Retrieves autofill entries from Chrome's Web Data database.
+ *
+ * @param options - Filtering and targeting options.
+ * @returns Array of autofill entries.
+ */
+export declare function getAutofillEntries({ chromeDir, profilePath, profile, browser, onDiagnostic, search, limit, }?: AutofillOptions): AutofillEntry[];
+/**
+ * Retrieves saved credit cards from Chrome's Web Data database.
+ * Card numbers are encrypted and will be decrypted.
+ *
+ * @param options - Targeting options.
+ * @returns Array of credit card entries.
+ */
+export declare function getCreditCards({ chromeDir, profilePath, profile, browser, onDiagnostic, decryptionKey, }?: CreditCardOptions): CreditCardEntry[];
+/**
+ * Retrieves saved addresses from Chrome's Web Data database.
+ *
+ * @param options - Targeting options.
+ * @returns Array of address entries.
+ */
+export declare function getAddresses(options?: AddressOptions): AddressEntry[];

package/dist/modules/bookmarks.d.ts

@@ -0,0 +1,22 @@
+import { type ResolveProfilesOptions } from "../chromium/profiles.js";
+export interface BookmarkOptions extends ResolveProfilesOptions {
+    folder?: string;
+    search?: string;
+}
+export interface BookmarkEntry {
+    profile?: string;
+    title: string;
+    url: string;
+    folder: string;
+    dateAdded: string;
+    dateLastUsed: string;
+    id?: string;
+    guid?: string;
+}
+/**
+ * Reads and parses bookmarks from Chrome's Bookmarks JSON file.
+ *
+ * @param options - Options for filtering and targeting.
+ * @returns Filtered bookmark entries.
+ */
+export declare function getBookmarks({ chromeDir, profilePath, profile, folder, search, browser, onDiagnostic, }?: BookmarkOptions): BookmarkEntry[];

package/dist/modules/cookies.d.ts

@@ -0,0 +1,40 @@
+import { type ResolveProfilesOptions } from "../chromium/profiles.js";
+export interface CookieOptions extends ResolveProfilesOptions {
+    domain?: string;
+    url?: string;
+    decrypt?: boolean;
+    limit?: number;
+    decryptionKey?: Buffer;
+}
+export interface CookieEntry {
+    profile: string;
+    domain: string;
+    name: string;
+    value: string;
+    path: string;
+    expires: string;
+    secure: boolean;
+    httpOnly: boolean;
+    sameSite: string;
+    created: string;
+    lastAccessed: string;
+}
+declare function parseURL(urlStr?: string): URL | null;
+declare function getPossibleHostKeys(hostname: string): string[];
+declare function domainMatch(hostname: string, hostKey: string): boolean;
+declare function pathMatch(urlPath: string, cookiePath: string): boolean;
+/**
+ * Extracts cookies from Chrome's Cookies database.
+ * Encrypted values are decrypted using the same mechanism as passwords.
+ *
+ * @param options - Targeting and filtering options.
+ * @returns Array of cookie entries.
+ */
+export declare function getCookies({ chromeDir, profilePath, profile, browser, onDiagnostic, domain, url, decrypt, limit, decryptionKey, }?: CookieOptions): CookieEntry[];
+export declare const _test: {
+    parseURL: typeof parseURL;
+    getPossibleHostKeys: typeof getPossibleHostKeys;
+    domainMatch: typeof domainMatch;
+    pathMatch: typeof pathMatch;
+};
+export {};

package/dist/modules/downloads.d.ts

@@ -0,0 +1,27 @@
+import { type ResolveProfilesOptions } from "../chromium/profiles.js";
+export interface DownloadOptions extends ResolveProfilesOptions {
+    search?: string;
+    limit?: number;
+}
+export interface DownloadEntry {
+    profile: string;
+    targetPath: string;
+    url: string;
+    siteUrl: string;
+    referrer: string;
+    totalBytes: number;
+    receivedBytes: number;
+    mimeType: string;
+    state: string;
+    dangerType: string;
+    opened: boolean;
+    startTime: string;
+    endTime: string;
+}
+/**
+ * Retrieves download history from Chrome's History database.
+ *
+ * @param options - Targeting, filtering, and limit options.
+ * @returns Array of download entries.
+ */
+export declare function getDownloads({ chromeDir, profilePath, profile, browser, onDiagnostic, search, limit, }?: DownloadOptions): DownloadEntry[];

package/dist/modules/extensions.d.ts

@@ -0,0 +1,24 @@
+import { type ResolveProfilesOptions } from "../chromium/profiles.js";
+export interface ExtensionOptions extends ResolveProfilesOptions {
+    search?: string;
+}
+export interface ExtensionEntry {
+    profile: string;
+    id: string;
+    name: string;
+    version: string;
+    description: string;
+    enabled: boolean;
+    homepageUrl: string;
+    updateUrl: string;
+    installTime: string;
+    fromWebstore: boolean;
+    location: number;
+}
+/**
+ * Retrieves installed Chrome extensions from the Preferences JSON file.
+ *
+ * @param options - Targeting and filtering options.
+ * @returns Array of extension entries.
+ */
+export declare function getExtensions({ chromeDir, profilePath, profile, search, browser, onDiagnostic, }?: ExtensionOptions): ExtensionEntry[];

package/dist/modules/history.d.ts

@@ -0,0 +1,34 @@
+import { type ResolveProfilesOptions } from "../chromium/profiles.js";
+export interface HistoryOptions extends ResolveProfilesOptions {
+    search?: string;
+    limit?: number;
+}
+export interface HistoryEntry {
+    profile: string;
+    url: string;
+    title: string;
+    visitCount: number;
+    lastVisit: string;
+}
+export interface SearchTermOptions extends ResolveProfilesOptions {
+    limit?: number;
+}
+export interface SearchTermEntry {
+    profile: string;
+    term: string;
+    url: string;
+}
+/**
+ * Retrieves browsing history from Chrome's History database.
+ *
+ * @param options - Filtering and targeting options.
+ * @returns Array of history entries.
+ */
+export declare function getHistory({ chromeDir, profilePath, profile, search, limit, browser, onDiagnostic, }?: HistoryOptions): HistoryEntry[];
+/**
+ * Retrieves search terms from Chrome's History database.
+ *
+ * @param options - Targeting and limit options.
+ * @returns Array of search term entries.
+ */
+export declare function getSearchTerms({ chromeDir, profilePath, profile, limit, browser, onDiagnostic, }?: SearchTermOptions): SearchTermEntry[];

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

@@ -0,0 +1,21 @@
+import { type ResolveProfilesOptions } from "../chromium/profiles.js";
+export interface LocalStorageOptions extends ResolveProfilesOptions {
+    origin?: string;
+    url?: string;
+    key?: string;
+    search?: string;
+    limit?: number;
+}
+export interface LocalStorageEntry {
+    profile: string;
+    origin: string;
+    key: string;
+    value: string;
+}
+/**
+ * Reads localStorage key/value pairs from Chromium's Local Storage store.
+ *
+ * @param options - Targeting and filtering options.
+ * @returns Array of localStorage entries.
+ */
+export declare function getLocalStorage({ chromeDir, profilePath, profile, browser, onDiagnostic, origin, url, key, search, limit, }?: LocalStorageOptions): LocalStorageEntry[];

package/dist/modules/passwords.d.ts

@@ -0,0 +1,50 @@
+import { type ResolveProfilesOptions } from "../chromium/profiles.js";
+export interface PasswordOptions extends ResolveProfilesOptions {
+    search?: string;
+    decryptionKey?: Buffer;
+}
+/** Which on-disk store a password came from. */
+export type PasswordSource = "device" | "account";
+export interface PasswordEntry {
+    profile: string;
+    /** "device" = local "Login Data"; "account" = synced "Login Data For Account". */
+    source?: PasswordSource;
+    url?: string;
+    username?: string;
+    password?: string;
+    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
+ * with its `source` (no de-duplication across the two).
+ *
+ * @param options - Options for profile selection and filtering.
+ * @returns Array of decrypted password entries.
+ */
+export declare function getPasswords({ chromeDir, profilePath, profile, search, browser, decryptionKey, onDiagnostic, }?: PasswordOptions): PasswordEntry[];

package/dist/modules/search-engines.d.ts

@@ -0,0 +1,21 @@
+import { type ResolveProfilesOptions } from "../chromium/profiles.js";
+export interface SearchEngineOptions extends ResolveProfilesOptions {
+}
+export interface SearchEngineEntry {
+    profile: string;
+    id: number;
+    name: string;
+    keyword: string;
+    url: string;
+    suggestionsUrl: string;
+    faviconUrl: string;
+    isDefault: boolean;
+    isActive: boolean;
+}
+/**
+ * Retrieves search engines configured in Chrome from the Web Data database.
+ *
+ * @param options - Targeting options.
+ * @returns Array of search engine entries.
+ */
+export declare function getSearchEngines({ chromeDir, profilePath, profile, browser, onDiagnostic, }?: SearchEngineOptions): SearchEngineEntry[];

package/dist/modules/top-sites.d.ts

@@ -0,0 +1,17 @@
+import { type ResolveProfilesOptions } from "../chromium/profiles.js";
+export interface TopSiteOptions extends ResolveProfilesOptions {
+}
+export interface TopSiteEntry {
+    profile: string;
+    url: string;
+    title: string;
+    rank: number;
+    redirects: string;
+}
+/**
+ * Retrieves top sites from Chrome's Top Sites database.
+ *
+ * @param options - Targeting options.
+ * @returns Array of top site entries.
+ */
+export declare function getTopSites({ chromeDir, profilePath, profile, browser, onDiagnostic }?: TopSiteOptions): TopSiteEntry[];

package/dist/platform/darwin.d.ts

@@ -0,0 +1,12 @@
+import type { ChromePlatform } from "./types.js";
+/**
+ * macOS backend.
+ *
+ * Key source: the active browser's "<Browser> Safe Storage" password from the
+ * login Keychain (e.g. "Chrome Safe Storage", "Microsoft Edge Safe Storage"),
+ * stretched with PBKDF2 (1003 iterations) — implemented in `core/keychain.ts`.
+ * Cipher: AES-128-CBC with a fixed 16-space IV — implemented in `core/crypto.ts`.
+ * The browser only changes *which* Keychain item and data dir are used; the
+ * crypto is identical across all Chromium forks.
+ */
+export declare const darwin: ChromePlatform;

package/dist/platform/index.d.ts

@@ -0,0 +1,33 @@
+import { type ProfileReadReporter } from "../storage/errors.js";
+/**
+ * Platform selection + facades.
+ *
+ * This is the ONLY place that reads `process.platform`. Everything else in the
+ * codebase imports the facades below (`getPlatformChromeDir`, `deriveEncryptionKey`,
+ * `decryptValue`, `decryptValueBuffer`, `clearKeyCache`) and stays OS-agnostic.
+ */
+import type { ChromePlatform } from "./types.js";
+import { type BrowserDescriptor } from "../chromium/browsers.js";
+export type { ChromePlatform } from "./types.js";
+export { BROWSERS, listBrowsers, resolveBrowser, requireBrowser, getActiveBrowser, setActiveBrowser, type BrowserId, type BrowserDescriptor, } from "../chromium/browsers.js";
+export { KeychainAccessError, isKeychainAccessDenied, type KeychainErrorKind, } from "../core/keychain.js";
+/**
+ * Returns the backend for the current OS, cached after first call.
+ * @throws On an unsupported platform.
+ */
+export declare function selectPlatform(): ChromePlatform;
+/** Default Chrome User Data directory for the current OS. */
+export declare function getPlatformChromeDir(browser?: string | BrowserDescriptor): string;
+/**
+ * Returns the symmetric key for decrypting this profile's secrets.
+ * @param chromeDir - Needed on Windows, where the key lives in `Local State`.
+ */
+export declare function deriveEncryptionKey(chromeDir?: string, browser?: string | BrowserDescriptor): Buffer;
+/** Decrypts a Chrome blob and returns the plaintext bytes (or a placeholder string). */
+export declare function decryptValueBuffer(blob: Buffer | Uint8Array | null | undefined, key: Buffer): Buffer | string;
+/** Decrypts a Chrome blob and returns the plaintext as a UTF-8 string. */
+export declare function decryptValue(blob: Buffer | Uint8Array | null | undefined, key: Buffer): string;
+/** Clears the active backend's cached key material. */
+export declare function clearKeyCache(): void;
+/** Resolve keys lazily for a single store and its explicit browser profile. */
+export declare function createProfileDecryptor(chromeDir: string, browser: string | undefined, overrideKey: Buffer | undefined, report: ProfileReadReporter | undefined, profile: string, store: string): (blob: Buffer) => Buffer | string;

package/dist/platform/linux.d.ts

@@ -0,0 +1,10 @@
+import type { ChromePlatform } from "./types.js";
+/**
+ * Linux backend.
+ *
+ * Key source: the active browser's "Safe Storage" password from the Secret
+ * Service (gnome-keyring / KWallet) via `secret-tool`, or the hardcoded
+ * "peanuts" fallback, stretched with PBKDF2 (1 iteration).
+ * Cipher: AES-128-CBC with a fixed 16-space IV (same primitive as macOS).
+ */
+export declare const linux: ChromePlatform;

package/dist/platform/types.d.ts

@@ -0,0 +1,49 @@
+import type { BrowserDescriptor } from "../chromium/browsers.js";
+export interface DecryptionContext {
+    chromeDir: string;
+    browser: BrowserDescriptor;
+}
+/**
+ * The platform-specific backend contract.
+ *
+ * Everything that differs between operating systems is bundled here because the
+ * three concerns are coupled — a Windows key only works with the Windows cipher,
+ * etc. Each backend (darwin/win32/linux) implements this once; the rest of the
+ * codebase stays platform-agnostic and talks to the selected backend through the
+ * facades in `./index.ts`.
+ */
+export interface ChromePlatform {
+    /** Node platform identifier this backend handles (e.g. "darwin", "win32", "linux"). */
+    readonly name: string;
+    /** Absolute path to Chrome's User Data directory for this OS. */
+    getDefaultChromeDir(browser?: BrowserDescriptor): string;
+    /**
+     * Returns the symmetric key used to decrypt this profile's secrets, ready to
+     * hand to {@link decrypt}. May read the OS key store and is cached internally.
+     *
+     * @param chromeDir - User Data dir, needed on platforms (Windows) where the
+     *   key lives inside `Local State`. Defaults to {@link getDefaultChromeDir}.
+     * @throws An actionable Error if the key cannot be obtained.
+     */
+    getDecryptionKey(chromeDir?: string, browser?: BrowserDescriptor): Buffer;
+    /**
+     * Returns the App-Bound Encryption key for Chrome 127+ on Windows.
+     * Only the win32 backend implements this; others return `undefined`.
+     *
+     * @param chromeDir - User Data dir containing the `Local State` file.
+     * @param browser - Browser to target (needed to select the COM CLSID).
+     * @returns The decrypted 32-byte AES key, or `undefined` if ABE is
+     *   unavailable or unsupported on this platform.
+     */
+    getAppBoundKey?(chromeDir?: string, browser?: BrowserDescriptor): Buffer | undefined;
+    /**
+     * Decrypts a single Chrome `v10`/`v11`/`v20` blob using this platform's
+     * scheme (AES-128-CBC on macOS/Linux, AES-256-GCM on Windows).
+     *
+     * @returns The plaintext bytes, or a `<...>` placeholder string on a
+     *   recognized but undecryptable blob (never throws).
+     */
+    decrypt(blob: Buffer, key: Buffer): Buffer | string;
+    /** Clears any cached key material. Useful for tests / re-authentication. */
+    clearCache(): void;
+}

package/dist/platform/win32.d.ts

@@ -0,0 +1,13 @@
+import type { ChromePlatform } from "./types.js";
+/**
+ * Windows backend.
+ *
+ * Key source: `os_crypt.encrypted_key` in Local State — base64, "DPAPI"-prefixed,
+ * unprotected via DPAPI into a raw 32-byte AES-256 key (no PBKDF2 on Windows).
+ * Cipher: AES-256-GCM (nonce + tag carried in each blob).
+ *
+ * Chrome 127+ adds `os_crypt.app_bound_encrypted_key` — base64, "APPB"-prefixed.
+ * It is passed directly to Chrome's IElevator COM service via the native helper
+ * to obtain the 32-byte AES-256 key for "v20" blobs.
+ */
+export declare const win32: ChromePlatform;

package/dist/storage/binary.d.ts

@@ -0,0 +1,6 @@
+export declare function readVarint32(data: Buffer, offset: number): {
+    value: number;
+    nextOffset: number;
+} | null;
+export declare const MAX_DECOMPRESSED_BYTES: number;
+export declare function snappyUncompress(input: Buffer): Buffer;

package/dist/storage/errors.d.ts

@@ -0,0 +1,13 @@
+export type StoreReadIssue = "missing_store" | "unsupported_schema" | "snapshot_unavailable" | "decryption_unavailable" | "unreadable";
+export interface ProfileReadDiagnostic {
+    profile: string;
+    store: string;
+    code: StoreReadIssue;
+    message: string;
+}
+export type ProfileReadReporter = (diagnostic: ProfileReadDiagnostic) => void;
+export declare class StoreReadError extends Error {
+    readonly code: StoreReadIssue;
+    constructor(code: StoreReadIssue, message: string, options?: ErrorOptions);
+}
+export declare function reportStoreIssue(report: ProfileReadReporter | undefined, profile: string, store: string, error: unknown): void;

package/dist/storage/files.d.ts

@@ -0,0 +1,5 @@
+import { type BigIntStats } from "node:fs";
+export declare function getFileStamp(path: string): BigIntStats | undefined;
+export declare function sameFile(before?: BigIntStats, after?: BigIntStats): boolean;
+/** Guard against a temporary directory configured inside the source profile. */
+export declare function createSnapshotDirectory(profilePath: string, prefix: string): string;

package/dist/storage/leveldb.d.ts

@@ -0,0 +1,8 @@
+export declare function readLevelDBSnapshot(path: string, profilePath: string): Iterable<RawLevelDBRecord>;
+interface RawLevelDBRecord {
+    key: Buffer;
+    value?: Buffer;
+    sequence: bigint;
+    deleted: boolean;
+}
+export {};

package/dist/storage/sqlite.d.ts

@@ -0,0 +1,5 @@
+export type SnapshotQuery = (sql: string, params?: unknown[]) => any[];
+/** SQLite opens only the private copy, including for journal recovery. */
+export declare function withDatabaseSnapshot<T>(path: string, read: (query: SnapshotQuery) => T): T;
+export declare function queryDatabase(dbFilePath: string, sql: string, params?: unknown[]): any[];
+export declare function tableExists(dbFilePath: string, tableName: string): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-tools",
-  "version": "1.1.18",
+  "version": "1.2.1",
   "description": "CLI & Node.js library for chrome",
   "type": "module",
   "main": "./dist/index.js",
@@ -58,11 +58,13 @@
     "dist"
   ],
   "scripts": {
-    "build": "node scripts/clean.mjs && tsup && tsc -p tsconfig.types.json && rollup -c rollup.types.config.mjs && node scripts/finalize.mjs && node scripts/verify-dist.mjs",
+    "build": "node scripts/clean.mjs && tsup && tsc -p tsconfig.types.json && node scripts/finalize.mjs && node scripts/verify-dist.mjs",
     "typecheck": "tsc --noEmit",
     "lint": "oxlint --deny-warnings .",
     "start": "node dist/cli.js",
-    "test": "npm run build && npm run typecheck && node --import tsx --test test/*.test.ts && node dist/cli.js --help",
+    "test": "npm run build && npm run typecheck && node scripts/test-unit.mjs && node dist/cli.js --help",
+    "test:chrome": "node test/compatibility/chrome.mjs",
+    "test:package": "node test/compatibility/package.mjs",
     "release": "node scripts/release.mjs"
   },
   "keywords": [
@@ -87,16 +89,13 @@
     "node": ">=22.16.0"
   },
   "devDependencies": {
-    "@types/node": "^26.1.2",
-    "@typescript/typescript6": "^6.0.2",
-    "chalk": "^6.0.0",
+    "@types/node": "^26.6.6",
+    "chalk": "^6.0.1",
     "cli-table3": "^0.6.5",
-    "commander": "^15.0.0",
+    "commander": "^15.1.0",
     "oxlint": "1.77.0",
-    "rollup": "^4.63.0",
-    "rollup-plugin-dts": "^6.5.1",
     "tsup": "^8.5.1",
-    "tsx": "^4.23.12",
+    "tsx": "^4.23.15",
     "typescript": "^7.0.2"
   }
 }