Add killinchu_bridge.py (integrity-stream + cyber quarantine) — staged module, ADDITIVE, NOT auto-wired (Yachay)

killinchu_bridge.py

@@ -0,0 +1,244 @@
+"""
+killinchu_bridge.py — Killinchu side of the Sentra <-> Killinchu cyber bridge.
+
+*** PENDING PATCH — NOT PUSHED TO THE KILLINCHU SPACE ***
+This file lives in sentra_killinchu_bridge/pending_patches/ ONLY. The Killinchu
+Space serve.py / killinchu_expansion.py are owned by the in-flight build agent
+`opus_killinchu_drone_flagship_build_mpus8anv`. To avoid a collision we do NOT
+edit those files. The build agent (or a later coordinated commit) applies this
+module additively with the ONE-LINE registration documented in §APPLY below.
+
+Adds two endpoints (ADDITIVE, mirrors the existing register_expansion pattern):
+  * POST /api/killinchu/v1/integrity-stream
+      Emits a Sentra-compatible szl.integrity.event/v1 for a drone integrity
+      result, writes a Khipu receipt (kind=integrity.event.cross) with
+      flagship_origin + cross_link, and forwards it to the Sentra webhook
+      (/api/sentra/v1/drone-cyber/events/ingest). Honest degrade if Sentra down.
+  * POST /api/killinchu/v1/quarantine
+      Cyber isolation (RTL + link isolation under signed Sentra cert), NEVER
+      kinetic, OWN-FLEET ONLY. Re-checks the 2-person Yuyay gate + Lambda floor
+      (defence in depth behind Sentra's gate). Honors the legal boundary
+      "WE SENSE, WE EVIDENCE" (CFAA / ITAR / Wassenaar).
+
+HARD DISCIPLINE:
+  * ADDITIVE only; reuses the host app's emit_receipt / lambda_aggregate /
+    lambda_floor / signature_placeholder injected via register_killinchu_bridge.
+  * Doctrine v11 LOCKED numbers preserved (13-axis yuyay_v3, floor 0.90).
+  * DSSE signature PLACEHOLDER until Sigstore CI lands. SLSA L1 (honest).
+  * RUWAY is the only ledger writer — we call the injected emit_receipt.
+
+— Yachay, 2026-06-01.
+
+============================================================================
+APPLY (one line for the build agent, inside the existing try/except in serve.py,
+right after the register_expansion(...) call):
+
+    import killinchu_bridge
+    killinchu_bridge.register_killinchu_bridge(
+        app, drones=_DRONES, emit_receipt=_emit_receipt,
+        lambda_aggregate=_lambda_aggregate, lambda_floor=_LAMBDA_FLOOR,
+        doctrine=DOCTRINE, json_body=_json_body,
+        signature_placeholder=SIGNATURE_PLACEHOLDER,
+        sentra_base="https://szlholdings-sentra.hf.space",
+    )
+============================================================================
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import urllib.request
+from datetime import datetime, timezone
+from typing import Callable
+
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+# Tripwire (T11-T20) -> Sentra signature (DSIG-01..10) + class. Mirrors the
+# 16-sig map in SENTRA_DRONE_CYBER_TAB.md / KILLINCHU_INTEGRITY_EVENT_SCHEMA.md.
+TRIPWIRE_TO_SIG = {
+    "T11": ("DSIG-01", "secure-boot-attestation-failure", "tamper"),
+    "T12": ("DSIG-02", "firmware-merkle-mismatch", "tamper"),
+    "T13": ("DSIG-03", "mavlink-anomaly", "intrusion"),
+    "T14": ("DSIG-04", "rf-fingerprint-deviation", "intrusion"),
+    "T15": ("DSIG-05", "accelerometer-imu-spoof", "tamper"),
+    "T16": ("DSIG-06", "gps-spoof", "intrusion"),
+    "T17": ("DSIG-07", "unexpected-ota-attempt", "tamper"),
+    "T18": ("DSIG-08", "geofence-violation", "anomaly"),
+    "T19": ("DSIG-09", "mission-deviation", "anomaly"),
+    "T20": ("DSIG-10", "unauthorized-mavlink-command", "intrusion"),
+}
+OWN_FLEET_SIDES = ("allied", "dual-use", "counter-uas")
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _sha(obj) -> str:
+    return hashlib.sha256(
+        json.dumps(obj, sort_keys=True, separators=(",", ":")).encode()
+    ).hexdigest()
+
+
+def register_killinchu_bridge(app, *, drones: list, emit_receipt: Callable,
+                              lambda_aggregate: Callable, lambda_floor: float,
+                              doctrine: str, json_body: Callable,
+                              signature_placeholder: str,
+                              sentra_base: str = "https://szlholdings-sentra.hf.space") -> None:
+    """Wire the two bridge endpoints onto the existing FastAPI app (ADDITIVE)."""
+
+    def _drone_by_id(did: str):
+        for d in drones:
+            if d.get("id") == did:
+                return d
+        return None
+
+    def _build_event(drone: dict, tripwire_id: str, verdict: str,
+                     lam: float, evidence: dict, prev_hash: str) -> dict:
+        sig_id, sig_name, klass = TRIPWIRE_TO_SIG.get(
+            tripwire_id, ("", "", "anomaly"))
+        body = {
+            "schema": "szl.integrity.event/v1",
+            "event_id": f"evt_{_now()}_{drone.get('id')}_{tripwire_id}",
+            "emitted_at": _now(),
+            "flagship_origin": "killinchu",
+            "drone": {
+                "id": drone.get("id"), "model": drone.get("model", ""),
+                "fleet_side": drone.get("side", "allied"),
+            },
+            "tripwire": {"id": tripwire_id, "name": sig_name, "hukkla": tripwire_id},
+            "verdict": verdict,
+            "severity": "high" if verdict == "TAMPER-SUSPECTED" else "info",
+            "sentra_signature": sig_id,
+            "evidence": evidence,
+            "lambda": {
+                "value": round(lam, 6), "floor": lambda_floor,
+                "below_floor": lam < lambda_floor,
+            },
+            "khipu": {"prev_hash": prev_hash},
+            "signature": {
+                "mode": "dsse", "value": signature_placeholder,
+                "slsa_level": "L1 (honest)",
+            },
+        }
+        body["khipu"]["this_hash"] = "sha256:" + _sha(
+            {"e": {k: v for k, v in body.items() if k != "signature"}, "p": prev_hash})
+        return body
+
+    def _forward_to_sentra(event: dict) -> dict:
+        """Best-effort POST to the Sentra webhook. Honest degrade on failure."""
+        url = sentra_base + "/api/sentra/v1/drone-cyber/events/ingest"
+        try:
+            data = json.dumps(event).encode()
+            req = urllib.request.Request(
+                url, data=data, headers={"content-type": "application/json"})
+            with urllib.request.urlopen(req, timeout=8.0) as r:
+                return {"forwarded": True, "sentra": json.loads(r.read().decode())}
+        except Exception as e:
+            return {"forwarded": False, "error": str(e),
+                    "note": "Sentra unreachable — event still receipted locally (honest degrade)."}
+
+    # ---- Integrity stream webhook (binding b) ----
+    @app.api_route("/api/killinchu/v1/integrity-stream", methods=["POST"])
+    async def integrity_stream(request: Request):
+        """Emit Sentra-compatible szl.integrity.event/v1 for a drone integrity
+        result; write a cross Khipu receipt; forward to Sentra."""
+        body = await json_body(request)
+        did = body.get("drone_id", "")
+        drone = _drone_by_id(did)
+        if drone is None:
+            return JSONResponse({"ok": False, "error": "drone not in fleet",
+                                 "drone_id": did, "doctrine": doctrine}, status_code=404)
+        fired = body.get("fired") or []
+        verdict = "TAMPER-SUSPECTED" if fired else "ATTESTED-CLEAN"
+        axis = body.get("axis_scores") or [0.93] * 13
+        lam = lambda_aggregate(axis)
+        events = []
+        for tid in (fired or ["T11"][:0]):  # one event per fired tripwire
+            evt = _build_event(
+                drone, tid, verdict, lam,
+                evidence={"detector": f"szl-sentra-detect/{TRIPWIRE_TO_SIG.get(tid,('','',''))[1]}",
+                          "raw_ref": f"twin://{did}/tamperFlags/{tid}"},
+                prev_hash="")
+            rcpt = emit_receipt("integrity.event.cross", {
+                "flagship_origin": "killinchu",
+                "cross_link": {"to_flagship": "sentra", "event_id": evt["event_id"]},
+                "event": evt,
+            })
+            evt["khipu"]["receipt_id"] = rcpt.get("digest") or rcpt.get("index")
+            fwd = _forward_to_sentra(evt)
+            events.append({"event": evt, "forward": fwd})
+        if not fired:
+            # clean scan still gets a receipt (honest, no event forwarded)
+            emit_receipt("integrity.event.cross", {
+                "flagship_origin": "killinchu", "drone_id": did,
+                "verdict": verdict, "fired": []})
+        return JSONResponse({
+            "ok": True, "drone_id": did, "verdict": verdict,
+            "emitted": len(events), "events": events,
+            "lambda": round(lam, 6), "lambda_floor": lambda_floor,
+            "schema": "szl.integrity.event/v1",
+            "signature": signature_placeholder, "slsa_level": "L1 (honest)",
+            "doctrine": doctrine,
+            "honesty": ("Events forwarded best-effort to Sentra; receipted locally regardless. "
+                        "Cross-Space durable broker NOT wired — correlation by event_id."),
+        })
+
+    # ---- Cyber quarantine (called by Sentra; defence-in-depth re-check) ----
+    @app.api_route("/api/killinchu/v1/quarantine", methods=["POST"])
+    async def quarantine(request: Request):
+        """Cyber isolation (RTL + link isolation), NEVER kinetic, own-fleet only.
+        Re-checks 2-person Yuyay + Lambda floor behind Sentra's gate."""
+        body = await json_body(request)
+        did = body.get("drone_id", "")
+        approvers = sorted(set(a for a in (body.get("approvers") or []) if a))
+        drone = _drone_by_id(did)
+        # Gate: own-fleet only
+        if drone is None:
+            return JSONResponse({"ok": False, "decision": "REFUSED",
+                "reason": "drone not in fleet", "drone_id": did,
+                "kinetic": False, "doctrine": doctrine}, status_code=403)
+        if drone.get("side") not in OWN_FLEET_SIDES:
+            return JSONResponse({"ok": False, "decision": "REFUSED",
+                "reason": ("own-fleet only; cyber isolation never applied to third-party "
+                           "(WE SENSE, WE EVIDENCE — CFAA/ITAR/Wassenaar)"),
+                "drone_id": did, "side": drone.get("side"),
+                "kinetic": False, "doctrine": doctrine}, status_code=403)
+        # Gate: 2-person
+        if len(approvers) < 2:
+            return JSONResponse({"ok": False, "decision": "BLOCKED",
+                "reason": "2-person Yuyay gate requires >=2 distinct approvers",
+                "kinetic": False, "doctrine": doctrine}, status_code=412)
+        # Gate: Lambda floor
+        axis = body.get("axis_scores") or [0.93] * 13
+        lam = lambda_aggregate(axis)
+        if lam < lambda_floor:
+            rcpt = emit_receipt("quarantine.halted", {
+                "drone_id": did, "lambda": round(lam, 6), "reason": "below Λ floor"})
+            return JSONResponse({"ok": False, "decision": "HALT",
+                "reason": f"Λ={lam:.4f} < floor {lambda_floor}", "drone_id": did,
+                "kinetic": False, "khipu_digest": rcpt.get("digest"),
+                "signature": signature_placeholder, "doctrine": doctrine}, status_code=409)
+        # Cleared — cyber isolation
+        cert_sha = _sha({"drone": did, "approvers": approvers, "ts": _now(),
+                         "cert": body.get("sentra_cert_sha256", "")})
+        rcpt = emit_receipt("quarantine.executed", {
+            "flagship_origin": "killinchu",
+            "cross_link": {"to_flagship": "sentra", "drone_id": did},
+            "drone_id": did, "approvers": approvers, "drone_state": "RTL",
+            "isolation": "command+telemetry links isolated under signed Sentra cert",
+            "lambda": round(lam, 6), "kinetic": False})
+        return JSONResponse({
+            "ok": True, "decision": "QUARANTINED", "drone_id": did,
+            "drone_state": "RTL",
+            "isolation": "command+telemetry links isolated under signed Sentra cert",
+            "kinetic": False, "approvers": approvers,
+            "killinchu_cert_sha256": cert_sha,
+            "lambda": round(lam, 6), "lambda_floor": lambda_floor,
+            "khipu_digest": rcpt.get("digest"),
+            "signature": signature_placeholder, "slsa_level": "L1 (honest)",
+            "doctrine": doctrine,
+            "honesty": ("Cyber isolation only (RTL + link isolation), NOT kinetic, own-fleet only. "
+                        "Defence-in-depth re-check behind Sentra's 2-person Yuyay gate. DSSE PLACEHOLDER."),
+        })

killinchu_bridge_patch_meta/README.md

@@ -0,0 +1,50 @@
+# pending_patches/ — collision-safe, NOT pushed to HF
+
+**Why this exists:** the Killinchu Space (`SZLHOLDINGS/killinchu`) `serve.py` and
+`killinchu_expansion.py` are owned by the in-flight build agent
+`opus_killinchu_drone_flagship_build_mpus8anv`. To honor the HARD RULE *"collision risk → write
+to pending_patches/, DO NOT push that one"*, the Killinchu-side bridge module is staged here and
+was **NOT** pushed to the Space.
+
+## File
+
+- `killinchu_bridge.py` — adds `POST /api/killinchu/v1/integrity-stream` (binding b webhook,
+  emits Sentra-compatible `szl.integrity.event/v1` + cross Khipu receipt + forwards to Sentra)
+  and `POST /api/killinchu/v1/quarantine` (cyber isolation, NOT kinetic, own-fleet only,
+  2-person Yuyay + Λ floor re-check). Validated: parses + registers both routes against a stub
+  app.
+
+## How the build agent applies it (one-line, additive)
+
+Add the file to the Killinchu Space repo and, inside the existing `try/except` in `serve.py`
+right after the `killinchu_expansion.register_expansion(...)` call, add:
+
+```python
+import killinchu_bridge
+killinchu_bridge.register_killinchu_bridge(
+    app, drones=_DRONES, emit_receipt=_emit_receipt,
+    lambda_aggregate=_lambda_aggregate, lambda_floor=_LAMBDA_FLOOR,
+    doctrine=DOCTRINE, json_body=_json_body,
+    signature_placeholder=SIGNATURE_PLACEHOLDER,
+    sentra_base="https://szlholdings-sentra.hf.space",
+)
+```
+
+The injected dependencies (`_DRONES`, `_emit_receipt`, `_lambda_aggregate`, `_LAMBDA_FLOOR`,
+`DOCTRINE`, `_json_body`, `SIGNATURE_PLACEHOLDER`) are the same ones already passed to
+`register_expansion` — verified present in the live `serve.py`. No existing endpoint, receipt
+schema, or Doctrine v11 LOCKED number is changed. ADDITIVE only.
+
+## Bridge status while pending
+
+The **Sentra side is LIVE and self-sufficient**: `/drone-cyber` and
+`/api/sentra/v1/drone-cyber/*` pull the Killinchu fleet directly from the existing live Killinchu
+endpoints (`/drones/database`, `/drones/{id}/twin`, `/drones/{id}/integrity`,
+`/receipt/ledger`). The unified SOC pane is demoable **today** without this Killinchu patch.
+
+What this patch *adds* once applied: Killinchu **push** of integrity events to Sentra (vs the
+current Sentra **pull**), and a first-class `/v1/quarantine` defence-in-depth re-check endpoint.
+Until then, Sentra's quarantine endpoint runs the full gate itself (own-fleet check via live
+`/drones/database`, 2-person, cross-flagship Λ) and records the cyber-isolation receipt.
+
+— Yachay, 2026-06-01. Collision-safe. NOT pushed. ADDITIVE when applied. v11 LOCKED preserved.