Documentation
¶
Overview ¶
Package remoteaccess owns authorization and durable native SSH executions.
Index ¶
- Constants
- Variables
- func ConnectNative(parent context.Context, endpoints []TransportEndpoint, timeout time.Duration) (*ssh.Client, io.Closer, error)
- type Approval
- type Artifact
- type BackgroundRequest
- type BackgroundResult
- type Catalog
- type ConfirmFunc
- type ExecuteRequest
- type Execution
- type FileRequest
- type FileResult
- type Grant
- type Hop
- type Identity
- type KeyInstallation
- type NativeTransport
- type PTYRequest
- type PTYSession
- type PTYTransport
- type Parameter
- type RPCTransport
- type RemoteJob
- type Route
- type Runbook
- type RunbookRequest
- type ScheduledRun
- type Scope
- type Secret
- type Server
- type Service
- func (s *Service) Artifact(sc Scope, id string) (Artifact, error)
- func (s *Service) Cancel(sc Scope, id string) error
- func (s *Service) Close() error
- func (s *Service) CredentialChanged(name string) error
- func (s *Service) Execute(ctx context.Context, sc Scope, req ExecuteRequest, confirm ConfirmFunc) (Execution, error)
- func (s *Service) ExecuteOperation(ctx context.Context, sc Scope, r ExecuteRequest, c ConfirmFunc) (Execution, error)
- func (s *Service) ExecuteRunbook(ctx context.Context, sc Scope, in RunbookRequest) (Execution, error)
- func (s *Service) ExecuteScheduledRunbook(ctx context.Context, owner, firing string, in RunbookRequest) (Execution, error)
- func (s *Service) GenerateIdentity(ctx context.Context, sc Scope, identity Identity) (Identity, error)
- func (s *Service) InstallPublicKey(ctx context.Context, sc Scope, routeID, identityID string, confirm ConfirmFunc) (KeyInstallation, error)
- func (s *Service) ModelOutputArtifact(ctx context.Context, sc Scope, executionID string) (Artifact, []string, error)
- func (s *Service) OpenTerminal(ctx context.Context, sc Scope, in TerminalRequest) (Terminal, PTYSession, error)
- func (s *Service) Preview(sc Scope, req ExecuteRequest) (Approval, error)
- func (s *Service) PreviewOperation(sc Scope, r ExecuteRequest) (Approval, error)
- func (s *Service) PreviewTerminal(sc Scope, in TerminalRequest) (Approval, error)
- func (s *Service) PutGrant(sc Scope, x Grant) (Grant, error)
- func (s *Service) PutIdentity(ctx context.Context, sc Scope, x Identity, secret *Secret) (Identity, error)
- func (s *Service) PutRoute(sc Scope, x Route) (Route, error)
- func (s *Service) PutRunbook(sc Scope, b Runbook) (Runbook, error)
- func (s *Service) PutServer(sc Scope, x Server) (Server, error)
- func (s *Service) ReconcilePublicKey(ctx context.Context, sc Scope, id, routeID string, confirm ConfirmFunc) (KeyInstallation, error)
- func (s *Service) RemovePublicKey(ctx context.Context, sc Scope, id, alternateID, routeID string, ...) (KeyInstallation, error)
- func (s *Service) RotatePublicKey(ctx context.Context, sc Scope, ...) (KeyInstallation, error)
- func (s *Service) SetEnabled(enabled bool) error
- func (s *Service) SetPrincipalChecker(check func(context.Context, string) bool)
- func (s *Service) Snapshot(sc Scope) Catalog
- func (s *Service) VerifyInstallation(ctx context.Context, sc Scope, id, routeID string, confirm ConfirmFunc) (KeyInstallation, error)
- type Terminal
- type TerminalOptions
- type TerminalRequest
- type Transport
- type TransportEndpoint
- type TransportRequest
- type TransportResult
- type WorkerHandler
Constants ¶
const FileLimit = 10 << 20
FileLimit bounds each transferred file before allocation or publication.
Variables ¶
var ErrDenied = errors.New("remote access denied")
ErrDenied reports an authorization or consent failure.
Functions ¶
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 ¶
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.
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 ¶
func (t *RPCTransport) Run(ctx context.Context, req TransportRequest) (TransportResult, error)
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 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 ¶
NewService opens a private, exclusively locked persistent catalog.
func (*Service) Cancel ¶
Cancel disconnects an owner operation without promising remote termination.
func (*Service) CredentialChanged ¶
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) 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) PutRunbook ¶
PutRunbook replaces the reviewed owner definition and invalidates prior standing grants.
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 ¶
SetEnabled changes global admission and cancels active work on disable.
func (*Service) SetPrincipalChecker ¶
SetPrincipalChecker configures the trusted account-state check used at admission and periodically for active operations. Production adapters must configure it.
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 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.