pals.dev/brief

A simple, zero-dependency library to generate (and verify) tokens of arbitrary data with an expiration date. You can think of this as a very stripped-down version of JWT.

It’s based on the Dos and Don’ts of Client Authentication on the Web, which is an oldie but goodie.

It is called brief because:

• Life is brief

• The tokens this module generates are best briefly-lived

• Brief means "letter" (paper & envelope!) in German, and you should sign those, too.

Installation [_installation]

To use brief in your project, run:

go get pals.dev/brief

Usage [_usage]

Below is a basic example of how to use the module to create a new Mint for generating tokens and how to verify a token’s validity.

The code below does not compile; see tests for executable code.

package main

import (
    "fmt"
    "time"

    "pals.dev/brief" // Import the module
)

func main() {
    // Create a new Mint with a secret.
    mint := brief.NewMint([]byte("your-256-bit-secret"))
    // Alternatively, use the zero-value
    mint = &Mint{}
    // If you used the zero-value, you might need the secret for another day
    sec := mint.GetSecret()
    encodedSecret := brief.Encode(sec) // string for another day.

    // Generate a token with a 1-hour expiration.
    token, err := mint.Sign([]byte("session-id-or-whatever"), time.Now().Add(time.Hour))
    if err != nil {
        // handle error
    }
    // You can also generate random data, say for a session ID.
    token, err := mint.Generate(18, time.Now().Add(time.Hour))
    if err != nil {
        // handle error
    }
    // If you need a list of key/value pairs, you can encode url.Values
    vals := url.Values{}
    vals.Add("uid", "some-user-id")
    vals.Add("host", "example.com")
    token, err := mint.SignValues(vals, time.Now().Add(time.Hour))
    if err != nil {
       // handle error
    }
    // Tokens with key/value pairs
    uid := token.Values.Get("uid")

    // Print the generated token... perhaps you want to send a cookie?
    tokenAsString := token.String()
    fmt.Println("Generated Token:", tokenAsString)

    // If you want to get the string-encoded form of random data...
    dataString := brief.Encode(token.Data)

    // Verify the token, e.g. parsing a cookie sent back from client.
    token2, err := mint.VerifyString(tokenAsString)
    if err != nil {
        fmt.Println("Token verification failed:", err)
    } else {
        fmt.Println("Token is valid. Payload:", brief.Encode(token2.Data))
    }
}