jwt

Documentation

Overview

Package jwt provides a stateless JWT authenticator for the Gas ecosystem. It implements gas.Authenticator and gas.Service.

Index

• func New(opts ...Option) func(gas.ConfigProvider, gas.Logger) *Service
• type Config
  • func DefaultConfig() *Config
  • func (c *Config) Validate() error
• type Option
  • func WithConfig(cfg *Config) Option
  • func WithSigningMethod(method string) Option
• type Provider
• type Service
  • func (s *Service) Authenticate(ctx context.Context, r *http.Request) (gas.Principal, error)
  • func (s *Service) Close() error
  • func (s *Service) Init() error
  • func (s *Service) Name() string
  • func (s *Service) Sign(subject string, claims map[string]any) (string, error)
  • func (s *Service) SignWithExpiry(subject string, claims map[string]any, expiry time.Duration) (string, error)
  • func (s *Service) Verify(tokenString string) (*TokenClaims, error)
• type Settings
• type TokenClaims

Functions

func New

func New(opts ...Option) func(gas.ConfigProvider, gas.Logger) *Service

New captures options and returns a DI-injectable constructor.

Types

type Config

type Config struct {
	env.WithGasEnv

	JWT Settings
}

Config holds JWT service settings.

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns a Config with sensible defaults.

func (*Config) Validate

func (c *Config) Validate() error

Validate checks the Config for correctness.

type Option

type Option func(*Service)

Option configures a Service.

func WithConfig

func WithConfig(cfg *Config) Option

WithConfig sets a custom configuration, skipping auto-bind from ConfigProvider.

func WithSigningMethod

func WithSigningMethod(method string) Option

WithSigningMethod overrides the default signing method.

type Provider

type Provider interface {
	// Authenticate reads a Bearer token from the Authorization header, verifies
	// it, and returns a principal with scheme "jwt".
	Authenticate(ctx context.Context, r *http.Request) (gas.Principal, error)
	// Sign creates a signed JWT with the given subject and custom claims using
	// the default expiry.
	Sign(subject string, claims map[string]any) (string, error)
	// SignWithExpiry creates a signed JWT with the given subject, custom claims,
	// and explicit expiry duration.
	SignWithExpiry(subject string, claims map[string]any, expiry time.Duration) (string, error)
	// Verify parses and validates a JWT string, returning the extracted claims.
	Verify(tokenString string) (*TokenClaims, error)
}

Provider defines an interface for JWT authentication and signing operations.

type Service

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

Service is a JWT authenticator implementing gas.Authenticator and gas.Service.

func (*Service) Authenticate

func (s *Service) Authenticate(ctx context.Context, r *http.Request) (gas.Principal, error)

Authenticate reads a Bearer token from the Authorization header, verifies it, and returns a principal with scheme "jwt".

func (*Service) Close

func (s *Service) Close() error

Close performs cleanup. JWT is stateless so this is a no-op.

func (*Service) Init

func (s *Service) Init() error

Init validates configuration and prepares signing keys.

func (*Service) Name

func (s *Service) Name() string

Name returns the service identifier.

func (*Service) Sign

func (s *Service) Sign(subject string, claims map[string]any) (string, error)

Sign creates a signed JWT with the given subject and custom claims using the default expiry.

func (*Service) SignWithExpiry

func (s *Service) SignWithExpiry(subject string, claims map[string]any, expiry time.Duration) (string, error)

SignWithExpiry creates a signed JWT with the given subject, custom claims, and explicit expiry duration.

func (*Service) Verify

func (s *Service) Verify(tokenString string) (*TokenClaims, error)

Verify parses and validates a JWT string, returning the extracted claims.

type Settings

type Settings struct {
	// SigningKey is the HMAC key used for HS256 signing and verification.
	SigningKey string
	// SigningMethod is the JWT signing algorithm. Supported: "HS256", "RS256".
	SigningMethod string
	// PublicKeyPath is the path to the RSA public key file for RS256 verification.
	PublicKeyPath string
	// PrivateKeyPath is the path to the RSA private key file for RS256 signing.
	PrivateKeyPath string
	// Issuer is the expected "iss" claim value.
	Issuer string
	// Audience is the expected "aud" claim value.
	Audience string
	// Expiry is the default token lifetime.
	Expiry time.Duration
}

Settings represents the JWT configuration values.

type TokenClaims

type TokenClaims struct {
	ExpiresAt    time.Time
	IssuedAt     time.Time
	CustomClaims map[string]any
	Subject      string
	TokenID      string
	Issuer       string
	Audience     []string
}

TokenClaims holds parsed JWT data.