🛠️ IdCraft.js

IdCraft.js is a professional-grade JavaScript toolkit designed for crafting and inspecting cryptographically strong identifiers. It provides a unified interface for NanoID, UUID (v1, v4, v7), ULID and Random String, with built-in metadata analysis.

---

✨ Key Features

• ULID Generation: Universally Unique Lexicographically Sortable Identifiers. Generates 26-character, URL-safe IDs using Crockford's Base32 alphabet. Includes an automatic Monotonicity Guard to ensure strict chronological ordering during batch generation within the same millisecond.
• NanoID Generation: Customizable, URL-friendly IDs with built-in protection against modulo bias.
• UUID Generation:
  • v4: Secure random identifiers. Uses native crypto.randomUUID() when available for maximum performance.
  • v7: Modern, time-ordered IDs—optimized for database primary keys and sequential indexing.
• Random String Generation: Generate random Strings & Passwords.
• Deep Inspection (v1, v4, v7): Powerful analysis tools to "decode" existing UUIDs. Extract timestamps, ISO dates, relative time (e.g., "5 mins ago"), and even Node (MAC) information from v1 strings.
• Cryptographically Secure: Leverages the Web Crypto API (crypto.getRandomValues) for maximum entropy.
• Zero Dependencies: Pure JavaScript. Lightweight, fast, and dependency-free.
• Entropy Analysis Engine: Measures the exact mathematical strength of any string payload. Computes information entropy in bits ($H$) using the Shannon Entropy formula.

---

🚀 Installation

You can include IdCraft.js in your project by importing it:

import IdCraft from './IdCraft.js';

---

📖 Usage Guide

1. Generating NanoIDs

Create short, secure, and customizable IDs.

const result = IdCraft.generateNanoIds({
   count: 10,
   length: 12,
   lowercase: true,
   uppercase: true,
   numbers: true,
   symbols: true,
   extra: "",
   prefix: "user_",
   suffix: ""
});

console.log(result.nanoIds); // ["user_A1b2C3d4E5f6"]

2. Generating UUIDs

Generate standard v4 (random) or the new v7 (time-ordered) UUIDs.

// Generate 5 time-ordered UUIDs (v7)
const batch = IdCraft.generateUUIDs({
   count: 5,
   version: "v7",         // v4, v7
   format: "lowercase",   // lowercase | uppercase
   withHyphens: true,
   braces: "none",       // none, curly
});

console.log(batch.uuids);

3. Generating ULIDs

Generate Universally Unique Lexicographically Sortable Identifiers (ULIDs) wrapped in Crockford's Base32 encoding.

// Generate 5 time-ordered ULIDs
const batch = IdCraft.generateULIDs({
    count: 5,
    format: "uppercase"   // uppercase (standard) | lowercase
});

console.log(batch.ulids);
// Output: Array of 26-character sortable strings

console.log(batch.monotonicUsed); 
// true if monotonicity guard was triggered within the same millisecond

4. Generating Random Strings & Passwords

Create cryptographically secure random strings or strong passwords with smart filtering rules and character group distribution guarantees.

const result = IdCraft.getRandomString({
    length: 16,
    lowercase: true,
    uppercase: true,
    numbers: true,
    symbols: true,
    excludeSimilar: true,     // Excludes confusing chars like O, 0, I, l, 1
    excludeAmbiguous: true,   // Excludes symbols like ' " ` \ to prevent escaping issues
    guaranteeAll: true,       // Ensures at least one character from each active group
    extra: ""                 // Pass any additional custom characters here
});

console.log(result.string); // Example: "pX9#mK4@fG2!vR7$"

5. Inspecting UUIDs

One of IdCraft's features is the ability to "deconstruct" a UUID string to see its origin.

// Example: Inspecting multiple IDs at once
const items = [
    "018f4a12-b7e1-7abc-8d2f-4a5b6c7d8e9f", // valid v7
    "48507851-419b-4654-9337-1836f32e9206", // valid v4
    "invalid-id-123"                         // invalid
];

const results = IdCraft.inspectUUIDs(items);

results.forEach((inspection, index) => {
    if (inspection.valid) {
        console.log(`Item ${index} is a valid v${inspection.uuid.version}`);
        console.log(inspection.uuid.getInformation());
        
        // Access relative time if it's a time-based UUID (v1 or v7)
        const timeInfo = inspection.uuid.v7?.relativeTime || inspection.uuid.v1?.relativeTime;
        if (timeInfo) console.log(`Generated: ${timeInfo}`);
    } else {
        console.error(`Item ${index} error: ${inspection.error}`);
    }
});

---

6. Analyzing String Entropy & Strength

IdCraft includes an entropy evaluation engine designed to measure the mathematical strength of any string payload, compute its crack time, and map architectural vulnerabilities.

// Example: Analyzing an API key in Exhaustive Mode
const tokenResult = IdCraft.analyzeEntropy("4a5b6c7d8e9f2a1b", {
    searchMode: "exhaustive"
});

if (tokenResult.valid) {
    console.log(`Entropy: ${tokenResult.entropyBits} bits`);
    console.log(`Character Pool Size: ${tokenResult.poolSize}`);
    console.log(`Estimated Crack Time: ${tokenResult.crackTimeFormatted}`);
}

// Example 2: Profiling a user password in Smart Mode (evaluating heuristics)
const passwordResult = IdCraft.analyzeEntropy("Password12345!", {
    searchMode: "smart",
    guessesPerSecond: 1e12 // Simulating a high-end GPU cracking rig
});

if (passwordResult.valid) {
    console.log(`String Length: ${passwordResult.stringLength}`);
    console.log(`Vulnerability Metrics: ${passwordResult.crackTimeFormatted}`);
    
    // Iterate through telemetry logs to inspect active structural alerts or penalties
    passwordResult.messages.forEach(msg => {
        console.log(`[${msg.severity.toUpperCase()}] ${msg.title}: ${msg.details}`);
    });
}

---

🛡️ Security & Performance

Native Speed

For UUID v4, IdCraft automatically detects if the environment supports the native crypto.randomUUID() method. If available, it uses the browser/runtime's optimized implementation. If not, it falls back to a secure crypto.getRandomValues() buffer implementation.

Modulo Bias Protection

Most simple ID generators use Math.random() % charset.length, which creates a subtle statistical bias. IdCraft eliminates this by calculating a maxValid threshold, ensuring that every character in your alphabet has a mathematically equal chance of being selected.

---

🛡️ View online

You can view the usage of library online at:

https://nkode.gr/GR/tools/uuid-generator

---

https://nkode.gr/EN/tools/uuid-inspector

---

https://nkode.gr/EN/tools/nano-id-generator

---

📜 License

This project is licensed under the GNU GPL v3.0 or later - see the LICENSE file for details.