@reclaimprotocol/client 0.1.28 → 0.1.31

package/lib/api.d.ts

@@ -2,6 +2,8 @@ export { ReclaimClient } from './client.ts';
 export type { ReclaimClientOptions } from './client.ts';
 export { isProblemDetails, isProblemError, readProblemDetails, throwProblemError, } from './errors.ts';
 export type { ProblemError } from './errors.ts';
+export { getBooleanFeatureFlag, getFeatureFlag, getNumberFeatureFlag, getStringFeatureFlag, } from './feature-flags.ts';
 export { DEFAULT_BASE_URL, PROBLEM_CONTENT_TYPE, } from './consts.ts';
+export { VerificationClient, } from './verification-clients.ts';
 export type * from './types/openapi.ts';
 export type * from './types/openapi.gen.ts';

package/lib/api.js

@@ -1,3 +1,5 @@
 export { ReclaimClient } from "./client.js";
 export { isProblemDetails, isProblemError, readProblemDetails, throwProblemError, } from "./errors.js";
+export { getBooleanFeatureFlag, getFeatureFlag, getNumberFeatureFlag, getStringFeatureFlag, } from "./feature-flags.js";
 export { DEFAULT_BASE_URL, PROBLEM_CONTENT_TYPE, } from "./consts.js";
+export { VerificationClient, } from "./verification-clients.js";

package/lib/client.js

@@ -91,6 +91,8 @@ export class ReclaimClient {
         }
         const empty = res.status === 204
             || res.headers.get('content-length') === '0';
+        // Fetch exposes parsed JSON as `any`; OpenAPI owns the operation-specific
+        // response type, and callers can inspect the original Response if needed.
         const data = (empty ? undefined : await res.json());
         return { data, response: res };
     }

package/lib/enckeys.d.ts

@@ -11,7 +11,7 @@ export type DecryptionKey = Uint8Array;
 export declare function loadDecryptionKey(input: DecryptionKeyInput): DecryptionKey;
 /**
  * Convert an uncompressed secp256k1 public key (`0x04` + 128 hex) to the public
- * JWK the API stores and the Verification Client encrypts to — so callers only
+ * JWK the API stores and Builder encrypts to — so callers only
  * ever handle eth-native hex, never a JWK. Mirrors the `x`/`y` coordinate split
  * in `jwksFromPrivateKey` (./jwks.ts).
  */

package/lib/enckeys.js

@@ -2,7 +2,7 @@
  * secp256k1 (Ethereum) encryption-key helpers for ECIES result delivery.
  *
  * The org's encryption key is its **Ethereum public key** (secp256k1). The
- * Verification Client ECIES-encrypts the signed JWS to it (see ./result.ts) and
+ * Builder ECIES-encrypts the signed JWS to it (see ./result.ts) and
  * the Consumer decrypts with the matching eth **private key**. Eth-native `0x`
  * hex is used everywhere at the edges (the format MetaMask/ethers/wallets
  * emit); the wire/DB store the public key as a secp256k1 JWK
@@ -32,7 +32,7 @@ export function loadDecryptionKey(input) {
 }
 /**
  * Convert an uncompressed secp256k1 public key (`0x04` + 128 hex) to the public
- * JWK the API stores and the Verification Client encrypts to — so callers only
+ * JWK the API stores and Builder encrypts to — so callers only
  * ever handle eth-native hex, never a JWK. Mirrors the `x`/`y` coordinate split
  * in `jwksFromPrivateKey` (./jwks.ts).
  */

package/lib/encoding.d.ts

@@ -14,3 +14,7 @@ export declare function bytesToHex(bytes: Uint8Array): string;
 export declare function base64urlToBytes(s: string): Uint8Array;
 /** Encode bytes (or a UTF-8 string) as unpadded base64url. */
 export declare function b64url(input: Uint8Array | string): string;
+/** `value` without trailing `/`s. A loop, not `/\/+$/`: that regex backtracks
+ *  quadratically on a long run of slashes followed by anything else, and
+ *  some callers get attacker-supplied input (a JWS header's `iss`). */
+export declare function stripTrailingSlashes(value: string): string;

package/lib/encoding.js

@@ -48,3 +48,13 @@ export function b64url(input) {
         .replace(/\//g, '_')
         .replace(/=+$/, '');
 }
+/** `value` without trailing `/`s. A loop, not `/\/+$/`: that regex backtracks
+ *  quadratically on a long run of slashes followed by anything else, and
+ *  some callers get attacker-supplied input (a JWS header's `iss`). */
+export function stripTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 0x2f) {
+        end--;
+    }
+    return value.slice(0, end);
+}

package/lib/feature-flags.d.ts

@@ -0,0 +1,9 @@
+import type { VerificationRuntimeConfig } from './types/openapi.ts';
+/** Read a resolved session flag without assuming its runtime type. */
+export declare function getFeatureFlag(config: VerificationRuntimeConfig | null | undefined, key: string): unknown;
+/** Read a boolean flag, returning `fallback` for absent or mistyped values. */
+export declare function getBooleanFeatureFlag(config: VerificationRuntimeConfig | null | undefined, key: string, fallback?: boolean): boolean;
+/** Read a string flag, returning `fallback` for absent or mistyped values. */
+export declare function getStringFeatureFlag(config: VerificationRuntimeConfig | null | undefined, key: string, fallback: string): string;
+/** Read a numeric flag, returning `fallback` for absent or mistyped values. */
+export declare function getNumberFeatureFlag(config: VerificationRuntimeConfig | null | undefined, key: string, fallback: number): number;

package/lib/feature-flags.js

@@ -0,0 +1,19 @@
+/** Read a resolved session flag without assuming its runtime type. */
+export function getFeatureFlag(config, key) {
+    return config?.values[key];
+}
+/** Read a boolean flag, returning `fallback` for absent or mistyped values. */
+export function getBooleanFeatureFlag(config, key, fallback = false) {
+    const value = getFeatureFlag(config, key);
+    return typeof value === 'boolean' ? value : fallback;
+}
+/** Read a string flag, returning `fallback` for absent or mistyped values. */
+export function getStringFeatureFlag(config, key, fallback) {
+    const value = getFeatureFlag(config, key);
+    return typeof value === 'string' ? value : fallback;
+}
+/** Read a numeric flag, returning `fallback` for absent or mistyped values. */
+export function getNumberFeatureFlag(config, key, fallback) {
+    const value = getFeatureFlag(config, key);
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}

package/lib/index.d.ts

@@ -7,11 +7,11 @@ export { addressFromUncompressedPubkey, secp, } from './secp.ts';
 export { eip191Digest, signEip191 } from './eip191.ts';
 export { type CallbackBody, decodeJwsPayload, decryptCallback, type DeliveryEnvelope, encryptForEthPublicKey, type Jws, ResultVerificationError, type ResultProofOutcome, signResultJws, verifyJwsSignature, verifyResult, verifyResultFull, type VerifyResultFullOptions, type VerifyResultFullOutcome, type VerifyResultOptions, type VerifyResultOutcome, } from './result.ts';
 export { type DecryptionKey, type DecryptionKeyInput, generateEthKeypair, type GeneratedEthKeypair, loadDecryptionKey, pubkeyJwkToEthAddress, uncompressedPubkeyToJwk, } from './enckeys.ts';
-export { createReclaim, type CreateSessionInput, type CreateSessionTeeAttestation, type Reclaim, type ReclaimConfig, type ReceiveOptions, type ReceivedDelivery, type RegisterCallbackInput, type SetKeypairInput, TERMINAL_EVENTS, } from './reclaim.ts';
-export { fetchJwks, fetchJwksUrl, fetchReclaimJwks, type Jwk, jwksFromPrivateKey, jwkToUncompressedPublicKey, type ReclaimJwks, selectKey, selectVerificationResultKey, trustedAttestorAddresses, validateAttestorAddresses, } from './jwks.ts';
+export { type BindSessionTeeNonceInput, type CreateSessionInput, type ImportReclaimVerificationConfig, type ReclaimConfig, type ReclaimFlowFactory, ReclaimVerification, type ReclaimVerificationState, type ReceiveOptions, type ReceivedDelivery, type SessionFlow, } from './reclaim.ts';
+export { fetchJwks, fetchJwksUrl, fetchReclaimJwks, type Jwk, jwksFromPrivateKey, jwkToUncompressedPublicKey, type ReclaimJwks, selectKey, selectVerificationResultKey, trustedAttestorAddresses, validateAttestorAddresses, validateAttestorImageDigests, } from './jwks.ts';
 export { type NestedProofOutcome, verifyNestedProof, } from './attestor-proof.ts';
-export { type LegacyProof, type LegacyProofOutcome, type LegacyVerifyProofOptions, type ProofHashRequirement, proofHashes, verifyProof, } from './legacy-proof.ts';
+export { type ProofHashRequirement, type ReclaimRequestProof, type ReclaimRequestProofOutcome, type VerifyRequestProofOptions, proofHashes, verifyRequestProof, } from './request-proof.ts';
 export { type BuilderProofRecipe, proofHashesFromBuilderRecipe, } from './proof-recipe.ts';
 export { getHashFromProof, hashProofClaimParams, hashRequestSpec, type HttpProofParams, type ProofRequestSpec, } from './proof-hash.ts';
 export { builderTeeBindingPayload, BUILDER_TEE_BINDING_DOMAIN, createBuilderTeeBinding, createLegacyTeeNonceContext, deriveLegacySignatureTeeNonce, deriveLegacyTeeNonce, LEGACY_TEE_ATTESTATION_VERSION, LEGACY_TEE_NONCE_DOMAIN, legacyApplicationIdFromPrivateKey, signBuilderTeeBinding, type BuilderTeeBinding, type BuilderTeeBindingPayload, type LegacyTeeNonceContext, type LegacyTeeNonceData, type LegacyTeeNonceMode, } from './tee-binding.ts';
-export { KNOWN_VERIFICATION_CLIENTS, type KnownVerificationClientName, type KnownVerificationClientUrlMap, } from './verification-clients.ts';
+export { VerificationClient, } from './verification-clients.ts';

package/lib/index.js

@@ -7,11 +7,11 @@ export { addressFromUncompressedPubkey, secp, } from "./secp.js";
 export { eip191Digest, signEip191 } from "./eip191.js";
 export { decodeJwsPayload, decryptCallback, encryptForEthPublicKey, ResultVerificationError, signResultJws, verifyJwsSignature, verifyResult, verifyResultFull, } from "./result.js";
 export { generateEthKeypair, loadDecryptionKey, pubkeyJwkToEthAddress, uncompressedPubkeyToJwk, } from "./enckeys.js";
-export { createReclaim, TERMINAL_EVENTS, } from "./reclaim.js";
-export { fetchJwks, fetchJwksUrl, fetchReclaimJwks, jwksFromPrivateKey, jwkToUncompressedPublicKey, selectKey, selectVerificationResultKey, trustedAttestorAddresses, validateAttestorAddresses, } from "./jwks.js";
+export { ReclaimVerification, } from "./reclaim.js";
+export { fetchJwks, fetchJwksUrl, fetchReclaimJwks, jwksFromPrivateKey, jwkToUncompressedPublicKey, selectKey, selectVerificationResultKey, trustedAttestorAddresses, validateAttestorAddresses, validateAttestorImageDigests, } from "./jwks.js";
 export { verifyNestedProof, } from "./attestor-proof.js";
-export { proofHashes, verifyProof, } from "./legacy-proof.js";
+export { proofHashes, verifyRequestProof, } from "./request-proof.js";
 export { proofHashesFromBuilderRecipe, } from "./proof-recipe.js";
 export { getHashFromProof, hashProofClaimParams, hashRequestSpec, } from "./proof-hash.js";
 export { builderTeeBindingPayload, BUILDER_TEE_BINDING_DOMAIN, createBuilderTeeBinding, createLegacyTeeNonceContext, deriveLegacySignatureTeeNonce, deriveLegacyTeeNonce, LEGACY_TEE_ATTESTATION_VERSION, LEGACY_TEE_NONCE_DOMAIN, legacyApplicationIdFromPrivateKey, signBuilderTeeBinding, } from "./tee-binding.js";
-export { KNOWN_VERIFICATION_CLIENTS, } from "./verification-clients.js";
+export { VerificationClient, } from "./verification-clients.js";

package/lib/jwks.d.ts

@@ -9,10 +9,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';
 }
@@ -20,13 +16,15 @@ 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 declare function jwksFromPrivateKey(privateKeyHex?: string, metadata?: Pick<Jwk, 'x-reclaim-purpose' | 'x-reclaim-verification-client-id' | 'x-reclaim-verification-client-ids'>): {
+export declare function jwksFromPrivateKey(privateKeyHex?: string, metadata?: Pick<Jwk, 'x-reclaim-purpose'>): {
     keys: Jwk[];
 };
 /** Fetch the JWK set published at `<iss>/.well-known/jwks.json`. */
@@ -37,12 +35,14 @@ export declare function fetchJwksUrl(url: string, fetchImpl?: typeof fetch): Pro
 export declare function fetchReclaimJwks(url: string, fetchImpl?: typeof fetch): Promise<ReclaimJwks>;
 /** Find the key matching `kid` (case-insensitive — kids are ETH addresses). */
 export declare function selectKey(keys: Jwk[], kid: string): Jwk | undefined;
-/** Select a result key and enforce its Verification Client ownership. */
-export declare function selectVerificationResultKey(keys: Jwk[], kid: string, verificationClientId: string): Jwk | undefined;
+/** Select Builder's result-signing key and validate its JOSE metadata. */
+export declare function selectVerificationResultKey(keys: Jwk[], kid: string): Jwk | undefined;
 /** Return ETH addresses from keys explicitly registered for attestor proofs. */
 export declare function trustedAttestorAddresses(keys: Jwk[]): string[];
 /** Validate and normalize the JWKS address-only trust extension. */
 export declare function validateAttestorAddresses(addresses: string[]): string[];
+/** Validate and normalize sha256 image digests from a JWKS trust extension. */
+export declare function validateAttestorImageDigests(digests: string[]): string[];
 /**
  * Reconstruct the uncompressed secp256k1 public key (`0x04` + X + Y) from an
  * EC JWK's base64url `x`/`y` coordinates, for signature verification.

package/lib/jwks.js

@@ -1,12 +1,12 @@
 /**
  * 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.js";
+import { b64url, base64urlToBytes, bytesToHex, stripTrailingSlashes, } from "./encoding.js";
 import { addressFromUncompressedPubkey, secp } from "./secp.js";
 /**
- * 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.
  */
@@ -34,7 +34,7 @@ export function jwksFromPrivateKey(privateKeyHex, metadata = {}) {
 }
 /** Fetch the JWK set published at `<iss>/.well-known/jwks.json`. */
 export async function fetchJwks(iss, fetchImpl = fetch) {
-    const base = iss.replace(/\/+$/, '');
+    const base = stripTrailingSlashes(iss);
     return fetchJwksUrl(`${base}/.well-known/jwks.json`, fetchImpl);
 }
 /** Fetch a JWK set from an explicitly trusted registry URL. */
@@ -44,6 +44,7 @@ export async function fetchJwksUrl(url, fetchImpl = fetch) {
 }
 /** Fetch Builder's JWKS plus its namespaced attestor trust registry. */
 export async function fetchReclaimJwks(url, fetchImpl = fetch) {
+    assertSecureJwksUrl(url);
     const res = await fetchImpl(url);
     if (!res.ok) {
         throw new Error(`JWKS fetch failed for ${url}: HTTP ${res.status}`);
@@ -52,6 +53,7 @@ export async function fetchReclaimJwks(url, fetchImpl = fetch) {
     return {
         keys: body.keys ?? [],
         'x-reclaim-attestors': validateAttestorAddresses(body['x-reclaim-attestors'] ?? []),
+        'x-reclaim-attestor-image-digests': validateAttestorImageDigests(body['x-reclaim-attestor-image-digests'] ?? []),
     };
 }
 /** Find the key matching `kid` (case-insensitive — kids are ETH addresses). */
@@ -59,11 +61,16 @@ export function selectKey(keys, kid) {
     const want = kid.toLowerCase();
     return keys.find((k) => (k.kid ?? '').toLowerCase() === want);
 }
-/** Select a result key and enforce its Verification Client ownership. */
-export function selectVerificationResultKey(keys, kid, verificationClientId) {
+/** Select Builder's result-signing key and validate its JOSE metadata. */
+export function selectVerificationResultKey(keys, kid) {
     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)));
 }
 /** Return ETH addresses from keys explicitly registered for attestor proofs. */
 export function trustedAttestorAddresses(keys) {
@@ -94,6 +101,16 @@ export function validateAttestorAddresses(addresses) {
             return normalized;
         }))];
 }
+/** Validate and normalize sha256 image digests from a JWKS trust extension. */
+export function validateAttestorImageDigests(digests) {
+    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.
@@ -110,18 +127,22 @@ export function jwkToUncompressedPublicKey(jwk) {
     out.set(y, 33);
     return '0x' + bytesToHex(out);
 }
-function belongsToVerificationClient(key, verificationClientId) {
-    const one = key['x-reclaim-verification-client-id'];
-    const many = key['x-reclaim-verification-client-ids'];
-    if (one) {
-        return one === verificationClientId;
+function jwkMatchesKid(key) {
+    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) {
+    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) {
     return Uint8Array.from(Buffer.from(value.slice(2), 'hex'));

package/lib/launch/destination.d.ts

@@ -0,0 +1,14 @@
+import type { ParsedFlowUrl, VerificationTarget } from './target.ts';
+export interface DestinationOptions {
+    portalUrl?: string;
+    appLinkBaseUrl?: string;
+}
+export declare 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 declare 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 declare function appendSessionQuery(base: string, parsed: Pick<ParsedFlowUrl, 'sessionId' | 'diag'>): string;
+export declare function resolveDestinationUrl(target: VerificationTarget | undefined, parsed: ParsedFlowUrl, options: DestinationOptions): string;

package/lib/launch/destination.js

@@ -0,0 +1,89 @@
+/**
+ * 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.js";
+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, parsed) {
+    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) {
+    return stripTrailingSlashes(value);
+}
+export function resolveDestinationUrl(target, parsed, options) {
+    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/lib/launch/device.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 } from './environment.ts';
+export type DeviceKind = 'desktop' | 'ios' | 'android';
+export type DetectionConfidence = 'high' | 'low';
+export interface DeviceDetection {
+    device: DeviceKind;
+    confidence: DetectionConfidence;
+}
+/** Resolves the device this flow is running on, with a confidence a caller
+ *  can act on instead of a silent guess. */
+export declare function resolveDevice(env: LaunchEnvironment): DeviceDetection;

package/lib/launch/device.js

@@ -0,0 +1,168 @@
+/** 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, query) {
+    try {
+        return win?.matchMedia?.(query)?.matches ?? false;
+    }
+    catch {
+        return false;
+    }
+}
+function safeCssSupports(win, property, value) {
+    try {
+        return win?.CSS?.supports?.(property, value) ?? false;
+    }
+    catch {
+        return false;
+    }
+}
+function safeQuerySelector(env, selector) {
+    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) {
+    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;
+}
+/** Ported iOS/Android cascade. Only called once `scoreMobile` has decided the
+ *  device is mobile. */
+function guessMobileOs(env) {
+    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) {
+    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',
+    };
+}