Entropy and collisions

To determine the correct length for the codes your system will issue, you can use the entropyBits property on the token instance returned by createToken.

The Problem: The “Birthday Paradox” in Codes

When you generate random IDs, you don’t just worry about running out of possible values—you worry about collisions. A collision occurs when generate() produces a value that has already been issued to another user.

Because of the “Birthday Paradox,” collisions happen much sooner than you’d expect. For example, with 35 bits of entropy, you don’t need 34 billion codes to see a collision; there’s a 50% chance of a collision after only 218,000 codes.

Calculating Entropy

The entropy of a token is the total number of random bits it carries. Since the check character is computed from the body and isn’t random, the formula is:

$\text{Entropy Bits} = (\text{length} - 1) \times \log_2(\text{dictionary size})$

entropyBits reports this figure automatically:

const token = createToken();
 
token.entropyBits; // -> 35
createToken({ length: 12 }).entropyBits; // -> 55
createToken({ length: 13, chunkSize: 13 }).entropyBits; // -> 60

The default length of 8 and 32-character dictionary provide 35 bits. Increasing the length to 13 increases the entropy to 60 bits.

Collision Probability

The 50% collision point is roughly $1.18 \times \sqrt{2^{\text{bits}}}$. As you increase the length, the risk of collision drops exponentially:

Handling Collisions with Unique Indexes

@evanion/token does not check your database for collisions because it has no access to your issued codes. The responsibility for uniqueness lies with your database.

The best practice is to put a UNIQUE index on the body column and redraw the code if the insert fails:

const token = createToken();
 
/** Stands in for the orders table's unique index on the code's body. */
const issued = new Set<string>();
 
function insertPickupCode(body: string): boolean {
  if (issued.has(body)) return false;
  issued.add(body);
  return true;
}
 
function issuePickupCode(): string {
  for (let attempt = 0; attempt < 5; attempt++) {
    const { value, body } = token.generate({ prefix: 'ORD' });
    if (insertPickupCode(body)) return value;
  }
  throw new Error('could not allocate a pickup code');
}
 
issuePickupCode().startsWith('ORD-'); // -> true
issued.size; // -> 1

In this pattern, you catch the unique violation error and call generate() again. The chance of five consecutive collisions at 35 bits is effectively zero ($\approx 10^{-15}$), making this a robust implementation.

Sizing Your Code Length

To choose the right length, calculate the chance that the next insert will conflict: $\frac{\text{Codes Issued}}{2^{\text{bits}}}$.

A good rule of thumb is to keep this probability below 1 in 1,000 for your expected volume over the next three years. For a default 35-bit token, this threshold is reached at about 34 million issued codes.

Security Warning: Guessing vs. Typo-Detection

It is critical to understand that token codes are not secure credentials.

A 35-bit code is designed to protect against transcription errors (typos), not adversarial guessing. If a code grants high-value access (like a password reset or a gift card balance), it is susceptible to enumeration attacks.

• Wrong tool: Do not use @evanion/token for session IDs or security tokens. Use a 128-bit random value (UUID) for those.
• Right tool: Use it for pickup codes, support tickets, or any identifier a human must handle.

If a readable code must gate a resource (like a gift card), you must implement additional security:

1. Rate-limiting: Prevent attackers from guessing thousands of codes per second.
2. Second-factor binding: Bind the code to a known identity, such as the customer’s email address.

Why not just make codes shorter?

You might wonder why we don’t just use a larger dictionary or drop the check character to save space.

1. Alphabet Limits: Using a 64-character dictionary would require punctuation or non-ASCII characters. Even expanding to a full alphanumeric set (36 chars) would force us to include characters like o and l, which are easily confused with 0 and 1. We prioritize a “clean” alphabet to ensure human readability and transcription accuracy over raw density.
2. The Value of the Check: Dropping the check character would increase entropy (e.g., 40 bits instead of 35), but it would mean every mistyped code triggers a database lookup and a “Not Found” error.

The check character is the primary value proposition of the library; without it, you’re just generating random strings.