@reclaimprotocol/client 0.1.27 → 0.1.29

package/src/proof-recipe.ts

@@ -0,0 +1,75 @@
+import type { components } from './types/openapi.gen.ts'
+import {
+	hashRequirementsFromSpecs,
+	type ProofRequestSpec,
+} from './proof-hash.ts'
+import type { LegacyProof } from './proof-types.ts'
+
+type RequestSelection = components['schemas']['RequestSelection']
+type RequestSelectionTemplate =
+	components['schemas']['RequestSelectionTemplate']
+
+/** Resolved Builder provider recipe returned for a verification session. */
+export interface BuilderProofRecipe {
+	providerId: string
+	resolvedVersion: string
+	initialUrl: string
+	requests: RequestSelection[]
+	allowedJsRequests?: RequestSelectionTemplate[]
+}
+
+/**
+ * Derive the exact hash requirements consumed by legacy `verifyProof` from a
+ * resolved Builder recipe. Builder's fixed requests are required once each.
+ */
+export function proofHashesFromBuilderRecipe(
+	recipe: BuilderProofRecipe,
+	proofs: LegacyProof[],
+) {
+	return hashRequirementsFromSpecs(
+		recipe.requests.map((request) => toRequestSpec(
+			request,
+			{ required: true, multiple: false },
+		)),
+		(recipe.allowedJsRequests ?? []).map(
+			(request) => toRequestSpec(request, {
+				required: request.required,
+				multiple: request.multiple,
+				templateParams: request.templateParams,
+				templateParamsMode: request.templateParamsMode,
+			}),
+		),
+		proofs,
+	)
+}
+
+function toRequestSpec(
+	request: RequestSelection | RequestSelectionTemplate,
+	flags: Pick<
+		ProofRequestSpec,
+		'required' | 'multiple' | 'templateParams' | 'templateParamsMode'
+	>,
+): ProofRequestSpec {
+	return {
+		url: request.url,
+		urlType: request.url.includes('{{') ? 'TEMPLATE' : 'CONSTANT',
+		method: request.method,
+		bodySniff: {
+			enabled: request.requestBodyTemplate !== undefined,
+			template: request.requestBodyTemplate ?? '',
+		},
+		responseMatches: (request.responseMatches ?? []).map((match) => ({
+			type: match.type,
+			value: match.value,
+			invert: undefined,
+			isOptional: match.isOptional,
+		})),
+		responseRedactions: (request.responseRedactions ?? []).map((redaction) => ({
+			...(redaction.hash ? { hash: redaction.hash } : {}),
+			jsonPath: redaction.jsonPath ?? '',
+			regex: redaction.regex ?? '',
+			xPath: redaction.xPath ?? '',
+		})),
+		...flags,
+	}
+}

package/src/proof-trust-constants.ts

@@ -0,0 +1,45 @@
+/* eslint-disable @stylistic/max-len */
+// GCP Confidential Space Root CA — pinned. Rotates infrequently
+// (current cert valid 2024-2034). Used to verify attestor TEE attestation JWTs.
+export const GCP_CONFIDENTIAL_SPACE_ROOT_CA = `-----BEGIN CERTIFICATE-----
+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
+uyT5CnJulxSC5CT1
+-----END CERTIFICATE-----`
+
+// Matches an `attestor_public_key:0x<40-hex>` entry in a GCP Confidential
+// Space attestation JWT's `eat_nonce` claim.
+export const ATTESTOR_NONCE_PATTERN = /^attestor_public_key:0x([0-9a-fA-F]{40})$/
+
+// Expected `iss` claim on GCP Confidential Space attestation JWTs.
+export const GCP_CONFIDENTIAL_SPACE_ISSUER = 'https://confidentialcomputing.googleapis.com'

package/src/proof-types.ts

@@ -0,0 +1,57 @@
+/** Exact legacy proof structures carried inside Builder result envelopes. */
+export interface LegacyProof {
+	identifier: string
+	claimData: LegacyClaimData
+	signatures: string[]
+	witnesses: LegacyWitness[]
+	extractedParameterValues: unknown
+	publicData?: unknown
+	taskId?: number
+	teeAttestation?: TeeAttestation | string
+}
+
+export interface LegacyClaimData {
+	provider: string
+	parameters: string
+	owner: string
+	timestampS: number
+	context: string
+	identifier: string
+	epoch: number
+}
+
+export interface LegacyWitness {
+	id: string
+	url: string
+	claimAttestation?: AttestorClaimAttestation
+}
+
+export interface AttestorClaimAttestation {
+	attestor_address: string
+	claim_signature: string
+	attestation_report: string
+}
+
+export interface TeeAttestation {
+	proof_version?: 'v2' | 'v3'
+	proofVersion?: 'v2' | 'v3'
+	tee_provider: string
+	tee_technology: string
+	nonce: string
+	timestamp: string
+	workload: { container_name?: string, image_digest: string }
+	verifier: { container_name?: string, image_digest: string }
+	attestation: { token: string }
+	error?: { code: string, message: string }
+}
+
+export interface TrustedData {
+	context: Record<string, unknown>
+	extractedParameters: Record<string, string>
+}
+
+export interface HashRequirement {
+	value: string | string[]
+	required?: boolean
+	multiple?: boolean
+}

package/src/proof-verification-error.ts

@@ -0,0 +1,13 @@
+export function legacyErrorClass(name: string) {
+	return class extends Error {
+		readonly innerError?: unknown
+
+		constructor(message?: string, innerError?: unknown) {
+			super(innerError
+				? `${message ?? ''} caused by ${String(innerError)}`
+				: message)
+			this.name = name
+			this.innerError = innerError
+		}
+	}
+}

package/src/reclaim.ts

@@ -28,6 +28,10 @@ import {
 	type DecryptionKeyInput,
 	loadDecryptionKey,
 } from './enckeys.ts'
+import { isProblemError } from './errors.ts'
+import type { BuilderProofRecipe } from './proof-recipe.ts'
+import { proofHashesFromBuilderRecipe } from './proof-recipe.ts'
+import type { LegacyProof } from './proof-types.ts'
 import {
 	type CallbackBody,
 	decryptCallback,
@@ -36,6 +40,10 @@ import {
 	type VerifyResultFullOptions,
 	type VerifyResultFullOutcome,
 } from './result.ts'
+import {
+	createBuilderTeeBinding,
+	type LegacyTeeNonceMode,
+} from './tee-binding.ts'
 
 type CallbackSubscription = components['schemas']['CallbackSubscription']
 type VerificationSession = components['schemas']['VerificationSession']
@@ -44,11 +52,19 @@ type VerificationEventRecord = components['schemas']['VerificationEventRecord']
 type OrgKeypair = components['schemas']['OrgKeypair']
 type OrgKeypairRequest = components['schemas']['OrgKeypairRequest']
 
-/** The three terminal events a subscription can receive. */
+/** Terminal lifecycle events selected by default for callback subscriptions. */
 export const TERMINAL_EVENTS = [
 	'verification_success',
 	'verification_rejected',
 	'verification_error',
+	'verification_cancelled',
+	'session_expired',
+] as const
+
+const SIGNED_RESULT_EVENTS = [
+	'verification_success',
+	'verification_rejected',
+	'verification_error',
 ] as const
 
 export interface RegisterCallbackInput {
@@ -61,8 +77,25 @@ export interface CreateSessionInput {
 	 *  session) and one combined result is delivered; all are required. */
 	providers: { providerId: string, version?: string }[]
 	context: Record<string, unknown>
-	/** URL with a `{sessionId}` placeholder the end-user opens. */
+	/** Exact registered Verification Client base URL. It may contain a
+	 *  `{sessionId}` placeholder; Builder otherwise adds the session id as a
+	 *  query parameter. Open the returned `verificationUrl`, not this base
+	 *  URL. */
 	verificationClientUrl: string
+	/** Optional legacy-compatible TEE session binding. The app secret is the
+	 *  organization's verification private key and never leaves this process.
+	 *  Session creation returns only after Builder stores the signed binding. */
+	teeAttestation?: CreateSessionTeeAttestation
+}
+
+/** Options intentionally mirror legacy `verifyProof`'s `teeAttestation`
+ *  vocabulary. `timestamp` is decimal Unix milliseconds; omit it to use now. */
+export interface CreateSessionTeeAttestation {
+	appSecret: string
+	timestamp?: string
+	/** `hash` is the default. Use `signature` only for an older Verification
+	 * Client that expects the 65-byte EIP-191 nonce. */
+	nonceMode?: LegacyTeeNonceMode
 }
 
 /** Input for `keypair.set`: the org's eth public key as uncompressed hex
@@ -105,6 +138,14 @@ export interface Reclaim {
 			input: Omit<CreateSessionInput, 'verificationClientUrl'> &
 				Partial<Pick<CreateSessionInput, 'verificationClientUrl'>>,
 		): Promise<VerificationSession>
+		/** Add the immutable legacy-compatible TEE context after session
+		 *  creation. Normally use
+		 *  `sessions.create({ teeAttestation: { appSecret } })`; this method
+		 *  supports retrying or explicitly orchestrating the two-step flow. */
+		bindTeeNonce(
+			sessionId: string,
+			input: CreateSessionTeeAttestation,
+		): Promise<VerificationSession>
 		get(sessionId: string): Promise<VerificationSession>
 		listEvents(sessionId: string): Promise<VerificationEventRecord[]>
 	}
@@ -112,7 +153,7 @@ export interface Reclaim {
 		/** Register a callback subscription (one-time setup). Delivery is scoped
 		 *  to the token's org; results are ECIES-encrypted to the org's eth key
 		 *  when `canEncryptResult` is enabled (see `keypair.set`), else plaintext.
-		 *  `events` defaults to all three terminal events. */
+		 *  `events` defaults to all terminal lifecycle events. */
 		register(
 			input: Partial<RegisterCallbackInput> &
 				Pick<RegisterCallbackInput, 'callbackUrl'>,
@@ -135,7 +176,7 @@ export interface Reclaim {
 		 *  the delivery is encrypted. */
 		decrypt(body: CallbackBody, credential?: DecryptionKeyInput): Promise<Jws>
 		/** Verify a decrypted JWS: JWKS discovery, ES256K signature,
-		 *  `reclaimSessionId`/`aud`/`exp`, nested attestor proofs. */
+		 *  `reclaimSessionId`/`aud`, any legacy `exp`, and exact legacy proofs. */
 		verify(
 			jws: Jws,
 			opts?: VerifyResultFullOptions,
@@ -190,15 +231,25 @@ export function createReclaim(config: ReclaimConfig): Reclaim {
 		api: client.call.bind(client),
 		sessions: {
 			async create(input) {
-				const body: CreateSessionInput = {
-					...input,
+				const { teeAttestation, ...request } = input
+				const body:
+				components['schemas']['CreateVerificationSessionRequest'] = {
+					...request,
 					verificationClientUrl:
-						input.verificationClientUrl ?? `${client.baseUrl}/v/{sessionId}`,
+						request.verificationClientUrl ?? `${client.baseUrl}/v/{sessionId}`,
 				}
 				const { data } = await client.call('CreateVerificationSession', {
 					body,
 				})
-				return data
+				return teeAttestation
+					? bindTeeNonce(data, teeAttestation)
+					: data
+			},
+			async bindTeeNonce(sessionId, input) {
+				const { data } = await client.call('GetVerificationSession', {
+					params: { sessionId },
+				})
+				return bindTeeNonce(data, input)
 			},
 			async get(sessionId) {
 				const { data } = await client.call('GetVerificationSession', {
@@ -269,7 +320,10 @@ export function createReclaim(config: ReclaimConfig): Reclaim {
 				return decryptCallback(resolveKey(credential), body)
 			},
 			verify(jws, opts) {
-				return verifyResultFull(jws, { fetchImpl: config.fetch, ...opts })
+				return verifyResultFull(jws, {
+					fetchImpl: config.fetch,
+					...withRegisteredIssuer(opts),
+				})
 			},
 			async receive(body, opts) {
 				// A delivery envelope tagged with a non-terminal event carries a
@@ -283,7 +337,7 @@ export function createReclaim(config: ReclaimConfig): Reclaim {
 					const env = body
 					if(
 						env.event
-						&& !(TERMINAL_EVENTS as readonly string[]).includes(env.event)
+						&& !(SIGNED_RESULT_EVENTS as readonly string[]).includes(env.event)
 					) {
 						const decoded = parseEventData(env.data)
 						return {
@@ -299,12 +353,151 @@ export function createReclaim(config: ReclaimConfig): Reclaim {
 				const jws = await decryptCallback(key, body)
 				const result = await verifyResultFull(jws, {
 					fetchImpl: config.fetch,
-					...verifyOpts,
+					...withRegisteredIssuer(verifyOpts),
 				})
 				return { kind: 'result', result }
 			},
 		},
 	}
+
+	async function bindTeeNonce(
+		session: VerificationSession,
+		input: CreateSessionTeeAttestation,
+	) {
+		const binding = createBuilderTeeBinding({
+			organizationId: session.orgId,
+			organizationVerificationPrivateKey: input.appSecret,
+			sessionId: session.id,
+			timestamp: input.timestamp ?? Date.now().toString(),
+			nonceMode: input.nonceMode,
+		})
+		const { data } = await client.call('BindVerificationSessionTeeNonce', {
+			params: { sessionId: session.id },
+			body: {
+				attestationNonce: binding.attestationNonce,
+				attestationNonceData: binding.attestationNonceData,
+				signature: binding.signature,
+			},
+		})
+		return data
+	}
+
+	async function resolvedSession(id: string) {
+		const { data } = await client.call(
+			'GetVerificationRecipe',
+			{ params: { sessionId: id } },
+		)
+		return { recipes: data.recipes satisfies BuilderProofRecipe[] }
+	}
+
+	async function resolvedProvider(
+		providerId: string,
+		providerVersion: string | undefined,
+		_allowedTags: string[] | undefined,
+		proofs: LegacyProof[],
+	) {
+		let exactVersion = providerVersion
+		if(!exactVersion) {
+			const { data: provider } = await client.call('GetProvider', {
+				params: { providerId },
+			})
+			if(!provider.latestVersion) {
+				throw new Error(`Provider ${providerId} has no live version`)
+			}
+
+			exactVersion = canonicalVersion(provider.latestVersion)
+		}
+
+		const { data: version } = await client.call('GetProviderVersion', {
+			params: { providerId, version: exactVersion },
+		})
+		return [{
+			hashes: proofHashesFromBuilderRecipe({
+				providerId,
+				resolvedVersion: exactVersion,
+				initialUrl: version.initialUrl,
+				requests: version.requests,
+				allowedJsRequests: version.allowedJsRequests,
+			}, proofs),
+		}]
+	}
+
+	function withRegisteredIssuer(opts: VerifyResultFullOptions = {}) {
+		const sessionId = opts.sessionId ?? opts.expectedReclaimSessionId
+		const requestedProofValidation = opts.proofValidation
+			?? opts.proofVerification
+		const resolvedOpts: VerifyResultFullOptions = {
+			...opts,
+			proofValidation: {
+				...requestedProofValidation,
+				resolveProvider: requestedProofValidation?.resolveProvider
+					?? resolvedProvider,
+			},
+			...(sessionId && !opts.resolveSession && !opts.proofRecipes
+				? { resolveSession: resolvedSession }
+				: {}),
+		}
+		if(
+			opts.signerPublicKey
+			|| opts.issuer
+			|| opts.trustedIssuer
+			|| opts.issuers?.length
+			|| opts.trustedIssuers?.length
+			|| opts.resolveIssuers
+			|| opts.issuerResolver
+			|| opts.issuersByVerificationClientId
+			|| opts.jwksUrl
+			|| opts.jwksUrlsByVerificationClientId
+			|| opts.resolveJwksUrl
+		) {
+			return resolvedOpts
+		}
+
+		return {
+			...resolvedOpts,
+			resolveIssuers: async(verificationClientId: string) => {
+				const session = await registeredClient(verificationClientId)
+				if(!session) {
+					return []
+				}
+
+				return session.verificationClientIssuer
+					? [session.verificationClientIssuer]
+					: []
+			},
+			resolveJwksUrl: async(verificationClientId: string) => {
+				const session = await registeredClient(verificationClientId)
+				return session?.verificationClientJwksUrl
+			},
+		}
+
+		async function registeredClient(verificationClientId: string) {
+			if(!sessionId) {
+				return undefined
+			}
+
+			const { data: session } = await client.call(
+				'GetVerificationSession',
+				{ params: { sessionId } },
+			)
+			if(session.verificationClientId !== verificationClientId) {
+				return undefined
+			}
+
+			return session
+		}
+	}
+}
+
+function canonicalVersion(
+	version: components['schemas']['ProviderVersionRef'],
+) {
+	const base = `${version.major}.${version.minor}.${version.patch}`
+	return version.branch
+		? `${base}-${version.branch}${version.buildNumber === undefined
+			? ''
+			: `.${version.buildNumber}`}`
+		: base
 }
 
 /** Non-terminal `data` is a base64-encoded JSON `{ event, eventData }`. */
@@ -323,13 +516,7 @@ function parseEventData(data: string | undefined): Record<string, unknown> {
 	}
 }
 
-/** True for a `404` thrown by {@link ReclaimClient.call} — a Boom error whose
- *  `output.statusCode` is 404 (see ./errors.ts). */
+/** True for a `404` thrown by {@link ReclaimClient.call}. */
 function isNotFound(err: unknown): boolean {
-	if(typeof err !== 'object' || err === null) {
-		return false
-	}
-
-	const boom = err as { output?: { statusCode?: number }, statusCode?: number }
-	return boom.output?.statusCode === 404 || boom.statusCode === 404
+	return isProblemError(err) && err.output.statusCode === 404
 }