@le-space/orbitdb-identity-provider-webauthn-did 0.1.0 → 0.2.1
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 +132 -410
- package/package.json +35 -5
- package/src/index.js +58 -503
- package/src/keystore/encryption.js +579 -0
- package/src/keystore/index.js +6 -0
- package/src/keystore/provider.js +555 -0
- package/src/keystore-encryption.js +6 -0
- package/src/varsig/assertion.js +205 -0
- package/src/varsig/credential.js +144 -0
- package/src/varsig/domain.js +11 -0
- package/src/varsig/identity.js +161 -0
- package/src/varsig/index.js +6 -0
- package/src/varsig/provider.js +78 -0
- package/src/varsig/storage.js +46 -0
- package/src/varsig/utils.js +43 -0
- package/src/verification.js +33 -33
- package/src/webauthn/provider.js +542 -0
- package/verification.js +1 -0
package/README.md
CHANGED
|
@@ -1,451 +1,173 @@
|
|
|
1
|
-
# OrbitDB WebAuthn
|
|
1
|
+
# OrbitDB WebAuthn Identity Providers
|
|
2
2
|
|
|
3
3
|
[](https://github.com/le-space/orbitdb-identity-provider-webauthn-did/actions/workflows/test.yml) [](https://github.com/le-space/orbitdb-identity-provider-webauthn-did/actions/workflows/ci-cd.yml)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
⚠️ **Security**: Experimental release. No formal audit. Use only after your own review.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
and biometric authentication via Passkey.
|
|
7
|
+
Two WebAuthn-based OrbitDB identity providers:
|
|
9
8
|
|
|
10
|
-
|
|
9
|
+
- **WebAuthn-Varsig**: No insecure OrbitDB keystore at all. Each entry is signed by WebAuthn (varsig envelope), so keys never leave the authenticator, one Passkey (WebAuthn) prompt per write.
|
|
11
10
|
|
|
12
|
-
-
|
|
13
|
-
- 🚫 **Private keys never leave hardware** - Keys are generated and stored in secure elements
|
|
14
|
-
- 🌐 **Cross-platform compatibility** - Works across modern browsers and platforms
|
|
15
|
-
- 📱 **Biometric authentication** - Seamless user experience with fingerprint, face recognition, or PIN
|
|
16
|
-
- 🔒 **Quantum-resistant** - P-256 elliptic curve cryptography with hardware backing
|
|
17
|
-
- 🆔 **DID-based identity** - Generates deterministic `did:key` DIDs based on WebAuthn credentials
|
|
11
|
+
- **Keystore-based DID**: Generates an Ed25519/secp256k1 keystore keypair for OrbitDB signing in browser memory. When `encryptKeystore` is enabled, the private key is encrypted with AES-GCM and only rehydrated in memory after a WebAuthn unlock (PRF, largeBlob, or hmac-secret).
|
|
18
12
|
|
|
19
|
-
|
|
13
|
+
**Recommendation (security-first):**
|
|
20
14
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
## Basic Usage
|
|
26
|
-
|
|
27
|
-
```javascript
|
|
28
|
-
import { createOrbitDB, Identities, IPFSAccessController } from '@orbitdb/core'
|
|
29
|
-
import { createHelia } from 'helia'
|
|
30
|
-
import {
|
|
31
|
-
WebAuthnDIDProvider,
|
|
32
|
-
OrbitDBWebAuthnIdentityProviderFunction,
|
|
33
|
-
registerWebAuthnProvider,
|
|
34
|
-
checkWebAuthnSupport,
|
|
35
|
-
storeWebAuthnCredential,
|
|
36
|
-
loadWebAuthnCredential
|
|
37
|
-
} from 'orbitdb-identity-provider-webauthn-did'
|
|
38
|
-
|
|
39
|
-
// Check WebAuthn support
|
|
40
|
-
const support = await checkWebAuthnSupport()
|
|
41
|
-
if (!support.supported) {
|
|
42
|
-
console.error('WebAuthn not supported:', support.message)
|
|
43
|
-
return
|
|
44
|
-
}
|
|
45
|
-
|
|
46
|
-
// Create or load WebAuthn credential
|
|
47
|
-
let credential = loadWebAuthnCredential()
|
|
48
|
-
|
|
49
|
-
if (!credential) {
|
|
50
|
-
// Create new WebAuthn credential (triggers biometric prompt)
|
|
51
|
-
credential = await WebAuthnDIDProvider.createCredential({
|
|
52
|
-
userId: 'alice@example.com',
|
|
53
|
-
displayName: 'Alice Smith'
|
|
54
|
-
})
|
|
55
|
-
|
|
56
|
-
// Store credential for future use
|
|
57
|
-
storeWebAuthnCredential(credential)
|
|
58
|
-
}
|
|
59
|
-
|
|
60
|
-
// Register the WebAuthn provider
|
|
61
|
-
registerWebAuthnProvider()
|
|
62
|
-
|
|
63
|
-
// Create identities instance
|
|
64
|
-
const identities = await Identities()
|
|
65
|
-
|
|
66
|
-
// Create WebAuthn identity
|
|
67
|
-
const identity = await identities.createIdentity({
|
|
68
|
-
provider: OrbitDBWebAuthnIdentityProviderFunction({ webauthnCredential: credential })
|
|
69
|
-
})
|
|
70
|
-
|
|
71
|
-
// Create IPFS instance - see OrbitDB Liftoff example for full libp2p configuration:
|
|
72
|
-
// https://github.com/orbitdb/orbitdb/tree/main/examples/liftoff
|
|
73
|
-
const ipfs = await createHelia()
|
|
74
|
-
|
|
75
|
-
// Create OrbitDB instance with WebAuthn identity
|
|
76
|
-
const orbitdb = await createOrbitDB({
|
|
77
|
-
ipfs,
|
|
78
|
-
identities,
|
|
79
|
-
identity
|
|
80
|
-
})
|
|
81
|
-
|
|
82
|
-
// Create a database - will require biometric authentication for each write
|
|
83
|
-
const db = await orbitdb.open('my-secure-database', {
|
|
84
|
-
type: 'keyvalue',
|
|
85
|
-
accessController: IPFSAccessController({
|
|
86
|
-
write: [identity.id] // Only this WebAuthn identity can write
|
|
87
|
-
})
|
|
88
|
-
})
|
|
89
|
-
|
|
90
|
-
// Adding data will trigger biometric prompt
|
|
91
|
-
await db.put('greeting', 'Hello, secure world!')
|
|
92
|
-
```
|
|
15
|
+
- **Best security:** Varsig provider (hardware-backed key for every write).
|
|
16
|
+
- **Best balance:** Keystore provider with WebAuthn-encrypted keystore (fewer prompts, faster writes, key material in memory during session).
|
|
93
17
|
|
|
94
|
-
|
|
18
|
+
Note: WebAuthn varsig support in this repo relies on our forked `@le-space/iso-*` packages of [Hugo Dias iso-repo](https://github.com/hugomrdias/iso-repo/) (notably `@le-space/iso-did` and `@le-space/iso-webauthn-varsig`) to align with the updated varsig flow.
|
|
95
19
|
|
|
96
|
-
### LibP2P and IPFS Setup
|
|
97
20
|
|
|
98
|
-
|
|
21
|
+
## Install
|
|
99
22
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
```javascript
|
|
103
|
-
const credential = await WebAuthnDIDProvider.createCredential({
|
|
104
|
-
userId: 'unique-user-identifier',
|
|
105
|
-
displayName: 'User Display Name',
|
|
106
|
-
domain: 'your-app-domain.com', // Defaults to current hostname
|
|
107
|
-
timeout: 60000 // Authentication timeout in milliseconds
|
|
108
|
-
})
|
|
109
|
-
```
|
|
110
|
-
|
|
111
|
-
### Identity Provider Configuration
|
|
112
|
-
|
|
113
|
-
```javascript
|
|
114
|
-
// Manual identity provider setup
|
|
115
|
-
import { OrbitDBWebAuthnIdentityProviderFunction } from 'orbitdb-identity-provider-webauthn-did'
|
|
116
|
-
|
|
117
|
-
const identityProvider = OrbitDBWebAuthnIdentityProviderFunction({
|
|
118
|
-
webauthnCredential: credential
|
|
119
|
-
})
|
|
120
|
-
|
|
121
|
-
const orbitdb = await createOrbitDB({
|
|
122
|
-
identity: {
|
|
123
|
-
provider: identityProvider
|
|
124
|
-
}
|
|
125
|
-
})
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
## WebAuthn Support Detection
|
|
129
|
-
|
|
130
|
-
The library provides utilities to check WebAuthn compatibility:
|
|
131
|
-
|
|
132
|
-
```javascript
|
|
133
|
-
import { checkWebAuthnSupport, WebAuthnDIDProvider } from 'orbitdb-identity-provider-webauthn-did'
|
|
134
|
-
|
|
135
|
-
// Comprehensive support check
|
|
136
|
-
const support = await checkWebAuthnSupport()
|
|
137
|
-
console.log({
|
|
138
|
-
supported: support.supported,
|
|
139
|
-
platformAuthenticator: support.platformAuthenticator,
|
|
140
|
-
message: support.message
|
|
141
|
-
})
|
|
142
|
-
|
|
143
|
-
// Quick checks
|
|
144
|
-
const isSupported = WebAuthnDIDProvider.isSupported()
|
|
145
|
-
const hasBiometric = await WebAuthnDIDProvider.isPlatformAuthenticatorAvailable()
|
|
23
|
+
```bash
|
|
24
|
+
npm install orbitdb-identity-provider-webauthn-did
|
|
146
25
|
```
|
|
147
26
|
|
|
148
|
-
|
|
27
|
+
Note: `@orbitdb/core` is patched (via `patch-package`) to support Ed25519 keystore keys.
|
|
149
28
|
|
|
150
|
-
|
|
151
|
-
|---------|---------|---------|----------|---------------|
|
|
152
|
-
| Chrome | 67+ | ✅ | ✅ | ✅ |
|
|
153
|
-
| Firefox | 60+ | ✅ | ✅ | ✅ |
|
|
154
|
-
| Safari | 14+ | ✅ | ✅ | ✅ |
|
|
155
|
-
| Edge | 18+ | ✅ | ✅ | ✅ |
|
|
156
|
-
|
|
157
|
-
## Platform Support
|
|
158
|
-
|
|
159
|
-
- **macOS**: Face ID, Touch ID
|
|
160
|
-
- **iOS**: Face ID, Touch ID
|
|
161
|
-
- **Windows**: Windows Hello (face, fingerprint, PIN)
|
|
162
|
-
- **Android**: Fingerprint, face unlock, screen lock
|
|
163
|
-
- **Linux**: FIDO2 security keys, fingerprint readers
|
|
164
|
-
|
|
165
|
-
## Credential Storage Utilities
|
|
166
|
-
|
|
167
|
-
The library provides utility functions for properly storing and loading WebAuthn credentials:
|
|
168
|
-
|
|
169
|
-
### Using the Built-in Utilities:
|
|
29
|
+
## Memory Keystore Quick Start
|
|
170
30
|
|
|
171
31
|
```javascript
|
|
172
|
-
import {
|
|
173
|
-
storeWebAuthnCredential,
|
|
174
|
-
loadWebAuthnCredential,
|
|
175
|
-
clearWebAuthnCredential
|
|
176
|
-
} from 'orbitdb-identity-provider-webauthn-did'
|
|
177
|
-
|
|
178
|
-
// Store credential (handles Uint8Array serialization automatically)
|
|
179
|
-
storeWebAuthnCredential(credential)
|
|
32
|
+
import { WebAuthnDIDProvider, OrbitDBWebAuthnIdentityProviderFunction } from 'orbitdb-identity-provider-webauthn-did';
|
|
180
33
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
clearWebAuthnCredential()
|
|
34
|
+
const credential = await WebAuthnDIDProvider.createCredential({
|
|
35
|
+
userId: 'alice@example.com',
|
|
36
|
+
displayName: 'Alice'
|
|
37
|
+
});
|
|
186
38
|
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
39
|
+
const identity = await identities.createIdentity({
|
|
40
|
+
provider: OrbitDBWebAuthnIdentityProviderFunction({ webauthnCredential: credential })
|
|
41
|
+
});
|
|
190
42
|
```
|
|
191
43
|
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
## Verification Utilities
|
|
195
|
-
|
|
196
|
-
The library provides comprehensive verification utilities to validate database operations and identity storage without relying on external network calls:
|
|
44
|
+
### Hardware Secured - Varsig Quick Start
|
|
197
45
|
|
|
198
46
|
```javascript
|
|
199
|
-
import {
|
|
200
|
-
verifyDatabaseUpdate,
|
|
201
|
-
verifyIdentityStorage,
|
|
202
|
-
verifyDataEntries,
|
|
203
|
-
isValidWebAuthnDID
|
|
204
|
-
} from 'orbitdb-identity-provider-webauthn-did'
|
|
205
|
-
|
|
206
|
-
// Verify database update events
|
|
207
|
-
const updateResult = await verifyDatabaseUpdate(database, identityHash, expectedWebAuthnDID)
|
|
208
|
-
if (updateResult.success) {
|
|
209
|
-
console.log('✅ Database update verified')
|
|
210
|
-
} else {
|
|
211
|
-
console.log('❌ Verification failed:', updateResult.error)
|
|
212
|
-
}
|
|
213
|
-
|
|
214
|
-
// Verify identity is properly stored
|
|
215
|
-
const storageResult = await verifyIdentityStorage(identities, identity)
|
|
216
|
-
console.log('Identity stored correctly:', storageResult.success)
|
|
217
|
-
|
|
218
|
-
// Verify generic data entries with custom matching
|
|
219
|
-
const dataResults = await verifyDataEntries(database, dataItems, expectedWebAuthnDID, {
|
|
220
|
-
matchFn: (dbItem, expectedItem) => dbItem.id === expectedItem.id,
|
|
221
|
-
checkLog: true
|
|
222
|
-
})
|
|
223
|
-
|
|
224
|
-
// DID format validation
|
|
225
|
-
if (isValidWebAuthnDID(identity.id)) {
|
|
226
|
-
console.log('Valid WebAuthn DID format')
|
|
227
|
-
}
|
|
228
|
-
```
|
|
229
|
-
|
|
230
|
-
### Verification Features
|
|
231
|
-
|
|
232
|
-
- **Database-centric verification**: Uses local database state instead of unreliable IPFS gateway calls
|
|
233
|
-
- **Access control validation**: Verifies write permissions and database ownership
|
|
234
|
-
- **Identity storage checking**: Confirms identities are properly stored in OrbitDB's identity store
|
|
235
|
-
- **Generic data verification**: Flexible verification system that works with any data structure
|
|
236
|
-
- **DID format validation**: Utility functions for WebAuthn DID validation and parsing
|
|
237
|
-
- **Pragmatic fallback**: Provides fallback verification when network resources are unavailable
|
|
238
|
-
|
|
239
|
-
## Security Considerations
|
|
240
|
-
|
|
241
|
-
### Private Key Security
|
|
242
|
-
|
|
243
|
-
- Private keys are generated within the secure hardware element
|
|
244
|
-
- Keys cannot be extracted, cloned, or compromised through software attacks
|
|
245
|
-
- Each authentication requires user presence and verification
|
|
246
|
-
|
|
247
|
-
### DID Generation
|
|
248
|
-
|
|
249
|
-
- DIDs are deterministically generated from the WebAuthn public key
|
|
250
|
-
- Same credential always produces the same DID
|
|
251
|
-
- Format: `did:key:{base58btc-encoded-multikey}` (compliant with DID key specification)
|
|
252
|
-
|
|
253
|
-
### Authentication Flow
|
|
254
|
-
|
|
255
|
-
1. User attempts database operation
|
|
256
|
-
2. WebAuthn prompt appears
|
|
257
|
-
3. User provides authentication
|
|
258
|
-
4. Hardware element signs the operation
|
|
259
|
-
5. OrbitDB verifies the signature
|
|
260
|
-
|
|
261
|
-
## Error Handling
|
|
47
|
+
import { WebAuthnVarsigProvider, createWebAuthnVarsigIdentity } from 'orbitdb-identity-provider-webauthn-did';
|
|
262
48
|
|
|
263
|
-
|
|
49
|
+
const credential = await WebAuthnVarsigProvider.createCredential({
|
|
50
|
+
userId: 'alice@example.com',
|
|
51
|
+
displayName: 'Alice'
|
|
52
|
+
});
|
|
264
53
|
|
|
265
|
-
|
|
266
|
-
try {
|
|
267
|
-
const credential = await WebAuthnDIDProvider.createCredential()
|
|
268
|
-
} catch (error) {
|
|
269
|
-
switch (error.message) {
|
|
270
|
-
case 'Biometric authentication was cancelled or failed':
|
|
271
|
-
// User cancelled or biometric failed
|
|
272
|
-
break
|
|
273
|
-
case 'WebAuthn is not supported on this device':
|
|
274
|
-
// Device/browser doesn't support WebAuthn
|
|
275
|
-
break
|
|
276
|
-
case 'A credential with this ID already exists':
|
|
277
|
-
// Credential already registered for this user
|
|
278
|
-
break
|
|
279
|
-
default:
|
|
280
|
-
console.error('WebAuthn error:', error.message)
|
|
281
|
-
}
|
|
282
|
-
}
|
|
54
|
+
const identity = await createWebAuthnVarsigIdentity({ credential });
|
|
283
55
|
```
|
|
284
56
|
|
|
285
|
-
## Development
|
|
286
|
-
|
|
287
|
-
### Building
|
|
288
57
|
|
|
289
|
-
|
|
290
|
-
|
|
58
|
+
### Keystore-based DID (WebAuthn + OrbitDB keystore)
|
|
59
|
+
|
|
60
|
+
```mermaid
|
|
61
|
+
sequenceDiagram
|
|
62
|
+
autonumber
|
|
63
|
+
participant User
|
|
64
|
+
participant App
|
|
65
|
+
participant WebAuthn
|
|
66
|
+
participant Auth as Authenticator
|
|
67
|
+
participant KS as OrbitDB Keystore
|
|
68
|
+
participant Enc as KeystoreEncryption
|
|
69
|
+
participant DB as OrbitDB
|
|
70
|
+
|
|
71
|
+
User->>App: Create credential
|
|
72
|
+
App->>WebAuthn: create()
|
|
73
|
+
WebAuthn->>Auth: Create passkey
|
|
74
|
+
Auth-->>WebAuthn: Attestation
|
|
75
|
+
WebAuthn-->>App: Credential
|
|
76
|
+
|
|
77
|
+
App->>KS: getKey()/createKey(Ed25519)
|
|
78
|
+
KS-->>App: Keystore keypair
|
|
79
|
+
|
|
80
|
+
opt encryptKeystore=true
|
|
81
|
+
App->>Enc: generateSecretKey()
|
|
82
|
+
Enc-->>App: sk
|
|
83
|
+
App->>Enc: encrypt keystore private key (AES-GCM)
|
|
84
|
+
alt prf
|
|
85
|
+
App->>WebAuthn: get() with PRF
|
|
86
|
+
WebAuthn->>Auth: User verification
|
|
87
|
+
Auth-->>WebAuthn: PRF output
|
|
88
|
+
WebAuthn-->>App: PRF bytes
|
|
89
|
+
App->>Enc: wrap sk with PRF
|
|
90
|
+
else largeBlob
|
|
91
|
+
App->>WebAuthn: get() with largeBlob write
|
|
92
|
+
WebAuthn->>Auth: User verification
|
|
93
|
+
Auth-->>WebAuthn: Store sk in largeBlob
|
|
94
|
+
WebAuthn-->>App: largeBlob stored
|
|
95
|
+
else hmac-secret
|
|
96
|
+
App->>WebAuthn: get() with hmac-secret
|
|
97
|
+
WebAuthn->>Auth: User verification
|
|
98
|
+
Auth-->>WebAuthn: HMAC output
|
|
99
|
+
WebAuthn-->>App: HMAC bytes
|
|
100
|
+
App->>Enc: wrap sk with HMAC
|
|
101
|
+
end
|
|
102
|
+
end
|
|
103
|
+
|
|
104
|
+
App->>DB: db.put()
|
|
105
|
+
DB->>KS: sign entry with keystore key
|
|
106
|
+
KS-->>DB: Entry signature
|
|
107
|
+
|
|
108
|
+
Note over App,KS: Keystore private key is stored encrypted at rest.
|
|
291
109
|
```
|
|
292
110
|
|
|
293
|
-
###
|
|
294
|
-
|
|
295
|
-
```
|
|
296
|
-
|
|
111
|
+
### Varsig (no keystore)
|
|
112
|
+
|
|
113
|
+
```mermaid
|
|
114
|
+
sequenceDiagram
|
|
115
|
+
autonumber
|
|
116
|
+
participant User
|
|
117
|
+
participant App
|
|
118
|
+
participant WebAuthn
|
|
119
|
+
participant Auth as Authenticator
|
|
120
|
+
participant Var as Varsig Provider
|
|
121
|
+
participant DB as OrbitDB
|
|
122
|
+
|
|
123
|
+
User->>App: Create credential
|
|
124
|
+
App->>WebAuthn: create()
|
|
125
|
+
WebAuthn->>Auth: Create passkey
|
|
126
|
+
Auth-->>WebAuthn: Attestation
|
|
127
|
+
WebAuthn-->>App: Credential
|
|
128
|
+
|
|
129
|
+
User->>App: Create varsig identity
|
|
130
|
+
App->>Var: createIdentity()
|
|
131
|
+
Var->>WebAuthn: get()
|
|
132
|
+
WebAuthn->>Auth: User verification
|
|
133
|
+
Auth-->>WebAuthn: Assertion
|
|
134
|
+
WebAuthn-->>Var: Assertion
|
|
135
|
+
Var->>Var: encode varsig envelope
|
|
136
|
+
Var-->>App: Identity
|
|
137
|
+
|
|
138
|
+
User->>App: Add entry
|
|
139
|
+
App->>DB: db.put()
|
|
140
|
+
DB->>Var: signIdentity(payload)
|
|
141
|
+
Var->>WebAuthn: get()
|
|
142
|
+
WebAuthn->>Auth: User verification
|
|
143
|
+
Auth-->>WebAuthn: Assertion
|
|
144
|
+
WebAuthn-->>Var: Assertion
|
|
145
|
+
Var->>Var: encode varsig envelope
|
|
146
|
+
Var-->>DB: Varsig signature
|
|
297
147
|
```
|
|
298
148
|
|
|
299
|
-
The test suite includes both unit tests and browser integration tests that verify WebAuthn functionality across different platforms.
|
|
300
|
-
|
|
301
|
-
### Dependencies
|
|
302
|
-
|
|
303
|
-
- `@orbitdb/core` - OrbitDB core functionality
|
|
304
|
-
- `cbor-web` - CBOR decoding for WebAuthn attestation objects
|
|
305
|
-
|
|
306
|
-
## API Reference
|
|
307
|
-
|
|
308
|
-
### WebAuthnDIDProvider
|
|
309
|
-
|
|
310
|
-
Core class for WebAuthn DID operations.
|
|
311
|
-
|
|
312
|
-
#### Static Methods
|
|
313
|
-
|
|
314
|
-
- `isSupported()` - Check if WebAuthn is supported
|
|
315
|
-
- `isPlatformAuthenticatorAvailable()` - Check for biometric authenticators
|
|
316
|
-
- `createCredential(options)` - Create new WebAuthn credential
|
|
317
|
-
- `createDID(credentialInfo)` - Generate DID from credential
|
|
318
|
-
- `extractPublicKey(credential)` - Extract public key from WebAuthn credential
|
|
319
|
-
|
|
320
|
-
#### Instance Methods
|
|
321
|
-
|
|
322
|
-
- `sign(data)` - Sign data using WebAuthn (triggers biometric prompt)
|
|
323
|
-
- `verify(signature, data, publicKey)` - Verify WebAuthn signature
|
|
324
|
-
|
|
325
|
-
### OrbitDBWebAuthnIdentityProvider
|
|
326
|
-
|
|
327
|
-
OrbitDB-compatible identity provider.
|
|
328
|
-
|
|
329
|
-
#### Methods
|
|
330
|
-
|
|
331
|
-
- `getId()` - Get the DID identifier
|
|
332
|
-
- `signIdentity(data, options)` - Sign identity data
|
|
333
|
-
- `verifyIdentity(signature, data, publicKey)` - Verify identity signature
|
|
334
|
-
|
|
335
|
-
### Utility Functions
|
|
336
|
-
|
|
337
|
-
- `registerWebAuthnProvider()` - Register provider with OrbitDB
|
|
338
|
-
- `checkWebAuthnSupport()` - Comprehensive support detection
|
|
339
|
-
- `OrbitDBWebAuthnIdentityProviderFunction(options)` - Provider factory function
|
|
340
|
-
- `storeWebAuthnCredential(credential, key?)` - Store credential to localStorage with proper serialization
|
|
341
|
-
- `loadWebAuthnCredential(key?)` - Load credential from localStorage with proper deserialization
|
|
342
|
-
- `clearWebAuthnCredential(key?)` - Clear stored credential from localStorage
|
|
343
|
-
|
|
344
149
|
## Examples
|
|
345
150
|
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
-
|
|
349
|
-
-
|
|
350
|
-
- Error handling scenarios
|
|
351
|
-
- Integration with OrbitDB databases
|
|
352
|
-
|
|
353
|
-
## Reference Documentation
|
|
151
|
+
Svelte demos:
|
|
152
|
+
- `examples/webauthn-todo-demo/` - WebAuthn DID (no keystore signing; identity-only).
|
|
153
|
+
- `examples/ed25519-encrypted-keystore-demo/` - Ed25519 keystore DID; keystore encrypted at rest with WebAuthn (PRF when available, otherwise largeBlob/hmac-secret).
|
|
154
|
+
- `examples/webauthn-varsig-demo/` - Varsig provider with passkey signing for each entry. Live demo: https://dweb.link/ipfs/bafybeib6tpwiby7pik67ufb3lxpr3j4by2l7r3ov3zzk6hjbzjzgsvckhy
|
|
354
155
|
|
|
355
|
-
|
|
156
|
+
Scripted examples:
|
|
157
|
+
- `examples/ed25519-keystore-did-example.js` - Keystore DID flow.
|
|
158
|
+
- `examples/encrypted-keystore-example.js` - Keystore encryption flow.
|
|
159
|
+
- `examples/simple-encryption-integration.js` - Keystore + database content encryption.
|
|
356
160
|
|
|
357
|
-
|
|
358
|
-
-
|
|
359
|
-
- [OrbitDB GitHub](https://github.com/orbitdb/orbitdb) - Source code and examples
|
|
360
|
-
- [OrbitDB Liftoff Example](https://github.com/orbitdb/orbitdb/tree/main/examples/liftoff) - Complete setup guide
|
|
161
|
+
Mermaid sequences for scripts:
|
|
162
|
+
- `docs/EXAMPLE-SEQUENCES.md`
|
|
361
163
|
|
|
362
|
-
|
|
363
|
-
- [Helia Documentation](https://helia.io/) - Lean, modular, and modern implementation of IPFS for JavaScript
|
|
364
|
-
- [Helia GitHub](https://github.com/ipfs/helia) - Source code and examples
|
|
365
|
-
- [IPFS Documentation](https://docs.ipfs.tech/) - InterPlanetary File System docs
|
|
164
|
+
## Documentation
|
|
366
165
|
|
|
367
|
-
|
|
368
|
-
-
|
|
369
|
-
-
|
|
370
|
-
-
|
|
371
|
-
|
|
372
|
-
### WebAuthn & Authentication
|
|
373
|
-
|
|
374
|
-
#### WebAuthn Standard
|
|
375
|
-
- [WebAuthn W3C Specification](https://w3c.github.io/webauthn/) - Official WebAuthn standard
|
|
376
|
-
- [WebAuthn Guide](https://webauthn.guide/) - Comprehensive WebAuthn tutorial
|
|
377
|
-
- [MDN WebAuthn API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API) - Browser API documentation
|
|
378
|
-
|
|
379
|
-
#### Passkeys
|
|
380
|
-
- [Passkeys.dev](https://passkeys.dev/) - Complete guide to implementing passkeys
|
|
381
|
-
- [Apple Passkeys](https://developer.apple.com/passkeys/) - iOS/macOS passkey implementation
|
|
382
|
-
- [Google Passkeys](https://developers.google.com/identity/passkeys) - Android/Chrome passkey support
|
|
383
|
-
- [Microsoft Passkeys](https://docs.microsoft.com/en-us/microsoft-edge/web-platform/passkeys) - Windows Hello integration
|
|
384
|
-
|
|
385
|
-
#### Hardware Security Keys
|
|
386
|
-
|
|
387
|
-
##### Ledger WebAuthn
|
|
388
|
-
- [Ledger WebAuthn Support](https://support.ledger.com/hc/en-us/articles/115005198545-FIDO-U2F) - FIDO U2F and WebAuthn on Ledger devices
|
|
389
|
-
- [Ledger Developer Portal](https://developers.ledger.com/) - Building apps for Ledger hardware wallets
|
|
390
|
-
- [Ledger WebAuthn Example](https://github.com/LedgerHQ/ledger-live/tree/develop/apps/ledger-live-desktop/src/renderer/families/ethereum/WebAuthnModal) - Implementation examples
|
|
391
|
-
|
|
392
|
-
##### YubiKey WebAuthn
|
|
393
|
-
- [YubiKey WebAuthn Guide](https://developers.yubico.com/WebAuthn/) - Complete WebAuthn implementation guide
|
|
394
|
-
- [YubiKey Developer Program](https://developers.yubico.com/) - SDKs, libraries, and documentation
|
|
395
|
-
- [YubiKey WebAuthn Examples](https://github.com/Yubico/java-webauthn-server) - Server-side WebAuthn implementation
|
|
396
|
-
- [YubiKey JavaScript Library](https://github.com/Yubico/yubikit-web) - Web integration tools
|
|
397
|
-
|
|
398
|
-
#### Browser Compatibility
|
|
399
|
-
- [Can I Use WebAuthn](https://caniuse.com/webauthn) - Browser support matrix
|
|
400
|
-
- [WebAuthn Awesome List](https://github.com/herrjemand/awesome-webauthn) - Curated WebAuthn resources
|
|
401
|
-
- [FIDO Alliance](https://fidoalliance.org/) - Industry standards and certification
|
|
402
|
-
|
|
403
|
-
### Cryptography & DIDs
|
|
404
|
-
|
|
405
|
-
#### Decentralized Identifiers (DIDs)
|
|
406
|
-
- [DID W3C Specification](https://w3c.github.io/did-core/) - Official DID standard
|
|
407
|
-
- [DID Method Registry](https://w3c.github.io/did-spec-registries/) - Registered DID methods
|
|
408
|
-
- [DID Primer](https://github.com/WebOfTrustInfo/rwot5-boston/blob/master/topics-and-advance-readings/did-primer.md) - Introduction to DIDs
|
|
409
|
-
|
|
410
|
-
#### P-256 Elliptic Curve Cryptography
|
|
411
|
-
- [RFC 6090 - ECC Algorithms](https://tools.ietf.org/html/rfc6090) - Fundamental ECC operations
|
|
412
|
-
- [NIST P-256 Curve](https://csrc.nist.gov/csrc/media/events/workshop-on-elliptic-curve-cryptography-standards/documents/papers/session6-adalier-mehmet.pdf) - Technical specifications
|
|
413
|
-
- [WebCrypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) - Browser cryptography APIs
|
|
414
|
-
|
|
415
|
-
## Changelog
|
|
416
|
-
|
|
417
|
-
### v0.1.0 - DID Key Format Migration (2025-01-10)
|
|
418
|
-
|
|
419
|
-
**⚠️ BREAKING CHANGES**
|
|
420
|
-
|
|
421
|
-
- **DID Format Change**: Migrated from custom `did:webauthn:` format to standard-compliant `did:key:` format
|
|
422
|
-
- **Ucanto Compatibility**: Now compatible with ucanto's P-256 key support for UCAN delegation
|
|
423
|
-
- **Standard Compliance**: Uses proper multikey encoding with P-256 multicodec prefix (0x1200)
|
|
424
|
-
- **Base58btc Encoding**: Implements correct base58btc encoding for multikey representation
|
|
425
|
-
|
|
426
|
-
**Technical Changes**:
|
|
427
|
-
- Fixed varint encoding issues in multiformats integration
|
|
428
|
-
- Updated all tests to validate `did:key:` format instead of `did:webauthn:`
|
|
429
|
-
- Improved error handling and fallback mechanisms for DID generation
|
|
430
|
-
- Enhanced public key compression and encoding
|
|
431
|
-
|
|
432
|
-
**Migration Guide**: Existing credentials will generate new DID identifiers. Users will need to recreate their OrbitDB databases or migrate data manually.
|
|
433
|
-
|
|
434
|
-
### v0.0.2 - Initial WebAuthn Implementation (2024-12-20)
|
|
435
|
-
|
|
436
|
-
- Initial release with WebAuthn DID provider
|
|
437
|
-
- Custom `did:webauthn:` format (deprecated in v0.1.0)
|
|
438
|
-
- Basic OrbitDB integration
|
|
439
|
-
- Platform authenticator support
|
|
440
|
-
|
|
441
|
-
## Contributing
|
|
442
|
-
|
|
443
|
-
Contributions are welcome! Please ensure all tests pass and follow the existing code style.
|
|
166
|
+
- `docs/USAGE-GUIDE.md`
|
|
167
|
+
- `docs/ED25519-KEYSTORE-DID.md`
|
|
168
|
+
- `docs/WEBAUTHN-ENCRYPTED-KEYSTORE-INTEGRATION.md`
|
|
169
|
+
- `docs/WEBAUTHN-DID-AND-ORBITDB-IDENTITY.md`
|
|
444
170
|
|
|
445
171
|
## License
|
|
446
172
|
|
|
447
|
-
MIT
|
|
448
|
-
|
|
449
|
-
## Security Disclosures
|
|
450
|
-
|
|
451
|
-
For security vulnerabilities, please email security@le-space.de instead of using the issue tracker.
|
|
173
|
+
MIT. See `LICENSE`.
|
package/package.json
CHANGED
|
@@ -1,11 +1,16 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@le-space/orbitdb-identity-provider-webauthn-did",
|
|
3
|
-
"version": "0.1
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "WebAuthn-based DID identity provider for OrbitDB for hardware-secured wallets and biometric Passkey authentication",
|
|
5
5
|
"main": "src/index.js",
|
|
6
6
|
"type": "module",
|
|
7
|
+
"exports": {
|
|
8
|
+
".": "./src/index.js",
|
|
9
|
+
"./verification": "./verification.js"
|
|
10
|
+
},
|
|
7
11
|
"scripts": {
|
|
8
|
-
"
|
|
12
|
+
"postinstall": "patch-package",
|
|
13
|
+
"test": "npm run test:all",
|
|
9
14
|
"test:all": "playwright test",
|
|
10
15
|
"test:headed": "playwright test tests/webauthn-focused.test.js --headed --project=chromium",
|
|
11
16
|
"test:ui": "playwright test --ui",
|
|
@@ -14,8 +19,10 @@
|
|
|
14
19
|
"test:integration": "playwright test tests/webauthn-integration.test.js",
|
|
15
20
|
"test:verification": "playwright test tests/webauthn-verification.test.js --project=chromium",
|
|
16
21
|
"test:ci": "playwright test tests/webauthn-verification.test.js --project=chromium --reporter=github",
|
|
17
|
-
"test:
|
|
18
|
-
"test:
|
|
22
|
+
"test:logging": "DEBUG='orbitdb-identity-provider-webauthn-did*' playwright test tests/webauthn-logging-e2e.test.js --project=chromium --reporter=line",
|
|
23
|
+
"test:varsig-e2e": "playwright test tests/webauthn-varsig-e2e.test.js --project=chromium --reporter=line",
|
|
24
|
+
"test:encrypted-keystore": "USE_ENCRYPTED_DEMO=true playwright test tests/ed25519-encrypted-keystore-e2e.test.js --project=chromium --reporter=line",
|
|
25
|
+
"test:encrypted-keystore-headed": "USE_ENCRYPTED_DEMO=true playwright test tests/ed25519-encrypted-keystore-e2e.test.js --headed --project=chromium",
|
|
19
26
|
"test:full-flow": "npm run demo:setup && npm run test:focused",
|
|
20
27
|
"lint": "eslint src/ tests/",
|
|
21
28
|
"lint:fix": "eslint src/ tests/ --fix",
|
|
@@ -54,7 +61,16 @@
|
|
|
54
61
|
"@orbitdb/core": "^3.0.0"
|
|
55
62
|
},
|
|
56
63
|
"dependencies": {
|
|
64
|
+
"@ipld/dag-cbor": "^9.2.5",
|
|
65
|
+
"@libp2p/logger": "^5.1.5",
|
|
66
|
+
"@libp2p/crypto": "^5.1.8",
|
|
67
|
+
"@simplewebauthn/browser": "^13.0.0",
|
|
57
68
|
"cbor-web": "^9.0.1",
|
|
69
|
+
"iso-base": "npm:@le-space/iso-base",
|
|
70
|
+
"iso-did": "npm:@le-space/iso-did@2.1.2",
|
|
71
|
+
"iso-passkeys": "npm:@le-space/iso-passkeys",
|
|
72
|
+
"iso-web": "^2.1.0",
|
|
73
|
+
"iso-webauthn-varsig": "npm:@le-space/iso-webauthn-varsig",
|
|
58
74
|
"multiformats": "^13.0.0",
|
|
59
75
|
"vite-plugin-node-polyfills": "^0.24.0"
|
|
60
76
|
},
|
|
@@ -65,7 +81,8 @@
|
|
|
65
81
|
"eslint": "^9.0.0",
|
|
66
82
|
"helia": "^5.0.0",
|
|
67
83
|
"libp2p": "^2.0.0",
|
|
68
|
-
"mocha": "^10.0.0"
|
|
84
|
+
"mocha": "^10.0.0",
|
|
85
|
+
"patch-package": "^8.0.1"
|
|
69
86
|
},
|
|
70
87
|
"engines": {
|
|
71
88
|
"node": ">=18.0.0"
|
|
@@ -75,10 +92,23 @@
|
|
|
75
92
|
},
|
|
76
93
|
"files": [
|
|
77
94
|
"src/",
|
|
95
|
+
"verification.js",
|
|
78
96
|
"README.md",
|
|
79
97
|
"LICENSE",
|
|
80
98
|
"package.json"
|
|
81
99
|
],
|
|
100
|
+
"pnpm": {
|
|
101
|
+
"overrides": {
|
|
102
|
+
"iso-base": "npm:@le-space/iso-base",
|
|
103
|
+
"iso-did": "npm:@le-space/iso-did@2.1.2",
|
|
104
|
+
"iso-webauthn-varsig": "npm:@le-space/iso-webauthn-varsig"
|
|
105
|
+
},
|
|
106
|
+
"onlyBuiltDependencies": [
|
|
107
|
+
"@ipshipyard/node-datachannel",
|
|
108
|
+
"classic-level",
|
|
109
|
+
"esbuild"
|
|
110
|
+
]
|
|
111
|
+
},
|
|
82
112
|
"publishConfig": {
|
|
83
113
|
"access": "public"
|
|
84
114
|
}
|