@zkproofport-app/sdk 0.2.6 → 0.2.8

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 ZKProofport
+Copyright (c) 2026 Masse Labs Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

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.
+TypeScript SDK for requesting zero-knowledge proofs from the [ZKProofport](https://zkproofport.com) mobile app and verifying them on-chain. Supports Coinbase KYC/Country attestations and OIDC domain attestations (Google, Microsoft 365).
 
 ## How It Works
 
@@ -163,6 +163,56 @@ 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.
 
+### `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 signature is required.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `scope` | `string` | Yes | Application-specific identifier for proof uniqueness |
+| `discloseFlags` | `number` | No | Attribute disclosure bitmask `0x00`–`0x0F` (`0x01` name, `0x02` birth, `0x04` sex, `0x08` phone). Omit or `0` for a fully anonymous ownership proof. |
+
+```typescript
+// Anonymous "holds a valid Korean mobile ID" proof
+const relay = await sdk.createRelayRequest('mdl_kr_ownership', {
+  scope: 'myapp.com',
+});
+```
+
+### `mdl_kr_age`
+
+Proves the user is at least `ageThreshold` years old according to their Korean mobile driver's license, without revealing the birth date.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `scope` | `string` | Yes | Application-specific identifier |
+| `ageThreshold` | `number` | Yes | Minimum age to prove (integer 1–150, e.g. `19` for Korean adult verification) |
+
+```typescript
+const relay = await sdk.createRelayRequest('mdl_kr_age', {
+  scope: 'myapp.com',
+  ageThreshold: 19,
+});
+```
+
+### `mdl_kr_region`
+
+Proves the user's registered address is in the specified si/do region without revealing the full address.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `scope` | `string` | Yes | Application-specific identifier |
+| `targetRegion` | `string` | Yes | Region (si/do) to prove residency in, in Korean (e.g. `'경기도'`, `'서울특별시'`) |
+
+```typescript
+const relay = await sdk.createRelayRequest('mdl_kr_region', {
+  scope: 'myapp.com',
+  targetRegion: '경기도',
+});
+```
+
+> The mDL circuits do not require `setSigner()` — the proof is bound to the license via an on-device nullifier (`nullifier_value` public input), not a wallet address. Use `sdk.extractNullifier(result.publicInputs, result.circuit)` for sybil-resistant user identification.
+
 ## Integration Guide
 
 ### Step 1: Initialize
@@ -373,9 +423,9 @@ if (result.status === 'completed') {
 const verification = await sdk.verifyResponseOnChain(response);
 ```
 
-### Step 7: Extract Scope and Nullifier
+### Step 7: Extract Scope, Nullifier, and Domain
 
-After verification, extract the scope and nullifier from the public inputs:
+After verification, extract data from the public inputs:
 
 ```typescript
 if (result.status === 'completed') {
@@ -388,6 +438,12 @@ if (result.status === 'completed') {
 
   console.log('Scope:', scope);       // '0x7a6b70726f...'
   console.log('Nullifier:', nullifier); // '0xabc123...'
+
+  // Extract domain — only for OIDC Domain Attestation
+  if (result.circuit === 'oidc_domain_attestation') {
+    const domain = sdk.extractDomain(result.publicInputs, result.circuit);
+    console.log('Domain:', domain); // 'example.com'
+  }
 }
 ```
 
@@ -398,16 +454,31 @@ The **nullifier** serves as a privacy-preserving user identifier:
 
 > **OIDC Domain:** The nullifier is a hash of the user's email and scope. The same email + scope always produces the same nullifier, enabling Sybil resistance without revealing the email address.
 
+The **domain** (OIDC Domain Attestation only) is the email domain the user proved:
+- Extracted from the circuit's public inputs
+- Matches the domain parameter provided during proof request
+- Available only for `oidc_domain_attestation` circuits
+
 **Standalone utility functions** are also available for use outside the SDK class:
 
 ```typescript
 import {
   extractScopeFromPublicInputs,
   extractNullifierFromPublicInputs,
+  extractDomainFromPublicInputs,
 } from '@zkproofport-app/sdk';
 
+// Works with all circuits: coinbase_attestation, coinbase_country_attestation, oidc_domain_attestation, mdl_kr_ownership, mdl_kr_age, mdl_kr_region
 const scope = extractScopeFromPublicInputs(publicInputs, 'coinbase_attestation');
 const nullifier = extractNullifierFromPublicInputs(publicInputs, 'coinbase_attestation');
+
+// OIDC domain attestation uses a different public input layout (148 fields)
+const oidcScope = extractScopeFromPublicInputs(publicInputs, 'oidc_domain_attestation');
+const oidcNullifier = extractNullifierFromPublicInputs(publicInputs, 'oidc_domain_attestation');
+
+// Extract domain from OIDC Domain Attestation
+const domain = extractDomainFromPublicInputs(publicInputs, 'oidc_domain_attestation');
+// domain: 'example.com' or null if circuit doesn't match or inputs insufficient
 ```
 
 ## Complete Example
@@ -524,6 +595,72 @@ interface OidcDomainInputs {
 }
 ```
 
+## Public Input Layout Constants
+
+The SDK exports constants defining the field positions in each circuit's public inputs array. These are useful when working with standalone extraction functions or building custom verification logic.
+
+```typescript
+import {
+  COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT,
+  COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT,
+  OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT,
+} from '@zkproofport-app/sdk';
+```
+
+**Coinbase KYC Attestation** (128 fields total):
+```typescript
+COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT = {
+  SIGNAL_HASH_START: 0,      // RSA modulus limbs (Coinbase signer)
+  SIGNAL_HASH_END: 31,
+  MERKLE_ROOT_START: 32,     // Merkle root of signers
+  MERKLE_ROOT_END: 63,
+  SCOPE_START: 64,           // keccak256 hash of scope string
+  SCOPE_END: 95,
+  NULLIFIER_START: 96,       // Unique identifier per user+scope
+  NULLIFIER_END: 127,
+}
+```
+
+**Coinbase Country Attestation** (150 fields total):
+```typescript
+COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT = {
+  SIGNAL_HASH_START: 0,
+  SIGNAL_HASH_END: 31,
+  MERKLE_ROOT_START: 32,
+  MERKLE_ROOT_END: 63,
+  COUNTRY_LIST_START: 64,    // Packed country codes
+  COUNTRY_LIST_END: 83,
+  COUNTRY_LIST_LENGTH: 84,   // Number of countries
+  IS_INCLUDED: 85,           // Boolean: user in list or not
+  SCOPE_START: 86,
+  SCOPE_END: 117,
+  NULLIFIER_START: 118,
+  NULLIFIER_END: 149,
+}
+```
+
+**OIDC Domain Attestation** (148 fields total):
+```typescript
+OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT = {
+  PUBKEY_MODULUS_START: 0,   // RSA modulus limbs (JWT issuer key)
+  PUBKEY_MODULUS_END: 17,
+  DOMAIN_STORAGE_START: 18,  // Domain bytes (up to 64 ASCII characters)
+  DOMAIN_STORAGE_END: 81,
+  DOMAIN_LEN: 82,            // Domain string length
+  SCOPE_START: 83,           // keccak256 hash of scope string
+  SCOPE_END: 114,
+  NULLIFIER_START: 115,      // Unique identifier per user+scope
+  NULLIFIER_END: 146,
+  PROVIDER: 147,             // OIDC provider code (0=none, 1=Google, 2=Microsoft)
+
+  // Deprecated aliases (use new names above)
+  DOMAIN_START: 18,          // @deprecated Use DOMAIN_STORAGE_START
+  DOMAIN_END: 82,            // @deprecated Use DOMAIN_LEN
+}
+```
+
+> **Note on field positions:** Each position in the public inputs array corresponds to a field element in the circuit. For bytes32 values (scope, nullifier, signal hash), 32 consecutive fields are concatenated to form the final value.
+
 ## Error Handling
 
 All async SDK methods throw standard `Error` objects:

package/dist/ProofportSDK.d.ts

@@ -168,6 +168,22 @@ export declare class ProofportSDK {
      * ```
      */
     private createProofRequest;
+    /**
+     * @internal
+     * Creates a Korea Mobile ID (mDL) proof request for any of the three
+     * mDL predicate circuits (ownership / age / region).
+     *
+     * The mobile app collects the license data on-device; the dapp only
+     * supplies the predicate parameters validated here. No wallet signature
+     * is required for mDL circuits.
+     *
+     * @param circuit - 'mdl_kr_ownership' | 'mdl_kr_age' | 'mdl_kr_region'
+     * @param inputs - Predicate inputs (see MdlKr*Inputs types)
+     * @param options - Request configuration options
+     *
+     * @throws Error if the predicate inputs fail validation
+     */
+    private createMdlKrRequest;
     /**
      * @internal
      * Generates a deep link URL for a proof request.
@@ -916,5 +932,24 @@ export declare class ProofportSDK {
      * ```
      */
     extractNullifier(publicInputs: string[], circuit: CircuitType): string | null;
+    /**
+     * Extracts the domain string from OIDC Domain Attestation proof public inputs.
+     *
+     * Only works with 'oidc_domain_attestation' circuit. Returns null for other circuits.
+     *
+     * @param publicInputs - Array of hex-encoded field elements from proof result
+     * @param circuit - Circuit type that produced the public inputs
+     * @returns Domain as ASCII string (e.g., 'example.com'), or null if not applicable
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.waitForProof(relay.requestId);
+     * if (result.status === 'completed') {
+     *   const domain = sdk.extractDomain(result.publicInputs, result.circuit);
+     *   console.log('Domain:', domain); // 'example.com'
+     * }
+     * ```
+     */
+    extractDomain(publicInputs: string[], circuit: CircuitType): string | null;
 }
 export default ProofportSDK;

package/dist/constants.d.ts

@@ -183,6 +183,36 @@ export declare const COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT: {
     readonly NULLIFIER_START: 118;
     readonly NULLIFIER_END: 149;
 };
+/**
+ * Korea Mobile ID (mDL) circuit public input layout (field offsets).
+ * All three mDL circuits share the same prefix: scope [0..31] and
+ * nullifier_value [32..63], each stored one byte per field element.
+ * The suffix differs per predicate circuit:
+ * - mdl_kr_ownership (97 inputs): disclose_flags [64], owner_commit [65..96]
+ * - mdl_kr_age (66 inputs): age_threshold [64], current_year [65]
+ * - mdl_kr_region (96 inputs): region_code [64..95]
+ *
+ * @example
+ * ```typescript
+ * const nullifier = publicInputs.slice(
+ *   MDL_KR_PUBLIC_INPUT_LAYOUT.NULLIFIER_START,
+ *   MDL_KR_PUBLIC_INPUT_LAYOUT.NULLIFIER_END + 1
+ * );
+ * ```
+ */
+export declare const MDL_KR_PUBLIC_INPUT_LAYOUT: {
+    readonly SCOPE_START: 0;
+    readonly SCOPE_END: 31;
+    readonly NULLIFIER_START: 32;
+    readonly NULLIFIER_END: 63;
+    readonly OWNERSHIP_DISCLOSE_FLAGS: 64;
+    readonly OWNERSHIP_OWNER_COMMIT_START: 65;
+    readonly OWNERSHIP_OWNER_COMMIT_END: 96;
+    readonly AGE_THRESHOLD: 64;
+    readonly AGE_CURRENT_YEAR: 65;
+    readonly REGION_CODE_START: 64;
+    readonly REGION_CODE_END: 95;
+};
 /**
  * OIDC Domain Attestation circuit public input layout (field offsets).
  * Defines the field positions in the flattened public inputs array (148 fields total).
@@ -205,12 +235,16 @@ export declare const COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT: {
 export declare const OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT: {
     readonly PUBKEY_MODULUS_START: 0;
     readonly PUBKEY_MODULUS_END: 17;
-    readonly DOMAIN_LEN: 18;
-    readonly DOMAIN_START: 19;
-    readonly DOMAIN_END: 82;
+    readonly DOMAIN_STORAGE_START: 18;
+    readonly DOMAIN_STORAGE_END: 81;
+    readonly DOMAIN_LEN: 82;
     readonly SCOPE_START: 83;
     readonly SCOPE_END: 114;
     readonly NULLIFIER_START: 115;
     readonly NULLIFIER_END: 146;
     readonly PROVIDER: 147;
+    /** @deprecated Use DOMAIN_STORAGE_START */
+    readonly DOMAIN_START: 18;
+    /** @deprecated Use DOMAIN_LEN */
+    readonly DOMAIN_END: 82;
 };

package/dist/deeplink.d.ts

@@ -1,7 +1,7 @@
 /**
  * Deep Link utilities for ZKProofport SDK
  */
-import type { ProofRequest, ProofResponse, DeepLinkComponents } from './types';
+import type { ProofRequest, ProofResponse, CircuitInputs, DeepLinkComponents } from './types';
 /**
  * Generates a unique request ID for proof requests.
  *
@@ -171,21 +171,22 @@ export declare function parseDeepLink(url: string): DeepLinkComponents | null;
  */
 export declare function isProofportDeepLink(url: string, scheme?: string): boolean;
 /**
- * @internal
- * Validates a proof request for completeness and correctness.
- *
- * Performs comprehensive validation including:
- * - Required fields (requestId, circuit, callbackUrl)
- * - Circuit type validity (must be a supported circuit)
- * - Circuit-specific input validation (e.g., userAddress format, countryList structure)
- * - Expiration check (if expiresAt is provided)
- *
- * Note: userAddress is optional for both circuits - the mobile app will prompt
- * for wallet connection if not provided.
- *
- * @param request - Proof request to validate
- * @returns Validation result with `valid` flag and optional `error` message
+ * Validates dapp-supplied inputs for the Korea Mobile ID (mDL) circuits.
+ * Shared by deep-link request validation and relay request creation so the
+ * same guards apply on every request path.
+ *
+ * Rules:
+ * - `scope` — required non-empty string, ≤256 chars, no control characters
+ * - `mdl_kr_ownership.discloseFlags` — optional integer 0–15 (0x0F bitmask)
+ * - `mdl_kr_age.ageThreshold` — required integer 1–150
+ * - `mdl_kr_region.targetRegion` — required non-empty string (Korean si/do),
+ *   ≤256 chars, no control characters
+ *
+ * @param circuit - One of the three mDL circuit identifiers
+ * @param inputs - Dapp-supplied circuit inputs
+ * @returns Error message string, or null when the inputs are valid
  */
+export declare function validateMdlInputs(circuit: 'mdl_kr_ownership' | 'mdl_kr_age' | 'mdl_kr_region', inputs: CircuitInputs): string | null;
 export declare function validateProofRequest(request: ProofRequest): {
     valid: boolean;
     error?: string;

package/dist/index.d.ts

@@ -26,6 +26,6 @@
  * ```
  */
 export { ProofportSDK, default } from './ProofportSDK';
-export { extractScopeFromPublicInputs, extractNullifierFromPublicInputs, } from './verifier';
-export { COINBASE_ATTESTATION_PUBLIC_INPUT_LAYOUT, COINBASE_COUNTRY_PUBLIC_INPUT_LAYOUT, OIDC_DOMAIN_ATTESTATION_PUBLIC_INPUT_LAYOUT, } from './constants';
-export type { CircuitType, ProofRequestStatus, CoinbaseKycInputs, CoinbaseCountryInputs, OidcDomainInputs, CircuitInputs, ProofRequest, ProofResponse, QRCodeOptions, VerifierContract, ProofportConfig, ChallengeResponse, WalletSigner, RelayProofRequest, RelayProofResult, SDKEnvironment, } from './types';
+export { extractScopeFromPublicInputs, extractNullifierFromPublicInputs, extractDomainFromPublicInputs, } 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 { CircuitType, ProofRequestStatus, CoinbaseKycInputs, CoinbaseCountryInputs, OidcDomainInputs, MdlKrOwnershipInputs, MdlKrAgeInputs, MdlKrRegionInputs, CircuitInputs, ProofRequest, ProofResponse, QRCodeOptions, VerifierContract, ProofportConfig, ChallengeResponse, WalletSigner, RelayProofRequest, RelayProofResult, SDKEnvironment, } from './types';