@zkproofport-app/sdk 0.5.0-beta.1 → 0.5.0-beta.3

package/dist/index.js

@@ -25,6 +25,49 @@ const RELAY_URLS = {
     staging: 'https://stg-relay.zkproofport.app',
     local: 'http://localhost:4001',
 };
+/**
+ * The chain each circuit is verified on, per environment. Complete: a circuit
+ * added to the SDK is a compile error here until somebody names its chain.
+ *
+ * Mirrors the mobile app's `CIRCUIT_NETWORKS` (proofport-app
+ * src/config/contracts.ts), because a proof is checked where the app said its
+ * verifier is: Base for the Coinbase and OIDC circuits, GIWA Sepolia for GIWA
+ * and Dojang (testnet-only), Base Sepolia for Korea Mobile ID (testnet-only).
+ * The ADDRESS on that chain always comes from core's pinned table, never from
+ * a proof response.
+ */
+const VERIFICATION_CHAINS = {
+    production: {
+        coinbase_attestation: 8453,
+        coinbase_country_attestation: 8453,
+        oidc_domain_attestation: 8453,
+        giwa_attestation: 91342,
+        dojang_playground: 91342,
+        mdl_kr_ownership: 84532,
+        mdl_kr_age: 84532,
+        mdl_kr_region: 84532,
+    },
+    staging: {
+        coinbase_attestation: 84532,
+        coinbase_country_attestation: 84532,
+        oidc_domain_attestation: 84532,
+        giwa_attestation: 91342,
+        dojang_playground: 91342,
+        mdl_kr_ownership: 84532,
+        mdl_kr_age: 84532,
+        mdl_kr_region: 84532,
+    },
+    local: {
+        coinbase_attestation: 84532,
+        coinbase_country_attestation: 84532,
+        oidc_domain_attestation: 84532,
+        giwa_attestation: 91342,
+        dojang_playground: 91342,
+        mdl_kr_ownership: 84532,
+        mdl_kr_age: 84532,
+        mdl_kr_region: 84532,
+    },
+};
 /**
  * Default deep link URL scheme for ZKProofport mobile app.
  * Used to construct deep link URLs that open the mobile app.
@@ -83,8 +126,10 @@ const CIRCUIT_METADATA = {
     oidc_domain_attestation: {
         name: 'OIDC Domain',
         description: 'Prove email domain affiliation via OIDC JWT',
-        publicInputsCount: 148,
-        publicInputNames: ['pubkey_modulus_limbs', 'domain', 'scope', 'nullifier', 'provider'],
+        // v2: 148 v1 fields, then aud_hash (32), nonce_mode (1), nonce_binding
+        // (32), now (1). oidc-domain-attestation/src/main.nr.
+        publicInputsCount: 214,
+        publicInputNames: ['pubkey_modulus_limbs', 'domain', 'scope', 'nullifier', 'provider', 'aud_hash', 'nonce_mode', 'nonce_binding', 'now'],
     },
     // Planned circuit — the identifier is reserved and the circuit exists, but it
     // is not officially supported yet. See CIRCUIT_SUPPORT_STATUS in ./circuits.
@@ -1098,6 +1143,12 @@ async function fetchVerificationKey(circuit, timeoutMs) {
  * Needs no setup from the caller: the verifier ships with this SDK and is
  * loaded on first use.
  *
+ * For `oidc_domain_attestation` it first checks the token's audience, nonce and
+ * time (core's `checkOidcPolicy`, against `options.request` when given) and the
+ * proof's RSA key against the provider's published JWKS (core's
+ * `checkOidcProviderKey`); any refusal, or a JWKS that cannot be fetched, is
+ * `{ valid: false }`.
+ *
  * @param circuit - Canonical circuit identifier
  * @param proof - Proof bytes as hex, WITHOUT public inputs (as the relay sends it)
  * @param publicInputs - Public inputs as hex strings, in circuit order
@@ -1116,6 +1167,18 @@ async function fetchVerificationKey(circuit, timeoutMs) {
  */
 async function verifyProofOffChain(circuit, proof, publicInputs, options = {}) {
     const timeoutMs = options.timeoutMs ?? 30000;
+    if (!circuits.isCircuitId(circuit)) {
+        return { valid: false, error: `Unknown circuit '${circuit}'. Known: ${circuits.ALL_CIRCUIT_IDS.join(', ')}.` };
+    }
+    // Before Barretenberg, and for the same reason as on-chain: a proof can be
+    // mathematically valid and still mean nothing, because some circuits take
+    // their trust anchor as a public input the prover chooses. For OIDC that is
+    // the RSA key -- see core's oidcProviderKeys. Checked here so a dApp that
+    // verifies off-chain gets the same answer as one that verifies on-chain.
+    const issuer = await core.checkProofIssuer(circuit, publicInputs, { request: options.request });
+    if (!issuer.ok) {
+        return { valid: false, error: issuer.error };
+    }
     // A REQUIRED dependency, loaded lazily.
     //
     // It was briefly an optional peer dependency, on the reasoning that the WASM
@@ -1254,24 +1317,41 @@ class ProofportSDK {
      */
     constructor(config = {}) {
         this.pendingRequests = new Map();
+        /**
+         * requestId -> scope of the relay requests this instance created, so that
+         * verifyResponse* can check an OIDC proof's request-bound nonce without the
+         * dApp passing the request back in. Oldest entries go first past
+         * {@link ProofportSDK.MAX_REMEMBERED_RELAY_REQUESTS}.
+         */
+        this.relayRequests = new Map();
         this.signer = null;
         this.socket = null;
+        /**
+         * Set by {@link ProofportSDK.create} from its environment preset. It decides
+         * which chain a proof is verified on when the dApp configured no verifier
+         * for the circuit; a custom-config SDK has none and must configure one.
+         */
+        this.environment = null;
         this.config = {
             scheme: config.scheme || DEFAULT_SCHEME,
             verifiers: config.verifiers || {},
         };
         this.relayUrl = config.relayUrl || '';
+        if (config.environment !== undefined) {
+            if (!Object.prototype.hasOwnProperty.call(VERIFICATION_CHAINS, config.environment)) {
+                throw new Error(`Unknown environment '${config.environment}'. Known: ${Object.keys(VERIFICATION_CHAINS).join(', ')}.`);
+            }
+            this.environment = config.environment;
+        }
     }
     // ============ Request Creation ============
     /**
      * @internal
-     * Creates a Coinbase KYC verification proof request.
-     *
-     * Generates a proof request for verifying Coinbase KYC status without revealing
-     * the actual attestation data. The proof confirms the user has passed Coinbase KYC
-     * while maintaining privacy through zero-knowledge proofs.
+     * Creates a proof request for a circuit whose dapp-side input is a scope
+     * (Coinbase KYC, OIDC domain, GIWA, Dojang), keeping that circuit's id.
      *
-     * @param inputs - Circuit inputs for Coinbase KYC
+     * @param circuit - The circuit requested; it is the request's circuit
+     * @param inputs - Circuit inputs; `scope` is required (and `domain` for OIDC)
      * @param inputs.scope - Application-specific scope (e.g., domain name)
      * @param options - Request configuration options
   
@@ -1286,7 +1366,7 @@ class ProofportSDK {
      *
      * @example
      * ```typescript
-     * const request = sdk.createCoinbaseKycRequest({
+     * const request = sdk.createScopedRequest('coinbase_attestation', {
      *   scope: 'myapp.com'
      * }, {
      *   dappName: 'My DApp',
@@ -1296,13 +1376,34 @@ class ProofportSDK {
      * const deepLink = sdk.getDeepLinkUrl(request);
      * ```
      */
-    createCoinbaseKycRequest(inputs, options = {}) {
-        if (!inputs.scope) {
-            throw new Error('scope is required for coinbase_attestation circuit');
+    createScopedRequest(circuit, inputs, options = {}) {
+        const scope = inputs.scope;
+        if (typeof scope !== 'string' || scope.trim() === '') {
+            throw new Error(`scope is required for ${circuit} circuit`);
+        }
+        if (circuit === 'oidc_domain_attestation') {
+            const domain = inputs.domain;
+            if (typeof domain !== 'string' || domain.trim() === '') {
+                throw new Error('domain is required for oidc_domain_attestation circuit');
+            }
+        }
+        const action = inputs.action;
+        const binding = circuits.circuitActionBinding(circuit);
+        if (binding === 'none' && action !== undefined) {
+            throw new Error(`${circuit} has no action inputs, so an action sent with it would not be proved.`);
+        }
+        if (binding === 'required' || (binding === 'optional' && action !== undefined)) {
+            const actionError = typedAction.validateTypedAction(action);
+            if (actionError)
+                throw new Error(`${actionError} (circuit: ${circuit})`);
         }
         const request = {
             requestId: generateRequestId(),
-            circuit: 'coinbase_attestation',
+            // The circuit asked for, always. This used to be the literal
+            // 'coinbase_attestation', and every circuit that was not country or mDL
+            // was routed here -- a GIWA, Dojang or OIDC request silently became a
+            // Coinbase KYC request.
+            circuit,
             inputs,
             message: options.message,
             dappName: options.dappName,
@@ -1399,16 +1500,17 @@ class ProofportSDK {
      * ```
      */
     createProofRequest(circuit, inputs, options = {}) {
-        if (circuit === 'coinbase_country_attestation') {
-            return this.createCoinbaseCountryRequest(inputs, options);
-        }
-        else if (circuit === 'mdl_kr_ownership' ||
-            circuit === 'mdl_kr_age' ||
-            circuit === 'mdl_kr_region') {
-            return this.createMdlKrRequest(circuit, inputs, options);
+        if (!circuits.isCircuitId(circuit)) {
+            throw new Error(`Unknown circuit '${circuit}'. Known: ${circuits.ALL_CIRCUIT_IDS.join(', ')}.`);
         }
-        else {
-            return this.createCoinbaseKycRequest(inputs, options);
+        const builder = ProofportSDK.REQUEST_BUILDERS[circuit];
+        switch (builder) {
+            case 'country':
+                return this.createCoinbaseCountryRequest(inputs, options);
+            case 'mdl':
+                return this.createMdlKrRequest(circuit, inputs, options);
+            case 'scoped':
+                return this.createScopedRequest(circuit, inputs, options);
         }
     }
     /**
@@ -1783,10 +1885,66 @@ class ProofportSDK {
      * }
      * ```
      */
-    async verifyOnChain(circuit, proof, publicInputs, providerOrSigner) {
+    async verifyOnChain(circuit, proof, publicInputs, providerOrSigner, options = {}) {
         const parsedProof = core.parseProofForOnChain(proof, publicInputs, publicInputs.length);
-        const customVerifier = this.config.verifiers[circuit];
-        return core.verifyProofOnChain(circuit, parsedProof, providerOrSigner, customVerifier);
+        return core.verifyProofOnChain(circuit, parsedProof, providerOrSigner, this.verifierTarget(circuit), undefined, {
+            request: options.request,
+        });
+    }
+    /**
+     * The request an `oidc_domain_attestation` response answers: the one the
+     * caller passed, else the relay request this instance created under the
+     * response's requestId. `{ error }` when there is none, or when the two
+     * disagree -- an OIDC proof made with a request-bound nonce is only
+     * meaningful against the request it was bound to, so a response this SDK
+     * cannot place is refused rather than checked without it.
+     */
+    oidcRequestFor(response, explicit) {
+        if (explicit !== undefined) {
+            if (explicit === null || typeof explicit !== 'object' || explicit.requestId !== response.requestId) {
+                return {
+                    error: `The request passed in (${JSON.stringify(explicit?.requestId)}) is not the one this response answers (${JSON.stringify(response.requestId)}).`,
+                };
+            }
+            return { request: explicit };
+        }
+        const remembered = this.relayRequests.get(response.requestId);
+        if (!remembered) {
+            return {
+                error: `No request ${JSON.stringify(response.requestId)} was created by this SDK instance, so the OIDC proof's ` +
+                    'nonce cannot be checked against it. Pass { request: { scope, requestId } } -- the scope and relay ' +
+                    'requestId of the request you created.',
+            };
+        }
+        return { request: remembered };
+    }
+    /** @internal Remember a relay request's scope for verifyResponse*. */
+    rememberRelayRequest(requestId, scope) {
+        if (typeof requestId !== 'string' || typeof scope !== 'string')
+            return;
+        this.relayRequests.delete(requestId);
+        this.relayRequests.set(requestId, { scope, requestId });
+        while (this.relayRequests.size > ProofportSDK.MAX_REMEMBERED_RELAY_REQUESTS) {
+            const oldest = this.relayRequests.keys().next().value;
+            this.relayRequests.delete(oldest);
+        }
+    }
+    /**
+     * The verifier for a circuit: the one the dApp configured, otherwise the
+     * pinned deployment on the chain this SDK's environment verifies that
+     * circuit on. `undefined` when neither exists, which core reports as an
+     * error. Never anything a proof response said.
+     */
+    verifierTarget(circuit) {
+        const configured = this.config.verifiers[circuit];
+        if (configured)
+            return configured;
+        if (this.environment === null)
+            return undefined;
+        const chains = VERIFICATION_CHAINS[this.environment];
+        if (!Object.prototype.hasOwnProperty.call(chains, circuit))
+            return undefined;
+        return { chainId: chains[circuit] };
     }
     /**
      * Verifies a proof response on-chain using the deployed verifier contract.
@@ -1796,6 +1954,9 @@ class ProofportSDK {
      *
      * @param response - ProofResponse object from parseResponse()
      * @param providerOrSigner - ethers v6 Provider or Signer (defaults to base mainnet public RPC)
+     * @param options.request - For `oidc_domain_attestation`: the `{ scope, requestId }`
+     *   the response answers. Not needed for a relay request this SDK instance
+     *   created; an OIDC response this instance cannot place is refused without it.
      *
      * @returns Promise resolving to verification result with valid boolean and optional error message
      *
@@ -1822,17 +1983,26 @@ class ProofportSDK {
      * });
      * ```
      */
-    async verifyResponseOnChain(response, providerOrSigner) {
+    async verifyResponseOnChain(response, providerOrSigner, options = {}) {
         if (response.status !== 'completed' || !response.proof || !response.publicInputs) {
             return { valid: false, error: 'Invalid or incomplete response' };
         }
+        let request;
+        if (response.circuit === 'oidc_domain_attestation') {
+            const found = this.oidcRequestFor(response, options.request);
+            if ('error' in found)
+                return { valid: false, error: found.error };
+            request = found.request;
+        }
         const parsedProof = core.parseProofForOnChain(response.proof, response.publicInputs, response.publicInputs.length);
-        const customVerifier = this.config.verifiers[response.circuit];
-        const responseVerifier = {
+        // The response's verifierAddress and chainId are a claim to check, never
+        // the contract to call: whoever wrote the response would otherwise pick
+        // the judge. A claim that differs from the pinned or configured verifier
+        // is refused.
+        return core.verifyProofOnChain(response.circuit, parsedProof, providerOrSigner, this.verifierTarget(response.circuit), {
             verifierAddress: response.verifierAddress,
             chainId: response.chainId,
-        };
-        return core.verifyProofOnChain(response.circuit, parsedProof, providerOrSigner, customVerifier, responseVerifier);
+        }, { request });
     }
     /**
      * Verifies a proof response off-chain, against the circuit's verification key.
@@ -1862,7 +2032,14 @@ class ProofportSDK {
         if (response.status !== 'completed' || !response.proof || !response.publicInputs) {
             return { valid: false, error: 'Invalid or incomplete response' };
         }
-        return verifyProofOffChain(response.circuit, response.proof, response.publicInputs, options);
+        let request;
+        if (response.circuit === 'oidc_domain_attestation') {
+            const found = this.oidcRequestFor(response, options?.request);
+            if ('error' in found)
+                return { valid: false, error: found.error };
+            request = found.request;
+        }
+        return verifyProofOffChain(response.circuit, response.proof, response.publicInputs, { ...options, request });
     }
     // ============ Utility Methods ============
     /**
@@ -1883,8 +2060,17 @@ class ProofportSDK {
      * ```
      */
     getVerifierAddress(circuit) {
-        const customVerifier = this.config.verifiers[circuit];
-        return core.getVerifierAddress(circuit, customVerifier);
+        return this.requireVerifier(circuit).address;
+    }
+    /** The configured or pinned verifier, or an error saying why there is none. */
+    requireVerifier(circuit) {
+        const target = this.verifierTarget(circuit);
+        if (!target) {
+            throw new Error(`No verifier configured for circuit '${circuit}'. Configure one in the SDK's verifiers option, or create the SDK with ProofportSDK.create() to use the pinned deployment.`);
+        }
+        if ('address' in target)
+            return { address: target.address, chainId: target.chainId };
+        return { address: core.getPinnedVerifier(circuit, target.chainId).address, chainId: target.chainId };
     }
     /**
      * Gets the blockchain chain ID where the verifier contract is deployed.
@@ -1904,8 +2090,7 @@ class ProofportSDK {
      * ```
      */
     getVerifierChainId(circuit) {
-        const customVerifier = this.config.verifiers[circuit];
-        return core.getVerifierChainId(circuit, customVerifier);
+        return this.requireVerifier(circuit).chainId;
     }
     /**
      * Gets metadata for a specific circuit type.
@@ -2052,17 +2237,20 @@ class ProofportSDK {
      */
     static create(envOrConfig) {
         if (typeof envOrConfig === 'undefined') {
-            return new ProofportSDK({ relayUrl: RELAY_URLS.production });
+            return ProofportSDK.forEnvironment('production');
         }
         if (typeof envOrConfig === 'string') {
-            const relayUrl = RELAY_URLS[envOrConfig];
-            if (!relayUrl) {
-                throw new Error(`Unknown environment: ${envOrConfig}. Use 'production', 'staging', or 'local'.`);
-            }
-            return new ProofportSDK({ relayUrl });
+            return ProofportSDK.forEnvironment(envOrConfig);
         }
         return new ProofportSDK(envOrConfig);
     }
+    /** @internal An SDK on an environment preset's relay, verifying on that environment's chains. */
+    static forEnvironment(env) {
+        if (!Object.prototype.hasOwnProperty.call(RELAY_URLS, env)) {
+            throw new Error(`Unknown environment: ${env}. Use 'production', 'staging', or 'local'.`);
+        }
+        return new ProofportSDK({ relayUrl: RELAY_URLS[env], environment: env });
+    }
     /**
      * Detects if the code is running on a mobile device.
      *
@@ -2196,7 +2384,10 @@ class ProofportSDK {
     // calling createRelayRequest() for it with no signer got no local error and
     // a relay 401 two round trips later.
     static needsWalletSignature(circuit) {
-        return circuits.CIRCUIT_NEEDS_WALLET_SIGNATURE[circuit] === true;
+        if (!circuits.isCircuitId(circuit)) {
+            throw new Error(`Unknown circuit '${circuit}'. Expected: ${circuits.ALL_CIRCUIT_IDS.join(', ')}`);
+        }
+        return circuits.CIRCUIT_NEEDS_WALLET_SIGNATURE[circuit];
     }
     async createRelayRequest(circuit, inputs, options = {}) {
         if (!this.relayUrl) {
@@ -2287,7 +2478,9 @@ class ProofportSDK {
             const error = await response.json().catch(() => ({ error: `HTTP ${response.status}` }));
             throw new Error(error.error || `Relay request failed: HTTP ${response.status}`);
         }
-        return await response.json();
+        const created = await response.json();
+        this.rememberRelayRequest(created.requestId, scope);
+        return created;
     }
     /**
      * Polls the relay for proof result status.
@@ -2570,6 +2763,23 @@ class ProofportSDK {
         return core.extractDomainFromPublicInputs(publicInputs, circuit);
     }
 }
+/** Bound on {@link relayRequests}; a dApp that verifies later can pass the request explicitly. */
+ProofportSDK.MAX_REMEMBERED_RELAY_REQUESTS = 1000;
+/**
+ * How each circuit's request is built and checked. Keyed by circuit id and
+ * exhaustive over it, so a new circuit is a compile error here instead of
+ * falling through to another circuit's builder.
+ */
+ProofportSDK.REQUEST_BUILDERS = {
+    coinbase_attestation: 'scoped',
+    coinbase_country_attestation: 'country',
+    oidc_domain_attestation: 'scoped',
+    giwa_attestation: 'scoped',
+    dojang_playground: 'scoped',
+    mdl_kr_ownership: 'mdl',
+    mdl_kr_age: 'mdl',
+    mdl_kr_region: 'mdl',
+};
 
 Object.defineProperty(exports, "COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT", {
     enumerable: true,
@@ -2583,10 +2793,46 @@ Object.defineProperty(exports, "MDL_KR_PUBLIC_INPUT_LAYOUT", {
     enumerable: true,
     get: function () { return core.MDL_KR_PUBLIC_INPUT_LAYOUT; }
 });
+Object.defineProperty(exports, "OIDC_ALLOWED_AUDIENCES", {
+    enumerable: true,
+    get: function () { return core.OIDC_ALLOWED_AUDIENCES; }
+});
 Object.defineProperty(exports, "OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT", {
     enumerable: true,
     get: function () { return core.OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT; }
 });
+Object.defineProperty(exports, "OIDC_NONCE_DOMAIN", {
+    enumerable: true,
+    get: function () { return core.OIDC_NONCE_DOMAIN; }
+});
+Object.defineProperty(exports, "OIDC_NOW_MAX_AGE_SECONDS", {
+    enumerable: true,
+    get: function () { return core.OIDC_NOW_MAX_AGE_SECONDS; }
+});
+Object.defineProperty(exports, "OIDC_NOW_MAX_FUTURE_SECONDS", {
+    enumerable: true,
+    get: function () { return core.OIDC_NOW_MAX_FUTURE_SECONDS; }
+});
+Object.defineProperty(exports, "OIDC_V1_PUBLIC_INPUT_COUNT", {
+    enumerable: true,
+    get: function () { return core.OIDC_V1_PUBLIC_INPUT_COUNT; }
+});
+Object.defineProperty(exports, "OIDC_V2_PUBLIC_INPUT_COUNT", {
+    enumerable: true,
+    get: function () { return core.OIDC_V2_PUBLIC_INPUT_COUNT; }
+});
+Object.defineProperty(exports, "PINNED_VERIFIERS", {
+    enumerable: true,
+    get: function () { return core.PINNED_VERIFIERS; }
+});
+Object.defineProperty(exports, "checkOidcPolicy", {
+    enumerable: true,
+    get: function () { return core.checkOidcPolicy; }
+});
+Object.defineProperty(exports, "deriveOidcNonceBinding", {
+    enumerable: true,
+    get: function () { return core.deriveOidcNonceBinding; }
+});
 Object.defineProperty(exports, "extractDomainFromPublicInputs", {
     enumerable: true,
     get: function () { return core.extractDomainFromPublicInputs; }
@@ -2599,6 +2845,14 @@ Object.defineProperty(exports, "extractScopeFromPublicInputs", {
     enumerable: true,
     get: function () { return core.extractScopeFromPublicInputs; }
 });
+Object.defineProperty(exports, "getPinnedVerifier", {
+    enumerable: true,
+    get: function () { return core.getPinnedVerifier; }
+});
+Object.defineProperty(exports, "oidcAudienceHash", {
+    enumerable: true,
+    get: function () { return core.oidcAudienceHash; }
+});
 Object.defineProperty(exports, "ALL_CIRCUIT_IDS", {
     enumerable: true,
     get: function () { return circuits.ALL_CIRCUIT_IDS; }