chrome-tools 1.0.5 → 1.0.7

package/README.md

@@ -1,248 +1,3 @@
 # chrome-tools
 
-A comprehensive, robust command-line interface and Node.js developer library built to extract, decrypt, and inspect saved data from Google Chrome on macOS.
-
-This tool interfaces with the macOS Keychain to retrieve the browser's safe storage key, decrypting AES-128-CBC credentials, cookie values, and autofill credit cards. It also parses open databases like Bookmarks (JSON), History (SQLite), Extensions (JSON), and more.
-
-## Features
-
-- 🔑 **Secure Decryption**: Automatically interfaces with the macOS Keychain to query the Chrome Safe Storage Password.
-- 📦 **Zero Database Locking**: Clones targeted SQLite databases to temporary directories before running queries, ensuring no lockups even while Chrome is active.
-- 👥 **Multi-Profile Support**: Scans and parses data across all discovered Chrome profiles (e.g. `Default`, `Profile 1`, `Profile 2`).
-- 📊 **Rich Subcommands**: Dedicated commands to extract:
-  - Saved website credentials (passwords)
-  - Bookmarks (fully flattened folder structures)
-  - Browsing history and download history
-  - Local session cookies
-  - Autofill entries, saved addresses, and credit cards
-  - Installed extension metadata
-  - Configured search engine keywords and top sites
-- 📂 **Target Custom Directories**: Easily target backed-up Chrome user data directories or specific profiles.
-- 🚀 **Dual Interface**: Fully functional as both a global **npx CLI** and an **importable npm module** for custom scripts.
-- 💎 **Developer Friendly**: Structured JSON output options on all commands for custom shell pipeline processing.
-
----
-
-## Installation & CLI Setup
-
-### Option 1: Run on-the-fly (Recommended)
-You can run any command instantly without manual installation using `npx`:
-```bash
-npx chrome-tools --profiles
-```
-
-### Option 2: Install Globally
-Install the package globally on your system:
-```bash
-npm install -g chrome-tools
-```
-Now, you can execute the command directly:
-```bash
-chrome-tools --help
-```
-
----
-
-## CLI Usage Guide
-
-`chrome-tools` provides a Commander.js-powered CLI featuring dedicated subcommands, global option support, and convenient shortcut flags.
-
-### Shortcut Flags
-For quick auditing, use these top-level shortcut flags:
-```bash
-# List all saved website credentials (requires macOS Keychain approval)
-npx chrome-tools --passwords
-
-# Flatten and list all bookmarks
-npx chrome-tools --bookmarks
-
-# List all discovered profiles and locations
-npx chrome-tools --profiles
-```
-
-### Subcommands
-
-#### Profiles
-Scan and check profile states:
-```bash
-# List profiles with directory name, display name, account email, and path
-npx chrome-tools profiles
-
-# Show detailed profile state along with which data stores are available/missing
-npx chrome-tools profiles states
-```
-
-#### Saved Passwords
-```bash
-# List all website credentials across all profiles
-npx chrome-tools passwords
-
-# Filter credentials using a search term (matches URL or username)
-npx chrome-tools passwords --search "gmail"
-
-# Target a specific profile directory only (placed before the subcommand)
-npx chrome-tools --profile "Profile 1" passwords
-```
-
-#### Bookmarks
-```bash
-# List all bookmarks
-npx chrome-tools bookmarks
-
-# Filter bookmarks inside folders containing "Travel"
-npx chrome-tools bookmarks --folder "travel"
-
-# Filter bookmarks by title or URL search term
-npx chrome-tools bookmarks --search "github"
-```
-
-#### History & Search Terms
-```bash
-# List last 100 browsing history entries
-npx chrome-tools history
-
-# Limit browsing history entries and search URL/Title
-npx chrome-tools history --limit 50 --search "news"
-
-# Extract search queries entered in the address bar
-npx chrome-tools search-terms --limit 20
-```
-
-#### Cookies
-```bash
-# List all cookies (decrypts secure cookie values via Keychain key)
-npx chrome-tools cookies
-
-# Filter cookies for a specific domain name
-npx chrome-tools cookies --domain "google.com" --limit 30
-
-# Filter cookies for a specific URL (matches domain, path, and secure status)
-npx chrome-tools cookies --url "https://github.com/settings/profile"
-
-# Skip decryption of encrypted values (fast metadata lookup)
-npx chrome-tools cookies --no-decrypt
-```
-
-#### Autofill, Credit Cards & Addresses
-```bash
-# List autocomplete text entries (e.g. form fields, text inputs)
-npx chrome-tools autofill --limit 50
-
-# List saved credit cards (decrypts credit card numbers)
-npx chrome-tools credit-cards
-
-# List saved autofill profile addresses (name, email, phone, address, city, zip)
-npx chrome-tools addresses
-```
-
-#### Extensions & Diagnostics
-```bash
-# List installed extensions (name, version, ID, enabled state, and webstore source)
-npx chrome-tools extensions
-
-# List configured search engine keywords
-npx chrome-tools search-engines
-
-# List frequently visited top sites ordered by rank
-npx chrome-tools top-sites
-```
-
-### Global Options
-
-These options apply globally to all subcommands and should be placed before the command (e.g. `npx chrome-tools --profile-path <path> --profile <name> cookies --url <url>`):
-
-- `--profile-path <path>`: Specify a custom Chrome User Data/profile folder (e.g., a backed-up profile from another machine). Defaults to the `PROFILE_PATH` env/`.env` variable, or falls back to the standard macOS Chrome User Data location.
-- `--profile <name>`: Target a specific profile directory (e.g., `Default`, `Profile 1`). Defaults to the `PROFILE_NAME` env/`.env` variable.
-- `--json`: Output strictly in JSON format (ideal for programmatic pipes or exporting to files).
-- `--limit <number>`: Restrict the output results count (for history, autofill, cookies, etc.).
-
-#### Custom Directory & JSON Examples
-```bash
-# Export bookmarks from a backed-up Chrome folder directly to a JSON file
-npx chrome-tools --profile-path "/path/to/backup/Chrome" bookmarks --json > bookmarks.json
-
-# Retrieve all history from a specific profile in JSON format
-npx chrome-tools --profile-path "/path/to/backup/Chrome" --profile "Profile 2" history --json --limit 10
-```
-
----
-
-## Library Import Guide (Programmatic API)
-
-`chrome-tools` is written as a modern ES module. You can import any extraction or utility function directly into your custom Node.js projects.
-
-### Full API Import
-```javascript
-import { 
-  discoverProfiles, 
-  getPasswords, 
-  getBookmarks, 
-  getHistory, 
-  getCookies 
-} from "chrome-tools";
-
-// 1. Discover active profiles
-const profiles = discoverProfiles("/path/to/chrome/User Data");
-console.log(profiles);
-
-// 2. Fetch bookmarks programmatically
-const githubBookmarks = getBookmarks({
-  profilePath: "/path/to/chrome/User Data",
-  search: "github"
-});
-
-// 3. Extract browsing history
-const history = getHistory({ limit: 50 });
-```
-
-### Subpath Imports
-For smaller footprints or isolated dependencies, you can import individual modules directly:
-```javascript
-import { getPasswords } from "chrome-tools/passwords";
-import { getBookmarks } from "chrome-tools/bookmarks";
-import { getHistory } from "chrome-tools/history";
-
-// Example: Retrieve username and password for "chatgpt.com"
-const credentials = getPasswords({ search: "chatgpt.com" });
-for (const cred of credentials) {
-  console.log(`Profile:  ${cred.profile}`);
-  console.log(`Username: ${cred.username}`);
-  console.log(`Password: ${cred.password}`);
-}
-```
-
-### Available API Modules & Signatures
-
-All core functions accept an options object with the following fields:
-- `profilePath` *(string)*: Custom Chrome User Data/profile directory (alias: `chromeDir`).
-- `chromeDir` *(string)*: Alias for `profilePath`.
-- `profile` *(string)*: Specific profile subdirectory name (e.g., `"Default"`).
-- `search` *(string)*: Case-insensitive filter term.
-- `limit` *(number)*: Maximum returned rows count.
-
-| Function | Module Path | Returns |
-| --- | --- | --- |
-| `discoverProfiles(profilePath)` | `chrome-tools` | `Array<{name, path}>` |
-| `getProfileStates(profilePath)` | `chrome-tools` | `Array<ProfileState>` |
-| `getPasswords({profilePath, chromeDir, profile, search})` | `chrome-tools/passwords` | `Array<Credentials>` |
-| `getBookmarks({profilePath, chromeDir, profile, folder, search})` | `chrome-tools/bookmarks` | `Array<Bookmark>` |
-| `getHistory({profilePath, chromeDir, profile, search, limit})` | `chrome-tools/history` | `Array<HistoryEntry>` |
-| `getSearchTerms({profilePath, chromeDir, profile, limit})` | `chrome-tools/history` | `Array<SearchTerm>` |
-| `getCookies({profilePath, chromeDir, profile, domain, url, decrypt, limit})` | `chrome-tools/cookies` | `Array<Cookie>` |
-| `getAutofillEntries({profilePath, chromeDir, profile, search, limit})` | `chrome-tools/autofill` | `Array<AutofillEntry>` |
-| `getCreditCards({profilePath, chromeDir, profile})` | `chrome-tools/autofill` | `Array<CreditCard>` |
-| `getAddresses({profilePath, chromeDir, profile})` | `chrome-tools/autofill` | `Array<Address>` |
-| `getDownloads({profilePath, chromeDir, profile, search, limit})` | `chrome-tools/downloads` | `Array<Download>` |
-| `getExtensions({profilePath, chromeDir, profile, search})` | `chrome-tools/extensions` | `Array<Extension>` |
-| `getSearchEngines({profilePath, chromeDir, profile})` | `chrome-tools/search-engines` | `Array<SearchEngine>` |
-| `getTopSites({profilePath, chromeDir, profile})` | `chrome-tools/top-sites` | `Array<TopSite>` |
-
----
-
-## Security Warning
-
-This utility is designed strictly for authorized administrative audits, security diagnostics, and local credential migration. macOS will request explicit Keychain authorization before releasing the Chrome Safe Storage Password. Keep your local credentials safe, and only run this code in trusted development environments.
-
-## License
-
-This project is licensed under the [MIT License](LICENSE).
+CLI & Node.js library for chrome

package/dist/bin/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * chrome-tools CLI
+ *
+ * A comprehensive command-line interface for extracting Chrome browser data on macOS.
+ * Supports subcommands and shortcut flags for quick access to all data types.
+ */
+export {};

package/dist/bin/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import{readFileSync as o,existsSync as e}from"node:fs";import{join as t}from"node:path";import{Command as s}from"commander";import i from"chalk";import r from"cli-table3";import{discoverProfiles as n,getProfileMetadata as l,getProfileStates as a,getDefaultChromeDir as c}from"../src/core/chrome.js";import{getPasswords as m}from"../src/modules/passwords.js";import{getBookmarks as p}from"../src/modules/bookmarks.js";import{getHistory as d,getSearchTerms as f}from"../src/modules/history.js";import{getCookies as h}from"../src/modules/cookies.js";import{getAutofillEntries as u,getCreditCards as g,getAddresses as b}from"../src/modules/autofill.js";import{getDownloads as y}from"../src/modules/downloads.js";import{getExtensions as w}from"../src/modules/extensions.js";import{getSearchEngines as S}from"../src/modules/search-engines.js";import{getTopSites as k}from"../src/modules/top-sites.js";const P=function(){const s={...process.env},i=t(process.cwd(),".env");if(e(i))try{const e=o(i,"utf8");for(const o of e.split(/\r?\n/)){const e=o.trim();if(!e||e.startsWith("#"))continue;const t=e.indexOf("=");if(-1!==t){const o=e.substring(0,t).trim();let i=e.substring(t+1).trim();(i.startsWith('"')&&i.endsWith('"')||i.startsWith("'")&&i.endsWith("'"))&&(i=i.slice(1,-1)),s[o]=i}}}catch{}return s}(),j=P.PROFILE_PATH||c(),L=P.PROFILE_NAME||void 0;function v(o){console.log(JSON.stringify(o,null,2))}function W(o,e){return new r({head:o.map(o=>i.bold.white(o)),colWidths:e,wordWrap:!0,style:{border:["grey"],head:[]}})}function D(o,e){0===e?console.log(i.yellow(`\n⚠ No ${o} found.\n`)):console.log(i.green(`\n✔ Found ${e} ${o}.\n`))}function N(o){return o.option("--profile-path <path>","Custom Chrome Profile Path",j).option("--profile <name>","Target a specific profile",L).option("--json","Output as JSON")}function C(o){return o.option("--search <term>","Filter results (case-insensitive)")}function U(o,e=100){return o.option("--limit <n>","Limit number of results",String(e))}const G=new s,O=JSON.parse(o(new URL("../../package.json",import.meta.url),"utf8"));G.name("chrome-tools").description(i.bold.cyan("Chrome Data Toolkit")+i.dim(" — Extract passwords, bookmarks, history, cookies, and more from Chrome on macOS")).version(O.version).option("--passwords","Shortcut: list saved passwords").option("--bookmarks","Shortcut: list bookmarks").option("--profiles","Shortcut: list profiles").option("--profile-path <path>","Custom Chrome Profile Path",j).option("--profile <name>","Target a specific profile",L).option("--json","Output as JSON").option("--search <term>","Filter results (for shortcut flags)").option("--limit <n>","Limit results (for shortcut flags)");const $=G.command("profiles").description("List Chrome profiles");function x(o){const e=n(o.profilePath),t=l(o.profilePath);if(o.json){const o=new Map(t.map(o=>[o.directory,o]));return v(e.map(e=>({...e,...o.get(e.name)||{}})))}if(0===e.length)return void console.log(i.yellow("\n⚠ No Chrome profiles found.\n"));const s=new Map(t.map(o=>[o.directory,o]));console.log(i.bold(`\n📁 Discovered ${e.length} profile(s):\n`));const r=W(["Directory","Display Name","Email","Path"],[16,22,30,50]);for(const o of e){const e=s.get(o.name)||{};r.push([i.cyan(o.name),i.white(e.name||o.name),i.dim(e.email||"—"),i.dim(o.path)])}console.log(r.toString()),D("profile(s)",e.length)}N($).action((o,e)=>{x(e.optsWithGlobals())}),$.command("states").description("Show detailed profile states with available data files").option("--profile-path <path>","Custom Chrome Profile Path",j).option("--json","Output as JSON").action((o,e)=>function(o){const e=a(o.profilePath);if(o.json)return v(e);if(0===e.length)return void console.log(i.yellow("\n⚠ No Chrome profiles found.\n"));console.log(i.bold(`\n📊 Profile States (${e.length} profile(s)):\n`));for(const o of e){console.log(i.bold.cyan(`  ${o.displayName}`)+i.dim(` (${o.directory})`)),o.email&&console.log(i.dim(`    Email: ${o.email}`)),console.log(i.dim(`    Path:  ${o.path}`));const e=o.dataFiles,t=Object.entries(e).filter(([,o])=>o).map(([o])=>o),s=Object.entries(e).filter(([,o])=>!o).map(([o])=>o);console.log(`    Available: ${t.map(o=>i.green(o)).join(", ")||i.dim("none")}`),s.length>0&&console.log(`    Missing:   ${s.map(o=>i.dim(o)).join(", ")}`),console.log()}}(e.optsWithGlobals()));function E(o){const e=m({chromeDir:o.profilePath,profile:o.profile,search:o.search});if(o.json)return v(e);if(0===e.length)return D("passwords",0);console.log(i.bold("\n🔑 Saved Passwords:\n"));const t=new Set(e.map(o=>o.profile)).size>1,s=W(t?["Profile","URL","Username","Password","Last Used"]:["URL","Username","Password","Last Used"],t?[12,40,24,22,20]:[45,28,25,22]);for(const o of e){const e=[i.cyan(o.url),i.green(o.username||"<empty>"),i.yellow(o.password||"<empty>"),i.dim(o.lastUsed)];t&&e.unshift(i.magenta(o.profile)),s.push(e)}console.log(s.toString()),D("password(s)",e.length)}C(N(G.command("passwords").description("List saved passwords"))).action((o,e)=>E(e.optsWithGlobals()));function F(o){const e=p({chromeDir:o.profilePath,profile:o.profile,folder:o.folder,search:o.search});if(o.json)return v(e);if(0===e.length)return D("bookmarks",0);console.log(i.bold("\n📚 Bookmarks:\n"));const t=W(["Title","URL","Folder","Date Added"],[30,50,25,20]);for(const o of e)t.push([i.white(o.title),i.cyan(o.url),i.dim(o.folder||"/"),i.dim(o.dateAdded)]);console.log(t.toString()),D("bookmark(s)",e.length)}C(N(G.command("bookmarks").description("List bookmarks"))).option("--folder <name>","Filter by folder name").action((o,e)=>F(e.optsWithGlobals()));C(U(N(G.command("history").description("List browsing history")))).action((o,e)=>{const t=e.optsWithGlobals(),s=d({chromeDir:t.profilePath,profile:t.profile,search:t.search,limit:parseInt(t.limit,10)||100});if(t.json)return v(s);if(0===s.length)return D("history entries",0);console.log(i.bold("\n🕐 Browsing History:\n"));const r=W(["URL","Title","Visits","Last Visit"],[50,30,8,22]);for(const o of s)r.push([i.cyan(o.url),i.white(o.title||"—"),i.yellow(String(o.visitCount)),i.dim(o.lastVisit)]);console.log(r.toString()),D("history entry(ies)",s.length)});U(N(G.command("search-terms").description("List search terms from history"))).action((o,e)=>{const t=e.optsWithGlobals(),s=f({chromeDir:t.profilePath,profile:t.profile,limit:parseInt(t.limit,10)||100});if(t.json)return v(s);if(0===s.length)return D("search terms",0);console.log(i.bold("\n🔍 Search Terms:\n"));const r=W(["Term","URL"],[40,80]);for(const o of s)r.push([i.white(o.term),i.dim(o.url)]);console.log(r.toString()),D("search term(s)",s.length)});U(N(G.command("cookies").description("List cookies (encrypted values decrypted)"))).option("--domain <domain>","Filter by domain").option("--url <url>","Filter by URL with path").option("--no-decrypt","Skip decryption of encrypted values").action((o,e)=>{const t=e.optsWithGlobals(),s=h({chromeDir:t.profilePath,profile:t.profile,domain:t.domain,url:t.url,decrypt:!1!==t.decrypt,limit:parseInt(t.limit,10)||100});if(t.json)return v(s);if(0===s.length)return D("cookies",0);console.log(i.bold("\n🍪 Cookies:\n"));const r=W(["Domain","Name","Value","Secure","Expires"],[30,25,30,8,22]);for(const o of s)r.push([i.cyan(o.domain),i.white(o.name),i.dim(o.value?o.value.substring(0,50)+(o.value.length>50?"…":""):"—"),o.secure?i.green("✓"):i.dim("✗"),i.dim(o.expires)]);console.log(r.toString()),D("cookie(s)",s.length)});C(U(N(G.command("autofill").description("List autofill entries")))).action((o,e)=>{const t=e.optsWithGlobals(),s=u({chromeDir:t.profilePath,profile:t.profile,search:t.search,limit:parseInt(t.limit,10)||100});if(t.json)return v(s);if(0===s.length)return D("autofill entries",0);console.log(i.bold("\n📝 Autofill Entries:\n"));const r=W(["Field Name","Value","Count","Last Used"],[25,40,8,22]);for(const o of s)r.push([i.cyan(o.name),i.white(o.value),i.yellow(String(o.count)),i.dim(o.dateLastUsed)]);console.log(r.toString()),D("autofill entry(ies)",s.length)});N(G.command("credit-cards").description("List saved credit cards")).action((o,e)=>{const t=e.optsWithGlobals(),s=g({chromeDir:t.profilePath,profile:t.profile});if(t.json)return v(s);if(0===s.length)return D("credit cards",0);console.log(i.bold("\n💳 Saved Credit Cards:\n"));const r=W(["Name on Card","Card Number","Expires","Nickname"],[25,25,14,20]);for(const o of s)r.push([i.white(o.nameOnCard||"—"),i.yellow(o.cardNumber||"—"),i.dim(`${o.expirationMonth}/${o.expirationYear}`),i.dim(o.nickname||"—")]);console.log(r.toString()),D("credit card(s)",s.length)});N(G.command("addresses").description("List saved addresses")).action((o,e)=>{const t=e.optsWithGlobals(),s=b({chromeDir:t.profilePath,profile:t.profile});if(t.json)return v(s);if(0===s.length)return D("addresses",0);console.log(i.bold("\n🏠 Saved Addresses:\n"));const r=W(["Name","Email","Phone","Address","City/State/Zip"],[20,25,16,30,25]);for(const o of s)r.push([i.white(o.fullName||"—"),i.cyan(o.email||"—"),i.dim(o.phone||"—"),i.white(o.streetAddress||"—"),i.dim([o.city,o.state,o.zipcode].filter(Boolean).join(", ")||"—")]);console.log(r.toString()),D("address(es)",s.length)});C(U(N(G.command("downloads").description("List download history")))).action((o,e)=>{const t=e.optsWithGlobals(),s=y({chromeDir:t.profilePath,profile:t.profile,search:t.search,limit:parseInt(t.limit,10)||100});if(t.json)return v(s);if(0===s.length)return D("downloads",0);console.log(i.bold("\n⬇️  Download History:\n"));const r=W(["File","URL","Size","State","Date"],[35,40,12,12,20]);for(const o of s){const e=o.targetPath?o.targetPath.split("/").pop():"—",t=o.totalBytes>0?R(o.totalBytes):"—";r.push([i.white(e||""),i.cyan(o.url?o.url.substring(0,60):"—"),i.dim(t),"complete"===o.state?i.green(o.state):i.yellow(o.state),i.dim(o.startTime)])}console.log(r.toString()),D("download(s)",s.length)});C(N(G.command("extensions").description("List installed extensions"))).action((o,e)=>{const t=e.optsWithGlobals(),s=w({chromeDir:t.profilePath,profile:t.profile,search:t.search});if(t.json)return v(s);if(0===s.length)return D("extensions",0);console.log(i.bold("\n🧩 Installed Extensions:\n"));const r=W(["Name","Version","ID","Enabled","Webstore"],[30,12,36,9,9]);for(const o of s)r.push([i.white(o.name),i.dim(o.version),i.dim(o.id),o.enabled?i.green("✓"):i.red("✗"),o.fromWebstore?i.green("✓"):i.dim("✗")]);console.log(r.toString()),D("extension(s)",s.length)});N(G.command("search-engines").description("List configured search engines")).action((o,e)=>{const t=e.optsWithGlobals(),s=S({chromeDir:t.profilePath,profile:t.profile});if(t.json)return v(s);if(0===s.length)return D("search engines",0);console.log(i.bold("\n🔎 Search Engines:\n"));const r=W(["Name","Keyword","URL","Active"],[20,16,60,8]);for(const o of s)r.push([i.white(o.name),i.cyan(o.keyword),i.dim(o.url?o.url.substring(0,80):"—"),o.isActive?i.green("✓"):i.dim("✗")]);console.log(r.toString()),D("search engine(s)",s.length)});function R(o){if(0===o)return"0 B";const e=Math.floor(Math.log(o)/Math.log(1024));return`${(o/Math.pow(1024,e)).toFixed(1)} ${["B","KB","MB","GB","TB"][e]}`}N(G.command("top-sites").description("List top sites")).action((o,e)=>{const t=e.optsWithGlobals(),s=k({chromeDir:t.profilePath,profile:t.profile});if(t.json)return v(s);if(0===s.length)return D("top sites",0);console.log(i.bold("\n⭐ Top Sites:\n"));const r=W(["Rank","Title","URL"],[8,30,80]);for(const o of s)r.push([i.yellow(String(o.rank+1)),i.white(o.title||"—"),i.cyan(o.url)]);console.log(r.toString()),D("top site(s)",s.length)}),G.parse();const T=G.opts();G.args.length>0||(T.passwords?E(T):T.bookmarks?F(T):T.profiles?x(T):G.help());

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

@@ -0,0 +1,77 @@
+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;
+}
+/**
+ * Returns the default Chrome User Data directory for macOS.
+ * @returns The absolute path to Chrome's User Data.
+ */
+export declare function getDefaultChromeDir(): string;
+/**
+ * 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 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[];
+/**
+ * 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, }?: ResolveProfilesOptions): DiscoveredProfile[];

package/dist/src/core/chrome.js

@@ -0,0 +1 @@
+import{existsSync as e,readdirSync as t,readFileSync as r}from"node:fs";import{homedir as o}from"node:os";import{join as a}from"node:path";const i=["Login Data","History","Bookmarks","Cookies","Web Data","Preferences"];export function getDefaultChromeDir(){return a(o(),"Library","Application Support","Google","Chrome")}export function discoverProfiles(r){const o=r||getDefaultChromeDir();if(!o||!e(o))return[];try{const r=t(o,{withFileTypes:!0}),n=[];for(const t of r){if(!t.isDirectory())continue;const r=a(o,t.name);i.some(t=>e(a(r,t)))&&n.push({name:t.name,path:r})}return n}catch{return[]}}export function getProfileMetadata(t){const o=t||getDefaultChromeDir(),i=a(o,"Local State");if(!e(i))return[];try{const e=r(i,"utf-8"),t=JSON.parse(e),o=t?.profile?.info_cache;return o&&"object"==typeof o?Object.entries(o).map(([e,t])=>{const r=t;return{directory:e,name:r.name||e,gaiaName:r.gaia_name||"",userName:r.user_name||"",email:r.user_name||"",avatarIcon:r.avatar_icon||"",isUsingDefaultName:r.is_using_default_name??!0,isEphemeral:r.is_ephemeral??!1,activeTime:r.active_time||0}}):[]}catch{return[]}}export function getProfileStates(t){const r=t||getDefaultChromeDir(),o=discoverProfiles(r),n=getProfileMetadata(r),s=new Map;for(const e of n)s.set(e.directory,e);return o.map(t=>{const r=s.get(t.name),o=t.path,n={};for(const t of i)n[t.replace(/\s+/g,"_").toLowerCase()]=e(a(o,t));return n.top_sites=e(a(o,"Top Sites")),n.extensions=e(a(o,"Extensions")),{directory:t.name,path:o,displayName:r?.name||t.name,gaiaName:r?.gaiaName||"",email:r?.email||"",avatarIcon:r?.avatarIcon||"",isEphemeral:r?.isEphemeral??!1,activeTime:r?.activeTime||0,dataFiles:n}})}export function resolveProfilePath(t,r){const o=t||getDefaultChromeDir(),i=a(o,r);return e(i)?i:null}export function resolveTargetProfiles({profilePath:e,chromeDir:t,profile:r}={}){const o=e||t||getDefaultChromeDir(),a=discoverProfiles(o);if(r){const e=a.filter(e=>e.name===r);if(0===e.length)throw new Error(`Profile "${r}" not found in ${o}`);return e}return a}

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 @@
+import{createDecipheriv as r}from"node:crypto";const t=Buffer.alloc(16," ");export function decryptValue(r,t){const e=decryptValueBuffer(r,t);return Buffer.isBuffer(e)?e.toString("utf-8"):e}export function decryptValueBuffer(e,n){if(!e||0===e.length)return Buffer.alloc(0);const f=Buffer.isBuffer(e)?e:Buffer.from(e),u=f.subarray(0,3).toString("utf-8");if("v10"!==u&&"v11"!==u)return"<unsupported encryption format>";const o=f.subarray(3);try{const e=r("aes-128-cbc",n,t);let f=e.update(o);return f=Buffer.concat([f,e.final()]),f}catch{return"<decryption failed>"}}export function chromeTimeToDate(r){if(!r||0===r||0n===r)return"N/A";try{const t=BigInt(r),e=Number((t-11644473600000000n)/1000n),n=new Date(e);return isNaN(n.getTime())?"N/A":n.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 @@
+import{existsSync as t,copyFileSync as e,mkdtempSync as r,unlinkSync as o,rmSync as a}from"node:fs";import{tmpdir as n}from"node:os";import{join as c,basename as s}from"node:path";import l from"better-sqlite3";export function queryDatabase(o,a,f=[]){if(!t(o))throw new Error(`Database file not found: ${o}`);const m=r(c(n(),"chrome-tools-")),h=c(m,s(o));try{e(o,h)}catch(t){throw i(h,m),new Error(`Failed to copy database file '${s(o)}': ${t.message}`)}let y;try{y=new l(h,{readonly:!0,timeout:5e3});const t=y.prepare(a);return f.length>0?t.all(...f):t.all()}catch(t){throw new Error(`Database query failed on '${s(o)}': ${t.message}`)}finally{if(y)try{y.close()}catch{}i(h,m)}}export function tableExists(t,e){try{return queryDatabase(t,"SELECT name FROM sqlite_master WHERE type='table' AND name=?",[e]).length>0}catch{return!1}}function i(t,e){try{o(t)}catch{}try{a(e,{recursive:!0,force:!0})}catch{}}

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 @@
+import{execSync as e}from"node:child_process";import{pbkdf2Sync as r}from"node:crypto";const n=Buffer.from("saltysalt");let o=null,t=null;export function getChromeKeychainPassword(){if(null!==o)return o;try{const r=e('security find-generic-password -w -s "Chrome Safe Storage"',{encoding:"utf-8",stdio:["pipe","pipe","pipe"]}).trim();return o=r,r}catch{throw new Error("Could not retrieve Chrome Safe Storage key from macOS Keychain.\nEnsure Google Chrome has been run at least once and you have granted Keychain access.")}}export function deriveEncryptionKey(e){if(null!==t)return t;const o=e||getChromeKeychainPassword();if(!o)throw new Error("Keychain password cannot be empty for key derivation.");return t=r(o,n,1003,16,"sha1"),t}export function clearKeychainCache(){o=null,t=null}

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

@@ -10,38 +10,14 @@
  * 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";
-
-// Feature modules
+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 } from "./modules/cookies.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";

package/dist/src/index.js

@@ -0,0 +1 @@
+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{getPasswords}from"./modules/passwords.js";export{getBookmarks}from"./modules/bookmarks.js";export{getHistory,getSearchTerms}from"./modules/history.js";export{getCookies}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/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[];

package/dist/src/modules/autofill.js

@@ -0,0 +1 @@
+import{join as e}from"node:path";import{resolveTargetProfiles as t}from"../core/chrome.js";import{deriveEncryptionKey as o}from"../core/keychain.js";import{decryptValue as n,chromeTimeToDate as i}from"../core/crypto.js";import{queryDatabase as a,tableExists as r}from"../core/db.js";export function getAutofillEntries({chromeDir:o,profile:n,search:d,limit:c=100}={}){const s=t({chromeDir:o,profile:n}),u=[];for(const t of s){const o=e(t.path,"Web Data");try{if(!r(o,"autofill"))continue;let e="SELECT name, value, date_created, date_last_used, count\n                 FROM autofill ORDER BY date_last_used DESC";c&&(e+=` LIMIT ${parseInt(c,10)}`);const n=a(o,e);for(const e of n){const o={profile:t.name,name:e.name||"",value:e.value||"",dateCreated:i(e.date_created?1000000n*BigInt(e.date_created)+11644473600000000n:0),dateLastUsed:i(e.date_last_used?1000000n*BigInt(e.date_last_used)+11644473600000000n:0),count:e.count||0};if(d){const e=d.toLowerCase();if(!(o.name&&o.name.toLowerCase().includes(e)||o.value&&o.value.toLowerCase().includes(e)))continue}u.push(o)}}catch{}}return u}export function getCreditCards({chromeDir:d,profile:c}={}){const s=t({chromeDir:d,profile:c}),u=o(),l=[];for(const t of s){const o=e(t.path,"Web Data");try{if(!r(o,"credit_cards"))continue;const e=a(o,"SELECT guid, name_on_card, expiration_month, expiration_year,\n                card_number_encrypted, date_modified, origin, use_count,\n                use_date, nickname\n         FROM credit_cards ORDER BY use_date DESC");for(const o of e){let e="";o.card_number_encrypted&&(e=n(o.card_number_encrypted,u)),l.push({profile:t.name,guid:o.guid||"",nameOnCard:o.name_on_card||"",expirationMonth:o.expiration_month||0,expirationYear:o.expiration_year||0,cardNumber:e,nickname:o.nickname||"",origin:o.origin||"",useCount:o.use_count||0,dateModified:i(o.date_modified?1000000n*BigInt(o.date_modified)+11644473600000000n:0)})}}catch{}}return l}export function getAddresses({chromeDir:o,profile:n}={}){const d=t({chromeDir:o,profile:n}),c=[];for(const t of d){const o=e(t.path,"Web Data");try{if(!r(o,"autofill_profiles"))continue;const e=a(o,"SELECT guid, company_name, street_address, dependent_locality,\n                city, state, zipcode, country_code, date_modified,\n                origin, use_count, use_date, language_code\n         FROM autofill_profiles ORDER BY use_date DESC");let n=[],d=[],s=[];try{r(o,"autofill_profile_names")&&(n=a(o,"SELECT guid, first_name, middle_name, last_name, full_name FROM autofill_profile_names"))}catch{}try{r(o,"autofill_profile_emails")&&(d=a(o,"SELECT guid, email FROM autofill_profile_emails"))}catch{}try{r(o,"autofill_profile_phones")&&(s=a(o,"SELECT guid, number FROM autofill_profile_phones"))}catch{}const u=new Map;for(const e of n)u.set(e.guid,e.full_name||[e.first_name,e.middle_name,e.last_name].filter(Boolean).join(" "));const l=new Map;for(const e of d)l.set(e.guid,e.email||"");const f=new Map;for(const e of s)f.set(e.guid,e.number||"");for(const o of e)c.push({profile:t.name,guid:o.guid||"",fullName:u.get(o.guid)||"",email:l.get(o.guid)||"",phone:f.get(o.guid)||"",companyName:o.company_name||"",streetAddress:o.street_address||"",city:o.city||"",state:o.state||"",zipcode:o.zipcode||"",countryCode:o.country_code||"",origin:o.origin||"",useCount:o.use_count||0,dateModified:i(o.date_modified?1000000n*BigInt(o.date_modified)+11644473600000000n:0)})}catch{}}return c}

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

@@ -0,0 +1,23 @@
+export interface BookmarkOptions {
+    chromeDir?: string;
+    profile?: string;
+    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, profile, folder, search }?: BookmarkOptions): BookmarkEntry[];

package/dist/src/modules/bookmarks.js

@@ -0,0 +1 @@
+import{existsSync as o,readFileSync as r}from"node:fs";import{join as e}from"node:path";import{resolveTargetProfiles as t}from"../core/chrome.js";import{chromeTimeToDate as n}from"../core/crypto.js";function s(o){return o&&"0"!==o?n(BigInt(o)):"N/A"}function i(o,r=""){const e=[];if(!o)return e;const t=r?`${r}/${o.name||""}`:o.name||"";if("url"===o.type&&e.push({title:o.name||"",url:o.url||"",folder:r,dateAdded:s(o.date_added),dateLastUsed:s(o.date_last_used),id:o.id,guid:o.guid||""}),o.children&&Array.isArray(o.children))for(const r of o.children)e.push(...i(r,t));return e}export function getBookmarks({chromeDir:n,profile:s,folder:c,search:f}={}){const d=t({chromeDir:n,profile:s}),a=[];for(const t of d){const n=e(t.path,"Bookmarks");if(o(n))try{const o=r(n,"utf-8"),e=JSON.parse(o).roots;if(!e)continue;const s=["bookmark_bar","other","synced"];for(const o of s)if(e[o]){const r=i(e[o],"");for(const o of r)o.profile=t.name,a.push(o)}}catch{}}let l=a;if(c){const o=c.toLowerCase();l=l.filter(r=>r.folder.toLowerCase().includes(o))}if(f){const o=f.toLowerCase();l=l.filter(r=>r.title.toLowerCase().includes(o)||r.url.toLowerCase().includes(o))}return l}

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

@@ -0,0 +1,40 @@
+export interface CookieOptions {
+    chromeDir?: string;
+    profile?: string;
+    domain?: string;
+    url?: string;
+    decrypt?: boolean;
+    limit?: number;
+}
+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, profile, domain, url, decrypt, limit, }?: CookieOptions): CookieEntry[];
+export declare const _test: {
+    parseURL: typeof parseURL;
+    getPossibleHostKeys: typeof getPossibleHostKeys;
+    domainMatch: typeof domainMatch;
+    pathMatch: typeof pathMatch;
+};
+export {};