@zkproofport-app/sdk 0.2.8 → 0.2.9

package/dist/ProofportSDK.d.ts

@@ -759,9 +759,29 @@ export declare class ProofportSDK {
      *
      * @param circuit - Circuit type identifier
      * @param inputs - Circuit-specific inputs
-     * @param options - Request options (message, dappName, dappIcon, nonce)
+     * @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'`.
+     *
+     *   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
+     *   there. The proof still comes back to you the same way it always did — over the
+     *   relay, via `waitForProof()` / `waitForResult()`. `returnScheme` only answers
+     *   "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.
+     *
+     *   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.
      * @returns Promise resolving to RelayProofRequest with requestId, deepLink, pollUrl
-     * @throws Error if signer not set or relay request fails
+     * @throws Error if signer not set, returnScheme is malformed, or the relay request fails
      *
      * @example
      * ```typescript
@@ -770,7 +790,7 @@ export declare class ProofportSDK {
      *
      * const relay = await sdk.createRelayRequest('coinbase_attestation', {
      *   scope: 'myapp.com'
-     * }, { dappName: 'My DApp' });
+     * }, { dappName: 'My DApp', returnScheme: 'mydapp://' });
      *
      * // Generate QR code from relay deep link
      * const qr = await sdk.generateQRCode(relay.deepLink);
@@ -785,6 +805,7 @@ export declare class ProofportSDK {
         dappName?: string;
         dappIcon?: string;
         nonce?: string;
+        returnScheme?: string;
     }): Promise<RelayProofRequest>;
     /**
      * Polls the relay for proof result status.

package/dist/deeplink.d.ts

@@ -187,6 +187,22 @@ export declare function isProofportDeepLink(url: string, scheme?: string): boole
  * @returns Error message string, or null when the inputs are valid
  */
 export declare function validateMdlInputs(circuit: 'mdl_kr_ownership' | 'mdl_kr_age' | 'mdl_kr_region', inputs: CircuitInputs): string | null;
+/**
+ * Longest accepted `returnScheme` value.
+ * Kept in sync with proofport-relay `src/returnScheme.ts`.
+ */
+export declare const MAX_RETURN_SCHEME_LENGTH = 128;
+/**
+ * Validates a `returnScheme` before it is sent to the relay, so a malformed
+ * 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.
+ *
+ * @param value - Candidate return target
+ * @returns `null` when acceptable, otherwise a human-readable error message
+ *
+ * @internal
+ */
+export declare function validateReturnScheme(value: unknown): string | null;
 export declare function validateProofRequest(request: ProofRequest): {
     valid: boolean;
     error?: string;

package/dist/index.esm.js

@@ -606,6 +606,70 @@ function validateMdlInputs(circuit, inputs) {
     }
     return null;
 }
+/**
+ * Longest accepted `returnScheme` value.
+ * Kept in sync with proofport-relay `src/returnScheme.ts`.
+ */
+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})?$/;
+const DENIED_RETURN_SCHEMES = new Set([
+    'about',
+    'blob',
+    'content',
+    'data',
+    'facetime',
+    'facetime-audio',
+    'file',
+    'ftp',
+    'http',
+    'intent',
+    'javascript',
+    'jar',
+    'mailto',
+    'sms',
+    'tel',
+    'vbscript',
+]);
+/**
+ * Validates a `returnScheme` before it is sent to the relay, so a malformed
+ * 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.
+ *
+ * @param value - Candidate return target
+ * @returns `null` when acceptable, otherwise a human-readable error message
+ *
+ * @internal
+ */
+function validateReturnScheme(value) {
+    if (typeof value !== 'string') {
+        return 'returnScheme must be a string';
+    }
+    if (value.length === 0) {
+        return 'returnScheme must not be empty';
+    }
+    // Length is checked before any regex so a huge string never reaches the matcher.
+    if (value.length > MAX_RETURN_SCHEME_LENGTH) {
+        return `returnScheme must be at most ${MAX_RETURN_SCHEME_LENGTH} characters`;
+    }
+    if (/\s/.test(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';
+    }
+    const schemeName = normalized.slice(0, normalized.indexOf(':'));
+    if (DENIED_RETURN_SCHEMES.has(schemeName)) {
+        return `returnScheme "${schemeName}" is not allowed`;
+    }
+    return null;
+}
 function validateProofRequest(request) {
     if (!request.requestId) {
         return { valid: false, error: 'Missing requestId' };
@@ -4999,6 +5063,14 @@ class ProofportSDK {
                 throw new Error(`${mdlError} (circuit: ${circuit})`);
             }
         }
+        // Return target: validated before we burn a challenge, so a typo surfaces
+        // as a local error instead of a relay 400 on the second round trip.
+        if (options.returnScheme !== undefined) {
+            const returnSchemeError = validateReturnScheme(options.returnScheme);
+            if (returnSchemeError) {
+                throw new Error(returnSchemeError);
+            }
+        }
         // Get challenge + requestId from relay
         const { requestId, challenge } = await this.getChallenge();
         const body = {
@@ -5019,6 +5091,8 @@ class ProofportSDK {
             body.dappIcon = options.dappIcon;
         if (options.nonce)
             body.nonce = options.nonce;
+        if (options.returnScheme)
+            body.returnScheme = options.returnScheme;
         const response = await fetch(`${this.relayUrl}/api/v1/proof/request`, {
             method: 'POST',
             headers: {
@@ -5319,9 +5393,29 @@ class ProofportSDK {
  *
  * @param circuit - Circuit type identifier
  * @param inputs - Circuit-specific inputs
- * @param options - Request options (message, dappName, dappIcon, nonce)
+ * @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'`.
+ *
+ *   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
+ *   there. The proof still comes back to you the same way it always did — over the
+ *   relay, via `waitForProof()` / `waitForResult()`. `returnScheme` only answers
+ *   "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.
+ *
+ *   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.
  * @returns Promise resolving to RelayProofRequest with requestId, deepLink, pollUrl
- * @throws Error if signer not set or relay request fails
+ * @throws Error if signer not set, returnScheme is malformed, or the relay request fails
  *
  * @example
  * ```typescript
@@ -5330,7 +5424,7 @@ class ProofportSDK {
  *
  * const relay = await sdk.createRelayRequest('coinbase_attestation', {
  *   scope: 'myapp.com'
- * }, { dappName: 'My DApp' });
+ * }, { dappName: 'My DApp', returnScheme: 'mydapp://' });
  *
  * // Generate QR code from relay deep link
  * const qr = await sdk.generateQRCode(relay.deepLink);