@reclaimprotocol/agent 0.1.1-dev.1 → 0.1.1

package/src/old/to-register.ts

@@ -1,9 +1,16 @@
-import type { ReclaimProvider } from '../provider/schema.ts'
+import type { ReclaimProvider, ResponseRedaction } from '../provider/schema.ts'
 import type {
 	RegisterProviderBody,
 	UpdateProviderConfigBody,
 } from './client.ts'
 
+/** Default web settings, mirroring the builder openapi defaults
+ *  (`ProviderWebSettings.geoLocation`, `PortalClientOptions.useProxy`). The old
+ *  backend accepts both: `geoLocation` lives on the providerConfig, `useProxy`
+ *  is a Provider-level flag (register only). */
+const DEFAULT_GEO_LOCATION = '{{DYNAMIC_GEO}}'
+const DEFAULT_USE_PROXY = true
+
 /**
  * Translate a drafted `ReclaimProvider` (from `propose_provider`) into the
  * OLD devtools backend shapes. Deliberately a SEPARATE module from
@@ -22,7 +29,10 @@ import type {
 export interface OldProviderOpts {
 	initialUrl: string
 	description?: string
+	/** Defaults to `{{DYNAMIC_GEO}}` when omitted. */
 	geoLocation?: string
+	/** Defaults to `true` when omitted. Register only (Provider-level flag). */
+	useProxy?: boolean
 	providerType?: 'PRIVATE' | 'PUBLIC'
 }
 
@@ -63,6 +73,20 @@ function requestDataFromProvider(provider: ReclaimProvider): OldRequestData {
 		)
 	}
 
+	// The old backend has no dotted interpolation: consumer-supplied params
+	// must use the `{{context_<name>}}` form here, not the builder's
+	// `{{context.<name>}}`. Catch the mix-up at publish with a clear error
+	// instead of a template that silently never resolves.
+	const dotted = `${provider.url}\n${provider.body ?? ''}`
+		.match(/\{\{context\.[A-Za-z_][A-Za-z0-9_]*\}\}/)
+	if(dotted) {
+		throw new Error(
+			`Old devtools does not support ${dotted[0]} — rename ` +
+			'consumer-supplied params to the {{context_<name>}} form ' +
+			'for this backend.',
+		)
+	}
+
 	const responseMatches: OldResponseMatch[] = provider.responseMatches.map(
 		(m, i) => ({
 			value: m.value,
@@ -72,29 +96,40 @@ function requestDataFromProvider(provider: ReclaimProvider): OldRequestData {
 		}),
 	)
 
-	const responseRedactions: OldResponseRedaction[] = (
-		provider.responseRedactions ?? []
-	).map((r, i) => {
-		const out: OldResponseRedaction = { order: i }
-		if(r.xPath !== undefined) {
-			out.xPath = r.xPath
-		}
+	// Old devtools wants `responseMatches` and `responseRedactions` as PARALLEL
+	// arrays. A drafted provider may instead carry each redaction nested in its
+	// match's `extract` (the builder shape). Prefer the explicit parallel array;
+	// fall back to the nested `extract`s so redactions are never dropped.
+	const nestedRedactions = provider.responseMatches
+		.map((m) => (m as { extract?: ResponseRedaction }).extract)
+		.filter((e): e is ResponseRedaction => Boolean(e))
+	const sourceRedactions = provider.responseRedactions?.length
+		? provider.responseRedactions
+		: nestedRedactions
 
-		if(r.jsonPath !== undefined) {
-			out.jsonPath = r.jsonPath
-		}
+	const responseRedactions: OldResponseRedaction[] = sourceRedactions.map(
+		(r, i) => {
+			const out: OldResponseRedaction = { order: i }
+			if(r.xPath !== undefined) {
+				out.xPath = r.xPath
+			}
 
-		if(r.regex !== undefined) {
-			out.regex = r.regex
-		}
+			if(r.jsonPath !== undefined) {
+				out.jsonPath = r.jsonPath
+			}
 
-		// OPRF redactions are supported — pass the mode through unchanged.
-		if(r.hash !== undefined) {
-			out.hash = r.hash
-		}
+			if(r.regex !== undefined) {
+				out.regex = r.regex
+			}
 
-		return out
-	})
+			// OPRF redactions are supported — pass the mode through unchanged.
+			if(r.hash !== undefined) {
+				out.hash = r.hash
+			}
+
+			return out
+		},
+	)
 
 	const requestData: OldRequestData = {
 		url: provider.url,
@@ -127,16 +162,15 @@ export function providerToRegisterBody(
 		name: provider.name,
 		loginUrl: opts.initialUrl,
 		providerType: opts.providerType ?? 'PRIVATE',
+		// Web-settings defaults mirror the builder openapi defaults.
+		geoLocation: opts.geoLocation ?? DEFAULT_GEO_LOCATION,
+		useProxy: opts.useProxy ?? DEFAULT_USE_PROXY,
 		requestData: [requestDataFromProvider(provider)],
 	}
 	if(opts.description !== undefined) {
 		body.description = opts.description
 	}
 
-	if(opts.geoLocation !== undefined) {
-		body.geoLocation = opts.geoLocation
-	}
-
 	return body
 }
 
@@ -149,13 +183,14 @@ export function providerToConfigBody(
 	version: string,
 	versionInfo: string,
 ): UpdateProviderConfigBody {
+	// `useProxy` is a Provider-level flag on the old backend, not part of a
+	// version's providerConfig — so the config (new-version) path only carries
+	// `geoLocation`. It defaults the same way as register.
 	const providerConfig: Record<string, unknown> = {
 		loginUrl: opts.initialUrl,
+		geoLocation: opts.geoLocation ?? DEFAULT_GEO_LOCATION,
 		requestData: [requestDataFromProvider(provider)],
 	}
-	if(opts.geoLocation !== undefined) {
-		providerConfig.geoLocation = opts.geoLocation
-	}
 
 	return { providerConfig, version, versionInfo }
 }

package/src/old/tools/publish.ts

@@ -33,6 +33,7 @@ export function createVersionFromCaptureTool(
 		providerId?: string
 		description?: string
 		geoLocation?: string
+		useProxy?: boolean
 		providerType?: 'PRIVATE' | 'PUBLIC'
 		notes?: string
 	}>(
@@ -83,7 +84,18 @@ export function createVersionFromCaptureTool(
 						type: 'string',
 						description: 'Provider description (new-provider register only).',
 					},
-					geoLocation: { type: 'string' },
+					geoLocation: {
+						type: 'string',
+						description:
+							'Geo the verification appears to originate from. Defaults to ' +
+							"'{{DYNAMIC_GEO}}' (the user's geo) when omitted.",
+					},
+					useProxy: {
+						type: 'boolean',
+						description:
+							'Route portal/attestation traffic through a proxy. Defaults to ' +
+							'true when omitted. Applied on register only.',
+					},
 					providerType: { type: 'string', enum: ['PRIVATE', 'PUBLIC'] },
 					notes: {
 						type: 'string',
@@ -105,6 +117,10 @@ export function createVersionFromCaptureTool(
 				opts.geoLocation = args.geoLocation
 			}
 
+			if(args.useProxy !== undefined) {
+				opts.useProxy = args.useProxy
+			}
+
 			if(args.providerType !== undefined) {
 				opts.providerType = args.providerType
 			}

package/src/proof/attestor.ts

@@ -6,11 +6,15 @@
 // revealed slice; jsonPath/xPath live on responseRedactions (what the prover
 // reveals), never on responseMatches.
 
+import { bytesToHex } from '@noble/hashes/utils.js'
 import {
-	createClaimOnAttestor, type Logger, type ProviderParams,
+	createClaimOnAttestor, type Logger,
 } from '@reclaimprotocol/attestor-core'
-import { resolveOwnerPrivateKey } from '../mcp/tools/credentials/cache.ts'
+import { resolveEthKey } from '../mcp/tools/authenticate/eth-key.ts'
 import type { ReclaimProvider } from '../provider/schema.ts'
+import {
+	buildHttpParams, ensureAttestorCrypto, parseClaim, resolveAttestorUrl,
+} from './proof-core.ts'
 import { ensureZkFiles } from './zk-files.ts'
 
 export interface AttestorLogEntry {
@@ -19,6 +23,37 @@ export interface AttestorLogEntry {
 	ctx?: Record<string, unknown>
 }
 
+/** The attestor's signed claim data + signature, for building the nested proof
+ *  JWS a Consumer verifies against the attestor's key. Populated when
+ *  `includeAttestorClaim` is set (the app's verification runner needs it; the
+ *  MCP `run_proof` tool ignores it). */
+export interface AttestorClaim {
+	/** ProviderClaimData: provider, parameters, context (JSON string), owner,
+	 *  timestampS, epoch, identifier. */
+	claim: Record<string, unknown>
+	/** Hex (0x) attestor ETH address that signed the claim (the nested `kid`). */
+	attestorAddress: string
+	/** Hex (0x) attestor claim signature (EIP-191 over the claim sign-data). */
+	claimSignature: string
+}
+
+/** Options for {@link runAttestorProof}. */
+export interface RunAttestorProofOptions {
+	attestorUrl?: string
+	/** 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. */
+	ownerPrivateKey?: string
+	/** ZK engine for `createClaimOnAttestor`. Defaults to `'gnark'`; the app's
+	 *  server-side verification runner uses `'snarkjs'`. */
+	zkEngine?: 'gnark' | 'snarkjs'
+	/** Extract the structured {@link AttestorClaim} (claim + attestor signature)
+	 *  onto the result for nested-proof construction. */
+	includeAttestorClaim?: boolean
+}
+
 export interface ProofResult {
 	proof: unknown
 	extractedValue: string
@@ -27,6 +62,9 @@ export interface ProofResult {
 	owner?: string
 	verified: boolean
 	error?: string
+	/** Structured claim + signature for nested-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
 	 *  sign with — distinguishes this recoverable case from other proof
 	 *  errors so the skill can point the dev at `issue_credentials` /
@@ -139,16 +177,6 @@ function makeCaptureLogger(): {
 	return { logger: make({}), entries }
 }
 
-/** Default public attestor websocket URL. Resolved per-call so an env-var
- *  change or per-request override takes effect without restarting the
- *  MCP server. */
-const FALLBACK_ATTESTOR_URL = 'wss://attestor.reclaimprotocol.org:444/ws'
-function resolveAttestorUrl(override?: string): string {
-	return (
-		override ?? process.env['RECLAIM_ATTESTOR_URL'] ?? FALLBACK_ATTESTOR_URL
-	)
-}
-
 // ---------------------------------------------------------------------------
 // Main entry point
 // ---------------------------------------------------------------------------
@@ -156,45 +184,60 @@ function resolveAttestorUrl(override?: string): string {
 export async function runAttestorProof(
 	provider: ReclaimProvider,
 	secrets: Record<string, string>,
-	attestorUrl?: string,
-	ownerAddress?: string,
+	opts: RunAttestorProofOptions = {},
 ): Promise<ProofResult> {
-	// The owner is chosen up front (resolve_owner_key) and passed as
-	// `ownerAddress`; here we just fetch its private key and sign.
-	const ownerPrivateKey = ownerAddress
-		? resolveOwnerPrivateKey(ownerAddress)
-		: undefined
-	if(!ownerPrivateKey) {
-		return {
-			proof: undefined,
-			extractedValue: '',
-			extractedParameters: {},
-			verified: false,
-			error:
-				`No private key available for ownerAddress "${ownerAddress ?? ''}". ` +
-				'Call resolve_owner_key to pick a credential (or ' +
-				'issue_credentials / import_credentials to set one up), then ' +
-				'retry run_proof with its address as ownerAddress.',
-			errorKind: 'missing-owner-key',
+	// Sign with the caller-supplied key (the app/VC's ephemeral per-session
+	// key) when given; otherwise resolve env/.env/file. `ownerAddress` is a
+	// sanity check on the resolved key (ignored when a key is supplied).
+	let ownerPrivateKey: string
+	if(opts.ownerPrivateKey) {
+		ownerPrivateKey = opts.ownerPrivateKey
+	} else {
+		const resolved = resolveEthKey()
+		if(!resolved) {
+			return {
+				proof: undefined,
+				extractedValue: '',
+				extractedParameters: {},
+				verified: false,
+				error:
+					'No eth proof-owner key available (no RECLAIM_PRIVATE_KEY in env, ' +
+					'.env, or RECLAIM_PRIVATE_KEY_FILE). Call resolve_owner_key, then ' +
+					'issue_credentials (generate) or import_credentials (provide one), ' +
+					'and retry run_proof.',
+				errorKind: 'missing-owner-key',
+			}
 		}
+
+		if(
+			opts.ownerAddress
+			&& opts.ownerAddress.toLowerCase() !== resolved.address
+		) {
+			return {
+				proof: undefined,
+				extractedValue: '',
+				extractedParameters: {},
+				verified: false,
+				error:
+					`Requested ownerAddress "${opts.ownerAddress}" does not match ` +
+					`the resolved eth key (${resolved.address}, source: ` +
+					`${resolved.source}). ` +
+					'Call resolve_owner_key to get the current address, or update the ' +
+					'configured key.',
+				errorKind: 'missing-owner-key',
+			}
+		}
+
+		ownerPrivateKey = resolved.privateKey
 	}
 
 	try {
-		// Circuits aren't downloaded at install time (that blocked the MCP
-		// server's first launch). Fetch them lazily on the first proof.
+		// Init the TLS crypto backend (idempotent), then fetch ZK circuits
+		// lazily on the first proof (not at install time).
+		ensureAttestorCrypto()
 		await ensureZkFiles()
 
-		const params: ProviderParams<'http'> = {
-			url: provider.url,
-			method: provider.method,
-			...(provider.headers !== undefined && { headers: provider.headers }),
-			...(provider.body !== undefined && { body: provider.body }),
-			responseMatches: provider.responseMatches,
-			responseRedactions: provider.responseRedactions ?? [],
-			...(provider.paramValues !== undefined && {
-				paramValues: provider.paramValues,
-			}),
-		}
+		const params = buildHttpParams(provider)
 
 		// Diagnostic logger capture is gated behind RECLAIM_AGENT_TRACE so the
 		// happy path doesn't pay the cost (the attestor SDK emits a *lot* of
@@ -214,8 +257,8 @@ export async function runAttestorProof(
 					headers: secrets,
 				},
 				ownerPrivateKey,
-				client: { url: resolveAttestorUrl(attestorUrl) },
-				zkEngine: 'snarkjs',
+				client: { url: resolveAttestorUrl(opts.attestorUrl) },
+				zkEngine: opts.zkEngine ?? 'gnark',
 				...(capture !== undefined && { logger: capture.logger as Logger }),
 			})
 		} catch(err) {
@@ -234,27 +277,8 @@ export async function runAttestorProof(
 			return errorResult
 		}
 
-		// ClaimTunnelResponse carries the claim under `.claim`.
-		const claimRecord = claim as Record<string, unknown>
-		const claimData =
-			claimRecord['claim'] as Record<string, unknown> | undefined
-
-		// claimData.context is a JSON-encoded string carrying
-		// { extractedParameters: {...}, providerHash, ... }.
-		let context: Record<string, unknown> = {}
-		const rawContext = claimData?.['context']
-		if(typeof rawContext === 'string') {
-			try {
-				context = JSON.parse(rawContext) as Record<string, unknown>
-			} catch{
-				// Leave context empty if it isn't valid JSON.
-			}
-		}
-
-		const extractedParameters =
-			(context['extractedParameters'] as Record<string, string> | undefined) ??
-			{}
-		const extractedValue = Object.values(extractedParameters)[0] ?? ''
+		const { extractedValue, extractedParameters, identifier, owner, claimData }
+			= parseClaim(claim)
 
 		const result: ProofResult = {
 			proof: claim,
@@ -262,16 +286,33 @@ export async function runAttestorProof(
 			extractedParameters,
 			verified: true,
 		}
-		const identifier = claimData?.['identifier']
-		if(typeof identifier === 'string') {
+		if(identifier !== undefined) {
 			result.identifier = identifier
 		}
 
-		const owner = claimData?.['owner']
-		if(typeof owner === 'string') {
+		if(owner !== undefined) {
 			result.owner = owner
 		}
 
+		// Structured claim + signature so the result JWS can carry a nested,
+		// attestor-signed proof the Consumer verifies independently.
+		if(opts.includeAttestorClaim) {
+			const sigs = (claim as {
+				signatures?: { attestorAddress?: unknown, claimSignature?: unknown }
+			}).signatures
+			if(
+				claimData
+				&& typeof sigs?.attestorAddress === 'string'
+				&& sigs.claimSignature instanceof Uint8Array
+			) {
+				result.attestorClaim = {
+					claim: claimData,
+					attestorAddress: sigs.attestorAddress,
+					claimSignature: '0x' + bytesToHex(sigs.claimSignature),
+				}
+			}
+		}
+
 		// Only set when RECLAIM_AGENT_TRACE=1. Full stream — the MCP layer
 		// trims for the LLM-visible response; the on-disk dump gets it all.
 		if(attestorLogs !== undefined && attestorLogs.length > 0) {

package/src/proof/index.ts

@@ -0,0 +1,21 @@
+// Proof primitives shared with the app's verification runner: the attestor
+// param/claim plumbing, the ZK-file bootstrap, and the agent's own
+// `runAttestorProof`. Exposed as `@reclaimprotocol/agent/proof`.
+export type {
+	AttestorClaim,
+	AttestorLogEntry,
+	ProofResult,
+	RunAttestorProofOptions,
+} from './attestor.ts'
+export { runAttestorProof, tailLogs, warnsAndErrors } from './attestor.ts'
+export {
+	buildHttpParams,
+	ensureAttestorCrypto,
+	type ParsedClaim,
+	parseClaim,
+	resolveAttestorUrl,
+} from './proof-core.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.
+export { createClaimOnAttestor } from '@reclaimprotocol/attestor-core'

package/src/proof/proof-core.ts

@@ -0,0 +1,109 @@
+/**
+ * Shared attestor-claim plumbing used by both proof callers: the agent's MCP
+ * `run_proof` (which resolves the owner key from the credential cache and
+ * captures trace logs) and the app's verification runner (which signs with an
+ * ephemeral per-session key and builds a nested-proof claim). Only those
+ * concerns differ — building the HTTP params, resolving the attestor URL, and
+ * parsing the claim response are identical, so they live here.
+ */
+import type { ProviderParams } from '@reclaimprotocol/attestor-core'
+import { setCryptoImplementation } from '@reclaimprotocol/tls'
+import { webcryptoCrypto } from '@reclaimprotocol/tls/webcrypto'
+import type { ReclaimProvider } from '../provider/schema.ts'
+
+const FALLBACK_ATTESTOR_URL = 'wss://attestor.reclaimprotocol.org:444/ws'
+
+let cryptoInitialized = false
+
+/** One-time crypto backend init for `@reclaimprotocol/tls` (idempotent). The
+ *  package ships with an empty `crypto = {}` and defers the backend to the
+ *  caller; without this the first proof dies inside the TLS client with
+ *  `crypto.randomBytes is not a function`. Shared by every attestor caller —
+ *  the agent MCP `run_proof` tool and the app's verification runner. */
+export function ensureAttestorCrypto(): void {
+	if(cryptoInitialized) {
+		return
+	}
+
+	setCryptoImplementation(webcryptoCrypto)
+	cryptoInitialized = true
+}
+
+/** Resolve the attestor websocket URL: explicit override → env → public
+ *  default. Resolved per-call so an env change or per-request override takes
+ *  effect without restarting. */
+export function resolveAttestorUrl(override?: string): string {
+	return (
+		override ?? process.env['RECLAIM_ATTESTOR_URL'] ?? FALLBACK_ATTESTOR_URL
+	)
+}
+
+/** Map a verification's provider recipe straight to the attestor's HTTP
+ *  params — never synthesized from captured traffic. */
+export function buildHttpParams(
+	provider: ReclaimProvider,
+): ProviderParams<'http'> {
+	return {
+		url: provider.url,
+		method: provider.method,
+		...(provider.headers !== undefined && { headers: provider.headers }),
+		...(provider.body !== undefined && { body: provider.body }),
+		responseMatches: provider.responseMatches,
+		responseRedactions: provider.responseRedactions ?? [],
+		...(provider.paramValues !== undefined && {
+			paramValues: provider.paramValues,
+		}),
+	}
+}
+
+export interface ParsedClaim {
+	/** ProviderClaimData: provider, parameters, context, owner, identifier, … */
+	claimData?: Record<string, unknown>
+	extractedParameters: Record<string, string>
+	extractedValue: string
+	identifier?: string
+	owner?: string
+}
+
+/** 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. */
+export function parseClaim(claim: unknown): ParsedClaim {
+	const claimRecord = claim as Record<string, unknown>
+	const claimData = claimRecord['claim'] as Record<string, unknown> | undefined
+
+	// claimData.context is a JSON-encoded string carrying
+	// { extractedParameters: {...}, providerHash, ... }.
+	let context: Record<string, unknown> = {}
+	const rawContext = claimData?.['context']
+	if(typeof rawContext === 'string') {
+		try {
+			context = JSON.parse(rawContext) as Record<string, unknown>
+		} catch{
+			// Leave context empty if it isn't valid JSON.
+		}
+	}
+
+	const extractedParameters =
+		(context['extractedParameters'] as Record<string, string> | undefined) ?? {}
+
+	const parsed: ParsedClaim = {
+		extractedParameters,
+		extractedValue: Object.values(extractedParameters)[0] ?? '',
+	}
+	if(claimData) {
+		parsed.claimData = claimData
+	}
+
+	const identifier = claimData?.['identifier']
+	if(typeof identifier === 'string') {
+		parsed.identifier = identifier
+	}
+
+	const owner = claimData?.['owner']
+	if(typeof owner === 'string') {
+		parsed.owner = owner
+	}
+
+	return parsed
+}

package/src/provider/index.ts

@@ -0,0 +1,20 @@
+// Provider primitives shared with the app's capture pipeline:
+// the attestor-derived recipe types, secret classification, and the GraphQL
+// op parser. Exposed as `@reclaimprotocol/agent/provider`.
+export { extractGraphqlOp, looksLikeGraphqlEndpoint } from './graphql.ts'
+export type {
+	CapturedRequest,
+	HttpMethod,
+	OprfMode,
+	ReclaimProvider,
+	RequestConcern,
+	ResponseMatch,
+	ResponseRedaction,
+	SecretParamRef,
+} from './schema.ts'
+export { classifyHeader, splitSecrets } from './secrets.ts'
+// Re-exported attestor-core provider primitives (the registry, the param hash,
+// and the param type) so the builder imports them via the agent rather than
+// depending on @reclaimprotocol/attestor-core directly.
+export { hashProviderParams, providers } from '@reclaimprotocol/attestor-core'
+export type { ProviderParams } from '@reclaimprotocol/attestor-core'