@reclaimprotocol/client 0.1.28 → 0.1.31

package/src/reclaim.ts

@@ -1,20 +1,19 @@
 /**
  * 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 `keypair.set`/`get`, and the eth decryption key to
- * `results.decrypt`/`receive` (only when results arrive encrypted):
+ * server-side. Pass the optional organization ETH private key only to the
+ * operation that needs it:
  *
- *   const reclaim = createReclaim({ orgSecret })
- *   // one-time setup:
- *   await reclaim.callbacks.register({ callbackUrl })
- *   // enable encryption (eth public key, hex):
- *   await reclaim.keypair.set(orgId, { publicKey, canEncryptResult: true })
- *   const session = await reclaim.sessions.create({ providers, context })
+ *   const reclaim = ReclaimVerification.create({ orgSecret })
+ *   const session = await reclaim.sessions.create({
+ *   	providers,
+ *   	context,
+ *   	orgEthPrivateKey, // optional TEE session binding
+ *   })
  *   // …end-user completes session.verificationUrl…
  *   const outcome = await reclaim.results.receive(callbackBody, {
- *   	credential: ethPrivateKeyHex, // omit for plaintext
- *   	expectedReclaimSessionId: session.id,
+ *   	orgEthPrivateKey, // optional decryption and TEE proof verification
+ *   	reclaimSessionId: session.id,
  *   })
  *
  * Built by composition over the package's pure helpers (`decryptCallback`,
@@ -28,10 +27,9 @@ import {
 	type DecryptionKeyInput,
 	loadDecryptionKey,
 } from './enckeys.ts'
-import { isProblemError } from './errors.ts'
 import type { BuilderProofRecipe } from './proof-recipe.ts'
 import { proofHashesFromBuilderRecipe } from './proof-recipe.ts'
-import type { LegacyProof } from './proof-types.ts'
+import type { ReclaimRequestProof } from './proof-types.ts'
 import {
 	type CallbackBody,
 	decryptCallback,
@@ -45,21 +43,9 @@ import {
 	type LegacyTeeNonceMode,
 } from './tee-binding.ts'
 
-type CallbackSubscription = components['schemas']['CallbackSubscription']
 type VerificationSession = components['schemas']['VerificationSession']
 type VerificationEvent = components['schemas']['VerificationEvent']
 type VerificationEventRecord = components['schemas']['VerificationEventRecord']
-type OrgKeypair = components['schemas']['OrgKeypair']
-type OrgKeypairRequest = components['schemas']['OrgKeypairRequest']
-
-/** Terminal lifecycle events selected by default for callback subscriptions. */
-export const TERMINAL_EVENTS = [
-	'verification_success',
-	'verification_rejected',
-	'verification_error',
-	'verification_cancelled',
-	'session_expired',
-] as const
 
 const SIGNED_RESULT_EVENTS = [
 	'verification_success',
@@ -67,47 +53,41 @@ const SIGNED_RESULT_EVENTS = [
 	'verification_error',
 ] as const
 
-export interface RegisterCallbackInput {
-	callbackUrl: string
-	events: VerificationEvent[]
-}
-
 export interface CreateSessionInput {
 	/** 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>
-	/** Exact registered Verification Client base URL. It may contain a
+	/** Exact registered Verification Client base URL. Defaults to the Portal.
+	 *  It may contain a
 	 *  `{sessionId}` placeholder; Builder otherwise adds the session id as a
 	 *  query parameter. Open the returned `verificationUrl`, not this base
 	 *  URL. */
-	verificationClientUrl: string
-	/** Optional legacy-compatible TEE session binding. The app secret is the
-	 *  organization's verification private key and never leaves this process.
+	verificationClientUrl?: string
+	/** Optional legacy-compatible TEE session binding. The organization's ETH
+	 *  private key never leaves this process.
 	 *  Session creation returns only after Builder stores the signed binding. */
-	teeAttestation?: CreateSessionTeeAttestation
+	orgEthPrivateKey?: string
+	/** Override the legacy TEE nonce mode when binding a session. */
+	teeNonceMode?: LegacyTeeNonceMode
+	/** Opt this session into diagnostic mode: more event detail, including
+	 *  personal data such as the claimant's IP addresses. Builder builds
+	 *  `verificationUrl` with `diag=1` for a diagnostic session — do not
+	 *  append `diag` to the URL directly, since Builder strips it and derives
+	 *  the parameter from this flag instead. Treat a diagnostic
+	 *  `verificationUrl` as sensitive. */
+	diagnostics?: boolean
 }
 
-/** Options intentionally mirror legacy `verifyProof`'s `teeAttestation`
- *  vocabulary. `timestamp` is decimal Unix milliseconds; omit it to use now. */
-export interface CreateSessionTeeAttestation {
-	appSecret: string
+/** Input for explicitly binding a session's legacy-compatible TEE context. */
+export interface BindSessionTeeNonceInput {
+	orgEthPrivateKey: string
 	timestamp?: string
 	/** `hash` is the default. Use `signature` only for an older Verification
 	 * Client that expects the 65-byte EIP-191 nonce. */
-	nonceMode?: LegacyTeeNonceMode
+	teeNonceMode?: LegacyTeeNonceMode
 }
 
-/** 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. */
@@ -120,70 +100,82 @@ export interface ReclaimConfig {
 	headers?: Record<string, string>
 }
 
+/** Serializable SDK configuration.
+ *  Credentials and runtime hooks are omitted. */
+export interface ReclaimVerificationState {
+	version: 1
+	baseUrl: string
+}
+
+/** Runtime-only values required to restore serialized SDK configuration. */
+export type ImportReclaimVerificationConfig = Omit<ReclaimConfig, 'baseUrl'>
+
 /** Options for `results.receive` — the verification options plus an optional
  *  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
+export type ReceiveOptions = VerifyResultFullOptions
+
+/** A thin backend-side handle on a session's `verificationUrl` — see
+ *  `reclaim.flow`. Not the browser launcher: this holds no device
+ *  detection or launch mechanism, only the URL the browser needs. The
+ *  browser-only `ReclaimFlow.from(session)` in
+ *  `@reclaimprotocol/client/launch` is the counterpart that actually
+ *  resolves how to open it. */
+export interface SessionFlow {
+	/** `session.verificationUrl`. A `Promise` so backend code calling this
+	 *  doesn't need to special-case it against the browser `ReclaimFlow`'s
+	 *  `getUrl()`, which does real async work. */
+	getUrl(): Promise<string>
+	readonly session: VerificationSession
 }
 
-export interface Reclaim {
+/** `reclaim.flow(session)` wraps a session already created via
+ *  `sessions.create`/`sessions.get`; `reclaim.flow.create(input)` creates one
+ *  and wraps it in the same step. */
+export interface ReclaimFlowFactory {
+	(session: VerificationSession): SessionFlow
+	create(input: CreateSessionInput): Promise<SessionFlow>
+}
+
+export interface ReclaimVerification {
+	/** Serialize non-secret configuration. Credentials, headers, and custom
+	 *  fetch implementations are never included. */
+	export(): string
 	/** 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>
+		 *  the Portal, `VerificationClient.portals`. */
+		create(input: CreateSessionInput): Promise<VerificationSession>
 		/** Add the immutable legacy-compatible TEE context after session
 		 *  creation. Normally use
-		 *  `sessions.create({ teeAttestation: { appSecret } })`; this method
+		 *  `sessions.create({ orgEthPrivateKey })`; this method
 		 *  supports retrying or explicitly orchestrating the two-step flow. */
 		bindTeeNonce(
-			sessionId: string,
-			input: CreateSessionTeeAttestation,
+			reclaimSessionId: string,
+			input: BindSessionTeeNonceInput,
 		): 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 ECIES-encrypted to the org's eth key
-		 *  when `canEncryptResult` is enabled (see `keypair.set`), else plaintext.
-		 *  `events` defaults to all terminal lifecycle events. */
-		register(
-			input: Partial<RegisterCallbackInput> &
-				Pick<RegisterCallbackInput, 'callbackUrl'>,
-		): Promise<CallbackSubscription>
-		list(): Promise<CallbackSubscription[]>
-		remove(subscriptionId: string): Promise<void>
-	}
-	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>
+		get(reclaimSessionId: string): Promise<VerificationSession>
+		listEvents(reclaimSessionId: string): Promise<VerificationEventRecord[]>
 	}
 	results: {
 		/** 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>
+		 *  signed JWS. Pass `orgEthPrivateKey` only when the delivery is
+		 *  encrypted. */
+		decrypt(
+			body: CallbackBody,
+			orgEthPrivateKey?: DecryptionKeyInput,
+		): Promise<Jws>
 		/** Verify a decrypted JWS: JWKS discovery, ES256K signature,
-		 *  `reclaimSessionId`/`aud`, any legacy `exp`, and exact legacy proofs. */
+		 *  `reclaimSessionId`/`aud`, any legacy `exp`, and exact 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
+		 *  `opts.orgEthPrivateKey` when encrypted) and 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.) */
@@ -192,6 +184,8 @@ export interface Reclaim {
 			opts?: ReceiveOptions,
 		): Promise<ReceivedDelivery>
 	}
+	/** `reclaim.flow(session)` — see `ReclaimFlowFactory`. */
+	flow: ReclaimFlowFactory
 }
 
 /** Outcome of `results.receive` — a verified terminal result or a plaintext
@@ -204,11 +198,26 @@ export type ReceivedDelivery =
 		eventData: Record<string, unknown>
 	}
 
-export function createReclaim(config: ReclaimConfig): Reclaim {
+export const ReclaimVerification = Object.freeze({
+	create: createReclaimVerification,
+	import: importReclaimVerification,
+})
+
+function importReclaimVerification(
+	serialized: string,
+	config: ImportReclaimVerificationConfig,
+) {
+	const state = parseReclaimVerificationState(serialized)
+	return createReclaimVerification({ ...config, baseUrl: state.baseUrl })
+}
+
+function createReclaimVerification(
+	config: ReclaimConfig,
+): ReclaimVerification {
 	if(!config?.orgSecret) {
 		throw new Error(
-			'createReclaim requires an org secret — pass '
-				+ 'createReclaim({ orgSecret: <rorg_… org secret> })',
+			'ReclaimVerification.create requires an org secret — pass '
+				+ 'ReclaimVerification.create({ orgSecret: <rorg_… org secret> })',
 		)
 	}
 
@@ -228,101 +237,42 @@ export function createReclaim(config: ReclaimConfig): Reclaim {
 	)
 
 	return {
+		export() {
+			return JSON.stringify({
+				version: 1,
+				baseUrl: client.baseUrl,
+			} satisfies ReclaimVerificationState)
+		},
 		api: client.call.bind(client),
 		sessions: {
-			async create(input) {
-				const { teeAttestation, ...request } = input
-				const body:
-				components['schemas']['CreateVerificationSessionRequest'] = {
-					...request,
-					verificationClientUrl:
-						request.verificationClientUrl ?? `${client.baseUrl}/v/{sessionId}`,
-				}
-				const { data } = await client.call('CreateVerificationSession', {
-					body,
-				})
-				return teeAttestation
-					? bindTeeNonce(data, teeAttestation)
-					: data
-			},
-			async bindTeeNonce(sessionId, input) {
+			create: createSession,
+			async bindTeeNonce(reclaimSessionId, input) {
 				const { data } = await client.call('GetVerificationSession', {
-					params: { sessionId },
+					params: { sessionId: reclaimSessionId },
 				})
 				return bindTeeNonce(data, input)
 			},
-			async get(sessionId) {
+			async get(reclaimSessionId) {
 				const { data } = await client.call('GetVerificationSession', {
-					params: { sessionId },
+					params: { sessionId: reclaimSessionId },
 				})
 				return data
 			},
-			async listEvents(sessionId) {
+			async listEvents(reclaimSessionId) {
 				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 },
+					params: { sessionId: reclaimSessionId },
 				})
-				return data
-			},
-			async list() {
-				const { data } = await client.call('ListCallbackSubscriptions')
 				return data.items
 			},
-			async remove(subscriptionId) {
-				await client.call('DeleteCallbackSubscription', {
-					params: { subscriptionId },
-				})
-			},
-		},
-		keypair: {
-			async set(orgId, input) {
-				// Forward the eth public key as given (hex or JWK); the API stores
-				// the secp256k1 JWK + derived address.
-				const body = {
-					...(input.publicKeyJwk
-						? { publicKeyJwk: input.publicKeyJwk }
-						: { publicKey: input.publicKey }),
-					canEncryptResult: input.canEncryptResult ?? false,
-					...(input.label ? { label: input.label } : {}),
-				} as OrgKeypairRequest
-				const { data } = await client.call('SetOrgKeypair', {
-					params: { orgId },
-					body,
-				})
-				return data
-			},
-			async get(orgId) {
-				try {
-					const { data } = await client.call('GetOrgKeypair', {
-						params: { orgId },
-					})
-					return data
-				} catch(err) {
-					// 404 ⇒ keyless org (plaintext delivery).
-					if(isNotFound(err)) {
-						return undefined
-					}
-
-					throw err
-				}
-			},
 		},
 		results: {
-			async decrypt(body, credential) {
-				return decryptCallback(resolveKey(credential), body)
+			async decrypt(body, orgEthPrivateKey) {
+				return decryptCallback(resolveKey(orgEthPrivateKey), body)
 			},
 			verify(jws, opts) {
 				return verifyResultFull(jws, {
 					fetchImpl: config.fetch,
-					...withRegisteredIssuer(opts),
+					...withBuilderTrust(opts),
 				})
 			},
 			async receive(body, opts) {
@@ -348,28 +298,59 @@ export function createReclaim(config: ReclaimConfig): Reclaim {
 					}
 				}
 
-				const { credential, ...verifyOpts } = opts ?? {}
-				const key = resolveKey(credential)
+				const { orgEthPrivateKey, ...verifyOpts } = opts ?? {}
+				const key = resolveKey(orgEthPrivateKey)
 				const jws = await decryptCallback(key, body)
 				const result = await verifyResultFull(jws, {
 					fetchImpl: config.fetch,
-					...withRegisteredIssuer(verifyOpts),
+					...withBuilderTrust({ ...verifyOpts, orgEthPrivateKey }),
 				})
 				return { kind: 'result', result }
 			},
 		},
+		flow: Object.assign(
+			(session: VerificationSession): SessionFlow => makeSessionFlow(session),
+			{
+				async create(input: CreateSessionInput): Promise<SessionFlow> {
+					return makeSessionFlow(await createSession(input))
+				},
+			},
+		),
+	}
+
+	async function createSession(
+		input: CreateSessionInput,
+	): Promise<VerificationSession> {
+		const {
+			orgEthPrivateKey,
+			teeNonceMode,
+			...request
+		} = input
+		const body:
+		components['schemas']['CreateVerificationSessionRequest'] = {
+			...request,
+		}
+		const { data } = await client.call('CreateVerificationSession', {
+			body,
+		})
+		return orgEthPrivateKey
+			? bindTeeNonce(data, {
+				orgEthPrivateKey,
+				teeNonceMode,
+			})
+			: data
 	}
 
 	async function bindTeeNonce(
 		session: VerificationSession,
-		input: CreateSessionTeeAttestation,
+		input: BindSessionTeeNonceInput,
 	) {
 		const binding = createBuilderTeeBinding({
 			organizationId: session.orgId,
-			organizationVerificationPrivateKey: input.appSecret,
+			organizationVerificationPrivateKey: input.orgEthPrivateKey,
 			sessionId: session.id,
 			timestamp: input.timestamp ?? Date.now().toString(),
-			nonceMode: input.nonceMode,
+			nonceMode: input.teeNonceMode,
 		})
 		const { data } = await client.call('BindVerificationSessionTeeNonce', {
 			params: { sessionId: session.id },
@@ -394,7 +375,7 @@ export function createReclaim(config: ReclaimConfig): Reclaim {
 		providerId: string,
 		providerVersion: string | undefined,
 		_allowedTags: string[] | undefined,
-		proofs: LegacyProof[],
+		proofs: ReclaimRequestProof[],
 	) {
 		let exactVersion = providerVersion
 		if(!exactVersion) {
@@ -422,10 +403,9 @@ export function createReclaim(config: ReclaimConfig): Reclaim {
 		}]
 	}
 
-	function withRegisteredIssuer(opts: VerifyResultFullOptions = {}) {
-		const sessionId = opts.sessionId ?? opts.expectedReclaimSessionId
+	function withBuilderTrust(opts: VerifyResultFullOptions = {}) {
+		const reclaimSessionId = opts.reclaimSessionId
 		const requestedProofValidation = opts.proofValidation
-			?? opts.proofVerification
 		const resolvedOpts: VerifyResultFullOptions = {
 			...opts,
 			proofValidation: {
@@ -433,59 +413,32 @@ export function createReclaim(config: ReclaimConfig): Reclaim {
 				resolveProvider: requestedProofValidation?.resolveProvider
 					?? resolvedProvider,
 			},
-			...(sessionId && !opts.resolveSession && !opts.proofRecipes
+			...(reclaimSessionId && !opts.resolveSession && !opts.proofRecipes
 				? { resolveSession: resolvedSession }
 				: {}),
 		}
 		if(
 			opts.signerPublicKey
-			|| opts.issuer
-			|| opts.trustedIssuer
-			|| opts.issuers?.length
 			|| opts.trustedIssuers?.length
-			|| opts.resolveIssuers
-			|| opts.issuerResolver
-			|| opts.issuersByVerificationClientId
 			|| opts.jwksUrl
-			|| opts.jwksUrlsByVerificationClientId
-			|| opts.resolveJwksUrl
 		) {
 			return resolvedOpts
 		}
 
 		return {
 			...resolvedOpts,
-			resolveIssuers: async(verificationClientId: string) => {
-				const session = await registeredClient(verificationClientId)
-				if(!session) {
-					return []
-				}
-
-				return session.verificationClientIssuer
-					? [session.verificationClientIssuer]
-					: []
-			},
-			resolveJwksUrl: async(verificationClientId: string) => {
-				const session = await registeredClient(verificationClientId)
-				return session?.verificationClientJwksUrl
-			},
+			trustedIssuers: [client.baseUrl],
+			jwksUrl: `${client.baseUrl}/.well-known/jwks.json`,
 		}
+	}
+}
 
-		async function registeredClient(verificationClientId: string) {
-			if(!sessionId) {
-				return undefined
-			}
-
-			const { data: session } = await client.call(
-				'GetVerificationSession',
-				{ params: { sessionId } },
-			)
-			if(session.verificationClientId !== verificationClientId) {
-				return undefined
-			}
-
-			return session
-		}
+function makeSessionFlow(session: VerificationSession): SessionFlow {
+	return {
+		session,
+		async getUrl() {
+			return session.verificationUrl
+		},
 	}
 }
 
@@ -516,7 +469,21 @@ function parseEventData(data: string | undefined): Record<string, unknown> {
 	}
 }
 
-/** True for a `404` thrown by {@link ReclaimClient.call}. */
-function isNotFound(err: unknown): boolean {
-	return isProblemError(err) && err.output.statusCode === 404
+function parseReclaimVerificationState(
+	serialized: string,
+): ReclaimVerificationState {
+	const state: unknown = JSON.parse(serialized)
+	if(
+		!state
+		|| typeof state !== 'object'
+		|| Array.isArray(state)
+		|| !('version' in state)
+		|| state.version !== 1
+		|| !('baseUrl' in state)
+		|| typeof state.baseUrl !== 'string'
+	) {
+		throw new Error('Invalid ReclaimVerification state')
+	}
+
+	return { version: 1, baseUrl: state.baseUrl }
 }