primarypath-server 1.0.0__py3-none-any.whl

app/routes/audit.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+import csv
+import hashlib
+import io
+import json
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi.responses import PlainTextResponse
+
+from ..auth import (
+    activity_scope,
+    get_identity,
+    require_admin,
+    require_console_reader,
+    require_reader,
+    resolve_tenant,
+    scope_units,
+    visible_to,
+)
+from ..ledger.hashing import canonical
+from ..ledger.store import DEFAULT_AGENT, GOVERNANCE_CHAIN
+from ..signing import SigningUnavailable
+
+router = APIRouter(prefix="/api/audit")
+
+# SIEM CSV columns, stable and documented: one row per event. F24 appended
+# chain_id/agent/unit; the original seven stay in place.
+CSV_COLUMNS = ["seq", "ts_ms", "type", "run_id", "approval_id", "actor",
+               "hash", "chain_id", "agent", "unit"]
+
+
+def _csv_rows(w, chain_id: str, events: list[dict]) -> None:
+    for e in events:
+        p = json.loads(e["payload"]) if isinstance(e["payload"], str) else e["payload"]
+        w.writerow([e["seq"], e["ts_ms"], e["type"],
+                    p.get("run_id", ""), p.get("approval_id", ""),
+                    p.get("reviewer", "") or p.get("by", ""), e["hash"],
+                    chain_id, e.get("agent_id", ""), e.get("unit", "")])
+
+
+def bundle_to_csv(bundle: dict) -> str:
+    out = io.StringIO()
+    w = csv.writer(out)
+    w.writerow(CSV_COLUMNS)
+    if "chains" in bundle:
+        for c in bundle["chains"]:
+            _csv_rows(w, c["chain_id"], c["events"])
+    else:
+        _csv_rows(w, bundle.get("chain_id", DEFAULT_AGENT), bundle["events"])
+    return out.getvalue()
+
+
+async def _exported_by(request: Request) -> str:
+    identity = await get_identity(request)
+    if identity:
+        return identity.get("email") or identity["subject"]
+    return "service"
+
+
+async def _chain_readable(request: Request, read_scope, agent: str,
+                          tenant: str) -> bool:
+    """An agent's whole chain is readable when the agent's unit is in the
+    caller's scope and so is every unit stamped on the chain. An agent
+    moved from one unit to another holds both units' work; a bundle cannot
+    drop events and still verify, so it goes only to a reader of both (B23)."""
+    unit = await request.app.state.agents.unit_of(agent, tenant)
+    if not visible_to(read_scope, agent, unit):
+        return False
+    units = scope_units(read_scope)
+    if units is None:
+        return True
+    return not await request.app.state.ledger.chain_has_unit_outside(
+        tenant, agent, units)
+
+
+@router.get("/export")
+async def export(request: Request, format: str = "json",
+                 agent: str | None = None, scope: str | None = None):
+    """The signed, portable audit artifact.
+
+    Auth is per shape (the brief makes audit-and-verify available to every
+    authenticated role, F24 scopes it): a single agent's chain is readable
+    by approver+ sessions and the admin token, gated by the caller's units
+    below; the governance chain and the whole log stay on the admin plane.
+    The bare agent service token can pull none of them.
+
+    Three shapes (F24):
+    - ?agent=A            one agent's chain, signed under ITS evidence
+                          profile (the auditor's unit of verification)
+    - ?scope=governance   the control-plane chain (who changed which
+                          control) — no agent activity lives there
+    - (no params)         the whole log: every chain, each independently
+                          verifiable; there is no single cross-chain hash
+
+    Deliberately side-effecting despite being a GET: every export appends an
+    audit_exported provenance event (who pulled the record, when, to what
+    head). Pulling the audit trail is itself an auditable act — the
+    provenance lands on the governance chain. Safe to repeat; each call is
+    its own provenance record. Documented in the API reference."""
+    if agent is not None and scope is not None:
+        raise HTTPException(400, "pass either agent or scope, not both")
+    if agent is not None:
+        await require_console_reader(request)
+    else:
+        await require_admin(request)
+
+    ledger = request.app.state.ledger
+    tenant = await resolve_tenant(request)
+
+    if scope == "governance":
+        bundle = await ledger.export_bundle(tenant, chain=GOVERNANCE_CHAIN)
+        bundle["scope"] = "governance"
+        # the sampled-mode pick is an HMAC keyed by this salt; disclosing
+        # it here (admin plane — the agent token cannot reach an export)
+        # lets an auditor recompute every routing decision offline
+        bundle["sampling_salt"] = \
+            await request.app.state.policy.sampling_salt(tenant)
+        signer = request.app.state.signer
+        if signer is not None:
+            bundle = signer.sign_bundle(bundle)
+        exported_scope, head_hash = "governance", bundle["head"]
+    elif agent is not None:
+        # an agent's chain is agent activity: the need-to-know gate applies
+        # to the operator here exactly as it does in the inbox
+        read_scope = await activity_scope(request)
+        if not await _chain_readable(request, read_scope, agent, tenant):
+            raise HTTPException(404, f"unknown agent {agent}")
+        profile = await request.app.state.agents.evidence_for(agent, tenant)
+        bundle = await ledger.export_bundle(tenant, chain=agent)
+        bundle["scope"] = f"agent:{agent}"
+        bundle["agent"] = agent
+        bundle["evidence"] = profile
+        if (profile["source"] == "default"
+                or profile["signing_backend"] == "default"):
+            # no explicit evidence demand, or an explicit "deployment
+            # default": the default signer
+            signer = request.app.state.signer
+        else:
+            try:
+                signer = request.app.state.signers.for_profile(profile)
+            except SigningUnavailable as e:
+                raise HTTPException(409, str(e)) from None
+        if signer is not None:
+            bundle = signer.sign_bundle(bundle)
+        exported_scope, head_hash = f"agent:{agent}", bundle["head"]
+    else:
+        bundle = await ledger.export_full(tenant)
+        bundle["sampling_salt"] = \
+            await request.app.state.policy.sampling_salt(tenant)
+        signer = request.app.state.signer
+        if signer is not None:
+            bundle = signer.sign_chains(bundle)
+        heads = {c["chain_id"]: c["head"] for c in bundle["chains"]}
+        # a single commitment to every chain head, for the provenance event
+        head_hash = hashlib.sha256(
+            canonical(heads).encode("utf-8")).hexdigest()
+        exported_scope = "full"
+
+    await ledger.append("audit_exported", {
+        "head_hash": head_hash, "by": await _exported_by(request),
+        "scope": exported_scope}, tenant=tenant)
+    if format == "csv":
+        return PlainTextResponse(bundle_to_csv(bundle), media_type="text/csv")
+    return bundle
+
+
+@router.get("/chains", dependencies=[Depends(require_console_reader)])
+async def chains(request: Request):
+    """Every chain the caller may verify, with its length and head: the
+    audit page's agent picker. Chain heads are metadata (verification
+    anchors), not activity content, but volume is information too: for a
+    non-admin the list is unit-scoped like the inbox, and the governance
+    chain (the admin's plane) is omitted."""
+    tenant = await resolve_tenant(request)
+    registry = request.app.state.agents
+    read_scope = await activity_scope(request)
+    is_admin = True
+    try:
+        await require_admin(request)
+    except HTTPException:
+        is_admin = False
+    out = []
+    for c in await request.app.state.ledger.chains(tenant):
+        entry = dict(c)
+        if c["chain_id"] == GOVERNANCE_CHAIN:
+            if not is_admin:
+                continue
+            entry["kind"] = "governance"
+        else:
+            unit = await registry.unit_of(c["chain_id"], tenant)
+            if not is_admin and not await _chain_readable(
+                    request, read_scope, c["chain_id"], tenant):
+                continue
+            entry["kind"] = "agent"
+            entry["unit"] = unit
+            entry["evidence"] = await registry.evidence_for(
+                c["chain_id"], tenant)
+        out.append(entry)
+    return out
+
+
+@router.get("/keys", dependencies=[Depends(require_reader)])
+async def keys(request: Request):
+    """The public-key ring: pin these to verify old and new bundles. Spans
+    every configured backend (file and KMS/HSM)."""
+    signer = request.app.state.signer
+    ring = dict(request.app.state.signers.pubring())
+    if signer is not None:
+        ring.update(signer.pubring())
+    return {"keys": ring,
+            "current": signer.key_id if signer else None,
+            "backends": request.app.state.signers.backends()}

app/routes/costgov.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+
+from ..auth import (
+    get_identity,
+    require_admin,
+    require_agent,
+    require_agent_binding,
+    require_console_reader,
+    require_reader,
+    resolve_tenant,
+)
+from ..costgov import ON_EXCEED, SCOPES, WINDOWS, GateAlreadyDecided
+from ..schemas import BudgetRule, EvalProfile, GateDecision, GateOverride
+
+router = APIRouter(prefix="/api")
+
+
+def _actor(identity: dict | None) -> str:
+    if identity:
+        return identity.get("email") or identity["subject"]
+    return "admin-token"
+
+
+async def _agent_actor(request: Request) -> str:
+    identity = await get_identity(request)
+    if identity:
+        return identity.get("email") or identity["subject"]
+    return "service-token"
+
+
+# -- budgets & spend ----------------------------------------------------------
+
+
+@router.get("/budgets", dependencies=[Depends(require_reader)])
+async def get_budgets(request: Request):
+    """Current folded budgets for the tenant (approver+)."""
+    return await request.app.state.cost.current_budgets(
+        tenant=await resolve_tenant(request))
+
+
+@router.put("/budgets/{scope}/{key}")
+async def set_budget(request: Request, scope: str, key: str, body: BudgetRule,
+                     identity: dict | None = Depends(require_admin)):
+    """Set a budget/quota (admin). Appends an audited budget_set."""
+    if scope not in SCOPES:
+        raise HTTPException(400, f"scope must be one of {SCOPES}")
+    if body.window not in WINDOWS:
+        raise HTTPException(400, f"window must be one of {WINDOWS}")
+    if body.on_exceed not in ON_EXCEED:
+        raise HTTPException(400, f"on_exceed must be one of {ON_EXCEED}")
+    if body.max_usd is None and body.max_tokens is None:
+        raise HTTPException(400, "set max_usd and/or max_tokens")
+    return await request.app.state.cost.set_budget(
+        scope, key, window=body.window, on_exceed=body.on_exceed,
+        max_usd=body.max_usd, max_tokens=body.max_tokens,
+        by=_actor(identity), reason=body.reason,
+        tenant=await resolve_tenant(request))
+
+
+@router.get("/spend", dependencies=[Depends(require_reader)])
+async def get_spend(request: Request):
+    """Spend vs budget per scope, in-window, plus the routing mix (approver+)."""
+    return await request.app.state.cost.spend_report(
+        tenant=await resolve_tenant(request))
+
+
+# -- evals & deploy gates -----------------------------------------------------
+
+
+@router.post("/evals", dependencies=[Depends(require_agent)])
+async def record_eval(request: Request, body: EvalProfile):
+    """Ingest an eval profile as chained evidence (agent/service token).
+    Not re-scored — drangue's evaluate owns the maths."""
+    await require_agent_binding(request, body.agent)
+    tenant = await resolve_tenant(request)
+    await request.app.state.cost.record_eval(
+        body.agent, body.version, profile=body.profile,
+        scenarios=body.scenarios, by=await _agent_actor(request), tenant=tenant)
+    return {"ok": True}
+
+
+@router.post("/gate", dependencies=[Depends(require_agent)])
+async def record_gate(request: Request, body: GateDecision):
+    """Record a deploy-gate decision as a chained event (agent/service token,
+    e.g. the CI job). Returns the resulting verdict.
+
+    A decided (agent, version) is immutable on this plane: gate_view folds
+    last-write-wins, so re-recording would let any service-token holder
+    flip a failed gate to pass and bypass the admin override entirely. The
+    only way past a decided gate is POST .../override (admin, audited).
+    The check lives INSIDE the store's append transaction, so two racing
+    recorders cannot both slip past it."""
+    await require_agent_binding(request, body.agent)
+    tenant = await resolve_tenant(request)
+    try:
+        verdict = await request.app.state.cost.record_gate(
+            body.agent, body.version, passed=body.passed,
+            baseline_version=body.baseline_version, blocks=body.blocks,
+            by=await _agent_actor(request), reason=body.reason, tenant=tenant)
+    except GateAlreadyDecided as e:
+        raise HTTPException(
+            409, f"gate for {body.agent}@{body.version} is already decided "
+                 f"(passed={e.verdict['passed']}); an admin override is the "
+                 f"only way to change it") from None
+    return verdict
+
+
+@router.get("/gate/{agent}/{version}", dependencies=[Depends(require_reader)])
+async def gate_verdict(request: Request, agent: str, version: str):
+    """The latest gate verdict for CI (approver+ or service). 404 until a
+    gate decision has been recorded for this agent+version."""
+    verdict = await request.app.state.cost.gate_verdict(
+        agent, version, tenant=await resolve_tenant(request))
+    if verdict is None:
+        raise HTTPException(404, f"no gate decision for {agent}@{version}")
+    return verdict
+
+
+@router.post("/gate/{agent}/{version}/override")
+async def override_gate(request: Request, agent: str, version: str,
+                        body: GateOverride,
+                        identity: dict | None = Depends(require_admin)):
+    """Override a gate for a deploy (admin only). Appends a NEW gate_decision
+    with override=true and the required reason — who overrode what and why is
+    provable in the signed export."""
+    tenant = await resolve_tenant(request)
+    current = await request.app.state.cost.gate_verdict(agent, version, tenant)
+    if current is None:
+        # never fabricate a pass: there must be a recorded gate to override
+        raise HTTPException(404, f"no gate decision to override for "
+                                 f"{agent}@{version}")
+    return await request.app.state.cost.record_gate(
+        agent, version, passed=True,
+        baseline_version=current["baseline_version"],
+        blocks=current["blocks"],
+        by=_actor(identity), reason=body.reason, override=True, tenant=tenant)
+
+
+@router.get("/evals", dependencies=[Depends(require_console_reader)])
+async def eval_history(request: Request, agent: str | None = None,
+                       version: str | None = None, limit: int = 500,
+                       before: int | None = None):
+    """Eval + gate history (approver+ console; excludes the bare service
+    token — it can post evidence but not read the whole history back).
+    Newest first, cursor-paged: `before` = the last row's `id`."""
+    return await request.app.state.cost.history(
+        agent=agent, version=version, tenant=await resolve_tenant(request),
+        limit=limit, before=before)

app/routes/health.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, Request, Response
+from fastapi.responses import JSONResponse
+
+router = APIRouter()
+
+
+@router.get("/livez")
+async def livez() -> dict:
+    """Liveness: is the process serving? Deliberately touches nothing
+    else — a database outage must show up as pods going UNREADY
+    (/readyz), never as kubelet restarting healthy processes."""
+    from .. import __version__
+
+    return {"status": "ok", "version": __version__}
+
+
+@router.get("/healthz")
+async def healthz(request: Request) -> dict:
+    """The operator's one-line check: process + database ping. Not a
+    liveness probe (see /livez); readiness is /readyz."""
+    async with request.app.state.pool.connection() as conn:
+        await conn.execute("SELECT 1")
+    from .. import __version__
+
+    return {"status": "ok", "db": "ok", "version": __version__}
+
+
+@router.get("/readyz")
+async def readyz(request: Request):
+    async with request.app.state.pool.connection() as conn:
+        cur = await conn.execute("SELECT version_num FROM alembic_version")
+        row = await cur.fetchone()
+    current = row[0] if row else None
+    head = request.app.state.migration_head
+    signer = request.app.state.signer
+    body = {"status": "ok", "db": "ok", "migration": current,
+            "migration_head": head,
+            "signing": signer.key_id if signer else None}
+    if current != head:
+        # not ready until the schema is at head (the k8s migration Job's gate)
+        return JSONResponse({**body, "status": "waiting-for-migrations"},
+                            status_code=503)
+    return body
+
+
+@router.get("/metrics")
+async def metrics(request: Request):
+    from ..metrics import CONTENT_TYPE
+
+    body = await request.app.state.metrics.scrape(request.app.state.pool)
+    return Response(content=body, media_type=CONTENT_TYPE)

app/routes/policy.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+
+from ..auth import require_admin, require_reader, resolve_tenant
+from ..policy import MODES
+from ..schemas import PolicyRule, Promote
+
+router = APIRouter(prefix="/api")
+
+
+def _actor(identity: dict | None) -> str:
+    if identity:
+        return identity.get("email") or identity["subject"]
+    return "admin-token"
+
+
+@router.get("/policy", dependencies=[Depends(require_reader)])
+async def get_policy(request: Request):
+    """The current folded policy for the tenant (approver+ read)."""
+    return await request.app.state.policy.current_policy(
+        tenant=await resolve_tenant(request))
+
+
+@router.put("/policy/{action}")
+async def set_rule(request: Request, action: str, body: PolicyRule,
+                   identity: dict | None = Depends(require_admin)):
+    """Author a per-action rule (admin). Appends an audited policy_set."""
+    if body.mode not in MODES:
+        raise HTTPException(400, f"mode must be one of {MODES}")
+    return await request.app.state.policy.set_policy(
+        action, mode=body.mode, reversible=body.reversible,
+        requires_approval=body.requires_approval, allow=body.allow,
+        deny=body.deny, approver_groups=body.approver_groups,
+        require_second_approval=body.require_second_approval,
+        sample_n=body.sample_n, risk=body.risk,
+        blast_radius=body.blast_radius,
+        by=_actor(identity), reason=body.reason,
+        tenant=await resolve_tenant(request))
+
+
+@router.get("/rollout", dependencies=[Depends(require_reader)])
+async def get_rollout(request: Request):
+    """Per-action mode + track record + graduation recommendation."""
+    return await request.app.state.policy.rollout(
+        tenant=await resolve_tenant(request))
+
+
+@router.post("/rollout/{action}/promote")
+async def promote(request: Request, action: str, body: Promote,
+                  identity: dict | None = Depends(require_admin)):
+    """Promote/demote an action's mode (admin). Appends an audited
+    policy_set; never automatic. Carries the existing rule's other fields so
+    only the mode moves."""
+    if body.mode not in MODES:
+        raise HTTPException(400, f"mode must be one of {MODES}")
+    tenant = await resolve_tenant(request)
+    existing = await request.app.state.policy.policy_for(action, tenant)
+    return await request.app.state.policy.set_policy(
+        action, mode=body.mode,
+        reversible=existing["reversible"] if existing else False,
+        requires_approval=None,  # derive from the new mode
+        allow=existing["allow"] if existing else [],
+        deny=existing["deny"] if existing else [],
+        approver_groups=existing["approver_groups"] if existing else [],
+        # a mode move must never silently drop dual control or the rate
+        require_second_approval=(existing["require_second_approval"]
+                                 if existing else False),
+        sample_n=(existing.get("sample_n") or None) if existing else None,
+        risk=existing.get("risk") if existing else None,
+        blast_radius=existing.get("blast_radius") if existing else None,
+        by=_actor(identity), reason=body.reason, tenant=tenant)

app/routes/runs.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import json
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+
+from ..auth import (
+    activity_scope,
+    agent_pin,
+    require_agent,
+    require_reader,
+    resolve_agent,
+    resolve_tenant,
+    visible_to,
+)
+from ..faults import fault_point
+from ..idempotency import idempotency_of
+from ..ledger import IdempotencyMismatch, RunOwnedByAnotherAgent
+from ..schemas import RunEvents
+
+router = APIRouter(prefix="/api/runs")
+
+
+def _captured(events: list[dict], capture: str) -> list[dict]:
+    """The agent's evidence profile decides how deep run traces go (F24):
+    'full' keeps everything, 'decisions' keeps model decisions and run
+    lifecycle (arguments/results of ordinary tool chatter are dropped),
+    'none' records no run trace at all. Approvals are never affected —
+    the decision record is the product."""
+    if capture == "full":
+        return events
+    if capture == "none":
+        return []
+    keep = {"model_decision", "run_started", "run_finished"}
+    return [e for e in events if (e.get("type") or e.get("kind")) in keep]
+
+
+@router.post("/{run_id}/events", dependencies=[Depends(require_agent)])
+async def ingest(request: Request, run_id: str, body: RunEvents):
+    ledger = request.app.state.ledger
+    tenant = await resolve_tenant(request)
+    # non-spoofable: stamped from the token record, never the body (F24)
+    agent_id, unit = await resolve_agent(request)
+    profile = await request.app.state.agents.evidence_for(agent_id, tenant)
+    events = _captured(body.events, profile["capture"])
+    # one atomic batch: a crash mid-ingest rolls back the whole POST, so
+    # the client's retry semantics stay simple (all or nothing); with an
+    # Idempotency-Key a retry after a lost response appends nothing
+    try:
+        await ledger.append_batch(
+            "run_event", [{"run_id": run_id, "event": e} for e in events],
+            tenant=tenant, agent_id=agent_id, unit=unit,
+            idem=await idempotency_of(request, body.model_dump()),
+            run_id=run_id, pinned=(await agent_pin(request)) is not None)
+    except IdempotencyMismatch:
+        raise HTTPException(422, "Idempotency-Key was already used for a "
+                                 "different request") from None
+    except RunOwnedByAnotherAgent as e:
+        # a run belongs to the agent that started it: run reads are
+        # authorized per run, so a shared id would leak the other stream
+        raise HTTPException(409, str(e)) from None
+    fault_point("after_write_commit_before_http")
+    out = {"ingested": len(events)}
+    if len(events) != len(body.events):
+        # honest about the evidence profile: dropped by capture depth,
+        # not lost
+        out["dropped"] = len(body.events) - len(events)
+        out["capture"] = profile["capture"]
+    return out
+
+
+async def _visible_run_events(request: Request, run_id: str) -> list[dict]:
+    events = await request.app.state.ledger.events_for_run(
+        run_id, tenant=await resolve_tenant(request))
+    scope = await activity_scope(request)
+    # per EVENT, not per run: ingest refuses a second pinned agent on a
+    # run_id, but a stream mixed before that rule (or by an unpinned
+    # credential) must still never hand one agent another's events.
+    # Outside your units, even existence is need-to-know.
+    return [e for e in events
+            if visible_to(scope, e.get("agent_id", "default"), e.get("unit"))]
+
+
+@router.get("/{run_id}/audit", dependencies=[Depends(require_reader)])
+async def audit(request: Request, run_id: str):
+    events = await _visible_run_events(request, run_id)
+    return [{"seq": e["seq"], "ts_ms": e["ts_ms"], "type": e["type"],
+             "detail": json.loads(e["payload"])} for e in events]
+
+
+@router.get("/{run_id}/export", dependencies=[Depends(require_reader)])
+async def run_export(request: Request, run_id: str):
+    """A signed bundle scoped to one run. Each event's hash still verifies
+    standalone; chain continuity applies only to chain exports."""
+    from ..ledger.hashing import GENESIS
+    from .audit import _exported_by
+
+    ledger = request.app.state.ledger
+    tenant = await resolve_tenant(request)
+    events = await _visible_run_events(request, run_id)
+    if not events:
+        raise HTTPException(404, f"unknown run {run_id}")
+    bundle = {"events": events,
+              "head": events[-1]["hash"] if events else GENESIS,
+              "scope": f"run:{run_id}"}
+    signer = request.app.state.signer
+    if signer is not None:
+        # a run bundle is a non-contiguous slice: bind the signature to
+        # every event hash, or an edited event with a recomputed hash
+        # would still verify (head/count/seqs unchanged)
+        bundle = signer.sign_bundle(bundle, bind_events=True)
+    await ledger.append("audit_exported", {
+        "head_hash": bundle["head"], "by": await _exported_by(request),
+        "scope": f"run:{run_id}"}, tenant=tenant)
+    return bundle

app/routes/slack.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import json
+import urllib.parse
+
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import JSONResponse, Response
+
+from ..slack import verify_slack_signature
+
+router = APIRouter(prefix="/slack")
+
+
+@router.post("/interactions")
+async def interactions(request: Request):
+    slack = getattr(request.app.state, "slack", None)
+    if slack is None:
+        raise HTTPException(404, "slack routing not configured")
+
+    body = await request.body()
+    ok = verify_slack_signature(
+        request.app.state.settings.slack_signing_secret,
+        request.headers.get("X-Slack-Request-Timestamp", ""),
+        body,
+        request.headers.get("X-Slack-Signature", ""))
+    if not ok:
+        # unverified interactions are approval forgeries; write nothing
+        raise HTTPException(401, "bad slack signature")
+
+    # parse the urlencoded form from the raw body we already verified
+    form = urllib.parse.parse_qs(body.decode("utf-8"))
+    try:
+        payload = json.loads(form.get("payload", ["{}"])[0])
+    except json.JSONDecodeError:
+        raise HTTPException(400, "malformed payload") from None
+
+    out = await slack.handle_interaction(payload)
+    if out is None:
+        return Response(status_code=200)
+    return JSONResponse(out)

app/routes/teams.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import json
+
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import JSONResponse, Response
+
+router = APIRouter(prefix="/teams")
+
+
+@router.post("/activities")
+async def activities(request: Request):
+    teams = getattr(request.app.state, "teams", None)
+    if teams is None:
+        raise HTTPException(404, "teams routing not configured")
+
+    # unverified interactions are approval forgeries; write nothing
+    await request.app.state.teams_verifier.verify(
+        request.headers.get("Authorization", ""))
+
+    try:
+        activity = json.loads(await request.body())
+    except json.JSONDecodeError:
+        raise HTTPException(400, "malformed activity") from None
+
+    reply = await teams.handle_activity(activity)
+    if reply is None:
+        return Response(status_code=200)
+    return JSONResponse(reply)