🔐 ForgeID

A scalable, secure, and verifiable unique ID generator for Node.js.
Designed to evolve with time and prevent collisions for decades — even millennia.

✨ Features

• ✅ Cryptographically signed (HMAC SHA-256)
• 🧆 Unique and verifiable
• 🕰️ ID length grows over time
• 🔐 Includes timestamp + device fingerprint
• 🧪 Built-in validation and stress testing
• 🩸 Zero dependency (only uses crypto and os)
• 🎨 Supports prefix and formatting (dash, space)

🚀 Installation

npm install forgeid

🔧 Basic Usage

const ForgeID = require('forgeid')
const forge = new ForgeID('your-secret')

const id = forge.generate()
console.log('ID:', id)

const isValid = forge.verify(id)
console.log('Verified:', isValid)

🎨 With Prefix & Format

forge.generate('TRX')                 // TRX-abc123xyz...
forge.generate('ORD', 'dash')        // ORD-abc123-def456...
forge.generate('REF', 'space')       // REF abc123 def456...

📀 ID Structure

Each ID includes:

• Random entropy from crypto.randomBytes
• Host fingerprint (hostname + MAC)
• Base36 timestamp (Date.now())
• Signature from HMAC (last 10 characters)

ID format is:

[prefix-]baseContent + signature

Length increases over time:

length = baseLength + floor((currentYear - startYear) / intervalYears)

🧪 Stress Test

const forge = new ForgeID('your-secret')
forge.stressTest(1e6, 1e5)

Tests 1 million IDs for:

• Duplicate collision
• HMAC signature validity

🗒️ API

new ForgeID(secret?: string, startYear?: number, baseLength?: number, intervalYears?: number)

forge.generate(prefix?: string, format?: 'dash' | 'space' | ''): string

forge.verify(id: string): boolean

forge.format(id: string, style?: 'dash' | 'space' | ''): string

forge.stressTest(total?: number, step?: number): void

✅ Unit Testing

npm install --save-dev mocha chai
npm test

Test cases cover:

• Raw ID generation & verification
• Formatted and prefixed IDs
• Tampered/invalid inputs
• Collision-free generation (10K+)

🧠 TypeScript Support

import ForgeID from 'forgeid'

const forge = new ForgeID()
const id: string = forge.generate('TRX', 'dash')
const isValid: boolean = forge.verify(id)

Types are defined in forgeid.d.ts.

📆 Build

npm run build

Produces:

• dist/forgeid.min.js → minified bundle
• dist/forgeid.d.ts → TypeScript definitions

📄 License

MIT © NeaByteLab