@reclaimprotocol/client 0.1.27 → 0.1.28

package/src/legacy-proof.ts

@@ -0,0 +1,367 @@
+import { createSignDataForClaim } from '@reclaimprotocol/attestor-core'
+import { recoverEip191Address } from './eip191.ts'
+import { fetchReclaimJwks, trustedAttestorAddresses } from './jwks.ts'
+import { assertValidProofHashes, getHashFromProof } from './proof-hash.ts'
+import type {
+	HashRequirement,
+	LegacyProof,
+	TrustedData,
+} from './proof-types.ts'
+import {
+	type AttestorTeeAttestationConfig,
+	runAttestorTeeVerification,
+} from './verify-attestor-tee.ts'
+import { runTeeVerification, type TeeAttestationConfig } from './verify-tee.ts'
+
+export type { LegacyProof } from './proof-types.ts'
+
+/** A proof hash requirement accepted by legacy `verifyProof`. */
+export type ProofHashRequirement = string | HashRequirement
+
+export interface ResolvedSessionProofValidation {
+	hashes?: ProofHashRequirement[]
+	providerId?: string
+	providerVersion?: string
+	allowedTags?: string[]
+}
+
+/** Exact provider requirements returned by a caller-controlled resolver. */
+export interface ResolvedProviderProofValidation {
+	hashes: ProofHashRequirement[]
+}
+
+/** Options intentionally preserve legacy `verifyProof` vocabulary. */
+export interface LegacyVerifyProofOptions {
+	hashes?: ProofHashRequirement[]
+	providerId?: string
+	providerVersion?: string
+	allowedTags?: string[]
+	dangerouslyDisableContentValidation?: true
+	/** Read `providerHash` from context, while still verifying signatures. */
+	hasNoPii?: true
+	teeAttestation?: TeeAttestationConfig
+	attestorTeeAttestation?: AttestorTeeAttestationConfig
+	/** Explicit trusted attestor ETH addresses. */
+	attestorAddresses?: string[]
+	/** Trusted Builder JWKS registry containing attestor-purpose keys. */
+	attestorJwksUrl?: string
+	fetchImpl?: typeof fetch
+	/** Builder session id. Requires a resolver without hashes or a provider. */
+	sessionId?: string
+	resolveSession?: (
+		sessionId: string,
+		proofs: LegacyProof[],
+	) => Promise<ResolvedSessionProofValidation>
+		| ResolvedSessionProofValidation
+	/** Resolve an exact provider without coupling this verifier to HTTP. */
+	resolveProvider?: (
+		providerId: string,
+		providerVersion: string | undefined,
+		allowedTags: string[] | undefined,
+		proofs: LegacyProof[],
+	) => Promise<ResolvedProviderProofValidation[]>
+		| ResolvedProviderProofValidation[]
+	expectedSessionId?: string
+	requireSessionBinding?: boolean
+	expectedContext?: Record<string, unknown>
+}
+
+export interface LegacyProofOutcome {
+	valid: boolean
+	reason?: string
+	proofHashes?: string[]
+	isTeeAttestationVerified?: boolean
+	isAttestorTeeAttestationVerified?: boolean
+	data?: TrustedData[]
+	publicData?: unknown[]
+}
+
+/** Return the provider hashes encoded in an exact legacy proof. */
+export function proofHashes(proof: LegacyProof): string[] {
+	return getHashFromProof(proof)
+}
+
+/**
+ * Verify exact legacy proofs without depending on `@reclaimprotocol/js-sdk`.
+ * The signed claim is never renamed or reconstructed.
+ */
+export async function verifyProof(
+	proofOrProofs: LegacyProof | LegacyProof[],
+	config: LegacyVerifyProofOptions,
+): Promise<LegacyProofOutcome> {
+	const proofs = Array.isArray(proofOrProofs) ? proofOrProofs : [proofOrProofs]
+	if(!proofs.length) {
+		return { valid: false, reason: 'no-proofs' }
+	}
+
+	try {
+		const effective = await resolveValidation(config, proofs)
+		assertSessionAndContext(proofs, effective)
+		const attestors = await resolveTrustedAttestors(effective)
+		assertVerifiedSignatures(proofs, attestors)
+		await assertContent(proofs, effective)
+
+		let isTeeAttestationVerified: boolean | undefined
+		if(effective.teeAttestation) {
+			await runTeeVerification(proofs, effective.teeAttestation)
+			isTeeAttestationVerified = true
+		}
+
+		let isAttestorTeeAttestationVerified: boolean | undefined
+		if(effective.attestorTeeAttestation) {
+			await runAttestorTeeVerification(
+				proofs,
+				effective.attestorTeeAttestation,
+			)
+			isAttestorTeeAttestationVerified = true
+		}
+
+		return {
+			valid: true,
+			proofHashes: collectProofHashes(proofs, effective.hasNoPii),
+			isTeeAttestationVerified,
+			isAttestorTeeAttestationVerified,
+			data: proofs.map(trustedData),
+			publicData: proofs.map((proof) => proof.publicData ?? {}),
+		}
+	} catch(error) {
+		return {
+			valid: false,
+			reason: failureReason(error),
+		}
+	}
+}
+
+async function resolveValidation(
+	config: LegacyVerifyProofOptions,
+	proofs: LegacyProof[],
+) {
+	let effective = config
+	if(config.sessionId && !hasContentValidation(config)) {
+		if(!config.resolveSession) {
+			throw new Error('session-resolver-required')
+		}
+
+		effective = {
+			...config,
+			...await config.resolveSession(config.sessionId, proofs),
+		}
+	}
+
+	return effective
+}
+
+async function resolveTrustedAttestors(config: LegacyVerifyProofOptions) {
+	const addresses = config.attestorAddresses?.map(normalized) ?? []
+	if(config.attestorJwksUrl) {
+		const registry = await fetchReclaimJwks(
+			config.attestorJwksUrl,
+			config.fetchImpl,
+		)
+		addresses.push(
+			...(registry['x-reclaim-attestors'] ?? []),
+			...trustedAttestorAddresses(registry.keys),
+		)
+	}
+
+	const unique = [...new Set(addresses)]
+	if(!unique.length) {
+		throw new Error('attestor-trust-required')
+	}
+
+	return unique
+}
+
+function assertVerifiedSignatures(
+	proofs: LegacyProof[],
+	trustedAttestors: string[],
+) {
+	for(const proof of proofs) {
+		if(!proof.signatures?.length || !proof.witnesses?.length) {
+			throw new Error('proof-signature-missing')
+		}
+
+		const signData = createSignDataForClaim(proof.claimData)
+		const signers = proof.signatures.map((signature) => (
+			normalized(recoverEip191Address(signData, signature))
+		))
+		const witnesses = proof.witnesses.map(({ id }) => normalized(id))
+		if(witnesses.some((witness) => !trustedAttestors.includes(witness))) {
+			throw new Error('attestor-not-allowed')
+		}
+
+		if(!signers.some((signer) => trustedAttestors.includes(signer))) {
+			throw new Error('attestor-not-allowed')
+		}
+
+		if(!signers.every((signer) => witnesses.includes(signer))) {
+			throw new Error('witness-signature-mismatch')
+		}
+	}
+}
+
+async function assertContent(
+	proofs: LegacyProof[],
+	config: LegacyVerifyProofOptions,
+) {
+	if(config.dangerouslyDisableContentValidation) {
+		return
+	}
+
+	if(config.hashes) {
+		assertValidProofHashes(proofs, config.hashes, config.hasNoPii)
+		return
+	}
+
+	if(config.providerId) {
+		if(!config.resolveProvider) {
+			throw new Error('provider-resolver-required')
+		}
+
+		const candidates = await config.resolveProvider(
+			config.providerId,
+			config.providerVersion,
+			config.allowedTags,
+			proofs,
+		)
+		if(!candidates.length) {
+			throw new Error('provider-not-found')
+		}
+
+		let lastError: unknown
+		for(const candidate of candidates) {
+			try {
+				assertValidProofHashes(proofs, candidate.hashes, config.hasNoPii)
+				return
+			} catch(error) {
+				lastError = error
+			}
+		}
+
+		throw lastError
+	}
+
+	throw new Error('proof-validation-required')
+}
+
+function assertSessionAndContext(
+	proofs: LegacyProof[],
+	config: LegacyVerifyProofOptions,
+) {
+	const expectedSessionId = config.sessionId ?? config.expectedSessionId
+	for(const proof of proofs) {
+		if(expectedSessionId) {
+			const ids = sessionIds(proof)
+			if(ids.some((id) => id !== expectedSessionId)) {
+				throw new Error('session-mismatch')
+			}
+
+			if((config.sessionId || config.requireSessionBinding) && !ids.length) {
+				throw new Error('session-missing')
+			}
+		}
+
+		if(!contextMatches(proof, config.expectedContext)) {
+			throw new Error('context-mismatch')
+		}
+	}
+}
+
+function trustedData(proof: LegacyProof): TrustedData {
+	const context = contextFrom(proof)
+	const extractedParameters = isRecord(context.extractedParameters)
+		? Object.fromEntries(Object.entries(context.extractedParameters).map(
+			([key, value]) => [key, String(value)],
+		))
+		: {}
+	delete context.extractedParameters
+	return { context, extractedParameters }
+}
+
+function collectProofHashes(
+	proofs: LegacyProof[],
+	hasNoPii: true | undefined,
+): string[] | undefined {
+	try {
+		return proofs.flatMap((proof) => getHashFromProof(proof, hasNoPii))
+	} catch{
+		return undefined
+	}
+}
+
+function hasContentValidation(config: LegacyVerifyProofOptions): boolean {
+	return Boolean(
+		config.hashes
+		|| config.providerId
+		|| config.dangerouslyDisableContentValidation,
+	)
+}
+
+function failureReason(error: unknown): string {
+	const message = error instanceof Error ? error.message : String(error)
+	const lower = message.toLowerCase()
+	if(
+		lower.includes('multiple')
+		|| lower.includes('duplicate')
+		|| lower.includes('more than once')
+	) {
+		return 'duplicate-proof-hash'
+	}
+
+	return message || 'proof-not-verified'
+}
+
+function normalized(value: string): string {
+	return value.trim().toLowerCase()
+}
+
+function contextFrom(proof: LegacyProof): Record<string, unknown> {
+	const raw = proof.claimData.context
+	if(!raw) {
+		return {}
+	}
+
+	try {
+		const context: unknown = JSON.parse(raw)
+		return isRecord(context) ? { ...context } : {}
+	} catch{
+		return {}
+	}
+}
+
+function sessionIds(proof: LegacyProof): string[] {
+	const context = contextFrom(proof)
+	const ids = [context.reclaimSessionId]
+	try {
+		const parameters = JSON.parse(
+			proof.claimData.parameters,
+		) as Record<string, unknown>
+		ids.push(parameters.proxySessionId, parameters.sessionId)
+	} catch{
+		// A non-HTTP claim is valid when session binding wasn't requested.
+	}
+
+	return ids.filter(
+		(value): value is string => (
+			typeof value === 'string' && value.length > 0
+		),
+	)
+}
+
+function contextMatches(
+	proof: LegacyProof,
+	expected?: Record<string, unknown>,
+): boolean {
+	if(!expected) {
+		return true
+	}
+
+	const context = contextFrom(proof)
+	return Object.entries(expected).every(([key, value]) => (
+		JSON.stringify(context[key]) === JSON.stringify(value)
+	))
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value && typeof value === 'object' && !Array.isArray(value))
+}

package/src/proof-hash.ts

@@ -0,0 +1,316 @@
+import { keccak_256 } from '@noble/hashes/sha3.js'
+import { canonicalJson as canonical } from './canonical.ts'
+import { bytesToHex } from './encoding.ts'
+import type { HashRequirement, LegacyProof } from './proof-types.ts'
+
+export interface HttpProofParams {
+	url: string
+	method: string
+	body?: string
+	responseMatches: Array<{
+		type?: string
+		value?: string
+		invert?: boolean
+		isOptional?: boolean
+	}>
+	responseRedactions: Array<{
+		xPath?: string
+		jsonPath?: string
+		regex?: string
+		hash?: string
+	}>
+}
+
+export interface ProofRequestSpec extends HttpProofParams {
+	urlType: string
+	bodySniff: { enabled: boolean, template: string }
+	required?: boolean
+	multiple?: boolean
+	templateParams?: string[]
+	templateParamsMode?: 'separate' | 'merge'
+}
+
+/** Exact legacy canonical HTTP-provider hashes, including optional matches. */
+export function hashProofClaimParams(params: HttpProofParams): string[] {
+	return canonicalProofParams(params).map((serialized) => (
+		'0x' + bytesToHex(keccak_256(new TextEncoder().encode(serialized)))
+	))
+}
+
+export function getHashFromProof(
+	proof: LegacyProof,
+	hasNoPii = false,
+): string[] {
+	if(hasNoPii) {
+		const context = JSON.parse(
+			proof.claimData.context,
+		) as Record<string, unknown>
+		if(typeof context.providerHash !== 'string' || !context.providerHash) {
+			throw new Error('Provider hash must be present in proof context')
+		}
+
+		return [context.providerHash]
+	}
+
+	const parsed: unknown = JSON.parse(proof.claimData.parameters)
+	if(!isHttpProofParams(parsed)) {
+		throw new Error('Proof has no HTTP provider params to hash')
+	}
+
+	return hashProofClaimParams(parsed)
+}
+
+export function hashRequestSpec(request: ProofRequestSpec): HashRequirement {
+	return {
+		value: hashProofClaimParams({
+			...request,
+			body: request.bodySniff.enabled ? request.bodySniff.template : '',
+		}),
+		required: request.required,
+		multiple: request.multiple,
+	}
+}
+
+export function hashRequirementsFromSpecs(
+	requestData: ProofRequestSpec[],
+	allowedInjectedRequestData: ProofRequestSpec[],
+	proofs: LegacyProof[],
+): HashRequirement[] {
+	const templates = expandTemplates(
+		allowedInjectedRequestData,
+		templateParametersFromProofs(proofs),
+	)
+	return [...requestData, ...templates].map(hashRequestSpec)
+}
+
+export function assertValidProofHashes(
+	proofs: LegacyProof[],
+	requirements: Array<string | HashRequirement>,
+	hasNoPii = false,
+) {
+	const unmatched = new Map(proofs.map((proof, index) => (
+		[index, getHashFromProof(proof, hasNoPii)]
+	)))
+	for(const raw of requirements) {
+		const requirement = typeof raw === 'string' ? { value: raw } : raw
+		const expected = (Array.isArray(requirement.value)
+			? requirement.value
+			: [requirement.value]).map(normalized)
+		let found = false
+		for(const [index, hashes] of unmatched) {
+			if(!hashes.map(normalized).some((hash) => expected.includes(hash))) {
+				continue
+			}
+
+			unmatched.delete(index)
+			if(found && requirement.multiple === false) {
+				throw new Error(
+					`Proof by hash '${expected.join(',')}' is not allowed `
+						+ 'to appear more than once',
+				)
+			}
+
+			found = true
+		}
+
+		if(!found && requirement.required !== false) {
+			throw new Error(
+				`Proof by required hash '${expected.join(',')}' was not found`,
+			)
+		}
+	}
+
+	if(unmatched.size) {
+		throw new Error(`${unmatched.size} extra proof(s) could not be validated`)
+	}
+}
+
+function canonicalProofParams(params: HttpProofParams): string[] {
+	const count = params.responseMatches.length
+	const values: string[] = []
+	for(let mask = 0; mask < 2 ** count; mask++) {
+		let valid = true
+		const matches: Array<Record<string, unknown>> = []
+		const redactions: Array<Record<string, unknown>> = []
+		for(let index = 0; index < count; index++) {
+			const match = params.responseMatches[index]
+			const redaction = params.responseRedactions[index]
+			if((mask & (1 << index)) === 0) {
+				if(match && !match.isOptional) {
+					valid = false
+				}
+
+				continue
+			}
+
+			if(match) {
+				matches.push({
+					value: match.value ?? '',
+					type: match.type ?? 'contains',
+					invert: match.invert || undefined,
+				})
+			}
+
+			if(redaction) {
+				redactions.push({
+					xPath: redaction.xPath ?? '',
+					jsonPath: redaction.jsonPath ?? '',
+					regex: redaction.regex ?? '',
+					hash: normalizedRedactionHash(redaction.hash),
+				})
+			}
+		}
+
+		if(valid && matches.length) {
+			values.push(canonical({
+				url: params.url ?? '',
+				method: params.method ?? 'GET',
+				body: params.body ?? '',
+				responseMatches: matches,
+				responseRedactions: redactions,
+			}))
+		}
+	}
+
+	return values.length ? values : [canonical({
+		url: params.url ?? '',
+		method: params.method ?? 'GET',
+		body: params.body ?? '',
+		responseMatches: [],
+		responseRedactions: [],
+	})]
+}
+
+function expandTemplates(
+	templates: ProofRequestSpec[],
+	parameters: Record<string, string[]>,
+): ProofRequestSpec[] {
+	const result: ProofRequestSpec[] = []
+	for(const template of templates) {
+		const names = template.templateParams ?? []
+		if(!names.length) {
+			result.push(template)
+			continue
+		}
+
+		const present = names.filter((name) => parameters[name]?.length)
+		if(present.length !== names.length) {
+			if(template.required === false && !present.length) {
+				continue
+			}
+
+			throw new Error('Not all template variables are present')
+		}
+
+		const length = parameters[names[0]].length
+		if(!names.every((name) => parameters[name].length === length)) {
+			throw new Error('Not all template variables have same length')
+		}
+
+		const expanded = Array.from({ length }, (_, index) => substitute(
+			template,
+			Object.fromEntries(names.map((name) => [name, parameters[name][index]])),
+		))
+		if(template.templateParamsMode !== 'merge') {
+			result.push(...expanded)
+			continue
+		}
+
+		result.push({
+			...template,
+			responseMatches: expanded.flatMap((item) => item.responseMatches),
+			responseRedactions: expanded.flatMap((item) => item.responseRedactions),
+		})
+	}
+
+	return result
+}
+
+function substitute(
+	template: ProofRequestSpec,
+	parameters: Record<string, string>,
+): ProofRequestSpec {
+	const replace = (value: string) => Object.entries(parameters).reduce(
+		(result, [name, replacement]) => (
+			result.split(`\${${name}}`).join(replacement)
+		),
+		value,
+	)
+	return {
+		...template,
+		responseMatches: template.responseMatches.map((match) => ({
+			...match,
+			value: replace(match.value ?? ''),
+		})),
+		responseRedactions: template.responseRedactions.map((redaction) => ({
+			...redaction,
+			xPath: replace(redaction.xPath ?? ''),
+			jsonPath: replace(redaction.jsonPath ?? ''),
+			regex: replace(redaction.regex ?? ''),
+		})),
+	}
+}
+
+function templateParametersFromProofs(proofs: LegacyProof[]) {
+	const combined: Record<string, unknown> = {}
+	for(const proof of proofs) {
+		for(const raw of [proof.claimData.parameters, proof.claimData.context]) {
+			try {
+				const parsed = JSON.parse(raw) as Record<string, unknown>
+				Object.assign(combined, parsed.paramValues, parsed.extractedParameters)
+			} catch{
+				// A proof without template parameters is valid.
+			}
+		}
+	}
+
+	const result: Record<string, string[]> = {}
+	for(const [name, raw] of Object.entries(combined)) {
+		let value = raw
+		if(typeof value === 'string') {
+			try {
+				value = JSON.parse(value)
+			} catch{ /* plain string */ }
+		}
+
+		if(Array.isArray(value) && value.length) {
+			result[name] = value.map(String)
+		}
+	}
+
+	return result
+}
+
+function isHttpProofParams(value: unknown): value is HttpProofParams {
+	if(!value || typeof value !== 'object' || Array.isArray(value)) {
+		return false
+	}
+
+	const params = value as Record<string, unknown>
+	return typeof params.url === 'string'
+		&& typeof params.method === 'string'
+		&& ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(params.method)
+		&& (
+			params.body === null
+			|| params.body === undefined
+			|| typeof params.body === 'string'
+		)
+		&& Array.isArray(params.responseMatches)
+		&& params.responseMatches.length > 0
+		&& Array.isArray(params.responseRedactions)
+}
+
+function normalized(value: string) {
+	return value.toLowerCase().trim()
+}
+
+/**
+ * All OPRF transports prove the same provider-level intent: the selected
+ * value is hidden behind an OPRF. Verification Clients may use the transport
+ * they implement, so transport spelling must not change the provider hash.
+ */
+function normalizedRedactionHash(value: string | undefined) {
+	return value === 'oprf' || value === 'oprf-mpc' || value === 'oprf-raw'
+		? '_oprf'
+		: value || undefined
+}