@reclaimprotocol/client 0.1.29 → 0.1.32

package/src/jwks.ts

@@ -1,9 +1,14 @@
 /**
  * JWKS (RFC 7517) discovery for verifying result/proof signatures. Signers
- * (the Verification Client, the Attestor) publish their secp256k1 public keys
+ * (Builder, the Attestor) publish their secp256k1 public keys
  * at `<iss>/.well-known/jwks.json` with `kid` = the signer's ETH address.
  */
-import { b64url, base64urlToBytes, bytesToHex } from './encoding.ts'
+import {
+	b64url,
+	base64urlToBytes,
+	bytesToHex,
+	stripTrailingSlashes,
+} from './encoding.ts'
 import { addressFromUncompressedPubkey, secp } from './secp.ts'
 
 export interface Jwk {
@@ -17,10 +22,6 @@ export interface Jwk {
 	key_ops?: string[]
 	/** Restricts how Builder consumers may use this key. */
 	'x-reclaim-purpose'?: 'verification-result' | 'attestor-proof'
-	/** Verification Client that owns a result-signing key. */
-	'x-reclaim-verification-client-id'?: string
-	/** Verification Clients that share a built-in result-signing key. */
-	'x-reclaim-verification-client-ids'?: string[]
 	/** Attestor proofs use EIP-191 rather than JOSE ES256K. */
 	'x-reclaim-signature-scheme'?: 'EIP-191'
 }
@@ -29,21 +30,18 @@ export interface ReclaimJwks {
 	keys: Jwk[]
 	/** Trusted EIP-191 attestor signer addresses (public-key hashes). */
 	'x-reclaim-attestors'?: string[]
+	/** Trusted sha256 digests for attestor Confidential Space images. */
+	'x-reclaim-attestor-image-digests'?: string[]
 }
 
 /**
- * Build the JWK set for an ES256K signing key (the Verification Client's
+ * Build the JWK set for an ES256K signing key (Builder's managed
  * result-signing key). `kid` is the key's ETH address; `x`/`y` are the
  * uncompressed public-key coordinates. Empty set when no key is configured.
  */
 export function jwksFromPrivateKey(
 	privateKeyHex?: string,
-	metadata: Pick<
-		Jwk,
-		'x-reclaim-purpose'
-		| 'x-reclaim-verification-client-id'
-		| 'x-reclaim-verification-client-ids'
-	> = {},
+	metadata: Pick<Jwk, 'x-reclaim-purpose'> = {},
 ): { keys: Jwk[] } {
 	if(!privateKeyHex) {
 		return { keys: [] }
@@ -76,7 +74,7 @@ export async function fetchJwks(
 	iss: string,
 	fetchImpl: typeof fetch = fetch,
 ): Promise<Jwk[]> {
-	const base = iss.replace(/\/+$/, '')
+	const base = stripTrailingSlashes(iss)
 	return fetchJwksUrl(`${base}/.well-known/jwks.json`, fetchImpl)
 }
 
@@ -94,6 +92,7 @@ export async function fetchReclaimJwks(
 	url: string,
 	fetchImpl: typeof fetch = fetch,
 ): Promise<ReclaimJwks> {
+	assertSecureJwksUrl(url)
 	const res = await fetchImpl(url)
 	if(!res.ok) {
 		throw new Error(`JWKS fetch failed for ${url}: HTTP ${res.status}`)
@@ -105,6 +104,9 @@ export async function fetchReclaimJwks(
 		'x-reclaim-attestors': validateAttestorAddresses(
 			body['x-reclaim-attestors'] ?? [],
 		),
+		'x-reclaim-attestor-image-digests': validateAttestorImageDigests(
+			body['x-reclaim-attestor-image-digests'] ?? [],
+		),
 	}
 }
 
@@ -114,16 +116,20 @@ export function selectKey(keys: Jwk[], kid: string): Jwk | undefined {
 	return keys.find((k) => (k.kid ?? '').toLowerCase() === want)
 }
 
-/** Select a result key and enforce its Verification Client ownership. */
+/** Select Builder's result-signing key and validate its JOSE metadata. */
 export function selectVerificationResultKey(
 	keys: Jwk[],
 	kid: string,
-	verificationClientId: string,
 ): Jwk | undefined {
 	return keys.find((key) => (
 		(key.kid ?? '').toLowerCase() === kid.toLowerCase()
+		&& key.kty === 'EC'
+		&& key.crv === 'secp256k1'
+		&& (!key.alg || key.alg === 'ES256K')
+		&& (!key.use || key.use === 'sig')
+		&& (!key.key_ops || key.key_ops.includes('verify'))
 		&& key['x-reclaim-purpose'] !== 'attestor-proof'
-		&& belongsToVerificationClient(key, verificationClientId)
+		&& jwkMatchesKid(key)
 	))
 }
 
@@ -167,6 +173,18 @@ export function validateAttestorAddresses(addresses: string[]): string[] {
 	}))]
 }
 
+/** Validate and normalize sha256 image digests from a JWKS trust extension. */
+export function validateAttestorImageDigests(digests: string[]): string[] {
+	return [...new Set(digests.map((digest) => {
+		const normalized = digest.trim().toLowerCase()
+		if(!/^sha256:[0-9a-f]{64}$/.test(normalized)) {
+			throw new Error('invalid attestor image digest in JWKS trust registry')
+		}
+
+		return normalized
+	}))]
+}
+
 /**
  * Reconstruct the uncompressed secp256k1 public key (`0x04` + X + Y) from an
  * EC JWK's base64url `x`/`y` coordinates, for signature verification.
@@ -185,23 +203,27 @@ export function jwkToUncompressedPublicKey(jwk: Jwk): string {
 	return '0x' + bytesToHex(out)
 }
 
-function belongsToVerificationClient(
-	key: Jwk,
-	verificationClientId: string,
-): boolean {
-	const one = key['x-reclaim-verification-client-id']
-	const many = key['x-reclaim-verification-client-ids']
-	if(one) {
-		return one === verificationClientId
+function jwkMatchesKid(key: Jwk): boolean {
+	try {
+		const address = addressFromUncompressedPubkey(
+			hexPublicKeyBytes(jwkToUncompressedPublicKey(key)),
+		)
+		return address.toLowerCase() === key.kid?.toLowerCase()
+	} catch{
+		return false
 	}
+}
 
-	if(many) {
-		return many.includes(verificationClientId)
+function assertSecureJwksUrl(value: string) {
+	const url = new URL(value)
+	if(url.protocol === 'https:' || (
+		url.protocol === 'http:'
+		&& ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)
+	)) {
+		return
 	}
 
-	// Untagged self-hosted JWKS remain compatible because their URL is itself
-	// selected from the registered Verification Client record.
-	return key['x-reclaim-purpose'] !== 'verification-result'
+	throw new Error('JWKS URL must use HTTPS except on loopback')
 }
 
 function hexPublicKeyBytes(value: string) {

package/src/launch/destination.ts

@@ -0,0 +1,111 @@
+/**
+ * Rebuilds the real, openable destination URL for a parsed flow.
+ *
+ * Since migration `20260917130000000.share-routes-uris.sql`, every built-in
+ * client's registered uri is itself a real, openable Builder page (`/share/
+ * {name}` — see `builtin-clients.ts` and `SharePage.tsx`), including
+ * `portals`, which used to be an attribution-only label Builder served
+ * nothing at. That does NOT mean this file's job shrinks to "pass every
+ * target through unchanged": which side rewrites is decided per target by
+ * who is able to honour an override and who has to keep working against a
+ * pre-migration deployment, not by whether Builder happens to have a page
+ * there today.
+ *
+ *   - `builder`: registered uri (`/v/{sessionId}` pre-migration, `/share/
+ *     builder` post-migration) is always real and there is no override to
+ *     express — Builder's own route owns any redirecting (`/share/builder`
+ *     302s to `/v/{sessionId}` server-side). This file never rewrites it.
+ *   - `portals`: this file keeps rewriting to `options.portalUrl ??
+ *     DEFAULT_PORTAL_URL`, unconditionally, even though `/share/portals` now
+ *     redirects there too. Two reasons it can't defer to Builder's hop: (1) a
+ *     pre-migration `/portals` uri is still a bare label Builder serves
+ *     nothing at, so passing it through would 404; (2) `options.portalUrl` is
+ *     an override Builder's fixed server-side redirect has no way to honour.
+ *     `DEFAULT_PORTAL_URL` here and `SharePage.tsx`'s redirect default are
+ *     deliberately kept identical, so the common (no-override) case reaches
+ *     the same destination either hop — Builder's `/share/portals` hop is
+ *     what makes a *pasted* link (opened without this SDK) still work.
+ *   - `verifier-app`: registered uri (`/s` or `/share/verifier-app`, both
+ *     real) is the share link itself, so this file passes it through unless
+ *     `options.appLinkBaseUrl` overrides it — same shape of reasoning as
+ *     `portals`, just already correct before this migration.
+ *   - `reclaim-browser-extension`: has no destination URL at all — the
+ *     mechanism is a `postMessage` handoff, not a navigation (see
+ *     ./extension.ts) — so `getUrl()` on that target, like an unrecognised
+ *     path, returns the original `verificationUrl` unchanged regardless of
+ *     which shape registered it.
+ */
+import { stripTrailingSlashes } from '../encoding.ts'
+import type { ParsedFlowUrl, VerificationTarget } from './target.ts'
+
+export interface DestinationOptions {
+	portalUrl?: string
+	appLinkBaseUrl?: string
+}
+
+export const DEFAULT_PORTAL_URL = 'https://portal.reclaimprotocol.org'
+/** The legacy share page. No longer a default — `verifier-app` sessions now
+ *  carry a real Builder share URL — but kept as the value a deployment still
+ *  pointing at `share.reclaimprotocol.org` would pass as `appLinkBaseUrl`. */
+export const LEGACY_APP_LINK_BASE_URL
+	= 'https://share.reclaimprotocol.org/verify'
+
+/** Copies `api`/`sessionId`/`diag` onto `base`, preserving any query
+ *  parameters `base` already carries (e.g. an App Clip's `?p=`). */
+export function appendSessionQuery(
+	base: string,
+	parsed: Pick<ParsedFlowUrl, 'sessionId' | 'diag'>,
+): string {
+	const url = new URL(base)
+	url.searchParams.set('api', '2')
+	if(parsed.sessionId) {
+		url.searchParams.set('sessionId', parsed.sessionId)
+	}
+
+	if(parsed.diag) {
+		url.searchParams.set('diag', '1')
+	}
+
+	return url.toString()
+}
+
+function withoutTrailingSlash(value: string): string {
+	return stripTrailingSlashes(value)
+}
+
+export function resolveDestinationUrl(
+	target: VerificationTarget | undefined,
+	parsed: ParsedFlowUrl,
+	options: DestinationOptions,
+): string {
+	switch (target) {
+		case 'builder':
+			return parsed.url.toString()
+		case 'portals': {
+			// Always rewritten here, even now that `/share/portals` also
+			// redirects server-side — see the file header for why this file,
+			// not Builder's route, has to own it.
+			const base = options.portalUrl ?? DEFAULT_PORTAL_URL
+			return appendSessionQuery(`${withoutTrailingSlash(base)}/verify`, parsed)
+		}
+
+		case 'verifier-app': {
+			// The registered uri for `verifier-app` is Builder's own share page
+			// (`GET /s`), a real openable URL — so the verificationUrl already
+			// IS the share link, and rewriting it onto another origin would
+			// throw away the app-link association that makes a scan open the
+			// app (`build.reclaimprotocol.org` is what the app's entitlements
+			// and assetlinks now claim).
+			//
+			// `appLinkBaseUrl` stays as the override for a deployment that
+			// hosts its own share page, or one still pointing at the legacy
+			// `share.reclaimprotocol.org/verify`.
+			const base = options.appLinkBaseUrl
+			return base ? appendSessionQuery(base, parsed) : parsed.url.toString()
+		}
+
+		case 'reclaim-browser-extension':
+		case undefined:
+			return parsed.url.toString()
+	}
+}

package/src/launch/device.ts

@@ -0,0 +1,242 @@
+/**
+ * Device detection, ported from the reference JS SDK's `src/utils/device.ts`
+ * (`getDeviceType`/`getMobileDeviceType`). Two differences from that source,
+ * both required by the launch-API plan:
+ *
+ *  - Every signal is read through a `LaunchEnvironment` (see ./environment.ts)
+ *    instead of module-scope `navigator`/`window`, so this is testable with
+ *    plain fakes and safe to import under SSR.
+ *  - The result carries a `confidence` ('high' | 'low') instead of silently
+ *    committing to a guess, so a caller can render a chooser instead of
+ *    assuming. `navigator.userAgentData` (Chromium's low-entropy User-Agent
+ *    Client Hints) is read as an extra signal where present — it is
+ *    Chromium-only and absent on every iOS browser, so it augments the
+ *    heuristics below rather than replacing them, and `getHighEntropyValues`
+ *    is never called (it's async and equally absent on WebKit).
+ *
+ * The mobile-vs-desktop scoring mirrors the reference SDK's weights exactly
+ * (`CONFIDENCE_THRESHOLD = 3`); the iOS-vs-Android cascade mirrors its rule
+ * order, including the iPad-reporting-as-macOS special case.
+ */
+import type { LaunchEnvironment, LaunchWindow } from './environment.ts'
+
+export type DeviceKind = 'desktop' | 'ios' | 'android'
+export type DetectionConfidence = 'high' | 'low'
+
+export interface DeviceDetection {
+	device: DeviceKind
+	confidence: DetectionConfidence
+}
+
+/** Matches the reference SDK's mobile/desktop scoring cutoff. */
+const MOBILE_SCORE_THRESHOLD = 3
+/** A mobile/desktop score this close to the cutoff is a coin flip, not a
+ *  confident read — surfaced as `confidence: 'low'`. */
+const MOBILE_SCORE_MARGIN = 2
+
+function safeMatchMedia(win: LaunchWindow | undefined, query: string): boolean {
+	try {
+		return win?.matchMedia?.(query)?.matches ?? false
+	} catch{
+		return false
+	}
+}
+
+function safeCssSupports(
+	win: LaunchWindow | undefined,
+	property: string,
+	value: string,
+): boolean {
+	try {
+		return win?.CSS?.supports?.(property, value) ?? false
+	} catch{
+		return false
+	}
+}
+
+function safeQuerySelector(env: LaunchEnvironment, selector: string): boolean {
+	try {
+		return !!env.document?.querySelector(selector)
+	} catch{
+		return false
+	}
+}
+
+/** Ported scoring pass. Returns the raw mobile score — positive leans
+ *  mobile, negative leans desktop. */
+function scoreMobile(env: LaunchEnvironment): number {
+	const win = env.window
+	const nav = env.navigator
+	const userAgent = (nav?.userAgent ?? '').toLowerCase()
+
+	if(!win || !nav) {
+		// SSR / no environment: the reference SDK assumes desktop.
+		return -MOBILE_SCORE_THRESHOLD
+	}
+
+	let score = 0
+
+	const screenWidth = win.innerWidth || win.screen?.width || 0
+	const screenHeight = win.innerHeight || win.screen?.height || 0
+	const hasSmallScreen = screenWidth <= 480 || screenHeight <= 480
+	const hasLargeScreen = screenWidth > 1024 && screenHeight > 768
+
+	const hasTouch = 'ontouchstart' in win || (nav.maxTouchPoints ?? 0) > 0
+	const hasPreciseMouse = safeMatchMedia(win, '(pointer: fine)')
+	const canHover = safeMatchMedia(win, '(hover: hover)')
+	const hasMouseAndTouch = hasTouch && hasPreciseMouse
+
+	const isWindowsTouchLaptop = /windows/i.test(userAgent)
+		&& hasPreciseMouse && hasTouch
+
+	if(hasTouch && !hasMouseAndTouch) {
+		score += 2
+	} else if(hasMouseAndTouch) {
+		score += 1
+	}
+
+	if(hasSmallScreen && !isWindowsTouchLaptop) {
+		score += 2
+	}
+
+	const mobileUaPattern = new RegExp(
+		'android|webos|iphone|ipad|ipod|blackberry|iemobile|opera mini|mobile',
+		'i',
+	)
+	const hasMobileUserAgent = mobileUaPattern.test(userAgent)
+	if(hasMobileUserAgent) {
+		score += 3
+	}
+
+	const hasMobileApis = 'orientation' in win
+		|| 'DeviceMotionEvent' in win
+		|| 'DeviceOrientationEvent' in win
+	const isDesktopSafari = /safari/i.test(userAgent)
+		&& !/mobile/i.test(userAgent)
+		&& /mac|intel/i.test(userAgent)
+	const mobileApisImplyMobile = hasMobileApis
+		&& (hasSmallScreen || hasMobileUserAgent)
+		&& !isDesktopSafari
+		&& !isWindowsTouchLaptop
+	if(mobileApisImplyMobile) {
+		score += 2
+	}
+
+	const hasHighDpi = (win.devicePixelRatio ?? 0) > 1.5
+	if(hasHighDpi && hasSmallScreen) {
+		score += 1
+	}
+
+	const hasViewportMeta = safeQuerySelector(env, 'meta[name="viewport"]')
+	if(hasViewportMeta && hasSmallScreen) {
+		score += 1
+	}
+
+	const isPadProInDesktopMode = userAgent.includes('macintosh') && hasTouch
+	if(isPadProInDesktopMode) {
+		score += 2
+	}
+
+	if(hasLargeScreen && hasPreciseMouse) {
+		score -= 3
+	} else if(hasLargeScreen && !hasTouch) {
+		score -= 2
+	}
+
+	if(hasPreciseMouse && canHover) {
+		score -= 2
+	}
+
+	const isWindowsDesktop = /windows/i.test(userAgent) && !hasMobileUserAgent
+	if(isWindowsDesktop) {
+		score -= 3
+	}
+
+	// Chromium's low-entropy UA-CH `mobile` hint: an explicit, high-confidence
+	// signal where present, applied on top of the heuristic score above rather
+	// than replacing it (it's absent on WebKit/Firefox entirely).
+	if(nav.userAgentData?.mobile === true) {
+		score += 2
+	} else if(nav.userAgentData?.mobile === false) {
+		score -= 2
+	}
+
+	return score
+}
+
+interface MobileOsGuess {
+	os: 'ios' | 'android'
+	/** False only for the reference SDK's final fallback: no rule matched
+	 *  either OS, so it defaulted to Android because that's the more common
+	 *  global install base — a guess, not a read. */
+	explicit: boolean
+}
+
+/** Ported iOS/Android cascade. Only called once `scoreMobile` has decided the
+ *  device is mobile. */
+function guessMobileOs(env: LaunchEnvironment): MobileOsGuess {
+	const win = env.window
+	const nav = env.navigator
+	const userAgent = nav?.userAgent ?? ''
+	const hasTouch = !!win
+		&& ('ontouchstart' in win || (nav?.maxTouchPoints ?? 0) > 0)
+
+	if(/iPad|iPhone|iPod/i.test(userAgent)) {
+		return { os: 'ios', explicit: true }
+	}
+
+	// iPad Pro reports as a Mac (both in the UA string and in UA-CH's
+	// `platform` hint) once it gains a keyboard/trackpad, but keeps touch.
+	const isMacWithTouch = /Macintosh|MacIntel/i.test(userAgent) && hasTouch
+	const isMacOsWithTouch = nav?.userAgentData?.platform === 'macOS' && hasTouch
+	if(isMacWithTouch || isMacOsWithTouch) {
+		return { os: 'ios', explicit: true }
+	}
+
+	const hasIosPermissionApi = typeof win?.DeviceMotionEvent?.requestPermission
+		=== 'function'
+	const hasIosTouchCallout = safeCssSupports(
+		win, '-webkit-touch-callout', 'none',
+	)
+	if(hasIosPermissionApi || hasIosTouchCallout) {
+		return { os: 'ios', explicit: true }
+	}
+
+	const isIosWebKit = /WebKit/i.test(userAgent)
+		&& !/Chrome|CriOS|Android/i.test(userAgent)
+		&& !/Macintosh|MacIntel/i.test(userAgent)
+	if(isIosWebKit) {
+		return { os: 'ios', explicit: true }
+	}
+
+	if(/Android/i.test(userAgent)) {
+		return { os: 'android', explicit: true }
+	}
+
+	if(nav?.userAgentData?.platform === 'Android') {
+		return { os: 'android', explicit: true }
+	}
+
+	// Final fallback: no rule matched. Android is the more common global
+	// install base, but this is a guess — callers see `confidence: 'low'`.
+	return { os: 'android', explicit: false }
+}
+
+/** Resolves the device this flow is running on, with a confidence a caller
+ *  can act on instead of a silent guess. */
+export function resolveDevice(env: LaunchEnvironment): DeviceDetection {
+	const score = scoreMobile(env)
+	const isMobile = score >= MOBILE_SCORE_THRESHOLD
+	const borderline
+		= Math.abs(score - MOBILE_SCORE_THRESHOLD) < MOBILE_SCORE_MARGIN
+
+	if(!isMobile) {
+		return { device: 'desktop', confidence: borderline ? 'low' : 'high' }
+	}
+
+	const guess = guessMobileOs(env)
+	return {
+		device: guess.os,
+		confidence: borderline || !guess.explicit ? 'low' : 'high',
+	}
+}