sshkeyvault/docs/PLAN.md

SSHKeyVault (sshkv) – Planung

Stand: 12.10.2026 · Status: freigegeben (12.10.2026)

---

1. Architektur

                 internes Netz / VPN
                        │ HTTPS (Reverse Proxy, z. B. Traefik/Caddy – nicht Teil von sshkv)
┌───────────────────────▼────────────────────────┐
│  sshkv-web  (Next.js 16, App Router, Node 24)   │
│  - UI (Server Components, Tailwind v4)          │
│  - OIDC authentik + Notfall-Admin      │
│  - Server Actions / Route Handlers              │
│  - schreibt Jobs in pg-boss, liest Ergebnisse   │
│  - KEINE SSH-Verbindungen, KEIN Master-Key*     │
└───────────────┬────────────────────────────────┘
                │ PostgreSQL 16 (Prisma + pg-boss-Schema)
┌───────────────▼────────────────────────────────┐
│  sshkv-worker  (gleiches Image, anderer Start)  │
│  - pg-boss-Consumer                             │
│  - Master-Key (Datei, read-only gemountet)      │
│  - ssh2: Verbindungen zu Hosts, strikt geprüft  │
│  - Schlüsselerzeugung, Ver-/Entschlüsselung     │
│  - Scheduler: Abgleich, Ablaufwarnungen         │
└───────────────┬────────────────────────────────┘
                │ SSH (nur Deployment-Key)
         ┌──────▼──────┐  ┌─────────────┐
         │ srv-pve01   │  │ srv-app01 … │
         └─────────────┘  └─────────────┘

* Ausnahme „Private Key anzeigen/exportieren“: Der Web-Prozess fordert die Entschlüsselung als Job an und reicht das Ergebnis genau einmal an den Browser durch (kein Caching, kein Logging). Alternative: Master-Key auch im Web-Container – bewusst nicht vorgesehen, damit eine Lücke im Webprozess allein nicht reicht, um alle Private Keys zu entschlüsseln.

Begründung Trennung Web/Worker: Lange SSH-Vorgänge laufen nie im Request; nur der Worker hält Master-Key und Deployment-Key. Der Web-Container hat keinen Netzwerkpfad zu den Hosts nötig (per Docker-Netz trennbar).

Bausteine

Bereich	Wahl	Bemerkung
Framework	Next.js 16 (App Router), TypeScript strict	output: "standalone" für schlankes Image
DB	PostgreSQL 17 + Prisma 7 (adapter-pg)	Migrationen versioniert im Repo
Jobs	pg-boss 10	kein Redis nötig; Cron-Schedules eingebaut
Auth	openid-client (OIDC, PKCE) + jose (Sitzungs-Cookie); Notfall-Admin mit argon2id + TOTP	kein Auth.js: v5 ist dauerhaft Beta (wie in Laufzettel/ProxLedger)
SSH	ssh2	hostVerifier gegen gespeicherten Host-Key
Schlüssel	Node crypto (ed25519, RSA-4096) + eigener OpenSSH-Serializer	kein ssh-keygen mit Temp-Dateien; Tests prüfen Kompatibilität gegen ssh-keygen -y
Krypto at rest	AES-256-GCM (Node crypto), Envelope Encryption	keine nativen Zusatz-Abhängigkeiten
UI	Tailwind v4 mit Design-Tokens als CSS-Variablen, @fontsource	keine externen CDNs
Validierung	zod	an allen Server-Grenzen
Tests	Vitest (Unit), Testcontainers + Debian-sshd-Image (Integration), Playwright (E2E + Screenshots)
Betrieb	Docker Compose: sshkv-web, sshkv-worker, sshkv-db	.env.example mit Präfix SSHKV_

Remote-Operationen

Alle Änderungen auf Hosts laufen über ein kleines POSIX-sh-Skript, das per exec mit Inhalt über stdin gestartet wird (keine Dateien auf dem sshkv-Server, keine Abhängigkeit von SFTP-Rechten):

1. Ziel-Benutzer prüfen (getent passwd), Home ermitteln, AuthorizedKeysFile per sshd -T auslesen (abweichende Pfade werden erkannt).
2. Dateioperationen in fremden Home-Verzeichnissen als Zielbenutzer (runuser -u <user> --), damit Symlink-Tricks im Home eines Benutzers keine Root-Schreibrechte erlangen.
3. Backup authorized_keys.sshkv.bak.<YYYYMMDD-HHMMSS> (Aufbewahrung: letzte N, konfigurierbar).
4. Schreiben in …/.sshkv.tmp.<rand> + chmod 0600 + mv (atomar), ~/.ssh 0700.
5. Rückgabe von Vorher-Hash und Nachher-Inhalt → Audit-Diff.
6. Optimistische Sperre: Der Dry-Run merkt sich den SHA-256 der Datei; hat sich die Datei bis zur Ausführung geändert, bricht der Job ab und fordert einen neuen Dry-Run.

Private Keys werden ausschließlich über stdin derselben SSH-Verbindung übertragen.

authorized_keys – verwalteter Block

# BEGIN SSHKV MANAGED – nicht manuell bearbeiten
restrict,from="10.0.0.12" ssh-ed25519 AAAA… sshkv:k_8f3a backup-srv-backup01
# END SSHKV MANAGED

• Parser (reine Funktion, umfangreich getestet): Optionen mit Anführungszeichen/Escapes/Kommas, Kommentare, Leerzeilen, CRLF, BOM, doppelte Keys, cert-authority, unbekannte Schlüsseltypen, kaputte Zeilen, fehlendes END-Marker, mehrere Blöcke.
• Merge: Alles außerhalb des Blocks bleibt bytegenau erhalten (inkl. Zeilenenden). Innerhalb wird der Block deterministisch aus dem Soll-Zustand neu erzeugt.
• Erkennung eines verwalteten Keys über Fingerprint (nicht über Kommentar); Kommentar sshkv:<id> <name> dient nur der Lesbarkeit.
• Duplikat außerhalb des Blocks → Hinweis im Dry-Run, keine automatische Löschung.
• Aussperrschutz: Der Deployment-Key ist in jedem root- bzw. Dienstbenutzer-Block unabänderlich enthalten; Aktionen, die ihn entfernen würden, werden serverseitig verweigert.

---

2. Datenmodell (Prisma, verkürzt)

Umgesetzt mit deutschen Bezeichnern (Konvention, siehe CLAUDE.md); die Zuordnung steht dort. Die Skizze unten zeigt die Struktur.

enum Role            { ADMIN OPERATOR READER }
enum KeyType         { ED25519 RSA4096 }
enum KeyCategory     { PERSON SERVICE DEPLOYMENT }
enum KeyStatus       { ACTIVE ROTATING REVOKED EXPIRED }
enum HostKeyStatus   { PENDING TRUSTED CHANGED REJECTED }
enum UsageState      { PLANNED DEPLOYED DRIFT REMOVING REMOVED FAILED }

model User {                       // Anmeldekonten der Oberfläche
  id String @id @default(cuid())
  oidcSub String? @unique
  email String? @unique
  name String
  role Role
  isBreakGlass Boolean @default(false)   // lokaler Notfall-Admin
  passwordHash String?                    // nur Notfall-Admin (argon2id)
  totpSecretEnc Bytes?                    // nur Notfall-Admin, verschlüsselt
  lastLoginAt DateTime?
  person Person?
}

model Person {                     // Menschen, denen Personen-Keys gehören
  id String @id @default(cuid())
  name String
  email String?
  organisation String?             // z. B. Dienstleister
  userId String? @unique           // Verknüpfung für Self-Service
  keys SshKey[]
}

model Customer { id String @id @default(cuid()); name String @unique; hosts Host[] }

model Host {
  id String @id @default(cuid())
  name String @unique              // srv-pve01
  address String                   // Hostname/IP
  port Int @default(22)
  description String?
  tags String[]
  customerId String?
  connectUser String @default("root")      // siehe offene Frage 1
  deploymentKeyId String?                  // null = Instanz-Default
  bootstrapState String                    // NEW | BOOTSTRAPPED
  reachable Boolean?
  lastCheckAt DateTime?
  lastSyncAt DateTime?
  driftState String?                       // IN_SYNC | DRIFT | UNKNOWN
  sshdFacts Json?                          // PermitRootLogin, PasswordAuthentication, AuthorizedKeysFile
  groups HostGroupMember[]
  hostKeys HostKey[]
}

model HostGroup {
  id String @id @default(cuid())
  name String @unique
  description String?
  deploymentKeyId String?          // optional Deployment-Key je Gruppe (später)
  members HostGroupMember[]
}
model HostGroupMember { hostId String; groupId String; @@id([hostId, groupId]) }

model HostKey {                    // TOFU
  id String @id @default(cuid())
  hostId String
  algorithm String                 // ssh-ed25519, ecdsa-…, rsa-sha2-512
  publicKey String
  fingerprint String               // SHA256:…
  status HostKeyStatus
  firstSeenAt DateTime
  confirmedById String?
  confirmedAt DateTime?
}

model SshKey {
  id String @id @default(cuid())
  name String                      // Zweck, z. B. „Backup srv-backup01 → srv-pve01“
  slug String @unique              // für Dateinamen: backup-srv-backup01-srv-pve01
  type KeyType
  category KeyCategory
  status KeyStatus
  publicKey String                 // OpenSSH-Zeile ohne Optionen
  fingerprint String @unique       // SHA256
  comment String                   // Default: sshkv:<slug>
  hasPrivateKey Boolean
  privateKeyEnc Bytes?             // Envelope-Ciphertext, nie in Listen-Queries selektiert
  dekEnc Bytes?                    // verschlüsselter Data-Key
  masterKeyVersion Int?
  passphraseProtected Boolean @default(false)
  personId String?
  templateId String?
  tags String[]
  expiresAt DateTime?
  createdAt DateTime @default(now())
  lastUsedAt DateTime?             // aus Verbindungstests/Abgleich
  rotatedFromId String?            // Rotationskette
  publicUsages PublicKeyUsage[]
  privateUsages PrivateKeyUsage[]
}

model PublicKeyUsage {             // Soll: Public Key in authorized_keys
  id String @id @default(cuid())
  keyId String
  hostId String?                   // genau eins von hostId / groupId
  groupId String?
  targetUser String                // root, deploy …
  options String?                  // restrict,from="…",command="…"
  state UsageState
  lastAppliedAt DateTime?
}

model PrivateKeyUsage {            // Soll: Private-Key-Datei auf Host
  id String @id @default(cuid())
  keyId String
  hostId String
  targetUser String
  path String                      // ~/.ssh/id_ed25519_<slug>
  sshConfigBlock Json?             // { alias, hostName, user, port, identitiesOnly }
  knownHostsFor String[]           // Host-IDs, deren Host-Key in known_hosts gepflegt wird
  state UsageState
  onRevoke String @default("DELETE") // DELETE | RENAME
  lastAppliedAt DateTime?
}

model ManagedAccount {             // vom sshkv angelegte Benutzer (deploy) und sudoers-Dateien
  id String @id @default(cuid())
  hostId String
  username String
  createdBySshkv Boolean
  sudoersFile String?              // /etc/sudoers.d/sshkv-deploy
  sudoersContent String?
}

model Template {                   // „Deployment-Zugang“, „Backup-Zugang“, …
  id String @id @default(cuid())
  name String @unique
  builtin Boolean @default(false)
  keyType KeyType
  category KeyCategory
  defaultTtlDays Int?
  targetUser String
  createTargetUser Boolean
  sudoMode String?                 // NONE | COMMANDS | FULL
  sudoCommands String[]
  authorizedKeysOptions String?    // mit Platzhaltern, z. B. from="{{sourceHostIp}}"
  sshConfigAlias String?           // z. B. deploy-{{targetHost}}
}

model Observation {                // Ist-Zustand aus dem letzten Abgleich
  id String @id @default(cuid())
  hostId String
  targetUser String
  file String
  sha256 String
  entries Json                     // geparste Zeilen inkl. inBlock/fingerprint/options
  observedAt DateTime
}

model DriftFinding {
  id String @id @default(cuid())
  hostId String
  targetUser String
  kind String                      // UNKNOWN_KEY | MISSING_KEY | EXTRA_IN_BLOCK | FILE_CHANGED | PERMS | HOSTKEY_CHANGED
  fingerprint String?
  detail Json
  openedAt DateTime
  resolvedAt DateTime?
}

model Operation {                  // fachliche Klammer um pg-boss-Jobs (für UI-Status)
  id String @id @default(cuid())
  kind String                      // DRY_RUN | APPLY | BOOTSTRAP | SYNC | TEST | ROTATE | REVOKE …
  status String                    // QUEUED | RUNNING | AWAITING_CONFIRM | DONE | FAILED
  requestedById String
  plan Json?                       // Dry-Run-Ergebnis inkl. Datei-Hashes
  result Json?
  createdAt DateTime @default(now())
  finishedAt DateTime?
}

model AuditEvent {                 // append-only (DB-Trigger verbietet UPDATE/DELETE)
  id BigInt @id @default(autoincrement())
  at DateTime @default(now())
  actorId String?                  // null = System/Scheduler
  actorName String
  action String                    // key.create, key.private.view, usage.apply, host.hostkey.confirm …
  hostName String?
  targetUser String?
  fingerprint String?
  diff String?                     // Vorher/Nachher (nur Public-Daten)
  result String                    // SUCCESS | FAILURE | DENIED
  detail Json?
  prevHash String                  // Hash-Kette → Manipulation erkennbar
  hash String
}

model Setting { key String @id; value Json }

Hinweise:

• privateKeyEnc/dekEnc liegen technisch in SshKey, werden aber nur über ein einziges Modul (lib/secrets) im Worker gelesen; Prisma-Queries nutzen sonst feste select-Listen ohne diese Felder (per Lint-Regel/Test abgesichert).
• Der Deployment-Key ist ein SshKey mit category = DEPLOYMENT.

---

3. Sicherheitskonzept (Kurzfassung, Langfassung in docs/security.md)

• Envelope Encryption: pro Private Key ein zufälliger 256-bit-DEK, Key mit AES-256-GCM verschlüsselt (AAD = Key-ID + Fingerprint), DEK mit Master-Key (AES-256-GCM) verschlüsselt. Master-Key: 32 Byte aus Datei SSHKV_MASTER_KEY_FILE (Docker Secret), nur im Worker. masterKeyVersion erlaubt Master-Key-Rotation (CLI-Kommando sshkv rewrap).
• Re-Auth für kritische Aktionen: OIDC mit prompt=login + max_age=0, Prüfung von auth_time (≤ 5 min); Notfall-Admin: Passwort + TOTP erneut.
• Web: Sitzungs-Cookie (jose, HS256) (httpOnly, Secure, SameSite=Lax), CSRF: Server Actions (Origin-Prüfung) + Token für Route Handler, Rate-Limit (Postgres-basiert) auf Login/Re-Auth/kritische Aktionen, CSP mit Nonce, HSTS, X-Frame-Options: DENY, Referrer-Policy: no-referrer.
• Logging: strukturierter Logger mit Redaction (privateKey, password, passphrase, -----BEGIN); Test, der bewusst einen Key durch Fehlerpfade schickt und Logs prüft.
• Bootstrap-Passwort: nur im Arbeitsspeicher des Workers für genau einen Job, nie in DB/Job-Payload im Klartext → wird vom Web-Prozess mit einem kurzlebigen Job-Schlüssel verschlüsselt, Job-Datensatz wird nach Abschluss gelöscht.
• Bedrohungsanalyse (Doku): Kompromittierung sshkv = root auf allen Hosts. Gegenmaßnahmen: nur intern/VPN, Worker ohne eingehende Ports, Master-Key getrennt, Audit mit Hash-Kette + Syslog-Export, Notfallplan „Deployment-Key auf allen Hosts tauschen“ (Rotation des Deployment-Keys als eigener Ablauf), optional from="<sshkv-IP>" am Deployment-Key.
• Backup: pg_dump + Master-Key getrennt sichern; Doku mit Restore-Test.

---

4. Rollen & Rechte

Aktion	Admin	Operator	Leser
Ansehen (Hosts, Keys, Matrix, Audit)	✓	✓	✓
Hosts anlegen/bootstrappen, Host-Key bestätigen	✓	✓	–
Public Key zuweisen/ausrollen/entfernen	✓	✓	–
Schlüssel erzeugen/importieren	✓	✓	–
Private Key ausrollen	✓	–	–
Private Key anzeigen/exportieren (Re-Auth)	✓	–	–
Deployment-Key ändern/rotieren (Re-Auth)	✓	–	–
Massenwiderruf (Re-Auth)	✓	–	–
Benutzer anlegen + sudoers (Re-Auth)	✓	–	–
Einstellungen, Vorlagen	✓	–	–
Eigene Public Keys hinterlegen (Self-Service)	✓	✓	✓

Rollenzuordnung über authentik-Gruppen: sshkv-admins, sshkv-operators, sshkv-readers (Namen konfigurierbar per SSHKV_OIDC_GROUP_*).

---

5. Phasenplan

Versionierung: 0.N.0 am Ende jeder Phase, 1.0.0 nach Phase 5 + Abnahme.

Phase 0 – Planung (jetzt)

Plan, Freigabe, Repo + Gitea-Issues.

Phase 1 – Grundgerüst → v0.1.0

• Repo, Next.js, Prisma-Schema, Docker Compose (web/worker/db), .env.example, CI-Basis (Lint, Typecheck, Tests).
• Design-System: Tokens, Schriften, Logo-Dateien + Favicon/PWA-Icons, Layout mit Seitenleiste.
• Auth: OIDC authentik, Notfall-Admin (argon2id + TOTP), Rollen, Re-Auth-Mechanik.
• Audit-Grundlage (append-only, Hash-Kette).
• Master-Key-Handling + lib/secrets.
• Deployment-Key erzeugen.
• Hosts/Hostgruppen CRUD, TOFU-Host-Key-Verifizierung, Erreichbarkeitsprüfung.
• Bootstrap: Einmal-Passwort-Login oder Copy-Paste-Befehl; sshd-Check (PermitRootLogin, PasswordAuthentication).
• Test-SSH-Container (Debian 12/13) für Integrationstests.

Phase 2 – Schlüssel & Public-Key-Ausrollen → v0.2.0

• Erzeugen (ed25519, rsa-4096, optional Passphrase), Import (Public/Paar), Export.
• Personen, Kategorien, Tags, Ablaufdatum.
• Private Key anzeigen/Download mit Re-Auth + Audit.
• authorized_keys-Parser/Merger (Unit-Tests mit allen Randfällen).
• Zuweisungen (Host/Gruppe × Benutzer, Optionen), Dry-Run-Diff, Backup, atomares Schreiben, Aussperrschutz.

Phase 3 – Private-Key-Ausrollen & Host-zu-Host → v0.3.0

• Private Key auf Host A, ~/.ssh/config-Block (verwaltet, eigener Marker), known_hosts-Pflege.
• Benutzer anlegen + sudoers (Vorschau, visudo -c).
• Vorlagen (eingebaut „Deployment-Zugang“, „Backup-Zugang“, „Admin-Zugang Person“; eigene in Einstellungen).
• Host-zu-Host-Assistent inkl. Verbindungstest A → B.
• Option „Private Key nach Ausrollen löschen“.

Phase 4 – Abgleich, Import, Rotation, Widerruf → v0.4.0

• Periodischer + manueller Abgleich, Drift-Befunde, Host-Status.
• Import bestehender authorized_keys (Zuordnung zu Person/Zweck).
• Geführte Rotation, Ein-Klick-Widerruf (inkl. Benutzer/sudoers entfernen), Massenwiderruf.
• Zuweisungsmatrix.

Phase 5 – Dashboard & Feinschliff → v0.5.0 / v1.0.0

• Übersicht laut Design, Audit-Ansicht + CSV-Export, Syslog-Weiterleitung.
• Benachrichtigungen (SMTP M365 / Webhook) bei Drift und Ablauf.
• Anleitung mit Screenshots (Installation, Bootstrap, Kern-Anwendungsfall), Bedrohungsanalyse, Backup-Konzept.

Später (eigene Phasen)

• Heller Modus, SSH-CA (Zertifikate), Deployment-Key je Hostgruppe (Datenmodell ist vorbereitet).

---

6. Arbeitsweise

• Gitea: pro Phase ein Milestone, Issues je Arbeitspaket, Commits referenzieren Issues (refs #12), Conventional Commits.
• devlog.md (Datum, Dauer, Tätigkeit), CHANGELOG.md (Keep a Changelog), SemVer-Tags.
• Sub-Agenten parallel für Tests, Doku, UI-Komponenten.
• Nach jeder Phase Screenshots (Playwright) und kurzer Bericht, Freigabe der nächsten Phase.

---

7. Entscheidungen aus der Freigabe (12.10.2026)

1. Anmeldung auf den Hosts nur per Schlüssel. Standard: Dienstbenutzer sshkv mit /etc/sudoers.d/sshkv (NOPASSWD); root direkt ist pro Host wählbar.
2. Gitea-Zugang folgt; bis dahin liegen die Issues als Dateien in docs/issues/ (#030).
3. Private Keys ausrollen: nur Admin.
4. Self-Service: Jeder angemeldete Benutzer darf eigene Public Keys hinterlegen; wirksam erst nach Zuweisung durch Operator/Admin.
5. Notfall-Admin: Passwort + verpflichtendes TOTP.
6. Passphrasen werden nie gespeichert; beim Ausrollen eines passphrasengeschützten Keys erscheint eine Warnung.
7. authentik vorerst über einen Mock-OIDC-Anbieter; echte Anbindung später.