@reclaimprotocol/agent 0.1.23 → 0.1.25

package/skill/user-script.md

@@ -0,0 +1,61 @@
+# User scripts (`jsUserScripts` / `customInjection`)
+
+A provider can inject **plain JavaScript** that runs in the page before every
+page load. Builder stores it as `webSettings.jsUserScripts`; old-devtools stores
+it as `customInjection`. Identical semantics, different field name.
+
+## What the script is for
+
+The verification client **already intercepts the page's network requests
+automatically** — the script does not need to capture, forward, or "claim" them.
+Its job is to get the page into the state where the target request happens,
+using standard browser APIs:
+
+- **Navigate** — `window.location.href = '…'`, `location.assign(…)`, the
+  history API.
+- **Interact** — select an element and `.click()` it, submit a form, dispatch
+  events.
+- **Wait** — poll the DOM until login/MFA completes or content loads, then
+  trigger the next step.
+
+Write it like any page script. It runs before EVERY page load, so keep it
+idempotent, cheap, and guarded against firing at the wrong time.
+
+Both backends run it the same way: before every page load, including before the
+first navigation to `initialUrl`/`loginUrl`.
+
+## `window.Reclaim` — rarely needed
+
+`window.Reclaim` is an OPTIONAL bridge for a handful of edge cases. Most
+providers never touch it, and **it does not do navigation** — use the standard
+browser APIs above for that.
+
+**On the Builder verification client it is installed but INERT.** Both
+`window.Reclaim` and `window.reclaimInterceptor` are injected before every
+document load, so a call won't throw — but the run never drains the
+`Reclaim` outbox and never delivers traffic to
+`reclaimInterceptor.addResponseMiddleware`, so nothing you send is acted on
+and no middleware ever fires. Write Builder-targeted scripts in plain browser
+JS unconditionally, and let the capture loop find the request itself.
+
+Don't reach for it by default. When an edge case genuinely requires it, consult
+the authoritative API surface rather than guessing:
+<https://github.com/reclaimprotocol/provider-web-script-dev/blob/main/src/support/env.d.ts>
+
+## Declaring the requests the script fires
+
+Requests the script triggers beyond the proven one (for example, pagination) are
+declared as `allowedJsRequests` (Builder) / `allowedInjectedRequestData`
+(old-devtools). Same concept, different field name.
+
+⚠️ **Before populating them to gate `verifyProof(proof, { providerId })`**, read
+topic `hash-validation` — the declared `url` is hashed VERBATIM, so a
+session-unique URL there makes `verifyProof` reject every real proof. Leaving
+the field empty is better than populating it wrong.
+
+## Related topics
+
+- `interception` — `injectionType`/`interceptorType`, live interception, and the
+  document-replay flag.
+- `hash-validation` — `bodySniff`, and how `verifyProof({ providerId })` gates
+  on the provider's declared spec.

package/src/authoring/backend.ts

@@ -85,9 +85,10 @@ export interface AuthoringBackend {
 	/** This session's drafts (propose → replay/run_proof). */
 	readonly drafts: DraftStore
 	/** Prove a drafted recipe. Local: attestor SDK (rich claim view). Remote: TEE
-	 *  `/reclaim/prove` (lean, secret-free summary). Returns the environment's
-	 *  display shape. A backend may record the proven recipe internally (e.g.
-	 *  the cloud publish step) — that side effect is the backend's, not ours. */
+	 * `/reclaim/prove` (lean, secret-free summary). Returns the environment's
+	 * display shape. A backend may record the proven recipe internally (for
+	 * example, the cloud publish step) — that side effect is the backend's, not
+	 * ours. */
 	prove(draft: Draft, opts?: ProveOptions): Promise<unknown>
 	/**
 	 * Validate/replay a drafted recipe before proving. Both local and remote
@@ -96,7 +97,7 @@ export interface AuthoringBackend {
 	 * always reflects the real browser session. With `withoutSecrets` it is
 	 * the AUTH-BOUND check: re-issue anonymously (`credentials: 'omit'`, no
 	 * secret headers) and report whether the values are STILL extractable —
-	 * i.e. the endpoint is public. Without it, validate extraction for the
+	 * that is, the endpoint is public. Without it, validate extraction for the
 	 * authenticated request. The shape is environment-specific and passed
 	 * straight through as the tool's result.
 	 */

package/src/authoring/tools.ts

@@ -116,7 +116,10 @@ export function authoringTools(
 		defineTool<Record<string, unknown>>(
 			{
 				name: 'navigate',
-				description: 'Navigate the browser tab to a URL, waiting for load.',
+				description:
+					'Navigate the captured tab to a URL and wait for its load event. '
+					+ 'Returns the URL the tab actually landed on, so you can detect a '
+					+ 'redirect to a login page.',
 				inputSchema: objectSchema(
 					{ url: { type: 'string' }, timeoutMs: { type: 'number' } },
 					['url'],
@@ -144,8 +147,10 @@ export function authoringTools(
 			{
 				name: 'eval_in_page',
 				description:
-					'Evaluate a JavaScript expression in the page and return its value '
-					+ '(use to read the displayed value, check login state, etc.).',
+					'Evaluate a JavaScript expression in the page and return its value. '
+					+ 'Use it to read the value being proven out of the DOM, to check '
+					+ 'login state, or to trigger the target request (for example, '
+					+ '`location.reload()`).',
 				inputSchema: objectSchema(
 					{ expression: { type: 'string' } }, ['expression'],
 				),
@@ -156,8 +161,10 @@ export function authoringTools(
 			{
 				name: 'wait_for_page',
 				description:
-					'Poll a JavaScript expression until it is truthy or the timeout '
-					+ 'elapses (e.g. wait for the user to finish logging in).',
+					'Poll a JavaScript expression once a second until it is truthy or '
+					+ 'the timeout elapses. Use it to wait for content to appear. To '
+					+ 'wait for a login, use wait_for_login instead — page JavaScript '
+					+ 'cannot see the httpOnly session cookie.',
 				inputSchema: objectSchema(
 					{ expression: { type: 'string' }, timeoutMs: { type: 'number' } },
 					['expression'],
@@ -183,26 +190,18 @@ export function authoringTools(
 			{
 				name: 'test_user_script',
 				description:
-					'Dry-run a USER SCRIPT — the same thing as the `jsUserScripts` / '
-					+ '`customInjection` field on a published provider: plain browser '
-					+ 'JS that runs before every page load, used to drive navigation '
-					+ 'for data gated behind login/routing — in the LIVE attached tab, '
-					+ 'BEFORE publishing. Installs `script` via CDP so it runs on the '
-					+ 'next navigation exactly like the real field would, then reports '
-					+ 'whether it ran and any errors it threw. Catches bugs (e.g. a '
-					+ 'listener registered with setTimeout that never fires because the '
-					+ "page was already past 'load' by the time it ran) before they "
-					+ 'surface in a real end-user session instead of after. If '
-					+ '`navigateUrl` is given, navigates there after installing, then '
-					+ 'removes the script again once the result is read (self-cleaning '
-					+ '— safe to call repeatedly). Without `navigateUrl` the script is '
-					+ 'left installed for you to navigate yourself (any way you like) '
-					+ 'then re-call this tool, or read '
-					+ '`window.__reclaimUserScriptResult` via eval_in_page — in that '
-					+ 'manual mode it is NOT auto-removed and keeps running on every '
-					+ 'later navigation until a follow-up call with `navigateUrl` '
-					+ 'removes it, so avoid stacking several manual-mode calls in a '
-					+ 'row.',
+					'Dry-run a USER SCRIPT (the `jsUserScripts` / `customInjection` '
+					+ 'field) in the LIVE attached tab, BEFORE publishing. Installs '
+					+ '`script` via CDP so it runs on the next navigation exactly as '
+					+ 'the real field would, then reports whether it ran and what it '
+					+ 'threw. With `navigateUrl`, it navigates there and removes the '
+					+ 'script once the result is read — self-cleaning, safe to repeat. '
+					+ 'WITHOUT `navigateUrl` the script stays installed (navigate '
+					+ 'yourself, then re-call this tool or read '
+					+ '`window.__reclaimUserScriptResult` via eval_in_page) and keeps '
+					+ 'running on every later navigation until a call WITH '
+					+ '`navigateUrl` removes it — so don\'t stack manual-mode calls. '
+					+ 'Guide: how_it_works({ topic: "user-script" }).',
 				inputSchema: objectSchema(
 					{
 						script: { type: 'string' },
@@ -246,8 +245,9 @@ export function authoringTools(
 							'Installed for the NEXT navigation only — it did not run on '
 							+ 'the current page, and stays installed (runs on every later '
 							+ 'navigation too) until a follow-up call with navigateUrl '
-							+ 'removes it. Navigate now (e.g. the navigate tool), then read '
-							+ 'window.__reclaimUserScriptResult via eval_in_page, or call '
+							+ 'removes it. Navigate now (for example, with the navigate '
+							+ 'tool), then read window.__reclaimUserScriptResult via '
+							+ 'eval_in_page, or call '
 							+ 'test_user_script again with navigateUrl.',
 					}
 				}
@@ -298,7 +298,8 @@ export function authoringTools(
 					'List the NAMES of cookies currently set for the page (values are '
 					+ 'NEVER returned). The most reliable, language- and DOM-independent '
 					+ 'login signal: after the user logs in, an auth/session cookie '
-					+ 'appears (e.g. session/sid/token/auth/jwt/_user/logged_in). '
+					+ 'appears (for example, session, sid, token, auth, jwt, _user, '
+					+ 'logged_in). '
 					+ 'Includes httpOnly cookies the page JS cannot see.',
 				inputSchema: objectSchema({}),
 			},
@@ -354,8 +355,8 @@ export function authoringTools(
 					'userFirstVisit', 'cf_', '_dd_', 'bcookie', 'bscookie', 'lidc',
 				].join('|') + ')', 'i')
 				// A real session/auth cookie name. Deliberately NOT bare `token` — a
-				// challenge/CSRF token (e.g. LinkedIn `chp_token`) contains it and is
-				// set BEFORE auth completes. Any new httpOnly cookie is also a
+				// challenge/CSRF token (for example, LinkedIn `chp_token`) contains it
+				// and is set BEFORE auth completes. Any new httpOnly cookie is also a
 				// candidate (server-set session cookies are usually httpOnly).
 				const SESSION = /sess|sid|jwt|_session|auth|logged.?in|remember|li_at/i
 				// Auth/challenge URL paths — while the page is still on one, login is

package/src/cdp/capture-engine.ts

@@ -89,9 +89,10 @@ export function isStaticAsset(url: string): boolean {
 }
 
 /** Response Content-Types for static assets. The URL-extension filter misses
- *  extension-less bundler/CDN URLs (e.g. `/assets/3b8f1c`), so we also drop by
- *  MIME at response time. `text/html`, `application/json`, and `text/plain`
- *  are NOT here — those are the document/API shapes recipes match. */
+ *  extension-less bundler/CDN URLs (for example, `/assets/3b8f1c`), so we also
+ *  drop by MIME at response time. `text/html`, `application/json`, and
+ *  `text/plain` are NOT here — those are the document/API shapes recipes
+ *  match. */
 const STATIC_ASSET_MIME_EXACT = new Set([
 	'text/css',
 	'application/javascript', 'text/javascript', 'application/x-javascript',
@@ -272,9 +273,9 @@ export function createCaptureEngine(opts: CaptureEngineOptions): CaptureEngine {
 	function onResponseReceived(p: ResponseReceivedLike) {
 		const f = inFlight.get(p.requestId)
 		if(!f) {
-			// No in-flight entry → the request was skipped (e.g. a static asset)
-			// or never seen. Discard any buffered response extra-info so a skipped
-			// asset can't leave a dangling entry.
+			// No in-flight entry → the request was skipped (for example, a static
+			// asset) or never seen. Discard any buffered response extra-info so a
+			// skipped asset can't leave a dangling entry.
 			pendingResponseExtra.delete(p.requestId)
 			return
 		}
@@ -339,7 +340,7 @@ export function createCaptureEngine(opts: CaptureEngineOptions): CaptureEngine {
 			r.finishedAt = Date.now()
 		} catch{
 			// Body might be unavailable for
-			// some content-types (e.g. websocket). Skip.
+			// some content-types (for example, websocket). Skip.
 		}
 	}
 }

package/src/cdp/claims.ts

@@ -0,0 +1,153 @@
+/**
+ * Which sessions are using which browser container.
+ *
+ * A container is worth sharing: about 2 GB of RAM and 7 to 17 seconds to start,
+ * so a developer running one session after another should get the same one back
+ * rather than pay for a new one each time.
+ *
+ * It can only be shared SEQUENTIALLY, and the profile is why. Every container
+ * mounts a host directory as Chromium's `user-data-dir`, and the runtime
+ * deletes `SingletonLock` on boot — so a second container on the same profile
+ * is a second writer on one cookie jar. Chromium does not support that, and the
+ * failure is silent corruption of the thing most worth keeping: the login.
+ *
+ * So each container gets a SLOT. A slot has one profile and at most one live
+ * claimant. A session adopts the first slot nobody holds; when the last claim
+ * on a slot goes, the container stops.
+ *
+ * State lives in a file because each MCP session is its own OS process, with
+ * no shared memory to count in. Claims are process ids, and liveness is a
+ * signal-0 check — the same test the orphan reaper uses. It fails the harmless
+ * way: a recycled pid keeps a container alive rather than pulling one out from
+ * under a running session.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { LOGGER } from '../logger.ts'
+import { reclaimHomeDirPath } from '../paths.ts'
+
+/**
+ * Slot → the claim tokens currently held on it.
+ *
+ * A token is `<pid>.<n>`, not a bare pid, because one session can legitimately
+ * hold a slot twice: re-attaching adopts the container it is already running,
+ * and for a moment both the new handle and the old one are outstanding. With
+ * bare pids those two collapse into one entry, so releasing the OLD handle
+ * stops the container the new one just adopted. The `<n>` keeps them distinct;
+ * the `<pid>` is what liveness is checked against.
+ */
+type ClaimFile = Record<string, string[]>
+
+/** Distinguishes claims made by this same process. */
+let claimSeq = 0
+
+/** The pid a token belongs to, or 0 when it is malformed. */
+function tokenPid(token: string): number {
+	const pid = Number(token.split('.')[0])
+	return Number.isInteger(pid) ? pid : 0
+}
+
+function claimsPath(): string {
+	return join(reclaimHomeDirPath(), 'browser-runtime-claims.json')
+}
+
+function read(): ClaimFile {
+	try {
+		const parsed = JSON.parse(readFileSync(claimsPath(), 'utf8')) as ClaimFile
+		// Drop claims whose process is gone: that is what makes a slot free again
+		// after a session was killed without cleaning up.
+		const live: ClaimFile = {}
+		for(const [slot, tokens] of Object.entries(parsed)) {
+			const alive = (Array.isArray(tokens) ? tokens : [])
+				.filter((token) => processAlive(tokenPid(token)))
+			if(alive.length) {
+				live[slot] = alive
+			}
+		}
+
+		return live
+	} catch{
+		// Missing or unreadable: nobody has claimed anything.
+		return {}
+	}
+}
+
+function write(claims: ClaimFile): void {
+	const path = claimsPath()
+	mkdirSync(dirname(path), { recursive: true })
+	// Write then rename, so a reader never sees a half-written file. Two sessions
+	// racing here means last-writer-wins on a file that is pruned on every read,
+	// which costs at most one redundant container.
+	const temp = `${path}.${process.pid}.tmp`
+	writeFileSync(temp, `${JSON.stringify(claims, null, '\t')}\n`)
+	renameSync(temp, path)
+}
+
+/** Whether a process is still running. Signal 0 checks without delivering. */
+export function processAlive(pid: number): boolean {
+	if(!Number.isInteger(pid) || pid <= 0) {
+		return false
+	}
+
+	try {
+		process.kill(pid, 0)
+		return true
+	} catch(err) {
+		// EPERM means it exists but belongs to another user — alive either way.
+		return (err as NodeJS.ErrnoException).code === 'EPERM'
+	}
+}
+
+/** Slots with at least one live claimant, so a caller can avoid them. */
+export function busySlots(): Set<string> {
+	return new Set(Object.keys(read()))
+}
+
+/**
+ * Slots THIS process already holds.
+ *
+ * Its own claim must not push it onto a new slot: re-attaching in one session
+ * should come back to the browser it is already running, not start a second.
+ */
+export function ownSlots(): Set<string> {
+	const mine = new Set<string>()
+	for(const [slot, tokens] of Object.entries(read())) {
+		if(tokens.some((token) => tokenPid(token) === process.pid)) {
+			mine.add(slot)
+		}
+	}
+
+	return mine
+}
+
+/** Take a claim on `slot`. Returns the token to release it with. */
+export function claim(slot: string): string {
+	const token = `${process.pid}.${++claimSeq}`
+	const claims = read()
+	claims[slot] = [...claims[slot] ?? [], token]
+	write(claims)
+	LOGGER.debug({ slot, held: claims[slot] }, 'claimed a browser slot')
+	return token
+}
+
+/**
+ * Give up this process's claim.
+ *
+ * Returns true when nobody is left, which is the caller's signal to stop the
+ * container. Returns false while another live session still holds it — stopping
+ * then would pull the browser out from under them.
+ */
+export function release(slot: string, token: string): boolean {
+	const claims = read()
+	const remaining = (claims[slot] ?? []).filter((held) => held !== token)
+	if(remaining.length) {
+		claims[slot] = remaining
+		write(claims)
+		LOGGER.debug({ slot, remaining }, 'released a claim; others still hold it')
+		return false
+	}
+
+	delete claims[slot]
+	write(claims)
+	return true
+}