secure-web-token 1.0.2 → 1.0.4

package/README.md

@@ -1,126 +1,129 @@
 # 🔐 Secure Web Token (SWT)
 
-**Secure Web Token (SWT)** is a lightweight Node.js authentication package designed to make token-based authentication **more secure than traditional JWTs** by binding tokens to **device fingerprints**.
+## 1. About the Package
 
-Unlike JWTs, SWT:
-- **Encrypts the payload** (can’t be decoded without the secret)
-- Allows **device-level access control**
-- Prevents token misuse across multiple devices
+**Secure Web Token (SWT)** operates on a strict **Device Registration Model**, providing a significant security upgrade over traditional JWTs. Through **AES-256-GCM encryption** and enforced **device-fingerprint binding**, SWT ensures that authentication tokens are intrinsically locked to specific devices, effectively neutralizing risks associated with token leakage and unauthorized access.
+
+It is designed for mission-critical applications where security and strictly controlled access are paramount.
 
 ---
 
-## ✨ Features
+## 2. What Problem Does It Solve?
 
-- 🔐 Encrypted payload (AES-256-GCM)
-- 📱 Device fingerprint support (single or multiple)
-- ⏱ Token expiration
-- ⚡ Lightweight & fast
-- 🧠 TypeScript + IntelliSense support
-- ✅ CommonJS compatible
+Traditional JWT has some well-known issues:
 
----
+- JWT payloads are **Base64 encoded**, not encrypted  
+- Anyone can decode the payload using online tools without the secret  
+- If a token leaks, it can be reused on **any device**  
+- No built-in way to restrict tokens to a specific device  
 
-## 📦 Installation
+**Secure Web Token (SWT)** solves these problems by:
 
-```bash
-npm install secure-web-token
-```
+- Encrypting the payload using **AES-256-GCM**
+- Making payload data **completely unreadable without the secret**
+- Allowing tokens to be bound to **one or more device fingerprints**
+- Preventing token reuse from unauthorized devices
+- Supporting auto-generated device IDs for stronger protection
 
----
+This makes SWT especially useful for:
+- Course platforms (anti-piracy)
+- SaaS dashboards
+- Admin panels
+- Device-restricted systems
 
-## 📥 Import
+---
 
-```js
-const { sign, verify } = require("secure-web-token");
-```
+## 3. Available Functions
 
----
+### `sign()`
+Creates an encrypted and signed token.
 
-## 🧠 What is a Fingerprint?
+**Features:**
+- Encrypts payload
+- Adds expiry (`iat`, `exp`)
+- Supports device fingerprint binding
+- Can auto-generate a device ID
 
-A fingerprint is any identifier that represents a device.
+---
 
-Examples:
-- Browser + OS (`Chrome-Linux`)
-- Device ID
-- IP address
-- Any custom unique string
+### `verify()`
+Verifies and decrypts a token.
 
-You can allow **one or multiple fingerprints** per token.
+**Checks performed:**
+- Token format
+- Signature integrity
+- Token expiry
+- Device fingerprint validation
 
 ---
 
-## ✍️ sign()
+## 4. Sample Code
 
-Creates a secure encrypted token.
+### Installation
 
-### Syntax
-
-```js
-sign(data, secret, options)
+```bash
+npm install secure-web-token
 ```
 
-### Options
-
-| Option | Type | Description |
-|------|------|------------|
-| expiresIn | number | Token expiry (seconds) |
-| fingerprint | true \| string \| string[] | Device fingerprint(s) |
+---
 
-### Payload Structure
+### Import
 
 ```js
-{
-  data: { ... },
-  iat: number,
-  exp: number,
-  fp: string[]
-}
+const { sign, verify } = require("secure-web-token");
 ```
 
-### Example (Auto Device ID)
+---
+
+### Signing a Token (Auto Device Registration)
 
 ```js
+const secret = "my-super-secret";
+
 const { token, deviceId } = sign(
   { userId: 1, role: "admin" },
-  "my-secret",
+  secret,
   { fingerprint: true }
 );
 
-console.log(token, deviceId);
+console.log("TOKEN:", token);
+console.log("DEVICE ID:", deviceId);
 ```
 
 ---
 
-## ✅ verify()
-
-Verifies token integrity, expiry, and fingerprint.
+### Verifying the Token
 
 ```js
-verify(token, secret, { fingerprint })
-```
-
-### Example
-
-```js
-const payload = verify(token, "my-secret", {
-  fingerprint: deviceId
-});
-
-console.log(payload.data);
+try {
+  const payload = verify(token, secret, {
+    fingerprint: deviceId
+  });
+
+  console.log("USER DATA:", payload.data);
+} catch (err) {
+  console.error("AUTH ERROR:", err.message);
+}
 ```
 
 ---
 
-## 🔐 Use Cases
+## Payload Structure (Internal)
 
-- Prevent account sharing
-- Device-restricted access
-- Secure SaaS authentication
-- Course/content protection
+```js
+{
+  data: {
+    userId: 1,
+    role: "admin"
+  },
+  iat: 1768368114,
+  exp: 1768369014,
+  fp: ["device-id"]
+}
+```
 
 ---
 
-## 📜 License
+## License
 
 MIT License

package/dist/sign.d.ts

@@ -11,7 +11,7 @@ export interface SignOptions {
      * true → auto-generate device ID
      * string | string[] → custom fingerprints
      */
-    fingerprint?: true | string | string[];
+    fingerprint?: true;
 }
 /**
  * Creates a Secure Web Token (SWT).

package/dist/sign.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sign.d.ts","sourceRoot":"","sources":["../src/sign.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,WAAW,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC;CACxC;AAED;;;GAGG;AACH,MAAM,CAAC,OAAO,UAAU,IAAI,CAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACzB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,WAAgB,GACxB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAgDtC"}
+{"version":3,"file":"sign.d.ts","sourceRoot":"","sources":["../src/sign.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,WAAW,CAAC,EAAE,IAAI,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,CAAC,OAAO,UAAU,IAAI,CAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACzB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,WAAgB,GACxB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CA4CtC"}

package/dist/sign.js

@@ -64,11 +64,6 @@ function sign(data, secret, options = {}) {
         deviceId = (0, device_1.generateDeviceId)();
         payload.fp = [deviceId];
     }
-    else if (options.fingerprint) {
-        payload.fp = Array.isArray(options.fingerprint)
-            ? options.fingerprint
-            : [options.fingerprint];
-    }
     const header = {
         alg: "AES-256-GCM+HMAC",
         typ: "SWT",

package/dist/verify.d.ts

@@ -5,7 +5,7 @@ export interface VerifyOptions {
     /**
      * Device fingerprint(s) allowed to verify token
      */
-    fingerprint?: string | string[];
+    fingerprint?: string;
 }
 /**
  * Verifies and decrypts a Secure Web Token.

package/dist/verify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,MAAM,CAC5B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAuDrB"}
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,MAAM,CAC5B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAmDrB"}

package/dist/verify.js

@@ -69,13 +69,9 @@ function verify(token, secret, options = {}) {
         throw new Error("Invalid payload structure");
     }
     if (options.fingerprint) {
-        const provided = Array.isArray(options.fingerprint)
-            ? options.fingerprint
-            : [options.fingerprint];
-        const stored = Array.isArray(payload.fp)
-            ? payload.fp
-            : [];
-        const matched = provided.some(fp => stored.includes(fp));
+        const provided = options.fingerprint;
+        const stored = payload.fp;
+        const matched = provided === stored;
         if (!matched) {
             throw new Error("Fingerprint mismatch");
         }

package/package.json

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