auth

Documentation

Overview

Package auth provides admin account management with bcrypt-hashed passwords.

Index

• Variables
• type APIKey
  • func (k *APIKey) HasScope(s Scope) bool
  • func (k *APIKey) IsExpired() bool
• type APIKeyStore
  • func NewAPIKeyStore(path string) (*APIKeyStore, error)
  • func TestStore(token string) *APIKeyStore
  • func TestStoreWithTeam(adminToken, teamToken string, scopes []Scope, team string) *APIKeyStore
  • func (s *APIKeyStore) Create(name string, scopes []Scope, expiresAt time.Time, team string) (plaintext string, key APIKey, err error)
  • func (s *APIKeyStore) Get(id string) *APIKey
  • func (s *APIKeyStore) Insert(name, plaintext string, scopes []Scope) (APIKey, error)
  • func (s *APIKeyStore) IsEmpty() bool
  • func (s *APIKeyStore) List() []APIKey
  • func (s *APIKeyStore) Lookup(token string) *APIKey
  • func (s *APIKeyStore) Revoke(id string) error
  • func (s *APIKeyStore) Rotate(id string) (plaintext string, key APIKey, err error)
  • func (s *APIKeyStore) TouchLastUsed(id string)
  • func (s *APIKeyStore) ValidToken(token string) bool
• type Admin
• type AdminStore
  • func NewAdminStore(path string) (*AdminStore, error)
  • func (s *AdminStore) Add(username, password string) error
  • func (s *AdminStore) Authenticate(username, password string) bool
  • func (s *AdminStore) IsEmpty() bool
  • func (s *AdminStore) List() []Admin
  • func (s *AdminStore) Remove(username string) error
  • func (s *AdminStore) SetPassword(username, password string) error
  • func (s *AdminStore) SetStore(db *store.Store) error
• type Scope
  • func ParseScopes(s string) ([]Scope, error)

Variables

var ValidScopes = map[Scope]bool{
	ScopeAdmin: true, ScopeAgents: true, ScopeChannels: true,
	ScopeTopology: true, ScopeBots: true, ScopeConfig: true,
	ScopeRead: true, ScopeChat: true,
}

ValidScopes is the set of all recognised scopes.

Types

type APIKey

type APIKey struct {
	ID        string    `json:"id"`
	Name      string    `json:"name"`
	Hash      string    `json:"hash"` // SHA-256 of the plaintext token
	Scopes    []Scope   `json:"scopes"`
	Team      string    `json:"team,omitempty"` // empty = unrestricted; non-empty = scoped to this team
	CreatedAt time.Time `json:"created_at"`
	LastUsed  time.Time `json:"last_used,omitempty"`
	ExpiresAt time.Time `json:"expires_at,omitempty"` // zero = never
	Active    bool      `json:"active"`
}

APIKey is a single API key record.

func (*APIKey) HasScope

func (k *APIKey) HasScope(s Scope) bool

HasScope reports whether the key has the given scope (or admin, which implies all).

func (*APIKey) IsExpired

func (k *APIKey) IsExpired() bool

IsExpired reports whether the key has passed its expiry time.

type APIKeyStore

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

APIKeyStore persists API keys to a JSON file.

func NewAPIKeyStore

func NewAPIKeyStore(path string) (*APIKeyStore, error)

NewAPIKeyStore loads (or creates) the API key store at the given path.

func TestStore

func TestStore(token string) *APIKeyStore

TestStore creates an in-memory APIKeyStore with a single admin-scope key for the given token. Intended for tests only — does not persist to disk.

func TestStoreWithTeam

func TestStoreWithTeam(adminToken, teamToken string, scopes []Scope, team string) *APIKeyStore

TestStoreWithTeam creates an in-memory APIKeyStore with two keys: an admin-scope key for adminToken (unrestricted) and a team-scoped key for teamToken with the given scopes and team. Intended for tests only.

func (*APIKeyStore) Create

func (s *APIKeyStore) Create(name string, scopes []Scope, expiresAt time.Time, team string) (plaintext string, key APIKey, err error)

Create generates a new API key with the given name, scopes, and optional team scope. Returns the plaintext token (shown only once) and the stored key record.

func (*APIKeyStore) Get

func (s *APIKeyStore) Get(id string) *APIKey

Get returns a key by ID, or nil if not found.

func (*APIKeyStore) Insert

func (s *APIKeyStore) Insert(name, plaintext string, scopes []Scope) (APIKey, error)

Insert adds a pre-built API key with a known plaintext token. Used for migrating the startup token into the store. Inserted keys have no team scope (unrestricted).

func (*APIKeyStore) IsEmpty

func (s *APIKeyStore) IsEmpty() bool

IsEmpty reports whether there are no keys.

func (*APIKeyStore) List

func (s *APIKeyStore) List() []APIKey

List returns all keys (active and revoked).

func (*APIKeyStore) Lookup

func (s *APIKeyStore) Lookup(token string) *APIKey

Lookup finds an active, non-expired key by plaintext token. Returns nil if no match.

func (*APIKeyStore) Revoke

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

Revoke deactivates a key by ID.

func (*APIKeyStore) Rotate

func (s *APIKeyStore) Rotate(id string) (plaintext string, key APIKey, err error)

Rotate generates a new token for an existing key by ID. The old token is immediately invalidated. Returns the new plaintext token.

func (*APIKeyStore) TouchLastUsed

func (s *APIKeyStore) TouchLastUsed(id string)

TouchLastUsed updates the last-used timestamp for a key by ID.

func (*APIKeyStore) ValidToken

func (s *APIKeyStore) ValidToken(token string) bool

Lookup (TokenValidator interface) reports whether the token is valid. Satisfies the mcp.TokenValidator interface.

type Admin

type Admin struct {
	Username string    `json:"username"`
	Hash     []byte    `json:"hash"`
	Created  time.Time `json:"created"`
}

Admin is a single admin account record.

type AdminStore

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

AdminStore persists admin accounts to a JSON file or database.

func NewAdminStore

func NewAdminStore(path string) (*AdminStore, error)

NewAdminStore loads (or creates) the admin store at the given path.

func (*AdminStore) Add

func (s *AdminStore) Add(username, password string) error

Add adds a new admin account. Returns an error if the username already exists.

func (*AdminStore) Authenticate

func (s *AdminStore) Authenticate(username, password string) bool

Authenticate returns true if the username/password pair is valid.

func (*AdminStore) IsEmpty

func (s *AdminStore) IsEmpty() bool

IsEmpty reports whether there are no admin accounts.

func (*AdminStore) List

func (s *AdminStore) List() []Admin

List returns a snapshot of all admin accounts.

func (*AdminStore) Remove

func (s *AdminStore) Remove(username string) error

Remove removes an admin account. Returns an error if not found.

func (*AdminStore) SetPassword

func (s *AdminStore) SetPassword(username, password string) error

SetPassword updates the password for an existing admin.

func (*AdminStore) SetStore

func (s *AdminStore) SetStore(db *store.Store) error

SetStore switches the admin store to database-backed persistence. All current in-memory state is replaced with rows loaded from the store.

type Scope

type Scope string

Scope represents a permission scope for an API key.

const (
	ScopeAdmin    Scope = "admin"    // full access
	ScopeAgents   Scope = "agents"   // agent registration, rotation, revocation
	ScopeChannels Scope = "channels" // channel CRUD, join, messages, presence
	ScopeTopology Scope = "topology" // channel provisioning, topology management
	ScopeBots     Scope = "bots"     // bot configuration, start/stop
	ScopeConfig   Scope = "config"   // server config read/write
	ScopeRead     Scope = "read"     // read-only access to all GET endpoints
	ScopeChat     Scope = "chat"     // send/receive messages only
)

func ParseScopes

func ParseScopes(s string) ([]Scope, error)

ParseScopes parses a comma-separated scope string into a slice. Returns an error if any scope is unrecognised.