token

Documentation

Overview

Package token provides token-based access control for shield-agent.

Index

• func GenerateToken() (string, error)
• func HashToken(raw string) string
• type Store
  • func NewStore(db *sql.DB) *Store
  • func (s *Store) CountUsage(tokenID string, window time.Duration) (int, error)
  • func (s *Store) Create(name, tokenHash string, expiresAt *time.Time, quotaHourly, quotaMonthly int, ...) (string, error)
  • func (s *Store) Delete(id string) error
  • func (s *Store) GetByHash(hash string) (*Token, error)
  • func (s *Store) GetByID(id string) (*Token, error)
  • func (s *Store) GetStats(tokenID string, since time.Duration) (*UsageStats, error)
  • func (s *Store) List(activeOnly bool) ([]Token, error)
  • func (s *Store) RecordUsage(tokenID, method string, success bool, latencyMs float64) error
  • func (s *Store) Revoke(id string) error
• type Token
  • func (t *Token) IsExpired() bool
  • func (t *Token) IsMethodAllowed(method string) bool
• type UsageRecord
• type UsageStats

Functions

func GenerateToken

func GenerateToken() (string, error)

GenerateToken creates a random 32-byte hex token string.

func HashToken

func HashToken(raw string) string

HashToken returns the SHA-256 hex hash of a raw token.

Types

type Store

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

Store manages tokens in SQLite.

func NewStore

func NewStore(db *sql.DB) *Store

NewStore creates a Store using the given database connection.

func (*Store) CountUsage

func (s *Store) CountUsage(tokenID string, window time.Duration) (int, error)

CountUsage returns the number of requests for a token within a time window.

func (*Store) Create

func (s *Store) Create(name, tokenHash string, expiresAt *time.Time, quotaHourly, quotaMonthly int, allowedMethods, ipAllowlist []string) (string, error)

Create stores a new token and returns its ID.

func (*Store) Delete

func (s *Store) Delete(id string) error

Delete removes a token and its usage records.

func (*Store) GetByHash

func (s *Store) GetByHash(hash string) (*Token, error)

GetByHash looks up a token by its hash. Returns nil if not found.

func (*Store) GetByID

func (s *Store) GetByID(id string) (*Token, error)

GetByID looks up a token by its ID. Returns nil if not found.

func (*Store) GetStats

func (s *Store) GetStats(tokenID string, since time.Duration) (*UsageStats, error)

GetStats returns aggregated usage statistics for a token within a time range.

func (*Store) List

func (s *Store) List(activeOnly bool) ([]Token, error)

List returns all tokens, optionally filtered by active status.

func (*Store) RecordUsage

func (s *Store) RecordUsage(tokenID, method string, success bool, latencyMs float64) error

RecordUsage inserts a usage record for a token.

func (*Store) Revoke

func (s *Store) Revoke(id string) error

Revoke deactivates a token by ID.

type Token

type Token struct {
	ID             string     `json:"id"`
	Name           string     `json:"name"`
	TokenHash      string     `json:"-"`
	CreatedAt      time.Time  `json:"created_at"`
	ExpiresAt      *time.Time `json:"expires_at,omitempty"`
	Active         bool       `json:"active"`
	QuotaHourly    int        `json:"quota_hourly"`
	QuotaMonthly   int        `json:"quota_monthly"`
	AllowedMethods []string   `json:"allowed_methods"`
	IPAllowlist    []string   `json:"ip_allowlist"`
}

Token represents an API access token.

func (*Token) IsExpired

func (t *Token) IsExpired() bool

IsExpired returns true if the token has an expiration time that has passed.

func (*Token) IsMethodAllowed

func (t *Token) IsMethodAllowed(method string) bool

IsMethodAllowed returns true if the given method is permitted by this token. An empty allowed_methods list means all methods are permitted.

type UsageRecord

type UsageRecord struct {
	TokenID   string    `json:"token_id"`
	Timestamp time.Time `json:"timestamp"`
	Method    string    `json:"method"`
	Success   bool      `json:"success"`
	LatencyMs float64   `json:"latency_ms"`
}

UsageRecord represents a single token usage entry.

type UsageStats

type UsageStats struct {
	TotalRequests int     `json:"total_requests"`
	SuccessCount  int     `json:"success_count"`
	FailCount     int     `json:"fail_count"`
	AvgLatencyMs  float64 `json:"avg_latency_ms"`
	HourlyUsage   int     `json:"hourly_usage"`
	MonthlyUsage  int     `json:"monthly_usage"`
}

UsageStats holds aggregated usage statistics for a token.