broker

type AgentInfo ¶ added in v0.1.2

type AgentInfo struct {
	Hash        string                 `json:"hash"`
	Connection  wire.Connection        `json:"connection"`
	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 caches a JWT obtained from fetch and refreshes it proactively before it expires.

Concurrency: Auth is safe for concurrent use. Concurrent Token() calls are coalesced (singleflight): the first caller invokes fetch, later callers join the in-flight attempt, receive a replay of its user-visible output so far, and share its result. fetch's context is canceled when every caller waiting on it has canceled its own context.

Locking invariants:

• mu protects: token, expiresAt, inflight
• the flight goroutine writes token/expiresAt back under mu on success; no other flight can start while one is in flight
• fetch is immutable after NewAuth()

func NewAuth(fetch TokenFunc) *Auth

func (a *Auth) ForceRefresh(ctx context.Context, out io.Writer) (string, error)

func (a *Auth) Token(ctx context.Context, out io.Writer) (string, error)

type Broker ¶

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

Broker manages authentication and per-connection SSH agents. Certificates are minted fresh from the CA for every match past the agents-map fast path - there is no cross-connection certificate cache.

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

Locking invariants:

• b.lock protects: agents map (both reads and writes)
• Auth has its own internal lock (auth.mu) - safe to call without b.lock
• Match() only holds b.lock around agents-map access, never across auth or CA calls, so concurrent matches can share an in-flight auth attempt. Concurrent matches for the same connection may each request a certificate from the CA; ensureAgent() reconciles them (last one wins).
• ensureAgent() acquires b.lock itself; do not call it with b.lock held

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

func New(log slog.Logger, socketPath string, fetch TokenFunc, caClient *caclient.Client, publicCAURL string, inventoryClient *inventoryclient.Client, verifyIdentity IdentityVerifier, agentSocketDir string) (*Broker, error)

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

func (b *Broker) Close()

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

func (b *Broker) IdentityWithUserOutput(ctx context.Context, out io.Writer) IdentityResponse

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

func (b *Broker) InventoryWithUserOutput(ctx context.Context, request inventoryapi.ControlRequest, out io.Writer) *InventoryResponse

func (b *Broker) Kill(request KillRequest, output *KillResponse) error

func (b *Broker) MatchWithUserOutput(ctx context.Context, conn wire.Connection, userOutput io.Writer) MatchResponse

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

func (b *Broker) Running() bool

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

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

type CAEndpointInfo ¶ added in v0.17.0

type CAEndpointInfo struct {
	URL      string `json:"url"`
	Priority int    `json:"priority"`
	State    string `json:"state"` // "closed", "open", "half-open"
}

CAEndpointInfo contains the current state of a CA endpoint.

type Event ¶ added in v0.18.0

type Event struct {
	Inventory *InventoryResponse `json:"inventory,omitempty"`
	Identity  *IdentityResponse  `json:"identity,omitempty"`
	Output    string             `json:"output,omitempty"`
	Result    *MatchResponse     `json:"result,omitempty"`
	Inspect   *InspectResponse   `json:"inspect,omitempty"`
	Kill      *KillResponse      `json:"kill,omitempty"`
}

Event is one line of JSON sent by the broker in response to a Request. For a Match request: zero or more Output events (auth progress, e.g. the auth-code+PKCE URL to visit) followed by exactly one Result event. For an Inspect request: exactly one Inspect event. Identity requests stream auth Output events followed by one Identity event. Inventory requests similarly stream Output events followed by one Inventory event.

type Identity ¶ added in v0.27.0

type Identity struct {
	Issuer        string `json:"issuer"`
	Subject       string `json:"subject"`
	OID           string `json:"oid,omitempty"`
	Email         string `json:"email,omitempty"`
	EmailVerified *bool  `json:"email_verified,omitempty"`
}

Identity reports selected claims from a verified token, never bearer credentials. EmailVerified is the issuer assertion, not an inventory authorization decision.

type IdentityResponse ¶ added in v0.27.0

type IdentityResponse struct {
	Identity *Identity `json:"identity,omitempty"`
	Error    string    `json:"error,omitempty"`
}

IdentityResponse is the terminal event for an identity request.

type IdentityVerifier ¶ added in v0.27.0

type IdentityVerifier func(context.Context, string) (*Identity, error)

IdentityVerifier verifies the agent's ID token and extracts diagnostic claims. It must be safe for concurrent calls and must not return token contents in errors.

type InspectRequest ¶ added in v0.1.2

type InspectRequest struct {
	ID wire.ConnectionHash `json:"id,omitempty"`
}

InspectRequest optionally selects an agent by full ID or unique prefix. An empty ID returns all agents.

type InspectResponse ¶ added in v0.1.2

type InspectResponse struct {
	SocketPath     string           `json:"socketPath"`
	AgentSocketDir string           `json:"agentSocketDir"`
	Agents         []AgentInfo      `json:"agents"`
	CAEndpoints    []CAEndpointInfo `json:"caEndpoints"`
}

InspectResponse contains the current broker state

type InventoryResponse ¶ added in v0.35.0

type InventoryResponse struct {
	inventoryapi.ControlResponse
	CAURL string `json:"ca-url,omitempty"`
}

InventoryResponse adds local agent context to the service result. CAURL comes from the broker's CA discovery and is used by the CLI for enrollment instructions; it is not part of the remote inventory API.

type KillRequest ¶ added in v0.25.0

type KillRequest struct {
	ID wire.ConnectionHash `json:"id"`
}

KillRequest identifies one per-connection agent by the ID returned from Inspect. The ID may be a full OpenSSH connection hash or a unique prefix.

type KillResponse ¶ added in v0.25.0

type KillResponse struct {
	ID         wire.ConnectionHash `json:"id"`
	Connection wire.Connection     `json:"connection"`
	Error      string              `json:"error,omitempty"`
}

KillResponse confirms which agent was evicted. Error is populated on the wire when a protocol request cannot be completed.

type MatchResponse ¶

type MatchResponse struct {
	// Should the `Match exec` actually match?
	Allow bool `json:"allow"`

	// Error contains any error which should be reported to the user on stderr
	Error string `json:"error,omitempty"`
}

type Request ¶ added in v0.18.0

type Request struct {
	Inventory *inventoryapi.ControlRequest `json:"inventory,omitempty"`
	Identity  *struct{}                    `json:"identity,omitempty"`
	Match     *wire.Connection             `json:"match,omitempty"`
	Inspect   *InspectRequest              `json:"inspect,omitempty"`
	Kill      *KillRequest                 `json:"kill,omitempty"`
}

Request is one line of JSON sent by the client. Exactly one field is set.

type TokenFunc ¶ added in v0.18.0

type TokenFunc func(ctx context.Context, out io.Writer, force bool) (string, error)

TokenFunc acquires a fresh JWT. force is true when the caller has already determined the current credential was rejected (ForceRefresh) and a genuinely new token is required, not merely "no cached token yet". Implementations backed by refreshable state (e.g. an oauth2.Token) must not treat force=true as an ordinary call and hand back a still-"valid" credential — that would silently defeat the 401 safety net. Invocations are serialized by Auth, so a stateful closure needs no locking of its own.