A library for generating safe, legit and random URL-safe IDs
npm install legidA 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.
In a modern web application, you often need to generate short and unique IDs
__on the client side__:
``typescript
// 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
`
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"admin"
via browser developer tools to return an ID of their choice, such as , the server/tweet/admin
would accept it without any verification. And suddenly, the user successfully created a tweet
with the special URL , 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
`bash`
pnpm install legid
Create a random ID string:
`typescript
import { createId } from 'legid'
const id = await createId()
// Example: 'e3N4BRJW2d'
`
Specify the custom ID length (approximate) and hash salt (see below) if needed:
`typescript
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.
Use the verify function to check if an ID is valid:
`typescript
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:
`typescript
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 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.
The MIT License.