primarypath-server 1.0.0__py3-none-any.whl

app/routes/traces.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+
+from ..auth import (
+    activity_scope,
+    require_console_reader,
+    resolve_tenant,
+    scope_units,
+    visible_to,
+)
+
+router = APIRouter(prefix="/api/traces")
+
+# a client-supplied limit is clamped: an absurd value would fold the whole
+# table per request
+MAX_LIMIT = 500
+
+
+@router.get("", dependencies=[Depends(require_console_reader)])
+async def list_runs(request: Request, status: str | None = None,
+                    tool: str | None = None, limit: int = 50, cursor: int = 0):
+    """Per-tenant run list with status, gated tools, steps, tokens, cost —
+    unit-scoped to the caller (server-enforced, F24)."""
+    scope = await activity_scope(request)
+    return await request.app.state.traces.run_list(
+        tenant=await resolve_tenant(request), status=status, tool=tool,
+        limit=max(1, min(limit, MAX_LIMIT)), offset=max(0, cursor),
+        units=scope_units(scope),
+        agent=scope.get("agent") if scope else None)
+
+
+@router.get("/cost", dependencies=[Depends(require_console_reader)])
+async def cost(request: Request, since_ms: int | None = None,
+               until_ms: int | None = None):
+    """Aggregate tokens/cost for the tenant over a period, by tool and model
+    — scoped to the caller's units (spend is volume, volume is information)."""
+    scope = await activity_scope(request)
+    return await request.app.state.traces.cost_summary(
+        tenant=await resolve_tenant(request), since_ms=since_ms,
+        until_ms=until_ms, units=scope_units(scope))
+
+
+@router.get("/{run_id}", dependencies=[Depends(require_console_reader)])
+async def run_detail(request: Request, run_id: str):
+    """One run's step timeline (reasoning, tool calls, timing), the approval
+    and decider, and the per-model cost breakdown — folded from the log."""
+    scope = await activity_scope(request)
+    trace = await request.app.state.traces.run_trace(
+        run_id, tenant=await resolve_tenant(request),
+        visible=lambda agent, unit: visible_to(scope, agent, unit))
+    if trace is None or not visible_to(scope, trace["agent"], trace["unit"]):
+        # outside your units, even existence is need-to-know (F24)
+        raise HTTPException(404, f"unknown run {run_id}")
+    return trace

app/schemas.py

@@ -0,0 +1,248 @@
+"""Request models for the HTTP contract (PLAN.md).
+
+Every field has an upper bound. An authenticated agent's token buys it
+the right to propose actions, not the right to write unbounded bytes or
+arbitrarily deep JSON into the chain; the limits below are generous for
+real agents and small for a runaway one.
+"""
+from __future__ import annotations
+
+import json
+
+from pydantic import BaseModel, Field, field_validator
+
+# identifiers: run/call/tool/agent/version/reviewer names
+ID_MAX = 256
+# free text a human reads in the inbox
+REASONING_MAX = 16_384
+REASON_MAX = 4_096
+NOTE_MAX = 16_384
+URL_MAX = 2_048
+# structured payloads: serialized size and nesting
+JSON_MAX_BYTES = 262_144
+JSON_MAX_DEPTH = 16
+EVENT_MAX_BYTES = 65_536
+EVENTS_PER_BATCH_MAX = 500
+LIST_MAX = 1_000
+
+
+def _depth(v, d: int = 1) -> int:
+    if isinstance(v, dict):
+        return max([d] + [_depth(x, d + 1) for x in v.values()])
+    if isinstance(v, list):
+        return max([d] + [_depth(x, d + 1) for x in v])
+    return d
+
+
+def bounded_json(v, *, max_bytes: int = JSON_MAX_BYTES,
+                 max_depth: int = JSON_MAX_DEPTH, what: str = "payload"):
+    """Validator: refuse a structure deeper than `max_depth` or larger
+    than `max_bytes` when serialized."""
+    if _depth(v) > max_depth:
+        raise ValueError(f"{what} nests deeper than {max_depth} levels")
+    size = len(json.dumps(v, separators=(",", ":"), ensure_ascii=False,
+                          default=str).encode("utf-8"))
+    if size > max_bytes:
+        raise ValueError(f"{what} is {size} bytes; the limit is {max_bytes}")
+    return v
+
+
+# identifiers travel in URL paths (/api/approvals/{run_id}:{call_id},
+# /api/runs/{run_id}/...) and the approval id is the two joined by ":".
+# Only characters that round-trip a path unchanged are accepted, so every
+# approval that can be created can be addressed; "/", "?", "#", "%",
+# whitespace and control characters cannot be, and ":" is the join
+# character, so call_id may not contain it.
+RUN_ID_RE = r"^[A-Za-z0-9][A-Za-z0-9._~@+=:-]*$"
+CALL_ID_RE = r"^[A-Za-z0-9][A-Za-z0-9._~@+=-]*$"
+ID_HINT = ("letters, digits and . _ - ~ @ + = (and : in run_id), starting with "
+           "a letter or digit: it must survive a URL path unchanged")
+
+
+class CreateApproval(BaseModel):
+    run_id: str = Field(min_length=1, max_length=ID_MAX, pattern=RUN_ID_RE,
+                        description=f"URL-safe: {ID_HINT}")
+    call_id: str = Field(min_length=1, max_length=ID_MAX, pattern=CALL_ID_RE,
+                         description=f"URL-safe: {ID_HINT}")
+    tool: str = Field(min_length=1, max_length=ID_MAX)
+    arguments: dict = Field(default_factory=dict)
+    reasoning: str | None = Field(default=None, max_length=REASONING_MAX)
+    framework: str | None = Field(default=None, max_length=ID_MAX)
+    deadline_ms: int | None = Field(default=None, ge=0)
+    callback_url: str | None = Field(default=None, max_length=URL_MAX)
+    # the proposal this one replaces. A PENDING one (arguments or context
+    # changed) closes as `superseded` in the same transaction. One a
+    # reviewer sent back (`changes_requested`) is already closed and keeps
+    # that outcome: this is its revision, linked, never rewriting it.
+    # Approving the new one never approves the old
+    supersedes: str | None = Field(default=None, max_length=2 * ID_MAX + 1)
+
+    @field_validator("arguments")
+    @classmethod
+    def _bounded_arguments(cls, v):
+        return bounded_json(v, what="arguments")
+
+
+class Redeem(BaseModel):
+    """Redeem an execution grant (agent plane: the executor's token)."""
+    nonce: str = Field(min_length=1, max_length=ID_MAX)
+    # the executor's own name for itself ("mcp-gateway@edge-1"): recorded
+    # as self-asserted context next to the credential-derived identity
+    # the server writes as the attribution
+    instance: str = Field(default="", max_length=ID_MAX)
+    # 0.2 name for `instance`; accepted for one minor
+    executor: str = Field(default="", max_length=ID_MAX)
+
+
+class Decision(BaseModel):
+    approved: bool
+    # in SSO mode the verified session identity overrides this field;
+    # in open/dev mode it is required (validated in the route)
+    reviewer: str = Field(default="", max_length=ID_MAX)
+    reason: str = Field(default="", max_length=REASON_MAX)
+    # set by a bulk action: the server refuses it for irreversible,
+    # dual-control or high/critical-risk actions (decide individually)
+    bulk: bool = False
+
+
+class ChangesRequest(BaseModel):
+    """POST /api/approvals/{id}/request-changes — send it back, not
+    approved and not refused: change it and propose again."""
+    reviewer: str = Field(default="", max_length=ID_MAX)
+    reason: str = Field(min_length=1, max_length=REASON_MAX)
+
+
+class Cancel(BaseModel):
+    """POST /api/approvals/{id}/cancel — the agent withdraws its proposal."""
+    reason: str = Field(default="", max_length=REASON_MAX)
+
+
+class Annotation(BaseModel):
+    reviewer: str = Field(default="", max_length=ID_MAX)
+    note: str = Field(min_length=1, max_length=NOTE_MAX)
+
+
+SEVERITIES = ("sev1", "sev2", "sev3", "sev4")
+
+
+class Incident(BaseModel):
+    """POST /api/approvals/{id}/incident — a structured outcome: the
+    executed action caused or contributed to an incident."""
+    reviewer: str = Field(default="", max_length=ID_MAX)
+    severity: str = Field(default="sev3", max_length=8)
+    summary: str = Field(min_length=1, max_length=NOTE_MAX)
+
+    @field_validator("severity")
+    @classmethod
+    def _known_severity(cls, v):
+        if v not in SEVERITIES:
+            raise ValueError(f"severity must be one of {SEVERITIES}")
+        return v
+
+
+class RunEvents(BaseModel):
+    events: list[dict] = Field(default_factory=list,
+                               max_length=EVENTS_PER_BATCH_MAX)
+
+    @field_validator("events")
+    @classmethod
+    def _bounded_events(cls, v):
+        for i, e in enumerate(v):
+            t = e.get("type")
+            if t is not None and (not isinstance(t, str) or len(t) > ID_MAX):
+                raise ValueError(f"events[{i}].type must be a string of at "
+                                 f"most {ID_MAX} characters")
+            bounded_json(e, max_bytes=EVENT_MAX_BYTES, what=f"events[{i}]")
+        return v
+
+
+class PolicyRule(BaseModel):
+    """PUT /api/policy/{action} — author a per-action rule (F21)."""
+    mode: str = Field(max_length=ID_MAX)  # validated in the route
+    reversible: bool = False
+    # None -> derive from mode (assisted gates; shadow/autonomous do not)
+    requires_approval: bool | None = None
+    # ENFORCED at decision time: a human approver's IdP groups must intersect
+    # these (admins bypass). Empty = any approver.
+    approver_groups: list[str] = Field(default_factory=list,
+                                       max_length=LIST_MAX)
+    # Dual control (four-eyes), ENFORCED at decision time: the first
+    # approval endorses (the approval stays pending), a DIFFERENT reviewer
+    # must give the second; implies a human gate whatever the mode says.
+    require_second_approval: bool = False
+    # sampled mode only: 1-in-N proposals routed to a human (deterministic
+    # on the approval_id, provable from the chain). Ignored otherwise.
+    sample_n: int | None = Field(default=None, ge=2, le=1_000_000)
+    # server-authored risk metadata the console shows and bulk approval
+    # is constrained on: risk ∈ low/medium/high/critical (None = derived
+    # from reversible/dual control), blast_radius = what this action can
+    # reach, in the admin's words ("one order", "every customer in EU")
+    risk: str | None = Field(default=None, max_length=16)
+    blast_radius: str | None = Field(default=None, max_length=ID_MAX)
+
+    @field_validator("risk")
+    @classmethod
+    def _known_risk(cls, v):
+        if v is not None and v not in ("low", "medium", "high", "critical"):
+            raise ValueError("risk must be one of low, medium, high, critical")
+        return v
+    # SEED values, NOT gate-enforced by the service: exposed via GET /api/policy
+    # so a framework bridge (drangue Guardrails, the MCP gate policy) can seed
+    # its own per-tool allow/deny. Documented so the audit never records a
+    # gate control the service silently ignores.
+    allow: list[str] = Field(default_factory=list, max_length=LIST_MAX)
+    deny: list[str] = Field(default_factory=list, max_length=LIST_MAX)
+    reason: str = Field(default="", max_length=REASON_MAX)
+
+
+class Promote(BaseModel):
+    """POST /api/rollout/{action}/promote — move an action's mode (F21)."""
+    mode: str = Field(max_length=ID_MAX)
+    reason: str = Field(default="", max_length=REASON_MAX)
+
+
+class BudgetRule(BaseModel):
+    """PUT /api/budgets/{scope}/{key} — set a budget/quota (F23)."""
+    window: str = Field(max_length=ID_MAX)  # validated in the route
+    on_exceed: str = Field(max_length=ID_MAX)  # gate | deny
+    max_usd: float | None = Field(default=None, ge=0)
+    max_tokens: int | None = Field(default=None, ge=0)
+    reason: str = Field(default="", max_length=REASON_MAX)
+
+
+class EvalProfile(BaseModel):
+    """POST /api/evals — ingest a drangue eval profile (F23)."""
+    agent: str = Field(min_length=1, max_length=ID_MAX)
+    version: str = Field(min_length=1, max_length=ID_MAX)
+    profile: dict = Field(default_factory=dict)
+    scenarios: list = Field(default_factory=list, max_length=LIST_MAX)
+
+    @field_validator("profile")
+    @classmethod
+    def _bounded_profile(cls, v):
+        return bounded_json(v, what="profile")
+
+    @field_validator("scenarios")
+    @classmethod
+    def _bounded_scenarios(cls, v):
+        return bounded_json(v, what="scenarios")
+
+
+class GateDecision(BaseModel):
+    """POST /api/gate — record a deploy-gate decision (F23)."""
+    agent: str = Field(min_length=1, max_length=ID_MAX)
+    version: str = Field(min_length=1, max_length=ID_MAX)
+    passed: bool
+    baseline_version: str | None = Field(default=None, max_length=ID_MAX)
+    blocks: list = Field(default_factory=list, max_length=LIST_MAX)
+    reason: str = Field(default="", max_length=REASON_MAX)
+
+    @field_validator("blocks")
+    @classmethod
+    def _bounded_blocks(cls, v):
+        return bounded_json(v, what="blocks")
+
+
+class GateOverride(BaseModel):
+    """POST /api/gate/{agent}/{version}/override (admin) (F23)."""
+    reason: str = Field(min_length=1, max_length=REASON_MAX)

app/security.py

@@ -0,0 +1,203 @@
+"""Transport and abuse hardening: the posture a deployment gets without
+having to know to ask for it.
+
+- **Secure cookies.** With an https public URL (TLS terminates at the
+  ingress) — or PRIMARYPATH_SECURE_COOKIES=1 — session and login-flow
+  cookies are `Secure` and carry the `__Host-` prefix (Path=/, no Domain,
+  so a sibling host cannot plant one). Plain http keeps the bare names
+  for loopback evaluation.
+- **Headers on every response.** An explicit Content-Security-Policy
+  (script-src 'self' plus the hash of each inline script the built
+  console ships, so nothing else executes), frame-ancestors 'none' and
+  X-Frame-Options DENY, nosniff, a strict Referrer-Policy, and HSTS when
+  the deployment is secure.
+- **Request-body limit.** Bodies over PRIMARYPATH_MAX_BODY_BYTES are
+  refused with 413 before a handler sees them (Content-Length up front;
+  chunked bodies are bounded while they stream).
+- **Session-secret strength.** With OIDC on, a secret shorter than
+  PRIMARYPATH_SESSION_SECRET_MIN_LENGTH refuses to start.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import re
+from collections.abc import Sequence
+
+_INLINE_SCRIPT = re.compile(
+    r"<script(?![^>]*\bsrc=)[^>]*>(.*?)</script>", re.DOTALL | re.IGNORECASE)
+
+
+def is_secure(settings) -> bool:
+    if settings.secure_cookies is not None:
+        return bool(settings.secure_cookies)
+    return str(settings.public_url or "").lower().startswith("https://")
+
+
+def cookie_name(base: str, settings) -> str:
+    """`__Host-` binds the cookie to this exact host over https only."""
+    return f"__Host-{base}" if is_secure(settings) else base
+
+
+def cookie_kwargs(settings) -> dict:
+    return {"httponly": True, "samesite": "lax", "path": "/",
+            "secure": is_secure(settings)}
+
+
+def inline_script_hashes(html: str) -> list[str]:
+    """CSP 'sha256-...' sources for every inline <script> in the served
+    index, so the console's own bootstrap runs and nothing injected does."""
+    out = []
+    for body in _INLINE_SCRIPT.findall(html):
+        digest = hashlib.sha256(body.encode("utf-8")).digest()
+        out.append(f"'sha256-{base64.b64encode(digest).decode()}'")
+    return out
+
+
+def build_csp(settings, script_hashes: Sequence[str] = ()) -> str:
+    if settings.csp:
+        return settings.csp
+    script_src = " ".join(["'self'", *script_hashes])
+    return ("default-src 'self'; "
+            f"script-src {script_src}; "
+            # React sets styles via CSSOM (allowed without unsafe-inline);
+            # the bundled CSS is 'self'. 'unsafe-inline' here covers
+            # style attributes in markup only — scripts stay strict.
+            "style-src 'self' 'unsafe-inline'; "
+            "img-src 'self' data:; font-src 'self'; connect-src 'self'; "
+            "object-src 'none'; base-uri 'self'; form-action 'self'; "
+            "frame-ancestors 'none'")
+
+
+def security_headers(settings, csp: str) -> list[tuple[bytes, bytes]]:
+    headers = [
+        (b"content-security-policy", csp.encode()),
+        (b"x-frame-options", b"DENY"),
+        (b"x-content-type-options", b"nosniff"),
+        (b"referrer-policy", b"strict-origin-when-cross-origin"),
+        (b"permissions-policy",
+         b"camera=(), microphone=(), geolocation=(), payment=()"),
+        (b"cross-origin-opener-policy", b"same-origin"),
+    ]
+    if is_secure(settings):
+        headers.append((b"strict-transport-security",
+                        b"max-age=31536000; includeSubDomains"))
+    return headers
+
+
+def check_session_secret(settings) -> None:
+    """Refuse a guessable cookie-signing secret on the human plane."""
+    if not settings.oidc_issuer or not settings.session_secret:
+        return
+    n = settings.session_secret_min_length
+    if len(settings.session_secret) < n:
+        raise RuntimeError(
+            f"PRIMARYPATH_SESSION_SECRET must be at least {n} characters "
+            f"(got {len(settings.session_secret)}); generate one with "
+            f"`python -c 'import secrets; print(secrets.token_urlsafe(48))'`")
+
+
+_LOOPBACK_HOSTS = ("127.0.0.1", "localhost", "::1", "[::1]")
+
+
+def check_transport_posture(settings) -> None:
+    """The human plane over plain http off loopback would hand out
+    non-Secure session cookies: refuse unless the operator explicitly
+    turned the secure posture off (PRIMARYPATH_SECURE_COOKIES=0), which is
+    visible in /api/admin/config. Loopback (dev with a local IdP) is fine."""
+    if not settings.oidc_issuer or settings.secure_cookies is not None:
+        return
+    url = str(settings.public_url or "")
+    host = url.split("://", 1)[-1].split("/", 1)[0].split(":")[0].lower()
+    if url.lower().startswith("https://") or host in _LOOPBACK_HOSTS:
+        return
+    raise RuntimeError(
+        f"PRIMARYPATH_PUBLIC_URL is {url!r}: OIDC sessions would be set with "
+        "non-Secure cookies over plain http. Set it to the https URL your "
+        "TLS terminator serves, or set PRIMARYPATH_SECURE_COOKIES=0 to "
+        "accept that explicitly (evaluation only).")
+
+
+class SecurityHeadersMiddleware:
+    """Pure ASGI: add the headers to every http response (never overriding
+    one a handler set)."""
+
+    def __init__(self, app, settings, csp: str):
+        self.app = app
+        self.headers = security_headers(settings, csp)
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] != "http":
+            return await self.app(scope, receive, send)
+
+        async def send_with_headers(message):
+            if message["type"] == "http.response.start":
+                present = {k.lower() for k, _ in message.get("headers", [])}
+                extra = [(k, v) for k, v in self.headers if k not in present]
+                message = {**message,
+                           "headers": [*message.get("headers", []), *extra]}
+            await send(message)
+
+        await self.app(scope, receive, send_with_headers)
+
+
+class BodyLimitMiddleware:
+    """Pure ASGI: 413 for a body over `max_bytes`. A declared
+    Content-Length is refused before any byte is read; an undeclared
+    (chunked) body is read up to the limit and refused past it, before
+    the handler runs."""
+
+    def __init__(self, app, max_bytes: int):
+        self.app = app
+        self.max_bytes = max_bytes
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] != "http" or self.max_bytes <= 0:
+            return await self.app(scope, receive, send)
+        length = None
+        for k, v in scope.get("headers", []):
+            if k == b"content-length":
+                try:
+                    length = int(v)
+                except ValueError:
+                    length = None
+        if length is not None and length > self.max_bytes:
+            return await self._reject(send)
+        if length is not None:
+            return await self.app(scope, receive, send)
+
+        # undeclared length: bound it while buffering
+        chunks: list[bytes] = []
+        total = 0
+        while True:
+            message = await receive()
+            if message["type"] != "http.request":
+                break
+            body = message.get("body", b"")
+            total += len(body)
+            if total > self.max_bytes:
+                return await self._reject(send)
+            chunks.append(body)
+            if not message.get("more_body"):
+                break
+        buffered = b"".join(chunks)
+        replayed = False
+
+        async def replay():
+            nonlocal replayed
+            if not replayed:
+                replayed = True
+                return {"type": "http.request", "body": buffered,
+                        "more_body": False}
+            return await receive()
+
+        await self.app(scope, replay, send)
+
+    async def _reject(self, send):
+        body = json.dumps({"error": "request body too large",
+                           "max_bytes": self.max_bytes}).encode()
+        await send({"type": "http.response.start", "status": 413,
+                    "headers": [(b"content-type", b"application/json"),
+                                (b"content-length", str(len(body)).encode())]})
+        await send({"type": "http.response.body", "body": body})