🤏 Tiny Web Tokens (TWT)

Tiny Web Tokens (TWT) are like JSON Web Tokens (JWT), but for tiny payloads. They're an opinionated, non-standard way to generate and validate string payloads.

Looking for the Twitter CLI twt? See the docs for v0.x on GitHub or npm.

📋 Spec

A TWT is a URL-safe string with a payload and its computed HMAC MD5. The length of a TWT is the length of its payload + 32 characters. For example:

hellobade63863c61ed0b3165806ecd6acefc

In the above example, the payload is hello, and its hash is bade63863c61ed0b3165806ecd6acefc, signed using the secret key secret.

Is TWT a replacement for JWT?

TWT is not a replacement for JWT, and you should use JWTs for most use cases. TWTs are only useful for no-expiry, string payloads. The use case is instead of using a random-character string, use its TWT, so that users cannot modify it.

You should not use TWT:

• For secure authentication tokens
• When you want token expiry
• When your payload is a JSON object
• When you want to customize the algorithm
• When you need to sign with RSA keys

However, you can use TWT when your payload is a single string with no expiry and you don't want users to modify them, in use cases like:

• Sessions tokens
• Unique user ID parameters in URLs
• Fingerprint cookies

TWTs are Tiny

Compared to a JWT which includes information about the algorithm and base64-encodes the JSON object, TWTs are much smaller because they are hardcoded to use HMAC with MD5 (which is insecure but short, and works very well for this use case) and only support a string.

A JWT signed with secret and one key-value pair { session_id: "fYbiqoTfXHtW6xPuq7hs" } is 131 characters long, whereas a TWT with the value fYbiqoTfXHtW6xPuq7hs is only 52 characters long, less than half of the JWT length.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uX2lkIjoiZlliaXFvVGZYSHRXNnhQdXE3aHMifQ.vrMGzUZ7qt4KXbBRG9VAVlVRGFLXTXYs0cAjQJpSc4s

Example use case

For example, if you have a webpage http://example.com/profile?id=3 where the user with ID = 3 can edit their profile, you can use a TWT instead: http://example.com/profile?id=3eccbc87e4b5ce2fe28308fd9f2a7baf3. This means that users cannot change the ID from the address bar to impersonate someone else (of course, there are other checks to ensure permissions, but you get the idea).

At Koj, we're using TWT as part of our onboarding process. When a new user signs up on https://koj.co/en-ch/get-started, we ask them their name and generate a unique ID for their onboarding session. Then, we redirect them to https://koj.co/en-ch/get-started/fYbiqoTfXHtW6xPuq7hsdaa019dae774e16ea5e3cb5e9c1cf72a/furniture/bed, for example, when we ask for their bed preference. In this case, the user's session ID is fYbiqoTfXHtW6xPuq7hs, but we use a TWT in the URL. This means that that users cannot simply change the session ID from the address bar to impersonate someone else.

💡 Usage

Install the package from npm:

npm install twt

Import and use:

import { sign, verify, decode, validate } from "twt";
const SECRET = "your-super-safe-secret";

sign("hello", SECRET);
// hellobade63863c61ed0b3165806ecd6acefc

verify("hellobade63863c61ed0b3165806ecd6acefc", SECRET);
// hello

verify("hello.this-is-not-the-correct-hmac", SECRET);
// Throws an InvalidHmacError

decode("hello.this-is-not-the-correct-hmac");
// hello

validate("hellobade63863c61ed0b3165806ecd6acefc");
// true

sign("hello", SECRET, 10);
// hellobade63863c with 10 characters length

sign("hello", SECRET, 64, "sha256");
// Example with SHA-256 (requires 64 characters)
// hello88aab3ede8d3adf94d26ab90d3bafd4a2083070c3bcce9c014ee04a443847c0b

For the secret, you should generate and use a random 160-bit key.

👩‍💻 Development

Build TypeScript:

npm run build

Run unit tests and view coverage:

npm run test-without-reporting

📄 License

• Code: MIT © Koj
• Thanks to Geoffrey Dhuyvetters for the npm package name twt