diff --git a/docs/prds/0046-ssh-config-provisioning.md b/docs/prds/0046-ssh-config-provisioning.md new file mode 100644 index 0000000..2ac31dd --- /dev/null +++ b/docs/prds/0046-ssh-config-provisioning.md @@ -0,0 +1,185 @@ +# 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: + +```yaml +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: + +```python +@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.