@alsania-io/browser-capture

Real-Chrome CDP driver + XHR/fetch capture + OpenAPI 3.0 exporter for Alsania agents.

Extracted from: extrApi by Youssef Kritet.

⚠️ License note: The upstream source declares "license": "MIT" in package.json and the README, but no LICENSE file was present in the source tree. We treat this as MIT with attribution. If the Alsania project needs an ironclad license, we should reimplement from scratch using this code as reference (see the deep-dive notes), or contact the author to confirm MIT grant.

What it does

Open a real, already-installed browser, log in manually, and record all XHR/fetch API traffic as you use a web app. Export a complete OpenAPI 3.0 spec plus LLM-callable tool definitions. Extract the session token (Bearer / cookies / auth localStorage) so you can drive that API headlessly afterward.

Backends

• CDP (default): drives an existing Chrome/Chromium/Brave/Edge binary via raw Chrome DevTools Protocol over WebSocket. No bundled Chromium. Lightweight and Alsania-Code-compatible.
• Playwright (fallback, optional): same interface, using playwright's bundled Chromium. Install separately with make install-playwright.

Backend swap is a source-level import change (see src/index.ts).

Session interface (shared)

openSession / navigate / click / fill / pressKey / getSnapshot / startCapture / stopCapture / extractSession / closeSession

Security model

Inherited from upstream and to be extended:

• findChrome() uses a fixed allowlist of standard install paths — no arbitrary binary is launched.
• validateUrl() restricts open_session/navigate to http:/https: (blocks file:, javascript:, data:).
• CDP debug port always bound to 127.0.0.1, random private-range port.
• Chrome runs against a throwaway --user-data-dir — never your real profile.
• Locator strings and fill values escaped via JSON.stringify before evaluation.
• Spawned Chrome child is non-detached — dies with the MCP server.

Alsania additions (TODO)

• src/security/domain-allowlist.ts — restrict outbound navigation to approved domains per session.
• src/security/token-vault.ts — encrypt extracted tokens at rest if persisted (AES-GCM-256).

Usage

make install
make build
make test

License

MIT (assumed). Upstream author: Youssef Kritet. See README.original.md for the original documentation.