{"_id":"@cheny56/zk-kyc-did","name":"@cheny56/zk-kyc-did","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@cheny56/zk-kyc-did","version":"1.0.0","description":"Zero-Knowledge KYC and Decentralized Identity - Prove credentials without revealing personal data","main":"lib/index.js","types":"lib/index.d.ts","exports":{".":{"require":"./lib/index.js","types":"./lib/index.d.ts"},"./lib":{"require":"./lib/index.js","types":"./lib/index.d.ts"},"./client":{"require":"./client/kyc-client.js"}},"scripts":{"test":"node examples/verify-setup.js","example:credential":"node examples/create-credential.js","example:proof":"node examples/generate-proof.js","example:verify":"node examples/verify-credential.js","circuits:compile":"bash scripts/compile-circuits.sh","circuits:setup":"bash scripts/trusted-setup.sh"},"keywords":["zk","zero-knowledge","kyc","did","decentralized-identity","credentials","privacy","selective-disclosure","verifiable-credentials","ethereum","quorum","circom","snarkjs"],"author":{"name":"cheny56"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/cheny56/zk-kyc-did.git"},"homepage":"https://github.com/cheny56/zk-kyc-did#readme","bugs":{"url":"https://github.com/cheny56/zk-kyc-did/issues"},"dependencies":{"circomlibjs":"^0.1.7"},"devDependencies":{"circomlib":"^2.0.5","snarkjs":"^0.7.3","hardhat":"^2.19.0","@nomicfoundation/hardhat-toolbox":"^4.0.0"},"peerDependencies":{"ethers":"^6.0.0"},"engines":{"node":">=18.0.0"},"directories":{"example":"examples","lib":"lib"},"_id":"@cheny56/zk-kyc-did@1.0.0","gitHead":"cea5c145cf90bdf6413777282b1193a9d1a3ddfb","_nodeVersion":"22.21.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-xAPu1+gDQdN2yBiln3boNtot7LgYUHl7pWO6e+AQ1aPtqflK2jZXJQptJtu5C49TzGYxy3bquWLVqBa4R9D5PQ==","shasum":"375a0a74a866cc37cb9fb22b0555a001dad0a422","tarball":"https://registry.npmjs.org/@cheny56/zk-kyc-did/-/zk-kyc-did-1.0.0.tgz","fileCount":16,"unpackedSize":77740,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDPJYFGbrtklSN7K0xopcO2wtKxEMrvB3U6ppUkrnwUvgIgcfPk1ZDRLac8BpAAw9teQIjxYMIHOllEG4y41osn/o4="}]},"_npmUser":{"name":"cheny56","email":"cheny5dyh@gmail.com"},"maintainers":[{"name":"cheny56","email":"cheny5dyh@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/zk-kyc-did_1.0.0_1769059627459_0.9548071188956504"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-22T05:27:07.369Z","1.0.0":"2026-01-22T05:27:07.600Z","modified":"2026-01-22T05:27:07.828Z"},"maintainers":[{"name":"cheny56","email":"cheny5dyh@gmail.com"}],"description":"Zero-Knowledge KYC and Decentralized Identity - Prove credentials without revealing personal data","homepage":"https://github.com/cheny56/zk-kyc-did#readme","keywords":["zk","zero-knowledge","kyc","did","decentralized-identity","credentials","privacy","selective-disclosure","verifiable-credentials","ethereum","quorum","circom","snarkjs"],"repository":{"type":"git","url":"git+https://github.com/cheny56/zk-kyc-did.git"},"author":{"name":"cheny56"},"bugs":{"url":"https://github.com/cheny56/zk-kyc-did/issues"},"license":"MIT","readme":"# @cheny56/zk-kyc-did\n\n**Zero-Knowledge KYC and Decentralized Identity**\n\nProve you meet requirements (age, nationality, verification status) without revealing personal data. Based on W3C Verifiable Credentials with ZK selective disclosure.\n\n[![npm version](https://img.shields.io/npm/v/@cheny56/zk-kyc-did.svg)](https://www.npmjs.com/package/@cheny56/zk-kyc-did)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Features\n\n- 🔒 **Selective Disclosure** - Prove predicates (age >= 18) without revealing exact values\n- 🆔 **W3C Verifiable Credentials** - Standards-compliant credential format\n- 🌐 **Any EVM Chain** - Works on Ethereum, Quorum, Polygon, etc.\n- 📦 **Self-Contained** - No external dependencies on special nodes\n- 🎯 **Privacy-First** - Only commitments and proofs are public\n\n## Installation\n\n```bash\nnpm install @cheny56/zk-kyc-did\n```\n\n## Quick Start\n\n```javascript\nconst { VerifiableCredential, CredentialWallet, Predicate, PredicateOp } = require('@cheny56/zk-kyc-did');\n\n// 1. User creates wallet\nconst wallet = new CredentialWallet();\nawait wallet.init();\n\n// 2. KYC provider issues credential\nconst credential = new VerifiableCredential({\n    issuer: '0x...', // KYC provider\n    subject: wallet.subjectDID,\n    claims: { age: 25, country: 'US', verified: true },\n});\nawait credential.init();\nwallet.addCredential(credential);\n\n// 3. User proves predicates without revealing values\nconst predicates = [\n    new Predicate({ claimKey: 'age', op: PredicateOp.GTE, value: 18 }),\n    new Predicate({ claimKey: 'country', op: PredicateOp.IN, value: ['US', 'UK'] }),\n];\n\n// 4. Generate ZK proof\nconst proof = await generateProof(credential, predicates);\n\n// 5. Verify on-chain\nawait contract.verifyCredential(proof, predicates);\n```\n\n## Table of Contents\n\n- [How It Works](#how-it-works)\n- [Core Concepts](#core-concepts)\n- [API Reference](#api-reference)\n- [Step-by-Step Guide](#step-by-step-guide)\n- [Examples](#examples)\n- [Circuit Compilation](#circuit-compilation)\n- [Contract Deployment](#contract-deployment)\n- [Use Cases](#use-cases)\n- [Security Considerations](#security-considerations)\n\n## How It Works\n\n```\n┌─────────────────────────────────────────────────────────────────────────┐\n│                         ZK KYC/DID FLOW                                  │\n├─────────────────────────────────────────────────────────────────────────┤\n│                                                                         │\n│  1. CREDENTIAL ISSUANCE (Off-Chain)                                     │\n│     ┌─────────────┐     ┌─────────────┐     ┌────────────────────────┐  │\n│     │ KYC Provider│ --> │ User's     │ --> │ Credential with        │  │\n│     │             │     │ Claims     │     │ Commitments            │  │\n│     │ {age: 25,   │     │            │     │ (values hidden)        │  │\n│     │  country:US}│     │            │     │                        │  │\n│     └─────────────┘     └─────────────┘     └────────────────────────┘  │\n│                                                                         │\n│  2. PROOF GENERATION (User Side)                                        │\n│     ┌──────────────────────────────────────────────────────────────┐    │\n│     │  User wants to prove:                                        │    │\n│     │    - age >= 18 (without revealing 25)                        │    │\n│     │    - country IN [US, UK] (without revealing US)              │    │\n│     │                                                               │    │\n│     │  ZK Circuit proves:                                          │    │\n│     │    1. Credential is valid (signature check)                   │    │\n│     │    2. age >= 18 (range proof)                                │    │\n│     │    3. country IN set (membership proof)                      │    │\n│     │                                                               │    │\n│     │  WITHOUT revealing:                                           │    │\n│     │    - Exact age                                                │    │\n│     │    - Which country                                            │    │\n│     │    - Other claims                                             │    │\n│     └──────────────────────────────────────────────────────────────┘    │\n│                                                                         │\n│  3. ON-CHAIN VERIFICATION                                               │\n│     ┌────────────┐     ┌────────────┐     ┌────────────────────────┐  │\n│     │ ZK Proof   │ --> │ Verifier   │ --> │ Contract verifies       │  │\n│     │            │     │ Contract   │     │ and grants access       │  │\n│     └────────────┘     └────────────┘     └────────────────────────┘  │\n│                                                                         │\n└─────────────────────────────────────────────────────────────────────────┘\n```\n\n## Core Concepts\n\n### Verifiable Credential\n\nA **Credential** contains claims (key-value pairs) that are committed using Poseidon hash:\n\n```javascript\nCredential = {\n    issuer: \"0x...\",           // KYC provider\n    subject: \"did:zk:...\",      // User's DID\n    claims: {\n        age: 25,                // Hidden in commitment\n        country: \"US\",          // Hidden in commitment\n        verified: true          // Hidden in commitment\n    },\n    claimCommitments: {         // Public (on-chain)\n        age: \"0xabc...\",\n        country: \"0xdef...\",\n        verified: \"0x123...\"\n    },\n    signature: \"0x...\"          // Issuer's signature\n}\n```\n\n### Selective Disclosure\n\n**Predicates** allow proving properties without revealing values:\n\n```javascript\n// Prove age >= 18 without revealing age is 25\nnew Predicate({ claimKey: 'age', op: PredicateOp.GTE, value: 18 })\n\n// Prove country is in allowed list without revealing which\nnew Predicate({ \n    claimKey: 'country', \n    op: PredicateOp.IN, \n    value: ['US', 'UK', 'CA'] \n})\n```\n\n### DID (Decentralized Identifier)\n\nA **DID** is a self-sovereign identifier:\n\n```\ndid:zk:0x1234567890abcdef...\n```\n\nUsers control their DID and can generate multiple credentials linked to it.\n\n## API Reference\n\n### VerifiableCredential\n\n```javascript\nconst { VerifiableCredential } = require('@cheny56/zk-kyc-did');\n\n// Create credential\nconst credential = new VerifiableCredential({\n    issuer: '0x...',\n    subject: 'did:zk:...',\n    claims: { age: 25, country: 'US' },\n    type: 'KYC',\n    expirationDate: Date.now() + 365*24*60*60*1000, // 1 year\n});\n\nawait credential.init();\n\n// Sign credential (issuer does this)\ncredential.sign(issuerPrivateKey);\n\n// Get commitments\nconst commitments = credential.getAllCommitments();\n\n// Verify signature\nconst valid = credential.verifySignature(issuerPublicKey);\n\n// Check expiration\nconst expired = credential.isExpired();\n```\n\n### CredentialWallet\n\n```javascript\nconst { CredentialWallet } = require('@cheny56/zk-kyc-did');\n\nconst wallet = new CredentialWallet();\nawait wallet.init();\n\n// Add credential\nwallet.addCredential(credential);\n\n// Get credentials\nconst all = wallet.getAllCredentials();\nconst kycCreds = wallet.getCredentialsByType('KYC');\n\n// Export for backup\nconst backup = wallet.toJSON();\n\n// Restore from backup\nconst restored = await CredentialWallet.fromJSON(backup);\n```\n\n### Predicate\n\n```javascript\nconst { Predicate, PredicateOp } = require('@cheny56/zk-kyc-did');\n\n// Create predicates\nconst predicates = [\n    new Predicate({ claimKey: 'age', op: PredicateOp.GTE, value: 18 }),\n    new Predicate({ claimKey: 'country', op: PredicateOp.IN, value: ['US', 'UK'] }),\n    new Predicate({ claimKey: 'verified', op: PredicateOp.EQ, value: true }),\n];\n\n// Evaluate predicate\nconst satisfied = predicate.evaluate(claimValue);\n```\n\n### KYCClient\n\n```javascript\nconst { KYCClient } = require('@cheny56/zk-kyc-did/client');\n\nconst client = new KYCClient({\n    provider,\n    signer,\n    verifierAddress: '0x...',\n});\n\nawait client.init();\n\n// Generate proof\nconst proofData = await client.generateProof(credentialId, predicates);\n\n// Verify on-chain\nconst { verified } = await client.verifyOnChain(proofData);\n```\n\n## Step-by-Step Guide\n\n### Step 1: Install and Initialize\n\n```bash\nnpm install @cheny56/zk-kyc-did\n```\n\n### Step 2: Create User Wallet\n\n```javascript\nconst { CredentialWallet } = require('@cheny56/zk-kyc-did');\n\nconst wallet = new CredentialWallet();\nawait wallet.init();\n\nconsole.log('Your DID:', wallet.subjectDID);\n```\n\n### Step 3: Issue Credential (KYC Provider)\n\n```javascript\nconst { VerifiableCredential } = require('@cheny56/zk-kyc-did');\n\n// KYC provider creates credential\nconst credential = new VerifiableCredential({\n    issuer: kycProviderPublicKey,\n    subject: userWallet.subjectDID,\n    claims: {\n        age: 25,\n        country: 'US',\n        documentType: 'passport',\n        verified: true,\n    },\n    type: 'KYC',\n});\n\nawait credential.init();\ncredential.sign(kycProviderPrivateKey);\n\n// Send to user (user stores in wallet)\nuserWallet.addCredential(credential);\n```\n\n### Step 4: Generate Proof\n\n```javascript\nconst { Predicate, PredicateOp, generateProofInputs } = require('@cheny56/zk-kyc-did');\n\n// Define what to prove\nconst predicates = [\n    new Predicate({ claimKey: 'age', op: PredicateOp.GTE, value: 18 }),\n    new Predicate({ claimKey: 'country', op: PredicateOp.IN, value: ['US', 'UK', 'CA'] }),\n];\n\n// Generate proof inputs\nconst privateInputs = await generateProofInputs(credential, predicates);\n\n// Use snarkjs to generate actual proof\nconst { proof, publicSignals } = await snarkjs.groth16.fullProve(\n    privateInputs,\n    'circuits/credential-proof.wasm',\n    'keys/credential-proof_final.zkey'\n);\n```\n\n### Step 5: Verify On-Chain\n\n```javascript\nconst { KYCClient } = require('@cheny56/zk-kyc-did/client');\n\nconst client = new KYCClient({\n    provider,\n    signer,\n    verifierAddress: '0x...',\n});\n\nawait client.init();\n\nconst proofData = await client.generateProof(credentialId, predicates);\nconst { verified } = await client.verifyOnChain(proofData);\n\nif (verified) {\n    console.log('Access granted!');\n}\n```\n\n## Examples\n\n### Basic Credential Creation\n\n```javascript\n// examples/create-credential.js\nconst { VerifiableCredential, CredentialWallet } = require('@cheny56/zk-kyc-did');\n\nasync function main() {\n    const wallet = new CredentialWallet();\n    await wallet.init();\n    \n    const credential = new VerifiableCredential({\n        issuer: '0x...',\n        subject: wallet.subjectDID,\n        claims: { age: 25, country: 'US' },\n    });\n    \n    await credential.init();\n    wallet.addCredential(credential);\n    \n    console.log('Credential created:', credential.id);\n}\n\nmain();\n```\n\n### Generate Proof\n\n```javascript\n// examples/generate-proof.js\nconst { Predicate, PredicateOp, generateProofInputs } = require('@cheny56/zk-kyc-did');\n\nconst predicates = [\n    new Predicate({ claimKey: 'age', op: PredicateOp.GTE, value: 18 }),\n];\n\nconst privateInputs = await generateProofInputs(credential, predicates);\n// ... generate proof with snarkjs\n```\n\n## Circuit Compilation\n\n```bash\n# Install circom\nnpm install -g circom snarkjs\n\n# Compile circuit\ncircom circuits/credential-proof.circom --r1cs --wasm --sym -o build/\n\n# Download powers of tau\nwget https://hermez.s3-eu-west-1.amazonaws.com/powersOfTau28_hez_final_12.ptau -O pot12_final.ptau\n\n# Generate proving keys\nsnarkjs groth16 setup build/credential-proof.r1cs pot12_final.ptau keys/credential-proof_0000.zkey\n\n# Contribute randomness\nsnarkjs zkey contribute keys/credential-proof_0000.zkey keys/credential-proof_final.zkey\n\n# Export Solidity verifier\nsnarkjs zkey export solidityverifier keys/credential-proof_final.zkey contracts/CredentialProofVerifier.sol\n```\n\n## Contract Deployment\n\n```javascript\nconst { ethers } = require('ethers');\n\nasync function deploy() {\n    const provider = new ethers.JsonRpcProvider('http://localhost:8545');\n    const wallet = new ethers.Wallet(PRIVATE_KEY, provider);\n    \n    // Deploy verifier contract (generated by snarkjs)\n    const Verifier = await ethers.getContractFactory('CredentialProofVerifier');\n    const verifier = await Verifier.deploy();\n    \n    // Deploy CredentialVerifier\n    const CredentialVerifier = await ethers.getContractFactory('CredentialVerifier');\n    const credentialVerifier = await CredentialVerifier.deploy(await verifier.getAddress());\n    \n    // Add trusted issuers\n    await credentialVerifier.addTrustedIssuer(KYC_PROVIDER_ADDRESS);\n    \n    console.log('Deployed:', await credentialVerifier.getAddress());\n}\n```\n\n## Use Cases\n\n### 1. Age Verification\n\n```javascript\n// Prove user is 18+ without revealing exact age\nconst predicate = new Predicate({\n    claimKey: 'age',\n    op: PredicateOp.GTE,\n    value: 18,\n});\n```\n\n### 2. Geographic Restrictions\n\n```javascript\n// Prove user is from allowed country without revealing which\nconst predicate = new Predicate({\n    claimKey: 'country',\n    op: PredicateOp.IN,\n    value: ['US', 'UK', 'CA', 'EU'],\n});\n```\n\n### 3. KYC Tier Verification\n\n```javascript\n// Prove user has completed KYC level 2\nconst predicate = new Predicate({\n    claimKey: 'kycTier',\n    op: PredicateOp.GTE,\n    value: 2,\n});\n```\n\n### 4. Document Verification\n\n```javascript\n// Prove user has verified passport\nconst predicate = new Predicate({\n    claimKey: 'documentVerified',\n    op: PredicateOp.EQ,\n    value: true,\n});\n```\n\n## Security Considerations\n\n1. **Trusted Issuers**: Only credentials from trusted issuers should be accepted\n2. **Credential Expiration**: Always check `credential.isExpired()` before use\n3. **Signature Verification**: Verify issuer signatures before accepting credentials\n4. **Predicate Validation**: Ensure predicates are satisfied before generating proofs\n5. **Key Management**: Protect credential wallets and private keys\n\n## Privacy Properties\n\n| Information | Public | Hidden |\n|-------------|--------|--------|\n| Issuer public key | ✅ | |\n| Predicates (>=18, IN[...]) | ✅ | |\n| Credential root | ✅ | |\n| ZK proof | ✅ | |\n| User's DID | | ✅ |\n| Actual claim values | | ✅ |\n| Blinding factors | | ✅ |\n| Credential signature | | ✅ |\n| Other claims | | ✅ |\n\n## Package Contents\n\n```\nzk-kyc-did/\n├── lib/\n│   ├── index.js           # Main exports\n│   ├── credential.js      # Credential management\n│   └── predicate.js       # Predicate proofs\n├── client/\n│   └── kyc-client.js      # Contract interaction\n├── contracts/\n│   ├── CredentialVerifier.sol\n│   └── interfaces/\n├── circuits/\n│   └── credential-proof.circom\n├── examples/\n│   ├── create-credential.js\n│   ├── generate-proof.js\n│   ├── verify-credential.js\n│   └── verify-setup.js\n├── package.json\n└── README.md\n```\n\n## License\n\nMIT\n\n## Related\n\n- [@cheny56/zk-voting](../zk-voting) - ZK voting system\n- [@cheny56/zk-confidential-offchain](../zk-confidential-offchain) - Confidential tokens\n","readmeFilename":"README.md","_rev":"1-1743ac4e4086924bfdaec77054d85f2b"}