Help us shape the future of Go! Take the 2026 Go Developer Survey

store

package
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 21, 2026 License: AGPL-3.0 Imports: 26 Imported by: 0

Documentation

Overview

Package store persists coordinator state in SQLite.

Index

Constants

View Source 
const (
	SettingPublicURL = "public_url"
	// SettingPolicy holds the access-control policy (HuJSON text).
	SettingPolicy = "policy"
	// SettingDNS holds the DNS configuration (JSON).
	SettingDNS = "dns"
	// SettingKeyExpiryDays is how long node keys last (0 or unset: forever).
	SettingKeyExpiryDays = "key_expiry_days"
)

Setting keys.

View Source 
const APITokenPrefix = "tpa_"

APITokenPrefix starts every API token.

View Source 
const AuthKeyPrefix = "trk_"

AuthKeyPrefix starts every pre-auth key, making leaked keys easy to recognise.

View Source 
const DBFile = "coordinator.db"

DBFile is the database file name inside the data directory.

View Source 
const NodeTokenPrefix = "trn_"

NodeTokenPrefix starts every node token.

View Source 
const SessionTokenPrefix = "trs_"

SessionTokenPrefix starts every admin session token.

Variables

View Source 
var (
	// ErrConflict is returned when a unique value (name, username) is taken.
	ErrConflict = errors.New("already exists")
	// ErrInvalidCredentials is returned for a wrong username or password.
	ErrInvalidCredentials = errors.New("invalid username or password")
	// ErrSetupDone is returned when creating the first admin after setup.
	ErrSetupDone = errors.New("setup has already been completed")
)
View Source 
var (
	// ErrNotFound is returned when a requested record does not exist.
	ErrNotFound = errors.New("not found")
	// ErrInvalidAuthKey is returned for unknown, revoked, expired or used-up auth keys.
	ErrInvalidAuthKey = errors.New("invalid or expired auth key")
)
View Source 
var ErrPostgresBackup = errors.New("the database is Postgres: back it up with pg_dump")

ErrPostgresBackup is returned by Backup on Postgres, which has its own tools for that.

Functions

func SanitizeName 

func SanitizeName(hostname string) string

SanitizeName turns a hostname into a DNS label: lowercase letters, digits and hyphens, at most 63 characters.

func ValidateCredentials 

func ValidateCredentials(username, password string) error

ValidateCredentials checks username and password requirements.

Types

type APIToken 

type APIToken struct {
	ID          string
	Description string
	AdminID     string
	Admin       string // username
	CreatedAt   time.Time
	ExpiresAt   *time.Time
	LastUsed    *time.Time
}

APIToken lets scripts call the admin API as the admin who created it.

type Admin 

type Admin struct {
	ID        string
	Username  string
	CreatedAt time.Time
	// HasPassword is false for admins who sign in through OIDC only.
	HasPassword bool
}

Admin is a user of the configuration UI.

type AuditEntry 

type AuditEntry struct {
	ID int64
	// Time is set by AppendAudit.
	Time time.Time
	// Actor is the admin's username, or e.g. "cli" or "policy".
	Actor  string
	Action string
	Target string
	Detail string
}

AuditEntry records an administrative change.

type AuthKey 

type AuthKey struct {
	ID          string
	Description string
	Reusable    bool
	UsedCount   int
	Revoked     bool
	// Tags are given to nodes the key enrolls.
	Tags      []string
	CreatedAt time.Time
	ExpiresAt *time.Time
}

AuthKey is a pre-auth key used to enroll nodes. The secret itself is only returned once, at creation time.

func (AuthKey) Valid 

func (k AuthKey) Valid(now time.Time) bool

Valid reports whether the key can still enroll a node at time now.

type AuthKeyOptions 

type AuthKeyOptions struct {
	Description string
	Reusable    bool
	// TTL is the key lifetime; zero means it never expires.
	TTL  time.Duration
	Tags []string
}

AuthKeyOptions configures a new auth key.

type Node 

type Node struct {
	ID          string
	Name        string
	Hostname    string
	OS          string
	WGPublicKey [32]byte
	IPv4        netip.Addr
	Endpoints   []string
	Tags        []string
	// AdvertisedRoutes are the subnet routes the node offers to forward
	// (0.0.0.0/0 for an exit node); ApprovedRoutes are those an admin or the
	// policy allowed. Routes() is what is in effect.
	AdvertisedRoutes []netip.Prefix
	ApprovedRoutes   []netip.Prefix
	CreatedAt        time.Time
	LastSeen         time.Time
	// ExpiresAt is when the node must re-authenticate; nil means never.
	ExpiresAt *time.Time
	// ExpiryDisabled exempts the node from key expiry.
	ExpiryDisabled bool
}

Node is a machine enrolled in the mesh.

func (Node) Expired 

func (n Node) Expired(now time.Time) bool

Expired reports whether the node's key has expired at now.

func (Node) Routes 

func (n Node) Routes() []netip.Prefix

Routes returns the routes in effect: advertised and approved.

type RegisterRequest 

type RegisterRequest struct {
	AuthKey     string
	WGPublicKey [32]byte
	Hostname    string
	OS          string
	// Prefix is the overlay network new addresses are allocated from.
	Prefix netip.Prefix
	// KeyExpiry is how long the node may stay connected before it has to
	// re-authenticate with an auth key; zero means indefinitely.
	KeyExpiry time.Duration
}

RegisterRequest holds what a node presents when enrolling.

type Store 

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

Store is a handle to the coordinator database.

func Open 

func Open(ctx context.Context, dataDir string) (*Store, error)

Open opens (creating if needed) the database in dataDir and applies migrations.

func OpenFile 

func OpenFile(ctx context.Context, path string) (*Store, error)

OpenFile opens a database file directly (e.g. a backup), applying migrations.

func OpenMemory 

func OpenMemory(ctx context.Context) (*Store, error)

OpenMemory opens a private in-memory database, for tests.

func OpenPostgres 

func OpenPostgres(ctx context.Context, dsn string) (*Store, error)

OpenPostgres opens a Postgres database (a postgres:// URL or key=value DSN) and applies migrations. One coordinator should use it at a time: online state lives in the coordinator's memory.

func (*Store) AdminCount 

func (s *Store) AdminCount(ctx context.Context) (int, error)

AdminCount returns the number of admins.

func (*Store) AppendAudit 

func (s *Store) AppendAudit(ctx context.Context, e AuditEntry) error

AppendAudit adds an entry to the audit log.

func (*Store) Authenticate 

func (s *Store) Authenticate(ctx context.Context, username, password string) (Admin, error)

Authenticate checks a username and password.

func (*Store) Backup 

func (s *Store) Backup(ctx context.Context, path string) error

Backup writes a consistent copy of the database to path, which must not exist. It is safe while the coordinator is running.

func (*Store) ChangePassword 

func (s *Store) ChangePassword(ctx context.Context, adminID, current, next, keepSessionToken string) error

ChangePassword replaces an admin's password after checking the current one, and ends all of that admin's other sessions.

func (*Store) Check 

func (s *Store) Check(ctx context.Context) error

Check runs SQLite's integrity check.

func (*Store) Close 

func (s *Store) Close() error

Close closes the database.

func (*Store) CreateAPIToken 

func (s *Store) CreateAPIToken(ctx context.Context, adminID, description string, ttl time.Duration) (APIToken, string, error)

CreateAPIToken creates a token for adminID and returns it with its secret, which is not stored. A zero ttl never expires.

func (*Store) CreateAdmin 

func (s *Store) CreateAdmin(ctx context.Context, username, password string) (Admin, error)

CreateAdmin adds another admin.

func (*Store) CreateAuthKey 

func (s *Store) CreateAuthKey(ctx context.Context, opts AuthKeyOptions) (AuthKey, string, error)

CreateAuthKey creates a key and returns it with its one-time-visible secret.

func (*Store) CreateFirstAdmin 

func (s *Store) CreateFirstAdmin(ctx context.Context, username, password string) (Admin, error)

CreateFirstAdmin creates the initial admin. It fails with ErrSetupDone if any admin exists, atomically, so two concurrent setups cannot both win.

func (*Store) CreateSession 

func (s *Store) CreateSession(ctx context.Context, adminID string, ttl time.Duration) (string, time.Time, error)

CreateSession starts a session for an admin and returns its token.

func (*Store) DeleteAPIToken 

func (s *Store) DeleteAPIToken(ctx context.Context, id string) error

DeleteAPIToken revokes a token.

func (*Store) DeleteNode 

func (s *Store) DeleteNode(ctx context.Context, id string) error

DeleteNode removes a node; its address becomes free for reuse.

func (*Store) DeleteSession 

func (s *Store) DeleteSession(ctx context.Context, token string) error

DeleteSession ends a session.

func (*Store) EnsureAuthKey 

func (s *Store) EnsureAuthKey(ctx context.Context, secret string, opts AuthKeyOptions) (AuthKey, error)

EnsureAuthKey makes sure a key with the given secret exists, creating it with opts if needed. It is used to bootstrap a coordinator from config.

func (*Store) ExpireNode 

func (s *Store) ExpireNode(ctx context.Context, id string) (Node, error)

ExpireNode expires a node's key now: it must re-authenticate.

func (*Store) ListAPITokens 

func (s *Store) ListAPITokens(ctx context.Context) ([]APIToken, error)

ListAPITokens returns all tokens, newest first.

func (*Store) ListAudit 

func (s *Store) ListAudit(ctx context.Context, limit int, before int64) ([]AuditEntry, error)

ListAudit returns up to limit entries older than before (all when before is 0), newest first.

func (*Store) ListAuthKeys 

func (s *Store) ListAuthKeys(ctx context.Context) ([]AuthKey, error)

ListAuthKeys returns all keys, newest first.

func (*Store) ListNodes 

func (s *Store) ListNodes(ctx context.Context) ([]Node, error)

ListNodes returns all nodes ordered by address.

func (*Store) NodeByID 

func (s *Store) NodeByID(ctx context.Context, id string) (Node, error)

NodeByID returns a node by ID.

func (*Store) NodeByName 

func (s *Store) NodeByName(ctx context.Context, name string) (Node, error)

NodeByName returns a node by name.

func (*Store) NodeByToken 

func (s *Store) NodeByToken(ctx context.Context, token string) (Node, error)

NodeByToken returns the node that owns token.

func (*Store) OIDCAdmin 

func (s *Store) OIDCAdmin(ctx context.Context, subject, username string) (Admin, error)

OIDCAdmin returns the admin linked to an OIDC subject ("<issuer> <sub>"), creating one named username on first sign-in. Such admins have no password. An existing password admin with the same name is never linked: that could hand their account to whoever controls the identity provider account, so it is reported as ErrConflict instead.

func (*Store) Postgres 

func (s *Store) Postgres() bool

Postgres reports whether the store is backed by Postgres.

func (*Store) RegisterNode 

func (s *Store) RegisterNode(ctx context.Context, req RegisterRequest) (Node, string, error)

RegisterNode validates the auth key and enrolls the node, or re-enrolls it if its WireGuard key is already known. It returns the node and a new token; any previous token for the node stops working.

func (*Store) RenameNode 

func (s *Store) RenameNode(ctx context.Context, id, name string) (Node, error)

RenameNode changes a node's name, sanitising it to a DNS label.

func (*Store) RevokeAuthKey 

func (s *Store) RevokeAuthKey(ctx context.Context, id string) error

RevokeAuthKey marks a key unusable. Nodes it enrolled are unaffected.

func (*Store) SessionAdmin 

func (s *Store) SessionAdmin(ctx context.Context, token string) (Admin, error)

SessionAdmin returns the admin owning a valid session token.

func (*Store) SetAdvertisedRoutes 

func (s *Store) SetAdvertisedRoutes(ctx context.Context, id string, routes []netip.Prefix) error

SetAdvertisedRoutes records the routes a node offers.

func (*Store) SetApprovedRoutes 

func (s *Store) SetApprovedRoutes(ctx context.Context, id string, routes []netip.Prefix) (Node, error)

SetApprovedRoutes replaces the routes a node may use.

func (*Store) SetNodeExpiry 

func (s *Store) SetNodeExpiry(ctx context.Context, id string, disabled bool, ttl time.Duration) (Node, error)

SetNodeExpiry exempts a node from key expiry, or subjects it again with a fresh expiry ttl from now (none when ttl is zero).

func (*Store) SetNodeTags 

func (s *Store) SetNodeTags(ctx context.Context, id string, tags []string) (Node, error)

SetNodeTags replaces a node's tags.

func (*Store) SetSetting 

func (s *Store) SetSetting(ctx context.Context, key, value string) error

SetSetting stores a setting.

func (*Store) Setting 

func (s *Store) Setting(ctx context.Context, key string) (string, error)

Setting returns a setting's value, or "" if unset.

func (*Store) TokenAdmin 

func (s *Store) TokenAdmin(ctx context.Context, secret string) (Admin, string, error)

TokenAdmin returns the admin a valid token acts as, and the token's ID.

func (*Store) TouchNode 

func (s *Store) TouchNode(ctx context.Context, id string) error

TouchNode updates a node's last-seen time.

func (*Store) UpdateNodeEndpoints 

func (s *Store) UpdateNodeEndpoints(ctx context.Context, id string, endpoints []string) error

UpdateNodeEndpoints records the endpoints a node reported and marks it seen.

type ValidationError 

type ValidationError struct{ Msg string }

ValidationError reports input that breaks a rule (as opposed to a failure).

func (*ValidationError) Error 

func (e *ValidationError) Error() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.