@zkpassport/sdk 0.1.2 → 0.2.0

package/README.md

@@ -1,4 +1,10 @@
-# zkpassport-sdk
+# ZKPassport SDK
+
+Privacy-preserving identity verification using passports and ID cards.
+
+_⚠️ Warning ⚠️_
+
+_This version of the SDK is only compatible with the version 0.5 and above of ZKPassport mobile app._
 
 ## Installation
 
@@ -9,35 +15,52 @@ npm install @zkpassport/sdk
 ## How to use
 
 ```ts
-import { ZkPassport } from '@zkpassport/sdk'
+import { ZKPassport, EU_COUNTRIES } from '@zkpassport/sdk'
 
 // Replace with your domain
-const zkPassport = new ZkPassport('demo.zkpassport.id')
+const zkPassport = new ZKPassport('demo.zkpassport.id')
 
 // Specify your app name, logo and the purpose of the request
 // you'll send to your visitors or users
 const queryBuilder = await zkPassport.request({
-  name: 'ZKpassport',
+  name: 'ZKPassport',
   logo: 'https://zkpassport.id/logo.png',
-  purpose: 'Proof of country and first name',
+  purpose: 'Prove you are an adult from the EU but not from Scandinavia',
+  // The scope is optional and can be used to scope the unique identifier
+  // of the request to a specific use case
+  // By default, the request's unique identifier is scoped to your domain name only
+  scope: 'eu-adult-not-scandinavia',
 })
 
 // Specify the data you want to disclose
 // Then you can call the `done` method to get the url and the callbacks to follow the progress
 // and get back the result along with the proof
-const { url, requestId, onQRCodeScanned, onGeneratingProof, onProofGenerated, onReject, onError } = queryBuilder
-  .disclose('nationality')
+// The example below requests to disclose the firstname, prove the user is at least 18 years old,
+// prove the user is from the EU but not from a Scandinavian country (note that Norway is not in the EU)
+const {
+  url,
+  requestId,
+  onRequestReceived,
+  onGeneratingProof,
+  onProofGenerated,
+  onResult,
+  onReject,
+  onError,
+} = queryBuilder
   .disclose('firstname')
+  .gte('age', 18)
+  .in('nationality', EU_COUNTRIES)
+  .out('nationality', ['Sweden', 'Denmark'])
   .done()
 
-// Generate a url with the url and let your user scan it
-// or transform it into a button if the user is on mobile
+// Generate a QR Code with the url and let your user scan it
+// or transform it into a button if the user is on their phone
 
-onQRCodeScanned(() => {
-  // The user scanned the QR code or clicked the button
+onRequestReceived(() => {
+  // The user scanned the QR code or clicked the link to the request
   // Essentially, this means the request popup is now opened
   // on the user phone
-  console.log('QR code scanned')
+  console.log('Request received')
 })
 
 onGeneratingProof(() => {
@@ -45,17 +68,49 @@ onGeneratingProof(() => {
   console.log('Generating proof')
 })
 
-onProofGenerated((result: ProofResult) => {
-  // The proof has been generated
-  // You can retrieve the proof, the verification key and the result of your query
-  // Note: the verify function will soon be added to the SDK so you can verify the proof
-  // directly
-  console.log('Proof', result.proof)
-  console.log('Verification key', result.verificationKey)
-  console.log('Query result', result.queryResult)
-  console.log('firstname', result.queryResult.firstname.disclose.result)
-  console.log('nationality', result.queryResult.nationality.disclose.result)
+// You probably don't need to use this callback
+// But if you want to get the proofs and verify them manually, it's here
+onProofGenerated(({ proof, vkeyHash, version, name }: ProofResult) => {
+  // One of the proofs has been generated
+  // Here, you can retrieve the proof manually and verify it
+  // But note that the verification of the proofs is handled
+  // automatically by the SDK
+  console.log('Proof generated', proof)
+  console.log('Verification key hash', vkeyHash)
+  console.log('Version', version)
+  console.log('Name', name)
 })
+
+// That's the callback you're looking for
+onResult(
+  ({
+    uniqueIdentifier,
+    verified,
+    result,
+  }: {
+    uniqueIdentifier: string
+    verified: boolean
+    result: QueryResult
+  }) => {
+    // All the proofs have been generated and the final result is available
+    console.log('firstname', result.firstname.disclose.result)
+    console.log('age over 18', result.age.gte.result)
+    console.log('nationality in EU', result.nationality.in.result)
+    console.log('nationality not from Scandinavia', result.nationality.out.result)
+    // You can also retrieved what were the values originally requested
+    console.log('age over', result.age.gte.expected)
+    console.log('nationality in', result.nationality.in.expected)
+    console.log('nationality not in', result.nationality.out.expected)
+    // You can make sure the proof are valid by checking verified is set to true
+    console.log('proofs are valid', verified)
+    // You can also retrieve the unique identifier associated to this request
+    // The assumption is that the unique identifier will be the same if coming
+    // from the same ID for the same domain name and scope
+    // So you can use it to identify if the user has already provided the proof
+    // for this specific use case
+    console.log('unique identifier', uniqueIdentifier)
+  },
+)
 ```
 
 ### Using with Next.js
@@ -68,12 +123,12 @@ You can integrate `@zkpassport/sdk` into a Next.js application by creating a bac
 
 ```typescript
 import { NextResponse } from 'next/server'
-import { ZkPassport } from '@zkpassport/sdk'
+import { ZKPassport } from '@zkpassport/sdk'
 
 export async function GET() {
-  const zkPassport = new ZkPassport('demo.zkpassport.id') // Replace with your domain
+  const zkPassport = new ZKPassport('demo.zkpassport.id') // Replace with your domain
   const queryBuilder = await zkPassport.request({
-    name: 'ZKpassport Demo',
+    name: 'ZKPassport Demo',
     logo: 'https://via.placeholder.com/150',
     purpose: 'Verify user nationality and first name',
   })

package/dist/cjs/encryption.js

@@ -0,0 +1,69 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateECDHKeyPair = generateECDHKeyPair;
+exports.getSharedSecret = getSharedSecret;
+exports.encrypt = encrypt;
+exports.decrypt = decrypt;
+const aes_1 = require("@noble/ciphers/aes");
+const utils_1 = require("@noble/ciphers/utils");
+async function sha256Truncate(topic) {
+    const encoder = new TextEncoder();
+    const data = encoder.encode(topic);
+    const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+    const fullHashArray = new Uint8Array(hashBuffer);
+    const truncatedHashArray = fullHashArray.slice(0, 12);
+    return truncatedHashArray;
+}
+async function generateECDHKeyPair() {
+    const secp256k1 = await Promise.resolve().then(() => __importStar(require('@noble/secp256k1')));
+    const privKey = secp256k1.utils.randomPrivateKey();
+    const pubKey = secp256k1.getPublicKey(privKey);
+    return {
+        privateKey: privKey,
+        publicKey: pubKey,
+    };
+}
+async function getSharedSecret(privateKey, publicKey) {
+    const secp256k1 = await Promise.resolve().then(() => __importStar(require('@noble/secp256k1')));
+    const sharedSecret = secp256k1.getSharedSecret(privateKey, publicKey);
+    return sharedSecret.slice(0, 32);
+}
+async function encrypt(message, sharedSecret, topic) {
+    // Nonce must be 12 bytes
+    const nonce = await sha256Truncate(topic);
+    const aes = (0, aes_1.gcm)(sharedSecret, nonce);
+    const data = (0, utils_1.utf8ToBytes)(message);
+    const ciphertext = aes.encrypt(data);
+    return ciphertext;
+}
+async function decrypt(ciphertext, sharedSecret, topic) {
+    // Nonce must be 12 bytes
+    const nonce = await sha256Truncate(topic);
+    const aes = (0, aes_1.gcm)(sharedSecret, nonce);
+    const data = aes.decrypt(ciphertext);
+    const dataString = new TextDecoder().decode(data);
+    return dataString;
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,191 @@
+import { type DisclosableIDCredential, type IDCredential, type IDCredentialValue, type NumericalIDCredential, type ProofResult, type QueryResult } from '@zkpassport/utils';
+export type * from '@zkpassport/utils';
+export { SANCTIONED_COUNTRIES, EU_COUNTRIES, EEA_COUNTRIES, SCHENGEN_COUNTRIES, ASEAN_COUNTRIES, MERCOSUR_COUNTRIES, } from '@zkpassport/utils';
+export type QueryBuilderResult = {
+    /**
+     * The URL of the request.
+     *
+     * You can either encode the URL in a QR code or let the user click the link
+     * to this URL on your website if they're visiting your website on their phone.
+     */
+    url: string;
+    /**
+     * The id of the request.
+     */
+    requestId: string;
+    /**
+     * Called when the user has scanned the QR code or clicked the link to the request.
+     *
+     * This means the user is currently viewing the request popup with your website information
+     * and the information requested from them.
+     */
+    onRequestReceived: (callback: () => void) => void;
+    /**
+     * Called when the user has accepted the request and
+     * started to generate the proof on their phone.
+     */
+    onGeneratingProof: (callback: () => void) => void;
+    /**
+     * Called when the SDK successfully connects to the bridge with the mobile app.
+     */
+    onBridgeConnect: (callback: () => void) => void;
+    /**
+     * Called when the user has generated a proof.
+     *
+     * There is a minimum of 4 proofs, but there can be more depending
+     * on the type of information requested from the user.
+     */
+    onProofGenerated: (callback: (proof: ProofResult) => void) => void;
+    /**
+     * Called when the user has sent the query result.
+     *
+     * The response contains the unique identifier associated to the user,
+     * your domain name and chosen scope, along with the query result and whether
+     * the proofs were successfully verified.
+     */
+    onResult: (callback: (response: {
+        uniqueIdentifier: string | undefined;
+        verified: boolean;
+        result: QueryResult;
+    }) => void) => void;
+    /**
+     * Called when the user has rejected the request.
+     */
+    onReject: (callback: () => void) => void;
+    /**
+     * Called when an error occurs, such as one of the requirements not being met
+     * or a proof failing to be generated.
+     */
+    onError: (callback: (error: string) => void) => void;
+    /**
+     * @returns true if the bridge with the mobile app is connected
+     */
+    isBridgeConnected: () => boolean;
+    /**
+     * Get if the user has scanned the QR code or the link to this request
+     * @returns true if the request has been received by the user on their phone
+     */
+    requestReceived: () => boolean;
+};
+export type QueryBuilder = {
+    /**
+     * Requires this attribute to be equal to the provided value.
+     * @param key The attribute to compare.
+     * @param value The value of the attribute you require.
+     */
+    eq: <T extends IDCredential>(key: T, value: IDCredentialValue<T>) => QueryBuilder;
+    /**
+     * Requires this attribute to be greater than or equal to the provided value.
+     * @param key The attribute to compare.
+     * @param value The value of the attribute you require.
+     */
+    gte: <T extends NumericalIDCredential>(key: T, value: IDCredentialValue<T>) => QueryBuilder;
+    /**
+     * Requires this attribute to be less than or equal to the provided value.
+     * @param key The attribute to compare.
+     * @param value The value of the attribute you require.
+     */
+    lte: <T extends 'birthdate' | 'expiry_date'>(key: T, value: IDCredentialValue<T>) => QueryBuilder;
+    /**
+     * Requires this attribute to be less than the provided value.
+     * @param key The attribute to compare.
+     * @param value The value of the attribute you require.
+     */
+    lt: <T extends 'age'>(key: T, value: IDCredentialValue<T>) => QueryBuilder;
+    /**
+     * Requires this attribute to be included in the provided range.
+     * @param key The attribute to compare.
+     * @param start The start of the range.
+     * @param end The end of the range.
+     */
+    range: <T extends NumericalIDCredential>(key: T, start: IDCredentialValue<T>, end: IDCredentialValue<T>) => QueryBuilder;
+    /**
+     * Requires this attribute to be included in the provided list.
+     * @param key The attribute to compare.
+     * @param value The list of values to check inclusion against.
+     */
+    in: <T extends 'nationality'>(key: T, value: IDCredentialValue<T>[]) => QueryBuilder;
+    /**
+     * Requires this attribute to be excluded from the provided list.
+     * @param key The attribute to compare.
+     * @param value The list of values to check exclusion against.
+     */
+    out: <T extends 'nationality'>(key: T, value: IDCredentialValue<T>[]) => QueryBuilder;
+    /**
+     * Requires this attribute to be disclosed.
+     * @param key The attribute to disclose.
+     */
+    disclose: (key: DisclosableIDCredential) => QueryBuilder;
+    /**
+     * Builds the request.
+     *
+     * This will return the URL of the request, which you can either encode in a QR code
+     * or provide as a link to the user if they're visiting your website on their phone.
+     * It also returns all the callbacks you can use to handle the user's response.
+     */
+    done: () => QueryBuilderResult;
+};
+export declare class ZKPassport {
+    private domain;
+    private topicToConfig;
+    private topicToKeyPair;
+    private topicToWebSocketClient;
+    private topicToSharedSecret;
+    private topicToRequestReceived;
+    private topicToService;
+    private topicToProofs;
+    private onRequestReceivedCallbacks;
+    private onGeneratingProofCallbacks;
+    private onBridgeConnectCallbacks;
+    private onProofGeneratedCallbacks;
+    private onResultCallbacks;
+    private onRejectCallbacks;
+    private onErrorCallbacks;
+    constructor(_domain?: string);
+    /**
+     * @notice Handle an encrypted message.
+     * @param request The request.
+     * @param outerRequest The outer request.
+     */
+    private handleEncryptedMessage;
+    private getZkPassportRequest;
+    /**
+     * @notice Create a new request.
+     * @returns The query builder object.
+     */
+    request({ name, logo, purpose, scope, topicOverride, keyPairOverride, }: {
+        name: string;
+        logo: string;
+        purpose: string;
+        scope?: string;
+        topicOverride?: string;
+        keyPairOverride?: {
+            privateKey: Uint8Array;
+            publicKey: Uint8Array;
+        };
+    }): Promise<QueryBuilder>;
+    private checkPublicInputs;
+    /**
+     * @notice Verify the proofs received from the mobile app.
+     * @param requestId The request ID.
+     * @param proofs The proofs to verify.
+     * @param queryResult The query result to verify against
+     * @returns An object containing the unique identifier associated to the user
+     * and a boolean indicating whether the proofs were successfully verified.
+     */
+    verify(requestId: string, proofs?: Array<ProofResult>, queryResult?: QueryResult): Promise<{
+        uniqueIdentifier: string | undefined;
+        verified: boolean;
+    }>;
+    /**
+     * @notice Returns the URL of the request.
+     * @param requestId The request ID.
+     * @returns The URL of the request.
+     */
+    getUrl(requestId: string): string;
+    /**
+     * @notice Cancels a request by closing the WebSocket connection and deleting the associated data.
+     * @param requestId The request ID.
+     */
+    cancelRequest(requestId: string): void;
+}