Auth Vault

Secure credential storage with AES-256-GCM encryption

Auth Vault

The Auth Vault provides secure credential storage for authentication workflows. Credentials are always encrypted at rest using AES-256-GCM, and the LLM never sees passwords - only profile names.

Quick Start

# Save credentials (password via stdin for security)
echo "mypassword" | agent-browser auth save github \
  --url https://github.com/login \
  --username myuser \
  --password-stdin

# Login using saved profile
agent-browser auth login github

Commands

Save Auth Profile

Store credentials for later use:

# Interactive (prompts for password)
agent-browser auth save <profile-name> \
  --url <login-url> \
  --username <username>

# Non-interactive (password via stdin)
echo "password" | agent-browser auth save <profile-name> \
  --url <login-url> \
  --username <username> \
  --password-stdin

# With custom selectors
agent-browser auth save myapp \
  --url https://myapp.com/login \
  --username [e-mail] \
  --username-selector "#email" \
  --password-selector "#pwd" \
  --submit-selector "button[type=submit]" \
  --password-stdin

Login with Profile

Navigate to login page and automatically fill credentials:

agent-browser auth login <profile-name>

This command:

1. Navigates to the profile’s URL
2. Fills username and password fields
3. Clicks the submit button
4. Updates lastLoginAt timestamp

List Profiles

View all saved auth profiles:

agent-browser auth list

Output:

Auth profiles:
  github
    URL: https://github.com/login
    Username: myuser
    Created: 2026-03-01T10:30:00.000Z
    Last login: 2026-03-02T08:15:00.000Z

Show Profile Details

View details for a specific profile (without password):

agent-browser auth show <profile-name>

Delete Profile

Remove a stored auth profile:

agent-browser auth delete <profile-name>

Storage Location

Auth profiles are stored at:

~/.agent-browser/auth/<profile-name>.json

Each profile file:

• Has 0600 permissions (owner read/write only)
• Is encrypted with AES-256-GCM
• Contains username, password, URL, and selectors

Encryption

Automatic Encryption Key

If no encryption key is configured, agent-browser automatically generates one on first use:

~/.agent-browser/.encryption-key

This file:

• Contains a 256-bit random key (64 hex characters)
• Has 0600 permissions (owner read/write only)
• Is used for all encryption operations

Manual Encryption Key

For production deployments, set an explicit encryption key:

# Generate a key
openssl rand -hex 32

# Set as environment variable
export AGENT_BROWSER_ENCRYPTION_KEY=<64-char-hex-key>

# Now save profiles
echo "password" | agent-browser auth save myapp \
  --url https://myapp.com/login \
  --username user \
  --password-stdin

Encryption Algorithm

• Algorithm: AES-256-GCM
• Key size: 256 bits (32 bytes)
• IV size: 96 bits (12 bytes)
• Authentication: AEAD with GCM auth tag

Auth profiles are stored as JSON with this structure:

{
  "version": 1,
  "encrypted": true,
  "iv": "base64-encoded-iv",
  "authTag": "base64-encoded-auth-tag",
  "data": "base64-encoded-ciphertext"
}

Decrypted Data Structure

The decrypted data contains:

interface AuthProfile {
  name: string;
  url: string;
  username: string;
  password: string;
  usernameSelector?: string;  // CSS selector for username field
  passwordSelector?: string;  // CSS selector for password field
  submitSelector?: string;    // CSS selector for submit button
  createdAt: string;          // ISO 8601 timestamp
  lastLoginAt?: string;       // ISO 8601 timestamp
}

Custom Selectors

By default, auth profiles use standard selectors:

• Username: input[type="text"], input[type="email"]
• Password: input[type="password"]
• Submit: button[type="submit"], input[type="submit"]

For non-standard login forms, specify custom selectors:

agent-browser auth save myapp \
  --url https://myapp.com/login \
  --username [e-mail] \
  --username-selector "#email-field" \
  --password-selector "input[name='pwd']" \
  --submit-selector ".login-btn" \
  --password-stdin

Profile Naming

Profile names must contain only:

• Alphanumeric characters (a-z, A-Z, 0-9)
• Hyphens (-)
• Underscores (_)

Invalid characters are rejected to prevent directory traversal attacks.

Security Best Practices

1. Always Use stdin for Passwords

Never pass passwords as command-line arguments (they appear in shell history):

# Good: password via stdin
echo "password" | agent-browser auth save profile --password-stdin

# Bad: password in command line
agent-browser auth save profile --password "password"  # DON'T DO THIS

2. Backup Your Encryption Key

If you lose the encryption key, encrypted profiles cannot be recovered:

# Backup the auto-generated key
cp ~/.agent-browser/.encryption-key ~/secure-backup/

# Or use an environment variable and store it securely
export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)
echo $AGENT_BROWSER_ENCRYPTION_KEY >> ~/secure-backup/agent-browser-key.txt

3. Use Unique Keys Per Environment

Don’t share encryption keys between development, staging, and production:

# Development
export AGENT_BROWSER_ENCRYPTION_KEY=<dev-key>

# Production
export AGENT_BROWSER_ENCRYPTION_KEY=<prod-key>

4. Rotate Keys Periodically

To rotate keys:

# 1. List current profiles
agent-browser auth list > profiles-backup.txt

# 2. Export profiles (note: requires manual re-creation)
# 3. Delete old profiles
agent-browser auth delete profile1
agent-browser auth delete profile2

# 4. Set new key
export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)

# 5. Re-create profiles with new key
echo "password1" | agent-browser auth save profile1 --password-stdin ...

Programmatic API

Auth profiles can also be managed via the Node.js API:

import {
  saveAuthProfile,
  getAuthProfile,
  listAuthProfiles,
  deleteAuthProfile,
  updateLastLogin
} from 'agent-browser/auth-vault';

// Save profile
const result = saveAuthProfile({
  name: 'github',
  url: 'https://github.com/login',
  username: 'myuser',
  password: 'mypassword',
  usernameSelector: '#login_field',
  passwordSelector: '#password',
  submitSelector: 'input[type="submit"]'
});

console.log(result);
// {
//   name: 'github',
//   url: 'https://github.com/login',
//   username: 'myuser',
//   createdAt: '2026-03-02T10:00:00.000Z',
//   updated: false
// }

// Get profile (with password)
const profile = getAuthProfile('github');
if (profile) {
  console.log(profile.password); // Decrypted password
}

// List all profiles (without passwords)
const profiles = listAuthProfiles();
console.log(profiles);
// [
//   {
//     name: 'github',
//     url: 'https://github.com/login',
//     username: 'myuser',
//     createdAt: '2026-03-02T10:00:00.000Z',
//     lastLoginAt: '2026-03-02T12:00:00.000Z'
//   }
// ]

// Delete profile
const deleted = deleteAuthProfile('github');
console.log(deleted); // true if existed, false otherwise

// Update last login timestamp
updateLastLogin('github');

Environment Variables

Variable	Description	Example
AGENT_BROWSER_ENCRYPTION_KEY	64-character hex encryption key for AES-256-GCM	openssl rand -hex 32

If not set, a key is auto-generated at ~/.agent-browser/.encryption-key.

Troubleshooting

Encryption key required error

Encryption key required to read encrypted auth profiles.
Set AGENT_BROWSER_ENCRYPTION_KEY or ensure ~/.agent-browser/.encryption-key exists.

Solution: The profile was encrypted with a key that’s no longer available. Either:

1. Restore the original key file or environment variable
2. Delete the profile and re-create it

Invalid auth profile name error

Invalid auth profile name 'my/profile': only alphanumeric characters, hyphens, and underscores are allowed

Solution: Use only alphanumeric characters, hyphens, and underscores in profile names.

Login fails with custom selectors

If auth login fails to find elements:

1. Open the login page in headed mode:

   agent-browser --headed open https://myapp.com/login
   

2. Inspect the page and identify correct selectors:

   agent-browser snapshot
   

3. Update the profile with correct selectors:

   echo "password" | agent-browser auth save myapp \
     --url https://myapp.com/login \
     --username user \
     --username-selector "#correct-selector" \
     --password-stdin
   

See Also

• Security Overview - All security features
• Domain Allowlist - Network restriction
• Action Policies - Action gating