cuid2 generator

CUID2 is the second generation of the Collision-Resistant Unique Identifier format, created by Eric Elliott as a complete redesign of the original CUID library. Released in 2023, CUID2 was built from the ground up to address security vulnerabilities, privacy concerns, and architectural limitations that had been identified in the original CUID over its decade of widespread use. Where the first version concatenated its entropy sources into a predictable structure, CUID2 takes a fundamentally different approach: it passes all entropy through a hash function, producing an opaque, cryptographically secure identifier that reveals nothing about the machine, process, or timing context in which it was generated.

The motivation for CUID2 came from growing awareness that the original CUID's reliance on Math.random(), combined with its exposed client fingerprint and readable timestamp, created theoretical attack vectors. In adversarial environments, a sufficiently motivated attacker could potentially predict future CUIDs or extract host information from generated identifiers. CUID2 eliminates these concerns entirely by using cryptographically secure random number generation and a one-way hash function that makes reverse-engineering the inputs computationally infeasible. The result is an identifier format that maintains the original's simplicity and developer ergonomics while meeting modern security expectations.

How CUID2 Works

CUID2 generation begins by gathering entropy from multiple sources, similar in spirit to the original CUID but with critical differences in how that entropy is processed. The inputs to the generation algorithm include a high-resolution timestamp, a global counter that increments with each call, a random salt generated using a cryptographically secure random number generator (such as the Web Crypto API in browsers or the crypto module in Node.js), and additional random data that replaces the original CUID's machine fingerprint.

The key architectural change is that all of these inputs are concatenated and then passed through a hash function rather than being directly included in the output. CUID2 uses a variant of the Sha3 hash algorithm (specifically, a simplified entropy hash) to collapse the combined inputs into a fixed-length digest. This hashing step is what makes CUID2 fundamentally more secure than its predecessor. Because hash functions are one-way operations, it is computationally infeasible to determine the timestamp, counter value, or any other input from the final identifier. This means CUID2 leaks no information about when or where it was generated.

The output of the hash is then encoded into a lowercase alphanumeric string. By default, CUID2 identifiers are 24 characters long, though the length is configurable. The first character is always a letter, ensuring compatibility with HTML element IDs, CSS selectors, and systems that require identifiers to begin with an alphabetic character. The default alphabet consists of the 36 characters a-z and 0-9, producing compact, URL-safe strings that require no encoding when used in web contexts.

Because the timestamp is hashed rather than encoded directly, CUID2 identifiers are not time-sortable. This is a deliberate design trade-off. The CUID2 authors considered time-sortability a potential information leak and prioritized security over ordering. Applications that require chronological sorting must store a separate timestamp field alongside the identifier.

The removal of the client fingerprint is another intentional design decision. The original CUID derived a fingerprint from host properties like the process ID and hostname, which raised concerns about information disclosure in multi-tenant environments and regulatory contexts where minimizing data exposure is important. CUID2 replaces the fingerprint with additional cryptographically secure random data, achieving equivalent collision resistance without embedding any host-specific information in the identifier.

The collision resistance of CUID2 has been empirically validated through large-scale testing. The library's test suite generates millions of identifiers across concurrent workers and verifies zero collisions. The theoretical collision probability for the default 24-character configuration is vanishingly small, comparable to the guarantees provided by 122-bit random UUIDs.

Use Cases

User-facing identifiers in web applications. CUID2 is an excellent choice for identifiers that appear in URLs, API responses, and user interfaces. The output is short, lowercase, and URL-safe, requiring no encoding or escaping. Because CUID2 reveals no information about its generation context, it is safe to expose in public-facing contexts without risk of leaking server topology, process details, or precise creation timestamps.

Multi-tenant SaaS platforms. In environments where multiple customers share infrastructure, the opacity of CUID2 identifiers is a significant advantage. Unlike formats that embed timestamps or machine identifiers, CUID2 prevents any tenant from inferring information about other tenants' activity, resource creation rates, or the underlying infrastructure. This property simplifies compliance with data minimization principles found in regulations like GDPR.

Distributed systems without ordering requirements. For microservices, event-driven architectures, and distributed databases where each node needs to independently generate unique identifiers without central coordination, CUID2 provides strong collision resistance with minimal overhead. The combination of timestamp, counter, and cryptographic randomness ensures that even nodes operating under identical conditions will produce distinct identifiers. Applications that do not need to sort records by creation time benefit from the enhanced security without any functional compromise.

Session tokens and ephemeral identifiers. The cryptographic security of CUID2 makes it suitable for session identifiers, invitation tokens, and other values where predictability could enable session hijacking or enumeration attacks. While CUID2 is not a replacement for purpose-built session management libraries, its unpredictability provides a stronger foundation than formats based on Math.random() or predictable sequences.

Comparison with Alternatives

Compared to the original CUID, CUID2 represents a complete architectural overhaul rather than an incremental update. The original concatenated its entropy sources into a readable format; CUID2 hashes them into an opaque string. The original used Math.random(); CUID2 uses cryptographically secure randomness. The original included a machine fingerprint; CUID2 does not. The original was roughly time-sortable; CUID2 deliberately is not. For any project currently using the original CUID, migrating to CUID2 is the recommended path forward.

Compared to Nano ID, CUID2 and Nano ID occupy similar design spaces but differ in philosophy. Nano ID is purely random with no internal structure, offers full customization of alphabet and length, and has an extremely small bundle size (around 130 bytes for the non-secure version). CUID2 incorporates a timestamp and counter into its hash input, providing a deterministic component that strengthens collision resistance beyond pure randomness, though this difference is negligible at typical scales. Nano ID is often preferred for its flexibility and minimal footprint, while CUID2 appeals to developers who want an opinionated, secure default with no configuration required.

Compared to UUID v4, CUID2 produces shorter, more visually compact identifiers without hyphens. Both formats rely on cryptographic randomness and provide comparable collision resistance at their default lengths. UUID v4 benefits from universal standardization, native support in virtually every database and programming language, and decades of production history. CUID2 offers a more modern developer experience with its shorter output, guaranteed alphabetic first character, and JavaScript-first design, but it lacks the cross-platform ubiquity of the UUID specification.