@reclaimprotocol/client 0.1.0 → 0.1.2

package/package.json

@@ -1,9 +1,10 @@
 {
 	"name": "@reclaimprotocol/client",
 	"title": "Reclaim Client",
-	"version": "0.1.0",
+	"version": "0.1.2",
 	"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",
+	"sideEffects": false,
 	"main": "./lib/index.js",
 	"types": "./lib/index.d.ts",
 	"exports": {
@@ -14,6 +15,10 @@
 		"./openapi": {
 			"types": "./lib/types/index.d.ts",
 			"import": "./lib/types/index.js"
+		},
+		"./enckeys": {
+			"types": "./lib/enckeys.d.ts",
+			"import": "./lib/enckeys.js"
 		}
 	},
 	"files": [
@@ -54,7 +59,7 @@
 		"@noble/secp256k1": "^3.1.0",
 		"@reclaimprotocol/attestor-core": "^5.0.7",
 		"canonicalize": "^2.1.0",
-		"jose": "^5.10.0"
+		"eciesjs": "^0.4.15"
 	},
 	"devDependencies": {
 		"@types/node": "^24.0.0",

package/src/enckeys.ts

@@ -1,46 +1,125 @@
 /**
- * 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):
+ * secp256k1 (Ethereum) encryption-key helpers for ECIES result delivery.
  *
- *   # 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
+ * The org's encryption key is its **Ethereum public key** (secp256k1). The
+ * Verification Client ECIES-encrypts the signed JWS to it (see ./result.ts) and
+ * the Consumer decrypts with the matching eth **private key**. Eth-native `0x`
+ * hex is used everywhere at the edges (the format MetaMask/ethers/wallets
+ * emit); the wire/DB store the public key as a secp256k1 JWK
+ * (`{kty:'EC',crv:'secp256k1',x,y}`), matching the signing JWKS shape in
+ * ./jwks.ts.
  *
- * 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).
+ * No PEM, no DER, no WebCrypto — `@noble/secp256k1` handles hex in every
+ * runtime.
  */
-import type { JWK } from 'jose'
-import { exportJWK, importPKCS8, importSPKI } from 'jose'
+import { b64url, hexToBytes } from './encoding.ts'
+import { type Jwk, jwkToUncompressedPublicKey } from './jwks.ts'
+import {
+	addressFromPublicKey,
+	deriveFromPrivateKey,
+	generateKeypair,
+} from './keypair.ts'
 
-/** 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. */
+/** The Consumer's eth private key as `0x`+64 hex (a 32-byte secp256k1
+ *  scalar). */
 export type DecryptionKeyInput = string
+/** The raw 32-byte private scalar — what `eciesjs.decrypt` consumes. */
+export type DecryptionKey = Uint8Array
+
+const ETH_PRIVATE_HEX = /^0x[0-9a-fA-F]{64}$/
+const UNCOMPRESSED_PUBKEY_HEX = /^0x04[0-9a-fA-F]{128}$/
+
+/**
+ * Validate and load an eth private key (`0x`+64 hex) into the raw scalar bytes
+ * `eciesjs.decrypt` needs. Pass the hex content — never a path or env-var name.
+ */
+export function loadDecryptionKey(input: DecryptionKeyInput): DecryptionKey {
+	const v = input.trim().replace(/^['"]|['"]$/g, '')
+	const hex = v.startsWith('0x') ? v : '0x' + v
+	if(!ETH_PRIVATE_HEX.test(hex)) {
+		throw new Error(
+			'not a valid Ethereum private key (expected a 32-byte / 0x+64-hex '
+				+ 'scalar)',
+		)
+	}
+
+	return hexToBytes(hex)
+}
+
+/**
+ * Convert an uncompressed secp256k1 public key (`0x04` + 128 hex) to the public
+ * JWK the API stores and the Verification Client encrypts to — so callers only
+ * ever handle eth-native hex, never a JWK. Mirrors the `x`/`y` coordinate split
+ * in `jwksFromPrivateKey` (./jwks.ts).
+ */
+export function uncompressedPubkeyToJwk(publicKeyHex: string): Jwk {
+	const v = publicKeyHex.trim()
+	const hex = v.startsWith('0x') ? v : '0x' + v
+	if(!UNCOMPRESSED_PUBKEY_HEX.test(hex)) {
+		throw new Error(
+			'not a valid uncompressed secp256k1 public key '
+				+ '(expected `0x04` + 128 hex)',
+		)
+	}
+
+	const bytes = hexToBytes(hex) // 65 bytes: 0x04 ‖ X ‖ Y
+	return {
+		kty: 'EC',
+		crv: 'secp256k1',
+		x: b64url(bytes.subarray(1, 33)),
+		y: b64url(bytes.subarray(33, 65)),
+	}
+}
 
-const ALG = 'ECDH-ES'
+/** Lowercase 0x ETH address that owns a secp256k1 public JWK (the org's
+ *  identity address). */
+export function pubkeyJwkToEthAddress(jwk: Jwk): string {
+	return addressFromPublicKey(jwkToUncompressedPublicKey(jwk))
+}
+
+/** A freshly generated org encryption keypair, in every form callers need:
+ *  the eth `0x`-hex private key (kept by the Consumer to decrypt), the
+ *  uncompressed public key hex, the public JWK (sent to the API / stored), and
+ *  the derived eth address. */
+export interface GeneratedEthKeypair {
+	privateKeyHex: string
+	publicKeyHex: string
+	publicJwk: Jwk
+	ethAddress: string
+}
 
-/** 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))
+/** Mint a fresh secp256k1 keypair for org encryption — the in-browser dashboard
+ *  generator, the SDK, and tests all use this so every keypair is shaped the
+ *  same way. The private key MUST stay local; only the public JWK is sent. */
+export function generateEthKeypair(): GeneratedEthKeypair {
+	const { privateKey, publicKey, address } = generateKeypair()
+	return {
+		privateKeyHex: privateKey,
+		publicKeyHex: publicKey,
+		publicJwk: uncompressedPubkeyToJwk(publicKey),
+		ethAddress: address,
+	}
 }
 
-/** 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)
+/** Derive the same `GeneratedEthKeypair` shape from a private key the user
+ *  already holds (`0x`+64 hex), so they can BYO a key instead of generating
+ *  one. Validates the format and throws otherwise. The private key stays
+ *  local — only the derived public key/address are ever surfaced. */
+export function ethKeypairFromPrivateKey(input: string): GeneratedEthKeypair {
+	const v = input.trim().replace(/^['"]|['"]$/g, '')
+	const hex = v.startsWith('0x') ? v : '0x' + v
+	if(!ETH_PRIVATE_HEX.test(hex)) {
+		throw new Error(
+			'not a valid Ethereum private key (expected a 32-byte / 0x+64-hex '
+				+ 'scalar)',
+		)
+	}
+
+	const { privateKey, publicKey, address } = deriveFromPrivateKey(hex)
+	return {
+		privateKeyHex: privateKey,
+		publicKeyHex: publicKey,
+		publicJwk: uncompressedPubkeyToJwk(publicKey),
+		ethAddress: address,
+	}
 }

package/src/encoding.ts

@@ -2,6 +2,11 @@
  * 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.
+ *
+ * base64url uses the `atob`/`btoa` globals + `TextEncoder` rather than Node's
+ * `Buffer` so the same code runs in the browser (the in-page keypair
+ * generator) — `Buffer` is undefined there. Both globals exist in Node ≥ 16
+ * and every browser.
  */
 export function hexToBytes(hex: string): Uint8Array {
 	const clean = hex.startsWith('0x') ? hex.slice(2) : hex
@@ -26,13 +31,26 @@ export function bytesToHex(bytes: Uint8Array): string {
 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'))
+	const bin = atob(b64 + pad)
+	const out = new Uint8Array(bin.length)
+	for(let i = 0; i < bin.length; i++) {
+		out[i] = bin.charCodeAt(i)
+	}
+
+	return out
 }
 
 /** 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')
+	const bytes = typeof input === 'string'
+		? new TextEncoder().encode(input)
+		: input
+	let bin = ''
+	for(const b of bytes) {
+		bin += String.fromCharCode(b)
+	}
+
+	return btoa(bin)
 		.replace(/\+/g, '-')
 		.replace(/\//g, '_')
 		.replace(/=+$/, '')

package/src/index.ts

@@ -25,7 +25,7 @@ export {
 	decodeJwsPayload,
 	decryptCallback,
 	type DeliveryEnvelope,
-	encryptForPublicJwk,
+	encryptForEthPublicKey,
 	type Jws,
 	ResultVerificationError,
 	type ResultProofOutcome,
@@ -41,8 +41,11 @@ export {
 export {
 	type DecryptionKey,
 	type DecryptionKeyInput,
+	generateEthKeypair,
+	type GeneratedEthKeypair,
 	loadDecryptionKey,
-	publicPemToJwk,
+	pubkeyJwkToEthAddress,
+	uncompressedPubkeyToJwk,
 } from './enckeys.ts'
 export {
 	createReclaim,
@@ -52,7 +55,7 @@ export {
 	type ReceiveOptions,
 	type ReceivedDelivery,
 	type RegisterCallbackInput,
-	type SetCredentialInput,
+	type SetKeypairInput,
 	TERMINAL_EVENTS,
 } from './reclaim.ts'
 export {

package/src/keypair.ts

@@ -6,11 +6,28 @@ 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. */
+	 *  ETH address, to verify ES256K JWS signatures (published via JWKS as
+	 *  `x`/`y`), and — for an org's encryption key — to ECIES-encrypt results
+	 *  (see ./enckeys.ts, ./result.ts). */
 	publicKey: string
 }
 
+/** Bytes of CSPRNG seed `@noble`'s `randomSecretKey` expects (it reduces a
+ *  ≥48-byte seed into a valid secp256k1 scalar). */
+const SECRET_KEY_SEED_LEN = 48
+
+/**
+ * Fresh CSPRNG bytes from the Web Crypto API. We read `crypto`
+ * (`getRandomValues`) — the WHATWG global present in browsers and Node ≥ 20
+ * alike — and SEED `@noble`'s key generation from it, rather than letting
+ * `@noble` dereference `globalThis.crypto` itself: its access is unguarded
+ * (`(globalThis?.crypto).getRandomValues(...)`) and throws an opaque
+ * TypeError wherever the global is absent.
+ */
+function randomSeed(): Uint8Array {
+	return crypto.getRandomValues(new Uint8Array(SECRET_KEY_SEED_LEN))
+}
+
 /**
  * Generate a fresh secp256k1 key-pair and derive its lowercase
  * Ethereum address (keccak-256 of the uncompressed pubkey minus the
@@ -23,7 +40,7 @@ export type EthKeypair = {
  * intermediate value used to compute the address and is not retained.
  */
 export function generateKeypair(): EthKeypair {
-	const priv = secp.utils.randomSecretKey()
+	const priv = secp.utils.randomSecretKey(randomSeed())
 	const pub = secp.getPublicKey(priv, false)
 	return {
 		address: addressFromPubBytes(pub),

package/src/reclaim.ts

@@ -2,18 +2,18 @@
  * Declarative entry point for the consumer SDK. The ONLY config is the org
  * secret (`rorg_…`) — it authenticates every call and identifies the org
  * server-side. Everything else is passed where it's actually used: the `orgId`
- * to the org-scoped `credential.set`/`get`, and the X25519 decryption key to
+ * to the org-scoped `keypair.set`/`get`, and the eth decryption key to
  * `results.decrypt`/`receive` (only when results arrive encrypted):
  *
  *   const reclaim = createReclaim({ orgSecret })
  *   // one-time setup:
  *   await reclaim.callbacks.register({ callbackUrl })
- *   // enable encryption:
- *   await reclaim.credential.set(orgId, { publicKeyJwk })
- *   const session = await reclaim.sessions.create({ providerId, context })
+ *   // enable encryption (eth public key, hex):
+ *   await reclaim.keypair.set(orgId, { publicKey, canEncryptResult: true })
+ *   const session = await reclaim.sessions.create({ providers, context })
  *   // …end-user completes session.verificationUrl…
  *   const outcome = await reclaim.results.receive(callbackBody, {
- *   	credential: privateJwk, // omit for plaintext
+ *   	credential: ethPrivateKeyHex, // omit for plaintext
  *   	expectedReclaimSessionId: session.id,
  *   })
  *
@@ -27,7 +27,6 @@ import {
 	type DecryptionKey,
 	type DecryptionKeyInput,
 	loadDecryptionKey,
-	publicPemToJwk,
 } from './enckeys.ts'
 import {
 	type CallbackBody,
@@ -42,8 +41,8 @@ type CallbackSubscription = components['schemas']['CallbackSubscription']
 type VerificationSession = components['schemas']['VerificationSession']
 type VerificationEvent = components['schemas']['VerificationEvent']
 type VerificationEventRecord = components['schemas']['VerificationEventRecord']
-type OrgCredential = components['schemas']['OrgCredential']
-type JwkX25519Public = components['schemas']['JwkX25519Public']
+type OrgKeypair = components['schemas']['OrgKeypair']
+type OrgKeypairRequest = components['schemas']['OrgKeypairRequest']
 
 /** The three terminal events a subscription can receive. */
 export const TERMINAL_EVENTS = [
@@ -58,22 +57,23 @@ export interface RegisterCallbackInput {
 }
 
 export interface CreateSessionInput {
-	providerId: string
-	version?: string
+	/** Providers to verify, in run order. The end-user proves each (one browser
+	 *  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. */
 	verificationClientUrl: string
 }
 
-export interface SetCredentialInput {
-	/** The org's X25519 encryption public key as an SPKI PEM — the content of
-	 *  `openssl pkey -in key.pem -pubout` (the `-----BEGIN PUBLIC KEY-----`
-	 *  block). It's converted to a JWK and stored; results are JWE-encrypted to
-	 *  it. Keep the matching private PEM to decrypt (pass it to
-	 *  `results.receive`/`decrypt`). */
-	publicKeyPem: string
-	label?: string
-}
+/** Input for `keypair.set`: the org's eth public key as uncompressed hex
+ *  (`publicKey`, the form wallets/ethers emit) OR as a secp256k1 JWK
+ *  (`publicKeyJwk`); keep the matching eth private key to decrypt results.
+ *  `canEncryptResult` toggles ECIES encryption (default off). The two request
+ *  shapes are the spec's `OrgKeypairRequest` union members, relaxed to optional
+ *  so the SDK caller supplies just one key form. */
+export type SetKeypairInput =
+	& Partial<components['schemas']['OrgKeypairHexRequest']>
+	& Partial<components['schemas']['OrgKeypairJwkRequest']>
 
 export interface ReclaimConfig {
 	/** The org secret (`rorg_…`). Authenticates ALL API calls and identifies
@@ -88,8 +88,8 @@ export interface ReclaimConfig {
 }
 
 /** Options for `results.receive` — the verification options plus an optional
- *  X25519 decryption key (a JWK, a PKCS#8 PEM string, or `{ env }` / env-var
- *  name). The key is needed only when the delivery is an encrypted (JWE). */
+ *  eth decryption key (the org's eth private key as `0x`-hex). The key is
+ *  needed only when the delivery is an ECIES ciphertext. */
 export type ReceiveOptions = VerifyResultFullOptions & {
 	credential?: DecryptionKeyInput
 }
@@ -110,9 +110,9 @@ export interface Reclaim {
 	}
 	callbacks: {
 		/** Register a callback subscription (one-time setup). Delivery is scoped
-		 *  to the token's org; results are JWE-encrypted to the org's credential
-		 *  when one is set (see `credential.set`), else plaintext. `events`
-		 *  defaults to all three terminal events. */
+		 *  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. */
 		register(
 			input: Partial<RegisterCallbackInput> &
 				Pick<RegisterCallbackInput, 'callbackUrl'>,
@@ -120,18 +120,19 @@ export interface Reclaim {
 		list(): Promise<CallbackSubscription[]>
 		remove(subscriptionId: string): Promise<void>
 	}
-	credential: {
-		/** Set/replace org `orgId`'s single X25519 encryption credential. Once
-		 *  set, terminal results are delivered as a compact JWE encrypted to it. */
-		set(orgId: string, input: SetCredentialInput): Promise<OrgCredential>
-		/** Get org `orgId`'s encryption credential, or `undefined` when none is
-		 *  set (delivery is plaintext). */
-		get(orgId: string): Promise<OrgCredential | undefined>
+	keypair: {
+		/** Set/rotate org `orgId`'s single eth encryption keypair. When
+		 *  `canEncryptResult` is enabled, terminal results are delivered as an
+		 *  ECIES ciphertext encrypted to it. */
+		set(orgId: string, input: SetKeypairInput): Promise<OrgKeypair>
+		/** Get org `orgId`'s encryption keypair, or `undefined` when none is set
+		 *  (the org is keyless ⇒ plaintext delivery). */
+		get(orgId: string): Promise<OrgKeypair | undefined>
 	}
 	results: {
-		/** Decrypt a callback body (JWE or plaintext JWS) to the signed JWS.
-		 *  Pass the X25519 `credential` (JWK/PEM/env) only when the delivery is
-		 *  a JWE. */
+		/** Decrypt a callback body (ECIES ciphertext or plaintext JWS) to the
+		 *  signed JWS. Pass the eth `credential` (`0x`-hex private key) only when
+		 *  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. */
@@ -177,14 +178,12 @@ export function createReclaim(config: ReclaimConfig): Reclaim {
 		headers: config.headers,
 	})
 
-	// Load an X25519 decryption key on demand — `undefined` input ⇒ no key, so
+	// Load the eth decryption key on demand — `undefined` input ⇒ no key, so
 	// plaintext-only consumers never touch the loader.
 	const resolveKey = (
 		input: DecryptionKeyInput | undefined,
-	): Promise<DecryptionKey | undefined> => (
-		input === undefined
-			? Promise.resolve(undefined)
-			: loadDecryptionKey(input)
+	): DecryptionKey | undefined => (
+		input === undefined ? undefined : loadDecryptionKey(input)
 	)
 
 	return {
@@ -232,27 +231,31 @@ export function createReclaim(config: ReclaimConfig): Reclaim {
 				})
 			},
 		},
-		credential: {
+		keypair: {
 			async set(orgId, input) {
-				// Convert the consumer's SPKI public PEM to the JWK the API stores
-				// (PEM at the edge; JWK on the wire/DB/VC stays unchanged).
-				const publicKeyJwk = (await publicPemToJwk(
-					input.publicKeyPem,
-				)) as JwkX25519Public
-				const { data } = await client.call('SetOrgCredential', {
+				// Forward the eth public key as given (hex or JWK); the API stores
+				// the secp256k1 JWK + derived address.
+				const body = {
+					...(input.publicKeyJwk
+						? { publicKeyJwk: input.publicKeyJwk }
+						: { publicKey: input.publicKey }),
+					canEncryptResult: input.canEncryptResult ?? false,
+					...(input.label ? { label: input.label } : {}),
+				} as OrgKeypairRequest
+				const { data } = await client.call('SetOrgKeypair', {
 					params: { orgId },
-					body: { publicKeyJwk, label: input.label },
+					body,
 				})
 				return data
 			},
 			async get(orgId) {
 				try {
-					const { data } = await client.call('GetOrgCredential', {
+					const { data } = await client.call('GetOrgKeypair', {
 						params: { orgId },
 					})
 					return data
 				} catch(err) {
-					// 404 ⇒ no credential set (plaintext delivery).
+					// 404 ⇒ keyless org (plaintext delivery).
 					if(isNotFound(err)) {
 						return undefined
 					}
@@ -263,7 +266,7 @@ export function createReclaim(config: ReclaimConfig): Reclaim {
 		},
 		results: {
 			async decrypt(body, credential) {
-				return decryptCallback(await resolveKey(credential), body)
+				return decryptCallback(resolveKey(credential), body)
 			},
 			verify(jws, opts) {
 				return verifyResultFull(jws, { fetchImpl: config.fetch, ...opts })
@@ -292,7 +295,7 @@ export function createReclaim(config: ReclaimConfig): Reclaim {
 				}
 
 				const { credential, ...verifyOpts } = opts ?? {}
-				const key = await resolveKey(credential)
+				const key = resolveKey(credential)
 				const jws = await decryptCallback(key, body)
 				const result = await verifyResultFull(jws, {
 					fetchImpl: config.fetch,