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

package/README.md

@@ -784,7 +784,9 @@ Verify the proof cryptographically by calling the deployed Solidity verifier con
 
 `verifyResponseOnChain` checks the proof against the verifier contract the SDK ships with for that circuit. Which contract judges a proof is never taken from the proof's own response: the SDK carries the deployed verifiers, generated from the circuits' deployment records, and a response whose `verifierAddress` or `chainId` differs from them is refused rather than checked elsewhere. If you configure your own verifier in the SDK's `verifiers` option, that one is used instead.
 
-For OIDC domain proofs the SDK also checks that the proof was made with a signing key Google or Microsoft actually publishes. That key is part of the proof's public inputs, so a proof made with a self-generated key would otherwise pass the contract. The SDK fetches the provider's published keys, caches them as the provider's own cache headers allow, and returns `{ valid: false, error }` when the key is not among them or the keys cannot be fetched. Every verify method does this; there is nothing to call separately.
+For OIDC domain proofs the SDK first checks what the proof says about the sign-in token: it must have been issued to a ZKProofport sign-in client (not to some other website), the proof must have been made within the last 15 minutes (and not more than 5 minutes ahead of your clock), and a proof made by the ZKProofport app must carry the nonce of **your** request — so a proof made for another request cannot be replayed as the answer to yours. For a request you created with `createRelayRequest` on the same SDK instance this happens automatically. If you verify in a different process (or after a restart), pass the request back: `sdk.verifyResponseOnChain(response, provider, { request: { scope, requestId } })`, with the scope you requested and the `requestId` the relay returned; without it an OIDC response is refused. `verifyOnChain` and `verifyResponseOffChain` take the same `request` option.
+
+The SDK also checks that the proof was made with a signing key Google or Microsoft actually publishes. That key is part of the proof's public inputs, so a proof made with a self-generated key would otherwise pass the contract. The SDK fetches the provider's published keys, caches them as the provider's own cache headers allow, and returns `{ valid: false, error }` when the key is not among them or the keys cannot be fetched. Every verify method does this; there is nothing to call separately.
 
 For Coinbase KYC, Coinbase country and GIWA proofs the SDK checks that the attestation's signer belongs to the published signer set: the proof carries the root of the signer list it was made against, and a proof made against any other list is refused with `{ valid: false, error }`. This too runs in every verify method.
 
@@ -932,7 +934,7 @@ import {
 const scope = extractScopeFromPublicInputs(publicInputs, 'coinbase_attestation');
 const nullifier = extractNullifierFromPublicInputs(publicInputs, 'coinbase_attestation');
 
-// OIDC domain attestation uses a different public input layout (148 fields)
+// OIDC domain attestation uses a different public input layout (214 fields)
 const oidcScope = extractScopeFromPublicInputs(publicInputs, 'oidc_domain_attestation');
 const oidcNullifier = extractNullifierFromPublicInputs(publicInputs, 'oidc_domain_attestation');
 
@@ -1156,7 +1158,7 @@ const signalHash = toBytes32(publicInputs.slice(L.SIGNAL_HASH_START, L.SIGNAL_HA
 
 The country list and the `is_included` flag are public inputs, which means the proof is only as strong as the list it was proved against. Read indices 64–85 back and confirm they are the list and the direction you asked for; a valid proof against a different list is still a valid proof.
 
-### `oidc_domain_attestation` — 148 entries
+### `oidc_domain_attestation` — 214 entries
 
 | Index | Constants | Circuit field | What it is |
 |-------|-----------|---------------|------------|
@@ -1166,6 +1168,12 @@ The country list and the `is_included` flag are public inputs, which means the p
 | 83–114 | `SCOPE_START` / `_END` | `scope` | `bytes32` scope hash |
 | 115–146 | `NULLIFIER_START` / `_END` | `nullifier` | `bytes32` over the user's email and the scope |
 | 147 | `PROVIDER` | `provider` | `0` = Google, `1` = Microsoft. The circuit accepts no other value |
+| 148–179 | `AUD_HASH_START` / `_END` | `aud_hash` | keccak256 of the ID token's `aud` (the sign-in client it was issued to) |
+| 180 | `NONCE_MODE` | `nonce_mode` | `1` = the token's nonce is bound to your request, `0` = no nonce (agent device sign-in) |
+| 181–212 | `NONCE_BINDING_START` / `_END` | `nonce_binding` | In mode `1`, keccak256("zkproofport-oidc-v1" ‖ keccak256(scope) ‖ requestId); all zero in mode `0` |
+| 213 | `NOW` | `now` | Unix seconds the proof was made at; the circuit proves the token was valid then |
+
+Proofs from the earlier 148-entry version of this circuit bind no audience, expiry or nonce and are refused by every verify method.
 
 `DOMAIN_START` and `DOMAIN_END` are kept as deprecated aliases of `DOMAIN_STORAGE_START` and `DOMAIN_LEN`. Use the current names — the old pair reads as a range and is not one.
 

package/dist/ProofportSDK.d.ts

@@ -3,6 +3,7 @@
  */
 import type { ProofRequest, ProofResponse, CircuitType, CircuitInputs, ProofportConfig, QRCodeOptions, ChallengeResponse, WalletSigner, RelayProofRequest, RelayProofResult } from './types';
 import { type OffChainVerifyOptions } from './offChainVerifier';
+import { type OidcRequestContext } from './verifier';
 import type { SDKEnvironment } from './types';
 /**
  * Main SDK class for interacting with the ZKProofport mobile app.
@@ -41,6 +42,15 @@ import type { SDKEnvironment } from './types';
 export declare class ProofportSDK {
     private config;
     private pendingRequests;
+    /**
+     * 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}.
+     */
+    private relayRequests;
+    /** Bound on {@link relayRequests}; a dApp that verifies later can pass the request explicitly. */
+    static readonly MAX_REMEMBERED_RELAY_REQUESTS = 1000;
     private signer;
     private relayUrl;
     private socket;
@@ -497,10 +507,23 @@ export declare class ProofportSDK {
      * }
      * ```
      */
-    verifyOnChain(circuit: CircuitType, proof: string, publicInputs: string[], providerOrSigner?: any): Promise<{
+    verifyOnChain(circuit: CircuitType, proof: string, publicInputs: string[], providerOrSigner?: any, options?: {
+        request?: OidcRequestContext;
+    }): Promise<{
         valid: boolean;
         error?: string;
     }>;
+    /**
+     * 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.
+     */
+    private oidcRequestFor;
+    /** @internal Remember a relay request's scope for verifyResponse*. */
+    private rememberRelayRequest;
     /**
      * The verifier for a circuit: the one the dApp configured, otherwise the
      * pinned deployment on the chain this SDK's environment verifies that
@@ -516,6 +539,9 @@ export declare 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
      *
@@ -542,7 +568,9 @@ export declare class ProofportSDK {
      * });
      * ```
      */
-    verifyResponseOnChain(response: ProofResponse, providerOrSigner?: any): Promise<{
+    verifyResponseOnChain(response: ProofResponse, providerOrSigner?: any, options?: {
+        request?: OidcRequestContext;
+    }): Promise<{
         valid: boolean;
         error?: string;
     }>;

package/dist/index.d.ts

@@ -32,6 +32,8 @@ export { verifyProofOffChain } from './offChainVerifier';
 export type { OffChainVerifyResult, OffChainVerifyOptions, } from './offChainVerifier';
 export { PINNED_VERIFIERS, getPinnedVerifier } from './verifier';
 export type { PinnedVerifier } from './verifier';
+export { checkOidcPolicy, deriveOidcNonceBinding, oidcAudienceHash, OIDC_ALLOWED_AUDIENCES, OIDC_NONCE_DOMAIN, OIDC_NOW_MAX_AGE_SECONDS, OIDC_NOW_MAX_FUTURE_SECONDS, OIDC_V1_PUBLIC_INPUT_COUNT, OIDC_V2_PUBLIC_INPUT_COUNT, } from './verifier';
+export type { OidcRequestContext, OidcAudience, OidcNonceMode } from './verifier';
 export { COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT, COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT, OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT, MDL_KR_PUBLIC_INPUT_LAYOUT, } from './constants';
 export type { CircuitId, CircuitSupportStatus } from './circuits';
 export { CIRCUIT_ACTION_BINDING, circuitActionBinding, } from './circuits';

package/dist/index.esm.js

@@ -1,5 +1,5 @@
 import { checkProofIssuer, parseProofForOnChain, verifyProofOnChain, getPinnedVerifier, extractScopeFromPublicInputs, extractNullifierFromPublicInputs, extractDomainFromPublicInputs } from '@zkproofport-app/core';
-export { COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT, COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT, MDL_KR_PUBLIC_INPUT_LAYOUT, OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT, PINNED_VERIFIERS, extractDomainFromPublicInputs, extractNullifierFromPublicInputs, extractScopeFromPublicInputs, getPinnedVerifier } from '@zkproofport-app/core';
+export { COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT, COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT, MDL_KR_PUBLIC_INPUT_LAYOUT, OIDC_ALLOWED_AUDIENCES, OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT, OIDC_NONCE_DOMAIN, OIDC_NOW_MAX_AGE_SECONDS, OIDC_NOW_MAX_FUTURE_SECONDS, OIDC_V1_PUBLIC_INPUT_COUNT, OIDC_V2_PUBLIC_INPUT_COUNT, PINNED_VERIFIERS, checkOidcPolicy, deriveOidcNonceBinding, extractDomainFromPublicInputs, extractNullifierFromPublicInputs, extractScopeFromPublicInputs, getPinnedVerifier, oidcAudienceHash } from '@zkproofport-app/core';
 import { isCircuitId, ALL_CIRCUIT_IDS, circuitActionBinding, CIRCUIT_VK_PATHS, CIRCUIT_NEEDS_WALLET_SIGNATURE } from '@zkproofport-app/core/circuits';
 export { ALL_CIRCUIT_IDS, CIRCUIT_ACTION_BINDING, CIRCUIT_IDS, CIRCUIT_SUPPORT_STATUS, CIRCUIT_VK_PATHS, EXPERIMENTAL_CIRCUIT_IDS, PLANNED_CIRCUIT_IDS, SUPPORTED_CIRCUIT_IDS, circuitActionBinding, getCircuitSupportStatus, isCircuitId, isSupportedCircuitId } from '@zkproofport-app/core/circuits';
 import { validateTypedAction } from '@zkproofport-app/core/typedAction';
@@ -124,8 +124,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.
@@ -4006,9 +4008,11 @@ 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 proof's RSA key against the
- * provider's published JWKS (core's `checkOidcProviderKey`); a key the provider
- * does not publish, or a JWKS that cannot be fetched, is `{ valid: false }`.
+ * 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)
@@ -4036,7 +4040,7 @@ async function verifyProofOffChain(circuit, proof, publicInputs, options = {}) {
     // 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 checkProofIssuer(circuit, publicInputs);
+    const issuer = await checkProofIssuer(circuit, publicInputs, { request: options.request });
     if (!issuer.ok) {
         return { valid: false, error: issuer.error };
     }
@@ -4178,6 +4182,13 @@ 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;
         /**
@@ -4739,9 +4750,49 @@ class ProofportSDK {
      * }
      * ```
      */
-    async verifyOnChain(circuit, proof, publicInputs, providerOrSigner) {
+    async verifyOnChain(circuit, proof, publicInputs, providerOrSigner, options = {}) {
         const parsedProof = parseProofForOnChain(proof, publicInputs, publicInputs.length);
-        return verifyProofOnChain(circuit, parsedProof, providerOrSigner, this.verifierTarget(circuit));
+        return 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
@@ -4768,6 +4819,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
      *
@@ -4794,10 +4848,17 @@ 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 = parseProofForOnChain(response.proof, response.publicInputs, response.publicInputs.length);
         // The response's verifierAddress and chainId are a claim to check, never
         // the contract to call: whoever wrote the response would otherwise pick
@@ -4806,7 +4867,7 @@ class ProofportSDK {
         return verifyProofOnChain(response.circuit, parsedProof, providerOrSigner, this.verifierTarget(response.circuit), {
             verifierAddress: response.verifierAddress,
             chainId: response.chainId,
-        });
+        }, { request });
     }
     /**
      * Verifies a proof response off-chain, against the circuit's verification key.
@@ -4836,7 +4897,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 ============
     /**
@@ -5275,7 +5343,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.
@@ -5558,6 +5628,8 @@ class ProofportSDK {
         return 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