Skip to content

README_PASSKEY_CONNECTION.md

Latest commit

 

History

History
262 lines (198 loc) · 5.9 KB

README_PASSKEY_CONNECTION.md

File metadata and controls

262 lines (198 loc) · 5.9 KB

Passkey Connection Flow - Complete Implementation

✅ What Was Added

A complete flow for connecting a passkey to an existing authenticated user session.

Problem

User signs up with Google, wants to add a passkey:

  • ❌ Standard registration tries to create session (fails)
  • ❌ Can't verify it's the same user
  • ❌ UX is broken

Solution

Dedicated connection endpoints that require existing session.

Files Overview

New Endpoints

app/api/webauthn/connect/
  ├── options/route.ts       (Generate registration options)
  └── verify/route.ts        (Verify & store passkey)

Documentation

PASSKEY_CONNECTION_FLOW.md         (Comprehensive guide)
PASSKEY_CONNECTION_STATUS.md       (Implementation notes)
PASSKEY_CONNECTION_QUICKSTART.md   (Quick reference)

How It Works

Flow

Authenticated User (Google logged in)
    ↓
Click "Link Passkey"
    ↓
POST /api/webauthn/connect/options
  ├─ Check session exists ✓
  └─ Generate challenge ✓
    ↓
User confirms on device (biometric)
    ↓
POST /api/webauthn/connect/verify
  ├─ Check session ✓
  ├─ Verify WebAuthn ✓
  ├─ Store passkey ✓
  └─ NO new session ← Key point
    ↓
Success! Passkey linked.
User stays authenticated with existing session.

Key Features

✅ Identity Verified: Session proves who user is ✅ No Session Conflict: Doesn't try to create new session ✅ Same Security: Uses all same WebAuthn checks as registration ✅ Rate Limited: Same limits as authentication ✅ No Account Hijacking: Session binding prevents attacks ✅ Seamless UX: User stays logged in throughout

Endpoints

POST /api/webauthn/connect/options

Generate WebAuthn registration options for existing user.

Required:

  • Authorization header with session token
  • email in body

Returns: WebAuthn options + challenge token

POST /api/webauthn/connect/verify

Verify device ownership and store passkey.

Required:

  • Authorization header with session token
  • WebAuthn attestation response
  • Challenge token

Returns: { success: true }

Usage Example

// User already logged in with Google
const sessionToken = getSessionToken();
const email = getCurrentUserEmail();

// 1. Get options
const options = await fetch('/api/webauthn/connect/options', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sessionToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ email })
}).then(r => r.json());

// 2. Create credential (user touches device)
const attestation = await navigator.credentials.create({
  publicKey: options
});

// 3. Verify
const result = await fetch('/api/webauthn/connect/verify', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sessionToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email,
    assertion: attestation,
    challenge: options.challenge,
    challengeToken: options.challengeToken
  })
}).then(r => r.json());

// Done! Passkey connected, user stays logged in

Security Model

Same WebAuthn verification as registration, PLUS:

  • Session requirement (identity proof)
  • User binding via session (can't hijack)
  • Rate limiting (same as auth)
  • Challenge time-binding (120s expiry)

Result: Connection is MORE secure than registration.

Comparison

Feature Registration Connection Auth
Endpoint /register/ /connect/ /auth/
Session Required ❌ ✅ ❌
Creates Session ✅ ❌ ✅
Purpose New account Link passkey Sign in
Use When Signup Add to existing Login

Use Cases

Primary: "Add Passkey" Feature

  1. User signs up with Google OAuth
  2. User goes to account settings
  3. User clicks "Add Passkey"
  4. User confirms on device
  5. Passkey stored
  6. User can now sign in with passkey

Secondary: Multi-Factor

  • User can have multiple auth methods
  • Google + Passkey = two ways to sign in
  • Account recovery if one method fails

Tertiary: No-Password Future

  • Transition away from passwords
  • Keep existing auth (Google, email, etc.)
  • Add passkey as modern alternative

Status

✅ Implementation: Complete ✅ Documentation: Complete ✅ Build: Passes ✅ TypeScript: Clean ✅ Security: Verified ✅ Backwards Compatible: 100%

Next Steps

  1. Read: PASSKEY_CONNECTION_QUICKSTART.md (5 min)
  2. Read: PASSKEY_CONNECTION_FLOW.md (15 min)
  3. Integrate: Add UI button for "Link Passkey"
  4. Test: Try with different devices
  5. Deploy: Roll out to users

Technical Details

Code Reuse

  • Uses existing issueChallenge()
  • Uses existing verifyChallengeToken()
  • Uses existing registerPasskey()
  • Uses existing rate limiting
  • No duplicated logic

Security Checks

  • Session validation
  • User verification
  • Challenge binding
  • WebAuthn verification
  • Rate limiting
  • Cryptographic validation

No New Dependencies

  • ✅ Uses existing @simplewebauthn
  • ✅ Uses existing crypto
  • ✅ Uses existing Appwrite integration

Differences from Registration

Registration

Unauthenticated → New User → Passkey + Session

Connection

Authenticated → Existing User → Passkey + No Session ← Key difference!

The key difference: No session creation because user already has one.

Files

Code (New)

  • app/api/webauthn/connect/options/route.ts (108 lines)
  • app/api/webauthn/connect/verify/route.ts (243 lines)

Documentation

  • PASSKEY_CONNECTION_FLOW.md - Full guide
  • PASSKEY_CONNECTION_STATUS.md - Implementation notes
  • PASSKEY_CONNECTION_QUICKSTART.md - Quick reference
  • This file - Overview

Status: ✅ Ready for integration and testing

For quick overview, read: PASSKEY_CONNECTION_QUICKSTART.md For full details, read: PASSKEY_CONNECTION_FLOW.md