@reclaimprotocol/client 0.1.27 → 0.1.28

package/lib/verify-tee.js

@@ -0,0 +1,347 @@
+import { keccak_256 } from '@noble/hashes/sha3.js';
+/* eslint-disable @stylistic/max-len */
+import { webcrypto } from 'node:crypto';
+import { recoverEip191Address } from "./eip191.js";
+import { GCP_CONFIDENTIAL_SPACE_ISSUER } from "./proof-trust-constants.js";
+import { legacyErrorClass } from "./proof-verification-error.js";
+import { deriveLegacyTeeNonce, legacyApplicationIdFromPrivateKey } from "./tee-binding.js";
+const TeeVerificationError = legacyErrorClass('TeeVerificationError');
+const EXPECTED_HW_MODEL = 'GCP_AMD_SEV';
+const EXPECTED_TEE_PROVIDER = 'gcp';
+const EXPECTED_TEE_TECHNOLOGY = 'amd-sev';
+const SUPPORTED_PROOF_VERSIONS = ['v2', 'v3'];
+const TOKEN_CLOCK_SKEW_S = 60;
+const NONCE_TIMESTAMP_MAX_SKEW_MS = 10 * 60 * 1000;
+const BROWSER_ENVIRONMENT_ERROR = 'TEE attestation verification is only supported in non-browser environments. Run verifyTeeAttestation on your server or API route.';
+function assert(condition, message) {
+    if (!condition) {
+        throw new Error(message);
+    }
+}
+function isBrowserEnvironment() {
+    if ('window' in globalThis || 'document' in globalThis) {
+        return true;
+    }
+    if (typeof navigator !== 'undefined' && typeof process === 'undefined') {
+        return true;
+    }
+    const workerGlobalScope = globalThis.WorkerGlobalScope;
+    if (typeof workerGlobalScope === 'function' &&
+        globalThis instanceof workerGlobalScope) {
+        return true;
+    }
+    return false;
+}
+function assertNonBrowserEnvironment() {
+    if (isBrowserEnvironment()) {
+        throw new Error(BROWSER_ENVIRONMENT_ERROR);
+    }
+}
+function normalizeHex(value) {
+    return (value || '').trim().replace(/^0x/i, '').toLowerCase();
+}
+function isHex(value) {
+    return /^[0-9a-f]+$/i.test(value);
+}
+function decodeBase64Url(input) {
+    const normalized = input.replace(/-/g, '+').replace(/_/g, '/');
+    const padded = normalized + '='.repeat((4 - normalized.length % 4) % 4);
+    if (typeof Buffer !== 'undefined') {
+        return new Uint8Array(Buffer.from(padded, 'base64'));
+    }
+    if (typeof atob === 'function') {
+        const binary = atob(padded);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i += 1) {
+            bytes[i] = binary.charCodeAt(i);
+        }
+        return bytes;
+    }
+    throw new Error('Base64 decoding is not supported in this environment');
+}
+function decodeUtf8(bytes) {
+    return new TextDecoder().decode(bytes);
+}
+function decodeJwt(token) {
+    const parts = token.split('.');
+    assert(parts.length === 3, 'attestation token is not a JWT');
+    return {
+        header: JSON.parse(decodeUtf8(decodeBase64Url(parts[0]))),
+        payload: JSON.parse(decodeUtf8(decodeBase64Url(parts[1]))),
+        signingInput: `${parts[0]}.${parts[1]}`,
+        signature: decodeBase64Url(parts[2]),
+    };
+}
+function getFetch() {
+    const fetchFn = globalThis.fetch;
+    assert(fetchFn, 'fetch is not available in this environment');
+    return fetchFn.bind(globalThis);
+}
+function getSubtleCrypto() {
+    if (globalThis.crypto?.subtle) {
+        return globalThis.crypto.subtle;
+    }
+    return webcrypto.subtle;
+}
+async function fetchJson(url) {
+    const response = await getFetch()(url);
+    if (!response.ok) {
+        throw new Error(`GET ${url} returned ${response.status} ${response.statusText}`);
+    }
+    // The caller supplies the expected shape and validates every field before use.
+    return await response.json();
+}
+async function sha256Hex(input) {
+    const digest = await getSubtleCrypto().digest('SHA-256', new TextEncoder().encode(input));
+    return Array.from(new Uint8Array(digest), (value) => value.toString(16).padStart(2, '0')).join('');
+}
+const JWKS_CACHE_TTL_MS = 5 * 60 * 1000;
+let cachedJwksUri = null;
+let cachedJwksKeys = null;
+let cachedJwksAt = 0;
+async function verifyJwtSignature(token, issuer) {
+    const { header, payload, signingInput, signature } = decodeJwt(token);
+    assert(header.alg === 'RS256', `unexpected attestation signing algorithm: ${header.alg}`);
+    assert(typeof header.kid === 'string' && header.kid.length > 0, 'attestation token kid is missing');
+    const isCacheFresh = cachedJwksKeys && (Date.now() - cachedJwksAt) < JWKS_CACHE_TTL_MS;
+    if (!isCacheFresh) {
+        const oidc = await fetchJson(`${issuer}/.well-known/openid-configuration`);
+        assert(typeof oidc?.jwks_uri === 'string' && oidc.jwks_uri.length > 0, 'issuer JWKS URI is missing');
+        cachedJwksUri = oidc.jwks_uri;
+        const jwks = await fetchJson(cachedJwksUri);
+        cachedJwksKeys = jwks?.keys || [];
+        cachedJwksAt = Date.now();
+    }
+    const jwk = cachedJwksKeys.find((key) => key.kid === header.kid);
+    assert(jwk, `no JWKS key found for kid ${header.kid}`);
+    const cryptoKey = await getSubtleCrypto().importKey('jwk', jwk, { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, ['verify']);
+    const isValid = await getSubtleCrypto().verify('RSASSA-PKCS1-v1_5', cryptoKey, signature, new TextEncoder().encode(signingInput));
+    assert(isValid, 'JWT signature verification failed');
+    return payload;
+}
+function isNonceContextData(obj) {
+    if (!obj || typeof obj !== 'object') {
+        return false;
+    }
+    const o = obj;
+    return typeof o.applicationId === 'string' && o.applicationId.length > 0
+        && typeof o.sessionId === 'string' && o.sessionId.length > 0
+        && typeof o.timestamp === 'string' && o.timestamp.length > 0;
+}
+function parseProofContext(proof) {
+    let parsedContext;
+    try {
+        parsedContext = JSON.parse(proof.claimData.context);
+    }
+    catch {
+        throw new Error('Malformed proof: claimData.context is not valid JSON');
+    }
+    if (!parsedContext || typeof parsedContext !== 'object') {
+        throw new Error('Malformed proof: claimData.context is not a JSON object');
+    }
+    const ctx = parsedContext;
+    const expectedNonce = ctx.attestationNonce;
+    assert(typeof expectedNonce === 'string' && expectedNonce.length > 0, 'Proof context is missing attestationNonce');
+    const nonceDataObj = ctx.attestationNonceData;
+    assert(isNonceContextData(nonceDataObj), 'Proof context is missing or has invalid attestationNonceData (requires applicationId, sessionId, timestamp)');
+    return { parsedContext: ctx, nonceDataObj, expectedNonce };
+}
+function verifyApplicationAndSessionBinding(proof, parsedContext, nonceDataObj, expectedApplicationId) {
+    const { applicationId, sessionId, timestamp } = nonceDataObj;
+    if (expectedApplicationId) {
+        assert(applicationId.toLowerCase() === expectedApplicationId.toLowerCase(), `Application ID Mismatch! Expected ${expectedApplicationId}, but proof context contains ${applicationId}`);
+    }
+    let parsedParameters = {};
+    if (proof.claimData.parameters) {
+        try {
+            const parsed = JSON.parse(proof.claimData.parameters);
+            parsedParameters = (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) ? parsed : {};
+        }
+        catch {
+            throw new Error('Malformed proof: claimData.parameters is not valid JSON');
+        }
+    }
+    const contextSessionId = parsedContext?.reclaimSessionId;
+    const parameterSessionId = parsedParameters?.proxySessionId ?? parsedParameters?.sessionId;
+    if (contextSessionId && contextSessionId.toString() !== sessionId.toString()) {
+        throw new Error(`Session ID Mismatch! Expected ${sessionId}, but proof context contains reclaimSessionId=${contextSessionId}`);
+    }
+    if (parameterSessionId && parameterSessionId.toString() !== sessionId.toString()) {
+        throw new Error(`Session ID Mismatch! Expected ${sessionId}, but proof parameters contain ${parameterSessionId}`);
+    }
+    if (!contextSessionId && !parameterSessionId) {
+        throw new Error('Proof is missing reclaimSessionId and proxySessionId/sessionId for attestation nonce verification');
+    }
+    const claimTimestampMs = proof.claimData.timestampS * 1000;
+    const nonceTimestampMs = parseInt(timestamp, 10);
+    const diffMs = Math.abs(claimTimestampMs - nonceTimestampMs);
+    if (diffMs > NONCE_TIMESTAMP_MAX_SKEW_MS) {
+        throw new Error(`Timestamp Skew Too Large! claimData.timestampS and attestationNonce timestamp differ by ${Math.round(diffMs / 1000)}s (limit: 600s)`);
+    }
+}
+function verifyNonceMaterial(expectedNonce, nonceDataObj, expectedAppSecret) {
+    const cleanExpectedNonce = normalizeHex(expectedNonce);
+    const { applicationId, sessionId, timestamp } = nonceDataObj;
+    assert(cleanExpectedNonce.length > 0, 'Proof context attestationNonce is empty');
+    assert(isHex(cleanExpectedNonce), 'Proof context attestationNonce is not valid hex');
+    if (expectedAppSecret) {
+        const recomputedNonce = deriveLegacyTeeNonce(expectedAppSecret, { applicationId, sessionId, timestamp });
+        assert(recomputedNonce === cleanExpectedNonce, 'Attestation nonce verification failed: app secret, application ID, session ID, or timestamp do not match');
+        return;
+    }
+    if (cleanExpectedNonce.length > 74) {
+        const legacyNonceData = `${applicationId}:${sessionId}:${timestamp}`;
+        const nonceMsg = keccak_256(new TextEncoder().encode(legacyNonceData));
+        const recoveredAddress = recoverEip191Address(nonceMsg, expectedNonce.startsWith('0x') ? expectedNonce : `0x${expectedNonce}`);
+        assert(recoveredAddress.toLowerCase() === applicationId.toLowerCase(), `Nonce signature verification failed: recovered ${recoveredAddress}, expected ${applicationId}`);
+        return;
+    }
+    throw new Error('App secret is required to verify hash-based attestation nonces');
+}
+function assertTokenFresh(claims) {
+    const now = Math.floor(Date.now() / 1000);
+    if (typeof claims.nbf === 'number' && now + TOKEN_CLOCK_SKEW_S < claims.nbf) {
+        throw new Error(`Attestation token is not valid before ${claims.nbf}`);
+    }
+    if (typeof claims.exp === 'number' && now - TOKEN_CLOCK_SKEW_S > claims.exp) {
+        throw new Error(`Attestation token expired at ${claims.exp}`);
+    }
+    if (typeof claims.iat === 'number' && claims.iat > now + TOKEN_CLOCK_SKEW_S) {
+        throw new Error(`Attestation token issued-at ${claims.iat} is in the future`);
+    }
+}
+function assertAudienceClaim(aud) {
+    if (typeof aud === 'string') {
+        assert(aud.length > 0, 'attestation token audience is empty');
+        return;
+    }
+    if (Array.isArray(aud)) {
+        assert(aud.length > 0, 'attestation token audience is empty');
+        assert(aud.every((entry) => typeof entry === 'string' && entry.length > 0), 'attestation token audience contains invalid entries');
+        return;
+    }
+    throw new Error('attestation token audience is missing');
+}
+function getProofVersion(teeAttestation) {
+    return teeAttestation.proof_version ?? teeAttestation.proofVersion;
+}
+function assertProofShape(teeAttestation) {
+    if (teeAttestation.error) {
+        throw new Error(`${teeAttestation.error.code}: ${teeAttestation.error.message}`);
+    }
+    const proofVersion = getProofVersion(teeAttestation);
+    assert(typeof proofVersion === 'string' && SUPPORTED_PROOF_VERSIONS.includes(proofVersion), `unexpected proof version: ${proofVersion}`);
+    assert(teeAttestation.tee_provider === EXPECTED_TEE_PROVIDER, `unexpected tee provider: ${teeAttestation.tee_provider}`);
+    assert(teeAttestation.tee_technology === EXPECTED_TEE_TECHNOLOGY, `unexpected tee technology: ${teeAttestation.tee_technology}`);
+    assert(typeof teeAttestation.nonce === 'string' && teeAttestation.nonce.length > 0, 'tee attestation nonce missing');
+    assert(typeof teeAttestation.timestamp === 'string' && teeAttestation.timestamp.length > 0, 'tee attestation timestamp missing');
+    assert(!Number.isNaN(Date.parse(teeAttestation.timestamp)), 'tee attestation timestamp is invalid');
+    assert(typeof teeAttestation.workload?.image_digest === 'string' && teeAttestation.workload.image_digest.length > 0, 'workload image digest missing');
+    assert(typeof teeAttestation.verifier?.image_digest === 'string' && teeAttestation.verifier.image_digest.length > 0, 'verifier image digest missing');
+    assert(typeof teeAttestation.attestation?.token === 'string' && teeAttestation.attestation.token.length > 0, 'attestation token missing');
+}
+async function computeDigestBinding(teeAttestation) {
+    const proofVersion = getProofVersion(teeAttestation);
+    if (proofVersion === 'v3') {
+        assert(typeof teeAttestation.workload.container_name === 'string' && teeAttestation.workload.container_name.length > 0, 'workload container name missing');
+        assert(typeof teeAttestation.verifier.container_name === 'string' && teeAttestation.verifier.container_name.length > 0, 'verifier container name missing');
+        return sha256Hex([
+            'v3',
+            `workload.container_name=${teeAttestation.workload.container_name}`,
+            `workload.image_digest=${teeAttestation.workload.image_digest}`,
+            `verifier.container_name=${teeAttestation.verifier.container_name}`,
+            `verifier.image_digest=${teeAttestation.verifier.image_digest}`,
+        ].join('\n'));
+    }
+    return sha256Hex(`${teeAttestation.workload.image_digest}\n${teeAttestation.verifier.image_digest}`);
+}
+async function verifyGcpClaims(teeAttestation, expectedNonce) {
+    const claims = await verifyJwtSignature(teeAttestation.attestation.token, GCP_CONFIDENTIAL_SPACE_ISSUER);
+    assert(claims.iss === GCP_CONFIDENTIAL_SPACE_ISSUER, `unexpected issuer: ${claims.iss}`);
+    assertAudienceClaim(claims.aud);
+    assert(Array.isArray(claims.eat_nonce), 'eat_nonce claim missing');
+    const digestBinding = await computeDigestBinding(teeAttestation);
+    assert(claims.eat_nonce.includes(expectedNonce), 'request nonce is not present in attestation token');
+    assert(claims.eat_nonce.includes(digestBinding), 'digest-binding nonce is not present in attestation token');
+    assert(claims.hwmodel === EXPECTED_HW_MODEL, `unexpected hwmodel: ${claims.hwmodel}`);
+    assert(claims.secboot === true, 'secure boot claim is not true');
+    const submods = claims.submods;
+    assert(isRecord(submods) && submods.gce, 'gce submod claim missing');
+    assertTokenFresh(claims);
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+/**
+ * Validates the hardware TEE attestation included in the proof.
+ * Derives the application ID from `appSecret` and verifies the attestation
+ * was generated for your application.
+ * Returns a result object with `isVerified` and an optional `error` message.
+ *
+ * This check is stateless and does not protect against replay of a previously
+ * valid proof. Callers must enforce session matching and dedup `sessionId` on
+ * their server. See the README's "Replay Protection" section.
+ *
+ * @param proof - The proof containing TEE attestation data
+ * @param appSecret - Your application secret (Ethereum private key). Used to
+ *   derive the application ID and recompute the attestation nonce.
+ */
+export async function verifyTeeAttestation(proof, appSecret) {
+    assertNonBrowserEnvironment();
+    try {
+        const appId = legacyApplicationIdFromPrivateKey(appSecret);
+        let teeAttestation = proof.teeAttestation;
+        if (!teeAttestation) {
+            throw new Error('Missing teeAttestation in proof');
+        }
+        if (typeof teeAttestation === 'string') {
+            teeAttestation = JSON.parse(teeAttestation);
+        }
+        assertProofShape(teeAttestation);
+        const { parsedContext, nonceDataObj, expectedNonce } = parseProofContext(proof);
+        verifyApplicationAndSessionBinding(proof, parsedContext, nonceDataObj, appId);
+        verifyNonceMaterial(expectedNonce, nonceDataObj, appSecret);
+        const cleanExpectedNonce = normalizeHex(expectedNonce);
+        const cleanTeeNonce = normalizeHex(teeAttestation.nonce);
+        assert(cleanTeeNonce.length > 0, 'TEE attestation nonce is empty');
+        assert(isHex(cleanTeeNonce), 'TEE attestation nonce is not valid hex');
+        assert(cleanTeeNonce === cleanExpectedNonce, `Nonce Mismatch! Expected ${cleanExpectedNonce}, got ${cleanTeeNonce}`);
+        await verifyGcpClaims(teeAttestation, cleanExpectedNonce);
+        return { isVerified: true };
+    }
+    catch (error) {
+        return {
+            isVerified: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Verifies TEE attestation for all proofs.
+ * Throws `TeeVerificationError` if any proof is missing TEE data or fails verification.
+ *
+ * @param proofs - The proofs to verify
+ * @param config - TEE attestation configuration containing the app secret
+ * @throws {TeeVerificationError} When TEE data is missing or verification fails
+ */
+export async function runTeeVerification(proofs, config) {
+    const hasTeeData = proofs.every(proof => {
+        if (proof.teeAttestation) {
+            return true;
+        }
+        try {
+            const context = JSON.parse(proof.claimData.context);
+            return !!context?.attestationNonce;
+        }
+        catch {
+            return false;
+        }
+    });
+    if (!hasTeeData) {
+        throw new TeeVerificationError('TEE verification requested but one or more proofs are missing TEE attestation data');
+    }
+    const teeResults = await Promise.all(proofs.map(proof => verifyTeeAttestation(proof, config.appSecret)));
+    if (!teeResults.every(r => r.isVerified)) {
+        throw new TeeVerificationError('TEE attestation verification failed for one or more proofs');
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/client",
 	"title": "Reclaim Client",
-	"version": "0.1.27",
+	"version": "0.1.28",
 	"description": "Typed SDK/HTTP client SDK for the Reclaim Protocol — the programmatic way to use Reclaim Protocol to verify **data points** about your users (a follower count, an account balance, an order). Can be directly integrated by apps to request verification for their users using Reclaim Protocol and verify the results.",
 	"type": "module",
 	"sideEffects": false,
@@ -12,6 +12,10 @@
 			"types": "./lib/index.d.ts",
 			"import": "./lib/index.js"
 		},
+		"./api": {
+			"types": "./lib/api.d.ts",
+			"import": "./lib/api.js"
+		},
 		"./openapi": {
 			"types": "./lib/types/index.d.ts",
 			"import": "./lib/types/index.js"

package/src/api.ts

@@ -0,0 +1,15 @@
+export { ReclaimClient } from './client.ts'
+export type { ReclaimClientOptions } from './client.ts'
+export {
+	isProblemDetails,
+	isProblemError,
+	readProblemDetails,
+	throwProblemError,
+} from './errors.ts'
+export type { ProblemError } from './errors.ts'
+export {
+	DEFAULT_BASE_URL,
+	PROBLEM_CONTENT_TYPE,
+} from './consts.ts'
+export type * from './types/openapi.ts'
+export type * from './types/openapi.gen.ts'

package/src/attestor-proof.ts

@@ -63,6 +63,12 @@ export interface NestedProofOutcome {
 	attestorAddress?: string
 	/** Decoded claim data. */
 	claim?: Record<string, unknown>
+	/** Recovered signers, in nested JWS signature order. */
+	attestorAddresses?: string[]
+	/** Decoded protected headers, in nested JWS signature order. */
+	headers?: Record<string, unknown>[]
+	/** The raw nested signatures, in hex form. */
+	signatures?: string[]
 }
 
 /**
@@ -84,51 +90,82 @@ export function verifyNestedProof(
 		return { valid: false, reason: 'proof-not-jws' }
 	}
 
-	const sig = jws.signatures?.[0]
-	if(!jws.payload || !sig) {
+	if(!jws.payload || !jws.signatures?.length) {
 		return { valid: false, reason: 'proof-malformed' }
 	}
 
-	let header: Record<string, unknown>
 	let claim: Record<string, unknown>
 	try {
-		header = decodeJson(sig.protected)
 		claim = decodeJson(jws.payload)
 	} catch{
 		return { valid: false, reason: 'proof-decode-failed' }
 	}
 
-	let recovered: string
-	try {
-		recovered = recoverEthAddress(
-			eip191Digest(createSignData(claim)),
-			base64urlToBytes(sig.signature),
-		)
-	} catch{
-		return { valid: false, reason: 'recover-failed', claim }
+	const recoveredAddresses: string[] = []
+	const headers: Record<string, unknown>[] = []
+	const signatures: string[] = []
+	let firstFailure: NestedProofOutcome | undefined
+	for(const sig of jws.signatures) {
+		let header: Record<string, unknown>
+		let recovered: string
+		try {
+			header = decodeJson(sig.protected)
+			recovered = recoverEthAddress(
+				eip191Digest(createSignData(claim)),
+				base64urlToBytes(sig.signature),
+			)
+		} catch{
+			firstFailure ||= { valid: false, reason: 'recover-failed', claim }
+			continue
+		}
+
+		const kid = String(header.kid ?? '').toLowerCase()
+		if(recovered.toLowerCase() !== kid) {
+			firstFailure ||= {
+				valid: false,
+				reason: 'attestor-signature-mismatch',
+				attestorAddress: recovered,
+				claim,
+			}
+			continue
+		}
+
+		recoveredAddresses.push(recovered)
+		headers.push(header)
+		signatures.push('0x' + bytesToHex(base64urlToBytes(sig.signature)))
 	}
 
-	const kid = String(header.kid ?? '').toLowerCase()
-	if(recovered.toLowerCase() !== kid) {
+	if(!recoveredAddresses.length) {
 		return {
-			valid: false,
-			reason: 'attestor-signature-mismatch',
-			attestorAddress: recovered,
+			...(firstFailure ?? { valid: false, reason: 'recover-failed' }),
 			claim,
 		}
 	}
 
 	if(opts.attestorAddresses) {
 		const allow = opts.attestorAddresses.map((a) => a.toLowerCase())
-		if(!allow.includes(kid)) {
+		const allowedIndex = recoveredAddresses.findIndex(
+			(a) => allow.includes(a.toLowerCase()),
+		)
+		if(allowedIndex < 0) {
 			return {
 				valid: false,
 				reason: 'attestor-not-allowed',
-				attestorAddress: recovered,
+				attestorAddress: recoveredAddresses[0],
+				attestorAddresses: recoveredAddresses,
+				headers,
+				signatures,
 				claim,
 			}
 		}
 	}
 
-	return { valid: true, attestorAddress: recovered, claim }
+	return {
+		valid: true,
+		attestorAddress: recoveredAddresses[0],
+		attestorAddresses: recoveredAddresses,
+		headers,
+		signatures,
+		claim,
+	}
 }

package/src/client.ts

@@ -1,16 +1,10 @@
-import { notFound } from '@hapi/boom'
-import assert from 'node:assert'
 import type {
 	IOperationArgs,
 	IOperationId,
 	IOperationResponse,
 } from './types/openapi.ts'
-import { DEFAULT_BASE_URL, USER_AGENT } from './consts.ts'
+import { DEFAULT_BASE_URL } from './consts.ts'
 import { throwProblemError } from './errors.ts'
-// `ROUTES` is generated from `packages/app/openapi.yaml` and is the
-// single source of method/path mapping for every operation. New
-// endpoints added to the spec are picked up by re-running
-// `npm run openapi:typegen --workspace=packages/client`.
 import { ROUTES } from './routes.gen.ts'
 
 export type ReclaimClientOptions = {
@@ -25,12 +19,7 @@ export type ReclaimClientOptions = {
 }
 
 /**
- * Core HTTP client. Shared by the SDK entrypoint, MCP server, and CLI —
- * extend behavior here rather than duplicating it across surfaces.
- *
- * Per @reclaimprotocol/app conventions, validation lives in the openapi
- * spec; this client forwards requests and maps RFC 9457 problem responses
- * to {@link ProblemError}.
+ * Browser-safe typed HTTP client generated from the Builder OpenAPI contract.
  */
 export class ReclaimClient {
 	readonly baseUrl: string
@@ -43,7 +32,6 @@ export class ReclaimClient {
 		this.#token = opts.token
 		this.#fetch = opts.fetch || fetch
 		this.#headers = {
-			'User-Agent': USER_AGENT,
 			Accept: 'application/json',
 			...opts.headers,
 		}
@@ -63,20 +51,17 @@ export class ReclaimClient {
 			? [args?: IOperationArgs<T>]
 			: [args: IOperationArgs<T>]
 	): Promise<{ data: IOperationResponse<T>, response: Response }> {
-		const args = argsRest[0] ?? {} as IOperationArgs<T>
-		const op = ROUTES[operationId] as
-			| { method: string, path: string }
-			| undefined
-		assert(op, notFound(`Unknown operation: ${String(operationId)}`))
+		const args = argsRest[0]
+		const op = ROUTES[operationId]
 
 		let url = `${this.baseUrl}${op.path}`
-		if(args.params) {
+		if(args?.params) {
 			for(const [key, value] of Object.entries(args.params)) {
 				url = url.replace(`{${key}}`, String(value))
 			}
 		}
 
-		if(args.query && Object.keys(args.query).length > 0) {
+		if(args?.query && Object.keys(args.query).length > 0) {
 			const search = new URLSearchParams()
 			for(const [key, value] of Object.entries(args.query)) {
 				if(value === undefined || value === null) {
@@ -84,8 +69,8 @@ export class ReclaimClient {
 				}
 
 				if(Array.isArray(value)) {
-					for(const v of value) {
-						search.append(key, String(v))
+					for(const item of value) {
+						search.append(key, String(item))
 					}
 				} else {
 					search.append(key, String(value))
@@ -103,10 +88,7 @@ export class ReclaimClient {
 			headers['Authorization'] = `Bearer ${this.#token}`
 		}
 
-		// Per-request header parameters (for example, `If-Match` for optimistic
-		// concurrency). Applied last so spec-declared headers win over the
-		// client-wide defaults, but never override Authorization.
-		if(args.headers) {
+		if(args?.headers) {
 			for(const [key, value] of Object.entries(args.headers)) {
 				if(value === undefined || value === null) {
 					continue
@@ -120,27 +102,22 @@ export class ReclaimClient {
 			method: op.method.toUpperCase(),
 			headers,
 		}
-		// Write methods always carry a JSON body (defaulting to `{}`) plus a
-		// Content-Type. Some endpoints — for example, the auth-only attach session
-		// — take an empty body, and omitting Content-Type makes the server reject
-		// the request with `415 unsupported media type`.
 		const method = op.method.toLowerCase()
 		if(method !== 'get' && method !== 'head') {
-			init.body = JSON.stringify(args.body ?? {})
+			init.body = JSON.stringify(args?.body ?? {})
 			headers['Content-Type'] = 'application/json'
 		}
 
 		const res = await this.#fetch(url, init)
-
 		if(!res.ok) {
 			await throwProblemError(res)
 		}
 
-		if(res.status === 204 || res.headers.get('content-length') === '0') {
-			return { data: undefined as IOperationResponse<T>, response: res }
-		}
-
-		const data = await res.json() as IOperationResponse<T>
+		const empty = res.status === 204
+			|| res.headers.get('content-length') === '0'
+		const data = (
+			empty ? undefined : await res.json()
+		) as IOperationResponse<T>
 		return { data, response: res }
 	}
 }

package/src/consts.ts

@@ -1,5 +1,4 @@
-export const DEFAULT_BASE_URL =
-	process.env.RECLAIM_BASE_URL || 'https://build.reclaimprotocol.org'
+export const DEFAULT_BASE_URL = 'https://build.reclaimprotocol.org'
 
 export const USER_AGENT = '@reclaimprotocol/client'
 

package/src/eip191.ts

@@ -12,8 +12,8 @@ const ENC = new TextEncoder()
 
 /** Standard EIP-191 / personal_sign digest: keccak256 of
  *  `0x19 ‖ "Ethereum Signed Message:\n" ‖ len ‖ data`. */
-export function eip191Digest(data: string): Uint8Array {
-	const bytes = ENC.encode(data)
+export function eip191Digest(data: string | Uint8Array): Uint8Array {
+	const bytes = typeof data === 'string' ? ENC.encode(data) : data
 	const prefix = ENC.encode('\x19Ethereum Signed Message:\n')
 	const len = ENC.encode(String(bytes.length))
 	const merged = new Uint8Array(prefix.length + len.length + bytes.length)
@@ -28,7 +28,10 @@ export function eip191Digest(data: string): Uint8Array {
  *  `ethers.verifyMessage(message, signature)` accepts — noble's `'recovered'`
  *  format prepends the recovery byte instead, so it's reordered to the end
  *  here (a raw `0`/`1` recovery byte is fine there, no `+27` needed). */
-export function signEip191(message: string, privateKeyHex: string): string {
+export function signEip191(
+	message: string | Uint8Array,
+	privateKeyHex: string,
+): string {
 	const digest = eip191Digest(message)
 	const privateKey = hexToBytes(privateKeyHex)
 	const recovered = secp.sign(digest, privateKey, {
@@ -39,3 +42,28 @@ export function signEip191(message: string, privateKeyHex: string): string {
 	const rs = recovered.slice(1)
 	return '0x' + bytesToHex(rs) + recovery.toString(16).padStart(2, '0')
 }
+
+/** Recover the lowercase Ethereum address from an EIP-191 signature. */
+export function recoverEip191Address(
+	message: string | Uint8Array,
+	signatureHex: string,
+): string {
+	const signature = hexToBytes(signatureHex)
+	if(signature.length !== 65) {
+		throw new Error('EIP-191 signature must contain 65 bytes')
+	}
+
+	const recovery = signature[64] >= 27
+		? signature[64] - 27
+		: signature[64]
+	const recovered = new Uint8Array(65)
+	recovered[0] = recovery
+	recovered.set(signature.subarray(0, 64), 1)
+	const compressed = secp.recoverPublicKey(
+		recovered,
+		eip191Digest(message),
+		{ prehash: false },
+	)
+	const uncompressed = secp.Point.fromBytes(compressed).toBytes(false)
+	return '0x' + bytesToHex(keccak_256(uncompressed.slice(1))).slice(-40)
+}