auth

README

auth

Reusable authentication primitives for HTTP services.
Uses github.com/golang-jwt/jwt/v5 to sign and verify access/refresh tokens.
Uses Go context values to propagate subject/admin flags through middleware and handlers.

Usage

go get github.com/jesse0michael/pkg/auth

Documentation

Index

• Constants
• Variables
• func Admin(ctx context.Context) (bool, bool)
• func Authorization(ctx context.Context) (string, bool)
• func Check(ctx context.Context, subject string) bool
• func JTI(ctx context.Context) (string, bool)
• func ReadOnly(ctx context.Context) (bool, bool)
• func Subject(ctx context.Context) (string, bool)
• func WithClaims(ctx context.Context, claim *Claim) context.Context
• func WithSpan(ctx context.Context) context.Context
• type Claim
• type Config
• type JWTAuth
  • func NewJWTAuth(cfg Config, signingMethod jwt.SigningMethod, opts ...jwt.ParserOption) *JWTAuth
  • func (a *JWTAuth) GenerateTokens(opts ...TokenOption) (string, string, error)
  • func (a *JWTAuth) RefreshTokens(token string) (string, string, error)
  • func (a *JWTAuth) VerifyAccessToken(token string) (*Claim, error)
  • func (a *JWTAuth) VerifyRefreshToken(token string) (*Claim, error)
  • func (a *JWTAuth) VerifyToken(tokenString, expectedType string) (*Claim, error)
• type RevokedTokenChecker
• type TokenOption
  • func WithAdmin() TokenOption
  • func WithAudience(audience ...string) TokenOption
  • func WithReadOnly() TokenOption
  • func WithSubject(subject string) TokenOption

Constants

const (
	AuthorizationContextKey = contextKey("authorization")
	SubjectContextKey       = contextKey("subject")
	AdminContextKey         = contextKey("admin")
	ReadOnlyContextKey      = contextKey("readOnly")
	JTIContextKey           = contextKey("jti")
	RequestContextKey       = contextKey("request")
)

const (
	AccessTokenType  = "access"
	RefreshTokenType = "refresh"
)

Variables

var (
	ErrInvalidToken      = errors.New("invalid token")
	ErrTokenExpired      = errors.New("token expired")
	ErrInvalidSigningKey = errors.New("invalid signing key")
)

Functions

func Admin

func Admin(ctx context.Context) (bool, bool)

func Authorization

func Authorization(ctx context.Context) (string, bool)

func Check

func Check(ctx context.Context, subject string) bool

func JTI

func JTI(ctx context.Context) (string, bool)

func ReadOnly

func ReadOnly(ctx context.Context) (bool, bool)

func Subject

func Subject(ctx context.Context) (string, bool)

func WithClaims

func WithClaims(ctx context.Context, claim *Claim) context.Context

WithClaims sets identifying information from the claims into the context

func WithSpan

func WithSpan(ctx context.Context) context.Context

WithSpan sets auth attributes on the current span and stores the trace ID in context

Types

type Claim

type Claim struct {
	// Admin indicates if the user has admin privileges
	Admin bool `json:"admin,omitempty"`

	// ReadOnly indicates if the user has read-only access
	ReadOnly bool `json:"readOnly,omitempty"`

	// TokenType indicates the type of the token (access or refresh)
	TokenType string `json:"type,omitempty"`

	jwt.RegisteredClaims
}

type Config

type Config struct {
	// SecretKey used for signing tokens (required)
	SecretKey []byte `envconfig:"AUTH_SECRET_KEY" required:"true"`

	// Issuer claim to include in tokens
	Issuer string `envconfig:"AUTH_ISSUER"`

	// Time-to-live for access tokens
	AccessTokenTTL time.Duration `envconfig:"AUTH_ACCESS_TOKEN_TTL" default:"168h"` // 7 days

	// Time-to-live for refresh tokens
	RefreshTokenTTL time.Duration `envconfig:"AUTH_REFRESH_TOKEN_TTL" default:"720h"` // 30 days
}

type JWTAuth

type JWTAuth struct {
	Options []jwt.ParserOption
	// contains filtered or unexported fields
}

func NewJWTAuth

func NewJWTAuth(cfg Config, signingMethod jwt.SigningMethod, opts ...jwt.ParserOption) *JWTAuth

func (*JWTAuth) GenerateTokens

func (a *JWTAuth) GenerateTokens(opts ...TokenOption) (string, string, error)

GenerateTokens creates both access and refresh tokens for a user in one call

func (*JWTAuth) RefreshTokens

func (a *JWTAuth) RefreshTokens(token string) (string, string, error)

RefreshTokens validates a refresh token and issues new access and refresh tokens

func (*JWTAuth) VerifyAccessToken

func (a *JWTAuth) VerifyAccessToken(token string) (*Claim, error)

VerifyAccessToken specifically validates access tokens

func (*JWTAuth) VerifyRefreshToken

func (a *JWTAuth) VerifyRefreshToken(token string) (*Claim, error)

VerifyRefreshToken specifically validates refresh tokens

func (*JWTAuth) VerifyToken

func (a *JWTAuth) VerifyToken(tokenString, expectedType string) (*Claim, error)

VerifyToken validates a token and returns the claims

type RevokedTokenChecker

type RevokedTokenChecker interface {
	IsRevoked(ctx context.Context, jti string) (bool, error)
}

RevokedTokenChecker abstracts the storage lookup for revoked tokens. Implement this against your database and pass it to the revoked-token middleware.

type TokenOption

type TokenOption func(*tokenParams)

TokenOption is a functional option for configuring token generation

func WithAdmin

func WithAdmin() TokenOption

WithAdmin sets the admin claim on the token

func WithAudience

func WithAudience(audience ...string) TokenOption

WithAudience sets the audience claim on the token

func WithReadOnly

func WithReadOnly() TokenOption

WithReadOnly sets the read-only claim on the token

func WithSubject

func WithSubject(subject string) TokenOption

WithSubject sets the subject claim on the token