simplicio-agent 0.25.0__py3-none-any.whl

plugins/cron_providers/chronos/_nas_client.py

@@ -0,0 +1,123 @@
+"""Thin HTTP client for the agent → NAS ``agent-cron`` endpoints (Chronos).
+
+The Chronos provider speaks ONLY to NAS — it names no scheduler vendor and
+holds no scheduler credentials. NAS owns the external scheduler (an internal
+implementation detail) and that scheduler's account; the agent just asks NAS to
+"arm a one-shot at time T" / "cancel" / "list", authenticated with the agent's
+existing Nous Portal access token (the same token it already uses to call the
+portal — no new secret).
+
+Wire contract: ``docs/chronos-managed-cron-contract.md``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger("cron.chronos")
+
+# Endpoint paths under the portal base URL.
+_PROVISION_PATH = "/api/agent-cron/provision"
+_CANCEL_PATH = "/api/agent-cron/cancel"
+_LIST_PATH = "/api/agent-cron/list"
+
+
+class NasCronClientError(RuntimeError):
+    """Raised when a NAS agent-cron call fails (non-2xx or transport error)."""
+
+
+class NasCronClient:
+    """Minimal client for the agent→NAS provision/cancel/list endpoints.
+
+    Uses the agent's refresh-aware Nous access token for auth. No scheduler
+    vendor, no scheduler creds — NAS hides all of that behind these three calls.
+    """
+
+    def __init__(self, portal_url: str, *, timeout_seconds: float = 15.0) -> None:
+        self.portal_url = portal_url.rstrip("/")
+        self.timeout_seconds = timeout_seconds
+
+    # -- auth -------------------------------------------------------------
+
+    def _access_token(self) -> str:
+        """The agent's existing Nous Portal access token (refresh-aware)."""
+        from hermes_cli.auth import resolve_nous_access_token
+        return resolve_nous_access_token()
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._access_token()}",
+            "Content-Type": "application/json",
+        }
+
+    # -- HTTP -------------------------------------------------------------
+
+    def _post(self, path: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        import requests  # lazy: agent already depends on requests
+
+        url = f"{self.portal_url}{path}"
+        try:
+            resp = requests.post(
+                url, json=body, headers=self._headers(), timeout=self.timeout_seconds
+            )
+        except Exception as e:
+            raise NasCronClientError(f"POST {path} failed: {e}") from e
+        if resp.status_code // 100 != 2:
+            raise NasCronClientError(
+                f"POST {path} returned {resp.status_code}: {resp.text[:200]}"
+            )
+        try:
+            return resp.json() if resp.content else {}
+        except Exception:
+            return {}
+
+    def _get(self, path: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        import requests
+
+        url = f"{self.portal_url}{path}"
+        try:
+            resp = requests.get(
+                url, params=params, headers=self._headers(), timeout=self.timeout_seconds
+            )
+        except Exception as e:
+            raise NasCronClientError(f"GET {path} failed: {e}") from e
+        if resp.status_code // 100 != 2:
+            raise NasCronClientError(
+                f"GET {path} returned {resp.status_code}: {resp.text[:200]}"
+            )
+        try:
+            return resp.json() if resp.content else {}
+        except Exception:
+            return {}
+
+    # -- endpoints --------------------------------------------------------
+
+    def provision(self, *, job_id: str, fire_at: str, agent_callback_url: str,
+                  dedup_key: str) -> Dict[str, Any]:
+        """Ask NAS to arm a one-shot for ``job_id`` at ``fire_at`` (ISO 8601).
+
+        ``dedup_key`` (``{job_id}:{fire_at}``) makes re-arming the same fire
+        idempotent NAS-side. Returns the NAS response (e.g. ``{schedule_id}``).
+        """
+        return self._post(_PROVISION_PATH, {
+            "job_id": job_id,
+            "fire_at": fire_at,
+            "agent_callback_url": agent_callback_url,
+            "dedup_key": dedup_key,
+        })
+
+    def cancel(self, *, job_id: str) -> Dict[str, Any]:
+        """Ask NAS to cancel any armed one-shot for ``job_id``."""
+        return self._post(_CANCEL_PATH, {"job_id": job_id})
+
+    def list_armed(self) -> List[Dict[str, Any]]:
+        """List the one-shots NAS currently has armed for this agent.
+
+        Returns a list of ``{job_id, fire_at, schedule_id}``. Best-effort: used
+        by reconcile to find orphaned arms on a cold process; on error the
+        caller falls back to idempotent re-arm of all desired jobs.
+        """
+        data = self._get(_LIST_PATH, {})
+        items = data.get("armed") if isinstance(data, dict) else None
+        return items if isinstance(items, list) else []

plugins/cron_providers/chronos/plugin.yaml

@@ -0,0 +1,9 @@
+name: chronos
+description: >-
+  Chronos — NAS-mediated managed cron provider for scale-to-zero hosted agents.
+  Delegates the "wake me at time T" trigger to Nous infrastructure so an idle
+  gateway can scale to zero and still fire cron jobs. The agent computes each
+  job's next-fire time and asks NAS to arm a one-shot; NAS calls the agent back
+  at fire time over an authenticated webhook. Inert unless cron.provider=chronos.
+version: 1.0.0
+author: Nous Research

plugins/cron_providers/chronos/verify.py

@@ -0,0 +1,145 @@
+"""Inbound cron-fire token verification for Chronos (Phase 4E.1).
+
+When NAS relays an external scheduler fire to the agent, it POSTs
+``/api/cron/fire`` with a short-lived NAS-minted JWT. This module verifies that
+JWT before any job runs — the security boundary for remotely-triggered job
+execution.
+
+We verify a NAS-minted JWT (the trust path the agent already has) rather than
+let an external scheduler call the agent directly: the scheduler signs with
+NAS's keys, which the agent doesn't (and shouldn't) hold. See the plan's DQ-4.
+
+The verifier is pluggable (``get_fire_verifier``) so the escape-hatch mode
+(direct per-job cron-key) can swap in later with no handler change.
+
+Crypto is delegated to PyJWT (already a declared dependency) — we do NOT
+hand-roll JWT verification.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from typing import Any, Callable, Dict, Optional
+
+logger = logging.getLogger("cron.chronos.verify")
+
+# The purpose claim that scopes a token to the fire endpoint. A general agent
+# JWT (without this claim) must NOT be replayable against /api/cron/fire.
+_FIRE_PURPOSE = "cron_fire"
+
+# Process-wide cache of PyJWKClient instances, keyed by JWKS URL.
+#
+# WHY THIS EXISTS: a PyJWKClient caches the fetched JWKS (signing keys) on the
+# INSTANCE. Constructing a fresh client per fire therefore threw that cache
+# away and forced a synchronous JWKS HTTP GET to the portal on EVERY fire. Under
+# a burst of concurrent fires (an instance with several cron jobs firing in the
+# same window) that fanned out into N simultaneous JWKS fetches, which the
+# portal rate-limited (HTTP 403) — verification then failed and the agent
+# answered 401. When a fetch was merely slow rather than rate-limited, it blocked
+# the event loop long enough that the fire webhook could not return its 202
+# before the relay's 30s timeout (observed in prod as relay 504s concentrated on
+# high-job-count instances). Reusing one client per URL keeps the signing keys
+# cached (NAS keys rotate rarely), so the steady state is zero JWKS fetches per
+# fire. See docs/chronos-managed-cron-contract.md and the betterstack triage.
+_JWK_CLIENTS: Dict[str, Any] = {}
+_JWK_CLIENTS_LOCK = threading.Lock()
+
+
+def _get_jwk_client(jwks_url: str) -> Any:
+    """Return a process-cached PyJWKClient for ``jwks_url`` (one per URL).
+
+    PyJWKClient does its own key caching internally (``cache_keys``/``lifespan``);
+    the whole point here is to reuse the SAME instance across fires so that cache
+    is actually hit instead of discarded. Double-checked-locked so concurrent
+    fires resolve to a single shared client without racing.
+    """
+    client = _JWK_CLIENTS.get(jwks_url)
+    if client is not None:
+        return client
+    with _JWK_CLIENTS_LOCK:
+        client = _JWK_CLIENTS.get(jwks_url)
+        if client is None:
+            from jwt import PyJWKClient
+
+            client = PyJWKClient(jwks_url)
+            _JWK_CLIENTS[jwks_url] = client
+        return client
+
+
+def verify_nas_fire_token(
+    *,
+    token: str,
+    expected_audience: str,
+    jwks_or_key: Optional[str] = None,
+    issuer: Optional[str] = None,
+    leeway_seconds: int = 30,
+) -> Optional[Dict[str, Any]]:
+    """Verify a NAS-minted cron-fire JWT. Return decoded claims, or None.
+
+    Checks (all must pass):
+      - signature against the NAS JWKS (``jwks_or_key`` is a JWKS URL) — RS256
+        family; symmetric secrets are rejected (NAS signs asymmetrically).
+      - ``aud`` == ``expected_audience`` (this agent: ``agent:{instance_id}``).
+      - ``exp`` / ``nbf`` within ``leeway_seconds``.
+      - ``iss`` == ``issuer`` when an issuer is configured.
+      - ``purpose`` == ``"cron_fire"`` — so a general agent JWT can't be
+        replayed against the fire endpoint.
+
+    Returns None (never raises) on any failure, so the handler can answer 401
+    without leaking which check failed.
+    """
+    if not token or not expected_audience:
+        return None
+    if not jwks_or_key:
+        # No verification key configured → cannot verify → refuse. We never
+        # fall back to unsigned decode for a security boundary.
+        logger.warning("cron fire: no JWKS/key configured; refusing token")
+        return None
+
+    try:
+        import jwt
+
+        # Resolve the signing key from the JWKS endpoint by the token's kid.
+        signing_key = None
+        if jwks_or_key.startswith("http://") or jwks_or_key.startswith("https://"):
+            # Reuse a process-cached client so the JWKS fetch is amortised across
+            # fires (a fresh client per fire re-fetched the JWKS every time and,
+            # under concurrent fires, tripped the portal's rate limit → 403 →
+            # 401, or blocked the event loop past the relay's 30s timeout → 504).
+            jwk_client = _get_jwk_client(jwks_or_key)
+            signing_key = jwk_client.get_signing_key_from_jwt(token).key
+        else:
+            # A PEM public key passed inline (test / pinned-key deployments).
+            signing_key = jwks_or_key
+
+        options = {"require": ["exp", "aud"]}
+        decode_kwargs: Dict[str, Any] = dict(
+            algorithms=["RS256", "RS384", "RS512", "ES256", "ES384"],
+            audience=expected_audience,
+            leeway=leeway_seconds,
+            options=options,
+        )
+        if issuer:
+            decode_kwargs["issuer"] = issuer
+
+        claims = jwt.decode(token, signing_key, **decode_kwargs)
+    except Exception as e:
+        logger.warning("cron fire: token verification failed: %s", e)
+        return None
+
+    if claims.get("purpose") != _FIRE_PURPOSE:
+        logger.warning("cron fire: token missing/!=%s purpose claim", _FIRE_PURPOSE)
+        return None
+
+    return claims
+
+
+def get_fire_verifier() -> Callable[..., Optional[Dict[str, Any]]]:
+    """Return the active inbound-fire verifier.
+
+    Default = the NAS-JWT verifier. The DQ-4 escape hatch (direct per-job
+    cron-key) would return a cron-key verifier here instead, selected by config
+    — so the webhook handler never changes when the auth mode is swapped.
+    """
+    return verify_nas_fire_token