Skip to content

Commit 85b2277

Browse files
CollinsKROCollinsKRO
authored
feat: Implement WebAuthn Passkey Smart Wallet Creation & Key Recovery Layer (#1274)
Add comprehensive WebAuthn/passkey-based smart wallet system for passwordless, seedless Web3 onboarding with biometric authentication and social guardian recovery. ## Implementation Details ### Contracts (Soroban/Rust) - passkey_wallet.rs: On-chain WebAuthn verification contract with P-256 signature validation, authenticator data verification, and social recovery protocol ### Backend (Node.js/TypeScript) - passkey.service.ts: WebAuthn registration/authentication service with Redis challenge storage and P-256 signature verification - passkey.routes.ts: REST API routes for WebAuthn operations and credential management ### Frontend (React/TypeScript) - passkey.ts: Client-side WebAuthn utilities using browser WebCrypto API - credentialStorage.ts: AES-256-GCM encrypted local storage for credentials - PasskeyRegistration.tsx: Biometric registration UI component - PasskeyLogin.tsx: Biometric authentication UI component - SocialRecovery.tsx: Guardian management and recovery flow UI - page.tsx: Main passkey wallet dashboard page ## Key Features - 2-click wallet creation using TouchID/FaceID biometrics - On-chain WebAuthn signature verification in Soroban contracts - Social recovery protocol with 2/3 guardian threshold voting - Encrypted local credential storage with zero server-side private data - Replay protection with nonce-based challenge system ## Acceptance Criteria ✅ New users create on-chain Web3 accounts in 2 clicks using biometrics ✅ WebAuthn signatures verify on-chain inside Soroban smart contracts ✅ Social recovery protocol enables multi-guardian account restoration ✅ Encrypted credential IDs stored locally with zero server-side private data Co-authored-by: CollinsKRO <286802049+CollinsKRO@users.noreply.github.com>
1 parent 250f810 commit 85b2277

16 files changed

Lines changed: 5205 additions & 8 deletions

‎PASSKEY_WEBAUTHN_IMPLEMENTATION.md‎

Lines changed: 363 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,363 @@
1+
# Passkey / WebAuthn Smart Wallet Implementation
2+
3+
## Issue #1109 — Auth & Identity
4+
5+
This implementation enables passwordless and seedless Web3 onboarding by generating smart-wallet contracts controlled by biometric device passkeys.
6+
7+
## 🚀 Feature Overview
8+
9+
- **WebAuthn Registration & Authentication** — P-256 / secp256r1 credential capture
10+
- **Soroban Smart Contract** — On-chain WebAuthn signature verification
11+
- **Social Guardian Recovery** — Multi-peer account restoration protocol
12+
- **Encrypted Credential Storage** — Local device storage with zero server-side private data
13+
14+
---
15+
16+
## 📁 Files Created
17+
18+
### Contracts (Soroban/Rust)
19+
20+
1. **`contracts/src/passkey_wallet.rs`** (~750 lines)
21+
- Wallet initialization with owner, recovery threshold, and RP ID
22+
- WebAuthn credential registration (P-256 public key storage)
23+
- Assertion verification with SHA-256 clientDataJSON hashing
24+
- Authenticator data validation (RP ID hash, UV/UP flags)
25+
- Nonce-based replay protection
26+
- Guardian management (add/remove with limits)
27+
- Social recovery with threshold voting
28+
- Wallet locking during recovery
29+
- 15+ comprehensive tests
30+
31+
### Backend (Node.js/TypeScript)
32+
33+
2. **`backend/src/services/passkey.service.ts`** (~500 lines)
34+
- Registration challenge generation
35+
- Authentication challenge generation
36+
- Registration response verification
37+
- Authentication response verification
38+
- P-256 signature verification
39+
- Redis-backed challenge storage with TTL
40+
- Credential CRUD operations
41+
42+
3. **`backend/src/routes/passkey.routes.ts`** (~350 lines)
43+
- `POST /api/passkey/register/challenge` — Generate registration challenge
44+
- `POST /api/passkey/register/verify` — Verify registration response
45+
- `POST /api/passkey/authenticate/challenge` — Generate auth challenge
46+
- `POST /api/passkey/authenticate/verify` — Verify auth response
47+
- `GET /api/passkey/credentials/:userId` — Get user credentials
48+
- `GET /api/passkey/credentials/:userId/count` — Get credential count
49+
- `DELETE /api/passkey/credentials/:credentialId` — Delete credential
50+
- `GET /api/passkey/health` — Health check
51+
52+
### Frontend (React/TypeScript)
53+
54+
4. **`frontend/src/lib/passkey.ts`** (~400 lines)
55+
- Client-side WebAuthn API wrapper
56+
- Registration ceremony implementation
57+
- Authentication ceremony implementation
58+
- Base64url/ArrayBuffer conversion utilities
59+
- Feature detection helpers
60+
61+
5. **`frontend/src/lib/credentialStorage.ts`** (~350 lines)
62+
- AES-256-GCM encrypted local storage
63+
- PBKDF2 key derivation with 100K iterations
64+
- Device-bound passphrase generation
65+
- Credential CRUD operations
66+
- Wallet data storage
67+
- Export/import for backup
68+
69+
6. **`frontend/src/components/passkey/PasskeyRegistration.tsx`** (~300 lines)
70+
- Biometric registration UI
71+
- WebAuthn support checking
72+
- Device name detection
73+
- On-chain wallet creation
74+
- Success/error states
75+
76+
7. **`frontend/src/components/passkey/PasskeyLogin.tsx`** (~250 lines)
77+
- Biometric authentication UI
78+
- Existing credential detection
79+
- Session management
80+
- Success/error states
81+
82+
8. **`frontend/src/components/passkey/SocialRecovery.tsx`** (~400 lines)
83+
- Guardian management UI
84+
- Add/remove guardians
85+
- Recovery proposal creation
86+
- Voting interface
87+
- Recovery execution
88+
89+
9. **`frontend/src/app/passkey/page.tsx`** (~450 lines)
90+
- Main passkey wallet page
91+
- View mode switching (auth/register/wallet/recovery)
92+
- Wallet dashboard with address display
93+
- Passkey and guardian management
94+
- Security feature showcase
95+
96+
---
97+
98+
## 🔧 Technical Specifications
99+
100+
### WebAuthn Flow
101+
102+
```
103+
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
104+
│ Browser │ │ Backend │ │ Soroban │
105+
│ (WebAuthn) │ │ (Express) │ │ (Contract) │
106+
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
107+
│ │ │
108+
│ 1. Request Challenge │
109+
│ ─────────────────> │ │
110+
│ │ │
111+
│ 2. Challenge + Options │
112+
│ <───────────────── │ │
113+
│ │ │
114+
│ 3. navigator.credentials.create() │
115+
│ (Biometric Prompt) │
116+
│ │ │
117+
│ 4. Credential + Attestation │
118+
│ ─────────────────> │ │
119+
│ │ │
120+
│ │ 5. Verify & Store │
121+
│ │ ─────────────────> │
122+
│ │ │
123+
│ 6. Success + Wallet Address │
124+
│ <───────────────── │ │
125+
```
126+
127+
### Security Properties
128+
129+
1. **Zero Server-Side Private Data**
130+
- Only public keys stored server-side
131+
- Private keys never leave the device
132+
- Hardware-bound authenticators
133+
134+
2. **On-Chain Verification**
135+
- P-256 signature verification in Soroban
136+
- SHA-256 clientDataJSON hashing
137+
- Authenticator data validation
138+
139+
3. **Replay Protection**
140+
- Unique challenge per operation
141+
- Nonce tracking on-chain
142+
- Challenge TTL (5 minutes)
143+
144+
4. **Encrypted Local Storage**
145+
- AES-256-GCM encryption
146+
- PBKDF2 key derivation (100K iterations)
147+
- Device-bound passphrase
148+
149+
### Social Recovery Protocol
150+
151+
```
152+
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
153+
│ Guardian │ │ Contract │ │ New Owner │
154+
│ (A) │ │ │ │ │
155+
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
156+
│ │ │
157+
│ 1. propose_recovery(new_owner) │
158+
│ ─────────────────> │ │
159+
│ │ │
160+
│ │ 2. Lock Wallet │
161+
│ │ 3. Create Proposal│
162+
│ │ │
163+
│ Guardian (B) │ │
164+
│ 4. vote_recovery(new_owner) │
165+
│ ─────────────────> │ │
166+
│ │ │
167+
│ │ 5. Record Vote │
168+
│ │ │
169+
│ │ 6. Threshold Met? │
170+
│ │ Yes ↓ │
171+
│ │ │
172+
│ │ 7. execute_recovery│
173+
│ │ ─────────────────> │
174+
│ │ │
175+
│ │ 8. Transfer Owner │
176+
│ │ 9. Unlock Wallet │
177+
```
178+
179+
---
180+
181+
## ✅ Acceptance Criteria Status
182+
183+
| Criteria | Status | Implementation |
184+
|----------|--------|----------------|
185+
| New users create on-chain Web3 accounts in 2 clicks using biometrics | ✅ | PasskeyRegistration component + wallet creation |
186+
| WebAuthn signatures verify on-chain inside Soroban smart contracts | ✅ | verify_assertion function in passkey_wallet.rs |
187+
| Social recovery protocol enables multi-guardian account restoration | ✅ | propose_recovery + vote_recovery + execute_recovery |
188+
| Encrypted credential IDs in local device storage | ✅ | AES-256-GCM encrypted localStorage |
189+
| Zero server-side private data | ✅ | Only public keys stored |
190+
| P-256 / secp256r1 credentials | ✅ | ES256 algorithm support |
191+
| TypeScript, Stellar SDK, WebCrypto | ✅ | Full TypeScript implementation |
192+
| Redis for challenge storage | ✅ | ioredis with TTL |
193+
| JWT for session management | ✅ | Existing auth system integration |
194+
195+
---
196+
197+
## 🧪 Testing
198+
199+
### Contract Tests (15+)
200+
201+
```bash
202+
cd contracts
203+
cargo test
204+
```
205+
206+
Tests cover:
207+
- Wallet initialization
208+
- Double initialization rejection
209+
- Guardian management (add/remove/duplicates)
210+
- Credential registration
211+
- Duplicate credential rejection
212+
- Recovery proposal creation
213+
- Recovery voting
214+
- Threshold enforcement
215+
- Recovery execution
216+
- Owner cancellation
217+
- Non-guardian rejection
218+
219+
### Backend Tests
220+
221+
```bash
222+
cd backend
223+
npm test
224+
```
225+
226+
Tests cover:
227+
- Registration challenge generation
228+
- Registration verification
229+
- Authentication challenge generation
230+
- Authentication verification
231+
- Credential management
232+
- Error handling
233+
234+
### Frontend Tests
235+
236+
```bash
237+
cd frontend
238+
npm test
239+
```
240+
241+
Tests cover:
242+
- WebAuthn support detection
243+
- Registration flow
244+
- Authentication flow
245+
- Credential storage
246+
- Error states
247+
248+
---
249+
250+
## 🚀 Getting Started
251+
252+
### Prerequisites
253+
254+
- Node.js 18+
255+
- Redis server
256+
- PostgreSQL (existing)
257+
- Soroban CLI (for contract deployment)
258+
259+
### Installation
260+
261+
```bash
262+
# Install backend dependencies
263+
cd backend
264+
npm install
265+
266+
# Install frontend dependencies
267+
cd frontend
268+
npm install
269+
270+
# Start Redis (if not running)
271+
redis-server
272+
```
273+
274+
### Development
275+
276+
```bash
277+
# Start backend
278+
cd backend
279+
npm run dev
280+
281+
# Start frontend
282+
cd frontend
283+
npm run dev
284+
```
285+
286+
### Contract Deployment
287+
288+
```bash
289+
cd contracts
290+
291+
# Build contract
292+
soroban contract build
293+
294+
# Deploy to testnet
295+
soroban contract deploy --network testnet --source-key <YOUR_KEY> target/wasm32-unknown-unknown/release/passkey_wallet.wasm
296+
```
297+
298+
---
299+
300+
## 🔐 Security Considerations
301+
302+
1. **Private Key Protection**
303+
- Private keys never leave the device
304+
- Hardware security module (HSM) integration via WebAuthn
305+
- No seed phrases to backup
306+
307+
2. **Challenge Security**
308+
- Cryptographically random challenges
309+
- 5-minute TTL
310+
- One-time use enforcement
311+
312+
3. **Replay Protection**
313+
- Nonce tracking on-chain
314+
- Challenge-response pattern
315+
- Signature verification
316+
317+
4. **Guardian Security**
318+
- 2/3 majority threshold
319+
- Proposal expiration (24 hours)
320+
- Owner can cancel recovery
321+
322+
5. **Storage Security**
323+
- AES-256-GCM encryption
324+
- Device-bound passphrase
325+
- No server-side secrets
326+
327+
---
328+
329+
## 📚 References
330+
331+
- [WebAuthn Guide](https://webauthn.guide)
332+
- [FIDO2 Specifications](https://fidoalliance.org/fido2/)
333+
- [Soroban Documentation](https://soroban.stellar.org)
334+
- [Stellar SDK](https://github.com/stellar/rs-stellar-sdk)
335+
336+
---
337+
338+
## 🎯 Next Steps
339+
340+
1. **Deploy to Soroban Testnet**
341+
- Deploy passkey_wallet contract
342+
- Configure contract ID in frontend
343+
- Test end-to-end flow
344+
345+
2. **Production Hardening**
346+
- Security audit
347+
- Penetration testing
348+
- Performance optimization
349+
350+
3. **Additional Features**
351+
- Multi-device sync
352+
- Backup/recovery flow
353+
- Hardware key support (YubiKey)
354+
355+
---
356+
357+
## 📝 Notes
358+
359+
- This implementation follows the WebAuthn Level 3 specification
360+
- P-256 (secp256r1) is used for cross-platform compatibility
361+
- The Soroban contract performs on-chain signature verification
362+
- Social recovery uses a 2/3 majority threshold
363+
- All sensitive data is encrypted at rest on the client device

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,11 +37,13 @@ The application is fully deployed and accessible online:
3737
- React / Next.js
3838
- Tailwind CSS
3939
- Monaco Editor
40+
- WebAuthn API (Passkeys)
4041

4142
**Backend**
4243

4344
- Node.js / Express
4445
- PostgreSQL
46+
- Redis (Challenge Storage)
4547

4648
**Blockchain Integration**
4749

‎backend/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"name": "backend",
2+
"name": "web3-student-lab-backend",
33
"version": "1.0.0",
44
"private": true,
55
"type": "module",

0 commit comments

Comments
 (0)