Documentation
¶
Overview ¶
Package jwt provides JWT token generation and validation for CoreForge applications.
Index ¶
- Variables
- func ComputeTokenHash(token string) string
- type CNFClaim
- type Claims
- func (c *Claims) DPoPThumbprint() string
- func (c *Claims) IsAccessToken() bool
- func (c *Claims) IsDPoPBound() bool
- func (c *Claims) IsExpired() bool
- func (c *Claims) IsRefreshToken() bool
- func (c *Claims) WithDPoPBinding(thumbprint string) *Claims
- func (c *Claims) WithOrganization(orgID uuid.UUID, slug, role string, permissions []string) *Claims
- func (c *Claims) WithPlatformAdmin(isPlatformAdmin bool) *Claims
- type Config
- type DPoPBinding
- type Service
- func (s *Service) AccessTokenTTL() time.Duration
- func (s *Service) Config() *Config
- func (s *Service) GenerateAccessToken(userID uuid.UUID, email, name string) (string, error)
- func (s *Service) GenerateAccessTokenWithOptions(userID uuid.UUID, email, name string, opts TokenOptions) (string, error)
- func (s *Service) GenerateAccessTokenWithOrg(userID uuid.UUID, email, name string, orgID uuid.UUID, orgSlug, role string, ...) (string, error)
- func (s *Service) GenerateAccessTokenWithOrgAndOptions(userID uuid.UUID, email, name string, orgID uuid.UUID, orgSlug, role string, ...) (string, error)
- func (s *Service) GenerateRefreshToken(userID uuid.UUID, family string) (string, error)
- func (s *Service) GenerateTokenPair(userID uuid.UUID, email, name string) (*TokenPair, error)
- func (s *Service) GenerateTokenPairLegacy(userID uuid.UUID, email string, isPlatformAdmin bool) (*TokenPair, error)
- func (s *Service) GenerateTokenPairWithOptions(userID uuid.UUID, email, name string, opts TokenOptions) (*TokenPair, error)
- func (s *Service) GenerateTokenPairWithOrg(userID uuid.UUID, email, name string, orgID uuid.UUID, orgSlug, role string, ...) (*TokenPair, error)
- func (s *Service) RefreshTokenTTL() time.Duration
- func (s *Service) ValidateAccessToken(tokenString string) (*Claims, error)
- func (s *Service) ValidateRefreshToken(tokenString string) (*Claims, error)
- type TokenOptions
- type TokenPair
- type TokenType
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNoSigningKey is returned when no signing key is configured. ErrNoSigningKey = errors.New("no signing key configured: provide Secret or PrivateKey") // ErrInvalidAlgorithm is returned when an unsupported algorithm is specified. ErrInvalidAlgorithm = errors.New("invalid signing algorithm") // ErrMissingPublicKey is returned when PrivateKey is set but PublicKey is not. ErrMissingPublicKey = errors.New("public key required when using asymmetric signing") )
var ( // ErrInvalidToken is returned when a token cannot be parsed or validated. ErrInvalidToken = errors.New("invalid token") // ErrTokenExpired is returned when a token has expired. ErrTokenExpired = errors.New("token expired") // ErrWrongTokenType is returned when the token type doesn't match expectations. ErrWrongTokenType = errors.New("wrong token type") )
Functions ¶
func ComputeTokenHash ¶
ComputeTokenHash computes the base64url-encoded SHA-256 hash of a token string. This is used for the ath (access token hash) claim in DPoP proofs.
Types ¶
type CNFClaim ¶
type CNFClaim struct {
// JKT is the JWK thumbprint of the DPoP public key (RFC 7638).
JKT string `json:"jkt,omitempty"`
}
CNFClaim represents the confirmation claim (cnf) for DPoP-bound tokens. Per RFC 9449, this contains the JWK thumbprint of the DPoP public key.
type Claims ¶
type Claims struct {
jwt.RegisteredClaims
// UserID is the CoreForge user ID.
UserID uuid.UUID `json:"uid,omitempty"`
// Email is the user's email address.
Email string `json:"email,omitempty"`
// Name is the user's display name.
Name string `json:"name,omitempty"`
// OrganizationID is the current organization context (optional).
OrganizationID *uuid.UUID `json:"org_id,omitempty"`
// OrganizationSlug is the current organization slug (optional).
OrganizationSlug string `json:"org_slug,omitempty"`
// Role is the user's role in the current organization (optional).
Role string `json:"role,omitempty"`
// Permissions are fine-grained permissions (optional).
Permissions []string `json:"perms,omitempty"`
// IsPlatformAdmin indicates cross-organization admin access.
IsPlatformAdmin bool `json:"platform_admin,omitempty"`
// TokenType distinguishes access tokens from refresh tokens.
TokenType TokenType `json:"type,omitempty"`
// TokenFamily is used for refresh token rotation tracking.
TokenFamily string `json:"family,omitempty"`
// Confirmation contains the DPoP binding (cnf claim with jkt).
// When set, the token is bound to a specific DPoP key pair.
Confirmation *CNFClaim `json:"cnf,omitempty"`
}
Claims represents the CoreForge JWT claims structure. It embeds standard JWT claims and adds CoreForge-specific fields.
func NewAccessClaims ¶
NewAccessClaims creates claims for a new access token.
func NewRefreshClaims ¶
NewRefreshClaims creates claims for a new refresh token.
func (*Claims) DPoPThumbprint ¶
DPoPThumbprint returns the DPoP JWK thumbprint if the token is DPoP-bound. Returns empty string if not bound.
func (*Claims) IsAccessToken ¶
IsAccessToken returns true if this is an access token.
func (*Claims) IsDPoPBound ¶
IsDPoPBound returns true if this token is bound to a DPoP key.
func (*Claims) IsRefreshToken ¶
IsRefreshToken returns true if this is a refresh token.
func (*Claims) WithDPoPBinding ¶
WithDPoPBinding adds DPoP binding to access token claims. The thumbprint should be computed using RFC 7638 (JWK thumbprint).
func (*Claims) WithOrganization ¶
WithOrganization adds organization context to the claims.
func (*Claims) WithPlatformAdmin ¶
WithPlatformAdmin marks the user as a platform administrator.
type Config ¶
type Config struct {
// Secret is the symmetric key used for HS256 signing.
// Either Secret or PrivateKey must be provided.
Secret []byte //nolint:gosec // G117: field holds runtime secret value
// PrivateKey is the RSA or ECDSA private key for RS256/ES256 signing.
// Either Secret or PrivateKey must be provided.
PrivateKey any
// PublicKey is the RSA or ECDSA public key for RS256/ES256 verification.
// Required when PrivateKey is set.
PublicKey any
// Algorithm specifies the signing algorithm.
// Supported: HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512
// Defaults to HS256.
Algorithm string
// Issuer is the JWT "iss" claim value.
Issuer string
// Audience is the JWT "aud" claim value.
Audience []string
// AccessTokenExpiry is the duration before access tokens expire.
// Defaults to 15 minutes.
AccessTokenExpiry time.Duration
// RefreshTokenExpiry is the duration before refresh tokens expire.
// Defaults to 7 days.
RefreshTokenExpiry time.Duration
// RefreshTokenRotation enables automatic refresh token rotation.
// When enabled, a new refresh token is issued on each refresh.
RefreshTokenRotation bool
}
Config holds JWT configuration options.
func DefaultConfig ¶
func DefaultConfig() *Config
DefaultConfig returns a Config with sensible defaults. You must still provide a Secret or PrivateKey.
type DPoPBinding ¶
type DPoPBinding struct {
// Thumbprint is the JWK thumbprint of the DPoP key pair.
Thumbprint string
}
DPoPBinding contains DPoP binding information for a token.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service provides JWT token operations.
func NewService ¶
NewService creates a new JWT service with the given configuration.
func (*Service) AccessTokenTTL ¶
AccessTokenTTL returns the access token expiry duration. This method provides compatibility with goauth/jwt.Service.
func (*Service) GenerateAccessToken ¶
GenerateAccessToken creates a new access token for the given user.
func (*Service) GenerateAccessTokenWithOptions ¶
func (s *Service) GenerateAccessTokenWithOptions(userID uuid.UUID, email, name string, opts TokenOptions) (string, error)
GenerateAccessTokenWithOptions creates a new access token with optional parameters.
func (*Service) GenerateAccessTokenWithOrg ¶
func (s *Service) GenerateAccessTokenWithOrg( userID uuid.UUID, email, name string, orgID uuid.UUID, orgSlug, role string, permissions []string, isPlatformAdmin bool, ) (string, error)
GenerateAccessTokenWithOrg creates an access token with organization context.
func (*Service) GenerateAccessTokenWithOrgAndOptions ¶
func (s *Service) GenerateAccessTokenWithOrgAndOptions( userID uuid.UUID, email, name string, orgID uuid.UUID, orgSlug, role string, permissions []string, isPlatformAdmin bool, opts TokenOptions, ) (string, error)
GenerateAccessTokenWithOrgAndOptions creates an access token with organization context and options.
func (*Service) GenerateRefreshToken ¶
GenerateRefreshToken creates a new refresh token for the given user. The family parameter is used for refresh token rotation tracking.
func (*Service) GenerateTokenPair ¶
GenerateTokenPair creates both an access token and refresh token.
func (*Service) GenerateTokenPairLegacy ¶
func (s *Service) GenerateTokenPairLegacy(userID uuid.UUID, email string, isPlatformAdmin bool) (*TokenPair, error)
GenerateTokenPairLegacy creates a token pair using the legacy goauth interface. This provides backward compatibility during migration from goauth/jwt. Deprecated: Use GenerateTokenPair or GenerateTokenPairWithOrg instead.
func (*Service) GenerateTokenPairWithOptions ¶
func (s *Service) GenerateTokenPairWithOptions(userID uuid.UUID, email, name string, opts TokenOptions) (*TokenPair, error)
GenerateTokenPairWithOptions creates a token pair with optional DPoP binding.
func (*Service) GenerateTokenPairWithOrg ¶
func (s *Service) GenerateTokenPairWithOrg( userID uuid.UUID, email, name string, orgID uuid.UUID, orgSlug, role string, permissions []string, isPlatformAdmin bool, ) (*TokenPair, error)
GenerateTokenPairWithOrg creates a token pair with organization context.
func (*Service) RefreshTokenTTL ¶
RefreshTokenTTL returns the refresh token expiry duration. This method provides compatibility with goauth/jwt.Service.
func (*Service) ValidateAccessToken ¶
ValidateAccessToken validates and parses an access token.
type TokenOptions ¶
type TokenOptions struct {
// DPoPThumbprint binds the token to a DPoP key pair.
// When set, the token will include a cnf.jkt claim.
DPoPThumbprint string
}
TokenOptions contains optional parameters for token generation.
Source Files