accesstoken

README

Golang module for generating access tokens in GitHub token format

This Golang module creates an access token in the format prefix + separator + code, where code is a base62-encoded combination of random bytes and a CRC-32 checksum, similar to the format used by GitHub.

The generated token can be used for purposes other than access control. You can distinguish token types using their prefixes within your own applications.

Security properties and limitations

IsChecksumOK only reports whether a token is well-formed — that its embedded checksum matches its embedded random bytes. This is a non-cryptographic CRC-32 checksum: it detects accidental corruption (e.g. a copy/paste error or a dropped character), but it provides no tamper resistance and no authenticity guarantee. There is no secret key involved, so anyone who knows the algorithm can construct a token with a valid-looking checksum.

A true result from IsChecksumOK must not be treated as proof that:

• the token was issued by your system,
• the token is still valid, unexpired, or unrevoked, or
• the caller is authorized.

Use IsChecksumOK only as a cheap, early rejection of malformed input (e.g. to avoid an unnecessary database round trip for a clearly garbled token). Always perform the real authorization decision — a database or cache lookup that checks issuance, expiry, and revocation status — before granting access.

IsChecksumOK never panics: malformed, truncated, or otherwise invalid input returns false.

Usage

const (
    prefix         = "abc"
    randomBytesLen = 32
)

token, err := accesstoken.Generate(prefix, accesstoken.Separator, accesstoken.RandomBytesLen)
if err != nil {
    return err
}

if !accesstoken.IsChecksumOK(prefix, accesstoken.Separator, token) {
    // token is malformed; reject before any database lookup
    return
}

// token is well-formed: proceed to look it up (and check expiry/revocation) in your database

Documentation

Overview

Package accesstoken generates and validates access tokens in the format prefix+separator+code, similar to the format used by GitHub. See the package README for the security properties and limitations of checksum validation.

Index

• Constants
• Variables
• func Generate(prefix, separator string, randBytesLen int) (output string, err error)
• func IsChecksumOK(prefix, separator, token string) (ok bool)

Constants

const (
	// Separator is the default separator used to distinguish the prefix from the generated code.
	Separator = "_"

	// RandomBytesLen is the default number of random bytes used to generate the code.
	RandomBytesLen = 32
)

Variables

var ErrInvalidRandBytesLen = errors.New("accesstoken: randBytesLen must be greater than zero")

ErrInvalidRandBytesLen is returned by Generate when randBytesLen is not greater than zero.

Functions

func Generate

func Generate(prefix, separator string, randBytesLen int) (output string, err error)

Generate creates an access token in the form prefix+separator+code, where code is a base62-encoded combination of randBytesLen cryptographically random bytes and a checksum. The checksum only detects accidental corruption of the token; it is not a cryptographic signature and does not prove the token was issued by a trusted system.

prefix and separator may each be empty; only their concatenation, prefix+separator, is meaningful to Generate and IsChecksumOK — the two arguments do not need to agree on exactly where the boundary between prefix and separator falls, as long as the combined string matches between generation and validation.

func IsChecksumOK

func IsChecksumOK(prefix, separator, token string) (ok bool)

IsChecksumOK reports whether token has the given prefix and separator, whether its embedded checksum matches its embedded random bytes, and whether its base62 body is the canonical encoding of those bytes. It never panics: any malformed, truncated, extended, aliased, or otherwise invalid token yields false.

The canonical-encoding check matters because base62's bit-packing encoding is not injective in reverse: some non-canonical strings (e.g. a truncated variant of a valid token) decode to the exact same bytes as the canonical one. Requiring the body to re-encode to itself ensures each decoded payload has exactly one accepted textual representation; it does not add cryptographic authentication, only encoding uniqueness.

A true result only means the token is well-formed and was not accidentally corrupted. It is not proof of authenticity, issuance, authorization, or that the token has not been revoked or expired — callers must still perform a database/revocation lookup before trusting a token.