@reclaimprotocol/agent 0.1.1-dev.1 → 0.1.2

package/src/cdp/capture.ts

@@ -1,213 +1,53 @@
+/**
+ * Local-CDP transport for the capture engine. Binds the page-level `Network.*`
+ * events directly and fetches bodies via the page's `getResponseBody`. All the
+ * request/response bookkeeping lives in `capture-engine.ts`, shared with the
+ * app's remote-Popcorn transport.
+ */
 import type CDP from 'chrome-remote-interface'
-import type { Protocol } from 'devtools-protocol'
-import { randomUUID } from 'node:crypto'
-import { extractGraphqlOp } from '../provider/graphql.ts'
-import type { CapturedRequest } from '../provider/schema.ts'
-import { BodyStore } from './eviction.ts'
+import {
+	type CaptureSession,
+	createCaptureEngine,
+	type StartCaptureOptions,
+} from './capture-engine.ts'
 
-/** Drop HTTP/2 pseudo-headers (`:authority`, `:method`, `:path`, `:scheme`,
- *  `:status`) from a CDP header map. Chrome emits them on HTTP/2 requests,
- *  but they're a transport-layer abstraction with no place in our domain:
- *  the URL already carries authority/path/scheme, the request object carries
- *  method, and Node's `fetch` (undici) throws on any header starting with
- *  `:`. Stripping at capture time keeps every downstream consumer
- *  (`get_request`, draft, replay, proof) clean by construction. */
-export function stripPseudoHeaders(
-	headers: Protocol.Network.Headers,
-): Record<string, string> {
-	const out: Record<string, string> = {}
-	for(const [k, v] of Object.entries(headers)) {
-		if(!k.startsWith(':')) {
-			out[k] = v
-		}
-	}
-
-	return out
-}
-
-export interface CaptureSession {
-	captureId: string
-	requests: Map<string, CapturedRequest>
-	bodies: BodyStore
-	stop: () => Promise<void>
-}
-
-interface InFlight {
-	requestId: string
-	method: string
-	url: string
-	requestHeaders: Record<string, string>
-	requestBody?: string
-	startedAt: number
-}
-
-export interface StartCaptureOptions {
-	maxBodyBytes?: number
-}
+export { stripPseudoHeaders } from './capture-engine.ts'
+export type { CaptureSession, StartCaptureOptions } from './capture-engine.ts'
 
 export async function startCapture(
 	tab: CDP.Client,
 	opts: StartCaptureOptions = {},
 ): Promise<CaptureSession> {
-	const captureId = randomUUID()
-	const requests = new Map<string, CapturedRequest>()
-	const inFlight = new Map<string, InFlight>()
-	const bodies = new BodyStore({
-		maxBytes: opts.maxBodyBytes ?? 200 * 1024 * 1024,
+	const engine = createCaptureEngine({
+		...(opts.maxBodyBytes !== undefined && { maxBodyBytes: opts.maxBodyBytes }),
+		fetchBody: (requestId) => tab.Network.getResponseBody({ requestId }),
 	})
-	// CDP doesn't guarantee `requestWillBeSent` arrives before
-	// `requestWillBeSentExtraInfo` (same for the response pair). When extra
-	// info lands first, buffer it here and drain on the matching primary
-	// event. Without this, headers (Cookie, Authorization, …) get silently
-	// dropped for any request whose events race in the unlucky order.
-	const pendingRequestExtra = new Map<string, Record<string, string>>()
-	const pendingResponseExtra = new Map<string, Record<string, string>>()
 
 	const { Network } = tab
 	await Network.enable()
 
-	/** Merge extra headers from the ...ExtraInfo events into either the
-	 *  in-flight entry or the finalized captured request, whichever has
-	 *  arrived. If neither exists yet (extra-info-first race), buffer the
-	 *  headers and drain on the matching primary event. */
-	function mergeRequestHeaders(
-		requestId: string,
-		extra: Protocol.Network.Headers,
-	) {
-		const clean = stripPseudoHeaders(extra)
-		const f = inFlight.get(requestId)
-		if(f) {
-			f.requestHeaders = { ...f.requestHeaders, ...clean }
-			return
-		}
-
-		const r = requests.get(requestId)
-		if(r) {
-			r.requestHeaders = { ...r.requestHeaders, ...clean }
-			return
-		}
-
-		const buffered = pendingRequestExtra.get(requestId) ?? {}
-		pendingRequestExtra.set(requestId, { ...buffered, ...clean })
-	}
-
-	function mergeResponseHeaders(
-		requestId: string,
-		extra: Protocol.Network.Headers,
-	) {
-		const clean = stripPseudoHeaders(extra)
-		const r = requests.get(requestId)
-		if(r) {
-			r.responseHeaders = { ...r.responseHeaders, ...clean }
-			return
-		}
-
-		const buffered = pendingResponseExtra.get(requestId) ?? {}
-		pendingResponseExtra.set(requestId, { ...buffered, ...clean })
-	}
-
-	Network.requestWillBeSent(({ requestId, request }) => {
-		const f: InFlight = {
-			requestId,
-			method: request.method,
-			url: request.url,
-			requestHeaders: stripPseudoHeaders(request.headers),
-			startedAt: Date.now(),
-		}
-		if(request.postData !== undefined) {
-			f.requestBody = request.postData
-		}
-
-		// Drain any extra-info that arrived before us.
-		const buffered = pendingRequestExtra.get(requestId)
-		if(buffered) {
-			f.requestHeaders = { ...f.requestHeaders, ...buffered }
-			pendingRequestExtra.delete(requestId)
-		}
-
-		inFlight.set(requestId, f)
-	})
-
+	Network.requestWillBeSent(engine.onRequestWillBeSent)
 	// CDP intentionally omits `Cookie` (and other browser-injected headers)
 	// from `requestWillBeSent.request.headers` for privacy. The real
 	// outgoing headers — including Cookie — arrive on the matching
 	// `requestWillBeSentExtraInfo` event.
 	Network.requestWillBeSentExtraInfo(({ requestId, headers }) => {
-		mergeRequestHeaders(requestId, headers)
+		engine.mergeRequestHeaders(requestId, headers)
 	})
-
-	Network.responseReceived(({ requestId, response }) => {
-		const f = inFlight.get(requestId)
-		if(!f) {
-			return
-		}
-
-		const captured: CapturedRequest = {
-			requestId,
-			method: f.method,
-			url: f.url,
-			status: response.status,
-			contentType: response.mimeType,
-			size: response.encodedDataLength,
-			requestHeaders: f.requestHeaders,
-			responseHeaders: stripPseudoHeaders(response.headers),
-			finishedAt: 0,
-		}
-
-		// Drain any response extra-info that arrived before us.
-		const bufferedResp = pendingResponseExtra.get(requestId)
-		if(bufferedResp) {
-			captured.responseHeaders = {
-				...captured.responseHeaders,
-				...bufferedResp,
-			}
-			pendingResponseExtra.delete(requestId)
-		}
-
-		if(f.requestBody !== undefined) {
-			captured.requestBody = f.requestBody
-		}
-
-		const op = extractGraphqlOp(f.requestBody)
-		if(op !== undefined) {
-			captured.graphqlOp = op
-		}
-
-		requests.set(requestId, captured)
-	})
-
+	Network.responseReceived(engine.onResponseReceived)
 	// Same privacy carve-out applies to `Set-Cookie` and other browser-
 	// visible response headers; they arrive on responseReceivedExtraInfo.
 	Network.responseReceivedExtraInfo(({ requestId, headers }) => {
-		mergeResponseHeaders(requestId, headers)
+		engine.mergeResponseHeaders(requestId, headers)
 	})
-
-	Network.loadingFinished(async({ requestId }) => {
-		const r = requests.get(requestId)
-		if(!r) {
-			return
-		}
-
-		try {
-			const { body, base64Encoded } = await Network.getResponseBody({
-				requestId,
-			})
-			const text = base64Encoded
-				? Buffer.from(body, 'base64').toString('utf8')
-				: body
-			bodies.set(requestId, text)
-			r.responseBody = text
-			r.finishedAt = Date.now()
-		} catch{
-			// Body might be unavailable for
-			// some content-types (e.g. websocket). Skip.
-		}
+	Network.loadingFinished(({ requestId }) => {
+		void engine.onLoadingFinished(requestId)
 	})
 
 	return {
-		captureId,
-		requests,
-		bodies,
+		captureId: engine.captureId,
+		requests: engine.requests,
+		bodies: engine.bodies,
 		stop: async() => {
 			await Network.disable()
 		},

package/src/cdp/index.ts

@@ -0,0 +1,6 @@
+// Capture pipeline shared with the app's remote-Popcorn transport:
+// the transport-agnostic engine, the body store, and the local-CDP
+// `startCapture`. Exposed as `@reclaimprotocol/agent/capture`.
+export * from './capture-engine.ts'
+export { startCapture } from './capture.ts'
+export { BodyStore } from './eviction.ts'

package/src/cdp/launcher.ts

@@ -2,6 +2,7 @@ import { type ChildProcess, spawn } from 'node:child_process'
 import { existsSync, mkdirSync } from 'node:fs'
 import { homedir, platform } from 'node:os'
 import { join } from 'node:path'
+import { chromePath, localAppData } from '../consts.ts'
 import { reclaimHomeDirPath } from '../paths.ts'
 
 export interface LaunchOptions {
@@ -38,14 +39,14 @@ function browserCandidates(): string[] {
 			'/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
 		]
 	case 'win32': {
-		const localAppData =
-				process.env['LOCALAPPDATA'] ?? join(homedir(), 'AppData', 'Local')
+		const appData =
+				localAppData() ?? join(homedir(), 'AppData', 'Local')
 		return [
 			// System-wide Chrome
 			'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
 			'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
 			// Per-user Chrome ("Install for me only")
-			join(localAppData, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+			join(appData, 'Google', 'Chrome', 'Application', 'chrome.exe'),
 			// Edge — Chromium-based, preinstalled on Win 10/11
 			'C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe',
 			'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
@@ -87,7 +88,7 @@ export function findChromeBinary(): string {
 }
 
 export function launchChrome(opts: LaunchOptions): ChildProcess {
-	const binary = process.env.RECLAIM_AGENT_CHROME_PATH ?? findChromeBinary()
+	const binary = chromePath() ?? findChromeBinary()
 	if(!existsSync(opts.profileDir)) {
 		mkdirSync(opts.profileDir, { recursive: true })
 	}

package/src/config/store.ts

@@ -6,8 +6,7 @@ import {
 	writeFileSync,
 } from 'node:fs'
 import { dirname, join } from 'node:path'
-import type { CachedCredential } from '../mcp/tools/credentials/cache.ts'
-import type { CachedSession } from '../mcp/tools/credentials/session-cache.ts'
+import type { CachedSession } from '../mcp/tools/authenticate/session-cache.ts'
 import type { OldIdentity } from '../old/client.ts'
 import { reclaimHomeDirPath } from '../paths.ts'
 
@@ -20,25 +19,27 @@ export interface ReclaimAgentConfig {
  * The single on-disk document at `~/.reclaim/config.json`. Each top-level
  * key is an independent section owned by a different subsystem:
  *   - `browser_agent` — Chrome attach mode/port (the agent tools)
- *   - `credentials`   — cached app key-pairs (the credential tools)
  *   - `session`       — the auth bearer token (authenticate)
  *   - `old_devtools`  — externally-supplied identity for OLD-devtools mode
  *                       (USE_OLD_DEVTOOLS); independent of `session`'s
  *                       builder token. Deletable with the rest of `src/old/`.
  * Sections are persisted independently via `ConfigStore.write`, which
  * merges rather than replaces, so one subsystem never clobbers another's.
+ *
+ * NOTE: eth proof-owner keys are NOT cached here — they live as PEMs in the
+ * project (see authenticate/eth-key.ts). This config holds no private keys
+ * other than the (short-lived) session bearer token.
  */
 export interface ReclaimConfig {
 	version: 1
 	browser_agent?: ReclaimAgentConfig
-	credentials?: CachedCredential[]
 	session?: CachedSession
 	old_devtools?: OldIdentity
 }
 
 /**
- * Read/write the unified Reclaim config document. The file holds secrets
- * (a bearer token and private keys), so it is always locked to `0600` and
+ * Read/write the unified Reclaim config document. The file holds the
+ * (short-lived) session bearer token, so it is always locked to `0600` and
  * its directory to `0700` — the `~/.ssh` posture. `read()` returns
  * `undefined` when the file is missing or unparseable; callers layer their
  * own validation (token expiry, credential shape) on top.

package/src/consts.ts

@@ -0,0 +1,164 @@
+/**
+ * Centralized environment access for `@reclaimprotocol/agent`.
+ *
+ * This is the ONLY non-test source file under `src/` that reads
+ * `process.env`. Every other module imports a getter from here instead of
+ * touching `process.env` directly.
+ *
+ * Almost everything is exposed as a LAZY GETTER FUNCTION rather than an eager
+ * `const`, on purpose: several tests mutate env at runtime (mcp-credentials
+ * sets/deletes RECLAIM_PRIVATE_KEY / RECLAIM_PRIVATE_KEY_FILE / RECLAIM_HOME;
+ * old-devtools sets/deletes USE_OLD_DEVTOOLS), and most of these vars are read
+ * at call time anyway. An eager const captured at import time would freeze the
+ * value and break those tests. The one eager const that's safe is `LOG_LEVEL`,
+ * which is read once at logger construction.
+ *
+ * Each var's default/fallback literal is co-located with its getter.
+ */
+import { DEFAULT_BASE_URL } from '@reclaimprotocol/client'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { DEFAULT_OLD_API_URL } from './old/client.ts'
+
+// ---------------------------------------------------------------------------
+// Default / fallback literals (used only as env fallbacks).
+// ---------------------------------------------------------------------------
+
+/** Public attestor websocket URL — fallback for `RECLAIM_ATTESTOR_URL`. */
+export const FALLBACK_ATTESTOR_URL = 'wss://attestor.reclaimprotocol.org:444/ws'
+
+/** The devtools dashboard login page — fallback for `RECLAIM_OLD_LOGIN_URL`. */
+export const DEFAULT_LOGIN_URL = 'https://dev.reclaimprotocol.org'
+
+// Re-export the two non-env-fallback defaults so callers can keep importing
+// their URL defaults from a single place if they wish.
+export { DEFAULT_BASE_URL, DEFAULT_OLD_API_URL }
+
+// ---------------------------------------------------------------------------
+// Logging.
+// ---------------------------------------------------------------------------
+
+/** Pino log level. Read once at logger construction, so an eager const is
+ *  safe (no test mutates LOG_LEVEL at runtime). */
+export const LOG_LEVEL = process.env.LOG_LEVEL || 'info'
+
+// ---------------------------------------------------------------------------
+// Paths.
+// ---------------------------------------------------------------------------
+
+/** Reclaim cache directory (`~/.reclaim`). `RECLAIM_HOME` overrides it so
+ *  tests can sandbox writes. */
+export function reclaimHome(): string {
+	return process.env.RECLAIM_HOME || join(homedir(), '.reclaim')
+}
+
+// ---------------------------------------------------------------------------
+// Mode flag.
+// ---------------------------------------------------------------------------
+
+/**
+ * `USE_OLD_DEVTOOLS` — single source of truth for which backend the MCP
+ * server targets. Defaults to OLD devtools while the builder backend is under
+ * development. Builder mode must be opted into EXPLICITLY with
+ * `USE_OLD_DEVTOOLS=false`; anything else keeps old mode on.
+ */
+export function useOldDevtools(): boolean {
+	return (process.env.USE_OLD_DEVTOOLS ?? '').trim().toLowerCase() !== 'false'
+}
+
+// ---------------------------------------------------------------------------
+// Chrome / CDP launcher.
+// ---------------------------------------------------------------------------
+
+/** `%LOCALAPPDATA%` on Windows, used to probe a per-user Chrome install. */
+export function localAppData(): string | undefined {
+	return process.env['LOCALAPPDATA']
+}
+
+/** Explicit Chrome/Edge/Chromium binary path override. */
+export function chromePath(): string | undefined {
+	return process.env.RECLAIM_AGENT_CHROME_PATH
+}
+
+// ---------------------------------------------------------------------------
+// MCP server / API clients.
+// ---------------------------------------------------------------------------
+
+/** Agent tools (Chrome CDP capture, synthesis, proof) are disabled in hosted
+ *  deployments by setting `RECLAIM_AGENT_DISABLED=1`. Shared by mcp/start and
+ *  the old-mode authenticate tool. */
+export function agentDisabled(): boolean {
+	return process.env.RECLAIM_AGENT_DISABLED === '1'
+}
+
+/** Old-devtools backend base URL. */
+export function oldApiUrl(): string {
+	return process.env.RECLAIM_OLD_API_URL || DEFAULT_OLD_API_URL
+}
+
+/** Builder backend base URL. Shared by mcp/start and the verification tool. */
+export function apiUrl(): string {
+	return process.env.RECLAIM_API_URL || DEFAULT_BASE_URL
+}
+
+/** Explicit builder API token (overrides the cached session token). */
+export function apiToken(): string | undefined {
+	return process.env.RECLAIM_API_TOKEN
+}
+
+// ---------------------------------------------------------------------------
+// Proof tracing.
+// ---------------------------------------------------------------------------
+
+/** Diagnostic trace capture (`RECLAIM_AGENT_TRACE=1`). Shared by the attestor
+ *  logger capture and the proof-run dump. */
+export function agentTraceEnabled(): boolean {
+	return process.env['RECLAIM_AGENT_TRACE'] === '1'
+}
+
+/** Attestor websocket URL override (`RECLAIM_ATTESTOR_URL`). */
+export function attestorUrlOverride(): string | undefined {
+	return process.env['RECLAIM_ATTESTOR_URL']
+}
+
+// ---------------------------------------------------------------------------
+// Eth proof-owner key resolution.
+// ---------------------------------------------------------------------------
+
+/** Raw 0x-hex Ethereum private key (`RECLAIM_PRIVATE_KEY`). */
+export function privateKey(): string | undefined {
+	return process.env.RECLAIM_PRIVATE_KEY
+}
+
+/** Path to a raw-hex key file (`RECLAIM_PRIVATE_KEY_FILE`). */
+export function privateKeyFile(): string | undefined {
+	return process.env.RECLAIM_PRIVATE_KEY_FILE
+}
+
+// ---------------------------------------------------------------------------
+// Verification reads.
+// ---------------------------------------------------------------------------
+
+/** Per-org bearer secret (`rorg_…`) used to authenticate verification reads. */
+export function orgSecret(): string | undefined {
+	return process.env.RECLAIM_ORG_SECRET
+}
+
+// ---------------------------------------------------------------------------
+// Old-devtools identity / login.
+// ---------------------------------------------------------------------------
+
+/** Dashboard Firebase bearer token for the old backend. */
+export function oldApiToken(): string | undefined {
+	return process.env.RECLAIM_OLD_API_TOKEN
+}
+
+/** An `eth:<addr>` (or bare `0x…`) uid for the old backend. */
+export function oldEthUid(): string | undefined {
+	return process.env.RECLAIM_OLD_ETH_UID
+}
+
+/** Override for the old-devtools dashboard login URL. */
+export function oldLoginUrl(): string | undefined {
+	return process.env.RECLAIM_OLD_LOGIN_URL
+}

package/src/index.ts

@@ -6,7 +6,5 @@
 export * from '@reclaimprotocol/client'
 
 // Agent — Chrome CDP capture, provider synthesis, replay, proof.
-export {
-	buildAgentTools,
-} from './mcp/tools/agent/build.ts'
-export type { AgentState } from './mcp/tools/agent/build.ts'
+export { buildAgentTools } from './mcp/tools/agent/index.ts'
+export type { AgentState } from './mcp/tools/agent/index.ts'

package/src/logger.ts

@@ -1,8 +1,9 @@
 import pino, { stdTimeFunctions } from 'pino'
+import { LOG_LEVEL } from './consts.ts'
 
 export const LOGGER = pino({
 	name: '@reclaimprotocol/agent',
 	timestamp: stdTimeFunctions.isoTime,
 	base: { hostname: undefined, pid: undefined },
 })
-LOGGER.level = process.env.LOG_LEVEL || 'info'
+LOGGER.level = LOG_LEVEL