bot

type ApprovalBinding ¶

type ApprovalBinding struct {
	Argv       []string
	Cwd        string
	AgentID    string
	SessionKey string
	EnvHash    string
}

ApprovalBinding is what the operator actually said yes to.

func BuildApprovalBinding(argv []string, cwd, agentID, sessionKey string, env map[string]string) (ApprovalBinding, []string)

type ApprovalDecision ¶

type ApprovalDecision string

ApprovalDecision is what an operator answered.

const (
	DecisionAllowOnce   ApprovalDecision = "allow-once"
	DecisionAllowAlways ApprovalDecision = "allow-always"
)

type ApprovalPlan ¶

type ApprovalPlan struct {
	Argv       []string
	Cwd        string
	RawCommand string
	AgentID    string
	SessionKey string
}

ApprovalPlan is the command the gateway resolved when it asked the operator. When a record carries one, it — not the caller's parameters — is what runs.

type ApprovalRecord ¶

type ApprovalRecord struct {
	RunID   string
	Node    NodeKey
	Host    string
	Binding *ApprovalBinding
	Plan    *ApprovalPlan

	ExpiresAt time.Time

	RequestedByConnID   string
	RequestedByDeviceID string

	// Decision is empty once consumed or when the request timed out.
	Decision ApprovalDecision
	// Resolved records that the request reached an end state.
	Resolved bool
	// ResolvedBy is empty when nobody answered, i.e. the request timed out.
	ResolvedBy string
}

ApprovalRecord is the gateway's record of one approval request.

Node is a NodeKey, not a bare id: an approval is an answer about one tenant's machine. Binding by id alone would let an approval for org A's "laptop" authorize org B's "laptop".

type ApprovalStore ¶

type ApprovalStore interface {
	// Snapshot returns the record for runID, or nil if unknown or expired.
	Snapshot(runID string) *ApprovalRecord
	// ConsumeAllowOnce spends a one-shot approval, returning false if it was
	// already spent. Replay protection lives here because it must be atomic.
	ConsumeAllowOnce(runID string) bool
}

ApprovalStore is the gateway's live approval state. It is an interface so this file stays pure: the only mutation policy needs is consuming a one-shot approval, and that has to be atomic with the check.

type AuthMode ¶

type AuthMode string

AuthMode is how the edge authenticates a caller.

const (
	// AuthUnset is the zero value and is treated as the strictest reading.
	AuthUnset        AuthMode = ""
	AuthIAM          AuthMode = "iam"
	AuthToken        AuthMode = "token"
	AuthTrustedProxy AuthMode = "trusted-proxy"
	// AuthNone means the edge authenticates nobody.
	AuthNone AuthMode = "none"
)

type Caller ¶

type Caller struct {
	ConnID   string
	DeviceID string
	Scopes   []string
}

Caller is who asked for the invocation.

type Cluster ¶

type Cluster struct {
	// Replica is this replica's stable id (CLOUD_POD_NAME / the StatefulSet
	// ordinal). It is what a presence claim names and what a Hop resolves.
	Replica string

	Presence PresenceStore
	Hop      Hop

	// TTL is the presence lease; Renew defaults to a third of it.
	TTL   time.Duration
	Renew time.Duration

	// PeerToken authenticates a forward. Empty disables PeerHandler entirely —
	// see PeerHandler for why that is the only safe default.
	PeerToken string

	Logger luxlog.Logger
}

Cluster is what one replica needs to reach sockets it does not hold.

type Decision ¶

type Decision struct {
	Allow bool
	// Code is stable and safe to put on the wire. Callers switch on it.
	Code string
	// Reason is for a human reading a log or an error body.
	Reason string
}

Decision is the answer this package gives. The zero value denies: a policy that has not run cannot have said yes.

func Check(s *Session, command string, args []string, mode Mode) Decision

func EvaluateApprovalMatch(argv []string, rec *ApprovalRecord, cwd, agentID, sessionKey string, env map[string]string) Decision

func ResolveSystemRunCommand(command []string, rawCommand string) (argv []string, cmdText string, d Decision)

type Denied ¶

type Denied struct {
	Code    string
	Message string
}

Denied is a gate refusal. It carries a stable code so the caller can answer with it, and it survives a peer forward.

func (d *Denied) Error() string

type Frame ¶

type Frame func(corrID string) ([]byte, error)

Frame builds the wire frame for one invocation.

corrID is minted by the replica that HOLDS the socket, and only by it: that replica's pending table is keyed by it, its disconnect sweep cancels by its prefix, and the node echoes it back on a socket where anything else is refused. An EMPTY corrID means "not minted yet" — the frame built with one is the frame that travels to the owning replica, which stamps its own id in before writing it.

type Gate ¶

type Gate func(s *Session, command string, params json.RawMessage) error

Gate authorizes one invocation, on the replica that holds the node's socket — the only replica that knows what that node declared it can do.

It is called at the SINGLE point where a frame is about to be written to a socket, so no path into a node can skip it: a locally-held node and one reached through a peer forward pass the same gate, once, with the same session in hand. Returning a *Denied makes the refusal travel a hop intact, so a caller gets the same answer wherever the socket happens to be.

A nil gate authorizes everything. That is what a bare plumbing registry wants (fixtures, the routing tests) and what a serving one must never have.

type Hop ¶

type Hop interface {
	Forward(ctx context.Context, replica string, key NodeKey, req []byte, timeout time.Duration) (InvokeResult, error)
}

Hop carries an invocation to the replica that holds the node's socket.

WHY HTTP AND NOT ZAP. ZAP is cloud's answer for INTER-SERVICE RPC — one service calling another across a trust boundary. This is not that: it is one replica of cloud reaching another replica of the SAME binary because a socket landed there, and cloud has already answered that question exactly once (shardrouter forwards an org's request to the pod owning its files, over the peer address from CLOUD_PEERS). A second mechanism for "reach my peer pod" would be a second answer to a settled question. Nor is there a ZAP client seam to reuse: zapface is a server face whose dispatch replays each call as an in-process HTTP request into the same Fiber app, so a ZAP hop here would be this HTTP hop with an extra codec in front of it.

WHY NOT THE KV'S OWN PUB/SUB (publish to bot:invoke:<pod>, listen on bot:invoke-result:<originPod>, which is how this worked before): a request/response spliced out of two fire-and-forget channels needs a second correlation table, with its own timeouts and its own cleanup, layered on the one the registry already keeps — and it cannot tell a dead owner from a slow one, so a replica that died between the lookup and the publish costs the caller a full timeout instead of a dial error. One synchronous connection makes the correlation the connection itself.

The interface is here so that transport can be replaced without the routing above it noticing.

func NewHTTPHop(resolve func(replica string) (addr string, ok bool), token string) Hop

type InvokeResult ¶

type InvokeResult struct {
	OK      bool
	Payload []byte
	Code    string
	Message string
}

InvokeResult is what a node answered.

type KV ¶

type KV interface {
	Set(ctx context.Context, key string, value any, expiration time.Duration) *kv.StatusCmd
	Get(ctx context.Context, key string) *kv.StringCmd
	Eval(ctx context.Context, script string, keys []string, args ...any) *kv.Cmd
}

KV is the slice of the Hanzo KV client the presence map uses. Narrow on purpose: the presence map is three operations, and naming only those three keeps the whole KV surface out of the registry's reach. github.com/hanzokv/go/v9's Cmdable satisfies it, so *kv.Client and *kv.ClusterClient are passed as-is.

type Mode ¶

type Mode struct {
	Auth AuthMode
	// Allow adds commands on top of the platform defaults. This is the only
	// way a dangerous command becomes reachable.
	Allow []string
	// Deny removes commands, and wins over Allow and over the defaults.
	Deny []string
}

Mode is the operator's policy for this deployment: the auth posture plus the explicit overlay on the platform defaults. Its zero value is the safe one — no extra commands, unknown auth treated as strict.

type NodeKey ¶

type NodeKey struct {
	Org    string
	NodeID string
}

NodeKey addresses a node. Both fields are required; there is no way to name a node without naming its tenant.

func (k NodeKey) String() string

type Option ¶

type Option func(*Registry)

Option is construction-time wiring. There is one constructor; what a Registry can do is what it was given, and nothing is switched on afterwards.

func WithCluster(c Cluster) Option

func WithGate(g Gate) Option

type Platform ¶

type Platform string

Platform is a node's classified operating system. It is derived from self-reported metadata, so it is a hint the policy hardens against, never a credential.

const (
	PlatformIOS     Platform = "ios"
	PlatformAndroid Platform = "android"
	PlatformMacOS   Platform = "macos"
	PlatformWindows Platform = "windows"
	PlatformLinux   Platform = "linux"
	PlatformUnknown Platform = "unknown"
)

func ClassifyPlatform(platform, deviceFamily string) Platform

type PresenceStore ¶

type PresenceStore interface {
	// Claim takes ownership unconditionally. A node that reconnects to another
	// replica must win immediately — the old replica's socket is dead whether or
	// not it has noticed yet.
	Claim(ctx context.Context, key NodeKey, replica string, ttl time.Duration) error

	// Renew extends a claim this replica still owns, and re-takes one that has
	// gone missing (a claim lost to a KV blip heals on the next tick). It must
	// NOT overwrite another replica's claim: a socket that has already moved
	// would otherwise be dragged back to a replica holding a half-open TCP
	// connection, where every invoke burns its full timeout.
	Renew(ctx context.Context, key NodeKey, replica string, ttl time.Duration) error

	// Release drops a claim only while it is still ours, for the same reason.
	Release(ctx context.Context, key NodeKey, replica string) error

	// Lookup returns the replica holding the node, or ErrNoSuchNode.
	Lookup(ctx context.Context, key NodeKey) (string, error)
}

PresenceStore is the shared answer to "which replica holds this node's socket". Lookup reports ErrNoSuchNode for an absent claim: to a caller, a node nobody holds and a node in another tenant are the same non-answer, and that sameness is the point.

func NewKVPresence(c KV) PresenceStore

type RateLimitConfig ¶

type RateLimitConfig struct {
	MaxAttempts int
	Window      time.Duration
	Lockout     time.Duration
	// RateLimitLoopback turns off the loopback exemption. It is phrased
	// negatively so the zero value keeps a local CLI from locking itself out.
	RateLimitLoopback bool
	// Now is the injected clock. nil means time.Now.
	Now func() time.Time
}

RateLimitConfig configures a RateLimiter. The zero value is the default policy: 10 attempts a minute, five minute lockout, loopback exempt.

type RateLimitResult ¶

type RateLimitResult struct {
	Allow      bool
	Remaining  int
	RetryAfter time.Duration
}

RateLimitResult answers "may this client try again".

type RateLimiter ¶

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

RateLimiter is a sliding-window limiter for failed authentication attempts, keyed by (scope, client ip).

The org is deliberately NOT part of that key. Everywhere else in this package the org is part of an identity; here the key is a budget, and a budget partitioned by something the caller names is no budget at all — an attacker would multiply their attempts by inventing org names.

func NewRateLimiter(cfg RateLimitConfig) *RateLimiter

func (l *RateLimiter) Check(ip, scope string) RateLimitResult

func (l *RateLimiter) Prune()

func (l *RateLimiter) RecordFailure(ip, scope string)

func (l *RateLimiter) Reset(ip, scope string)

func (l *RateLimiter) Size() int

type Registry ¶

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

Registry tracks connected nodes, correlates in-flight invocations, and — when wired for a cluster — routes to sockets held by another replica.

It is transport-agnostic about the SOCKET on purpose: the WS layer registers a Session with a send func and feeds answers back by correlation id. Keeping the socket out of here is what lets the routing be tested without a network.

func NewRegistry(opts ...Option) *Registry

func (r *Registry) Answer(corrID string, res InvokeResult)

func (r *Registry) Invoke(ctx context.Context, key NodeKey, frame Frame, timeout time.Duration) (InvokeResult, error)

func (r *Registry) List(org string) []*Session

func (r *Registry) PeerHandler() http.Handler

func (r *Registry) Register(s *Session) error

func (r *Registry) Run(ctx context.Context)

func (r *Registry) Unregister(connID string)

type Session ¶

type Session struct {
	Key         NodeKey
	ConnID      string
	DisplayName string
	Platform    string
	Version     string
	Caps        []string
	Commands    []string
	Permissions map[string]bool
	RemoteIP    string
	ConnectedAt time.Time
	// contains filtered or unexported fields
}

Session is a connected node.

type SystemRunParams ¶

type SystemRunParams struct {
	Command              []string          `json:"command,omitempty"`
	RawCommand           string            `json:"rawCommand,omitempty"`
	Cwd                  string            `json:"cwd,omitempty"`
	Env                  map[string]string `json:"env,omitempty"`
	TimeoutMs            int               `json:"timeoutMs,omitempty"`
	NeedsScreenRecording bool              `json:"needsScreenRecording,omitempty"`
	AgentID              string            `json:"agentId,omitempty"`
	SessionKey           string            `json:"sessionKey,omitempty"`
	RunID                string            `json:"runId,omitempty"`

	// Approved and ApprovalDecision are control fields. A caller may ask for
	// them; only a matching approval record puts them on the wire.
	Approved         bool             `json:"approved,omitempty"`
	ApprovalDecision ApprovalDecision `json:"approvalDecision,omitempty"`
}

SystemRunParams is exactly the set of fields a node's system.run handler understands.

The type is the allowlist. The TypeScript had to copy a hand-written list of keys out of an untyped object to stop internal control fields being smuggled through; here a field the node does not implement has nowhere to live.

type WSOptions ¶

type WSOptions struct {
	// ServerVersion is reported to the node in hello-ok.
	ServerVersion string

	Logger luxlog.Logger

	// OnNodeEvent receives a node's unsolicited node.event pushes (idle
	// notices, proxy stream chunks). payload is raw JSON, already unwrapped
	// when the node sent it as payloadJSON. Nil drops them, which is the
	// correct default: an unread push is cheaper than a fabricated consumer.
	OnNodeEvent func(key NodeKey, event string, payload []byte)
}

WSOptions configures the node transport. Every field is optional.