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) Login(ctx context.Context, out io.Writer, method LoginMethod) (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 current login session.

Locking invariants:

• b.lock protects: agents map and session
• 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 and session Protected by closeOnce: brokerListener, done channel Self-synchronized: each session's Auth (has internal lock)

func New(log slog.Logger, socketPath string, newToken TokenFactory, caClient *caclient.Client, publicCAURL string, inventoryClient *facts.AdminClient, 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, method LoginMethod) IdentityResponse

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

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

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

func (b *Broker) Logout() LogoutResponse

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 DirectoryListRequest ¶ added in v0.43.0

type DirectoryListRequest struct {
	Resource   string `json:"resource"`
	StartIndex int    `json:"startIndex"`
}

DirectoryListRequest asks for one bounded SCIM page; Resource is Users or Groups, and StartIndex is one-based.

type DirectoryListResponse ¶ added in v0.43.0

type DirectoryListResponse struct {
	Page  *facts.SCIMPage `json:"page,omitempty"`
	Error string          `json:"error,omitempty"`
}

DirectoryListResponse carries a SCIM page without exposing the agent's credential.

type Event ¶ added in v0.18.0

type Event struct {
	DirectoryList *DirectoryListResponse `json:"directory-list,omitempty"`
	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"`
	Logout        *LogoutResponse        `json:"logout,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. Kill and Logout each return one event of their respective type. DirectoryList streams auth Output events followed by one DirectoryList event containing a single SCIM page.

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 IdentityRequest ¶ added in v0.44.0

type IdentityRequest struct {
	LoginMethod string `json:"loginMethod,omitempty"`
}

IdentityRequest optionally overrides the interactive method for this request. An empty method uses the running agent's configured default.

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 {
	facts.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 LoginMethod ¶ added in v0.44.0

type LoginMethod uint8

LoginMethod selects how to authenticate if interactive login is necessary. LoginDefault preserves the fetcher's configured method.

const (
	LoginDefault LoginMethod = iota
	LoginBrowser
	LoginDevice
)

type LogoutResponse ¶ added in v0.37.0

type LogoutResponse struct {
	AgentsCleared int    `json:"agentsCleared"`
	Error         string `json:"error,omitempty"`
}

LogoutResponse reports how many per-connection agents were cleared.

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 {
	DirectoryList *DirectoryListRequest `json:"directory-list,omitempty"`
	Inventory     *facts.ControlRequest `json:"inventory,omitempty"`
	Identity      *IdentityRequest      `json:"identity,omitempty"`
	Match         *wire.Connection      `json:"match,omitempty"`
	Inspect       *InspectRequest       `json:"inspect,omitempty"`
	Logout        *struct{}             `json:"logout,omitempty"`
	Kill          *KillRequest          `json:"kill,omitempty"`
}

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

type TokenFactory ¶ added in v0.37.0

type TokenFactory func() TokenFunc

TokenFactory creates an independent, initially unauthenticated token fetcher. It must not perform authentication or other blocking work. Each fetcher owns its refresh state; replacing it on logout drops that state along with Auth's ID token cache, even if a canceled fetch from the old session finishes late.

type TokenFunc ¶ added in v0.18.0

type TokenFunc func(ctx context.Context, out io.Writer, request TokenRequest) (string, error)

TokenFunc acquires a JWT according to request. Auth serializes invocations, so a stateful closure needs no locking of its own.

type TokenRequest ¶ added in v0.44.0

type TokenRequest struct {
	// ForceRefresh requires a replacement for a rejected credential. A fetcher
	// with refreshable state must not return that same credential, even if its
	// expiry still says it is valid.
	ForceRefresh bool
	// LoginMethod applies only if interactive authentication is necessary;
	// it does not prevent token reuse or refresh.
	LoginMethod LoginMethod
}

TokenRequest describes one acquisition attempt, not persistent configuration.