@zkpassport/sdk 0.16.2 → 0.17.0-beta.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +96 -107
- package/dist/cjs/index-PPMt5JWF.d.cts +444 -0
- package/dist/cjs/index.cjs +2 -2
- package/dist/cjs/index.cjs.map +1 -1
- package/dist/cjs/index.d.cts +2 -399
- package/dist/cjs/popup.cjs +3 -0
- package/dist/cjs/popup.cjs.map +1 -0
- package/dist/cjs/popup.d.cts +91 -0
- package/dist/cjs/query.cjs +2 -0
- package/dist/cjs/query.cjs.map +1 -0
- package/dist/cjs/query.d.cts +3 -0
- package/dist/esm/index-PPMt5JWF.d.ts +444 -0
- package/dist/esm/index.d.ts +2 -399
- package/dist/esm/index.js +2 -2
- package/dist/esm/index.js.map +1 -1
- package/dist/esm/popup.d.ts +91 -0
- package/dist/esm/popup.js +3 -0
- package/dist/esm/popup.js.map +1 -0
- package/dist/esm/query.d.ts +3 -0
- package/dist/esm/query.js +2 -0
- package/dist/esm/query.js.map +1 -0
- package/package.json +31 -7
package/README.md
CHANGED
|
@@ -2,10 +2,6 @@
|
|
|
2
2
|
|
|
3
3
|
Privacy-preserving identity verification using passports and ID cards.
|
|
4
4
|
|
|
5
|
-
_⚠️ Warning ⚠️_
|
|
6
|
-
|
|
7
|
-
_This is experimental software that has not been audited yet. Use at your own risk._
|
|
8
|
-
|
|
9
5
|
## Installation
|
|
10
6
|
|
|
11
7
|
```
|
|
@@ -14,6 +10,8 @@ npm install @zkpassport/sdk
|
|
|
14
10
|
|
|
15
11
|
## How to use
|
|
16
12
|
|
|
13
|
+
For a drop-in QR card or verify button that wraps all of this, see [`@zkpassport/ui`](https://www.npmjs.com/package/@zkpassport/ui).
|
|
14
|
+
|
|
17
15
|
```ts
|
|
18
16
|
import { ZKPassport, EU_COUNTRIES } from "@zkpassport/sdk"
|
|
19
17
|
|
|
@@ -26,24 +24,21 @@ const queryBuilder = await zkPassport.request({
|
|
|
26
24
|
name: "ZKPassport",
|
|
27
25
|
logo: "https://zkpassport.id/logo.png",
|
|
28
26
|
purpose: "Prove you are an adult from the EU but not from Scandinavia",
|
|
29
|
-
//
|
|
30
|
-
//
|
|
31
|
-
// By default, the request's unique identifier is scoped to your domain name only
|
|
27
|
+
// Optional: ties the user's unique identifier to a use case;
|
|
28
|
+
// by default it is tied to your domain only
|
|
32
29
|
scope: "eu-adult-not-scandinavia",
|
|
33
30
|
})
|
|
34
31
|
|
|
35
|
-
//
|
|
36
|
-
//
|
|
37
|
-
//
|
|
38
|
-
// The example below requests to disclose the firstname, prove the user is at least 18 years old,
|
|
39
|
-
// prove the user is from the EU but not from a Scandinavian country (note that Norway is not in the EU)
|
|
32
|
+
// Build the query; done() returns the request URL and the progress callbacks.
|
|
33
|
+
// Here: disclose the first name, prove 18+, prove EU nationality but not Scandinavian
|
|
34
|
+
// (Norway is already excluded — it is not in the EU)
|
|
40
35
|
const {
|
|
41
36
|
url,
|
|
42
37
|
requestId,
|
|
43
38
|
onRequestReceived,
|
|
44
39
|
onGeneratingProof,
|
|
45
40
|
onProofGenerated,
|
|
46
|
-
|
|
41
|
+
onSuccess,
|
|
47
42
|
onReject,
|
|
48
43
|
onError,
|
|
49
44
|
} = queryBuilder
|
|
@@ -57,9 +52,7 @@ const {
|
|
|
57
52
|
// or transform it into a button if the user is on their phone
|
|
58
53
|
|
|
59
54
|
onRequestReceived(() => {
|
|
60
|
-
// The user scanned the QR code or
|
|
61
|
-
// Essentially, this means the request popup is now opened
|
|
62
|
-
// on the user phone
|
|
55
|
+
// The user scanned the QR code or opened the link; the request is now on their phone
|
|
63
56
|
console.log("Request received")
|
|
64
57
|
})
|
|
65
58
|
|
|
@@ -69,12 +62,10 @@ onGeneratingProof(() => {
|
|
|
69
62
|
})
|
|
70
63
|
|
|
71
64
|
// You probably don't need to use this callback
|
|
72
|
-
//
|
|
73
|
-
|
|
65
|
+
// It reports the progress as the proofs are generated one by one;
|
|
66
|
+
// the full set arrives in onSuccess
|
|
67
|
+
onProofGenerated(({ proof, vkeyHash, version, name }) => {
|
|
74
68
|
// One of the proofs has been generated
|
|
75
|
-
// Here, you can retrieve the proof manually and verify it
|
|
76
|
-
// But note that the verification of the proofs is handled
|
|
77
|
-
// automatically by the SDK
|
|
78
69
|
console.log("Proof generated", proof)
|
|
79
70
|
console.log("Verification key hash", vkeyHash)
|
|
80
71
|
console.log("Version", version)
|
|
@@ -82,112 +73,105 @@ onProofGenerated(({ proof, vkeyHash, version, name }: ProofResult) => {
|
|
|
82
73
|
})
|
|
83
74
|
|
|
84
75
|
// That's the callback you're looking for
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
// You can also retrieved what were the values originally requested
|
|
101
|
-
console.log("age over", result.age.gte.expected)
|
|
102
|
-
console.log("nationality in", result.nationality.in.expected)
|
|
103
|
-
console.log("nationality not in", result.nationality.out.expected)
|
|
104
|
-
// You can make sure the proof are valid by checking verified is set to true
|
|
105
|
-
console.log("proofs are valid", verified)
|
|
106
|
-
// You can also retrieve the unique identifier associated to this request
|
|
107
|
-
// The assumption is that the unique identifier will be the same if coming
|
|
108
|
-
// from the same ID for the same domain name and scope
|
|
109
|
-
// So you can use it to identify if the user has already provided the proof
|
|
110
|
-
// for this specific use case
|
|
111
|
-
console.log("unique identifier", uniqueIdentifier)
|
|
112
|
-
},
|
|
113
|
-
)
|
|
76
|
+
onSuccess(({ proofs, result }) => {
|
|
77
|
+
// All the proofs have been generated and the result is available
|
|
78
|
+
console.log("firstname", result.firstname.disclose.result)
|
|
79
|
+
console.log("age over 18", result.age.gte.result)
|
|
80
|
+
console.log("nationality in EU", result.nationality.in.result)
|
|
81
|
+
console.log("nationality not from Scandinavia", result.nationality.out.result)
|
|
82
|
+
// You can also retrieve what were the values originally requested
|
|
83
|
+
console.log("age over", result.age.gte.expected)
|
|
84
|
+
console.log("nationality in", result.nationality.in.expected)
|
|
85
|
+
console.log("nationality not in", result.nationality.out.expected)
|
|
86
|
+
// The proofs are NOT verified at this point. A result checked in the browser
|
|
87
|
+
// can be tampered with, so send the proofs and the result to your backend
|
|
88
|
+
// and verify them there (see "Verifying the proofs" below)
|
|
89
|
+
fetch("/api/register", { method: "POST", body: JSON.stringify({ proofs, result }) })
|
|
90
|
+
})
|
|
114
91
|
```
|
|
115
92
|
|
|
93
|
+
The deprecated `onResult` callback still verifies the proofs for you and returns a `verified` flag along with the `uniqueIdentifier`, but a flag delivered to the browser cannot be trusted. Use `onSuccess` and verify on your backend instead.
|
|
94
|
+
|
|
95
|
+
### Verifying the proofs
|
|
96
|
+
|
|
97
|
+
On your backend, recreate the original query so a tampered request cannot pass, then verify the proofs you received:
|
|
98
|
+
|
|
99
|
+
```ts
|
|
100
|
+
import { ZKPassport, EU_COUNTRIES } from "@zkpassport/sdk"
|
|
101
|
+
|
|
102
|
+
const zkPassport = new ZKPassport("demo.zkpassport.id")
|
|
103
|
+
|
|
104
|
+
const { query } = zkPassport
|
|
105
|
+
.createQuery()
|
|
106
|
+
.disclose("firstname")
|
|
107
|
+
.gte("age", 18)
|
|
108
|
+
.in("nationality", EU_COUNTRIES)
|
|
109
|
+
.out("nationality", ["Sweden", "Denmark"])
|
|
110
|
+
.done()
|
|
111
|
+
|
|
112
|
+
const { verified, uniqueIdentifier } = await zkPassport.verify({
|
|
113
|
+
proofs,
|
|
114
|
+
originalQuery: query,
|
|
115
|
+
queryResult: result,
|
|
116
|
+
scope: "eu-adult-not-scandinavia",
|
|
117
|
+
})
|
|
118
|
+
if (!verified) return { registered: false }
|
|
119
|
+
|
|
120
|
+
// The unique identifier stays the same for the same ID, domain and scope,
|
|
121
|
+
// so it can act as the account key: store it in your DB with a uniqueness
|
|
122
|
+
// constraint, and a duplicate means this person already has an account
|
|
123
|
+
await db.users.insert({ zkpassportId: uniqueIdentifier })
|
|
124
|
+
return { registered: true }
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
`verify()` checks the proofs locally and defers to the ZKPassport verifier API when the local result is not verified. Set `verifierMode` to `"local"` or `"api"` to force one.
|
|
128
|
+
|
|
116
129
|
### Using with Next.js
|
|
117
130
|
|
|
118
|
-
|
|
131
|
+
Request the proofs in the browser (with the "How to use" example above, or the drop-in card/button from `@zkpassport/ui`), then send them from `onSuccess` to an API route that verifies them:
|
|
119
132
|
|
|
120
|
-
|
|
133
|
+
```ts
|
|
134
|
+
onSuccess(async ({ proofs, result }) => {
|
|
135
|
+
await fetch("/api/register", { method: "POST", body: JSON.stringify({ proofs, result }) })
|
|
136
|
+
})
|
|
137
|
+
```
|
|
121
138
|
|
|
122
|
-
**App Router:** `app/api/
|
|
139
|
+
**App Router:** `app/api/register/route.ts`
|
|
123
140
|
|
|
124
141
|
```typescript
|
|
125
142
|
import { NextResponse } from "next/server"
|
|
126
143
|
import { ZKPassport } from "@zkpassport/sdk"
|
|
127
144
|
|
|
128
|
-
|
|
129
|
-
const zkPassport = new ZKPassport("demo.zkpassport.id") // Replace with your domain
|
|
130
|
-
const queryBuilder = await zkPassport.request({
|
|
131
|
-
name: "ZKPassport Demo",
|
|
132
|
-
logo: "https://via.placeholder.com/150",
|
|
133
|
-
purpose: "Verify user nationality and first name",
|
|
134
|
-
})
|
|
135
|
-
const { url } = queryBuilder.disclose("nationality").disclose("firstname").done()
|
|
136
|
-
return NextResponse.json({ url })
|
|
137
|
-
}
|
|
138
|
-
```
|
|
145
|
+
const zkPassport = new ZKPassport("demo.zkpassport.id") // Replace with your domain
|
|
139
146
|
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
**App Router:** `app/page.tsx`
|
|
143
|
-
|
|
144
|
-
```tsx
|
|
145
|
-
"use client"
|
|
146
|
-
import { useEffect, useState } from "react"
|
|
147
|
-
|
|
148
|
-
export default function Home() {
|
|
149
|
-
const [verificationUrl, setVerificationUrl] = useState<string | null>(null)
|
|
150
|
-
|
|
151
|
-
useEffect(() => {
|
|
152
|
-
fetch("/api/zkpassport")
|
|
153
|
-
.then((res) => res.json())
|
|
154
|
-
.then((data) => setVerificationUrl(data.url))
|
|
155
|
-
.catch(console.error)
|
|
156
|
-
}, [])
|
|
157
|
-
|
|
158
|
-
return (
|
|
159
|
-
<div>
|
|
160
|
-
<h1>ZKPassport Demo</h1>
|
|
161
|
-
{verificationUrl ? (
|
|
162
|
-
<a href={verificationUrl} target="_blank" rel="noopener noreferrer">
|
|
163
|
-
<button>Verify Identity</button>
|
|
164
|
-
</a>
|
|
165
|
-
) : (
|
|
166
|
-
<p>Loading...</p>
|
|
167
|
-
)}
|
|
168
|
-
</div>
|
|
169
|
-
)
|
|
170
|
-
}
|
|
171
|
-
```
|
|
147
|
+
export async function POST(request: Request) {
|
|
148
|
+
const { proofs, result } = await request.json()
|
|
172
149
|
|
|
173
|
-
|
|
150
|
+
// Recreate the original query so a tampered request cannot pass
|
|
151
|
+
const { query } = zkPassport.createQuery().gte("age", 18).done()
|
|
174
152
|
|
|
175
|
-
|
|
153
|
+
const { verified, uniqueIdentifier } = await zkPassport.verify({
|
|
154
|
+
proofs,
|
|
155
|
+
originalQuery: query,
|
|
156
|
+
queryResult: result,
|
|
157
|
+
scope: "age-check",
|
|
158
|
+
})
|
|
159
|
+
if (!verified) return NextResponse.json({ registered: false })
|
|
176
160
|
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
161
|
+
// Store uniqueIdentifier in your DB as the user's key
|
|
162
|
+
return NextResponse.json({ registered: true })
|
|
163
|
+
}
|
|
180
164
|
```
|
|
181
165
|
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
```sh
|
|
185
|
-
bun install
|
|
186
|
-
```
|
|
166
|
+
## Working on the SDK
|
|
187
167
|
|
|
188
|
-
|
|
168
|
+
The SDK lives in the [zkpassport-packages](https://github.com/zkpassport/zkpassport-packages) monorepo:
|
|
189
169
|
|
|
190
170
|
```sh
|
|
171
|
+
git clone https://github.com/zkpassport/zkpassport-packages.git
|
|
172
|
+
cd zkpassport-packages
|
|
173
|
+
bun install
|
|
174
|
+
cd packages/zkpassport-sdk
|
|
191
175
|
bun test
|
|
192
176
|
```
|
|
193
177
|
|
|
@@ -196,3 +180,8 @@ bun test
|
|
|
196
180
|
Simulate mobile websocket messages: `bun run scripts/simulate.ts mobile`
|
|
197
181
|
|
|
198
182
|
Simulate frontend websocket messages: `bun run scripts/simulate.ts frontend`
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
### Security
|
|
186
|
+
|
|
187
|
+
ZKPassport has undergone multiple internal audits, but it has not yet had an external audit.
|