zkpjwt-mvp

Zero-Knowledge Proof access control with Merkle Trees - MVP for decentralized authorization

What is this?

A TypeScript library that enables privacy-preserving access control using:

• Merkle Trees: Efficient cryptographic proofs of membership
• Zero-Knowledge Proofs: Verify authorization without revealing identity
• On-chain verification: Decentralized proof validation on Arbitrum

How it works

1. Create authorization group    →  Merkle Tree
2. Publish Merkle root on-chain  →  Immutable record
3. Generate access token         →  Contains encrypted data + root
4. Verify membership             →  Prove you're authorized without revealing which member
5. Access granted                →  Cryptographic proof validated

Installation

npm install zkpjwt-mvp

Quick Start

1. Create Merkle Tree from authorized wallets

import { createMerkleTree, getMerkleRoot } from 'zkpjwt-mvp';

// Define who can access your data
const authorizedWallets = [
  '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  '0x5B38Da6a701c568545dCfcB03FcB875f56beddC4',
  '0xAb8483F64d9C6d1EcF9b849Ae677dD3315835cb2'
];

// Build Merkle Tree
const tree = createMerkleTree(authorizedWallets);
const merkleRoot = getMerkleRoot(tree);

console.log('Merkle Root:', merkleRoot);
// Publish this root on-chain (smart contract)

2. Encrypt your message

import { encryptMessage } from 'zkpjwt-mvp';

const message = 'Confidential medical results...';
const encrypted = encryptMessage(message);

console.log('Encrypted:', encrypted.encrypted);
console.log('Key:', encrypted.key.toString('hex'));

3. Generate Merkle Proof

import { generateMerkleProof } from 'zkpjwt-mvp';

const myWallet = '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb';
const proof = generateMerkleProof(tree, myWallet);

console.log('Proof valid:', proof.verified);
console.log('Proof path:', proof.proof);

4. Verify on-chain

// Use proof.proof and proof.leaf with your smart contract
await contract.unlockAccess(merkleRoot, proof.leaf, proof.proof);

5. Decrypt message

import { decryptMessage } from 'zkpjwt-mvp';

const decrypted = decryptMessage(
  encrypted.encrypted,
  encrypted.key,
  encrypted.iv
);

console.log('Decrypted:', decrypted);

API Reference

createMerkleTree(wallets: string[]): MerkleTree

Creates a Merkle Tree from wallet addresses.

getMerkleRoot(tree: MerkleTree): string

Returns the Merkle root as hex string.

encryptMessage(message: string): EncryptedData

Encrypts message using AES-256-GCM.

decryptMessage(encrypted: string, key: Buffer, iv: Buffer): string

Decrypts an encrypted message.

generateMerkleProof(tree: MerkleTree, wallet: string): MerkleProof

Generates a Merkle proof for a specific wallet.

verifyMerkleProof(proof: MerkleProof): boolean

Verifies a Merkle proof.

Technical Details

Cryptography

• Hashing: Keccak256 (Ethereum-compatible)
• Encryption: AES-256-GCM (military-grade)
• Merkle Tree: Sorted pairs, binary tree structure

What goes on-chain?

• ✅ Merkle root (32 bytes hash)
• ✅ Proof verification result
• ❌ Wallet addresses (privacy preserved)
• ❌ Encrypted data (stays off-chain)

What stays off-chain?

• Encrypted message
• Encryption keys
• List of authorized wallets
• Full Merkle Tree structure

Use Cases

• Medical Records: Doctors share results with specific patients
• Legal Documents: Lawyers control document access
• Corporate Data: Selective information sharing
• NFT Gating: Token-based access control
• DAO Voting: Anonymous membership verification

Current Limitations (MVP)

⚠️ This is an MVP - Not production-ready for sensitive data:

1. Demo encryption: Current demo uses base64 encoding, not real encryption
2. Key management: No secure key distribution (keys in token)
3. Scalability: Large groups = large proofs
4. No key revocation: Can't revoke access after token creation

Next Steps (Roadmap)

Phase 2: Real Encryption

• [ ] Implement hybrid encryption (asymmetric + symmetric)
• [ ] Secure key distribution per wallet
• [ ] Use wallet signatures for key derivation

Phase 3: Enhanced Features

• [ ] Access revocation mechanism
• [ ] Time-based access expiration
• [ ] Multi-signature authorization
• [ ] IPFS integration for large data

Phase 4: Production Ready

• [ ] Audit by security firm
• [ ] HIPAA/GDPR compliance tools
• [ ] Key recovery system
• [ ] Performance optimization

Smart Contract

Deploy the included Solidity contract to verify proofs on-chain:

// See contracts/ZKPJWTVerifier.sol
function unlockAccess(
    bytes32 root,
    bytes32 leaf,
    bytes32[] calldata proof
) external returns (bool success)

Deployed on Arbitrum Sepolia:

• Solidity: 0xf935f364f797AF2336FfDb3ee06431e1616B7c6C
• Stylus (Rust): 0x531668485fe72c14bb3eed355916f27f4d0b7dea

Examples

See src/examples.ts for complete working examples.

Contributing

Contributions welcome! This is an MVP - help make it production-ready.

License

MIT © DevCristobalvc

Links

• GitHub Repository
• Smart Contract on Arbiscan
• Demo Application

Built for Arbitrum ARG25 Program 🚀