# KHY Remote SSH Rollout Checklist (Phase 0.7)

This checklist translates the Remote SSH vision into implementation-ready tasks under current KHY-OS architecture.

## 0. Scope

Goal:
- Connect KHY-OS to team-managed remote development environments via SSH.
- Reuse the same security relay, redaction gateway, approval flow, and cross-device handover.

Out of scope (Phase 0.7):
- Kubernetes-level multi-node orchestration.
- Persistent remote agent marketplace.

## 1. Service Decomposition (Backend)

Add services under `backend/src/services/remote/`:

1. `sshConfigService.js`
- Parse and watch `~/.ssh/config`.
- Expose normalized host entries (alias, host, port, user, identityFile, proxyJump).

2. `sshCredentialGuard.js`
- Validate key path readability and file mode.
- Block insecure key files and unsafe agent-forward defaults by policy.

3. `sshConnectionManager.js`
- Own SSH connection lifecycle.
- Manage `connection_id`, health state, reconnect backoff, and idle close.

4. `remoteWorkspaceResolver.js`
- Resolve remote cwd/workspace per host profile.
- Validate allowed workspace prefixes.

5. `remoteExecService.js`
- Execute remote commands with stream callbacks.
- Emit structured execution events (`step_start`, `stdout_chunk`, `step_end`).

6. `remoteApprovalBridge.js`
- Route high-risk remote actions into the same approval ticket flow.
- Ensure no remote bypass of approval.

7. `remoteStateSyncService.js`
- Feed remote task states into cross-device snapshot builder.
- Include pending approvals and active remote sessions.

## 2. API / Interface Contracts

Recommended routes under `backend/src/routes/remoteSsh.js`:

1. `GET /api/remote/ssh/hosts`
- Return discovered SSH hosts from `~/.ssh/config`.

2. `POST /api/remote/ssh/connect`
- Input:
  - `hostAlias` (required)
  - `workspace` (optional)
  - `purpose` (optional, default `development`)
- Output:
  - `connection_id`
  - `status` (`connected|reconnecting|failed`)
  - `host`, `user`, `workspace`, `trace_id`

3. `POST /api/remote/ssh/disconnect`
- Input: `connection_id`
- Output: `status`

4. `POST /api/remote/ssh/exec`
- Input:
  - `connection_id`
  - `commands[]`
  - `risk_context` (optional)
  - `dry_run` (default `true`)
- Behavior:
  - Risk classify each command.
  - If high risk and not pre-approved, return `approval_required`.
  - If approved, execute and stream events.

5. `GET /api/remote/ssh/sessions`
- Return active connections and health summary.

## 3. Event Fields (Streaming + Trace)

All remote events should include:
- `trace_id`
- `connection_id`
- `host_alias`
- `remote_user`
- `remote_workspace`
- `sequence`
- `ts`
- `kind`
- `severity`
- `redaction_applied`

Recommended `kind`:
- `remote_connection_state`
- `remote_exec_step`
- `remote_exec_stdout`
- `remote_exec_stderr`
- `remote_approval_required`
- `remote_exec_summary`

## 4. Security and Policy Enforcement

1. Command risk policy:
- Reuse existing command classification path (`safe/moderate/dangerous/critical`).
- Apply same approval rules as local execution.

2. Data egress policy:
- Never push full source file content to mobile.
- Remote output to mobile passes through redaction gateway first.

3. SSH hardening defaults:
- Disable unsafe shell interpolation in command templates.
- Deny remote execution on unknown host alias unless explicitly allowed.
- Keep optional allowlist for host aliases (`KHY_REMOTE_SSH_ALLOWLIST`).

4. Audit:
- Persist connect/disconnect/exec/approval events with `trace_id`.

## 5. Cross-Device Continuity Requirements

When switching between local terminal, mobile, and remote SSH:
- Include active remote sessions in handover snapshot.
- Include pending remote approvals in same approval queue.
- Preserve in-progress remote task state (`running`, `retry_wait`, `paused`).

## 6. Minimal Test Matrix

Add tests under `backend/tests/remote/`:

1. `sshConfigService.test.js`
- Parse multi-host `~/.ssh/config`.
- Handles `Host *` defaults and host overrides.

2. `sshConnectionManager.test.js`
- Successful connect/disconnect.
- Reconnect with exponential backoff after network drop.

3. `remoteExecService.test.js`
- Streams stdout/stderr in order with sequence monotonicity.
- Handles command timeout and cancellation.

4. `remoteApprovalBridge.test.js`
- High-risk command returns approval ticket before execution.
- Approved ticket executes exactly once.

5. `remoteStateSyncService.test.js`
- Snapshot includes remote sessions + pending approvals.

6. `remoteRedactionPipeline.test.js`
- Secrets in remote output are masked before mobile event emission.

7. `remoteSsh.route.test.js`
- Route-level validation for connect/exec/disconnect.
- Authorization and malformed payload rejection.

## 7. Rollout Plan (Suggested)

Week 1:
- Implement host discovery, connection manager, connect/disconnect APIs.

Week 2:
- Implement remote exec streaming + approval bridge + redaction pipeline.

Week 3:
- Integrate cross-device snapshot and add full remote test matrix.

## 8. Phase Exit Criteria

- `~/.ssh/config` hosts can be discovered and connected reliably.
- High-risk remote commands cannot run without approval.
- Remote execution stream is visible on mobile and desktop with redaction.
- Device switching preserves remote task and approval continuity.

