gstack Cookie Import Authenticated Testing | Import Real Browser Cookies

What Is gstack Cookie Import Authenticated Testing?

gstack cookie import authenticated testing is powered by the /setup-browser-cookies skill, which extracts session cookies from your real browsers and injects them into gstack's headless Chromium instance. This lets Claude Code browse authenticated pages -- dashboards, admin panels, logged-in user views -- without ever requiring you to type a password into the terminal or store credentials in a config file.

The skill auto-detects every Chromium-based browser installed on your Mac, including Comet, Google Chrome, Arc, Brave, and Microsoft Edge. It reads each browser's cookie database, decrypts the cookie values using your macOS Keychain, and presents an interactive picker UI where you choose exactly which domains to import. The entire process takes seconds, and the imported cookies persist in the headless browser session for as long as the daemon is running.

This approach solves a fundamental problem in automated testing: how do you test pages that require authentication without hardcoding passwords, managing OAuth flows programmatically, or maintaining fragile login scripts? With gstack cookie import authenticated testing, the answer is simple -- you borrow the sessions you already have.

Why Cookie Import Matters

Most authenticated testing approaches require storing credentials, building login automation, or using special test accounts. Cookie import sidesteps all of that. If you are logged into a service in your browser, you can test that service in Claude Code within seconds. No passwords, no OAuth dance, no test accounts to maintain.

How /setup-browser-cookies Works

The /setup-browser-cookies skill follows a carefully designed pipeline that prioritizes both convenience and security. Here is the step-by-step flow for gstack cookie import authenticated testing:

Browser detection -- The skill scans for installed Chromium-based browsers using a hardcoded registry of known browser paths. It checks for Comet, Chrome, Arc, Brave, and Edge, reporting which ones are available on your system.
Cookie database access -- Each Chromium browser stores cookies in a SQLite database. The skill copies this database to a temporary file (read-only access to the original) and opens it using Bun's native SQLite driver. No external dependencies are needed.
Keychain decryption -- Chromium encrypts cookie values using a key stored in the macOS Keychain. The skill retrieves this key via the security command, which triggers a macOS Keychain prompt on first access per browser. The key is then used for in-process decryption via PBKDF2 key derivation and AES-128-CBC decryption.
Interactive domain picker -- A terminal-based picker UI displays all domains that have cookies in the selected browser. You select exactly which domains to import. Critically, no cookie values are ever displayed in the picker -- you only see domain names.
Cookie injection -- Selected cookies are injected into the persistent headless Chromium browser managed by the /browse skill. They immediately become available for all subsequent browsing commands.

Supported Browsers

gstack cookie import authenticated testing supports every major Chromium-based browser on macOS. The skill auto-detects which browsers are installed and presents them as options:

Browser	Detection	Notes
Comet	Auto-detected	Full support for cookie extraction and decryption
Google Chrome	Auto-detected	Most widely used; works with all Chrome profiles
Arc	Auto-detected	The Browser Company's Chromium fork, fully supported
Brave	Auto-detected	Privacy-focused browser with standard Chromium cookie storage
Microsoft Edge	Auto-detected	Edge for macOS uses Chromium's cookie format

All five browsers use the same underlying Chromium cookie storage format, which means the decryption and extraction logic is consistent across all of them. The only difference is the file path where each browser stores its cookie database and the Keychain entry name for the encryption key.

Two Ways to Import Cookies

The /setup-browser-cookies skill offers two modes of operation, depending on whether you want to browse and select domains interactively or import specific domains directly.

Interactive Picker Mode

Running the skill without arguments launches the full interactive experience:

# Launch the interactive cookie import picker
/setup-browser-cookies

This displays a terminal UI where you first select a browser, then see a list of all domains with stored cookies. You check the domains you want to import, confirm your selection, and the cookies are injected into the headless browser. This mode is ideal when you are not sure which domains you need, or when you want to import cookies for multiple services at once.

The picker is designed with security in mind: no cookie values are ever displayed. You only see domain names and the number of cookies available for each domain. This prevents accidental exposure of session tokens in terminal history or screen recordings.

Direct Domain Import

When you know exactly which domain you need, skip the picker entirely:

# Import cookies for a specific domain directly
/setup-browser-cookies github.com

# Import cookies for your internal dashboard
/setup-browser-cookies dashboard.yourcompany.com

Direct import is faster and scriptable. It finds the matching domain in your browser's cookie database, decrypts the cookies, and injects them immediately. If the domain has cookies in multiple installed browsers, the skill will prompt you to choose which browser to use.

Security Model: Defense in Depth

Cookie data is sensitive -- session tokens can grant full access to authenticated accounts. The gstack cookie import authenticated testing security model is designed with multiple layers of protection to ensure that cookie data is handled responsibly at every step.

Keychain Gatekeeper

The first import per browser triggers a macOS Keychain prompt. You must explicitly approve access. This is a system-level security gate that cannot be bypassed programmatically.

In-Process Decryption

Cookie decryption uses PBKDF2 key derivation and AES-128-CBC, performed entirely in-process. Decrypted values are never written to disk in plaintext -- they exist only in memory.

Read-Only Database Access

The skill copies the browser's cookie database to a temporary file before reading it. The original database is never modified, and no write operations are performed against it.

Per-Session Key Caching

The Keychain decryption key is cached in memory for the duration of the server session. When the gstack server shuts down, the cached key is gone -- there is no persistent key storage.

No Cookie Values in Logs

Cookie values never appear in terminal output, log files, or the interactive picker UI. Only domain names and metadata are displayed to the user.

Shell Injection Prevention

The skill uses a hardcoded browser registry and Bun.spawn() with explicit argument arrays. There is no string interpolation into shell commands, eliminating shell injection as an attack vector.

Security Summary

The threat model assumes that an attacker could potentially control the domain argument passed to the skill. Even in that scenario, the hardcoded browser registry prevents path traversal, Bun.spawn() prevents shell injection, and the macOS Keychain prompt requires physical user approval. Cookie values are ephemeral -- they live in process memory and the headless browser session, both of which are destroyed when the server shuts down.

Technical Architecture

Understanding the internals of gstack cookie import authenticated testing helps you troubleshoot issues and appreciate the design decisions behind the skill.

Native SQLite via Bun

The skill uses Bun's built-in SQLite driver to read Chromium cookie databases. This means there are no external dependencies -- no better-sqlite3, no sql.js, no native bindings to compile. Bun ships with SQLite support out of the box, which keeps the skill lightweight and eliminates an entire class of installation issues.

The cookie database is opened in read-only mode from a temporary copy. The original database file (typically located at ~/Library/Application Support/[Browser]/Default/Cookies) is never modified. This copy-then-read approach also avoids SQLite locking conflicts with the running browser.

Chromium Cookie Encryption

Chromium on macOS encrypts cookie values using a two-step process:

Key retrieval -- A master password is stored in the macOS Keychain under a browser-specific service name (for example, Chrome Safe Storage). The skill retrieves this password using the macOS security find-generic-password command.
Key derivation and decryption -- The master password is run through PBKDF2 with 1003 iterations and a salt of saltysalt to produce a 16-byte AES key. Each cookie value is then decrypted using AES-128-CBC with a fixed IV of 16 space characters.

This is the standard Chromium cookie encryption scheme on macOS. All five supported browsers use the same algorithm -- only the Keychain service name differs between browsers.

Cookie Injection into Headless Browser

Once cookies are decrypted, they are injected into the Playwright-managed headless Chromium instance via the browser automation skill's API. The injected cookies behave exactly like cookies set by a real browsing session -- they are sent with requests, respected by JavaScript, and persist across page navigations within the headless browser session.

Common Workflows

gstack cookie import authenticated testing enables several workflows that would otherwise require significant setup effort.

Testing Authenticated Dashboards

The most common use case is verifying that an authenticated dashboard renders correctly after code changes. Instead of building a login automation script or maintaining test credentials, you simply import your existing session:

# Import your GitHub session cookies
/setup-browser-cookies github.com

# Navigate to a private repository page
/browse goto https://github.com/your-org/private-repo

# Verify the page loaded with authentication
/browse snapshot -i

QA Testing Behind Authentication Walls

When combined with the automated QA testing skill, cookie import allows comprehensive testing of authenticated features. Import cookies once at the start of a QA session, then run your full test suite against protected pages.

# Import session for your staging environment
/setup-browser-cookies staging.yourapp.com

# Now QA testing can access authenticated routes
/browse goto https://staging.yourapp.com/admin/users
/browse snapshot
/browse goto https://staging.yourapp.com/admin/settings
/browse snapshot -D

Debugging Production Issues

When a user reports an issue on a production page that requires authentication to access, cookie import lets you quickly reproduce the problem. Import your production session cookies, navigate to the problematic page, and use /browse commands to inspect the DOM, check console errors, and verify network requests -- all without leaving Claude Code.

Multi-Service Testing

Modern applications often integrate with multiple third-party services. With gstack cookie import authenticated testing, you can import cookies from multiple domains in a single session. For example, import cookies for both your application and a connected analytics dashboard to verify that cross-service integrations are working correctly.

Troubleshooting

Most issues with gstack cookie import authenticated testing relate to macOS Keychain access or browser state. Here are the most common scenarios and their solutions.

Keychain Prompt Not Appearing

The first time you import cookies from a particular browser, macOS should display a Keychain access prompt. If you do not see the prompt, check that your macOS user session is active (not locked) and that you have not previously denied access for the gstack process. You can reset Keychain permissions in Keychain Access.app under the browser's safe storage entry.

Cookies Not Working After Import

If the import succeeds but authenticated pages still show a login screen, the most likely cause is that the session has expired in your real browser since you last used it. Open the target site in your regular browser, verify you are still logged in, and then re-import. Some services also use additional authentication mechanisms (like IP-based session binding) that may prevent cookies from working in a different browser context.

Browser Not Detected

The skill uses a hardcoded registry of browser paths. If your browser is installed in a non-standard location, it may not be detected. The standard macOS installation paths under /Applications are checked. If you have installed a browser to a custom directory, you may need to create a symlink or move the application to the standard location.

Tip: Check Browser State First

Before importing cookies, make sure you are actively logged into the target service in your real browser. Cookie import transfers your current session state -- if you are logged out in your browser, you will be logged out in the headless browser too. For the best results, visit the target site in your real browser immediately before running /setup-browser-cookies.

Integration with the gstack Ecosystem

The /setup-browser-cookies skill is designed to work seamlessly with other gstack skills. Here is how it fits into the broader ecosystem:

Browser Automation -- Cookie import is the authentication layer for the /browse skill. Import cookies first, then use /browse to navigate, interact with, and test authenticated pages.
Automated QA Testing -- QA test plans often include authenticated scenarios. Cookie import removes the need for login automation in your test scripts, making QA runs faster and more reliable.
Setup Guide -- The /setup-browser-cookies skill is available as part of the standard gstack installation. No additional configuration is required beyond having at least one supported Chromium browser installed.
Shipping Workflow -- Pre-ship smoke tests against authenticated pages become trivial when you can import your existing session cookies in seconds.

Frequently Asked Questions

Does cookie import work with Firefox or Safari?

No. gstack cookie import authenticated testing supports Chromium-based browsers only: Comet, Chrome, Arc, Brave, and Edge. Firefox and Safari use different cookie storage formats and encryption mechanisms that are not currently supported.

Are my cookies stored anywhere after import?

Imported cookies exist only in the headless browser's memory and the in-process cache. When the gstack server shuts down, both are destroyed. No cookies are written to disk in plaintext at any point during the process.

Can I import cookies from multiple browsers simultaneously?

Yes. You can run /setup-browser-cookies multiple times, selecting different browsers each time. Cookies from all imports accumulate in the headless browser session. If the same domain has cookies in multiple browsers, the most recently imported set takes precedence.

What happens when my session expires?

Imported cookies have the same expiration as they do in your real browser. If a session cookie expires, you will need to log back into the service in your real browser and re-import. Long-lived cookies (like "remember me" tokens) will continue to work until their original expiration date.

Is there a risk of accidentally leaking session tokens?

The skill is specifically designed to prevent this. Cookie values are never displayed in the terminal picker, never logged to files, and never included in command output. The only place cookie values exist is in process memory and the headless browser's cookie store, both of which are ephemeral.

Getting Started

If you have gstack installed and configured, the /setup-browser-cookies skill is available immediately. Make sure you have at least one supported Chromium browser installed with active sessions for the services you want to test.

# Quick start: import cookies interactively
/setup-browser-cookies

# Or import a specific domain directly
/setup-browser-cookies github.com

# Then browse authenticated pages
/browse goto https://github.com/settings/profile
/browse snapshot -i

The first run will trigger a macOS Keychain prompt for the selected browser. After you approve access, subsequent imports from the same browser within the same server session will not prompt again, thanks to per-session key caching.

For a complete walkthrough of setting up gstack and all its skills, see the setup and install guide. To learn about the headless browser that receives the imported cookies, read the browser automation testing guide.

gstack Cookie Import Authenticated Testing: Real Browser Sessions for Claude Code