@reclaimprotocol/client 0.1.0-dev.1 → 0.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/client",
 	"title": "Reclaim Client",
-	"version": "0.1.0-dev.1",
+	"version": "0.1.0",
 	"description": "Typed SDK client for @reclaimprotocol/app. Used by @reclaimprotocol/agent and any other consumer that needs programmatic API access without the full agent.",
 	"type": "module",
 	"main": "./lib/index.js",
@@ -10,6 +10,10 @@
 		".": {
 			"types": "./lib/index.d.ts",
 			"import": "./lib/index.js"
+		},
+		"./openapi": {
+			"types": "./lib/types/index.d.ts",
+			"import": "./lib/types/index.js"
 		}
 	},
 	"files": [
@@ -28,10 +32,10 @@
 	"websiteUrl": "https://docs.reclaimprotocol.org",
 	"scripts": {
 		"build": "tsc",
-		"openapi:typegen": "openapi-typescript ../app/openapi.yaml --output ./src/types/openapi.gen.ts && node ../app/scripts/mcp-tools-gen.ts",
 		"prepublishOnly": "npm run build",
 		"dev": "tsc --watch",
-		"test": "node --test tests/*.test.ts"
+		"test": "node --test tests/*.test.ts",
+		"check": "tsc -p tsconfig.test.json"
 	},
 	"keywords": [
 		"sdk",
@@ -45,7 +49,12 @@
 	},
 	"license": "MIT",
 	"dependencies": {
-		"@hapi/boom": "^9.1.4"
+		"@hapi/boom": "^9.1.4",
+		"@noble/hashes": "^2.2.0",
+		"@noble/secp256k1": "^3.1.0",
+		"@reclaimprotocol/attestor-core": "^5.0.7",
+		"canonicalize": "^2.1.0",
+		"jose": "^5.10.0"
 	},
 	"devDependencies": {
 		"@types/node": "^24.0.0",
@@ -53,4 +62,4 @@
 		"typescript": "^5.9.0",
 		"yaml": "^2.6.0"
 	}
-}
+}

package/src/attestor-proof.ts

@@ -0,0 +1,148 @@
+/**
+ * Verify a result's nested attestor proof (RFC 7515 JWS, base64url-encoded).
+ *
+ * The attestor signs the claim with a standard EIP-191 / `personal_sign`
+ * signature (`0x19 ‖ "Ethereum Signed Message:\n" ‖ len ‖ data`) over the
+ * canonical sign-data — NOT the JOSE signing input. The sign-data (and the
+ * claim identifier inside it) comes straight from
+ * `@reclaimprotocol/attestor-core`'s `createSignDataForClaim` (which calls
+ * `getIdentifierFromClaimInfo`), so this
+ * module stays in lockstep with the attestor by construction; it only adds the
+ * EIP-191 digest + secp256k1 address recovery and matches the JWS header `kid`.
+ */
+import { keccak_256 } from '@noble/hashes/sha3.js'
+import { createSignDataForClaim } from '@reclaimprotocol/attestor-core'
+import { base64urlToBytes, bytesToHex } from './encoding.ts'
+import { secp } from './secp.ts'
+
+const ENC = new TextEncoder()
+
+function decodeJson(b64url: string): Record<string, unknown> {
+	return JSON.parse(new TextDecoder().decode(base64urlToBytes(b64url)))
+}
+
+/** The canonical string the attestor signs for a claim — delegated to
+ *  attestor-core so the identifier hash + serialization can't drift. The
+ *  decoded claim's fields are coerced to attestor-core's `CompleteClaimData`
+ *  shape (context is always the JSON string the attestor signs over). */
+function createSignData(claim: Record<string, unknown>): string {
+	const raw = claim.context
+	const context = typeof raw === 'string'
+		? raw
+		: raw !== null && raw !== undefined
+			? JSON.stringify(raw)
+			: ''
+	return createSignDataForClaim({
+		provider: String(claim.provider ?? ''),
+		parameters: String(claim.parameters ?? ''),
+		context,
+		owner: String(claim.owner ?? ''),
+		timestampS: Number(claim.timestampS ?? 0),
+		epoch: Number(claim.epoch ?? 0),
+	})
+}
+
+/** Standard EIP-191 / personal_sign digest: keccak256 of
+ *  `0x19 ‖ "Ethereum Signed Message:\n" ‖ len ‖ data`. */
+function eip191Digest(data: string): Uint8Array {
+	const bytes = ENC.encode(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)
+	merged.set(prefix, 0)
+	merged.set(len, prefix.length)
+	merged.set(bytes, prefix.length + len.length)
+	return keccak_256(merged)
+}
+
+/** Recover the lowercase ETH address from a 65-byte r‖s‖v signature. */
+function recoverEthAddress(digest: Uint8Array, sig: Uint8Array): string {
+	const v = sig[64]
+	const recovery = v >= 27 ? v - 27 : v
+	const recovered = new Uint8Array(65)
+	recovered[0] = recovery
+	recovered.set(sig.subarray(0, 64), 1)
+	// digest is already the final keccak hash — don't let noble re-hash it.
+	const compressed = secp.recoverPublicKey(recovered, digest, {
+		prehash: false,
+	})
+	const uncompressed = secp.Point.fromBytes(compressed).toBytes(false)
+	return '0x' + bytesToHex(keccak_256(uncompressed.slice(1))).slice(-40)
+}
+
+export interface NestedProofOutcome {
+	valid: boolean
+	reason?: string
+	/** Recovered attestor ETH address. */
+	attestorAddress?: string
+	/** Decoded claim data. */
+	claim?: Record<string, unknown>
+}
+
+/**
+ * Verify a base64url-encoded nested attestor proof JWS: recover the attestor
+ * address from the claim signature and require it to match the header `kid`
+ * (and, if `attestorAddresses` is given, be in that allowlist).
+ */
+export function verifyNestedProof(
+	proofB64: string,
+	opts: { attestorAddresses?: string[] } = {},
+): NestedProofOutcome {
+	let jws: {
+		payload?: string
+		signatures?: { protected: string, signature: string }[]
+	}
+	try {
+		jws = JSON.parse(new TextDecoder().decode(base64urlToBytes(proofB64)))
+	} catch{
+		return { valid: false, reason: 'proof-not-jws' }
+	}
+
+	const sig = jws.signatures?.[0]
+	if(!jws.payload || !sig) {
+		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 kid = String(header.kid ?? '').toLowerCase()
+	if(recovered.toLowerCase() !== kid) {
+		return {
+			valid: false,
+			reason: 'attestor-signature-mismatch',
+			attestorAddress: recovered,
+			claim,
+		}
+	}
+
+	if(opts.attestorAddresses) {
+		const allow = opts.attestorAddresses.map((a) => a.toLowerCase())
+		if(!allow.includes(kid)) {
+			return {
+				valid: false,
+				reason: 'attestor-not-allowed',
+				attestorAddress: recovered,
+				claim,
+			}
+		}
+	}
+
+	return { valid: true, attestorAddress: recovered, claim }
+}

package/src/canonical.ts

@@ -0,0 +1,20 @@
+/**
+ * RFC 8785 (JSON Canonicalization Scheme) stringification — object keys sorted
+ * recursively, no whitespace, canonical number/string forms. The single source
+ * of truth for canonical JSON in the SDK: the attestor `contentHash` binding
+ * and provider `context` hashing both use it. Do not reimplement with a sorted
+ * `JSON.stringify`.
+ */
+import { badData } from '@hapi/boom'
+import * as canonicalizeMod from 'canonicalize'
+import assert from 'node:assert'
+
+// canonicalize ships as a CJS default export; resolve it across interop modes.
+const canonicalize = ((canonicalizeMod as { default?: unknown }).default
+	?? canonicalizeMod) as (input: unknown) => string | undefined
+
+export function canonicalJson(value: unknown): string {
+	const out = canonicalize(value)
+	assert(out !== undefined, badData('value is not JSON-serializable'))
+	return out
+}

package/src/enckeys.ts

@@ -0,0 +1,46 @@
+/**
+ * X25519 encryption-key helpers for JWE result delivery (RFC 7516,
+ * `ECDH-ES + A256GCM`), all via `jose`. Consumers mint the keypair themselves
+ * with openssl (we never generate keys for them):
+ *
+ *   # private (PKCS#8):
+ *   openssl genpkey -algorithm X25519 -out reclaim-x25519.pem
+ *   # public (SPKI):
+ *   openssl pkey -in reclaim-x25519.pem -pubout \
+ *     -out reclaim-x25519.pub.pem
+ *
+ * Register the PUBLIC PEM as the org credential (`reclaim.credential.set` turns
+ * it into the JWK the API stores) and keep the PRIVATE PEM to decrypt delivered
+ * results (`results.receive(body, { credential: <private PEM> })`). Pass PEM
+ * *content* — never a file path or env var. Eth is not involved in encryption;
+ * it only signs/verifies the inner JWS (see ./result.ts, ./secp.ts).
+ */
+import type { JWK } from 'jose'
+import { exportJWK, importPKCS8, importSPKI } from 'jose'
+
+/** A jose-usable private key — what `importPKCS8` returns and what
+ *  `compactDecrypt` accepts as the recipient key. */
+export type DecryptionKey = Awaited<ReturnType<typeof importPKCS8>>
+
+/** The consumer's X25519 private key as a PKCS#8 PEM string — the *content* of
+ *  `openssl genpkey -algorithm X25519` (the `-----BEGIN PRIVATE KEY-----`
+ *  block), not a path or env-var name. */
+export type DecryptionKeyInput = string
+
+const ALG = 'ECDH-ES'
+
+/** Load an X25519 PKCS#8 PEM (the openssl `BEGIN PRIVATE KEY` block) as the
+ *  `ECDH-ES` recipient key for `compactDecrypt`. Pass the PEM content. */
+export async function loadDecryptionKey(
+	pem: DecryptionKeyInput,
+): Promise<DecryptionKey> {
+	return (await importPKCS8(pem.trim(), ALG))
+}
+
+/** Convert an X25519 SPKI public PEM (the openssl `BEGIN PUBLIC KEY` block) to
+ *  the public JWK the API stores and the Verification Client encrypts to — so a
+ *  consumer only ever handles PEM, never a JWK. */
+export async function publicPemToJwk(pem: string): Promise<JWK> {
+	const key = await importSPKI(pem.trim(), ALG, { extractable: true })
+	return exportJWK(key)
+}

package/src/encoding.ts

@@ -0,0 +1,39 @@
+/**
+ * Byte / hex / base64url encoders shared across the verification crypto paths
+ * (result, jwks, attestor-proof). `hexToBytes` tolerates an optional `0x`
+ * prefix, matching how ETH keys/addresses are passed around.
+ */
+export function hexToBytes(hex: string): Uint8Array {
+	const clean = hex.startsWith('0x') ? hex.slice(2) : hex
+	const out = new Uint8Array(clean.length / 2)
+	for(let i = 0; i < out.length; i++) {
+		out[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16)
+	}
+
+	return out
+}
+
+export function bytesToHex(bytes: Uint8Array): string {
+	let out = ''
+	for(const b of bytes) {
+		out += b.toString(16).padStart(2, '0')
+	}
+
+	return out
+}
+
+/** Decode a base64url string (with or without padding) to bytes. */
+export function base64urlToBytes(s: string): Uint8Array {
+	const b64 = s.replace(/-/g, '+').replace(/_/g, '/')
+	const pad = b64.length % 4 ? '='.repeat(4 - (b64.length % 4)) : ''
+	return Uint8Array.from(Buffer.from(b64 + pad, 'base64'))
+}
+
+/** Encode bytes (or a UTF-8 string) as unpadded base64url. */
+export function b64url(input: Uint8Array | string): string {
+	return Buffer.from(input as Uint8Array)
+		.toString('base64')
+		.replace(/\+/g, '-')
+		.replace(/\//g, '_')
+		.replace(/=+$/, '')
+}

package/src/index.ts

@@ -1,10 +1,68 @@
 export * from './client.ts'
 export type * from './client.ts'
-export { ProblemError, type ProblemDetails } from './errors.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 {
+	addressFromPublicKey,
 	deriveFromPrivateKey,
 	type EthKeypair,
 	generateKeypair,
 } from './keypair.ts'
-export * from './types/index.ts'
+export { canonicalJson } from './canonical.ts'
+export {
+	b64url,
+	base64urlToBytes,
+	bytesToHex,
+	hexToBytes,
+} from './encoding.ts'
+export {
+	addressFromUncompressedPubkey,
+	secp,
+} from './secp.ts'
+export {
+	type CallbackBody,
+	decodeJwsPayload,
+	decryptCallback,
+	type DeliveryEnvelope,
+	encryptForPublicJwk,
+	type Jws,
+	ResultVerificationError,
+	type ResultProofOutcome,
+	signResultJws,
+	verifyJwsSignature,
+	verifyResult,
+	verifyResultFull,
+	type VerifyResultFullOptions,
+	type VerifyResultFullOutcome,
+	type VerifyResultOptions,
+	type VerifyResultOutcome,
+} from './result.ts'
+export {
+	type DecryptionKey,
+	type DecryptionKeyInput,
+	loadDecryptionKey,
+	publicPemToJwk,
+} from './enckeys.ts'
+export {
+	createReclaim,
+	type CreateSessionInput,
+	type Reclaim,
+	type ReclaimConfig,
+	type ReceiveOptions,
+	type ReceivedDelivery,
+	type RegisterCallbackInput,
+	type SetCredentialInput,
+	TERMINAL_EVENTS,
+} from './reclaim.ts'
+export {
+	fetchJwks,
+	type Jwk,
+	jwksFromPrivateKey,
+	jwkToUncompressedPublicKey,
+	selectKey,
+} from './jwks.ts'
+export {
+	type NestedProofOutcome,
+	verifyNestedProof,
+} from './attestor-proof.ts'

package/src/jwks.ts

@@ -0,0 +1,86 @@
+/**
+ * JWKS (RFC 7517) discovery for verifying result/proof signatures. Signers
+ * (the Verification Client, the Attestor) publish their secp256k1 public keys
+ * at `<iss>/.well-known/jwks.json` with `kid` = the signer's ETH address.
+ */
+import { b64url, base64urlToBytes, bytesToHex } from './encoding.ts'
+import { addressFromUncompressedPubkey, secp } from './secp.ts'
+
+export interface Jwk {
+	kty: string
+	crv: string
+	x: string
+	y: string
+	kid?: string
+	alg?: string
+	use?: string
+}
+
+/**
+ * Build the JWK set for an ES256K signing key (the Verification Client's
+ * 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[] } {
+	if(!privateKeyHex) {
+		return { keys: [] }
+	}
+
+	const priv = privateKeyHex.replace(/^0x/, '')
+	const pub = secp.getPublicKey(
+		Uint8Array.from(Buffer.from(priv, 'hex')),
+		false, // uncompressed: 0x04 ‖ X ‖ Y
+	)
+	return {
+		keys: [
+			{
+				kty: 'EC',
+				crv: 'secp256k1',
+				alg: 'ES256K',
+				use: 'sig',
+				kid: addressFromUncompressedPubkey(pub),
+				x: b64url(pub.subarray(1, 33)),
+				y: b64url(pub.subarray(33, 65)),
+			},
+		],
+	}
+}
+
+/** Fetch the JWK set published at `<iss>/.well-known/jwks.json`. */
+export async function fetchJwks(
+	iss: string,
+	fetchImpl: typeof fetch = fetch,
+): Promise<Jwk[]> {
+	const base = iss.replace(/\/+$/, '')
+	const res = await fetchImpl(`${base}/.well-known/jwks.json`)
+	if(!res.ok) {
+		throw new Error(`JWKS fetch failed for ${base}: HTTP ${res.status}`)
+	}
+
+	const body = (await res.json()) as { keys?: Jwk[] }
+	return body.keys ?? []
+}
+
+/** Find the key matching `kid` (case-insensitive — kids are ETH addresses). */
+export function selectKey(keys: Jwk[], kid: string): Jwk | undefined {
+	const want = kid.toLowerCase()
+	return keys.find((k) => (k.kid ?? '').toLowerCase() === want)
+}
+
+/**
+ * Reconstruct the uncompressed secp256k1 public key (`0x04` + X + Y) from an
+ * EC JWK's base64url `x`/`y` coordinates, for signature verification.
+ */
+export function jwkToUncompressedPublicKey(jwk: Jwk): string {
+	const x = base64urlToBytes(jwk.x)
+	const y = base64urlToBytes(jwk.y)
+	if(x.length !== 32 || y.length !== 32) {
+		throw new Error('invalid EC JWK: x/y must be 32 bytes each')
+	}
+
+	const out = new Uint8Array(65)
+	out[0] = 0x04
+	out.set(x, 1)
+	out.set(y, 33)
+	return '0x' + bytesToHex(out)
+}

package/src/keypair.ts

@@ -1,9 +1,14 @@
 import { keccak_256 } from '@noble/hashes/sha3.js'
+import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js'
 import * as secp from '@noble/secp256k1'
 
 export type EthKeypair = {
 	address: string
 	privateKey: string
+	/** Uncompressed secp256k1 public key (`0x04` + 128 hex). Used to derive the
+	 *  ETH address and to verify ES256K JWS signatures (published via JWKS as
+	 *  `x`/`y`). Result *encryption* now uses X25519 JWE, not this key. */
+	publicKey: string
 }
 
 /**
@@ -21,8 +26,9 @@ export function generateKeypair(): EthKeypair {
 	const priv = secp.utils.randomSecretKey()
 	const pub = secp.getPublicKey(priv, false)
 	return {
-		address: '0x' + bytesToHex(keccak_256(pub.slice(1))).slice(-40),
+		address: addressFromPubBytes(pub),
 		privateKey: '0x' + bytesToHex(priv),
+		publicKey: '0x' + bytesToHex(pub),
 	}
 }
 
@@ -35,29 +41,25 @@ export function deriveFromPrivateKey(privateKey: string): EthKeypair {
 	const priv = hexToBytes(hex)
 	const pub = secp.getPublicKey(priv, false)
 	return {
-		address: '0x' + bytesToHex(keccak_256(pub.slice(1))).slice(-40),
+		address: addressFromPubBytes(pub),
 		privateKey: '0x' + hex,
+		publicKey: '0x' + bytesToHex(pub),
 	}
 }
 
-function bytesToHex(bytes: Uint8Array): string {
-	let out = ''
-	for(const b of bytes) {
-		out += b.toString(16).padStart(2, '0')
-	}
-
-	return out
+/**
+ * Derive the lowercase Ethereum address that owns an uncompressed secp256k1
+ * public key (`0x04` + 128 hex) — keccak-256 of the key minus the `0x04`
+ * prefix byte, last 20 bytes. The holder of the matching private key controls
+ * this address; used to scope a callback subscription to its key's owner
+ * without ever needing the private key.
+ */
+export function addressFromPublicKey(publicKey: string): string {
+	return addressFromPubBytes(hexToBytes(publicKey.replace(/^0x/, '')))
 }
 
-function hexToBytes(hex: string): Uint8Array {
-	if(hex.length % 2 !== 0) {
-		throw new Error('private key hex must have even length')
-	}
-
-	const out = new Uint8Array(hex.length / 2)
-	for(let i = 0; i < out.length; i++) {
-		out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16)
-	}
-
-	return out
+/** keccak-256 of the uncompressed pubkey minus its `0x04` prefix byte,
+ *  last 20 bytes — the Ethereum address derivation, lowercase (no checksum). */
+function addressFromPubBytes(pub: Uint8Array): string {
+	return '0x' + bytesToHex(keccak_256(pub.slice(1))).slice(-40)
 }