# Git over SSH

Status: SSH key management is implemented. The SSH gateway is designed here
and is not deployed; it needs infrastructure the owner provisions.

Forge serves Git over Smart HTTP from Cloudflare Workers. Developers also
expect `git clone git@forge.smol.ai:owner/repo.git`, which is how GitHub
clients usually authenticate. This document explains why SSH cannot terminate
in a Worker, what is shipped, and the small gateway that completes the feature.

## Why a Worker cannot serve SSH

A Worker receives HTTP requests (and WebSockets upgraded from them). It cannot
listen on TCP port 22 or accept an arbitrary inbound TCP stream. Cloudflare
Containers are reached only through a Worker or Durable Object over HTTP, so
they cannot accept inbound SSH from the internet either. `connect()` in Workers
is outbound only.

SSH therefore has to terminate in a process that owns a TCP listener, then
hand the Git protocol to Forge over HTTP.

## What is shipped

- `user_ssh_keys` (migration 0034): one row per public key, with a unique
  OpenSSH `SHA256:` fingerprint, so a key identifies exactly one account (as on
  GitHub). `last_used_at` is stamped on each successful lookup.
- API, session-authenticated (credentials are never managed with API tokens):
  - `GET /api/users/me/ssh-keys`
  - `POST /api/users/me/ssh-keys` with `{ "title": "Laptop", "key": "ssh-ed25519 AAAA… comment" }`
  - `DELETE /api/users/me/ssh-keys/:id`
  Accepted types: `ssh-ed25519`, `ecdsa-sha2-nistp{256,384,521}`, the `sk-`
  security-key variants, and `ssh-rsa` of at least 2048 bits. The stored key
  drops the comment; the comment becomes the default title.
- Settings → SSH keys in the web app.
- `findActiveUserBySshFingerprint()` in
  `packages/api/src/features/ssh-keys/model.ts`: the lookup the gateway uses.

## Gateway design

```
git client ──SSH:22──▶ edge TCP proxy ──▶ forge-sshd ──HTTPS──▶ Forge Smart HTTP
                       (Spectrum or        (container          (existing
                        Tunnel)             or VM)              /owner/repo.git/*)
```

`forge-sshd` is a small SSH server (for example Go `gliderlabs/ssh`, or
OpenSSH with `AuthorizedKeysCommand` and a `ForceCommand` shim). For each
connection it:

1. Accepts public-key authentication only, as user `git`. It asks Forge to
   resolve the offered key's fingerprint. OpenSSH verifies possession of the
   private key before the command runs.
2. Accepts exactly `git-upload-pack '<owner>/<repo>.git'` or
   `git-receive-pack '<owner>/<repo>.git'` (plus `git-lfs-authenticate`, which
   returns the existing LFS HTTP endpoint and a temporary token). It refuses
   shells, port forwarding, and agent forwarding.
3. Mints a short-lived repository credential for the resolved user, the same
   kind as `createTemporaryRepositoryCredential()` (30-minute, single
   repository, `repo:read`/`repo:write`). Forge's normal permission checks then
   apply unchanged.
4. Bridges the Git stateless-RPC streams onto Smart HTTP: send `info/refs`
   with `Git-Protocol: version=2` when the client asked for it, then
   `POST git-upload-pack` or `git-receive-pack`, copying pkt-lines in both
   directions. Protocol v2 makes this a clean request-per-command mapping.
   Upload-pack v0 needs the same `--stateless-rpc` framing that `git
   http-backend` uses.

Forge needs one internal endpoint for the gateway, which this change does not
add: `POST /api/internal/ssh/authorize`, with `{ fingerprint, repository,
service }`. It is authenticated by a gateway secret or a Cloudflare service
binding, and returns `{ username, token }` or 403. It combines
`findActiveUserBySshFingerprint`, the repository permission check, and
temporary-credential minting. That keeps all authorization in Forge; the
gateway holds no database credentials.

The host key must be stable and its fingerprints published in the docs so
clients can verify them on first connect, as GitHub publishes its own.

## Infrastructure the owner must choose

None of these resources exist yet. Each needs an owner decision and account
changes.

| Option | What it needs | Notes |
| --- | --- | --- |
| Cloudflare Spectrum (SSH app) on `ssh.forge.smol.ai:22` → origin running `forge-sshd` | Spectrum on the zone (SSH is supported on paid plans), an origin VM or container host with a public or tunnelled address | Keeps `git@forge.smol.ai`-style UX if a dedicated hostname is used; DDoS protection included |
| Cloudflare Tunnel (`cloudflared`) from the `forge-sshd` host + Spectrum or a public TCP route | A small always-on VM (e.g. 1 vCPU) | No inbound ports on the host |
| Port 22 directly on a VM (no Cloudflare in path) | DNS record for `ssh.forge.smol.ai` (grey-cloud) | Simplest; loses Cloudflare edge protection |

`forge-sshd` is stateless and does little CPU work. Git data streams through
it to Workers, so one small instance per region handles typical use. The
owner also needs to:

- create the gateway secret (`FORGE_SSH_GATEWAY_SECRET`) in the identity
  Worker and the gateway,
- generate and back up the SSH host key,
- add the SSH clone URL to the repository page only once the gateway is live.

## Why not tunnel SSH through WebSockets

A Worker could accept SSH tunnelled through a WebSocket (as
`cloudflared access ssh` does), but every client would need a helper in its
`ProxyCommand`. That fails the main goal: unmodified `git` with an SSH remote.
