internal

Documentation

Index

• Constants
• func ClearHMACCaches()
• func DecodeHeaderAlg(headerSegment string) string
• func DecodeSegment(segment string, dest any) error
• func GenerateTokenID() (string, error)
• func IsWeakKey(key []byte) bool
• func ParseTokenID(tokenString string) (string, error)
• func ReleaseCore(c *Core)
• func SignToken(alg string, claims any, method Method, key any) (string, error)
• func ZeroBytes(data []byte)
• type Core
  • func ParseUnverified(tokenString string, claims any) (*Core, map[string]any, error)
  • func ParseWithClaims(tokenString string, claims any, keyFunc func(*Core) (any, error)) (*Core, error)
• type Manager
  • func NewManagerWithClock(s storeOps, nowFunc func() time.Time) *Manager
  • func (m *Manager) BlacklistTokenString(tokenString string) error
  • func (m *Manager) Close() error
  • func (m *Manager) IsBlacklisted(tokenID string) (bool, error)
• type Method
  • func GetInternalSigningMethod(alg string) (Method, error)
• type Store
  • func NewMemoryStore(maxSize int, cleanupInterval time.Duration, enableAutoCleanup bool, ...) Store

Constants

const (
	// TokenIDLength is the length of the random portion of a token ID in bytes.
	TokenIDLength = 16
	// TokenIDPrefix is the prefix added to all generated token IDs.
	TokenIDPrefix = "tok_"
)

const DefaultBlacklistTTL = 7 * 24 * time.Hour

DefaultBlacklistTTL is the default time-to-live for blacklisted tokens when the token does not have an expiration time.

const MaxBlacklistTTL = 30 * 24 * time.Hour

MaxBlacklistTTL caps the maximum blacklist entry TTL to prevent untrusted exp values from crafted tokens causing DoS.

Functions

func ClearHMACCaches

func ClearHMACCaches()

ClearHMACCaches drains all HMAC hasher pools, allowing GC to reclaim hasher objects that may retain secret key material in their internal state.

func DecodeHeaderAlg

func DecodeHeaderAlg(headerSegment string) string

DecodeHeaderAlg extracts the "alg" field from a base64url-encoded JWT header without fully decoding the header into a map. Returns empty string if alg is not found or if the header is invalid. This avoids map[string]any allocation and interface boxing for the common case where only the algorithm is needed.

func DecodeSegment

func DecodeSegment(segment string, dest any) error

func GenerateTokenID

func GenerateTokenID() (string, error)

GenerateTokenID generates a unique token ID using cryptographic random bytes. The ID has the format "tok_" followed by 32 hexadecimal characters. Uses stack-allocated arrays instead of pooled buffers because the fixed result size (36 bytes) makes pool Get/Put overhead (~60ns) more expensive than a single string() copy.

func IsWeakKey

func IsWeakKey(key []byte) bool

func ParseTokenID

func ParseTokenID(tokenString string) (string, error)

ParseTokenID extracts the token ID (jti) from a JWT without verifying the signature. Returns empty string if the token has no jti claim.

func ReleaseCore

func ReleaseCore(c *Core)

ReleaseCore returns a Core struct to the pool after clearing its fields.

func SignToken

func SignToken(alg string, claims any, method Method, key any) (string, error)

SignToken creates a signed JWT token string directly without allocating a Core struct or header map. Uses precomputed headers for all built-in algorithms. Encodes claims with a pooled JSON buffer and signs directly into the output buffer to minimize allocations.

func ZeroBytes

func ZeroBytes(data []byte)

Types

type Core

type Core struct {
	Header    map[string]any `json:"header"`
	Claims    any            `json:"claims"`
	Signature string         `json:"-"`
	Method    Method
	Valid     bool
	Raw       string
	// Alg caches the algorithm extracted during fast-path parsing so keyFunc
	// can read it without storing the string as an interface in Header (which
	// causes one heap allocation per parse for the string→any boxing).
	// Empty when the slow path (full header decode) was used.
	Alg string
}

func ParseUnverified

func ParseUnverified(tokenString string, claims any) (*Core, map[string]any, error)

func ParseWithClaims

func ParseWithClaims(tokenString string, claims any, keyFunc func(*Core) (any, error)) (*Core, error)

type Manager

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

Manager handles token blacklist operations.

func NewManagerWithClock

func NewManagerWithClock(s storeOps, nowFunc func() time.Time) *Manager

NewManagerWithClock creates a new Manager with the given store and clock function. If nowFunc is nil, time.Now is used.

func (*Manager) BlacklistTokenString

func (m *Manager) BlacklistTokenString(tokenString string) error

func (*Manager) Close

func (m *Manager) Close() error

func (*Manager) IsBlacklisted

func (m *Manager) IsBlacklisted(tokenID string) (bool, error)

type Method

type Method interface {
	// Alg returns the algorithm identifier (e.g., "HS256", "RS256").
	Alg() string

	// Sign creates a signature for the given signing string.
	Sign(signingString string, key any) (string, error)

	// SignTo writes the base64-encoded signature to dst and returns bytes written.
	// Avoids intermediate string allocation by encoding directly into the caller's buffer.
	SignTo(dst []byte, signingString string, key any) (int, error)

	// Verify checks if the signature is valid for the given signing string.
	Verify(signingString string, signature string, key any) error

	// Hash returns the hash function used by this method.
	Hash() crypto.Hash
}

Method defines the interface for JWT signing algorithms.

func GetInternalSigningMethod

func GetInternalSigningMethod(alg string) (Method, error)

GetInternalSigningMethod retrieves a signing method by algorithm name. All built-in methods are registered in init(), so this simply checks the registry.

type Store

type Store interface {
	Add(tokenID string, expiresAt time.Time) error
	Contains(tokenID string) (bool, error)
	Cleanup() (int, error)
	Close() error
}

func NewMemoryStore

func NewMemoryStore(maxSize int, cleanupInterval time.Duration, enableAutoCleanup bool, nowFunc func() time.Time) Store