chrome-tools 1.0.5 → 1.0.6

package/dist/src/core/chrome.js

@@ -0,0 +1,159 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Known database/data files that indicate a valid Chrome profile directory. */
+const PROFILE_INDICATORS = [
+    "Login Data",
+    "History",
+    "Bookmarks",
+    "Cookies",
+    "Web Data",
+    "Preferences",
+];
+/**
+ * Returns the default Chrome User Data directory for macOS.
+ * @returns The absolute path to Chrome's User Data.
+ */
+export function getDefaultChromeDir() {
+    return join(homedir(), "Library", "Application Support", "Google", "Chrome");
+}
+/**
+ * Scans the Chrome User Data directory for profile subdirectories.
+ * A directory is considered a profile if it contains at least one known data file.
+ *
+ * @param chromeDir - Chrome User Data path. Defaults to standard macOS location.
+ * @returns Discovered profiles with name and absolute path.
+ */
+export function discoverProfiles(chromeDir) {
+    const dir = chromeDir || getDefaultChromeDir();
+    if (!dir || !existsSync(dir)) {
+        return [];
+    }
+    try {
+        const entries = readdirSync(dir, { withFileTypes: true });
+        const profiles = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const profilePath = join(dir, entry.name);
+            const hasIndicator = PROFILE_INDICATORS.some((file) => existsSync(join(profilePath, file)));
+            if (hasIndicator) {
+                profiles.push({ name: entry.name, path: profilePath });
+            }
+        }
+        return profiles;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * 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 function getProfileMetadata(chromeDir) {
+    const dir = chromeDir || getDefaultChromeDir();
+    const localStatePath = join(dir, "Local State");
+    if (!existsSync(localStatePath)) {
+        return [];
+    }
+    try {
+        const raw = readFileSync(localStatePath, "utf-8");
+        const localState = JSON.parse(raw);
+        const infoCache = localState?.profile?.info_cache;
+        if (!infoCache || typeof infoCache !== "object") {
+            return [];
+        }
+        return Object.entries(infoCache).map(([dirName, infoAny]) => {
+            const info = infoAny;
+            return {
+                directory: dirName,
+                name: info.name || dirName,
+                gaiaName: info.gaia_name || "",
+                userName: info.user_name || "",
+                email: info.user_name || "",
+                avatarIcon: info.avatar_icon || "",
+                isUsingDefaultName: info.is_using_default_name ?? true,
+                isEphemeral: info.is_ephemeral ?? false,
+                activeTime: info.active_time || 0,
+            };
+        });
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * 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 function getProfileStates(chromeDir) {
+    const dir = chromeDir || getDefaultChromeDir();
+    const discovered = discoverProfiles(dir);
+    const metadata = getProfileMetadata(dir);
+    const metaMap = new Map();
+    for (const m of metadata) {
+        metaMap.set(m.directory, m);
+    }
+    return discovered.map((profile) => {
+        const meta = metaMap.get(profile.name);
+        const profilePath = profile.path;
+        // Check which data files exist
+        const dataFiles = {};
+        for (const file of PROFILE_INDICATORS) {
+            dataFiles[file.replace(/\s+/g, "_").toLowerCase()] = existsSync(join(profilePath, file));
+        }
+        // Additional files
+        dataFiles.top_sites = existsSync(join(profilePath, "Top Sites"));
+        dataFiles.extensions = existsSync(join(profilePath, "Extensions"));
+        return {
+            directory: profile.name,
+            path: profilePath,
+            displayName: meta?.name || profile.name,
+            gaiaName: meta?.gaiaName || "",
+            email: meta?.email || "",
+            avatarIcon: meta?.avatarIcon || "",
+            isEphemeral: meta?.isEphemeral ?? false,
+            activeTime: meta?.activeTime || 0,
+            dataFiles,
+        };
+    });
+}
+/**
+ * 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 function resolveProfilePath(chromeDir, profileName) {
+    const dir = chromeDir || getDefaultChromeDir();
+    const profilePath = join(dir, profileName);
+    return existsSync(profilePath) ? profilePath : 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 function resolveTargetProfiles({ profilePath, chromeDir, profile, } = {}) {
+    const dir = profilePath || chromeDir || getDefaultChromeDir();
+    const allProfiles = discoverProfiles(dir);
+    if (profile) {
+        const match = allProfiles.filter((p) => p.name === profile);
+        if (match.length === 0) {
+            throw new Error(`Profile "${profile}" not found in ${dir}`);
+        }
+        return match;
+    }
+    return allProfiles;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Decrypts a password/value buffer encrypted by Chrome on macOS.
+ * Chrome v10+ on macOS prefixes the encrypted blob with "v10" or "v11",
+ * followed by AES-128-CBC ciphertext.
+ *
+ * @param encryptedBlob - The encrypted blob from the database.
+ * @param derivedKey - The derived 16-byte key.
+ * @returns The decrypted plaintext, or an error placeholder.
+ */
+export declare function decryptValue(encryptedBlob: Buffer | Uint8Array | null | undefined, derivedKey: Buffer): string;
+/**
+ * Decrypts a Chrome encrypted blob and returns the raw plaintext bytes.
+ *
+ * @param encryptedBlob - The encrypted blob from the database.
+ * @param derivedKey - The derived 16-byte key.
+ * @returns The decrypted plaintext bytes, or an error placeholder.
+ */
+export declare function decryptValueBuffer(encryptedBlob: Buffer | Uint8Array | null | undefined, derivedKey: Buffer): Buffer | string;
+/**
+ * Converts a Chrome/Webkit timestamp (microseconds since 1601-01-01)
+ * to a readable local Date string.
+ *
+ * @param chromeTimestamp - Timestamp in microseconds.
+ * @returns Human-readable date-time string, or "N/A".
+ */
+export declare function chromeTimeToDate(chromeTimestamp: bigint | number | null | undefined): string;

package/dist/src/core/crypto.js

@@ -0,0 +1,69 @@
+import { createDecipheriv } from "node:crypto";
+const AES_IV = Buffer.alloc(16, " "); // 16 spaces (0x20)
+/**
+ * Decrypts a password/value buffer encrypted by Chrome on macOS.
+ * Chrome v10+ on macOS prefixes the encrypted blob with "v10" or "v11",
+ * followed by AES-128-CBC ciphertext.
+ *
+ * @param encryptedBlob - The encrypted blob from the database.
+ * @param derivedKey - The derived 16-byte key.
+ * @returns The decrypted plaintext, or an error placeholder.
+ */
+export function decryptValue(encryptedBlob, derivedKey) {
+    const decrypted = decryptValueBuffer(encryptedBlob, derivedKey);
+    return Buffer.isBuffer(decrypted) ? decrypted.toString("utf-8") : decrypted;
+}
+/**
+ * Decrypts a Chrome encrypted blob and returns the raw plaintext bytes.
+ *
+ * @param encryptedBlob - The encrypted blob from the database.
+ * @param derivedKey - The derived 16-byte key.
+ * @returns The decrypted plaintext bytes, or an error placeholder.
+ */
+export function decryptValueBuffer(encryptedBlob, derivedKey) {
+    if (!encryptedBlob || encryptedBlob.length === 0) {
+        return Buffer.alloc(0);
+    }
+    const blob = Buffer.isBuffer(encryptedBlob)
+        ? encryptedBlob
+        : Buffer.from(encryptedBlob);
+    const prefix = blob.subarray(0, 3).toString("utf-8");
+    if (prefix !== "v10" && prefix !== "v11") {
+        return "<unsupported encryption format>";
+    }
+    const ciphertext = blob.subarray(3);
+    try {
+        const decipher = createDecipheriv("aes-128-cbc", derivedKey, AES_IV);
+        let decrypted = decipher.update(ciphertext);
+        decrypted = Buffer.concat([decrypted, decipher.final()]);
+        return decrypted;
+    }
+    catch {
+        return "<decryption failed>";
+    }
+}
+/**
+ * Converts a Chrome/Webkit timestamp (microseconds since 1601-01-01)
+ * to a readable local Date string.
+ *
+ * @param chromeTimestamp - Timestamp in microseconds.
+ * @returns Human-readable date-time string, or "N/A".
+ */
+export function chromeTimeToDate(chromeTimestamp) {
+    if (!chromeTimestamp || chromeTimestamp === 0 || chromeTimestamp === 0n) {
+        return "N/A";
+    }
+    try {
+        const timestampBigInt = BigInt(chromeTimestamp);
+        const unixMicroseconds = timestampBigInt - 11644473600000000n;
+        const ms = Number(unixMicroseconds / 1000n);
+        const date = new Date(ms);
+        if (isNaN(date.getTime())) {
+            return "N/A";
+        }
+        return date.toLocaleString();
+    }
+    catch {
+        return "N/A";
+    }
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Copies a Chrome SQLite database to a temporary location, executes a query,
+ * and cleans up. This avoids SQLite locking issues when Chrome is running.
+ *
+ * @param dbFilePath - Absolute path to the Chrome database file.
+ * @param sql - SQL query to execute.
+ * @param params - Bound parameters for the query.
+ * @returns Query result rows.
+ * @throws If the file doesn't exist or query fails.
+ */
+export declare function queryDatabase(dbFilePath: string, sql: string, params?: unknown[]): any[];
+/**
+ * Checks whether a specific table exists in the given database file.
+ *
+ * @param dbFilePath - Absolute path to the database file.
+ * @param tableName - Name of the table to check.
+ * @returns True if the table exists.
+ */
+export declare function tableExists(dbFilePath: string, tableName: string): boolean;

package/dist/src/core/db.js

@@ -0,0 +1,78 @@
+import { existsSync, copyFileSync, mkdtempSync, unlinkSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, basename } from "node:path";
+import Database from "better-sqlite3";
+/**
+ * Copies a Chrome SQLite database to a temporary location, executes a query,
+ * and cleans up. This avoids SQLite locking issues when Chrome is running.
+ *
+ * @param dbFilePath - Absolute path to the Chrome database file.
+ * @param sql - SQL query to execute.
+ * @param params - Bound parameters for the query.
+ * @returns Query result rows.
+ * @throws If the file doesn't exist or query fails.
+ */
+export function queryDatabase(dbFilePath, sql, params = []) {
+    if (!existsSync(dbFilePath)) {
+        throw new Error(`Database file not found: ${dbFilePath}`);
+    }
+    const tmpDir = mkdtempSync(join(tmpdir(), "chrome-tools-"));
+    const tmpDb = join(tmpDir, basename(dbFilePath));
+    try {
+        copyFileSync(dbFilePath, tmpDb);
+    }
+    catch (err) {
+        cleanupTmp(tmpDb, tmpDir);
+        throw new Error(`Failed to copy database file '${basename(dbFilePath)}': ${err.message}`);
+    }
+    let db;
+    try {
+        db = new Database(tmpDb, { readonly: true, timeout: 5000 });
+        const stmt = db.prepare(sql);
+        return params.length > 0 ? stmt.all(...params) : stmt.all();
+    }
+    catch (err) {
+        throw new Error(`Database query failed on '${basename(dbFilePath)}': ${err.message}`);
+    }
+    finally {
+        if (db) {
+            try {
+                db.close();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        cleanupTmp(tmpDb, tmpDir);
+    }
+}
+/**
+ * Checks whether a specific table exists in the given database file.
+ *
+ * @param dbFilePath - Absolute path to the database file.
+ * @param tableName - Name of the table to check.
+ * @returns True if the table exists.
+ */
+export function tableExists(dbFilePath, tableName) {
+    try {
+        const rows = queryDatabase(dbFilePath, `SELECT name FROM sqlite_master WHERE type='table' AND name=?`, [tableName]);
+        return rows.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function cleanupTmp(tmpDb, tmpDir) {
+    try {
+        unlinkSync(tmpDb);
+    }
+    catch {
+        /* ignore */
+    }
+    try {
+        rmSync(tmpDir, { recursive: true, force: true });
+    }
+    catch {
+        /* ignore */
+    }
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Retrieves the "Chrome Safe Storage" password from the macOS Keychain.
+ * Caches the result for subsequent calls within the same process.
+ *
+ * @returns The raw keychain password.
+ * @throws If the password could not be retrieved.
+ */
+export declare function getChromeKeychainPassword(): string;
+/**
+ * Derives the AES-128-CBC key from the Keychain password using PBKDF2.
+ * Caches the result for subsequent calls.
+ *
+ * @param keychainPassword - The raw password. If omitted, fetched from Keychain.
+ * @returns The derived 16-byte key.
+ */
+export declare function deriveEncryptionKey(keychainPassword?: string): Buffer;
+/**
+ * Clears cached keychain data. Useful for testing or re-authentication.
+ */
+export declare function clearKeychainCache(): void;

package/dist/src/core/keychain.js

@@ -0,0 +1,53 @@
+import { execSync } from "node:child_process";
+import { pbkdf2Sync } from "node:crypto";
+const PBKDF2_ITERATIONS = 1003;
+const PBKDF2_KEY_LENGTH = 16;
+const PBKDF2_SALT = Buffer.from("saltysalt");
+let _cachedKeychainPassword = null;
+let _cachedDerivedKey = null;
+/**
+ * Retrieves the "Chrome Safe Storage" password from the macOS Keychain.
+ * Caches the result for subsequent calls within the same process.
+ *
+ * @returns The raw keychain password.
+ * @throws If the password could not be retrieved.
+ */
+export function getChromeKeychainPassword() {
+    if (_cachedKeychainPassword !== null) {
+        return _cachedKeychainPassword;
+    }
+    try {
+        const password = execSync('security find-generic-password -w -s "Chrome Safe Storage"', { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+        _cachedKeychainPassword = password;
+        return password;
+    }
+    catch {
+        throw new Error("Could not retrieve Chrome Safe Storage key from macOS Keychain.\n" +
+            "Ensure Google Chrome has been run at least once and you have granted Keychain access.");
+    }
+}
+/**
+ * Derives the AES-128-CBC key from the Keychain password using PBKDF2.
+ * Caches the result for subsequent calls.
+ *
+ * @param keychainPassword - The raw password. If omitted, fetched from Keychain.
+ * @returns The derived 16-byte key.
+ */
+export function deriveEncryptionKey(keychainPassword) {
+    if (_cachedDerivedKey !== null) {
+        return _cachedDerivedKey;
+    }
+    const password = keychainPassword || getChromeKeychainPassword();
+    if (!password) {
+        throw new Error("Keychain password cannot be empty for key derivation.");
+    }
+    _cachedDerivedKey = pbkdf2Sync(password, PBKDF2_SALT, PBKDF2_ITERATIONS, PBKDF2_KEY_LENGTH, "sha1");
+    return _cachedDerivedKey;
+}
+/**
+ * Clears cached keychain data. Useful for testing or re-authentication.
+ */
+export function clearKeychainCache() {
+    _cachedKeychainPassword = null;
+    _cachedDerivedKey = null;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * chrome-tools — Public API
+ *
+ * This module re-exports all feature modules for use as a Node.js library.
+ *
+ * @example
+ * import { getPasswords, getBookmarks, discoverProfiles } from 'chrome-tools';
+ *
+ * const passwords = getPasswords({ profile: 'Default' });
+ * const bookmarks = getBookmarks({ search: 'github' });
+ * const profiles  = discoverProfiles();
+ */
+export { getDefaultChromeDir, discoverProfiles, getProfileMetadata, getProfileStates, resolveProfilePath, resolveTargetProfiles, type DiscoveredProfile, type ProfileMetadata, type ProfileState, type ResolveProfilesOptions, } from "./core/chrome.js";
+export { getChromeKeychainPassword, deriveEncryptionKey, clearKeychainCache, } from "./core/keychain.js";
+export { decryptValue, chromeTimeToDate, } from "./core/crypto.js";
+export { queryDatabase, tableExists, } from "./core/db.js";
+export { getPasswords } from "./modules/passwords.js";
+export { getBookmarks } from "./modules/bookmarks.js";
+export { getHistory, getSearchTerms } from "./modules/history.js";
+export { getCookies, type CookieEntry, type CookieOptions } from "./modules/cookies.js";
+export { getAutofillEntries, getCreditCards, getAddresses } from "./modules/autofill.js";
+export { getDownloads } from "./modules/downloads.js";
+export { getExtensions } from "./modules/extensions.js";
+export { getSearchEngines } from "./modules/search-engines.js";
+export { getTopSites } from "./modules/top-sites.js";

package/{src → dist/src}/index.js

@@ -10,33 +10,11 @@
  * const bookmarks = getBookmarks({ search: 'github' });
  * const profiles  = discoverProfiles();
  */
-
 // Core utilities
-export {
-  getDefaultChromeDir,
-  discoverProfiles,
-  getProfileMetadata,
-  getProfileStates,
-  resolveProfilePath,
-  resolveTargetProfiles,
-} from "./core/chrome.js";
-
-export {
-  getChromeKeychainPassword,
-  deriveEncryptionKey,
-  clearKeychainCache,
-} from "./core/keychain.js";
-
-export {
-  decryptValue,
-  chromeTimeToDate,
-} from "./core/crypto.js";
-
-export {
-  queryDatabase,
-  tableExists,
-} from "./core/db.js";
-
+export { getDefaultChromeDir, discoverProfiles, getProfileMetadata, getProfileStates, resolveProfilePath, resolveTargetProfiles, } from "./core/chrome.js";
+export { getChromeKeychainPassword, deriveEncryptionKey, clearKeychainCache, } from "./core/keychain.js";
+export { decryptValue, chromeTimeToDate, } from "./core/crypto.js";
+export { queryDatabase, tableExists, } from "./core/db.js";
 // Feature modules
 export { getPasswords } from "./modules/passwords.js";
 export { getBookmarks } from "./modules/bookmarks.js";

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

@@ -0,0 +1,72 @@
+export interface AutofillOptions {
+    chromeDir?: string;
+    profile?: string;
+    search?: string;
+    limit?: number;
+}
+export interface AutofillEntry {
+    profile: string;
+    name: string;
+    value: string;
+    dateCreated: string;
+    dateLastUsed: string;
+    count: number;
+}
+export interface CreditCardOptions {
+    chromeDir?: string;
+    profile?: string;
+}
+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 {
+    chromeDir?: string;
+    profile?: string;
+}
+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, profile, 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, profile }?: CreditCardOptions): CreditCardEntry[];
+/**
+ * Retrieves saved addresses from Chrome's Web Data database.
+ *
+ * @param options - Targeting options.
+ * @returns Array of address entries.
+ */
+export declare function getAddresses({ chromeDir, profile }?: AddressOptions): AddressEntry[];