# ABE — Exploration Scope & Target Authentication Specification

## Exploration Config Object

This config is passed via POST /api/sessions and stored in sessions.config_json.
```typescript
interface ExplorationConfig {
  // Scope
  allowedDomains: string[];     // e.g. ["localhost", "myapp.com"] — never follow external links
  maxStates: number;            // default: 50 — stop after this many unique states
  maxDepth: number;             // default: 5 — max click depth from start URL
  actionDelayMs: number;        // default: 500 — wait between actions (politeness)
  sessionTimeoutMs: number;     // default: 300000 (5 min) — hard stop

  // Exclusions
  excludedPaths: string[];      // e.g. ["/logout", "/admin"] — never navigate here
  excludedSelectors: string[];  // e.g. ["button.delete", "a[href*='delete']"]

  // Target authentication
  auth: AuthConfig | null;

  // Fuzzing
  fuzzingEnabled: boolean;      // default: true
  fuzzingIntensity: 'low' | 'medium' | 'high'; // default: 'medium'
}

type AuthConfig =
  | { type: 'cookies'; cookies: Array<{ name: string; value: string; domain: string }> }
  | { type: 'headers'; headers: Record<string, string> }
  | { type: 'login_flow'; loginUrl: string; usernameSelector: string; passwordSelector: string; submitSelector: string; username: string; password: string }
```

## Scope Rules (enforced in PlaywrightAgent)

1. Before navigating to any URL, check if hostname is in allowedDomains. If not, skip.
2. Before executing any action, check if current path matches excludedPaths. If yes, skip.
3. Before clicking any element, check if it matches excludedSelectors. If yes, skip.
4. Stop exploration when statesVisited >= maxStates OR depth >= maxDepth OR elapsed > sessionTimeoutMs.

## Authentication Flow

### type: 'cookies'
Inject cookies before the first navigation using playwright context.addCookies().

### type: 'headers'
Set extra HTTP headers on the browser context using context.setExtraHTTPHeaders().

### type: 'login_flow'
Before starting exploration:
1. Navigate to loginUrl
2. Fill usernameSelector with username
3. Fill passwordSelector with password
4. Click submitSelector
5. Wait for navigation to complete
6. Verify we are no longer on loginUrl (if still there, login failed → abort session with error)
7. Proceed with exploration from startUrl

## Updated POST /api/sessions request body
```json
{
  "url": "http://localhost:3000",
  "seed": 42,
  "config": {
    "allowedDomains": ["localhost"],
    "maxStates": 50,
    "maxDepth": 5,
    "actionDelayMs": 500,
    "sessionTimeoutMs": 300000,
    "excludedPaths": ["/logout"],
    "excludedSelectors": [],
    "auth": {
      "type": "login_flow",
      "loginUrl": "http://localhost:3000/login",
      "usernameSelector": "input[name='email']",
      "passwordSelector": "input[name='password']",
      "submitSelector": "button[type='submit']",
      "username": "test@example.com",
      "password": "password123"
    },
    "fuzzingEnabled": true,
    "fuzzingIntensity": "medium"
  }
}
```