@zkproofport-app/sdk 0.2.10 → 0.2.12

package/dist/index.js

@@ -56,20 +56,26 @@ const DEEP_LINK_HOSTS = {
  * ```typescript
  * const metadata = CIRCUIT_METADATA['coinbase_attestation'];
  * console.log(metadata.name); // "Coinbase KYC"
- * console.log(metadata.publicInputsCount); // 2
+ * console.log(metadata.publicInputsCount); // 128
  * ```
  */
 const CIRCUIT_METADATA = {
     coinbase_attestation: {
         name: 'Coinbase KYC',
         description: 'Prove Coinbase identity verification',
-        publicInputsCount: 2,
+        // 4 x `pub [u8; 32]` in coinbase-attestation/src/main.nr, flattened to
+        // bytes: signal_hash, signer_list_merkle_root, scope, nullifier.
+        // Read 2 here until 2026-09-04, which was wrong under any reading —
+        // the circuit has never had two public inputs, logical or flattened.
+        publicInputsCount: 128,
         publicInputNames: ['signal_hash', 'signer_list_merkle_root'],
     },
     coinbase_country_attestation: {
         name: 'Coinbase Country',
         description: 'Prove Coinbase country verification',
-        publicInputsCount: 14,
+        // 32 + 32 + (10 x 2) + 1 + 1 + 32 + 32 = 150, counted off
+        // coinbase-country-attestation/src/main.nr. Read 14 until 2026-09-04.
+        publicInputsCount: 150,
         publicInputNames: ['signal_hash', 'signer_list_merkle_root', 'country_list', 'country_list_length', 'is_included'],
     },
     oidc_domain_attestation: {
@@ -78,8 +84,22 @@ const CIRCUIT_METADATA = {
         publicInputsCount: 148,
         publicInputNames: ['pubkey_modulus_limbs', 'domain', 'scope', 'nullifier', 'provider'],
     },
-    // Korea Mobile ID (mDL) circuits. Counts are byte-flattened field totals
-    // from the compiled circuit ABIs: [u8; 32] arrays contribute 32 inputs each.
+    // Planned circuit — the identifier is reserved and the circuit exists, but it
+    // is not officially supported yet. See CIRCUIT_SUPPORT_STATUS in ./circuits.
+    // Forked from coinbase_attestation and shares its four public inputs, so the
+    // count is the byte-flattened total (4 x [u8; 32] = 128), matching the
+    // COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT indices below. The
+    // coinbase_attestation entry above reports a legacy logical count of 2 and is
+    // left as-is for backwards compatibility.
+    giwa_attestation: {
+        name: 'GIWA Attestation',
+        description: 'Prove GIWA identity verification (planned — not officially supported yet)',
+        publicInputsCount: 128,
+        publicInputNames: ['signal_hash', 'signer_list_merkle_root', 'scope', 'nullifier'],
+    },
+    // Korea Mobile ID (mDL) circuits. Planned — not officially supported yet.
+    // Counts are byte-flattened field totals from the compiled circuit ABIs:
+    // [u8; 32] arrays contribute 32 inputs each.
     mdl_kr_ownership: {
         name: 'Korea Mobile ID — Ownership',
         description: "Prove valid Korean mobile driver's license ownership with selective disclosure",
@@ -618,8 +638,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',
@@ -630,6 +658,7 @@ const DENIED_RETURN_SCHEMES = new Set([
     'file',
     'ftp',
     'http',
+    'https',
     'intent',
     'javascript',
     'jar',
@@ -643,6 +672,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
  *
@@ -663,11 +697,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)) {
@@ -675,6 +706,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' };
@@ -2229,8 +2344,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: {
@@ -2534,8 +2654,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
@@ -2544,14 +2666,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
  *
@@ -2577,13 +2711,167 @@ ProofportSDK.WALLET_SIGNATURE_CIRCUITS = [
     'coinbase_country_attestation',
 ];
 
+/**
+ * Canonical ZKProofport circuit identifiers.
+ *
+ * This module is the single source of truth for circuit IDs. Every other layer
+ * — the mobile app, the demo, the relay, server-side provers — reads its list
+ * from here instead of keeping a private copy that silently drifts.
+ *
+ * It has **no imports and no dependencies**, so it can be pulled in on its own:
+ *
+ * ```typescript
+ * import { CIRCUIT_IDS, isCircuitId } from '@zkproofport-app/sdk/circuits';
+ * ```
+ *
+ * The same names are also re-exported from the package root
+ * (`@zkproofport-app/sdk`) for callers that already import the SDK.
+ *
+ * ## Identifiers are canonical and case-sensitive
+ *
+ * Each ID is the circuit's `name` in its `Nargo.toml`, verbatim. The format is
+ * lowercase with underscores. Hyphenated spellings (`coinbase-kyc`,
+ * `mdl-kr-age`) are directory or UI route names in other repositories — they
+ * are **not** circuit IDs, and passing one produces a nullifier mismatch or a
+ * failed on-chain lookup rather than a clear error.
+ */
+/**
+ * Canonical circuit identifiers, keyed by a stable constant name.
+ *
+ * Prefer these constants over string literals so a rename is a compile error
+ * rather than a runtime surprise.
+ *
+ * @example
+ * ```typescript
+ * import { CIRCUIT_IDS } from '@zkproofport-app/sdk/circuits';
+ *
+ * const relay = await sdk.createRelayRequest(CIRCUIT_IDS.COINBASE_ATTESTATION, {
+ *   scope: 'myapp.com',
+ * });
+ * ```
+ */
+const CIRCUIT_IDS = Object.freeze({
+    /** Coinbase KYC attestation. Officially supported. */
+    COINBASE_ATTESTATION: 'coinbase_attestation',
+    /** Coinbase country attestation (inclusion / exclusion). Officially supported. */
+    COINBASE_COUNTRY_ATTESTATION: 'coinbase_country_attestation',
+    /** OIDC email-domain attestation. Officially supported. */
+    OIDC_DOMAIN_ATTESTATION: 'oidc_domain_attestation',
+    /** GIWA attestation. Planned — not officially supported yet. */
+    GIWA_ATTESTATION: 'giwa_attestation',
+    /** Korea Mobile ID ownership. Planned — not officially supported yet. */
+    MDL_KR_OWNERSHIP: 'mdl_kr_ownership',
+    /** Korea Mobile ID age threshold. Planned — not officially supported yet. */
+    MDL_KR_AGE: 'mdl_kr_age',
+    /** Korea Mobile ID si/do region. Planned — not officially supported yet. */
+    MDL_KR_REGION: 'mdl_kr_region',
+});
+/**
+ * Support status for every circuit.
+ *
+ * The record is exhaustive over {@link CircuitId}: adding an identifier without
+ * giving it a status is a compile error, so this list cannot drift from
+ * {@link CIRCUIT_IDS}.
+ *
+ * @example
+ * ```typescript
+ * import { CIRCUIT_SUPPORT_STATUS } from '@zkproofport-app/sdk/circuits';
+ *
+ * CIRCUIT_SUPPORT_STATUS.coinbase_attestation; // 'supported'
+ * CIRCUIT_SUPPORT_STATUS.mdl_kr_age;           // 'planned'
+ * ```
+ */
+const CIRCUIT_SUPPORT_STATUS = Object.freeze({
+    coinbase_attestation: 'supported',
+    coinbase_country_attestation: 'supported',
+    oidc_domain_attestation: 'supported',
+    giwa_attestation: 'planned',
+    mdl_kr_ownership: 'planned',
+    mdl_kr_age: 'planned',
+    mdl_kr_region: 'planned',
+});
+/**
+ * Every canonical circuit identifier, in declaration order.
+ *
+ * Includes circuits that are still `planned`. Use {@link SUPPORTED_CIRCUIT_IDS}
+ * when you only want the ones that are officially supported today.
+ */
+const ALL_CIRCUIT_IDS = Object.freeze(Object.values(CIRCUIT_IDS));
+/**
+ * Circuits that are officially supported today: the two Coinbase circuits and
+ * OIDC domain attestation.
+ *
+ * Derived from {@link CIRCUIT_SUPPORT_STATUS}, so it cannot fall out of sync.
+ */
+const SUPPORTED_CIRCUIT_IDS = Object.freeze(ALL_CIRCUIT_IDS.filter((id) => CIRCUIT_SUPPORT_STATUS[id] === 'supported'));
+/**
+ * Circuits whose identifiers are reserved but which are not officially
+ * supported yet: GIWA attestation and the three Korea Mobile ID circuits.
+ *
+ * Derived from {@link CIRCUIT_SUPPORT_STATUS}, so it cannot fall out of sync.
+ */
+const PLANNED_CIRCUIT_IDS = Object.freeze(ALL_CIRCUIT_IDS.filter((id) => CIRCUIT_SUPPORT_STATUS[id] === 'planned'));
+/**
+ * Narrows an unknown value to a canonical circuit identifier.
+ *
+ * Returns `false` for hyphenated route names such as `'coinbase-kyc'`, which
+ * are not circuit IDs.
+ *
+ * @example
+ * ```typescript
+ * isCircuitId('coinbase_attestation'); // true
+ * isCircuitId('coinbase-kyc');         // false
+ * ```
+ */
+function isCircuitId(value) {
+    return typeof value === 'string' && ALL_CIRCUIT_IDS.includes(value);
+}
+/**
+ * Narrows an unknown value to a circuit identifier that is officially supported
+ * today. Planned circuits return `false`.
+ *
+ * @example
+ * ```typescript
+ * isSupportedCircuitId('oidc_domain_attestation'); // true
+ * isSupportedCircuitId('mdl_kr_age');              // false — planned
+ * ```
+ */
+function isSupportedCircuitId(value) {
+    return isCircuitId(value) && CIRCUIT_SUPPORT_STATUS[value] === 'supported';
+}
+/**
+ * Returns the support status of a circuit.
+ *
+ * @param circuit - A canonical circuit identifier.
+ * @throws Error when the value is not a canonical circuit identifier.
+ *
+ * @example
+ * ```typescript
+ * getCircuitSupportStatus('giwa_attestation'); // 'planned'
+ * ```
+ */
+function getCircuitSupportStatus(circuit) {
+    if (!isCircuitId(circuit)) {
+        throw new Error(`Unknown circuit '${String(circuit)}'. Expected one of: ${ALL_CIRCUIT_IDS.join(', ')}`);
+    }
+    return CIRCUIT_SUPPORT_STATUS[circuit];
+}
+
+exports.ALL_CIRCUIT_IDS = ALL_CIRCUIT_IDS;
+exports.CIRCUIT_IDS = CIRCUIT_IDS;
+exports.CIRCUIT_SUPPORT_STATUS = CIRCUIT_SUPPORT_STATUS;
 exports.COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT = COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT;
 exports.COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT = COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT;
 exports.MDL_KR_PUBLIC_INPUT_LAYOUT = MDL_KR_PUBLIC_INPUT_LAYOUT;
 exports.OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT = OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT;
+exports.PLANNED_CIRCUIT_IDS = PLANNED_CIRCUIT_IDS;
 exports.ProofportSDK = ProofportSDK;
+exports.SUPPORTED_CIRCUIT_IDS = SUPPORTED_CIRCUIT_IDS;
 exports.default = ProofportSDK;
 exports.extractDomainFromPublicInputs = extractDomainFromPublicInputs;
 exports.extractNullifierFromPublicInputs = extractNullifierFromPublicInputs;
 exports.extractScopeFromPublicInputs = extractScopeFromPublicInputs;
+exports.getCircuitSupportStatus = getCircuitSupportStatus;
+exports.isCircuitId = isCircuitId;
+exports.isSupportedCircuitId = isSupportedCircuitId;
 //# sourceMappingURL=index.js.map