@reclaimprotocol/agent 0.1.29 → 0.1.32

package/src/old/flag.ts

@@ -2,11 +2,8 @@
  * `USE_OLD_DEVTOOLS` — single source of truth for which backend the MCP
  * server targets.
  *
- * Defaults to OLD devtools (the system still in production) while the new
- * "builder" backend is under development. Builder mode must be opted into
- * EXPLICITLY by setting `USE_OLD_DEVTOOLS=false`. Anything else — unset,
- * empty, `true`, `1`, a typo — keeps old mode on, so a forgotten env var
- * can never silently route a developer at the half-built builder backend.
+ * Builder is the default. Only `true` or `1` explicitly selects old devtools;
+ * an unset value or typo stays on Builder.
  *
  * The actual env read lives in `../consts.ts` (the single env-access module);
  * this widely-imported path re-exports it for back-compat.

package/src/old/instructions.ts

@@ -1,6 +1,6 @@
 /**
  * MCP server instructions shown to the LLM when running in OLD-devtools mode
- * (`USE_OLD_DEVTOOLS` unset or not `false`). Describes the REDUCED tool
+ * (`USE_OLD_DEVTOOLS=true` or `1`). Describes the REDUCED tool
  * surface — there are no org/credential-link/review flows and no generated
  * API tools here. Both modes' instructions load together in
  * `mcp/instructions` (alongside the topic-split authoring guide); re-exported

package/src/old/to-register.ts

@@ -72,9 +72,10 @@ export interface OldProviderOpts {
 	 *  .interceptorOptions.isDocumentRequestReplayEnabled`, is likewise always
 	 *  force-disabled by `providerToCreateVersionRequest`. */
 	disableRequestReplay?: boolean
-	/** Interception mechanism — `NONE` (the publish tool's default) for the
-	 *  standard capture→replay flow; `HAWKEYE`/`MSWJS`/`XHOOK`/`CDP` for a
-	 *  genuine live-interception provider. Old-devtools calls this
+	/** Interception mechanism. Omit it to use the backend's `HAWKEYE` default;
+	 *  use `NONE` only when disabling interception after diagnosis.
+	 *  `HAWKEYE`/`MSWJS`/`XHOOK`/`CDP` enable live interception. Old-devtools
+	 *  calls this
 	 *  `injectionType`; builder's equivalent is `webSettings.clientOptions
 	 *  .inapp.interceptorOptions.interceptorType` (no `NONE` value there —
 	 *  omitting the whole object is builder's no-interception signal

package/src/old/tools/get-provider-info.ts

@@ -41,7 +41,9 @@ export function getProviderInfoTool(client: ReclaimSdkClient): RegisteredTool {
 				'Read a PUBLISHED provider from the public production SDK backend ' +
 				'(api.reclaimprotocol.org — what the verification SDK/attestor ' +
 				'itself fetches at runtime), for ANY provider, no auth required. ' +
-				'This is the provider-read tool for old-devtools mode. \n\n' +
+				'This is the provider-read tool for old-devtools mode. A ' +
+				'published provider is usable as-is: don\'t re-verify it ' +
+				'(capture/replay/proof) unless the user asks to test it.\n\n' +
 				'Returns two complementary reads for the given version (latest ' +
 				'when `versionNumber` is omitted): `provider` (the FULL provider ' +
 				'+ providerConfig — `customInjection`, `userAgent`, ' +

package/src/old/tools/publish.ts

@@ -455,20 +455,12 @@ export function createVersionFromCaptureTool(
 						type: 'string',
 						enum: ['NONE', 'MSWJS', 'XHOOK', 'CDP', 'HAWKEYE'],
 						description:
-							'Interception mechanism for this version. Omit to leave it ' +
-							'unset — the devtools backend\'s own column default ' +
-							'(`HAWKEYE`) applies, which is inert and harmless for the ' +
-							'standard capture→replay flow with no interceptor script ' +
-							'installed. Only set `HAWKEYE`/`MSWJS`/`XHOOK` when you are ' +
-							'ALSO supplying a `customInjection` script that calls ' +
-							'`window.reclaimInterceptor.addResponseMiddleware(...)` for ' +
-							'genuine live interception, or set `NONE` explicitly to be ' +
-							'certain none is configured. Builder calls the equivalent ' +
-							'concept `interceptorType` (no `NONE` there — omitting the ' +
-							'whole `interceptorOptions` object is its no-interception ' +
-							'signal instead). ' + COOKIE_ATTACHMENT_HINT +
-							'What each value actually does: ' +
-							'how_it_works({ topic: "interception" }).',
+							'Live-interception mechanism. Omit it for the standard flow. ' +
+							'Use `NONE` only to confirm a suspected interception problem; ' +
+							'if that fixes the provider, keep `NONE` and use ' +
+							'`window.Reclaim.requestClaim(...)`. For selection rules, call ' +
+							'how_it_works({ topic: "interception" }). ' +
+							COOKIE_ATTACHMENT_HINT,
 					},
 					disableRequestReplay: {
 						type: 'boolean',
@@ -499,6 +491,16 @@ export function createVersionFromCaptureTool(
 					'registration starts at the backend-defined version.',
 				),
 			)
+			assert(
+				args.injectionType !== 'NONE'
+					|| !args.customInjection?.includes('addResponseMiddleware'),
+				badRequest(
+					'`injectionType: NONE` cannot deliver ' +
+					'`addResponseMiddleware` traffic. Use an interceptor type, or ' +
+					'keep `NONE` and replace intercepted requests with ' +
+					'`window.Reclaim.requestClaim(...)`.',
+				),
+			)
 			// `provider` / `providers` are just two spellings of the same input —
 			// fold them into one array. Zero drafts is allowed ONLY when adding a
 			// version to an EXISTING provider (`providerId` set): that publishes

package/src/proof/attestor-auth.ts

@@ -11,16 +11,33 @@ export interface AttestorAuthentication {
 /**
  * Create legacy-compatible attestor authorization when the deployment has an
  * auth private key. An absent key intentionally means authentication is off.
+ *
+ * `expiresInSeconds` overrides the attestor library's default lifetime. A
+ * zkFetch authorization uses a very short one: the attestor validates expiry
+ * once, when it authenticates the connection, and never again for the life of
+ * that connection — so the window only has to cover the caller receiving the
+ * token and opening its socket, not the proof that follows.
  */
 export async function createAttestorAuthentication(
 	sessionId: string,
 	privateKey: string | undefined,
+	opts: { expiresInSeconds?: number } = {},
 ): Promise<AttestorAuthentication | undefined> {
 	if(!privateKey?.trim()) {
 		return undefined
 	}
 
-	const request = await createAuthRequest({ id: sessionId }, privateKey)
+	const request = await createAuthRequest(
+		{
+			id: sessionId,
+			...(opts.expiresInSeconds === undefined
+				? {}
+				: {
+					expiresAt: Math.floor(Date.now() / 1000) + opts.expiresInSeconds,
+				}),
+		},
+		privateKey,
+	)
 	const token = Buffer.from(
 		JSON.stringify({
 			...request,

package/src/proof/attestor.ts

@@ -22,6 +22,7 @@ import type { ReclaimProvider } from '../provider/schema.ts'
 import { installResponseDump } from './debug-response-dump.ts'
 import {
 	buildHttpParams,
+	claimRejection,
 	ensureAttestorCrypto,
 	parseClaim,
 	resolveAttestorUrl
@@ -65,7 +66,7 @@ export interface RunAttestorProofOptions {
 	 *  want gnark's speed pin it explicitly (for example, the verify runner). */
 	zkEngine?: 'gnark' | 'snarkjs' | 'stwo'
 	/** Extract the structured {@link AttestorClaim} (claim + attestor signature)
-	 *  onto the result for legacy Proof construction. */
+	 *  onto the result for Proof construction. */
 	includeAttestorClaim?: boolean
 }
 
@@ -77,7 +78,7 @@ export interface ProofResult {
 	owner?: string
 	verified: boolean
 	error?: string
-	/** Structured claim + signature for legacy Proof verification. Set only when
+	/** Structured claim + signature for Proof verification. Set only when
 	 *  `includeAttestorClaim` was requested and the claim carries signatures. */
 	attestorClaim?: AttestorClaim
 	/** Set to `'missing-owner-key'` when no credential was available to
@@ -300,6 +301,26 @@ export async function runAttestorProof(
 			return errorResult
 		}
 
+		// The attestor reports a rejected claim (for example, an invalid ZK proof)
+		// in the response rather than by throwing, so a returned value alone is
+		// not a proof: it needs a claim, a claim signature, and no error.
+		const rejection = claimRejection(claim)
+		if(rejection !== undefined) {
+			const rejected: ProofResult = {
+				proof: claim,
+				extractedValue: '',
+				extractedParameters: {},
+				verified: false,
+				error: rejection,
+				sentParams: params,
+			}
+			if(attestorLogs !== undefined) {
+				rejected.attestorLogs = attestorLogs
+			}
+
+			return rejected
+		}
+
 		const { extractedValue, extractedParameters, identifier, owner, claimData }
 			= parseClaim(claim)
 
@@ -318,7 +339,7 @@ export async function runAttestorProof(
 		}
 
 		// Structured claim + signature so the result JWS can carry the exact
-		// legacy Proof the Consumer verifies independently.
+		// Proof the Consumer verifies independently.
 		if(opts.includeAttestorClaim) {
 			const sigs = (claim as {
 				signatures?: { attestorAddress?: unknown, claimSignature?: unknown }

package/src/proof/pod-prover.ts

@@ -27,7 +27,7 @@
  * The pod API is unauthenticated (gateway/session is the trust boundary); call
  * it over the same internal host used for CDP. Consumers verify
  * `claim_signature` with the legacy SDK's `verifyProof`, so this hands back an
- * {@link AttestorClaim} that the app places in the exact legacy `Proof` shape.
+ * {@link AttestorClaim} that the app places in the exact `Proof` shape.
  * `result_signature` is unused by consumers.
  */
 import { bytesToHex } from '@noble/hashes/utils.js'

package/src/proof/proof-core.ts

@@ -75,6 +75,34 @@ export interface ParsedClaim {
 	owner?: string
 }
 
+/** Why the attestor did not sign `claim`, or `undefined` when it did. The
+ *  attestor returns rejections (for example, an invalid ZK proof) as a
+ *  response with `error` set and no claim signature, not by throwing. */
+export function claimRejection(claim: unknown): string | undefined {
+	const response = claim as {
+		claim?: unknown
+		error?: { code?: unknown, message?: unknown }
+		signatures?: { claimSignature?: unknown }
+	} | null | undefined
+	const error = response?.error
+	if(error?.message || error?.code) {
+		return typeof error.message === 'string' && error.message
+			? error.message
+			: `attestor error code ${String(error.code)}`
+	}
+
+	if(!response?.claim) {
+		return 'attestor returned no claim'
+	}
+
+	const signature = response.signatures?.claimSignature
+	if(!(signature instanceof Uint8Array) || !signature.length) {
+		return 'attestor did not sign the claim'
+	}
+
+	return undefined
+}
+
 /** Pull claimData + decoded `context.extractedParameters` (plus identifier /
  *  owner) out of a `createClaimOnAttestor` result. The full result still
  *  carries signatures the caller may need for nested-proof building. */

package/src/provider/injection-doc.ts

@@ -33,17 +33,19 @@ export const USER_SCRIPT_HINT =
 
 /** Prefixes the `allowedJsRequests` / `allowedInjectedRequestData` field. The
  *  trap it describes is silent and total — a mis-declared entry makes
- *  `verifyProof({ providerId })` reject EVERY real proof — so the warning
- *  itself stays in the schema even though its explanation moved to a topic. */
+ *  `verifyRequestProof({ providerId })` reject EVERY real proof — so the
+ *  warning itself stays in the schema even though its explanation moved to a
+ *  topic. */
 export const ALLOWED_REQUESTS_HINT =
 	'⚠️ Only populate this if you intend to gate '
-	+ '`verifyProof(proof, { providerId })`: each entry feeds a client-side '
-	+ 'hash-equality check and its `url` is hashed VERBATIM (no regex/template '
-	+ 'resolution, even with urlType REGEX/TEMPLATE). If the real captured URL '
-	+ 'carries ANY per-session part (nonce, CSRF token, cache-busting '
-	+ 'timestamp), no declared spec can ever hash-match a real proof — '
-	+ 'populating it then makes verifyProof reject every real proof, which is '
-	+ 'worse than leaving it empty. Diff the same endpoint\'s captured URL '
-	+ 'across two sessions first. Mechanics, the body-templating rules and the '
+	+ '`verifyRequestProof(proof, { providerId })`: each entry feeds a '
+	+ 'client-side hash-equality check and its `url` is hashed VERBATIM (no '
+	+ 'regex/template resolution, even with urlType REGEX/TEMPLATE). If the '
+	+ 'real captured URL carries ANY per-session part (nonce, CSRF token, '
+	+ 'cache-busting timestamp), no declared spec can ever hash-match a real '
+	+ 'proof — populating it then makes verifyRequestProof reject every real '
+	+ 'proof, which is worse than leaving it empty. Diff the same endpoint\'s '
+	+ 'captured URL across two sessions first. Mechanics, the '
+	+ 'body-templating rules and the '
 	+ 'dangerouslyDisableContentValidation fallback: '
 	+ 'how_it_works({ topic: "hash-validation" }).'

package/src/provider/matcher.ts

@@ -327,16 +327,32 @@ function findJsonPath(body: string, target: string): string | undefined {
 	}
 
 	const candidates = normalizeCandidates(target)
-	return walk(parsed, '$', candidates)
+	const paths: string[] = []
+	collectJsonPaths(parsed, '$', candidates, paths)
+	if(paths.length > 1) {
+		throw new Error(
+			`target value "${target}" occurs at multiple JSON paths `
+			+ `(${paths.join(', ')}) — choose a value that identifies one field`,
+		)
+	}
+
+	return paths[0]
 }
 
-function walk(
+function collectJsonPaths(
 	node: unknown,
 	path: string,
 	candidates: string[],
-): string | undefined {
+	paths: string[],
+): void {
+	// Two paths are enough to prove ambiguity and keep traversal bounded for a
+	// response containing the same primitive many times.
+	if(paths.length > 1) {
+		return
+	}
+
 	if(node === null || node === undefined) {
-		return undefined
+		return
 	}
 
 	if(
@@ -346,21 +362,18 @@ function walk(
 	) {
 		const str = String(node)
 		if(candidates.includes(str)) {
-			return path
+			paths.push(path)
 		}
 
-		return undefined
+		return
 	}
 
 	if(Array.isArray(node)) {
 		for(const [i, element] of node.entries()) {
-			const found = walk(element, `${path}[${i}]`, candidates)
-			if(found) {
-				return found
-			}
+			collectJsonPaths(element, `${path}[${i}]`, candidates, paths)
 		}
 
-		return undefined
+		return
 	}
 
 	if(typeof node === 'object') {
@@ -368,14 +381,9 @@ function walk(
 			const childPath = /^[A-Za-z_][A-Za-z0-9_]*$/.test(k)
 				? `${path}.${k}`
 				: `${path}["${k}"]`
-			const found = walk(v, childPath, candidates)
-			if(found) {
-				return found
-			}
+			collectJsonPaths(v, childPath, candidates, paths)
 		}
 	}
-
-	return undefined
 }
 
 // ---------------------------------------------------------------------------

package/src/provider/to-version.ts

@@ -74,6 +74,11 @@ export interface CreateVersionOptions {
 	jsUserScripts?: string
 	/** Requests the injection script may fire, as `RequestSelectionTemplate`s. */
 	allowedJsRequests?: AllowedJsRequest[]
+	/** Portal-only authenticated actions exposed as
+	 *  `window.Reclaim.browserRequest`. */
+	browserRequestActions?: NonNullable<
+		CreateProviderVersionRequest['webSettings']['browserRequestActions']
+	>
 	/** In-app interception options, mapped to
 	 *  `webSettings.clientOptions.inapp.interceptorOptions` — ONLY when this
 	 *  is explicitly passed (builder's schema has no `NONE` interceptorType;
@@ -218,7 +223,7 @@ export function providerToCreateVersionRequest(
 ): CreateProviderVersionRequest {
 	const {
 		notes, version, requiredContext: requestedContext, jsUserScripts,
-		allowedJsRequests, interceptorOptions,
+		allowedJsRequests, browserRequestActions, interceptorOptions,
 	} = opts
 	const requiredContext = requestedContext ?? deriveRequiredContext(
 		providers,
@@ -279,6 +284,7 @@ export function providerToCreateVersionRequest(
 			},
 			// Only set when non-empty; an empty string would store a no-op script.
 			...(script ? { jsUserScripts: script } : {}),
+			...(browserRequestActions?.length ? { browserRequestActions } : {}),
 		},
 		// Derived from `{{context.<name>}}` placeholders only — a captured
 		// provider's `paramValues` are extracted response parameters, not