secure-web-token 1.0.0

package/README.md

@@ -0,0 +1,178 @@
+# 🔐 Secure Web Token (Fingerprint Based)
+
+A lightweight Node.js authentication package that allows you to **sign and verify tokens using one or more device fingerprints**.
+
+This helps prevent token misuse across different devices.
+
+---
+
+## ✨ Features
+
+- Supports **single or multiple fingerprints**
+- Simple `sign()` and `verify()` API
+- CommonJS compatible
+- Editor IntelliSense support
+- No heavy dependencies
+
+---
+
+## 📦 Installation
+
+```bash
+npm install secure-web-token
+```
+
+---
+
+## 📥 Import
+
+```js
+const { sign, verify } = require("secure-web-token");
+```
+
+---
+
+## 🧠 What is Fingerprint?
+
+A fingerprint is any unique identifier of a device, for example:
+- Browser + OS (`Chrome-Linux`)
+- Device name
+- IP address
+- Custom string
+
+You can pass **one or multiple fingerprints**.
+
+---
+
+## ✍️ sign()
+
+Creates a secure token with fingerprint validation.
+
+### Syntax
+
+```js
+sign(payload, secret, options)
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|---------|-----|-------------|
+| payload | Object | Data you want inside token |
+| secret | String | Secret key |
+| options.expiresIn | Number | Expiry time (seconds) |
+| options.fingerprint | String \| String[] | Allowed fingerprint(s) |
+
+---
+
+### Example: Single Fingerprint
+
+```js
+const token = sign(
+  { userId: 1 },
+  "my-secret",
+  {
+    expiresIn: 60,
+    fingerprint: "Chrome-Linux"
+  }
+);
+
+console.log("TOKEN:", token);
+```
+
+---
+
+### Example: Multiple Fingerprints
+
+```js
+const token = sign(
+  { userId: 1 },
+  "my-secret",
+  {
+    expiresIn: 60,
+    fingerprint: ["Chrome-Linux", "monjal"]
+  }
+);
+```
+
+---
+
+## ✅ verify()
+
+Verifies the token and checks whether the fingerprint is valid.
+
+### Syntax
+
+```js
+verify(token, secret, options)
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|---------|-----|-------------|
+| token | String | Token to verify |
+| secret | String | Same secret used while signing |
+| options.fingerprint | String \| String[] | Current device fingerprint |
+
+---
+
+### Example: Successful Verification
+
+```js
+const payload = verify(token, "my-secret", {
+  fingerprint: "Chrome-Linux"
+});
+
+console.log("PAYLOAD:", payload);
+```
+
+---
+
+### Example: Multiple Fingerprints Verification
+
+```js
+const payload = verify(token, "my-secret", {
+  fingerprint: ["Chrome-Linux", "monjal"]
+});
+```
+
+---
+
+## ❌ Invalid Fingerprint Example
+
+```js
+try {
+  verify(token, "my-secret", {
+    fingerprint: "Unknown-Device"
+  });
+} catch (err) {
+  console.error(err.message);
+}
+```
+
+---
+
+## ⏰ Token Expiry Example
+
+```js
+const token = sign(
+  { role: "admin" },
+  "secret-key",
+  {
+    expiresIn: 5,
+    fingerprint: "Chrome-Linux"
+  }
+);
+
+// After 5 seconds
+verify(token, "secret-key", {
+  fingerprint: "Chrome-Linux"
+});
+```
+
+---
+
+## 📜 License
+
+MIT License

package/dist/decrypt.d.ts

@@ -0,0 +1,2 @@
+export default function decrypt(encryptedPayload: string, secret: string): Record<string, any>;
+//# sourceMappingURL=decrypt.d.ts.map

package/dist/decrypt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decrypt.d.ts","sourceRoot":"","sources":["../src/decrypt.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,OAAO,UAAU,OAAO,CAC3B,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE,MAAM,GACf,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CA0BrB"}

package/dist/decrypt.js

@@ -0,0 +1,55 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = decrypt;
+const crypto = __importStar(require("crypto"));
+const utils_1 = require("./utils");
+function decrypt(encryptedPayload, secret) {
+    const data = (0, utils_1.base64urlDecode)(encryptedPayload);
+    const iv = data.subarray(0, 12);
+    const tag = data.subarray(12, 28);
+    const text = data.subarray(28);
+    const key = crypto
+        .createHash("sha256")
+        .update(secret)
+        .digest();
+    const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAuthTag(tag);
+    const decrypted = Buffer.concat([
+        decipher.update(text),
+        decipher.final(),
+    ]);
+    return JSON.parse(decrypted.toString("utf8"));
+}

package/dist/encrypt.d.ts

@@ -0,0 +1,2 @@
+export default function encrypt(payload: Record<string, any>, secret: string): string;
+//# sourceMappingURL=encrypt.d.ts.map

package/dist/encrypt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encrypt.d.ts","sourceRoot":"","sources":["../src/encrypt.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,OAAO,UAAU,OAAO,CAC3B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC5B,MAAM,EAAE,MAAM,GACf,MAAM,CAoBR"}

package/dist/encrypt.js

@@ -0,0 +1,52 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = encrypt;
+const crypto = __importStar(require("crypto"));
+const utils_1 = require("./utils");
+function encrypt(payload, secret) {
+    const iv = crypto.randomBytes(12);
+    const key = crypto
+        .createHash("sha256")
+        .update(secret)
+        .digest();
+    const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+    const encrypted = Buffer.concat([
+        cipher.update(JSON.stringify(payload), "utf8"),
+        cipher.final(),
+    ]);
+    const tag = cipher.getAuthTag();
+    return (0, utils_1.base64urlEncode)(Buffer.concat([iv, tag, encrypted]));
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { default as sign } from "./sign";
+export { default as verify } from "./verify";
+export type { SignOptions } from "./sign";
+export type { VerifyOptions } from "./verify";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,UAAU,CAAC;AAE7C,YAAY,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC1C,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verify = exports.sign = void 0;
+var sign_1 = require("./sign");
+Object.defineProperty(exports, "sign", { enumerable: true, get: function () { return __importDefault(sign_1).default; } });
+var verify_1 = require("./verify");
+Object.defineProperty(exports, "verify", { enumerable: true, get: function () { return __importDefault(verify_1).default; } });

package/dist/sign.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Options for signing a secure token
+ */
+export interface SignOptions {
+    /**
+     * Token expiry time in seconds
+     * @default 900 (15 minutes)
+     */
+    expiresIn?: number;
+    /**
+     * One or more fingerprints allowed to use this token
+     * Example: device hash, IP hash, browser hash
+     */
+    fingerprint?: string | string[];
+}
+/**
+ * Creates a secure encrypted token.
+ *
+ * @param payload - Data you want to store inside the token
+ * @param secret - Secret key used for encryption & signature
+ * @param options - Optional token settings (expiry, fingerprint)
+ *
+ * @returns Encrypted and signed token string
+ *
+ * @example
+ * sign({ userId: 1 }, "secret", { expiresIn: 60 })
+ */
+export default function sign(payload: Record<string, any>, secret: string, options?: SignOptions): string;
+//# sourceMappingURL=sign.d.ts.map

package/dist/sign.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign.d.ts","sourceRoot":"","sources":["../src/sign.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACjC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,OAAO,UAAU,IAAI,CAC1B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC5B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,WAAgB,GACxB,MAAM,CA0BR"}

package/dist/sign.js

@@ -0,0 +1,76 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = sign;
+const crypto = __importStar(require("crypto"));
+const encrypt_1 = __importDefault(require("./encrypt"));
+const utils_1 = require("./utils");
+/**
+ * Creates a secure encrypted token.
+ *
+ * @param payload - Data you want to store inside the token
+ * @param secret - Secret key used for encryption & signature
+ * @param options - Optional token settings (expiry, fingerprint)
+ *
+ * @returns Encrypted and signed token string
+ *
+ * @example
+ * sign({ userId: 1 }, "secret", { expiresIn: 60 })
+ */
+function sign(payload, secret, options = {}) {
+    const header = {
+        alg: "AES-256-GCM+HMAC",
+        typ: "STK",
+    };
+    const now = Math.floor(Date.now() / 1000);
+    payload.iat = now;
+    payload.exp = now + (options.expiresIn ?? 900);
+    if (options.fingerprint) {
+        payload.fp = Array.isArray(options.fingerprint)
+            ? options.fingerprint
+            : [options.fingerprint];
+    }
+    const encodedHeader = (0, utils_1.base64urlEncode)(JSON.stringify(header));
+    const encryptedPayload = (0, encrypt_1.default)(payload, secret);
+    const dataToSign = `${encodedHeader}.${encryptedPayload}`;
+    const signature = crypto
+        .createHmac("sha256", secret)
+        .update(dataToSign)
+        .digest("base64url");
+    return `${dataToSign}.${signature}`;
+}

package/dist/utils.d.ts

@@ -0,0 +1,5 @@
+export declare function base64urlEncode(input: Buffer | string): string;
+export declare function base64urlDecode(input: string): Buffer;
+export declare function hash(data: string | Buffer): Buffer;
+export declare function timingSafeEqual(a: Buffer, b: Buffer): boolean;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAEA,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAE9D;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAG7D"}

package/dist/utils.js

@@ -0,0 +1,54 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.base64urlEncode = base64urlEncode;
+exports.base64urlDecode = base64urlDecode;
+exports.hash = hash;
+exports.timingSafeEqual = timingSafeEqual;
+const crypto = __importStar(require("crypto"));
+function base64urlEncode(input) {
+    return Buffer.from(input).toString("base64url");
+}
+function base64urlDecode(input) {
+    return Buffer.from(input, "base64url");
+}
+function hash(data) {
+    return crypto.createHash("sha256").update(data).digest();
+}
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    return crypto.timingSafeEqual(a, b);
+}

package/dist/verify.d.ts

@@ -0,0 +1,5 @@
+export interface VerifyOptions {
+    fingerprint?: string | string[];
+}
+export default function verify(token: string, secret: string, options?: VerifyOptions): Record<string, any>;
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,aAAa;IAC1B,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,CAAC,OAAO,UAAU,MAAM,CAC1B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,aAAkB,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAiDrB"}

package/dist/verify.js

@@ -0,0 +1,75 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = verify;
+const crypto = __importStar(require("crypto"));
+const decrypt_1 = __importDefault(require("./decrypt"));
+const utils_1 = require("./utils");
+function verify(token, secret, options = {}) {
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+        throw new Error("Invalid token format");
+    }
+    const [header, encryptedPayload, signature] = parts;
+    const dataToVerify = `${header}.${encryptedPayload}`;
+    const expectedSignature = crypto
+        .createHmac("sha256", secret)
+        .update(dataToVerify)
+        .digest("base64url");
+    if (!(0, utils_1.timingSafeEqual)(Buffer.from(signature), Buffer.from(expectedSignature))) {
+        throw new Error("Invalid signature");
+    }
+    const payload = (0, decrypt_1.default)(encryptedPayload, secret);
+    const now = Math.floor(Date.now() / 1000);
+    if (payload.exp < now) {
+        throw new Error("Token expired");
+    }
+    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));
+        if (!matched) {
+            throw new Error("Fingerprint mismatch");
+        }
+    }
+    return payload;
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "secure-web-token",
+  "version": "1.0.0",
+  "description": "A secure web token utility",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "node test.js"
+  },
+  "keywords": [
+    "token",
+    "security"
+  ],
+  "author": "Znos",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "commonjs",
+  "devDependencies": {
+    "@types/node": "^25.0.6",
+    "typescript": "^5.9.3"
+  }
+}