primarypath-server 1.0.0__py3-none-any.whl

app/routes/admin.py

@@ -0,0 +1,312 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from pydantic import BaseModel, Field
+
+from .. import __version__
+from ..auth import (
+    admin_read_activity_enabled,
+    get_identity,
+    require_admin,
+    resolve_tenant,
+)
+from ..ledger.projection import rebuild_projection
+from ..ledger.store import DEFAULT_AGENT
+from ..security import is_secure
+
+router = APIRouter(prefix="/api/admin", dependencies=[Depends(require_admin)])
+
+# the advertised integrations and the SDK ranges each shim is contract-
+# tested on (pins live in the shim pyprojects; this is what the console
+# and the readiness checklist state to the operator)
+SUPPORTED_SDKS = {
+    "openai-agents": ">=0.22,<1",
+    "langgraph": ">=1,<2",
+    "claude-agent-sdk": ">=0.2,<1",
+    "mcp": ">=1.23,<2",
+}
+
+
+class BackupVerified(BaseModel):
+    note: str = Field(default="", max_length=1024)
+
+
+class IssueToken(BaseModel):
+    kind: str  # service | admin
+    label: str = Field(default="", max_length=200)
+    # F24, service tokens only: the agent this token speaks for and the
+    # unit it stamps — the admin maps an agent to a unit right here
+    agent: str | None = Field(default=None, max_length=200)
+    unit: str | None = Field(default=None, max_length=200)
+
+
+class ReadActivity(BaseModel):
+    """PUT /api/admin/read-activity — the separation-of-duties toggle."""
+    enabled: bool
+    reason: str = ""
+
+
+async def _admin_actor(request: Request) -> str:
+    identity = await get_identity(request)
+    if identity:
+        return identity.get("email") or identity["subject"]
+    return "admin-token"
+
+
+async def _record_admin_action(request: Request, action: str,
+                               detail: dict) -> None:
+    """Administering the governance system is itself a chained, provable
+    event: the control plane audits its own operators. Lands in the
+    operator's tenant chain (resolved from the auth context, F20)."""
+    await request.app.state.ledger.append(
+        "admin_action",
+        {"action": action, "by": await _admin_actor(request), **detail},
+        tenant=await resolve_tenant(request))
+
+
+@router.post("/rebuild-projection")
+async def rebuild(request: Request):
+    """Re-fold the caller's tenant's projections from the log, proving they
+    are pure caches. Tenant-scoped: one tenant's admin never rebuilds
+    another tenant's cache (the F20/FOLLOWUPS seam, closed)."""
+    tenant = await resolve_tenant(request)
+    async with request.app.state.pool.connection() as conn:
+        async with conn.transaction():
+            await rebuild_projection(conn, tenant=tenant)
+    await _record_admin_action(request, "rebuild_projection", {})
+    return {"ok": True}
+
+
+@router.post("/rotate-key")
+async def rotate_key(request: Request):
+    """Rotate the Ed25519 signing key; old bundles keep verifying via the ring."""
+    signer = request.app.state.signer
+    if signer is None:
+        raise HTTPException(400, "signing is not configured")
+    old = signer.key_id
+    new = signer.rotate()
+    await _record_admin_action(request, "rotate_key",
+                               {"old_key_id": old, "new_key_id": new})
+    return {"key_id": new}
+
+
+@router.get("/settings")
+async def settings_summary(request: Request):
+    """What is configured (never the secrets themselves)."""
+    s = request.app.state.settings
+    return {
+        "oidc": bool(s.oidc_issuer),
+        "rbac": s.rbac_enabled,
+        "slack": bool(s.slack_bot_token and s.slack_channel),
+        "service_token": bool(s.service_token),
+        "signing_key": bool(s.signing_key_path),
+    }
+
+
+# -- F22: the config console (admin-only, read-mostly, mutations audited) -----
+
+
+@router.get("/config")
+async def config(request: Request):
+    """How the system is wired: integrations, chat surfaces, SIEM, signing
+    key ring — never a secret value. The registry lists the
+    frameworks that have checked in via ingested run events per tenant."""
+    s = request.app.state.settings
+    tenant = await resolve_tenant(request)
+    signer = request.app.state.signer
+
+    # frameworks that have actually governed a run in this tenant
+    async with request.app.state.pool.connection() as conn:
+        cur = await conn.execute(
+            "SELECT DISTINCT payload_json->>'framework' FROM events "
+            "WHERE tenant_id = %s AND type = 'approval_requested' "
+            "AND payload_json->>'framework' IS NOT NULL", (tenant,))
+        frameworks = sorted(r[0] for r in await cur.fetchall())
+
+    async with request.app.state.pool.connection() as conn:
+        cur = await conn.execute(
+            "SELECT count(*) FILTER (WHERE status = 'pending'), "
+            "count(*) FILTER (WHERE status = 'dead') "
+            "FROM webhook_outbox WHERE tenant_id = %s", (tenant,))
+        wh_pending, wh_dead = await cur.fetchone()
+        cur = await conn.execute(
+            "SELECT value, updated_ts_ms FROM config_view "
+            "WHERE tenant_id = %s AND key = 'backup_verified'", (tenant,))
+        backup = await cur.fetchone()
+
+    return {
+        # the eval-to-production seam, visible: the console's readiness
+        # checklist is driven from here, never from guesses
+        "insecure": bool(s.insecure),
+        # webhook durability: the outbox (pending = in flight or retrying,
+        # dead = exhausted retries, replayable)
+        "webhooks": {"pending": wh_pending, "dead": wh_dead,
+                     "secret": bool(s.webhook_secret),
+                     "attempts": s.webhook_attempts},
+        # the operator's attestation that a restore was exercised: the
+        # service cannot know, so the checklist asks and records the answer
+        "backups": {"verified_ts_ms": backup[1] if backup else None,
+                    "note": (backup[0] or {}).get("note") if backup else None},
+        # transport posture: Secure/__Host- cookies and HSTS follow an https
+        # public URL (or PRIMARYPATH_SECURE_COOKIES); visible, never silent
+        "transport": {"secure_cookies": is_secure(s), "hsts": is_secure(s),
+                      "public_url": s.public_url,
+                      "max_body_bytes": s.max_body_bytes,
+                      "agent_write_rate_per_minute":
+                          s.agent_write_rate_per_minute},
+        "integrations": {
+            "frameworks_seen": frameworks,  # drangue, mcp, langgraph, ...
+            "slack": bool(s.slack_bot_token and s.slack_channel),
+            "teams": bool(s.teams_app_id and s.teams_conversation_id),
+            # the framework SDK versions the shims are contract-tested
+            # against (server/tests/test_contract_sdks.py, run in CI)
+            "pinned": SUPPORTED_SDKS,
+        },
+        "auth": {
+            "oidc": bool(s.oidc_issuer), "rbac": s.rbac_enabled,
+            "service_token_env": bool(s.service_token),
+            "admin_token_env": bool(s.admin_token),
+        },
+        "siem": {"sink": s.siem,
+                 "configured": s.siem != "none"},
+        # F23: the no-budget cost posture is a client risk choice — surfaced
+        # here so it is visible, never silent.
+        "cost": {"default_posture": s.cost_default_posture,
+                 "default_on_exceed": s.cost_default_on_exceed,
+                 "prices_configured": bool(s.model_prices)},
+        "signing": {"backend": s.signing_backend,
+                    "key_id": signer.key_id if signer else None,
+                    "ring": signer.pubring() if signer else {},
+                    "backends": request.app.state.signers.backends()},
+        # execution grants ride the signing key: minted only when it exists
+        "grants": {"enabled": signer is not None, "ttl_s": s.grant_ttl_s},
+        # F24: the separation-of-duties posture, visible, never silent
+        "admin_can_read_activity": await admin_read_activity_enabled(
+            request, tenant),
+        "version": __version__,
+    }
+
+
+@router.get("/tokens")
+async def list_tokens(request: Request):
+    """Issued tokens: metadata only, never the token or its hash."""
+    return await request.app.state.tokens.list(
+        tenant=await resolve_tenant(request))
+
+
+@router.post("/tokens")
+async def issue_token(request: Request, body: IssueToken):
+    """Issue a service (agent plane) or admin (operator plane) token. The
+    plaintext is returned ONCE and never recoverable. Kinds stay distinct —
+    the token-split invariant. Audited.
+
+    A service token may carry {agent, unit}: the agent-to-unit map, stamped
+    server-side onto everything the agent writes (F24). Mapping an agent is
+    itself a governance event (agent_registered)."""
+    if body.kind not in ("service", "admin"):
+        raise HTTPException(400, "kind must be 'service' or 'admin'")
+    if body.kind != "service" and (body.agent or body.unit):
+        raise HTTPException(400, "agent/unit apply to service tokens only")
+    if body.unit and not body.agent:
+        raise HTTPException(400, "unit requires an agent")
+    if body.agent == DEFAULT_AGENT:
+        # "default" is the implicit agent of UNPINNED credentials (the env
+        # token, open dev mode): a token pinned to that name would share
+        # its chain with them and be indistinguishable in the audit. The
+        # ledger treats such a token as pinned regardless (pin-ness is
+        # credential metadata), but the name is refused up front.
+        raise HTTPException(
+            400, f"'{DEFAULT_AGENT}' is the implicit agent of unpinned "
+                 f"credentials; pin the token to a real agent name")
+    tenant = await resolve_tenant(request)
+    by = await _admin_actor(request)
+    token_id, plaintext = await request.app.state.tokens.issue(
+        body.kind, body.label, by=by, tenant=tenant,
+        agent_id=body.agent, unit=body.unit)
+    detail = {"token_id": token_id, "kind": body.kind, "label": body.label}
+    if body.agent:
+        detail["agent"] = body.agent
+        detail["unit"] = body.unit
+    await _record_admin_action(request, "issue_token", detail)
+    if body.agent and body.unit:
+        await request.app.state.agents.register(
+            body.agent, body.unit, by=by,
+            reason=f"service token {token_id} issued", tenant=tenant)
+    return {"id": token_id, "kind": body.kind, "token": plaintext,
+            "agent": body.agent, "unit": body.unit,
+            "note": "store this now; it is not recoverable"}
+
+
+@router.get("/read-activity")
+async def get_read_activity(request: Request):
+    """The separation-of-duties posture: may the admin role read agent
+    activity?"""
+    tenant = await resolve_tenant(request)
+    return {"enabled": await admin_read_activity_enabled(request, tenant)}
+
+
+@router.put("/read-activity")
+async def set_read_activity(request: Request, body: ReadActivity):
+    """Flip admin_can_read_activity — an event-sourced governance event, so
+    enabling break-glass is itself provable (and survives a projection
+    rebuild)."""
+    tenant = await resolve_tenant(request)
+    await request.app.state.ledger.append(
+        "admin_action",
+        {"action": "set_config", "key": "admin_can_read_activity",
+         "value": body.enabled, "by": await _admin_actor(request),
+         "reason": body.reason},
+        tenant=tenant)
+    return {"enabled": body.enabled}
+
+
+@router.delete("/tokens/{token_id}")
+async def revoke_token(request: Request, token_id: str):
+    """Revoke an issued token (tenant-scoped). Audited."""
+    tenant = await resolve_tenant(request)
+    ok = await request.app.state.tokens.revoke(token_id, tenant)
+    if not ok:
+        raise HTTPException(404, "unknown or already-revoked token")
+    await _record_admin_action(request, "revoke_token", {"token_id": token_id})
+    return {"ok": True}
+
+
+# -- webhook outbox (F02): what was delivered, what is waiting, what died ----
+
+
+@router.get("/webhooks")
+async def list_webhooks(request: Request, status: str | None = None,
+                        limit: int = 100):
+    """Delivery rows, newest first: attempts, next retry, last error.
+    `status` ∈ pending/delivered/dead."""
+    if status is not None and status not in ("pending", "delivered", "dead"):
+        raise HTTPException(400, "status must be pending, delivered or dead")
+    return await request.app.state.webhooks.list(
+        tenant=await resolve_tenant(request), status=status,
+        limit=max(1, min(limit, 500)))
+
+
+@router.post("/webhooks/{delivery_id}/replay")
+async def replay_webhook(request: Request, delivery_id: int):
+    """Re-queue a dead (or delivered) row. Audited."""
+    tenant = await resolve_tenant(request)
+    ok = await request.app.state.webhooks.replay(delivery_id, tenant)
+    if not ok:
+        raise HTTPException(404, "unknown delivery, or still pending")
+    await _record_admin_action(request, "replay_webhook",
+                               {"delivery_id": delivery_id})
+    return {"ok": True}
+
+
+@router.put("/backup-verified")
+async def backup_verified(request: Request, body: BackupVerified):
+    """The operator attests a restore was exercised (date + note). An
+    audited governance event; the readiness checklist reads it back."""
+    tenant = await resolve_tenant(request)
+    await request.app.state.ledger.append(
+        "admin_action",
+        {"action": "set_config", "key": "backup_verified",
+         "value": {"note": body.note}, "by": await _admin_actor(request),
+         "reason": "backup restore verified"},
+        tenant=tenant)
+    return {"ok": True}

app/routes/agents.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from pydantic import BaseModel, Field
+
+from ..agents import CAPTURES, SIGNING_BACKENDS
+from ..auth import (
+    activity_scope,
+    admin_read_activity_enabled,
+    get_identity,
+    require_admin,
+    require_reader,
+    resolve_tenant,
+)
+
+router = APIRouter(prefix="/api")
+
+
+class AgentUpdate(BaseModel):
+    """PUT /api/agents/{agent} — map an agent to a unit and/or set its
+    evidence profile. Every change is an audited governance event."""
+    unit: str | None = Field(default=None, max_length=200)
+    signing_backend: str | None = None  # default | none | file | kms
+    key_id: str | None = None
+    capture: str | None = None  # none | decisions | full
+    retention_days: int | None = Field(default=None, ge=0)
+    reason: str = ""
+
+
+async def _actor(request: Request) -> str:
+    identity = await get_identity(request)
+    if identity:
+        return identity.get("email") or identity["subject"]
+    return "admin-token"
+
+
+@router.get("/agents", dependencies=[Depends(require_admin)])
+async def list_agents(request: Request):
+    """Every agent with its unit and evidence profile (admin). The registry
+    is metadata about the system, not agent activity — the operator manages
+    the map without reading the work."""
+    return await request.app.state.agents.agents(
+        tenant=await resolve_tenant(request))
+
+
+@router.put("/agents/{agent}", dependencies=[Depends(require_admin)])
+async def update_agent(request: Request, agent: str, body: AgentUpdate):
+    """Set an agent's unit and/or evidence profile -> agent_registered /
+    evidence_set on the governance chain."""
+    if body.signing_backend is not None \
+            and body.signing_backend not in SIGNING_BACKENDS:
+        raise HTTPException(
+            400, f"signing_backend must be one of {SIGNING_BACKENDS}")
+    if body.capture is not None and body.capture not in CAPTURES:
+        raise HTTPException(400, f"capture must be one of {CAPTURES}")
+
+    tenant = await resolve_tenant(request)
+    registry = request.app.state.agents
+    by = await _actor(request)
+    sent = body.model_fields_set
+
+    if "unit" in sent:
+        await registry.register(agent, body.unit, by=by, reason=body.reason,
+                                tenant=tenant)
+    if sent & {"signing_backend", "key_id", "capture", "retention_days"}:
+        current = await registry.evidence_for(agent, tenant)
+        await registry.set_evidence(
+            agent,
+            signing_backend=body.signing_backend
+            or current["signing_backend"],
+            key_id=body.key_id if "key_id" in sent else current["key_id"],
+            capture=body.capture or current["capture"],
+            retention_days=body.retention_days if "retention_days" in sent
+            else current["retention_days"],
+            by=by, reason=body.reason, tenant=tenant)
+
+    return {
+        "agent": agent,
+        "unit": await registry.unit_of(agent, tenant),
+        "evidence": await registry.evidence_for(agent, tenant),
+    }
+
+
+@router.get("/viewer", dependencies=[Depends(require_reader)])
+async def viewer(request: Request):
+    """The caller's need-to-know context, for the console: which units it
+    can see, whether the admin separation-of-duties lock applies, and
+    whether reading as an admin would be recorded (break-glass)."""
+    tenant = await resolve_tenant(request)
+    # scope only describes what a read WOULD see; it is not itself an
+    # activity read, so it never trips the break-glass record
+    scope = await activity_scope(request, record=False)
+    can_read = await admin_read_activity_enabled(request, tenant)
+    if scope is None:
+        return {"units": None, "visible_units": None, "units_in_force": False,
+                "role": None, "locked": False,
+                "admin_can_read_activity": can_read}
+    known = await request.app.state.agents.known_units(tenant)
+    visible = sorted(scope["units"] & known)
+    # locked = separation of duties is actually shutting this admin out:
+    # units are in force in this tenant and none of theirs match
+    locked = scope["locked"]
+    if scope.get("role") == "admin" and not can_read and not locked:
+        locked = bool(known) and not visible
+    return {"units": sorted(scope["units"]),
+            "visible_units": visible,
+            "units_in_force": bool(known),
+            "agent": scope.get("agent"),
+            "role": scope.get("role"),
+            "locked": locked,
+            "admin_can_read_activity": can_read}