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

package/README.md

@@ -81,7 +81,7 @@ const qrDataUrl = await sdk.generateQRCode(relay.deepLink);
 const result = await sdk.waitForProof(relay.requestId);
 
 if (result.status === 'completed') {
-  // 6. Verify on-chain — the relay result carries the verifier to call
+  // 6. Verify on-chain — against the SDK's own verifier for this circuit
   const response: ProofResponse = {
     requestId: result.requestId,
     circuit: result.circuit as CircuitType,
@@ -296,9 +296,8 @@ One more difference worth knowing if you count people: its nullifier is
 a constant compiled into the circuit, so one wallet in one scope has exactly
 one nullifier and there is no input a prover can vary.
 
-**Testnet only.** The verifier lives on GIWA Sepolia (chain `91342`) and
-nowhere else, so the mobile app keeps it behind Developer Mode. A mainnet
-deployment is planned; until it exists, do not ship on this.
+The verifier is deployed on GIWA Sepolia (chain `91342`). The mobile app shows
+this circuit in its Laboratory, which the user turns on in More.
 
 ### `dojang_playground`
 
@@ -350,7 +349,7 @@ something the circuit never saw.
 
 ## Planned Circuits
 
-The identifiers below are reserved and exported, and the circuits exist — but they are **not officially supported yet**. Availability, input shape and public-input layout can change without a major version bump, so treat anything here as provisional. `CIRCUIT_SUPPORT_STATUS` reports each of them as `planned`.
+ZKProofport is registered with the Ministry of the Interior and Safety as a Korea Mobile ID integration service (모바일 신분증 연계서비스). The three circuits below are in beta: `CIRCUIT_SUPPORT_STATUS` reports each of them as `planned`, and their input shape and public-input layout can change without a major version bump.
 
 ### `mdl_kr_ownership`
 
@@ -677,8 +676,8 @@ When you are done, `sdk.disconnect()` closes any open socket.
   circuit: 'coinbase_attestation',
   proof: '0x1f8b0a…',                       // proof bytes, opaque
   publicInputs: ['0x00…2f', '0x00…a1', …],  // ordered — 128 entries for this circuit
-  verifierAddress: '0x…',                   // contract that can check this proof
-  chainId: …,                               // network that contract lives on
+  verifierAddress: '0x…',                   // the verifier the app reports (checked, not trusted)
+  chainId: …,                               // the network the app reports (checked, not trusted)
   deepLink: 'zkproofport://proof-request?data=…',
   createdAt: '2026-02-07T09:14:02.101Z',
   updatedAt: '2026-02-07T09:14:48.902Z',
@@ -692,8 +691,8 @@ When you are done, `sdk.disconnect()` closes any open socket.
 | `circuit` | `string` | terminal results | Which circuit produced the proof, as reported by the mobile app. You need it to read `publicInputs`, because the layout is per circuit. Undefined while the request is still pending. |
 | `proof` | `string` | `'completed'` | The proof bytes as a `0x` hex string. Opaque: the only thing to do with it is hand it to a verifier. |
 | `publicInputs` | `string[]` | `'completed'` | The circuit's public inputs **in circuit order**. This is the part that carries meaning — what each index holds is in [Public Input Layout Constants](#public-input-layout-constants). |
-| `verifierAddress` | `string` | `'completed'` | Address of the Solidity verifier contract that can check this exact proof. It comes from the mobile app — forward it, do not hardcode one. |
-| `chainId` | `number` | `'completed'` | The chain that `verifierAddress` lives on. Same rule: forward it. |
+| `verifierAddress` | `string` | `'completed'` | The verifier contract the mobile app reports. Forward it: the SDK compares it with the verifier it ships with and refuses the proof if they differ. It never verifies against this address. |
+| `chainId` | `number` | `'completed'` | The network the mobile app reports. Same rule: compared, never trusted. |
 | `error` | `string` | `'error'`, `'failed'`, `'expired'` | Human-readable reason from the mobile app or the relay. |
 | `errorCode` | `string` | some `'error'` results | The app's error code, `E` + four digits (e.g. `'E2007'`). Absent when the app did not send one. |
 | `deepLink` | `string` | polling path only | The deep link the request was created with. |
@@ -771,8 +770,8 @@ The relay answers `'expired'` before the SDK's default `timeoutMs` (300 000 ms)
 | `status` | `'pending' \| 'completed' \| 'error' \| 'cancelled'` | Yes | `'completed'`. Anything else and verification returns `{ valid: false, error: 'Invalid or incomplete response' }` without touching the chain. Note the relay says `'failed'` where this type says `'error'` |
 | `proof` | `string` | When completed | `result.proof` |
 | `publicInputs` | `string[]` | When completed | `result.publicInputs` |
-| `verifierAddress` | `string` | When completed | `result.verifierAddress`. Without it there is no contract to call and verification fails with `No verifier address provided…` |
-| `chainId` | `number` | When completed | `result.chainId`. Used to pick a network when you pass no provider of your own |
+| `verifierAddress` | `string` | No | `result.verifierAddress`. Optional. When present it must match the SDK's own verifier for the circuit, or verification is refused |
+| `chainId` | `number` | No | `result.chainId`. Optional. When present it must match the network the SDK verifies the circuit on, or verification is refused |
 | `numPublicInputs` | `number` | No | Never delivered by the relay, and never read during verification — `publicInputs.length` is used instead. Omit it |
 | `timestamp` | `number` | No | Not delivered by the relay. Omit it |
 | `error` | `string` | On failure | `result.error`. Carried for your own logging; verification ignores it |
@@ -783,7 +782,17 @@ There is no `nullifier` field here either.
 
 Verify the proof cryptographically by calling the deployed Solidity verifier contract.
 
-The relay result tells you which contract to call (`verifierAddress`) and on which chain (`chainId`), so verification goes through `verifyResponseOnChain`, which reads both off the response:
+`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 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.
+
+The one limit: a proof made with a key the provider has already withdrawn, which this process never saw while it was published, cannot be checked and is refused. Keys seen while published stay acceptable for 24 hours after they disappear.
+
+
 
 ```typescript
 import type { CircuitType, ProofResponse } from '@zkproofport-app/sdk';
@@ -815,11 +824,11 @@ The SDK connects to the right network on its own. Pass your own ethers `Provider
 const verification = await sdk.verifyResponseOnChain(response, myProvider);
 ```
 
-`verifyResponseOnChain` reports failures instead of throwing them. An incomplete response (`status` other than `'completed'`, or a missing `proof` / `publicInputs`) returns `{ valid: false, error: 'Invalid or incomplete response' }` without making a network call; a missing `verifierAddress` returns `{ valid: false, error: 'No verifier address provided…' }`; and a reverting contract call returns `{ valid: false, error }` carrying the revert message. It does throw in one case: a response carrying a `chainId` the SDK has no built-in endpoint for, when you passed no provider of your own. Pass your own provider if you ever hit that.
+`verifyResponseOnChain` reports failures instead of throwing them. An incomplete response (`status` other than `'completed'`, or a missing `proof` / `publicInputs`) returns `{ valid: false, error: 'Invalid or incomplete response' }` without making a network call; an unknown circuit, a response naming a different verifier, an OIDC signing key the provider does not publish and a reverting contract call each return `{ valid: false, error }` saying which.
 
 `valid: true` means the verifier contract accepted the proof: it is a real proof for that circuit, and its public inputs are the ones it was proved against. It does **not** yet mean the proof answers *your* question — that it was bound to your scope, or that the domain or country in it is the one you asked for. Those live in the public inputs, and reading them is Step 8. `valid: false` is a rejected proof, not an outage: do not retry it, refuse the user.
 
-> **Why not `verifyOnChain`?** `sdk.verifyOnChain(circuit, proof, publicInputs, providerOrSigner?)` takes the same proof in raw pieces. Those pieces carry no verifier address, and it never looks at a response for one — it consults only the `verifiers` map the SDK was constructed with, which `ProofportSDK.create()` leaves empty. Out of the box it therefore returns `{ valid: false, error: 'No verifier address provided. Configure via SDK or ensure proof response includes verifierAddress.' }`. Use `verifyResponseOnChain`.
+> **`verifyOnChain` and `verifyResponseOffChain`.** `sdk.verifyOnChain(circuit, proof, publicInputs, providerOrSigner?)` takes the same proof in raw pieces and checks it against the same built-in verifier, with the same OIDC key check. `sdk.verifyResponseOffChain(response)` checks the proof against the circuit's verification key with no chain involved, and runs the same OIDC key check. Prefer `verifyResponseOnChain` when the answer has to be the one a contract gives.
 
 ### Step 8: Extract Scope, Nullifier, and Domain
 
@@ -925,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');
 
@@ -1025,7 +1034,7 @@ async function verifyUser() {
 
 ## Configuration
 
-`ProofportSDK.create()` returns a fully configured SDK instance. No manual configuration is needed: the relay endpoint is built in, and the verifier contract and network to check a proof against arrive with the proof itself (`verifierAddress`, `chainId`).
+`ProofportSDK.create()` returns a fully configured SDK instance. No manual configuration is needed: the relay endpoint and the verifier contracts proofs are checked against are built in. The verifier a proof response names is compared with them, never used in their place.
 
 ## Types Reference
 
@@ -1149,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 |
 |-------|-----------|---------------|------------|
@@ -1159,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,9 +42,24 @@ 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;
+    /**
+     * 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.
+     */
+    private environment;
     /**
      * Creates a new ProofportSDK instance.
      *
@@ -73,13 +89,11 @@ export declare class ProofportSDK {
     constructor(config?: ProofportConfig);
     /**
      * @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
   
@@ -94,7 +108,7 @@ export declare class ProofportSDK {
      *
      * @example
      * ```typescript
-     * const request = sdk.createCoinbaseKycRequest({
+     * const request = sdk.createScopedRequest('coinbase_attestation', {
      *   scope: 'myapp.com'
      * }, {
      *   dappName: 'My DApp',
@@ -104,7 +118,7 @@ export declare class ProofportSDK {
      * const deepLink = sdk.getDeepLinkUrl(request);
      * ```
      */
-    private createCoinbaseKycRequest;
+    private createScopedRequest;
     /**
      * @internal
      * Creates a Coinbase Country attestation proof request.
@@ -169,6 +183,12 @@ export declare class ProofportSDK {
      * ```
      */
     private createProofRequest;
+    /**
+     * 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.
+     */
+    private static readonly REQUEST_BUILDERS;
     /**
      * @internal
      * Creates a Korea Mobile ID (mDL) proof request for any of the three
@@ -487,10 +507,30 @@ 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
+     * circuit on. `undefined` when neither exists, which core reports as an
+     * error. Never anything a proof response said.
+     */
+    private verifierTarget;
     /**
      * Verifies a proof response on-chain using the deployed verifier contract.
      *
@@ -499,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
      *
@@ -525,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;
     }>;
@@ -575,6 +620,8 @@ export declare class ProofportSDK {
      * ```
      */
     getVerifierAddress(circuit: CircuitType): string;
+    /** The configured or pinned verifier, or an error saying why there is none. */
+    private requireVerifier;
     /**
      * Gets the blockchain chain ID where the verifier contract is deployed.
      *
@@ -731,6 +778,8 @@ export declare class ProofportSDK {
      * ```
      */
     static create(envOrConfig?: SDKEnvironment | ProofportConfig): ProofportSDK;
+    /** @internal An SDK on an environment preset's relay, verifying on that environment's chains. */
+    private static forEnvironment;
     /**
      * Detects if the code is running on a mobile device.
      *

package/dist/constants.d.ts

@@ -13,6 +13,49 @@ import type { CircuitType, SDKEnvironment } from './types';
  * ```
  */
 export declare const RELAY_URLS: Record<SDKEnvironment, string>;
+/**
+ * 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.
+ */
+export declare const VERIFICATION_CHAINS: {
+    readonly production: {
+        readonly coinbase_attestation: 8453;
+        readonly coinbase_country_attestation: 8453;
+        readonly oidc_domain_attestation: 8453;
+        readonly giwa_attestation: 91342;
+        readonly dojang_playground: 91342;
+        readonly mdl_kr_ownership: 84532;
+        readonly mdl_kr_age: 84532;
+        readonly mdl_kr_region: 84532;
+    };
+    readonly staging: {
+        readonly coinbase_attestation: 84532;
+        readonly coinbase_country_attestation: 84532;
+        readonly oidc_domain_attestation: 84532;
+        readonly giwa_attestation: 91342;
+        readonly dojang_playground: 91342;
+        readonly mdl_kr_ownership: 84532;
+        readonly mdl_kr_age: 84532;
+        readonly mdl_kr_region: 84532;
+    };
+    readonly local: {
+        readonly coinbase_attestation: 84532;
+        readonly coinbase_country_attestation: 84532;
+        readonly oidc_domain_attestation: 84532;
+        readonly giwa_attestation: 91342;
+        readonly dojang_playground: 91342;
+        readonly mdl_kr_ownership: 84532;
+        readonly mdl_kr_age: 84532;
+        readonly mdl_kr_region: 84532;
+    };
+};
 /**
  * Default deep link URL scheme for ZKProofport mobile app.
  * Used to construct deep link URLs that open the mobile app.

package/dist/index.d.ts

@@ -30,6 +30,10 @@ export { extractScopeFromPublicInputs, extractNullifierFromPublicInputs, extract
 export { CIRCUIT_IDS, CIRCUIT_SUPPORT_STATUS, ALL_CIRCUIT_IDS, SUPPORTED_CIRCUIT_IDS, EXPERIMENTAL_CIRCUIT_IDS, PLANNED_CIRCUIT_IDS, isCircuitId, isSupportedCircuitId, getCircuitSupportStatus, CIRCUIT_VK_PATHS, } from './circuits';
 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';