dotfiles/agents/README.md

# Design: SSH-Key- und Git-Signing-Architektur (Arbeitsrechner mwiegand)

Stand 2026-08-04 — umgesetzt und verifiziert. Beschreibt das *Warum* hinter
dem Code in diesem Verzeichnis (`agent-env.zsh`, `ensure-machine-agent`,
`.env.agents`) plus `~/.ssh/config` und `~/.gitconfig`.

Umsetzungsstand, Historie und die offenen Schritte auf ISAC-Seite stehen im
ai-Repo: `tasks/2026-07-31-agent-key-isolation/HANDOFF.md`, Vorarbeit in
`tasks/2026-06-13-isac-infra-agent-isolation/`.

## Problem

Auf dem Rechner laufen zwei Arten von Akteuren mit unterschiedlichem
Vertrauensniveau:

- **Ich** (interaktive Shell) — brauche den persönlichen SSH-Key, der über
  LDAP auch auf **Kundensystemen** autorisiert ist.
- **Agents** (Claude/OpenCode via `agent-env`) — sollen interne Systeme
  erreichen, aber **strukturell nicht unbemerkt** an den kundenfähigen Key
  kommen.

Vor dem Umbau war die Trennung rein konventioniert: der private Haupt-Key lag
unverschlüsselt als `~/.ssh/id_mwiegand` auf der Platte (für jede Agent-Session
lesbar), der 1Password-SSH-Agent bot alle Keys jedem Prozess an, und ein
Login-Script lud den Haupt-Key zusätzlich in den Apple-Agent. Git-Signing hing
am Datei-Key.

Dazu die Komfort-Anforderung: **Signieren darf im Alltag nicht nerven** —
keine Fingerabdruck-Freigabe pro Commit.

## Anforderungen

1. Agents verwenden einen eigenen SSH-Key (nur interne Systeme); der
   kundenfähige Haupt-Key ist für sie nicht still nutzbar.
2. Jede Nutzung des Haupt-Keys erzeugt eine sichtbare, bewusste Freigabe
   (Fingerabdruck) — der Prompt ist die Schranke.
3. Kein privater Schlüssel liegt als Datei auf der Platte.
4. Git-Commits sind signiert, prompt-frei — Herkunft „diese Maschine" ist
   nachweisbar (Mensch/Agent unterscheiden die Commit-Trailer).
5. Kein Autoload beim Login (explizite Entscheidung): was in einem Agent
   liegt, wurde bewusst dorthin gelegt.

## Architektur: drei Schlüssel, drei Wege

| Schlüssel (1Password-Item, Vault Employee) | Fingerprint | Lebt in | Zweck | Prompt-Verhalten |
|---|---|---|---|---|
| **SSH Key mwiegand** (Haupt-Key) | `SHA256:lIx1Na…` | nur 1Password | SSH überall, inkl. Kundensysteme | 1Password-Freigabe pro Key und Terminal-Session — bewusst spürbar |
| **SSH isac agent** (Agent-Key) | `SHA256:77FiJM…` | geteilter Maschinen-ssh-agent `~/.ssh/isac-agent.sock` | SSH auf interne Systeme (User `mwiegand-agent`) | einmal `op read` pro Boot, danach still |
| **SSH Signing Key mwiegand** (Signing-Key) | `SHA256:SvHSJQ…` | geteilter Maschinen-ssh-agent `~/.ssh/isac-agent.sock` | Git-Signing **aller** Commits der Maschine — meine und Agent-Commits | einmal `ensure-machine-agent` pro Boot (passiert automatisch mit der ersten Agent-Session), danach still |

Die Auswahl des Schlüssels erfolgt **über den Agent-Socket**, nicht über
Key-Dateien:

- `~/.ssh/config` `Host *` → `IdentityAgent ~/.1password/agent.sock`
  (Haupt-Key, promptet pro Nutzung).
- `Match exec USE_AGENT_SSH_USER=1` → `User mwiegand-agent` +
  `IdentityAgent ~/.ssh/isac-agent.sock` (Ein-Key-Agent; steht vor `Host *`,
  nach den ckn-Host-Blöcken).
- Git-Signing läuft über `SSH_AUTH_SOCK`, der überall (interaktive Shell via
  `agent-env.zsh`, Agent-Sessions zusätzlich via `.env.agents`) auf den
  Maschinen-Agent zeigt — signiert wird immer mit dem Signing-Key. Fürs
  interaktive SSH ist `SSH_AUTH_SOCK` irrelevant, weil die `ssh_config`
  `IdentityAgent` explizit setzt.

Der Sicherheitskern: **die Prompt-Semantik bleibt sauber.** Ein
1Password-Prompt bedeutet immer „jemand will den kundenfähigen Key" — er
kommt selten und ist ernst zu nehmen. Signing und Agent-SSH erzeugen nie
Prompts, also gibt es keine Gewöhnung an reflexhaftes Bestätigen.

## Komponenten

Alles Agent-bezogene liegt versioniert in diesem Verzeichnis; `~/.zshrc` und
`~/.local/bin` enthalten nur noch Verweise darauf.

| Datei | Rolle |
|---|---|
| `agents/agent-env.zsh` (gesourced von `dotfiles/.zshrc`) | exportiert `SSH_AUTH_SOCK` fest auf `~/.ssh/isac-agent.sock`; `agent-env()` ruft `ensure-machine-agent` und dann `op run --env-file ~/.env.agents` |
| `agents/ensure-machine-agent` (Symlink in `~/.local/bin/`) | idempotent: startet den Maschinen-Agent bei Bedarf und stellt **beide** Keys sicher (Signing + Agent). Wird von `agent-env` gerufen; manuell nur nötig, wenn man nach einem Reboot committen will, bevor die erste Agent-Session lief |
| `agents/.env.agents` (Symlink `~/.env.agents`) | rein deklarativ — `op run` parst die Datei nur, führt keinen Code aus: `USE_AGENT_SSH_USER=1`, `SSH_AUTH_SOCK` (Robustheit: Konsumenten ohne `agent-env` finden den richtigen Socket), `BW_SSH_ARGS`, `GIT_CONFIG_*` → `user.signingkey` = Signing-Pubkey (Env schlägt alle git-Configs, auch lokale), Secret-Referenzen |
| `~/.ssh/config` | Socket-Routing s. o.; keine `IdentityFile`-Einträge für persönliche Keys |
| `~/.gitconfig` | `gpg.format=ssh`, `commit.gpgsign=true`, `user.signingkey` = Signing-Pubkey-String (kein Pfad), `gpg.ssh.allowedSignersFile` |
| `~/.ssh/allowed_signers` | beide Pubkeys (Signing + Agent) für lokale Verifikation (`git log --format=%G?`) |

Gelöscht: `~/.ssh/id_mwiegand` (unverschlüsselter Datei-Key),
`add-ssh-key-to-agent` (Login-Autoload des Haupt-Keys), lokale
`user.signingkey`-Overrides in 8 Repos.

## Entscheidungen und verworfene Alternativen

**Signing-Key als eigener Schlüssel statt Haupt-Key.** Die Prompt-Frequenz
hängt nicht am Schlüssel, sondern am Mechanismus — aber ein gemeinsamer
Schlüssel hätte Haupt-Key-Prompts beim Committen alltäglich gemacht und die
Schranke durch Gewöhnung entwertet. Außerdem: Forges kennen den Signing-Key
nur als Signaturschlüssel; ein Leak ist kein Systemzugriff.

**Ein gemeinsamer Signing-Key für Mensch und Agents** (statt Agent-Commits
mit dem Agent-SSH-Key zu signieren, wie zuerst gebaut). Die Key-Trennung
hätte nur *ehrliche* Agent-Commits von meinen unterschieden: die
Agent-Sockets sind für jeden lokalen Prozess erreichbar, ein böswilliger
Agent könnte ohnehin als ich signieren. Für ehrliche Commits leistet der
`Co-Authored-By`-Trailer die Unterscheidung. Die Signatur bedeutet ehrlich
„kam von meiner Maschine"; dafür halbiert sich die Forge-Pflege (ein Key
registrieren/verifizieren statt zwei) und der Boot-Load läuft automatisch
über die erste Agent-Session mit. Ältere Commits (2026-08-04) sind noch mit
dem Agent-Key signiert — er bleibt dafür in `allowed_signers`.

**`op-ssh-sign` erwogen und verworfen.** Zuerst umgesetzt (Key verlässt
1Password nie), dann zurückgebaut: die 1Password-Autorisierung gilt global
pro App(+Terminal-Session) für *alle* Keys. Das Signing-Nerv-Problem hätte
sich nur durch Lockern des Modells lösen lassen — was die Haupt-Key-Schranke
mitgelockert hätte. Der Agent-Weg entkoppelt beides: Signing prompt-frei,
1Password-Modell bleibt streng. (Zwischenschritt Apple-Agent als
Signing-Halter wurde durch den Maschinen-Agent ersetzt — ein Agent weniger.)

**macOS-Keychain als Signer verworfen.** Die Keychain speichert Bytes, kann
aber keine SSH-Signaturen erzeugen (`security` bietet nur `cms`). Jeder
Keychain-Weg endet in einer Klartext-Tempdatei pro Commit — schlechter als
jeder Agent. (`ssh-add --apple-use-keychain` speichert nur Passphrasen und
setzt eine Key-Datei voraus.)

**Kein Login-Autoload.** Bewusste Entscheidung: Keys werden nicht beim Login
geladen, sondern lazy — mit der ersten Agent-Session (automatisch) bzw. per
`ensure-machine-agent` von Hand. Symptom eines fehlenden Loads ist ein
Commit-Fehler `Couldn't find key in agent?` — eindeutig und folgenlos.

**Geteilter Agent statt Agent pro Session.** Ein fester Socket
(`~/.ssh/isac-agent.sock`) statt mktemp pro Session: ein `op read` pro Key
und Boot statt pro Session, kein Cleanup verwaister Agents, und der
Match-Block kann auf einen stabilen Pfad zeigen (wirkt auch für Subprozesse
mit bereinigtem Env). Beide Bewohner (Agent-Key, Signing-Key) sind per
Definition die Schlüssel, die Agents zugänglich sein dürfen — Langlebigkeit
weicht nichts auf.

**`SSH_AUTH_SOCK` zusätzlich fest in `.env.agents`.** Lektion aus dem Umbau:
eine Shell mit veralteter `agent-env`-Funktion lud die neue `.env.agents`
(Signing-Config auf Agent-Key), zeigte aber noch auf den leeren Apple-Agent →
`Couldn't find key in agent?`. Signing-Config und Socket dürfen nicht
auseinanderfallen; beide stehen jetzt in derselben Datei.

## Grenzen (bewusst offen)

Die Architektur ist eine **Zustimmungs- und Erkennungsschranke, keine
technische Unerreichbarkeit**:

- Der 1Password-Socket bleibt für Agent-Prozesse erreichbar
  (`allowAllUnixSockets: true` in der Claude-Sandbox-Config; 1Password kann
  Keys nicht pro Client filtern). Ein Agent, der den Haupt-Key anfordert,
  löst aber einen sichtbaren Prompt aus, den ich ablehnen kann.
- **`op`-CLI-Pfad** (empirisch geprüft 2026-08-04): ein Agent kann `op read`
  auf beliebige Items *versuchen* — u. a. den Haupt-Key — aber nicht
  unbemerkt. Vier Versuche aus einer Agent-Session ergaben vier
  1Password-Dialoge; die Freigabe für das `op run` beim `agent-env`-Start
  deckt nachgelagerte `op`-Aufrufe **nicht** mit ab (ob eine *bestätigte*
  Freigabe danach ein 10-Minuten-Fenster öffnet, ist unverifiziert — der
  Dialog behauptet das, gemessen wurde es nicht).
  Die verbleibende Schwäche ist die **Blindheit des Dialogs**: er sagt „full
  access to your account", nennt aber nicht das angefragte Item. Beim
  Bestätigen ist nicht unterscheidbar, ob ein Agent ein harmloses
  API-Passwort oder den kundenfähigen SSH-Key liest. Das ist systematisch,
  nicht nur eine Eigenschaft offener Abfragen: auch `op read` mit einer
  punktgenauen `op://Employee/<item>/<feld>`-Referenz zeigt denselben
  Dialog (geprüft 2026-08-04) — 1Password autorisiert das Werkzeug, nie den
  Zugriff, selbst wenn dieser vollständig spezifiziert ist. Gerade die
  Secrets in `.env.agents` sind ausschließlich solche Referenzen — und weil legitime
  Agent-Starts denselben Dialog erzeugen, trainiert der Alltag reflexhaftes
  Bestätigen. Genau das macht der gescopte Service-Account (Schritt 1)
  überflüssig: was nicht anfragbar ist, muss nicht beurteilt werden.
- Vollständige Schließung = HANDOFF-Schritte 1/3: gescopter Service-Account
  mit eigenem Vault für den Agent-Key, Socket-Sperre in der Sandbox,
  Seatbelt-Variante für unsandboxte Kommandos.

## Betrieb

- **Nach Reboot:** die erste `agent-env`-Session lädt beide Keys automatisch;
  nur wer vorher committen will, ruft einmal `ensure-machine-agent` (Symptom
  sonst: `Couldn't find key in agent?`).
- **Verifikation:** `git log --format='%h %G? %GK'` — `G` + `SvHSJQ…` für
  alle Maschinen-Commits (Commits vom 2026-08-04 noch mit `77FiJM…`).
  `ssh-add -l` in einer Agent-Session zeigt genau die zwei Maschinen-Keys.
- **Forges:** der Signing-Pubkey muss bei Bitbucket DC/Forgejo als *Signing*
  Key registriert sein; bei Forgejo zusätzlich ownership-verifiziert
  (Challenge signieren, nur via Web-UI), sonst „unverified" (offen).
- **Rotation:** neuer Key = neues 1Password-Item + Pubkey in
  `~/.gitconfig`/`allowed_signers`/`.env.agents` bzw. ISAC
  (`admin_agent_users`) nachziehen; es gibt keine Key-Dateien zu tauschen.