legid

A library for generating safe, legit and random URL-compat IDs.

Unlike other random ID libs, Legid is to solve the client-side manipulation problem. Read the example below.

Why use Legid?

In a modern web application, you often need to generate short and unique IDs on the client side:

<button onClick={async () => {
  // Some function to generate a random ID
  const id = generateId()

  // Optimistically update the URL so the user will see the page immediately
  router.push(`/tweet/${id}`)

  // Send the actual request to post the tweet
  await createTweet(id, content)
}}>
  Submit Tweet
</button>

Usually, you would use a random string generator or just a UUID. However, the main problem with these approaches is client-side manipulation and man-in-the-middle attacks.

For example, if a malicious user overrides the client generateId implementation via browser developer tools to return an ID of their choice, such as "admin", the server would accept it without any verification. And suddenly, the user successfully created a tweet with the special URL /tweet/admin, which is not what we want to happen.

Usually, this can be solved by generating the ID on the server side, or by using both an ID and a verification token/nonce. But we want to avoid:

• Extra network request before knowing the ID
• Storing pre-generated IDs on the server
• Sending one-off tokens or nonces between client and server
• Using a wordlist on the server to filter out not-allowed IDs

Legid is here to solve this problem.

Features

The legid library provides a simple and secure way to generate and verify IDs that only consist of URL-safe characters (A-Z, a-z, 0-9). It is designed to be:

• Safe to use on the client side
  • Avoids manipulation
  • Prevents malicious tampering
• Easy to verify on the server side
  • No nounce or shared secret necessary between client and server
  • No extra token or verification step required

Usage

pnpm install legid

Client side

Create a random ID string:

import { createId } from 'legid'

const id = await createId()

// Example: 'e3N4BRJW2d'

Specify the custom ID length (approximate) and hash salt (see below) if needed:

import { createId } from 'legid'

const id = await createId({
  approximateLength: 20,  // Custom length, default is 10
  salt: 'my-custom-salt', // Custom salt, default is 'legid:'
})

// Example: 'gnzJb1TCJobhuG4PrIZz'

It’s safe to expose the salt on the client side, as it is not a secret. Make sure the verification on the server side uses the same salt.

Server side

Use the verify function to check if an ID is valid:

import { verifyId } from 'legid'

// Server Side
const isValid = await verifyId(id)

When isValid is false, the ID is either malformed or not generated by legid.

The verifyId function can also accept a custom salt just like createId:

import { verifyId } from 'legid'

const isValid = await verifyId(id, {
  salt: 'my-custom-salt', // Custom salt, default is 'legid:'
})

How it works

The generated ID consists of a random data buffer with its SHA-1 hash. These 2 parts are mixed together at odd and even positions, respectively, and then converted to a custom alphabet (A-Z, a-z, 0-9). The SHA-1 hash is salted with a prefix to prevent rainbow table attacks.

The reversed process is used to verify the ID.

This means that if a malicious user tries to generate an ID with a specific value, let’s say "admin", conceptually they need to ensure that SHA1(salt + "di") starts with "amn" so the mixed ID would be "admin". This is very unlikely to happen, at least not with a reasonable amount of effort.

Note

While this is not a cryptographic solution, it is designed to make it difficult to manipulate the ID with lowest effort. It is not intended for use in cryptographic applications or where high security is required.

Collisions are still possible. The format Legid uses will decrease the possible generation space. For a given length L, there will be approximately 62^(L/2) IDs available. You should always check collision and ID length on the server side before proceeding.

Possible adjustments can be made to this lib by changing RHRHRH (R for random data position, H for hash positions) to other representations like HRRHRR to reduce the collision rate with a compromise of security.

Author

Created by Shu Ding @vercel.

License

The MIT License.