chrome-tools 1.1.15 → 1.1.18

package/dist/src/core/browsers.js

@@ -1,186 +0,0 @@
-/**
- * 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.
- */
-/**
- * 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 const BROWSERS = {
-    chrome: {
-        id: "chrome",
-        name: "Google Chrome",
-        aliases: ["google-chrome", "google chrome"],
-        safeStorageLabel: "Chrome Safe Storage",
-        linuxSecretApp: "chrome",
-        dirs: {
-            darwin: "Google/Chrome",
-            win32: "Google/Chrome/User Data",
-            linux: "google-chrome",
-        },
-    },
-    "chrome-beta": {
-        id: "chrome-beta",
-        name: "Google Chrome Beta",
-        safeStorageLabel: "Chrome Safe Storage",
-        linuxSecretApp: "chrome",
-        dirs: {
-            darwin: "Google/Chrome Beta",
-            win32: "Google/Chrome Beta/User Data",
-            linux: "google-chrome-beta",
-        },
-    },
-    "chrome-canary": {
-        id: "chrome-canary",
-        name: "Google Chrome Canary",
-        aliases: ["canary"],
-        safeStorageLabel: "Chrome Safe Storage",
-        linuxSecretApp: "chrome",
-        dirs: {
-            darwin: "Google/Chrome Canary",
-            win32: "Google/Chrome SxS/User Data",
-            linux: "google-chrome-unstable",
-        },
-    },
-    chromium: {
-        id: "chromium",
-        name: "Chromium",
-        safeStorageLabel: "Chromium Safe Storage",
-        linuxSecretApp: "chromium",
-        dirs: {
-            darwin: "Chromium",
-            win32: "Chromium/User Data",
-            linux: "chromium",
-        },
-    },
-    edge: {
-        id: "edge",
-        name: "Microsoft Edge",
-        aliases: ["msedge", "microsoft-edge", "microsoft edge"],
-        safeStorageLabel: "Microsoft Edge Safe Storage",
-        linuxSecretApp: "chromium",
-        dirs: {
-            darwin: "Microsoft Edge",
-            win32: "Microsoft/Edge/User Data",
-            linux: "microsoft-edge",
-        },
-    },
-    brave: {
-        id: "brave",
-        name: "Brave",
-        aliases: ["brave-browser"],
-        safeStorageLabel: "Brave Safe Storage",
-        linuxSecretApp: "chrome",
-        dirs: {
-            darwin: "BraveSoftware/Brave-Browser",
-            win32: "BraveSoftware/Brave-Browser/User Data",
-            linux: "BraveSoftware/Brave-Browser",
-        },
-    },
-    comet: {
-        id: "comet",
-        name: "Comet",
-        aliases: ["perplexity", "perplexity-comet"],
-        safeStorageLabel: "Comet Safe Storage",
-        linuxSecretApp: "chromium",
-        // macOS dir verified (~/Library/Application Support/Comet); Win/Linux best-effort.
-        dirs: {
-            darwin: "Comet",
-            win32: "Perplexity/Comet/User Data",
-            linux: "comet",
-        },
-    },
-    vivaldi: {
-        id: "vivaldi",
-        name: "Vivaldi",
-        // Vivaldi reuses Chrome's Keychain item rather than minting its own.
-        safeStorageLabel: "Chrome Safe Storage",
-        linuxSecretApp: "chrome",
-        dirs: {
-            darwin: "Vivaldi",
-            win32: "Vivaldi/User Data",
-            linux: "vivaldi",
-        },
-    },
-    opera: {
-        id: "opera",
-        name: "Opera",
-        safeStorageLabel: "Opera Safe Storage",
-        linuxSecretApp: "chromium",
-        // Opera's product dir *is* the user-data root (no nested "User Data").
-        // Profiles are usually still under Default/; some layouts are flat at root —
-        // discoverProfiles handles both.
-        dirs: {
-            darwin: "com.operasoftware.Opera",
-            win32: "Opera Software/Opera Stable",
-            win32Base: "roaming",
-            linux: "opera",
-        },
-    },
-};
-const DEFAULT_BROWSER = "chrome";
-/** All supported browsers, in a stable display order. */
-export function listBrowsers() {
-    return Object.values(BROWSERS);
-}
-/**
- * Resolves a browser by id, display name, or alias (case-insensitive).
- * @returns The descriptor, or `null` if unrecognized.
- */
-export function resolveBrowser(idOrName) {
-    if (!idOrName)
-        return null;
-    const needle = idOrName.trim().toLowerCase();
-    for (const b of listBrowsers()) {
-        if (b.id.toLowerCase() === needle)
-            return b;
-        if (b.name.toLowerCase() === needle)
-            return b;
-        if (b.aliases?.some((a) => a.toLowerCase() === needle))
-            return b;
-    }
-    return null;
-}
-/** Resolves a browser or throws an actionable error without changing global state. */
-export function requireBrowser(idOrName) {
-    const resolved = resolveBrowser(idOrName);
-    if (resolved)
-        return resolved;
-    throw new Error(`Unknown browser "${idOrName}". Supported: ${listBrowsers().map((b) => b.id).join(", ")}.`);
-}
-let _active = BROWSERS[DEFAULT_BROWSER];
-/** The browser currently targeted by dir/key lookups. Defaults to Chrome. */
-export function getActiveBrowser() {
-    return _active;
-}
-/**
- * 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 function setActiveBrowser(idOrName) {
-    if (!idOrName || !idOrName.trim()) {
-        _active = BROWSERS[DEFAULT_BROWSER];
-        return _active;
-    }
-    _active = requireBrowser(idOrName);
-    return _active;
-}

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

@@ -1,124 +0,0 @@
-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;
-}
-/**
- * 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.
- * @returns Discovered profiles with name and absolute path.
- */
-export declare function discoverProfiles(chromeDir?: string): 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, }?: ResolveProfilesOptions): DiscoveredProfile[];

package/dist/src/core/chrome.js

@@ -1,259 +0,0 @@
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { basename, join } from "node:path";
-import { getPlatformChromeDir } from "./platform/index.js";
-import { listBrowsers, requireBrowser, } from "./browsers.js";
-/** Known database/data files that indicate a valid Chrome profile directory. */
-const PROFILE_INDICATORS = [
-    "Login Data",
-    "History",
-    "Bookmarks",
-    "Cookies",
-    "Web Data",
-    "Local Storage",
-    "Preferences",
-];
-/**
- * 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 function resolveCookiesDatabasePath(profilePath) {
-    const networkPath = join(profilePath, "Network", "Cookies");
-    return existsSync(networkPath) ? networkPath : join(profilePath, "Cookies");
-}
-/** True when `dir` looks like a Chromium profile (has at least one indicator). */
-function isProfileDirectory(dir) {
-    return PROFILE_INDICATORS.some((file) => existsSync(join(dir, file))) ||
-        existsSync(resolveCookiesDatabasePath(dir));
-}
-/**
- * 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 function getDefaultChromeDir(browser) {
-    return getPlatformChromeDir(browser);
-}
-/**
- * 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 function detectInstalledBrowsers({ includeMissing = false } = {}) {
-    const out = [];
-    for (const browser of listBrowsers()) {
-        const chromeDir = getDefaultChromeDir(browser);
-        const installed = existsSync(chromeDir);
-        if (!installed && !includeMissing)
-            continue;
-        out.push({
-            browser,
-            chromeDir,
-            installed,
-            profileCount: installed ? discoverProfiles(chromeDir).length : 0,
-        });
-    }
-    return out;
-}
-/**
- * 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.
- * @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;
-            // `Network` belongs to its containing profile. Because it may hold a
-            // legacy-looking `Cookies` indicator directly, treating it as a profile
-            // would return `<profile>/Network` instead of the actual profile root.
-            if (entry.name === "Network")
-                continue;
-            const profilePath = join(dir, entry.name);
-            if (isProfileDirectory(profilePath)) {
-                profiles.push({ name: entry.name, path: profilePath });
-            }
-        }
-        // Flat / root-level profile: indicators live on the product dir itself
-        // (no Default/Profile N children), or the caller passed a profile path.
-        if (profiles.length === 0 && isProfileDirectory(dir)) {
-            const name = basename(dir) || "Default";
-            profiles.push({ name, path: dir });
-        }
-        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));
-        }
-        dataFiles.cookies = existsSync(resolveCookiesDatabasePath(profilePath));
-        // 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,
-        };
-    });
-}
-/**
- * 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 function getDirectorySize(dirPath) {
-    if (!dirPath || !existsSync(dirPath)) {
-        return 0;
-    }
-    let total = 0;
-    let entries;
-    try {
-        entries = readdirSync(dirPath, { withFileTypes: true });
-    }
-    catch {
-        return 0;
-    }
-    for (const entry of entries) {
-        const entryPath = join(dirPath, entry.name);
-        try {
-            if (entry.isSymbolicLink()) {
-                continue;
-            }
-            if (entry.isDirectory()) {
-                total += getDirectorySize(entryPath);
-            }
-            else if (entry.isFile()) {
-                total += statSync(entryPath).size;
-            }
-        }
-        catch {
-            // Skip entries we cannot stat (e.g. permission denied, race on deletion).
-        }
-    }
-    return total;
-}
-/**
- * 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, browser, } = {}) {
-    // Validate an explicit browser even when a custom path bypasses default-dir lookup.
-    const targetBrowser = browser ? requireBrowser(browser) : undefined;
-    const dir = profilePath || chromeDir || getDefaultChromeDir(targetBrowser);
-    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

@@ -1,52 +0,0 @@
-/**
- * Decrypts a password/value buffer encrypted by Chrome on macOS or Linux.
- * Chrome v10+ prefixes the encrypted blob with "v10" or "v11", followed by
- * AES-128-CBC ciphertext. (Windows uses AES-256-GCM — see decryptValueBufferGcm.)
- *
- * @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;
-/**
- * Decrypts a Windows Chrome `v10` blob using AES-256-GCM.
- *
- * Unlike the macOS/Linux CBC scheme, Windows blobs carry their own 12-byte
- * nonce after the version prefix and a 16-byte GCM auth tag at the end. The
- * `key` is the 32-byte AES key recovered from `Local State` via DPAPI.
- *
- * @param encryptedBlob - The encrypted blob from the database.
- * @param key - The 32-byte AES-256 key.
- * @returns The decrypted plaintext bytes, or a placeholder string.
- */
-export declare function decryptValueBufferGcm(encryptedBlob: Buffer | Uint8Array | null | undefined, key: Buffer): Buffer | string;
-/**
- * Decrypts a Windows Chrome 127+ `v20` blob using AES-256-GCM.
- *
- * App-Bound Encryption uses the same AES-256-GCM layout as `v10`/`v11` but
- * with a `"v20"` prefix and a key obtained from Chrome's Elevation Service
- * (IElevator COM) instead of plain DPAPI.
- *
- * Layout: "v20" (3 bytes) + 12-byte nonce + ciphertext + 16-byte GCM tag
- *
- * @param encryptedBlob - The encrypted blob from the database.
- * @param key - The 32-byte AES-256 key from ABE decryption.
- * @returns The decrypted plaintext bytes, or a placeholder string.
- */
-export declare function decryptValueBufferGcmV20(encryptedBlob: Buffer | Uint8Array | null | undefined, key: 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 | string | null | undefined): string;