@reclaimprotocol/client 0.1.29 → 0.1.32

package/src/launch/flow.ts

@@ -0,0 +1,369 @@
+/**
+ * `ReclaimFlow` — the public entry point. One constructor
+ * (`ReclaimFlow.from`), per the launch-API plan: no
+ * `fromSession`/`fromVerificationUrl`/`fromDescriptor` family.
+ *
+ * `resolveTarget()`/`launch()` decide the mechanism from the URL's client
+ * (see ./target.ts) and the device (see ./device.ts); `launch()` runs it
+ * (./portal.ts, ./mobile.ts, ./extension.ts, ./modal.ts) and hands back a
+ * `FlowHandle` that tears down whatever UI it created.
+ */
+import type { VerificationSession } from '../types/openapi.ts'
+import { appendSessionQuery, resolveDestinationUrl } from './destination.ts'
+import type { DetectionConfidence, DeviceKind } from './device.ts'
+import { resolveDevice } from './device.ts'
+import type {
+	LaunchElement,
+	LaunchEnvironment,
+	LaunchWindowHandle
+} from './environment.ts'
+import { defaultEnvironment } from './environment.ts'
+import type { ReclaimFlowUnavailableReason } from './errors.ts'
+import { ReclaimFlowUnavailableError } from './errors.ts'
+import {
+	probeExtension,
+	sendExtensionCancelVerification,
+	sendExtensionStartVerification,
+} from './extension.ts'
+import {
+	buildAndroidMarketIntentUrl,
+	redirectToAndroid,
+	redirectToAppClip,
+	redirectToIosDeepLink,
+} from './mobile.ts'
+import { showQrModal } from './modal.ts'
+import type { FlowOptions } from './options.ts'
+import {
+	DEFAULT_APP_CLIP_URL,
+	DEFAULT_IOS_APP_DOWNLOAD_URL,
+	DEFAULT_IOS_DEEP_LINK_BASE_URL,
+	resolveAndroidAppDownloadUrl,
+	resolveAndroidDeepLinkPackage,
+	resolveCanUseDeferredDeepLinksFlow,
+} from './options.ts'
+import { embedPortalIframe, openPortalTab } from './portal.ts'
+import type { ParsedFlowUrl, VerificationTarget } from './target.ts'
+import { parseFlowUrl } from './target.ts'
+
+export type { FlowOptions } from './options.ts'
+export type { VerificationTarget } from './target.ts'
+export type { DetectionConfidence, DeviceKind } from './device.ts'
+export {
+	ReclaimFlowUnavailableError,
+	isReclaimFlowUnavailableError,
+} from './errors.ts'
+export type { ReclaimFlowUnavailableReason } from './errors.ts'
+
+/** A `verificationUrl` string, or any object carrying one — a full
+ *  `VerificationSession` satisfies it. */
+export type FlowInput =
+	| string
+	| VerificationSession
+	| { verificationUrl: string }
+
+export type LaunchMechanism =
+	| 'new-tab'
+	| 'iframe'
+	| 'extension-handoff'
+	| 'qr-modal'
+	| 'ios-app-clip'
+	| 'ios-deep-link'
+	| 'android-deep-link'
+	| 'unavailable'
+
+/** Which client and mechanism a flow resolves to on this device. Read-only —
+ *  `resolveTarget()` changes nothing (see the plan's "Targets" section). */
+export interface ResolvedTarget {
+	/** The client the URL names, or `undefined` for an unrecognised path
+	 *  (degrades to `mechanism: 'new-tab'`). */
+	client: VerificationTarget | undefined
+	device: DeviceKind
+	/** Exposed so a caller can render a chooser instead of trusting a
+	 *  borderline device-detection guess — see ./device.ts. */
+	confidence: DetectionConfidence
+	mechanism: LaunchMechanism
+	/** `false` only for an extension-bound session this device can't run
+	 *  (see `reason`); `launch()` rejects rather than substituting another
+	 *  mechanism. */
+	available: boolean
+	reason?: ReclaimFlowUnavailableReason
+}
+
+export interface FlowHandle {
+	/** Tears down the UI this launch created (tab/iframe/modal, or the
+	 *  extension's in-progress verification). Does not cancel the session —
+	 *  the Builder session outcome still arrives at the consumer's backend
+	 *  callback. */
+	close(): void
+	readonly target: ResolvedTarget
+	readonly iframe?: LaunchElement
+	readonly tab?: LaunchWindowHandle | null
+}
+
+function inputVerificationUrl(input: FlowInput): string {
+	const verificationUrl = typeof input === 'string'
+		? input
+		: input.verificationUrl
+	if(!verificationUrl) {
+		throw new Error(
+			'ReclaimFlow.from() input must be a verificationUrl string, or '
+				+ 'an object carrying one',
+		)
+	}
+
+	return verificationUrl
+}
+
+export class ReclaimFlow {
+	readonly #input: FlowInput
+	#options: FlowOptions
+	#env: LaunchEnvironment
+	#parsed: ParsedFlowUrl | undefined
+
+	private constructor(input: FlowInput, options: FlowOptions) {
+		this.#input = input
+		this.#options = options
+		this.#env = options.environment ?? defaultEnvironment()
+	}
+
+	/** The only constructor — no `fromSession`/`fromVerificationUrl`/
+	 *  `fromDescriptor` family. */
+	static from(input: FlowInput, options: FlowOptions = {}): ReclaimFlow {
+		return new ReclaimFlow(input, options)
+	}
+
+	/** The `session`/object this flow was built from, or `undefined` when
+	 *  `from()` was given a bare `verificationUrl` string. */
+	get session(): VerificationSession | { verificationUrl: string } | undefined {
+		return typeof this.#input === 'string' ? undefined : this.#input
+	}
+
+	/** Merges `options` for later `getUrl()`/`resolveTarget()`/`launch()`
+	 *  calls. Chainable. */
+	setOptions(options: FlowOptions): this {
+		this.#options = { ...this.#options, ...options }
+		if(options.environment) {
+			this.#env = options.environment
+		}
+
+		// `verificationClientId` feeds target resolution (./target.ts), so a
+		// change invalidates the cached parse.
+		this.#parsed = undefined
+		return this
+	}
+
+	/** Resolves the target and returns the claimant URL, without navigating. */
+	async getUrl(): Promise<string> {
+		const parsed = this.#parse()
+		return resolveDestinationUrl(parsed.target, parsed, this.#options)
+	}
+
+	/** Which client and mechanism this flow will use on this device. A read:
+	 *  reports the mechanism and changes nothing (the one exception is a
+	 *  short-lived `postMessage` probe for an extension-bound session, which
+	 *  navigates nothing and shows no UI). */
+	async resolveTarget(): Promise<ResolvedTarget> {
+		return this.#resolve()
+	}
+
+	/** Opens it. Rejects with `ReclaimFlowUnavailableError` for an
+	 *  extension-bound session this device can't run, rather than silently
+	 *  falling back to another mechanism. */
+	async launch(): Promise<FlowHandle> {
+		const resolved = await this.#resolve()
+		if(!resolved.available) {
+			throw new ReclaimFlowUnavailableError(
+				resolved.reason ?? 'extension-not-found',
+			)
+		}
+
+		return this.#execute(resolved)
+	}
+
+	#parse(): ParsedFlowUrl {
+		this.#parsed ??= parseFlowUrl(
+			inputVerificationUrl(this.#input),
+			this.#options.verificationClientId,
+		)
+		return this.#parsed
+	}
+
+	async #resolve(): Promise<ResolvedTarget> {
+		const parsed = this.#parse()
+		const { device, confidence } = resolveDevice(this.#env)
+		const client = parsed.target
+
+		if(client === 'reclaim-browser-extension') {
+			return this.#resolveExtensionTarget(client, device, confidence)
+		}
+
+		if(client === 'verifier-app') {
+			let mechanism: LaunchMechanism
+			if(device === 'desktop') {
+				mechanism = 'qr-modal'
+			} else if(device === 'ios') {
+				mechanism = this.#options.useAppClip ? 'ios-app-clip' : 'ios-deep-link'
+			} else {
+				mechanism = 'android-deep-link'
+			}
+
+			return { client, device, confidence, mechanism, available: true }
+		}
+
+		// `builder` | `portals` | undefined (unrecognised path — degrades to a
+		// tab). iframe embedding is desktop-only, per the plan's mechanism
+		// table — mobile always gets a new tab even with `options.target` set.
+		const wantsIframe = !!client && device === 'desktop'
+			&& !!this.#options.target
+		const mechanism: LaunchMechanism = wantsIframe ? 'iframe' : 'new-tab'
+		return { client, device, confidence, mechanism, available: true }
+	}
+
+	async #resolveExtensionTarget(
+		client: VerificationTarget,
+		device: DeviceKind,
+		confidence: DetectionConfidence,
+	): Promise<ResolvedTarget> {
+		const unavailable = (
+			reason: ReclaimFlowUnavailableReason,
+		): ResolvedTarget => ({
+			client,
+			device,
+			confidence,
+			mechanism: 'unavailable',
+			available: false,
+			reason,
+		})
+
+		if(device !== 'desktop') {
+			return unavailable('mobile-device')
+		}
+
+		if(this.#options.useBrowserExtension === false) {
+			return unavailable('extension-disabled')
+		}
+
+		const found = await probeExtension(this.#env, this.#options)
+		if(!found) {
+			return unavailable('extension-not-found')
+		}
+
+		return {
+			client,
+			device,
+			confidence,
+			mechanism: 'extension-handoff',
+			available: true,
+		}
+	}
+
+	#execute(resolved: ResolvedTarget): FlowHandle {
+		const parsed = this.#parse()
+
+		switch (resolved.mechanism) {
+			case 'extension-handoff': {
+				const handoff = {
+					sessionId: parsed.sessionId ?? '',
+					diag: parsed.diag,
+					extensionID: this.#options.extensionID,
+				}
+				sendExtensionStartVerification(this.#env, handoff)
+				return {
+					target: resolved,
+					close: () => sendExtensionCancelVerification(this.#env, handoff),
+				}
+			}
+
+			case 'qr-modal': {
+				const url = resolveDestinationUrl(parsed.target, parsed, this.#options)
+				const modal = showQrModal(this.#env, url, {
+					...this.#options.modalOptions,
+					renderQr: this.#options.renderQr,
+				})
+				return { target: resolved, close: () => modal.close() }
+			}
+
+			case 'ios-app-clip': {
+				const appClipUrl = appendSessionQuery(
+					this.#options.appClipUrl ?? DEFAULT_APP_CLIP_URL,
+					parsed,
+				)
+				const handle = redirectToAppClip(this.#env, appClipUrl)
+				return { target: resolved, close: () => handle.close() }
+			}
+
+			case 'ios-deep-link': {
+				const deepLinkUrl = appendSessionQuery(
+					this.#options.iosDeepLinkBaseUrl ?? DEFAULT_IOS_DEEP_LINK_BASE_URL,
+					parsed,
+				)
+				const storeUrl = this.#options.iosAppDownloadUrl
+					?? DEFAULT_IOS_APP_DOWNLOAD_URL
+				const handle = redirectToIosDeepLink(
+					this.#env, { deepLinkUrl, storeUrl },
+				)
+				return { target: resolved, close: () => handle.close() }
+			}
+
+			case 'android-deep-link': {
+				const shareUrl = resolveDestinationUrl(
+					parsed.target, parsed, this.#options,
+				)
+				const deepLinkUrl = appendSessionQuery(
+					this.#options.iosDeepLinkBaseUrl ?? DEFAULT_IOS_DEEP_LINK_BASE_URL,
+					parsed,
+				)
+				const marketIntentUrl = buildAndroidMarketIntentUrl(
+					shareUrl,
+					resolveAndroidDeepLinkPackage(this.#options),
+				)
+				const handle = redirectToAndroid(this.#env, {
+					deepLinkUrl,
+					marketIntentUrl,
+					shareUrl,
+					canUseDeferredDeepLinksFlow: resolveCanUseDeferredDeepLinksFlow(
+						this.#options, 'android',
+					),
+				})
+				return { target: resolved, close: () => handle.close() }
+			}
+
+			case 'iframe': {
+				const url = resolveDestinationUrl(parsed.target, parsed, this.#options)
+				const container = this.#options.target
+				if(!container) {
+				// `#resolve()` only picks 'iframe' when `options.target` is set;
+				// kept total rather than asserting, in case options changed
+				// between `resolveTarget()` and `launch()`.
+					return this.#openNewTab(resolved, url)
+				}
+
+				const handle = embedPortalIframe(this.#env, url, container)
+				return {
+					target: resolved, iframe: handle.iframe, close: () => handle.close(),
+				}
+			}
+
+			case 'new-tab': {
+				const url = resolveDestinationUrl(parsed.target, parsed, this.#options)
+				return this.#openNewTab(resolved, url)
+			}
+
+			case 'unavailable':
+				// `launch()` already rejected before calling `#execute()`.
+				throw new ReclaimFlowUnavailableError(
+					resolved.reason ?? 'extension-not-found',
+				)
+		}
+	}
+
+	#openNewTab(resolved: ResolvedTarget, url: string): FlowHandle {
+		const handle = openPortalTab(this.#env, url, this.#options.preOpenedTab)
+		return { target: resolved, tab: handle.tab, close: () => handle.close() }
+	}
+}
+
+// Re-exported so a consumer building `androidAppDownloadUrl`/
+// `androidDeepLinkPackage` defaults for display (e.g. an install-link
+// banner) doesn't have to duplicate them.
+export { resolveAndroidAppDownloadUrl, resolveAndroidDeepLinkPackage }

package/src/launch/index.ts

@@ -0,0 +1,42 @@
+/**
+ * `@reclaimprotocol/client/launch` — a browser-only, credential-free
+ * launcher. Given a Builder `verificationUrl`, `ReclaimFlow` works out how
+ * to open it on this device (browser extension handoff, native app deep
+ * link/App Clip, portal/builder tab or iframe, or a QR modal) and hands
+ * back a `FlowHandle` to tear the UI down again.
+ *
+ * See `devtools/plans/client-launch-api.md` for the design this implements.
+ */
+export {
+	ReclaimFlow,
+	ReclaimFlowUnavailableError,
+	isReclaimFlowUnavailableError,
+} from './flow.ts'
+export type {
+	DetectionConfidence,
+	DeviceKind,
+	FlowHandle,
+	FlowInput,
+	FlowOptions,
+	LaunchMechanism,
+	ReclaimFlowUnavailableReason,
+	ResolvedTarget,
+	VerificationTarget,
+} from './flow.ts'
+export { showQrModal } from './modal.ts'
+export type { ModalHandle, ModalOptions } from './modal.ts'
+export type { RenderQr } from './qr.ts'
+export { defaultEnvironment } from './environment.ts'
+export type {
+	LaunchClipboard,
+	LaunchContainer,
+	LaunchDocument,
+	LaunchElement,
+	LaunchEnvironment,
+	LaunchMessageEvent,
+	LaunchNavigator,
+	LaunchStyleDeclaration,
+	LaunchUserAgentData,
+	LaunchWindow,
+	LaunchWindowHandle,
+} from './environment.ts'

package/src/launch/mobile.ts

@@ -0,0 +1,184 @@
+/**
+ * The `verifier-app` target's mobile mechanisms, ported from the reference
+ * JS SDK's `redirectToAppClip`/`redirectToiOSApp`/`redirectToInstantApp`
+ * (`Reclaim.ts` ~1663/~1752/~1773). Per the launch-API plan's mechanism
+ * table (not the reference SDK's own branching, which folds iOS into an
+ * Android-shaped fallback in one corner case the plan doesn't carry over):
+ *
+ *  - iOS is exactly two mechanisms: `useAppClip` picks the App Clip, its
+ *    absence picks the `reclaimverifier://` deep link with a 3s App Store
+ *    fallback. Both redirect the current tab — there's no popup on a phone.
+ *  - Android mirrors it: clipboard write, top-level `reclaimverifier://`
+ *    navigation, Play Store market-intent fallback if the tab never
+ *    backgrounds. Unless `canUseDeferredDeepLinksFlow` is false, in which
+ *    case it's a plain redirect to the share URL.
+ *
+ * All delays go through `env.setTimeout`/`env.clearTimeout` (see
+ * ./environment.ts), so tests exercise the fallback paths with a fake
+ * scheduler instead of waiting on real 1.5s/3s timers.
+ */
+import type { LaunchEnvironment } from './environment.ts'
+
+/** How long to wait for the OS to hand off to the app before deciding it is
+ *  not installed and sending the claimant to the Play Store. The tab
+ *  backgrounding is the only signal a page gets, and it arrives quickly when
+ *  it arrives at all. */
+const ANDROID_STORE_FALLBACK_MS = 1500
+
+export interface MobileRedirectHandle {
+	close(): void
+}
+
+function writeClipboardBestEffort(env: LaunchEnvironment, text: string): void {
+	env.navigator?.clipboard?.writeText(text)?.catch(() => {
+		// Clipboard access can be denied (permissions, insecure context); the
+		// deep link/store redirect below is the fallback either way.
+	})
+}
+
+/** iOS, `useAppClip: true`. A one-way redirect — nothing to probe or fall
+ *  back from, so `close()` is a no-op. */
+export function redirectToAppClip(
+	env: LaunchEnvironment,
+	appClipUrl: string,
+): MobileRedirectHandle {
+	env.navigate(appClipUrl)
+	return { close() {} }
+}
+
+/** iOS, `useAppClip: false` (the default): try the custom-scheme deep link,
+ *  fall back to the App Store after 3s if the tab never backgrounded (i.e.
+ *  the OS never handed off to the app). */
+export function redirectToIosDeepLink(
+	env: LaunchEnvironment,
+	options: { deepLinkUrl: string, storeUrl: string },
+): MobileRedirectHandle {
+	writeClipboardBestEffort(env, options.deepLinkUrl)
+
+	let appOpened = false
+	const onVisibilityChange = () => {
+		if(env.document?.hidden) {
+			appOpened = true
+		}
+	}
+
+	env.document?.addEventListener(
+		'visibilitychange', onVisibilityChange, { once: true },
+	)
+	env.navigate(options.deepLinkUrl)
+
+	const timeoutHandle = env.setTimeout(() => {
+		env.document?.removeEventListener('visibilitychange', onVisibilityChange)
+		if(!appOpened) {
+			env.navigate(options.storeUrl)
+		}
+	}, 3000)
+
+	return {
+		close() {
+			env.document?.removeEventListener('visibilitychange', onVisibilityChange)
+			env.clearTimeout(timeoutHandle)
+		},
+	}
+}
+
+/** Android. `canUseDeferredDeepLinksFlow` (default `true`) gates the
+ *  clipboard-write + hidden-iframe probe + Play Store market-intent
+ *  fallback; `false` is a plain redirect to the share URL. */
+export function redirectToAndroid(
+	env: LaunchEnvironment,
+	options: {
+		deepLinkUrl: string
+		marketIntentUrl: string
+		shareUrl: string
+		canUseDeferredDeepLinksFlow: boolean
+	},
+): MobileRedirectHandle {
+	if(!options.canUseDeferredDeepLinksFlow) {
+		env.navigate(options.shareUrl)
+		return { close() {} }
+	}
+
+	writeClipboardBestEffort(env, options.shareUrl)
+
+	// Navigate the tab straight at the custom scheme, rather than probing it
+	// from a hidden iframe first. Chrome on Android has blocked custom-scheme
+	// navigation from an iframe for years — it fails silently, so the probe
+	// never opened the app and the Play Store fallback did all the work, even
+	// for someone who already had the app installed. A top-level navigation
+	// is the only thing the OS acts on, and it is what the iOS branch above
+	// has always done.
+	let appOpened = false
+	const onVisibilityChange = () => {
+		if(env.document?.hidden) {
+			appOpened = true
+		}
+	}
+
+	env.document?.addEventListener(
+		'visibilitychange', onVisibilityChange, { once: true },
+	)
+	env.navigate(options.deepLinkUrl)
+
+	// Still here, still visible: the scheme resolved to nothing, so the app is
+	// not installed. Send them to the Play Store, carrying the referrer that
+	// survives the install.
+	const timeoutHandle = env.setTimeout(() => {
+		env.document?.removeEventListener('visibilitychange', onVisibilityChange)
+		if(!appOpened) {
+			env.navigate(options.marketIntentUrl)
+		}
+	}, ANDROID_STORE_FALLBACK_MS)
+
+	return {
+		close() {
+			env.document?.removeEventListener('visibilitychange', onVisibilityChange)
+			env.clearTimeout(timeoutHandle)
+		},
+	}
+}
+
+/** Builds the Play Store market-intent fallback URL, ported from
+ *  `redirectToInstantApp`'s `deepLink` construction.
+ *
+ *  The legacy JS SDK put the verification URL in `url=`. Play never read it —
+ *  Play forwards exactly one parameter to the installed app, `referrer`, via
+ *  the Install Referrer API, so `url=` has always been inert and only the
+ *  clipboard carried a deferred install across the Play Store. This emits
+ *  `referrer=` instead, which `reclaim-verifier-app`'s
+ *  `checkInstallReferrerForLink` (`lib/widgets/link_handler.dart`) now reads
+ *  via `PlayInstallReferrer.installReferrer`. `url=` is dropped rather than
+ *  kept alongside `referrer=`: nothing in this codebase or the verifier app
+ *  reads it (the app has no `queryParameters['url']` handling anywhere), so
+ *  it would be dead weight carried forward for no reason.
+ *
+ *  Exactly one layer of `encodeURIComponent` is applied to `shareUrl` here:
+ *   - `referrer` is itself a query-string value inside this intent URI, so it
+ *     needs at least one layer to survive the `?`/`&`/`=` characters in
+ *     `shareUrl` without corrupting the outer intent.
+ *   - Play decodes exactly one layer of percent-encoding off the referrer
+ *     string before handing it to the app — the app's
+ *     `_parseBuilderReferrerUri` documents this and tries the raw string
+ *     first. One layer here round-trips to the literal share URL on the
+ *     other side. The app also falls back to `Uri.decodeFull` if the raw
+ *     string doesn't parse, tolerating an extra layer either way, but this
+ *     is deliberately exactly one layer rather than leaning on that
+ *     fallback.
+ *
+ *  Play truncates the referrer string at roughly 1KB. A Builder verification
+ *  URL is a UUID and two query parameters, comfortably under that — which is
+ *  what makes this viable where the legacy SDK's base64 `template=` payload
+ *  never could be (see the launch-api plan's "Install Referrer beats the
+ *  clipboard"). Keep the clipboard write in `redirectToAndroid` regardless:
+ *  it is still the only carrier for an install that did not come through
+ *  Play, and the app still reads it. */
+export function buildAndroidMarketIntentUrl(
+	shareUrl: string,
+	androidDeepLinkPackage: string,
+): string {
+	const encodedShareUrl = encodeURIComponent(shareUrl)
+	return `intent://details?id=${androidDeepLinkPackage}`
+		+ `&referrer=${encodedShareUrl}`
+		+ '#Intent;scheme=market;action=android.intent.action.VIEW;'
+		+ 'package=com.android.vending;end;'
+}