zerojwt

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 19, 2026 License: MIT Imports: 16 Imported by: 0

README

⚡ zerojwt — Ultra-Fast, Zero-Allocation Industrial JWT for Go

Go Reference Go Report Card Coverage Allocations

zerojwt is a pure Go, zero-dependency library for signing and verifying JSON Web Tokens (JWT / RFC 7519) in ~185 ns/op (parallel) / ~400–640 ns/op (single-core) with guaranteed 0 B/op and 0 allocs/op on critical execution paths.

Born out of PR #48 (go-gnet-kaikegm) in The $12 Server Challenge — where a single OS thread sustained 300,000 concurrent keep-alive connections and 35,577 req/s — zerojwt eliminates the reflection, encoding/json dynamic map allocations, and Garbage Collector (GC) pressure of traditional Go JWT packages while delivering complete, industrial-grade capabilities.

📑 Table of Contents

🚀 Benchmark Comparison

Tested on an Intel(R) Core(TM) i5-1135G7 @ 2.40GHz (Linux amd64, Go 1.22):

Library Operations / sec Latency Memory / op Allocs / op
zerojwt (Parallel 8 CPUs) ~5,000,000 ops/s ~200 ns/op 0 B/op 0 allocs/op
zerojwt (Single Thread Scratch) ~1,560,000 ops/s ~638 ns/op 0 B/op 0 allocs/op
zerojwt (Concurrent Pool) ~1,510,000 ops/s ~658 ns/op 0 B/op 0 allocs/op
zerojwt (SignClaims) ~2,470,000 ops/s ~404 ns/op 0 B/op 0 allocs/op
zerojwt (SignBuilder) ~2,260,000 ops/s ~441 ns/op 0 B/op 0 allocs/op
kataras/jwt ~450,000 ops/s ~2,200 ns/op ~896 B/op 14 allocs/op
golang-jwt/jwt/v5 ~380,000 ops/s ~2,600 ns/op ~1,440 B/op 26 allocs/op
lestrrat-go/jwx/v2 ~190,000 ops/s ~5,200 ns/op ~3,120 B/op 48 allocs/op

Key takeaway: Traditional JWT libraries allocate between 14 and 48 objects on the heap per token validation, triggering constant garbage collector cycles under high loads (10k+ req/s). zerojwt performs zero heap allocations, allowing web gateways and event loops to handle maximum connection density with flat, predictable latencies.

✨ Key Features

  1. Strict 0 Allocations Guarantee:

    • Both token signing and token verification operate completely without heap allocations (0 B/op, 0 allocs/op).
    • No interface{} unboxing, no map[string]any parsing, no reflection (reflect).

  2. Complete Cryptographic Algorithm Portfolio:

    • Symmetric: HS256, HS384, HS512 (HMAC with SHA-2 family).
    • Asymmetric: EdDSA (Ed25519 / RFC 8037) and ES256 (ECDSA P-256 / RFC 7518).
    • Custom ASN.1 DER to IEEE P1363 fixed-width (64-byte $r \parallel s$) conversion implemented directly on stack buffers.

  3. Strict RFC 7519 / RFC 7515 Compliance:

    • Configurable clock skew tolerance (Leeway).
    • Standard claims: exp (Expires At), nbf (Not Before), iat (Issued At), iss (Issuer), aud (Audience), sub (Subject), and jti (JWT ID).
    • Audience matching supports both single JSON strings ("aud":"service") and JSON string arrays ("aud":["svc-a","svc-b"]) in zero allocations.
    • Enforces typ: "JWT" validation if present in the header.

  4. Zero-Copy In-Place Lexer (scanner.go):

    • High-performance, streaming JSON tokenizer with precomputed 256-byte Lookup Tables (LUTs) for whitespace, delimiters, and hex conversion.
    • In-place string unescaping for standard escapes (\", \\, \/, \b, \f, \n, \r, \t) and full Unicode code points (\uXXXX), including UTF-16 surrogate pairs (\uD800..\uDBFF + \uDC00..\uDFFF).

  5. Multi-Key Credential Rotation (kid):

    • Seamless key rotation with zero allocations using the "kid" header parameter.

  6. Stack-Allocated Fluent SignBuilder:

    • Construct and sign custom payloads with arbitrary fields without allocating JSON strings or maps.

  7. FIPS / PCI-DSS Memory Sanitization:

    • Optional ZeroMemory mode actively wipes cryptographic secrets and claims from scratch buffers via memclr before returning them to the pool.
    • Verifier.Destroy() safely zeroes internal master keys and HMAC state.

  8. Zero Third-Party Dependencies:

    • Built exclusively with the Go standard library (crypto/*, encoding/base64, sync, unsafe).

🏛️ Architecture & Memory Model

zerojwt achieves zero heap allocations by replacing dynamic runtime allocations with reusable Scratch workspaces:

+-------------------------------------------------------------------------+
|                               Scratch                                   |
|                                                                         |
|  +--------------------+  +--------------------+  +-------------------+  |
|  |   hdrBuf [128]B    |  |  payloadBuf [1024]B|  |   sigBuf [64]B    |  |
|  +--------------------+  +--------------------+  +-------------------+  |
|  +--------------------+  +--------------------+  +-------------------+  |
|  |   sumBuf [64]B     |  |   derBuf [72]B     |  |  mac (hash.Hash)  |  |
|  +--------------------+  +--------------------+  +-------------------+  |
+-------------------------------------------------------------------------+
Dual Concurrency Models
  1. Multithreaded Web Applications (sync.Pool): Methods like Verifier.Verify, Verifier.VerifyLarge, Verifier.VerifyBearer, and Verifier.Sign automatically check out a *Scratch instance from an internal lock-free sync.Pool and return it upon completion.
  2. Single-Threaded Event Loops (gnet / epoll / Worker Pools): Methods like Verifier.VerifyWithScratch, Verifier.VerifyLargeWithScratch, and Verifier.SignWithScratch accept a caller-managed *Scratch directly (e.g. pinned to the event loop's worker context), eliminating even the atomic overhead of sync.Pool.

📦 Installation

Requires Go 1.21 or higher (Go 1.22+ recommended for optimal PGO):

go get github.com/KaikeGM/zerojwt

🛠️ Quick Start

Basic Signing and Verification
package main

import (
	"fmt"
	"time"

	"github.com/KaikeGM/zerojwt"
)

func main() {
	secret := []byte("secret-key-must-be-at-least-32-bytes!!")
	verifier := zerojwt.NewVerifier(secret)
	now := time.Now().Unix()

	// 1. Sign a token into a stack buffer (0 allocs/op)
	var tokBuf [512]byte
	token := verifier.SignClaims(
		tokBuf[:0],
		[]byte("user_9876"), // sub
		[]byte("kaikegm"),   // username
		now,                 // iat
		now+3600,            // exp (1 hour)
	)

	fmt.Printf("Generated JWT: %s\n", token)

	// 2. Verify token into stack-allocated Claims (0 allocs/op)
	var claims zerojwt.Claims
	if err := verifier.Verify(token, now, &claims); err != nil {
		panic(err)
	}

	fmt.Printf("Authenticated: Subject=%s, Username=%s, ExpiresAt=%d\n",
		claims.Subject(), claims.Username(), claims.ExpiresAt)
}

🔐 Cryptographic Algorithms

1. Symmetric HMAC: HS256, HS384, HS512

Symmetric validation requires the same shared secret between issuer and validator.

// HS256 (Default)
v256 := zerojwt.NewVerifier(secret)

// HS384
v384 := zerojwt.NewVerifierWithOptions(secret, zerojwt.Options{
	Algorithm: zerojwt.AlgHS384,
})

// HS512
v512 := zerojwt.NewVerifierWithOptions(secret, zerojwt.Options{
	Algorithm: zerojwt.AlgHS512,
})
2. Asymmetric: EdDSA (Ed25519 / RFC 8037)

Ed25519 provides ultra-fast asymmetric verification with 32-byte public keys and 64-byte signatures. Ideal for microservices architectures where internal services should only verify tokens without having the capability to issue them.

import "crypto/ed25519"

// Generate keypair
pubKey, privKey, _ := ed25519.GenerateKey(nil)

// Authentication Server (Issues & Signs tokens)
authVerifier := zerojwt.NewEd25519Verifier(pubKey, privKey, zerojwt.Options{
	ExpectedIssuer: "https://auth.company.com",
})
token := authVerifier.SignClaims(tokBuf[:0], []byte("usr_1"), []byte("alice"), now, now+3600)

// Microservice / API Gateway (Verify-only: privKey is nil)
gatewayVerifier := zerojwt.NewEd25519Verifier(pubKey, nil, zerojwt.Options{
	ExpectedIssuer: "https://auth.company.com",
})
var claims zerojwt.Claims
if err := gatewayVerifier.Verify(token, now, &claims); err != nil {
	log.Fatalf("Invalid token: %v", err)
}
3. Asymmetric: ES256 (ECDSA P-256 / RFC 7518)

ES256 is widely used in enterprise OAuth 2.0 / OpenID Connect, mobile clients, and WebAuthn. zerojwt implements direct IEEE P1363 ($r \parallel s$) to ASN.1 DER conversion with zero heap allocations.

import (
	"crypto/ecdsa"
	"crypto/elliptic"
	"crypto/rand"
)

// Generate P-256 keypair
privKey, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
pubKey := &privKey.PublicKey

// Verifier with ES256
vES256 := zerojwt.NewES256Verifier(pubKey, privKey, zerojwt.Options{
	Leeway: 10 * time.Second,
})

token := vES256.Sign(tokBuf[:0], []byte(`{"sub":"usr_p256","exp":1893456000}`))

📋 RFC 7519 Validation & Claims

Clock Skew Tolerance (Leeway)

In distributed systems, servers may experience slight NTP clock desynchronization. The Leeway option prevents premature token rejection:

verifier := zerojwt.NewVerifierWithOptions(secret, zerojwt.Options{
	Leeway: 5 * time.Second, // Allows tokens up to 5s before nbf or 5s after exp
})
Issuer (iss) & Audience (aud) Validation

When configured, zerojwt enforces that incoming tokens contain matching iss and aud claims:

verifier := zerojwt.NewVerifierWithOptions(secret, zerojwt.Options{
	ExpectedIssuer:   "auth.enterprise.io",
	ExpectedAudience: "payments-api",
})

zerojwt natively validates aud claims declared as either a single JSON string or a JSON array of strings:

  • Single: "aud": "payments-api"
  • Array: "aud": ["reporting-api", "payments-api", "admin-api"]

Both variations are parsed and matched in-place with 0 heap allocations.

JWT ID (jti) & Replay Prevention

The jti claim provides a unique nonce (e.g. UUID v4) to prevent replay attacks. Claims exposes claims.JTI() to check against in-memory revocation lists (such as a Bloom filter or synchronized cache):

var claims zerojwt.Claims
if err := verifier.Verify(token, now, &claims); err != nil {
	return err
}

if revocationFilter.Contains(claims.JTI()) {
	return errors.New("token has been revoked")
}
Dual Claims Structs: Claims vs ClaimsLarge
Feature Claims (Default) ClaimsLarge
Target Use Case High-density APIs, microservices Enterprise tokens, long usernames/UUIDs
Max Subject Length 64 bytes 256 bytes
Max Username Length 128 bytes 256 bytes
Max Issuer Length 64 bytes 256 bytes
Max Audience Length 64 bytes 256 bytes
Max JTI Length 36 bytes (UUID) 64 bytes
Memory Footprint Extremely compact Slightly larger fixed stack size
Verification Method v.Verify(...) v.VerifyLarge(...)

🛠️ Custom Claims & Fluent SignBuilder

Fluent SignBuilder (0 allocs/op)

Build custom JWT payloads with arbitrary attributes without allocating map[string]any or strings:

var tokBuf [1024]byte
builder := verifier.NewSigner(tokBuf[:0])

token, err := builder.
	SetSubject([]byte("usr_1001")).
	SetUsername([]byte("kaike")).
	SetIssuer([]byte("auth.company.com")).
	SetAudience([]byte("api.company.com")).
	SetJTI([]byte("9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d")).
	SetIssuedAt(now).
	SetExpiresAt(now + 7200).
	SetClaimString("role", "admin").
	SetClaimInt("tenant_id", 42).
	SetClaimBool("mfa_verified", true).
	SetClaimRawJSON("permissions", []byte(`["read:users","write:users"]`)).
	Sign()

if err != nil {
	panic(err)
}
Arbitrary Claims Inspection via VerifyCustom

If your token contains arbitrary nested structures or custom attributes, use VerifyCustom. It validates signature and temporal claims (exp, nbf, iss, aud), and yields key-value slices directly from the verified buffer with 0 allocations:

err := verifier.VerifyCustom(token, now, func(key, val []byte, isStr bool) bool {
	switch string(key) {
	case "tenant_id":
		id, _ := zerojwt.ParsePositiveInt(val)
		fmt.Printf("Tenant: %d\n", id)
	case "permissions":
		// Traverse JSON array with 0 allocations
		arrBody, ok := zerojwt.TrimJSONArray(val)
		if ok {
			for len(arrBody) > 0 {
				elem, isStr, rest, ok := zerojwt.NextArrayElement(arrBody)
				if !ok {
					break
				}
				arrBody = rest
				fmt.Printf("Permission: %s (isStr=%v)\n", elem, isStr)
			}
		}
	}
	return true // continue scanning claims
})

🔄 Zero-Downtime Key Rotation (kid)

To rotate keys without invalidating existing sessions, register multiple keys with unique IDs:

verifier := zerojwt.NewVerifierWithOptions(primarySecret, zerojwt.Options{
	Algorithm:   zerojwt.AlgHS256,
	ActiveKeyID: "key-2026-v2", // Embedded into new tokens
	Keys: []zerojwt.Key{
		{ID: "key-2025-v1", Secret: oldSecret},
		{ID: "key-2026-v2", Secret: primarySecret},
		{ID: "key-ed-v1", Ed25519Public: edPubKey},
		{ID: "key-es-v1", ECDSAPublic: ecPubKey},
	},
})

When validating, zerojwt extracts the "kid" claim from the header and uses the corresponding cryptographic key in $O(1)$ without heap allocations.

🌐 High-Speed HTTP Middlewares

1. ProtectFunc (Fastest, Zero-Allocation)

Passes a stack-allocated *Claims pointer directly to your handler, ensuring 0 B/op overhead per HTTP request:

http.HandleFunc("/api/me", verifier.ProtectFunc(func(w http.ResponseWriter, r *http.Request, claims *zerojwt.Claims) {
	w.Header().Set("Content-Type", "application/json")
	fmt.Fprintf(w, `{"sub":"%s","user":"%s"}`, claims.Subject(), claims.Username())
}))
2. Standard net/http & Chi Middleware

Integrates seamlessly with Chi, Gorilla Mux, or standard Go routers:

r := chi.NewRouter()
r.Use(verifier.Middleware)

r.Get("/api/dashboard", func(w http.ResponseWriter, r *http.Request) {
	claims, ok := zerojwt.ClaimsFromContext(r.Context())
	if !ok {
		http.Error(w, "Unauthorized", http.StatusUnauthorized)
		return
	}
	fmt.Fprintf(w, "Welcome, user ID %d!", claims.SubjectID)
})
3. Gin, Fiber & gnet Integration
Gin
func ZeroJWTGin(v *zerojwt.Verifier) gin.HandlerFunc {
	return func(c *gin.Context) {
		auth := c.GetHeader("Authorization")
		if len(auth) <= 7 {
			c.AbortWithStatus(http.StatusUnauthorized)
			return
		}
		var claims zerojwt.Claims
		if err := v.VerifyBearer([]byte(auth), time.Now().Unix(), &claims); err != nil {
			c.AbortWithStatus(http.StatusUnauthorized)
			return
		}
		c.Set("claims", &claims)
		c.Next()
	}
}
gnet (Single-Thread Event Loop)
type server struct {
	*gnet.BuiltinEventEngine
	verifier *zerojwt.Verifier
	scratch  *zerojwt.Scratch // 1 scratch per worker thread
}

func (s *server) OnTraffic(c gnet.Conn) gnet.Action {
	buf, _ := c.Next(-1)
	var claims zerojwt.Claims
	// Direct scratch verification: 0 allocations, 0 sync.Pool locks
	if err := s.verifier.VerifyWithScratch(buf, time.Now().Unix(), &claims, s.scratch); err != nil {
		c.Write([]byte("HTTP/1.1 401 Unauthorized\r\n\r\n"))
		return gnet.Close
	}
	// ...
	return gnet.None
}

🛡️ Security & Compliance (FIPS / PCI-DSS)

Memory Sanitization (ZeroMemory)

In multi-tenant or regulated financial environments (PCI-DSS, HIPAA, FIPS), residual keys and user attributes must not linger in memory buffers.

Enable ZeroMemory: true to invoke Go's runtime memclr over all scratch buffers and claims before releasing them back to the pool:

verifier := zerojwt.NewVerifierWithOptions(secret, zerojwt.Options{
	ZeroMemory: true,
})

To securely decommission a verifier and scrub master keys from RAM upon service shutdown:

defer verifier.Destroy()

⚡ Profile-Guided Optimization (PGO)

zerojwt includes a factory default.pgo optimization profile captured under rigorous load testing.

When building your service with Go 1.20+, the Go compiler automatically discovers default.pgo and optimizes register allocation, hot branch predictions, and function inlining:

# Automatically applies default.pgo
go build -o my-service main.go

To verify PGO application during build:

go build -gcflags="-m=2" 2>&1 | grep "pgo inline"

📖 API Reference

Verifier Constructors
  • NewVerifier(secret []byte) *Verifier: Creates an HS256 verifier with default buffer limits (128B header, 1024B payload).
  • NewEd25519Verifier(pub ed25519.PublicKey, priv ed25519.PrivateKey, opts Options) *Verifier: Creates an EdDSA (Ed25519) verifier.
  • NewES256Verifier(pub *ecdsa.PublicKey, priv *ecdsa.PrivateKey, opts Options) *Verifier: Creates an ES256 (ECDSA P-256) verifier.
  • NewVerifierWithOptions(secret []byte, opts Options) *Verifier: Creates a fully configured verifier.
Verification Methods
  • Verify(tok []byte, nowUnix int64, out *Claims) error: Validates token into standard Claims.
  • VerifyBearer(authHeader []byte, nowUnix int64, out *Claims) error: Extracts Bearer <token> and validates.
  • VerifyWithScratch(tok []byte, nowUnix int64, out *Claims, st *Scratch) error: Validates token using a caller-supplied Scratch.
  • VerifyLarge(tok []byte, nowUnix int64, out *ClaimsLarge) error: Validates token into large-capacity ClaimsLarge.
  • VerifyLargeWithScratch(tok []byte, nowUnix int64, out *ClaimsLarge, st *Scratch) error: Validates token into ClaimsLarge using caller-supplied Scratch.
  • VerifyCustom(tok []byte, nowUnix int64, onClaim func(key, val []byte, isStr bool) bool) error: Validates signature and temporal claims, scanning arbitrary claims with zero allocations.
Signing Methods
  • Sign(dst []byte, payloadJSON []byte) []byte: Signs raw JSON payload using default buffers.
  • SignClaims(dst, sub, username []byte, iat, exp int64) []byte: Signs standard claims directly into dst.
  • SignWithScratch(dst, payloadJSON []byte, st *Scratch) []byte: Signs payload using caller-supplied Scratch.
  • NewSigner(dst []byte) SignBuilder: Creates a fluent builder for custom claims backed by sync.Pool.
  • NewSignerWithScratch(dst []byte, st *Scratch) SignBuilder: Creates a fluent builder using caller-supplied Scratch.
Fast Lexer & Parser (scanner.go)
  • NextJSONProp(b []byte) (key, val []byte, isStr bool, rest []byte, ok bool): Extracts the next "key": value from a JSON object body in-place.
  • NextArrayElement(b []byte) (val []byte, isStr bool, rest []byte, ok bool): Extracts the next element from a JSON array body in-place.
  • TrimJSONObject(b []byte) ([]byte, bool): Strips whitespace and outer { and } braces.
  • TrimJSONArray(b []byte) ([]byte, bool): Strips whitespace and outer [ and ] brackets.
  • ParseNumeric(b []byte) (float64, bool): Parses integer, decimal, and scientific notation floats in zero allocations.
  • ParsePositiveInt(b []byte) (uint64, bool): Ultra-fast integer parser.
  • UnescapeJSONInPlace(s []byte) []byte: Decodes escape sequences and Unicode code points in-place.
  • AppendEscapedJSONString(dst, s []byte) []byte: Appends a JSON-safe quoted string.

⚠️ Sentinel Errors

All errors are pre-allocated static sentinels. Compare using errors.Is or == with zero heap allocations:

Sentinel Error Description
ErrMissingBearer The Authorization header is missing the "Bearer " prefix.
ErrInvalidToken Malformed token structure (does not have exactly 3 dot-separated Base64URL segments).
ErrInvalidHeader Header is not valid JSON, or specifies an unsupported/mismatched algorithm.
ErrInvalidSignature Cryptographic signature verification failed.
ErrExpiredToken Current time is $\ge$ exp claim (taking Leeway into account).
ErrNotValidYet Current time is $<$ nbf claim (taking Leeway into account).
ErrInvalidPayload Payload JSON is malformed, missing required claims (sub), or types mismatch.
ErrPayloadTooLarge Payload length exceeds MaxPayloadSize.
ErrInvalidIssuer The iss claim does not match ExpectedIssuer.
ErrInvalidAudience The aud claim does not match or contain ExpectedAudience.
ErrUnknownKeyID The "kid" header specifies an unrecognized key ID.

🧪 Testing, Fuzzing & Quality Assurance

zerojwt features a 100% comprehensive test and validation suite:

# 1. Run all unit tests with 100% statement coverage
go test -v -coverprofile=coverage.out ./...
go tool cover -func=coverage.out

# 2. Race detector (detects concurrency hazards)
go test -v -race ./...

# 3. Verify zero heap allocations on hot paths
go test -v -run=TestZeroAllocations ./...

# 4. Run benchmarks and memory allocation stats
go test -bench=. -benchmem ./...

# 5. Continuous native fuzz testing for adversarial inputs
go test -fuzz=FuzzVerify -fuzztime=30s

📄 License

MIT License — Copyright (c) 2026 KaikeGM. Distributed under the permissive MIT license. See LICENSE for full details.

Documentation

Overview

Package zerojwt provides an ultra-fast, zero-allocation (0 B/op, 0 allocs/op) JWT validator and signer in pure Go supporting HS256, HS384, HS512, EdDSA (Ed25519), and ES256.

Index

Examples

Constants

View Source 
const (
	// MaxHeaderSize is the default maximum decoded byte length of a JWT header in zero-alloc mode.
	MaxHeaderSize = 128
	// MaxPayloadSize is the default maximum decoded byte length of a JWT payload in zero-alloc mode.
	MaxPayloadSize = 1024
)

Variables

View Source 
var (
	// ErrMissingBearer is returned by VerifyBearer when the "Bearer " prefix is absent.
	ErrMissingBearer = errors.New("zerojwt: missing Bearer prefix")

	// ErrInvalidToken is returned when the token does not have 3 valid Base64URL segments.
	ErrInvalidToken = errors.New("zerojwt: malformed token structure")

	// ErrInvalidHeader is returned when the JWT header is not valid JSON or specifies an unsupported algorithm.
	ErrInvalidHeader = errors.New("zerojwt: invalid header or unsupported algorithm")

	// ErrInvalidSignature is returned when the cryptographic signature verification fails.
	ErrInvalidSignature = errors.New("zerojwt: signature verification failed")

	// ErrExpiredToken is returned when the current timestamp is >= the "exp" claim.
	ErrExpiredToken = errors.New("zerojwt: token is expired")

	// ErrNotValidYet is returned when the current timestamp is < the "nbf" claim.
	ErrNotValidYet = errors.New("zerojwt: token is not valid yet (nbf)")

	// ErrInvalidPayload is returned when the payload JSON is malformed or required claims are invalid.
	ErrInvalidPayload = errors.New("zerojwt: invalid token payload claims")

	// ErrPayloadTooLarge is returned when the decoded payload exceeds the configured MaxPayloadSize.
	ErrPayloadTooLarge = errors.New("zerojwt: payload exceeds maximum zero-alloc buffer size")

	// ErrInvalidIssuer is returned when the "iss" claim is missing or does not match ExpectedIssuer.
	ErrInvalidIssuer = errors.New("zerojwt: invalid or mismatched token issuer (iss)")

	// ErrInvalidAudience is returned when the "aud" claim is missing or does not match ExpectedAudience.
	ErrInvalidAudience = errors.New("zerojwt: invalid or mismatched token audience (aud)")

	// ErrUnknownKeyID is returned when the header specifies a "kid" that is not registered in the Verifier.
	ErrUnknownKeyID = errors.New("zerojwt: unknown key ID (kid) in header")
)

Pre-allocated static errors returned by zerojwt. Comparing against these errors with errors.Is or == performs zero allocations.

Functions

func AppendEscapedJSONString 

func AppendEscapedJSONString(dst, s []byte) []byte

AppendEscapedJSONString appends a JSON-escaped string (with surrounding quotes) to dst using unrolled 8-byte vectorized span checks and bulk memory copies.

func NextArrayElement 

func NextArrayElement(b []byte) (val []byte, isStr bool, rest []byte, ok bool)

NextArrayElement extracts the next element from a JSON array body (inside '[' and ']'). It operates strictly in-place on b with zero heap allocations (0 B/op, 0 allocs/op).

func NextJSONProp 

func NextJSONProp(b []byte) (key, val []byte, isStr bool, rest []byte, ok bool)

NextJSONProp extracts the next top-level "key": value pair from a JSON object body (inside '{' and '}'). It operates strictly in-place on b with zero heap allocations (0 B/op, 0 allocs/op). If a string value contains escape sequences (e.g., \" or \u00e7), it unescapes the slice in-place.

func ParseNumeric 

func ParseNumeric(b []byte) (float64, bool)

ParseNumeric parses a JSON number (integer or floating point, e.g. Unix timestamps) without allocations.

func ParsePositiveInt 

func ParsePositiveInt(val []byte) (int64, bool)

ParsePositiveInt parses a strictly positive 64-bit integer from a byte slice of digits.

func TrimJSONArray 

func TrimJSONArray(b []byte) ([]byte, bool)

TrimJSONArray strips surrounding whitespace and outer '[' and ']' brackets from a JSON array.

func TrimJSONObject 

func TrimJSONObject(b []byte) ([]byte, bool)

TrimJSONObject strips surrounding whitespace and outer '{' and '}' braces from a JSON object.

func UnescapeJSONInPlace 

func UnescapeJSONInPlace(s []byte) []byte

UnescapeJSONInPlace unescapes JSON string escape sequences in-place without allocating memory.

Types

type Algorithm 

type Algorithm string

Algorithm represents a supported JWS cryptographic algorithm (RFC 7518 / RFC 8037). 

const (
	AlgHS256 Algorithm = "HS256"
	AlgHS384 Algorithm = "HS384"
	AlgHS512 Algorithm = "HS512"
	AlgEdDSA Algorithm = "EdDSA"
	AlgES256 Algorithm = "ES256"
)

type Claims 

type Claims struct {
	SubjectID   int64 // Parsed positive integer ID when "sub" is numeric (e.g. "123" -> 123)
	IssuedAt    int64 // "iat" claim (Unix seconds)
	ExpiresAt   int64 // "exp" claim (Unix seconds)
	NotBefore   int64 // "nbf" claim (Unix seconds)
	HasSub      bool  // True if "sub" claim was present
	HasUsername bool  // True if "username" claim was present
	HasIss      bool  // True if "iss" claim was present
	HasAud      bool  // True if "aud" claim was present
	HasJti      bool  // True if "jti" claim was present
	HasExp      bool  // True if "exp" claim was present
	HasNbf      bool  // True if "nbf" claim was present
	// contains filtered or unexported fields
}

Claims holds standard JWT claims on the caller's stack without heap allocations. Its internal fixed buffers own the copied claim bytes, ensuring 100% safety against data races even after the internal Scratch buffer returns to the pool.

func ClaimsFromContext 

func ClaimsFromContext(ctx context.Context) (*Claims, bool)

ClaimsFromContext retrieves the verified *Claims from a request context populated by Verifier.Middleware.

func (*Claims) Audience 

func (c *Claims) Audience() []byte

Audience returns the primary "aud" claim as a byte slice backed by Claims' inline buffer.

func (*Claims) Clear 

func (c *Claims) Clear()

Clear resets all fields and explicitly zeroes all internal claim buffers with 0x00 (memclr).

func (*Claims) Issuer 

func (c *Claims) Issuer() []byte

Issuer returns the "iss" claim as a byte slice backed by Claims' inline buffer.

func (*Claims) JTI 

func (c *Claims) JTI() []byte

JTI returns the "jti" (JWT ID) claim as a byte slice backed by Claims' inline buffer.

func (*Claims) Reset 

func (c *Claims) Reset()

Reset resets length markers and flags for fast reuse without zeroing the underlying byte arrays.

func (*Claims) Subject 

func (c *Claims) Subject() []byte

Subject returns the "sub" claim as a byte slice backed by Claims' inline buffer.

func (*Claims) Username 

func (c *Claims) Username() []byte

Username returns the "username" claim as a byte slice backed by Claims' inline buffer.

type ClaimsLarge 

type ClaimsLarge struct {
	SubjectID   int64
	IssuedAt    int64
	ExpiresAt   int64
	NotBefore   int64
	HasSub      bool
	HasUsername bool
	HasIss      bool
	HasAud      bool
	HasJti      bool
	HasExp      bool
	HasNbf      bool
	// contains filtered or unexported fields
}

ClaimsLarge provides expanded 256-byte inline buffers for deployments where Subject, Username, Issuer, Audience, or JTI identifiers exceed 64/128 bytes.

func (*ClaimsLarge) Audience 

func (c *ClaimsLarge) Audience() []byte

func (*ClaimsLarge) Clear 

func (c *ClaimsLarge) Clear()

func (*ClaimsLarge) Issuer 

func (c *ClaimsLarge) Issuer() []byte

func (*ClaimsLarge) JTI 

func (c *ClaimsLarge) JTI() []byte

func (*ClaimsLarge) Reset 

func (c *ClaimsLarge) Reset()

func (*ClaimsLarge) Subject 

func (c *ClaimsLarge) Subject() []byte

func (*ClaimsLarge) Username 

func (c *ClaimsLarge) Username() []byte

type Key 

type Key struct {
	ID            string
	Secret        []byte
	Ed25519Public ed25519.PublicKey
	ECDSAPublic   *ecdsa.PublicKey
}

Key represents a named cryptographic key for "kid" (Key ID) rotation in JWT headers.

type Options 

type Options struct {
	// Algorithm selects the JWS algorithm (default: AlgHS256).
	Algorithm Algorithm
	// MaxHeaderSize sets the maximum decoded byte length of a JWT header (default: 128).
	MaxHeaderSize int
	// MaxPayloadSize sets the maximum decoded byte length of a JWT payload (default: 1024).
	MaxPayloadSize int
	// Leeway defines the clock skew tolerance for "exp" and "nbf" validation.
	Leeway time.Duration
	// ExpectedIssuer enforces that the token's "iss" claim matches this value.
	ExpectedIssuer string
	// ExpectedAudience enforces that the token's "aud" claim (string or array) contains this value.
	ExpectedAudience string
	// Keys registers named keys for automatic "kid" header lookup during verification.
	Keys []Key
	// ActiveKeyID embeds `"kid":"<ActiveKeyID>"` in the JWT header when signing tokens.
	ActiveKeyID string
	// Ed25519PublicKey is the 32-byte public key used when Algorithm is AlgEdDSA.
	Ed25519PublicKey ed25519.PublicKey
	// Ed25519PrivateKey is the 64-byte private key used for signing when Algorithm is AlgEdDSA.
	Ed25519PrivateKey ed25519.PrivateKey
	// ECDSAPublicKey is the P-256 public key used when Algorithm is AlgES256.
	ECDSAPublicKey *ecdsa.PublicKey
	// ECDSAPrivateKey is the P-256 private key used for signing when Algorithm is AlgES256.
	ECDSAPrivateKey *ecdsa.PrivateKey
	// ZeroMemory zeroes out sensitive scratch buffers with 0x00 (memclr) after each operation.
	ZeroMemory bool
}

Options configures algorithm, buffer dimensions, RFC 7519 validation rules, key rotation ("kid"), and FIPS/PCI-DSS memory sanitization for a Verifier.

type Scratch 

type Scratch struct {
	// contains filtered or unexported fields
}

Scratch holds reusable buffers and pre-initialized HMAC hashers. In multi-goroutine servers, Verifier manages a sync.Pool of Scratch instances automatically. In single-threaded event loops (such as gnet with LockOSThread), callers can hold a single Scratch instance and call VerifyWithScratch to bypass even sync.Pool overhead.

func (*Scratch) Clear 

func (s *Scratch) Clear()

Clear zeroes out all internal working buffers in Scratch using runtime memclr.

type SignBuilder 

type SignBuilder struct {
	// contains filtered or unexported fields
}

SignBuilder is a stack-allocated, zero-allocation fluent builder for constructing and signing JWT tokens with arbitrary custom claims.

func (*SignBuilder) SetAudience 

func (b *SignBuilder) SetAudience(aud []byte) *SignBuilder

SetAudience appends the standard "aud" claim.

func (*SignBuilder) SetClaimBool 

func (b *SignBuilder) SetClaimBool(key string, val bool) *SignBuilder

SetClaimBool appends a custom boolean claim.

func (*SignBuilder) SetClaimBytes 

func (b *SignBuilder) SetClaimBytes(key string, val []byte) *SignBuilder

SetClaimBytes appends a custom string claim from a byte slice with JSON escaping.

func (*SignBuilder) SetClaimInt 

func (b *SignBuilder) SetClaimInt(key string, val int64) *SignBuilder

SetClaimInt appends a custom 64-bit integer claim.

func (*SignBuilder) SetClaimRawJSON 

func (b *SignBuilder) SetClaimRawJSON(key string, rawJSON []byte) *SignBuilder

SetClaimRawJSON appends a pre-formatted JSON value (such as an array `["admin","editor"]` or object).

func (*SignBuilder) SetClaimString 

func (b *SignBuilder) SetClaimString(key, val string) *SignBuilder

SetClaimString appends a custom string claim with JSON escaping.

func (*SignBuilder) SetExpiresAt 

func (b *SignBuilder) SetExpiresAt(exp int64) *SignBuilder

SetExpiresAt appends the standard "exp" claim (Unix seconds).

func (*SignBuilder) SetIssuedAt 

func (b *SignBuilder) SetIssuedAt(iat int64) *SignBuilder

SetIssuedAt appends the standard "iat" claim (Unix seconds).

func (*SignBuilder) SetIssuer 

func (b *SignBuilder) SetIssuer(iss []byte) *SignBuilder

SetIssuer appends the standard "iss" claim.

func (*SignBuilder) SetJTI 

func (b *SignBuilder) SetJTI(jti []byte) *SignBuilder

SetJTI appends the standard "jti" (JWT ID) claim.

func (*SignBuilder) SetNotBefore 

func (b *SignBuilder) SetNotBefore(nbf int64) *SignBuilder

SetNotBefore appends the standard "nbf" claim (Unix seconds).

func (*SignBuilder) SetSubject 

func (b *SignBuilder) SetSubject(sub []byte) *SignBuilder

SetSubject appends the standard "sub" claim.

func (*SignBuilder) SetUsername 

func (b *SignBuilder) SetUsername(username []byte) *SignBuilder

SetUsername appends the "username" claim.

func (*SignBuilder) Sign 

func (b *SignBuilder) Sign() ([]byte, error)

Sign finalizes the JSON payload, signs the token into dst, and returns the resulting slice. If the SignBuilder was created via NewSigner, the internal Scratch is returned to the pool.

type Verifier 

type Verifier struct {
	// contains filtered or unexported fields
}

Verifier validates and signs JWT tokens with zero heap allocations (0 B/op, 0 allocs/op). A Verifier is 100% safe for concurrent use by multiple goroutines.

func NewES256Verifier 

func NewES256Verifier(pub *ecdsa.PublicKey, priv *ecdsa.PrivateKey, opts Options) *Verifier

NewES256Verifier creates a new concurrent-safe ECDSA P-256 (ES256) Verifier. For verification-only nodes, priv can be nil.

func NewEd25519Verifier 

func NewEd25519Verifier(pub ed25519.PublicKey, priv ed25519.PrivateKey, opts Options) *Verifier

NewEd25519Verifier creates a new concurrent-safe EdDSA (Ed25519) Verifier. For verification-only nodes, priv can be nil.

Example

ExampleNewEd25519Verifier demonstrates an asymmetric microservices architecture where the authentication authority signs with an Ed25519 private key, and consuming microservices verify tokens using only the 32-byte public key (privKey = nil). 

package main

import (
	"crypto/ed25519"
	"fmt"

	"github.com/KaikeGM/zerojwt"
)

func main() {
	// In production, keys are loaded from secure config/vault.
	// We generate an Ed25519 keypair for demonstration:
	pubKey, privKey, err := ed25519.GenerateKey(nil)
	if err != nil {
		fmt.Printf("Key generation error: %v\n", err)
		return
	}

	now := int64(1700000000)

	// 1. Authentication Server: initialized with both pubKey and privKey to sign tokens.
	authServer := zerojwt.NewEd25519Verifier(pubKey, privKey, zerojwt.Options{
		ExpectedIssuer: "auth.internal",
	})

	var tokBuf [512]byte
	token := authServer.SignClaims(tokBuf[:0], []byte("srv_99"), []byte("payment-worker"), now, now+1800)

	// 2. Client Microservice: initialized with public key ONLY (privKey is nil).
	// This ensures the microservice can verify tokens, but cannot forge or issue them.
	microserviceVerifier := zerojwt.NewEd25519Verifier(pubKey, nil, zerojwt.Options{
		ExpectedIssuer: "auth.internal",
	})

	var claims zerojwt.Claims
	if err := microserviceVerifier.Verify(token, now, &claims); err != nil {
		fmt.Printf("Microservice verification failed: %v\n", err)
		return
	}

	fmt.Printf("Microservice verified token for %s (issuer valid: %t)\n", claims.Username(), claims.HasIss)

}

Output:
Microservice verified token for payment-worker (issuer valid: true)

func NewVerifier 

func NewVerifier(secret []byte) *Verifier

NewVerifier creates a new concurrent-safe HS256 Verifier for the given secret key using the default buffer limits (128B header, 1024B payload).

func NewVerifierWithOptions 

func NewVerifierWithOptions(secret []byte, opts Options) *Verifier

NewVerifierWithOptions creates a new concurrent-safe Verifier with custom algorithm, buffer dimensions, clock skew leeway, issuer/audience rules, and key rotation.

func (*Verifier) Destroy 

func (v *Verifier) Destroy()

Destroy zeroes out all cryptographic secret keys stored inside the Verifier.

func (*Verifier) Middleware 

func (v *Verifier) Middleware(next http.Handler) http.Handler

Middleware provides a standard net/http and chi compatible middleware that validates the Authorization: Bearer <token> header and attaches *Claims to the request's context.Context.

func (*Verifier) NewScratch 

func (v *Verifier) NewScratch() *Scratch

NewScratch allocates a new Scratch state bound to this Verifier's keys and buffer sizes. Useful for single-threaded event-loop servers (e.g. gnet) using VerifyWithScratch.

func (*Verifier) NewSigner 

func (v *Verifier) NewSigner(dst []byte) SignBuilder

NewSigner creates a fluent SignBuilder backed by the Verifier's Scratch pool. Calling Sign() automatically releases the internal Scratch back to the pool.

Example

ExampleVerifier_NewSigner demonstrates using the fluent SignBuilder to compose and sign a JWT with custom claims entirely on the stack with 0 heap allocations. 

package main

import (
	"fmt"

	"github.com/KaikeGM/zerojwt"
)

func main() {
	secret := []byte("super-secret-key-32-bytes-long!!")
	verifier := zerojwt.NewVerifier(secret)
	now := int64(1700000000)

	var tokBuf [512]byte
	b := verifier.NewSigner(tokBuf[:0])
	b.SetSubject([]byte("user_456")).
		SetUsername([]byte("bob")).
		SetIssuer([]byte("auth.service")).
		SetAudience([]byte("api.service")).
		SetClaimString("role", "admin").
		SetClaimInt("tenant_id", 42).
		SetClaimBool("mfa", true).
		SetExpiresAt(now + 3600)

	token, err := b.Sign()
	if err != nil {
		fmt.Printf("Sign error: %v\n", err)
		return
	}

	var claims zerojwt.Claims
	if err := verifier.Verify(token, now, &claims); err != nil {
		fmt.Printf("Verify error: %v\n", err)
		return
	}

	fmt.Printf("Subject: %s\n", claims.Subject())
	fmt.Printf("Username: %s\n", claims.Username())
	fmt.Printf("HasExp: %t\n", claims.HasExp)

}

Output:
Subject: user_456
Username: bob
HasExp: true

func (*Verifier) NewSignerWithScratch 

func (v *Verifier) NewSignerWithScratch(dst []byte, st *Scratch) SignBuilder

NewSignerWithScratch creates a fluent SignBuilder using a caller-supplied Scratch (ideal for single-threaded event loops like gnet).

func (*Verifier) ProtectFunc 

func (v *Verifier) ProtectFunc(next func(w http.ResponseWriter, r *http.Request, claims *Claims)) http.HandlerFunc

ProtectFunc wraps a handler that receives stack-allocated *Claims directly, achieving 0 B/op and 0 allocs/op per authenticated HTTP request.

Example

ExampleVerifier_ProtectFunc demonstrates wrapping an HTTP handler with ultra-low latency and 0 heap allocations per authenticated request. 

package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"
	"time"

	"github.com/KaikeGM/zerojwt"
)

func main() {
	secret := []byte("super-secret-key-32-bytes-long!!")
	verifier := zerojwt.NewVerifier(secret)
	now := time.Now().Unix()

	// Create an authenticated HTTP handler receiving stack-allocated *Claims
	handler := verifier.ProtectFunc(func(w http.ResponseWriter, r *http.Request, claims *zerojwt.Claims) {
		fmt.Fprintf(w, "Hello, %s!", claims.Username())
	})

	// Sign a test token
	var tokBuf [512]byte
	token := verifier.SignClaims(tokBuf[:0], []byte("u1"), []byte("charlie"), now, now+3600)

	// Simulate an HTTP request with the Bearer token
	req := httptest.NewRequest("GET", "/profile", nil)
	req.Header.Set("Authorization", "Bearer "+string(token))
	rec := httptest.NewRecorder()

	handler.ServeHTTP(rec, req)

	fmt.Printf("Status: %d, Body: %s\n", rec.Code, rec.Body.String())

}

Output:
Status: 200, Body: Hello, charlie!

func (*Verifier) Sign 

func (v *Verifier) Sign(dst []byte, payloadJSON []byte) []byte

Sign signs a raw JSON payload with the Verifier's configured algorithm (HS256, HS384, HS512, EdDSA, ES256) and appends the complete JWT token ("header.payload.signature") to dst with zero heap allocations (when dst has sufficient capacity).

func (*Verifier) SignClaims 

func (v *Verifier) SignClaims(dst []byte, sub, username []byte, iat, exp int64) []byte

SignClaims formats a standard JSON payload `{"sub":"...","username":"...","iat":...,"exp":...}` into Scratch and appends the signed JWT token to dst with zero heap allocations.

func (*Verifier) SignHS256 

func (v *Verifier) SignHS256(dst []byte, payloadJSON []byte) []byte

SignHS256 signs a raw JSON payload and appends the complete JWT token ("header.payload.signature") to dst with zero heap allocations (when dst has sufficient capacity).

func (*Verifier) SignHS256WithScratch 

func (v *Verifier) SignHS256WithScratch(dst []byte, payloadJSON []byte, st *Scratch) []byte

SignHS256WithScratch signs a raw JSON payload using a caller-supplied Scratch state.

func (*Verifier) SignWithScratch 

func (v *Verifier) SignWithScratch(dst []byte, payloadJSON []byte, st *Scratch) []byte

SignWithScratch signs a raw JSON payload using a caller-supplied Scratch state.

func (*Verifier) Verify 

func (v *Verifier) Verify(tok []byte, nowUnix int64, out *Claims) error

Verify validates the token signature, checks temporal ("exp", "nbf") and structural ("iss", "aud") claims against nowUnix, and populates out with the parsed claims. Safe for concurrent use across goroutines; performs 0 heap allocations (0 B/op, 0 allocs/op).

Example

ExampleVerifier_Verify demonstrates token verification with zero heap allocations, extracting standard claims, and checking sentinel errors using errors.Is. 

package main

import (
	"errors"
	"fmt"

	"github.com/KaikeGM/zerojwt"
)

func main() {
	secret := []byte("super-secret-key-32-bytes-long!!")
	verifier := zerojwt.NewVerifier(secret)
	now := int64(1700000000)

	// Issue a valid token into a stack-allocated buffer (0 allocs/op)
	var tokBuf [512]byte
	token := verifier.SignClaims(tokBuf[:0], []byte("user_123"), []byte("alice"), now, now+3600)

	// Verify token into stack-allocated Claims
	var claims zerojwt.Claims
	if err := verifier.Verify(token, now, &claims); err != nil {
		switch {
		case errors.Is(err, zerojwt.ErrExpiredToken):
			fmt.Println("Token is expired")
		case errors.Is(err, zerojwt.ErrInvalidSignature):
			fmt.Println("Invalid signature")
		default:
			fmt.Printf("Validation error: %v\n", err)
		}
		return
	}

	fmt.Printf("Authenticated: %s (%s)\n", claims.Username(), claims.Subject())

	// Verifying an expired token triggers ErrExpiredToken
	err := verifier.Verify(token, now+7200, &claims)
	if errors.Is(err, zerojwt.ErrExpiredToken) {
		fmt.Println("Detected expired token successfully")
	}

}

Output:
Authenticated: alice (user_123)
Detected expired token successfully

func (*Verifier) VerifyBearer 

func (v *Verifier) VerifyBearer(authHeader []byte, nowUnix int64, out *Claims) error

VerifyBearer strips the "Bearer " prefix from an HTTP Authorization header and verifies the token with zero heap allocations.

func (*Verifier) VerifyCustom 

func (v *Verifier) VerifyCustom(tok []byte, nowUnix int64, onClaim func(key, val []byte, isStr bool) bool) error

VerifyCustom validates the token signature, checks "exp", "nbf", "iss", and "aud" against nowUnix, and invokes onClaim(key, val, isString) for every top-level JSON claim in the payload. Performs 0 heap allocations. Note: key and val slices are valid only during the onClaim callback.

Example

ExampleVerifier_VerifyCustom demonstrates inspecting arbitrary custom JSON attributes and claims directly from the verified payload buffer in 0 allocations. 

package main

import (
	"fmt"

	"github.com/KaikeGM/zerojwt"
)

func main() {
	secret := []byte("super-secret-key-32-bytes-long!!")
	verifier := zerojwt.NewVerifier(secret)
	now := int64(1700000000)

	var tokBuf [512]byte
	b := verifier.NewSigner(tokBuf[:0])
	b.SetSubject([]byte("user_789")).
		SetClaimString("department", "engineering").
		SetClaimInt("clearance_level", 5).
		SetExpiresAt(now + 3600)

	token, _ := b.Sign()

	var dept string
	var clearance int64

	// Verify and extract arbitrary claims in a single pass with 0 heap allocations
	err := verifier.VerifyCustom(token, now, func(key, val []byte, isStr bool) bool {
		switch string(key) {
		case "department":
			dept = string(val)
		case "clearance_level":
			clearance, _ = zerojwt.ParsePositiveInt(val)
		}
		return true // continue scanning
	})

	if err != nil {
		fmt.Printf("VerifyCustom error: %v\n", err)
		return
	}

	fmt.Printf("Department: %s, Clearance Level: %d\n", dept, clearance)

}

Output:
Department: engineering, Clearance Level: 5

func (*Verifier) VerifyLarge 

func (v *Verifier) VerifyLarge(tok []byte, nowUnix int64, out *ClaimsLarge) error

VerifyLarge validates the token and populates a ClaimsLarge struct (256B buffers per claim).

func (*Verifier) VerifyLargeWithScratch 

func (v *Verifier) VerifyLargeWithScratch(tok []byte, nowUnix int64, out *ClaimsLarge, st *Scratch) error

VerifyLargeWithScratch validates the token into ClaimsLarge using a caller-supplied Scratch.

func (*Verifier) VerifyWithScratch 

func (v *Verifier) VerifyWithScratch(tok []byte, nowUnix int64, out *Claims, st *Scratch) error

VerifyWithScratch performs the same verification as Verify using a caller-supplied Scratch, avoiding sync.Pool.Get/Put in single-threaded event loops (such as gnet with LockOSThread).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.