@agentikos/omega-os 0.1.0 → 0.19.5

package/omega/Agentik_Engine/omega_engine/webhooks.py

@@ -0,0 +1,262 @@
+"""Inbound webhooks — GitHub / Linear / generic HMAC-SHA256.
+
+The autonomous supervisor already has ``wake_webhook(path, payload)``. The
+gap was the *HTTP front door*: nothing was listening on a port, nothing
+verified signatures. This module is that front door.
+
+Specs live in ``Agentik_SSOT/webhooks/webhooks.yaml`` (one path = one
+spec). The engine daemon's HTTP server handles ``POST /webhook/<id>``:
+it locates the spec, reads the source-specific signature header, looks
+up the HMAC secret in the vault, verifies, and calls
+``supervisor.wake_webhook(path, payload)``. On a valid signature the
+caller gets ``202 Accepted`` immediately — the mission runs async.
+
+We never accept an unsigned webhook. The default is ``source: generic``
+which still requires HMAC-SHA256 in a configurable header.
+
+Why we ship this small (no fancy framework):
+
+  * The engine daemon is already on a loopback port. The operator's
+    reverse proxy (nginx, Cloudflare Tunnel) is responsible for the
+    public face. We do auth, not networking.
+  * Signature verification is the only thing that matters — without it,
+    a webhook endpoint is a remote code execution waiting to happen.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+# Source-specific header names. The signature value's wire format is
+# different per source; see _verify_source for the parsing.
+_SIGNATURE_HEADER = {
+    "github":  "X-Hub-Signature-256",
+    "linear":  "Linear-Signature",
+    "generic": "X-Omega-Signature",
+}
+
+
+@dataclass
+class WebhookSpec:
+    """One inbound webhook endpoint."""
+    id: str
+    path: str                            # "/webhook/github-prs"
+    source: str = "generic"              # "github" | "linear" | "generic"
+    secret_ref: str = ""                 # vault ref for the HMAC secret
+    description: str = ""
+
+    @staticmethod
+    def from_dict(d: dict[str, Any]) -> "WebhookSpec":
+        return WebhookSpec(
+            id=str(d["id"]),
+            path=str(d.get("path") or f"/webhook/{d['id']}"),
+            source=str(d.get("source", "generic")),
+            secret_ref=str(d.get("secret_ref",
+                                  f"WEBHOOK_{d['id'].upper().replace('-', '_')}")),
+            description=str(d.get("description", "")),
+        )
+
+
+@dataclass
+class WebhookRegistry:
+    """All webhook specs known to the engine."""
+    specs: list[WebhookSpec] = field(default_factory=list)
+
+    def by_path(self, path: str) -> WebhookSpec | None:
+        for s in self.specs:
+            if s.path == path:
+                return s
+        return None
+
+    def by_id(self, id: str) -> WebhookSpec | None:
+        for s in self.specs:
+            if s.id == id:
+                return s
+        return None
+
+
+def load_registry(omega_home: str | Path) -> WebhookRegistry:
+    """Read ``Agentik_SSOT/webhooks/webhooks.yaml``. Empty if missing."""
+    path = (Path(omega_home) / "Agentik_SSOT" / "webhooks" / "webhooks.yaml")
+    if not path.exists():
+        return WebhookRegistry()
+    data = yaml.safe_load(path.read_text()) or {}
+    specs = [
+        WebhookSpec.from_dict(d)
+        for d in (data.get("webhooks") or [])
+        if isinstance(d, dict) and d.get("id")
+    ]
+    return WebhookRegistry(specs=specs)
+
+
+def signature_header_for(source: str) -> str:
+    """Return the header name the signature is expected in."""
+    return _SIGNATURE_HEADER.get(source.lower(), _SIGNATURE_HEADER["generic"])
+
+
+def verify_signature(
+    source: str,
+    body: bytes,
+    signature_header_value: str | None,
+    secret: str,
+    *,
+    timestamp_header_value: str | None = None,
+    replay_window_s: int = 300,
+    now_s: float | None = None,
+) -> tuple[bool, str]:
+    """Return (ok, reason) for a webhook signature.
+
+    Hard rule: missing signature → False. Missing secret → False. We
+    NEVER let an unsigned webhook through.
+
+    Replay protection
+    -----------------
+    When ``timestamp_header_value`` is provided, we require the timestamp
+    to be within ``replay_window_s`` seconds of ``now_s``. An attacker who
+    captured a valid signed body can otherwise replay it forever. Callers
+    SHOULD pass the timestamp header (X-Omega-Timestamp / X-Hub-Timestamp /
+    Linear-Delivery-Timestamp); when absent we accept the request (HMAC
+    alone is the v0.5 contract; timestamp is additive).
+
+    Source-specific notes:
+
+      * ``github`` ships ``X-Hub-Signature-256: sha256=<hex>``.
+      * ``linear`` ships ``Linear-Signature: <hex>`` (no prefix).
+      * ``generic`` expects ``X-Omega-Signature: sha256=<hex>``.
+    """
+    if not signature_header_value:
+        return False, "missing signature header"
+    if not secret:
+        return False, "secret not set in vault"
+
+    # Replay window check (additive, off when no timestamp supplied).
+    if timestamp_header_value is not None:
+        try:
+            ts = float(timestamp_header_value)
+        except (TypeError, ValueError):
+            return False, "timestamp header is not numeric"
+        import time as _t
+        wall = now_s if now_s is not None else _t.time()
+        if abs(wall - ts) > replay_window_s:
+            return False, (
+                f"timestamp outside ±{replay_window_s}s replay window "
+                f"(now={wall:.0f} hdr={ts:.0f})"
+            )
+
+    src = source.lower()
+    raw_sig = signature_header_value.strip()
+    if src in ("github", "generic"):
+        # `sha256=<hex>` form
+        if not raw_sig.startswith("sha256="):
+            return False, "signature missing sha256= prefix"
+        provided = raw_sig.split("=", 1)[1]
+    elif src == "linear":
+        # raw hex
+        provided = raw_sig
+    else:
+        return False, f"unknown source {source!r}"
+
+    mac = hmac.new(
+        secret.encode("utf-8"), body, hashlib.sha256,
+    ).hexdigest()
+    if not hmac.compare_digest(mac, provided):
+        return False, "signature mismatch"
+    return True, "ok"
+
+
+def _load_secret(omega_home: str | Path, secret_ref: str) -> str:
+    """Best-effort vault read."""
+    if not secret_ref:
+        return ""
+    try:
+        from omega_engine.vault import vault_read
+        v = vault_read(omega_home, secret_ref)
+        return v or ""
+    except Exception:  # noqa: BLE001
+        return ""
+
+
+def handle_webhook(
+    omega_home: str | Path,
+    *,
+    path: str,
+    headers: dict[str, str],
+    body: bytes,
+    supervisor=None,
+) -> dict[str, Any]:
+    """Run the gate for one inbound webhook.
+
+    Returns ``{status: int, ok: bool, reason: str, fired: [charter_ids]}``.
+    Status codes: 200 (already-known but no charter fired), 202 (charters
+    fired), 401 (bad signature), 404 (unknown path), 500 (internal).
+
+    ``supervisor`` is optional — pass an ``AutonomousSupervisor`` to
+    actually fire charters. Without one, we still verify but don't fire
+    (useful for ``omega webhook test``).
+    """
+    home = Path(omega_home)
+    registry = load_registry(home)
+    spec = registry.by_path(path)
+    if spec is None:
+        return {"status": 404, "ok": False, "reason": "no spec for path",
+                "fired": []}
+
+    secret = _load_secret(home, spec.secret_ref)
+    sig_header_name = signature_header_for(spec.source)
+    sig_value = None
+    # Headers come from a stdlib BaseHTTPRequestHandler which lower-cases
+    # access via dict-style only when wrapped; here we normalise both sides.
+    for k, v in headers.items():
+        if k.lower() == sig_header_name.lower():
+            sig_value = v
+            break
+    ok, reason = verify_signature(spec.source, body, sig_value, secret)
+    if not ok:
+        return {"status": 401, "ok": False, "reason": reason, "fired": []}
+
+    # Parse payload best-effort; webhooks SHOULD be JSON.
+    try:
+        payload = json.loads(body.decode("utf-8") or "{}")
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        payload = {"_raw": body.decode("utf-8", errors="replace")[:1000]}
+
+    fired: list[str] = []
+    if supervisor is not None:
+        try:
+            fired = supervisor.wake_webhook(path, payload) or []
+        except Exception as exc:  # noqa: BLE001
+            return {
+                "status": 500, "ok": False,
+                "reason": f"supervisor raised: {exc}"[:300],
+                "fired": [],
+            }
+
+    return {
+        "status": 202 if fired else 200,
+        "ok": True,
+        "reason": "ok",
+        "fired": fired,
+    }
+
+
+def generate_test_signature(source: str, body: bytes, secret: str) -> str:
+    """Build a valid signature header value for the given source.
+
+    Used by ``omega webhook test`` and by the integration tests so we can
+    POST a synthetic webhook to the engine and confirm the gate works.
+    """
+    mac = hmac.new(secret.encode("utf-8"), body, hashlib.sha256).hexdigest()
+    src = source.lower()
+    if src in ("github", "generic"):
+        return f"sha256={mac}"
+    if src == "linear":
+        return mac
+    raise ValueError(f"unknown source: {source}")