twt
    TypeScript icon, indicating that this package has built-in type declarations

    1.3.1 • Public • Published

    🤏 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.

    Node CI Travis CI Coverage Dependencies License Vulnerabilities Based on Node.ts npm type definitions npm package npm downloads Contributors semantic-release

    npm

    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

    Koj

    An open source project by Koj.
    Furnish your home in style, for as low as CHF175/month →

    Install

    npm i twt

    DownloadsWeekly Downloads

    33

    Version

    1.3.1

    License

    MIT

    Unpacked Size

    14.8 kB

    Total Files

    6

    Last publish

    Collaborators

    • anandchowdhary
    • kojbot