feat: add session state management vercel-labs/agent-browser

[amannhq]

This PR implements session persistence with automatic state save/restore, encryption support, and comprehensive state management commands.

Resolves #42
Resolves #86
Resolves #115
Resolves #158

Features

1. Session Persistence (--session-name)

Automatically save and restore cookies/localStorage across browser restarts:

# Auto-save/load state for "twitter" session
agent-browser --session-name twitter open twitter.com

# Login once, then state persists automatically
# State files stored in ~/.agent-browser/sessions/

#### 2. State Encryption (AES-256-GCM)

Encrypt sensitive session data at rest:

```bash
# Generate key: openssl rand -hex 32
export AGENT_BROWSER_ENCRYPTION_KEY=<64-char-hex-key>

# State files are now encrypted automatically
agent-browser --session-name secure open example.com

3. State Management Commands

Command	Description
state list	List saved state files with size, date, encryption status
state show <file>	Show state summary (cookies, origins, domains)
state rename <old> <new>	Rename a state file
state clear <session>	Clear states for a specific session name
state clear --all	Clear all saved states
state clean --older-than <days>	Delete states older than N days
state save <path>	Manual save to custom path
state load <path>	Manual load from custom path

4. Auto-Expiration

Automatically clean up old state files:

export AGENT_BROWSER_STATE_EXPIRE_DAYS=7  # Default: 30

# Or manually clean old states
agent-browser state clean --older-than 7

#### 5. Session Name Validation

Security hardening to prevent path traversal attacks:
- Only alphanumeric, hyphens, underscores allowed
- Rejects `../`, spaces, slashes, special characters

Environment Variables

Variable	Description
AGENT_BROWSER_SESSION_NAME	Auto-save/load state persistence name
AGENT_BROWSER_ENCRYPTION_KEY	64-char hex key for AES-256-GCM encryption
AGENT_BROWSER_STATE_EXPIRE_DAYS	Auto-delete states older than N days (default: 30)

---

CLI Click Command with --new-tab Flag

How It Works

1. User Input

agent-browser click #button --new-tab

[vercel]

@amannhq is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

[ctate]

Appreciate the work on session persistence! The encryption implementation looks solid (AES-256-GCM, proper auth tags, random IVs), but there are critical issues:

Security: Path Traversal Vulnerability

src/state-utils.ts:54-62

export function getAutoStateFilePath(sessionName: string, sessionId: string): string | null {
  if (!sessionName) return null;
  if (!isValidSessionId(sessionId)) {  // Validates sessionId
    throw new Error(...);
  }
  const sessionsDir = ensureSessionsDir();
  return path.join(sessionsDir, `${sessionName}-${sessionId}.json`);  // sessionName not validated
}

Attack vector:
The daemon (not CLI) reads AGENT_BROWSER_SESSION_NAME from environment at three locations:

• daemon.ts:337 (auto-launch)
• daemon.ts:356 (explicit launch)
• daemon.ts:370 (close/save)

None validate before passing to getAutoStateFilePath(). An attacker can:

# Bypass CLI validation entirely
export AGENT_BROWSER_SESSION_NAME="../../../etc/passwd"
node dist/daemon.js  # Daemon starts with malicious session name

Required fix:

export function getAutoStateFilePath(sessionName: string, sessionId: string): string | null {
  if (!sessionName) return null;

  // Add this validation
  if (!isValidSessionName(sessionName)) {
    throw new Error(
      `Invalid session name '${sessionName}'. Only alphanumeric characters, hyphens, and underscores are allowed.`
    );
  }

  if (!isValidSessionId(sessionId)) {
    throw new Error(...);
  }
  // ... rest
}

Missing Tests for Cryptographic Code

encryption.ts (111 lines of crypto code) has zero unit tests. This is a blocker. Need tests for:

• Round-trip: decryptData(encryptData(plain, key), key) === plain
• Tampered auth tag throws error
• Wrong key throws error
• IV uniqueness (encrypt same data twice → different IVs)
• Invalid key format handling
• Malformed encrypted payload detection

Please fix the path traversal vulnerability and add crypto tests before this can be merged.

[amannhq]

@ctate
@Levix

Hey Chris, thanks for the thorough security review! I've addressed all the concerns. Here's a summary:

---

Issues You Raised

1. Path Traversal Vulnerability - FIXED

Identified that sessionName wasn't being validated in getAutoStateFilePath(), allowing attackers to bypass CLI validation via environment variables.

Fix applied:

• Added isValidSessionName() validation in getAutoStateFilePath() (state-utils.ts:70-74)
• All 3 daemon entry points now validate session names from environment variables before use
• Attack vector AGENT_BROWSER_SESSION_NAME="../../../etc/passwd" is now blocked

Test coverage: 22 tests covering path traversal attempts, special characters, Unicode homograph attacks, etc.

2. Missing Crypto Tests - FIXED

The encryption.ts module now has comprehensive test coverage in encryption.test.ts (37 tests):

Requirement	Status
Round-trip: decrypt(encrypt(plain)) === plain	✓ 5 tests
Tampered auth tag throws error	✓
Wrong key throws error	✓ 2 tests
IV uniqueness (same data → different IVs)	✓ 2 tests
Invalid key format handling	✓ 7 tests
Malformed encrypted payload detection	✓ 6 tests

---

Additional Issues Found & Fixed

During the security audit, I discovered two more issues:

3. StreamServer Network Exposure - FIXED

The WebSocket server was binding to 0.0.0.0, exposing browser input injection to the network.

- this.wss = new WebSocketServer({ port: this.port });
+ this.wss = new WebSocketServer({ port: this.port, host: '127.0.0.1' });

4. Prototype Pollution Risk - FIXED

Header merging used object spread which was vulnerable to __proto__ injection.

- headers: { ...requestHeaders, ...headers }
+ headers: safeHeaderMerge(requestHeaders, headers)

The new safeHeaderMerge() utility filters dangerous keys (__proto__, constructor, prototype) and returns a null-prototype object.

---

Code Quality Improvements

Also refactored duplicated code while I was in there:

• Consolidated listStateFiles() and cleanupExpiredStates() into state-utils.ts
• Removed dead code (loadStateFromFile() was unused)

---

Let me know if you'd like any changes!