registry

package
v1.6.2 Latest Latest
Warning

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

 Go to latest Published: Apr 9, 2026 License: AGPL-3.0 Imports: 37 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AllowedPortsToPolicy added in v1.6.0 

func AllowedPortsToPolicy(ports []uint16) (json.RawMessage, error)

AllowedPortsToPolicy converts a port allowlist into a PolicyDocument JSON (json.RawMessage). This replaces the old AllowedPorts mechanism with equivalent policy rules.

func RulesToPolicy added in v1.6.0 

func RulesToPolicy(r *NetworkRules) (json.RawMessage, error)

RulesToPolicy converts a NetworkRules struct into a PolicyDocument JSON (json.RawMessage). This provides backward compatibility: existing managed networks continue to work through the policy engine.

func ValidateBlueprint added in v1.5.1 

func ValidateBlueprint(bp *NetworkBlueprint) error

ValidateBlueprint checks a blueprint for configuration errors.

func ValidateRules added in v1.6.0 

func ValidateRules(r *NetworkRules) error

ValidateRules checks that a NetworkRules is well-formed. Returns nil if valid.

Types

type AuditEntry added in v1.5.1 

type AuditEntry struct {
	Timestamp string `json:"timestamp"`
	Action    string `json:"action"`
	NetworkID uint16 `json:"network_id,omitempty"`
	NodeID    uint32 `json:"node_id,omitempty"`
	Details   string `json:"details,omitempty"`
}

AuditEntry records a single audit event.

type AuditExporter added in v1.5.1 

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

AuditExporter sends audit events to an external system in the configured format (Splunk HEC, syslog/CEF, or plain JSON). It runs asynchronously with a buffered channel, just like registryWebhook.

func (*AuditExporter) Close added in v1.5.1 

func (ae *AuditExporter) Close()

Close drains the queue and stops the background goroutine.

func (*AuditExporter) Export added in v1.5.1 

func (ae *AuditExporter) Export(entry *AuditEntry)

Export queues an audit entry for export. Non-blocking; drops if buffer full.

func (*AuditExporter) Stats added in v1.5.1 

func (ae *AuditExporter) Stats() (exported, dropped uint64)

Stats returns export statistics.

type BinaryClient added in v1.6.0 

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

BinaryClient talks to a registry server using the binary wire protocol. It provides native binary encoding for hot-path operations (heartbeat, lookup, resolve) and JSON-over-binary passthrough for all other operations.

func DialBinary added in v1.6.0 

func DialBinary(addr string) (*BinaryClient, error)

DialBinary connects to a registry server and negotiates the binary wire protocol. The server detects the magic bytes and switches to binary mode for this connection.

func (*BinaryClient) Addr added in v1.6.0 

func (c *BinaryClient) Addr() string

Addr returns the registry address this client is connected to.

func (*BinaryClient) Close added in v1.6.0 

func (c *BinaryClient) Close() error

Close shuts down the binary client connection.

func (*BinaryClient) Heartbeat added in v1.6.0 

func (c *BinaryClient) Heartbeat(nodeID uint32, sig []byte) (unixTime int64, keyExpiryWarning bool, err error)

Heartbeat sends a binary heartbeat and returns the server time and key expiry warning.

func (*BinaryClient) Lookup added in v1.6.0 

func (c *BinaryClient) Lookup(nodeID uint32) (*WireLookupResult, error)

Lookup sends a binary lookup request and returns the decoded result.

func (*BinaryClient) Resolve added in v1.6.0 

func (c *BinaryClient) Resolve(nodeID, requesterID uint32, sig []byte) (*WireResolveResult, error)

Resolve sends a binary resolve request and returns the decoded result.

func (*BinaryClient) SendJSON added in v1.6.0 

func (c *BinaryClient) SendJSON(msg map[string]interface{}) (map[string]interface{}, error)

SendJSON sends a JSON message over the binary protocol using JSON passthrough. This allows any registry operation to be used without a native binary encoding.

type BlueprintAuditExport added in v1.5.1 

type BlueprintAuditExport struct {
	Format   string `json:"format"`           // "json", "splunk_hec", "syslog_cef"
	Endpoint string `json:"endpoint"`         // destination URL or address
	Token    string `json:"token,omitempty"`  // auth token (e.g., Splunk HEC token)
	Index    string `json:"index,omitempty"`  // Splunk index
	Source   string `json:"source,omitempty"` // source identifier
}

BlueprintAuditExport configures external audit log export.

type BlueprintIdentityProvider added in v1.5.1 

type BlueprintIdentityProvider struct {
	Type     string `json:"type"`                // "oidc", "saml", "webhook", "entra_id", "ldap"
	URL      string `json:"url"`                 // verification endpoint
	Issuer   string `json:"issuer,omitempty"`    // OIDC issuer URL
	ClientID string `json:"client_id,omitempty"` // OIDC client ID
	TenantID string `json:"tenant_id,omitempty"` // Azure AD / Entra ID tenant
	Domain   string `json:"domain,omitempty"`    // LDAP domain
}

BlueprintIdentityProvider configures external identity verification.

type BlueprintPolicy added in v1.5.1 

type BlueprintPolicy struct {
	MaxMembers   int      `json:"max_members,omitempty"`
	AllowedPorts []uint16 `json:"allowed_ports,omitempty"`
	Description  string   `json:"description,omitempty"`
}

BlueprintPolicy defines the network policy section of a blueprint.

type BlueprintRole added in v1.5.1 

type BlueprintRole struct {
	ExternalID string `json:"external_id"`
	Role       string `json:"role"` // "owner", "admin", "member"
}

BlueprintRole pre-assigns RBAC roles by external identity.

type BlueprintWebhooks added in v1.5.1 

type BlueprintWebhooks struct {
	AuditURL    string `json:"audit_url,omitempty"`    // audit event webhook
	IdentityURL string `json:"identity_url,omitempty"` // identity verification webhook
}

BlueprintWebhooks configures webhook endpoints for the network.

type Client 

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

Client talks to a registry server over TCP (optionally TLS). It automatically reconnects if the connection drops.

func Dial 

func Dial(addr string) (*Client, error)

func DialTLS 

func DialTLS(addr string, tlsConfig *tls.Config) (*Client, error)

DialTLS connects to a registry server over TLS. A non-nil tlsConfig is required. For certificate pinning, use DialTLSPinned.

func DialTLSPinned 

func DialTLSPinned(addr, fingerprint string) (*Client, error)

DialTLSPinned connects to a registry server over TLS with certificate pinning. The fingerprint is a hex-encoded SHA-256 hash of the server's DER-encoded certificate.

func (*Client) CheckTrust added in v1.4.0 

func (c *Client) CheckTrust(nodeA, nodeB uint32) (bool, error)

CheckTrust checks if a trust pair or shared network exists between two nodes.

func (*Client) ClearKeyExpiryAdmin added in v1.5.1 

func (c *Client) ClearKeyExpiryAdmin(nodeID uint32, adminToken string) (map[string]interface{}, error)

ClearKeyExpiryAdmin removes the key expiry from a node using admin token auth.

func (*Client) Close 

func (c *Client) Close() error

func (*Client) CreateManagedNetwork added in v1.6.0 

func (c *Client) CreateManagedNetwork(nodeID uint32, name, joinRule, token, adminToken string, enterprise bool, rules string, networkAdminToken ...string) (map[string]interface{}, error)

CreateManagedNetwork creates a network with managed rules.

func (*Client) CreateNetwork 

func (c *Client) CreateNetwork(nodeID uint32, name, joinRule, token, adminToken string, enterprise bool, networkAdminToken ...string) (map[string]interface{}, error)

func (*Client) DeleteNetwork added in v1.5.1 

func (c *Client) DeleteNetwork(networkID uint16, adminToken string, nodeID ...uint32) (map[string]interface{}, error)

func (*Client) DemoteMember added in v1.5.1 

func (c *Client) DemoteMember(networkID uint16, nodeID, targetNodeID uint32, adminToken string) (map[string]interface{}, error)

DemoteMember demotes an admin to member. Only the owner can demote.

func (*Client) Deregister 

func (c *Client) Deregister(nodeID uint32) (map[string]interface{}, error)

func (*Client) DeregisterAdmin added in v1.5.1 

func (c *Client) DeregisterAdmin(nodeID uint32, adminToken string) (map[string]interface{}, error)

DeregisterAdmin removes a node using admin token auth.

func (*Client) DirectoryStatus added in v1.5.1 

func (c *Client) DirectoryStatus(networkID uint16, adminToken string) (map[string]interface{}, error)

DirectoryStatus returns directory sync status for a network.

func (*Client) DirectorySync added in v1.5.1 

func (c *Client) DirectorySync(networkID uint16, entries []map[string]interface{}, removeUnlisted bool, adminToken string) (map[string]interface{}, error)

DirectorySync pushes a directory listing to update RBAC roles and membership.

func (*Client) GetAuditExport added in v1.5.1 

func (c *Client) GetAuditExport(adminToken string) (map[string]interface{}, error)

GetAuditExport returns the current audit export configuration. Requires admin token.

func (*Client) GetAuditLog added in v1.5.1 

func (c *Client) GetAuditLog(networkID uint16, adminToken string) (map[string]interface{}, error)

GetAuditLog returns recent audit entries from the registry.

func (*Client) GetExprPolicy added in v1.6.0 

func (c *Client) GetExprPolicy(networkID uint16) (map[string]interface{}, error)

GetExprPolicy returns the programmable policy for a network.

func (*Client) GetIDPConfig added in v1.5.1 

func (c *Client) GetIDPConfig(adminToken string) (map[string]interface{}, error)

GetIDPConfig returns the current identity provider configuration. Requires admin token.

func (*Client) GetIdentity added in v1.5.1 

func (c *Client) GetIdentity(nodeID uint32, adminToken string) (map[string]interface{}, error)

GetIdentity returns the external identity of a node. Requires admin token.

func (*Client) GetKeyInfo added in v1.5.1 

func (c *Client) GetKeyInfo(nodeID uint32) (map[string]interface{}, error)

GetKeyInfo returns key lifecycle metadata for a node.

func (*Client) GetMemberRole added in v1.5.1 

func (c *Client) GetMemberRole(networkID uint16, targetNodeID uint32) (map[string]interface{}, error)

GetMemberRole returns the RBAC role of a node in a network.

func (*Client) GetMemberTags added in v1.6.0 

func (c *Client) GetMemberTags(netID uint16, targetNodeID uint32) (map[string]interface{}, error)

GetMemberTags returns admin-assigned member tags for a node (or all members if targetNodeID=0).

func (*Client) GetNetworkPolicy added in v1.5.1 

func (c *Client) GetNetworkPolicy(networkID uint16) (map[string]interface{}, error)

GetNetworkPolicy returns the policy for a given network.

func (*Client) GetPoloScore added in v1.3.0 

func (c *Client) GetPoloScore(nodeID uint32) (int, error)

GetPoloScore retrieves the current polo score for a node.

func (*Client) GetProvisionStatus added in v1.5.1 

func (c *Client) GetProvisionStatus(adminToken string) (map[string]interface{}, error)

GetProvisionStatus returns per-network provisioning status. Requires admin token.

func (*Client) GetWebhook added in v1.5.1 

func (c *Client) GetWebhook(adminToken string) (map[string]interface{}, error)

GetWebhook returns the current webhook configuration.

func (*Client) GetWebhookDLQ added in v1.5.1 

func (c *Client) GetWebhookDLQ(adminToken string) (map[string]interface{}, error)

GetWebhookDLQ returns the dead letter queue (failed webhook events).

func (*Client) Heartbeat 

func (c *Client) Heartbeat(nodeID uint32) (map[string]interface{}, error)

func (*Client) InviteToNetwork added in v1.5.1 

func (c *Client) InviteToNetwork(networkID uint16, inviterID, targetNodeID uint32, adminToken string) (map[string]interface{}, error)

InviteToNetwork stores a pending invite for a target node to join an invite-only network.

func (*Client) JoinNetwork 

func (c *Client) JoinNetwork(nodeID uint32, networkID uint16, token string, inviterID uint32, adminToken string) (map[string]interface{}, error)

func (*Client) KickMember added in v1.5.1 

func (c *Client) KickMember(networkID uint16, nodeID, targetNodeID uint32, adminToken string) (map[string]interface{}, error)

KickMember removes a member from a network. Requires owner or admin role.

func (*Client) LeaveNetwork 

func (c *Client) LeaveNetwork(nodeID uint32, networkID uint16, adminToken string) (map[string]interface{}, error)

func (*Client) ListNetworks 

func (c *Client) ListNetworks() (map[string]interface{}, error)

func (*Client) ListNodes 

func (c *Client) ListNodes(networkID uint16, adminToken ...string) (map[string]interface{}, error)

func (*Client) Lookup 

func (c *Client) Lookup(nodeID uint32) (map[string]interface{}, error)

func (*Client) PollHandshakes 

func (c *Client) PollHandshakes(nodeID uint32) (map[string]interface{}, error)

PollHandshakes retrieves and clears pending handshake requests for a node. H3 fix: includes a signature to prove node identity.

func (*Client) PollInvites added in v1.5.1 

func (c *Client) PollInvites(nodeID uint32) (map[string]interface{}, error)

PollInvites returns and clears pending network invites for a node. Signed.

func (*Client) PromoteMember added in v1.5.1 

func (c *Client) PromoteMember(networkID uint16, nodeID, targetNodeID uint32, adminToken string) (map[string]interface{}, error)

PromoteMember promotes a network member to admin. Only the owner can promote.

func (*Client) ProvisionNetwork added in v1.5.1 

func (c *Client) ProvisionNetwork(blueprint map[string]interface{}, adminToken string) (map[string]interface{}, error)

ProvisionNetwork applies a network blueprint. Requires admin token.

func (*Client) Punch 

func (c *Client) Punch(requesterID, nodeA, nodeB uint32) (map[string]interface{}, error)

func (*Client) Register 

func (c *Client) Register(listenAddr string) (map[string]interface{}, error)

func (*Client) RegisterWithKey 

func (c *Client) RegisterWithKey(listenAddr, publicKeyB64, owner string, lanAddrs []string) (map[string]interface{}, error)

RegisterWithKey re-registers using an existing Ed25519 public key. The registry returns the same node_id if the key is known. lanAddrs are the node's LAN addresses for same-network peer detection.

func (*Client) RegisterWithOwner 

func (c *Client) RegisterWithOwner(listenAddr, owner string) (map[string]interface{}, error)

RegisterWithOwner registers a new node with an owner identifier (email/name) for key rotation recovery.

func (*Client) RenameNetwork added in v1.5.1 

func (c *Client) RenameNetwork(networkID uint16, name, adminToken string, nodeID ...uint32) (map[string]interface{}, error)

func (*Client) ReportTrust 

func (c *Client) ReportTrust(nodeID, peerID uint32) (map[string]interface{}, error)

func (*Client) RequestHandshake 

func (c *Client) RequestHandshake(fromNodeID, toNodeID uint32, justification, signatureB64 string) (map[string]interface{}, error)

RequestHandshake relays a handshake request through the registry to a target node. This works even for private nodes — no IP exposure needed. M12 fix: includes a signature to prove sender identity.

func (*Client) Resolve 

func (c *Client) Resolve(nodeID, requesterID uint32) (map[string]interface{}, error)

func (*Client) ResolveHostname 

func (c *Client) ResolveHostname(hostname string) (map[string]interface{}, error)

ResolveHostname resolves a hostname to node info (node_id, address, public flag).

func (*Client) ResolveHostnameAs added in v1.4.0 

func (c *Client) ResolveHostnameAs(requesterID uint32, hostname string) (map[string]interface{}, error)

ResolveHostnameAs resolves a hostname with a requester_id for privacy checks. Private nodes require the requester to have a trust pair or shared network.

func (*Client) RespondHandshake 

func (c *Client) RespondHandshake(nodeID, peerID uint32, accept bool, signatureB64 string) (map[string]interface{}, error)

RespondHandshake approves or rejects a relayed handshake request. If accepted, the registry creates a mutual trust pair. M12 fix: includes a signature to prove responder identity.

func (*Client) RespondInvite added in v1.5.1 

func (c *Client) RespondInvite(nodeID uint32, networkID uint16, accept bool) (map[string]interface{}, error)

RespondInvite accepts or rejects a pending network invite. Signed.

func (*Client) RevokeTrust 

func (c *Client) RevokeTrust(nodeID, peerID uint32) (map[string]interface{}, error)

func (*Client) RotateKey 

func (c *Client) RotateKey(nodeID uint32, signatureB64, newPubKeyB64 string) (map[string]interface{}, error)

RotateKey requests a key rotation for a node. Requires a signature proving ownership of the current key and the new public key.

func (*Client) Send 

func (c *Client) Send(msg map[string]interface{}) (map[string]interface{}, error)

func (*Client) SetAuditExport added in v1.5.1 

func (c *Client) SetAuditExport(format, endpoint, token, index, source, adminToken string) (map[string]interface{}, error)

SetAuditExport configures the audit export adapter. Requires admin token.

func (*Client) SetExprPolicy added in v1.6.0 

func (c *Client) SetExprPolicy(networkID uint16, policyJSON json.RawMessage, adminToken string) (map[string]interface{}, error)

SetExprPolicy sets the programmable policy for a network. Requires owner/admin role or admin token.

func (*Client) SetExternalID added in v1.5.1 

func (c *Client) SetExternalID(nodeID uint32, externalID, adminToken string) (map[string]interface{}, error)

SetExternalID sets the external identity on a node. Requires admin token.

func (*Client) SetHostname 

func (c *Client) SetHostname(nodeID uint32, hostname string) (map[string]interface{}, error)

SetHostname sets or clears the hostname for a node. An empty hostname clears the current hostname.

func (*Client) SetHostnameAdmin added in v1.5.1 

func (c *Client) SetHostnameAdmin(nodeID uint32, hostname, adminToken string) (map[string]interface{}, error)

SetHostnameAdmin sets a node's hostname using admin token auth.

func (*Client) SetIDPConfig added in v1.5.1 

func (c *Client) SetIDPConfig(idpType, url, issuer, clientID, tenantID, domain, adminToken string) (map[string]interface{}, error)

SetIDPConfig configures the identity provider. Requires admin token.

func (*Client) SetIdentityWebhook added in v1.5.1 

func (c *Client) SetIdentityWebhook(url, adminToken string) (map[string]interface{}, error)

SetIdentityWebhook configures the identity verification webhook URL.

func (*Client) SetKeyExpiry added in v1.5.1 

func (c *Client) SetKeyExpiry(nodeID uint32, expiresAt time.Time) (map[string]interface{}, error)

SetKeyExpiry sets the key expiry time for a node. Requires signature.

func (*Client) SetKeyExpiryAdmin added in v1.5.1 

func (c *Client) SetKeyExpiryAdmin(nodeID uint32, expiresAt time.Time, adminToken string) (map[string]interface{}, error)

SetKeyExpiryAdmin sets a node's key expiry using admin token auth.

func (*Client) SetMemberTags added in v1.6.0 

func (c *Client) SetMemberTags(netID uint16, targetNodeID uint32, tags []string, adminToken string) (map[string]interface{}, error)

SetMemberTags sets admin-assigned tags for a member within a network.

func (*Client) SetNetworkEnterprise added in v1.5.1 

func (c *Client) SetNetworkEnterprise(networkID uint16, enterprise bool, adminToken string) (map[string]interface{}, error)

func (*Client) SetNetworkPolicy added in v1.5.1 

func (c *Client) SetNetworkPolicy(networkID uint16, policy map[string]interface{}, adminToken string) (map[string]interface{}, error)

SetNetworkPolicy sets or updates a network's policy. Requires owner/admin role or admin token.

func (*Client) SetPoloScore added in v1.3.0 

func (c *Client) SetPoloScore(nodeID uint32, poloScore int) (map[string]interface{}, error)

SetPoloScore sets the polo score of a node to a specific value.

func (*Client) SetSigner 

func (c *Client) SetSigner(fn func(challenge string) string)

SetSigner sets a signing function for authenticated registry operations (H3 fix). The signer receives a challenge string and returns a base64-encoded Ed25519 signature.

func (*Client) SetTags 

func (c *Client) SetTags(nodeID uint32, tags []string) (map[string]interface{}, error)

SetTags sets the capability tags for a node.

func (*Client) SetTagsAdmin added in v1.5.1 

func (c *Client) SetTagsAdmin(nodeID uint32, tags []string, adminToken string) (map[string]interface{}, error)

SetTagsAdmin sets a node's tags using admin token auth.

func (*Client) SetTaskExec 

func (c *Client) SetTaskExec(nodeID uint32, enabled bool) (map[string]interface{}, error)

func (*Client) SetTaskExecAdmin added in v1.5.1 

func (c *Client) SetTaskExecAdmin(nodeID uint32, enabled bool, adminToken string) (map[string]interface{}, error)

SetTaskExecAdmin sets a node's task exec flag using admin token auth.

func (*Client) SetVisibility 

func (c *Client) SetVisibility(nodeID uint32, public bool) (map[string]interface{}, error)

func (*Client) SetVisibilityAdmin added in v1.5.1 

func (c *Client) SetVisibilityAdmin(nodeID uint32, public bool, adminToken string) (map[string]interface{}, error)

SetVisibilityAdmin sets a node's visibility using admin token auth.

func (*Client) SetWebhook added in v1.5.1 

func (c *Client) SetWebhook(url, adminToken string) (map[string]interface{}, error)

SetWebhook configures the registry webhook URL. Pass empty string to disable.

func (*Client) TransferOwnership added in v1.5.1 

func (c *Client) TransferOwnership(networkID uint16, ownerNodeID, newOwnerID uint32, adminToken string) (map[string]interface{}, error)

TransferOwnership transfers network ownership to another member. Only the current owner can transfer.

func (*Client) UpdatePoloScore added in v1.3.0 

func (c *Client) UpdatePoloScore(nodeID uint32, delta int) (map[string]interface{}, error)

UpdatePoloScore adjusts the polo score of a node by the given delta. Delta can be positive (increase polo score) or negative (decrease polo score).

func (*Client) ValidateToken added in v1.5.1 

func (c *Client) ValidateToken(token, adminToken string) (map[string]interface{}, error)

ValidateToken validates a JWT token against the configured IDP. Requires admin token.

type DashboardEdge 

type DashboardEdge struct {
	Source string `json:"source"`
	Target string `json:"target"`
}

DashboardEdge represents a trust relationship between two nodes.

type DashboardNode 

type DashboardNode struct {
	Address    string   `json:"address"`
	Tags       []string `json:"tags"`
	Online     bool     `json:"online"`
	TrustLinks int      `json:"trust_links"`
	TaskExec   bool     `json:"task_exec"`
	PoloScore  int      `json:"polo_score"`
}

DashboardNode is a public-safe view of a node for the dashboard.

type DashboardStats 

type DashboardStats struct {
	TotalNodes      int             `json:"total_nodes"`
	ActiveNodes     int             `json:"active_nodes"`
	TotalTrustLinks int             `json:"total_trust_links"`
	TotalRequests   int64           `json:"total_requests"`
	UniqueTags      int             `json:"unique_tags"`
	TaskExecutors   int             `json:"task_executors"`
	Nodes           []DashboardNode `json:"nodes"`
	Edges           []DashboardEdge `json:"edges"`
	UptimeSecs      int64           `json:"uptime_secs"`
}

DashboardStats is the public-safe data returned by the dashboard API.

type DeltaEntry added in v1.6.0 

type DeltaEntry struct {
	SeqNo  uint64          `json:"seq_no"`
	Type   DeltaType       `json:"type"`
	NodeID uint32          `json:"node_id,omitempty"`
	Data   json.RawMessage `json:"data,omitempty"`
}

DeltaEntry records a single state mutation for incremental replication.

type DeltaType added in v1.6.0 

type DeltaType uint8

DeltaType identifies what kind of mutation a delta represents. 

const (
	DeltaRegister      DeltaType = 1
	DeltaDeregister    DeltaType = 2
	DeltaHeartbeat     DeltaType = 3
	DeltaTrustAdd      DeltaType = 4
	DeltaTrustRevoke   DeltaType = 5
	DeltaVisibility    DeltaType = 6
	DeltaHostname      DeltaType = 7
	DeltaTags          DeltaType = 8
	DeltaNetworkCreate DeltaType = 9
	DeltaNetworkJoin   DeltaType = 10
	DeltaNetworkLeave  DeltaType = 11
	DeltaKeyRotation   DeltaType = 12
	DeltaTaskExec      DeltaType = 13
)

type DirectoryEntry added in v1.5.1 

type DirectoryEntry struct {
	ExternalID  string   `json:"external_id"` // unique ID from directory (OIDC sub, email, GUID)
	DisplayName string   `json:"display_name,omitempty"`
	Email       string   `json:"email,omitempty"`
	Groups      []string `json:"groups,omitempty"`   // directory groups
	Role        string   `json:"role,omitempty"`     // desired pilot role: "owner", "admin", "member"
	Disabled    bool     `json:"disabled,omitempty"` // deprovisioned users
}

DirectoryEntry represents a user from an enterprise directory (AD, Entra ID, LDAP).

type DirectorySyncRequest added in v1.5.1 

type DirectorySyncRequest struct {
	NetworkID uint16           `json:"network_id"`
	Entries   []DirectoryEntry `json:"entries"`
	// If true, nodes whose external_id is not in the entries list will be kicked.
	RemoveUnlisted bool `json:"remove_unlisted,omitempty"`
}

DirectorySyncRequest is the protocol payload for directory sync.

type DirectorySyncResult added in v1.5.1 

type DirectorySyncResult struct {
	Updated  int      `json:"updated"`  // roles updated
	Disabled int      `json:"disabled"` // nodes disabled (kicked)
	Mapped   int      `json:"mapped"`   // entries mapped to existing nodes
	Unmapped int      `json:"unmapped"` // entries with no matching node
	Actions  []string `json:"actions"`
}

DirectorySyncResult describes what the sync operation did.

type HandshakeRelayMsg 

type HandshakeRelayMsg struct {
	FromNodeID    uint32    `json:"from_node_id"`
	Justification string    `json:"justification"`
	Timestamp     time.Time `json:"timestamp"`
}

HandshakeRelayMsg is a handshake request stored in the registry's relay inbox.

type HandshakeResponseMsg 

type HandshakeResponseMsg struct {
	FromNodeID uint32    `json:"from_node_id"` // the node that approved/rejected
	Accept     bool      `json:"accept"`
	Timestamp  time.Time `json:"timestamp"`
}

HandshakeResponseMsg is a handshake approval/rejection stored for the original requester.

type KeyInfo added in v1.5.1 

type KeyInfo struct {
	CreatedAt   time.Time `json:"created_at"`
	RotatedAt   time.Time `json:"rotated_at,omitempty"` // zero if never rotated
	RotateCount int       `json:"rotate_count"`
	ExpiresAt   time.Time `json:"expires_at,omitempty"` // zero = no expiry
}

KeyInfo tracks key lifecycle metadata for compliance and trust decisions.

type NetworkBlueprint added in v1.5.1 

type NetworkBlueprint struct {
	// Network settings
	Name       string `json:"name"`
	JoinRule   string `json:"join_rule,omitempty"`  // "open", "token", "invite" (default: "open")
	JoinToken  string `json:"join_token,omitempty"` // required if join_rule = "token"
	Enterprise bool   `json:"enterprise,omitempty"` // enable enterprise features

	// Policy
	Policy *BlueprintPolicy `json:"policy,omitempty"`

	// RBAC pre-assignments (by external_id)
	Roles []BlueprintRole `json:"roles,omitempty"`

	// Identity provider configuration
	IdentityProvider *BlueprintIdentityProvider `json:"identity_provider,omitempty"`

	// Observability
	Webhooks *BlueprintWebhooks `json:"webhooks,omitempty"`

	// Audit export
	AuditExport *BlueprintAuditExport `json:"audit_export,omitempty"`

	// Per-network admin token (optional override)
	NetworkAdminToken string `json:"network_admin_token,omitempty"`
}

NetworkBlueprint defines a declarative configuration for provisioning an enterprise network. Enterprises apply blueprints via the registry protocol or the pilotctl CLI to create and configure networks in one shot.

func LoadBlueprint added in v1.5.1 

func LoadBlueprint(path string) (*NetworkBlueprint, error)

LoadBlueprint reads a network blueprint from a JSON file.

type NetworkInfo 

type NetworkInfo struct {
	ID          uint16
	Name        string
	JoinRule    string
	Token       string // for token-gated networks
	Members     []uint32
	MemberRoles map[uint32]Role     // per-member RBAC roles
	MemberTags  map[uint32][]string // admin-assigned per-member tags (e.g. "service")
	AdminToken  string              // per-network admin token (optional)
	Policy      NetworkPolicy       // network policy (membership limits, port restrictions)
	Rules       *NetworkRules       // managed network rules (nil = normal network)
	ExprPolicy  json.RawMessage     // programmable policy engine document (nil = none)
	Enterprise  bool                // enterprise network (gates Phase 2-5 features)
	Created     time.Time
}

type NetworkInvite added in v1.5.1 

type NetworkInvite struct {
	NetworkID uint16    `json:"network_id"`
	InviterID uint32    `json:"inviter_id"`
	Timestamp time.Time `json:"timestamp"`
}

NetworkInvite is a pending network invitation stored in the registry's invite inbox.

type NetworkPolicy added in v1.5.1 

type NetworkPolicy struct {
	MaxMembers   int      `json:"max_members"`   // 0 = unlimited
	AllowedPorts []uint16 `json:"allowed_ports"` // empty = all ports allowed
	Description  string   `json:"description"`   // human-readable network description
}

NetworkPolicy defines constraints and metadata for a network.

type NetworkRules added in v1.6.0 

type NetworkRules struct {
	Links   int    `json:"links"`           // max managed peers per node
	Cycle   string `json:"cycle"`           // Go duration: "24h", "1h"
	Prune   int    `json:"prune"`           // how many to drop per cycle
	PruneBy string `json:"prune_by"`        // "score", "age", "activity"
	Fill    int    `json:"fill"`            // how many to add per cycle
	FillHow string `json:"fill_how"`        // "random"
	Grace   string `json:"grace,omitempty"` // grace period for new members
}

NetworkRules defines the managed network ruleset. When set on a NetworkInfo, the network becomes "managed" — daemon-local link lifecycle is governed by these rules. The registry only stores and distributes the rules; all cycle logic runs inside each daemon.

func ParseRules added in v1.6.0 

func ParseRules(raw string) (*NetworkRules, error)

ParseRules unmarshals a JSON string into NetworkRules and validates it.

type NodeInfo 

type NodeInfo struct {
	ID         uint32
	Owner      string // email or identifier (for key rotation)
	PublicKey  []byte
	RealAddr   string
	Networks   []uint16
	LastSeen   time.Time // used during registration (under s.mu.Lock); heartbeat uses lastSeenNano
	Public     bool      // if true, endpoint is visible in lookup/list_nodes
	Hostname   string    // unique hostname for discovery (empty = none)
	Tags       []string  // capability tags (e.g., "webserver", "assistant")
	PoloScore  int       // polo score for reputation system (default: 0)
	TaskExec   bool      // if true, node advertises task execution capability
	LANAddrs   []string  // LAN addresses for same-network peer detection
	KeyMeta    KeyInfo   // key lifecycle metadata
	ExternalID string    // verified external identity (e.g., OIDC sub, email from IdP)
	// contains filtered or unexported fields
}

type OperationRateLimiter added in v1.5.1 

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

OperationRateLimiter provides per-operation rate limiting using separate token buckets for each operation category. Each category has its own rate.

func NewOperationRateLimiter added in v1.5.1 

func NewOperationRateLimiter() *OperationRateLimiter

NewOperationRateLimiter creates a rate limiter with per-operation categories.

func (*OperationRateLimiter) AddCategory added in v1.5.1 

func (orl *OperationRateLimiter) AddCategory(name string, rate int, window time.Duration)

AddCategory registers a rate limit for an operation category.

func (*OperationRateLimiter) Allow added in v1.5.1 

func (orl *OperationRateLimiter) Allow(category, ip string) bool

Allow checks if a request from the given IP is allowed for the given category. Returns true if the category is not registered (no limit configured). Note: categories map is read-only after initialization (AddCategory is only called during NewWithStore before any concurrent access), so no lock needed.

func (*OperationRateLimiter) Cleanup added in v1.5.1 

func (orl *OperationRateLimiter) Cleanup()

Cleanup removes stale buckets from all categories.

func (*OperationRateLimiter) SetClock added in v1.5.1 

func (orl *OperationRateLimiter) SetClock(fn func() time.Time)

SetClock overrides the time source for all categories (for testing).

type ProvisionResult added in v1.5.1 

type ProvisionResult struct {
	NetworkID uint16   `json:"network_id"`
	Name      string   `json:"name"`
	Created   bool     `json:"created"` // true if network was created (vs updated)
	Actions   []string `json:"actions"` // human-readable list of actions taken
}

ProvisionResult describes what the provisioning operation did.

type RateLimiter 

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

RateLimiter tracks per-IP registration attempts using a token bucket.

func NewRateLimiter 

func NewRateLimiter(rate int, window time.Duration) *RateLimiter

NewRateLimiter creates a rate limiter allowing rate requests per window per IP.

func (*RateLimiter) Allow 

func (rl *RateLimiter) Allow(ip string) bool

Allow checks if a request from the given IP is allowed. Uses a sliding window: tokens refill proportionally to elapsed time.

func (*RateLimiter) BucketCount 

func (rl *RateLimiter) BucketCount() int

BucketCount returns the number of tracked IPs (for testing).

func (*RateLimiter) Cleanup 

func (rl *RateLimiter) Cleanup()

Cleanup removes stale buckets. Called periodically.

func (*RateLimiter) HasBucket 

func (rl *RateLimiter) HasBucket(ip string) bool

HasBucket returns whether a given IP has an active bucket (for testing).

func (*RateLimiter) SetClock 

func (rl *RateLimiter) SetClock(fn func() time.Time)

SetClock overrides the time source (for testing).

type RegistryWebhookEvent added in v1.5.1 

type RegistryWebhookEvent struct {
	EventID   uint64                 `json:"event_id"`
	Action    string                 `json:"action"`
	Timestamp time.Time              `json:"timestamp"`
	Details   map[string]interface{} `json:"details,omitempty"`
}

RegistryWebhookEvent is the JSON payload POSTed to webhook endpoints.

type Role added in v1.5.1 

type Role string

Role represents a member's permission level within a network. 

const (
	RoleOwner  Role = "owner"  // created the network, full control
	RoleAdmin  Role = "admin"  // can invite, remove members, change settings
	RoleMember Role = "member" // can communicate, cannot manage
)

type Server 

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

func New 

func New(beaconAddr string) *Server

func NewWithStore 

func NewWithStore(beaconAddr, storePath string) *Server

func (*Server) Addr 

func (s *Server) Addr() net.Addr

Addr returns the server's bound address. Only valid after Ready() fires.

func (*Server) ApplyBlueprint added in v1.5.1 

func (s *Server) ApplyBlueprint(bp *NetworkBlueprint, adminToken string) (*ProvisionResult, error)

ApplyBlueprint provisions a network from a blueprint. It creates the network if it doesn't exist, then applies policy, RBAC, webhooks, and audit config. The adminToken is the global registry admin token.

func (*Server) Close 

func (s *Server) Close() error

func (*Server) ConnCount added in v1.5.1 

func (s *Server) ConnCount() int64

ConnCount returns the current number of active connections (for testing).

func (*Server) GetAuditExportConfig added in v1.5.1 

func (s *Server) GetAuditExportConfig() *BlueprintAuditExport

GetAuditExportConfig returns the current audit export config. Thread-safe.

func (*Server) GetDashboardStats 

func (s *Server) GetDashboardStats() DashboardStats

GetDashboardStats returns public-safe statistics for the dashboard. No IPs, keys, or endpoints are exposed.

func (*Server) GetIdentityProviderConfig added in v1.5.1 

func (s *Server) GetIdentityProviderConfig() *BlueprintIdentityProvider

GetIdentityProviderConfig returns the current identity provider config. Thread-safe.

func (*Server) IsStandby 

func (s *Server) IsStandby() bool

IsStandby returns true if this server is running in standby mode.

func (*Server) ListenAndServe 

func (s *Server) ListenAndServe(addr string) error

func (*Server) Ready 

func (s *Server) Ready() <-chan struct{}

Ready returns a channel that is closed when the server has bound its port.

func (*Server) Reap added in v1.4.0 

func (s *Server) Reap()

Reap triggers stale node and beacon cleanup (for testing).

func (*Server) RunStandby 

func (s *Server) RunStandby(primaryAddr string)

RunStandby connects to a primary registry and receives replicated snapshots. On each snapshot, the standby updates its own state and persists to storePath. This blocks until the connection is lost, then retries with backoff.

func (*Server) ServeDashboard 

func (s *Server) ServeDashboard(addr string) error

ServeDashboard starts an HTTP server serving the dashboard UI and stats API.

func (*Server) SetAdminToken 

func (s *Server) SetAdminToken(token string)

SetAdminToken sets the admin token required for network creation. If empty, network creation is disabled entirely (secure by default).

func (*Server) SetClock added in v1.4.0 

func (s *Server) SetClock(fn func() time.Time)

SetClock overrides the time source for testing.

func (*Server) SetIdentityWebhookURL added in v1.5.1 

func (s *Server) SetIdentityWebhookURL(url string)

SetIdentityWebhookURL configures a verification webhook for identity tokens. When a node registers with an identity_token, the registry POSTs it to this URL for verification. The webhook should return {"verified": true, "external_id": "..."} or {"verified": false, "error": "..."}. Empty URL disables identity verification.

func (*Server) SetMaxConnections added in v1.5.1 

func (s *Server) SetMaxConnections(max int64)

SetMaxConnections overrides the default connection limit (for testing).

func (*Server) SetOperationRateLimiterClock added in v1.5.1 

func (s *Server) SetOperationRateLimiterClock(fn func() time.Time)

SetOperationRateLimiterClock overrides the time source for per-operation rate limits (for testing).

func (*Server) SetReplicationToken 

func (s *Server) SetReplicationToken(token string)

SetReplicationToken sets the token required for subscribe_replication (H4 fix). If empty, replication subscription is disabled.

func (*Server) SetStandby 

func (s *Server) SetStandby(primary string)

SetStandby configures this server as a standby that receives replicated state from a primary. In standby mode, write operations are rejected.

func (*Server) SetTLS 

func (s *Server) SetTLS(certFile, keyFile string) error

SetTLS configures the registry to use TLS with the given cert and key files. If certFile is empty, a self-signed certificate is generated automatically.

func (*Server) SetWebhookRetryBackoff added in v1.6.0 

func (s *Server) SetWebhookRetryBackoff(d time.Duration)

SetWebhookRetryBackoff sets the initial retry backoff for the audit webhook. Useful for tests to avoid multi-second waits on retry exhaustion.

func (*Server) SetWebhookURL added in v1.5.1 

func (s *Server) SetWebhookURL(url string)

SetWebhookURL configures the registry to POST audit events to the given URL. If url is empty, webhook dispatching is disabled.

func (*Server) SyncTimestamp added in v1.5.1 

func (s *Server) SyncTimestamp(netID uint16) time.Time

SyncTimestamp returns the last directory sync time for a network.

func (*Server) TriggerSnapshot added in v1.3.0 

func (s *Server) TriggerSnapshot() error

TriggerSnapshot manually triggers a snapshot save. This is useful for testing and for ensuring data is persisted before shutdown. Returns an error if the save fails, or nil if there's no storePath configured.

type SplunkHECEvent added in v1.5.1 

type SplunkHECEvent struct {
	Time       int64                  `json:"time"`
	Host       string                 `json:"host,omitempty"`
	Source     string                 `json:"source,omitempty"`
	SourceType string                 `json:"sourcetype,omitempty"`
	Index      string                 `json:"index,omitempty"`
	Event      map[string]interface{} `json:"event"`
}

SplunkHECEvent is the Splunk HTTP Event Collector event format.

type WAL added in v1.6.0 

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

WAL implements an append-only write-ahead log for registry mutations. Instead of serializing the entire state on every mutation (O(N) per save), the WAL appends only the delta entry (O(1) per mutation). Full snapshots are written periodically (compaction) and the WAL is truncated.

On-disk format: sequential records of [4-byte little-endian length][delta entry JSON]. The WAL file path is derived from the snapshot path: "{storePath}.wal".

func NewWAL added in v1.6.0 

func NewWAL(path string) (*WAL, error)

NewWAL opens or creates a WAL file at the given path. Returns nil if path is empty (no persistence configured).

func (*WAL) Append added in v1.6.0 

func (w *WAL) Append(entry DeltaEntry) error

Append writes a delta entry to the WAL. The entry is fsync'd to ensure durability. Returns an error if the write fails.

func (*WAL) Close added in v1.6.0 

func (w *WAL) Close() error

Close closes the WAL file.

func (*WAL) Replay added in v1.6.0 

func (w *WAL) Replay(fn func(DeltaEntry) error) (int, error)

Replay reads all entries from the WAL and calls fn for each. Used during startup to replay mutations that occurred after the last snapshot.

func (*WAL) Size added in v1.6.0 

func (w *WAL) Size() int64

Size returns the current WAL file size in bytes.

func (*WAL) Truncate added in v1.6.0 

func (w *WAL) Truncate() error

Truncate clears the WAL file (called after a successful full snapshot). This is the "compaction" step — the snapshot supersedes all WAL entries.

type WireLookupResult added in v1.6.0 

type WireLookupResult struct {
	NodeID     uint32
	Public     bool
	TaskExec   bool
	PoloScore  int
	Networks   []uint16
	PubKey     []byte
	Hostname   string
	Tags       []string
	RealAddr   string
	ExternalID string
}

WireLookupResult holds the decoded fields from a binary lookup response.

type WireResolveResult added in v1.6.0 

type WireResolveResult struct {
	NodeID     uint32
	RealAddr   string
	LANAddrs   []string
	KeyAgeDays int // -1 if unknown
}

WireResolveResult holds the decoded fields from a binary resolve response.

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.