chrome-tools 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,244 @@
+# 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
+npx chrome-tools passwords --profile "Profile 1"
+```
+
+#### 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
+
+# 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 can be placed anywhere in your command line:
+
+- `--chrome-dir <path>`: Specify a custom Chrome User Data folder (e.g., a backed-up profile from another machine).
+- `--profile <name>`: Limit operations to a single profile directory (e.g., `Default`, `Profile 1`).
+- `--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 bookmarks --chrome-dir "/path/to/backup/Chrome" --json > bookmarks.json
+
+# Retrieve all history from a specific profile in JSON format
+npx chrome-tools history --profile "Profile 2" --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({
+  chromeDir: "/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:
+- `chromeDir` *(string)*: Custom Chrome User Data directory.
+- `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(chromeDir)` | `chrome-tools` | `Array<{name, path}>` |
+| `getProfileStates(chromeDir)` | `chrome-tools` | `Array<ProfileState>` |
+| `getPasswords({chromeDir, profile, search})` | `chrome-tools/passwords` | `Array<Credentials>` |
+| `getBookmarks({chromeDir, profile, folder, search})` | `chrome-tools/bookmarks` | `Array<Bookmark>` |
+| `getHistory({chromeDir, profile, search, limit})` | `chrome-tools/history` | `Array<HistoryEntry>` |
+| `getSearchTerms({chromeDir, profile, limit})` | `chrome-tools/history` | `Array<SearchTerm>` |
+| `getCookies({chromeDir, profile, domain, decrypt, limit})` | `chrome-tools/cookies` | `Array<Cookie>` |
+| `getAutofillEntries({chromeDir, profile, search, limit})` | `chrome-tools/autofill` | `Array<AutofillEntry>` |
+| `getCreditCards({chromeDir, profile})` | `chrome-tools/autofill` | `Array<CreditCard>` |
+| `getAddresses({chromeDir, profile})` | `chrome-tools/autofill` | `Array<Address>` |
+| `getDownloads({chromeDir, profile, search, limit})` | `chrome-tools/downloads` | `Array<Download>` |
+| `getExtensions({chromeDir, profile, search})` | `chrome-tools/extensions` | `Array<Extension>` |
+| `getSearchEngines({chromeDir, profile})` | `chrome-tools/search-engines` | `Array<SearchEngine>` |
+| `getTopSites({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).