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 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 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, or WithECDSA) 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.
Source Files