api

Documentation

Overview

Package api serves /api/v1, the machine contract of Sextant: sxctl, CI, AI agents and any future frontend are all clients of this surface. Handlers are thin: decode -> one service call -> encode.

Index

• type API
  • func New(s Services, authz Authz, token string, write bool, log *slog.Logger) *API
  • func (a *API) Routes(mux *http.ServeMux)
• type Authz
• type CheckinAPI
  • func NewCheckin(inv *app.InventoryService, devs DeviceAuthenticator, sharedToken string) *CheckinAPI
  • func (c *CheckinAPI) Routes(mux *http.ServeMux)
  • func (c *CheckinAPI) WithClock(now func() time.Time) *CheckinAPI
  • func (c *CheckinAPI) WithDeviceSecrets(secrets *app.DeviceSecretsService) *CheckinAPI
  • func (c *CheckinAPI) WithDiagnostics(diag *app.DiagnosticsService) *CheckinAPI
  • func (c *CheckinAPI) WithElevation(svc *app.ElevationService) *CheckinAPI
  • func (c *CheckinAPI) WithIntent(intent func(ctx context.Context, tag string) string) *CheckinAPI
  • func (c *CheckinAPI) WithIntentKey(key []byte) *CheckinAPI
  • func (c *CheckinAPI) WithLifecycle(retired func(tag string) bool) *CheckinAPI
  • func (c *CheckinAPI) WithLog(log *slog.Logger) *CheckinAPI
  • func (c *CheckinAPI) WithProvision(provision func(ctx context.Context, c observed.CheckIn) error) *CheckinAPI
• type DeviceAuthAPI
  • func NewDeviceAuth(devs *app.DeviceCredentials, gateToken string) *DeviceAuthAPI
  • func (a *DeviceAuthAPI) Routes(mux *http.ServeMux)
• type DeviceAuthenticator
• type Services
• type SessionSource
• type StationAPI
  • func NewStation(svc *app.DiscoveryService, imaging *app.ImagingService, ...) *StationAPI
  • func (s *StationAPI) Routes(mux *http.ServeMux)
  • func (s *StationAPI) WithConfig(w fleetWriter) *StationAPI
  • func (s *StationAPI) WithSecrets(sink secretSink) *StationAPI
• type StationAuthenticator
• type TokenAuthenticator

Types

type API

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

API is the /api/v1 handler group.

func New

func New(s Services, authz Authz, token string, write bool, log *slog.Logger) *API

New builds the API. Principals: a bearer token (service, owner everywhere) or a browser session (human, per-scope roles). No token and no session source disables the surface, so an unconfigured deployment exposes nothing by accident. write=false serves reads only.

func (*API) Routes

func (a *API) Routes(mux *http.ServeMux)

Routes registers the API on mux.

type Authz

type Authz struct {
	Sessions       SessionSource
	Tokens         TokenAuthenticator
	BaselineViewer []string
	BaselineEditor []string
	BaselineOwner  []string
}

Authz derives per-scope roles from the current fleet document. Baselines are the server-configured org-wide groups.

type CheckinAPI

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

CheckinAPI serves the device-facing check-in endpoint. Two auth modes, preferring the strong one: a per-device credential (the device proves it is the tag it reports), or the shared bridge token (migration only, any device can report any tag - kept until every device is re-issued).

func NewCheckin

func NewCheckin(inv *app.InventoryService, devs DeviceAuthenticator, sharedToken string) *CheckinAPI

NewCheckin builds the check-in surface. Both auth sources are optional but at least one must be set or check-in is disabled.

func (*CheckinAPI) Routes

func (c *CheckinAPI) Routes(mux *http.ServeMux)

Routes registers the device-facing endpoints.

func (*CheckinAPI) WithClock

func (c *CheckinAPI) WithClock(now func() time.Time) *CheckinAPI

WithClock injects the clock (tests).

func (*CheckinAPI) WithDeviceSecrets

func (c *CheckinAPI) WithDeviceSecrets(secrets *app.DeviceSecretsService) *CheckinAPI

WithDeviceSecrets wires the escrow store for provisioning-minted LUKS recovery keys (design 0009).

func (*CheckinAPI) WithDiagnostics

func (c *CheckinAPI) WithDiagnostics(diag *app.DiagnosticsService) *CheckinAPI

WithDiagnostics wires the sealed bundle store for the diagnostics upload (design 0010). nil (or the deployment kill switch) leaves the endpoint answering 503, so a device retries rather than dropping its bundle.

func (*CheckinAPI) WithElevation

func (c *CheckinAPI) WithElevation(svc *app.ElevationService) *CheckinAPI

WithElevation enables the elevation-request endpoints. Without it they are absent rather than failing, so a console deployed without the queue does not advertise a door that leads nowhere.

func (*CheckinAPI) WithIntent

func (c *CheckinAPI) WithIntent(intent func(ctx context.Context, tag string) string) *CheckinAPI

WithIntent wires the pending-intent lookup (from the config snapshot, falling back to the provisioning wizard's derived intent).

func (*CheckinAPI) WithIntentKey

func (c *CheckinAPI) WithIntentKey(key []byte) *CheckinAPI

WithIntentKey enables the wipe replay guard (design 0004): the wipe intent is signed with this key and the wipe ack is verified against it. Empty leaves the guard off.

func (*CheckinAPI) WithLifecycle

func (c *CheckinAPI) WithLifecycle(retired func(tag string) bool) *CheckinAPI

WithLifecycle wires the retired-tag predicate (from the config snapshot).

func (*CheckinAPI) WithLog

func (c *CheckinAPI) WithLog(log *slog.Logger) *CheckinAPI

WithLog wires a logger (the capability passes the process logger; tests and older call sites fall back to slog.Default).

func (*CheckinAPI) WithProvision

func (c *CheckinAPI) WithProvision(provision func(ctx context.Context, c observed.CheckIn) error) *CheckinAPI

WithProvision wires the provisioning-wizard advancement hook.

type DeviceAuthAPI

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

DeviceAuthAPI answers credential-verification questions for the gate.

func NewDeviceAuth

func NewDeviceAuth(devs *app.DeviceCredentials, gateToken string) *DeviceAuthAPI

NewDeviceAuth wires the endpoint. An empty token leaves it MOUNTED BUT CLOSED rather than absent: a deployment that forgot the token should refuse every call, not quietly answer them.

func (*DeviceAuthAPI) Routes

func (a *DeviceAuthAPI) Routes(mux *http.ServeMux)

Routes mounts the endpoint.

type DeviceAuthenticator

type DeviceAuthenticator interface {
	AuthenticateTag(ctx context.Context, secret, claimedTag string) bool
	// HasCredential reports whether a tag already holds a credential of its
	// own, so the bridge token can be refused for it. The error is returned
	// rather than folded into the bool: "we could not tell" and "it has
	// none" must not look the same on an auth path.
	HasCredential(ctx context.Context, tag string) (bool, error)
}

DeviceAuthenticator verifies a per-device credential against a claimed tag (ADR 0008). Implemented by app.DeviceCredentials.

type Services

type Services struct {
	Config    *app.ConfigService
	Changes   *app.ChangeService
	Rollouts  *app.RolloutService
	Inventory *app.InventoryService
	Tokens    *app.TokenService
	DevCreds  *app.DeviceCredentials
	Prefs     ports.PrefsStore
	Directory ports.Directory
	Evidence  *app.EvidenceService
}

Services bundles the use-case services the API exposes. Changes, Rollouts and Inventory are optional: nil leaves their endpoints unregistered.

type SessionSource

type SessionSource interface {
	SessionUser(r *http.Request) (identity.User, string, bool)
}

SessionSource lets humans use the API with a browser session (the UI and htmx calls). Implemented by the oidc adapter; nil means token-only.

type StationAPI

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

StationAPI serves the imaging-station endpoints. A station reports the devices it has seen over PXE (discovery), claims the image jobs an operator dispatched, and reports install progress. Auth prefers a per-station credential (the station proves it is the tag it reports); a shared bridge token is accepted only as a labelled migration path, like the check-in endpoint.

func NewStation

func NewStation(svc *app.DiscoveryService, imaging *app.ImagingService, devCreds deviceCredIssuer, stations StationAuthenticator, sharedToken string, log *slog.Logger) *StationAPI

NewStation builds the station-report surface. At least one auth source must be set or the endpoint is disabled (fail-closed). imaging/devCreds may be nil (the job endpoints then report as unavailable).

func (*StationAPI) Routes

func (s *StationAPI) Routes(mux *http.ServeMux)

Routes registers the station-facing endpoints.

func (*StationAPI) WithConfig

func (s *StationAPI) WithConfig(w fleetWriter) *StationAPI

WithConfig wires the fleet document so an installed device's SSH host public key is recorded against its asset record. Returns the receiver for chaining at construction.

func (*StationAPI) WithSecrets

func (s *StationAPI) WithSecrets(sink secretSink) *StationAPI

WithSecrets wires the per-device secret store so an installed device's LUKS recovery key is sealed at rest instead of kept in the job message. Returns the receiver for chaining at construction.

type StationAuthenticator

type StationAuthenticator interface {
	AuthenticateTag(ctx context.Context, secret, claimedTag string) bool
	// HasCredential reports whether a station already holds a credential of
	// its own, so the bridge token can be refused for it. See the identical
	// method on DeviceAuthenticator (checkin.go) for why the error is
	// returned rather than folded into the bool.
	HasCredential(ctx context.Context, tag string) (bool, error)
}

StationAuthenticator verifies a per-station credential against a claimed station tag (ADR 0008). Implemented by app.StationCredentials.

type TokenAuthenticator

type TokenAuthenticator interface {
	Authenticate(ctx context.Context, secret string) (identity.User, identity.Role, bool)
}

TokenAuthenticator resolves a bearer secret to a principal plus an optional ceiling role (ADR 0008). Implemented by app.TokenService.