@reclaimprotocol/agent 0.1.0 → 0.1.1

package/README.md

@@ -188,7 +188,7 @@ The MCP server targets one of two backends, selected by `USE_OLD_DEVTOOLS`:
   - `reclaim_authenticate` — by default opens the dashboard in Chrome via CDP, waits for sign-in, reads the Firebase token from page storage, and closes the tab (or pass a `token` / `ethAddress` to skip the browser).
   - `create_provider_version_from_capture` — registers a new provider, or adds a version to an existing one when given a `providerId`.
   - `get_me_providers` — list the providers you own (the only provider-listing tool in this mode).
-- **Builder (`USE_OLD_DEVTOOLS=false`).** Registers the auto-generated HTTP-API tools plus the builder credential tools (`reclaim_authenticate` device-code flow, `reclaim_status`, and the local credential tools).
+- **Builder (`USE_OLD_DEVTOOLS=false`).** Registers the auto-generated HTTP-API tools plus the authentication/credential tools (`authenticate` device-pairing login, `issue_credentials` / `import_credentials` to set up the local eth proof-owner key, `resolve_owner_key`) and a verification-result helper (`get_verification_result`).
 
 Relevant env vars: `RECLAIM_OLD_API_URL` (default `https://devapi.reclaimprotocol.org`), `RECLAIM_OLD_API_TOKEN` / `RECLAIM_OLD_ETH_UID` (headless identity), `RECLAIM_OLD_LOGIN_URL` (default `https://dev.reclaimprotocol.org`); builder mode uses `RECLAIM_API_URL` / `RECLAIM_API_TOKEN`.
 

package/lib/cdp/capture-engine.d.ts

@@ -0,0 +1,66 @@
+import type { CapturedRequest } from '../provider/schema.ts';
+import { BodyStore } from './eviction.ts';
+/** The slice of CDP `Network.requestWillBeSent` the engine reads. Kept
+ *  structural — not devtools-protocol's full event type — so a transport
+ *  pinned to a different devtools-protocol version still satisfies it. */
+export interface RequestWillBeSentLike {
+    requestId: string;
+    request: {
+        method: string;
+        url: string;
+        headers: Record<string, string>;
+        postData?: string;
+    };
+}
+/** The slice of CDP `Network.responseReceived` the engine reads. */
+export interface ResponseReceivedLike {
+    requestId: string;
+    response: {
+        status: number;
+        mimeType: string;
+        encodedDataLength: number;
+        headers: Record<string, string>;
+    };
+}
+/** 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 declare function stripPseudoHeaders(headers: Record<string, string>): Record<string, string>;
+export interface CaptureSession {
+    captureId: string;
+    requests: Map<string, CapturedRequest>;
+    bodies: BodyStore;
+    stop: () => Promise<void>;
+}
+/** Public knobs a transport accepts; mapped into `CaptureEngineOptions`. */
+export interface StartCaptureOptions {
+    maxBodyBytes?: number;
+}
+export interface CaptureEngineOptions {
+    maxBodyBytes?: number;
+    /** Fetch a finished response body. Transport-specific: the agent calls
+     *  `Network.getResponseBody` on the page binding, the app routes the
+     *  command through its Popcorn session. */
+    fetchBody: (requestId: string) => Promise<{
+        body: string;
+        base64Encoded: boolean;
+    }>;
+}
+/** The engine state plus the handlers a transport drives. A transport feeds
+ *  raw CDP events into these and exposes `captureId`/`requests`/`bodies` to
+ *  its caller. */
+export interface CaptureEngine {
+    captureId: string;
+    requests: Map<string, CapturedRequest>;
+    bodies: BodyStore;
+    onRequestWillBeSent: (p: RequestWillBeSentLike) => void;
+    mergeRequestHeaders: (requestId: string, extra: Record<string, string>) => void;
+    onResponseReceived: (p: ResponseReceivedLike) => void;
+    mergeResponseHeaders: (requestId: string, extra: Record<string, string>) => void;
+    onLoadingFinished: (requestId: string) => Promise<void>;
+}
+export declare function createCaptureEngine(opts: CaptureEngineOptions): CaptureEngine;

package/lib/cdp/capture-engine.js

@@ -0,0 +1,153 @@
+/**
+ * Transport-agnostic CDP Network → CapturedRequest state machine. The agent
+ * (local CDP, page-level `Network.*` bindings) and the app (remote Popcorn,
+ * events read off a session-filtered `event` stream) share this entire engine;
+ * only how events are delivered and how a response body is fetched differ, so
+ * those two are injected. See `cdp/capture.ts` and the app's
+ * `capture/capture.ts` for the two thin transports that wire into it.
+ */
+import { randomUUID } from 'node:crypto';
+import { extractGraphqlOp } from "../provider/graphql.js";
+import { BodyStore } from "./eviction.js";
+/** 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) {
+    const out = {};
+    for (const [k, v] of Object.entries(headers)) {
+        if (!k.startsWith(':')) {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+export function createCaptureEngine(opts) {
+    const captureId = randomUUID();
+    const requests = new Map();
+    const inFlight = new Map();
+    const bodies = new BodyStore({
+        maxBytes: opts.maxBodyBytes ?? 200 * 1024 * 1024,
+    });
+    // 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();
+    const pendingResponseExtra = new Map();
+    return {
+        captureId,
+        requests,
+        bodies,
+        onRequestWillBeSent,
+        mergeRequestHeaders,
+        onResponseReceived,
+        mergeResponseHeaders,
+        onLoadingFinished,
+    };
+    /** 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, extra) {
+        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, extra) {
+        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 });
+    }
+    function onRequestWillBeSent(p) {
+        const f = {
+            requestId: p.requestId,
+            method: p.request.method,
+            url: p.request.url,
+            requestHeaders: stripPseudoHeaders(p.request.headers),
+            startedAt: Date.now(),
+        };
+        if (p.request.postData !== undefined) {
+            f.requestBody = p.request.postData;
+        }
+        // Drain any extra-info that arrived before us.
+        const buffered = pendingRequestExtra.get(p.requestId);
+        if (buffered) {
+            f.requestHeaders = { ...f.requestHeaders, ...buffered };
+            pendingRequestExtra.delete(p.requestId);
+        }
+        inFlight.set(p.requestId, f);
+    }
+    function onResponseReceived(p) {
+        const f = inFlight.get(p.requestId);
+        if (!f) {
+            return;
+        }
+        const captured = {
+            requestId: p.requestId,
+            method: f.method,
+            url: f.url,
+            status: p.response.status,
+            contentType: p.response.mimeType,
+            size: p.response.encodedDataLength,
+            requestHeaders: f.requestHeaders,
+            responseHeaders: stripPseudoHeaders(p.response.headers),
+            finishedAt: 0,
+        };
+        // Drain any response extra-info that arrived before us.
+        const bufferedResp = pendingResponseExtra.get(p.requestId);
+        if (bufferedResp) {
+            captured.responseHeaders = {
+                ...captured.responseHeaders,
+                ...bufferedResp,
+            };
+            pendingResponseExtra.delete(p.requestId);
+        }
+        if (f.requestBody !== undefined) {
+            captured.requestBody = f.requestBody;
+        }
+        const op = extractGraphqlOp(f.requestBody);
+        if (op !== undefined) {
+            captured.graphqlOp = op;
+        }
+        requests.set(p.requestId, captured);
+    }
+    async function onLoadingFinished(requestId) {
+        const r = requests.get(requestId);
+        if (!r) {
+            return;
+        }
+        try {
+            const { body, base64Encoded } = await opts.fetchBody(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.
+        }
+    }
+}

package/lib/cdp/capture.d.ts

@@ -1,22 +1,11 @@
+/**
+ * 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 type { CapturedRequest } from '../provider/schema.ts';
-import { BodyStore } from './eviction.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 declare function stripPseudoHeaders(headers: Protocol.Network.Headers): Record<string, string>;
-export interface CaptureSession {
-    captureId: string;
-    requests: Map<string, CapturedRequest>;
-    bodies: BodyStore;
-    stop: () => Promise<void>;
-}
-export interface StartCaptureOptions {
-    maxBodyBytes?: number;
-}
+import { type CaptureSession, type StartCaptureOptions } from './capture-engine.ts';
+export { stripPseudoHeaders } from './capture-engine.ts';
+export type { CaptureSession, StartCaptureOptions } from './capture-engine.ts';
 export declare function startCapture(tab: CDP.Client, opts?: StartCaptureOptions): Promise<CaptureSession>;

package/lib/cdp/capture.js

@@ -1,157 +1,33 @@
-import { randomUUID } from 'node:crypto';
-import { extractGraphqlOp } from "../provider/graphql.js";
-import { BodyStore } from "./eviction.js";
-/** 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) {
-    const out = {};
-    for (const [k, v] of Object.entries(headers)) {
-        if (!k.startsWith(':')) {
-            out[k] = v;
-        }
-    }
-    return out;
-}
+import { createCaptureEngine, } from "./capture-engine.js";
+export { stripPseudoHeaders } from "./capture-engine.js";
 export async function startCapture(tab, opts = {}) {
-    const captureId = randomUUID();
-    const requests = new Map();
-    const inFlight = new Map();
-    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();
-    const pendingResponseExtra = new Map();
     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, extra) {
-        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, extra) {
-        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 = {
-            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);
-    });
-    Network.responseReceived(({ requestId, response }) => {
-        const f = inFlight.get(requestId);
-        if (!f) {
-            return;
-        }
-        const captured = {
-            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);
+        engine.mergeRequestHeaders(requestId, headers);
     });
+    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/lib/cdp/index.d.ts

@@ -0,0 +1,3 @@
+export * from './capture-engine.ts';
+export { startCapture } from './capture.ts';
+export { BodyStore } from './eviction.ts';

package/lib/cdp/index.js

@@ -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.js";
+export { startCapture } from "./capture.js";
+export { BodyStore } from "./eviction.js";

package/lib/config/store.d.ts

@@ -1,5 +1,4 @@
-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';
 export interface ReclaimAgentConfig {
     attachMode: 'dedicated' | 'attach';
@@ -9,24 +8,26 @@ 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/lib/config/store.js

@@ -2,8 +2,8 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from '
 import { dirname, join } from 'node:path';
 import { reclaimHomeDirPath } from "../paths.js";
 /**
- * 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/lib/index.d.ts

@@ -1,3 +1,3 @@
 export * from '@reclaimprotocol/client';
-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/lib/index.js

@@ -4,4 +4,4 @@
 // only need one package for both the typed HTTP client and the agent tools.
 export * from '@reclaimprotocol/client';
 // Agent — Chrome CDP capture, provider synthesis, replay, proof.
-export { buildAgentTools, } from "./mcp/tools/agent/build.js";
+export { buildAgentTools } from "./mcp/tools/agent/index.js";