broker

package
v0.6.2 Latest Latest
Warning

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

 Go to latest Published: Jan 8, 2026 License: Apache-2.0, Apache-2.0 Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source 
const MaxStateBlobSize = 10 * 1024 * 1024

MaxStateBlobSize is the maximum size of the state blob (10 MiB). This prevents malicious or buggy auth plugins from exhausting memory.

Variables

This section is empty.

Functions

func AuthConfigToCommand added in v0.5.1 

func AuthConfigToCommand(auth caclient.BootstrapAuth) (string, error)

AuthConfigToCommand converts a bootstrap auth config to an executable command string. For type="oidc": constructs "<executable> auth oidc --issuer X --client-id Y --scopes Z" For type="command": returns the command as-is (substituting "epithet" with os.Executable()) Returns an error if the auth type is unknown or if os.Executable() fails.

Types

type AgentInfo added in v0.1.2 

type AgentInfo struct {
	Hash        string                 `json:"hash"`
	SocketPath  string                 `json:"socketPath"`
	ExpiresAt   time.Time              `json:"expiresAt"`
	Certificate sshcert.RawCertificate `json:"certificate"`
}

AgentInfo contains information about a running agent

type Auth 

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

Auth represents a configured authentication command.

Concurrency: Auth is safe for concurrent use. All public methods use internal locking.

Locking invariants:

  • lock protects: state, token
  • Token() reads token under lock
  • Run() holds lock for entire auth command execution and state update (atomic operation)
  • cmdLine is immutable after NewAuth()

func NewAuth 

func NewAuth(cmdLine string) *Auth

NewAuth creates a new Auth with an unparsed command line.

func (*Auth) ClearToken 

func (h *Auth) ClearToken()

ClearToken clears the stored authentication token. Keeps the state intact (refresh token may still be valid). Used when receiving HTTP 401 from CA to force re-authentication.

func (*Auth) Run 

func (h *Auth) Run(attrs any) (string, error)

Run executes the auth command with the current state and updates state based on output. Returns the authentication token on success. The command line is rendered as a mustache template with the provided attrs.

Protocol:

  • stdin: current state bytes (empty on first call)
  • stdout: authentication token (raw bytes)
  • fd 3: new state bytes (max MaxStateBlobSize)
  • stderr: error messages on failure
  • exit 0: success, non-zero: failure

func (*Auth) Token 

func (h *Auth) Token() string

Token returns the current authentication token, or empty string if not authenticated.

type Broker 

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

Broker manages authentication, certificate storage, and per-connection SSH agents.

Concurrency: Broker is safe for concurrent access from multiple RPC clients. The primary lock (b.lock) protects the agents map and coordinates with Auth and CertificateStore.

Locking invariants:

  • b.lock protects: agents map (both reads and writes)
  • Auth has its own internal lock (auth.lock) - safe to call without b.lock
  • CertificateStore has its own internal lock (certStore.lock) - safe to call without b.lock
  • Match() holds b.lock for the entire operation to ensure atomic cert lookup + agent creation
  • ensureAgent() MUST be called with b.lock held (caller responsibility)

Immutable after New(): brokerSocketPath, agentSocketDir, caClient, log Protected by b.lock: agents map Protected by closeOnce: brokerListener, done channel Self-synchronized: auth (has internal lock), certStore (has internal lock)

func New 

func New(log slog.Logger, socketPath string, authCommand string, caClient *caclient.Client, agentSocketDir string, options ...Option) (*Broker, error)

New creates a new Broker instance. This does not start listening - call Serve() to begin accepting connections.

func (*Broker) AgentSocketPath 

func (b *Broker) AgentSocketPath(hash policy.ConnectionHash) string

AgentSocketPath returns the socket path for a given connection hash. This is used by SSH to connect to the per-connection agent.

func (*Broker) BrokerSocketPath 

func (b *Broker) BrokerSocketPath() string

BrokerSocketPath returns the path to the broker's RPC socket.

func (*Broker) Close 

func (b *Broker) Close()

func (*Broker) Done 

func (b *Broker) Done() <-chan struct{}

func (*Broker) Inspect added in v0.1.2 

func (b *Broker) Inspect(_ InspectRequest, output *InspectResponse) error

Inspect is invoked via RPC from `epithet inspect` to get broker state

func (*Broker) LookupCertificate 

func (b *Broker) LookupCertificate(conn policy.Connection) (agent.Credential, bool)

LookupCertificate finds a valid certificate for the given connection. Returns the Credential and true if found and not expired, otherwise returns false.

func (*Broker) Match 

func (b *Broker) Match(input MatchRequest, output *MatchResponse) error

Match is invoked via rpc from `epithet match` invocations

func (*Broker) Ready added in v0.3.5 

func (b *Broker) Ready() <-chan struct{}

Ready returns a channel that is closed when the broker is ready to accept connections. Use this to wait for the broker to start: <-b.Ready()

func (*Broker) Running 

func (b *Broker) Running() bool

func (*Broker) Serve 

func (b *Broker) Serve(ctx context.Context) error

Serve starts the broker listening on the configured socket and blocks until the context is cancelled. Returns an error if the listener cannot be started, otherwise returns ctx.Err() when shutdown completes.

func (*Broker) SetShutdownTimeout added in v0.1.2 

func (b *Broker) SetShutdownTimeout(d time.Duration)

SetShutdownTimeout sets the timeout for waiting on in-flight RPCs during shutdown. Use 0 to skip waiting (useful for tests).

func (*Broker) StoreCertificate 

func (b *Broker) StoreCertificate(pc PolicyCert)

StoreCertificate adds or updates a certificate for a given policy pattern.

type CertInfo added in v0.1.2 

type CertInfo struct {
	Certificate sshcert.RawCertificate `json:"certificate"`
	Policy      policy.Policy          `json:"policy"`
	ExpiresAt   time.Time              `json:"expiresAt"`
}

CertInfo contains information about a stored certificate

type CertificateStore 

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

CertificateStore manages the mapping of policies to certificates.

Concurrency: CertificateStore is safe for concurrent use. All public methods use internal locking (lock/RWMutex).

Locking invariants:

  • lock protects: certs slice (all reads and writes)
  • Store() uses write lock (exclusive access)
  • Lookup() uses write lock (not read lock) because it may modify the slice (removing expired certs)

func NewCertificateStore 

func NewCertificateStore() *CertificateStore

NewCertificateStore creates a new empty certificate store

func (*CertificateStore) List added in v0.1.2 

func (cs *CertificateStore) List() []CertInfo

List returns information about all stored certificates. Used by the inspect command to show broker state.

func (*CertificateStore) Lookup 

func (cs *CertificateStore) Lookup(conn policy.Connection) (agent.Credential, bool)

Lookup finds a valid certificate for the given connection. Returns the Credential and true if found and not expired, otherwise returns false. Policies are evaluated in order; the first matching, non-expired certificate is returned. Expired certificates are removed from the store during lookup. Certificates are considered expired expiryBuffer seconds before their actual expiration time.

func (*CertificateStore) Store 

func (cs *CertificateStore) Store(pc PolicyCert)

Store adds a certificate for a given policy. No deduplication is performed - overlapping policies are fine and will coexist. Certificates expire naturally and are cleaned up during Lookup.

type InspectRequest added in v0.1.2 

type InspectRequest struct{}

InspectRequest is the input for Broker.Inspect RPC

type InspectResponse added in v0.1.2 

type InspectResponse struct {
	SocketPath        string      `json:"socketPath"`
	AgentSocketDir    string      `json:"agentSocketDir"`
	DiscoveryPatterns []string    `json:"discoveryPatterns,omitempty"` // Fetched live from CA (HTTP cached)
	Agents            []AgentInfo `json:"agents"`
	Certificates      []CertInfo  `json:"certificates"`
}

InspectResponse contains the current broker state

type MatchRequest 

type MatchRequest struct {
	Connection policy.Connection
}

type MatchResponse 

type MatchResponse struct {
	// Should the `Match exec` actually match?
	Allow bool

	// Error contains any error which should be reported to the user on stderr
	Error string
}

type Option added in v0.1.4 

type Option interface {
	// contains filtered or unexported methods
}

Option configures the Broker

type PolicyCert 

type PolicyCert struct {
	Policy     policy.Policy
	Credential agent.Credential
	ExpiresAt  time.Time
}

PolicyCert combines a policy with its associated certificate and expiration.

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.