bot-bottle/docs/prds/0046-ssh-config-provisioning.md

PRD 0046: SSH Config Provisioning

• Status: Draft
• Author: didericis-codex
• Created: 2026-06-02
• Issue: #150

Summary

Add top-level bottle SSH client config support so operators can provide approved Host stanzas to the agent and git environment without using ExtraHosts as a DNS override. This lets SSH remotes that rely on host aliases work inside a bottle while HTTP/API traffic continues to resolve through the declared egress route.

Problem

git.remotes.*.ExtraHosts is currently the available mechanism for steering git-gate reachability when an upstream host needs an explicit address. That is useful when the gate itself needs hosts-file resolution, but it is the wrong tool for ordinary SSH client aliasing.

The Gitea remote case needs the bottle to carry operator-approved SSH client config into the agent/git environment. Local SSH config can make git@gitea:didericis/bot-bottle.git resolve to the same endpoint as ssh://git@gitea.dideric.is:30009/didericis/bot-bottle.git, but encoding that as ExtraHosts can affect Docker extra_hosts, sidecar hosts config, agent hosts config, and egress DNS. That coupling can break HTTP/API access because the egress path sees the public hostname resolving to an internal address.

Goals / Success Criteria

• The manifest parser accepts a top-level ssh.config list.
• Each config entry supports at least Host, Hostname, Port, User, and IdentityFile.
• IdentityFile values are host-side paths, and provisioning stages or mounts the referenced key material through the existing key-handling path.
• Generated in-bottle SSH config rewrites IdentityFile to the staged in-bottle key path.
• Private key contents are never printed, logged, committed, or inlined into the manifest or generated config outside the intended staged key file.
• Git operations using SSH host aliases, such as git@gitea:didericis/bot-bottle.git, work because SSH sees the provisioned Host gitea stanza.
• ssh.config entries do not alter Docker extra_hosts, sidecar hosts config, agent hosts config, git-gate ExtraHosts, or egress route DNS.
• Documentation distinguishes SSH client config, git insteadOf rewrites, and ExtraHosts.

Non-goals

• No gitconfig-only alias feature.
• No change to git.remotes.*.ExtraHosts; it remains the explicit hosts override mechanism for git-gate reachability.
• No automatic import of the operator's full host ~/.ssh/config.
• No SSH config support for arbitrary OpenSSH directives beyond the fields listed in this PRD.
• No private key material in manifests, logs, PRDs, tests, or generated non-key config files.
• No changes to HTTP/API egress auth or DNS routing semantics.

Scope

In scope:

• Add manifest model and schema support for top-level ssh.config.
• Validate required SSH config fields and reject malformed entries with clear manifest errors.
• Add a shared provisioning plan for staged SSH config and referenced identity files.
• Apply the provisioning plan in both Docker and smolmachines agent/git environments.
• Update focused unit tests for parsing, rendered SSH config, key path rewriting, and hosts/DNS isolation.
• Update user documentation and examples.

Out of scope:

• Integration tests that require a live SSH server.
• Reworking git-gate URL rewriting or gitleaks scanning.
• Supporting Include, Match, ProxyCommand, CertificateFile, or other advanced SSH config directives.
• Per-command SSH config injection for tools outside the bottle's provisioned environment.

Design

Add a top-level ssh manifest block:

git:
  remotes:
    gitea.dideric.is:
      Name: bot-bottle
      Upstream: ssh://git@gitea.dideric.is:30009/didericis/bot-bottle.git

ssh:
  config:
    - Host: gitea
      Hostname: 100.78.141.42
      Port: 30009
      User: git
      IdentityFile: ~/.ssh/gitea-delos-2.pem
    - Host: gitea.dideric.is
      Hostname: 100.78.141.42
      Port: 30009
      User: git
      IdentityFile: ~/.ssh/gitea-delos-2.pem

Represent each entry with a small manifest dataclass, for example:

@dataclass(frozen=True)
class SshConfigEntry:
    Host: str
    Hostname: str
    Port: int
    User: str
    IdentityFile: str

BottleManifest should expose the parsed entries on the bottle object, similar to existing git, env, and egress accessors. Parser validation should require non-empty strings for Host, Hostname, User, and IdentityFile, and an integer Port in the valid TCP port range.

Provisioning

Build an SSH provisioning plan during backend prepare. The plan should:

1. Expand each host-side IdentityFile path using the existing tilde and key-file validation behavior.
2. Stage or mount each referenced key through the same private-key handling path used for git remotes.
3. Assign each staged key a stable in-bottle path with private file permissions.
4. Render an OpenSSH-compatible config file where each IdentityFile points to the staged in-bottle key path.
5. Install the rendered config where agent and git commands will use it by default.

The rendered config should contain only SSH directives and staged key paths. It must not contain private key contents, host-side private key paths, or any secret-derived material.

Isolation from Hosts and Egress

ssh.config is SSH client configuration only. It must not be translated into:

• Docker extra_hosts.
• Sidecar hosts config.
• Agent hosts config.
• Git-gate ExtraHosts.
• Egress route DNS or auth config.

Git remotes continue to use insteadOf rewrites for git-gate routing. If an operator needs a hosts-file override for the gate itself, they should continue to use git.remotes.*.ExtraHosts. If they need SSH client aliases for the agent/git environment, they should use ssh.config.

Testing Strategy

• Unit-test manifest parsing for valid ssh.config entries.
• Unit-test parser errors for missing fields, empty string fields, non-integer ports, and out-of-range ports.
• Unit-test SSH config rendering to prove Host, Hostname, Port, User, and rewritten IdentityFile lines are emitted correctly.
• Unit-test duplicate IdentityFile handling so repeated keys are staged once or otherwise handled deterministically.
• Unit-test Docker and smolmachines provisioning plans install the same logical SSH config and staged key paths.
• Unit-test that ssh.config entries do not appear in Docker extra_hosts, sidecar hosts config, agent hosts config, git-gate ExtraHosts, or egress route config.
• Unit-test documentation examples through the existing manifest loader where practical.

Run:

• python3 -m unittest discover -s tests/unit

Open Questions

None.