@reclaimprotocol/client 0.1.0 → 0.1.2

package/README.md

@@ -4,18 +4,19 @@ Typed SDK for the Reclaim Builder API. One package gives you:
 
 - **`createReclaim(...)`** — a small, declarative client for the consumer happy path: create verification sessions, register callbacks, and receive + verify results.
 - **`ReclaimClient`** — a low-level typed HTTP client (`call('OperationId', args)`) for any operation in the spec.
-- **Crypto helpers** — X25519 JWE decryption (you mint the keys with openssl), result-JWS signing/verification, JWKS discovery, and nested attestor-proof verification.
+- **Crypto helpers** — ECIES decryption with the org's eth key, result-JWS signing/verification, JWKS discovery, and nested attestor-proof verification.
 
 Works in Node, Deno, browsers, and edge runtimes (it uses WebCrypto + `@noble`, no native deps).
 
 ## The model in one paragraph
 
-Authentication is a single **per-org secret** (`rorg_…`, the `orgSecret`) — a bearer credential; no signatures, no per-call secrets. Verification **results are encrypted with JWE** (`ECDH-ES + A256GCM` over **X25519**): you mint an X25519 keypair with openssl, publish the **public** SPKI PEM as the org's encryption credential, and keep the matching **private** PKCS#8 PEM to decrypt. Ethereum is used **only** to *verify* the result's signature — the Verification Client signs the result JWS with `ES256K` and you verify it against the Builder's JWKS — so you never hold an eth private key as a consumer.
+Authentication is a single **per-org secret** (`rorg_…`, the `orgSecret`) — a bearer credential; no signatures, no per-call secrets. The org is identified by an **Ethereum (secp256k1) public key**, set as its keypair. When that keypair's `canEncryptResult` is enabled, verification **results are encrypted with ECIES** (secp256k1 + AES-256-GCM) to the org's eth public key, and you keep the matching **eth private key** (`0x`-hex — the form any wallet/ethers emits) to decrypt. Ethereum also signs the result JWS with `ES256K`, which you verify against the Builder's JWKS.
 
 ```
                           ┌─ one-time setup ─────────────────────────┐
-  reclaim.callbacks.register({ callbackUrl })     ← where results go
-  reclaim.credential.set(orgId, { publicKeyPem }) ← optional: encrypt to your key
+  reclaim.callbacks.register({ callbackUrl })      ← where results go
+  reclaim.keypair.set(orgId, { publicKey,          ← identity + (optional)
+                       canEncryptResult: true })      encrypt to your key
                           └──────────────────────────────────────────┘
                           ┌─ per verification ───────────────────────┐
   reclaim.sessions.create(...) → open session.verificationUrl
@@ -36,7 +37,6 @@ Configure once with your org secret. `orgId` below is your organization's id (th
 
 ```ts
 import { createReclaim } from '@reclaimprotocol/client'
-import { readFileSync } from 'node:fs'
 
 const reclaim = createReclaim({
   orgSecret: process.env.RECLAIM_ORG_SECRET,   // rorg_… (issued by an org owner)
@@ -54,19 +54,19 @@ await reclaim.callbacks.register({ callbackUrl: 'https://my.app/reclaim/callback
 
 ### 2. Enable encryption (optional, one-time)
 
-By default results are delivered as plaintext signed JWS (still verified). To have the Builder **encrypt** results so only you can read them, publish an X25519 **public** key as the org's encryption credential. Mint the keypair yourself with openssl — the SDK never generates keys:
+By default results are delivered as plaintext signed JWS (still verified). To have the Builder **encrypt** results so only you can read them, register your org's eth **public** key with `canEncryptResult: true`. Use any eth key (the `0x`-hex form wallets/ethers emit), or mint one with the SDK:
 
-```bash
-# private key (PKCS#8 PEM) — keep this, it decrypts results
-openssl genpkey -algorithm X25519 -out reclaim-x25519.pem
-# public key (SPKI PEM) — this is what you register
-openssl pkey -in reclaim-x25519.pem -pubout -out reclaim-x25519.pub.pem
+```ts
+import { generateEthKeypair } from '@reclaimprotocol/client'
+// keep privateKeyHex secret — it decrypts results
+const { privateKeyHex, publicKeyHex } = generateEthKeypair()
 ```
 
 ```ts
-// (also doable from the dashboard, which can even mint the keypair for you)
-await reclaim.credential.set(orgId, {
-  publicKeyPem: readFileSync('reclaim-x25519.pub.pem', 'utf8'),
+// (also doable from the dashboard, which can mint the keypair in-browser)
+await reclaim.keypair.set(orgId, {
+  publicKey: publicKeyHex,   // 0x04+128 hex (or pass publicKeyJwk)
+  canEncryptResult: true,
 })
 ```
 
@@ -100,7 +100,7 @@ When the end-user finishes, the Builder POSTs to your `callbackUrl`. Pass the re
 ```ts
 // in your callback HTTP handler:
 const outcome = await reclaim.results.receive(requestBody, {
-  credential: readFileSync('reclaim-x25519.pem', 'utf8'),  // private PEM; omit for plaintext
+  credential: process.env.RECLAIM_ETH_PRIVATE_KEY,  // 0x-hex eth key; omit for plaintext
   expectedReclaimSessionId: session.id,
 })
 if (outcome.kind === 'result') {
@@ -112,13 +112,13 @@ if (outcome.kind === 'result') {
 
 ### Three ways to set up
 
-The one-time setup (registering the callback subscription + the encryption credential) can be done however suits you — they all hit the same API:
+The one-time setup (registering the callback subscription + the encryption keypair) can be done however suits you — they all hit the same API:
 
-- **This SDK** — `reclaim.callbacks.register(...)` + `reclaim.credential.set(...)`, as above (good for scripting/CI).
-- **The dashboard** — the org's web console has a callback-subscription form and a "Set encryption credential" dialog that can **generate the X25519 keypair in your browser** and download the private key for you (no openssl needed).
+- **This SDK** — `reclaim.callbacks.register(...)` + `reclaim.keypair.set(...)`, as above (good for scripting/CI).
+- **The dashboard** — the org's web console has a callback-subscription form and a "Set encryption keypair" dialog that can **generate the eth keypair in your browser** and download the private key for you.
 - **The agent** (`@reclaimprotocol/agent` — the `reclaim` CLI / MCP server) — handy while building and testing a provider locally.
 
-Whichever you use, at runtime your backend needs only the org secret (to authenticate) and the private key (to decrypt) — the `results.receive(...)` step is unchanged.
+Whichever you use, at runtime your backend needs only the org secret (to authenticate) and the eth private key (to decrypt) — the `results.receive(...)` step is unchanged.
 
 ---
 
@@ -126,7 +126,7 @@ Whichever you use, at runtime your backend needs only the org secret (to authent
 
 ### `createReclaim(config)`
 
-Returns a `Reclaim` with four namespaces (`sessions`, `callbacks`, `credential`, `results`) plus an `api` escape hatch.
+Returns a `Reclaim` with four namespaces (`sessions`, `callbacks`, `keypair`, `results`) plus an `api` escape hatch.
 
 | `ReclaimConfig` field | type | required | notes |
 |---|---|---|---|
@@ -135,7 +135,7 @@ Returns a `Reclaim` with four namespaces (`sessions`, `callbacks`, `credential`,
 | `fetch` | `typeof fetch` | no | Custom fetch (tests, edge runtimes). |
 | `headers` | `Record<string,string>` | no | Extra headers merged into every request. |
 
-`orgSecret` is the only config. Everything else is passed where it's used: the **`orgId`** to `credential.set`/`get`, and the **X25519 private key** to `results.receive`/`decrypt`.
+`orgSecret` is the only config. Everything else is passed where it's used: the **`orgId`** to `keypair.set`/`get`, and the **eth private key** (`0x`-hex) to `results.receive`/`decrypt`.
 
 ### `reclaim.sessions`
 
@@ -158,20 +158,20 @@ reclaim.callbacks.remove(subscriptionId)  // → void
 
 `events` is any subset of `VerificationEvent`. The terminal events (`verification_success` / `verification_rejected` / `verification_error`, exported as `TERMINAL_EVENTS`) deliver the signed result; non-terminal events deliver a plaintext progress notification.
 
-### `reclaim.credential` (the org's single encryption key)
+### `reclaim.keypair` (the org's single eth encryption key)
 
 ```ts
-await reclaim.credential.set(orgId, { publicKeyPem, label?: 'prod' })  // → OrgCredential
-await reclaim.credential.get(orgId)  // → OrgCredential | undefined (undefined ⇒ plaintext delivery)
+await reclaim.keypair.set(orgId, { publicKey, canEncryptResult?: true, label?: 'prod' })  // → OrgKeypair
+await reclaim.keypair.get(orgId)  // → OrgKeypair | undefined (undefined ⇒ keyless / plaintext delivery)
 ```
 
-`publicKeyPem` is the X25519 **SPKI public PEM** (the `-----BEGIN PUBLIC KEY-----` block from `openssl pkey -pubout`) — `set` converts it to a JWK and stores it. There is exactly **one** credential per org; `set` replaces it. Keep the matching **PKCS#8 private PEM** and pass it as the decryption key to `results.receive`/`decrypt`.
+`publicKey` is the org's eth **uncompressed public key** (`0x04` + 128 hex — the form `generateEthKeypair()`/ethers produce); alternatively pass `publicKeyJwk` (a secp256k1 JWK). `set` stores the JWK + derived eth address. There is exactly **one** keypair per org; `set` replaces it (rotation). `canEncryptResult` toggles whether results are encrypted to it (default `false` ⇒ plaintext). Keep the matching **eth private key** (`0x`-hex) and pass it as the decryption key to `results.receive`/`decrypt`.
 
 ### `reclaim.results`
 
 ```ts
 reclaim.results.receive(body, opts?)        // → ReceivedDelivery  ← the 90% path
-reclaim.results.decrypt(body, credential?)  // → Jws   (JWE or plaintext → signed JWS)
+reclaim.results.decrypt(body, credential?)  // → Jws   (ECIES or plaintext → signed JWS)
 reclaim.results.verify(jws, opts?)          // → VerifyResultFullOutcome
 ```
 
@@ -183,7 +183,7 @@ type ReceivedDelivery =
   | { kind: 'event'; event: VerificationEvent; eventData: Record<string, unknown> } // non-terminal: plaintext
 ```
 
-`opts` (`ReceiveOptions`) is `VerifyResultFullOptions` (`expectedReclaimSessionId` nonce check, `expectedAud`, attestor allowlists, `fetchImpl`, `now`) **plus** an optional `credential` — the X25519 decryption key as a **PKCS#8 PEM string** (the content of your `reclaim-x25519.pem`, not a path or env name). All three methods are async; pass `credential` only when the delivery is encrypted.
+`opts` (`ReceiveOptions`) is `VerifyResultFullOptions` (`expectedReclaimSessionId` nonce check, `expectedAud`, attestor allowlists, `fetchImpl`, `now`) **plus** an optional `credential` — the eth decryption key as a **`0x`-hex private key string** (the key content, not a path or env name). All three methods are async; pass `credential` only when the delivery is encrypted.
 
 **Invalid results throw.** `receive` and `verify` (and the underlying `verifyResult` / `verifyResultFull`) never *return* a failed verdict — they throw a **`ResultVerificationError`** carrying the failure `reason` and the full `outcome` (payload, `reclaimSessionId`, per-proof detail). So the `result` branch is always verified; wrap the call to inspect failures:
 
@@ -213,13 +213,15 @@ const { data } = await reclaim.api('GetVerificationSession', { params: { session
 ## Crypto & key helpers
 
 ```ts
-// X25519 encryption keys (consumer side) — you mint keys with openssl, not the SDK
-loadDecryptionKey(pem): Promise<DecryptionKey>   // PKCS#8 private PEM → recipient key
-publicPemToJwk(spkiPem): Promise<JWK>            // SPKI public PEM → JWK (what credential.set does for you)
+// Eth encryption keys (consumer side)
+generateEthKeypair(): { privateKeyHex, publicKeyHex, publicJwk, ethAddress }  // mint an org keypair
+loadDecryptionKey(hex): DecryptionKey            // 0x-hex eth private key → raw scalar
+uncompressedPubkeyToJwk(hex): Jwk                // 0x04+128 hex → secp256k1 JWK
+pubkeyJwkToEthAddress(jwk): string               // secp256k1 JWK → 0x eth address
 
-// JWE (encryptForPublicJwk is used by the first-party Verification Client; consumers only decrypt)
-encryptForPublicJwk(publicJwk, bytes): Promise<string>   // → compact JWE
-decryptCallback(decryptionKey, body): Promise<Jws>        // JWE/plaintext → JWS
+// ECIES (encryptForEthPublicKey is used by the first-party Verification Client; consumers only decrypt)
+encryptForEthPublicKey(publicJwk, bytes): Promise<string>  // → ECIES ciphertext (base64url)
+decryptCallback(decryptionKey, body): Promise<Jws>          // ECIES/plaintext → JWS
 
 // Result JWS (eth ES256K)
 signResultJws(ethPrivHex, payload, issuer): Jws                // VC-side
@@ -236,7 +238,7 @@ verifyNestedProof(...): NestedProofOutcome
 
 ### Eth keypair utils (low-level)
 
-`generateKeypair()`, `deriveFromPrivateKey(hex)`, `addressFromPublicKey(...)`, plus the `secp` instance and `addressFromUncompressedPubkey(...)`, are exported for the Verification Client and the agent (proof-owner signing). **Consumers don't need an eth private key** — only the X25519 decryption key above. `canonicalJson` (RFC 8785) is also exported (used by content-hash binding).
+`generateKeypair()`, `deriveFromPrivateKey(hex)`, `addressFromPublicKey(...)`, plus the `secp` instance and `addressFromUncompressedPubkey(...)`, are exported for the Verification Client and the agent (proof-owner signing). A consumer that enables encryption holds an **eth private key** (the same key family) to decrypt — see the encryption-key helpers above. `canonicalJson` (RFC 8785) is also exported (used by content-hash binding).
 
 ## `ReclaimClient` (low-level)
 
@@ -251,6 +253,6 @@ Errors are thrown as `ProblemError` (RFC 9457). `throwProblemError`, `DEFAULT_BA
 ## Security notes
 
 - The **org secret is a bearer credential** — treat it like a password; rotate it from the dashboard (`POST /orgs/{orgId}/token`, which invalidates the prior one). The server stores only an HMAC of it.
-- **Encryption is X25519 + AES-GCM** via WebCrypto — runs in browsers, Node, Deno, and edge runtimes.
+- **Encryption is ECIES over secp256k1 + AES-256-GCM** (via `eciesjs` / `@noble`) — runs in browsers, Node, Deno, and edge runtimes, and uses the same eth key family as signing.
 - **Signature verification stays secp256k1** (not routed through `jose`) so it works on WebCrypto-only runtimes that lack `ES256K`.
 - The callback delivery is **unauthenticated transport** — never trust the raw POST body; trust only the decrypted, signature-verified result that `results.receive` returns.

package/lib/enckeys.d.ts

@@ -1,33 +1,40 @@
+import { type Jwk } from './jwks.ts';
+/** 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;
 /**
- * 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).
+ * 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.
  */
-import type { JWK } from 'jose';
-import { importPKCS8 } 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;
-/** 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 declare function loadDecryptionKey(pem: DecryptionKeyInput): Promise<DecryptionKey>;
-/** 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 declare function publicPemToJwk(pem: string): Promise<JWK>;
+export declare function loadDecryptionKey(input: DecryptionKeyInput): DecryptionKey;
+/**
+ * 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 declare function uncompressedPubkeyToJwk(publicKeyHex: string): Jwk;
+/** Lowercase 0x ETH address that owns a secp256k1 public JWK (the org's
+ *  identity address). */
+export declare function pubkeyJwkToEthAddress(jwk: Jwk): string;
+/** 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;
+}
+/** 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 declare function generateEthKeypair(): GeneratedEthKeypair;
+/** 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 declare function ethKeypairFromPrivateKey(input: string): GeneratedEthKeypair;

package/lib/enckeys.js

@@ -1,14 +1,89 @@
-import { exportJWK, importPKCS8, importSPKI } from 'jose';
-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) {
-    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) {
-    const key = await importSPKI(pem.trim(), ALG, { extractable: true });
-    return exportJWK(key);
+/**
+ * secp256k1 (Ethereum) encryption-key helpers for ECIES result delivery.
+ *
+ * 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.
+ *
+ * No PEM, no DER, no WebCrypto — `@noble/secp256k1` handles hex in every
+ * runtime.
+ */
+import { b64url, hexToBytes } from "./encoding.js";
+import { jwkToUncompressedPublicKey } from "./jwks.js";
+import { addressFromPublicKey, deriveFromPrivateKey, generateKeypair, } from "./keypair.js";
+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) {
+    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) {
+    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)),
+    };
+}
+/** Lowercase 0x ETH address that owns a secp256k1 public JWK (the org's
+ *  identity address). */
+export function pubkeyJwkToEthAddress(jwk) {
+    return addressFromPublicKey(jwkToUncompressedPublicKey(jwk));
+}
+/** 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() {
+    const { privateKey, publicKey, address } = generateKeypair();
+    return {
+        privateKeyHex: privateKey,
+        publicKeyHex: publicKey,
+        publicJwk: uncompressedPubkeyToJwk(publicKey),
+        ethAddress: address,
+    };
+}
+/** 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) {
+    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/lib/encoding.d.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 declare function hexToBytes(hex: string): Uint8Array;
 export declare function bytesToHex(bytes: Uint8Array): string;

package/lib/encoding.js

@@ -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) {
     const clean = hex.startsWith('0x') ? hex.slice(2) : hex;
@@ -22,12 +27,23 @@ export function bytesToHex(bytes) {
 export function base64urlToBytes(s) {
     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) {
-    return Buffer.from(input)
-        .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/lib/index.d.ts

@@ -7,8 +7,8 @@ export { addressFromPublicKey, deriveFromPrivateKey, type EthKeypair, generateKe
 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 { type CallbackBody, decodeJwsPayload, decryptCallback, type DeliveryEnvelope, encryptForEthPublicKey, 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, generateEthKeypair, type GeneratedEthKeypair, loadDecryptionKey, pubkeyJwkToEthAddress, uncompressedPubkeyToJwk, } from './enckeys.ts';
+export { createReclaim, type CreateSessionInput, type Reclaim, type ReclaimConfig, type ReceiveOptions, type ReceivedDelivery, type RegisterCallbackInput, type SetKeypairInput, TERMINAL_EVENTS, } from './reclaim.ts';
 export { fetchJwks, type Jwk, jwksFromPrivateKey, jwkToUncompressedPublicKey, selectKey, } from './jwks.ts';
 export { type NestedProofOutcome, verifyNestedProof, } from './attestor-proof.ts';

package/lib/index.js

@@ -5,8 +5,8 @@ export { addressFromPublicKey, deriveFromPrivateKey, generateKeypair, } from "./
 export { canonicalJson } from "./canonical.js";
 export { b64url, base64urlToBytes, bytesToHex, hexToBytes, } from "./encoding.js";
 export { addressFromUncompressedPubkey, secp, } from "./secp.js";
-export { decodeJwsPayload, decryptCallback, encryptForPublicJwk, ResultVerificationError, signResultJws, verifyJwsSignature, verifyResult, verifyResultFull, } from "./result.js";
-export { loadDecryptionKey, publicPemToJwk, } from "./enckeys.js";
+export { decodeJwsPayload, decryptCallback, encryptForEthPublicKey, ResultVerificationError, signResultJws, verifyJwsSignature, verifyResult, verifyResultFull, } from "./result.js";
+export { generateEthKeypair, loadDecryptionKey, pubkeyJwkToEthAddress, uncompressedPubkeyToJwk, } from "./enckeys.js";
 export { createReclaim, TERMINAL_EVENTS, } from "./reclaim.js";
 export { fetchJwks, jwksFromPrivateKey, jwkToUncompressedPublicKey, selectKey, } from "./jwks.js";
 export { verifyNestedProof, } from "./attestor-proof.js";

package/lib/keypair.d.ts

@@ -2,8 +2,9 @@ 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;
 };
 /**

package/lib/keypair.js

@@ -1,6 +1,20 @@
 import { keccak_256 } from '@noble/hashes/sha3.js';
 import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
 import * as secp from '@noble/secp256k1';
+/** 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() {
+    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
@@ -13,7 +27,7 @@ import * as secp from '@noble/secp256k1';
  * intermediate value used to compute the address and is not retained.
  */
 export function generateKeypair() {
-    const priv = secp.utils.randomSecretKey();
+    const priv = secp.utils.randomSecretKey(randomSeed());
     const pub = secp.getPublicKey(priv, false);
     return {
         address: addressFromPubBytes(pub),

package/lib/reclaim.d.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,
  *   })
  *
@@ -29,7 +29,7 @@ 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 OrgKeypair = components['schemas']['OrgKeypair'];
 /** The three terminal events a subscription can receive. */
 export declare const TERMINAL_EVENTS: readonly ["verification_success", "verification_rejected", "verification_error"];
 export interface RegisterCallbackInput {
@@ -37,21 +37,23 @@ export interface RegisterCallbackInput {
     events: VerificationEvent[];
 }
 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
      *  the org server-side. The only required config. */
@@ -64,8 +66,8 @@ export interface ReclaimConfig {
     headers?: Record<string, string>;
 }
 /** 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;
 };
@@ -82,25 +84,26 @@ 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'>): Promise<CallbackSubscription>;
         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. */