Sovereign gateway

Request envelope

Bearer JWT identifies the user; the X-LyDos-* headers identify the device via the Key Sovereignty Layer (KSL). The Ed25519 signature is computed client-side over the nonce + timestamp + path + body hash. Private keys never leave the device.

bash
curl -X POST https://lydos.ailydian.com/api/integrations/my/groq/exec \
  -H "Authorization: Bearer ${JWT}" \
  -H "X-Lyd-Surface: web" \
  -H "X-LyDos-Device: ${DEVICE_ID}" \
  -H "X-LyDos-Signature: ${KSL_ED25519_SIG}" \
  -H "X-LyDos-Nonce: ${NONCE}" \
  -H "X-LyDos-Timestamp: ${UNIX_TS_MS}" \
  -H "Content-Type: application/json" \
  -d '{"action":"health_check"}'

Response envelope

Every success carries the rotation key id (TTL 90 s) plus the KSL mode resolved at the time of the call. KSL mode is driven by the LYDOS_KSL_INTEGRATION_MODE environment variable — operator picks off / warn / enforce.

json
{
  "success": true,
  "integration": "groq",
  "action": "health_check",
  "latency_ms": 142.7,
  "error": null,
  "surface": "web",
  "rotation_request_id": "<24-char hex>",
  "rotation_expires_at": 1747000090,
  "ksl_mode": "off",
  "ksl_verified": false
}

The five layers

• 1. AES-256-GCM per-user vault — core/integrations/credential_vault.py. Raw secrets are encrypted at rest with a per-user-derived key. The decrypted value lives only in the request handler's local stack during the upstream call; it never appears in logs or the response.
• 2. Rotation key (HS256, 90 s TTL) — core/integrations/request_rotator.py. One rotation_request_id is minted per call, recorded in the ASR chain, expires automatically. Replay defence + audit-trail anchor in one primitive.
• 3. LSIA quarantine (50 events / 10 s → 60 s 429) — when the per-user-per-integration sliding window crosses the threshold, subsequent exec attempts return the response below until the window expires. KURAL 22 — LSIA CRITICAL_LOCKDOWN overrides every other engine.
• 4. KSL gate (3 modes) — core/integrations/ksl_integration_gate.py.off ignores X-LyDos-* headers; warn records the verification result but does not block; enforce rejects calls without a valid Ed25519 signature with 401 ksl:bad_signature. KURAL 18 — every critical operation needs a KSL signature.
• 5. ASR hash-chained audit — core/integrations/asr.py. Every exec, rotation mint, and quarantine event lands in the append-only hash chain. KURAL 23 — only user_id_hash = sha256[:16] is recorded; raw user_id, email, IP, and payload never enter the log.

Quarantine response

http
HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{"detail": "integration_quarantined: anomalous request rate detected; this integration is temporarily blocked. Retry after the 60-second quarantine window."}

KSL enforce-mode rejection

http
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"detail": "ksl:bad_signature"}

See also

• Integration catalogue — every shipped slug with its own per-page docs.
• Getting started — developer quickstart with real curl.
• Architecture — how the sovereign engines fit together.