@reclaimprotocol/client 0.1.0-dev.1 → 0.1.0

package/src/result.ts

@@ -0,0 +1,448 @@
+/**
+ * Consumer-side handling of a delivered callback. Two entry points:
+ *  - {@link verifyResult}: the offline primitive — decrypt + decode + optional
+ *    ES256K signature check (caller-supplied key) + `reclaimSessionId` nonce.
+ *  - {@link verifyResultFull}: the full async verification — discovers the
+ *    Verification Client's key via JWKS, verifies the top-level JWS, checks
+ *    `reclaimSessionId`/`aud`/`exp`, and verifies each result's nested attestor
+ *    proof + `content_hash` (see ./attestor-proof.ts and ./jwks.ts).
+ *
+ * See docs/verification-session.md → "Verification by Consumer".
+ */
+import { sha256 } from '@noble/hashes/sha2.js'
+import { keccak_256 } from '@noble/hashes/sha3.js'
+import type { JWK } from 'jose'
+import { compactDecrypt, CompactEncrypt, importJWK } from 'jose'
+import type { components } from './types/openapi.gen.ts'
+import { type NestedProofOutcome, verifyNestedProof } from './attestor-proof.ts'
+import { canonicalJson } from './canonical.ts'
+import type { DecryptionKey } from './enckeys.ts'
+import { b64url, base64urlToBytes, bytesToHex, hexToBytes } from './encoding.ts'
+import { fetchJwks, jwkToUncompressedPublicKey, selectKey } from './jwks.ts'
+import { addressFromUncompressedPubkey, secp } from './secp.ts'
+
+export interface Jws {
+	payload: string
+	signatures: {
+		protected: string
+		header?: Record<string, unknown>
+		signature: string
+	}[]
+}
+
+export interface VerifyResultOptions {
+	/** Uncompressed ETH public key (`0x04`+128 hex) of the signer; when given,
+	 *  the JWS signature is verified. Omit to only decode + check the nonce. */
+	signerPublicKey?: string
+	/** The `reclaimSessionId` the consumer expects (the session id they got
+	 *  back at creation). When given, mismatch fails verification. */
+	expectedReclaimSessionId?: string
+}
+
+export interface VerifyResultOutcome {
+	valid: boolean
+	reason?: string
+	payload: Record<string, unknown>
+	reclaimSessionId?: string
+}
+
+/**
+ * JWE-encrypt `plaintext` for the holder of `publicJwk` (an X25519 public JWK,
+ * `{kty:'OKP', crv:'X25519', x}`) as a compact JWE (`ECDH-ES + A256GCM`). Used
+ * by the first-party Verification Client to encrypt the signed JWS for each
+ * Consumer before submitting it to the Builder (which only relays the
+ * ciphertext). Consumers never call this — they only {@link decryptCallback}.
+ *
+ * `plaintext` is bytes (e.g. `new TextEncoder().encode(JSON.stringify(jws))`);
+ * returns the compact JWE string.
+ */
+export async function encryptForPublicJwk(
+	publicJwk: JWK,
+	plaintext: Uint8Array,
+): Promise<string> {
+	const key = await importJWK(publicJwk, 'ECDH-ES')
+	return new CompactEncrypt(plaintext)
+		.setProtectedHeader({ alg: 'ECDH-ES', enc: 'A256GCM' })
+		.encrypt(key)
+}
+
+/**
+ * What a consumer's callback endpoint receives — the Builder POSTs the JSON
+ * `VerificationResultDelivery` envelope: plaintext `sessionId`/`event`/
+ * `timestamp` routing hints. For terminal events `data` is a compact JWE
+ * string wrapping the signed JWS (or the plaintext JWS JSON when the org has
+ * no encryption credential). The envelope is unauthenticated; trust only the
+ * decrypted+verified JWS.
+ *
+ * Derived from the generated spec type so it can't drift; the hint fields
+ * are relaxed to optional — decryption only needs `data`.
+ */
+export type DeliveryEnvelope = Partial<
+	components['schemas']['VerificationResultDelivery']
+> &
+	Pick<components['schemas']['VerificationResultDelivery'], 'data'>
+
+/** Anything a callback handler may have on hand: the parsed envelope, its
+ *  JSON text, its raw body bytes — or a bare compact JWE / JWS string. */
+export type CallbackBody =
+	| DeliveryEnvelope
+	| string
+	| Uint8Array
+	| ArrayBuffer
+
+/** Normalize any {@link CallbackBody} to the terminal-result `data` string —
+ *  either a compact JWE (`xxxx.yyyy.zzzz.aaaa.bbbb`) or the plaintext JWS JSON
+ *  (`{…}`). The envelope object/text wraps it in `.data`; raw bytes are decoded
+ *  to text first. */
+function payloadFrom(body: CallbackBody): string {
+	if(typeof body === 'string') {
+		const s = body.trim()
+		// A JSON envelope/JWS starts with '{'; anything else is the bare `data`
+		// (compact JWE). An envelope's `data` is extracted; a bare JWS is returned.
+		if(s.startsWith('{')) {
+			const parsed = JSON.parse(s) as DeliveryEnvelope | Jws
+			if(typeof (parsed as DeliveryEnvelope).data === 'string') {
+				return (parsed as DeliveryEnvelope).data
+			}
+
+			return s
+		}
+
+		return s
+	}
+
+	if(body instanceof ArrayBuffer) {
+		return payloadFrom(new TextDecoder().decode(new Uint8Array(body)))
+	}
+
+	if(body instanceof Uint8Array) {
+		return payloadFrom(new TextDecoder().decode(body))
+	}
+
+	return body.data
+}
+
+/**
+ * Decrypt a delivered terminal callback to the signed JWS. `data` is either a
+ * compact JWE (decrypted with the X25519 `privateKey`) or — when the org has no
+ * encryption credential — the plaintext JWS JSON. A compact JWE has exactly
+ * five dot-separated base64url segments; a JSON JWS starts with `{`.
+ *
+ * `privateKey` may be absent (plaintext delivery); an encrypted delivery with
+ * no key throws a clear error.
+ */
+export async function decryptCallback(
+	privateKey: DecryptionKey | undefined,
+	body: CallbackBody,
+): Promise<Jws> {
+	const data = payloadFrom(body)
+	const trimmed = data.trim()
+
+	// Plaintext delivery: `data` is the JWS JSON directly.
+	if(trimmed.startsWith('{')) {
+		return JSON.parse(trimmed) as Jws
+	}
+
+	// Otherwise it's a compact JWE — five base64url segments.
+	if(!privateKey) {
+		throw new Error(
+			'received an encrypted (JWE) delivery but no decryption credential was '
+				+ 'configured — pass the X25519 private key (JWK/PEM): '
+				+ 'results.receive(body, { credential }) or decrypt(body, credential)',
+		)
+	}
+
+	const { plaintext } = await compactDecrypt(trimmed, privateKey)
+	return JSON.parse(new TextDecoder().decode(plaintext)) as Jws
+}
+
+/**
+ * Sign a verification result as a flattened JWS (JOSE ES256K = ECDSA/secp256k1
+ * over SHA-256 of the `<protected>.<payload>` signing input — a single hash).
+ * `kid` is the signer's ETH address (published via JWKS); `iss` is the issuer
+ * URL. Used by the Verification Client to sign results before encrypting them.
+ */
+export function signResultJws(
+	privateKeyHex: string,
+	payload: Record<string, unknown>,
+	iss: string,
+): Jws {
+	const priv = hexToBytes(privateKeyHex)
+	const protectedHeader = b64url(
+		JSON.stringify({
+			alg: 'ES256K',
+			kid: addressFromUncompressedPubkey(secp.getPublicKey(priv, false)),
+			typ: 'JWS',
+			iss,
+		}),
+	)
+	const payloadB64 = b64url(JSON.stringify(payload))
+	const signingInput = new TextEncoder().encode(
+		`${protectedHeader}.${payloadB64}`,
+	)
+	// Standard ES256K: a single SHA-256 of the signing input. `prehash:false`
+	// stops @noble hashing the digest again, so any JOSE tool can verify it.
+	const sig = secp.sign(sha256(signingInput), priv, { prehash: false })
+	return {
+		payload: payloadB64,
+		signatures: [{ protected: protectedHeader, signature: b64url(sig) }],
+	}
+}
+
+/** Decode the JWS payload (base64url JSON). */
+export function decodeJwsPayload(jws: Jws): Record<string, unknown> {
+	return JSON.parse(
+		new TextDecoder().decode(base64urlToBytes(jws.payload)),
+	) as Record<string, unknown>
+}
+
+/**
+ * Verify a JWS signature (JOSE ES256K = ECDSA/secp256k1 over SHA-256 of the
+ * `<protected>.<payload>` signing input) with an uncompressed public key.
+ */
+export function verifyJwsSignature(jws: Jws, signerPublicKey: string): boolean {
+	const pub = hexToBytes(signerPublicKey)
+	return jws.signatures.some((s) => {
+		try {
+			const signingInput = new TextEncoder().encode(
+				`${s.protected}.${jws.payload}`
+			)
+			const digest = sha256(signingInput)
+			const sig = base64urlToBytes(s.signature)
+			// digest is the single SHA-256 of the signing input — don't let
+			// @noble hash it again (standard ES256K).
+			return secp.verify(sig, digest, pub, { prehash: false })
+		} catch{
+			return false
+		}
+	})
+}
+
+/** Content hash binding extracted parameters — MUST mirror the Verification
+ *  Client's `contentHash` exactly (keccak256 of the RFC 8785 canonical JSON,
+ *  via the shared `canonicalJson`). */
+function contentHash(params: Record<string, string>): string {
+	const canonical = canonicalJson(params)
+	return '0x' + bytesToHex(keccak_256(new TextEncoder().encode(canonical)))
+}
+
+export interface VerifyResultFullOptions {
+	/** The `reclaimSessionId` the consumer expects (mismatch fails). */
+	expectedReclaimSessionId?: string
+	/** The consumer's `orgId`; the result's `aud` must match it. */
+	expectedAud?: string
+	/** Allowlist of trusted attestor ETH addresses (lowercased compared). */
+	attestorAddresses?: string[]
+	/** Override the VC signer key instead of JWKS discovery via header `iss`. */
+	signerPublicKey?: string
+	/** Injectable fetch (for JWKS); defaults to global `fetch`. */
+	fetchImpl?: typeof fetch
+	/** Override "now" (unix seconds) for `exp` checks. */
+	now?: number
+}
+
+export interface ResultProofOutcome {
+	requestId?: string
+	proofValid: boolean
+	reason?: string
+	attestorAddress?: string
+}
+
+export interface VerifyResultFullOutcome extends VerifyResultOutcome {
+	proofs?: ResultProofOutcome[]
+}
+
+/**
+ * Thrown by {@link verifyResult} / {@link verifyResultFull} (and therefore
+ * `reclaim.results.verify`/`receive`) when a result fails verification. Carries
+ * the full invalid outcome so callers can inspect it in a `catch`:
+ *
+ *   try {
+ *     const { result } = await reclaim.results.receive(body, { credential })
+ *     // result is verified — use result.payload
+ *   } catch (err) {
+ *     if (err instanceof ResultVerificationError) {
+ *       // e.g. 'expired', { payload, … }
+ *       console.error(err.reason, err.outcome)
+ *     }
+ *   }
+ */
+export class ResultVerificationError extends Error {
+	/** Machine-readable failure reason — `'bad-signature'`, `'expired'`,
+	 *  `'reclaimSessionId-mismatch'`, `'aud-mismatch'`, `'invalid-proof'`, … */
+	readonly reason: string
+	/** The full (invalid) outcome: `payload`, `reclaimSessionId`, and per-proof
+	 *  detail (`proofs`) when verification got that far. */
+	readonly outcome: VerifyResultFullOutcome
+
+	constructor(outcome: VerifyResultFullOutcome) {
+		super(`result verification failed: ${outcome.reason ?? 'invalid'}`)
+		this.name = 'ResultVerificationError'
+		this.reason = outcome.reason ?? 'invalid'
+		this.outcome = outcome
+	}
+}
+
+/**
+ * Full consumer verification: discovers the Verification Client's signing key
+ * via JWKS (header `iss`/`kid`), verifies the top-level JWS, checks
+ * `reclaimSessionId`/`aud`/`exp`, then verifies each result's nested attestor
+ * proof and its `content_hash`. Network access (JWKS) makes this async; use
+ * {@link verifyResult} for the offline primitive.
+ */
+export async function verifyResultFull(
+	jws: Jws,
+	opts: VerifyResultFullOptions = {},
+): Promise<VerifyResultFullOutcome> {
+	const payload = decodeJwsPayload(jws)
+	const reclaimSessionId = payload.reclaimSessionId as string | undefined
+	/** Throw with the full invalid outcome — verification never *returns* an
+	 *  invalid result. */
+	const fail = (
+		reason: string,
+		extra: Partial<VerifyResultFullOutcome> = {},
+	): never => {
+		throw new ResultVerificationError({
+			valid: false,
+			reason,
+			payload,
+			reclaimSessionId,
+			...extra,
+		})
+	}
+
+	// 1. Resolve the VC signer key: explicit override, else JWKS via header iss.
+	let signerPublicKey = opts.signerPublicKey
+	let header: Record<string, unknown> = {}
+	const sig0 = jws.signatures[0]
+	if(sig0) {
+		try {
+			header = JSON.parse(
+				new TextDecoder().decode(base64urlToBytes(sig0.protected)),
+			)
+		} catch{
+			return fail('bad-header')
+		}
+	}
+
+	if(!signerPublicKey) {
+		const iss = String(header.iss ?? '')
+		if(!iss) {
+			return fail('no-issuer')
+		}
+
+		const keys = await fetchJwks(iss, opts.fetchImpl)
+		const jwk = selectKey(keys, String(header.kid ?? ''))
+		if(!jwk) {
+			return fail('signer-key-not-found')
+		}
+
+		signerPublicKey = jwkToUncompressedPublicKey(jwk)
+	}
+
+	if(!verifyJwsSignature(jws, signerPublicKey)) {
+		return fail('bad-signature')
+	}
+
+	// 2. Freshness / audience / expiry.
+	if(
+		opts.expectedReclaimSessionId &&
+		reclaimSessionId !== opts.expectedReclaimSessionId
+	) {
+		return fail('reclaimSessionId-mismatch')
+	}
+
+	if(opts.expectedAud && payload.aud !== opts.expectedAud) {
+		return fail('aud-mismatch')
+	}
+
+	const now = opts.now ?? Math.floor(Date.now() / 1000)
+	if(typeof payload.exp === 'number' && payload.exp < now) {
+		return fail('expired')
+	}
+
+	// 3. Per-result nested attestor proof + content_hash binding.
+	const results = Array.isArray(payload.results)
+		? (payload.results as Record<string, unknown>[])
+		: []
+	const proofs: ResultProofOutcome[] = []
+	for(const r of results) {
+		const requestId =
+			typeof r.request_id === 'string' ? r.request_id : undefined
+		if(typeof r.proof !== 'string') {
+			proofs.push({ requestId, proofValid: false, reason: 'proof-missing' })
+			continue
+		}
+
+		const np: NestedProofOutcome = verifyNestedProof(r.proof, {
+			attestorAddresses: opts.attestorAddresses,
+		})
+		if(!np.valid) {
+			proofs.push({
+				requestId,
+				proofValid: false,
+				reason: np.reason,
+				attestorAddress: np.attestorAddress,
+			})
+			continue
+		}
+
+		if(
+			typeof r.content_hash === 'string' &&
+			r.extracted_parameters &&
+			typeof r.extracted_parameters === 'object'
+		) {
+			const params = r.extracted_parameters as Record<string, string>
+			if(contentHash(params).toLowerCase() !== r.content_hash.toLowerCase()) {
+				proofs.push({
+					requestId,
+					proofValid: false,
+					reason: 'content-hash-mismatch',
+					attestorAddress: np.attestorAddress,
+				})
+				continue
+			}
+		}
+
+		proofs.push({
+			requestId,
+			proofValid: true,
+			attestorAddress: np.attestorAddress,
+		})
+	}
+
+	if(!proofs.every((p) => p.proofValid)) {
+		return fail('invalid-proof', { proofs })
+	}
+
+	return { valid: true, payload, reclaimSessionId, proofs }
+}
+
+/** Decrypt-and-verify in one step. */
+export function verifyResult(
+	jws: Jws,
+	opts: VerifyResultOptions = {},
+): VerifyResultOutcome {
+	const payload = decodeJwsPayload(jws)
+	const reclaimSessionId = payload.reclaimSessionId as string | undefined
+
+	if(opts.signerPublicKey && !verifyJwsSignature(jws, opts.signerPublicKey)) {
+		throw new ResultVerificationError({
+			valid: false, reason: 'bad-signature', payload, reclaimSessionId,
+		})
+	}
+
+	if(
+		opts.expectedReclaimSessionId &&
+		reclaimSessionId !== opts.expectedReclaimSessionId
+	) {
+		throw new ResultVerificationError({
+			valid: false,
+			reason: 'reclaimSessionId-mismatch',
+			payload,
+			reclaimSessionId,
+		})
+	}
+
+	return { valid: true, payload, reclaimSessionId }
+}

package/src/routes.gen.ts

@@ -5,10 +5,12 @@
 
 export const ROUTES = {
 	"AddOrgMember": {"method":"post","path":"/orgs/{orgId}/members"},
+	"AdminCallbackDlq": {"method":"get","path":"/admin/callback-dlq"},
 	"AdminHome": {"method":"get","path":"/admin"},
 	"AdminOrgs": {"method":"get","path":"/admin/orgs"},
 	"AdminProviders": {"method":"get","path":"/admin/providers"},
 	"AdminReviews": {"method":"get","path":"/admin/reviews"},
+	"AdminSessions": {"method":"get","path":"/admin/sessions"},
 	"AdminThemes": {"method":"get","path":"/admin/themes"},
 	"AdminUsers": {"method":"get","path":"/admin/users"},
 	"AttachPage": {"method":"get","path":"/attach/{code}"},
@@ -16,15 +18,19 @@ export const ROUTES = {
 	"ComponentsDemo": {"method":"get","path":"/components_demo"},
 	"ConfirmAttachSession": {"method":"post","path":"/credentials/attach/sessions/{code}/confirm"},
 	"CreateAttachSession": {"method":"post","path":"/credentials/attach/sessions"},
+	"CreateCallbackSubscription": {"method":"post","path":"/verifications/callback-subscriptions"},
 	"CreateOrg": {"method":"post","path":"/orgs"},
+	"CreateOrgCallbackSubscription": {"method":"post","path":"/orgs/{orgId}/callback-subscriptions"},
 	"CreateProvider": {"method":"post","path":"/providers"},
 	"CreateProviderVersion": {"method":"post","path":"/providers/{providerId}/versions"},
 	"CreateTheme": {"method":"post","path":"/orgs/{orgId}/themes"},
-	"CredentialAuthChallenge": {"method":"post","path":"/credentials/auth/challenge"},
-	"CredentialAuthVerify": {"method":"post","path":"/credentials/auth/verify"},
+	"CreateVerificationSession": {"method":"post","path":"/verifications/sessions"},
 	"DecideProviderVersionReview": {"method":"post","path":"/providers/{providerId}/versions/{version}/review-decision"},
+	"DeleteCallbackSubscription": {"method":"delete","path":"/verifications/callback-subscriptions/{subscriptionId}"},
 	"DeleteOrg": {"method":"delete","path":"/orgs/{orgId}"},
 	"DeleteOrgBilling": {"method":"delete","path":"/orgs/{orgId}/billing"},
+	"DeleteOrgCallbackSubscription": {"method":"delete","path":"/orgs/{orgId}/callback-subscriptions/{subscriptionId}"},
+	"DeleteOrgCredential": {"method":"delete","path":"/orgs/{orgId}/credential"},
 	"DeleteOrgIcon": {"method":"delete","path":"/orgs/{orgId}/icon"},
 	"DeleteProvider": {"method":"delete","path":"/providers/{providerId}"},
 	"DeleteProviderVersion": {"method":"delete","path":"/providers/{providerId}/versions/{version}"},
@@ -32,23 +38,34 @@ export const ROUTES = {
 	"Docs": {"method":"get","path":"/docs"},
 	"ExplorePreviewImage": {"method":"get","path":"/og/explore.png"},
 	"GetAttachSession": {"method":"get","path":"/credentials/attach/sessions/{code}"},
-	"GetCredential": {"method":"get","path":"/credentials/{credentialId}"},
-	"GetCredentialByAddress": {"method":"get","path":"/credentials/by-address/{address}"},
 	"GetImage": {"method":"get","path":"/images/{imageId}"},
 	"GetMe": {"method":"get","path":"/me"},
 	"GetOrg": {"method":"get","path":"/orgs/{orgId}"},
 	"GetOrgBilling": {"method":"get","path":"/orgs/{orgId}/billing"},
+	"GetOrgCredential": {"method":"get","path":"/orgs/{orgId}/credential"},
+	"GetOrgSession": {"method":"get","path":"/orgs/{orgId}/sessions/{sessionId}"},
+	"GetOrgToken": {"method":"get","path":"/orgs/{orgId}/token"},
 	"GetProvider": {"method":"get","path":"/providers/{providerId}"},
 	"GetProviderBySlug": {"method":"get","path":"/providers/{providerId}/{slug}"},
 	"GetProviderVersion": {"method":"get","path":"/providers/{providerId}/versions/{version}"},
 	"GetTheme": {"method":"get","path":"/orgs/{orgId}/themes/{themeId}"},
 	"GetUser": {"method":"get","path":"/users/{userId}"},
+	"GetVerificationRecipe": {"method":"get","path":"/verifications/sessions/{sessionId}/recipe"},
+	"GetVerificationResult": {"method":"get","path":"/verifications/sessions/{sessionId}/result"},
+	"GetVerificationSession": {"method":"get","path":"/verifications/sessions/{sessionId}"},
 	"Index": {"method":"get","path":"/"},
-	"LinkCredential": {"method":"post","path":"/credentials"},
-	"ListOrgCredentials": {"method":"get","path":"/orgs/{orgId}/credentials"},
+	"IssueOrgToken": {"method":"post","path":"/orgs/{orgId}/token"},
+	"JwksJson": {"method":"get","path":"/.well-known/jwks.json"},
+	"ListCallbackDlq": {"method":"get","path":"/verifications/callback-dlq"},
+	"ListCallbackSubscriptions": {"method":"get","path":"/verifications/callback-subscriptions"},
+	"ListOrgCallbackSubscriptions": {"method":"get","path":"/orgs/{orgId}/callback-subscriptions"},
 	"ListOrgs": {"method":"get","path":"/orgs"},
+	"ListOrgVerificationSessions": {"method":"get","path":"/orgs/{orgId}/sessions"},
 	"ListProviderVersions": {"method":"get","path":"/providers/{providerId}/versions"},
+	"ListSessionCallbackKeys": {"method":"get","path":"/verifications/sessions/{sessionId}/callback-keys"},
 	"ListThemes": {"method":"get","path":"/orgs/{orgId}/themes"},
+	"ListVerificationDeliveries": {"method":"get","path":"/verifications/sessions/{sessionId}/deliveries"},
+	"ListVerificationEvents": {"method":"get","path":"/verifications/sessions/{sessionId}/events"},
 	"Login": {"method":"post","path":"/auth/login"},
 	"LoginPage": {"method":"get","path":"/login"},
 	"Logout": {"method":"post","path":"/logout"},
@@ -58,12 +75,17 @@ export const ROUTES = {
 	"Providers": {"method":"get","path":"/providers"},
 	"PublishProviderVersion": {"method":"post","path":"/providers/{providerId}/versions/{version}/publish"},
 	"RemoveOrgMember": {"method":"delete","path":"/orgs/{orgId}/members/{memberId}"},
+	"ReportClaimant": {"method":"post","path":"/v/{sessionId}/claimant"},
+	"ReportVerificationEvent": {"method":"post","path":"/verifications/sessions/{sessionId}/events"},
 	"RequestPublicListing": {"method":"post","path":"/providers/{providerId}/request-public"},
-	"RevokeCredential": {"method":"delete","path":"/credentials/{credentialId}"},
+	"RetryCallbackDlq": {"method":"post","path":"/verifications/callback-dlq/{dlqId}/retry"},
+	"RetryVerificationCallback": {"method":"post","path":"/verifications/sessions/{sessionId}/retry-callback"},
 	"Robots": {"method":"get","path":"/robots.txt"},
+	"SetOrgCredential": {"method":"put","path":"/orgs/{orgId}/credential"},
 	"SetupProviderCreate": {"method":"post","path":"/providers/setup"},
 	"Sitemap": {"method":"get","path":"/sitemap.xml"},
 	"SubmitProviderVersionForReview": {"method":"post","path":"/providers/{providerId}/versions/{version}/review"},
+	"SubmitVerificationResult": {"method":"post","path":"/verifications/sessions/{sessionId}/result"},
 	"TransferProvider": {"method":"post","path":"/providers/{providerId}/transfer"},
 	"UpdateMe": {"method":"patch","path":"/me"},
 	"UpdateOrg": {"method":"patch","path":"/orgs/{orgId}"},
@@ -73,6 +95,9 @@ export const ROUTES = {
 	"UpdateProvider": {"method":"patch","path":"/providers/{providerId}"},
 	"UpdateProviderVersion": {"method":"patch","path":"/providers/{providerId}/versions/{version}"},
 	"UpdateTheme": {"method":"patch","path":"/orgs/{orgId}/themes/{themeId}"},
+	"VerificationPage": {"method":"get","path":"/v/{sessionId}"},
+	"VerificationSessionSse": {"method":"get","path":"/v/{sessionId}/sse"},
+	"VerificationStatus": {"method":"get","path":"/v/{sessionId}/status"},
 } as const
 
 export type RouteId = keyof typeof ROUTES

package/src/secp.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared `@noble/secp256k1` instance with the v3 hash hooks wired once
+ * (sign + recover need SHA-256 / HMAC-SHA256). Import `secp` from here — never
+ * set `secp.hashes` ad-hoc — so the hooks are guaranteed initialised before any
+ * sign/verify/recover call, regardless of import order.
+ */
+import { hmac } from '@noble/hashes/hmac.js'
+import { sha256 } from '@noble/hashes/sha2.js'
+import { keccak_256 } from '@noble/hashes/sha3.js'
+import * as secp from '@noble/secp256k1'
+import { bytesToHex } from './encoding.ts'
+
+secp.hashes.sha256 = sha256
+secp.hashes.hmacSha256 = (key: Uint8Array, msg: Uint8Array) => {
+	return hmac(sha256, key, msg)
+}
+
+export { keccak_256, secp }
+
+/** Lowercase 0x ETH address from an uncompressed (65-byte) public key:
+ *  keccak256 of the 64-byte X‖Y (drop the 0x04 prefix), last 20 bytes. */
+export function addressFromUncompressedPubkey(pub: Uint8Array): string {
+	return '0x' + bytesToHex(keccak_256(pub.slice(1))).slice(-40)
+}

package/src/types/index.ts

@@ -1,2 +1,2 @@
 export * from './openapi.ts'
-export type { components, operations, paths } from './openapi.gen.ts'
+export * from './openapi.gen.ts'