@reclaimprotocol/client 0.1.34 → 0.1.36

package/src/request-proof.ts

@@ -1,5 +1,6 @@
 import { createSignDataForClaim } from '@reclaimprotocol/attestor-core'
 import { recoverEip191Address } from './eip191.ts'
+import { isTransientFailure, networkStep } from './errors.ts'
 import { fetchReclaimJwks, trustedAttestorAddresses } from './jwks.ts'
 import { assertValidProofHashes, getHashFromProof } from './proof-hash.ts'
 import type {
@@ -41,9 +42,15 @@ export interface VerifyRequestProofOptions {
 	/** Read `providerHash` from context, while still verifying signatures. */
 	hasNoPii?: true
 	teeAttestation?: TeeAttestationConfig
+	/** Require every witness to carry a `claimAttestation`, and verify any
+	 *  `attestation_report` against `expectedImageDigests`. */
 	attestorTeeAttestation?: AttestorTeeAttestationConfig
 	/** Explicit trusted attestor ETH addresses. */
 	attestorAddresses?: string[]
+	/** Trusted attestor image digests, like `x-reclaim-attestor-image-digests`.
+	 *  Pin any `attestation_report` a witness carries without requiring one,
+	 *  matching `@reclaimprotocol/js-sdk`'s default. */
+	attestorImageDigests?: string[]
 	/** Trusted Builder JWKS registry containing attestor-purpose keys. */
 	attestorJwksUrl?: string
 	fetchImpl?: typeof fetch
@@ -70,6 +77,10 @@ export interface VerifyRequestProofOptions {
 export interface ReclaimRequestProofOutcome {
 	valid: boolean
 	reason?: string
+	/** On failure: true when a temporary condition caused it, such as a
+	 *  network error while resolving the session or provider. A retry can
+	 *  succeed. */
+	transient?: boolean
 	proofHashes?: string[]
 	isTeeAttestationVerified?: boolean
 	/** True when at least one witness's `attestation_report` verified; false
@@ -116,6 +127,8 @@ export async function verifyRequestProof(
 			trust.imageDigests,
 		)
 		if(attestorTeeAttestation) {
+			// Only a caller-configured check requires an envelope on every
+			// witness; registry digests alone pin the reports that exist.
 			// `verified` counts witnesses whose attestation report was checked.
 			// A proof whose witnesses carry no report still passes the address
 			// and signature bindings, but nothing was attested — say so rather
@@ -123,6 +136,7 @@ export async function verifyRequestProof(
 			const summary = await runAttestorTeeVerification(
 				proofs,
 				attestorTeeAttestation,
+				{ requireClaimAttestation: !!effective.attestorTeeAttestation },
 			)
 			isAttestorTeeAttestationVerified = summary.verified > 0
 		}
@@ -139,6 +153,7 @@ export async function verifyRequestProof(
 		return {
 			valid: false,
 			reason: failureReason(error),
+			transient: isTransientFailure(error),
 		}
 	}
 }
@@ -148,14 +163,15 @@ async function resolveValidation(
 	proofs: ReclaimRequestProof[],
 ) {
 	let effective = config
-	if(config.sessionId && !hasContentValidation(config)) {
-		if(!config.resolveSession) {
+	const { sessionId, resolveSession } = config
+	if(sessionId && !hasContentValidation(config)) {
+		if(!resolveSession) {
 			throw new Error('session-resolver-required')
 		}
 
 		effective = {
 			...config,
-			...await config.resolveSession(config.sessionId, proofs),
+			...await networkStep(() => resolveSession(sessionId, proofs)),
 		}
 	}
 
@@ -164,12 +180,12 @@ async function resolveValidation(
 
 async function resolveAttestorTrust(config: VerifyRequestProofOptions) {
 	const addresses = config.attestorAddresses?.map(normalized) ?? []
-	const imageDigests: string[] = []
-	if(config.attestorJwksUrl) {
-		const registry = await fetchReclaimJwks(
-			config.attestorJwksUrl,
-			config.fetchImpl,
-		)
+	const imageDigests = config.attestorImageDigests?.map(normalized) ?? []
+	const { attestorJwksUrl, fetchImpl } = config
+	if(attestorJwksUrl) {
+		const registry = await networkStep(() => (
+			fetchReclaimJwks(attestorJwksUrl, fetchImpl)
+		))
 		addresses.push(
 			...(registry['x-reclaim-attestors'] ?? []),
 			...trustedAttestorAddresses(registry.keys),
@@ -258,17 +274,15 @@ async function assertContent(
 		return
 	}
 
-	if(config.providerId) {
-		if(!config.resolveProvider) {
+	const { providerId, providerVersion, allowedTags, resolveProvider } = config
+	if(providerId) {
+		if(!resolveProvider) {
 			throw new Error('provider-resolver-required')
 		}
 
-		const candidates = await config.resolveProvider(
-			config.providerId,
-			config.providerVersion,
-			config.allowedTags,
-			proofs,
-		)
+		const candidates = await networkStep(() => (
+			resolveProvider(providerId, providerVersion, allowedTags, proofs)
+		))
 		if(!candidates.length) {
 			throw new Error('provider-not-found')
 		}

package/src/result.ts

@@ -20,6 +20,7 @@ import {
 	hexToBytes,
 	stripTrailingSlashes,
 } from './encoding.ts'
+import { isTransientError } from './errors.ts'
 import {
 	fetchReclaimJwks,
 	type Jwk,
@@ -303,6 +304,9 @@ export interface ResultProofOutcome {
 	proof?: ReclaimRequestProof
 	proofValid: boolean
 	reason?: string
+	/** On failure: true when a temporary condition caused it, such as a
+	 *  network error while resolving the provider. */
+	transient?: boolean
 	/** @deprecated Use `attestorAddresses`; retained for compatibility. */
 	attestorAddress?: string
 	/** Every attestor address declared by the proof. */
@@ -330,12 +334,18 @@ export interface VerifyResultFullOutcome extends VerifyResultOutcome {
 
 export interface ResultVerificationFailure extends VerifyResultFullOutcome {
 	reason: string
+	/** True when a temporary condition caused the failure. Set by the
+	 *  verifier; read it as {@link ResultVerificationError.retryable}. */
+	retryable?: boolean
 }
 
 /**
  * Thrown by {@link verifyResult} / {@link verifyResultFull} (and therefore
  * `reclaim.results.verify`/`receive`) when a result fails verification. Carries
- * the full invalid outcome so callers can inspect it in a `catch`:
+ * the full invalid outcome so callers can inspect it in a `catch`.
+ *
+ * In a callback handler, answer 2xx when `retryable` is `false` (Builder
+ * retrying the same delivery can't help) and 5xx when it's `true`:
  *
  *   try {
  *     const { result } = await reclaim.results.receive(body, {
@@ -346,6 +356,7 @@ export interface ResultVerificationFailure extends VerifyResultFullOutcome {
  *     if (err instanceof ResultVerificationError) {
  *       // for example, 'expired', { payload, … }
  *       console.error(err.reason, err.outcome)
+ *       res.sendStatus(err.retryable ? 503 : 200)
  *     }
  *   }
  */
@@ -356,12 +367,22 @@ export class ResultVerificationError extends Error {
 	/** The full (invalid) outcome: `payload`, `reclaimSessionId`, and per-proof
 	 *  detail (`proofs`) when verification got that far. */
 	readonly outcome: ResultVerificationFailure
+	/**
+	 * Whether a retry can succeed. `true` only for a temporary condition on
+	 * the verifier's side: Builder's JWKS or recipe couldn't be fetched
+	 * (network error, timeout, 5xx, 429). `false` when the result itself is
+	 * wrong (signature, issuer, audience, session, expiry, invalid proof), so
+	 * redelivering the same body fails the same way. Respond 5xx to a
+	 * callback only when `true`.
+	 */
+	readonly retryable: boolean
 
 	constructor(outcome: ResultVerificationFailure) {
 		super(`result verification failed: ${outcome.reason}`)
 		this.name = 'ResultVerificationError'
 		this.reason = outcome.reason
 		this.outcome = outcome
+		this.retryable = outcome.retryable ?? false
 	}
 }
 
@@ -446,8 +467,10 @@ export async function verifyResultFull(
 			jwksAttestorAddresses = registry['x-reclaim-attestors'] ?? []
 			jwksAttestorImageDigests =
 				registry['x-reclaim-attestor-image-digests'] ?? []
-		} catch{
-			return fail('jwks-fetch-failed')
+		} catch(error) {
+			return fail('jwks-fetch-failed', {
+				retryable: isTransientError(error),
+			})
 		}
 
 		const jwk = selectVerificationResultKey(
@@ -594,7 +617,12 @@ export async function verifyResultFull(
 			expectedImageDigests = configuredImageDigests
 		}
 
-		const attestorTeeAttestation = expectedImageDigests.length
+		// A caller-configured check requires a `claimAttestation` on every
+		// witness. Registry digests alone only pin the attestor reports that
+		// are present, as `@reclaimprotocol/js-sdk` does by default — a portal
+		// TEE proof without a bound nonce carries no envelope.
+		const attestorTeeAttestation = configuredAttestorTee
+			&& expectedImageDigests.length
 			? { ...configuredAttestorTee, expectedImageDigests }
 			: configuredAttestorTee
 		const commonValidation = {
@@ -606,6 +634,9 @@ export async function verifyResultFull(
 			...(attestorTeeAttestation
 				? { attestorTeeAttestation }
 				: {}),
+			...(expectedImageDigests.length
+				? { attestorImageDigests: expectedImageDigests }
+				: {}),
 			...(expectedSessionId
 				? {
 					expectedSessionId,
@@ -622,7 +653,12 @@ export async function verifyResultFull(
 	}
 
 	if(!proofs.every((p) => p.proofValid)) {
-		return fail('invalid-proof', { proofs })
+		// Retry only when every failure is transient; one genuinely invalid
+		// proof makes redelivery pointless.
+		return fail('invalid-proof', {
+			proofs,
+			retryable: proofs.every((p) => p.proofValid || p.transient),
+		})
 	}
 
 	return { payload, reclaimSessionId, proofs }
@@ -666,6 +702,7 @@ export async function verifyResultFull(
 		for(const { outcomeIndex } of group) {
 			proofs[outcomeIndex].proofValid = false
 			proofs[outcomeIndex].reason = requestProofOutcome.reason
+			proofs[outcomeIndex].transient = requestProofOutcome.transient
 		}
 	}
 
@@ -678,8 +715,11 @@ export async function verifyResultFull(
 			try {
 				const resolved = await opts.resolveSession(expectedSessionId)
 				recipes = resolved.recipes
-			} catch{
-				return fail('session-resolution-failed', { proofs })
+			} catch(error) {
+				return fail('session-resolution-failed', {
+					proofs,
+					retryable: isTransientError(error),
+				})
 			}
 		}
 

package/src/routes.gen.ts

@@ -1,11 +1,12 @@
 // AUTO-GENERATED by packages/app/scripts/mcp-tools-gen.ts
-// from packages/app/openapi.yaml (spec v0.1.0, source sha256:e2db795ab15c).
+// from packages/app/openapi.yaml (spec v0.1.0, source sha256:96339e8dff91).
 // The hash catches drift the version misses (a spec can change without a
 // version bump) — do not remove it as "redundant" with the version.
 // Run `npm run openapi:gen --workspace=packages/app` to regenerate. Do not edit by hand.
 
 export const ROUTES = {
 	"AcceptOrgInvite": {"method":"post","path":"/orgs/{orgId}/invite"},
+	"AcknowledgeCallbackEvents": {"method":"post","path":"/verifications/callback-events/acknowledge"},
 	"AddOrgMember": {"method":"post","path":"/orgs/{orgId}/members"},
 	"AddProviderContributionComment": {"method":"post","path":"/providers/{providerId}/contributions/{campaignId}/comments"},
 	"AddStaffMember": {"method":"post","path":"/admin/staff"},
@@ -28,6 +29,7 @@ export const ROUTES = {
 	"AdminUsers": {"method":"get","path":"/admin/users"},
 	"AdminVerificationClients": {"method":"get","path":"/admin/verification-clients"},
 	"AdminVoidOrgCredit": {"method":"post","path":"/admin/orgs/{orgId}/credits/{grantId}/void"},
+	"AgentInstallationMarkdown": {"method":"get","path":"/docs/agent-installation.md"},
 	"AppleAppSiteAssociation": {"method":"get","path":"/.well-known/apple-app-site-association"},
 	"AssetLinksJson": {"method":"get","path":"/.well-known/assetlinks.json"},
 	"BindVerificationSessionTeeNonce": {"method":"put","path":"/verifications/sessions/{sessionId}/tee-nonce"},
@@ -103,6 +105,7 @@ export const ROUTES = {
 	"JwksJson": {"method":"get","path":"/.well-known/jwks.json"},
 	"ListBillingPlans": {"method":"get","path":"/billing/plans"},
 	"ListCallbackDlq": {"method":"get","path":"/verifications/callback-dlq"},
+	"ListCallbackEvents": {"method":"get","path":"/verifications/callback-events"},
 	"ListCallbackSubscriptions": {"method":"get","path":"/verifications/callback-subscriptions"},
 	"ListFeatureFlagRevisions": {"method":"get","path":"/admin/feature-flags/{flagKey}/revisions"},
 	"ListOrgCallbackSubscriptions": {"method":"get","path":"/orgs/{orgId}/callback-subscriptions"},
@@ -129,6 +132,7 @@ export const ROUTES = {
 	"PublishProviderVersion": {"method":"post","path":"/providers/{providerId}/versions/{version}/publish"},
 	"RefreshBillingPlans": {"method":"post","path":"/admin/billing/plans/refresh"},
 	"RefundTransaction": {"method":"post","path":"/admin/billing/transactions/{txId}/refund"},
+	"ReleaseCallbackListener": {"method":"post","path":"/verifications/callback-listener/release"},
 	"RemoveOrgMember": {"method":"delete","path":"/orgs/{orgId}/members/{memberId}"},
 	"RemoveStaffMember": {"method":"delete","path":"/admin/staff/{email}"},
 	"ReportClaimant": {"method":"post","path":"/v/{sessionId}/claimant"},