chrome-tools 1.0.6 → 1.0.8

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