@reclaimprotocol/client 0.1.28 → 0.1.31

package/lib/launch/modal.js

@@ -0,0 +1,258 @@
+import { defaultRenderQr } from "./qr.js";
+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, url, options = {}) {
+    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 = doc;
+    const theme = themeFor(!!options.darkTheme);
+    const total = normalizeSeconds(options.autoCloseSeconds);
+    let remaining = total;
+    let closed = false;
+    let timer;
+    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;
+    let progressBar;
+    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) {
+        if (!event || event.target === overlay) {
+            close();
+        }
+    }
+    function onKeydown(event) {
+        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) {
+    const seconds = value ?? DEFAULT_AUTO_CLOSE_SECONDS;
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+        return null;
+    }
+    return Math.ceil(seconds);
+}
+function closeButton(doc, theme, onClick) {
+    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, theme, extensionUrl) {
+    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;
+}
+function themeFor(dark) {
+    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, declarations) {
+    Object.assign(el.style, declarations);
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}

package/lib/launch/options.d.ts

@@ -0,0 +1,74 @@
+/**
+ * `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 declare const DEFAULT_USE_BROWSER_EXTENSION = true;
+export declare const DEFAULT_EXTENSION_TIMEOUT_MS = 200;
+export declare const DEFAULT_IOS_DEEP_LINK_BASE_URL = "reclaimverifier://org.reclaimprotocol.app";
+export declare const DEFAULT_ANDROID_DEEP_LINK_PACKAGE = "org.reclaimprotocol.app";
+export declare const DEFAULT_IOS_APP_DOWNLOAD_URL = "itms-apps://apps.apple.com/in/app/reclaim-verifier/id6503247508";
+export declare const DEFAULT_USE_APP_CLIP = false;
+export declare const DEFAULT_APP_CLIP_URL = "https://appclip.apple.com/id?p=org.reclaimprotocol.app.clip";
+export declare function resolveAndroidAppDownloadUrl(options: FlowOptions): string;
+export declare function resolveAndroidDeepLinkPackage(options: FlowOptions): string;
+export declare function resolveCanUseDeferredDeepLinksFlow(options: FlowOptions, device: 'ios' | 'android'): boolean;

package/lib/launch/options.js

@@ -0,0 +1,20 @@
+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) {
+    const androidPackage = resolveAndroidDeepLinkPackage(options);
+    return options.androidAppDownloadUrl
+        ?? `https://play.google.com/store/apps/details?id=${androidPackage}`;
+}
+export function resolveAndroidDeepLinkPackage(options) {
+    return options.androidDeepLinkPackage ?? DEFAULT_ANDROID_DEEP_LINK_PACKAGE;
+}
+export function resolveCanUseDeferredDeepLinksFlow(options, device) {
+    return options.canUseDeferredDeepLinksFlow ?? (device === 'android');
+}

package/lib/launch/portal.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 declare function openPortalTab(env: LaunchEnvironment, url: string, preOpenedTab?: LaunchWindowHandle | null): PortalTabHandle;
+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 declare function embedPortalIframe(env: LaunchEnvironment, url: string, container: LaunchContainer): PortalIframeHandle;

package/lib/launch/portal.js

@@ -0,0 +1,68 @@
+/**
+ * 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, url, preOpenedTab) {
+    // 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.
+            }
+        },
+    };
+}
+/** Embeds `url` inside `container` (`options.target`). Appends
+ *  `embedded=true` so the portal skips extension detection, matching the
+ *  reference SDK. */
+export function embedPortalIframe(env, url, container) {
+    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/lib/launch/qr.d.ts

@@ -0,0 +1,5 @@
+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 declare const defaultRenderQr: RenderQr;

package/lib/launch/qr.js

@@ -0,0 +1,28 @@
+/**
+ * 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.js";
+/** Renders `url` as an inline SVG QR code into `container`. Quiet zone of 4
+ *  modules, as the QR spec recommends. */
+export const defaultRenderQr = (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>';
+};

package/lib/launch/target.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Which client a `verificationUrl` names, and what a caller-supplied
+ * `verificationClientId` escape hatch can override.
+ *
+ * `build_verification_url` (packages/app/sql/ddl.sql) appends
+ * `?api=2&sessionId=<uuid>` (plus optional `&diag=1`) to the registered
+ * client's base URL, so parsing the path is enough to name the client — the
+ * registered URI is an attribution label, never the URL to open (see
+ * ./destination.ts for what actually gets opened).
+ *
+ * As of migration `20260917130000000.share-routes-uris.sql`, every built-in
+ * client (`builder` included) registers at the uniform `{origin}/share/
+ * {name}` shape (see `packages/app/src/verification/builtin-clients.ts`'s
+ * `clientUrl()` and `packages/app/src/routes/SharePage.tsx`). Only four of
+ * the six names are launchable targets here — `inapp-sdk` and `zkfetch` have
+ * no claimant browser flow, so `/share/inapp-sdk` and `/share/zkfetch`
+ * degrade the same as the old bare `/zkfetch` label always did.
+ *
+ * The pre-migration shapes — `/portals`, `/s` / `/verifier-app`,
+ * `/reclaim-browser-extension`, and `builder`'s own `/v/{id}` — are kept
+ * recognised too, deliberately, not just for a transition window:
+ *   - a deployment that has not yet run that migration still seeds and
+ *     serves the old uris, so dropping them would break every consumer
+ *     hitting an un-migrated Builder;
+ *   - `register_verification_client`'s seed upsert COALESCEs `uri` and never
+ *     clobbers a non-null value, so an admin who set a custom (old-shape)
+ *     uri before the migration keeps it forever — there is no future point
+ *     at which the old shapes stop appearing in the wild;
+ *   - `builder`'s own `/share/builder` route 302s to `/v/{sessionId}`
+ *     server-side (see SharePage.tsx) — `/v/{id}` is where a claimant
+ *     *actually lands* regardless of which shape the session was created
+ *     against, so it must stay recognised independent of the migration
+ *     question entirely.
+ * There is no ambiguity cost to recognising both: the shapes are disjoint
+ * path segments, so a URL can only ever match one.
+ */
+export type VerificationTarget = 'builder' | 'portals' | 'verifier-app' | 'reclaim-browser-extension';
+export interface ParsedFlowUrl {
+    url: URL;
+    target: VerificationTarget | undefined;
+    sessionId: string | undefined;
+    diag: boolean;
+}
+/** Parses a `verificationUrl` into its client and session id, without
+ *  rebuilding anything — see `./destination.ts` for the openable URL. */
+export declare function parseFlowUrl(verificationUrl: string, verificationClientId?: string): ParsedFlowUrl;

package/lib/launch/target.js

@@ -0,0 +1,128 @@
+/**
+ * Which client a `verificationUrl` names, and what a caller-supplied
+ * `verificationClientId` escape hatch can override.
+ *
+ * `build_verification_url` (packages/app/sql/ddl.sql) appends
+ * `?api=2&sessionId=<uuid>` (plus optional `&diag=1`) to the registered
+ * client's base URL, so parsing the path is enough to name the client — the
+ * registered URI is an attribution label, never the URL to open (see
+ * ./destination.ts for what actually gets opened).
+ *
+ * As of migration `20260917130000000.share-routes-uris.sql`, every built-in
+ * client (`builder` included) registers at the uniform `{origin}/share/
+ * {name}` shape (see `packages/app/src/verification/builtin-clients.ts`'s
+ * `clientUrl()` and `packages/app/src/routes/SharePage.tsx`). Only four of
+ * the six names are launchable targets here — `inapp-sdk` and `zkfetch` have
+ * no claimant browser flow, so `/share/inapp-sdk` and `/share/zkfetch`
+ * degrade the same as the old bare `/zkfetch` label always did.
+ *
+ * The pre-migration shapes — `/portals`, `/s` / `/verifier-app`,
+ * `/reclaim-browser-extension`, and `builder`'s own `/v/{id}` — are kept
+ * recognised too, deliberately, not just for a transition window:
+ *   - a deployment that has not yet run that migration still seeds and
+ *     serves the old uris, so dropping them would break every consumer
+ *     hitting an un-migrated Builder;
+ *   - `register_verification_client`'s seed upsert COALESCEs `uri` and never
+ *     clobbers a non-null value, so an admin who set a custom (old-shape)
+ *     uri before the migration keeps it forever — there is no future point
+ *     at which the old shapes stop appearing in the wild;
+ *   - `builder`'s own `/share/builder` route 302s to `/v/{sessionId}`
+ *     server-side (see SharePage.tsx) — `/v/{id}` is where a claimant
+ *     *actually lands* regardless of which shape the session was created
+ *     against, so it must stay recognised independent of the migration
+ *     question entirely.
+ * There is no ambiguity cost to recognising both: the shapes are disjoint
+ * path segments, so a URL can only ever match one.
+ */
+/**
+ * Fixed, deployment-independent ids for the built-in clients — duplicated
+ * from `packages/app/src/verification/builtin-clients.ts`'
+ * `BUILTIN_CLIENT_IDS` (also duplicated in the in-app SDK and the browser
+ * extension SDK). Changing one copy alone breaks every other caller.
+ *
+ * Used only as the `options.verificationClientId` escape hatch: when a
+ * staff-registered custom client's URL doesn't match the path convention
+ * above (an admin-overridden `uri`, or a fresh custom registration that was
+ * nonetheless assigned one of these fixed ids), a caller who knows the id
+ * out of band can still get the right launch mechanism instead of degrading
+ * to a tab. This is unrelated to — and does not feed — the extension
+ * handoff payload, which never carries a client id at all (see
+ * ./extension.ts).
+ */
+const BUILTIN_CLIENT_IDS = {
+    builder: '00000000-0000-4000-8000-000000000001',
+    'verifier-app': '00000000-0000-4000-8000-000000000002',
+    portals: '00000000-0000-4000-8000-000000000004',
+    'reclaim-browser-extension': '00000000-0000-4000-8000-000000000005',
+};
+/** Parses a `verificationUrl` into its client and session id, without
+ *  rebuilding anything — see `./destination.ts` for the openable URL. */
+export function parseFlowUrl(verificationUrl, verificationClientId) {
+    const url = new URL(verificationUrl);
+    const segments = url.pathname.split('/').filter(Boolean);
+    let target;
+    if (segments[0] === 'v' && segments.length >= 2) {
+        // Both a pre-migration `builder` uri (registered directly at
+        // `/v/{sessionId}`) and where a claimant's browser actually lands after
+        // `/share/builder`'s server-side 302 — recognised unconditionally, not
+        // merely as one of the two shapes below.
+        target = 'builder';
+    }
+    else if (segments[0] === 'share' && segments.length >= 2) {
+        target = targetForShareName(segments[1]);
+    }
+    else if (segments[0] === 'portals') {
+        target = 'portals';
+    }
+    else if (segments[0] === 's' || segments[0] === 'verifier-app') {
+        // `/s` is Builder's own share page and the uri `verifier-app` is
+        // registered at today; `/verifier-app` is the attribution-only label it
+        // used to carry, still recognised for a deployment that has not run the
+        // re-pointing migration (or whose admin kept the old uri).
+        target = 'verifier-app';
+    }
+    else if (segments[0] === 'reclaim-browser-extension') {
+        target = 'reclaim-browser-extension';
+    }
+    // Falls back for EITHER an unrecognised path (old shape or new) or a
+    // `/share/{name}` naming a non-launchable client (`inapp-sdk`/`zkfetch`) —
+    // `targetForShareName` returning `undefined` for those must still let this
+    // run, not short-circuit it.
+    if (!target && verificationClientId) {
+        target = targetForClientId(verificationClientId);
+    }
+    return {
+        url,
+        target,
+        sessionId: url.searchParams.get('sessionId')?.trim() || undefined,
+        diag: url.searchParams.get('diag') === '1',
+    };
+}
+/** The four launchable targets' `/share/{name}` segment, post-migration —
+ *  see `builtin-clients.ts`'s `clientUrl()`. `inapp-sdk` and `zkfetch` get a
+ *  real `/share/{name}` page too (so a stray GET doesn't 404), but neither
+ *  has a claimant browser flow, so they degrade like the old bare `/zkfetch`
+ *  label always did. */
+function targetForShareName(name) {
+    switch (name) {
+        case 'builder':
+        case 'portals':
+        case 'verifier-app':
+        case 'reclaim-browser-extension':
+            return name;
+        default:
+            return undefined;
+    }
+}
+function targetForClientId(verificationClientId) {
+    const normalized = verificationClientId.trim().toLowerCase();
+    for (const [target, id] of Object.entries(BUILTIN_CLIENT_IDS)) {
+        if (id === normalized) {
+            // The key side of `Object.entries` on
+            // `Record<VerificationTarget, string>` is exactly
+            // `VerificationTarget`; TS widens it to `string` on the way out.
+            return target;
+        }
+    }
+    return undefined;
+}