remoteaccess

package
v0.56.4 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2026 License: MIT Imports: 35 Imported by: 0

Documentation

Overview

Package remoteaccess owns authorization and durable native SSH executions.

Index

Constants

View Source
const FileLimit = 10 << 20

FileLimit bounds each transferred file before allocation or publication.

Variables

View Source
var ErrDenied = errors.New("remote access denied")

ErrDenied reports an authorization or consent failure.

Functions

func ConnectNative

func ConnectNative(parent context.Context, endpoints []TransportEndpoint, timeout time.Duration) (*ssh.Client, io.Closer, error)

ConnectNative establishes pinned, authenticated multi-hop SSH connections.

Types

type Approval

type Approval struct {
	ModelOutput            bool       `json:"model_output"`
	GrantID                string     `json:"grant_id"`
	AuthorizationExpiresAt time.Time  `json:"authorization_expires_at"`
	ApprovalID             string     `json:"approval_id"`
	CredentialVersions     []string   `json:"credential_versions"`
	ExecutionID            string     `json:"execution_id"`
	PlanHash               string     `json:"plan_hash"`
	Command                string     `json:"command"`
	Route                  Route      `json:"route"`
	Servers                []Server   `json:"servers"`
	Identities             []Identity `json:"identities"`
	ExpiresAt              time.Time  `json:"expires_at"`
}

Approval is the immutable human-visible operation preview.

type Artifact

type Artifact struct {
	File       *FileResult       `json:"file,omitempty"`
	Background *BackgroundResult `json:"background,omitempty"`
	Command    string            `json:"command"`
	Stdout     string            `json:"stdout"`
	Stderr     string            `json:"stderr"`
}

Artifact contains private command details and bounded remote output.

type BackgroundRequest

type BackgroundRequest struct {
	Root    string `json:"root"`
	JobID   string `json:"job_id"`
	Command string `json:"command,omitempty"`
}

BackgroundRequest identifies one durable managed operation on a remote Linux host.

type BackgroundResult

type BackgroundResult struct {
	JobID    string `json:"job_id"`
	State    string `json:"state"`
	PID      int    `json:"pid"`
	ExitCode *int   `json:"exit_code,omitempty"`
}

BackgroundResult exposes only validated job lifecycle metadata.

type Catalog

type Catalog struct {
	ScheduledTaskFloor int64                      `json:"scheduled_task_floor,omitempty"`
	ScheduledRuns      map[string]ScheduledRun    `json:"scheduled_runs,omitempty"`
	Jobs               map[string]RemoteJob       `json:"jobs,omitempty"`
	Runbooks           map[string]Runbook         `json:"runbooks,omitempty"`
	Approvals          map[string]storedApproval  `json:"approvals,omitempty"`
	PolicyRevision     uint64                     `json:"policy_revision"`
	Installations      map[string]KeyInstallation `json:"installations"`
	Enabled            bool                       `json:"enabled"`
	Servers            map[string]Server          `json:"servers"`
	Identities         map[string]Identity        `json:"identities"`
	Routes             map[string]Route           `json:"routes"`
	Grants             map[string]Grant           `json:"grants"`
	Executions         map[string]Execution       `json:"executions"`
	Artifacts          map[string]sealedArtifact  `json:"artifacts,omitempty"`
}

Catalog is the durable remote access inventory and execution metadata.

type ConfirmFunc

type ConfirmFunc func(context.Context, Approval) (bool, error)

ConfirmFunc asks the authenticated owner to approve one immutable operation.

type ExecuteRequest

type ExecuteRequest struct {
	ModelOutput      bool               `json:"model_output"`
	Operation        string             `json:"operation,omitempty"`
	Terminal         *TerminalOptions   `json:"terminal,omitempty"`
	File             *FileRequest       `json:"file,omitempty"`
	Background       *BackgroundRequest `json:"background,omitempty"`
	RunbookID        string             `json:"runbook_id,omitempty"`
	RunbookRevision  int                `json:"runbook_revision,omitempty"`
	ApprovalID       string             `json:"approval_id,omitempty"`
	Capability       string             `json:"capability,omitempty"`
	ExpectedPlanHash string             `json:"expected_plan_hash,omitempty"`
	RouteID          string             `json:"route_id"`
	Command          string             `json:"command"`
	TimeoutSeconds   int                `json:"timeout_seconds"`
}

ExecuteRequest specifies an exact command and optional one-use approval.

type Execution

type Execution struct {
	ModelOutput   bool      `json:"model_output"`
	GrantID       string    `json:"grant_id,omitempty"`
	RouteRevision int       `json:"route_revision,omitempty"`
	Operation     string    `json:"operation,omitempty"`
	ID            string    `json:"id"`
	OwnerID       string    `json:"owner_id"`
	CallerID      string    `json:"caller_id"`
	RouteID       string    `json:"route_id"`
	PlanHash      string    `json:"plan_hash"`
	State         string    `json:"state"`
	CreatedAt     time.Time `json:"created_at"`
	FinishedAt    time.Time `json:"finished_at"`
	ExitCode      *int      `json:"exit_code,omitempty"`
	ErrorCode     string    `json:"error_code,omitempty"`
	Truncated     bool      `json:"truncated"`
	StdoutBytes   int       `json:"stdout_bytes"`
	StderrBytes   int       `json:"stderr_bytes"`
	ArtifactID    string    `json:"artifact_id,omitempty"`
	ApprovedAt    time.Time `json:"approved_at"`
}

Execution contains metadata only; raw output resides in encrypted artifacts.

type FileRequest

type FileRequest struct {
	Root      string `json:"root"`
	Path      string `json:"path"`
	SHA256    string `json:"sha256"`
	Data      []byte `json:"data,omitempty"`
	Overwrite bool   `json:"overwrite,omitempty"`
}

FileRequest identifies a bounded file operation under an approved remote root.

type FileResult

type FileResult struct {
	Path   string `json:"path"`
	SHA256 string `json:"sha256"`
	Data   []byte `json:"data,omitempty"`
	Size   int64  `json:"size"`
}

FileResult contains a verified file digest and optional private download bytes.

type Grant

type Grant struct {
	AllowModelOutput bool      `json:"allow_model_output"`
	FileRoot         string    `json:"file_root,omitempty"`
	RunbookID        string    `json:"runbook_id,omitempty"`
	RunbookRevision  int       `json:"runbook_revision,omitempty"`
	MaxUses          int       `json:"max_uses,omitempty"`
	Uses             int       `json:"uses,omitempty"`
	ID               string    `json:"id"`
	OwnerID          string    `json:"owner_id"`
	CallerID         string    `json:"caller_id"`
	RouteID          string    `json:"route_id"`
	RouteRevision    int       `json:"route_revision"`
	Capability       string    `json:"capability"`
	ExpiresAt        time.Time `json:"expires_at"`
	Permanent        bool      `json:"permanent"`
	Enabled          bool      `json:"enabled"`
}

Grant authorizes one caller and capability against an exact route revision.

func (Grant) ActiveAt added in v0.53.2

func (g Grant) ActiveAt(now time.Time) bool

ActiveAt reports whether an enabled grant has an explicit valid lifetime. A missing expiry on a legacy timed grant never authorizes access.

type Hop

type Hop struct {
	ServerID   string `json:"server_id"`
	IdentityID string `json:"identity_id"`
}

Hop binds one route endpoint to its authentication identity.

type Identity

type Identity struct {
	PublicKey         string    `json:"public_key,omitempty"`
	PublicFingerprint string    `json:"public_fingerprint,omitempty"`
	ID                string    `json:"id"`
	OwnerID           string    `json:"owner_id"`
	Username          string    `json:"username"`
	AuthType          string    `json:"auth_type"`
	CredentialRef     string    `json:"credential_ref"`
	Enabled           bool      `json:"enabled"`
	ExpiresAt         time.Time `json:"expires_at"`
	Revision          int       `json:"revision"`
}

Identity references encrypted authentication material and safe public metadata.

type KeyInstallation

type KeyInstallation struct {
	ID          string    `json:"id"`
	OwnerID     string    `json:"owner_id"`
	ServerID    string    `json:"server_id"`
	Username    string    `json:"username"`
	IdentityID  string    `json:"identity_id"`
	PublicKey   string    `json:"public_key"`
	Fingerprint string    `json:"fingerprint"`
	State       string    `json:"state"`
	ExecutionID string    `json:"execution_id"`
	VerifiedAt  time.Time `json:"verified_at"`
	UpdatedAt   time.Time `json:"updated_at"`
}

KeyInstallation remains in inventory even after local identities are disabled. Verified means a separate SSH login succeeded, not merely a file write.

type NativeTransport

type NativeTransport struct{}

NativeTransport performs no pooling, agent forwarding, PTY, or automatic retries.

func (NativeTransport) OpenPTY

func (NativeTransport) OpenPTY(parent context.Context, req PTYRequest) (PTYSession, error)

OpenPTY opens one shell without forwarding or replay.

func (NativeTransport) Run

func (NativeTransport) Run(parent context.Context, req TransportRequest) (result TransportResult, err error)

Run connects to each verified hop and executes the command once.

type PTYRequest

type PTYRequest struct {
	Endpoints  []TransportEndpoint
	Rows, Cols int
	Term       string
	Timeout    time.Duration
}

PTYRequest opens an explicitly human-operated terminal. Authentication is only performed by SSH; credentials must never be injected through terminal input.

type PTYSession

type PTYSession interface {
	io.ReadWriteCloser
	Resize(rows, cols int) error
	Wait() error
}

PTYSession is a single-owner human terminal without reattachment.

type PTYTransport

type PTYTransport interface {
	OpenPTY(context.Context, PTYRequest) (PTYSession, error)
}

PTYTransport opens authenticated human terminal sessions.

type Parameter

type Parameter struct {
	Values []string `json:"values"`
}

Parameter bounds the set of values accepted by a reviewed command template.

type RPCTransport

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

RPCTransport never retries a request: an HTTP failure after transmission is ambiguous even when no SSH acknowledgement made it back to the controller.

func NewRPCTransport

func NewRPCTransport(endpoint string, key []byte) (*RPCTransport, error)

NewRPCTransport creates a no-retry client over TLS or a private Unix socket.

func (*RPCTransport) OpenPTY

func (t *RPCTransport) OpenPTY(parent context.Context, req PTYRequest) (PTYSession, error)

OpenPTY authenticates one terminal over the private worker channel.

func (*RPCTransport) Run

Run sends a single authenticated request without replay on transport failure.

type RemoteJob

type RemoteJob struct {
	ID          string `json:"id"`
	OwnerID     string `json:"owner_id"`
	RouteID     string `json:"route_id"`
	Root        string `json:"root"`
	CommandHash string `json:"command_hash"`
	ExecutionID string `json:"execution_id"`
	State       string `json:"state"`
}

RemoteJob keeps immutable execution identity even when the remote outcome is unknown.

type Route

type Route struct {
	ID       string `json:"id"`
	OwnerID  string `json:"owner_id"`
	Label    string `json:"label"`
	Hops     []Hop  `json:"hops"`
	Enabled  bool   `json:"enabled"`
	Revision int    `json:"revision"`
}

Route contains an ordered sequence of bastions and the destination.

type Runbook

type Runbook struct {
	ID         string               `json:"id"`
	OwnerID    string               `json:"owner_id"`
	RouteID    string               `json:"route_id"`
	Label      string               `json:"label"`
	Command    string               `json:"command"`
	Parameters map[string]Parameter `json:"parameters"`
	Revision   int                  `json:"revision"`
	Enabled    bool                 `json:"enabled"`
}

Runbook is a versioned, owner-authored command with finite parameter choices.

type RunbookRequest

type RunbookRequest struct {
	RunbookID      string            `json:"runbook_id"`
	Parameters     map[string]string `json:"parameters"`
	TimeoutSeconds int               `json:"timeout_seconds"`
}

RunbookRequest contains only validated runbook parameters and an execution budget.

type ScheduledRun

type ScheduledRun struct {
	TaskID      int64  `json:"task_id"`
	OwnerID     string `json:"owner_id"`
	RequestHash string `json:"request_hash"`
	ExecutionID string `json:"execution_id"`
	State       string `json:"state"`
}

ScheduledRun is a durable no-replay claim for one scheduler queue task.

type Scope

type Scope struct {
	OwnerID  string `json:"owner_id"`
	CallerID string `json:"caller_id"`
}

Scope identifies the authenticated owner and trusted calling adapter.

type Secret

type Secret struct {
	Password   string `json:"password,omitempty"`
	PrivateKey string `json:"private_key,omitempty"`
	Passphrase string `json:"passphrase,omitempty"`
}

Secret is write-only authentication material supplied outside model input.

type Server

type Server struct {
	ID          string   `json:"id"`
	OwnerID     string   `json:"owner_id"`
	Label       string   `json:"label"`
	Address     string   `json:"address"`
	Port        int      `json:"port"`
	HostKeys    []string `json:"host_keys"`
	TrustSource string   `json:"trust_source"`
	Enabled     bool     `json:"enabled"`
	Revision    int      `json:"revision"`
}

Server describes a pinned SSH endpoint owned by one principal.

type Service

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

Service authorizes, records and dispatches owner-scoped SSH operations.

func NewService

func NewService(path string, vault *credential.Store, t Transport) (*Service, error)

NewService opens a private, exclusively locked persistent catalog.

func (*Service) Artifact

func (s *Service) Artifact(sc Scope, id string) (Artifact, error)

Artifact decrypts one unexpired private artifact for its owner.

func (*Service) Cancel

func (s *Service) Cancel(sc Scope, id string) error

Cancel disconnects an owner operation without promising remote termination.

func (*Service) Close

func (s *Service) Close() error

Close cancels work and releases the persistent catalog lock.

func (*Service) CredentialChanged

func (s *Service) CredentialChanged(name string) error

CredentialChanged invalidates approvals and disconnects work using a changed or deleted vault identity. It must be wired to the vault lifecycle publisher.

func (*Service) Execute

func (s *Service) Execute(ctx context.Context, sc Scope, req ExecuteRequest, confirm ConfirmFunc) (Execution, error)

Execute authorizes and confirms an arbitrary SSH command.

func (*Service) ExecuteOperation

func (s *Service) ExecuteOperation(ctx context.Context, sc Scope, r ExecuteRequest, c ConfirmFunc) (Execution, error)

ExecuteOperation uses the same consent and durable dispatcher for file and managed job operations.

func (*Service) ExecuteRunbook

func (s *Service) ExecuteRunbook(ctx context.Context, sc Scope, in RunbookRequest) (Execution, error)

ExecuteRunbook permits unattended dispatch only through an exact standing grant.

func (*Service) ExecuteScheduledRunbook

func (s *Service) ExecuteScheduledRunbook(ctx context.Context, owner, firing string, in RunbookRequest) (Execution, error)

ExecuteScheduledRunbook claims a firing before dispatch. A crash leaves an unknown result; re-delivery never repeats the remote operation.

func (*Service) GenerateIdentity

func (s *Service) GenerateIdentity(ctx context.Context, sc Scope, identity Identity) (Identity, error)

GenerateIdentity writes generated private material directly to the encrypted credential store. Only public metadata is returned to the caller.

func (*Service) InstallPublicKey

func (s *Service) InstallPublicKey(ctx context.Context, sc Scope, routeID, identityID string, confirm ConfirmFunc) (KeyInstallation, error)

InstallPublicKey adds an exact managed entry through an approved execution.

func (*Service) ModelOutputArtifact added in v0.54.0

func (s *Service) ModelOutputArtifact(ctx context.Context, sc Scope, executionID string) (Artifact, []string, error)

ModelOutputArtifact releases output only from an explicitly approved ordinary execution while its exact original authorization remains valid. Artifact IDs supplied by callers are never accepted by this API. Exact credential values are returned transiently for the trusted adapter to redact: neither these values nor the unsanitized artifact may be sent directly to the model.

func (*Service) OpenTerminal

func (s *Service) OpenTerminal(ctx context.Context, sc Scope, in TerminalRequest) (Terminal, PTYSession, error)

OpenTerminal consumes one durable approval. There is no reconnect or replay.

func (*Service) Preview

func (s *Service) Preview(sc Scope, req ExecuteRequest) (Approval, error)

Preview freezes the exact owner/caller/route/identity revisions and command.

func (*Service) PreviewOperation

func (s *Service) PreviewOperation(sc Scope, r ExecuteRequest) (Approval, error)

PreviewOperation freezes file or managed job consent using the shared policy.

func (*Service) PreviewTerminal

func (s *Service) PreviewTerminal(sc Scope, in TerminalRequest) (Approval, error)

PreviewTerminal freezes one terminal session for explicit owner approval.

func (*Service) PutGrant

func (s *Service) PutGrant(sc Scope, x Grant) (Grant, error)

PutGrant authorizes one caller against an exact route revision.

func (*Service) PutIdentity

func (s *Service) PutIdentity(ctx context.Context, sc Scope, x Identity, secret *Secret) (Identity, error)

PutIdentity stores authentication material in the encrypted credential vault.

func (*Service) PutRoute

func (s *Service) PutRoute(sc Scope, x Route) (Route, error)

PutRoute validates and records an ordered owner-scoped route.

func (*Service) PutRunbook

func (s *Service) PutRunbook(sc Scope, b Runbook) (Runbook, error)

PutRunbook replaces the reviewed owner definition and invalidates prior standing grants.

func (*Service) PutServer

func (s *Service) PutServer(sc Scope, x Server) (Server, error)

PutServer creates or revises owner-scoped endpoint trust.

func (*Service) ReconcilePublicKey

func (s *Service) ReconcilePublicKey(ctx context.Context, sc Scope, id, routeID string, confirm ConfirmFunc) (KeyInstallation, error)

ReconcilePublicKey observes an ambiguous installation/removal without replaying a mutation. An absent exact managed entry is distinguished from inspection errors by its dedicated exit status. It never claims authentication succeeded.

func (*Service) RemovePublicKey

func (s *Service) RemovePublicKey(ctx context.Context, sc Scope, id, alternateID, routeID string, confirm ConfirmFunc) (KeyInstallation, error)

RemovePublicKey never removes an unmanaged line or the last verified key.

func (*Service) RotatePublicKey

func (s *Service) RotatePublicKey(ctx context.Context, sc Scope, oldID, bootstrapRoute, newIdentityID, newRoute string, confirm ConfirmFunc) (KeyInstallation, error)

RotatePublicKey composes independently approved installation, login and removal. New key installation and independent login must finish before old-key removal.

func (*Service) SetEnabled

func (s *Service) SetEnabled(enabled bool) error

SetEnabled changes global admission and cancels active work on disable.

func (*Service) SetPrincipalChecker

func (s *Service) SetPrincipalChecker(check func(context.Context, string) bool)

SetPrincipalChecker configures the trusted account-state check used at admission and periodically for active operations. Production adapters must configure it.

func (*Service) Snapshot

func (s *Service) Snapshot(sc Scope) Catalog

Snapshot returns a detached owner-scoped metadata inventory.

func (*Service) VerifyInstallation

func (s *Service) VerifyInstallation(ctx context.Context, sc Scope, id, routeID string, confirm ConfirmFunc) (KeyInstallation, error)

VerifyInstallation requires a separately authorized route using the NEW key.

type Terminal

type Terminal struct {
	ExecutionID string `json:"execution_id"`
	RouteID     string `json:"route_id"`
}

Terminal identifies the auditable execution without exposing credentials.

type TerminalOptions

type TerminalOptions struct {
	Rows           int    `json:"rows"`
	Cols           int    `json:"cols"`
	Term           string `json:"term"`
	TimeoutSeconds int    `json:"timeout_seconds"`
}

TerminalOptions defines one explicitly approved human terminal session.

type TerminalRequest

type TerminalRequest struct {
	RouteID          string          `json:"route_id"`
	Options          TerminalOptions `json:"options"`
	ApprovalID       string          `json:"approval_id,omitempty"`
	ExpectedPlanHash string          `json:"expected_plan_hash,omitempty"`
}

TerminalRequest binds terminal consent to the route and immutable dimensions.

type Transport

type Transport interface {
	Run(context.Context, TransportRequest) (TransportResult, error)
}

Transport executes exactly one request without automatic retries.

type TransportEndpoint

type TransportEndpoint struct {
	Address                          string
	Port                             int
	Username                         string
	HostKeys                         []string
	Password, PrivateKey, Passphrase string
}

TransportEndpoint contains short-lived resolved credentials. Never log this value.

type TransportRequest

type TransportRequest struct {
	Operation  string
	File       *FileRequest
	Background *BackgroundRequest
	Endpoints  []TransportEndpoint
	Command    string
	Timeout    time.Duration
}

TransportRequest fixes the route, remote command and total time budget.

type TransportResult

type TransportResult struct {
	File           *FileResult
	Background     *BackgroundResult
	ExitCode       *int
	Stdout, Stderr []byte
	Truncated      bool
	Dispatched     bool
	ErrorCode      string
}

TransportResult separates remote exit status from ambiguous transport loss.

type WorkerHandler

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

WorkerHandler must be served behind TLS or on a private unix socket. Nonces are durably claimed before dispatch, including across worker restarts.

func NewWorkerHandler

func NewWorkerHandler(key []byte, cidrs []string, stateDir string) (*WorkerHandler, error)

NewWorkerHandler validates destination networks and durable replay storage.

func (*WorkerHandler) ServeHTTP

func (h *WorkerHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*WorkerHandler) ServePTY

func (h *WorkerHandler) ServePTY(w http.ResponseWriter, r *http.Request)

ServePTY accepts a single authenticated, durable-nonce terminal open frame. All subsequent input belongs to this connection only: no attach or replay API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址