ProofedMesh/docs/adr/0007-signing-service-dual-identity-check.md

ADR-0007: Signing-Service — zweistufige Identitätsprüfung (Pocket-ID JWKS + K8s TokenReview)

• Status: accepted
• Datum: 2026-10-25
• Entscheider: CTO
• Betroffene Dokumente: docs/architecture/v1.1.md §4.2 (DSSE), §9.1 (Workload-Identität), services/signing-service/internal/httpapi/sign.go, services/signing-service/internal/token/, services/signing-service/internal/registry/

Kontext und Problemstellung

ADR-0005 legt die POST /api/v1/sign/dsse-API fest; die dort gezeigte Authentisierung ("Pocket-ID-Access-Token, client_credentials") war aber die minimale Variante. Für den Produktionsbetrieb reicht sie nicht: ein geleaktes Pocket-ID-Client-Credential würde reichen, um aus einem beliebigen Pod (oder einer beliebigen Workstation) einen Transform- oder Approval-Signaturen zu erzeugen, die im Transparency-Log als "signiert von Agent X" landen.

Zwei Identitäten müssen am Punkt der Signatur gleichzeitig stimmen:

1. Wer ruft die API semantisch auf? — eine OIDC-Client-Identität, die wir dem Agenten/Service im Agent-Registry zugeordnet haben.
2. Welche Workload spricht wirklich mit uns? — eine Kubernetes-Pod-Identität (Namespace + ServiceAccount), die am TLS-/HTTP-Rand nicht gefälscht werden kann, ohne das K8s-API-Server oder den Node zu kompromittieren.

Wenn beide Identitäten unabhängig voneinander auf dieselbe Agent-Registry-Row zeigen, ist die Aussage "Agent agent-X signiert" substantiell schwerer zu fälschen als mit nur einer der beiden.

Entscheidungsoptionen

• Option A: Pocket-ID JWKS allein (ADR-0005-Minimum). Nur Authorization: Bearer <Pocket-ID-Access-Token> validieren, aus dem Token client_id/sub ziehen, Policy entscheidet. Workload-ID wird nicht geprüft.
• Option B: K8s TokenReview allein (projected ServiceAccount token). Nur X-Workload-Token: <projected-SA-token> gegen den Kube-API-Server (authentication.k8s.io/v1 TokenReview) prüfen, (ns, sa) → Agent-Registry-Lookup, Policy entscheidet. Pocket-ID wird nicht geprüft.
• Option C: Beide Identitäten prüfen und auf Konvergenz in der Agent-Registry bestehen. Beide Header verlangen, Pocket-ID-sub → Registry-Row A, (ns, sa) → Registry-Row B. Nur signieren, wenn A und B existieren und auf dieselbe Agent-Row zeigen; sonst Registry-Mismatch → 403.
• Option D: mTLS mit SPIFFE/SPIRE als zweite Identität. Statt K8s-TokenReview ein SPIFFE-Mesh einziehen, SVIDs als Client-Zert im HTTP-Request.

Entscheidung

Wir wählen Option C.

Konkret:

• Der Handler nimmt Authorization: Bearer <JWT> und X-Workload-Token: <projected-SA-token> entgegen.
• Pocket-ID-Validator (services/signing-service/internal/token/) prüft Signatur gegen {POCKET_ID_ISSUER}/.well-known/jwks.json, Audience, Expiry → sub = client_id.
• TokenReviewer (internal/token/k8s_tokenreview.go) ruft POST /apis/authentication.k8s.io/v1/tokenreviews am K8s-API-Server auf, prüft status.authenticated == true, status.user.username entspricht system:serviceaccount:<ns>:<sa> → liefert (Namespace, ServiceAccount) zurück.
• Registry.ByPocketID(sub) und Registry.ByK8sIdentity(ns, sa) schlagen die jeweils zugehörige Agent-Row nach. Beide Lookups müssen erfolgreich sein und dieselbe agent_id liefern.
• Die strukturierte Policy (internal/policy/policy.go#StructuredDecider) bekommt beide Lookups als Input.Registry.ByPocketID / Input.Registry.ByK8s plus KeyRef und entscheidet die Signatur-Erlaubnis.
• Beim Entwickeln/CI darf der K8s-Pfad abgeschaltet werden (TokenReviewer == nil); dann greift der Legacy-Decider mit nur Pocket-ID-Subject. Produktion fährt zwingend mit beiden: die Prüfung useStructuredPath() schaltet den Doppel-Check erst dann frei, wenn alle drei Komponenten (TokenReviewer, Registry, StructuredPolicy) verdrahtet sind — Prod-Deployments setzen sie, Dev nicht.

Fehlermodell:

• Pocket-ID JWT fehlt/ungültig/abgelaufen → 401 unauthorized.
• X-Workload-Token fehlt → 401 unauthorized ("missing X-Workload-Token header").
• TokenReview antwortet authenticated: false oder ErrWorkloadAuthFailed → 401 unauthorized.
• Registry-Mismatch (eine der beiden Lookups scheitert, oder beide liefern unterschiedliche agent_id): Policy deny mit Begründung registry_identity_mismatch → 403 signing_denied, error.message enthält die OPA-/Decider-Deny-Reason. Dieser Fehler ist audit-relevant und wird strukturiert geloggt.
• KeyRef existiert nicht → 400 unknown_key.

Begründung

• Zwei unabhängige Vertrauensanker. Pocket-ID lebt in einem anderen Deployment, mit anderen Schlüsseln (RSA/ECDSA JWKS). K8s TokenReview verifiziert gegen den API-Server-Signaturpfad. Ein Angreifer muss beide gleichzeitig kompromittieren, nicht nur einen.
• Container-interne Skripte können kein JWT fälschen. Projected ServiceAccount-Tokens haben kurze Lebenszeit und einen fixen audience: trust-api; sie werden vom Kubelet rotierend ausgestellt. Ein Pod kann nicht an einen fremden Namespace heranmanövrieren, ohne dass TokenReview das sofort bemerkt.
• Registry-Mismatch als expliziter Fehlerzustand. Das ist der Hauptgrund für die Doppelprüfung: wenn der Pocket-ID-Client zu Agent A gehört, der Pod aber unter einem SA läuft, der im Registry Agent B hinterlegt ist, lehnen wir ab. Verschleppte Leaks (ein gestohlenes Client-Secret in einem anderen Pod) scheitern an diesem Mismatch, nicht erst an einer Policy-Decke weiter oben.
• Kompatibel mit ADR-0005. Der API-Vertrag bleibt unverändert (POST /api/v1/sign/dsse); wir fügen genau einen zusätzlichen Header hinzu und präzisieren das Policy-Input.

Alternativen bewusst nicht gewählt

• Option A (nur Pocket-ID) reicht nur, solange wir dem Client-Secret komplett vertrauen. Für Prod zu wenig: ein geleaktes Secret ist nicht rotierbar schnell genug, um die Blast-Radius-Analyse zu bestehen.
• Option B (nur TokenReview) wäre für in-cluster Konsumenten attraktiv, verliert aber die Pocket-ID-Audit-Spur ("welcher OIDC-Client hat semantisch gehandelt"). Außerdem erschwert sie den Betrieb externer Konsumenten (admin-api aus einem Dev-Workspace), die keinen projected SA-Token haben.
• Option D (SPIFFE/SPIRE) ist semantisch ähnlich zu C, aber operativ teurer: zusätzliches Mesh, zusätzlicher Lifecycle, komplizierteres Dev-Setup. Wir behalten SPIFFE als Option für Phase 3+, falls Multi-Cluster-Signing anstehen sollte. Für den aktuellen Scope (ein Cluster, bekannte Namespaces) ist die TokenReview-Variante billiger und ausreichend.

Konsequenzen

Positive

• Zwei Identitäten → zwei getrennte Kompromittierungs-Pfade zum Signieren nötig.
• Konkreter, benannter Fehlermodus (registry_identity_mismatch) für Audits; keine stille Degradierung.
• Klarer Policy-Input: Input.Registry.ByPocketID / Input.Registry.ByK8s sind getrennte Felder, die OPA-Regeln können explizit auf "beide auf dieselbe agent_id" prüfen oder Agenten-spezifische Signaturerlaubnisse ableiten.
• Dev-Pfad bleibt leicht (-bearers=dev-token=agent-admin-api): der Doppel-Check wird nur eingeschaltet, wenn TokenReviewer + Registry + StructuredPolicy alle gesetzt sind.

Negative / Trade-offs

• Konsumenten (admin-api, approval-service, testagent-transform, dummy-sink) müssen den projected SA-Token aus /var/run/secrets/tokens/trust-api beschaffen und als X-Workload-Token-Header senden. Boilerplate liegt zentral in services/*/internal/auth/sa_token.go.
• Agent-Registry muss sowohl pocket_id_client als auch k8s_namespace/k8s_service_account pro Agent-Row vorhalten. Das Schema steht in Phase 2 noch nicht final (eigene Migration folgt), Phase 1 kommt mit einem statischen In-Memory-Resolver aus.
• Zusätzlicher Netz-Hop pro Signatur zum K8s-API-Server für den TokenReview. Latenz-Budget: ~5 ms, cacheable (Projected SA-Tokens rotieren langsam genug).

Folgearbeiten / Open Points

• Prod-Agent-Registry: PostgreSQL-Backend für registry.Resolver + Migration. Phase 2.
• Signing-Policy in OPA (policies/signing/*.rego): regelt agent_id → erlaubte key_refs → erlaubte predicateType-Namen. Phase 2.
• TokenReview-Caching (kurzes TTL, Hash(workloadToken) → k8sID), um bei Lastspitzen den API-Server-Hop zu entlasten. Nur bei tatsächlicher Last.
• OpenBao-Transit-Backend für Signer (ADR-0005) — bleibt orthogonal zu dieser ADR, aber lebt im selben Service.

Links

• services/signing-service/README.md — API, Dev-Pfad, Deployment
• services/signing-service/internal/httpapi/sign.go — Handler mit useStructuredPath()
• services/signing-service/internal/token/k8s_tokenreview.go — TokenReview-Client
• services/signing-service/internal/registry/ — Resolver-Interface
• services/testagent-transform/README.md — Beispiel-Konsument mit beiden Identitäten
• docs/architecture/v1.1.md §4.2, §9.1
• Kubernetes TokenReview API: https://kubernetes.io/docs/reference/access-authn-authz/authentication/#token-review-api
• ADR-0005 — API-Form, erweitert durch diese ADR