@reclaimprotocol/client 0.1.0-dev.1 → 0.1.0

package/src/reclaim.ts

@@ -0,0 +1,332 @@
+/**
+ * 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
+ * `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 })
+ *   // …end-user completes session.verificationUrl…
+ *   const outcome = await reclaim.results.receive(callbackBody, {
+ *   	credential: privateJwk, // omit for plaintext
+ *   	expectedReclaimSessionId: session.id,
+ *   })
+ *
+ * Built by composition over the package's pure helpers (`decryptCallback`,
+ * `verifyResultFull`, …) — drop down to those, or to `reclaim.api`, for full
+ * control.
+ */
+import type { components } from './types/openapi.gen.ts'
+import { ReclaimClient } from './client.ts'
+import {
+	type DecryptionKey,
+	type DecryptionKeyInput,
+	loadDecryptionKey,
+	publicPemToJwk,
+} from './enckeys.ts'
+import {
+	type CallbackBody,
+	decryptCallback,
+	type Jws,
+	verifyResultFull,
+	type VerifyResultFullOptions,
+	type VerifyResultFullOutcome,
+} from './result.ts'
+
+type CallbackSubscription = components['schemas']['CallbackSubscription']
+type VerificationSession = components['schemas']['VerificationSession']
+type VerificationEvent = components['schemas']['VerificationEvent']
+type VerificationEventRecord = components['schemas']['VerificationEventRecord']
+type OrgCredential = components['schemas']['OrgCredential']
+type JwkX25519Public = components['schemas']['JwkX25519Public']
+
+/** The three terminal events a subscription can receive. */
+export const TERMINAL_EVENTS = [
+	'verification_success',
+	'verification_rejected',
+	'verification_error',
+] as const
+
+export interface RegisterCallbackInput {
+	callbackUrl: string
+	events: VerificationEvent[]
+}
+
+export interface CreateSessionInput {
+	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
+}
+
+export interface ReclaimConfig {
+	/** The org secret (`rorg_…`). Authenticates ALL API calls and identifies
+	 *  the org server-side. The only required config. */
+	orgSecret: string
+	/** Backend base URL. Defaults to the production Builder. */
+	baseUrl?: string
+	/** Custom fetch implementation. */
+	fetch?: typeof fetch
+	/** Extra headers merged into every request. */
+	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). */
+export type ReceiveOptions = VerifyResultFullOptions & {
+	credential?: DecryptionKeyInput
+}
+
+export interface Reclaim {
+	/** Typed escape hatch: `reclaim.api('OperationId', args)` for any spec
+	 *  operation. */
+	api: ReclaimClient['call']
+	sessions: {
+		/** Create a verification session. `verificationClientUrl` defaults to
+		 *  the Builder's own `/v/{sessionId}` page. */
+		create(
+			input: Omit<CreateSessionInput, 'verificationClientUrl'> &
+				Partial<Pick<CreateSessionInput, 'verificationClientUrl'>>,
+		): Promise<VerificationSession>
+		get(sessionId: string): Promise<VerificationSession>
+		listEvents(sessionId: string): Promise<VerificationEventRecord[]>
+	}
+	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. */
+		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>
+	}
+	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(body: CallbackBody, credential?: DecryptionKeyInput): Promise<Jws>
+		/** Verify a decrypted JWS: JWKS discovery, ES256K signature,
+		 *  `reclaimSessionId`/`aud`/`exp`, nested attestor proofs. */
+		verify(
+			jws: Jws,
+			opts?: VerifyResultFullOptions,
+		): Promise<VerifyResultFullOutcome>
+		/** Handle any callback delivery in one call — the 90% path. Branches on
+		 *  the envelope's `event`: a terminal event is decrypted (with
+		 *  `opts.credential` when encrypted) + verified into a `result`; a
+		 *  non-terminal event is returned as a plaintext (unsigned) `event`
+		 *  notification without decryption. (A raw JWE/JWS body with no envelope
+		 *  `event` is treated as a terminal result.) */
+		receive(
+			body: CallbackBody,
+			opts?: ReceiveOptions,
+		): Promise<ReceivedDelivery>
+	}
+}
+
+/** Outcome of `results.receive` — a verified terminal result or a plaintext
+ *  non-terminal progress notification. Branch on `kind`. */
+export type ReceivedDelivery =
+	| { kind: 'result', result: VerifyResultFullOutcome }
+	| {
+		kind: 'event'
+		event: VerificationEvent
+		eventData: Record<string, unknown>
+	}
+
+export function createReclaim(config: ReclaimConfig): Reclaim {
+	if(!config?.orgSecret) {
+		throw new Error(
+			'createReclaim requires an org secret — pass '
+				+ 'createReclaim({ orgSecret: <rorg_… org secret> })',
+		)
+	}
+
+	const client = new ReclaimClient({
+		baseUrl: config.baseUrl,
+		token: config.orgSecret,
+		fetch: config.fetch,
+		headers: config.headers,
+	})
+
+	// Load an X25519 decryption key on demand — `undefined` input ⇒ no key, so
+	// plaintext-only consumers never touch the loader.
+	const resolveKey = (
+		input: DecryptionKeyInput | undefined,
+	): Promise<DecryptionKey | undefined> => (
+		input === undefined
+			? Promise.resolve(undefined)
+			: loadDecryptionKey(input)
+	)
+
+	return {
+		api: client.call.bind(client),
+		sessions: {
+			async create(input) {
+				const body: CreateSessionInput = {
+					...input,
+					verificationClientUrl:
+						input.verificationClientUrl ?? `${client.baseUrl}/v/{sessionId}`,
+				}
+				const { data } = await client.call('CreateVerificationSession', {
+					body,
+				})
+				return data
+			},
+			async get(sessionId) {
+				const { data } = await client.call('GetVerificationSession', {
+					params: { sessionId },
+				})
+				return data
+			},
+			async listEvents(sessionId) {
+				const { data } = await client.call('ListVerificationEvents', {
+					params: { sessionId },
+				})
+				return data.items
+			},
+		},
+		callbacks: {
+			async register(input) {
+				const events = input.events ?? [...TERMINAL_EVENTS]
+				const { data } = await client.call('CreateCallbackSubscription', {
+					body: { callbackUrl: input.callbackUrl, events },
+				})
+				return data
+			},
+			async list() {
+				const { data } = await client.call('ListCallbackSubscriptions')
+				return data.items
+			},
+			async remove(subscriptionId) {
+				await client.call('DeleteCallbackSubscription', {
+					params: { subscriptionId },
+				})
+			},
+		},
+		credential: {
+			async set(orgId, input) {
+				// Convert the consumer's SPKI public PEM to the JWK the API stores
+				// (PEM at the edge; JWK on the wire/DB/VC stays unchanged).
+				const publicKeyJwk = (await publicPemToJwk(
+					input.publicKeyPem,
+				)) as JwkX25519Public
+				const { data } = await client.call('SetOrgCredential', {
+					params: { orgId },
+					body: { publicKeyJwk, label: input.label },
+				})
+				return data
+			},
+			async get(orgId) {
+				try {
+					const { data } = await client.call('GetOrgCredential', {
+						params: { orgId },
+					})
+					return data
+				} catch(err) {
+					// 404 ⇒ no credential set (plaintext delivery).
+					if(isNotFound(err)) {
+						return undefined
+					}
+
+					throw err
+				}
+			},
+		},
+		results: {
+			async decrypt(body, credential) {
+				return decryptCallback(await resolveKey(credential), body)
+			},
+			verify(jws, opts) {
+				return verifyResultFull(jws, { fetchImpl: config.fetch, ...opts })
+			},
+			async receive(body, opts) {
+				// A delivery envelope tagged with a non-terminal event carries a
+				// plaintext, unsigned `{ event, eventData }` payload — return it
+				// directly, no decryption/verification.
+				if(
+					body && typeof body === 'object'
+					&& !(body instanceof Uint8Array)
+					&& !(body instanceof ArrayBuffer)
+				) {
+					const env = body
+					if(
+						env.event
+						&& !(TERMINAL_EVENTS as readonly string[]).includes(env.event)
+					) {
+						const decoded = parseEventData(env.data)
+						return {
+							kind: 'event',
+							event: env.event,
+							eventData: decoded,
+						}
+					}
+				}
+
+				const { credential, ...verifyOpts } = opts ?? {}
+				const key = await resolveKey(credential)
+				const jws = await decryptCallback(key, body)
+				const result = await verifyResultFull(jws, {
+					fetchImpl: config.fetch,
+					...verifyOpts,
+				})
+				return { kind: 'result', result }
+			},
+		},
+	}
+}
+
+/** Non-terminal `data` is a base64-encoded JSON `{ event, eventData }`. */
+function parseEventData(data: string | undefined): Record<string, unknown> {
+	if(!data) {
+		return {}
+	}
+
+	try {
+		const decoded = JSON.parse(
+			Buffer.from(data, 'base64').toString('utf8'),
+		) as { eventData?: Record<string, unknown> }
+		return decoded.eventData ?? {}
+	} catch{
+		return {}
+	}
+}
+
+/** True for a `404` thrown by {@link ReclaimClient.call} — a Boom error whose
+ *  `output.statusCode` is 404 (see ./errors.ts). */
+function isNotFound(err: unknown): boolean {
+	if(typeof err !== 'object' || err === null) {
+		return false
+	}
+
+	const boom = err as { output?: { statusCode?: number }, statusCode?: number }
+	return boom.output?.statusCode === 404 || boom.statusCode === 404
+}