Implement hybrid JWT signing with passkey attestation

- Remove Ethereum dependencies.
- Use SQLite for credential storage.
- Add comprehensive documentation, including guides for signing and verification flows.
- Add integrate tests.
- Update project structure and configuration files accordingly.

Author: Muhammad-Altabba

.gitignore

@@ -41,4 +41,6 @@ yarn-error.log*
 *.tsbuildinfo
 next-env.d.ts
 
-/database.json
+# database files
+/database.json
+/passkeys.db

FLOW.md

@@ -0,0 +1,172 @@
+# Signing & Verification Flow
+
+## Signing Flow
+
+### Step 1: Generate Ephemeral Key Pair
+
+```typescript
+const ephemeralKeys = await generateEphemeralKeyPair();
+// Creates: { publicKey, privateKey, publicKeyJWK, publicKeyFingerprint }
+```
+
+**What happens:**
+
+- Ed25519 key pair generated using Web Crypto API
+- Public key exported as JWK (JSON Web Key)
+- Fingerprint = SHA-256(canonical JWK)
+
+### Step 2: Passkey Signs Ephemeral Public Key
+
+```typescript
+const passkeyAttestation = await startAuthentication({
+  challenge: ephemeralKeys.publicKeyFingerprint,
+});
+```
+
+**What happens:**
+
+- Challenge = ephemeral public key fingerprint
+- User authenticates (biometric, PIN, etc.)
+- Passkey (in secure hardware) signs the challenge
+- Returns WebAuthn `AuthenticationResponseJSON`
+
+### Step 3: Build JWT Payload
+
+```typescript
+const payload = {
+  message: "your data",
+  nonce: "unique-value",
+  timestamp: Date.now(),
+  epk: ephemeralKeys.publicKeyJWK, // Ephemeral public key
+  passkey_attestation: {
+    credential_id: credentialId,
+    fingerprint: ephemeralKeys.publicKeyFingerprint,
+    signature: passkeyAttestation, // WebAuthn response
+  },
+};
+```
+
+### Step 4: Sign JWT with Ephemeral Private Key
+
+```typescript
+const jwt = await new SignJWT(payload)
+  .setProtectedHeader({ alg: "EdDSA", typ: "JWT" })
+  .sign(ephemeralKeys.privateKey);
+```
+
+**Result:** Standard JWT with structure `header.payload.signature`
+
+---
+
+## Verification Flow
+
+### Stage 1: Standard JWT Verification
+
+```typescript
+// Extract ephemeral public key from payload
+const parts = jwt.split(".");
+const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString());
+const publicKey = await importJWK(payload.epk, "EdDSA");
+
+// Verify JWT signature using jose
+const result = await jwtVerify(jwt, publicKey, { algorithms: ["EdDSA"] });
+// ✅ JWT signature valid
+```
+
+**Works with ANY JWT library** - This is standard JWT verification.
+
+### Stage 2: Passkey Attestation Verification
+
+```typescript
+const attestation = payload.passkey_attestation;
+
+// 1. Verify fingerprint matches ephemeral public key
+const fingerprintValid = await verifyPublicKeyFingerprint(
+  payload.epk,
+  attestation.fingerprint
+);
+
+// 2. Verify passkey signed the fingerprint
+const passkeyValid = await verifyAuthenticationResponse({
+  response: attestation.signature,
+  expectedChallenge: attestation.fingerprint,
+  expectedOrigin: origin,
+  expectedRPID: "localhost",
+  credential: { id, publicKey, counter, transports },
+});
+// ✅ Passkey attestation valid
+```
+
+**WebAuthn verification** - Ensures hardware-backed trust.
+
+---
+
+## JWT Structure
+
+```
+eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJtZXNzYWdl...
+│                                     │
+│  Header (base64url)                 │  Payload (base64url)
+│  { alg: "EdDSA", typ: "JWT" }       │  {
+│                                     │    message: "...",
+│                                     │    epk: { kty, crv, x },
+│                                     │    passkey_attestation: { ... }
+│                                     │  }
+│
+│  Signature (base64url)
+│  EdDSA signature by ephemeral private key
+```
+
+---
+
+## Security Properties
+
+### From Stage 1 (JWT)
+
+- Signature integrity (payload can't be modified)
+- Standard verification (any JWT library)
+
+### From Stage 2 (Passkey)
+
+- Hardware-backed trust (ephemeral key is attested)
+- Origin verification (prevents phishing)
+- User presence (proves user interaction)
+- Replay protection (counter mechanism)
+- Non-repudiation (only passkey holder can attest)
+
+---
+
+## API Endpoints
+
+### Sign JWT
+
+```typescript
+POST /api/sign
+{ jwt: "eyJ...", credentialId: "..." }
+```
+
+### Verify JWT
+
+```typescript
+POST / api / validate;
+{
+  jwt: "eyJ...";
+}
+// Returns: { valid, jwt_verified, passkey_verified, ... }
+```
+
+### Verify JWT Only (Stage 1)
+
+```typescript
+POST /api/validate
+{ jwt: "eyJ...", mode: "jwt_only" }
+// Demonstrates standard JWT verification works
+```
+
+### Inspect JWT
+
+```typescript
+POST /api/validate
+{ jwt: "eyJ...", mode: "inspect" }
+// Decodes without verification
+```

JWT-VERIFICATION-GUIDE.md

@@ -0,0 +1,177 @@
+# JWT Verification Guide
+
+## For External Applications
+
+This guide shows how to verify these JWTs in any application.
+
+## Option 1: Use the Verification Library
+
+### Installation
+
+```bash
+npm install jose @simplewebauthn/server
+```
+
+### Copy the Verifier
+
+Copy `src/lib/jwt-hybrid-verifier.ts` to your project.
+
+### Verify
+
+```typescript
+import { verifyHybridJWT } from "./jwt-hybrid-verifier";
+
+const result = await verifyHybridJWT(jwt, origin, async (credentialId) => {
+  // Your database lookup
+  const cred = await db.getCredential(credentialId);
+  return {
+    publicKey: cred.publicKeyBytes,
+    counter: cred.counter,
+    transports: cred.transports,
+    algorithm: cred.algorithm,
+  };
+});
+
+if (result.valid) {
+  console.log("✅ JWT verified!");
+  console.log("Payload:", result.payload);
+}
+```
+
+## Option 2: Use the REST API
+
+```bash
+curl -X POST http://localhost:3000/api/validate \
+  -H "Content-Type: application/json" \
+  -d '{"jwt": "eyJhbGci..."}'
+```
+
+**Response:**
+
+```json
+{
+  "valid": true,
+  "jwt_verified": true,
+  "passkey_verified": true,
+  "payload": { "message": "...", "nonce": "..." },
+  "details": {
+    "jwt_verification": "JWT signature verified",
+    "passkey_verification": "Passkey attested ephemeral key"
+  }
+}
+```
+
+## Option 3: Manual Implementation
+
+### Stage 1: Standard JWT Verification
+
+```typescript
+import { jwtVerify, importJWK } from "jose";
+
+// Decode to get ephemeral public key
+const parts = jwt.split(".");
+const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString());
+
+// Import and verify
+const publicKey = await importJWK(payload.epk, "EdDSA");
+const result = await jwtVerify(jwt, publicKey, { algorithms: ["EdDSA"] });
+// ✅ Stage 1 complete
+```
+
+### Stage 2: Passkey Attestation
+
+```typescript
+import { verifyAuthenticationResponse } from "@simplewebauthn/server";
+
+const attestation = payload.passkey_attestation;
+
+// Verify fingerprint matches
+const fingerprintMatches = await verifyPublicKeyFingerprint(
+  payload.epk,
+  attestation.fingerprint
+);
+
+// Verify WebAuthn signature
+const webauthnResult = await verifyAuthenticationResponse({
+  response: attestation.signature,
+  expectedChallenge: attestation.fingerprint,
+  expectedOrigin: origin,
+  expectedRPID: "localhost",
+  credential: {
+    /* from your database */
+  },
+});
+// ✅ Stage 2 complete
+```
+
+## Verification Modes
+
+### Full (Both Stages)
+
+```json
+{ "jwt": "..." }
+```
+
+Returns: `{ valid, jwt_verified, passkey_verified }`
+
+### JWT Only (Stage 1)
+
+```json
+{ "jwt": "...", "mode": "jwt_only" }
+```
+
+Demonstrates standard JWT verification works.
+
+### Inspect (No Verification)
+
+```json
+{ "jwt": "...", "mode": "inspect" }
+```
+
+Decodes header and payload using jose.
+
+## Other Languages
+
+### Python
+
+```python
+import requests
+
+response = requests.post(
+    'http://localhost:3000/api/validate',
+    json={'jwt': jwt_token}
+)
+result = response.json()
+```
+
+### Go
+
+```go
+type ValidationRequest struct {
+    JWT string `json:"jwt"`
+}
+
+resp, _ := http.Post(
+    "http://localhost:3000/api/validate",
+    "application/json",
+    bytes.NewBuffer(jsonData),
+)
+```
+
+### Any Language
+
+Use HTTP client → POST to `/api/validate` → Parse JSON response
+
+## FAQ
+
+**Q: Can I use standard JWT libraries?**  
+A: Yes for Stage 1! The JWT signature is standard EdDSA. Stage 2 requires WebAuthn verification.
+
+**Q: Why two stages?**  
+A: Stage 1 proves JWT integrity (standard). Stage 2 proves the signing key was attested by hardware (WebAuthn security).
+
+**Q: What if I only do Stage 1?**  
+A: You get standard JWT security. Stage 2 adds hardware-backed trust.
+
+**Q: Is this production-ready?**  
+A: Yes. Uses `jose` (20M+ weekly downloads) and `@simplewebauthn/server` (battle-tested).