@reclaimprotocol/client 0.1.28 → 0.1.31

package/src/launch/modal.ts

@@ -0,0 +1,378 @@
+/**
+ * The desktop `verifier-app` mechanism: a dependency-free QR dialog over the
+ * share URL, with the QR itself bundled (see ./qr.ts).
+ *
+ * The layout follows the reference JS SDK's `utils/modalUtils.ts`
+ * `QRCodeModal` — same card, same close affordance, same countdown and
+ * progress bar along the bottom — so a consumer moving from `reclaim-js-sdk`
+ * sees the dialog they already know. Two things differ on purpose: the QR is
+ * an inline SVG from the vendored encoder rather than a `qrcode` dependency,
+ * and the countdown can be switched off entirely, because a dialog that
+ * closes itself under a claimant who is still reaching for their phone is
+ * worse than one that waits.
+ */
+import type {
+	LaunchDocument,
+	LaunchElement,
+	LaunchEnvironment,
+	LaunchKeyboardEvent,
+	LaunchMouseEvent,
+	LaunchStyleDeclaration,
+} from './environment.ts'
+import type { RenderQr } from './qr.ts'
+import { defaultRenderQr } from './qr.ts'
+
+export interface ModalOptions {
+	title?: string
+	description?: string
+	darkTheme?: boolean
+	/**
+	 * Seconds to keep the dialog open before closing it on the claimant's
+	 * behalf, shown as a countdown and a draining progress bar.
+	 *
+	 * Pass `0` (or `Infinity`) to keep it open until something closes it —
+	 * `handle.close()`, the close button, the backdrop, or Escape. The
+	 * countdown and bar are then omitted rather than frozen, since a timer
+	 * that never moves reads as broken.
+	 */
+	autoCloseSeconds?: number
+	/** Shows the "install the extension" tip, linking here. */
+	extensionUrl?: string
+	/** Called once, whenever and however the dialog closes. */
+	onClose?(): void
+}
+
+export interface ModalHandle {
+	close(): void
+	/** Seconds left before the dialog closes itself, or `null` when it is
+	 *  waiting indefinitely. Reads `0` once closed. */
+	readonly remainingSeconds: number | null
+}
+
+const DEFAULT_TITLE = 'Verify with Reclaim'
+const DEFAULT_DESCRIPTION
+	= 'Scan the QR code with your phone to complete verification.'
+const DEFAULT_AUTO_CLOSE_SECONDS = 60
+const MODAL_FONT_FAMILY
+	= '-apple-system, BlinkMacSystemFont, \'Segoe UI\', Roboto, sans-serif'
+const TICK_MS = 1000
+
+/**
+ * Opens the dialog and returns the handle that closes it again.
+ *
+ * Exported from the package root as well as used by `launch()`, so a consumer
+ * who only wants a QR over a share link can open one directly without going
+ * through flow resolution.
+ */
+export function showQrModal(
+	env: LaunchEnvironment,
+	url: string,
+	options: ModalOptions & { renderQr?: RenderQr } = {},
+): ModalHandle {
+	const doc = env.document
+	const body = doc?.body
+	if(!doc || !body) {
+		return { close() {}, remainingSeconds: null }
+	}
+
+	// Captured with its narrowed type: `close` below is a hoisted function
+	// declaration, and TypeScript will not carry a narrowing into one.
+	const activeDoc: LaunchDocument = doc
+	const theme = themeFor(!!options.darkTheme)
+	const total = normalizeSeconds(options.autoCloseSeconds)
+	let remaining = total
+	let closed = false
+	let timer: unknown
+
+	const overlay = doc.createElement('div')
+	setStyle(overlay, {
+		position: 'fixed', inset: '0', display: 'flex', alignItems: 'center',
+		justifyContent: 'center', padding: '16px', boxSizing: 'border-box',
+		background: theme.backdrop, zIndex: '2147483647',
+	})
+
+	const card = doc.createElement('div')
+	card.setAttribute('role', 'dialog')
+	card.setAttribute('aria-modal', 'true')
+	card.setAttribute('aria-label', options.title ?? DEFAULT_TITLE)
+	setStyle(card, {
+		position: 'relative', background: theme.card, color: theme.title,
+		borderRadius: '12px', padding: '32px', maxWidth: '400px', width: '100%',
+		boxSizing: 'border-box', textAlign: 'center',
+		fontFamily: MODAL_FONT_FAMILY, boxShadow: theme.shadow,
+	})
+	overlay.appendChild(card)
+
+	card.appendChild(closeButton(doc, theme, () => close()))
+
+	const title = doc.createElement('h2')
+	title.innerHTML = escapeHtml(options.title ?? DEFAULT_TITLE)
+	setStyle(title, {
+		margin: '0 0 16px 0', fontSize: '24px', fontWeight: '600',
+		color: theme.title,
+	})
+	card.appendChild(title)
+
+	const description = doc.createElement('p')
+	description.innerHTML = escapeHtml(options.description ?? DEFAULT_DESCRIPTION)
+	setStyle(description, {
+		margin: '0 0 24px 0', fontSize: '14px', lineHeight: '1.5',
+		color: theme.text,
+	})
+	card.appendChild(description)
+
+	const qrSlot = doc.createElement('div')
+	setStyle(qrSlot, {
+		margin: '0 auto 24px auto', display: 'inline-block', padding: '8px',
+		background: theme.qr, borderRadius: '8px',
+	})
+	card.appendChild(qrSlot)
+	void (options.renderQr ?? defaultRenderQr)(url, qrSlot)
+
+	if(options.extensionUrl) {
+		card.appendChild(extensionTip(doc, theme, options.extensionUrl))
+	}
+
+	const copyLink = doc.createElement('button')
+	copyLink.setAttribute('type', 'button')
+	copyLink.innerHTML = 'Copy link'
+	setStyle(copyLink, {
+		background: theme.button, color: theme.buttonText, border: 'none',
+		borderRadius: '6px', padding: '8px 16px', fontSize: '13px',
+		cursor: 'pointer',
+	})
+	card.appendChild(copyLink)
+	copyLink.addEventListener('click', () => {
+		void env.navigator?.clipboard?.writeText(url).catch(() => {})
+	})
+
+	// Only built when there is a countdown to show. An unmoving timer and a
+	// full progress bar would both claim something is being measured.
+	let countdownText: LaunchElement | undefined
+	let progressBar: LaunchElement | undefined
+	if(total !== null) {
+		const wrap = doc.createElement('div')
+		setStyle(wrap, { marginTop: '16px' })
+
+		countdownText = doc.createElement('div')
+		setStyle(countdownText, {
+			fontSize: '12px', color: theme.countdown, marginBottom: '8px',
+		})
+		wrap.appendChild(countdownText)
+
+		const track = doc.createElement('div')
+		setStyle(track, {
+			width: '100%', height: '4px', backgroundColor: theme.progressTrack,
+			borderRadius: '2px', overflow: 'hidden',
+		})
+		progressBar = doc.createElement('div')
+		setStyle(progressBar, {
+			width: '100%', height: '100%', background: theme.progressFill,
+			borderRadius: '2px', transition: 'width 1s linear',
+		})
+		track.appendChild(progressBar)
+		wrap.appendChild(track)
+		card.appendChild(wrap)
+	}
+
+	overlay.addEventListener('click', onBackdropClick)
+	doc.addEventListener('keydown', onKeydown)
+	body.appendChild(overlay)
+
+	if(total !== null) {
+		renderCountdown()
+		timer = env.setTimeout(tick, TICK_MS)
+	}
+
+	return {
+		close,
+		get remainingSeconds() {
+			return remaining
+		},
+	}
+
+	function tick() {
+		if(closed || remaining === null) {
+			return
+		}
+
+		remaining -= 1
+		renderCountdown()
+		if(remaining <= 0) {
+			close()
+			return
+		}
+
+		timer = env.setTimeout(tick, TICK_MS)
+	}
+
+	function renderCountdown() {
+		if(remaining === null || total === null) {
+			return
+		}
+
+		const minutes = Math.floor(remaining / 60)
+		const seconds = remaining % 60
+		if(countdownText) {
+			countdownText.innerHTML = escapeHtml(
+				`Closes in ${minutes}:${String(seconds).padStart(2, '0')}`,
+			)
+		}
+
+		if(progressBar) {
+			progressBar.style.width = `${Math.max(0, remaining / total) * 100}%`
+		}
+	}
+
+	// `e.target === overlay` is what separates a click on the backdrop from
+	// one that bubbled up out of the card — without it, every click inside
+	// the dialog would close it.
+	function onBackdropClick(event?: LaunchMouseEvent) {
+		if(!event || event.target === overlay) {
+			close()
+		}
+	}
+
+	function onKeydown(event: LaunchKeyboardEvent) {
+		if(event.key === 'Escape') {
+			close()
+		}
+	}
+
+	function close() {
+		if(closed) {
+			return
+		}
+
+		closed = true
+		remaining = total === null ? null : 0
+		if(timer !== undefined) {
+			env.clearTimeout(timer)
+			timer = undefined
+		}
+
+		overlay.removeEventListener('click', onBackdropClick)
+		activeDoc.removeEventListener('keydown', onKeydown)
+		overlay.remove()
+		options.onClose?.()
+	}
+}
+
+/** `undefined` means the default countdown; `0`/negative/non-finite means
+ *  wait indefinitely, which the caller sees as `null` throughout. */
+function normalizeSeconds(value: number | undefined): number | null {
+	const seconds = value ?? DEFAULT_AUTO_CLOSE_SECONDS
+	if(!Number.isFinite(seconds) || seconds <= 0) {
+		return null
+	}
+
+	return Math.ceil(seconds)
+}
+
+function closeButton(
+	doc: LaunchDocument,
+	theme: ModalTheme,
+	onClick: () => void,
+): LaunchElement {
+	const button = doc.createElement('button')
+	button.setAttribute('type', 'button')
+	button.setAttribute('aria-label', 'Close')
+	button.setAttribute('title', 'Close')
+	setStyle(button, {
+		position: 'absolute', top: '16px', right: '16px', width: '32px',
+		height: '32px', background: 'none', border: 'none', cursor: 'pointer',
+		borderRadius: '6px', display: 'flex', alignItems: 'center',
+		justifyContent: 'center', padding: '4px',
+	})
+	button.innerHTML = '<svg width="16" height="16" viewBox="0 0 16 16" '
+		+ 'fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">'
+		+ `<path d="M12 4L4 12M4 4L12 12" stroke="${theme.buttonText}" `
+		+ 'stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>'
+		+ '</svg>'
+	button.addEventListener('click', onClick)
+	return button
+}
+
+function extensionTip(
+	doc: LaunchDocument,
+	theme: ModalTheme,
+	extensionUrl: string,
+): LaunchElement {
+	const tip = doc.createElement('div')
+	setStyle(tip, {
+		marginBottom: '24px', padding: '16px', background: theme.tip,
+		border: `1px solid ${theme.tipBorder}`, borderRadius: '8px',
+		textAlign: 'left',
+	})
+	tip.innerHTML = '<p style="margin:0 0 8px 0;font-size:14px;font-weight:500;'
+		+ `color:${theme.tipText}">For a faster route</p>`
+		+ '<p style="margin:0 0 12px 0;font-size:13px;line-height:1.4;'
+		+ `color:${theme.tipText}">Install the browser extension to verify `
+		+ 'here, without a phone.</p>'
+		+ `<a href="${escapeHtml(extensionUrl)}" target="_blank" `
+		+ 'rel="noopener noreferrer" style="display:inline-block;'
+		+ `background:${theme.accent};color:#fff;text-decoration:none;`
+		+ 'padding:8px 16px;border-radius:6px;font-size:12px;font-weight:500">'
+		+ 'Install extension</a>'
+	return tip
+}
+
+interface ModalTheme {
+	backdrop: string
+	card: string
+	shadow: string
+	title: string
+	text: string
+	qr: string
+	button: string
+	buttonText: string
+	countdown: string
+	progressTrack: string
+	progressFill: string
+	tip: string
+	tipBorder: string
+	tipText: string
+	accent: string
+}
+
+function themeFor(dark: boolean): ModalTheme {
+	return dark
+		? {
+			backdrop: 'rgba(0,0,0,0.8)', card: '#1f2937',
+			shadow: '0 20px 25px -5px rgba(0,0,0,0.5)',
+			title: '#f9fafb', text: '#d1d5db', qr: '#374151',
+			button: '#374151', buttonText: '#f9fafb', countdown: '#6b7280',
+			progressTrack: '#4b5563',
+			progressFill:
+				'linear-gradient(90deg,#3b82f6 0%,#2563eb 50%,#1d4ed8 100%)',
+			tip: '#1e3a8a', tipBorder: '#1e40af', tipText: '#dbeafe',
+			accent: '#2563eb',
+		}
+		: {
+			backdrop: 'rgba(0,0,0,0.5)', card: '#fff',
+			shadow: '0 20px 25px -5px rgba(0,0,0,0.1),'
+				+ '0 10px 10px -5px rgba(0,0,0,0.04)',
+			title: '#1f2937', text: '#6b7280', qr: '#f9fafb',
+			button: '#f3f4f6', buttonText: '#374151', countdown: '#9ca3af',
+			progressTrack: '#e5e7eb',
+			progressFill:
+				'linear-gradient(90deg,#2563eb 0%,#1d4ed8 50%,#1e40af 100%)',
+			tip: '#f0f9ff', tipBorder: '#e0f2fe', tipText: '#0369a1',
+			accent: '#2563eb',
+		}
+}
+
+/** Every property `LaunchStyleDeclaration` declares is a real
+ *  `CSSStyleDeclaration` property name, so this needs no cast — unlike a
+ *  generic `Record<string, string>` target, which would. */
+function setStyle(el: LaunchElement, declarations: LaunchStyleDeclaration) {
+	Object.assign(el.style, declarations)
+}
+
+function escapeHtml(value: string): string {
+	return value
+		.replace(/&/g, '&amp;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+}

package/src/launch/options.ts

@@ -0,0 +1,99 @@
+/**
+ * `FlowOptions` — the launch-API plan's "Options" table. Option NAMES match
+ * the reference JS SDK's so existing call sites port unchanged; everything
+ * here is optional, and every default lives in `DEFAULT_FLOW_OPTIONS`/the
+ * `resolve*Options` helpers below rather than scattered through `flow.ts`.
+ */
+import type {
+	LaunchContainer,
+	LaunchEnvironment,
+	LaunchWindowHandle
+} from './environment.ts'
+import type { ModalOptions } from './modal.ts'
+import type { RenderQr } from './qr.ts'
+
+export interface FlowOptions {
+	/** Whether to probe for the browser extension at all. Default `true`. */
+	useBrowserExtension?: boolean
+	/** Strict-mode match against `chrome.runtime.id`. Omitted means any
+	 *  extension answers. */
+	extensionID?: string
+	/** Availability probe budget, in ms. Default `200`. */
+	extensionTimeout?: number
+	/** Portal origin; `/verify` is appended. Default
+	 *  `https://portal.reclaimprotocol.org`. */
+	portalUrl?: string
+	/** Universal link for the verifier app. Default
+	 *  `https://share.reclaimprotocol.org/verify`. */
+	appLinkBaseUrl?: string
+	/** iOS custom-scheme deep link base, used both for the direct iOS deep
+	 *  link and (with the same custom scheme) the Android probe. Default
+	 *  `reclaimverifier://org.reclaimprotocol.app`. */
+	iosDeepLinkBaseUrl?: string
+	/** Android package id, used to build the Play Store market-intent
+	 *  fallback. Default `org.reclaimprotocol.app`. */
+	androidDeepLinkPackage?: string
+	/** iOS App Store fallback. Default the Reclaim Verifier App Store page. */
+	iosAppDownloadUrl?: string
+	/** Android Play Store fallback. Defaults to the Play Store page for
+	 *  `androidDeepLinkPackage`. */
+	androidAppDownloadUrl?: string
+	/** Prefer the App Clip on iOS over the direct deep link. Default `false`. */
+	useAppClip?: boolean
+	/** App Clip destination. Default
+	 *  `https://appclip.apple.com/id?p=org.reclaimprotocol.app.clip`. */
+	appClipUrl?: string
+	/** Android: clipboard write + deep-link probe + market-intent fallback
+	 *  (`true`, the default) vs. a plain redirect to the share URL (`false`).
+	 *  iOS: no effect — the iOS mechanism is chosen by `useAppClip` alone.
+	 *  Defaults to `true` on Android, `false` on iOS. */
+	canUseDeferredDeepLinksFlow?: boolean
+	/** DOM element to embed the portal/builder page into as an iframe,
+	 *  instead of opening a new tab (desktop only). */
+	target?: LaunchContainer
+	/** QR dialog title, description, theme, auto-close countdown, optional
+	 *  extension tip, and close handler. */
+	modalOptions?: ModalOptions
+	/** Overrides the bundled QR renderer. */
+	renderQr?: RenderQr
+	/** A tab already opened via `window.open('about:blank')` inside the
+	 *  click handler, so the network round trip before `launch()` doesn't
+	 *  lose the user gesture a fresh `window.open` would need. */
+	preOpenedTab?: LaunchWindowHandle | null
+	/** Escape hatch for a staff-registered custom client whose URL doesn't
+	 *  match the seeded path convention — see `./target.ts`. Never required. */
+	verificationClientId?: string
+	/** Overrides the real browser globals — see ./environment.ts. Tests pass
+	 *  a fake; browser code never needs to set this. */
+	environment?: LaunchEnvironment
+}
+
+export const DEFAULT_USE_BROWSER_EXTENSION = true
+export const DEFAULT_EXTENSION_TIMEOUT_MS = 200
+// `portalUrl`/`appLinkBaseUrl` defaults live in ./destination.ts, next to the
+// `resolveDestinationUrl()` that's the only place they're read.
+export const DEFAULT_IOS_DEEP_LINK_BASE_URL
+	= 'reclaimverifier://org.reclaimprotocol.app'
+export const DEFAULT_ANDROID_DEEP_LINK_PACKAGE = 'org.reclaimprotocol.app'
+export const DEFAULT_IOS_APP_DOWNLOAD_URL
+	= 'itms-apps://apps.apple.com/in/app/reclaim-verifier/id6503247508'
+export const DEFAULT_USE_APP_CLIP = false
+export const DEFAULT_APP_CLIP_URL
+	= 'https://appclip.apple.com/id?p=org.reclaimprotocol.app.clip'
+
+export function resolveAndroidAppDownloadUrl(options: FlowOptions): string {
+	const androidPackage = resolveAndroidDeepLinkPackage(options)
+	return options.androidAppDownloadUrl
+		?? `https://play.google.com/store/apps/details?id=${androidPackage}`
+}
+
+export function resolveAndroidDeepLinkPackage(options: FlowOptions): string {
+	return options.androidDeepLinkPackage ?? DEFAULT_ANDROID_DEEP_LINK_PACKAGE
+}
+
+export function resolveCanUseDeferredDeepLinksFlow(
+	options: FlowOptions,
+	device: 'ios' | 'android',
+): boolean {
+	return options.canUseDeferredDeepLinksFlow ?? (device === 'android')
+}

package/src/launch/portal.ts

@@ -0,0 +1,104 @@
+/**
+ * The `new-tab`/`iframe` mechanisms shared by the `builder` and `portals`
+ * targets. Ported from the reference JS SDK's `openPortalTab`/
+ * `embedPortalIframe` (`Reclaim.ts` ~1159/~1191).
+ */
+import type {
+	LaunchContainer,
+	LaunchElement,
+	LaunchEnvironment,
+	LaunchWindowHandle
+} from './environment.ts'
+
+export interface PortalTabHandle {
+	tab: LaunchWindowHandle | null
+	close(): void
+}
+
+/**
+ * Opens `url` in a new tab. Popup blockers kill a `window.open` that happens
+ * after a network round trip, so a caller that already opened
+ * `window.open('about:blank')` synchronously inside the click handler passes
+ * it as `preOpenedTab` — this just navigates it, preserving the user
+ * gesture. Falls back to opening fresh (and recovers if the pre-opened tab
+ * never actually navigated, e.g. a blocker allowed the open but not the
+ * navigation) exactly as the reference SDK does.
+ */
+export function openPortalTab(
+	env: LaunchEnvironment,
+	url: string,
+	preOpenedTab?: LaunchWindowHandle | null,
+): PortalTabHandle {
+	// Matches the reference SDK exactly: the fresh path also opens
+	// `about:blank` first rather than the real URL directly, so the recovery
+	// check below (which looks for a tab stuck at `about:blank`) applies
+	// uniformly to both paths.
+	const tab = preOpenedTab ?? env.open('about:blank', '_blank')
+	if(!tab) {
+		return { tab: null, close() {} }
+	}
+
+	tab.navigate(url)
+
+	// Verify navigation actually happened; recover by opening fresh if not.
+	const recoveryHandle = env.setTimeout(() => {
+		try {
+			if(tab.location.href === 'about:blank') {
+				tab.close()
+				env.open(url, '_blank')
+			}
+		} catch{
+			// Cross-origin after navigation means it worked.
+		}
+	}, 500)
+
+	return {
+		tab,
+		close() {
+			env.clearTimeout(recoveryHandle)
+			try {
+				tab.close()
+			} catch{
+				// Cross-origin — tab may have navigated away.
+			}
+		},
+	}
+}
+
+export interface PortalIframeHandle {
+	iframe: LaunchElement | undefined
+	close(): void
+}
+
+/** Embeds `url` inside `container` (`options.target`). Appends
+ *  `embedded=true` so the portal skips extension detection, matching the
+ *  reference SDK. */
+export function embedPortalIframe(
+	env: LaunchEnvironment,
+	url: string,
+	container: LaunchContainer,
+): PortalIframeHandle {
+	if(!env.document) {
+		return { iframe: undefined, close() {} }
+	}
+
+	const embedUrl = new URL(url)
+	embedUrl.searchParams.set('embedded', 'true')
+
+	const iframe = env.document.createElement('iframe')
+	iframe.src = embedUrl.toString()
+	iframe.style.width = '100%'
+	iframe.style.height = '100%'
+	iframe.style.border = 'none'
+	iframe.setAttribute('allow', 'clipboard-write')
+	iframe.setAttribute('sandbox', 'allow-scripts allow-same-origin allow-forms')
+
+	container.appendChild(iframe)
+
+	return {
+		iframe,
+		close() {
+			iframe.remove()
+		},
+	}
+}

package/src/launch/qr.ts

@@ -0,0 +1,37 @@
+/**
+ * Default QR renderer — bundled so the desktop `verifier-app` modal works
+ * with zero configuration (`options.renderQr` overrides it for a branded
+ * code). Renders an inline SVG (no `<canvas>`/image needed) from the vendored
+ * encoder in ./vendor/qrcodegen.ts.
+ */
+import { QrCode, QrCodeEcc } from './vendor/qrcodegen.ts'
+import type { LaunchElement } from './environment.ts'
+
+export type RenderQr = (
+	url: string,
+	container: LaunchElement,
+) => void | Promise<void>
+
+/** Renders `url` as an inline SVG QR code into `container`. Quiet zone of 4
+ *  modules, as the QR spec recommends. */
+export const defaultRenderQr: RenderQr = (url, container) => {
+	const qr = QrCode.encodeText(url, QrCodeEcc.MEDIUM)
+	const quietZone = 4
+	const dimension = qr.size + quietZone * 2
+
+	let path = ''
+	for(let y = 0; y < qr.size; y++) {
+		for(let x = 0; x < qr.size; x++) {
+			if(qr.getModule(x, y)) {
+				path += `M${x + quietZone},${y + quietZone}h1v1h-1z`
+			}
+		}
+	}
+
+	const viewBox = `0 0 ${dimension} ${dimension}`
+	container.innerHTML = `<svg viewBox="${viewBox}" width="200" height="200" `
+		+ 'role="img" aria-label="QR code" xmlns="http://www.w3.org/2000/svg">'
+		+ `<rect width="${dimension}" height="${dimension}" fill="#fff"/>`
+		+ `<path d="${path}" fill="#000"/>`
+		+ '</svg>'
+}