auth

Documentation

Overview

Package auth provides API authentication for Alancoin.

Authentication model: - Public endpoints (discovery, stats): No auth required - Mutations (update, delete): Require API key with ownership proof - API keys are issued on agent registration

Index

• Constants
• Variables
• func GetAuthenticatedAgent(c *gin.Context) string
• func IsAuthenticated(c *gin.Context) bool
• func Middleware(m *Manager) gin.HandlerFunc
• func RequireAuth(m *Manager) gin.HandlerFunc
• func RequireOwnership(m *Manager, paramName string) gin.HandlerFunc
• type APIKey
  • func GetAPIKey(c *gin.Context) (*APIKey, bool)
• type CreateKeyRequest
• type Handler
  • func NewHandler(m *Manager) *Handler
  • func (h *Handler) CreateKey(c *gin.Context)
  • func (h *Handler) GetCurrentAgent(c *gin.Context)
  • func (h *Handler) Info(c *gin.Context)
  • func (h *Handler) ListKeys(c *gin.Context)
  • func (h *Handler) RegenerateKey(c *gin.Context)
  • func (h *Handler) RevokeKey(c *gin.Context)
• type Manager
  • func NewManager(store Store) *Manager
  • func (m *Manager) GenerateKey(ctx context.Context, agentAddr, name string) (rawKey string, key *APIKey, err error)
  • func (m *Manager) ListKeys(ctx context.Context, agentAddr string) ([]*APIKey, error)
  • func (m *Manager) RevokeKey(ctx context.Context, keyID, agentAddr string) error
  • func (m *Manager) ValidateKey(ctx context.Context, rawKey string) (*APIKey, error)
• type MemoryStore
  • func NewMemoryStore() *MemoryStore
  • func (s *MemoryStore) Create(ctx context.Context, key *APIKey) error
  • func (s *MemoryStore) Delete(ctx context.Context, id string) error
  • func (s *MemoryStore) GetByAgent(ctx context.Context, addr string) ([]*APIKey, error)
  • func (s *MemoryStore) GetByHash(ctx context.Context, hash string) (*APIKey, error)
  • func (s *MemoryStore) Update(ctx context.Context, key *APIKey) error
• type PostgresStore
  • func NewPostgresStore(db *sql.DB) *PostgresStore
  • func (p *PostgresStore) Create(ctx context.Context, key *APIKey) error
  • func (p *PostgresStore) Delete(ctx context.Context, id string) error
  • func (p *PostgresStore) GetByAgent(ctx context.Context, addr string) ([]*APIKey, error)
  • func (p *PostgresStore) GetByHash(ctx context.Context, hash string) (*APIKey, error)
  • func (p *PostgresStore) Migrate(ctx context.Context) error
  • func (p *PostgresStore) Update(ctx context.Context, key *APIKey) error
• type Store

Constants

const (
	// ContextKeyAPIKey is the key for storing API key in gin context
	ContextKeyAPIKey = "apiKey"
	// ContextKeyAgentAddr is the key for storing authenticated agent address
	ContextKeyAgentAddr = "authAgentAddr"
)

Variables

var (
	ErrNoAPIKey      = errors.New("API key required")
	ErrInvalidAPIKey = errors.New("invalid or expired API key")
	ErrNotOwner      = errors.New("not authorized for this resource")
	ErrKeyNotFound   = errors.New("API key not found")
)

Errors

Functions

func GetAuthenticatedAgent

func GetAuthenticatedAgent(c *gin.Context) string

GetAuthenticatedAgent returns the authenticated agent's address

func IsAuthenticated

func IsAuthenticated(c *gin.Context) bool

IsAuthenticated checks if the request is authenticated

func Middleware

func Middleware(m *Manager) gin.HandlerFunc

Middleware extracts and validates API key from request Sets apiKey and authAgentAddr in context if valid

func RequireAuth

func RequireAuth(m *Manager) gin.HandlerFunc

RequireAuth middleware rejects requests without valid auth

func RequireOwnership

func RequireOwnership(m *Manager, paramName string) gin.HandlerFunc

RequireOwnership middleware requires auth AND ownership of the :address param

Types

type APIKey

type APIKey struct {
	ID        string     `json:"id"`
	Hash      string     `json:"-"`         // SHA256 hash of key (stored)
	AgentAddr string     `json:"agentAddr"` // The agent this key belongs to
	Name      string     `json:"name"`      // Friendly name
	CreatedAt time.Time  `json:"createdAt"`
	LastUsed  time.Time  `json:"lastUsed,omitempty"`
	ExpiresAt *time.Time `json:"expiresAt,omitempty"`
	Revoked   bool       `json:"revoked"`
}

APIKey represents an API key

func GetAPIKey

func GetAPIKey(c *gin.Context) (*APIKey, bool)

GetAPIKey returns the API key from context (if authenticated)

type CreateKeyRequest

type CreateKeyRequest struct {
	Name string `json:"name"`
}

CreateKeyRequest is the request body for creating a key

type Handler

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

Handler provides HTTP endpoints for auth management

func NewHandler

func NewHandler(m *Manager) *Handler

NewHandler creates a new auth handler

func (*Handler) CreateKey

func (h *Handler) CreateKey(c *gin.Context)

CreateKey creates a new API key

func (*Handler) GetCurrentAgent

func (h *Handler) GetCurrentAgent(c *gin.Context)

GetCurrentAgent returns info about the authenticated agent

func (*Handler) Info

func (h *Handler) Info(c *gin.Context)

Info returns auth configuration info

func (*Handler) ListKeys

func (h *Handler) ListKeys(c *gin.Context)

ListKeys returns API keys for the authenticated agent

func (*Handler) RegenerateKey

func (h *Handler) RegenerateKey(c *gin.Context)

RegenerateKey revokes old key and creates new one

func (*Handler) RevokeKey

func (h *Handler) RevokeKey(c *gin.Context)

RevokeKey revokes an API key

type Manager

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

Manager handles authentication

func NewManager

func NewManager(store Store) *Manager

NewManager creates a new auth manager

func (*Manager) GenerateKey

func (m *Manager) GenerateKey(ctx context.Context, agentAddr, name string) (rawKey string, key *APIKey, err error)

GenerateKey creates a new API key for an agent Returns the raw key (shown once) and the stored metadata

func (*Manager) ListKeys

func (m *Manager) ListKeys(ctx context.Context, agentAddr string) ([]*APIKey, error)

ListKeys returns all keys for an agent

func (*Manager) RevokeKey

func (m *Manager) RevokeKey(ctx context.Context, keyID, agentAddr string) error

RevokeKey revokes an API key

func (*Manager) ValidateKey

func (m *Manager) ValidateKey(ctx context.Context, rawKey string) (*APIKey, error)

ValidateKey validates an API key and returns the key metadata

type MemoryStore

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

MemoryStore is an in-memory implementation of Store

func NewMemoryStore

func NewMemoryStore() *MemoryStore

NewMemoryStore creates a new in-memory store

func (*MemoryStore) Create

func (s *MemoryStore) Create(ctx context.Context, key *APIKey) error

func (*MemoryStore) Delete

func (s *MemoryStore) Delete(ctx context.Context, id string) error

func (*MemoryStore) GetByAgent

func (s *MemoryStore) GetByAgent(ctx context.Context, addr string) ([]*APIKey, error)

func (*MemoryStore) GetByHash

func (s *MemoryStore) GetByHash(ctx context.Context, hash string) (*APIKey, error)

func (*MemoryStore) Update

func (s *MemoryStore) Update(ctx context.Context, key *APIKey) error

type PostgresStore

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

PostgresStore persists API keys in PostgreSQL

func NewPostgresStore

func NewPostgresStore(db *sql.DB) *PostgresStore

NewPostgresStore creates a new PostgreSQL-backed auth store

func (*PostgresStore) Create

func (p *PostgresStore) Create(ctx context.Context, key *APIKey) error

Create stores a new API key

func (*PostgresStore) Delete

func (p *PostgresStore) Delete(ctx context.Context, id string) error

Delete removes an API key

func (*PostgresStore) GetByAgent

func (p *PostgresStore) GetByAgent(ctx context.Context, addr string) ([]*APIKey, error)

GetByAgent retrieves all API keys for an agent

func (*PostgresStore) GetByHash

func (p *PostgresStore) GetByHash(ctx context.Context, hash string) (*APIKey, error)

GetByHash retrieves an API key by its hash

func (*PostgresStore) Migrate

func (p *PostgresStore) Migrate(ctx context.Context) error

Migrate creates the api_keys table if it doesn't exist

func (*PostgresStore) Update

func (p *PostgresStore) Update(ctx context.Context, key *APIKey) error

Update updates an API key

type Store

type Store interface {
	Create(ctx context.Context, key *APIKey) error
	GetByHash(ctx context.Context, hash string) (*APIKey, error)
	GetByAgent(ctx context.Context, addr string) ([]*APIKey, error)
	Update(ctx context.Context, key *APIKey) error
	Delete(ctx context.Context, id string) error
}

Store persists API keys