ADR-052: Connected Apps und signierte Hooks

• Status: Angenommen
• Datum: 2026-07-18

Kontext

Manche Integrationen müssen unabhängig von Owlat deployt werden und können weder innerhalb von Convex noch im Nuxt-Bundle laufen. Ihre Netzwerkantworten, Zugangsdaten und Endpunkte sind nicht vertrauenswürdig und benötigen eine engere Grenze als beliebige Callbacks.

Entscheidung

Eine Connected App ist an genau ein gebündeltes Plugin, an explizite Capabilities und an plugin-gescopte API-Keys gebunden. Gemeinsame Hook-Secrets werden mit einem CSPRNG erzeugt, mit AES-256-GCM unter einem per HKDF abgeleiteten Schlüssel versiegelt, einmalig angezeigt und niemals von einer Query zurückgegeben.

Synchrone Draft-, Gate- und Score-Hooks verwenden domänenseparierte HMAC-SHA256-Signaturen über den exakten Body und die Request-Metadaten. Nonces verhindern Replays; die Verifikation erfolgt in konstanter Zeit. Endpunktvalidierung und abgesicherte Fetches schützen vor privaten Zielen, DNS-Rebinding und unsicheren Redirects. Deaktivierung oder Widerruf wird vor jeder Operation geprüft, und ein Widerruf greift kaskadierend auf plugin-gebundene API-Keys durch.

Konsequenzen

Connected Apps können Owlat erweitern, ohne einen Convex-Kontext oder Deployment-Secrets zu erhalten. Netzwerkunsicherheit schlägt in die sichere Richtung fehl, Zustell-Logs sind mandantengescopt und redigiert, und ausschließlich einschränkende Gate-Antworten können keinen Versand freigeben. Siehe Connected Apps.