@zkproofport-app/sdk 0.2.10 → 0.2.11

package/README.md

@@ -292,7 +292,7 @@ const relay = await sdk.createRelayRequest('coinbase_attestation', {
   dappIcon: 'https://myapp.com/icon.png',
   message: 'Verify your identity to continue',
   nonce: 'unique-nonce-123',  // Optional: replay prevention
-  returnScheme: 'mydapp://',  // Optional: mobile-only, see below
+  returnScheme: 'mydapp://',  // Optional: native apps only, see below
 });
 
 // relay.requestId  — Relay-issued UUID
@@ -303,48 +303,72 @@ const relay = await sdk.createRelayRequest('coinbase_attestation', {
 
 Every field of the third argument is optional: `message`, `dappName` and `dappIcon` are shown to the user in the ZKProofport app, `nonce` is a value of your own choosing that the relay refuses to accept twice, and `returnScheme` is described next.
 
-#### Switching back to your app: `returnScheme`
+#### Switching back: `returnScheme`
 
-By default the user stays in the ZKProofport app after generating a proof and switches back to your app themselves. Pass `returnScheme` and the ZKProofport app brings your app to the foreground once the proof has been delivered — the same handoff a wallet performs after a signature.
+When ZKProofport finishes a proof, the user is sitting in the ZKProofport app. `returnScheme` answers one question: **which app should come back to the foreground?**
+
+It names an app. It is not a URL, not a return address, and the proof is never sent to it — the proof still reaches you exactly as before, through `waitForProof()` / `waitForResult()`. This is the same handoff a wallet performs after a signature (`redirect.native`).
+
+**One form is accepted:**
+
+| Form | Example |
+|------|---------|
+| Bare custom scheme | `'mydapp://'` — an RFC 3986 scheme followed by exactly `://` |
+
+**If you are a native app**, pass the scheme your app registers:
 
 ```typescript
-// Native app: your own registered scheme
 await sdk.createRelayRequest('coinbase_attestation', { scope: 'myapp.com' }, {
   returnScheme: 'mydapp://',
 });
-
-// Web app: your own origin
-await sdk.createRelayRequest('coinbase_attestation', { scope: 'myapp.com' }, {
-  returnScheme: 'https://myapp.com',
-});
 ```
 
-**Only set it in the mobile deep-link flow.** The switch happens on the phone that generated the proof, so it makes sense only when that phone is also where the user started — i.e. when you navigated the browser to `relay.deepLink` on the same device. In the desktop QR flow the user is watching the desktop screen while the proof happens on their phone; opening a page or an app on the phone at that moment surfaces something nobody asked for. Gate it:
+**If you are a web page, pass nothing.** You have no app to come back to, so there is no value you can honestly put here — and the SDK handles the browser case for you:
 
 ```typescript
-const relay = await sdk.createRelayRequest('coinbase_attestation', { scope: 'myapp.com' },
-  ProofportSDK.isMobile() ? { returnScheme: 'https://myapp.com' } : {});
+// Correct. Do not pass returnScheme from a web page.
+await sdk.createRelayRequest('coinbase_attestation', { scope: 'myapp.com' });
 ```
 
-`returnScheme` is **not** a return address. It says which app to open, nothing more — the proof still reaches you the usual way, through `waitForProof()` / `waitForResult()`, and the ZKProofport app never posts anything to it.
+##### What the SDK does automatically
 
-Two shapes are accepted, and nothing else:
+With the option omitted, the SDK looks at the page's own user agent and decides:
 
-| Form | Example | Notes |
-|------|---------|-------|
-| Bare custom scheme | `'mydapp://'` | An RFC 3986 scheme followed by exactly `://` |
-| https origin | `'https://myapp.com'`, `'https://myapp.com:8443'` | Host (and optional port) only |
+| Where your page is running | What the SDK sends | What the user sees when the proof is done |
+|---|---|---|
+| **Chrome for iOS** (`CriOS`) | `googlechrome://` | Chrome comes forward on **the tab they were already reading** — no new tab, no reload, page state intact |
+| **Firefox for iOS** (`FxiOS`) | `firefox://` | Same: Firefox comes forward on the tab they were already reading |
+| **Android**, any browser | nothing | The ZKProofport app puts itself in the background and the browser resumes exactly as it was |
+| **Safari, Brave, Arc, Edge, Opera on iOS** | nothing | ZKProofport tells them the proof was delivered and to switch back; the system "‹ Back" breadcrumb is still at the top left |
+| **In-app webviews** (KakaoTalk, Naver, Line, Instagram) | nothing | Same notice. Any scheme would destroy the page they are on |
+| **Desktop** | nothing | This is the QR flow: the proof happens on a different device, and your page updates over the relay socket |
 
-Anything else throws before the SDK makes a single network call — no challenge is consumed, so nothing is wasted on a typo:
+Only Chrome and Firefox are auto-detected, each from a positive UA token, because they are the two iOS browsers whose bare scheme is **verified in their own source** to bring the app forward without navigating anywhere. There is no Safari equivalent. Brave and Arc are indistinguishable from Safari on iOS, so guessing would eject those users into a browser they were not using — worse than doing nothing. Edge and Opera are closed source and stay out until someone can show their bare schemes behave the same way.
 
-- a path, query string or fragment (`'mydapp://transfer?to=0x...'`, `'https://myapp.com/done'`), which is what keeps a request from driving your app to a specific action
+An explicit `returnScheme` always wins; the SDK never overrides a value you set.
+
+##### `https://` origins are not accepted
+
+An https origin such as `'https://myapp.com'` used to be allowed. **It is now rejected** by the SDK, the relay and the ZKProofport app alike.
+
+Opening one does not return anybody anywhere. The OS hands the URL to the browser, and the browser opens a **new tab** on a freshly loaded page — the tab your user actually started in is left behind, along with everything in it, including the socket waiting for the proof you just generated. The round trip the field exists to complete was the thing it broke.
+
+##### What is rejected
+
+These throw before the SDK makes a single network call, so no challenge is consumed and nothing is wasted on a typo:
+
+- **https and http origins** — `'https://myapp.com'`, `'https://myapp.com:8443'` (see above)
+- **bare `https://` and `http://`** — a browser with no page to open is not a return target
+- a host, path, query string or fragment — `'mydapp://transfer?to=0x...'` — which is what stops a request driving your app to a specific action rather than just opening it
 - an empty or whitespace-containing value, or one longer than 128 characters
-- userinfo (`'https://user:pass@myapp.com'`) and non-ASCII hosts (use punycode)
-- `http://` and other schemes the OS treats specially: `about`, `blob`, `content`, `data`, `facetime`, `facetime-audio`, `file`, `ftp`, `intent`, `javascript`, `jar`, `mailto`, `sms`, `tel`, `vbscript`
+- non-ASCII schemes (use punycode if you somehow need one)
+- schemes the OS treats specially: `about`, `blob`, `content`, `data`, `facetime`, `facetime-audio`, `file`, `ftp`, `intent`, `javascript`, `jar`, `mailto`, `sms`, `tel`, `vbscript`
 
 The value is matched case-insensitively and stored lowercased by the relay.
 
-Omit `returnScheme` and nothing changes: the request is created without it and the user stays in the ZKProofport app when the proof is done. There is no auto-switch when proof generation fails either — the error has to be read in the ZKProofport app first.
+##### When nothing happens
+
+There is no auto-switch when proof generation **fails** — the error has to be read in the ZKProofport app first. And when no target is sent and none can be inferred, ZKProofport shows the user a notice saying the proof was delivered and to switch back themselves. That is the intended outcome on iOS outside Chrome, not a bug.
 
 **OIDC Domain Attestation:**
 
@@ -860,7 +884,7 @@ import type {
 | `MdlKrAgeInputs` | Inputs for `mdl_kr_age`: `{ scope, ageThreshold }` |
 | `MdlKrRegionInputs` | Inputs for `mdl_kr_region`: `{ scope, targetRegion }` |
 | `CircuitInputs` | Union of every input type above (plus an empty-input form for circuits that need nothing from the dApp) |
-| `ProofRequest` | Request object: `requestId`, `circuit`, `inputs`, `createdAt`, plus optional `message`, `dappName`, `dappIcon`, `returnScheme`, `expiresAt` |
+| `ProofRequest` | Request object: `requestId`, `circuit`, `inputs`, `createdAt`, plus optional `message`, `dappName`, `dappIcon`, `returnScheme` (a bare scheme such as `mydapp://`), `expiresAt` |
 | `ProofResponse` | What `verifyResponseOnChain()` takes: `requestId`, `circuit`, `status`, and — when completed — `proof`, `publicInputs`, `verifierAddress`, `chainId`; `error` when it failed. `numPublicInputs` and `timestamp` also exist but the relay never fills them, so omit them. Field by field in [Step 6](#step-6-read-the-result) |
 | `QRCodeOptions` | QR customization: `width`, `margin`, `darkColor`, `lightColor`, `errorCorrectionLevel` |
 | `VerifierContract` | Verifier contract info: `{ address, chainId, abi }` |
@@ -996,12 +1020,12 @@ try {
 
 try {
   await sdk.createRelayRequest('coinbase_attestation', { scope: 'app.com' }, {
-    returnScheme: 'https://myapp.com/done',
+    returnScheme: 'https://myapp.com',
   });
 } catch (err) {
-  // "returnScheme must be a bare custom scheme such as "mydapp://" or an https
-  //  origin such as "https://myapp.com" — paths, query strings and fragments are
-  //  not accepted"  (thrown before any network call)
+  // "returnScheme must be a bare custom scheme such as "mydapp://" — hosts,
+  //  paths, query strings and fragments are not accepted, and an https URL is
+  //  not a return target"  (thrown before any network call)
 }
 
 try {

package/dist/ProofportSDK.d.ts

@@ -762,8 +762,10 @@ export declare class ProofportSDK {
      * @param options - Request options (message, dappName, dappIcon, nonce, returnScheme)
      * @param options.returnScheme - Which app the ZKProofport app should switch back
      *   to once it has finished. Put **your own** deep link scheme here — the bare
-     *   scheme your app registers, e.g. `'mydapp://'`. A web app can instead pass its
-     *   own https origin, e.g. `'https://myapp.com'`.
+     *   scheme your app registers, e.g. `'mydapp://'`. Only a native app has an
+     *   answer to this question; a web app omits the option entirely, because
+     *   opening its https origin would launch a new browser tab on a fresh page
+     *   rather than return the user to the tab they started from.
      *
      *   This is intentionally **not** a URL and not a return address: no path, query
      *   string or fragment is accepted, and the ZKProofport app never sends the proof
@@ -772,14 +774,26 @@ export declare class ProofportSDK {
      *   "which app should come back to the foreground", exactly like the
      *   `redirect.native` value a wallet uses to hand control back after signing.
      *
-     *   **Omit it and nothing changes** — the user simply stays in the ZKProofport app
-     *   after the proof and switches back manually. There is no auto-switch on proof
-     *   failure either; only on success and on the user declining the request.
+     *   **Omit it and the SDK decides for you.** When the request is created from a
+     *   page running in Chrome for iOS (`CriOS`) or Firefox for iOS (`FxiOS`), the
+     *   SDK fills in `'googlechrome://'` or `'firefox://'` by itself: opening either
+     *   scheme bare brings that browser forward without navigating, so the user lands
+     *   back on the tab they were already reading. Every other browser sends nothing,
+     *   because nothing safe exists to send — Safari has no such scheme, and Brave
+     *   and Arc are indistinguishable from Safari on iOS, so guessing would eject the
+     *   user into the wrong browser.
+     *   On Android nothing is needed at all: the ZKProofport app brings itself to the
+     *   back and the browser resumes exactly as it was. When no target is sent and
+     *   none can be inferred, the ZKProofport app tells the user the proof was
+     *   delivered and lets them switch back themselves.
+     *
+     *   There is no auto-switch on proof failure; only on success and on the user
+     *   declining the request.
      *
      *   Rejected with an error before the request is sent: empty or whitespace values,
-     *   anything longer than 128 characters, values containing a path/query/fragment,
-     *   and the `http:`, `file:`, `data:`, `javascript:`, `intent:`, `tel:`, `sms:`,
-     *   `mailto:` families.
+     *   anything longer than 128 characters, values carrying a host/path/query/fragment
+     *   (including https origins such as `'https://myapp.com'`), and the `http:`,
+     *   `file:`, `data:`, `javascript:`, `intent:`, `tel:`, `sms:`, `mailto:` families.
      * @returns Promise resolving to RelayProofRequest with requestId, deepLink, pollUrl
      * @throws Error if signer not set, returnScheme is malformed, or the relay request fails
      *

package/dist/deeplink.d.ts

@@ -197,12 +197,82 @@ export declare const MAX_RETURN_SCHEME_LENGTH = 128;
  * value fails fast in the integrator's own code instead of coming back as a
  * relay 400. The relay re-validates and is the authority.
  *
+ * One shape is accepted: a bare custom scheme such as `mydapp://`. It names an
+ * app to switch back to, never a page to visit — so hosts, paths and query
+ * strings are rejected, and an https URL is not a valid value. A web page has
+ * no app to return to and simply omits the field.
+ *
  * @param value - Candidate return target
  * @returns `null` when acceptable, otherwise a human-readable error message
  *
  * @internal
  */
 export declare function validateReturnScheme(value: unknown): string | null;
+/**
+ * The return target to use when the integrator named none.
+ *
+ * Only the requesting PAGE can answer "which browser is this?" — iOS gives the
+ * ZKProofport app nothing to work with (`sourceApplication` is nil across team
+ * identifiers, and there is no public API to foreground an app by bundle id).
+ * So the detection has to happen here, in the SDK, and travel with the request.
+ *
+ * Two cases are detected, each from a POSITIVE token, and each verified in the
+ * browser's own source to foreground WITHOUT navigating anywhere:
+ *
+ *   Chrome for iOS  (`CriOS/`) -> `googlechrome://`
+ *   Firefox for iOS (`FxiOS/`) -> `firefox://`
+ *
+ * The BARE scheme is the point in both cases: it carries no URL, so the browser
+ * comes forward with nothing to open and the user lands on the tab they were
+ * already reading — no new tab, no navigation, no reload, JS state intact.
+ *
+ * Chrome: `ios/chrome/app/startup/chrome_app_startup_parameters.mm` replaces
+ * the scheme with `http`, producing `http://`, which fails GURL validation
+ * (`if (!externalURL.is_valid()) return nil;`), so the startup parameters are
+ * nil and there is nothing to open.
+ *
+ * Firefox: `firefox://` has an empty host, and
+ * `Coordinators/Router/RouteBuilder.swift` resolves the host through
+ * `DeeplinkInput.Host(rawValue: "")`, which is nil because no case has an empty
+ * raw value (`Coordinators/Router/DeeplinkInput.swift`). The scheme is not http
+ * either, so `makeRoute(url:)` falls to its final `else { return nil }`, and
+ * `SceneDelegate.handleOpenURL` then hits `guard let route = ... else
+ * { return }` and does nothing at all. Verified on the warm path — the browser
+ * is already running, which is always true here, because the user came from a
+ * page in it.
+ *
+ * Everything else deliberately returns undefined, and that is not a gap:
+ *
+ *   - Safari has no equivalent. No scheme means "just come forward";
+ *     `https://<url>` navigates and opens a new tab, `x-web-search://` opens a
+ *     search page. Both lose the user's page.
+ *   - Brave and Arc for iOS are UNDETECTABLE. Brave ships no UA token and
+ *     identifies itself only via Client Hints, which WebKit does not implement,
+ *     so it looks exactly like Safari. Inferring "Safari" by elimination and
+ *     firing a Safari-ish scheme would throw Brave and Arc users into a browser
+ *     they were not using — strictly worse than doing nothing.
+ *   - In-app webviews (KakaoTalk, Naver, Line, Instagram) are not tabs at all.
+ *     Any scheme destroys the page; the system "< Back to X" breadcrumb is the
+ *     only thing that preserves it.
+ *   - Edge (`EdgiOS`) and Opera (`OPiOS` / `OPT`) for iOS are NOT included.
+ *     Both are closed source, so `microsoft-edge://` and `opera-http://` cannot
+ *     be checked the way Chrome's and Firefox's were. Their bare schemes are
+ *     plausible analogues, and that is exactly why they stay out: an unverified
+ *     guess that opens a new tab is the bug this field exists to avoid. Add one
+ *     only with evidence that it foregrounds WITHOUT navigating.
+ *   - Android needs nothing: the ZKProofport app brings itself to the back
+ *     (`moveTaskToBack`), which resumes the browser exactly as it was.
+ *
+ * When this returns undefined the field is omitted and the ZKProofport app
+ * tells the user the proof was delivered and to switch back themselves.
+ *
+ * @param userAgent - override, for tests. Defaults to `navigator.userAgent`.
+ *   Returns undefined when there is no navigator at all (Node, SSR).
+ * @returns a scheme that is safe to open, or undefined to send nothing
+ *
+ * @internal
+ */
+export declare function detectReturnScheme(userAgent?: string): string | undefined;
 export declare function validateProofRequest(request: ProofRequest): {
     valid: boolean;
     error?: string;

package/dist/index.esm.js

@@ -613,8 +613,16 @@ function validateMdlInputs(circuit, inputs) {
 const MAX_RETURN_SCHEME_LENGTH = 128;
 /** RFC 3986 scheme (`ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )`) followed by exactly `://`. */
 const BARE_SCHEME_RE = /^[a-z][a-z0-9+.-]*:\/\/$/;
-/** `https://host[:port]` with no userinfo, path, query or fragment. */
-const HTTPS_ORIGIN_RE = /^https:\/\/[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+(:[0-9]{1,5})?$/;
+/**
+ * Schemes we refuse even in the bare `scheme://` shape.
+ *
+ * `http` and `https` are the back door the shape rule alone leaves open: with
+ * no host, `https://` is shaped exactly like a bare custom scheme and would
+ * otherwise pass. A browser pointed at nowhere is not a return target, and
+ * accepting it would re-open the URL-shaped door this field just closed.
+ * `googlechrome://` and `firefox://` are deliberately NOT denied — bare, they
+ * foreground that browser without navigating, which is the whole point.
+ */
 const DENIED_RETURN_SCHEMES = new Set([
     'about',
     'blob',
@@ -625,6 +633,7 @@ const DENIED_RETURN_SCHEMES = new Set([
     'file',
     'ftp',
     'http',
+    'https',
     'intent',
     'javascript',
     'jar',
@@ -638,6 +647,11 @@ const DENIED_RETURN_SCHEMES = new Set([
  * value fails fast in the integrator's own code instead of coming back as a
  * relay 400. The relay re-validates and is the authority.
  *
+ * One shape is accepted: a bare custom scheme such as `mydapp://`. It names an
+ * app to switch back to, never a page to visit — so hosts, paths and query
+ * strings are rejected, and an https URL is not a valid value. A web page has
+ * no app to return to and simply omits the field.
+ *
  * @param value - Candidate return target
  * @returns `null` when acceptable, otherwise a human-readable error message
  *
@@ -658,11 +672,8 @@ function validateReturnScheme(value) {
         return 'returnScheme must not contain whitespace';
     }
     const normalized = value.toLowerCase();
-    if (HTTPS_ORIGIN_RE.test(normalized)) {
-        return null;
-    }
     if (!BARE_SCHEME_RE.test(normalized)) {
-        return 'returnScheme must be a bare custom scheme such as "mydapp://" or an https origin such as "https://myapp.com" — paths, query strings and fragments are not accepted';
+        return 'returnScheme must be a bare custom scheme such as "mydapp://" — hosts, paths, query strings and fragments are not accepted, and an https URL is not a return target';
     }
     const schemeName = normalized.slice(0, normalized.indexOf(':'));
     if (DENIED_RETURN_SCHEMES.has(schemeName)) {
@@ -670,6 +681,90 @@ function validateReturnScheme(value) {
     }
     return null;
 }
+/**
+ * The return target to use when the integrator named none.
+ *
+ * Only the requesting PAGE can answer "which browser is this?" — iOS gives the
+ * ZKProofport app nothing to work with (`sourceApplication` is nil across team
+ * identifiers, and there is no public API to foreground an app by bundle id).
+ * So the detection has to happen here, in the SDK, and travel with the request.
+ *
+ * Two cases are detected, each from a POSITIVE token, and each verified in the
+ * browser's own source to foreground WITHOUT navigating anywhere:
+ *
+ *   Chrome for iOS  (`CriOS/`) -> `googlechrome://`
+ *   Firefox for iOS (`FxiOS/`) -> `firefox://`
+ *
+ * The BARE scheme is the point in both cases: it carries no URL, so the browser
+ * comes forward with nothing to open and the user lands on the tab they were
+ * already reading — no new tab, no navigation, no reload, JS state intact.
+ *
+ * Chrome: `ios/chrome/app/startup/chrome_app_startup_parameters.mm` replaces
+ * the scheme with `http`, producing `http://`, which fails GURL validation
+ * (`if (!externalURL.is_valid()) return nil;`), so the startup parameters are
+ * nil and there is nothing to open.
+ *
+ * Firefox: `firefox://` has an empty host, and
+ * `Coordinators/Router/RouteBuilder.swift` resolves the host through
+ * `DeeplinkInput.Host(rawValue: "")`, which is nil because no case has an empty
+ * raw value (`Coordinators/Router/DeeplinkInput.swift`). The scheme is not http
+ * either, so `makeRoute(url:)` falls to its final `else { return nil }`, and
+ * `SceneDelegate.handleOpenURL` then hits `guard let route = ... else
+ * { return }` and does nothing at all. Verified on the warm path — the browser
+ * is already running, which is always true here, because the user came from a
+ * page in it.
+ *
+ * Everything else deliberately returns undefined, and that is not a gap:
+ *
+ *   - Safari has no equivalent. No scheme means "just come forward";
+ *     `https://<url>` navigates and opens a new tab, `x-web-search://` opens a
+ *     search page. Both lose the user's page.
+ *   - Brave and Arc for iOS are UNDETECTABLE. Brave ships no UA token and
+ *     identifies itself only via Client Hints, which WebKit does not implement,
+ *     so it looks exactly like Safari. Inferring "Safari" by elimination and
+ *     firing a Safari-ish scheme would throw Brave and Arc users into a browser
+ *     they were not using — strictly worse than doing nothing.
+ *   - In-app webviews (KakaoTalk, Naver, Line, Instagram) are not tabs at all.
+ *     Any scheme destroys the page; the system "< Back to X" breadcrumb is the
+ *     only thing that preserves it.
+ *   - Edge (`EdgiOS`) and Opera (`OPiOS` / `OPT`) for iOS are NOT included.
+ *     Both are closed source, so `microsoft-edge://` and `opera-http://` cannot
+ *     be checked the way Chrome's and Firefox's were. Their bare schemes are
+ *     plausible analogues, and that is exactly why they stay out: an unverified
+ *     guess that opens a new tab is the bug this field exists to avoid. Add one
+ *     only with evidence that it foregrounds WITHOUT navigating.
+ *   - Android needs nothing: the ZKProofport app brings itself to the back
+ *     (`moveTaskToBack`), which resumes the browser exactly as it was.
+ *
+ * When this returns undefined the field is omitted and the ZKProofport app
+ * tells the user the proof was delivered and to switch back themselves.
+ *
+ * @param userAgent - override, for tests. Defaults to `navigator.userAgent`.
+ *   Returns undefined when there is no navigator at all (Node, SSR).
+ * @returns a scheme that is safe to open, or undefined to send nothing
+ *
+ * @internal
+ */
+function detectReturnScheme(userAgent) {
+    const ua = (typeof navigator === 'undefined' ? undefined : navigator.userAgent);
+    if (typeof ua !== 'string' || ua.length === 0) {
+        return undefined;
+    }
+    // A device token is required alongside the browser token. `CriOS` and `FxiOS`
+    // are already iOS-only and unambiguous on their own, but pairing them with the
+    // device token costs nothing and stops a synthetic or spoofed desktop user
+    // agent from producing a mobile-only scheme.
+    if (!/(iPhone|iPad|iPod)/.test(ua)) {
+        return undefined;
+    }
+    if (/CriOS\//.test(ua)) {
+        return 'googlechrome://';
+    }
+    if (/FxiOS\//.test(ua)) {
+        return 'firefox://';
+    }
+    return undefined;
+}
 function validateProofRequest(request) {
     if (!request.requestId) {
         return { valid: false, error: 'Missing requestId' };
@@ -5091,8 +5186,13 @@ class ProofportSDK {
             body.dappIcon = options.dappIcon;
         if (options.nonce)
             body.nonce = options.nonce;
-        if (options.returnScheme)
-            body.returnScheme = options.returnScheme;
+        // An explicit value always wins. Otherwise ask the SDK to work one out from
+        // the page's own user agent — the requesting page is the only side that can
+        // (iOS tells the app nothing about who launched it). Both paths can end in
+        // "send nothing", which is a legitimate outcome, not a failure.
+        const returnScheme = options.returnScheme ?? detectReturnScheme();
+        if (returnScheme)
+            body.returnScheme = returnScheme;
         const response = await fetch(`${this.relayUrl}/api/v1/proof/request`, {
             method: 'POST',
             headers: {
@@ -5396,8 +5496,10 @@ class ProofportSDK {
  * @param options - Request options (message, dappName, dappIcon, nonce, returnScheme)
  * @param options.returnScheme - Which app the ZKProofport app should switch back
  *   to once it has finished. Put **your own** deep link scheme here — the bare
- *   scheme your app registers, e.g. `'mydapp://'`. A web app can instead pass its
- *   own https origin, e.g. `'https://myapp.com'`.
+ *   scheme your app registers, e.g. `'mydapp://'`. Only a native app has an
+ *   answer to this question; a web app omits the option entirely, because
+ *   opening its https origin would launch a new browser tab on a fresh page
+ *   rather than return the user to the tab they started from.
  *
  *   This is intentionally **not** a URL and not a return address: no path, query
  *   string or fragment is accepted, and the ZKProofport app never sends the proof
@@ -5406,14 +5508,26 @@ class ProofportSDK {
  *   "which app should come back to the foreground", exactly like the
  *   `redirect.native` value a wallet uses to hand control back after signing.
  *
- *   **Omit it and nothing changes** — the user simply stays in the ZKProofport app
- *   after the proof and switches back manually. There is no auto-switch on proof
- *   failure either; only on success and on the user declining the request.
+ *   **Omit it and the SDK decides for you.** When the request is created from a
+ *   page running in Chrome for iOS (`CriOS`) or Firefox for iOS (`FxiOS`), the
+ *   SDK fills in `'googlechrome://'` or `'firefox://'` by itself: opening either
+ *   scheme bare brings that browser forward without navigating, so the user lands
+ *   back on the tab they were already reading. Every other browser sends nothing,
+ *   because nothing safe exists to send — Safari has no such scheme, and Brave
+ *   and Arc are indistinguishable from Safari on iOS, so guessing would eject the
+ *   user into the wrong browser.
+ *   On Android nothing is needed at all: the ZKProofport app brings itself to the
+ *   back and the browser resumes exactly as it was. When no target is sent and
+ *   none can be inferred, the ZKProofport app tells the user the proof was
+ *   delivered and lets them switch back themselves.
+ *
+ *   There is no auto-switch on proof failure; only on success and on the user
+ *   declining the request.
  *
  *   Rejected with an error before the request is sent: empty or whitespace values,
- *   anything longer than 128 characters, values containing a path/query/fragment,
- *   and the `http:`, `file:`, `data:`, `javascript:`, `intent:`, `tel:`, `sms:`,
- *   `mailto:` families.
+ *   anything longer than 128 characters, values carrying a host/path/query/fragment
+ *   (including https origins such as `'https://myapp.com'`), and the `http:`,
+ *   `file:`, `data:`, `javascript:`, `intent:`, `tel:`, `sms:`, `mailto:` families.
  * @returns Promise resolving to RelayProofRequest with requestId, deepLink, pollUrl
  * @throws Error if signer not set, returnScheme is malformed, or the relay request fails
  *