@reclaimprotocol/client 0.1.27 → 0.1.29

package/src/errors.ts

@@ -1,30 +1,144 @@
-import { Boom } from '@hapi/boom'
 import type { ProblemDetails } from './types/openapi.ts'
 import { PROBLEM_CONTENT_TYPE } from './consts.ts'
-export type { ProblemDetails } from './types/openapi.ts'
 
-export type ProblemError = Boom<ProblemDetails>
+type ProblemErrorOutput = {
+	statusCode: number
+	headers: Record<string, string>
+	payload: ProblemDetails & {
+		statusCode: number
+		error: string
+		message: string
+	}
+}
+
+/**
+ * RFC 9457 error with the fields expected by Boom consumers.
+ *
+ * `@hapi/boom`'s `isBoom()` recognizes this structural contract. The client
+ * doesn't import Boom at runtime, so this error remains browser-safe.
+ */
+export type ProblemError = Error & {
+	readonly isBoom: true
+	readonly isServer: boolean
+	readonly data: ProblemDetails
+	readonly output: ProblemErrorOutput
+}
+
+/** Returns whether a thrown value is a Builder {@link ProblemError}. */
+export function isProblemError(error: unknown): error is ProblemError {
+	if(!(error instanceof Error) || !('isBoom' in error)) {
+		return false
+	}
+
+	if(
+		error.isBoom !== true
+		|| !('isServer' in error)
+		|| typeof error.isServer !== 'boolean'
+		|| !('data' in error)
+		|| !('output' in error)
+	) {
+		return false
+	}
+
+	return isProblemDetails(error.data)
+		&& isProblemErrorOutput(error.output)
+}
+
+/** Returns whether a value follows the RFC 9457 problem-details schema. */
+export function isProblemDetails(value: unknown): value is ProblemDetails {
+	if(!isRecord(value)) {
+		return false
+	}
+
+	return isOptionalString(value.type)
+		&& isOptionalString(value.title)
+		&& isOptionalStatus(value.status)
+		&& isOptionalString(value.detail)
+		&& isOptionalString(value.instance)
+		&& isOptionalString(value.event)
+		&& isOptionalString(value.sessionId)
+}
 
-// Reads an `application/problem+json` response and throws a Boom-style
-// error. Falls back to status-only mapping when the body isn't a problem doc.
-export async function throwProblemError(res: Response) {
+/** Reads an RFC 9457 response, with a status-only fallback for other bodies. */
+export async function readProblemDetails(res: Response) {
 	const contentType = res.headers.get('Content-Type') || ''
-	let problem: ProblemDetails
 	if(contentType.includes(PROBLEM_CONTENT_TYPE)) {
-		problem = (await res.json()) as ProblemDetails
-	} else {
-		problem = {
-			type: 'about:blank',
-			status: res.status,
-			title: res.statusText,
+		try {
+			const value: unknown = await res.json()
+			if(isProblemDetails(value)) {
+				return {
+					...value,
+					type: value.type || 'about:blank',
+					title: value.title || res.statusText,
+					status: value.status || res.status,
+				} satisfies ProblemDetails
+			}
+		} catch{
+			// Fall back to the HTTP status when the problem body isn't valid JSON.
 		}
 	}
 
-	throw new Boom<ProblemDetails>(
-		problem.title,
-		{
+	return {
+		type: 'about:blank',
+		status: res.status,
+		title: res.statusText,
+	} satisfies ProblemDetails
+}
+
+/** Throws a browser-safe, Boom-compatible RFC 9457 error. */
+export async function throwProblemError(res: Response): Promise<never> {
+	const problem = await readProblemDetails(res)
+	const title = problem.title || res.statusText || 'Request failed'
+	const fields = {
+		isBoom: true,
+		isServer: res.status >= 500,
+		data: problem,
+		output: {
 			statusCode: res.status,
-			data: problem,
+			headers: { 'content-type': PROBLEM_CONTENT_TYPE },
+			payload: {
+				...problem,
+				statusCode: res.status,
+				error: title,
+				message: problem.detail || title,
+			},
 		},
-	)
+	} satisfies Omit<ProblemError, keyof Error>
+	const error = Object.assign(new Error(title), fields)
+	error.name = 'ProblemError'
+	throw error
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isProblemErrorOutput(value: unknown): value is ProblemErrorOutput {
+	if(!isRecord(value) || !isRecord(value.payload)) {
+		return false
+	}
+
+	return typeof value.statusCode === 'number'
+		&& isStringRecord(value.headers)
+		&& isProblemDetails(value.payload)
+		&& typeof value.payload.statusCode === 'number'
+		&& typeof value.payload.error === 'string'
+		&& typeof value.payload.message === 'string'
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+	return isRecord(value)
+		&& Object.values(value).every(item => typeof item === 'string')
+}
+
+function isOptionalString(value: unknown) {
+	return value === undefined || typeof value === 'string'
+}
+
+function isOptionalStatus(value: unknown) {
+	return value === undefined
+		|| typeof value === 'number'
+			&& Number.isInteger(value)
+			&& value >= 100
+			&& value <= 599
 }

package/src/index.ts

@@ -1,8 +1,5 @@
-export * from './client.ts'
-export type * from './client.ts'
-export { throwProblemError } from './errors.ts'
-export type { ProblemDetails, ProblemError } from './errors.ts'
-export { DEFAULT_BASE_URL, PROBLEM_CONTENT_TYPE, USER_AGENT } from './consts.ts'
+export * from './api.ts'
+export { USER_AGENT } from './consts.ts'
 export {
 	addressFromPublicKey,
 	deriveFromPrivateKey,
@@ -51,6 +48,7 @@ export {
 export {
 	createReclaim,
 	type CreateSessionInput,
+	type CreateSessionTeeAttestation,
 	type Reclaim,
 	type ReclaimConfig,
 	type ReceiveOptions,
@@ -61,12 +59,59 @@ export {
 } from './reclaim.ts'
 export {
 	fetchJwks,
+	fetchJwksUrl,
+	fetchReclaimJwks,
 	type Jwk,
 	jwksFromPrivateKey,
 	jwkToUncompressedPublicKey,
+	type ReclaimJwks,
 	selectKey,
+	selectVerificationResultKey,
+	trustedAttestorAddresses,
+	validateAttestorAddresses,
 } from './jwks.ts'
 export {
 	type NestedProofOutcome,
 	verifyNestedProof,
 } from './attestor-proof.ts'
+export {
+	type LegacyProof,
+	type LegacyProofOutcome,
+	type LegacyVerifyProofOptions,
+	type ProofHashRequirement,
+	proofHashes,
+	verifyProof,
+} from './legacy-proof.ts'
+export {
+	type BuilderProofRecipe,
+	proofHashesFromBuilderRecipe,
+} from './proof-recipe.ts'
+export {
+	getHashFromProof,
+	hashProofClaimParams,
+	hashRequestSpec,
+	type HttpProofParams,
+	type ProofRequestSpec,
+} from './proof-hash.ts'
+export {
+	builderTeeBindingPayload,
+	BUILDER_TEE_BINDING_DOMAIN,
+	createBuilderTeeBinding,
+	createLegacyTeeNonceContext,
+	deriveLegacySignatureTeeNonce,
+	deriveLegacyTeeNonce,
+	LEGACY_TEE_ATTESTATION_VERSION,
+	LEGACY_TEE_NONCE_DOMAIN,
+	legacyApplicationIdFromPrivateKey,
+	signBuilderTeeBinding,
+	type BuilderTeeBinding,
+	type BuilderTeeBindingPayload,
+	type LegacyTeeNonceContext,
+	type LegacyTeeNonceData,
+	type LegacyTeeNonceMode,
+} from './tee-binding.ts'
+export {
+	KNOWN_VERIFICATION_CLIENTS,
+	type KnownVerificationClientName,
+	type KnownVerificationClientUrlMap,
+} from './verification-clients.ts'

package/src/jwks.ts

@@ -14,6 +14,21 @@ export interface Jwk {
 	kid?: string
 	alg?: string
 	use?: string
+	key_ops?: string[]
+	/** Restricts how Builder consumers may use this key. */
+	'x-reclaim-purpose'?: 'verification-result' | 'attestor-proof'
+	/** Verification Client that owns a result-signing key. */
+	'x-reclaim-verification-client-id'?: string
+	/** Verification Clients that share a built-in result-signing key. */
+	'x-reclaim-verification-client-ids'?: string[]
+	/** Attestor proofs use EIP-191 rather than JOSE ES256K. */
+	'x-reclaim-signature-scheme'?: 'EIP-191'
+}
+
+export interface ReclaimJwks {
+	keys: Jwk[]
+	/** Trusted EIP-191 attestor signer addresses (public-key hashes). */
+	'x-reclaim-attestors'?: string[]
 }
 
 /**
@@ -21,7 +36,15 @@ export interface Jwk {
  * result-signing key). `kid` is the key's ETH address; `x`/`y` are the
  * uncompressed public-key coordinates. Empty set when no key is configured.
  */
-export function jwksFromPrivateKey(privateKeyHex?: string): { keys: Jwk[] } {
+export function jwksFromPrivateKey(
+	privateKeyHex?: string,
+	metadata: Pick<
+		Jwk,
+		'x-reclaim-purpose'
+		| 'x-reclaim-verification-client-id'
+		| 'x-reclaim-verification-client-ids'
+	> = {},
+): { keys: Jwk[] } {
 	if(!privateKeyHex) {
 		return { keys: [] }
 	}
@@ -38,6 +61,8 @@ export function jwksFromPrivateKey(privateKeyHex?: string): { keys: Jwk[] } {
 				crv: 'secp256k1',
 				alg: 'ES256K',
 				use: 'sig',
+				key_ops: ['verify'],
+				...metadata,
 				kid: addressFromUncompressedPubkey(pub),
 				x: b64url(pub.subarray(1, 33)),
 				y: b64url(pub.subarray(33, 65)),
@@ -52,13 +77,35 @@ export async function fetchJwks(
 	fetchImpl: typeof fetch = fetch,
 ): Promise<Jwk[]> {
 	const base = iss.replace(/\/+$/, '')
-	const res = await fetchImpl(`${base}/.well-known/jwks.json`)
+	return fetchJwksUrl(`${base}/.well-known/jwks.json`, fetchImpl)
+}
+
+/** Fetch a JWK set from an explicitly trusted registry URL. */
+export async function fetchJwksUrl(
+	url: string,
+	fetchImpl: typeof fetch = fetch,
+): Promise<Jwk[]> {
+	const jwks = await fetchReclaimJwks(url, fetchImpl)
+	return jwks.keys
+}
+
+/** Fetch Builder's JWKS plus its namespaced attestor trust registry. */
+export async function fetchReclaimJwks(
+	url: string,
+	fetchImpl: typeof fetch = fetch,
+): Promise<ReclaimJwks> {
+	const res = await fetchImpl(url)
 	if(!res.ok) {
-		throw new Error(`JWKS fetch failed for ${base}: HTTP ${res.status}`)
+		throw new Error(`JWKS fetch failed for ${url}: HTTP ${res.status}`)
 	}
 
-	const body = (await res.json()) as { keys?: Jwk[] }
-	return body.keys ?? []
+	const body = (await res.json()) as Partial<ReclaimJwks>
+	return {
+		keys: body.keys ?? [],
+		'x-reclaim-attestors': validateAttestorAddresses(
+			body['x-reclaim-attestors'] ?? [],
+		),
+	}
 }
 
 /** Find the key matching `kid` (case-insensitive — kids are ETH addresses). */
@@ -67,6 +114,59 @@ export function selectKey(keys: Jwk[], kid: string): Jwk | undefined {
 	return keys.find((k) => (k.kid ?? '').toLowerCase() === want)
 }
 
+/** Select a result key and enforce its Verification Client ownership. */
+export function selectVerificationResultKey(
+	keys: Jwk[],
+	kid: string,
+	verificationClientId: string,
+): Jwk | undefined {
+	return keys.find((key) => (
+		(key.kid ?? '').toLowerCase() === kid.toLowerCase()
+		&& key['x-reclaim-purpose'] !== 'attestor-proof'
+		&& belongsToVerificationClient(key, verificationClientId)
+	))
+}
+
+/** Return ETH addresses from keys explicitly registered for attestor proofs. */
+export function trustedAttestorAddresses(keys: Jwk[]): string[] {
+	return keys
+		.filter((key) => key['x-reclaim-purpose'] === 'attestor-proof')
+		.map((key) => {
+			if(
+				key.kty !== 'EC'
+				|| key.crv !== 'secp256k1'
+				|| key.use !== 'sig'
+				|| key['x-reclaim-signature-scheme'] !== 'EIP-191'
+				|| (key.key_ops && !key.key_ops.includes('verify'))
+			) {
+				throw new Error('invalid attestor JWK metadata')
+			}
+
+			const address = addressFromUncompressedPubkey(
+				hexPublicKeyBytes(jwkToUncompressedPublicKey(key)),
+			).toLowerCase()
+			if((key.kid ?? '').toLowerCase() !== address) {
+				throw new Error(
+					'attestor JWK kid does not match its ETH public key',
+				)
+			}
+
+			return address
+		})
+}
+
+/** Validate and normalize the JWKS address-only trust extension. */
+export function validateAttestorAddresses(addresses: string[]): string[] {
+	return [...new Set(addresses.map((address) => {
+		const normalized = address.trim().toLowerCase()
+		if(!/^0x[0-9a-f]{40}$/.test(normalized)) {
+			throw new Error('invalid attestor address in JWKS trust registry')
+		}
+
+		return normalized
+	}))]
+}
+
 /**
  * Reconstruct the uncompressed secp256k1 public key (`0x04` + X + Y) from an
  * EC JWK's base64url `x`/`y` coordinates, for signature verification.
@@ -84,3 +184,26 @@ export function jwkToUncompressedPublicKey(jwk: Jwk): string {
 	out.set(y, 33)
 	return '0x' + bytesToHex(out)
 }
+
+function belongsToVerificationClient(
+	key: Jwk,
+	verificationClientId: string,
+): boolean {
+	const one = key['x-reclaim-verification-client-id']
+	const many = key['x-reclaim-verification-client-ids']
+	if(one) {
+		return one === verificationClientId
+	}
+
+	if(many) {
+		return many.includes(verificationClientId)
+	}
+
+	// Untagged self-hosted JWKS remain compatible because their URL is itself
+	// selected from the registered Verification Client record.
+	return key['x-reclaim-purpose'] !== 'verification-result'
+}
+
+function hexPublicKeyBytes(value: string) {
+	return Uint8Array.from(Buffer.from(value.slice(2), 'hex'))
+}