primarypath-server 1.0.0rc1__py3-none-any.whl

app/__init__.py

@@ -0,0 +1,351 @@
+"""Primary Path approval control plane: app factory."""
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+
+from ._version import VERSION
+from .config import Settings, get_settings
+from .db import make_pool, run_migrations
+
+# the release version as VERSION spells it (scripts/version.py stamps
+# _version.py with every other copy; package metadata would say 1.0.0rc1
+# for 1.0.0-rc.1); reported by /healthz, /livez and /api/admin/config so
+# an operator can read what runs
+__version__ = VERSION
+
+BUNDLED_WEB_DIST = Path(__file__).resolve().parent / "web-dist"
+
+
+def resolve_web_dist(settings) -> str | None:
+    """Where the console lives: PRIMARYPATH_WEB_DIST when set, else the
+    console bundled into the installed wheel (scripts/build-wheels.sh
+    copies web/dist to app/web-dist), else nothing (API only)."""
+    if settings.web_dist:
+        return settings.web_dist
+    if (BUNDLED_WEB_DIST / "index.html").is_file():
+        return str(BUNDLED_WEB_DIST)
+    return None
+
+
+def create_app(settings: Settings | None = None) -> FastAPI:
+    settings = settings or get_settings()
+
+    from .obslog import setup_logging
+
+    setup_logging(settings)
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        from .db import head_revision
+
+        if settings.migrate_on_start:
+            await run_migrations(settings)
+        app.state.migration_head = head_revision()
+        pool = make_pool(settings)
+        await pool.open(wait=True)
+        app.state.pool = pool
+        app.state.settings = settings
+
+        from .ledger import Ledger
+        from .metrics import Metrics
+        from .webhooks import WebhookOutbox
+
+        app.state.metrics = Metrics()
+        app.state.ledger = Ledger(pool)
+        app.state.ledger.on_append_seconds = \
+            app.state.metrics.append_seconds.observe
+        app.state.webhooks = WebhookOutbox(
+            pool,
+            attempts=settings.webhook_attempts,
+            backoff_base=settings.webhook_backoff_base,
+            backoff_max=settings.webhook_backoff_max,
+            poll_interval_s=settings.webhook_poll_interval_s,
+            lease_s=settings.webhook_lease_s,
+            secret=settings.webhook_secret,
+            metrics=app.state.metrics)
+        # every decision surface funnels through Ledger.decide: the callback
+        # row commits in the decision's own transaction
+        app.state.ledger.decision_hooks.append(app.state.webhooks.on_decision)
+
+        from .signing import SignerRegistry
+
+        # every configured backend, selectable per agent evidence profile
+        # (F24); .default is what make_signer returned pre-F24
+        app.state.signers = SignerRegistry(settings)
+        app.state.signer = app.state.signers.default
+        app.state.webhooks.signer = app.state.signer  # Ed25519 delivery sigs
+        # execution grants are minted with the audit key, inside the
+        # granting transaction (no signer = no grants, fail closed at the
+        # executor)
+        if app.state.signer is not None:
+            from .grants import GrantMinter
+            app.state.ledger.grant_minter = GrantMinter(
+                app.state.signer, settings.grant_ttl_s).mint
+
+        app.state.oidc = None
+        if settings.oidc_issuer:
+            if not settings.session_secret:
+                raise RuntimeError("PRIMARYPATH_SESSION_SECRET is required with OIDC")
+            from .auth import OIDC
+
+            assert settings.oidc_client_id, "PRIMARYPATH_OIDC_CLIENT_ID is required with OIDC"
+            app.state.oidc = OIDC(settings.oidc_issuer, settings.oidc_client_id,
+                                  settings.oidc_client_secret or "",
+                                  settings.oidc_redirect_url
+                                  or f"{settings.public_url}/auth/callback",
+                                  settings.oidc_scopes,
+                                  algorithms=[a.strip() for a in
+                                              settings.oidc_algorithms.split(",")
+                                              if a.strip()])
+
+        app.state.slack = None
+        if (settings.slack_bot_token and settings.slack_signing_secret
+                and settings.slack_channel):
+            from .slack import SlackAPI, SlackRouter
+
+            app.state.slack = SlackRouter(
+                SlackAPI(settings.slack_bot_token), pool, app.state.ledger,
+                settings.slack_channel, settings.public_url,
+                approver_ids=settings.slack_approver_ids)
+
+        app.state.teams = None
+        app.state.teams_verifier = None
+        if (settings.teams_app_id and settings.teams_app_password
+                and settings.teams_service_url
+                and settings.teams_conversation_id):
+            from .teams import TeamsAPI, TeamsRequestVerifier, TeamsRouter
+
+            app.state.teams = TeamsRouter(
+                TeamsAPI(settings.teams_app_id, settings.teams_app_password,
+                         settings.teams_service_url),
+                pool, app.state.ledger, settings.teams_conversation_id,
+                settings.public_url,
+                approver_ids=settings.teams_approver_ids)
+            app.state.teams_verifier = TeamsRequestVerifier(
+                settings.teams_app_id,
+                openid_config_url=settings.teams_openid_config_url,
+                issuer=settings.teams_token_issuer)
+
+        # every configured chat surface gets notified and reflected
+        app.state.chat_routers = [r for r in (app.state.slack, app.state.teams)
+                                  if r is not None]
+
+        from .agents import AgentRegistry
+        from .costgov import CostStore
+        from .policy import PolicyStore
+        from .tokens import TokenStore
+        from .traces import TraceStore
+
+        app.state.policy = PolicyStore(pool, app.state.ledger, settings)
+        app.state.traces = TraceStore(pool, app.state.ledger, settings)
+        app.state.tokens = TokenStore(pool)
+        app.state.cost = CostStore(pool, app.state.ledger, settings)
+        app.state.agents = AgentRegistry(pool, app.state.ledger)
+
+        # chat surfaces fail closed on approver_groups: give them the policy
+        # store so decide_from_chat can refuse actions restricted to IdP groups
+        # a chat identity can't prove membership of. (The callback needs no
+        # wiring here: a chat decision goes through Ledger.decide like any
+        # other, and the outbox hook rides that transaction.)
+        for _chat in app.state.chat_routers:
+            _chat.policy = app.state.policy
+
+        from .sla import SLAMonitor
+
+        app.state.sla = SLAMonitor(app.state.ledger, pool, settings,
+                                   slack=app.state.slack,
+                                   webhooks=app.state.webhooks,
+                                   chat_routers=app.state.chat_routers)
+        app.state.sla.start()
+
+        from .maintenance import Maintenance
+
+        # housekeeping on its own task: it must not depend on the SLA
+        # loop (or any other feature) being switched on
+        app.state.maintenance = Maintenance(app.state.ledger, settings)
+        app.state.maintenance.start()
+
+        from .siem import SiemForwarder, make_sink
+
+        app.state.siem = SiemForwarder(pool, make_sink(settings),
+                                       batch=settings.siem_batch,
+                                       interval_s=settings.siem_interval_s)
+        app.state.siem.start()
+        app.state.webhooks.start()
+        yield
+        # rows outlive the process: stop the worker, never "drain" — an
+        # undelivered callback waits in the table for the next start
+        await app.state.webhooks.stop()
+        await app.state.siem.stop()
+        await app.state.sla.stop()
+        await app.state.maintenance.stop()
+        for chat in app.state.chat_routers:
+            await chat.drain()
+        await pool.close()
+
+    from .security import (
+        BodyLimitMiddleware,
+        SecurityHeadersMiddleware,
+        build_csp,
+        check_session_secret,
+        check_transport_posture,
+        inline_script_hashes,
+    )
+
+    # fail at construction, not at the first login
+    check_session_secret(settings)
+    check_transport_posture(settings)
+
+    app = FastAPI(title="primarypath", lifespan=lifespan)
+
+    # the console's own inline bootstrap (theme stamp) is hashed into the
+    # CSP; anything else inline is refused by the browser
+    web_dist = resolve_web_dist(settings)
+    _hashes: list[str] = []
+    if web_dist:
+        from pathlib import Path as _Path
+        _index = _Path(web_dist) / "index.html"
+        if _index.is_file():
+            _hashes = inline_script_hashes(_index.read_text("utf-8"))
+    app.state.csp = build_csp(settings, _hashes)
+    # outermost: refuse oversized bodies before anything else runs, and
+    # stamp the security headers on every response
+    app.add_middleware(SecurityHeadersMiddleware, settings=settings,
+                       csp=app.state.csp)
+    app.add_middleware(BodyLimitMiddleware, max_bytes=settings.max_body_bytes)
+
+    if settings.cors_origins:
+        from fastapi.middleware.cors import CORSMiddleware
+
+        app.add_middleware(
+            CORSMiddleware, allow_origins=settings.cors_origins,
+            allow_credentials=True, allow_methods=["*"], allow_headers=["*"])
+
+    import time as _time
+
+    from fastapi.responses import JSONResponse as _JSON
+
+    from .obslog import new_request_id, request_id_var
+    from .ratelimit import RateLimiter, agent_key, is_agent_write, is_guarded
+
+    _limiter = RateLimiter(settings.rate_limit_per_minute,
+                           agent_per_minute=settings.agent_write_rate_per_minute)
+
+    @app.middleware("http")
+    async def rate_limit(request: Request, call_next):
+        ip = (request.client.host if request.client else "unknown")
+        path = request.url.path
+        if is_guarded(request.method, path):
+            if not _limiter.allow(ip, path, _time.time()):
+                return _JSON({"error": "rate limit exceeded, slow down"},
+                             status_code=429,
+                             headers={"Retry-After": "60"})
+        elif is_agent_write(request.method, path):
+            subject = agent_key(request.headers.get("authorization"), ip)
+            if not _limiter.allow_agent_write(subject, _time.time()):
+                return _JSON({"error": "agent write quota exceeded for this "
+                                       "credential; retry after the window"},
+                             status_code=429,
+                             headers={"Retry-After": "60"})
+        return await call_next(request)
+
+    @app.middleware("http")
+    async def observe_requests(request: Request, call_next):
+        request_id_var.set(request.headers.get("X-Request-Id")
+                           or new_request_id())
+        start = _time.perf_counter()
+        response = await call_next(request)
+        elapsed = _time.perf_counter() - start
+        metrics = getattr(request.app.state, "metrics", None)
+        if metrics is not None:
+            route = request.scope.get("route")
+            path = getattr(route, "path", request.url.path)
+            metrics.http_requests.labels(request.method, path,
+                                         str(response.status_code)).inc()
+            metrics.http_seconds.labels(request.method, path).observe(elapsed)
+        response.headers["X-Request-Id"] = request_id_var.get() or ""
+        return response
+
+    @app.exception_handler(RequestValidationError)
+    async def validation_400(request: Request, exc: RequestValidationError):
+        # The contract promises 400 (not FastAPI's default 422) on bad input.
+        # loc/msg/type only: a value_error's ctx carries the raw exception
+        # object, which is neither serializable nor the client's business.
+        detail = [{"loc": e.get("loc"), "msg": e.get("msg"),
+                   "type": e.get("type")} for e in exc.errors()]
+        return JSONResponse({"error": "invalid request", "detail": detail},
+                            status_code=400)
+
+    from .ledger import UnsupportedPayload
+
+    @app.exception_handler(UnsupportedPayload)
+    async def unsupported_payload_400(request: Request, exc: UnsupportedPayload):
+        return JSONResponse({"error": str(exc)}, status_code=400)
+
+    from . import auth as auth_module
+    from .routes import (
+        admin,
+        agents,
+        approvals,
+        audit,
+        costgov,
+        health,
+        policy,
+        runs,
+        slack,
+        teams,
+        traces,
+    )
+
+    app.include_router(health.router)
+    app.include_router(agents.router)
+    app.include_router(approvals.router)
+    app.include_router(runs.router)
+    app.include_router(audit.router)
+    app.include_router(slack.router)
+    app.include_router(teams.router)
+    app.include_router(auth_module.router)
+    app.include_router(admin.router)
+    app.include_router(policy.router)
+    app.include_router(traces.router)
+    app.include_router(costgov.router)
+
+    if settings.oidc_issuer:
+        from fastapi.responses import RedirectResponse
+
+        from .auth import get_identity
+
+        @app.middleware("http")
+        async def inbox_gate(request: Request, call_next):
+            path = request.url.path
+            # /teams has its own Bot Framework JWT verification; /metrics,
+            # /healthz and /readyz are the operational plane (a 307 to the
+            # IdP would break Prometheus and count as probe success for
+            # kubelet, defeating the waiting-for-migrations 503 gate).
+            open_prefixes = ("/api", "/auth", "/slack", "/teams",
+                             "/livez", "/healthz", "/readyz", "/metrics")
+            if path.startswith(open_prefixes):
+                return await call_next(request)
+            identity = await get_identity(request)
+            if identity is None:
+                return RedirectResponse("/auth/login")
+            if not identity.get("roles"):
+                return JSONResponse(
+                    {"error": "no role assigned; ask an admin to map your "
+                              "group or email"}, status_code=403)
+            return await call_next(request)
+
+    if web_dist:
+        from pathlib import Path
+
+        from fastapi.staticfiles import StaticFiles
+
+        dist = Path(web_dist)
+        if dist.is_dir():
+            app.mount("/", StaticFiles(directory=dist, html=True), name="inbox")
+    return app

app/_version.py

@@ -0,0 +1,8 @@
+"""The release version, spelled exactly as VERSION spells it.
+
+Stamped by scripts/version.py with every other copy. It exists because
+package metadata normalizes a prerelease (1.0.0-rc.1 becomes 1.0.0rc1),
+and what runs must name the release the operator deployed, as the image
+tag, the chart and the release page spell it.
+"""
+VERSION = "1.0.0-rc.1"

app/agents.py

@@ -0,0 +1,150 @@
+"""The agent registry + per-agent evidence profiles (F24), event-sourced.
+
+An agent is the unit of evidence: its own hash chain, its own signing
+backend and key, its own capture depth and retention intent. The registry
+(agent -> unit) and every profile change are `agent_registered` /
+`evidence_set` events on the per-tenant GOVERNANCE chain, folded into
+`agents_view` / `evidence_view` — the log is truth, the tables are
+rebuildable caches (the approvals_view discipline).
+
+Retention is recorded intent for export/ops tooling, never enforced by
+deletion: the chain is append-only, and silently dropping records would be
+indistinguishable from tampering.
+"""
+from __future__ import annotations
+
+from .ledger.store import DEFAULT_TENANT, Ledger
+
+# "default" is first-class: sign with whatever the deployment's default
+# signer is (it is also the sentinel an unprofiled agent reports, so a
+# partial profile update can round-trip it)
+SIGNING_BACKENDS = ("default", "none", "file", "kms")
+CAPTURES = ("none", "decisions", "full")
+
+DEFAULT_PROFILE = {
+    "signing_backend": "default", "key_id": None, "capture": "full",
+    "retention_days": None, "source": "default",
+}
+
+
+class AgentRegistry:
+    def __init__(self, pool, ledger: Ledger):
+        self.pool = pool
+        self.ledger = ledger
+
+    # -- reads ----------------------------------------------------------------
+
+    async def agents(self, tenant: str = DEFAULT_TENANT) -> list[dict]:
+        """Every agent the tenant knows: the registered map plus any agent
+        that has activity but was never mapped (a dev agent riding the
+        default chain still shows up, honestly unassigned)."""
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(
+                """
+                SELECT a.agent, a.unit, a.updated_by, a.updated_ts_ms,
+                       e.signing_backend, e.key_id, e.capture,
+                       e.retention_days, s.events, s.last_ts_ms
+                FROM (
+                    SELECT agent, unit, updated_by, updated_ts_ms
+                    FROM agents_view WHERE tenant_id = %(t)s
+                    UNION
+                    SELECT DISTINCT agent_id, NULL::text, NULL::text,
+                                    NULL::bigint
+                    FROM events
+                    WHERE tenant_id = %(t)s AND agent_id IS NOT NULL
+                      AND agent_id NOT IN
+                          (SELECT agent FROM agents_view WHERE tenant_id = %(t)s)
+                ) a
+                LEFT JOIN evidence_view e
+                       ON e.tenant_id = %(t)s AND e.agent = a.agent
+                LEFT JOIN (
+                    SELECT agent_id, count(*) AS events,
+                           max(ts_ms) AS last_ts_ms
+                    FROM events WHERE tenant_id = %(t)s
+                      AND agent_id IS NOT NULL GROUP BY agent_id
+                ) s ON s.agent_id = a.agent
+                ORDER BY a.agent
+                """, {"t": tenant})
+            rows = await cur.fetchall()
+        out = []
+        for r in rows:
+            profile = {
+                "signing_backend": r[4] or DEFAULT_PROFILE["signing_backend"],
+                "key_id": r[5],
+                "capture": r[6] or DEFAULT_PROFILE["capture"],
+                "retention_days": r[7],
+            }
+            out.append({"agent": r[0], "unit": r[1], "updated_by": r[2],
+                        "updated_ts_ms": r[3], "evidence": profile,
+                        "events": r[8] or 0, "last_ts_ms": r[9]})
+        return out
+
+    async def known_units(self, tenant: str = DEFAULT_TENANT) -> set[str]:
+        """Every unit any agent is (or was) mapped to — what "need-to-know
+        is in force" means for this tenant."""
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(
+                """
+                SELECT unit FROM agents_view
+                WHERE tenant_id = %(t)s AND unit IS NOT NULL
+                UNION
+                SELECT DISTINCT unit FROM approvals_view
+                WHERE tenant_id = %(t)s AND unit IS NOT NULL
+                """, {"t": tenant})
+            rows = await cur.fetchall()
+        return {r[0] for r in rows}
+
+    async def unit_of(self, agent: str,
+                      tenant: str = DEFAULT_TENANT) -> str | None:
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(
+                "SELECT unit FROM agents_view WHERE tenant_id = %s "
+                "AND agent = %s", (tenant, agent))
+            row = await cur.fetchone()
+        return row[0] if row else None
+
+    async def evidence_for(self, agent: str,
+                           tenant: str = DEFAULT_TENANT) -> dict:
+        """The agent's evidence profile; when none is set, the fail-safe
+        default: sign with whatever the deployment's default signer is,
+        capture everything (`source` says which case this is)."""
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(
+                "SELECT signing_backend, key_id, capture, retention_days "
+                "FROM evidence_view WHERE tenant_id = %s AND agent = %s",
+                (tenant, agent))
+            row = await cur.fetchone()
+        if row is None:
+            return dict(DEFAULT_PROFILE)
+        return {"signing_backend": row[0], "key_id": row[1],
+                "capture": row[2], "retention_days": row[3], "source": "set"}
+
+    # -- writes (governance events) --------------------------------------------
+
+    async def register(self, agent: str, unit: str | None, by: str,
+                       reason: str = "",
+                       tenant: str = DEFAULT_TENANT) -> None:
+        """Map (or re-map) an agent to a unit — a chained governance event."""
+        await self.ledger.append(
+            "agent_registered",
+            {"agent": agent, "unit": unit, "by": by, "reason": reason},
+            tenant=tenant)
+
+    async def set_evidence(self, agent: str, *, signing_backend: str,
+                           key_id: str | None = None, capture: str = "full",
+                           retention_days: int | None = None, by: str,
+                           reason: str = "",
+                           tenant: str = DEFAULT_TENANT) -> dict:
+        """Change an agent's evidence demands — itself an audited governance
+        event."""
+        if signing_backend not in SIGNING_BACKENDS:
+            raise ValueError(f"signing_backend must be one of {SIGNING_BACKENDS}")
+        if capture not in CAPTURES:
+            raise ValueError(f"capture must be one of {CAPTURES}")
+        await self.ledger.append(
+            "evidence_set",
+            {"agent": agent, "signing_backend": signing_backend,
+             "key_id": key_id, "capture": capture,
+             "retention_days": retention_days, "by": by, "reason": reason},
+            tenant=tenant)
+        return await self.evidence_for(agent, tenant)

app/alembic.ini

@@ -0,0 +1,37 @@
+[alembic]
+script_location = migrations
+sqlalchemy.url = postgresql+psycopg://primarypath:primarypath@localhost:5432/primarypath
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S