Aleph

Temporal cryptography and absolute unique value generator based on AES-256 and UUIDv7.

@morkg/aleph is a production-ready TypeScript library for generating cryptographically secure, time-based tokens with built-in encryption, expiration support, and lifetime tracking. It combines AES-256-CBC encryption with UUIDv7 for creating tamper-proof, unique identifiers perfect for authentication tokens, session management, and secure data transmission.

Why use Aleph

• Military-grade encryption: AES-256-CBC cryptography with secure key derivation
• Time-based uniqueness: UUIDv7 ensures temporal uniqueness and sortability
• Zero dependencies: Lightweight, minimal footprint, no external runtime dependencies
• TypeScript native: Full type safety with built-in type definitions
• Expiration built-in: Optional token expiration with automatic lifetime tracking
• Simple API: Three main functions covering all use cases
• Production-ready: Battle-tested for authentication and session management

Installation

Install with npm or yarn:

npm install @morkg/aleph

or:

yarn add @morkg/aleph

Quick Start

import { encode, decode, lifetime } from "@morkg/aleph";

// Create an encrypted token with 24-hour expiration
const token = encode("user:12345", "your-secret-key", 24 * 60 * 60 * 1000);

// Decrypt and retrieve the original content
const content = decode(token, "your-secret-key");
console.log(content); // "user:12345"

// Check token metadata
const tokenLifetime = lifetime(token, "your-secret-key");
console.log(tokenLifetime.createdAt);
console.log(tokenLifetime.expiresAt);

Importing

ES Modules

import aleph, { encode, decode, lifetime } from "@morkg/aleph";

CommonJS

const aleph = require("@morkg/aleph").default;
const { encode, decode, lifetime } = require("@morkg/aleph");

API Reference

encode(text, secret, expire?)

Generates a unique encrypted token that embeds the original text.

Parameters:

• text (string): The string or payload to protect
• secret (string): Master key used to derive the AES-256 encryption key
• expire (optional, Date | number): Token expiration as Date object or milliseconds

Returns: A hexadecimal token string containing:

• A randomly generated UUIDv7 (uniqueness guarantor)
• The original text encrypted with AES-256-CBC
• The UUID encrypted with the derived key

Example:

import { encode } from "@morkg/aleph";

const secret = "my-secret-password";
const payload = "user:12345";
const token = encode(payload, secret);
console.log(token);

With expiration:

import { encode } from "@morkg/aleph";

const secret = "my-secret-password";
const payload = "access:admin";
const expiresAt = new Date(Date.now() + 60 * 60 * 1000); // expires in 1 hour
const token = encode(payload, secret, expiresAt);
console.log(token);

decode(token, secret)

Retrieves the original text from a token created by encode.

Parameters:

• token (string): The hexadecimal token produced by encode
• secret (string): The same secret used during token creation

Decryption Process:

1. Decrypts the initial UUID using the master secret
2. Uses that UUID to decrypt and retrieve the original payload

Throws: Token expired error if the token has an expiration timestamp that has already passed.

Example:

import { decode } from "@morkg/aleph";

const secret = "my-secret-password";
const token = "..."; // from encode()

try {
  const original = decode(token, secret);
  console.log("Decoded:", original);
} catch (error) {
  console.error("Decode failed:", error.message);
}

lifetime(token, secret)

Extracts the creation and optional expiration dates of a token.

Parameters:

• token (string): The hexadecimal token produced by encode
• secret (string): The same secret used during token creation

Returns: An object with:

• created (Date): When the token was created
• expires (Date | null): Token expiration date, or null if no expiration

Example:

import { lifetime } from "@morkg/aleph";

const token = "..."; // from encode()
const dates = lifetime(token, "my-secret-password");

console.log("Created:", dates.created.toISOString());
console.log("Expires:", dates.expires?.toISOString() ?? "Never");

How It Works

Aleph uses a multi-layer encryption strategy:

• SHA-256 Key Derivation: Derives a 32-byte AES key from your secret
• AES-256-CBC Encryption: Military-grade encryption with initialization vectors
• UUIDv7 Uniqueness: Time-based UUIDs ensure temporal ordering and absolute uniqueness
• Dual Encryption: The internal UUID is also encrypted with the derived key for additional security

Key Features

• Unique tokens: Each encode() produces a unique token, even for identical inputs
• Expiration support: Optional expiration dates with automatic validation on decode
• Zero state: No database or external state required—all data is embedded in the token
• Fast validation: Check token lifetime without full decryption

Exports

The package exports:

• encode — Creates encrypted tokens
• decode — Decrypts and validates tokens
• lifetime — Extracts token metadata (creation/expiration dates)
• origin — Deprecated alias for lifetime
• default — Default export with all functions

Using default export:

import aleph from "@morkg/aleph";

const token = aleph.encode("data", "secret");
const text = aleph.decode(token, "secret");
const dates = aleph.lifetime(token, "secret");

Use Cases

• Session tokens: Tamper-proof user sessions with automatic expiration
• API authentication: Secure, stateless API tokens without database lookups
• Email verification: Time-limited verification tokens that embed user IDs
• Password reset: Self-contained reset tokens with expiration windows
• OAuth flows: Secure state parameters and temporary access credentials
• Rate limiting: Embed user/IP data in rate-limit tokens

Performance

• No external I/O: All operations are CPU-bound with no I/O overhead
• Minimal dependencies: Uses only Node.js built-in crypto module
• O(1) operations: Encode, decode, and lifetime operations are constant-time
• Suitable for high-throughput: Generates thousands of tokens per second

Security Considerations

• Secret management: Store secrets securely using environment variables or secret managers
• Collision resistance: UUIDv7 provides cryptographic uniqueness; use strong secrets for additional security
• Token transmission: Always transmit tokens over HTTPS or secure channels
• Expiration validation: Always validate expiration on token decode
• Secret rotation: Implement secret rotation strategies for long-running applications

Contributing

Contributions are welcome! Please:

• Open an issue for feature requests or bugs
• Keep pull requests focused and well-described
• Run npm run build before submitting changes
• Follow existing code style and patterns

See the https://github.com/morkg/aleph for guidelines.

License

MIT