@reclaimprotocol/client 0.1.0-dev.1 → 0.1.0-dev.2

package/README.md

@@ -0,0 +1,256 @@
+# @reclaimprotocol/client
+
+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.
+
+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.
+
+```
+                          ┌─ one-time setup ─────────────────────────┐
+  reclaim.callbacks.register({ callbackUrl })     ← where results go
+  reclaim.credential.set(orgId, { publicKeyPem }) ← optional: encrypt to your key
+                          └──────────────────────────────────────────┘
+                          ┌─ per verification ───────────────────────┐
+  reclaim.sessions.create(...) → open session.verificationUrl
+        … end-user completes it …
+  POST → your callbackUrl → reclaim.results.receive(body) → verified payload
+                          └──────────────────────────────────────────┘
+```
+
+## Install
+
+```bash
+npm install @reclaimprotocol/client
+```
+
+## Quick start (consumer)
+
+Configure once with your org secret. `orgId` below is your organization's id (the org the secret belongs to).
+
+```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)
+})
+const orgId = process.env.RECLAIM_ORG_ID       // your org's id
+```
+
+### 1. Register a callback (one-time)
+
+Tell the Builder where to POST verification results. This is one-time setup and can also be done from the **dashboard** or the **agent** — see [Three ways to set up](#three-ways-to-set-up).
+
+```ts
+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:
+
+```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
+// (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'),
+})
+```
+
+### 3. Create a session (per verification)
+
+```ts
+const session = await reclaim.sessions.create({
+  providerId: 'prov_…',
+  context: { userId: 'abc' },
+})
+console.log('open this:', session.verificationUrl)   // hand to the end-user
+```
+
+It's a plain authenticated POST, so you don't need the SDK — curl works too (the org secret is the only auth):
+
+```bash
+curl -X POST "$BUILDER_URL/verifications/sessions" \
+  -H "Authorization: Bearer $RECLAIM_ORG_SECRET" \
+  -H 'Content-Type: application/json' \
+  -d '{
+        "providerId": "prov_…",
+        "context": { "userId": "abc" }
+      }'
+# → 201 { "id": "…", "verificationUrl": "…", "status": "pending", "mode": "…", … }
+```
+
+### 4. Receive & verify the result
+
+When the end-user finishes, the Builder POSTs to your `callbackUrl`. Pass the request body to `results.receive`. It decrypts (if encrypted) and verifies the signature + nested proofs, and **throws if the result is invalid** — so reaching the `result` branch means it's verified.
+
+```ts
+// in your callback HTTP handler:
+const outcome = await reclaim.results.receive(requestBody, {
+  credential: readFileSync('reclaim-x25519.pem', 'utf8'),  // private PEM; omit for plaintext
+  expectedReclaimSessionId: session.id,
+})
+if (outcome.kind === 'result') {
+  console.log('verified!', outcome.result.payload)
+} else {
+  console.log('progress event:', outcome.event)          // non-terminal notification
+}
+```
+
+### 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:
+
+- **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).
+- **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.
+
+---
+
+## API reference
+
+### `createReclaim(config)`
+
+Returns a `Reclaim` with four namespaces (`sessions`, `callbacks`, `credential`, `results`) plus an `api` escape hatch.
+
+| `ReclaimConfig` field | type | required | notes |
+|---|---|---|---|
+| `orgSecret` | `string` | **yes** | The org secret `rorg_…`. Sent as `Authorization: Bearer`; identifies the org server-side. |
+| `baseUrl` | `string` | no | Defaults to the production Builder. |
+| `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`.
+
+### `reclaim.sessions`
+
+```ts
+reclaim.sessions.create({ providerId, version?, context, verificationClientUrl? })
+  // → VerificationSession (has `id`, `verificationUrl`, `status`, `mode`, …)
+  // verificationClientUrl defaults to the Builder's own /v/{sessionId} page.
+reclaim.sessions.get(sessionId)         // → VerificationSession
+reclaim.sessions.listEvents(sessionId)  // → VerificationEventRecord[]
+```
+
+### `reclaim.callbacks`
+
+```ts
+reclaim.callbacks.register({ callbackUrl, events? })  // events defaults to the 3 terminal events
+  // → CallbackSubscription. Org-scoped; no address/publicKey/secret.
+reclaim.callbacks.list()                  // → CallbackSubscription[]
+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)
+
+```ts
+await reclaim.credential.set(orgId, { publicKeyPem, label?: 'prod' })  // → OrgCredential
+await reclaim.credential.get(orgId)  // → OrgCredential | undefined (undefined ⇒ 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`.
+
+### `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.verify(jws, opts?)          // → VerifyResultFullOutcome
+```
+
+`receive` branches on the delivery:
+
+```ts
+type ReceivedDelivery =
+  | { kind: 'result'; result: VerifyResultFullOutcome }  // terminal: decrypted + verified
+  | { 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.
+
+**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:
+
+```ts
+import { ResultVerificationError } from '@reclaimprotocol/client'
+try {
+  const { result } = await reclaim.results.receive(body, { credential })
+  // result.payload is verified
+} catch (err) {
+  if (err instanceof ResultVerificationError) {
+    console.error(err.reason, err.outcome)  // e.g. 'expired' / 'bad-signature' / 'invalid-proof'
+  } else {
+    throw err
+  }
+}
+```
+
+A non-terminal `event` delivery is not a result and never throws — it returns `{ kind: 'event', … }`.
+
+### `reclaim.api` — escape hatch
+
+```ts
+// fully typed against the OpenAPI spec — for any operation the namespaces don't wrap
+const { data } = await reclaim.api('GetVerificationSession', { params: { sessionId } })
+```
+
+## 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)
+
+// 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
+
+// Result JWS (eth ES256K)
+signResultJws(ethPrivHex, payload, issuer): Jws                // VC-side
+verifyResult(jws, opts): VerifyResultOutcome                   // offline signature/nonce check (throws if invalid)
+verifyResultFull(jws, opts): Promise<VerifyResultFullOutcome>  // + JWKS discovery + attestor proofs (throws if invalid)
+verifyJwsSignature(jws, signerPublicKey), decodeJwsPayload(jws)
+
+// JWKS (signature-key discovery / publishing)
+fetchJwks(url), jwksFromPrivateKey(ethPrivHex), selectKey(...), jwkToUncompressedPublicKey(jwk)
+
+// Nested attestor-proof verification
+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).
+
+## `ReclaimClient` (low-level)
+
+```ts
+import { ReclaimClient } from '@reclaimprotocol/client'
+const client = new ReclaimClient({ baseUrl, token, fetch, headers })
+const { data, response } = await client.call('GetVerificationSession', { params: { sessionId } })
+```
+
+Errors are thrown as `ProblemError` (RFC 9457). `throwProblemError`, `DEFAULT_BASE_URL`, `USER_AGENT`, encoding helpers (`b64url`, `hexToBytes`, …), and the generated `components` / `operations` types are also exported.
+
+## 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.
+- **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/attestor-proof.d.ts

@@ -0,0 +1,16 @@
+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 declare function verifyNestedProof(proofB64: string, opts?: {
+    attestorAddresses?: string[];
+}): NestedProofOutcome;

package/lib/attestor-proof.js

@@ -0,0 +1,121 @@
+/**
+ * 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.js";
+import { secp } from "./secp.js";
+const ENC = new TextEncoder();
+function decodeJson(b64url) {
+    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) {
+    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) {
+    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, sig) {
+    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);
+}
+/**
+ * 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, opts = {}) {
+    let jws;
+    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;
+    let claim;
+    try {
+        header = decodeJson(sig.protected);
+        claim = decodeJson(jws.payload);
+    }
+    catch {
+        return { valid: false, reason: 'proof-decode-failed' };
+    }
+    let recovered;
+    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/lib/canonical.d.ts

@@ -0,0 +1 @@
+export declare function canonicalJson(value: unknown): string;

package/lib/canonical.js

@@ -0,0 +1,18 @@
+/**
+ * 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.default
+    ?? canonicalizeMod);
+export function canonicalJson(value) {
+    const out = canonicalize(value);
+    assert(out !== undefined, badData('value is not JSON-serializable'));
+    return out;
+}

package/lib/eip712.d.ts

@@ -0,0 +1,20 @@
+declare const TYPES: {
+    readonly CreateVerificationSession: readonly [readonly ["providerId", "string"], readonly ["version", "string"], readonly ["context", "string"], readonly ["verificationClientUrl", "string"], readonly ["timestamp", "uint256"]];
+    readonly CreateCallbackSubscription: readonly [readonly ["callbackUrl", "string"], readonly ["events", "string"], readonly ["publicKey", "string"], readonly ["address", "string"], readonly ["timestamp", "uint256"]];
+    readonly VerificationAuth: readonly [readonly ["timestamp", "uint256"]];
+};
+export type Eip712PrimaryType = keyof typeof TYPES;
+/** Deterministic JSON via RFC 8785 (JSON Canonicalization Scheme): object
+ *  keys sorted recursively, no whitespace, canonical number/string forms.
+ *  Both signer and verifier canonicalize `context`/`events` this way so the
+ *  string fields hash identically. Single source of truth for canonical
+ *  stringification in the repo — `contentHash` (result binding) uses it too;
+ *  do not reimplement with sorted JSON.stringify. */
+export declare function canonicalJson(value: unknown): string;
+/** EIP-712 digest: keccak256(0x1901 ‖ domainSeparator ‖ structHash). */
+export declare function eip712Digest(primaryType: Eip712PrimaryType, message: Record<string, string | bigint>): Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>;
+/** Recover the signer of a typed message, or null on failure. Used by the
+ *  Builder (`packages/app`) to verify legacy typed-data signatures; the client
+ *  itself no longer signs — all consumer auth is the org bearer token. */
+export declare function recoverTypedSigner(primaryType: Eip712PrimaryType, message: Record<string, string | bigint>, signature: string): string | null;
+export {};

package/lib/eip712.js

@@ -0,0 +1,108 @@
+/**
+ * EIP-712 typed-data primitives for the legacy verification-session signature
+ * scheme — kept for the Builder verifier (`eip712Digest` + `recoverTypedSigner`,
+ * imported by `packages/app`). The consumer client no longer signs (all auth is
+ * the org bearer token), so there is no `buildAuthHeaders` here anymore. The
+ * typed data is tiny (only `string` / `uint256` / `address` fields), so it's
+ * hashed directly with keccak-256; recovery is standard secp256k1 over the
+ * digest (`prehash:false`, see ./secp.ts).
+ */
+import { badData } from '@hapi/boom';
+import * as canonicalizeMod from 'canonicalize';
+import assert from 'node:assert';
+import { hexToBytes } from "./encoding.js";
+import { keccak_256, recoverAddress } from "./secp.js";
+// canonicalize ships as a CJS default export; resolve it across interop
+// modes (same dance as ajv-formats in packages/app).
+const canonicalize = (canonicalizeMod.default ??
+    canonicalizeMod);
+const DOMAIN = {
+    name: 'Reclaim Builder',
+    version: '1',
+    chainId: 1n,
+    verifyingContract: '0x0000000000000000000000000000000000000000',
+};
+const TYPES = {
+    CreateVerificationSession: [
+        ['providerId', 'string'],
+        ['version', 'string'],
+        ['context', 'string'],
+        ['verificationClientUrl', 'string'],
+        ['timestamp', 'uint256'],
+    ],
+    CreateCallbackSubscription: [
+        ['callbackUrl', 'string'],
+        ['events', 'string'],
+        ['publicKey', 'string'],
+        ['address', 'string'],
+        ['timestamp', 'uint256'],
+    ],
+    VerificationAuth: [['timestamp', 'uint256']],
+};
+/** Deterministic JSON via RFC 8785 (JSON Canonicalization Scheme): object
+ *  keys sorted recursively, no whitespace, canonical number/string forms.
+ *  Both signer and verifier canonicalize `context`/`events` this way so the
+ *  string fields hash identically. Single source of truth for canonical
+ *  stringification in the repo — `contentHash` (result binding) uses it too;
+ *  do not reimplement with sorted JSON.stringify. */
+export function canonicalJson(value) {
+    const out = canonicalize(value);
+    assert(out !== undefined, badData('value is not JSON-serializable'));
+    return out;
+}
+function utf8(s) {
+    return new TextEncoder().encode(s);
+}
+function uint256(value) {
+    const out = new Uint8Array(32);
+    let v = value;
+    for (let i = 31; i >= 0 && v > 0n; i--) {
+        out[i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+    return out;
+}
+function addressWord(addr) {
+    const out = new Uint8Array(32);
+    out.set(hexToBytes(addr), 12);
+    return out;
+}
+function concat(...parts) {
+    const total = parts.reduce((n, p) => n + p.length, 0);
+    const out = new Uint8Array(total);
+    let off = 0;
+    for (const p of parts) {
+        out.set(p, off);
+        off += p.length;
+    }
+    return out;
+}
+function typeHash(primaryType) {
+    const fields = TYPES[primaryType].map(([n, t]) => `${t} ${n}`).join(',');
+    return keccak_256(utf8(`${primaryType}(${fields})`));
+}
+function encodeField(type, value) {
+    return type === 'string'
+        ? keccak_256(utf8(value))
+        : uint256(value);
+}
+function structHash(primaryType, message) {
+    const parts = [typeHash(primaryType)];
+    for (const [name, type] of TYPES[primaryType]) {
+        parts.push(encodeField(type, message[name]));
+    }
+    return keccak_256(concat(...parts));
+}
+const DOMAIN_SEPARATOR = keccak_256(concat(keccak_256(utf8('EIP712Domain(string name,string version,uint256 chainId,' +
+    'address verifyingContract)')), keccak_256(utf8(DOMAIN.name)), keccak_256(utf8(DOMAIN.version)), uint256(DOMAIN.chainId), addressWord(DOMAIN.verifyingContract)));
+/** EIP-712 digest: keccak256(0x1901 ‖ domainSeparator ‖ structHash). */
+export function eip712Digest(primaryType, message) {
+    return keccak_256(concat(Uint8Array.from([0x19, 0x01]), DOMAIN_SEPARATOR, structHash(primaryType, message)));
+}
+/** Recover the signer of a typed message, or null on failure. Used by the
+ *  Builder (`packages/app`) to verify legacy typed-data signatures; the client
+ *  itself no longer signs — all consumer auth is the org bearer token. */
+export function recoverTypedSigner(primaryType, message, signature) {
+    const digest = eip712Digest(primaryType, message);
+    return recoverAddress(digest, hexToBytes(signature));
+}

package/lib/enckeys.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 { 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>;

package/lib/enckeys.js

@@ -0,0 +1,14 @@
+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);
+}

package/lib/encoding.d.ts

@@ -0,0 +1,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.
+ */
+export declare function hexToBytes(hex: string): Uint8Array;
+export declare function bytesToHex(bytes: Uint8Array): string;
+/** Decode a base64url string (with or without padding) to bytes. */
+export declare function base64urlToBytes(s: string): Uint8Array;
+/** Encode bytes (or a UTF-8 string) as unpadded base64url. */
+export declare function b64url(input: Uint8Array | string): string;

package/lib/encoding.js

@@ -0,0 +1,34 @@
+/**
+ * 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) {
+    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) {
+    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) {
+    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) {
+    return Buffer.from(input)
+        .toString('base64')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/, '');
+}

package/lib/index.d.ts

@@ -1,6 +1,14 @@
 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 { deriveFromPrivateKey, type EthKeypair, generateKeypair, } from './keypair.ts';
-export * from './types/index.ts';
+export { addressFromPublicKey, deriveFromPrivateKey, type EthKeypair, generateKeypair, } from './keypair.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';