timebasedcipher 3.0.2 → 3.0.3

package/dist/cipher.d.ts

@@ -0,0 +1,81 @@
+import { RuntimeEnv } from "./cryptoProvider";
+/**
+ * Options controlling encryption and decryption behavior.
+ */
+export interface CipherOptions {
+    /**
+     * Runtime environment override.
+     *
+     * @default "auto"
+     *
+     * @example
+     * encrypt(data, secret, 60, { env: "node" })
+     */
+    env?: RuntimeEnv;
+    /**
+     * Token expiration time in seconds.
+     * Defaults to intervalSeconds if not provided.
+     *
+     * @example
+     * encrypt(data, secret, 60, { ttlSeconds: 300 })
+     */
+    ttlSeconds?: number;
+    /**
+     * Allowed clock drift tolerance in seconds.
+     *
+     * @default 30
+     *
+     * @example
+     * decrypt(token, secret, 60, { clockToleranceSeconds: 60 })
+     */
+    clockToleranceSeconds?: number;
+    /**
+     * Custom signature used to validate token purpose/domain.
+     *
+     * @example
+     * encrypt(data, secret, 60, { signature: "auth-session" })
+     */
+    signature?: string;
+}
+/**
+ * Encrypts JSON data into a secure token.
+ *
+ * @template T
+ * @param data Data to encrypt
+ * @param secret Shared secret
+ * @param intervalSeconds Key rotation interval
+ * @param options Optional settings
+ *
+ * @returns Secure encrypted token
+ *
+ * @example
+ * const token = await encrypt(
+ *   { userId: 1 },
+ *   "super-secret",
+ *   60,
+ *   { signature: "auth-session", ttlSeconds: 300 }
+ * )
+ */
+export declare function encrypt<T>(data: T, secret: string, intervalSeconds: number, options?: CipherOptions): Promise<string>;
+/**
+ * Decrypts a token and validates signature, expiration, and replay.
+ *
+ * @template T
+ * @param token Encrypted token
+ * @param secret Shared secret
+ * @param intervalSeconds Rotation interval
+ * @param options Validation options
+ *
+ * @returns Decrypted data
+ *
+ * @throws Error if token invalid, expired, replayed, or signature mismatch
+ *
+ * @example
+ * const data = await decrypt(
+ *   token,
+ *   "super-secret",
+ *   60,
+ *   { signature: "auth-session" }
+ * )
+ */
+export declare function decrypt<T>(token: string, secret: string, intervalSeconds: number, options?: CipherOptions): Promise<T>;

package/dist/cipher.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encrypt = encrypt;
+exports.decrypt = decrypt;
+const cryptoProvider_1 = require("./cryptoProvider");
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+/**
+ * Converts ArrayBuffer → Base64URL string.
+ *
+ * @example
+ * const encoded = b64url(buffer)
+ */
+function b64url(buffer) {
+    return Buffer.from(buffer)
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+/**
+ * Converts Base64URL → ArrayBuffer.
+ *
+ * @example
+ * const buffer = fromB64url(encoded)
+ */
+function fromB64url(str) {
+    const pad = str.length % 4 ? "=".repeat(4 - (str.length % 4)) : "";
+    const base64 = str.replace(/-/g, "+").replace(/_/g, "/") + pad;
+    return Uint8Array.from(Buffer.from(base64, "base64")).buffer;
+}
+/**
+ * Cache for derived keys to improve performance.
+ */
+const keyCache = new Map();
+/**
+ * Derives AES-256-GCM key using HKDF.
+ *
+ * @param cryptoObj Web Crypto instance
+ * @param secret Shared secret
+ * @param timeSlot Rotation slot
+ *
+ * @example
+ * const key = await deriveKey(crypto, "secret", 12345)
+ */
+async function deriveKey(cryptoObj, secret, timeSlot) {
+    const cacheKey = `${secret}:${timeSlot}`;
+    if (keyCache.has(cacheKey))
+        return keyCache.get(cacheKey);
+    const baseKey = await cryptoObj.subtle.importKey("raw", encoder.encode(secret), { name: "HKDF" }, false, ["deriveKey"]);
+    const key = await cryptoObj.subtle.deriveKey({
+        name: "HKDF",
+        hash: "SHA-256",
+        salt: encoder.encode(String(timeSlot)),
+        info: encoder.encode("time-based-encryption"),
+    }, baseKey, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
+    keyCache.set(cacheKey, key);
+    if (keyCache.size > 50)
+        keyCache.clear();
+    return key;
+}
+/**
+ * In-memory nonce store for replay protection.
+ */
+const nonceStore = new Set();
+/**
+ * Validates nonce uniqueness.
+ *
+ * @throws Error if nonce already used
+ */
+function checkReplay(nonce) {
+    if (nonceStore.has(nonce)) {
+        throw new Error("Replay attack detected");
+    }
+    nonceStore.add(nonce);
+    if (nonceStore.size > 1000)
+        nonceStore.clear();
+}
+/**
+ * Encrypts JSON data into a secure token.
+ *
+ * @template T
+ * @param data Data to encrypt
+ * @param secret Shared secret
+ * @param intervalSeconds Key rotation interval
+ * @param options Optional settings
+ *
+ * @returns Secure encrypted token
+ *
+ * @example
+ * const token = await encrypt(
+ *   { userId: 1 },
+ *   "super-secret",
+ *   60,
+ *   { signature: "auth-session", ttlSeconds: 300 }
+ * )
+ */
+async function encrypt(data, secret, intervalSeconds, options = {}) {
+    var _a, _b;
+    const cryptoObj = await (0, cryptoProvider_1.getCrypto)(options.env);
+    const now = Math.floor(Date.now() / 1000);
+    const ttl = (_a = options.ttlSeconds) !== null && _a !== void 0 ? _a : intervalSeconds;
+    const signature = (_b = options.signature) !== null && _b !== void 0 ? _b : "default-signature";
+    const payload = {
+        sig: signature,
+        iat: now,
+        exp: now + ttl,
+        nonce: cryptoObj.randomUUID(),
+        data,
+    };
+    const timeSlot = Math.floor(now / intervalSeconds);
+    const key = await deriveKey(cryptoObj, secret, timeSlot);
+    const iv = cryptoObj.getRandomValues(new Uint8Array(12));
+    const cipher = await cryptoObj.subtle.encrypt({ name: "AES-GCM", iv }, key, encoder.encode(JSON.stringify(payload)));
+    return `v1.${b64url(cipher)}.${b64url(iv.buffer)}`;
+}
+/**
+ * Decrypts a token and validates signature, expiration, and replay.
+ *
+ * @template T
+ * @param token Encrypted token
+ * @param secret Shared secret
+ * @param intervalSeconds Rotation interval
+ * @param options Validation options
+ *
+ * @returns Decrypted data
+ *
+ * @throws Error if token invalid, expired, replayed, or signature mismatch
+ *
+ * @example
+ * const data = await decrypt(
+ *   token,
+ *   "super-secret",
+ *   60,
+ *   { signature: "auth-session" }
+ * )
+ */
+async function decrypt(token, secret, intervalSeconds, options = {}) {
+    var _a, _b;
+    const cryptoObj = await (0, cryptoProvider_1.getCrypto)(options.env);
+    const expectedSignature = (_a = options.signature) !== null && _a !== void 0 ? _a : "default-signature";
+    const [version, cipherB64, ivB64] = token.split(".");
+    if (version !== "v1")
+        throw new Error("Unsupported token version");
+    const iv = fromB64url(ivB64);
+    const cipher = fromB64url(cipherB64);
+    const now = Math.floor(Date.now() / 1000);
+    const tolerance = (_b = options.clockToleranceSeconds) !== null && _b !== void 0 ? _b : 30;
+    const timeSlots = [
+        Math.floor(now / intervalSeconds),
+        Math.floor((now - tolerance) / intervalSeconds),
+        Math.floor((now + tolerance) / intervalSeconds),
+    ];
+    let payload = null;
+    for (const slot of timeSlots) {
+        try {
+            const key = await deriveKey(cryptoObj, secret, slot);
+            const plain = await cryptoObj.subtle.decrypt({ name: "AES-GCM", iv }, key, cipher);
+            payload = JSON.parse(decoder.decode(plain));
+            break;
+        }
+        catch { }
+    }
+    if (!payload)
+        throw new Error("Unable to decrypt token");
+    if (payload.sig !== expectedSignature) {
+        throw new Error("Invalid token signature");
+    }
+    if (payload.exp + tolerance < now) {
+        throw new Error("Token expired");
+    }
+    checkReplay(payload.nonce);
+    return payload.data;
+}

package/dist/cryptoProvider.d.ts

@@ -0,0 +1,8 @@
+export type RuntimeEnv = "auto" | "browser" | "node";
+/**
+ * Returns a Web Crypto compatible Crypto object depending on runtime.
+ *
+ * - Browser → window.crypto
+ * - Node 18+ → node:crypto webcrypto
+ */
+export declare function getCrypto(env?: RuntimeEnv): Promise<Crypto>;

package/dist/cryptoProvider.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCrypto = getCrypto;
+/**
+ * Returns a Web Crypto compatible Crypto object depending on runtime.
+ *
+ * - Browser → window.crypto
+ * - Node 18+ → node:crypto webcrypto
+ */
+async function getCrypto(env = "auto") {
+    // Browser detection
+    if (env === "browser" || (env === "auto" && typeof window !== "undefined")) {
+        if (!globalThis.crypto) {
+            throw new Error("Web Crypto API not available in browser");
+        }
+        return globalThis.crypto;
+    }
+    // Node detection
+    if (env === "node" || env === "auto") {
+        try {
+            const nodeCrypto = await import("node:crypto");
+            return nodeCrypto.webcrypto;
+        }
+        catch {
+            throw new Error("Web Crypto API not available in Node.js (requires Node 18+)");
+        }
+    }
+    throw new Error("Unable to detect runtime crypto environment");
+}

package/dist/index.d.ts

@@ -1,30 +1,2 @@
-/**
- * Time-Based Cipher with Encrypted Signature
- *
- * Format:
- *   sigCipherHex:sigIvHex:dataCipherHex:dataIvHex
- *
- * Requirements:
- *   - Node.js 18+
- *   - Modern browsers
- */
-/**
- * Encrypt JSON data with encrypted signature.
- *
- * @param data - JSON-serializable data.
- * @param secret - Shared secret.
- * @param intervalSeconds - Rotation interval in seconds.
- *
- * @returns Promise resolving to ciphertext string.
- */
-export declare function encrypt<T>(data: T, secret: string, intervalSeconds: number): Promise<string>;
-/**
- * Decrypt ciphertext with encrypted signature validation.
- *
- * @param payload - Ciphertext string.
- * @param secret - Shared secret.
- * @param intervalSeconds - Rotation interval.
- *
- * @returns Promise resolving to decrypted data.
- */
-export declare function decrypt<T>(payload: string, secret: string, intervalSeconds: number): Promise<T>;
+export * from "./cipher";
+export * from "./cryptoProvider";

package/dist/index.js

@@ -1,122 +1,18 @@
 "use strict";
-/**
- * Time-Based Cipher with Encrypted Signature
- *
- * Format:
- *   sigCipherHex:sigIvHex:dataCipherHex:dataIvHex
- *
- * Requirements:
- *   - Node.js 18+
- *   - Modern browsers
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.encrypt = encrypt;
-exports.decrypt = decrypt;
-const cryptoObj = (() => {
-    if (typeof globalThis !== "undefined" && globalThis.crypto) {
-        return globalThis.crypto;
-    }
-    throw new Error("Web Crypto API not available. Requires Node 18+ or modern browser.");
-})();
-const encoder = new TextEncoder();
-const decoder = new TextDecoder();
-/**
- * Convert ArrayBuffer to hex string.
- */
-function toHex(buffer) {
-    return Array.from(new Uint8Array(buffer))
-        .map((b) => b.toString(16).padStart(2, "0"))
-        .join("");
-}
-/**
- * Convert hex string to ArrayBuffer.
- */
-function hexToBuffer(hex) {
-    if (!/^[0-9a-fA-F]+$/.test(hex) || hex.length % 2 !== 0) {
-        throw new Error("Invalid hex string");
-    }
-    const bytes = new Uint8Array(hex.match(/.{1,2}/g).map((b) => parseInt(b, 16)));
-    return bytes.buffer;
-}
-/**
- * Derive AES-256-GCM key using HKDF-SHA256.
- */
-async function deriveKey(secret, intervalSeconds) {
-    if (!secret)
-        throw new Error("Secret must not be empty");
-    if (intervalSeconds <= 0)
-        throw new Error("intervalSeconds must be positive");
-    const now = Date.now() - 1000;
-    const timeSlot = Math.floor(now / (intervalSeconds * 1000));
-    const baseKey = await cryptoObj.subtle.importKey("raw", encoder.encode(secret).buffer, { name: "HKDF" }, false, ["deriveKey"]);
-    return cryptoObj.subtle.deriveKey({
-        name: "HKDF",
-        hash: "SHA-256",
-        salt: encoder.encode(String(timeSlot)).buffer,
-        info: encoder.encode("time-based-encryption").buffer,
-    }, baseKey, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
-}
-/**
- * Encrypt raw ArrayBuffer with AES-GCM.
- */
-async function aesEncrypt(key, data) {
-    const ivBytes = cryptoObj.getRandomValues(new Uint8Array(12));
-    const iv = ivBytes.buffer;
-    const cipher = await cryptoObj.subtle.encrypt({ name: "AES-GCM", iv }, key, data);
-    return { cipher, iv };
-}
-/**
- * Decrypt raw ArrayBuffer with AES-GCM.
- */
-async function aesDecrypt(key, cipher, iv) {
-    return cryptoObj.subtle.decrypt({ name: "AES-GCM", iv }, key, cipher);
-}
-/**
- * Encrypt JSON data with encrypted signature.
- *
- * @param data - JSON-serializable data.
- * @param secret - Shared secret.
- * @param intervalSeconds - Rotation interval in seconds.
- *
- * @returns Promise resolving to ciphertext string.
- */
-async function encrypt(data, secret, intervalSeconds) {
-    const key = await deriveKey(secret, intervalSeconds);
-    // Signature payload (can be customized)
-    const signaturePayload = encoder.encode("signature-v1").buffer;
-    const sigEncrypted = await aesEncrypt(key, signaturePayload);
-    const dataBuffer = encoder.encode(JSON.stringify(data)).buffer;
-    const dataEncrypted = await aesEncrypt(key, dataBuffer);
-    return [
-        toHex(sigEncrypted.cipher),
-        toHex(sigEncrypted.iv),
-        toHex(dataEncrypted.cipher),
-        toHex(dataEncrypted.iv),
-    ].join(":");
-}
-/**
- * Decrypt ciphertext with encrypted signature validation.
- *
- * @param payload - Ciphertext string.
- * @param secret - Shared secret.
- * @param intervalSeconds - Rotation interval.
- *
- * @returns Promise resolving to decrypted data.
- */
-async function decrypt(payload, secret, intervalSeconds) {
-    const parts = payload.split(":");
-    if (parts.length !== 4) {
-        throw new Error("Invalid cipher format");
+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]; } };
     }
-    const [sigCipherHex, sigIvHex, dataCipherHex, dataIvHex,] = parts;
-    const key = await deriveKey(secret, intervalSeconds);
-    // Decrypt signature
-    const sigPlain = await aesDecrypt(key, hexToBuffer(sigCipherHex), hexToBuffer(sigIvHex));
-    const sigText = decoder.decode(sigPlain);
-    if (sigText !== "signature-v1") {
-        throw new Error("Invalid signature");
-    }
-    // Decrypt actual data
-    const dataPlain = await aesDecrypt(key, hexToBuffer(dataCipherHex), hexToBuffer(dataIvHex));
-    return JSON.parse(decoder.decode(dataPlain));
-}
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./cipher"), exports);
+__exportStar(require("./cryptoProvider"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "timebasedcipher",
-  "version": "3.0.2",
+  "version": "3.0.3",
   "description": "Time-based key generation and AES encryption/decryption SDK",
   "main": "dist/index.js",
   "module": "dist/index.js",