docs: enterprise refactor plan with ralph specs

.ralph/specs/legacy/exploration-config.md

@@ -0,0 +1,84 @@
+# 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"
+  }
+}
+```