sshremote

type ErrHostKeyMismatch ¶

type ErrHostKeyMismatch struct {
	// Host is the address (as passed to Verify) whose key changed.
	Host string
	// Fingerprint is the SHA256 fingerprint of the NEW, untrusted key that
	// was presented -- not any of the previously-trusted keys.
	Fingerprint string
	// Err is the underlying *knownhosts.KeyError.
	Err error
}

ErrHostKeyMismatch is returned by Verify when host was previously trusted under a DIFFERENT key than the one presented now -- knownhosts' own KeyError doc comment calls this out as a possible MITM signal. This is deliberately a distinct type from ErrUnknownHostKey: a caller that only checks for ErrUnknownHostKey (e.g. to decide whether to show a "trust and connect" prompt) must NOT have a key-mismatch silently fall through the same code path -- it needs its own explicit handling, and in particular must never be treated as "safe to connect."

func (e *ErrHostKeyMismatch) Error() string

func (e *ErrHostKeyMismatch) Unwrap() error

type ErrUnknownHostKey ¶

type ErrUnknownHostKey = tmux.ErrUnknownHostKey

ErrUnknownHostKey is re-exported from session/tmux so callers of Verify (and RemoteService, which maps it to a structured RPC response) only ever need to errors.As against one type, whether the error came from this store's Verify directly or, transitively, from a *tmux.SSHRunner dialed with HostKeyCallback(). There's no import-cycle risk re-using it: tmux never imports sshremote (Phase 3's wiring layer, not yet written, is expected to import both from a third package rather than have tmux depend on this one -- see NewSSHRunner's doc comment).

type GeneratedIdentity ¶

type GeneratedIdentity struct {
	// PrivateKeyPEM is the OpenSSH-format PEM-encoded private key, suitable
	// for both KeyStore.SetIdentity and ssh.ParsePrivateKey/
	// ssh.NewSignerFromKey-compatible consumption once parsed back.
	PrivateKeyPEM []byte
	// PublicKeyText is the bare authorized_keys-format public key line
	// ("ssh-ed25519 AAAA...", no trailing newline, no options).
	PublicKeyText string
	// AuthorizedKeysLine is PublicKeyText prefixed with the ADR-004
	// recommended command=/restrict/pty scoping options, ready to display
	// to the user during remote onboarding (Phase 6, Epic 6.1) as
	// copy-paste text -- not something this package installs anywhere.
	AuthorizedKeysLine string
}

GeneratedIdentity is the result of generating a fresh per-remote Ed25519 SSH keypair.

func GenerateIdentity(remoteName string) (GeneratedIdentity, error)

type HealthEventPublisher ¶

type HealthEventPublisher interface {
	// PublishRemoteHealthChanged is called synchronously on every actual
	// state transition (never on a no-op "transitioned to the state it was
	// already in" check) -- implementations that do I/O should not block
	// the prober's watcher/liveness goroutines for long.
	PublishRemoteHealthChanged(remoteName string, state, previousState RemoteConnectionState)
}

HealthEventPublisher is anything that can be notified of a remote's connection-state transition. Defined here (the consumer package) rather than importing pkg/events.EventBus/NewRemoteHealthChangedEvent directly, which would create the import cycle described on RemoteConnectionState's doc comment -- mirrors PermissionRequestHandler's identical rationale in approval_relay.go.

Unlike PermissionRequestHandler (which *server/services.ApprovalHandler already satisfies structurally with zero changes), no existing production type satisfies this interface yet: pkg/events.EventBus.Publish takes a *pkg/events.Event, not this signature. The production wiring that starts a RemoteHealthProber per configured remote (Task 6.4.1c, server/server.go -- out of scope for this change) is expected to supply a small adapter that calls events.NewRemoteHealthChangedEvent(remoteName, state, previousState) and hands the result to an *events.EventBus.Publish.

type IdentityKind ¶

type IdentityKind string

IdentityKind tags which of the two logical value kinds an identity envelope holds -- a raw private key, or a passphrase protecting one. Both kinds live under the same key namespace (keyPrefix + remote name); the tag is what lets GetIdentity tell them apart on read-back.

const (
	// IdentityKindPrivateKey tags an envelope holding raw private key bytes
	// (e.g. an OpenSSH-format PEM block).
	IdentityKindPrivateKey IdentityKind = "private_key"
	// IdentityKindPassphrase tags an envelope holding a passphrase that
	// protects an encrypted private key.
	IdentityKindPassphrase IdentityKind = "passphrase"
)

type KeyStore ¶

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

KeyStore stores SSH identity material (private keys and passphrases) in the OS keychain, keyed per remote name -- never in a file under ~/.stapler-squad/, and never with an on-disk fallback if the keychain is unavailable (per research/build-vs-buy.md §3: fail loud instead).

func NewKeyStore(opts ...KeyStoreOption) *KeyStore

func (ks *KeyStore) DeleteIdentity(ctx context.Context, remoteName string) error

func (ks *KeyStore) GenerateAndStoreIdentity(ctx context.Context, remoteName string) (GeneratedIdentity, error)

func (ks *KeyStore) GenerateOrDescribeIdentity(ctx context.Context, remoteName string) (GeneratedIdentity, error)

func (ks *KeyStore) GetIdentity(ctx context.Context, remoteName string) (IdentityKind, []byte, error)

func (ks *KeyStore) SetIdentity(ctx context.Context, remoteName string, kind IdentityKind, value []byte) error

type KeyStoreOption ¶

type KeyStoreOption func(*KeyStore)

KeyStoreOption configures a KeyStore at construction time.

type KnownHostsStore ¶

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

KnownHostsStore is a file-backed, app-managed known_hosts-equivalent store for TOFU (trust-on-first-use) SSH host-key decisions, using golang.org/x/crypto/ssh/knownhosts' standard file format (knownhosts.New()/knownhosts.Line()) so the backing file stays inspectable with ordinary SSH tooling even though it's never read by a real ssh(1)/ sshd(8) process.

func NewKnownHostsStore(opts ...KnownHostsStoreOption) (*KnownHostsStore, error)

func (s *KnownHostsStore) HostKeyCallback() ssh.HostKeyCallback

func (s *KnownHostsStore) IsHostTrusted(host string) (bool, error)

func (s *KnownHostsStore) Trust(host string, key ssh.PublicKey) error

func (s *KnownHostsStore) Verify(host string, key ssh.PublicKey) error

type KnownHostsStoreOption ¶

type KnownHostsStoreOption func(*KnownHostsStore)

KnownHostsStoreOption configures a KnownHostsStore at construction time.

type PermissionRequestHandler ¶

type PermissionRequestHandler interface {
	HandlePermissionRequest(w http.ResponseWriter, r *http.Request)
}

PermissionRequestHandler is anything that can process a raw PermissionRequest hook payload the same way server/services.ApprovalHandler.HandlePermissionRequest does -- defined here (the consumer package) rather than imported from server/services, which would create an import cycle (server/services already imports session/sshremote for KeyStore/KnownHostsStore). *server/services. ApprovalHandler already has exactly this method signature and satisfies this interface structurally, with zero changes there.

type RemoteApprovalRelay ¶

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

RemoteApprovalRelay reads approval-request payloads a remote agent process writes to a fixed Unix domain socket on the remote host (RemoteApprovalSocketPath) via a direct-streamlocal@openssh.com channel dialed over the SAME pooled *ssh.Client the session's terminal stream already uses, and drives them through PermissionRequestHandler exactly the way Claude Code's real HTTP PermissionRequest hook does -- see ADR-003 (project_plans/ssh-remote-workspaces/decisions/) for why this reuses the existing multiplexed SSH connection instead of a reverse tunnel or a third-party tunneling library, and its addendum for why the forwarding target changed from Epic 5.1's original session.ExternalApprovalMonitor to this handler-based design.

Unlike Epic 5.1's original design (request-direction-only, closing the connection immediately after decoding), this merges the request and response into a single blocking round trip: handleConnection decodes the payload, builds a synthetic *http.Request from its raw bytes, calls PermissionRequestHandler.HandlePermissionRequest -- which BLOCKS until a human decision is made or its own configured timeout fires, exactly as it does for a real local HTTP hook -- and writes the resulting response body back onto the SAME connection before closing it, so the remote-side hook script (server/services.remoteApprovalHookCommand's socat pipeline) gets the identical bytes curl's stdout would have gotten locally. This subsumes what was originally planned as a separate Epic 5.3 response- delivery step: merging request+response into one blocking round trip is simpler than two independent half-duplex pieces and was never separately buildable once PermissionRequestHandler (not ExternalApprovalMonitor) was identified as the correct target.

Known v1 constraint (not addressed here): the remote-host socket path is fixed per session, so only one approval can be in flight per remote session at a time -- handleConnection blocks the poll loop for the duration of the human decision, and a second concurrent request has nowhere to connect until the first completes. Acceptable per the original plan design; not solved by this change.

RemoteApprovalRelay never dials the SSH connection pool itself -- it only subscribes (via pool.Subscribe) to whichever *ssh.Client is CURRENTLY pooled for remoteName. Some other component (terminal streaming, per Phase 4/session/tmux.SSHRunner) is responsible for establishing and redialing that connection; decoupling the relay from dial config/ credentials entirely means it has nothing more to configure than "which pooled connection" and "which remote-side socket."

func NewRemoteApprovalRelay(
	pool *tmux.SSHClientPool,
	handler PermissionRequestHandler,
	target RemoteApprovalRelayTarget,
	opts ...RemoteApprovalRelayOption,
) (*RemoteApprovalRelay, error)

func (r *RemoteApprovalRelay) BearerToken() (token string, expiresAt time.Time)

func (r *RemoteApprovalRelay) RotateToken() error

func (r *RemoteApprovalRelay) Start(ctx context.Context)

func (r *RemoteApprovalRelay) Stop()

type RemoteApprovalRelayOption ¶

type RemoteApprovalRelayOption func(*RemoteApprovalRelay)

RemoteApprovalRelayOption configures a RemoteApprovalRelay at construction time.

type RemoteApprovalRelayTarget ¶

type RemoteApprovalRelayTarget struct {
	// RemoteName is the SSHClientPool key this relay's channel is dialed
	// under (session/tmux.SSHClientPool). Must match the same name the
	// session's own tmux.SSHRunner/tmux.SSHTarget was constructed with, so
	// this relay shares the SAME pooled *ssh.Client the terminal stream
	// uses (ADR-003) rather than dialing an unrelated connection.
	RemoteName string
	// BasePath is the session's remote-host working-directory root -- i.e.
	// its worktree path on the remote host (session.Instance.
	// GetEffectiveRootDir()), NOT the remote's shared config.RemoteConfig.
	// BasePath. RemoteApprovalSocketPath is derived from it, so the fixed
	// socket this relay reads from is scoped to ONE session, not shared
	// across every session on the same remote (which would make the "one
	// approval in flight at a time" constraint apply across unrelated
	// sessions instead of within a single one).
	BasePath string
	// StableSessionID is written into the synthetic HTTP request's
	// X-CS-Session-ID header before it's handed to PermissionRequestHandler
	// -- must be the SAME stable ID server/services.ApprovalHandler.
	// resolveSessionID resolves this session to locally
	// (session.Instance.GetStableID(): UUID, falling back to Title), or the
	// handler silently fails to correlate the relayed request with the
	// right session's approval UI/notifications. Renamed from Epic 5.1's
	// "SessionKey" (a session.ExternalApprovalMonitor lookup key that no
	// longer applies once this relay stopped forwarding into that
	// subsystem -- see ADR-003's addendum) to name what this value is
	// actually used for now.
	StableSessionID string
	// Title is used only for this relay's own log messages; the local
	// approval UI's session title comes from PermissionRequestHandler's own
	// session lookup (ApprovalHandler.resolveSessionName), not from here.
	Title string
}

RemoteApprovalRelayTarget bundles the four caller-supplied identifiers NewRemoteApprovalRelay needs. Deliberately a struct, not four adjacent string parameters: RemoteName/BasePath/StableSessionID/Title are independently meaningful, same-typed strings a caller could silently transpose at a call site with no compiler error (e.g. passing StableSessionID where Title is expected still compiles) -- exactly what the `primitive-obsession-checklist` skill exists to catch. Field names carry the disambiguation a positional four-string parameter list can't.

type RemoteConnectionState ¶

type RemoteConnectionState string

RemoteConnectionState identifies where a configured remote's SSH connection currently stands, as tracked by RemoteHealthProber. No prior definition of this concept exists anywhere in the codebase (grepped session/, server/, pkg/ for RemoteConnectionState/ConnectionState before adding this) -- defined here, alongside the prober that owns the state machine, rather than in pkg/events: pkg/events imports session, and session (session/instance.go) already imports session/sshremote, so session/sshremote importing pkg/events back would be an import cycle (confirmed via `go list -deps`). This mirrors why PermissionRequestHandler is defined in THIS package rather than imported from server/services (see approval_relay.go's doc comment) -- same cycle shape, one layer over. pkg/events references this type instead (session/sshremote has no dependency back on pkg/events or session, so that direction is cycle-free) -- the same shape session/detection.DetectedStatus already has via pkg/events.Event.DetectedStatusTyped.

const (
	// RemoteConnectionStateDisconnected is a RemoteHealthProber's initial
	// state, and the state entered when either (a) the pooled *ssh.Client's
	// Wait() returns (a hard, push-driven disconnect signal), or (b) a
	// reconnect attempt has not yet succeeded.
	RemoteConnectionStateDisconnected RemoteConnectionState = "disconnected"
	// RemoteConnectionStateConnected is entered once the pooled *ssh.Client
	// is live and the most recent liveness check succeeded.
	RemoteConnectionStateConnected RemoteConnectionState = "connected"
	// RemoteConnectionStateReconnecting is a soft, between-hard-disconnects
	// signal: the pooled *ssh.Client's Wait() has not returned (no hard
	// teardown observed), but the most recent periodic liveness check (a
	// trivial no-op remote command) failed -- e.g. a stalled or degraded
	// network path, or the remote host rejecting new channels while the
	// underlying transport connection is still technically up.
	RemoteConnectionStateReconnecting RemoteConnectionState = "reconnecting"
)

type RemoteHealthProber ¶

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

RemoteHealthProber tracks one configured remote's SSH connection health and publishes push-driven connected/reconnecting/disconnected state transitions via HealthEventPublisher, per Epic 6.4 / Story 6.4.1.

It never dials a dedicated connection of its own: runner must be constructed against the SAME SSHClientPool passed as pool (and the same SSHTarget.Name as remoteName), so both this prober's liveness checks and any session's own SSHRunner/RemoteApprovalRelay for the same remote share exactly one dialed *ssh.Client (see tmux.SSHRunner.Dial's doc comment, which names RemoteHealthProber as its reuse case). Disconnect detection is driven primarily by that shared client's Wait() -- a push/blocking signal, not a poll loop -- with a periodic lightweight liveness check (SSHRunner.Run(ctx, "", "true")) filling the gap Wait() alone can't see: a connection that hasn't hard-failed yet but also isn't currently answering commands.

func NewRemoteHealthProber(
	pool *tmux.SSHClientPool,
	runner *tmux.SSHRunner,
	remoteName string,
	publisher HealthEventPublisher,
	opts ...RemoteHealthProberOption,
) (*RemoteHealthProber, error)

func (p *RemoteHealthProber) Start(ctx context.Context)

func (p *RemoteHealthProber) State() RemoteConnectionState

func (p *RemoteHealthProber) Stop()

type RemoteHealthProberOption ¶

type RemoteHealthProberOption func(*RemoteHealthProber)

RemoteHealthProberOption configures a RemoteHealthProber at construction time.