tool-browserAutomationScripts

What it is

A TypeScript-based utility for macOS that interacts directly with Google Chrome's internal storage. It lists user profiles, extracts and decrypts HTTP cookies by accessing the macOS Keychain and SQLite databases, and launches Chrome instances with specific profiles via the command line or as a Node.js library.

Features

• Lists all local Google Chrome user profiles on macOS
• Decrypts Chrome cookies using macOS Keychain and AES-128-CBC
• Launches Chrome with specific profiles and optional URLs
• Provides both CLI interface and TypeScript library API
• Outputs cookie data in table or JSON format

Quickstart

npm install
npm run build
npm link
bas profiles

Architecture

flowchart TD
    User[User/Script] -->|CLI or Import| BAS[browser-automation-scripts]
    subgraph Core_Library
        Profiles[listProfiles]
        Cookies[getCookies]
        Launcher[launchProfile]
    end
    BAS --> Profiles
    BAS --> Cookies
    BAS --> Launcher
    
    Profiles --> FS[File System]
    FS -->|Read Dir| ChromeData[~/Library/Application Support/Google/Chrome]
    
    Cookies --> Keychain[macOS Keychain]
    Keychain -->|Safe Storage Password| Decrypt[AES-128-CBC Decryptor]
    Cookies --> DB[(SQLite Cookies DB)]
    DB -->|Encrypted Values| Decrypt
    Decrypt -->|Plain Text Cookies| BAS
    
    Launcher --> Exec[Child Process]
    Exec -->|Spawn| ChromeBin[Google Chrome Binary]

How it's built

Built with TypeScript and compiled to JavaScript. It uses `commander` for the CLI interface, `better-sqlite3` for reading Chrome's cookie database, and Node.js `crypto` and `child_process` modules to handle AES-128-CBC decryption and Keychain access. The build process is managed via npm scripts.

How it runs

sequenceDiagram
    participant Client as Client (CLI/Library)
    participant BAS as BAS Core
    participant FS as File System
    participant Keychain as macOS Keychain
    participant DB as SQLite DB

    Note over Client, DB: Cookie Decryption Flow
    Client->>BAS: getCookies(domain, profile)
    BAS->>FS: Resolve Profile Path
    FS-->>BAS: Profile Directory
    BAS->>DB: Copy Cookies DB to Temp
    DB-->>BAS: Temp DB Path
    BAS->>Keychain: security find-generic-password
    Keychain-->>BAS: Safe Storage Password
    BAS->>BAS: Derive AES Key (PBKDF2)
    BAS->>DB: Query Encrypted Cookies
    DB-->>BAS: Encrypted Rows
    BAS->>BAS: Decrypt Values (AES-128-CBC)
    BAS-->>Client: Decrypted Cookie Array

How to apply & reuse

Use the `bas` CLI to quickly inspect active sessions (cookies) for web scraping or debugging, list available profiles for multi-account management, or launch specific Chrome profiles from automation scripts. Integrate the library into larger Node.js automation workflows to programmatically manage browser state.

At a glance