Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/VEXT-1.md
T

475 lines
42 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# VEXT-1 · KWP-API-Zugang nutzen + Recut-Detailplanung gegen API-Doku
| | |
|---|---|
| **Typ** | Setup (Externals — `typ:external`) |
| **Owner** | Raffael |
| **Phase** | Phase 32 (v2-P5) — KWP-Integration (Vorlauf) |
| **Cycle/Fenster** | v2-W2 — KWP/Portal/Mobile-Start · fällig 2026-07-20 |
| **Status** | Done · Demand-Refresh-Dauerbetrieb auf Staging verifiziert · **4/4 DoD = 100 % done** |
> 🔴 **Regression 2026-07-23:** Der Dauer-Proof vom 22.07. bleibt als historischer Nachweis gültig, reicht
> aber nicht mehr für einen aktuellen Haltbarkeits-Claim. Nach 20 weiteren erfolgreichen automatischen
> Rotationen akzeptierte der Token-Endpunkt um **21:08:10 CEST** noch eine HTTP-2xx-JSON-Antwort, die
> anschließend an einem der zusammengefassten semantischen Refresh-Checks scheiterte. Die Connection wurde
> fail-closed auf `broken` gesetzt und benötigt nach dem Fix einen normalen OAuth-Reconnect. Die vorhandene
> Diagnose unterschied fehlenden Access-/Refresh-Token, nicht rotierenden Refresh-Token, Scope-Echo und
> Ablaufzeit nicht. Zusätzlich verlangte der automatische Refresh fälschlich exakt `expires_in=300`, obwohl
> der Erst-Login bereits jede positive Laufzeit bis maximal 300 Sekunden akzeptiert und OAuth `expires_in`
> als tatsächliche Laufzeit definiert. Der Fix vereinheitlicht diesen Vertrag, protokolliert ausschließlich
> feste redigierte Diagnosecodes und behält den sicheren Nicht-Replay bei möglicherweise verbrauchtem
> Einmal-Refresh-Token bei. Bis Deploy, Reconnect und erneutem Langzeit-Proof gilt:
> **VEXT-1: 3/4 DoD = 75 % done · 1 Punkt offen · 1 selbst machbar.**
> 🟢 **Regression geschlossen 2026-08-01:** Der Demand-Refresh-Fix aus PR `#312` lief nach einem
> normalen OAuth-Reconnect zwei Stunden stabil auf Staging. **20/20** Einmal-Refresh-Token-Rotationen aus
> Web-, Import- und Health-Pfaden gelangen; acht Health-Sweeps meldeten `checked=1`, `unhealthy=0`. Es gab
> keinen Provider-, Persistenz- oder Claim-Fehler und keine erneute Reconnect-Aufforderung.
> **VEXT-1: 4/4 DoD = 100 % done · 0 Punkte offen · Done.**
> 🟢 **Superseding Scope-Entscheidung 2026-07-22:** VEXT-1 ist für den initialen aktuellen
> **read-only** KWP-Vertrag vollständig abgeschlossen. Project-/Auftrag-Create, Writeback, Push-Queue und
> M091 sind keine Rest-DoD von VEXT-1 oder `VR-P32a`; die fehlende externe Write-/Create-Capability wird
> separat in `VEXT-6` als Blocked / On Hold nachgehalten. `VEXT-6` blockiert keine read-only
> Connector-/Inbound-Tickets. Die datierten Vertrags- und Diagnoseeinträge unten bleiben als Historie
> erhalten.
> 🟢 **Update 2026-06-25 — Freischaltungsdaten eingetroffen (früher als ~19./20.07.):** KWP hat den OAuth2-Client für den Mandanten `geerkens2` bereitgestellt. Der reine Kalenderblocker ist damit aufgelöst; die KWP-Phase bleibt jedoch durch Runtime-Token/Scope-Proof und die fehlende Auftrag-Create-Capability blockiert. R-P5 (Apps-Engine M33a) ist inzwischen abgeschlossen. Stand der 7 Vertrags-Fragen siehe Umsetzungs-Notiz unten. **KWP bleibt v2-Scope.**
> 🟡 **Update 2026-07-12 — tenant-spezifischer Vertrag verifiziert:** Der KWP-Loadbalancer löst
> `geerkens2` aktuell auf `https://geerkens2.app04.kwp-online.de` auf. Maßgeblich ist die Tenant-OpenAPI unter
> `/relay/geerkens2/pwa/swagger/v1/swagger.json` (OAS 3.0.1, 301 Pfade, 303 Operationen, 396 Schemas,
> SHA-256 `5c504ffa955bc492fcc16ae01a92ad0491db29a904ad59058123fc3b24f26762`). Endpoints,
> Dokumentenfluss und partielle Konfliktfelder sind damit belastbar erfasst. Ein echter Token-/Resource-Call
> bleibt offen, weil die per Mail genannten Keycloak-Endpunkte von den OAuth-Endpunkten der Tenant-Swagger
> abweichen. Formal abgeschlossen sind der Recut-Ausschluss von `kwpsync.exe` sowie Redirect-/AVV-Nachzug.
> 🟡 **Runtime-Probe 2026-07-12 — Benutzerlogin fehlt:** Client-ID, Client-Secret, Kundenkürzel und die von
> KWP gelieferten Scopes liegen verschlüsselt in `secrets/dev.sops.env`; Klartextwerte stehen nicht in Git oder
> dieser Doc. Keycloak lehnt `client_credentials` ab, weil der Service-Account für den Client deaktiviert ist,
> und lehnt den Device Authorization Grant ab, weil dieser Flow ebenfalls deaktiviert ist. Damit ist
> **Authorization Code + PKCE mit einem echten bnWin-Benutzer der einzige freigeschaltete Login-Pfad**. Die
> Kombination `openid` + fünf `*-extern`-Scopes + `offline_access` wird am Authorization-Endpunkt akzeptiert;
> der zusätzliche Discovery-Scope `email` führt für diesen Client zu `invalid_scope`. Token-Austausch und erster
> Resource-Call warten auf einen berechtigten Geerkens/bnWin-Testbenutzer aus `VN-1`.
> 🟢 **Herstellerantworten 2026-07-20 — Recut-Planung fachlich geklärt:** Pro Client gilt ein
> Hard-Cap von **60 Requests/Minute**; weitere Vorgaben zu Parallelität, Backoff, Jitter oder `429` wurden nicht
> gemacht. Access-Token gelten **5 Minuten** plus **5 Minuten technischen Clock-Skew**. Refresh-Token gelten
> **30 Tage idle / maximal 365 Tage**, sind einmalig und rotieren bei jeder Access-Token-Anforderung; eine
> Passwortänderung oder Benutzerdeaktivierung widerruft sie. KWP bietet keine Änderungs-Webhooks oder
> authentifizierten Änderungs-Callbacks, Delta-Cursor, als Delta-Vertrag nutzbaren einheitlichen
> Änderungszeitstempel oder „geändert
> seit“-Filter und keine Sandbox bzw. keinen Testkunden. `x-kwp-client-version` ist optional. Die Neuanlage
> eines Projekts/Auftrags über die API ist
> ausdrücklich nicht vorgesehen. `mandant` wird nur gesendet, wenn in kwp-bnWin.net ein Mandant eingerichtet
> ist, dann mit dessen Kürzel; andernfalls entfällt der Queryparameter. Ob dies für Geerkens zutrifft, ist noch
> offen. Damit ist die Recut-Detailplanung abgeschlossen; nur der echte Login-/Token-/Resource-Proof bleibt offen.
> 🟢 **Herstellerdiagnose zum fehlgeschlagenen Login 2026-07-20:** Laut KWP-Logs aktualisierte sich der
> BackendApi-Dienst erst am **13.07.2026** auf **2.81.62**; die damaligen Tests liefen größtenteils am 12.07.
> und damit vor dem erforderlichen Backend-Stand. KWP erwartet, dass die Anmeldung jetzt funktioniert. Diese
> Diagnose ersetzt den ausstehenden Retest nicht. Verbindlich sind der zentrale Issuer
> `https://id.kwp-online.de/realms/kwp-federated` und für die Geerkens-Resource die Audience
> `https://geerkens2.app04.kwp-online.de/relay/geerkens2/pwa`. Einen separaten `resource`-Wert hat KWP nicht
> benannt, sondern um Präzisierung gebeten; er bleibt deshalb ohne erfundenen Claim-/Parametervertrag offen.
> 🟡 **Lokaler Retest 2026-07-20 — Versionsblocker weg, BNWIN-Login offen:** Der echte lokale HiveGrid-Pfad
> erreicht nach Login, Tenant-/Feature-/Permission-Gate und CSRF-Prüfung den zentralen Keycloak-Authorization-
> Endpoint mit allen sieben vereinbarten Scopes, `tenant=geerkens2`, State, Nonce und PKCE/S256. Die lokale
> Callback-URL wird erwartungsgemäß mit `400 invalid_redirect_uri` abgelehnt; die bereits registrierte
> Staging-Callback-URL liefert mit demselben Request `200` und das BNWIN-Loginformular. Parallel liefern
> `Core/GetApiVersion` den Wert `2` und `Core/GetVersion` die Hersteller-Version **2.81.62**. Ein geschützter
> Adressaufruf ohne Token endet korrekt mit `401 Bearer`. Damit ist der frühere Backend-Versionsblocker
> ausgeräumt. Die registrierten HiveGrid-Staging-Routen selbst liefern aktuell noch `404`, weil der lokale
> Pilot-Branch nicht deployt ist. Auth-Code, Token, Scope-Claims, authentifizierter Resource-Call und Refresh
> bleiben bis zu Deploy und echtem BNWIN-Login offen. Es wurde kein Credential rotiert.
> 🟢 **Dependency-Ausnahme 2026-07-20:** In `VR-P32a` darf ausschließlich der schmale
> **Geerkens-Pilot-Slice** vor Abschluss dieses Tickets umgesetzt werden: OAuth2/PKCE-Start, fester Callback,
> Code-/Token-Austausch und per-Tenant-DEK-verschlüsselte Persistenz. Read-only Relay-Discovery und Health sind
> ausschließlich als notwendiger Live-Proof enthalten; Refresh-Rotation gehört zum Token-Lifecycle. **Pull,
> Push und manueller Sync sind in diesem Slice nicht freigegeben.** Die Ausnahme ersetzt weder den
> berechtigten bnWin-Testbenutzer aus `VN-1` noch Auth-Code-, Token-, Scope- und Resource-Proof. `VEXT-1` bleibt
> deshalb Blocker für Live-Verifikation und Done von `VR-P32a`; ohne erfolgreichen bnWin-Login begründet der
> Slice keinen Live- oder Done-Claim.
> 🟡 **Staging-Erst-Proof 2026-07-21:** Der echte BNWIN-Authorization-Code-/PKCE-Flow war auf Staging
> vollständig erfolgreich. HiveGrid tauschte den Code am zentralen Keycloak aus, akzeptierte ausschließlich
> die fünf verpflichtenden `*-extern`-Scopes, rief mit dem Access-Token den geschützten Relay-Endpunkt
> `Core/GetApiVersion` erfolgreich auf und persistierte die OAuth-Credentials per-Tenant-DEK-verschlüsselt in
> einer aktiven `DataConnection`. Der General Worker rotierte den einmaligen Refresh-Token anschließend
> automatisch; die Token-Ablaufzeit rückte dabei um weitere fünf Minuten vor und der Connection-Health blieb
> `active`. Kein Client-Secret, Passwort oder API-Key wurde rotiert; ausschließlich der von KWP zwingend
> rotierende Einmal-Refresh-Token wurde im normalen Refresh-Flow ersetzt. `KWP_MANDANT` blieb ungesetzt und
> Produktion blieb unverändert. Dieser Lauf beweist den echten Auth-/Resource-Pfad, aber noch keinen stabilen
> Dauerbetrieb: Ein späterer Refresh schlug um 03:09:54 CEST fehl und setzte die Verbindung auf `broken`.
> 🟢 **Mandantenvertrag und Scope-Freigabe 2026-07-21:** Die aktuelle Geerkens-Tenant-OpenAPI enthält
> `GET /api/Mandant/Load`. Der Endpoint beschreibt die für den angemeldeten Benutzer zulässigen Mandanten als
> `DtoMandant{id, kuerzel, bezeichnung}` und ist damit die bevorzugte Discovery für den neuen
> VR-P32a-Verbindungsflow. Seine OpenAPI-Security nennt jedoch nicht die fünf für HiveGrid gelieferten
> `*-extern`-Scopes, sondern andere KWP-interne Produkt-Scopes; die Capability ist für den externen Client
> deshalb erst zur Laufzeit beweisbar. Die Implementierung darf bei fehlender Berechtigung nicht „kein
> Mandant“ annehmen, sondern verlangt eine ausdrückliche `none`-Bestätigung oder das manuell eingegebene
> exakte Kürzel. Die konkrete Geerkens-Zuordnung bleibt Live-/E2E-Input, blockiert aber nicht mehr den
> generischen Setup-Bau. Der vorprovisionierte Pilot bleibt processweit an `KWP_HIVEGRID_TENANT_ID` gebunden;
> eine sichere Mehr-Tenant-/Mehr-Kunden-Provisionierung ist Folge-Scope.
## Was zu tun
KWP-API-Zugang aktivieren und die **Recut-Detailplanung pro Milestone gegen die echte API-Doku** durchführen — nicht gegen Annahmen. Konkret die 7 ursprünglich offenen Vertrags-Fragen aus dem bindenden Recut klären und je Milestone (M089–M095) entscheiden (Auflösungsstand siehe Umsetzung):
1. **Auth-Runtime** (Keycloak- oder Relay-`/connect/*`-Endpoint, Token-/Refresh-Verhalten) → `App.connectionType='oauth2'` + Credential-Handling ist bereits gesetzt
2. **Endpoints + Capabilities** (welche Entitäten les-/schreibbar: Aufträge, Stammdaten, Belege, Plantafel, Dokumente?)
3. **Webhook-/Delta-Support** außerhalb der Tenant-OpenAPI → laut Hersteller nicht vorhanden; ein späterer Pull muss ohne Delta-Mechanismus geplant werden
4. **Rate-Limits** → 60 Requests/Minute Hard-Cap pro Client; bestimmt Replay-Rate (M091) und Pull-Intervalle
5. **Versionierung/Changelog** → API `v1`, `x-kwp-client-version` optional; bestimmt Umfang M092 (eigenständig vs. in M089)
6. **Dokumenten-API** (Listing + Download) → Voraussetzung M095
7. **Konflikt-Felder** pro Endpoint → M093 nutzt mangels einheitlicher Felder HiveGrid-Snapshots + Audit-Restore
In v1 bereits erledigt (Andockpunkte): Callback-URL `https://app.hivegrid.de/integrations/kwp/oauth/callback` an KWP gemeldet (feste URL, Tenant im `state`, OAuth Auth-Code + PKCE); bnWin.net-8.1-N3-Update bei Geerkens angestoßen. Produktions- und Staging-Redirect werden vom Authorization-Endpunkt akzeptiert (Probe 2026-07-12).
## Warum / blockt
Die Detailplanung ist durch OpenAPI, Herstellerantworten und den erfolgreichen Staging-Runtime-Proof belastbar.
Der Proof gibt keinen über den read-only Geerkens-Scope hinausgehenden Sync-Bau frei. Der vom Hersteller
nicht unterstützte Project-/Auftrag-Create wird in `VEXT-6` geparkt; die fehlenden kontrollierten fachlichen
Testdaten bleiben in `VN-1` separat zu klären.
**`kwpsync.exe` NICHT bauen** (Recut bindend, M089 = Connector statt Windows-Client). ⚠ Creds liegen bei API-Anbindung verschlüsselt in der Cloud
(`DataConnection.credentialsCiphertext`, Per-Tenant-DEK) — Spec-19.1.2 gilt nicht mehr 1:1 → Vermerk an AVV/Subprozessoren
(VR-P31/M166) weiterreichen.
## Abhängigkeiten
- **Blocked by:** keine. `VN-1` bleibt wegen des noch nicht kontrolliert freigegebenen Geerkens-Datenbereichs
und des fehlenden minimal berechtigten BNWIN-Testbenutzers eigenständig bei 0/1.
Die generische Discovery-/Auswahl-Implementierung in `VR-P32a` ist abgeschlossen; im Live-Reconnect wurde
genau eine Geerkens-Bindung ausdrücklich bestätigt und verschlüsselt gespeichert. Kontrollierte fachliche
Daten-Calls und Sync-E2E bleiben weiterhin Scope von `VN-1`/`VN-2`.
- **Blocks:** keine read-only Connector-Tickets mehr. `VR-P32a` ist nach dem zweistündigen Demand-Refresh-
Dauer-Proof 5/5 Done; der Code-/Fixture-Proof und credential-geschützte Staging-Betrieb von
`VR-P32b`/`VR-P32d` bleiben abgeschlossen. Ein möglicher späterer Write-/Create-Vertrag liegt
ausschließlich in `VEXT-6`.
- **Parallel:** v1-Andockpunkte (Apps-Engine M33a, Extension-Points) stehen bereits — dieser Task füllt nur die Vertrags-Lücken.
## Definition of Done
- [x] **KWP-API-Zugang dauerhaft aktiv** (Auth-Code, Token, Scope und geschützter Resource-Call bleiben
bewiesen; erneuter Langzeit-Proof nach Refresh-Regression mit 20/20 Demand-Rotationen erbracht)
- [x] **Recut-Detailplanung pro Milestone** (M089–M095) gegen echte Doku + Herstellerantworten — alle 7 Vertrags-Fragen für die Planung beantwortet
- [x] **`kwpsync.exe` NICHT gebaut** (Recut bindend bestätigt)
- [x] Staging-Redirect-URI bei KWP registriert; AVV/Subprozessor-Vermerk an VR-P31 weitergereicht
## Quellen (granular)
- **`.planning/KWP-API-CONTRACT.md` (bindend)** → 7 offene Vertrags-Fragen, `appsEngine.prisma`-Übernahme-Liste, Credential-Hinweis
- [Offizielle KWP-API-Dokumentation](https://www.kwpsoftware.de/kwp-api-dokumentation/) → dynamische
Host-Auflösung, userbezogene Auth, `mandant`-Query und Azure-Blob-Dokumentenaustausch
- Tenant-OpenAPI `https://geerkens2.app04.kwp-online.de/relay/geerkens2/pwa/swagger/v1/swagger.json`
→ maßgeblicher maschinenlesbarer Vertrag für `geerkens2`, einschließlich
`GET /api/Mandant/Load`/`DtoMandant` (Snapshot/Hash siehe Umsetzung)
- `ROADMAP-V2.md` → §v2-P5 + §Offene Vorlauf-Tasks #1 (Runtime-/Capability-Restvertrag)
- `ROADMAP.md` → Phase 32 · Milestones: (Callback-URL gemeldet, bnWin.net-8.1-N3, Andockpunkte v1)
- abhängig-für: `ticket-docs/VR-P32a.md`/`VR-P32b.md`/`VR-P32c.md`
## Umsetzung (2026-06-25 / Vertragsprüfung 2026-07-12 / Herstellerantworten 2026-07-20, Owner Raffael)
**Historischer Abschlussstand:** **VEXT-1: 4/4 DoD = 100 % done.** Der Staging-Erst-Proof vom 2026-07-21 schloss Auth-Code,
Token, Scope, geschützten Resource-Call und verschlüsselte Persistenz ab. Der Haltbarkeits-Deploy und neun
aufeinanderfolgende automatische Refresh-Rotationen vom 2026-07-22 schließen den Dauer-Live-Punkt. `VN-1`
bleibt als eigenständiges Testumgebungs-Ticket offen. Im Reconnect wurde eine Bindung über den generischen
Verbindungsflow ausdrücklich bestätigt und verschlüsselt gespeichert; ihr Wert wird nicht in dieser Doc
wiederholt und begründet keine Freigabe kontrollierter Fach-E2E-Daten. Proof
2026-07-12: Tenant-OpenAPI vollständig
abgerufen und per SHA-256 fixiert; offizielle KWP-Webdoku gegengeprüft; Keycloak-Authorization-Probe mit dem
gelieferten externen Client, PKCE/S256 und den fünf externen Scopes für Produktions- und Staging-Redirect jeweils
HTTP 200/Login-Seite ohne `invalid_client` oder `invalid_redirect`; kein ausführbarer `kwpsync.exe`-Konsument
im Repository angelegt. Der Staging-Redirect ist damit am Authorization-Endpunkt plausibilisiert; der konkrete
Cloud-Credential-/Relay-/Azure-Austausch-Vermerk wurde am 2026-07-12 in `VR-P31` übernommen.
**Zusatz-Proof 2026-07-12:** Die Freischaltungs-Mail wurde ausschließlich lokal verarbeitet; die Felder
`KWP_OAUTH_CLIENT_ID`, `KWP_OAUTH_CLIENT_SECRET`, `KWP_OAUTH_SCOPES`, `KWP_CUSTOMER_CODE` und
`KWP_OIDC_ISSUER` wurden per SOPS/age verschlüsselt abgelegt. Für lokale Tests und Staging bleibt das aktuell
provisionierte Secret unverändert; ohne ausdrücklichen User-Auftrag wird es weder rotiert noch als Test- oder
Deploy-Blocker behandelt. Der Token-Endpunkt antwortete auf
`client_credentials` mit `401 unauthorized_client` (Service-Account deaktiviert); der Device-Endpoint auf den
Device Authorization Grant mit `400 unauthorized_client` (Flow deaktiviert). Scope-Probes bestätigten die fünf
gelieferten `*-extern`-Scopes gemeinsam mit `openid`/`offline_access`; nur `email` ist für den Client nicht
freigeschaltet. Der Auth-Code-Flow leitete an die bei KWP registrierte Staging-Redirect-URL weiter; dort war zu
diesem Zeitpunkt noch kein HiveGrid-Callback-Handler deployt. Ohne bnWin-Benutzerlogin entstand zudem kein
Code/Token. Einmalige PKCE-State-/Verifier-Dateien wurden danach lokal entfernt.
**Lokaler Pilot-Slice 2026-07-20:** Der Worktree enthält nun den festen Setup-/Callback-Pfad und bindet die
Prozess-Credentials über `KWP_HIVEGRID_TENANT_ID` an genau einen HiveGrid-Tenant. Dieser Stand ist nicht auf
Staging oder Produktion deployt und begründet weder einen erfolgreichen Callback noch Token-/Resource-Proof.
`KWP_MANDANT` bleibt bis zur Geerkens-Antwort bewusst ungesetzt. Lokaler Basis-Proof: Implementierungs-Commit
`f0a0033bb`, Typecheck/Lint grün und 6.926 Tests bestanden; den vollständigen Verify-Stand einschließlich der
vorbestehenden Route-Inventar-Drift dokumentiert `VR-P32a`. Das ist nur Code-Regressions-Proof und kein
Auth-/Token-/Scope-/Resource-/Refresh-Live-Proof. KWP-Disconnect ist im Pilot in UI und Action fail-closed deaktiviert, weil eine lokale
Connection-Löschung den Keycloak-Refresh-Token nicht nachweisbar widerruft. Reconnect bleibt möglich;
providerseitige Revocation ist unverifiziert und bleibt Token-Lifecycle-Nachzug sowie Live-Blocker.
Plane-Kommentar: `00c2720b-1a72-44b8-9d51-5b7c7c1fa647`. **VEXT-1 bleibt 3/4 DoD = 75 % done**.
**Lokaler HTTP-/Provider-Proof 2026-07-20:** Login `200`, Session `302`, authentifiziertes KWP-Setup `200`
und Authorization-Redirect `302` wurden über den laufenden lokalen Web-Prozess ausgeführt. Der erzeugte
Authorization-Request ist vollständig und verwendet exakt die sieben vereinbarten Scopes sowie PKCE/S256.
Keycloak akzeptiert die registrierte Staging-Callback-URL (`200`, BNWIN-Loginformular), nicht jedoch die nicht
registrierte Localhost-Callback-URL (`400 invalid_redirect_uri`). Die Staging-Setup-/Callback-Routen liefern
bis zum Deploy dieses Branches beide `404`. Damit endet ein rein lokaler E2E-Lauf vor der Benutzeranmeldung.
Dieser Proof ändert die DoD-Zählung nicht: **VEXT-1 bleibt 3/4 DoD = 75 % done; offen:
1 Punkt, extern durch BNWIN-Testzugang/`mandant`-Auskunft blockiert, 0 selbst machbar.**
**Staging-Callback-Retest 2026-07-20:** Der echte BNWIN-Login einschließlich Zustimmung wurde abgeschlossen
und der gültige OAuth-Rückruf erreichte HiveGrid. Challenge und `state` wurden erfolgreich eingelöst; der
anschließende Token-/Aktivierungspfad endete jedoch vor jeder verschlüsselten Token-Persistenz, und die
reservierte Verbindung blieb `pending`. Der bisherige Catch ließ Token-Austausch, KWP-Health und Persistenz
nicht sicher unterscheiden; der Follow-up ergänzt dafür ausschließlich feste, secretsichere Diagnosecodes.
Ein geschützter Resource-Aufruf steht weiter aus. Es gab keine Credential-Rotation und keine Änderung an
Produktion oder `KWP_MANDANT`. **VEXT-1 bleibt 3/4 DoD = 75 % done; offen: 1 Live-Proof-Punkt.**
Der secretsichere Diagnose-Follow-up liegt lokal in Commit `4886f3132`; **57/57** gezielte KWP-Tests und der
vollständige Lauf mit **6.975 bestandenen / 55 übersprungenen Tests** sind grün. Ein neuer Live-Versuch folgt
erst nach dem Staging-Deploy dieses Commits.
**Staging-Scope-Diagnose 2026-07-21:** Nach dem Deploy der secretsicheren Diagnose auf Revision
`65976d712` erreichten zwei frische OAuth-Rückrufe den Token-Austausch und scheiterten reproduzierbar mit
`exchange_failed` / `scope_mismatch`. Damit ist die alte einzelne `pending`-Verbindung als Ursache
ausgeschlossen: Der Setup-Pfad verwendet sie bei jedem neuen Versuch weiter, und ein fehlgeschlagener Callback
verändert sie nicht. Der Token-Response enthielt bereits Access-Token, Refresh-Token und eine gültige Ablaufzeit;
HiveGrid verlangte danach jedoch fälschlich ein exaktes Echo aller sieben Request-Scopes. Der lokale Fix lässt
im Response-Echo ausschließlich das Fehlen von `openid` und/oder `offline_access` zu. Alle fünf
`*-extern`-Scopes bleiben zwingend, unbekannte und doppelte Scopes werden abgelehnt, und Requests sowie
verschlüsselte Soll-Policy bleiben exakt auf den sieben kanonischen Scopes. Derselbe Vertrag gilt beim Refresh;
Rotation und 300-Sekunden-TTL ändern sich nicht. Lokaler Proof: **80/80** gezielte KWP-Tests, **189/189**
Tests im Integrationspaket und der vollständige Lauf mit **6.985 bestandenen / 55 übersprungenen Tests** sind
grün; ebenso Typecheck, Lint, die vier allgemeinen Repository-Validatoren, `git diff --check` und der
EU-Provider-Scan. Keine Rotation, keine Änderung an `KWP_MANDANT`, keine Produktionsänderung. Ein Deploy und
der geschützte Resource-Call stehen weiter aus;
**VEXT-1 bleibt 3/4 DoD = 75 % done.**
**Staging-Abschluss-Proof 2026-07-21:** Der Scope-Fix aus PR `#191` wurde als Revision `56d2b4f00`
ausschließlich auf Staging deployt; Deploy-Run `10863` war erfolgreich und alle Staging-Runtime-Container
liefen anschließend auf exakt dieser Revision. Der danach neu gestartete echte BNWIN-Login samt Zustimmung
schloss den Authorization-Code-/PKCE-Flow ab. Der Callback aktivierte genau eine `DataConnection`, speicherte
die Credentials per-Tenant-DEK verschlüsselt und führte über den registrierten KWP-Adapter einen erfolgreichen
geschützten Health-Aufruf auf `Core/GetApiVersion` aus. Der Datenbank-Proof zeigte `connectionStatus=active`,
vorhandenes Ciphertext-Material und `healthMessageKey=integrations.kwp.health.active`. Um **02:54:47 CEST**
schloss der General Worker `integrations-token-refresh` erfolgreich ab; `tokenExpiresAt` rückte dabei auf
**02:59:47 CEST** vor und der anschließende Health-Stand blieb `active`. Da der Adapter beim Refresh einen
neuen, vom vorherigen Wert verschiedenen Refresh-Token verlangt, beweist dieser Lauf auch die einmalige
Refresh-Token-Rotation. Es wurden keine Token-, Secret- oder Passwortwerte ausgelesen oder protokolliert.
Kein Client-Secret, Passwort oder API-Key wurde rotiert; ausschließlich der von KWP zwingend rotierende
Einmal-Refresh-Token wurde im normalen Refresh-Flow ersetzt. `KWP_MANDANT` blieb ungesetzt und Produktion
blieb auf der unveränderten Revision `6100b4e16`. Dieser Erstlauf erfüllte den Live-Proof zunächst vollständig;
die nachfolgende Langzeitkorrektur nimmt den damaligen Abschluss-Claim wieder zurück.
**Langzeit-Korrektur 2026-07-21:** Der Erst-Proof war echt, der Dauerbetrieb ist jedoch nicht grün. Nach einem
erfolgreichen Refresh um **03:04:46 CEST** (`refreshed=1`, Dauer 701 ms) endete der nächste Lauf um
**03:09:54 CEST** nach **7,36 s** mit `refreshed=0`, `failed=1`. Die `DataConnection` steht seitdem auf
`broken`, `healthMessageKey=integrations.health.refreshFailed`; Ciphertext bleibt vorhanden. Der auf der
damaligen Staging-Revision laufende Worker verwirft beim Provider-Aufruf den konkreten Fehlercode, daher lässt
sich aus Worker-, BullMQ- und Loki-Proof nicht sicher zwischen Provider-Ablehnung und transientem
Transportfehler unterscheiden. Kein
Client-Secret, Passwort oder API-Key wurde rotiert, `KWP_MANDANT` blieb ungesetzt und Produktion unverändert.
Der vorherige 100-%-Claim wird zurückgenommen: **VEXT-1: 3/4 DoD = 75 % done · 1 Punkt diagnostisch offen ·
1 selbst machbar.**
**Lokaler Refresh-Stabilitätsfix 2026-07-21:** Der zu diesem Zeitpunkt noch nicht deployte Follow-up klassifiziert
Providerfehler ausschließlich über feste Diagnosecodes und einen optionalen numerischen HTTP-Status; weder
Provider-Body noch Token- oder Secret-Werte werden gespeichert oder geloggt. Genau ein transienter Fehler
(`408`, `429`, `5xx`, Netzwerk/Timeout oder die allowgelisteten OAuth-Fehler `server_error` und
`temporarily_unavailable`) wird nach frühestens fünf Minuten einmal wiederholt. Dauerhafte Auth-/Scope-/
Credential-Fehler und ein zweiter transienter Fehler setzen die Verbindung auf `broken` und verlangen einen
Reconnect. Während des Retry-Fensters läuft keine konkurrierende Health-Probe. Auch nach erfolgreichem
Token-Retry bleibt die Verbindung `degraded` mit `integrations.health.refreshRecovered`, bis ein echter
geschützter `Core/GetApiVersion`-Probe sie wieder auf `active` setzt. Ein älter als zehn Minuten liegen
gebliebener Claim wird ohne erneuten Provider-Aufruf terminalisiert. BullMQ weist geplante Retries separat als
`retryScheduled` statt als `failed` aus. Tests decken die persistierte Einmal-Token-Kette `r1 → r2 → r3`,
die Fünf-Minuten-Grenze, unbekannten POST-Ausgang, Status-/OAuth-Klassifizierung, Retry-Erschöpfung,
Resource-Probe und Stale-Claim-Recovery ab. Der bestehende `broken`-Datensatz wird absichtlich nicht mit alten
Credentials erneut verwendet; nach dem Staging-Deploy ist genau ein neuer interaktiver OAuth-Reconnect nötig.
Lokaler Proof: **80/80** gezielte KWP-Tests, **217/217** Tests im Integrationspaket, **1/1** fokussierter
Worker-Handler-Test sowie der vollständige Root-Lauf mit **7.026 bestandenen / 55 übersprungenen Tests** sind
grün. Ebenso grün sind Root-Typecheck, Root-Lint, Integrations-/Worker-Typecheck, `verify:ci-baseline`,
`verify:source-health`, `verify:i18n`, `verify:secrets`, `git diff --check` und der EU-Provider-Scan.
Bis dieser Reconnect und mehrere echte Refresh-/Resource-Zyklen stabil belegt sind, bleibt
**VEXT-1: 3/4 DoD = 75 % done · 1 Live-Punkt offen · 1 selbst machbar.** Es wurde nichts manuell rotiert,
`KWP_MANDANT` bleibt ungesetzt und Produktion bleibt unverändert.
**Staging-Langzeitstand und lokaler Haltbarkeits-Nachzug 2026-07-22:** Die beobachtete Staging-Revision war
`d4daa0421`. Der präzisierte Worker-/Datenbankabgleich zeigt um **03:04:47 CEST** einen erfolgreichen
Refresh und um **03:09:53 CEST** den direkt folgenden fehlgeschlagenen Lauf. Die `DataConnection` wechselte
auf `broken` mit `integrations.health.refreshFailed`; eine konkrete Provider-/Transportklassifikation war in
den verfügbaren Runtime-Diagnosen nicht vorhanden. Der dauerhafte Runtime-Proof bleibt deshalb offen.
Der Haltbarkeits-Nachzug ist lokal **abgeschlossen**, aber noch nicht deployt. Er bindet die
Handler-Diagnostik an den strukturierten Runtime-Logger, trennt nachweislich replay-sichere Fehlerantworten
von mehrdeutigen Token-POST-Ausgängen und wiederholt einen möglicherweise bereits verbrauchten
Einmal-Refresh-Token niemals beim Provider. Retries gelten ausschließlich der lokalen Persistenz eines schon
erhaltenen Provider-Ergebnisses; der KWP-spezifische Refresh-/Health-Gate wird außerdem früher ausgeführt.
Erst mehrere erneute echte Refresh-/Resource-Zyklen können den Live-Punkt schließen. Keine manuelle Rotation,
keine Deploy- oder Live-Proof-Behauptung für diesen Nachzug. Der vollständige lokale Root-Testlauf ist mit
**7.115 bestandenen / 55 übersprungenen Tests** grün; ebenso Root-Typecheck/-Lint, Worker-Build und die
relevanten Deploy-, Runtime-, i18n-, Observability-, CI-, Source-, Secret- und Env-Gates. **VEXT-1 bleibt
3/4 DoD = 75 % done · 1 Live-Punkt offen · 1 selbst machbar.**
**Staging-Abschluss des Dauer-Live-Proofs 2026-07-22:** Der Haltbarkeits-Nachzug aus PR `#210` wurde als
Revision `2938f29da` über den erfolgreichen Deploy-Run `10995` auf Staging ausgerollt. Nach genau einem
normalen Authorization-Code-/PKCE-Reconnect war die Connection spätestens beim automatischen geschützten
Health-Probe um **03:54:47 UTC** `active`; der Probe meldete `checked=1`, `unhealthy=0`. Der
`worker-general` rotierte die KWP-Einmal-Refresh-Token danach neunmal automatisch und ohne Fehler:
**03:58:09**, **04:02:09**, **04:06:09**, **04:10:09**, **04:14:09**, **04:18:09**, **04:22:09**,
**04:38:09** und **04:42:09 UTC**; `tokenExpiresAt` stieg dabei bis auf **04:47:09.642 UTC**. Alle neun Läufe
meldeten `outcome=refreshed`, `failed=0` und `retryScheduled=0`; weder Provider- noch Persistenzfehler traten
auf. Die automatischen geschützten Health-Sweeps um **04:24:47 UTC** und **04:39:47 UTC** meldeten jeweils
`checked=1`, `unhealthy=0`. Der abschließende Read-only-Snapshot um **04:44:48 UTC** blieb `active` /
`integrations.kwp.health.active` mit
verschlüsselten Credentials. Kein Client-Secret, Passwort,
API-Key oder anderes Staging-Credential wurde manuell rotiert; ausschließlich KWP rotierte den
Einmal-Refresh-Token im normalen OAuth-Flow. Produktion blieb unverändert. Der Dokumentationsnachzug ist mit
Root-Typecheck, Root-Lint, **7.115 bestandenen / 55 übersprungenen Tests**, `verify:ci-baseline`,
`verify:source-health`, `verify:secrets`, `git diff --check` und dem EU-Provider-Scan grün.
**VEXT-1: 4/4 DoD = 100 % done.**
**Geliefert von KWP (Mandant `geerkens2`):** OAuth2-Zugang via **Keycloak-OIDC, Realm `kwp-federated`**
(`id.kwp-online.de`). Confidential Client (`offline_access`), ClientId-Schema `_extern-<tenant>`, Tenant-Kürzel
als URL-Param `tenant=geerkens2` am Authorization-Endpoint. **Secret NICHT in Repo/Doc** — gehört in
Coolify-Secret-Store bzw. später per-Tenant-DEK in `DataConnection.credentialsCiphertext` (AD-8). Für Staging gilt die
verbindliche No-Rotation-Regel aus `AGENTS.md`: vorhandene Credentials unverändert verwenden, solange der User
nicht ausdrücklich eine Rotation anordnet.
**OIDC-Discovery aus dem Mail-/Keycloak-Pfad verifiziert** (`…/realms/kwp-federated/.well-known/openid-configuration`):
Auth `…/protocol/openid-connect/auth` · Token `…/token` · Userinfo · JWKS `…/certs` · Logout · Introspection ·
Revocation. `grant_types`: authorization_code, **refresh_token**, client_credentials, device_code, token-exchange u.a.
`code_challenge_methods`: **plain, S256** (PKCE ✓). Token-Auth: client_secret_basic/-post, private_key_jwt, mTLS.
`scopes_supported` global nur `openid, email` → die fachlichen Scopes sind **Client-zugewiesene Keycloak-Scopes**
(die aus der Mail sind maßgeblich für unseren Token-Request).
**Token-Lifecycle laut Herstellerantwort 2026-07-20:** Access-Token gelten **5 Minuten** zuzüglich **5 Minuten
technischem Clock-Skew**. Refresh-Token gelten **30 Tage idle**, höchstens **365 Tage**, sind einmalig und
werden bei jeder Access-Token-Anforderung rotiert. Passwortänderung und Benutzerdeaktivierung widerrufen die
Token. Der Geerkens-Pilot muss den jeweils neu gelieferten Refresh-Token verschlüsselt ersetzen.
**Auth-Endpunkt-Diskrepanz — Runtime-Pfad live geklärt:** Die Tenant-OpenAPI nennt dagegen
`https://geerkens2.app04.kwp-online.de/relay/geerkens2/pwa/connect/authorize` und `…/connect/token`.
Der Staging-Live-Lauf bestätigt den von KWP per Mail benannten zentralen Keycloak-Authorization- und
Token-Endpunkt als verbindlichen Runtime-Pfad: Authorization Code + PKCE, Token-Austausch, geschützter
Relay-Resource-Aufruf und Refresh liefen dort erfolgreich. Die abweichenden `/connect/*`-Metadaten der
Tenant-Swagger werden daher nicht für HiveGrid verwendet. Service-Account- und Device-Flow bleiben für den
Client deaktiviert; der echte bnWin-Benutzerlogin ist zwingend. Laut offizieller KWP-Doku handelt die API
immer im Namen dieses Benutzers; dessen Rechte begrenzen alle Antworten und Schreibaktionen.
**Maßgebliche Resource-API für Geerkens:** Hosts werden nicht hart kodiert, sondern über
`https://loadbalancer.kwp-online.de/Relay/GetAppUrl?linkId=<KUNDENKUERZEL>` ermittelt. Für `geerkens2` lieferte
der Loadbalancer am 2026-07-12 `https://geerkens2.app04.kwp-online.de`; der Vertrag liegt unter
`/relay/geerkens2/pwa/swagger/v1/swagger.json`. Snapshot: **OAS 3.0.1 · 301 Pfade · 303 Operationen ·
396 Schemas · SHA-256 `5c504ffa955bc492fcc16ae01a92ad0491db29a904ad59058123fc3b24f26762`**.
Eine erneute Live-Probe am 2026-07-20 nach dem Hersteller-Update liefert **OAS 3.0.4 · 550 Pfade · 554
Operationen · 490 Schemas · SHA-256
`dcaff9253fe1bd2bf9bf6f29c89de7bd1f4415e115d90320775ead7e49c5febc`**. Der ältere Wert bleibt als
historischer 12.07.-Snapshot dokumentiert; für weitere Planung ist der 20.07.-Vertrag maßgeblich.
Der Server-Pfad ist `/relay/geerkens2/pwa`; die API bleibt RPC-artig. Nutzt ein Kunde bnWin-Mandanten, verlangt
die offizielle Doku bei jedem Request zusätzlich den Queryparameter `mandant=<Mandantenkürzel>`. Der Hersteller
hat präzisiert: Der Parameter wird nur gesetzt, wenn in kwp-bnWin.net tatsächlich ein Mandant eingerichtet ist,
dann mit dem dortigen Kürzel; andernfalls wird er weggelassen. `GET /api/Mandant/Load` beschreibt die für den
aktuellen Benutzer zulässigen Mandanten als `DtoMandant` mit interner `id`, Kürzel und Bezeichnung. Da die
OpenAPI-Security dieses Endpoints andere KWP-Produkt-Scopes statt der fünf gelieferten `*-extern`-Scopes nennt,
muss VR-P32a den Zugriff opportunistisch prüfen und einen bewussten manuellen Fallback anbieten. Ein Fehler oder
eine leere Antwort darf nicht automatisch als „kein Mandant“ gelten. Die konkrete Geerkens-Bindung steht noch
aus.
**Stand der 7 Vertrags-Fragen:**
1. **Auth-Methode → 🟡 Vertrag sowie Auth-/Resource-Erst-Proof abgeschlossen; Dauerbetrieb offen:** OAuth2/Auth-Code + PKCE und Refresh/
`offline_access` → `App.connectionType='oauth2'`. `client_credentials` und Device Flow sind für den Client
deaktiviert. Gültiger Request-Scope ist `openid` + fünf `*-extern`-Scopes + `offline_access`; `email` darf
nicht angefordert werden. Userbezogene Rechte sind bindend. Access-Token: 5 Minuten plus 5 Minuten Clock-Skew;
Refresh-Token: 30 Tage idle/maximal 365 Tage, einmalig und bei jeder Access-Token-Anforderung rotiert,
Widerruf bei Passwortänderung oder Benutzerdeaktivierung. Staging bewies Token-Austausch, geschützten
Relay-Aufruf und automatische Refresh-Rotation über den zentralen Keycloak-Pfad.
2. **Endpoints/Capabilities → 🟢 tenant-spezifisch erfasst, Project-Create nicht unterstützt:** In den
Operation-Security-Angaben erscheint `adresse-extern` aktuell an **23**, `archiv-extern` an **15**, `termin-extern`
an **14**, `vorgang-extern` an **31** und `aktivitaet-extern` an **31** Operationen. Adresse, Aktivität,
Termin/Monteursteuerung, Projekt/Projektampel/Vorgangsanzeige und Archiv sind vorhanden. Laut Hersteller ist
die **Neuanlage eines kaufmännischen Auftrags/Projekts über die API ausdrücklich nicht vorgesehen**;
`/api/Projekt/Save` ändert laut Vertrag nur die Bezeichnung eines bestehenden Projekts. Der geplante
Won→Auftrag-Push ist damit im aktuellen Vertrag nicht umsetzbar und darf nicht auf eine andere Operation
umgedeutet werden.
3. **Webhook-/Delta-Support → 🟢 geklärt, nicht vorhanden:** KWP bietet keine Änderungs-Webhooks oder
authentifizierten Änderungs-Callbacks und keine Delta-Cursor, als Delta-Vertrag nutzbaren einheitlichen
Änderungszeitstempel oder
„geändert seit“-Filter. Einzelne DTO-Felder aus Punkt 7 bilden keinen Delta-Vertrag. Ein späterer Pull muss
daher ohne diese Herstellermechanismen geplant werden; er gehört nicht zum freigegebenen Callback-Slice.
4. **Rate-Limits → 🟢 geklärt:** **60 Requests/Minute Hard-Cap pro Client.** Weitere Vorgaben zu parallelen
Verbindungen, Backoff, Jitter oder `429` wurden nicht gemacht. Replay und Pull müssen den Hard-Cap selbst
sicher einhalten; ihre Implementierung gehört nicht zum freigegebenen Callback-Slice.
5. **Versionierung → 🟢 Planungsgrundlage geklärt:** API-Dokument `v1`; der an allen 554 Operationen geführte
Header `x-kwp-client-version` ist laut Hersteller optional. Ein Pflicht-/Mindestwert wurde nicht vorgegeben;
M092 plant deshalb gegen den verifizierten Vertrag statt gegen einen angenommenen Mindestwert.
6. **Dokumenten-API → 🟢 vertraglich geklärt:** Listing/Suche/Details/Revisionen und Export sind unter
`/api/archiv-extern/*` vorhanden. Dateien laufen laut offizieller Doku nicht im API-Body, sondern über Azure
Blob Storage: `GetSetup.azureConnectionUri` maximal **6 h cachen**; Blobs werden nach **24 h gelöscht**;
`ExportDatei(revisionId,guid)` liefert `exchangeFileUri`, diese URL liefert JSON mit dem eigentlichen
Downloadlink. Upload: Blob ablegen, dann `ImportDatei(containerId,dateiname)` aufrufen.
7. **Konflikt-Felder → 🟢 Planungsentscheidung abgeschlossen:** Aktivitäten liefern `datumAenderung`/`userAenderung`; Archiv-
DTOs liefern `letzteAenderungAm`/`letzteAenderungVon` sowie `revisionId`/`revision`. Adresse, Termin und
Projekt/Vorgang haben keine einheitlichen Record-Versionen oder Änderungszeitstempel. Es gibt keine
`ETag`-/`Last-Modified`-Responses oder `If-Match`-Preconditions. M093 darf daher nicht auf uniformes
KWP-Optimistic-Locking bauen.
**Scope-Mapping — Authorization und Resource-Akzeptanz live bewiesen:** Die fünf `*-extern`-Scopes stehen jetzt direkt
an den oben gezählten Operationen. Sie fehlen jedoch in der Scope-Liste des OAuth-Flows; außerdem kombiniert die
Spec interne und externe Scope-Namen in einer Security-Liste, die nach strikter OpenAPI-Semantik alle Scopes
gleichzeitig verlangen würde. Der Live-Lauf bestätigte alle fünf Pflicht-Scopes im Provider-Echo und die
Akzeptanz des Access-Tokens am geschützten read-only Resource-/Health-Endpunkt. Schreib-Calls gehören nicht
zum Geerkens-Pilot-Slice und wurden nicht ausgeführt.
**Abschluss:** Auth-Code, Token-Austausch, Pflicht-Scopes, Relay-Pfad, geschützter read-only Resource-/Health-
Call, neun aufeinanderfolgende automatische Refresh-Rotationen und automatische geschützte
Health-Probes sind live bewiesen. Der Providerpfad ist
secretsicher klassifiziert; die Connection blieb `active`. Der AVV/Subprozessor-Vermerk ist in VR-P31/M166
übernommen und beide Redirects sind registriert. Die weiterhin fehlende KWP-Testumgebung bleibt in `VN-1`;
sie verhindert keine Erfüllung dieses Zugangstickets. Im Reconnect wurde genau eine Mandantenbindung
ausdrücklich bestätigt und verschlüsselt gespeichert; der konkrete Wert wird nicht in die Ticket-Doc kopiert.
`KWP_MANDANT` bleibt als processweite Mapping-Quelle ungenutzt.
**Superseding Scope-Abschluss 2026-07-22:** Der aktuelle Produktvertrag nutzt ausschließlich lesende
KWP-Operationen. Die fehlende Project-/Auftrag-Create-Capability wird nicht mehr als Blocker des Connectors
oder der Inbound-Tickets geführt, sondern in `VEXT-6` bis zu einem belastbaren Herstellervertrag geparkt.
**VEXT-1: 4/4 DoD = 100 % done.**
**Regression-Nachzug 2026-07-23:** Die Scope-Entscheidung bleibt unverändert read-only. Der erste
Dauerbetriebs-DoD ist wegen der oben dokumentierten späteren Refresh-Regression erneut offen; die drei
Vertrags-/Recut-Punkte bleiben erfüllt. **VEXT-1: 3/4 DoD = 75 % done · 1 Punkt offen · 1 selbst machbar.**
**Lokaler Regressionsfix-Proof 2026-07-23:** Commit `ccdc74ebe` vereinheitlicht die Laufzeitprüfung von
Erst-Login und automatischem Refresh auf positive ganzzahlige Werte bis maximal 300 Sekunden und ergänzt
feste redigierte Diagnosecodes für sämtliche semantischen Ablehnungsgründe. Ein mehrdeutiger Token-POST wird
weiterhin nicht wiederholt; es wurden keine Credentials manuell rotiert. Proof: Integrationspaket
**290/290**, fokussierter Worker-Satz **6/6**, Root-Typecheck, Root-Lint und Root-Testlauf **1.028 Dateien /
7.387 Tests bestanden, 55 übersprungen** sowie sämtliche release-relevanten Vertrags-, RLS-, Coverage-,
Hot-Swap-, Secret-, Deploy- und Build-Gates grün. Der dauerhafte Runtime-Proof bleibt bis normalem Reconnect
und erneutem Staging-Langzeitlauf offen. **VEXT-1: 3/4 DoD = 75 % done · 1 Live-Punkt offen.**
**Demand-Refresh-Live-Abschluss 2026-08-01:** PR `#312` wurde nach **11/11 grünen CI-Jobs** als normaler
Merge `a55b811ccd652cc04264d8d09e0f270a6487f27d` über Deploy-Run `11609` auf Staging ausgerollt. Nach einem
normalen Authorization-Code-/PKCE-Reconnect endeten im zweistündigen Fenster **20/20** Demand-Refreshes mit
`outcome=refreshed`; acht Health-Sweeps meldeten `checked=1`, `unhealthy=0`. Es gab keine Provider-,
Persistenz- oder Claim-Fehler, keinen `broken`-/`degraded`-Status und keine erneute Reconnect-Aufforderung.
KWP wurde aus dem generischen Minutensweep ausgeschlossen und rotierte nur noch vor echter Arbeit oder dem
regulären Health-Fenster. Damit ist der Runtime-DoD wieder geschlossen:
**VEXT-1: 4/4 DoD = 100 % done · 0 Punkte offen · Done.**
### Herstellerantworten (eingearbeitet 2026-07-20)
1. **Project-Create:** Die Neuanlage eines Projekts/Auftrags über die API ist nicht vorgesehen.
2. **Synchronisation:** Keine Änderungs-Webhooks oder authentifizierten Änderungs-Callbacks; keine Delta-Cursor, als Delta-Vertrag
nutzbaren einheitlichen Änderungszeitstempel oder „geändert seit“-Filter.
3. **Rate-Limit:** 60 Requests/Minute Hard-Cap pro Client; keine weiteren Vorgaben zu Parallelität,
Backoff, Jitter oder `429`.
4. **Token:** Access 5 Minuten plus 5 Minuten technischer Clock-Skew; Refresh 30 Tage idle/maximal 365 Tage,
einmalig und bei jeder Access-Token-Anforderung rotiert; Widerruf bei Passwortänderung oder
Benutzerdeaktivierung.
5. **Testumgebung:** Keine Sandbox und kein Testkunde.
6. **Mandant:** Nur setzen, wenn in kwp-bnWin.net ein Mandant eingerichtet ist; dann dessen Kürzel verwenden,
sonst den Queryparameter erst nach ausdrücklicher `none`-Bestätigung weglassen. Bevorzugte Discovery ist
`GET /api/Mandant/Load`; wegen der abweichenden Security-Scopes ist ein fail-closed manueller Fallback
erforderlich. Im Live-Reconnect wurde genau eine Geerkens-Bindung bestätigt und verschlüsselt gespeichert;
ihr konkreter Wert bleibt bewusst außerhalb der Ticket-Doc.
7. **Client-Version:** `x-kwp-client-version` ist optional.
ClientId, Secret und reale Redirect-Werte bleiben ausschließlich im vereinbarten sicheren Kanal.