A library for generating safe, legit and random URL-compat IDs.
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.
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
pnpm install legidCreate a random ID string:
import { createId } from 'legid'
const id = await createId()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:'
})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.
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:'
})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.
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 MIT License.