secure-web-token 1.2.3 → 1.2.5

package/README.md

@@ -1,43 +1,50 @@
 # 🔐 Secure Web Token (SWT)
 
+A **secure, device-bound authentication token system** for Node.js applications.
+
+---
+
 ## 1. About the Package
 
-Secure Web Token (SWT) is a **next-generation authentication token system** designed for security-critical applications. Unlike traditional JWTs, SWT operates on a **Device Registration and Server-Side Session Model**, ensuring that tokens are intrinsically tied to specific devices and sessions.
+**Secure Web Token (SWT)** is a next-generation alternative to JWT, built for **security-critical applications** where token leakage, device hijacking, or session reuse must be prevented.
 
-Key highlights:
+Unlike JWTs (which are only Base64 encoded), SWT uses **full encryption + server-side session binding**, making stolen tokens useless on other devices.
 
-- **AES-256-GCM encryption**: Ensures payloads are fully encrypted, not just Base64 encoded.
-- **Device fingerprint binding**: Tokens are locked to a device (or session) to prevent unauthorized reuse.
-- **Server-side session store**: Device IDs and sessions are managed securely on the backend, never exposed to the browser.
-- **Simple developer experience**: Easily integrate into Node.js applications with `sign` and `verify` functions.
+### Key Highlights ✨
 
-SWT is ideal for **mission-critical applications** where security, controlled access, and device binding are required.
+- 🔐 **AES-256-GCM encrypted payloads**
+- 🧷 **Device-bound tokens (single-device login)**
+- 🗄 **Server-side session management**
+- 🍪 **HttpOnly session cookies**
+- ⏱ **Expiry support (`iat`, `exp`)**
+- ⚡ Simple API: `sign()` and `verify()`
+- 🧠 Memory store (Redis-ready design)
 
 ---
 
 ## 2. What Problem Does It Solve?
 
-Traditional JWTs have several limitations:
+### Problems with JWT ❌
 
-- JWT payloads are only Base64 encoded, not encrypted. Anyone can decode them.
-- If a token leaks, it can be reused from any device.
-- No built-in mechanism to restrict tokens to specific devices.
-- Cannot safely enforce single-device login without additional server logic.
+- Payloads are readable (Base64 ≠ encryption)
+- Tokens can be reused on any device
+- No native device binding
+- Logout does not truly invalidate tokens
 
-**SWT addresses these issues by:**
+### How SWT Solves This ✅
 
-- Fully encrypting token payloads using AES-256-GCM.
-- Binding tokens to **device fingerprints** managed on the backend.
-- Preventing token reuse from unauthorized devices.
-- Supporting auto-generated device IDs for added security.
-- Managing sessions server-side, so sensitive identifiers never reach the browser.
+- Encrypts payload using **AES-256-GCM**
+- Binds tokens to **server-managed device sessions**
+- Prevents token reuse across devices
+- Supports true logout via session revocation
+- Sensitive identifiers never reach the browser
 
-Use cases:
-
-- Course platforms with anti-piracy requirements
+**Best suited for:**
+- Admin panels
 - SaaS dashboards
-- Admin panels with restricted access
-- Any system requiring **device-bound authentication**
+- Course platforms
+- Internal tools
+- High-security APIs
 
 ---
 
@@ -45,81 +52,54 @@ Use cases:
 
 ### `sign()`
 
-Creates a **secure, encrypted token**.
+Creates a **secure, encrypted token** and optionally registers a **server-side device session**.
+
+### `verify()`
+
+Validates and decrypts the token, ensuring the request comes from the **correct device and active session**.
 
-**Features:**
+---
 
-- Encrypts the payload completely
-- Adds `iat` (issued at) and `exp` (expiry) timestamps
-- Supports **device fingerprint binding**
-- Can auto-generate a device ID
-- Optional server-side session management
+## 4. Boiler Code (Core Usage)
 
+### `sign()` function
 ```ts
 import { sign } from "secure-web-token";
 
-const secret = "my-super-secret";
+const SECRET = "super-secret-key";
 
-// Auto device registration + server session
 const { token, sessionId } = sign(
   { userId: 1, role: "admin" },
-  secret,
-  { fingerprint: true, store: "memory", expiresIn: 3600 }
+  SECRET,
+  {
+    fingerprint: true,
+    store: "memory",
+    expiresIn: 3600,
+  }
 );
-
-console.log("TOKEN:", token);
-console.log("SESSION ID (internal, not exposed to browser):", sessionId);
 ```
 
 ---
 
-### `verify()`
-
-Verifies and decrypts a token.
-
-**Checks performed:**
-
-- Token format integrity
-- Signature correctness
-- Expiry check
-- Device fingerprint / session validation
-
+### `verify()` function
 ```ts
 import { verify, getStore } from "secure-web-token";
 
-// Get the store instance (MemoryStore / Redis)
 const store = getStore("memory");
+const session = store.getSession(sessionId);
 
-try {
-  const payload = verify(token, secret, {
-    sessionId,          // Server-side session ID
-    fingerprint: "abc", // Device fingerprint stored internally
-    store: "memory"     // Must match the store used during sign()
-  });
-
-  console.log("USER DATA:", payload.data);
-} catch (err) {
-  console.error("AUTH ERROR:", err.message);
-}
+const payload = verify(token, SECRET, {
+  sessionId,
+  fingerprint: session.fingerprint,
+  store: "memory",
+});
 ```
 
 ---
 
-## 4. Server-Side Session Model (Recommended)
-
-> In SWT v2+, **device verification is entirely server-side**.\
-> This prevents attackers from copying tokens and device IDs from one browser to another.
-
-**Workflow:**
-
-1. **User logs in** → `sign()` generates token + server session
-2. **Server stores session** internally (deviceId, fingerprint)
-3. **Browser receives token + HttpOnly cookie** → cannot read device ID
-4. **verify()**** checks session + fingerprint internally** → ensures single-device access
-5. **Session revocation** automatically prevents token reuse
-
-**Example Express backend:**
+## 5. Demo App
 
+### Backend (Express.js + Node.js)
 ```ts
 import express from "express";
 import cookieParser from "cookie-parser";
@@ -134,35 +114,78 @@ app.use(express.json());
 const SECRET = "super-secret-key";
 const store = getStore("memory");
 
-// LOGIN
 app.post("/login", (req, res) => {
-  const user = { userId: 1, name: "John" };
-  const { token, sessionId } = sign(user, SECRET, { fingerprint: true, store: "memory", expiresIn: 3600 });
+  const user = { userId: 1, name: "Mintu" };
+
+  const { token, sessionId } = sign(user, SECRET, {
+    fingerprint: true,
+    store: "memory",
+  });
 
-  res.cookie("swt_session", sessionId, { httpOnly: true, sameSite: "strict", secure: false });
+  res.cookie("swt_session", sessionId, { httpOnly: true });
   res.json({ token });
 });
 
-// PROFILE
 app.get("/profile", (req, res) => {
   try {
     const sessionId = req.cookies.swt_session;
     const session = store.getSession(sessionId);
-    if (!session) throw new Error("Unauthorized or session expired");
-
     const token = req.headers.authorization?.split(" ")[1];
-    const payload = verify(token, SECRET, { sessionId, fingerprint: session.fingerprint, store: "memory" });
+
+    const payload = verify(token, SECRET, {
+      sessionId,
+      fingerprint: session.fingerprint,
+      store: "memory",
+    });
+
     res.json({ user: payload.data });
-  } catch (err) {
-    res.status(401).json({ error: err.message });
+  } catch {
+    res.status(401).json({ error: "Unauthorized" });
   }
 });
+
+app.listen(4000);
 ```
 
----
+### Frontend (React.js)
+```tsx
+import { useState } from "react";
+
+function App() {
+  const [user, setUser] = useState(null);
+
+  const login = async () => {
+    const res = await fetch("http://localhost:4000/login", {
+      method: "POST",
+      credentials: "include",
+    });
+    const data = await res.json();
+    localStorage.setItem("token", data.token);
+  };
+
+  const profile = async () => {
+    const token = localStorage.getItem("token");
+    const res = await fetch("http://localhost:4000/profile", {
+      credentials: "include",
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    console.log(await res.json());
+  };
+
+  return (
+    <>
+      <button onClick={login}>Login</button>
+      <button onClick={profile}>View Profile</button>
+    </>
+  );
+}
 
-## 5. Payload Structure (Internal)
+export default App;
+```
+
+---
 
+## 6. Payload Structure
 ```json
 {
   "data": {
@@ -171,24 +194,20 @@ app.get("/profile", (req, res) => {
   },
   "iat": 1768368114,
   "exp": 1768369014,
-  "fp": "device-fingerprint" // stored server-side
+  "fp": "device-id"
 }
 ```
 
-> Note: The `fp` (fingerprint) and session ID are **not exposed to the browser**, making token copying attacks impossible.
-
 ---
 
-## 6. Installation
-
+## 7. Installation
 ```bash
 npm install secure-web-token
 ```
 
 ---
 
-## 7. Importing
-
+## 8. Importing
 ```ts
 // ESM
 import { sign, verify, getStore } from "secure-web-token";
@@ -199,13 +218,7 @@ const { sign, verify, getStore } = require("secure-web-token");
 
 ---
 
-## 8. Summary of Features
-
-- 🔐 AES-256-GCM encryption
-- 🔒 Server-side session + device binding
-- ⏱ Expiry (`iat` + `exp`)
-- 🛡 Prevents token reuse on unauthorized devices
-- ⚡ Easy integration with Node.js / Express
-- ✅ Auto-generated device IDs
-- ✅ Fully optional server-side memory store
+### Final Note
 
+If you need **encrypted tokens**, **single-device login**, and **true logout**,  
+**Secure Web Token (SWT)** is built for you.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "secure-web-token",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "A secure web token utility",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",