grantauth

Documentation

Overview

Package grantauth signs and validates short-lived Shellin grant tokens.

Tokens are HMAC-SHA256 JWTs with issuer, audience, subject, expiry, token ID, role, and session claims. Signaling tokens must also pass replay protection through a ReplayStore before a WebSocket is accepted.

Index

• Constants
• Variables
• func SignHS256(secret string, claims map[string]any) (string, error)
• func ValidateHMACSecret(secret string) error
• type Claims
• type MemoryReplayStore
  • func NewMemoryReplayStore() *MemoryReplayStore
  • func (s *MemoryReplayStore) Consume(tokenID string, expiresAt time.Time) error
• type ReplayGuard
  • func NewReplayGuard() *ReplayGuard
  • func NewReplayGuardWithStore(store ReplayStore) *ReplayGuard
  • func (g *ReplayGuard) Consume(tokenID string, expiresAt time.Time) error
• type ReplayStore
• type Validator
  • func NewValidator(secret, issuer, audience string) (*Validator, error)
  • func (v *Validator) Validate(token string) (*Claims, error)

Constants

const MinHMACSecretBytes = 32

Variables

var (
	ErrReplayDetected         = errors.New("grant token replay detected")
	ErrReplayStoreUnavailable = errors.New("grant replay store unavailable")
)

var (
	ErrMalformedToken = errors.New("malformed grant token")
	ErrBadSignature   = errors.New("invalid grant token signature")
	ErrExpired        = errors.New("grant token expired")
	ErrNotYetValid    = errors.New("grant token not yet valid")
	ErrInvalidClaim   = errors.New("invalid grant token claim")
)

Functions

func SignHS256

func SignHS256(secret string, claims map[string]any) (string, error)

SignHS256 builds and signs a JWT using the provided claims map.

func ValidateHMACSecret

func ValidateHMACSecret(secret string) error

Types

type Claims

type Claims struct {
	Subject     string
	Issuer      string
	Audience    []string
	ExpiresAt   time.Time
	NotBefore   time.Time
	MaxSessions int
	TokenID     string
	Role        string
	SessionID   string
}

type MemoryReplayStore

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

func NewMemoryReplayStore

func NewMemoryReplayStore() *MemoryReplayStore

func (*MemoryReplayStore) Consume

func (s *MemoryReplayStore) Consume(tokenID string, expiresAt time.Time) error

type ReplayGuard

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

func NewReplayGuard

func NewReplayGuard() *ReplayGuard

func NewReplayGuardWithStore

func NewReplayGuardWithStore(store ReplayStore) *ReplayGuard

func (*ReplayGuard) Consume

func (g *ReplayGuard) Consume(tokenID string, expiresAt time.Time) error

type ReplayStore

type ReplayStore interface {
	Consume(tokenID string, expiresAt time.Time) error
}

ReplayStore atomically records a token ID until expiresAt.

Implementations backed by shared infrastructure must perform this as a conditional put: the first caller for a token ID succeeds, and later callers fail with ErrReplayDetected until the stored expiry has passed.

type Validator

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

func NewValidator

func NewValidator(secret, issuer, audience string) (*Validator, error)

func (*Validator) Validate

func (v *Validator) Validate(token string) (*Claims, error)