jwt

Documentation

Overview

Package jwt provides JWT creation, signing, decoding, and validation helpers for the security module.

It supports multiple signing strategies, including HMAC, RSA, RSA-PSS, and Ed25519, and lets applications attach custom validation callbacks after the token signature has been verified.

Main entry points:

• New to build a Service from explicit options
• NewConfiguredService to build a Service from viper-backed configuration
• Encode to create a signed token from claims
• Decode to validate a token and unmarshal claims into a destination value

The package is transport-agnostic and can be used directly by HTTP handlers, gRPC services, or higher-level authentication middleware.

Index

• Constants
• Variables
• func SetJWTAsymmetricKeys(priv, pub, alg string) error
• type ConfigServiceInput
• type Ed25519ServiceInput
• type HMACServiceInput
• type Header
• type Option
  • func WithEd25519(privateKey ed25519.PrivateKey, publicKey ed25519.PublicKey) Option
  • func WithHMACSHA256(secret string) Option
  • func WithRSAPSSSHA256(privateKey *rsa.PrivateKey, publicKey *rsa.PublicKey) Option
  • func WithRSASHA256(privateKey *rsa.PrivateKey, publicKey *rsa.PublicKey) Option
  • func WithStrategy(strategy Strategy) Option
  • func WithValidator(validator Validator) Option
• type RSAServiceInput
• type Service
  • func New(options ...Option) (*Service, error)
  • func NewConfiguredService(input ConfigServiceInput) (*Service, error)
  • func NewEd25519Service(input Ed25519ServiceInput) (*Service, error)
  • func NewHMACService(input HMACServiceInput) (*Service, error)
  • func NewRSAPSSService(input RSAServiceInput) (*Service, error)
  • func NewRSAService(input RSAServiceInput) (*Service, error)
  • func (service *Service) Create(claims any) (string, error)
  • func (service *Service) Decode(ctx context.Context, token string, destination any, validators ...Validator) (Token, error)
  • func (service *Service) Read(token string, destination any) error
  • func (service *Service) ValidateSignature(token string) error
• type Strategy
  • func NewEd25519(privateKey ed25519.PrivateKey, publicKey ed25519.PublicKey) Strategy
  • func NewHMACSHA256(secret string) Strategy
  • func NewRSAPSSSHA256(privateKey *rsa.PrivateKey, publicKey *rsa.PublicKey) Strategy
  • func NewRSASHA256(privateKey *rsa.PrivateKey, publicKey *rsa.PublicKey) Strategy
• type Token
• type Validator

Constants

const (
	DefaultAlgorithmKey       = "jwt.algorithm"
	DefaultHMACSecretKey      = "jwt.hmac.secret"
	DefaultRSAPrivateKeyKey   = "jwt.rsa.private_key"
	DefaultRSAPublicKeyKey    = "jwt.rsa.public_key"
	DefaultEdDSAPrivateKeyKey = "jwt.eddsa.private_key"
	DefaultEdDSAPublicKeyKey  = "jwt.eddsa.public_key"
)

Variables

var (
	ErrNilStrategy            = errors.New("jwt: signing strategy is required")
	ErrMissingSecret          = errors.New("jwt: secret is required")
	ErrMissingPrivateKey      = errors.New("jwt: private key is required")
	ErrMissingPublicKey       = errors.New("jwt: public key is required")
	ErrMissingEdDSAPrivateKey = errors.New("jwt: ed25519 private key is required")
	ErrMissingEdDSAPublicKey  = errors.New("jwt: ed25519 public key is required")
	ErrInvalidToken           = errors.New("jwt: invalid token format")
	ErrInvalidSignature       = errors.New("jwt: invalid token signature")
	ErrUnexpectedAlg          = errors.New("jwt: unexpected algorithm")
	ErrNilDestination         = errors.New("jwt: destination is required")
	ErrNilValidator           = errors.New("jwt: validator cannot be nil")
	ErrMissingValidation      = errors.New("jwt: validation callback is required")
	ErrUnsupportedAlg         = errors.New("jwt: unsupported algorithm")
)

Functions

func SetJWTAsymmetricKeys

func SetJWTAsymmetricKeys(priv, pub, alg string) error

SetJWTAsymmetricKeys stores the configured asymmetric key pair in viper using the standard JWT config keys for the selected algorithm. Existing values are overwritten with Set, while previously unset values are registered with SetDefault so package defaults remain discoverable. Supported algorithms are "rsa" and "eddsa", matched case-insensitively.

Types

type ConfigServiceInput

type ConfigServiceInput struct {
	Algorithm          string
	AlgorithmKey       string
	HMACSecretKey      string
	RSAPrivateKeyKey   string
	RSAPublicKeyKey    string
	EdDSAPrivateKeyKey string
	EdDSAPublicKeyKey  string
	Validator          Validator
}

ConfigServiceInput configures NewConfiguredService. When Algorithm is empty, the constructor reads it from viper. Validator is optional.

type Ed25519ServiceInput

type Ed25519ServiceInput struct {
	PrivateKey    ed25519.PrivateKey
	PublicKey     ed25519.PublicKey
	PrivateKeyEnv string
	PublicKeyEnv  string
	Validator     Validator
}

Ed25519ServiceInput configures NewEd25519Service.

type HMACServiceInput

type HMACServiceInput struct {
	Secret    string
	SecretEnv string
	Validator Validator
}

HMACServiceInput configures NewHMACService. SecretEnv keeps its original name for compatibility and is treated as a viper key when Secret is empty. Validator is optional.

type Header

type Header struct {
	Type      string `json:"typ"`
	Algorithm string `json:"alg"`
}

Header represents the standard JWT header section.

type Option

type Option func(*Service) error

Option configures a Service instance during construction.

func WithEd25519

func WithEd25519(privateKey ed25519.PrivateKey, publicKey ed25519.PublicKey) Option

WithEd25519 configures the service to use Ed25519 signatures.

func WithHMACSHA256

func WithHMACSHA256(secret string) Option

WithHMACSHA256 configures the service to use HMAC-SHA256 signatures.

func WithRSAPSSSHA256

func WithRSAPSSSHA256(privateKey *rsa.PrivateKey, publicKey *rsa.PublicKey) Option

WithRSAPSSSHA256 configures the service to use RSA-PSS SHA-256 signatures.

func WithRSASHA256

func WithRSASHA256(privateKey *rsa.PrivateKey, publicKey *rsa.PublicKey) Option

WithRSASHA256 configures the service to use RSA-SHA256 signatures.

func WithStrategy

func WithStrategy(strategy Strategy) Option

WithStrategy injects a custom signing strategy into the service.

func WithValidator

func WithValidator(validator Validator) Option

WithValidator registers a validator that will run on every Decode call after signature verification and claim decoding succeed.

type RSAServiceInput

type RSAServiceInput struct {
	PrivateKey    *rsa.PrivateKey
	PublicKey     *rsa.PublicKey
	PrivateKeyEnv string
	PublicKeyEnv  string
	Validator     Validator
}

RSAServiceInput configures NewRSAService. PrivateKeyEnv and PublicKeyEnv keep their original names for compatibility and are treated as viper keys when the corresponding key is nil. Validator is optional.

type Service

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

Service is a facade over JWT creation and validation. It uses a Strategy for cryptographic concerns and a validation pipeline for domain-specific checks.

func New

func New(options ...Option) (*Service, error)

New builds a JWT service from the provided options. A signing strategy must be configured, either directly with WithStrategy or through a convenience option such as WithHMACSHA256.

func NewConfiguredService

func NewConfiguredService(input ConfigServiceInput) (*Service, error)

NewConfiguredService builds a JWT service based on the configured algorithm. It reads values from viper using the provided keys or the package defaults.

func NewEd25519Service

func NewEd25519Service(input Ed25519ServiceInput) (*Service, error)

NewEd25519Service builds a JWT service for EdDSA signatures.

func NewHMACService

func NewHMACService(input HMACServiceInput) (*Service, error)

NewHMACService builds a JWT service for HS256 signatures. The secret can be provided directly or loaded from viper.

func NewRSAPSSService

func NewRSAPSSService(input RSAServiceInput) (*Service, error)

NewRSAPSSService builds a JWT service for PS256 signatures.

func NewRSAService

func NewRSAService(input RSAServiceInput) (*Service, error)

NewRSAService builds a JWT service for RS256 signatures. Keys can be provided directly or loaded from Base64-encoded viper values containing PKCS#8 private and X.509 public keys.

func (*Service) Create

func (service *Service) Create(claims any) (string, error)

Create builds and signs a JWT using the configured signing strategy. The token header is generated automatically, so callers only provide claims.

func (*Service) Decode

func (service *Service) Decode(ctx context.Context, token string, destination any, validators ...Validator) (Token, error)

Decode validates the token signature, unmarshals its claims into destination, and runs both service-level and per-call validators.

func (*Service) Read

func (service *Service) Read(token string, destination any) error

Read validates the token and unmarshals its claims into destination using a background context and the service-level validators.

func (*Service) ValidateSignature

func (service *Service) ValidateSignature(token string) error

ValidateSignature verifies the JWT structure, algorithm, and signature without decoding its claims into a destination value.

type Strategy

type Strategy interface {
	Algorithm() string
	Sign(signingInput []byte) ([]byte, error)
	Verify(signingInput []byte, signature []byte) error
}

Strategy defines how a JWT is signed and how its signature is verified. Different algorithms can be supported by providing alternative implementations.

func NewEd25519

func NewEd25519(privateKey ed25519.PrivateKey, publicKey ed25519.PublicKey) Strategy

NewEd25519 returns an Ed25519 signing strategy.

func NewHMACSHA256

func NewHMACSHA256(secret string) Strategy

NewHMACSHA256 returns an HMAC-SHA256 signing strategy.

func NewRSAPSSSHA256

func NewRSAPSSSHA256(privateKey *rsa.PrivateKey, publicKey *rsa.PublicKey) Strategy

NewRSAPSSSHA256 returns an RSA-PSS SHA-256 signing strategy.

func NewRSASHA256

func NewRSASHA256(privateKey *rsa.PrivateKey, publicKey *rsa.PublicKey) Strategy

NewRSASHA256 returns an RSA-SHA256 signing strategy. The private key is used to sign tokens and the public key is used to verify them.

type Token

type Token struct {
	Raw       string
	Header    Header
	Claims    json.RawMessage
	Signature string
}

Token contains the parsed pieces of a validated JWT.

type Validator

type Validator func(ctx context.Context, token Token) error

Validator represents an additional validation step executed after the token signature has been verified and its claims have been decoded.