@reclaimprotocol/agent 0.1.23 → 0.1.25

package/src/old/tools/publish.ts

@@ -1,7 +1,10 @@
 import { Boom, isBoom } from '@hapi/boom'
 import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
 import type { AttachState } from '../../mcp/tools/agent/attach.ts'
-import { INJECTION_GUIDE } from '../../provider/injection-doc.ts'
+import {
+	ALLOWED_REQUESTS_HINT,
+	USER_SCRIPT_HINT,
+} from '../../provider/injection-doc.ts'
 import {
 	countsFor,
 	matchRedactionWarnings,
@@ -35,8 +38,8 @@ function extractProviderId(resp: unknown): string | undefined {
  * `providerId` for a public provider (or anyone else's) comes back as
  * 401/403/404 — the dev's likely intent is to publish their OWN version of that
  * site, which on this backend means registering a separate copy. Rethrow those
- * failures with that actionable suggestion; leave other errors (e.g. a 400
- * version collision) untouched so their real detail surfaces.
+ * failures with that actionable suggestion; leave other errors (for example, a
+ * 400 version collision) untouched so their real detail surfaces.
  */
 function rethrowOwnershipError(err: unknown, providerId: string): never {
 	const status = isBoom(err) ? err.output.statusCode : undefined
@@ -62,7 +65,7 @@ function rethrowOwnershipError(err: unknown, providerId: string): never {
 /**
  * Publish a drafted provider to the OLD devtools backend. Keeps the builder
  * tool NAME (`create_provider_version_from_capture`) so the skill flow is
- * unchanged, but the behaviour differs:
+ * unchanged, but the behavior differs:
  *
  *   - WITHOUT `providerId` → `POST /api/providers/register`: creates a
  *     brand-new provider + version 1.0.0. Re-running creates a DUPLICATE.
@@ -100,67 +103,43 @@ export function createVersionFromCaptureTool(
 		useIncognitoWebview?: boolean
 		extensionConfig?: unknown
 		injectionType?: 'NONE' | 'MSWJS' | 'XHOOK' | 'CDP' | 'HAWKEYE'
+		disableRequestReplay?: boolean
 	}>(
 		{
 			name: 'create_provider_version_from_capture',
 			description:
-				'Publish drafted ReclaimProvider(s) to the devtools backend. ' +
-				'Requires its OWN old-devtools login via reclaim_authenticate — ' +
-				'separate from authenticate_builder/Builder auth, which does not ' +
-				'authorize this call. Check status with get_devtools_mode. \n\n' +
-				'Pass the `provider` object from propose_provider VERBATIM and the ' +
-				'`initialUrl` the user landed on (the login/landing page, NOT the ' +
-				'API url). \n\n' +
-				'For a MULTI-REQUEST provider, pass `providers: [...]` (each entry a ' +
-				'proven draft from propose_provider) — every entry becomes one ' +
-				'`requestData` entry on the SAME version, and all are verified ' +
-				'together. Pass a single `provider` for the one-request case ' +
-				'(provide exactly one of `provider` / `providers`). \n\n' +
-				'Omit `providerId` to REGISTER A NEW provider (creates it + version ' +
-				'1.0.0; re-running creates a duplicate). Pass `providerId` (from ' +
-				'get_me_providers) to add a NEW VERSION to that existing provider ' +
-				'(the patch is auto-bumped). \n\n' +
-				'You can only add versions to a provider YOU own — the `providerId` ' +
-				'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 ' +
-				'USER SCRIPT (same concept as the builder\'s `jsUserScripts` — ' +
-				'devtools just calls the field `customInjection`) that drives the ' +
-				'page to where the request fires. \n\n' +
-				'BY DESIGN, this backend only ever CREATES A NEW VERSION (POST) — ' +
-				'there is no partial-patch/edit endpoint, and this tool does NOT ' +
-				'read or carry anything forward from the previous version. Every ' +
-				'new version replaces the WHOLE providerConfig with exactly what ' +
-				'you pass in THIS call. Therefore any field you want present in the ' +
-				'new version MUST be supplied here — `customInjection`, `userAgent`, ' +
-				'`pageTitle`, `allowedInjectedRequestData`, `stepsToFollow`, ' +
-				'`useIncognitoWebview`, `extensionConfig`, and `requestData` (via ' +
-				'`provider`/`providers`). Anything you OMIT is published blank/' +
-				'default in the new version, NOT preserved. To change one field ' +
-				'while keeping the rest, first read the current version with ' +
-				'get_provider_info, then pass the full desired config (the existing ' +
-				'values plus your change) back into this call. ' +
-				'`allowedInjectedRequestData`/`useIncognitoWebview`/' +
-				'`extensionConfig` only take effect on add-version — the register ' +
-				'endpoint (no `providerId`) ignores them, so on a fresh register ' +
-				'this tool automatically follows up with an add-version call that ' +
-				'applies them (also where document replay gets force-disabled — ' +
-				'see below). Per-request fields you may set on ' +
-				'`provider`/`providers`: `credentials` (omit/same-origin/include, ' +
-				'default include), `urlType` (REGEX/CONSTANT/TEMPLATE, default ' +
-				'derived from {{placeholders}}), and `isOptional` on each ' +
-				'responseMatch (default false). \n\n' +
-				'Captured requests must be GET/POST. OPRF redactions are supported. ' +
-					'Document replay — the HAWKEYE-level flag controlling whether the ' +
-					'page\'s own document/navigation request gets genuinely re-sent ' +
-					'through the interceptor at verification time — is ALWAYS ' +
-					'published disabled (`disableRequestReplay: true`); there is no ' +
-					'way to enable it here. ' +
-					'On success, if a browser is still attached, the response\'s ' +
-					'`_notes` reminds you to confirm with the developer before ' +
-					'calling `dispose_browser` — never close it unprompted, they ' +
-					'may want it for further edits.',
+				'Publish drafted ReclaimProvider(s) to the devtools backend. Needs '
+				+ 'its OWN reclaim_authenticate login — authenticate_builder does NOT '
+				+ 'authorize this call. Pass the `provider` object(s) from '
+				+ 'propose_provider VERBATIM, plus the `initialUrl` the user landed '
+				+ 'on (the login/landing page, NOT the API url). Exactly one of '
+				+ '`provider` (one request) or `providers` (a multi-request '
+				+ 'provider — every entry becomes a parallel requestData entry, all '
+				+ 'verified together). Captured requests must be GET/POST; OPRF '
+				+ 'redactions are supported.\n\n'
+				+ 'Omit `providerId` to REGISTER A NEW provider (creates it + '
+				+ 'version 1.0.0 — re-running creates a DUPLICATE). Pass '
+				+ '`providerId` (from get_me_providers) to add a NEW VERSION to it; '
+				+ 'the patch auto-bumps. You can only version a provider YOU own — '
+				+ 'to publish your own take on one you don\'t own, omit '
+				+ '`providerId` to register your own copy.\n\n'
+				+ 'THIS BACKEND ONLY EVER CREATES A NEW VERSION — there is no '
+				+ 'partial-patch endpoint, and this tool carries NOTHING forward '
+				+ 'from the previous version: every version replaces the WHOLE '
+				+ 'providerConfig with exactly what you pass in THIS call. Any '
+				+ 'field you want to survive must be re-supplied here '
+				+ '(`customInjection`, `userAgent`, `pageTitle`, '
+				+ '`allowedInjectedRequestData`, `stepsToFollow`, '
+				+ '`useIncognitoWebview`, `extensionConfig`, `requestData`); '
+				+ 'anything omitted is published blank. To change one field, read '
+				+ 'the current config with get_provider_info first and pass it back '
+				+ 'with your edit. `allowedInjectedRequestData`/'
+				+ '`useIncognitoWebview`/`extensionConfig` apply on add-version '
+				+ 'only, so a fresh register auto-follows with an add-version call '
+				+ 'that applies them (and disables document replay — see '
+				+ '`disableRequestReplay`).\n\n'
+				+ 'Always read the response\'s `_notes`. '
+				+ 'Full walkthrough: how_it_works({ topic: "publish" }).',
 			inputSchema: {
 				type: 'object',
 				properties: {
@@ -272,15 +251,11 @@ export function createVersionFromCaptureTool(
 					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,
+							USER_SCRIPT_HINT
+							+ ' Old-devtools\' name for what the builder calls '
+							+ 'webSettings.jsUserScripts. The backend rejects a few '
+							+ 'deprecated injection APIs (window.payloadData, '
+							+ 'window.ReclaimInjected) with a 400.',
 					},
 					userAgent: {
 						type: 'object',
@@ -299,39 +274,15 @@ export function createVersionFromCaptureTool(
 					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). ' +
-							'IMPORTANT whenever a claim\'s request HAS a body: set `body` ' +
-							'here (see its own description below) — if only a small part ' +
-							'of the real body varies per user/run (e.g. one id field, not ' +
-							'the whole payload), template just that part with ' +
-							'`{{paramName}}` and keep the rest as fixed literal text; see ' +
-							'the "bodySniff" section of the customInjection field\'s guide ' +
-							'for the exact mechanics and a worked example. ' +
-							'⚠️ BEFORE populating this to gate ' +
-							'`verifyProof(proof, { providerId })`: this whole entry (url, ' +
-							'method, body, responseMatches, responseRedactions) feeds a ' +
-							'client-side hash-equality check, and `url` is hashed VERBATIM ' +
-							'— no regex/template resolution, even with `urlType: REGEX` or ' +
-							'`TEMPLATE`. If the real captured URL contains ANY per-session ' +
-							'part (a tracking nonce, CSRF token, cache-busting timestamp), ' +
-							'no declared spec can EVER hash-match a real proof, no matter ' +
-							'how correct the rest of this entry is — populating' +
-							'it for such ' +
-							'a provider makes verifyProof reject every real proof,' +
-							'which is ' +
-							'worse than leaving this field empty. Diff the same endpoint\'s' +
-							' captured URL across two separate sessions before wiring this ' +
-							'up. If provider-hash validation keeps causing problems ' +
-							'(unstable url, or any other persistent mismatch), the ' +
-							'fallback on the verifying side is `verifyProof(proof, { ' +
-							'dangerouslyDisableContentValidation: true })` — trusts only ' +
-							'the attestor\'s signature, skips the hash-equality check ' +
-							'entirely; see the "Provider-hash validation" section of the ' +
-							'customInjection field\'s guide for the full mechanics and ' +
-							'when to reach for it.',
+							'Extra requests the customInjection user script is allowed to '
+							+ 'fire (for example, pagination) — add-version ONLY, the '
+							+ 'register '
+							+ 'endpoint ignores it. Each item has the same shape as '
+							+ '`provider`, plus `multiple`/`required` (default true). Set '
+							+ '`body` whenever the request has one (see its own description '
+							+ 'below). The builder calls the same concept '
+							+ '`allowedJsRequests`. '
+							+ ALLOWED_REQUESTS_HINT,
 						items: {
 							type: 'object',
 							properties: {
@@ -353,7 +304,8 @@ export function createVersionFromCaptureTool(
 										'body at all (skip only for a genuinely bodyless ' +
 										'request, typically GET). If the real body is FIXED ' +
 										'(identical for every user/run), put that literal body ' +
-										'text here verbatim. If only PART of it varies (e.g. ' +
+										'text here verbatim. If only PART of it varies (for ' +
+										'example, ' +
 										'`{"request":1,"type":"user_info","id":"12345"}` where ' +
 										'only `id` differs per user), template ONLY that part: ' +
 										'`{"request":1,"type":"user_info",' +
@@ -376,7 +328,7 @@ export function createVersionFromCaptureTool(
 										'reproduces the real captured request body ' +
 										'byte-for-byte. Fallback if per-field templating keeps ' +
 										'mismatching (more fields vary than expected, unstable ' +
-										'key order, etc.) and you can\'t pin down every ' +
+										'key order, and so on) and you can\'t pin down every ' +
 										'variable field: template the WHOLE body as one ' +
 										'placeholder instead, `{{REQ_BODY_GRD}}` — the `GRD` ' +
 										'suffix makes it a greedy match (captures everything) ' +
@@ -394,7 +346,7 @@ export function createVersionFromCaptureTool(
 										'`value` must literally appear (or match, if `regex`) ' +
 										'somewhere in the response body for the claim to be ' +
 										'accepted; it commonly embeds one or more ' +
-										'`{{paramName}}` extraction placeholders (e.g. ' +
+										'`{{paramName}}` extraction placeholders (for example, ' +
 										'`"name":"{{name_0}}"`) whose real value is redacted ' +
 										'out and supplied separately as a witness/extracted ' +
 										'param. Use `${var}` (not `{{var}}`) inside this string ' +
@@ -410,7 +362,8 @@ export function createVersionFromCaptureTool(
 										'Each item: `{ jsonPath?: string, xPath?: string, ' +
 										'regex?: string, hash?: string }`. Identifies WHICH ' +
 										'part of the response the matching `{{paramName}}` in ' +
-										'`responseMatches` actually redacts/extracts — e.g. ' +
+										'`responseMatches` actually redacts or extracts — for ' +
+										'example, ' +
 										'`jsonPath: "$.data.items[0].name"` for a JSON response. ' +
 										'Order/count should line up with `responseMatches`\' ' +
 										'placeholders one-to-one for a typical claim.',
@@ -475,17 +428,28 @@ export function createVersionFromCaptureTool(
 							'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 this to `HAWKEYE`/`MSWJS`/`XHOOK` ' +
-							'when you are ALSO supplying a `customInjection` script ' +
-							'that calls ' +
+							'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 if you ' +
-							'want to be certain no interception is configured — see ' +
-							'injection-api.md\'s "Recognizing this on a provider you ' +
-							'didn\'t author" section for what these values actually do. ' +
-							'Builder calls the equivalent concept `interceptorType` (no ' +
-							'`NONE` there — omitting the whole `interceptorOptions` ' +
-							'object is its no-interception signal instead).',
+							'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). What each value actually does: ' +
+							'how_it_works({ topic: "interception" }).',
+					},
+					disableRequestReplay: {
+						type: 'boolean',
+						description:
+							'Whether the page\'s own document/navigation request is ' +
+							'skipped (constructed locally) instead of genuinely replayed ' +
+							'through the interceptor. Defaults to `true` (disabled) when ' +
+							'omitted. Only meaningful for `injectionType` ' +
+							'HAWKEYE/MSWJS/XHOOK — pass `false` to enable real document ' +
+							'replay for those (for example, the target value is embedded ' +
+							'in the page\'s own HTML). Inert when `injectionType` is ' +
+							'`CDP` or ' +
+							'unset.',
 					},
 				},
 				required: ['initialUrl'],
@@ -529,9 +493,9 @@ export function createVersionFromCaptureTool(
 				// column default applies when omitted, same as before this field
 				// existed at all.
 				injectionType: args.injectionType,
-				// Always disabled — see the tool description above; there is no
-				// author-facing way to enable document replay.
-				disableRequestReplay: true,
+				// Author-settable; defaults to disabled (see tool description).
+				// Only meaningful for HAWKEYE/MSWJS/XHOOK — inert for CDP.
+				disableRequestReplay: args.disableRequestReplay ?? true,
 				allowedInjectedRequestData: args.allowedInjectedRequestData
 					? injectedRequestDataFrom(
 						args.allowedInjectedRequestData,
@@ -584,12 +548,12 @@ export function createVersionFromCaptureTool(
 					)
 				}
 
-				// disableRequestReplay is honored ONLY on add-version, and it's now
-				// always forced true — so every register is immediately followed by
-				// an add-version call that actually applies it (which also lands
-				// an explicit injectionType, when passed — unverified whether
-				// register persists it — and any other register-ignored fields the
-				// caller passed).
+				// disableRequestReplay is honored ONLY on add-version — so every
+				// register is immediately followed by an add-version call that
+				// actually applies it (whatever value — default or author-set;
+				// which also lands an explicit injectionType, when passed —
+				// unverified whether register persists it — and any other
+				// register-ignored fields the caller passed).
 				const REGISTER_IGNORED_KEYS = [
 					'allowedInjectedRequestData',
 					'useIncognitoWebview',
@@ -603,8 +567,8 @@ export function createVersionFromCaptureTool(
 						`${ignoredOnRegister.length > 1 ? 'are' : 'is'} ` +
 						'ignored on register (no providerId) — the devtools backend only ' +
 						'reads them when adding a version. They were applied by the ' +
-						'automatic follow-up version this tool always creates to ' +
-						'force-disable document replay.',
+						'automatic follow-up version this tool always creates to apply ' +
+						'disableRequestReplay.',
 					)
 				}
 
@@ -633,7 +597,7 @@ export function createVersionFromCaptureTool(
 						await client.updateProviderConfig(newProviderId, configBody)
 						notes.push(
 							`Created an automatic follow-up version (${followVersion}) to ` +
-							'force-disable document replay (disableRequestReplay)' +
+							`apply disableRequestReplay (${opts.disableRequestReplay})` +
 							(opts.injectionType !== undefined
 								? ` and set injectionType (${opts.injectionType})`
 								: '') +
@@ -657,7 +621,7 @@ export function createVersionFromCaptureTool(
 					}
 				} else {
 					notes.push(
-						'Could not force-disable document replay: the ' +
+						'Could not apply disableRequestReplay: the ' +
 						'register response did not include the new providerId. Call ' +
 						'this tool again WITH `providerId` to create a version that ' +
 						'applies them.',
@@ -668,7 +632,7 @@ export function createVersionFromCaptureTool(
 			}
 
 			// New version of an existing provider — pick the next patch above
-			// the highest existing version. A provider you don't own (e.g. a
+			// the highest existing version. A provider you don't own (for example, a
 			// public one) fails here with 401/403/404; surface the register-a-copy
 			// workaround instead of a bare permission error.
 			const providerId = args.providerId

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

@@ -8,7 +8,7 @@ import type { ReclaimOldClient, UpdateProviderMetadataBody } from '../client.ts'
  * `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
+ * re-supply `requestData`/`customInjection`, and so on, and
  * no new version is created).
  *
  * The backend 403s if you don't own the provider (and aren't an admin) —

package/src/old/tools/verify-sdk-setup.ts

@@ -122,7 +122,7 @@ export function verifySdkSetupTool(client: ReclaimOldClient): RegisteredTool {
 					: 'PUBLIC_URL not set — fine if you only read the proof from the ' +
 						'frontend flow, but the async webhook callback needs a ' +
 						'publicly-reachable URL or it will never fire. Get one via a ' +
-						'tunnel (e.g. `ngrok http <port>`) or by deploying to a ' +
+						'tunnel (for example, `ngrok http <port>`) or by deploying to a ' +
 						'dev/staging server you already have — ask the user which they ' +
 						'prefer.',
 			})

package/src/proof/attestor.ts

@@ -53,13 +53,13 @@ export interface RunAttestorProofOptions {
 	/** When resolving the key from env/.env/file, the address the caller expects
 	 *  to sign with (sanity check). Ignored when `ownerPrivateKey` is given. */
 	ownerAddress?: string
-	/** Sign with this key directly (e.g. the app/VC's ephemeral per-session key)
-	 *  instead of resolving from env/.env/file. */
+	/** Sign with this key directly (for example, the app or VC's ephemeral
+	 *  per-session key) instead of resolving from env/.env/file. */
 	ownerPrivateKey?: string
 	/** 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). */
+	 *  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 nested-proof construction. */

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

@@ -1,10 +1,10 @@
 // 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.
+// server-side re-fetch differs from what the browser (replay) saw — for
+// example, 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 +,

package/src/proof/index.ts

@@ -15,6 +15,14 @@ export {
 	parseClaim,
 	resolveAttestorUrl,
 } from './proof-core.ts'
+export {
+	type HttpParams,
+	type HttpSecretParams,
+	type PopcornProveOptions,
+	popcornProve,
+	popcornValidateExtraction,
+	type ValidateExtractionResult,
+} from './pod-prover.ts'
 export { ensureZkFiles } from './zk-files.ts'
 // Re-exported attestor-core claim primitive so the agent is the single
 // integration point with @reclaimprotocol/attestor-core across the builder.

package/src/proof/page-replay.ts

@@ -102,7 +102,7 @@ function authenticatedPageFetch(
  * (`authenticatedPageFetch`) so cookies are the real browser's, which a
  * detached call could never reproduce without manually re-deriving them.
  * WITH `withoutSecrets` (the auth-bound check — "does this still work with
- * no credentials, i.e. is it actually public"), replay instead through the
+ * no credentials, that is, is it actually public"), replay instead through the
  * detached Node-side `replayProvider`: the whole point of that check is to
  * prove NO secret rides along, and the live page's own global `fetch` can't
  * give that guarantee — a site (or a script installed via test_user_script)