primarypath-server 1.0.0__py3-none-any.whl

app/ledger/verify.py

@@ -0,0 +1,31 @@
+"""Server-side chain verification: same algorithm as the offline verifier.
+
+Takes export-shaped events (payload as canonical JSON string) and names the
+exact broken record on failure.
+"""
+from __future__ import annotations
+
+from .hashing import GENESIS, chain_hash
+
+
+def verify_chain(events: list[dict], head: str | None = None) -> tuple[bool, str]:
+    """Recompute the chain; when `head` is given, also require the chain to
+    REACH it — without that check, silently dropping the newest events is
+    undetectable from the event list alone."""
+    prev = GENESIS
+    for e in events:
+        if e["prev_hash"] != prev:
+            return False, f"broken at seq {e['seq']}: prev_hash mismatch"
+        recomputed = chain_hash(e["seq"], e["ts_ms"], e["type"], e["payload"], prev)
+        if recomputed != e["hash"]:
+            return False, (
+                f"broken at seq {e['seq']}: recomputed hash differs, "
+                f"record was modified after writing"
+            )
+        prev = recomputed
+    if head is not None and prev != head:
+        return False, (
+            f"chain ends at {prev[:16]}... but the head says {head[:16]}...: "
+            f"events were dropped from the tail"
+        )
+    return True, f"verified: {len(events)} events, head {prev[:16]}..."

app/main.py

@@ -0,0 +1,50 @@
+"""Uvicorn entrypoint: python -m app.main"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import sys
+
+import uvicorn
+
+from . import create_app
+from .config import get_settings
+
+if sys.platform == "win32":
+    # psycopg's async pool cannot run on Windows' default ProactorEventLoop;
+    # without this the pool times out on startup. Deploys run in Linux
+    # containers; this keeps `python -m app.main` working for Windows dev.
+    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
+
+LOOPBACK = ("127.0.0.1", "::1", "localhost")
+
+
+def check_bind_security(settings) -> None:
+    """Fail closed: a network-reachable bind with no auth at all needs an
+    explicit PRIMARYPATH_INSECURE=1."""
+    auth_on = bool(settings.oidc_issuer or settings.service_token
+                   or settings.admin_token)
+    if settings.host not in LOOPBACK and not auth_on and not settings.insecure:
+        raise SystemExit(
+            f"refusing to bind {settings.host}:{settings.port} with no "
+            "authentication configured. Set PRIMARYPATH_OIDC_ISSUER and/or "
+            "PRIMARYPATH_SERVICE_TOKEN/PRIMARYPATH_ADMIN_TOKEN, bind to 127.0.0.1, or set "
+            "PRIMARYPATH_INSECURE=1 to accept an unauthenticated, network-reachable "
+            "deploy (evaluation only).")
+    if not auth_on:
+        logging.getLogger("primarypath").warning(
+            "no authentication configured: every surface is open. "
+            "Evaluation only — do not expose this deployment.")
+
+
+def main() -> None:
+    settings = get_settings()
+    check_bind_security(settings)
+    # loop="none" on Windows: uvicorn's own loop factory would force the
+    # Proactor loop back, and psycopg async cannot run on it
+    uvicorn.run(create_app(settings), host=settings.host, port=settings.port,
+                loop="none" if sys.platform == "win32" else "auto")
+
+
+if __name__ == "__main__":
+    main()

app/maintenance.py

@@ -0,0 +1,56 @@
+"""Housekeeping that must run whether or not any feature loop does.
+
+The SLA monitor is optional (PRIMARYPATH_SLA_SCAN_INTERVAL_S <= 0 turns it
+off); expiring Idempotency-Keys is not. It used to ride the SLA loop, so
+switching SLAs off silently stopped the purge: the documented TTL went
+unenforced, the table grew without bound, and keys never became reusable.
+This loop has one job and its own switch, and it runs once at startup so
+a process that was down for longer than the TTL catches up immediately.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from .ledger import Ledger
+
+log = logging.getLogger("primarypath.maintenance")
+
+
+class Maintenance:
+    def __init__(self, ledger: Ledger, settings):
+        self.ledger = ledger
+        self.settings = settings
+        self._task: asyncio.Task | None = None
+
+    def start(self) -> None:
+        if self.settings.maintenance_interval_s > 0:
+            self._task = asyncio.get_running_loop().create_task(self._loop())
+        else:
+            log.warning("maintenance loop disabled (PRIMARYPATH_MAINTENANCE_INTERVAL_S <= 0): "
+                        "Idempotency-Keys will not expire and idempotency_keys will grow")
+
+    async def stop(self) -> None:
+        if self._task is not None:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+
+    async def _loop(self) -> None:
+        while True:
+            try:
+                await self.run_once()
+            except Exception:
+                log.exception("maintenance pass failed; will retry")
+            await asyncio.sleep(self.settings.maintenance_interval_s)
+
+    async def run_once(self) -> dict[str, int]:
+        """One pass; returns what it did, for tests and for the log."""
+        purged = await self.ledger.purge_idempotency_keys(
+            self.settings.idempotency_ttl_s * 1000)
+        if purged:
+            log.info("expired %d idempotency key(s) older than %ds",
+                     purged, self.settings.idempotency_ttl_s)
+        return {"idempotency_keys_purged": purged}

app/metrics.py

@@ -0,0 +1,89 @@
+"""Prometheus metrics (/metrics). Operational only: counts, durations,
+saturation — never approval payloads, reasoning text, or identities.
+
+Event-derived series are computed from the log at scrape time (the log is
+the truth here too); transport series are process counters. Documented in
+docs/METRICS.md; a per-app registry keeps test instances isolated.
+"""
+from __future__ import annotations
+
+import time
+
+from prometheus_client import (
+    CONTENT_TYPE_LATEST,
+    CollectorRegistry,
+    Counter,
+    Gauge,
+    Histogram,
+    generate_latest,
+)
+
+DECISION_PCTS = (0.5, 0.9, 0.99)
+
+
+class Metrics:
+    def __init__(self):
+        r = self.registry = CollectorRegistry()
+        self.http_requests = Counter(
+            "primarypath_http_requests_total", "HTTP requests",
+            ["method", "path", "status"], registry=r)
+        self.http_seconds = Histogram(
+            "primarypath_http_request_seconds", "HTTP request latency",
+            ["method", "path"], registry=r)
+        self.append_seconds = Histogram(
+            "primarypath_append_seconds", "Event append (lock+insert+projection)",
+            registry=r)
+        self.webhook_deliveries = Counter(
+            "primarypath_webhook_deliveries_total",
+            "callback_url decision deliveries", ["result"], registry=r)
+
+        self.events_total = Gauge(
+            "primarypath_events_total", "Events in the chain, by type (from the log)",
+            ["type"], registry=r)
+        self.pending = Gauge(
+            "primarypath_pending_approvals", "Approvals awaiting a decision",
+            registry=r)
+        self.oldest_pending_age = Gauge(
+            "primarypath_oldest_pending_age_seconds",
+            "Age of the oldest pending approval", registry=r)
+        self.time_to_decision = Gauge(
+            "primarypath_time_to_decision_seconds",
+            "Decision latency percentiles over decided approvals",
+            ["quantile"], registry=r)
+        self.pool_size = Gauge(
+            "primarypath_db_pool_size", "Connections in the pool", registry=r)
+        self.pool_waiting = Gauge(
+            "primarypath_db_pool_requests_waiting",
+            "Requests waiting for a connection", registry=r)
+
+    async def scrape(self, pool) -> bytes:
+        """Refresh log-derived gauges, then render the registry."""
+        now_ms = int(time.time() * 1000)
+        async with pool.connection() as conn:
+            cur = await conn.execute(
+                "SELECT type, count(*) FROM events GROUP BY type")
+            for type_, count in await cur.fetchall():
+                self.events_total.labels(type=type_).set(count)
+            cur = await conn.execute(
+                "SELECT count(*), min(requested_ts_ms) FROM approvals_view "
+                "WHERE status = 'pending'")
+            pending, oldest = await cur.fetchone()
+            self.pending.set(pending)
+            self.oldest_pending_age.set(
+                max(0.0, (now_ms - oldest) / 1000) if oldest else 0.0)
+            cur = await conn.execute(
+                "SELECT percentile_cont(ARRAY[0.5, 0.9, 0.99]) WITHIN GROUP "
+                "(ORDER BY (decided_ts_ms - requested_ts_ms) / 1000.0) "
+                "FROM approvals_view WHERE decided_ts_ms IS NOT NULL")
+            row = await cur.fetchone()
+            if row and row[0]:
+                for q, v in zip(DECISION_PCTS, row[0]):
+                    if v is not None:
+                        self.time_to_decision.labels(quantile=str(q)).set(v)
+        stats = pool.get_stats()
+        self.pool_size.set(stats.get("pool_size", 0))
+        self.pool_waiting.set(stats.get("requests_waiting", 0))
+        return generate_latest(self.registry)
+
+
+CONTENT_TYPE = CONTENT_TYPE_LATEST

app/migrations/env.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from alembic import context
+from sqlalchemy import create_engine
+
+config = context.config
+
+
+def run_migrations_online() -> None:
+    url = config.get_main_option("sqlalchemy.url")
+    assert url, "sqlalchemy.url is set by app.db before migrations run"
+    engine = create_engine(url)
+    with engine.connect() as connection:
+        context.configure(connection=connection, target_metadata=None)
+        with context.begin_transaction():
+            context.run_migrations()
+    engine.dispose()
+
+
+run_migrations_online()

app/migrations/script.py.mako

@@ -0,0 +1,23 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+"""
+from __future__ import annotations
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

app/migrations/versions/0001_baseline.py

@@ -0,0 +1,19 @@
+"""Baseline: empty schema anchor.
+
+Revision ID: 0001
+Revises:
+"""
+from __future__ import annotations
+
+revision = "0001"
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    pass
+
+
+def downgrade() -> None:
+    pass

app/migrations/versions/0002_events_and_projection.py

@@ -0,0 +1,78 @@
+"""events log (append-only, hash-chained) + approvals_view projection.
+
+Revision ID: 0002
+Revises: 0001
+"""
+from __future__ import annotations
+
+from alembic import op
+
+revision = "0002"
+down_revision = "0001"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # payload is the EXACT canonical string that was hashed: hashing, storage,
+    # and export must be byte-identical or honest data reads as tampering
+    # (JSONB does not preserve numeric representation). payload_json is a
+    # derived column for querying only; the TEXT column is the truth.
+    op.execute("""
+        CREATE TABLE events (
+            seq          BIGINT PRIMARY KEY,
+            ts_ms        BIGINT NOT NULL,
+            type         TEXT   NOT NULL,
+            payload      TEXT   NOT NULL,
+            payload_json JSONB  GENERATED ALWAYS AS (payload::jsonb) STORED,
+            prev_hash    TEXT   NOT NULL,
+            hash         TEXT   NOT NULL,
+            run_id       TEXT
+        )
+    """)
+    op.execute("CREATE INDEX events_run_id_idx ON events (run_id)")
+    op.execute("""
+        CREATE FUNCTION events_append_only() RETURNS trigger AS $$
+        BEGIN
+            RAISE EXCEPTION 'events is append-only';
+        END
+        $$ LANGUAGE plpgsql
+    """)
+    op.execute("""
+        CREATE TRIGGER events_no_update_delete
+        BEFORE UPDATE OR DELETE ON events
+        FOR EACH ROW EXECUTE FUNCTION events_append_only()
+    """)
+    op.execute("""
+        CREATE TRIGGER events_no_truncate
+        BEFORE TRUNCATE ON events
+        FOR EACH STATEMENT EXECUTE FUNCTION events_append_only()
+    """)
+    op.execute("""
+        CREATE TABLE approvals_view (
+            approval_id     TEXT PRIMARY KEY,
+            run_id          TEXT NOT NULL,
+            call_id         TEXT NOT NULL,
+            tool            TEXT NOT NULL,
+            arguments       JSONB NOT NULL DEFAULT '{}'::jsonb,
+            reasoning       TEXT,
+            framework       TEXT,
+            callback_url    TEXT,
+            status          TEXT NOT NULL,
+            reviewer        TEXT,
+            reason          TEXT,
+            requested_ts_ms BIGINT NOT NULL,
+            decided_ts_ms   BIGINT,
+            deadline_ms     BIGINT,
+            annotations     JSONB NOT NULL DEFAULT '[]'::jsonb
+        )
+    """)
+    op.execute("CREATE INDEX approvals_view_status_idx ON approvals_view (status)")
+
+
+def downgrade() -> None:
+    op.execute("DROP TABLE approvals_view")
+    op.execute("DROP TRIGGER events_no_truncate ON events")
+    op.execute("DROP TRIGGER events_no_update_delete ON events")
+    op.execute("DROP FUNCTION events_append_only()")
+    op.execute("DROP TABLE events")

app/migrations/versions/0003_slack_messages.py

@@ -0,0 +1,27 @@
+"""slack message refs: operational state, not part of the audit chain.
+
+Revision ID: 0003
+Revises: 0002
+"""
+from __future__ import annotations
+
+from alembic import op
+
+revision = "0003"
+down_revision = "0002"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        CREATE TABLE slack_messages (
+            approval_id TEXT PRIMARY KEY,
+            channel     TEXT NOT NULL,
+            ts          TEXT NOT NULL
+        )
+    """)
+
+
+def downgrade() -> None:
+    op.execute("DROP TABLE slack_messages")

app/migrations/versions/0004_sessions.py

@@ -0,0 +1,31 @@
+"""reviewer sessions: operational state, not part of the audit chain.
+
+Revision ID: 0004
+Revises: 0003
+"""
+from __future__ import annotations
+
+from alembic import op
+
+revision = "0004"
+down_revision = "0003"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        CREATE TABLE sessions (
+            id         TEXT PRIMARY KEY,
+            subject    TEXT NOT NULL,
+            email      TEXT,
+            name       TEXT,
+            roles      JSONB NOT NULL DEFAULT '[]'::jsonb,
+            csrf       TEXT NOT NULL,
+            expires_at BIGINT NOT NULL
+        )
+    """)
+
+
+def downgrade() -> None:
+    op.execute("DROP TABLE sessions")

app/migrations/versions/0005_siem_cursor.py

@@ -0,0 +1,26 @@
+"""siem forwarder cursor: operational state, not part of the audit chain.
+
+Revision ID: 0005
+Revises: 0004
+"""
+from __future__ import annotations
+
+from alembic import op
+
+revision = "0005"
+down_revision = "0004"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        CREATE TABLE siem_cursor (
+            id       INTEGER PRIMARY KEY CHECK (id = 1),
+            last_seq BIGINT NOT NULL
+        )
+    """)
+
+
+def downgrade() -> None:
+    op.execute("DROP TABLE siem_cursor")

app/migrations/versions/0006_teams_messages.py

@@ -0,0 +1,27 @@
+"""teams message refs: operational state, not part of the audit chain.
+
+Revision ID: 0006
+Revises: 0005
+"""
+from __future__ import annotations
+
+from alembic import op
+
+revision = "0006"
+down_revision = "0005"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        CREATE TABLE teams_messages (
+            approval_id     TEXT PRIMARY KEY,
+            conversation_id TEXT NOT NULL,
+            activity_id     TEXT NOT NULL
+        )
+    """)
+
+
+def downgrade() -> None:
+    op.execute("DROP TABLE teams_messages")

app/migrations/versions/0007_tenant_scoping.py

@@ -0,0 +1,50 @@
+"""Tenant seam: chain-per-tenant. seq and the hash chain are scoped per
+tenant_id, so each tenant's audit bundle is self-contained and verifiable
+independently. Single-tenant deployments ride the 'default' tenant and
+notice nothing.
+
+Revision ID: 0007
+Revises: 0006
+"""
+from __future__ import annotations
+
+from alembic import op
+
+revision = "0007"
+down_revision = "0006"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # ADD COLUMN ... DEFAULT is metadata-only (no row rewrite), so the
+    # append-only trigger is not in play; PK swaps are index DDL.
+    op.execute("ALTER TABLE events ADD COLUMN tenant_id TEXT NOT NULL "
+               "DEFAULT 'default'")
+    op.execute("ALTER TABLE events DROP CONSTRAINT events_pkey")
+    op.execute("ALTER TABLE events ADD PRIMARY KEY (tenant_id, seq)")
+    op.execute("DROP INDEX IF EXISTS events_run_id_idx")
+    op.execute("CREATE INDEX events_tenant_run_idx ON events (tenant_id, run_id)")
+
+    op.execute("ALTER TABLE approvals_view ADD COLUMN tenant_id TEXT NOT NULL "
+               "DEFAULT 'default'")
+    op.execute("ALTER TABLE approvals_view DROP CONSTRAINT approvals_view_pkey")
+    op.execute("ALTER TABLE approvals_view ADD PRIMARY KEY (tenant_id, approval_id)")
+
+    for table in ("slack_messages", "teams_messages"):
+        op.execute(f"ALTER TABLE {table} ADD COLUMN tenant_id TEXT NOT NULL "
+                   f"DEFAULT 'default'")
+        op.execute(f"ALTER TABLE {table} DROP CONSTRAINT {table}_pkey")
+        op.execute(f"ALTER TABLE {table} ADD PRIMARY KEY (tenant_id, approval_id)")
+
+    op.execute("DROP TABLE siem_cursor")
+    op.execute("""
+        CREATE TABLE siem_cursor (
+            tenant_id TEXT PRIMARY KEY,
+            last_seq  BIGINT NOT NULL
+        )
+    """)
+
+
+def downgrade() -> None:
+    raise NotImplementedError("tenancy is a one-way seam")

app/migrations/versions/0008_policy_view.py

@@ -0,0 +1,39 @@
+"""policy_view: the folded current policy per tenant (a cache of policy_set
+events, last-write-wins per action). The policy's own history lives in the
+chain as policy_set events; this table is a rebuildable projection, same
+discipline as approvals_view.
+
+Revision ID: 0008
+Revises: 0007
+"""
+from __future__ import annotations
+
+from alembic import op
+
+revision = "0008"
+down_revision = "0007"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        CREATE TABLE policy_view (
+            tenant_id         TEXT NOT NULL,
+            action            TEXT NOT NULL,
+            requires_approval BOOLEAN NOT NULL,
+            reversible        BOOLEAN NOT NULL DEFAULT false,
+            mode              TEXT NOT NULL,
+            allow             JSONB NOT NULL DEFAULT '[]'::jsonb,
+            deny              JSONB NOT NULL DEFAULT '[]'::jsonb,
+            approver_groups   JSONB NOT NULL DEFAULT '[]'::jsonb,
+            updated_by        TEXT,
+            reason            TEXT,
+            updated_ts_ms     BIGINT NOT NULL,
+            PRIMARY KEY (tenant_id, action)
+        )
+    """)
+
+
+def downgrade() -> None:
+    op.execute("DROP TABLE policy_view")

app/migrations/versions/0009_api_tokens.py

@@ -0,0 +1,37 @@
+"""api_tokens: issued service/admin tokens (F22 config console).
+
+Operational state, not part of the audit chain — but issuance/revocation
+is recorded as an admin_action in the chain. Only the sha256 of a token is
+stored; the plaintext is shown once at issue time and never again.
+
+Revision ID: 0009
+Revises: 0008
+"""
+from __future__ import annotations
+
+from alembic import op
+
+revision = "0009"
+down_revision = "0008"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        CREATE TABLE api_tokens (
+            id            TEXT PRIMARY KEY,
+            tenant_id     TEXT NOT NULL DEFAULT 'default',
+            kind          TEXT NOT NULL CHECK (kind IN ('service', 'admin')),
+            token_sha256  TEXT NOT NULL UNIQUE,
+            label         TEXT,
+            created_ts_ms BIGINT NOT NULL,
+            created_by    TEXT,
+            revoked_ts_ms BIGINT
+        )
+    """)
+    op.execute("CREATE INDEX api_tokens_hash_idx ON api_tokens (token_sha256)")
+
+
+def downgrade() -> None:
+    op.execute("DROP TABLE api_tokens")

app/migrations/versions/0010_session_groups.py

@@ -0,0 +1,23 @@
+"""sessions.groups: the reviewer's raw IdP groups, kept so per-action
+approver_groups can be enforced at decision time (F21 review fix).
+
+Revision ID: 0010
+Revises: 0009
+"""
+from __future__ import annotations
+
+from alembic import op
+
+revision = "0010"
+down_revision = "0009"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("ALTER TABLE sessions ADD COLUMN groups JSONB "
+               "NOT NULL DEFAULT '[]'::jsonb")
+
+
+def downgrade() -> None:
+    op.execute("ALTER TABLE sessions DROP COLUMN groups")