Documentation
¶
Overview ¶
Package jwt provides JWT creation, validation, and revocation for the api-security-sdk. It supports HMAC (HS256/384/512), RSA (RS256/512), and ECDSA (ES256/384/512) signing algorithms.
Quick start:
svc := jwt.New(jwt.WithHMAC([]byte("at-least-32-bytes-secret")))
token, err := svc.Sign(jwt.Claims{Subject: "user123"})
claims, err := svc.Verify(token)
Index ¶
- Variables
- type Blacklist
- type Claims
- type MemoryBlacklist
- type Option
- func WithBlacklist(bl Blacklist) Option
- func WithECDSA(privateKey *ecdsa.PrivateKey, publicKey *ecdsa.PublicKey) Option
- func WithExpiry(d time.Duration) Option
- func WithHMAC(secret []byte) Option
- func WithHMAC384(secret []byte) Option
- func WithHMAC512(secret []byte) Option
- func WithIssuer(issuer string) Option
- func WithJWKS(kf gojwt.Keyfunc) Option
- func WithRSA(privateKey *rsa.PrivateKey, publicKey *rsa.PublicKey) Option
- func WithRSA512(privateKey *rsa.PrivateKey, publicKey *rsa.PublicKey) Option
- type Service
Constants ¶
This section is empty.
Variables ¶
var ( ErrInvalidToken = errors.New("jwt: invalid token") ErrExpiredToken = errors.New("jwt: token has expired") ErrInvalidSigningMethod = errors.New("jwt: unexpected signing method") ErrTokenRevoked = errors.New("jwt: token has been revoked") ErrNoBlacklist = errors.New("jwt: no blacklist configured; use WithBlacklist") ErrMissingAlgorithm = errors.New("jwt: no signing algorithm configured; use WithHMAC, WithRSA, or WithECDSA") )
Sentinel errors returned by Service methods.
Functions ¶
This section is empty.
Types ¶
type Blacklist ¶
type Blacklist interface {
// Revoke marks the token string as revoked.
Revoke(token string) error
// IsRevoked reports whether the token has been revoked.
IsRevoked(token string) (bool, error)
}
Blacklist is the interface for a token revocation store.
type Claims ¶
type Claims struct {
// Subject identifies the principal that is the subject of the token (e.g. user ID).
Subject string
// Audience identifies the recipients that the token is intended for.
Audience []string
// ExpiresAt is when the token expires.
ExpiresAt time.Time
// IssuedAt is when the token was issued.
IssuedAt time.Time
// Custom holds application-specific claims.
Custom map[string]any
}
Claims represents the payload of a JWT token.
type MemoryBlacklist ¶
type MemoryBlacklist struct {
// contains filtered or unexported fields
}
MemoryBlacklist is a thread-safe, in-memory Blacklist implementation. Revoked tokens are stored indefinitely. For production, prefer a Redis-backed implementation with TTL-based expiry.
func NewMemoryBlacklist ¶
func NewMemoryBlacklist() *MemoryBlacklist
NewMemoryBlacklist returns an initialised MemoryBlacklist.
func (*MemoryBlacklist) IsRevoked ¶
func (b *MemoryBlacklist) IsRevoked(token string) (bool, error)
IsRevoked reports whether the token is in the revocation set.
func (*MemoryBlacklist) Revoke ¶
func (b *MemoryBlacklist) Revoke(token string) error
Revoke adds the token to the revocation set.
type Option ¶
type Option func(*options)
Option configures the JWT Service.
func WithBlacklist ¶
WithBlacklist attaches a token revocation store to the service. Revoked tokens are rejected during Verify.
func WithECDSA ¶
func WithECDSA(privateKey *ecdsa.PrivateKey, publicKey *ecdsa.PublicKey) Option
WithECDSA configures ECDSA signing. The algorithm is auto-detected from the key's curve: P-256 → ES256, P-384 → ES384, P-521 → ES512.
func WithExpiry ¶
WithExpiry sets the token lifetime (default: 1 hour).
func WithHMAC ¶
WithHMAC configures HMAC-SHA256 (HS256) signing with the given secret. The secret must be at least 32 bytes to provide adequate security.
func WithHMAC384 ¶
WithHMAC384 configures HMAC-SHA384 (HS384) signing.
func WithHMAC512 ¶
WithHMAC512 configures HMAC-SHA512 (HS512) signing.
func WithIssuer ¶
WithIssuer sets the "iss" claim on all issued tokens.
func WithJWKS ¶ added in v1.0.1
WithJWKS configures the service to verify tokens using an external keyfunc (e.g. from auth/jwks.Source.KeyFunc). When set, signingMethod and verifyKey are not used during Verify — the keyfunc is called instead.
Sign still requires a local signing method (WithHMAC, WithRSA, or WithECDSA). Use WithJWKS for verify-only services backed by Auth0, Cognito, Google, etc.
src := jwks.Auth0("myapp.auth0.com")
svc := jwt.New(jwt.WithJWKS(src.KeyFunc))
func WithRSA ¶
func WithRSA(privateKey *rsa.PrivateKey, publicKey *rsa.PublicKey) Option
WithRSA configures RSA-SHA256 (RS256) signing. Use a minimum key size of 2048 bits.
func WithRSA512 ¶
func WithRSA512(privateKey *rsa.PrivateKey, publicKey *rsa.PublicKey) Option
WithRSA512 configures RSA-SHA512 (RS512) signing.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service handles JWT signing, verification, and revocation.
func New ¶
New creates a JWT Service. At least one algorithm option (WithHMAC, WithRSA, WithECDSA, or WithJWKS) must be provided before calling Sign or Verify.
func (*Service) Refresh ¶
Refresh validates an existing token and issues a new one with a fresh expiry window. If a blacklist is configured the old token is revoked automatically.
func (*Service) Revoke ¶
Revoke adds a token to the blacklist so subsequent Verify calls reject it. Returns ErrNoBlacklist if no blacklist was configured.
func (*Service) Verify ¶
Verify parses and validates a JWT string, returning its claims on success. Returns an error if the token is malformed, expired, signed with the wrong algorithm, or present in the revocation blacklist.
When WithJWKS was used, the external keyfunc is called to resolve the key. Otherwise, the statically configured verifyKey is used.
Source Files