bro-auth 0.1.4 → 0.2.0

package/README.md

@@ -1,169 +1,231 @@
 # bro-auth
 
-```
-┌──────────────────────────────────────────────────────────────┐
-│  █▄▄ █▀█ █▀█   █▀█ █ █ ▀█▀ █ █      bro-auth                 │
-│  █▄█ █▀▄ █▄█   █▀█ █▄█  █  █▀█                               │
-├──────────────────────────────────────────────────────────────┤
-│     Stateless JWT · Device Fingerprinting · Zero Replay      │
-└──────────────────────────────────────────────────────────────┘
-```
-
-A lightweight, **stateless**, and **high-security** authentication layer that combines JWT tokens with device fingerprinting to prevent token theft and replay attacks—no database required.
+**Stateless JWT authentication with device fingerprint binding and derived signing keys.**
 
 [![npm version](https://img.shields.io/npm/v/bro-auth.svg)](https://www.npmjs.com/package/bro-auth)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
 ---
 
-## 🎯 Why bro-auth?
+## Overview
+
+`bro-auth` is a Node.js library that binds JWT tokens to browser devices using fingerprinting and derives signing keys from application-provided secrets. This prevents token replay attacks and limits the impact of token theft.
+
+**What bro-auth does:**
+- Generates and verifies JWT tokens bound to device fingerprints
+- Derives unique signing secrets per user-device combination using HMAC
+- Provides browser fingerprinting utilities
+
+**What bro-auth does NOT do:**
+- Manage secrets or environment variables (your application's responsibility)
+- Prevent XSS attacks (your application's responsibility)
+- Handle login UI or session management (your application's responsibility)
+
+---
 
-Traditional JWT authentication has a critical weakness: **stolen tokens work from any device**. If an attacker intercepts your JWT, they can use it from anywhere until it expires.
+## Why Use bro-auth?
 
-**bro-auth solves this** by binding tokens to specific devices using browser fingerprinting. Even if a token is stolen, it won't work on a different device.
+Traditional JWT tokens work from any device if stolen. `bro-auth` binds tokens to specific devices, making stolen tokens unusable on different browsers.
 
-### Key Benefits
+### Attack Mitigation
 
-- 🔐 **Stateless JWT authentication** - No session storage needed
-- 🆔 **Device fingerprint binding** - Tokens only work on the issuing device
-- 🚫 **Replay attack protection** - Stolen tokens are useless on other browsers
-- ⚡ **Zero dependencies** - Lightweight core (only `jsonwebtoken` + `crypto-es`)
-- 🧩 **Framework agnostic** - Works with Next.js, Express, Fastify, or vanilla Node
-- 🌐 **Browser module included** - Easy fingerprint extraction
-- 📦 **Production ready** - TypeScript support, comprehensive error handling
+For an attacker to successfully use a stolen token, they would need:
+
+1. The JWT token itself (stolen via XSS, network interception, etc.)
+2. The user ID (embedded in token)
+3. The application's access/refresh secrets
+4. The exact device fingerprint hash (SHA-256)
+5. The application's server-only pepper (`BRO_AUTH_SECRET_PEPPER`)
+
+Even with items 1-4, the attacker cannot:
+- Use the token from a different device (fingerprint mismatch fails verification)
+- Forge new tokens (requires the server-only pepper)
+- Replay the token (derived secret verification fails)
+
+### Security Scope & Limitations
+
+**What bro-auth protects against:**
+- Token replay from different devices
+- Token forgery without server secrets
+- Credential stuffing across devices
+
+**What bro-auth does NOT protect against:**
+- XSS attacks during active execution (attacker can make requests while JS runs)
+- Full server compromise (if secrets are leaked, all bets are off)
+- Social engineering or phishing attacks
+- Browser fingerprint spoofing (though difficult, it's theoretically possible)
+
+**Your application must:**
+- Implement XSS prevention (CSP, input sanitization, etc.)
+- Store tokens securely (HTTP-only cookies for refresh tokens)
+- Protect environment variables and secrets
+- Use HTTPS in production
 
 ---
 
-## 📦 Installation
+## Installation
 
 ```bash
 npm install bro-auth
 ```
 
-```bash
-yarn add bro-auth
+---
+
+## How It Works
+
+### 1. Authentication Flow
+
+```
+Browser                                    Server
+  │
+  ├─ Generate fingerprint hash
+  │  (Canvas, GPU, User-Agent, etc.)
+  │
+  ├─ POST /login ────────────────────────▶ Verify credentials
+  │  { username, password, fpHash }        │
+  │                                        ├─ Derive signing secret:
+  │                                        │  HMAC(pepper, secret|userId|fpHash)
+  │                                        │
+  │                                        ├─ Sign JWT with derived secret
+  │                                        │  Payload: { sub: userId, fp: fpHash }
+  │                                        │
+  │  ◀──────────────────────────────────── Return tokens
+  │  { accessToken, refreshToken }
+  │
 ```
 
-```bash
-pnpm add bro-auth
+### 2. Verification Flow
+
+```
+Browser                                    Server
+  │
+  ├─ GET /api/protected ─────────────────▶ Extract token & fpHash
+  │  Headers:                              │
+  │    Authorization: Bearer <token>       ├─ Decode token (unsafe)
+  │    X-Fingerprint: <fpHash>             │  Extract userId from payload
+  │                                        │
+  │                                        ├─ Re-derive signing secret:
+  │                                        │  HMAC(pepper, secret|userId|fpHash)
+  │                                        │
+  │                                        ├─ Verify JWT signature
+  │                                        │  jwt.verify(token, derivedSecret)
+  │                                        │
+  │                                        ├─ Compare fingerprints
+  │                                        │  payload.fp === request.fpHash
+  │                                        │
+  │  ◀──────────────────────────────────── Grant access ✓
+  │
 ```
 
+### 3. Why Stolen Tokens Fail
+
+```
+Attacker (Different Device)                Server
+  │
+  ├─ GET /api/protected ─────────────────▶ Extract token & fpHash
+  │  Token: <stolen_token>                 │
+  │  Fingerprint: <attacker_fp_hash>       ├─ Decode token
+  │                                        │  payload.fp = <victim_fp_hash>
+  │                                        │
+  │                                        ├─ Derive secret using attacker's FP:
+  │                                        │  HMAC(pepper, secret|userId|attacker_fp)
+  │                                        │
+  │                                        ├─ Verify signature
+  │                                        │  ✗ FAILS - Different derived secret
+  │                                        │
+  │  ◀──────────────────────────────────── Reject: "invalid signature"
+  │
+```
+
+**Key insight:** The signing secret is derived from the fingerprint. A different fingerprint produces a different secret, causing signature verification to fail.
+
 ---
 
-## 🧠 How It Works
+## Quick Start
 
-```mermaid
-sequenceDiagram
-    participant Browser
-    participant Server
-    
-    Browser->>Browser: Generate device fingerprint
-    Browser->>Server: Login with credentials + fingerprint
-    Server->>Server: Hash fingerprint (SHA-256)
-    Server->>Server: Create JWT bound to fingerprint hash
-    Server->>Browser: Return access + refresh tokens
-    
-    Browser->>Server: API request with token + fingerprint
-    Server->>Server: Verify token signature
-    Server->>Server: Verify fingerprint match
-    Server->>Browser: Grant access ✅
-    
-    Note over Browser,Server: If attacker steals token...
-    
-    Browser->>Server: Request from different device
-    Server->>Server: Fingerprint mismatch detected
-    Server->>Browser: Reject request ❌
-```
+### Step 1: Configure Environment Variables
 
-### The Security Flow
+Create a `.env` file in your application (NOT in bro-auth):
 
-1. **Client generates a device fingerprint** using browser characteristics (User-Agent, screen, GPU, canvas, etc.)
-2. **Server receives fingerprint** during login and creates a SHA-256 hash
-3. **JWT tokens are bound** to this fingerprint hash in their payload
-4. **Every request is verified** for both token validity and fingerprint match
-5. **Token theft is mitigated** - stolen tokens fail fingerprint verification on different devices
+```bash
+# Required: Application-owned server-only pepper
+# bro-auth requires this but does NOT provide it
+BRO_AUTH_SECRET_PEPPER=your-random-string-min-32-chars-never-expose
 
----
+# Your application's JWT signing secrets
+ACCESS_SECRET=your-access-secret-min-32-chars
+REFRESH_SECRET=your-refresh-secret-min-32-chars
+```
 
-## 🚀 Quick Start
+**Important:** These are YOUR application's secrets. `bro-auth` reads them but does not manage or provide them.
 
-### 1. Browser: Generate Device Fingerprint
+### Step 2: Browser - Generate Fingerprint
 
 ```javascript
 import { getFingerprint } from "bro-auth/browser";
 
 async function handleLogin() {
-  const fp = await getFingerprint();
+  // Generate device fingerprint hash
+  const fpHash = await getFingerprint();
+  
+  // fpHash is a string: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
   
-  // Send to your login endpoint
   const response = await fetch("/api/login", {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({
       username: "user@example.com",
-      password: "password",
-      fingerprint: fp.hash
+      password: "password123",
+      fingerprint: fpHash
     })
   });
   
   const { accessToken, refreshToken } = await response.json();
-  // Store tokens securely
-}
-```
-
-**Fingerprint output example:**
-
-```json
-{
-  "hash": "53ff76d8a4c21b9c8e3f1a7d9e2c4b5a8f1e3d6c9b2a5e8f1d4c7b0a3e6f9c2696",
-  "raw": "Mozilla/5.0|1920x1080|ANGLE (Intel, Mesa Intel UHD)|canvas_data...",
-  "components": {
-    "userAgent": "Mozilla/5.0 (X11; Linux x86_64)...",
-    "screenResolution": "1920x1080",
-    "gpu": "ANGLE (Intel, Mesa Intel UHD Graphics 620)",
-    "canvas": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
-    "timezone": "America/New_York"
-  }
+  
+  // Store tokens (see security best practices)
+  sessionStorage.setItem("accessToken", accessToken);
 }
 ```
 
-### 2. Server: Generate Tokens
+### Step 3: Server - Generate Tokens
 
 ```javascript
-import { generateTokens } from "bro-auth";
+import { generateTokens } from "bro-auth/core";
 
 app.post("/api/login", async (req, res) => {
   const { username, password, fingerprint } = req.body;
   
-  // Verify credentials (your logic here)
-  const user = await verifyCredentials(username, password);
+  // 1. Verify credentials (your logic)
+  const user = await authenticateUser(username, password);
   if (!user) {
     return res.status(401).json({ error: "Invalid credentials" });
   }
   
-  // Generate tokens bound to device fingerprint
-  const { accessToken, refreshToken } = generateTokens({
-    userId: user.id,
-    fingerprintHash: fingerprint,
-    accessSecret: process.env.ACCESS_SECRET,
-    refreshSecret: process.env.REFRESH_SECRET,
-    accessExpiresIn: "15m",  // Optional: default 15m
-    refreshExpiresIn: "7d"   // Optional: default 7d
-  });
+  // 2. Generate device-bound tokens
+  const { accessToken, refreshToken } = generateTokens(
+    user.id,                          // userId
+    fingerprint,                      // fpHash from browser
+    process.env.ACCESS_SECRET,        // your secret
+    process.env.REFRESH_SECRET        // your secret
+  );
   
   res.json({ accessToken, refreshToken });
 });
 ```
 
-### 3. Server: Verify Access Token
+### Step 4: Server - Verify Requests
 
 ```javascript
-import { verifyAccessToken } from "bro-auth";
+import { verifyAccessToken } from "bro-auth/core";
 
 app.get("/api/protected", (req, res) => {
   const token = req.headers.authorization?.replace("Bearer ", "");
   const fingerprint = req.headers["x-fingerprint"];
   
+  if (!token || !fingerprint) {
+    return res.status(401).json({ error: "Missing credentials" });
+  }
+  
   const result = verifyAccessToken(
     token,
     fingerprint,
@@ -175,15 +237,15 @@ app.get("/api/protected", (req, res) => {
   }
   
   // Access granted
-  const userId = result.payload.userId;
-  res.json({ message: "Protected data", userId });
+  const userId = result.payload.sub;
+  res.json({ message: "Success", userId });
 });
 ```
 
-### 4. Server: Refresh Tokens
+### Step 5: Server - Refresh Tokens
 
 ```javascript
-import { verifyRefreshToken, generateTokens, buildRefreshCookie } from "bro-auth";
+import { verifyRefreshToken, generateTokens } from "bro-auth/core";
 
 app.post("/api/refresh", (req, res) => {
   const { refreshToken, fingerprint } = req.body;
@@ -195,20 +257,16 @@ app.post("/api/refresh", (req, res) => {
   );
   
   if (!result.valid) {
-    return res.status(401).json({ error: result.error });
+    return res.status(401).json({ error: "Invalid refresh token" });
   }
   
   // Issue new token pair
-  const tokens = generateTokens({
-    userId: result.payload.userId,
-    fingerprintHash: fingerprint,
-    accessSecret: process.env.ACCESS_SECRET,
-    refreshSecret: process.env.REFRESH_SECRET
-  });
-  
-  // Optional: Set refresh token as HTTP-only cookie
-  const cookie = buildRefreshCookie(tokens.refreshToken);
-  res.setHeader("Set-Cookie", cookie);
+  const tokens = generateTokens(
+    result.payload.sub,
+    fingerprint,
+    process.env.ACCESS_SECRET,
+    process.env.REFRESH_SECRET
+  );
   
   res.json({ accessToken: tokens.accessToken });
 });
@@ -216,162 +274,310 @@ app.post("/api/refresh", (req, res) => {
 
 ---
 
-## 📚 API Reference
+## API Reference
 
-### Browser Module
+### Browser Module (`bro-auth/browser`)
 
-#### `getFingerprint(): Promise<FingerprintResult>`
+#### `getFingerprint()`
 
-Generates a unique device fingerprint from browser characteristics.
+Generates a SHA-256 hash of browser device characteristics.
 
-**Returns:**
-```typescript
-{
-  hash: string;        // SHA-256 hash (send to server)
-  raw: string;         // Raw concatenated fingerprint data
-  components: {        // Individual fingerprint components
-    userAgent: string;
-    screenResolution: string;
-    gpu: string;
-    canvas: string;
-    timezone: string;
-    // ... more components
-  }
-}
+**Returns:** `Promise<string>`
+
+**Example:**
+```javascript
+const fpHash = await getFingerprint();
+// "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
 ```
 
-### Server Module
+---
+
+### Server Module (`bro-auth/core`)
 
-#### `generateTokens(options): TokenPair`
+#### `generateTokens(userId, fpHash, accessSecret, refreshSecret)`
 
-Creates JWT access and refresh tokens bound to a device fingerprint.
+Generates access and refresh tokens bound to a device fingerprint.
 
 **Parameters:**
-- `userId` (string): Unique user identifier
-- `fingerprintHash` (string): Device fingerprint hash from browser
-- `accessSecret` (string): Secret key for access tokens
-- `refreshSecret` (string): Secret key for refresh tokens
-- `accessExpiresIn` (string, optional): Access token TTL (default: "15m")
-- `refreshExpiresIn` (string, optional): Refresh token TTL (default: "7d")
-
-**Returns:**
-```typescript
-{
-  accessToken: string;
-  refreshToken: string;
-}
+- `userId` (string) - Unique user identifier
+- `fpHash` (string) - Device fingerprint hash from browser
+- `accessSecret` (string) - Your application's access token secret
+- `refreshSecret` (string) - Your application's refresh token secret
+
+**Returns:** `{ accessToken: string, refreshToken: string }`
+
+**Example:**
+```javascript
+const tokens = generateTokens(
+  "user_123",
+  fpHash,
+  process.env.ACCESS_SECRET,
+  process.env.REFRESH_SECRET
+);
 ```
 
-#### `verifyAccessToken(token, fingerprintHash, secret): VerificationResult`
+---
+
+#### `generateAccessToken(userId, fpHash, secret, expiresIn?)`
+
+Generates only an access token.
+
+**Parameters:**
+- `userId` (string) - User identifier
+- `fpHash` (string) - Fingerprint hash
+- `secret` (string) - Signing secret
+- `expiresIn` (string, optional) - Expiration time (default: "15m")
+
+**Returns:** `string`
+
+**Example:**
+```javascript
+const accessToken = generateAccessToken(
+  "user_123",
+  fpHash,
+  process.env.ACCESS_SECRET,
+  "30m"
+);
+```
+
+---
+
+#### `generateRefreshToken(userId, fpHash, secret, expiresIn?)`
+
+Generates only a refresh token.
+
+**Parameters:**
+- `userId` (string) - User identifier
+- `fpHash` (string) - Fingerprint hash
+- `secret` (string) - Signing secret
+- `expiresIn` (string, optional) - Expiration time (default: "7d")
+
+**Returns:** `string`
+
+---
+
+#### `verifyAccessToken(token, fpHash, secret)`
+
+Verifies an access token and fingerprint binding.
 
-Verifies an access token and its fingerprint binding.
+**Parameters:**
+- `token` (string) - JWT access token
+- `fpHash` (string) - Current device fingerprint hash
+- `secret` (string) - Signing secret
+
+**Returns:** `VerificationResult`
 
-**Returns:**
 ```typescript
 {
   valid: boolean;
   payload?: {
-    userId: string;
-    fingerprintHash: string;
-    iat: number;
-    exp: number;
+    sub: string;      // userId
+    fp: string;       // fingerprint hash
+    type: string;     // "access"
+    iat: number;      // issued at timestamp
+    exp: number;      // expiration timestamp
   };
   error?: string;
 }
 ```
 
-#### `verifyRefreshToken(token, fingerprintHash, secret): VerificationResult`
+**Possible errors:**
+- `"Invalid token structure"` - Malformed JWT
+- `"invalid signature"` - Token tampered or wrong fingerprint
+- `"jwt expired"` - Token expired
+- `"Invalid token type"` - Not an access token
+- `"Fingerprint mismatch"` - Device fingerprint doesn't match
+
+**Example:**
+```javascript
+const result = verifyAccessToken(token, fpHash, process.env.ACCESS_SECRET);
+
+if (result.valid) {
+  console.log("User ID:", result.payload.sub);
+} else {
+  console.error("Error:", result.error);
+}
+```
 
-Verifies a refresh token and its fingerprint binding.
+---
 
-#### `buildRefreshCookie(refreshToken, options?): string`
+#### `verifyRefreshToken(token, fpHash, secret)`
+
+Verifies a refresh token and fingerprint binding.
+
+**Parameters:** Same as `verifyAccessToken`
+
+**Returns:** `VerificationResult`
+
+---
+
+#### `buildRefreshCookie(refreshToken, options?)`
 
 Generates a secure HTTP-only cookie string for refresh tokens.
 
-**Options:**
-- `maxAge` (number): Cookie lifetime in seconds (default: 7 days)
-- `domain` (string, optional): Cookie domain
-- `sameSite` ("Strict" | "Lax" | "None"): SameSite policy (default: "Strict")
-- `secure` (boolean): HTTPS only (default: true)
+**Parameters:**
+- `refreshToken` (string) - The refresh token
+- `options` (object, optional):
+  - `maxAge` (number) - Cookie lifetime in seconds (default: 604800 = 7 days)
+  - `domain` (string) - Cookie domain
+  - `sameSite` ("Strict" | "Lax" | "None") - SameSite policy (default: "Strict")
+  - `secure` (boolean) - HTTPS only (default: true)
+
+**Returns:** `string` (Set-Cookie header value)
+
+**Example:**
+```javascript
+const cookie = buildRefreshCookie(refreshToken, {
+  maxAge: 86400,
+  sameSite: "Strict",
+  secure: true
+});
+
+res.setHeader("Set-Cookie", cookie);
+```
 
 ---
 
-## 🔒 Security Best Practices
+#### `buildClearRefreshCookie()`
+
+Generates a cookie string to clear the refresh token (for logout).
+
+**Returns:** `string`
+
+**Example:**
+```javascript
+app.post("/api/logout", (req, res) => {
+  res.setHeader("Set-Cookie", buildClearRefreshCookie());
+  res.json({ message: "Logged out" });
+});
+```
+
+---
+
+#### `deriveSecret(secret, userId, fpHash)`
+
+Derives a unique signing secret using HMAC-SHA256 with the application's pepper.
+
+**Parameters:**
+- `secret` (string) - Base secret (access or refresh)
+- `userId` (string) - User identifier
+- `fpHash` (string) - Fingerprint hash
+
+**Returns:** `string` (Hex-encoded derived secret)
+
+**Note:** This is used internally. You typically don't need to call this directly.
+
+---
+
+## Security Best Practices
 
 ### 1. Environment Variables
 
 Never hardcode secrets. Use environment variables:
 
 ```bash
-# .env
-ACCESS_SECRET=your-super-secret-access-key-min-32-chars
-REFRESH_SECRET=your-super-secret-refresh-key-min-32-chars
+# .env (add to .gitignore)
+BRO_AUTH_SECRET_PEPPER=min-32-chars-random-string
+ACCESS_SECRET=min-32-chars-random-string
+REFRESH_SECRET=min-32-chars-random-string
+```
+
+Generate secrets using:
+```bash
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
 ```
 
 ### 2. Token Storage
 
 **Access tokens:**
 - Store in memory (React state, Vue reactive)
-- Never in localStorage (XSS vulnerable)
+- Session storage is acceptable for SPAs
+- **Never** in localStorage (XSS vulnerable)
 
 **Refresh tokens:**
-- Use HTTP-only cookies (best)
-- Or secure memory storage with HTTPS
+- HTTP-only, Secure, SameSite=Strict cookies (recommended)
+- **Never** accessible to JavaScript
+
+**Example:**
+```javascript
+// ✓ Good: In-memory
+const [accessToken, setAccessToken] = useState(null);
+
+// ✗ Bad: localStorage
+localStorage.setItem("token", accessToken); // XSS vulnerable
+```
 
 ### 3. HTTPS Only
 
-Always use HTTPS in production to prevent man-in-the-middle attacks.
+Always use HTTPS in production:
 
-### 4. Short-lived Access Tokens
+```javascript
+const cookie = buildRefreshCookie(refreshToken, {
+  secure: process.env.NODE_ENV === "production",
+  sameSite: "Strict"
+});
+```
 
-Keep access token TTL short (5-15 minutes) to limit exposure window.
+### 4. Short-Lived Access Tokens
+
+Keep access token TTL short (5-15 minutes):
+
+```javascript
+generateAccessToken(userId, fpHash, secret, "15m");
+```
 
 ### 5. Token Rotation
 
-Rotate refresh tokens on each use to detect token theft:
+Rotate refresh tokens on each use:
 
 ```javascript
-// When refreshing, invalidate old refresh token
-// and issue a new pair
+app.post("/api/refresh", async (req, res) => {
+  const result = verifyRefreshToken(/* ... */);
+  
+  if (result.valid) {
+    // Issue new token pair
+    const newTokens = generateTokens(/* ... */);
+    
+    // Optional: Invalidate old refresh token in database
+    await revokeToken(req.body.refreshToken);
+    
+    res.json(newTokens);
+  }
+});
 ```
 
----
+### 6. Rate Limiting
 
-## 🎨 Integration Examples
+Implement rate limiting on auth endpoints:
 
-### Next.js App Router
+```javascript
+import rateLimit from "express-rate-limit";
 
-```typescript
-// app/api/login/route.ts
-import { generateTokens } from "bro-auth";
-import { NextRequest, NextResponse } from "next/server";
+const loginLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  max: 5
+});
 
-export async function POST(req: NextRequest) {
-  const { username, password, fingerprint } = await req.json();
-  
-  // Your auth logic
-  const user = await authenticate(username, password);
-  
-  const tokens = generateTokens({
-    userId: user.id,
-    fingerprintHash: fingerprint,
-    accessSecret: process.env.ACCESS_SECRET!,
-    refreshSecret: process.env.REFRESH_SECRET!
-  });
-  
-  return NextResponse.json(tokens);
-}
+app.post("/api/login", loginLimiter, handleLogin);
 ```
 
+---
+
+## Framework Examples
+
 ### Express.js Middleware
 
 ```javascript
-import { verifyAccessToken } from "bro-auth";
+import { verifyAccessToken } from "bro-auth/core";
 
 export const authMiddleware = (req, res, next) => {
   const token = req.headers.authorization?.replace("Bearer ", "");
   const fingerprint = req.headers["x-fingerprint"];
   
+  if (!token || !fingerprint) {
+    return res.status(401).json({ error: "Unauthorized" });
+  }
+  
   const result = verifyAccessToken(
     token,
     fingerprint,
@@ -379,10 +585,10 @@ export const authMiddleware = (req, res, next) => {
   );
   
   if (!result.valid) {
-    return res.status(401).json({ error: "Unauthorized" });
+    return res.status(401).json({ error: result.error });
   }
   
-  req.userId = result.payload.userId;
+  req.userId = result.payload.sub;
   next();
 };
 
@@ -392,57 +598,225 @@ app.get("/api/user", authMiddleware, (req, res) => {
 });
 ```
 
----
+### Next.js 14 App Router
 
-## ❓ FAQ
+**Server Action:**
+```typescript
+// app/actions/auth.ts
+'use server'
 
-### Q: Can users have multiple devices?
+import { generateTokens } from "bro-auth/core";
+import { cookies } from "next/headers";
 
-**A:** Yes! Each device generates its own fingerprint. Issue separate token pairs for each device. You can track active sessions by storing fingerprint hashes (optional).
+export async function loginAction(formData: FormData) {
+  const username = formData.get("username") as string;
+  const password = formData.get("password") as string;
+  const fingerprint = formData.get("fingerprint") as string;
+  
+  const user = await authenticateUser(username, password);
+  if (!user) {
+    return { error: "Invalid credentials" };
+  }
+  
+  const tokens = generateTokens(
+    user.id,
+    fingerprint,
+    process.env.ACCESS_SECRET!,
+    process.env.REFRESH_SECRET!
+  );
+  
+  cookies().set("refreshToken", tokens.refreshToken, {
+    httpOnly: true,
+    secure: true,
+    sameSite: "strict",
+    maxAge: 60 * 60 * 24 * 7
+  });
+  
+  return { accessToken: tokens.accessToken };
+}
+```
 
-### Q: What if fingerprint changes (browser update, etc.)?
+**Client Component:**
+```typescript
+// app/login/page.tsx
+'use client'
 
-**A:** The user will need to re-authenticate. This is a security feature—it prevents fingerprint spoofing. Consider implementing a "trusted devices" system for better UX.
+import { getFingerprint } from "bro-auth/browser";
+import { loginAction } from "@/app/actions/auth";
 
-### Q: Is this more secure than sessions?
+export default function LoginPage() {
+  async function handleSubmit(e: FormEvent) {
+    e.preventDefault();
+    const formData = new FormData(e.target as HTMLFormElement);
+    
+    const fpHash = await getFingerprint();
+    formData.append("fingerprint", fpHash);
+    
+    const result = await loginAction(formData);
+    if (result.accessToken) {
+      sessionStorage.setItem("accessToken", result.accessToken);
+      router.push("/dashboard");
+    }
+  }
+  
+  return (
+    <form onSubmit={handleSubmit}>
+      <input name="username" type="email" required />
+      <input name="password" type="password" required />
+      <button type="submit">Login</button>
+    </form>
+  );
+}
+```
 
-**A:** It's different. Sessions require server-side storage but can be invalidated instantly. bro-auth is stateless (scales better) but tokens can't be revoked until expiry. Choose based on your needs.
+### React Auth Context
 
-### Q: What about privacy?
+```javascript
+import { createContext, useContext, useState, useEffect } from "react";
+import { getFingerprint } from "bro-auth/browser";
 
-**A:** The fingerprint is hashed with SHA-256 before storage. Only the hash is sent to the server—individual components stay client-side. However, browser fingerprinting can be privacy-sensitive, so disclose this in your privacy policy.
+const AuthContext = createContext();
 
-### Q: Does this work with mobile apps?
+export function AuthProvider({ children }) {
+  const [accessToken, setAccessToken] = useState(null);
+  const [fingerprint, setFingerprint] = useState(null);
+  
+  useEffect(() => {
+    getFingerprint().then(setFingerprint);
+  }, []);
+  
+  async function login(username, password) {
+    const response = await fetch("/api/login", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ username, password, fingerprint })
+    });
+    
+    const data = await response.json();
+    setAccessToken(data.accessToken);
+  }
+  
+  async function apiCall(endpoint, options = {}) {
+    return fetch(endpoint, {
+      ...options,
+      headers: {
+        ...options.headers,
+        "Authorization": `Bearer ${accessToken}`,
+        "X-Fingerprint": fingerprint
+      }
+    });
+  }
+  
+  return (
+    <AuthContext.Provider value={{ login, apiCall, accessToken }}>
+      {children}
+    </AuthContext.Provider>
+  );
+}
 
-**A:** The browser module is web-only. For mobile apps, generate a device ID using native APIs (iOS: `identifierForVendor`, Android: `ANDROID_ID`) and use that as the fingerprint.
+export const useAuth = () => useContext(AuthContext);
+```
 
 ---
 
-## 🤝 Contributing
+## FAQ
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+**Q: Can users have multiple devices?**
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+A: Yes. Each device generates its own fingerprint. Issue separate token pairs for each device. Optionally track active sessions by storing fingerprint hashes.
+
+**Q: What if the fingerprint changes (browser update)?**
+
+A: The user must re-authenticate. This is intentional—it prevents fingerprint spoofing. For better UX, implement a "trusted devices" feature or send email notifications for new logins.
+
+**Q: What about privacy concerns?**
+
+A: The fingerprint is SHA-256 hashed before transmission. Only the hash is sent to the server. However, disclose fingerprinting in your privacy policy and comply with GDPR/CCPA.
+
+**Q: Does this work with mobile apps?**
+
+A: The browser module is web-only. For mobile apps, use native device identifiers:
+- iOS: `identifierForVendor`
+- Android: `ANDROID_ID`
+- React Native: `react-native-device-info`
+
+**Q: How do I invalidate tokens immediately?**
+
+A: `bro-auth` is stateless, so tokens can't be revoked until expiry. For immediate invalidation:
+- Maintain a token blacklist in Redis
+- Use short-lived access tokens (5-15 min)
+- Implement token versioning (increment on password change)
+
+**Q: Can I use this with GraphQL?**
+
+A: Yes. Pass credentials in HTTP headers:
+
+```javascript
+const client = new ApolloClient({
+  uri: '/graphql',
+  request: async (operation) => {
+    const fpHash = await getFingerprint();
+    operation.setContext({
+      headers: {
+        authorization: `Bearer ${accessToken}`,
+        'x-fingerprint': fpHash
+      }
+    });
+  }
+});
+```
 
 ---
 
-## 📄 License
+## Testing
 
-MIT © Vaishnav
+### Run Backend Tests
+
+```bash
+npm test
+```
+
+Tests:
+- Token generation
+- Token verification
+- Fingerprint binding
+- Secret derivation
+- Invalid fingerprint rejection
+
+### Run Browser Tests
+
+```bash
+npx serve .
+```
+
+Open: `http://localhost:3000/tests/test-browser.html`
+
+Tests:
+- Fingerprint generation
+- SHA-256 hashing
+- Browser compatibility
 
 ---
 
+## Contributing
+
+Contributions welcome. Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Run tests (`npm test`)
+4. Submit a pull request
+
 ---
 
-## 🔗 Links
+## License
 
-- [NPM Package](https://www.npmjs.com/package/bro-auth)
-- [GitHub Repository](https://github.com/ChakraVaishnav/bro-auth)
+MIT © Vaishnav
 
 ---
 
-**Made with 💪 by developers who care about security**
+## Links
+
+- [NPM Package](https://www.npmjs.com/package/bro-auth)
+- [GitHub Repository](https://github.com/ChakraVaishnav/bro-auth)
+- [Report Issues](https://github.com/ChakraVaishnav/bro-auth/issues)