deploy(hf): sync szl-holdings/killinchu@main derived COPY set

Reusable Dockerfile-COPY-derived deploy from szl-holdings/killinchu main.
Files: 882 Pruned: 0
Derived from Dockerfile COPY sources (NO hand-maintained allowlist).

Signed-off-by: SZL Holdings <noreply@szlholdings.ai>
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

killinchu_backend.py

@@ -518,7 +518,7 @@ def _store() -> _Store:
 # ---------------------------------------------------------------------------
 def _envelope(status: str, data: Dict[str, Any], citations: List[Dict[str, str]]) -> Dict[str, Any]:
     body = {
-        "status": status,           # ok | live | cached | degraded | error
+        "status": status,           # ok | live | cached | degraded | error | failed
         "doctrine": DOCTRINE,
         "service": "killinchu",
         "citations": citations,
@@ -768,6 +768,20 @@ def _evaluate_watchlists(st: _Store, snap_id: int, event_id: int, count: int,
 # ---------------------------------------------------------------------------
 _SCHED_STARTED = False
 _sched_lock = threading.Lock()  # non-reentrant: guards against overlapping runs
+_STORAGE_FAILURE_CLASS = "storage_unavailable"
+_STORAGE_FAILURE_PATTERNS = (
+    "database or disk is full",
+    "disk i/o error",
+    "no space left on device",
+    "disk quota exceeded",
+    "attempt to write a readonly database",
+    "read-only file system",
+    "enospc",
+)
+_STORAGE_REMEDIATION = (
+    "Free writable storage for the Killinchu durable store, then restart the "
+    "service. Scheduled and manual crawls remain fail-closed until restart."
+)
 _sched_state: Dict[str, Any] = {
     "enabled": None,
     "interval_seconds": None,
@@ -775,13 +789,60 @@ _sched_state: Dict[str, Any] = {
     "running": False,
     "runs": 0,
     "last_run_at": None,
+    "last_success_at": None,
     "last_status": None,
     "last_error": None,
     "consecutive_failures": 0,
     "next_run_at": None,
+    "circuit_open": False,
+    "failure_class": None,
+    "paused_at": None,
+    "operator_action": None,
 }
 
 
+def _scheduler_failure_class(error: Any) -> Optional[str]:
+    """Classify only known non-retriable local-storage failures.
+
+    Upstream timeouts, rate limits, and malformed responses remain ordinary
+    degraded runs with exponential backoff. Storage failures are different:
+    retrying the same write forever cannot recover the disk and can flood logs.
+    """
+    if isinstance(error, OSError) and getattr(error, "errno", None) in (28, 30, 122):
+        return _STORAGE_FAILURE_CLASS
+    normalized = str(error or "").casefold()
+    if any(pattern in normalized for pattern in _STORAGE_FAILURE_PATTERNS):
+        return _STORAGE_FAILURE_CLASS
+    return None
+
+
+def _open_scheduler_circuit(error: Any, paused_at: Optional[str] = None) -> None:
+    """Halt crawl writes after a non-retriable storage failure."""
+    _sched_state.update({
+        "last_status": "error",
+        "last_error": str(error),
+        "next_run_at": None,
+        "circuit_open": True,
+        "failure_class": _STORAGE_FAILURE_CLASS,
+        "paused_at": paused_at or _now_iso(),
+        "operator_action": _STORAGE_REMEDIATION,
+    })
+
+
+def _scheduler_health(cfg: Dict[str, Any]) -> str:
+    """Return the public scheduler health without equating wiring with health."""
+    if _sched_state["circuit_open"]:
+        return "failed"
+    if not cfg["enabled"] or not _SCHED_STARTED:
+        return "disabled"
+    last_status = str(_sched_state.get("last_status") or "").lower()
+    if last_status == "live":
+        return "ok"
+    if last_status in ("cached", "degraded", "error", "skipped"):
+        return "degraded"
+    return "starting"
+
+
 def _env_bool(name: str, default: bool) -> bool:
     v = os.environ.get(name)
     if v is None or not v.strip():
@@ -815,9 +876,11 @@ def run_crawl_guarded(mode: str = "auto") -> Optional[Dict[str, Any]]:
     """Run one crawl unless one is already in flight (no pile-up).
 
     Returns the run_crawl() envelope, or None if a run was already in progress
-    and this call was skipped. The lock is non-blocking so a slow run never
-    causes scheduled cycles to queue up.
+    and this call was skipped, or if the storage circuit is open. The lock is
+    non-blocking so a slow run never causes scheduled cycles to queue up.
     """
+    if _sched_state["circuit_open"]:
+        return None
     if not _sched_lock.acquire(blocking=False):
         return None
     try:
@@ -860,15 +923,37 @@ async def _scheduler_loop() -> None:
                 if status == "live":
                     _sched_state["consecutive_failures"] = 0
                     _sched_state["last_error"] = None
+                    _sched_state["last_success_at"] = started
+                    _sched_state["failure_class"] = None
+                    _sched_state["paused_at"] = None
+                    _sched_state["operator_action"] = None
                 else:
                     # 'cached'/'degraded' = the scrape did not get fresh data.
                     _sched_state["consecutive_failures"] += 1
-                    _sched_state["last_error"] = (res.get("data") or {}).get("error")
+                    error = res.get("error")
+                    _sched_state["last_error"] = error
+                    if _scheduler_failure_class(error) == _STORAGE_FAILURE_CLASS:
+                        _open_scheduler_circuit(error, paused_at=started)
+                        print(
+                            "[killinchu-backend] auto-crawl halted: "
+                            f"{_STORAGE_FAILURE_CLASS} ({error})",
+                            file=sys.stderr,
+                        )
+                        return
         except Exception as e:  # never let the loop die
             _sched_state["consecutive_failures"] += 1
+            _sched_state["last_run_at"] = started
             _sched_state["last_status"] = "error"
             _sched_state["last_error"] = repr(e)
             print(f"[killinchu-backend] auto-crawl cycle error: {e!r}", file=sys.stderr)
+            if _scheduler_failure_class(e) == _STORAGE_FAILURE_CLASS:
+                _open_scheduler_circuit(e, paused_at=started)
+                print(
+                    "[killinchu-backend] auto-crawl halted fail-closed; "
+                    f"operator action: {_STORAGE_REMEDIATION}",
+                    file=sys.stderr,
+                )
+                return
         finally:
             _sched_state["running"] = False
 
@@ -944,6 +1029,14 @@ def register(app, ns: str = "killinchu") -> str:
         s = _store()
         if not s.ok():
             return JSONResponse(_envelope("degraded", {"error": "no durable backend"}, _adsb_citation()), status_code=200)
+        if _sched_state["circuit_open"]:
+            return JSONResponse(_envelope("failed", {
+                "health": "failed",
+                "error": _sched_state["last_error"],
+                "failure_class": _sched_state["failure_class"],
+                "circuit_open": True,
+                "operator_action": _sched_state["operator_action"],
+            }, _adsb_citation()), status_code=503)
         rows = s.query("SELECT id, fetched_at, record_count FROM snapshots ORDER BY id DESC LIMIT 1")
         if rows:
             try:
@@ -967,13 +1060,28 @@ def register(app, ns: str = "killinchu") -> str:
     # -- crawl/run (manual) ------------------------------------------------
     async def crawl_run(request: Request) -> JSONResponse:
         """POST /crawl/run — trigger a manual crawl and return its result envelope."""
+        if _sched_state["circuit_open"]:
+            return JSONResponse(_envelope("failed", {
+                "health": "failed",
+                "error": _sched_state["last_error"],
+                "failure_class": _sched_state["failure_class"],
+                "circuit_open": True,
+                "operator_action": _sched_state["operator_action"],
+            }, _adsb_citation()), status_code=503)
         return JSONResponse(run_crawl(mode="crawl"))
 
     # -- crawl/status (auto-crawl scheduler health) ------------------------
     async def crawl_status(request: Request) -> JSONResponse:
         """GET /crawl/status — report the auto-crawl scheduler configuration + health."""
         cfg = scheduler_config()
+        health = _scheduler_health(cfg)
+        last_status = str(_sched_state.get("last_status") or "").lower()
+        freshness = "fresh" if last_status == "live" else (
+            "stale" if _sched_state.get("last_success_at") else "unverified"
+        )
         data = {
+            "health": health,
+            "freshness": freshness,
             "config": {
                 "enabled": cfg["enabled"],
                 "interval_seconds": cfg["interval"],
@@ -983,9 +1091,12 @@ def register(app, ns: str = "killinchu") -> str:
             },
             "scheduler": dict(_sched_state),
             "wired": _SCHED_STARTED,
+            "circuit_open": _sched_state["circuit_open"],
+            "failure_class": _sched_state["failure_class"],
+            "paused_at": _sched_state["paused_at"],
+            "operator_action": _sched_state["operator_action"],
         }
-        status = "ok" if (cfg["enabled"] and _SCHED_STARTED) else "disabled"
-        return JSONResponse(_envelope(status, data, []))
+        return JSONResponse(_envelope(health, data, []))
 
     # -- timeline ----------------------------------------------------------
     async def timeline(request: Request) -> JSONResponse:

killinchu_cot_interop.py

@@ -53,11 +53,15 @@ from __future__ import annotations
 
 import datetime as _dt
 import json
+import logging
 import os
 import re
 from typing import Any, Iterable
 from xml.etree import ElementTree as ET
 
+from defusedxml import ElementTree as DefusedET
+from defusedxml.common import DefusedXmlException
+
 try:
     from fastapi import APIRouter, Request
     from fastapi.responses import JSONResponse, Response
@@ -69,11 +73,26 @@ except Exception:  # pragma: no cover
 
 _HERE = os.path.dirname(os.path.abspath(__file__))
 _VESSELS_PATH = os.path.join(_HERE, "fleet_vessels_data.json")
+_LOGGER = logging.getLogger(__name__)
 
 COT_VERSION = "2.0"
 # CoT default multicast SA group (ROADMAP target only — never opened here).
 COT_DEFAULT_MULTICAST = "239.2.3.1:6969"
 
+# CoT events are compact tactical messages. Hard limits bound parser memory and
+# post-parse traversal even after DTD/entity expansion has been disabled.
+MAX_COT_XML_BYTES = 256 * 1024
+MAX_COT_XML_ELEMENTS = 2048
+MAX_COT_XML_DEPTH = 24
+MAX_COT_XML_TEXT_CHARS = 128 * 1024
+MAX_COT_ATTRIBUTES_PER_ELEMENT = 64
+
+# Client responses deliberately expose only stable categories. Detailed
+# exception context remains in server logs and never crosses the HTTP boundary.
+_INGEST_ERROR_TOO_LARGE = "CoT XML payload too large"
+_INGEST_ERROR_ENCODING = "CoT XML must be UTF-8"
+_INGEST_ERROR_INVALID = "invalid CoT XML"
+
 HONESTY_LABEL = (
     "Real CoT 2.0 XML export + schema-shape validation + ingest, computed from "
     "killinchu sample tracks. No live TAK-server / UDP multicast in this build "
@@ -93,6 +112,71 @@ COT_SOURCES = [
 ]
 
 
+class CotPayloadTooLarge(ValueError):
+    """Raised before parsing when an inbound CoT body exceeds the byte limit."""
+
+
+def _parse_untrusted_xml(xml: str) -> ET.Element:
+    """Parse untrusted CoT XML with entity expansion and DTDs disabled.
+
+    The byte limit is checked before parsing; structural limits are then
+    enforced iteratively to avoid recursive traversal of adversarial trees.
+    """
+    if not isinstance(xml, str):
+        raise ValueError("CoT XML must be text")
+    try:
+        encoded = xml.encode("utf-8")
+    except UnicodeEncodeError as exc:
+        raise ValueError(f"invalid CoT XML encoding: {exc}") from exc
+    if len(encoded) > MAX_COT_XML_BYTES:
+        raise CotPayloadTooLarge(f"CoT XML exceeds {MAX_COT_XML_BYTES} byte limit")
+
+    try:
+        root = DefusedET.fromstring(
+            xml,
+            forbid_dtd=True,
+            forbid_entities=True,
+            forbid_external=True,
+        )
+    except (DefusedXmlException, ET.ParseError, ValueError) as exc:
+        raise ValueError(f"XML parse error: {exc}") from exc
+
+    element_count = 0
+    text_chars = 0
+    stack: list[tuple[ET.Element, int]] = [(root, 1)]
+    while stack:
+        element, depth = stack.pop()
+        element_count += 1
+        if element_count > MAX_COT_XML_ELEMENTS:
+            raise ValueError(f"CoT XML exceeds {MAX_COT_XML_ELEMENTS} element limit")
+        if depth > MAX_COT_XML_DEPTH:
+            raise ValueError(f"CoT XML exceeds {MAX_COT_XML_DEPTH} level depth limit")
+        if len(element.attrib) > MAX_COT_ATTRIBUTES_PER_ELEMENT:
+            raise ValueError(
+                "CoT XML element exceeds "
+                f"{MAX_COT_ATTRIBUTES_PER_ELEMENT} attribute limit"
+            )
+        text_chars += len(element.text or "") + len(element.tail or "")
+        if text_chars > MAX_COT_XML_TEXT_CHARS:
+            raise ValueError(
+                f"CoT XML exceeds {MAX_COT_XML_TEXT_CHARS} text-character limit"
+            )
+        stack.extend((child, depth + 1) for child in list(element))
+    return root
+
+
+async def _read_limited_request_body(request: Request) -> bytes:
+    """Read a streaming request body without buffering past the CoT limit."""
+    chunks: list[bytes] = []
+    total = 0
+    async for chunk in request.stream():
+        total += len(chunk)
+        if total > MAX_COT_XML_BYTES:
+            raise CotPayloadTooLarge(f"CoT XML exceeds {MAX_COT_XML_BYTES} byte limit")
+        chunks.append(chunk)
+    return b"".join(chunks)
+
+
 # ---------------------------------------------------------------------------
 # CoT type-atom resolution (MIL-STD-2525 / CoT hierarchy).
 #   a            = atoms (vs b=bits, t=tasking, etc.)
@@ -433,9 +517,9 @@ def validate_xml_string(xml: str) -> tuple[bool, list[str]]:
     """Validate a CoT XML string. Handles both a single <event> and an
     <events> batch wrapper. Returns (ok, errors)."""
     try:
-        root = ET.fromstring(xml)
-    except ET.ParseError as exc:
-        return (False, [f"XML parse error: {exc}"])
+        root = _parse_untrusted_xml(xml)
+    except ValueError as exc:
+        return (False, [str(exc)])
     if root.tag == "events":
         all_errs: list[str] = []
         children = root.findall("event")
@@ -457,8 +541,8 @@ def cot_xml_to_track(xml: str) -> dict[str, Any]:
 
     Raises ValueError if the XML is not a valid CoT event."""
     try:
-        root = ET.fromstring(xml)
-    except ET.ParseError as exc:
+        root = _parse_untrusted_xml(xml)
+    except ValueError as exc:
         raise ValueError(f"invalid CoT XML: {exc}") from exc
     if root.tag != "event":
         raise ValueError(f"expected root <event>, got <{root.tag}>")
@@ -623,11 +707,30 @@ def register(app) -> dict[str, Any]:
 
     @router.post(f"{base}/ingest")
     async def _ingest(request: Request) -> JSONResponse:
-        raw = await request.body()
         try:
+            raw = await _read_limited_request_body(request)
             track = cot_xml_to_track(raw.decode("utf-8"))
-        except ValueError as exc:
-            return JSONResponse({"ok": False, "error": str(exc)}, status_code=400)
+        except CotPayloadTooLarge:
+            _LOGGER.info(
+                "Rejected CoT ingest", extra={"cot_rejection": "payload_too_large"}
+            )
+            return JSONResponse(
+                {"ok": False, "error": _INGEST_ERROR_TOO_LARGE}, status_code=413
+            )
+        except UnicodeDecodeError:
+            _LOGGER.info(
+                "Rejected CoT ingest", extra={"cot_rejection": "invalid_encoding"}
+            )
+            return JSONResponse(
+                {"ok": False, "error": _INGEST_ERROR_ENCODING}, status_code=400
+            )
+        except ValueError:
+            _LOGGER.info(
+                "Rejected CoT ingest", extra={"cot_rejection": "invalid_xml"}
+            )
+            return JSONResponse(
+                {"ok": False, "error": _INGEST_ERROR_INVALID}, status_code=400
+            )
         return JSONResponse({"ok": True, "track": track, "honesty": HONESTY_LABEL})
     registered.append(f"{base}/ingest")
 

killinchu_elite_console.py

@@ -2455,33 +2455,40 @@ async function crawlStatusLoad(id){
     var j=await getJSON('/api/killinchu/crawl/status');
     var cfg=(j&&j.config)||{}, sch=(j&&j.scheduler)||{}, wired=!!(j&&j.wired);
     var enabled=(cfg.enabled!==false)&&wired;
+    var health=String((j&&j.health)||(j&&j.status)||'unverified').toLowerCase();
+    var halted=!!(j&&j.circuit_open)||health==='failed';
     var last=String(sch.last_status||'').toLowerCase();
     var outcome, oc;
-    if(!sch.last_run_at){ outcome='NO RUN YET'; oc='#c9a05f'; }
+    if(halted){ outcome='HALTED'; oc='#ff7b7b'; }
+    else if(!sch.last_run_at){ outcome='NO RUN YET'; oc='#c9a05f'; }
     else if(last==='live'){ outcome='OK'; oc='#5fb3a3'; }
     else if(last==='error'){ outcome='ERROR'; oc='#ff7b7b'; }
     else if(last==='skipped'){ outcome='SKIPPED'; oc='#c9a05f'; }
     else { outcome='DEGRADED'; oc='#f5b301'; }   // cached / degraded — not fresh data
-    var schTxt=enabled?'ENABLED':(wired?'DISABLED':'NOT WIRED');
-    var schC=enabled?'#5fb3a3':'#ff7b7b';
+    var schTxt=halted?'CIRCUIT OPEN':(enabled?'ENABLED':(wired?'DISABLED':'NOT WIRED'));
+    var schC=(halted||!enabled)?'#ff7b7b':'#5fb3a3';
     var cf=sch.consecutive_failures||0;
-    var boTxt=cf>0?('backing off \u00b7 '+cf+' consecutive miss'+(cf===1?'':'es')):'nominal';
-    var boC=cf>0?'#f5b301':'var(--dim)';
+    var boTxt=halted?'fail-closed \u00b7 no retries':(cf>0?('backing off \u00b7 '+cf+' consecutive miss'+(cf===1?'':'es')):'nominal');
+    var boC=halted?'#ff7b7b':(cf>0?'#f5b301':'var(--dim)');
     var ivl=cfg.interval_seconds!=null?(cfg.interval_seconds+'s'):'\u2014';
+    var freshness=String((j&&j.freshness)||'unverified').toUpperCase();
+    var title='Intel feed \u00b7 '+(halted?'HALTED':freshness);
     var cell=function(label,val,color){ return '<div class="kpi" style="padding:.5rem .7rem"><div class="k">'+esc(label)+'</div><div class="v" style="font-size:1rem;color:'+(color||'var(--cream)')+'">'+val+'</div></div>'; };
-    var note=((outcome==='DEGRADED'||outcome==='ERROR')&&sch.last_error)
+    var remediation=halted&&j.operator_action
+      ? '<div class="row mono" style="font-size:11px;color:#ff7b7b;margin-top:.5rem;word-break:break-word">operator action: '+esc(String(j.operator_action))+'</div>' : '';
+    var note=((outcome==='DEGRADED'||outcome==='ERROR'||outcome==='HALTED')&&sch.last_error)
       ? '<div class="row mono" style="font-size:11px;color:#f5b301;margin-top:.5rem;word-break:break-word">last issue: '+esc(String(sch.last_error))+'</div>'
       : (outcome==='SKIPPED' ? '<div class="row mono dim" style="font-size:11px;margin-top:.5rem">a run was still in progress \u2014 this cycle was skipped to avoid pile-up</div>' : '');
     box.innerHTML=
-      '<div class="card-h"><span class="card-t">&#8635; Live intel feed \u2014 auto-refresh</span><span class="card-ep">GET /api/killinchu/crawl/status \u00b7 adsb.lol military ADS-B</span></div>'+
+      '<div class="card-h"><span class="card-t">&#8635; '+esc(title)+'</span><span class="card-ep">GET /api/killinchu/crawl/status \u00b7 adsb.lol military ADS-B</span></div>'+
       '<div class="kpis" style="grid-template-columns:repeat(auto-fit,minmax(118px,1fr));gap:.5rem;margin:0">'+
         cell('Scheduler',schTxt,schC)+
         cell('Last run',_csRel(sch.last_run_at,false),'var(--cream)')+
         cell('Outcome',outcome,oc)+
-        cell('Next run',enabled?_csRel(sch.next_run_at,true):'\u2014','var(--cream)')+
+        cell('Next run',(enabled&&!halted)?_csRel(sch.next_run_at,true):'\u2014','var(--cream)')+
         cell('Backoff',boTxt,boC)+
         cell('Interval',ivl,'var(--dim)')+
-      '</div>'+note;
+      '</div>'+note+remediation;
   }catch(e){ box.innerHTML='<div class="row mono" style="color:#ff7b7b">&#8635; auto-refresh status unavailable: '+esc(e&&e.message||e)+'</div>'; }
 }
 window.crawlStatusBanner=crawlStatusBanner; window.crawlStatusLoad=crawlStatusLoad;

serve.py

@@ -42,32 +42,14 @@ from starlette.middleware.cors import CORSMiddleware
 
 import killinchu_protocols as kp
 from killinchu_receipt_export import build_receipt_export
+from szl_safe_static import RootedStaticFiles
 
 _APP_ROOT = Path(os.environ.get("KILLINCHU_ROOT", "/app"))
 STATIC_DIR = _APP_ROOT / "static"
 ASSETS_DIR = STATIC_DIR / "assets"
 INDEX_HTML = STATIC_DIR / "index.html"
 DRONES_DB_PATH = _APP_ROOT / "drones_db.json"
-
-
-def _safe_join_under(base: Path, user_rel: str) -> Path | None:
-    """Resolve `user_rel` under `base` and return it only if it stays inside.
-
-    Root-cause path-injection guard for user-controlled relative paths reaching
-    a filesystem read. We fully resolve with os.path.realpath (following
-    symlinks) and require the result to be contained within the canonical base
-    directory. Anything that escapes (../, absolute, symlink) returns None and
-    the caller serves the SPA/404 fallback. Allowlist-on-resolved-location,
-    not a substring denylist.
-    """
-    try:
-        base_real = os.path.realpath(base)
-        cand_real = os.path.realpath(os.path.join(base_real, user_rel))
-        if cand_real == base_real or cand_real.startswith(base_real + os.sep):
-            return Path(cand_real)
-        return None
-    except Exception:
-        return None
+_SPA_FILES = RootedStaticFiles(STATIC_DIR)
 
 
 def _wired_ok(status) -> bool:
@@ -1239,18 +1221,18 @@ try:
     _F1_SHARED_DIR = _F1_Path("/app/static/shared")
     _F1_JS_CT = "application/javascript; charset=utf-8"
     _F1_SHARED_ALLOW = {
-        "szl_label_engine.js": _F1_JS_CT,
-        "szl_receipt_cosign.js": _F1_JS_CT,
-        "szl_codename_sanitizer.js": _F1_JS_CT,
-        "szl_holo3d.js": _F1_JS_CT,
+        "szl_label_engine.js": (_F1_SHARED_DIR / "szl_label_engine.js", _F1_JS_CT),
+        "szl_receipt_cosign.js": (_F1_SHARED_DIR / "szl_receipt_cosign.js", _F1_JS_CT),
+        "szl_codename_sanitizer.js": (_F1_SHARED_DIR / "szl_codename_sanitizer.js", _F1_JS_CT),
+        "szl_holo3d.js": (_F1_SHARED_DIR / "szl_holo3d.js", _F1_JS_CT),
     }
 
     @app.get("/static/shared/{fname}")
     async def _f1_shared_module(fname: str):
-        ct = _F1_SHARED_ALLOW.get(fname)
-        if ct is None:
+        asset = _F1_SHARED_ALLOW.get(fname)
+        if asset is None:
             return JSONResponse({"error": "shared module not allowlisted", "file": fname}, status_code=404)
-        f = (_F1_SHARED_DIR / fname)
+        f, ct = asset
         if not f.is_file():
             return JSONResponse({"error": "shared module missing on disk", "file": fname}, status_code=404)
         return Response(content=f.read_bytes(), media_type=ct,
@@ -3430,16 +3412,22 @@ try:
     from starlette.responses import Response as _OPW_KC_SResp
     _OPW_KC_VENDOR = Path("/app/static-vendor")
     _OPW_KC_FILES = {
-        "a11oy-operator-widget.js": "application/javascript; charset=utf-8",
-        "a11oy-operator-widget.css": "text/css; charset=utf-8",
+        "a11oy-operator-widget.js": (
+            _OPW_KC_VENDOR / "a11oy-operator-widget.js",
+            "application/javascript; charset=utf-8",
+        ),
+        "a11oy-operator-widget.css": (
+            _OPW_KC_VENDOR / "a11oy-operator-widget.css",
+            "text/css; charset=utf-8",
+        ),
     }
 
     @app.get("/vendor/{fname}")
     async def _opw_kc_vendor(fname: str):
-        ct = _OPW_KC_FILES.get(fname)
-        if ct is None:
+        asset = _OPW_KC_FILES.get(fname)
+        if asset is None:
             return JSONResponse({"error": "vendor asset not allowlisted", "file": fname}, status_code=404)
-        f = _OPW_KC_VENDOR / fname
+        f, ct = asset
         if not f.is_file():
             return JSONResponse({"error": "vendor asset missing on disk", "file": fname}, status_code=404)
         return _OPW_KC_Resp(content=f.read_bytes(), media_type=ct,
@@ -3456,9 +3444,12 @@ try:
             _wp = request.url.path
             if _wp in ("/vendor/a11oy-operator-widget.js", "/vendor/a11oy-operator-widget.css"):
                 _fn = _wp.rsplit("/", 1)[-1]
-                _ct = _OPW_KC_FILES.get(_fn)
-                _f = _OPW_KC_VENDOR / _fn
-                if _ct and _f.is_file():
+                _asset = _OPW_KC_FILES.get(_fn)
+                if _asset is not None:
+                    _f, _ct = _asset
+                else:  # defensive: membership above is a fixed allowlist
+                    _f, _ct = None, None
+                if _f is not None and _ct is not None and _f.is_file():
                     return _OPW_KC_Resp(content=_f.read_bytes(), media_type=_ct,
                                         headers={"Cache-Control": "public, max-age=31536000, immutable"})
                 return _OPW_KC_Resp(content=b'/* operator widget asset missing on disk */',
@@ -4620,7 +4611,7 @@ except Exception as _qa6_e:  # pragma: no cover — additive; never break the Sp
 
 
 @app.get("/{full_path:path}")
-async def spa_fallback(full_path: str) -> Response:
+async def spa_fallback(full_path: str, request: Request) -> Response:
     # QA6 defense-in-depth: bare data prefixes must NEVER be served the SPA HTML.
     # If a bare data path somehow reaches the catch-all (alias not wired), return an
     # honest JSON 404 instead of the globe page (which would be silently wrong).
@@ -4628,11 +4619,9 @@ async def spa_fallback(full_path: str) -> Response:
         return JSONResponse({"error": "not found"}, status_code=404)
     if full_path in ("feeds", "osint", "mesh"):
         return JSONResponse({"error": "not found"}, status_code=404)
-    candidate = _safe_join_under(STATIC_DIR, full_path)
-    if candidate is None:
-        return FileResponse(INDEX_HTML, media_type="text/html")
-    if candidate.is_file():
-        return FileResponse(candidate)
+    static_response = await _SPA_FILES.get(full_path, request.scope)
+    if static_response is not None:
+        return static_response
     return FileResponse(INDEX_HTML, media_type="text/html")
 
 
@@ -5063,7 +5052,6 @@ try:
     from fastapi import Request as _JK_Request
     from fastapi.routing import APIRoute as _JK_Route
     from fastapi.responses import (
-        FileResponse as _JK_File,
         HTMLResponse as _JK_HTML,
         RedirectResponse as _JK_Redir,
         JSONResponse as _JK_JSON,
@@ -5072,6 +5060,7 @@ try:
 
     _JK_DIR = _JK_Path(__file__).resolve().parent / "static" / "jackin"
     _JK_INDEX = _JK_DIR / "index.html"
+    _JK_FILES = RootedStaticFiles(_JK_DIR)
 
     def _jk_index_html() -> str:
         # Serve index.html with a <base href="/jackin/"> injected so the app's
@@ -5096,11 +5085,9 @@ try:
         rel = request.path_params.get("jk_path", "") or ""
         if rel in ("", "index.html"):
             return _JK_HTML(_jk_index_html())
-        candidate = _safe_join_under(_JK_DIR, rel)
-        if candidate is None:
-            return _JK_HTML(_jk_index_html())
-        if candidate.is_file():
-            return _JK_File(str(candidate))
+        static_response = await _JK_FILES.get(rel, request.scope)
+        if static_response is not None:
+            return static_response
         # SPA-style fallback to the jackin index for unknown sub-paths.
         return _JK_HTML(_jk_index_html())
 
@@ -5537,20 +5524,6 @@ except Exception as _kc_wave_e:  # pragma: no cover — never break SPA/other or
 # ============================================================================
 
 
-
-# ============================================================================
-# READ-ONLY PUBLIC CONTRACTS -- source/deployment attestation, runtime status,
-# MELT summary, and fail-safe OpenAPI discovery. Registered last and inserted at
-# the front so explicit machine-readable routes beat the SPA history fallback.
-# No targeting, collection, decision, or effector behavior is changed here.
-# ============================================================================
-try:
-    import killinchu_public_contracts as _kc_public_contracts
-    _kc_public_contract_status = _kc_public_contracts.register(app, ns="killinchu")
-    print(f"[killinchu] public contracts registered: {_kc_public_contract_status}", file=sys.stderr)
-except Exception as _kc_public_contract_error:  # pragma: no cover
-    print(f"[killinchu] public contracts NOT registered: {_kc_public_contract_error!r}", file=sys.stderr)
-
 if __name__ == "__main__":
     import uvicorn
     port = int(os.environ.get("PORT", "7860"))

szl_connectors/governance.py

@@ -10,8 +10,8 @@ DOCTRINE (non-negotiable):
   • Every write emits a DSSE-signed Khipu receipt (real ECDSA-P256 over the DSSE
     PAE when SZL_COSIGN_PRIVATE_PEM is present; an explicit UNSIGNED envelope
     otherwise — NEVER a fabricated signature). Reuses the live `szl_dsse` module.
-  • No credential value is EVER placed in a receipt body — only a credential
-    fingerprint hash (sha256, truncated).
+  • No credential value is EVER placed in a receipt body — only a
+    PBKDF2-HMAC-SHA256 credential fingerprint.
   • State-changing writes carry the 2-person Yuyay gate + Khipu 3-of-4 quorum
     status (the hatun-mcp governance contract). Until a connector is CONNECTED,
     write() is refused with an honest reason.
@@ -22,14 +22,22 @@ call directly.
 """
 from __future__ import annotations
 
-import hashlib
 import json
-import os
+import re
 from datetime import datetime, timezone
 from typing import Any
 
+from szl_content_address import sha256_content_address
+
 # Anti-overconfidence floor: Λ is never reported as 1.0. We cap at this ceiling.
 LAMBDA_CEILING = 0.985
+_FINGERPRINT_RE = re.compile(r"\Apbkdf2-sha256:[0-9a-f]{32}\Z")
+_FINGERPRINT_LABEL_RE = re.compile(r"\A[A-Za-z0-9_.:-]{1,80}\Z")
+_SENSITIVE_KEY_PARTS = frozenset({"password", "passwd", "secret", "token", "credential"})
+_SENSITIVE_KEY_NAMES = frozenset({
+    "api_key", "private_key", "authorization", "proxy_authorization",
+    "cookie", "set_cookie",
+})
 
 
 def _now() -> str:
@@ -67,6 +75,53 @@ def quorum_status(present: list[str] | None = None, n: int = 4, f: int = 1) -> d
     }
 
 
+def _is_sensitive_key(key: object) -> bool:
+    normalized = re.sub(r"[^a-z0-9]+", "_", str(key).lower()).strip("_")
+    parts = frozenset(part for part in normalized.split("_") if part)
+    return normalized in _SENSITIVE_KEY_NAMES or bool(parts & _SENSITIVE_KEY_PARTS)
+
+
+def _contains_sensitive_field(value: Any) -> bool:
+    if isinstance(value, dict):
+        return any(
+            _is_sensitive_key(key) or _contains_sensitive_field(child)
+            for key, child in value.items()
+        )
+    if isinstance(value, (list, tuple)):
+        return any(_contains_sensitive_field(child) for child in value)
+    return False
+
+
+def _scrub_sensitive_fields(value: Any) -> Any:
+    """Recursively remove secret-bearing fields without copying their values."""
+    if isinstance(value, dict):
+        return {
+            key: _scrub_sensitive_fields(child)
+            for key, child in value.items()
+            if not _is_sensitive_key(key)
+        }
+    if isinstance(value, list):
+        return [_scrub_sensitive_fields(child) for child in value]
+    if isinstance(value, tuple):
+        return tuple(_scrub_sensitive_fields(child) for child in value)
+    return value
+
+
+def _validated_fingerprints(values: dict[str, str] | None) -> dict[str, str]:
+    """Allow only the KDF output format emitted by ``cred_fingerprint``."""
+    safe: dict[str, str] = {}
+    for label, fingerprint in (values or {}).items():
+        if not isinstance(label, str) or _FINGERPRINT_LABEL_RE.fullmatch(label) is None:
+            continue
+        if fingerprint == "absent":
+            safe[label] = "absent"
+        elif isinstance(fingerprint, str) and _FINGERPRINT_RE.fullmatch(fingerprint):
+            safe[label] = fingerprint
+        else:
+            safe[label] = "invalid-fingerprint"
+    return safe
+
+
 def _dsse_sign(payload: dict[str, Any]) -> dict[str, Any]:
     """Sign a receipt payload via the live szl_dsse module if importable; else an
     honest UNSIGNED envelope (NEVER a fabricated signature)."""
@@ -98,9 +153,10 @@ def receipt_for_write(*, connector_id: str, action: dict[str, Any],
     NOT secret values), the Λ score, quorum status, credential FINGERPRINT HASHES
     (never the values), and a result summary. Returns {receipt_hash, dsse, body}.
     """
-    # scrub the action of anything secret-looking; keep only shape
-    safe_action = {k: v for k, v in (action or {}).items()
-                   if k.lower() not in ("token", "secret", "password", "api_key", "key")}
+    # Scrub at every nesting level. Direct callers receive the same protection
+    # as gate_write callers, including secrets hidden in list/dict children.
+    safe_action = _scrub_sensitive_fields(action or {})
+    safe_result = _scrub_sensitive_fields(result_summary or {})
     body = {
         "kind": "szl.connector.write",
         "connector_id": connector_id,
@@ -108,13 +164,15 @@ def receipt_for_write(*, connector_id: str, action: dict[str, Any],
         "lambda_value": lambda_value,
         "lambda_note": "Λ never 1.0 (conformal anti-overconfidence floor 1/(n+1)); Λ = Conjecture 1",
         "quorum": quorum or quorum_status(),
-        "credential_fingerprints": cred_fingerprints or {},
-        "result": result_summary or {},
+        "credential_fingerprints": _validated_fingerprints(cred_fingerprints),
+        "result": safe_result,
         "emitted_at": _now(),
         "doctrine": "v11 — Λ-gate + DSSE/Khipu receipt on every write; no committed keys; trust never 100%",
     }
-    receipt_hash = "sha256:" + hashlib.sha256(
-        json.dumps(body, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+    canonical_body = json.dumps(body, sort_keys=True, separators=(",", ":")).encode()
+    receipt_hash = "sha256:" + sha256_content_address(
+        canonical_body, purpose="khipu-receipt"
+    )
     body["receipt_hash"] = receipt_hash
     dsse = _dsse_sign(body)
     return {"receipt_hash": receipt_hash, "dsse": dsse, "body": body}
@@ -135,7 +193,7 @@ def gate_write(*, connector_id: str, connected: bool, action: dict[str, Any],
     """
     has_method = bool((action or {}).get("method") or (action or {}).get("object")
                       or (action or {}).get("doctype") or (action or {}).get("sobject"))
-    leak = any(k.lower() in ("token", "secret", "password") for k in (action or {}))
+    leak = _contains_sensitive_field(action or {})
     q = quorum_status(present=quorum_present)
     axes = {
         "connected": 1.0 if connected else 0.0,

szl_connectors/oauth.py

@@ -91,6 +91,23 @@ PROVIDER_OAUTH: dict[str, dict[str, str]] = {
     },
 }
 
+# Keep public scopes in a separate container from endpoint metadata whose
+# ``token`` key is (correctly but over-broadly) treated as sensitive by taint
+# analysis. Receipt content uses this public-only map, so no credential-like
+# container can flow into a protocol content address.
+PROVIDER_SCOPES: dict[str, str] = {
+    "salesforce": "api refresh_token",
+    "hubspot": "crm.objects.contacts.read crm.objects.companies.read crm.objects.deals.read",
+    "zoho_crm": "ZohoCRM.modules.ALL ZohoCRM.org.READ",
+    "slack": "channels:read chat:write users:read",
+    "okta": "okta.users.read okta.groups.read",
+    "entra": "https://graph.microsoft.com/.default offline_access",
+    "auth0": "read:users read:logs",
+    "dynamics_crm": "https://{org}.api.crm.dynamics.com/.default offline_access",
+    "netsuite": "rest_webservices",
+    "servicenow": "useraccount",
+}
+
 
 # Domain-separation salt + work factor for deriving the state-signing key.
 _STATE_KDF_SALT = b"szl.killinchu.oauth-state.v1"
@@ -224,18 +241,19 @@ def exchange_code(connector_id: str, *, code: str, state: str, redirect_uri: str
                 "provider_detail": str(body)[:200]}
     refresh = body.get("refresh_token", "")
     access = body.get("access_token", "")
+    public_scope = PROVIDER_SCOPES.get(connector_id, "")
     # credential-bound DSSE receipt — fingerprint ONLY, never the token value.
     from .governance import receipt_for_write
     rcpt = receipt_for_write(
         connector_id=connector_id,
         action={"method": "oauth.credential_bound", "object": "refresh_token",
-                "scope": cfg.get("scope", "")},
+                "scope": public_scope},
         lambda_value=0.9,
         cred_fingerprints={
             "refresh_token": cred_fingerprint(refresh) if refresh else "absent",
             "access_token": cred_fingerprint(access) if access else "absent",
         },
-        result_summary={"granted_scope": cfg.get("scope", ""),
+        result_summary={"granted_scope": public_scope,
                         "note": "secret persisted to Space secret store only; never committed"},
     )
     return {

szl_content_address.py

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Explicit SHA-256 content addressing for protocol and receipt bytes.
+
+This module is deliberately *not* a password or credential derivation API.
+Callers must provide one of the narrow protocol purposes below, and the input
+bytes are hashed exactly as supplied.  Keeping this operation separate from
+PBKDF2-based credential fingerprints prevents accidental reuse while
+preserving the byte-for-byte hashes already carried by DSSE envelopes and
+Khipu receipts.
+"""
+from __future__ import annotations
+
+import hashlib
+
+
+_PURPOSES = frozenset({"dsse-pae", "khipu-receipt", "public-key"})
+
+
+def sha256_content_address(data: bytes, *, purpose: str) -> str:
+    """Return the protocol-compatible SHA-256 hex address of public content.
+
+    ``purpose`` is intentionally mandatory and allowlisted.  Secret values
+    belong in a password KDF such as PBKDF2, never in this function.
+    """
+    if purpose not in _PURPOSES:
+        raise ValueError(f"unsupported content-address purpose: {purpose!r}")
+    if not isinstance(data, bytes):
+        raise TypeError("content address input must be bytes")
+    return hashlib.sha256(data).hexdigest()
+
+
+__all__ = ["sha256_content_address"]

szl_dsse.py

@@ -66,13 +66,14 @@ for SZL Khipu receipts, backed by the SZLHOLDINGS **Cosign** keypair.
 from __future__ import annotations
 
 import base64
-import hashlib
 import json
 import os
 import sys
 from datetime import datetime, timezone
 from typing import Any
 
+from szl_content_address import sha256_content_address
+
 KEYID = "szlholdings-cosign"
 KHIPU_PAYLOAD_TYPE = "application/vnd.szl.khipu+json"
 COSIGN_PUB_FINGERPRINT_ENV = "SZL_COSIGN_PUB_SHA256"  # optional pin
@@ -151,7 +152,9 @@ def signing_available() -> bool:
 
 
 def public_key_fingerprint() -> str:
-    return hashlib.sha256(COSIGN_PUBLIC_PEM.strip().encode()).hexdigest()
+    return sha256_content_address(
+        COSIGN_PUBLIC_PEM.strip().encode(), purpose="public-key"
+    )
 
 
 # ---------------------------------------------------------------------------
@@ -171,7 +174,7 @@ def sign_payload(payload_obj: Any, payload_type: str = KHIPU_PAYLOAD_TYPE) -> di
         "payloadType": payload_type,
         "payload": base64.b64encode(body).decode("ascii"),
         "_dsse": "DSSEv1",
-        "_pae_sha256": hashlib.sha256(to_sign).hexdigest(),
+        "_pae_sha256": sha256_content_address(to_sign, purpose="dsse-pae"),
         "_signed_at": datetime.now(timezone.utc).isoformat(),
     }
     priv = _load_private_key()
@@ -210,7 +213,7 @@ def verify_envelope(env: dict[str, Any]) -> dict[str, Any]:
             return {**out, "verified": False, "reason": "no signatures (unsigned envelope)"}
         body = base64.b64decode(payload_b64)
         to_verify = pae(payload_type, body)
-        out["pae_sha256"] = hashlib.sha256(to_verify).hexdigest()
+        out["pae_sha256"] = sha256_content_address(to_verify, purpose="dsse-pae")
         pub = _load_public_key()
         from cryptography.hazmat.primitives.asymmetric import ec
         from cryptography.hazmat.primitives import hashes

szl_killinchu_cookbook.py

@@ -25,6 +25,7 @@ import os
 import sys
 import hashlib
 import datetime
+import re
 from pathlib import Path
 
 from fastapi import Request
@@ -34,6 +35,11 @@ from fastapi.responses import JSONResponse, PlainTextResponse
 # Resolve relative to THIS module so it works regardless of CWD.
 _HERE = Path(__file__).resolve().parent
 _DATA = _HERE / "static" / "cookbook"
+_SAFE_RECIPE_ID = re.compile(r"\Arecipe-[a-z0-9-]+\Z")
+_MISSION_FILES = {
+    "P1": "P1.json", "P2": "P2.json", "P3": "P3.json", "P4": "P4.json",
+    "P5": "P5.json", "P6": "P6.json", "P7": "P7.json", "P8": "P8.json",
+}
 
 DOCTRINE = "v11"
 NUMBERS = {"declarations": 749, "axioms": 14, "sorries": 163}
@@ -196,9 +202,14 @@ def register_cookbook(app, ns: str = "killinchu", sign_fn=None):
     async def cookbook_get(recipe_id: str) -> JSONResponse:
         idx = _read_json(_DATA / "recipes" / "_index.json") or []
         meta = next((r for r in idx if r.get("id") == recipe_id), None)
-        # sanitize id -> filename
-        safe = recipe_id.replace("/", "").replace("..", "")
-        md = _read_text(_DATA / "recipes" / f"{safe}.md")
+        # The path component comes from the trusted, committed index entry, not
+        # from the route parameter. Validate the index too so a malformed bundle
+        # fails closed instead of becoming a filesystem path.
+        indexed_id = meta.get("id") if isinstance(meta, dict) else None
+        if not isinstance(indexed_id, str) or _SAFE_RECIPE_ID.fullmatch(indexed_id) is None:
+            md = ""
+        else:
+            md = _read_text(_DATA / "recipes" / f"{indexed_id}.md")
         if not md or meta is None:
             return JSONResponse(_base({
                 "error": "recipe not found", "ref": recipe_id,
@@ -233,15 +244,16 @@ def register_cookbook(app, ns: str = "killinchu", sign_fn=None):
 
     @app.get(p + "/missions/{mission_id}")
     async def mission_get(mission_id: str) -> JSONResponse:
-        safe = mission_id.upper().replace("/", "").replace("..", "")
-        m = _read_json(_DATA / "missions" / f"{safe}.json")
+        mission_key = mission_id.upper()
+        filename = _MISSION_FILES.get(mission_key)
+        m = _read_json(_DATA / "missions" / filename) if filename is not None else None
         if m is None:
             return JSONResponse(_base({
                 "error": "mission not found", "ref": mission_id,
                 "available": ["P1", "P2", "P3", "P4", "P5", "P6", "P7", "P8"],
             }), status_code=404)
         drone = bool(m.get("drone_domain"))
-        m["recall_receipt"] = _recall_receipt("mission", safe, _digest(m))
+        m["recall_receipt"] = _recall_receipt("mission", mission_key, _digest(m))
         # m already carries doctrine/numbers/disclaimer from generation; ensure disclaimer on drone
         if drone and "disclaimer" not in m:
             m["disclaimer"] = LEGAL_DISCLAIMER

szl_safe_static.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Root-confined static-file lookup for application catch-all routes."""
+from __future__ import annotations
+
+from os import PathLike
+from typing import Any
+
+from starlette.exceptions import HTTPException as StarletteHTTPException
+from starlette.responses import Response
+from starlette.staticfiles import StaticFiles
+
+
+class RootedStaticFiles:
+    """Serve a relative URL path through Starlette's containment-checked API.
+
+    Starlette's ``StaticFiles.lookup_path`` canonicalizes the configured root
+    and candidate then requires ``os.path.commonpath`` containment.  This thin
+    adapter exposes a nullable response so SPA routes can fall back to their
+    index without ever constructing a filesystem path from request data.
+    """
+
+    def __init__(self, directory: str | PathLike[str]) -> None:
+        self._files = StaticFiles(directory=str(directory), check_dir=False)
+
+    async def get(self, relative_path: str, scope: dict[str, Any]) -> Response | None:
+        if not isinstance(relative_path, str):
+            return None
+        try:
+            response = await self._files.get_response(relative_path, scope)
+        except StarletteHTTPException as exc:
+            if exc.status_code == 404:
+                return None
+            raise
+        except ValueError:
+            # ``os.path.commonpath`` rejects mixed-drive Windows paths. Treat
+            # that attacker-controlled shape as an ordinary miss, never a 500.
+            return None
+        return None if response.status_code == 404 else response
+
+
+__all__ = ["RootedStaticFiles"]