@evanion/token

Short codes a person can read aloud, type off a card, or dictate over a phone — each carrying a check character, so a mistyped one is rejected before you touch the database.

import { createToken } from '@evanion/token';
 
const token = createToken();
 
token.generate();
// { value: 'a4kp-9mxa', body: 'a4kp9mx', check: 'a', prefix: undefined }
 
token.validate('a4kp-9mxa'); // { valid: true, body: 'a4kp9mx' }
token.validate('a4kp-9mx8'); // { valid: false, reason: 'check-failed' }

Installation

npm install @evanion/token

Node 20 or newer, or a browser — generate draws from crypto.getRandomValues, which both provide. ESM only. One dependency, @evanion/luhn.

The alphabet and the check character

The alphabet leaves out characters that are confused when read or heard. 1/l/i and 0/o are the point; w goes too, because “double-u” is the one English letter name that contains another letter’s name.

Every code carries a check character and there is no option to omit it. A mistyped code fails the check without a database lookup.

value and body

token.generate({ prefix: 'ORD' });
// { value: 'ORD-a4kp-9mxa', body: 'a4kp9mx', check: 'a', prefix: 'ORD' }

value is the code as a person sees it: prefix, chunks, separators. body is what the check character was computed over, unchunked — the form to store and index on.

validate returns body too, from the stripped and case-folded input, so a code typed without its separators still resolves to the same stored key.

What it does not do

It does not check for collisions and never retries. Uniqueness is a unique index on your table; see Entropy and collisions for the numbers you need to size length.

valid: true does not mean the code exists, and it is not authentication. One code in n passes by construction — one in 32 with the default alphabet. Treat it as a filter in front of a lookup, never as a credential.

The prefix sits outside the checksum. ORD-a4kp-9mxa checksums a4kp9mx only, and validate takes the code without the prefix.

Pages

• Generating and validating — the two operations, separators, prefixes
• The alphabet — the default 32, and the constraints on your own
• Entropy and collisions — sizing length
• API reference

Related

@evanion/luhn supplies the check character and is the package to reach for when you have your own identifier and only want to sign it.