storage

type BootstrapToken struct {
	ID          string
	TokenHash   string
	Role        string
	OwnerID     string
	MaxUsages   int
	UsagesCount int
	Description string
	CreatedAt   time.Time
	ExpiresAt   time.Time
	// RevokedAt is set by RevokeBootstrapToken - a soft revoke, distinct from
	// natural expiry, since enrollment_requests.token_id has a foreign key
	// into this table and a hard delete would break that trail. Nil means
	// never revoked.
	RevokedAt *time.Time
	// AutonomousRecovery is copied onto every node this token enrolls; see
	// EnrolledNode.AutonomousRecovery.
	AutonomousRecovery bool
	// Ephemeral is copied onto every node this token enrolls; see
	// EnrolledNode.Ephemeral.
	Ephemeral bool
}

type EnrolledNode struct {
	PeerID         string
	PublicKey      []byte
	Biscuit        []byte
	Role           string
	EnrollmentType string
	ClaimsJSON     string
	OwnerID        string
	// Labels are the attested key=value claims minted into the node's
	// biscuit; kept on the record so token refreshes re-mint them unchanged.
	Labels     map[string]string
	EnrolledAt time.Time
	ExpiresAt  time.Time
	Banned     bool
	// AutonomousRecovery lets /refresh re-issue this node's biscuit after the
	// key that signed it has been retired, on proof of possession alone. Off
	// by default: without it a bootstrap node offline past the key grace
	// period needs an operator to mint a new token, which is what stops a
	// forgotten or stolen machine from rejoining on its own. Only ever set
	// server-side, from the token that enrolled the node or by an admin.
	AutonomousRecovery bool
	// Ephemeral marks a member enrolled by an ephemeral bootstrap token: a
	// fleet member, a probe, a CI job. Such a member is forgotten soon after
	// it falls silent (DeleteSilentBootstrapNodes), where a regular one is
	// kept for the full retention. Copied from the token at enrollment.
	Ephemeral bool
}

type EnrollmentRequest struct {
	ID        string
	PeerID    string
	PublicKey []byte
	TokenID   string
	Status    api.EnrollmentStatus
	// Labels are the operator-declared key=value claims, surfaced to the
	// approving admin; approval attests them into the minted biscuit.
	Labels       map[string]string
	BiscuitToken []byte
	CreatedAt    time.Time
	ResolvedAt   *time.Time
	ResolvedBy   string
}

type KeyPair struct {
	Private    ed25519.PrivateKey
	Public     ed25519.PublicKey
	Expiration time.Time
}

type NodeCount struct {
	Role  string
	State NodeState
	Count int
}

type NodeCursor struct {
	EnrolledAt time.Time
	PeerID     string
}

type NodeFilter struct {
	// States keeps the nodes in any of these states at Now, time.Now() if zero.
	States []NodeState
	Now    time.Time
	// OwnerID nil means every owner; any other value, even "", keeps only
	// that owner's nodes.
	OwnerID *string
	Role    string
	// After resumes from the last row of the previous page. Limit 0 is no limit.
	After *NodeCursor
	Limit int
}

type NodeState string

type OIDCKeyPair struct {
	Kid        string
	PrivateKey []byte
	PublicKey  []byte
	Expiration time.Time
}

type RouterLease struct {
	PeerID         string
	Addresses      []string
	LastRenewal    time.Time
	ExpiresAt      time.Time
	ConnectedPeers []string
	DHTSize        int
	// The router's load as of this lease: open inbound connections and the
	// number it accepts. Listed on /info for members to choose routers by.
	Connections     int
	ConnectionLimit int
}

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

type Store interface {
	// Ping checks the health of the underlying database connection.
	Ping(ctx context.Context) error

	// GetCurrentKey retrieves the active key pair for biscuit signing.
	GetCurrentKey(ctx context.Context) (ed25519.PrivateKey, ed25519.PublicKey, error)

	// GetAllValidKeys retrieves the active key pair and any non-expired historical key pairs.
	GetAllValidKeys(ctx context.Context) ([]KeyPair, error)

	// GetAllValidPublicKeys is GetAllValidKeys for verifiers: the same key
	// set without the private halves.
	GetAllValidPublicKeys(ctx context.Context) ([]ed25519.PublicKey, error)

	// RotateKeys rotates the current key to a new key pair and sets the expiration of the old key.
	RotateKeys(ctx context.Context, newPriv ed25519.PrivateKey, newPub ed25519.PublicKey, gracePeriod time.Duration) error

	// ClaimKeyRotation atomically claims the next scheduled key-rotation
	// window, so multiple control-plane replicas sharing one database rotate
	// keys exactly once per interval instead of racing independently. It
	// returns true if the caller won the claim (advancing the deadline by
	// interval), false if another replica already claimed this window.
	ClaimKeyRotation(ctx context.Context, now time.Time, interval time.Duration) (bool, error)

	// ReleaseKeyRotationClaim reverts a claim won via ClaimKeyRotation with
	// the same now/interval back to its pre-claim deadline, so the window
	// can be retried without waiting a full interval. Callers use this when
	// the rotation that followed a successful claim failed.
	ReleaseKeyRotationClaim(ctx context.Context, now time.Time, interval time.Duration) error

	// ScheduleKeyRotationIfUnset sets the first rotation deadline of a store
	// that never had one, and reports whether it did. A store that already
	// carries a deadline, due or not, is left as it is.
	ScheduleKeyRotationIfUnset(ctx context.Context, at time.Time) (bool, error)

	// NextKeyRotation is the deadline ClaimKeyRotation will honour: the
	// instant the next rotation is due, zero when none was ever scheduled.
	NextKeyRotation(ctx context.Context) (time.Time, error)

	// SaveInitialKey sets the initial key pair if no keys exist yet.
	SaveInitialKey(ctx context.Context, priv ed25519.PrivateKey, pub ed25519.PublicKey) error

	// SetKeyring makes the keyring reflect a set the operator owns, in one
	// transaction: current becomes the signing key, each of verifying stays
	// valid for verification for as long as the operator lists it, and any
	// other key still valid in the store is given gracePeriod to expire so
	// that credentials it signed keep verifying meanwhile. Keys already
	// present are updated in place, so the same set applied twice is a
	// no-op and a key moved back to the front becomes current again.
	// Expired rows are purged first.
	SetKeyring(ctx context.Context, current KeyPair, verifying []KeyPair, gracePeriod time.Duration) error

	// SaveUser creates or updates a User.
	SaveUser(ctx context.Context, user *User) error

	// GetUser retrieves a User by ID.
	GetUser(ctx context.Context, id string) (*User, error)

	// ListUsers retrieves all registered users.
	ListUsers(ctx context.Context) ([]User, error)

	// EnrollNode registers or updates a node enrollment. EnrolledAt is when
	// the member was last seen; unset, it is recorded as now, never as the
	// zero time, which the silent-member sweep would read as decades ago.
	EnrollNode(ctx context.Context, node *EnrolledNode) error

	// GetNode retrieves node enrollment details.
	GetNode(ctx context.Context, peerID string) (*EnrolledNode, error)

	// SetNodeBanned updates the banned status of a node. ErrNotFound if no
	// node has that peer ID.
	SetNodeBanned(ctx context.Context, peerID string, banned bool) error

	// IsNodeBanned checks if a node is currently banned.
	IsNodeBanned(ctx context.Context, peerID string) (bool, error)

	// SetNodeAutonomousRecovery toggles EnrolledNode.AutonomousRecovery.
	// Returns ErrNotFound if no such node is enrolled.
	SetNodeAutonomousRecovery(ctx context.Context, peerID string, enabled bool) error

	// SetIdentityBanned bans or unbans an enrolled OIDC identity, keyed as
	// "issuer|subject". A node ban is keyed on a self-generated peer id, so
	// this is what makes a ban survive keypair regeneration.
	SetIdentityBanned(ctx context.Context, identity string, banned bool) error

	// SetNodeAndIdentityBanned is SetNodeBanned and SetIdentityBanned in one
	// transaction, so a failure cannot leave the device banned while its
	// identity may still enroll a new one, or the other way round. An empty
	// identity bans the node alone.
	SetNodeAndIdentityBanned(ctx context.Context, peerID, identity string, banned bool) error

	// IsIdentityBanned checks if an identity is currently banned.
	IsIdentityBanned(ctx context.Context, identity string) (bool, error)

	// ListBannedPeerIDs returns the peer IDs of every currently banned node.
	// Callers publish this as the complete ban set (see
	// ControlPlaneInfoResponse.banned_peer_ids), so it must be the whole list
	// rather than a page of it.
	ListBannedPeerIDs(ctx context.Context) ([]string, error)

	// UpsertRouterLease updates or creates a lease for a agentmesh-router.
	UpsertRouterLease(ctx context.Context, lease *RouterLease) error

	// GetActiveRouters retrieves all routers whose leases are still valid.
	GetActiveRouters(ctx context.Context) ([]RouterLease, error)

	// SaveMeshPolicy persists the mesh configurations.
	SaveMeshPolicy(ctx context.Context, roles []*api.PolicyRole, bindings []*api.PolicyBinding) error

	// GetMeshPolicy loads the mesh configurations.
	GetMeshPolicy(ctx context.Context) ([]*api.PolicyRole, []*api.PolicyBinding, error)

	// SaveEgressDestinations replaces the egress section of the mesh policy
	// (PolicyConfig.egress).
	SaveEgressDestinations(ctx context.Context, egress []*api.EgressDestination) error

	// GetEgressDestinations loads the egress section of the mesh policy.
	GetEgressDestinations(ctx context.Context) ([]*api.EgressDestination, error)

	// SavePolicyDocument replaces roles, bindings and egress destinations in
	// one transaction: a policy post is applied whole or not at all.
	SavePolicyDocument(ctx context.Context, roles []*api.PolicyRole, bindings []*api.PolicyBinding, egress []*api.EgressDestination) error

	// SaveBootstrapToken persists a new bootstrap token.
	SaveBootstrapToken(ctx context.Context, token *BootstrapToken) error

	// GetBootstrapToken retrieves a bootstrap token by its ID (sha256 hash).
	GetBootstrapToken(ctx context.Context, id string) (*BootstrapToken, error)

	// ConsumeBootstrapTokenUsage spends one usage of a token, atomically
	// with the check that a usage is left and that the token is neither
	// expired (as of now) nor revoked. ErrBootstrapTokenUnusable when it is
	// not: a read-then-increment would let concurrent enrollments overshoot
	// max_usages.
	ConsumeBootstrapTokenUsage(ctx context.Context, id string, now time.Time) error

	// RevokeBootstrapToken soft-revokes a token by setting its RevokedAt, so
	// HandleEnroll refuses it even though it may still be within its TTL and
	// usage count. Idempotent: revoking an already-revoked or unknown token
	// is not an error - callers that need to distinguish "unknown" first
	// look the token up with GetBootstrapToken.
	RevokeBootstrapToken(ctx context.Context, id string) error

	// CreateEnrollmentRequest saves a new pending enrollment request.
	CreateEnrollmentRequest(ctx context.Context, req *EnrollmentRequest) error

	// GetEnrollmentRequest retrieves an enrollment request by PeerID.
	GetEnrollmentRequest(ctx context.Context, peerID string) (*EnrollmentRequest, error)

	// GetEnrollmentRequestByID retrieves an enrollment request by ID.
	GetEnrollmentRequestByID(ctx context.Context, id string) (*EnrollmentRequest, error)

	// ListEnrollmentRequests retrieves all enrollment requests.
	ListEnrollmentRequests(ctx context.Context) ([]EnrollmentRequest, error)

	// UpdateEnrollmentRequest updates status, resolved details, and stored Biscuit of a request.
	UpdateEnrollmentRequest(ctx context.Context, id string, status api.EnrollmentStatus, biscuit []byte, resolvedBy string) error

	// ResolveEnrollmentRequest is UpdateEnrollmentRequest for a request that
	// must still be pending: two admins acting on the same request cannot
	// both succeed. ErrEnrollmentAlreadyResolved if it was not pending.
	ResolveEnrollmentRequest(ctx context.Context, id string, status api.EnrollmentStatus, biscuit []byte, resolvedBy string) error

	// ListNodes retrieves the enrolled nodes the filter selects, newest
	// enrollment first. Peer ID breaks ties, so pages neither skip nor repeat a row.
	// A listed node carries no PublicKey and no Biscuit: GetNode reads those.
	ListNodes(ctx context.Context, filter NodeFilter) ([]EnrolledNode, error)

	// CountNodes counts every enrolled node by role and by its state at now.
	CountNodes(ctx context.Context, now time.Time) ([]NodeCount, error)

	// CountEnrollmentRequests counts the enrollment requests by status.
	CountEnrollmentRequests(ctx context.Context) (map[api.EnrollmentStatus]int64, error)

	// DeleteExpiredNodes removes enrolled nodes whose session expired before
	// the given time and that are not banned, returning how many went. A
	// lapsed session already refuses every refresh, so the row only records
	// that the node once existed; a ban, by contrast, is the row, and must
	// outlive the session it was placed on. Nodes with no session bound
	// (zero ExpiresAt) are not removed here; see DeleteSilentBootstrapNodes.
	DeleteExpiredNodes(ctx context.Context, before time.Time) (int64, error)

	// DeleteSilentBootstrapNodes removes enrolled nodes that have no session
	// bound (a bootstrap enrollment) and are not banned, whose last refresh
	// (EnrolledAt, which a refresh rewrites) is before `before`, or before
	// `ephemeralBefore` for a node an ephemeral token enrolled. A member
	// that refreshes keeps its row; one that fell silent for the retention
	// is forgotten, and enrolls again if it comes back. It returns how many
	// regular and how many ephemeral rows went.
	DeleteSilentBootstrapNodes(ctx context.Context, before, ephemeralBefore time.Time) (regular, ephemeral int64, err error)

	// DeleteStaleEnrollmentRequests removes enrollment requests created, or
	// resolved, before `before`, and before `ephemeralBefore` when the token
	// that made them is ephemeral. A resolved request is a record of a
	// decision; a pending one that old was abandoned by its enrollee long
	// ago. It returns how many went.
	DeleteStaleEnrollmentRequests(ctx context.Context, before, ephemeralBefore time.Time) (int64, error)

	// DeleteExpiredBootstrapTokens removes tokens that expired before
	// `before` and that no enrollment request refers to any more; a token
	// is the proof a member gave once, and once its requests are gone
	// nothing points at it. It returns how many went.
	DeleteExpiredBootstrapTokens(ctx context.Context, before time.Time) (int64, error)

	// DeleteExpiredRouterLeases removes router leases that expired before
	// `before`. A router that comes back leases again under its peer ID; a
	// lease long expired is a router that is gone. It returns how many went.
	DeleteExpiredRouterLeases(ctx context.Context, before time.Time) (int64, error)

	// CountRows counts the rows of every table whose size the control plane
	// reports, keyed by table name.
	CountRows(ctx context.Context) (map[string]int64, error)

	// ListBootstrapTokens retrieves all bootstrap tokens.
	ListBootstrapTokens(ctx context.Context) ([]BootstrapToken, error)

	// GetCurrentOIDCKey retrieves the active ES256 key pair for OIDC/STS JWT signing.
	GetCurrentOIDCKey(ctx context.Context) (*OIDCKeyPair, error)

	// GetAllValidOIDCKeys retrieves the active ES256 key pair and any non-expired historical key pairs.
	GetAllValidOIDCKeys(ctx context.Context) ([]OIDCKeyPair, error)

	// SaveInitialOIDCKey saves the initial ES256 key pair if no OIDC keys exist yet.
	SaveInitialOIDCKey(ctx context.Context, kid string, priv, pub []byte) error

	// RotateOIDCKeys rotates the current ES256 key to a new key pair and sets the expiration of the old key.
	RotateOIDCKeys(ctx context.Context, kid string, newPriv, newPub []byte, gracePeriod time.Duration) error

	// SetOIDCKeyring is SetKeyring for the ES256 keyring, keyed by kid.
	SetOIDCKeyring(ctx context.Context, current OIDCKeyPair, verifying []OIDCKeyPair, gracePeriod time.Duration) error

	// SaveRevokedBiscuit persists a Biscuit revocation ID until its expiration time.
	SaveRevokedBiscuit(ctx context.Context, revocationID string, expiresAt time.Time) error

	// ListRevokedBiscuits returns all unexpired Biscuit revocation IDs as of now and prunes expired rows.
	ListRevokedBiscuits(ctx context.Context, now time.Time) (map[string]time.Time, error)

	// IsBiscuitRevoked checks if the given base64url-encoded revocation ID is currently revoked.
	IsBiscuitRevoked(ctx context.Context, revocationID string, now time.Time) (bool, error)

	// Close closes the underlying database connection.
	Close() error
}

type User struct {
	// ID is the OIDC subject. Issuer is the OIDC issuer it came from: the
	// pair is what an identity ban is keyed on (see SetIdentityBanned), and
	// two issuers may hand out the same subject to different people.
	ID        string
	Issuer    string
	Email     string
	Role      string
	CreatedAt time.Time
}