@zkproofport-app/sdk 0.2.10 → 0.2.12

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/@zkproofport-app/sdk)](https://www.npmjs.com/package/@zkproofport-app/sdk)
 [![license](https://img.shields.io/npm/l/@zkproofport-app/sdk)](./LICENSE)
 
-TypeScript SDK for requesting zero-knowledge proofs from the [ZKProofport](https://zkproofport.com) mobile app and verifying them on-chain. Six circuits are supported: Coinbase KYC and country attestations, OIDC email-domain attestations (Google, Microsoft 365), and the three Korean mobile ID (mDL) circuits.
+TypeScript SDK for requesting zero-knowledge proofs from the [ZKProofport](https://zkproofport.com) mobile app and verifying them on-chain. Three circuits are officially supported today — Coinbase KYC, Coinbase country attestation, and OIDC email-domain attestation (Google, Microsoft 365). Four more identifiers are reserved and planned: GIWA attestation and the three Korean mobile ID (mDL) circuits. [Circuit Identifiers](#circuit-identifiers) has the full list and what each status means.
 
 ## How It Works
 
@@ -97,9 +97,73 @@ if (result.status === 'completed') {
 }
 ```
 
+## Circuit Identifiers
+
+Circuit IDs are canonical, lowercase and case-sensitive: each one is the `name` field of that circuit's `Nargo.toml`, verbatim. Hyphenated spellings such as `coinbase-kyc` or `mdl-kr-age` are route and directory names from elsewhere — they are not circuit IDs, and passing one does not fail with a clear error. It produces a nullifier mismatch or a verifier lookup that finds nothing.
+
+This SDK is the single source of truth for that list. Import the constants rather than typing the strings, and a rename becomes a compile error instead of a runtime surprise:
+
+```typescript
+import { CIRCUIT_IDS } from '@zkproofport-app/sdk';
+
+const relay = await sdk.createRelayRequest(CIRCUIT_IDS.COINBASE_ATTESTATION, {
+  scope: 'myapp.com',
+});
+```
+
+The same names are also published on their own subpath, which holds nothing but the list — no `ethers`, no `socket.io-client`, no SDK code. A server, a worker or a build script can read it without pulling the SDK in:
+
+```typescript
+import { CIRCUIT_IDS, CIRCUIT_SUPPORT_STATUS } from '@zkproofport-app/sdk/circuits';
+```
+
+### Status
+
+| Constant | Circuit ID | Status |
+|----------|-----------|--------|
+| `CIRCUIT_IDS.COINBASE_ATTESTATION` | `coinbase_attestation` | **Supported** |
+| `CIRCUIT_IDS.COINBASE_COUNTRY_ATTESTATION` | `coinbase_country_attestation` | **Supported** |
+| `CIRCUIT_IDS.OIDC_DOMAIN_ATTESTATION` | `oidc_domain_attestation` | **Supported** |
+| `CIRCUIT_IDS.GIWA_ATTESTATION` | `giwa_attestation` | Planned |
+| `CIRCUIT_IDS.MDL_KR_OWNERSHIP` | `mdl_kr_ownership` | Planned |
+| `CIRCUIT_IDS.MDL_KR_AGE` | `mdl_kr_age` | Planned |
+| `CIRCUIT_IDS.MDL_KR_REGION` | `mdl_kr_region` | Planned |
+
+**Supported** means generally available — build a product on it. **Planned** means the identifier is reserved and the circuit exists, but it is not officially supported yet: availability, inputs and public-input layout can change without a major version bump.
+
+Every ID appears in `CircuitType` and in `sdk.getSupportedCircuits()`, planned ones included, so being assignable is not a support guarantee. Gate on the status, not on the type:
+
+```typescript
+import { CIRCUIT_SUPPORT_STATUS, isSupportedCircuitId } from '@zkproofport-app/sdk';
+
+CIRCUIT_SUPPORT_STATUS.coinbase_attestation; // 'supported'
+CIRCUIT_SUPPORT_STATUS.mdl_kr_age;           // 'planned'
+
+isSupportedCircuitId('oidc_domain_attestation'); // true
+isSupportedCircuitId('mdl_kr_age');              // false
+isSupportedCircuitId('coinbase-kyc');            // false — not an ID at all
+```
+
+### Exports
+
+| Export | Type | What it is |
+|--------|------|------------|
+| `CIRCUIT_IDS` | object | Every canonical ID, keyed by a stable constant name |
+| `ALL_CIRCUIT_IDS` | `readonly CircuitId[]` | Every ID, in the order of the table above |
+| `SUPPORTED_CIRCUIT_IDS` | `readonly CircuitId[]` | Only the officially supported ones |
+| `PLANNED_CIRCUIT_IDS` | `readonly CircuitId[]` | Only the planned ones |
+| `CIRCUIT_SUPPORT_STATUS` | `Readonly<Record<CircuitId, CircuitSupportStatus>>` | The status of each circuit |
+| `isCircuitId(value)` | `value is CircuitId` | Narrows an unknown value; `false` for hyphenated names |
+| `isSupportedCircuitId(value)` | `value is CircuitId` | The same, and additionally requires `supported` |
+| `getCircuitSupportStatus(id)` | `CircuitSupportStatus` | Status of one ID; throws on an unknown one |
+| `CircuitId` | type | Union of the seven IDs. `CircuitType` is an alias of it |
+| `CircuitSupportStatus` | type | `'supported' \| 'planned'` |
+
+Both objects and all three arrays are frozen. `ALL_CIRCUIT_IDS`, `SUPPORTED_CIRCUIT_IDS` and `PLANNED_CIRCUIT_IDS` are derived from `CIRCUIT_SUPPORT_STATUS` at load time, so they cannot disagree with it.
+
 ## Supported Circuits
 
-Circuit IDs are canonical and case-sensitive — pass them exactly as written here. `sdk.getSupportedCircuits()` returns the same list at runtime.
+The circuits below are officially supported. Pass their IDs exactly as written, or use the `CIRCUIT_IDS` constants. `sdk.getSupportedCircuits()` returns every known ID at runtime, planned ones included — see [Circuit Identifiers](#circuit-identifiers).
 
 ### `coinbase_attestation`
 
@@ -178,6 +242,14 @@ const relay = await sdk.createRelayRequest('oidc_domain_attestation', {
 
 > When `provider` is set, the mobile app verifies the user's account is managed by the specified workspace provider (e.g., Google Workspace `hd` claim, Microsoft 365 `tid` claim). Without `provider`, only the email domain is verified.
 
+## 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`.
+
+### `giwa_attestation`
+
+Reserved identifier for GIWA attestation. It is a fork of `coinbase_attestation` and carries the same four public inputs, but there is no dedicated input type for it and no supported request flow. The ID is exported so that every layer spells it the same way; do not build on it yet.
+
 ### `mdl_kr_ownership`
 
 Proves the user holds a valid Korean mobile driver's license (모바일 신분증). The license data stays on-device; only the attributes selected by `discloseFlags` are revealed. No wallet signer is required.
@@ -292,7 +364,7 @@ const relay = await sdk.createRelayRequest('coinbase_attestation', {
   dappIcon: 'https://myapp.com/icon.png',
   message: 'Verify your identity to continue',
   nonce: 'unique-nonce-123',  // Optional: replay prevention
-  returnScheme: 'mydapp://',  // Optional: mobile-only, see below
+  returnScheme: 'mydapp://',  // Optional: native apps only, see below
 });
 
 // relay.requestId  — Relay-issued UUID
@@ -303,48 +375,72 @@ const relay = await sdk.createRelayRequest('coinbase_attestation', {
 
 Every field of the third argument is optional: `message`, `dappName` and `dappIcon` are shown to the user in the ZKProofport app, `nonce` is a value of your own choosing that the relay refuses to accept twice, and `returnScheme` is described next.
 
-#### Switching back to your app: `returnScheme`
+#### Switching back: `returnScheme`
+
+When ZKProofport finishes a proof, the user is sitting in the ZKProofport app. `returnScheme` answers one question: **which app should come back to the foreground?**
+
+It names an app. It is not a URL, not a return address, and the proof is never sent to it — the proof still reaches you exactly as before, through `waitForProof()` / `waitForResult()`. This is the same handoff a wallet performs after a signature (`redirect.native`).
+
+**One form is accepted:**
+
+| Form | Example |
+|------|---------|
+| Bare custom scheme | `'mydapp://'` — an RFC 3986 scheme followed by exactly `://` |
 
-By default the user stays in the ZKProofport app after generating a proof and switches back to your app themselves. Pass `returnScheme` and the ZKProofport app brings your app to the foreground once the proof has been delivered — the same handoff a wallet performs after a signature.
+**If you are a native app**, pass the scheme your app registers:
 
 ```typescript
-// Native app: your own registered scheme
 await sdk.createRelayRequest('coinbase_attestation', { scope: 'myapp.com' }, {
   returnScheme: 'mydapp://',
 });
-
-// Web app: your own origin
-await sdk.createRelayRequest('coinbase_attestation', { scope: 'myapp.com' }, {
-  returnScheme: 'https://myapp.com',
-});
 ```
 
-**Only set it in the mobile deep-link flow.** The switch happens on the phone that generated the proof, so it makes sense only when that phone is also where the user started — i.e. when you navigated the browser to `relay.deepLink` on the same device. In the desktop QR flow the user is watching the desktop screen while the proof happens on their phone; opening a page or an app on the phone at that moment surfaces something nobody asked for. Gate it:
+**If you are a web page, pass nothing.** You have no app to come back to, so there is no value you can honestly put here — and the SDK handles the browser case for you:
 
 ```typescript
-const relay = await sdk.createRelayRequest('coinbase_attestation', { scope: 'myapp.com' },
-  ProofportSDK.isMobile() ? { returnScheme: 'https://myapp.com' } : {});
+// Correct. Do not pass returnScheme from a web page.
+await sdk.createRelayRequest('coinbase_attestation', { scope: 'myapp.com' });
 ```
 
-`returnScheme` is **not** a return address. It says which app to open, nothing more — the proof still reaches you the usual way, through `waitForProof()` / `waitForResult()`, and the ZKProofport app never posts anything to it.
+##### What the SDK does automatically
+
+With the option omitted, the SDK looks at the page's own user agent and decides:
+
+| Where your page is running | What the SDK sends | What the user sees when the proof is done |
+|---|---|---|
+| **Chrome for iOS** (`CriOS`) | `googlechrome://` | Chrome comes forward on **the tab they were already reading** — no new tab, no reload, page state intact |
+| **Firefox for iOS** (`FxiOS`) | `firefox://` | Same: Firefox comes forward on the tab they were already reading |
+| **Android**, any browser | nothing | The ZKProofport app puts itself in the background and the browser resumes exactly as it was |
+| **Safari, Brave, Arc, Edge, Opera on iOS** | nothing | ZKProofport tells them the proof was delivered and to switch back; the system "‹ Back" breadcrumb is still at the top left |
+| **In-app webviews** (KakaoTalk, Naver, Line, Instagram) | nothing | Same notice. Any scheme would destroy the page they are on |
+| **Desktop** | nothing | This is the QR flow: the proof happens on a different device, and your page updates over the relay socket |
 
-Two shapes are accepted, and nothing else:
+Only Chrome and Firefox are auto-detected, each from a positive UA token, because they are the two iOS browsers whose bare scheme is **verified in their own source** to bring the app forward without navigating anywhere. There is no Safari equivalent. Brave and Arc are indistinguishable from Safari on iOS, so guessing would eject those users into a browser they were not using — worse than doing nothing. Edge and Opera are closed source and stay out until someone can show their bare schemes behave the same way.
 
-| Form | Example | Notes |
-|------|---------|-------|
-| Bare custom scheme | `'mydapp://'` | An RFC 3986 scheme followed by exactly `://` |
-| https origin | `'https://myapp.com'`, `'https://myapp.com:8443'` | Host (and optional port) only |
+An explicit `returnScheme` always wins; the SDK never overrides a value you set.
 
-Anything else throws before the SDK makes a single network call — no challenge is consumed, so nothing is wasted on a typo:
+##### `https://` origins are not accepted
 
-- a path, query string or fragment (`'mydapp://transfer?to=0x...'`, `'https://myapp.com/done'`), which is what keeps a request from driving your app to a specific action
+An https origin such as `'https://myapp.com'` used to be allowed. **It is now rejected** by the SDK, the relay and the ZKProofport app alike.
+
+Opening one does not return anybody anywhere. The OS hands the URL to the browser, and the browser opens a **new tab** on a freshly loaded page — the tab your user actually started in is left behind, along with everything in it, including the socket waiting for the proof you just generated. The round trip the field exists to complete was the thing it broke.
+
+##### What is rejected
+
+These throw before the SDK makes a single network call, so no challenge is consumed and nothing is wasted on a typo:
+
+- **https and http origins** — `'https://myapp.com'`, `'https://myapp.com:8443'` (see above)
+- **bare `https://` and `http://`** — a browser with no page to open is not a return target
+- a host, path, query string or fragment — `'mydapp://transfer?to=0x...'` — which is what stops a request driving your app to a specific action rather than just opening it
 - an empty or whitespace-containing value, or one longer than 128 characters
-- userinfo (`'https://user:pass@myapp.com'`) and non-ASCII hosts (use punycode)
-- `http://` and other schemes the OS treats specially: `about`, `blob`, `content`, `data`, `facetime`, `facetime-audio`, `file`, `ftp`, `intent`, `javascript`, `jar`, `mailto`, `sms`, `tel`, `vbscript`
+- non-ASCII schemes (use punycode if you somehow need one)
+- schemes the OS treats specially: `about`, `blob`, `content`, `data`, `facetime`, `facetime-audio`, `file`, `ftp`, `intent`, `javascript`, `jar`, `mailto`, `sms`, `tel`, `vbscript`
 
 The value is matched case-insensitively and stored lowercased by the relay.
 
-Omit `returnScheme` and nothing changes: the request is created without it and the user stays in the ZKProofport app when the proof is done. There is no auto-switch when proof generation fails either — the error has to be read in the ZKProofport app first.
+##### When nothing happens
+
+There is no auto-switch when proof generation **fails** — the error has to be read in the ZKProofport app first. And when no target is sent and none can be inferred, ZKProofport shows the user a notice saying the proof was delivered and to switch back themselves. That is the intended outcome on iOS outside Chrome, not a bug.
 
 **OIDC Domain Attestation:**
 
@@ -828,6 +924,8 @@ Types you can import:
 
 ```typescript
 import type {
+  CircuitId,
+  CircuitSupportStatus,
   CircuitType,
   ProofRequestStatus,
   CoinbaseKycInputs,
@@ -851,7 +949,9 @@ import type {
 
 | Type | Description |
 |------|-------------|
-| `CircuitType` | `'coinbase_attestation' \| 'coinbase_country_attestation' \| 'oidc_domain_attestation' \| 'mdl_kr_ownership' \| 'mdl_kr_age' \| 'mdl_kr_region'` |
+| `CircuitId` | Union of the seven canonical circuit IDs — `'coinbase_attestation' \| 'coinbase_country_attestation' \| 'oidc_domain_attestation' \| 'giwa_attestation' \| 'mdl_kr_ownership' \| 'mdl_kr_age' \| 'mdl_kr_region'`. Also exported from `@zkproofport-app/sdk/circuits` |
+| `CircuitSupportStatus` | `'supported' \| 'planned'` — see [Circuit Identifiers](#circuit-identifiers) |
+| `CircuitType` | Alias of `CircuitId`. Kept as the name used throughout `ProofRequest`, `ProofResponse` and the SDK methods |
 | `ProofRequestStatus` | `'pending' \| 'completed' \| 'error' \| 'cancelled'` — the status on a `ProofResponse` |
 | `CoinbaseKycInputs` | Inputs for `coinbase_attestation`: `{ scope, userAddress?, rawTransaction? }` |
 | `CoinbaseCountryInputs` | Inputs for `coinbase_country_attestation`: `{ scope, countryList, isIncluded, userAddress?, rawTransaction? }` |
@@ -860,7 +960,7 @@ import type {
 | `MdlKrAgeInputs` | Inputs for `mdl_kr_age`: `{ scope, ageThreshold }` |
 | `MdlKrRegionInputs` | Inputs for `mdl_kr_region`: `{ scope, targetRegion }` |
 | `CircuitInputs` | Union of every input type above (plus an empty-input form for circuits that need nothing from the dApp) |
-| `ProofRequest` | Request object: `requestId`, `circuit`, `inputs`, `createdAt`, plus optional `message`, `dappName`, `dappIcon`, `returnScheme`, `expiresAt` |
+| `ProofRequest` | Request object: `requestId`, `circuit`, `inputs`, `createdAt`, plus optional `message`, `dappName`, `dappIcon`, `returnScheme` (a bare scheme such as `mydapp://`), `expiresAt` |
 | `ProofResponse` | What `verifyResponseOnChain()` takes: `requestId`, `circuit`, `status`, and — when completed — `proof`, `publicInputs`, `verifierAddress`, `chainId`; `error` when it failed. `numPublicInputs` and `timestamp` also exist but the relay never fills them, so omit them. Field by field in [Step 6](#step-6-read-the-result) |
 | `QRCodeOptions` | QR customization: `width`, `margin`, `darkColor`, `lightColor`, `errorCorrectionLevel` |
 | `VerifierContract` | Verifier contract info: `{ address, chainId, abi }` |
@@ -996,12 +1096,12 @@ try {
 
 try {
   await sdk.createRelayRequest('coinbase_attestation', { scope: 'app.com' }, {
-    returnScheme: 'https://myapp.com/done',
+    returnScheme: 'https://myapp.com',
   });
 } catch (err) {
-  // "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"  (thrown before any network call)
+  // "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"  (thrown before any network call)
 }
 
 try {

package/dist/ProofportSDK.d.ts

@@ -762,8 +762,10 @@ export declare 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
@@ -772,14 +774,26 @@ export declare 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
      *

package/dist/circuits.d.ts

@@ -0,0 +1,144 @@
+/**
+ * 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.
+ */
+/**
+ * Whether a circuit is officially supported today or still on the roadmap.
+ *
+ * - `supported` — generally available. Safe to build a product on.
+ * - `planned` — the identifier is reserved and the circuit exists, but it is
+ *   not officially supported yet. Availability, inputs and public-input layout
+ *   may change without a major version bump.
+ */
+export type CircuitSupportStatus = 'supported' | 'planned';
+/**
+ * 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',
+ * });
+ * ```
+ */
+export declare const CIRCUIT_IDS: Readonly<{
+    /** Coinbase KYC attestation. Officially supported. */
+    readonly COINBASE_ATTESTATION: "coinbase_attestation";
+    /** Coinbase country attestation (inclusion / exclusion). Officially supported. */
+    readonly COINBASE_COUNTRY_ATTESTATION: "coinbase_country_attestation";
+    /** OIDC email-domain attestation. Officially supported. */
+    readonly OIDC_DOMAIN_ATTESTATION: "oidc_domain_attestation";
+    /** GIWA attestation. Planned — not officially supported yet. */
+    readonly GIWA_ATTESTATION: "giwa_attestation";
+    /** Korea Mobile ID ownership. Planned — not officially supported yet. */
+    readonly MDL_KR_OWNERSHIP: "mdl_kr_ownership";
+    /** Korea Mobile ID age threshold. Planned — not officially supported yet. */
+    readonly MDL_KR_AGE: "mdl_kr_age";
+    /** Korea Mobile ID si/do region. Planned — not officially supported yet. */
+    readonly MDL_KR_REGION: "mdl_kr_region";
+}>;
+/**
+ * Union of every canonical circuit identifier.
+ *
+ * `CircuitType` (exported from the package root) is an alias of this type — the
+ * two names refer to the same union, and this module is where it is defined.
+ */
+export type CircuitId = (typeof CIRCUIT_IDS)[keyof typeof CIRCUIT_IDS];
+/**
+ * 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'
+ * ```
+ */
+export declare const CIRCUIT_SUPPORT_STATUS: Readonly<Record<CircuitId, CircuitSupportStatus>>;
+/**
+ * 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.
+ */
+export declare const ALL_CIRCUIT_IDS: readonly CircuitId[];
+/**
+ * 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.
+ */
+export declare const SUPPORTED_CIRCUIT_IDS: readonly CircuitId[];
+/**
+ * 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.
+ */
+export declare const PLANNED_CIRCUIT_IDS: readonly CircuitId[];
+/**
+ * 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
+ * ```
+ */
+export declare function isCircuitId(value: unknown): value is CircuitId;
+/**
+ * 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
+ * ```
+ */
+export declare function isSupportedCircuitId(value: unknown): value is CircuitId;
+/**
+ * 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'
+ * ```
+ */
+export declare function getCircuitSupportStatus(circuit: CircuitId): CircuitSupportStatus;

package/dist/circuits.esm.js

@@ -0,0 +1,148 @@
+/**
+ * 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];
+}
+
+export { ALL_CIRCUIT_IDS, CIRCUIT_IDS, CIRCUIT_SUPPORT_STATUS, PLANNED_CIRCUIT_IDS, SUPPORTED_CIRCUIT_IDS, getCircuitSupportStatus, isCircuitId, isSupportedCircuitId };
+//# sourceMappingURL=circuits.esm.js.map

package/dist/circuits.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuits.esm.js","sources":["../src/circuits.ts"],"sourcesContent":["/**\n * Canonical ZKProofport circuit identifiers.\n *\n * This module is the single source of truth for circuit IDs. Every other layer\n * — the mobile app, the demo, the relay, server-side provers — reads its list\n * from here instead of keeping a private copy that silently drifts.\n *\n * It has **no imports and no dependencies**, so it can be pulled in on its own:\n *\n * ```typescript\n * import { CIRCUIT_IDS, isCircuitId } from '@zkproofport-app/sdk/circuits';\n * ```\n *\n * The same names are also re-exported from the package root\n * (`@zkproofport-app/sdk`) for callers that already import the SDK.\n *\n * ## Identifiers are canonical and case-sensitive\n *\n * Each ID is the circuit's `name` in its `Nargo.toml`, verbatim. The format is\n * lowercase with underscores. Hyphenated spellings (`coinbase-kyc`,\n * `mdl-kr-age`) are directory or UI route names in other repositories — they\n * are **not** circuit IDs, and passing one produces a nullifier mismatch or a\n * failed on-chain lookup rather than a clear error.\n */\n\n/**\n * Whether a circuit is officially supported today or still on the roadmap.\n *\n * - `supported` — generally available. Safe to build a product on.\n * - `planned` — the identifier is reserved and the circuit exists, but it is\n *   not officially supported yet. Availability, inputs and public-input layout\n *   may change without a major version bump.\n */\nexport type CircuitSupportStatus = 'supported' | 'planned';\n\n/**\n * Canonical circuit identifiers, keyed by a stable constant name.\n *\n * Prefer these constants over string literals so a rename is a compile error\n * rather than a runtime surprise.\n *\n * @example\n * ```typescript\n * import { CIRCUIT_IDS } from '@zkproofport-app/sdk/circuits';\n *\n * const relay = await sdk.createRelayRequest(CIRCUIT_IDS.COINBASE_ATTESTATION, {\n *   scope: 'myapp.com',\n * });\n * ```\n */\nexport const CIRCUIT_IDS = Object.freeze({\n  /** Coinbase KYC attestation. Officially supported. */\n  COINBASE_ATTESTATION: 'coinbase_attestation',\n  /** Coinbase country attestation (inclusion / exclusion). Officially supported. */\n  COINBASE_COUNTRY_ATTESTATION: 'coinbase_country_attestation',\n  /** OIDC email-domain attestation. Officially supported. */\n  OIDC_DOMAIN_ATTESTATION: 'oidc_domain_attestation',\n  /** GIWA attestation. Planned — not officially supported yet. */\n  GIWA_ATTESTATION: 'giwa_attestation',\n  /** Korea Mobile ID ownership. Planned — not officially supported yet. */\n  MDL_KR_OWNERSHIP: 'mdl_kr_ownership',\n  /** Korea Mobile ID age threshold. Planned — not officially supported yet. */\n  MDL_KR_AGE: 'mdl_kr_age',\n  /** Korea Mobile ID si/do region. Planned — not officially supported yet. */\n  MDL_KR_REGION: 'mdl_kr_region',\n} as const);\n\n/**\n * Union of every canonical circuit identifier.\n *\n * `CircuitType` (exported from the package root) is an alias of this type — the\n * two names refer to the same union, and this module is where it is defined.\n */\nexport type CircuitId = (typeof CIRCUIT_IDS)[keyof typeof CIRCUIT_IDS];\n\n/**\n * Support status for every circuit.\n *\n * The record is exhaustive over {@link CircuitId}: adding an identifier without\n * giving it a status is a compile error, so this list cannot drift from\n * {@link CIRCUIT_IDS}.\n *\n * @example\n * ```typescript\n * import { CIRCUIT_SUPPORT_STATUS } from '@zkproofport-app/sdk/circuits';\n *\n * CIRCUIT_SUPPORT_STATUS.coinbase_attestation; // 'supported'\n * CIRCUIT_SUPPORT_STATUS.mdl_kr_age;           // 'planned'\n * ```\n */\nexport const CIRCUIT_SUPPORT_STATUS: Readonly<Record<CircuitId, CircuitSupportStatus>> =\n  Object.freeze({\n    coinbase_attestation: 'supported',\n    coinbase_country_attestation: 'supported',\n    oidc_domain_attestation: 'supported',\n    giwa_attestation: 'planned',\n    mdl_kr_ownership: 'planned',\n    mdl_kr_age: 'planned',\n    mdl_kr_region: 'planned',\n  } as const);\n\n/**\n * Every canonical circuit identifier, in declaration order.\n *\n * Includes circuits that are still `planned`. Use {@link SUPPORTED_CIRCUIT_IDS}\n * when you only want the ones that are officially supported today.\n */\nexport const ALL_CIRCUIT_IDS: readonly CircuitId[] = Object.freeze(\n  Object.values(CIRCUIT_IDS) as CircuitId[]\n);\n\n/**\n * Circuits that are officially supported today: the two Coinbase circuits and\n * OIDC domain attestation.\n *\n * Derived from {@link CIRCUIT_SUPPORT_STATUS}, so it cannot fall out of sync.\n */\nexport const SUPPORTED_CIRCUIT_IDS: readonly CircuitId[] = Object.freeze(\n  ALL_CIRCUIT_IDS.filter((id) => CIRCUIT_SUPPORT_STATUS[id] === 'supported')\n);\n\n/**\n * Circuits whose identifiers are reserved but which are not officially\n * supported yet: GIWA attestation and the three Korea Mobile ID circuits.\n *\n * Derived from {@link CIRCUIT_SUPPORT_STATUS}, so it cannot fall out of sync.\n */\nexport const PLANNED_CIRCUIT_IDS: readonly CircuitId[] = Object.freeze(\n  ALL_CIRCUIT_IDS.filter((id) => CIRCUIT_SUPPORT_STATUS[id] === 'planned')\n);\n\n/**\n * Narrows an unknown value to a canonical circuit identifier.\n *\n * Returns `false` for hyphenated route names such as `'coinbase-kyc'`, which\n * are not circuit IDs.\n *\n * @example\n * ```typescript\n * isCircuitId('coinbase_attestation'); // true\n * isCircuitId('coinbase-kyc');         // false\n * ```\n */\nexport function isCircuitId(value: unknown): value is CircuitId {\n  return typeof value === 'string' && (ALL_CIRCUIT_IDS as readonly string[]).includes(value);\n}\n\n/**\n * Narrows an unknown value to a circuit identifier that is officially supported\n * today. Planned circuits return `false`.\n *\n * @example\n * ```typescript\n * isSupportedCircuitId('oidc_domain_attestation'); // true\n * isSupportedCircuitId('mdl_kr_age');              // false — planned\n * ```\n */\nexport function isSupportedCircuitId(value: unknown): value is CircuitId {\n  return isCircuitId(value) && CIRCUIT_SUPPORT_STATUS[value] === 'supported';\n}\n\n/**\n * Returns the support status of a circuit.\n *\n * @param circuit - A canonical circuit identifier.\n * @throws Error when the value is not a canonical circuit identifier.\n *\n * @example\n * ```typescript\n * getCircuitSupportStatus('giwa_attestation'); // 'planned'\n * ```\n */\nexport function getCircuitSupportStatus(circuit: CircuitId): CircuitSupportStatus {\n  if (!isCircuitId(circuit)) {\n    throw new Error(\n      `Unknown circuit '${String(circuit)}'. Expected one of: ${ALL_CIRCUIT_IDS.join(', ')}`\n    );\n  }\n  return CIRCUIT_SUPPORT_STATUS[circuit];\n}\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;AAuBG;AAYH;;;;;;;;;;;;;;AAcG;AACI,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC;;AAEvC,IAAA,oBAAoB,EAAE,sBAAsB;;AAE5C,IAAA,4BAA4B,EAAE,8BAA8B;;AAE5D,IAAA,uBAAuB,EAAE,yBAAyB;;AAElD,IAAA,gBAAgB,EAAE,kBAAkB;;AAEpC,IAAA,gBAAgB,EAAE,kBAAkB;;AAEpC,IAAA,UAAU,EAAE,YAAY;;AAExB,IAAA,aAAa,EAAE,eAAe;AACtB,CAAA;AAUV;;;;;;;;;;;;;;AAcG;AACI,MAAM,sBAAsB,GACjC,MAAM,CAAC,MAAM,CAAC;AACZ,IAAA,oBAAoB,EAAE,WAAW;AACjC,IAAA,4BAA4B,EAAE,WAAW;AACzC,IAAA,uBAAuB,EAAE,WAAW;AACpC,IAAA,gBAAgB,EAAE,SAAS;AAC3B,IAAA,gBAAgB,EAAE,SAAS;AAC3B,IAAA,UAAU,EAAE,SAAS;AACrB,IAAA,aAAa,EAAE,SAAS;AAChB,CAAA;AAEZ;;;;;AAKG;AACI,MAAM,eAAe,GAAyB,MAAM,CAAC,MAAM,CAChE,MAAM,CAAC,MAAM,CAAC,WAAW,CAAgB;AAG3C;;;;;AAKG;AACI,MAAM,qBAAqB,GAAyB,MAAM,CAAC,MAAM,CACtE,eAAe,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,sBAAsB,CAAC,EAAE,CAAC,KAAK,WAAW,CAAC;AAG5E;;;;;AAKG;AACI,MAAM,mBAAmB,GAAyB,MAAM,CAAC,MAAM,CACpE,eAAe,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,sBAAsB,CAAC,EAAE,CAAC,KAAK,SAAS,CAAC;AAG1E;;;;;;;;;;;AAWG;AACG,SAAU,WAAW,CAAC,KAAc,EAAA;IACxC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,eAAqC,CAAC,QAAQ,CAAC,KAAK,CAAC;AAC5F;AAEA;;;;;;;;;AASG;AACG,SAAU,oBAAoB,CAAC,KAAc,EAAA;IACjD,OAAO,WAAW,CAAC,KAAK,CAAC,IAAI,sBAAsB,CAAC,KAAK,CAAC,KAAK,WAAW;AAC5E;AAEA;;;;;;;;;;AAUG;AACG,SAAU,uBAAuB,CAAC,OAAkB,EAAA;AACxD,IAAA,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE;AACzB,QAAA,MAAM,IAAI,KAAK,CACb,CAAA,iBAAA,EAAoB,MAAM,CAAC,OAAO,CAAC,CAAA,oBAAA,EAAuB,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA,CAAE,CACvF;IACH;AACA,IAAA,OAAO,sBAAsB,CAAC,OAAO,CAAC;AACxC;;;;"}