Key-Store, Scopes und Auditlog vor produktiver Ausgabe prüfen

Developer-Onboarding, OpenAPI, Postman, SDKs und Sandbox contract_ready_waiting_for_live_keys · Developer Experience

Schließt die Developer-Experience-Lücke zu API-first Wettbewerbern mit Docs, Collections und SDK-Pfaden.

Grenze: Docs und Fixtures sind bereit; ohne Live-Key-Ausgabe bleibt es eine Integrationsvorbereitung. Nicht behaupten: Self-service API-Onboarding ist produktiv live.

Claims für Betreiber konsolidieren begrenzt

Dossier trennt technische Vorbereitung, Produktiv-Gates, Signoff, Rollback und Canary-Checks.

Grenze: Nicht behaupten: echte API-Keys sind live, solange Storage, Secrets, Domain-Claim und Gates nicht zusammen grün sind. Nächster Schritt: Darstellung auf klare Betreiber-Entscheidungen ausrichten: was ist fertig, was ist blockiert, was ist der nächste sichere Schritt.

Keine produktive Key-Ausgabe behaupten erlaubt: API-Key-Prozess ist vorbereitet und no-secret dokumentiert.

Nicht behaupten: Produktive API-Keys sind verfügbar.

Storage-Tabellen, Pepper, Betreiberrolle, Domain-Claim und Runtime-Gates müssen gemeinsam freigegeben sein.

Migration ist Übergabepaket, kein Auto-Apply erlaubt: SQL, Hash und Preflight sind für die DB-Verantwortung prüfbar.

Nicht behaupten: Die Migration wurde produktiv angewendet.

Der aktuelle Web-DB-User hat kein CREATE-Recht; Admin-DSN darf nicht öffentlich gespeichert werden.

Smokes prüfen Grenzen, nicht private Zielsysteme erlaubt: Öffentliche Routen, No-Secret-Regeln und Deny-Verhalten sind prüfbar.

Nicht behaupten: Alle Kundenintegrationen sind produktiv abgenommen.

Private Empfänger, Betreiberidentitäten, echte Keys und Webhook-Secrets bleiben außerhalb öffentlicher Evidence.

Betreiber-Wording statt Technikbehauptung erlaubt: Betreiber sehen nächste sichere Schritte und klare Stop-Bedingungen.

Nicht behaupten: Score oder API-Reife als pauschales Sicherheitsurteil darstellen.

Automatisierte Checks können Kontext wie Rollen, Consent, Paywall oder manuelle Betreiberfreigaben nicht vollständig bewerten.

Preflight

scripts/run-api-access-migration-preflight.sh

psql -d saferpage -Atq -c "select current_database(), current_user;"

psql -d saferpage -Atq -c "select coalesce(to_regclass('public.api_keys')::text,'missing'), coalesce(to_regclass('public.api_access_audit_log')::text,'missing');"

Smoke-Test

scripts/run-api-access-migration-preflight.sh

curl -fsS https://saferpage.de/api-zugriff/key-readiness-json | python3 -m json.tool

scripts/run-api-runtime-deny-smoke.sh

scripts/run-api-service-smoke.sh

Aktivierung

DDL-Migration für api_keys und api_access_audit_log anwenden.

API-Readiness erneut prüfen: api_access_storage_table_count muss 2 zeigen.

API-Key-Pepper und Write-HMAC-Secret nur im Server-Environment oder Secret Manager setzen.

Domain-Claim und Betreiberrolle verifizieren.

Test-Key nur einmal anzeigen, danach Deny-/Allow-/Revocation-Smokes ausführen.

Pause/Rollback

Sofortige Pause ohne DDL-Rollback: alle SAFERPAGE_API_*_READY Freigaben entfernen und API-Service neu starten.

Keys bei Verdacht auf Fehlkonfiguration auf status=revoked setzen statt Rohdaten zu exportieren.

DDL-Drop nur nach Backup-, Audit- und Retention-Freigabe ausführen.

Abnahme

api_keys und api_access_audit_log existieren.

api_keys enthält nur Prefix/Hash/Scopes/Status und keinen Roh-Key.

api_access_audit_log schreibt sanitisierte Deny-/Allow-Events ohne Authorization-Header.

Runtime-Gate-Probe bestätigt 401/403/429/Revocation-Fixtures.

Write-HMAC-Test-Fixture ist gegen Client/Receiver verifiziert.

Signoff-Paket

DDL-Hash fixiert · ready

27d802d48887d084e9132c841b943681c70638bd432746a92cab7809be621213

Preflight vor/nach Migration · ready

https://saferpage.de/evidence/api-access-migration-preflight.json

Kurzlebiger Admin-DSN · not_required_after_apply

DSN wird nie in Public-State, Repo, Logs oder Smoke-Ergebnis ausgegeben.

DB-Verantwortungsfreigabe · ready

Freigabe muss verantwortliche DB-Rolle, Zeitpunkt, SQL-Hash und Rollback/Pause-Entscheidung nennen.

API-Service Restart geplant · ready

Service-Restart erst nach erfolgreichem Preflight und Secret-Referenzen.

Rollback-Probe

Key-Ausgabe pausieren

Protected Routen bleiben denied.

Keine Rohdaten exportieren

No-Secret-Policy im Smoke bleibt grün.

Test-Keys widerrufen

Revocation-Smoke liefert Deny.

DDL nur nach Backup droppen

DB-Verantwortungsentscheidung außerhalb Public-Export dokumentiert.

Canary nach Migration

Preflight nach Apply

api_access_storage_table_count=2 und missing_required_artifact_count=0.

Readiness JSON prüfen

Storage grün, Produktiv-Gates nur bei echten Env-Freigaben grün.

Deny-Smoke ohne Key

401 deny und sanitisiertes Audit.

Runtime-Gate-Probe

Public/Protected/HMAC/Revocation-Vertrag vollständig.

No-Secret-Smoke

failed_check_count=0; blocked_expected nur für bewusst offene Gates.

Public Evidence erneut deployen

Öffentliche Evidence zeigt neue Smoke-Zeit und keine Secrets.

SQL-Hash vergleichen DB-Verantwortung

Public SHA-256 mit der lokal angewendeten Datei vergleichen.

Abnahme: Hash stimmt exakt mit dem Readiness-Export überein. Grenze: Hash beweist nur Dateigleichheit, nicht erfolgreiche Migration.

Apply-Fenster und Backup festlegen DB-Verantwortung/Platform

Zeitfenster, Backup-Stand und Pause-Entscheidung privat dokumentieren.

Abnahme: Zeitfenster und Rollback-Verantwortung sind vor Apply bestätigt. Grenze: Private Backup-Details werden nicht öffentlich exportiert.

Kurzlebigen Admin-DSN nutzen DB-Verantwortung

Migration nur aus sicherer Shell mit kurzlebigem Admin-DSN ausführen und DSN danach entfernen.

Abnahme: DSN taucht in keinem Public-Export, Repo, Log oder Smoke auf. Grenze: Ohne Admin-DSN bleibt der Web-DB-User erwartbar blockiert.

Preflight und Runtime-Smokes wiederholen Platform/Security

Preflight, Deny-Smoke, Runtime-Probe und API-Key-Readiness-Smoke nach Apply erneut ausführen.

Abnahme: api_access_storage_table_count=2 und failed_check_count=0; offene Produktiv-Gates bleiben als Blocker sichtbar. Grenze: Smokes erzeugen keine produktiven API-Keys.

Runtime-Gates erst nach Secret-Signoff aktivieren Security/Operator

API-Key-Pepper, Write-HMAC-Secret, Domain-Claim und Betreiberrolle privat abnehmen.

Abnahme: Alle Produktiv-Gates sind mit privatem Signoff und öffentlicher No-Secret-Evidence belegt. Grenze: Storage allein erlaubt noch keine Key-Ausgabe.

Sanitisierte Validierungsqueries

select coalesce(to_regclass('public.api_keys')::text, 'missing');

select coalesce(to_regclass('public.api_access_audit_log')::text, 'missing');

select count(*) from information_schema.columns where table_schema = 'public' and table_name = 'api_keys';

select count(*) from information_schema.columns where table_schema = 'public' and table_name = 'api_access_audit_log';

select tgname from pg_trigger where tgrelid = 'public.api_keys'::regclass and not tgisinternal;

Handoff-Abnahme

DB-Verantwortung bestätigt SQL-Hash und Apply-Fenster privat.

api_keys und api_access_audit_log existieren nach Apply.

Public Evidence enthält keine DSN-, Passwort-, Key-, Hash-, Header- oder Ziel-URL-Werte.

Deny-Smoke liefert 401/deny und schreibt nur sanitisiertes Audit.

Produktive Key-Ausgabe bleibt blockiert, bis Pepper, HMAC, Domain-Claim und Betreiberrolle privat freigegeben sind.

Go-live-Dossier nennt Rollback, Stop-Bedingungen und Nachlaufbeobachtung.

HMAC-SHA256 X-SaferPage-Signature · X-SaferPage-Idempotency-Key

Client berechnet über exakt diesen kanonischen String dieselbe Signatur und sendet sie mit Idempotency-Key.

Öffentlicher Testfall für Operator-API-Write-Clients. Nicht als produktives Secret verwenden.

Read-Probe mit Bearer-Key curl · reports:read

Bearer-Key nur aus Secret Manager oder Server-Env laden; nie in Browser, Logs oder Public Config schreiben.

401 ohne Authorization oder 403 bei fehlendem Scope/Domain-Claim.

curl -fsS "https://saferpage.de/api/operator/probe?scope=reports:read&domain=anrufer.info" -H "Authorization: Bearer ${SAFERPAGE_API_KEY}"

Node.js Write-HMAC node · nachweise:write

HMAC-Secret serverseitig halten; Idempotency-Key pro logischem Auftrag stabil setzen.

401/403/409 bei fehlender Signatur, falschem Scope oder wiederverwendetem Idempotency-Key.

crypto.createHmac("sha256", process.env.SAFERPAGE_API_WRITE_HMAC_SECRET).update(canonical).digest("hex")

PHP Server-Client php · portfolio:read

Key aus getenv lesen; Exception-Handler darf Authorization-Header nicht loggen.

401 bis Key-Store, Domain-Claim und Scope-Gate produktiv freigegeben sind.

$headers = ["Authorization: Bearer " . getenv("SAFERPAGE_API_KEY")];

CI-Dry-run ohne echten Key ci · schemas:read

CI nutzt nur Public Probe und Fixture-Signaturen; keine Live-Keys in Pull Requests.

Protected Routen bleiben im CI ohne Key denied.

curl -fsS https://saferpage.de/api-zugriff/runtime-gate-probe-json | jq .metrics

OpenAPI-Vertrag

Bearer-Auth als Security Scheme

Authorization: Bearer ${SAFERPAGE_API_KEY}; Roh-Key nie in Beispiele oder Public-Exports schreiben.

Scopes als x-saferpage-scopes

Jede geschützte Route nennt erlaubte Scopes, Domain-Scope und Risiko-Tier.

Sanitisierte Fehlerstruktur

code, message, request_id, retry_after und decision; keine Secrets, Header oder Rohpayloads.

Rate-Limit-Header

Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset als Client-Vertrag.

Write-HMAC Extension

x-saferpage-hmac mit Canonical-String, Idempotency-Key und Negativtests aus Fixture.

Request-ID und Audit-Korrelation

Clients senden oder übernehmen X-Request-ID; Audit exportiert nur Prefix, Scope, Entscheidung und Hashes.

Postman/Smoke Collection

runtime_gate_probe

Public Runtime-Vertrag und Deny-Fixtures abrufen.

missing_authorization_deny

401-Deny ohne Authorization reproduzieren.

operator_read_probe

Read-Key nach Go-live prüfen.

operator_write_hmac_probe

Write-HMAC und Idempotency testen.

revocation_probe

Widerrufener oder abgelaufener Key muss 403 liefern.

SDK-Readiness

Node.js

fetch oder undici, crypto.createHmac, AbortController

PHP

curl/ext-openssl, getenv, PSR-3 Redaction

Python

requests/httpx, hmac, uuid, backoff

Go

net/http, crypto/hmac, context timeout

CI/curl

curl, jq, masked secrets

Sandbox-Onboarding

Public Contract lesen

Runtime-Gate-Probe, Scope-Matrix, Fehlervertrag und No-Secret-Grenzen prüfen.

Deny-Smoke ausführen

Ohne Authorization 401 und sanitisiertes Audit erwarten.

Domain-Claim vorbereiten

Betreiberrolle, Domain-Scope und Zweckbindung vor Key-Ausgabe dokumentieren.

Read-Key testen

Test-Key einmal anzeigen, in Secret Manager legen und Read-Probe ausführen.

Write-HMAC testen

Canonical-String, Signatur und Idempotency-Key gegen Fixture prüfen.

Rotation proben

Dual-run, Client-Switch, Revocation und 24h-Nachlauf durchführen.

Webhook-Receiver-Abnahme

Receiver validiert HMAC

X-SaferPage-Signature wird mit konstantzeitlichem Vergleich geprüft.

Receiver speichert Idempotency-Key

Doppelte Write-Requests erzeugen keine zweite externe Aktion.

Retry ist nebenwirkungsarm

409/429/5xx werden mit Backoff und Jitter behandelt.

Payload minimiert

Keine Roh-Cookies, Authorization-Header, Besucherlogs oder private Dokument-URLs.

Receiver-Logs redacted

Logs enthalten Request-ID, Prefix und Entscheidung, aber keine Secrets.

Support-SLO

sev1_key_leak_suspected

Key pausieren, Prefix auditieren, Rotation erzwingen.

sev2_write_delivery_blocked

HMAC, Idempotency, 409/429 und Receiver-Antwort prüfen.

sev3_scope_or_domain_denied

Scope-Matrix, Domain-Claim und Betreiberrolle prüfen.

sev4_docs_or_sdk_question

Quickstart, OpenAPI/Postman oder SDK-Beispiel aktualisieren.

Issuance-Signoff

Requester und Betreiberrolle verifiziert · required_before_key

OIDC/MFA, Betreiberkonto und Domain-Claim sind vor Key-Erzeugung bestätigt.

Scopes und Domain-Grenzen freigegeben · required_before_key

Scope-Matrix, Domain-Scope und Zweckbindung sind dokumentiert.

Ablaufdatum gesetzt · required_before_key

Produktive Keys maximal 90 Tage; Test-Keys kürzer.

One-time Display akzeptiert · required_before_key

Raw-Key wird nur einmal angezeigt, nie gespeichert und nie exportiert.

Deny-/Allow-Smoke geplant · required_before_live

401/403/429/Revocation-Fixtures und Request-ID werden vor Go-live geprüft.

Rotationsverantwortung gesetzt · required_before_live

Verantwortlichkeit, Rotationstermin, Revocation-Pfad und Notfallkontakt sind bekannt.

Rate Limits

public_read

cachebar, pro IP begrenzt

operator_read

pro Key und Domain moderat

evidence_read

streng pro Key und Report-Pack

operator_write

sehr streng mit Idempotency

admin

MFA/Vier-Augen, kein Burst

Abuse Response

Anomalie erkennen

Key-Prefix, Scope, Domain-Hash und Request-ID ohne Raw-Key prüfen.

Key pausieren

status=revoked oder rotating setzen; keine Roh-Keys exportieren.

Client informieren

Sanitisierte Fehlermeldung mit Prefix, Zeitraum und Request-IDs senden.

Rotation erzwingen

Neuen Key mit reduzierten Scopes ausstellen und alten Key denied testen.

Nachlauf auditieren

Auditlog auf alte Prefixe, Rate-Limits und Scope-Mismatches prüfen.

Nachlauf

first_successful_request

Genau erwartete Domain/Scope-Kombination, Request-ID vorhanden.

denied_request_ratio

Deny-Anteil plausibel; keine wiederholten 401/403-Schleifen.

rate_limit_events

429 selten; Client beachtet Retry-After und Backoff.

write_idempotency_conflicts

Keine unkontrollierten 409-Wiederholungen.

old_prefix_usage_after_rotation

Alter Prefix erzeugt nur Deny-Audit, keine Allow-Events.

evidence:read operator_read · GET · Risiko hoch

Sanitization, Domain-Claim und Auditlog erforderlich

/nachweise/{domain}/export, /api/report/export

nachweise:write operator_write · POST · Risiko hoch

HMAC, Idempotency-Key und Zielsystem-Dry-Run erforderlich

Nachweispositions-Delivery

dispatch:write operator_write · POST · Risiko hoch

Betreiberfreigabe, Rate-Limit und Stop-Conditions erforderlich

Scan-Dispatch und Alert-Dispatch