@reclaimprotocol/agent 0.1.4 → 0.1.6

package/src/old/tools/publish.ts

@@ -1,14 +1,18 @@
 import { Boom, isBoom } from '@hapi/boom'
 import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
+import { INJECTION_GUIDE } from '../../provider/injection-doc.ts'
 import {
 	countsFor,
 	matchRedactionWarnings,
 } from '../../provider/match-redaction-warning.ts'
 import type { ReclaimProvider } from '../../provider/schema.ts'
+import type { AllowedJsRequest } from '../../provider/to-version.ts'
 import type { ReclaimOldClient } from '../client.ts'
 import {
 	bumpPatchString,
 	extractVersions,
+	injectedRequestDataFrom,
+	type OldInjectedRequestData,
 	type OldProviderOpts,
 	providerToConfigBody,
 	providerToRegisterBody,
@@ -16,6 +20,56 @@ import {
 
 const DEFAULT_VERSION_INFO = 'Updated from MCP browser capture'
 
+/** Fields with no partial-patch equivalent on this backend: a version always
+ *  replaces the WHOLE `providerConfig`, so omitting one of these on
+ *  add-version must carry forward the current value rather than publish it
+ *  blank. `allowedInjectedRequestData` is handled alongside these (see
+ *  `resolveInjectedRequests`) since it needs translation when freshly
+ *  authored, unlike these — which pass through unchanged either way. */
+const PRESERVABLE_KEYS = [
+	'customInjection',
+	'userAgent',
+	'pageTitle',
+	'stepsToFollow',
+	'useIncognitoWebview',
+	'extensionConfig',
+] as const
+
+/** Pull `providerConfig` out of a `get_provider_version_config` /
+ *  `getProviderConfig` response, tolerant of a missing/malformed shape. */
+function extractProviderConfig(
+	resp: unknown,
+): Record<string, unknown> | undefined {
+	if(resp && typeof resp === 'object') {
+		const cfg = (resp as { providerConfig?: unknown }).providerConfig
+		if(cfg && typeof cfg === 'object') {
+			return cfg as Record<string, unknown>
+		}
+	}
+
+	return undefined
+}
+
+/** Prefer the caller's explicit value; otherwise fall back to `current`'s
+ *  value (if any) and record `fieldName` as carried forward. */
+function resolveField<T>(
+	explicit: T | undefined,
+	current: unknown,
+	fieldName: string,
+	carried: string[],
+): T | undefined {
+	if(explicit !== undefined) {
+		return explicit
+	}
+
+	if(current !== undefined) {
+		carried.push(fieldName)
+		return current as T
+	}
+
+	return undefined
+}
+
 /**
  * The old backend lets you add a version only to a provider YOU own. A
  * `providerId` for a public provider (or anyone else's) comes back as
@@ -71,6 +125,13 @@ export function createVersionFromCaptureTool(
 		useProxy?: boolean
 		providerType?: 'PRIVATE' | 'PUBLIC'
 		notes?: string
+		customInjection?: string
+		userAgent?: { ios?: string, android?: string }
+		pageTitle?: string
+		allowedInjectedRequestData?: AllowedJsRequest[]
+		stepsToFollow?: string
+		useIncognitoWebview?: boolean
+		extensionConfig?: unknown
 	}>(
 		{
 			name: 'create_provider_version_from_capture',
@@ -92,6 +153,23 @@ export function createVersionFromCaptureTool(
 				'must come from get_me_providers. To publish your own version of a ' +
 				"PUBLIC provider you don't own, omit `providerId` to register your " +
 				'own copy (you cannot edit someone else\'s provider here). \n\n' +
+				'For data gated behind login/navigation, pass `customInjection` — a ' +
+				'page-injection script (old-devtools\' name for the builder\'s ' +
+				'jsUserScripts) that drives the page to where the request fires. \n\n' +
+				'This backend has NO partial-patch endpoint — adding a version ' +
+				'always replaces the WHOLE providerConfig. When `providerId` is ' +
+				'set, any of `customInjection`, `userAgent`, `pageTitle`, ' +
+				'`allowedInjectedRequestData`, `stepsToFollow`, ' +
+				'`useIncognitoWebview`, `extensionConfig` that you OMIT is carried ' +
+				'forward unchanged from the currently-published version (so ' +
+				're-publishing requestData never wipes a working login script or ' +
+				'other config someone set via the dashboard). Pass an explicit ' +
+				'value (`""`, `[]`, `false`, ...) to intentionally clear one of ' +
+				'them instead, or call get_provider_version_config first to see ' +
+				'exactly what is live today before deciding what to change. ' +
+				'`allowedInjectedRequestData`/`useIncognitoWebview`/' +
+				'`extensionConfig` only take effect on add-version — the register ' +
+				'endpoint (no `providerId`) ignores them. \n\n' +
 				'Captured requests must be GET/POST. OPRF redactions are supported.',
 			inputSchema: {
 				type: 'object',
@@ -171,6 +249,78 @@ export function createVersionFromCaptureTool(
 							'Change note for the new version (update only; must be ≥10 ' +
 							'chars or a default is used).',
 					},
+					customInjection: {
+						type: 'string',
+						description:
+							'Plain JavaScript injected into the provider page before every ' +
+							'page load — old-devtools\' name for what the builder calls ' +
+							'`webSettings.jsUserScripts`. Use standard browser APIs ' +
+							'(window.location, element.click(), forms) to drive login/' +
+							'navigation so the target request fires — window.Reclaim is ' +
+							'only for rare edge cases, not navigation. The backend rejects ' +
+							'a few deprecated injection APIs (e.g. window.payloadData, ' +
+							'window.ReclaimInjected) with a 400. Guide:\n\n' +
+							INJECTION_GUIDE,
+					},
+					userAgent: {
+						type: 'object',
+						description:
+							'Per-platform user-agent override for the verification ' +
+							'webview. Accepted on register too.',
+						properties: {
+							ios: { type: 'string' },
+							android: { type: 'string' },
+						},
+					},
+					pageTitle: {
+						type: 'string',
+						description: 'Page title metadata. Accepted on register too.',
+					},
+					allowedInjectedRequestData: {
+						type: 'array',
+						description:
+							'Extra requests the customInjection script is allowed to ' +
+							'fire (e.g. pagination) — add-version ONLY, the register ' +
+							'endpoint ignores this. Each item has the same shape as ' +
+							'`provider`, plus `multiple`/`required` (default true).',
+						items: {
+							type: 'object',
+							properties: {
+								url: { type: 'string' },
+								method: { type: 'string' },
+								body: { type: 'string' },
+								responseMatches: { type: 'array' },
+								responseRedactions: { type: 'array' },
+								multiple: {
+									type: 'boolean',
+									description: 'Allow matching many requests. Default true.',
+								},
+								required: {
+									type: 'boolean',
+									description:
+										'Fail validation if none match. Default true.',
+								},
+							},
+							required: ['url', 'method'],
+						},
+					},
+					stepsToFollow: {
+						type: 'string',
+						description:
+							'Free-text setup/manual-verification steps shown to the ' +
+							'dev/verifier. Add-version ONLY.',
+					},
+					useIncognitoWebview: {
+						type: 'boolean',
+						description:
+							'Run the verification webview in incognito mode. ' +
+							'Add-version ONLY.',
+					},
+					extensionConfig: {
+						description:
+							'Free-form JSON passed through to the client. Add-version ' +
+							'ONLY.',
+					},
 				},
 				required: ['initialUrl'],
 			},
@@ -207,11 +357,16 @@ export function createVersionFromCaptureTool(
 				opts.providerType = args.providerType
 			}
 
+			if(args.customInjection !== undefined) {
+				opts.customInjection = args.customInjection
+			}
+
 			// Non-blocking advisory per request — never alters or blocks the
 			// publish; the author keeps full control. Attaches under `_notes`.
 			const notes = matchRedactionWarnings(
 				providers.map((p, i) => countsFor(`Request ${i + 1}`, p)),
 			)
+
 			const withNotes = (result: unknown) => {
 				if(notes.length && result && typeof result === 'object') {
 					return { ...result, _notes: notes }
@@ -220,8 +375,46 @@ export function createVersionFromCaptureTool(
 				return result
 			}
 
-			// New provider.
+			// New provider — no prior version to carry anything forward from.
+			// `allowedInjectedRequestData` / `useIncognitoWebview` /
+			// `extensionConfig` are accepted on the schema but the register
+			// controller never reads them from the body — warn rather than
+			// silently drop, so a dev doesn't think they took effect.
 			if(!args.providerId) {
+				if(opts.customInjection?.trim()) {
+					notes.push(
+						'customInjection will run in the verification client before ' +
+						'every page load (before navigating to initialUrl), matching ' +
+						'the builder\'s jsUserScripts.',
+					)
+				}
+
+				const REGISTER_IGNORED_KEYS = [
+					'allowedInjectedRequestData',
+					'useIncognitoWebview',
+					'extensionConfig',
+				] as const
+				const ignoredOnRegister = REGISTER_IGNORED_KEYS
+					.filter((k) => args[k] !== undefined)
+				if(ignoredOnRegister.length) {
+					notes.push(
+						`${ignoredOnRegister.join(', ')} ${
+							ignoredOnRegister.length > 1 ? 'are' : 'is'
+						} ignored on register (no providerId) — the old backend only ` +
+						'reads them when adding a version. Publish once to create ' +
+						'the provider, then call this again WITH the returned ' +
+						'providerId to set them.',
+					)
+				}
+
+				if(args.userAgent !== undefined) {
+					opts.userAgent = args.userAgent
+				}
+
+				if(args.pageTitle !== undefined) {
+					opts.pageTitle = args.pageTitle
+				}
+
 				const body = providerToRegisterBody(providers, opts)
 				return withNotes(await client.registerProvider(body))
 			}
@@ -232,6 +425,56 @@ export function createVersionFromCaptureTool(
 			// workaround instead of a bare permission error.
 			const providerId = args.providerId
 			try {
+				// This backend has no partial-patch endpoint — a version always
+				// replaces the WHOLE providerConfig. Anything the caller didn't
+				// pass at all is carried forward from the currently-published
+				// version instead of going out blank. Pass an explicit empty
+				// value ("", [], false) to intentionally clear one.
+				const needsCurrent = PRESERVABLE_KEYS.some((k) => args[k] === undefined)
+					|| args.allowedInjectedRequestData === undefined
+				const current = needsCurrent
+					? extractProviderConfig(await client.getProviderConfig(providerId))
+					: undefined
+
+				const carried: string[] = []
+				for(const key of PRESERVABLE_KEYS) {
+					const resolved = resolveField(args[key], current?.[key], key, carried)
+					if(resolved !== undefined) {
+						(opts as unknown as Record<string, unknown>)[key] = resolved
+					}
+				}
+
+				const freshInjected = args.allowedInjectedRequestData !== undefined
+					? injectedRequestDataFrom(args.allowedInjectedRequestData)
+					: undefined
+				const resolvedInjected = resolveField<OldInjectedRequestData[]>(
+					freshInjected,
+					current?.allowedInjectedRequestData,
+					'allowedInjectedRequestData',
+					carried,
+				)
+				if(resolvedInjected !== undefined) {
+					opts.allowedInjectedRequestData = resolvedInjected
+				}
+
+				if(carried.length) {
+					notes.push(
+						'Not passed, carried forward unchanged from the current ' +
+						`published version: ${carried.join(', ')}. Pass an explicit ` +
+						'value ("", [], false, ...) to override any of them, or ' +
+						'call get_provider_version_config first to see what is ' +
+						'live today.',
+					)
+				}
+
+				if(args.customInjection !== undefined && opts.customInjection?.trim()) {
+					notes.push(
+						'customInjection will run in the verification client before ' +
+						'every page load (before navigating to initialUrl), matching ' +
+						'the builder\'s jsUserScripts.',
+					)
+				}
+
 				const versionsResp = await client.listVersions(providerId)
 				const version = bumpPatchString(extractVersions(versionsResp))
 				const versionInfo =

package/src/old/tools/update-provider-metadata.ts

@@ -0,0 +1,72 @@
+import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
+import type { ReclaimOldClient, UpdateProviderMetadataBody } from '../client.ts'
+
+/**
+ * Edit provider-level metadata on the old devtools backend
+ * (`POST /api/providers/:providerId`) — a genuine PARTIAL update on the
+ * PROVIDER document itself, distinct from both
+ * `create_provider_version_from_capture` paths: it does NOT touch
+ * `providerConfig`/versions at all, and only the fields you pass here
+ * change — everything else on the provider is left untouched (no need to
+ * re-supply `requestData`/`customInjection`/etc., and
+ * no new version is created).
+ *
+ * The backend 403s if you don't own the provider (and aren't an admin) —
+ * surfaced verbatim, same as any other auth failure from this client.
+ */
+export function updateProviderMetadataTool(
+	client: ReclaimOldClient,
+): RegisteredTool {
+	return defineTool<UpdateProviderMetadataBody & { providerId: string }>(
+		{
+			name: 'update_provider_metadata',
+			description:
+				'Rename, redescribe, retag, flip providerType (PRIVATE/PUBLIC), or ' +
+				'toggle isActive on a provider YOU own — WITHOUT creating a new ' +
+				'version. Only the fields you pass change; everything else ' +
+				'(requestData, customInjection, versions, ...) is untouched. Pass ' +
+				'at least one of the optional fields. Get a `providerId` from ' +
+				'get_me_providers.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					providerId: {
+						type: 'string',
+						description: 'UUID of the provider to update.',
+					},
+					name: { type: 'string', description: 'New provider name.' },
+					description: {
+						type: 'string',
+						description: 'New provider description.',
+					},
+					providerType: {
+						type: 'string',
+						enum: ['PRIVATE', 'PUBLIC'],
+						description: 'Change PRIVATE/PUBLIC visibility.',
+					},
+					tags: {
+						type: 'array',
+						items: { type: 'string' },
+						description: 'Replace the provider\'s tag list.',
+					},
+					isActive: {
+						type: 'boolean',
+						description: 'Whether the provider is active.',
+					},
+				},
+				required: ['providerId'],
+			},
+		},
+		async({ providerId, ...body }) => {
+			const hasAnyField = Object.values(body).some((v) => v !== undefined)
+			if(!hasAnyField) {
+				throw new Error(
+					'Pass at least one of: name, description, providerType, tags, ' +
+					'isActive.',
+				)
+			}
+
+			return client.updateProviderMetadata(providerId, body)
+		},
+	)
+}

package/src/proof/attestor.ts

@@ -10,9 +10,14 @@ import { bytesToHex } from '@noble/hashes/utils.js'
 import {
 	createClaimOnAttestor, type Logger,
 } from '@reclaimprotocol/attestor-core'
+// Side-effect: make external domhandler nodes DOM-like so attestor-core's
+// bundled `xpath` accepts them (see patch-domhandler.ts). Must load before any
+// proof runs its response-redaction extraction.
+import './patch-domhandler.ts'
 import { agentTraceEnabled } from '../consts.ts'
 import { resolveEthKey } from '../mcp/tools/authenticate/eth-key.ts'
 import type { ReclaimProvider } from '../provider/schema.ts'
+import { installResponseDump } from './debug-response-dump.ts'
 import {
 	buildHttpParams, ensureAttestorCrypto, parseClaim, resolveAttestorUrl,
 } from './proof-core.ts'
@@ -47,9 +52,11 @@ export interface RunAttestorProofOptions {
 	/** Sign with this key directly (e.g. the app/VC's ephemeral per-session key)
 	 *  instead of resolving from env/.env/file. */
 	ownerPrivateKey?: string
-	/** ZK engine for `createClaimOnAttestor`. Defaults to `'gnark'`; the app's
-	 *  server-side verification runner uses `'snarkjs'`. */
-	zkEngine?: 'gnark' | 'snarkjs'
+	/** ZK engine for `createClaimOnAttestor`. Defaults to `'stwo'` — a pure-WASM
+	 *  prover that runs everywhere (no native shared library, so it works on
+	 *  Windows where `'gnark'` fails to load its `.dll`). Server-side paths that
+	 *  want gnark's speed pin it explicitly (e.g. the verify runner). */
+	zkEngine?: 'gnark' | 'snarkjs' | 'stwo'
 	/** Extract the structured {@link AttestorClaim} (claim + attestor signature)
 	 *  onto the result for nested-proof construction. */
 	includeAttestorClaim?: boolean
@@ -249,6 +256,11 @@ export async function runAttestorProof(
 		const capture = traceEnabled ? makeCaptureLogger() : undefined
 		const attestorLogs = capture?.entries
 
+		// Debug (RECLAIM_AGENT_DUMP_RESPONSE): dump the exact response the
+		// attestor validates against, so "Response does not contain X" is
+		// diagnosable against the attestor's real server-side fetch.
+		installResponseDump()
+
 		let claim: unknown
 		try {
 			claim = await createClaimOnAttestor({
@@ -259,7 +271,7 @@ export async function runAttestorProof(
 				},
 				ownerPrivateKey,
 				client: { url: resolveAttestorUrl(opts.attestorUrl) },
-				zkEngine: opts.zkEngine ?? 'gnark',
+				zkEngine: opts.zkEngine ?? 'stwo',
 				...(capture !== undefined && { logger: capture.logger as Logger }),
 			})
 		} catch(err) {

package/src/proof/debug-response-dump.ts

@@ -0,0 +1,70 @@
+// Debug helper (gated by RECLAIM_AGENT_DUMP_RESPONSE): capture the EXACT
+// response bytes the attestor validates a claim against, plus a per-match
+// presence check. A "Response does not contain X" failure means the attestor's
+// server-side re-fetch differs from what the browser (replay) saw — e.g. GitHub
+// embeds nav/userMenu data for browser requests but not for the attestor's raw
+// fetch. Seeing the attestor's actual response is the only way to tell what it
+// really returned.
+//
+// On each getResponseRedactions call it writes the response to
+// `attestor-last-response.html` in the process CWD and logs the byte count +,
+// for every responseMatch (paramValues substituted), whether it's present.
+import { providers } from '@reclaimprotocol/attestor-core'
+import { writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+interface RedactionArg {
+	response: Uint8Array
+	params: {
+		responseMatches?: Array<{ value?: string }>
+		paramValues?: Record<string, string>
+	}
+}
+
+let installed = false
+
+/** Wrap attestor-core's http `getResponseRedactions` to dump the response it
+ *  runs against. Idempotent; no-op unless RECLAIM_AGENT_DUMP_RESPONSE is
+ *  set. */
+export function installResponseDump(): void {
+	if(installed || !process.env['RECLAIM_AGENT_DUMP_RESPONSE']) {
+		return
+	}
+
+	const http = providers['http'] as unknown as {
+		getResponseRedactions?: (arg: RedactionArg) => unknown
+	}
+	const original = http.getResponseRedactions
+	if(typeof original !== 'function') {
+		return
+	}
+
+	installed = true
+	http.getResponseRedactions = function(this: unknown, arg: RedactionArg) {
+		try {
+			const bytes = Buffer.from(arg.response)
+			const text = bytes.toString('utf8')
+			const paramValues = arg.params.paramValues ?? {}
+			const matches = (arg.params.responseMatches ?? []).map((m) => {
+				let value = m.value ?? ''
+				for(const [key, val] of Object.entries(paramValues)) {
+					value = value.split(`{{${key}}}`).join(val)
+				}
+
+				return { value, present: text.includes(value) }
+			})
+			const path = join(process.cwd(), 'attestor-last-response.html')
+			writeFileSync(path, text)
+			process.stderr.write(`${JSON.stringify({
+				tag: 'attestor-response-dump',
+				bytes: bytes.length,
+				path,
+				matches,
+			})}\n`)
+		} catch{
+			// diagnostic only — never break proving
+		}
+
+		return original.call(this, arg)
+	}
+}

package/src/proof/patch-domhandler.ts

@@ -0,0 +1,68 @@
+// Side-effect module: make `domhandler` nodes DOM-like for the `xpath` engine.
+//
+// WHY THIS EXISTS
+// `@reclaimprotocol/attestor-core`'s published `lib` bundles its own inlined
+// copy of `domhandler` and applies a DOM-compat patch (nodeName / localName +
+// a NamedNodeMap `item()` shim) to THAT copy. But at proof time the HTML tree
+// is built by the *external* `parse5-htmlparser2-tree-adapter`, which uses the
+// separately-installed `domhandler` — a different, UNPATCHED copy. The `xpath`
+// engine then fails `isNodeLike()` on every node (it needs a string `nodeName`)
+// and throws "Context node does not appear to be a valid DOM node", so ALL
+// xPath / xPath+jsonPath response redactions fail during `runAttestorProof`'s
+// receipt validation. (Regex-only redactions escape it — they never touch the
+// parse5/xpath path.) Running attestor-core from source works because there is
+// then a single shared `domhandler`; the bug is only in the bundled `lib`.
+//
+// Rather than fork attestor-core, apply the identical patch to the external
+// `domhandler` the adapter actually uses, so its tree nodes are DOM-like. This
+// mirrors attestor-core's own `patch-parse5-tree`. Idempotent and
+// version-agnostic. Import it before any proving path runs.
+//
+// Remove once attestor-core externalizes `domhandler` in its build (one shared
+// copy → its own patch suffices).
+import { Element, Node } from 'domhandler'
+
+const PATCH_FLAG = Symbol.for('reclaim.domhandler.domCompatPatched')
+const proto = Node.prototype as unknown as Record<PropertyKey, unknown>
+
+if(!proto[PATCH_FLAG]) {
+	// `xpath`'s isNodeLike() requires a string `nodeName`; domhandler nodes carry
+	// the tag under `.name`.
+	Object.defineProperty(Node.prototype, 'nodeName', {
+		configurable: true,
+		get(this: { name?: string }) {
+			return this.name
+		},
+	})
+	Object.defineProperty(Node.prototype, 'localName', {
+		configurable: true,
+		get(this: { name?: string }) {
+			return this.name
+		},
+	})
+
+	// Attribute-predicate steps (`[@id=…]`, `contains(@class,…)`) walk the
+	// NamedNodeMap via `.item(i)`; give each returned attribute node the DOM
+	// shape `xpath` expects (nodeType 2 + localName).
+	const attrsGetter =
+		Object.getOwnPropertyDescriptor(Element.prototype, 'attributes')?.get
+	if(attrsGetter) {
+		Object.defineProperty(Element.prototype, 'attributes', {
+			configurable: true,
+			get(this: unknown) {
+				const attrs = attrsGetter.call(this) as
+					(Record<number, { name: string }> & {
+						item?: (i: number) => unknown
+					})
+				attrs.item = (i: number) => {
+					const attr = attrs[i]
+					return { ...attr, nodeType: 2, localName: attr.name }
+				}
+
+				return attrs
+			},
+		})
+	}
+
+	proto[PATCH_FLAG] = true
+}

package/src/proof/proof-core.ts

@@ -38,7 +38,7 @@ export function resolveAttestorUrl(override?: string): string {
 	)
 }
 
-/** Map a verification's provider recipe straight to the attestor's HTTP
+/** Map a provider's recipe straight to the attestor's HTTP
  *  params — never synthesized from captured traffic. */
 export function buildHttpParams(
 	provider: ReclaimProvider,

package/src/proof/zk-files.ts

@@ -1,6 +1,7 @@
 // Lazy download of the @reclaimprotocol/zk-symmetric-crypto circuit resources
-// that the snarkjs proof engine needs. These are ~280MB and are NOT fetched in
-// a `postinstall` (that blocked the MCP server's first launch past the connect
+// the proof engines need (the downloader fetches every engine — stwo, snarkjs,
+// gnark — as one bundle). These are ~280MB and are NOT fetched in a
+// `postinstall` (that blocked the MCP server's first launch past the connect
 // timeout — see the install notes). Instead we fetch them on the first proof,
 // once, so the server starts immediately and only `run_proof` pays the cost.
 
@@ -43,12 +44,12 @@ async function download(): Promise<void> {
 	}
 
 	// mainPath is <pkg>/lib/index.js → resources live at <pkg>/resources, the
-	// downloader at <pkg>/lib/scripts/download-files.js. We only use the snarkjs
-	// engine (createClaimOnAttestor zkEngine: 'snarkjs'), so its presence is the
-	// signal that the circuits are ready.
+	// downloader at <pkg>/lib/scripts/download-files.js. Proofs default to the
+	// stwo (WASM) engine, so its resource dir being present is the signal that
+	// the circuits are ready (the downloader fetches all engines together).
 	const libDir = dirname(mainPath)
 	const pkgDir = dirname(libDir)
-	if(existsSync(join(pkgDir, 'resources', 'snarkjs'))) {
+	if(existsSync(join(pkgDir, 'resources', 'stwo'))) {
 		return
 	}