timebasedcipher

A lightweight, isomorphic (Node.js 18+ and modern browsers) library for secure token encryption and decryption using rotating keys.

It provides:

• Secure encryption of JSON data
• Automatic key rotation
• Built-in integrity validation
• Token expiration support
• Replay protection
• Compact URL-safe tokens
• Zero external dependencies

Installation

npm install timebasedcipher
# or
yarn add timebasedcipher
# or
pnpm add timebasedcipher

Requirements

• Node.js 18+ OR modern browser
• A shared secret string
• Same rotation interval used for encrypt and decrypt

Quick Start

import { encrypt, decrypt } from "timebasedcipher";

const secret = "mySuperSecret";
const intervalSeconds = 60;

const data = { userId: 123, role: "admin" };

// Encrypt
const token = await encrypt(data, secret, intervalSeconds);

// Decrypt
const result = await decrypt(token, secret, intervalSeconds);

console.log(result);

Token Behavior

Tokens created by this library:

• Automatically expire
• Cannot be tampered with
• Cannot be reused (replay protection)
• Are URL safe
• Rotate keys automatically based on time interval

API Reference

encrypt(data, secret, intervalSeconds, options?)

Encrypts JSON data and returns a secure token.

Parameters

| Name | Type | Description | | ----------------- | ------ | ----------------------- | | data | any | JSON serializable value | | secret | string | Shared secret | | intervalSeconds | number | Key rotation interval | | options | object | Optional settings |

Options

| Name | Type | Default | Description | | ----------------------- | ------------------------------- | --------------- | --------------------- | | ttlSeconds | number | intervalSeconds | Token expiration time | | clockToleranceSeconds | number | 30 | Allowed clock drift | | env | "auto" \| "node" \| "browser" | auto | Runtime override |

Returns

Promise<string>

Secure encrypted token.

decrypt(token, secret, intervalSeconds, options?)

Decrypts and validates a token.

Parameters

| Name | Type | Description | | ----------------- | ------ | --------------------------- | | token | string | Token from encrypt | | secret | string | Same secret used to encrypt | | intervalSeconds | number | Same rotation interval | | options | object | Optional settings |

Returns

Promise<T> Original decrypted data.

Example With Options

const token = await encrypt(data, secret, 60, {
  ttlSeconds: 300,
  clockToleranceSeconds: 60,
});

const result = await decrypt(token, secret, 60);

Environment Usage

Node.js

await encrypt(data, secret, 60, { env: "node" });

Browser

await encrypt(data, secret, 60, { env: "browser" });

Auto Detect (default)

await encrypt(data, secret, 60);

Error Handling

Decryption may throw errors in these cases:

• Token is invalid
• Token has expired
• Secret is incorrect
• Token was already used
• Token was modified
• Unsupported token version

Common Use Cases

• Session tokens
• API authentication
• Secure links
• Temporary access tokens
• Signed payload transport
• Passwordless login links

Performance

Typical latency on modern hardware:

• Encryption: ~0.3–1 ms
• Decryption: ~0.3–1 ms

Security Notes

• Keep your secret secure
• Use sufficiently long secrets (32+ characters recommended)
• Ensure system clocks are reasonably synchronized
• For multi-server deployments, consider shared nonce storage

Environment Support

| Platform | Supported | | --------------- | --------- | | Node.js 18+ | Yes | | Modern Browsers | Yes | | React / Next.js | Yes | | Edge runtimes | Yes |

License

MIT License © 2026
Deb Kalyan Mohanty