secure-web-token 1.2.2 → 1.2.3

package/README.md

@@ -1,42 +1,211 @@
 # 🔐 Secure Web Token (SWT)
 
-## About the Package
-SWT is a secure token system that encrypts payloads and binds them to devices. Unlike JWT, it prevents token reuse on other devices.
+## 1. About the Package
 
-## What Problem Does It Solve?
-- JWT can be decoded easily.
-- Tokens can be used on any device if leaked.
-- SWT encrypts payloads and binds tokens to device fingerprints.
+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.
 
-## Functions
+Key highlights:
+
+- **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.
+
+SWT is ideal for **mission-critical applications** where security, controlled access, and device binding are required.
+
+---
+
+## 2. What Problem Does It Solve?
+
+Traditional JWTs have several limitations:
+
+- 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.
+
+**SWT addresses these issues by:**
+
+- 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.
+
+Use cases:
+
+- Course platforms with anti-piracy requirements
+- SaaS dashboards
+- Admin panels with restricted access
+- Any system requiring **device-bound authentication**
+
+---
+
+## 3. Available Functions
+
+### `sign()`
+
+Creates a **secure, encrypted token**.
+
+**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
 
-### sign()
-Creates a secure token.
 ```ts
 import { sign } from "secure-web-token";
-const { token, deviceId } = sign({ userId:1 }, "secret", { fingerprint: true });
-console.log(token, deviceId);
+
+const secret = "my-super-secret";
+
+// Auto device registration + server session
+const { token, sessionId } = sign(
+  { userId: 1, role: "admin" },
+  secret,
+  { fingerprint: true, store: "memory", expiresIn: 3600 }
+);
+
+console.log("TOKEN:", token);
+console.log("SESSION ID (internal, not exposed to browser):", sessionId);
 ```
 
-### verify()
+---
+
+### `verify()`
+
 Verifies and decrypts a token.
+
+**Checks performed:**
+
+- Token format integrity
+- Signature correctness
+- Expiry check
+- Device fingerprint / session validation
+
+```ts
+import { verify, getStore } from "secure-web-token";
+
+// Get the store instance (MemoryStore / Redis)
+const store = getStore("memory");
+
+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);
+}
+```
+
+---
+
+## 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:**
+
 ```ts
-import { verify } from "secure-web-token";
-const payload = verify(token, "secret", { fingerprint: deviceId });
-console.log(payload.data);
+import express from "express";
+import cookieParser from "cookie-parser";
+import cors from "cors";
+import { sign, verify, getStore } from "secure-web-token";
+
+const app = express();
+app.use(cors({ origin: true, credentials: true }));
+app.use(cookieParser());
+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 });
+
+  res.cookie("swt_session", sessionId, { httpOnly: true, sameSite: "strict", secure: false });
+  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" });
+    res.json({ user: payload.data });
+  } catch (err) {
+    res.status(401).json({ error: err.message });
+  }
+});
 ```
 
-## Installation
+---
+
+## 5. Payload Structure (Internal)
+
+```json
+{
+  "data": {
+    "userId": 1,
+    "role": "admin"
+  },
+  "iat": 1768368114,
+  "exp": 1768369014,
+  "fp": "device-fingerprint" // stored server-side
+}
+```
+
+> Note: The `fp` (fingerprint) and session ID are **not exposed to the browser**, making token copying attacks impossible.
+
+---
+
+## 6. Installation
+
 ```bash
 npm install secure-web-token
 ```
 
-## Importing
+---
+
+## 7. Importing
+
 ```ts
-import { sign, verify } from "secure-web-token";
-// or
-const { sign, verify } = require("secure-web-token");
+// ESM
+import { sign, verify, getStore } from "secure-web-token";
+
+// CommonJS
+const { sign, verify, getStore } = require("secure-web-token");
 ```
 
-This simple version focuses on **encrypted tokens and device binding**.
+---
+
+## 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
 

package/package.json

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