primarypath-server 1.0.0__py3-none-any.whl

app/chat.py

@@ -0,0 +1,122 @@
+"""The shared chat-routing core: Slack and Teams differ only in transport.
+
+Every chat surface does the same things: post the case when an approval is
+requested, write the decision through the SAME ledger path as the web, and
+reflect the outcome back onto the original message. Nothing chat-specific
+ever enters the audit chain beyond the reviewer string.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from .ledger import AlreadyDecided, Ledger, UnknownApproval
+from .ledger.store import DEFAULT_TENANT
+
+log = logging.getLogger("primarypath.chat")
+
+
+class ChatRouter:
+    def __init__(self, ledger: Ledger, tenant: str = DEFAULT_TENANT,
+                 policy=None):
+        self.ledger = ledger
+        # a chat surface serves one tenant (F20 seam); multi-tenant chat
+        # means one router per tenant workspace, not a shared one
+        self.tenant = tenant
+        # set after construction; used to fail closed on approver_groups
+        self.policy = policy
+        self._tasks: set[asyncio.Task] = set()
+
+    class ChatNotPermitted(Exception):
+        """The action's approver_groups can't be proven from a chat identity."""
+
+    # -- background plumbing ---------------------------------------------------
+
+    def _spawn(self, coro) -> None:
+        task = asyncio.get_running_loop().create_task(coro)
+        self._tasks.add(task)
+        task.add_done_callback(self._tasks.discard)
+
+    async def drain(self) -> None:
+        # drop finished tasks here rather than trust the done-callback to
+        # have run: a finished task still in the set made `while self._tasks`
+        # spin forever (three chat tests timed out in CI for rc.5), and
+        # shutdown drains the same way
+        while True:
+            self._tasks.difference_update([t for t in self._tasks if t.done()])
+            if not self._tasks:
+                return
+            await asyncio.gather(*list(self._tasks), return_exceptions=True)
+
+    # -- surface hooks (transport-specific) --------------------------------------
+
+    def notify(self, approval: dict) -> None:
+        raise NotImplementedError
+
+    def reflect(self, approval: dict) -> None:
+        raise NotImplementedError
+
+    # -- the one shared decision path ---------------------------------------------
+
+    async def decide_from_chat(self, approval_id: str, approved: bool,
+                               reviewer: str, reason: str = "",
+                               tenant: str | None = None) -> dict | None:
+        """Write the decision exactly like the web path would, into this
+        surface's tenant chain. On a race, return the standing decision so
+        the caller can show who won.
+
+        Fail closed on approver_groups and on dual control: a chat identity
+        (Slack/Teams user) cannot prove IdP group membership, and the chat
+        card has no endorsed-awaiting-second state, so actions that pin
+        approver_groups or demand a second approver are REFUSED here and
+        must be decided in the web inbox. Otherwise the chat allowlist
+        would silently satisfy a stronger control. Raises ChatNotPermitted."""
+        tenant = tenant or self.tenant
+        await self._require_chat_decidable(approval_id, tenant)
+        try:
+            a = await self.ledger.decide(approval_id, approved=approved,
+                                         reviewer=reviewer, reason=reason,
+                                         tenant=tenant)
+        except AlreadyDecided:
+            # the racing decider already called the agent back
+            return await self.ledger.approval(approval_id, tenant=tenant)
+        except UnknownApproval:
+            log.warning("chat decision for unknown approval %s", approval_id)
+            return None
+        # the agent's callback_url is served by the ledger's decision hook
+        # (outbox row in the decision transaction) — same as a web decision
+        return a
+
+    async def _require_chat_decidable(self, approval_id: str,
+                                      tenant: str) -> None:
+        if self.policy is None:
+            return
+        a = await self.ledger.approval(approval_id, tenant=tenant)
+        if a is None:
+            return
+        # the case's snapshot binds as well as the live rule (B6)
+        live = await self.policy.policy_for(a["tool"], tenant)
+        stored = a.get("policy") or {}
+        if any(r and (r.get("approver_groups") or []) for r in (stored, live)):
+            raise self.ChatNotPermitted(
+                "this action restricts approvers to specific groups; "
+                "decide it in the web inbox with your SSO identity")
+        if any(r and r.get("require_second_approval") for r in (stored, live)):
+            raise self.ChatNotPermitted(
+                "this action requires two approvers (dual control); "
+                "decide it in the web inbox")
+
+    async def record_refusal(self, approval_id: str, reviewer: str,
+                             surface: str, verb: str,
+                             tenant: str | None = None) -> None:
+        """An unauthorized click is refused AND becomes part of the record."""
+        log.warning("unauthorized %s %s attempt on %s by %s",
+                    surface, verb, approval_id, reviewer)
+        try:
+            await self.ledger.annotate(
+                approval_id, reviewer,
+                f"unauthorized {surface} {verb} attempt refused "
+                f"(user not in the approver allowlist)",
+                tenant=tenant or self.tenant)
+        except UnknownApproval:
+            pass

app/config.py

@@ -0,0 +1,258 @@
+"""Service settings, env-driven. Only database_url is required to boot."""
+from __future__ import annotations
+
+from functools import lru_cache
+
+from pydantic import field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", env_prefix="PRIMARYPATH_", extra="ignore")
+
+    # compose passes unset optionals as empty strings; treat those as unset
+    @field_validator(
+        "signing_key_path", "oidc_issuer", "oidc_client_id",
+        "oidc_client_secret", "oidc_redirect_url", "session_secret",
+        "service_token", "admin_token", "slack_bot_token", "slack_signing_secret",
+        "signing_ring_path", "pkcs11_module", "pkcs11_token_label", "pkcs11_pin",
+        "siem_endpoint", "siem_token", "teams_app_id", "teams_app_password",
+        "teams_service_url", "teams_conversation_id",
+        "slack_channel", "web_dist",
+        "sla_default_seconds", "sla_escalation_channel",
+        "sla_escalation_webhook", "webhook_secret", "csp", "secure_cookies",
+        mode="before")
+    @classmethod
+    def _empty_env_is_none(cls, v):
+        return None if v == "" else v
+
+    database_url: str = "postgresql://primarypath:primarypath@localhost:5432/primarypath"
+    host: str = "127.0.0.1"  # non-loopback binds require auth or insecure=true
+    port: int = 8123
+    insecure: bool = False  # explicit opt-in to expose an unauthenticated deploy
+    # k8s: a pre-install/pre-upgrade Job runs migrations instead, so N
+    # replicas don't race Alembic at startup
+    migrate_on_start: bool = True
+
+    # F18 — observability
+    log_json: bool = True
+    log_level: str = "info"
+
+    # CORS: empty = no cross-origin (the inbox is same-origin with the API).
+    # Set a csv of allowed origins only if a separate front-end needs them.
+    cors_allow_origins: str = ""
+
+    # Rate limiting on abuse-sensitive endpoints (auth, decisions, chat
+    # interactions) — per client IP, fixed 1-minute window. 0 disables. Reads
+    # and agent polling are never limited. In-memory and per-replica; put a
+    # limiter at your ingress too for multi-replica deployments.
+    rate_limit_per_minute: int = 60
+    # per-credential fixed-window limit on authenticated AGENT writes
+    # (create approval, ingest run events, evals, gate). Reads and
+    # polling are never limited. In-memory, per replica.
+    agent_write_rate_per_minute: int = 600
+    # bodies over this are 413 before a handler runs
+    max_body_bytes: int = 1_048_576
+
+    # transport posture (TLS terminates at the ingress). None = derive
+    # from public_url (https => secure). Secure => cookies are Secure and
+    # __Host-prefixed, and HSTS is sent.
+    secure_cookies: bool | None = None
+    # override the computed Content-Security-Policy (see app/security.py)
+    csp: str | None = None
+    session_secret_min_length: int = 32
+
+    @property
+    def cors_origins(self) -> list[str]:
+        return [o.strip() for o in self.cors_allow_origins.split(",") if o.strip()]
+
+    # static inbox build (F04): path to web/dist; served at / when set
+    web_dist: str | None = None
+
+    # base URL used in outbound links (Slack messages, etc.)
+    public_url: str = "http://127.0.0.1:8123"
+
+    # webhook delivery (F02): a transactional outbox with a leased worker.
+    # attempts is the dead-letter threshold; backoff is base*2^n capped at
+    # max; the worker leases a row for lease_s per attempt (a crashed
+    # replica's row is retried by another after that); secret enables the
+    # HMAC signature header (the Ed25519 one rides on the audit key).
+    webhook_attempts: int = 10
+    webhook_backoff_base: float = 0.5
+    webhook_backoff_max: float = 300.0
+    webhook_poll_interval_s: float = 1.0  # <= 0 disables the worker
+    webhook_lease_s: float = 30.0
+    webhook_secret: str | None = None
+    # SSRF guard: callback_url targeting private/loopback hosts is refused
+    # unless this is set (self-hosted internal webhooks). The cloud-metadata
+    # link-local range is always refused.
+    webhook_allow_private: bool = False
+
+    # F09/F15 — audit signing. Backend "file" (default) or "pkcs11" (the
+    # private key lives in the customer's HSM/KMS and never leaves it).
+    signing_backend: str = "file"
+    signing_key_path: str | None = None
+    signing_ring_path: str | None = None  # pkcs11 mode: where the pubring lives
+    pkcs11_module: str | None = None
+    pkcs11_token_label: str | None = None
+    pkcs11_pin: str | None = None
+    pkcs11_key_label: str = "primarypath-audit"
+    # execution grants: how long an executor has to redeem the grant minted
+    # with a decision. Grants need a signer (file or pkcs11); without one,
+    # approvals carry no grant and a grant-requiring executor refuses.
+    grant_ttl_s: int = 300
+    # how long an Idempotency-Key is remembered (a retry later than this
+    # is a new request); expired by the maintenance loop below
+    idempotency_ttl_s: int = 7 * 24 * 3600
+    # housekeeping cadence (idempotency-key expiry), independent of every
+    # feature loop; <= 0 disables it, with a startup warning, and nothing
+    # then expires the keys
+    maintenance_interval_s: float = 60.0
+
+    # F06 — human plane (OIDC sessions) and agent plane (service token)
+    oidc_issuer: str | None = None
+    oidc_client_id: str | None = None
+    oidc_client_secret: str | None = None
+    oidc_redirect_url: str | None = None
+    oidc_scopes: str = "openid profile email"
+    oidc_algorithms: str = "RS256"  # csv; e.g. "RS256,ES256" per your IdP
+    session_secret: str | None = None
+    session_ttl_s: int = 8 * 3600
+    # agent plane: create approvals, ingest run events, poll status. This
+    # token must never satisfy admin surfaces — every governed agent holds it.
+    service_token: str | None = None
+    # operator plane: full audit export, key rotation, admin endpoints.
+    admin_token: str | None = None
+
+    # F08 — SLAs. Deadlines resolve request > per-tool > default; None = no SLA.
+    sla_default_seconds: int | None = None
+    sla_by_tool: str = ""  # "refund:600,rollback_deploy:120"
+    sla_remind_before_seconds: int = 300
+    sla_escalate_to: str = "ops"
+    sla_escalation_channel: str | None = None
+    sla_escalation_webhook: str | None = None
+    sla_breach_auto_deny: bool = False
+    sla_scan_interval_s: float = 5.0  # <= 0 disables the background loop
+
+    def sla_for_tool(self, tool: str) -> int | None:
+        for part in self.sla_by_tool.split(","):
+            if ":" in part:
+                name, _, secs = part.strip().partition(":")
+                if name == tool and secs.strip().isdigit():
+                    return int(secs)
+        return self.sla_default_seconds
+
+    # F17 — Microsoft Teams routing (mirrors Slack; off when unconfigured)
+    teams_app_id: str | None = None
+    teams_app_password: str | None = None
+    teams_service_url: str | None = None
+    teams_conversation_id: str | None = None
+    # AAD object ids allowed to decide; empty = NOBODY (fail closed)
+    teams_approvers: str = ""
+    teams_openid_config_url: str = (
+        "https://login.botframework.com/v1/.well-known/openidconfiguration")
+    teams_token_issuer: str = "https://api.botframework.com"
+
+    @property
+    def teams_approver_ids(self) -> set[str]:
+        return {x.strip() for x in self.teams_approvers.split(",") if x.strip()}
+
+    # F21 — policy & rollout. Enforcement consults live policy_view; an
+    # action with no rule falls back to fail-safe (require approval).
+    policy_default_requires_approval: bool = True
+    policy_graduation_min_decisions: int = 10
+    policy_graduation_approval_rate: float = 0.95
+    policy_demotion_rejection_rate: float = 0.2
+    # the rollout track record counts approvals and incidents from the
+    # last N days (0 = all history); reported on every row as window_days
+    policy_rollout_lookback_days: int = 90
+
+    # F22 — traces & cost. Optional per-model prices, USD per 1M tokens:
+    # "claude-opus-4-8:15/75,claude-sonnet-5:3/15". Empty -> tokens only,
+    # cost null (honest: tokens are exact, cost is an estimate).
+    model_prices: str = ""
+
+    # F23 — cost governance. The no-budget posture is the client's risk
+    # choice, never hard-coded. "open" (default): an action no budget covers
+    # has no cost gate. "closed": it falls back to cost_default_on_exceed.
+    # Either way the F21 safety gate stays independent and fail-safe.
+    cost_default_posture: str = "open"  # open | closed
+    cost_default_on_exceed: str = "gate"  # gate | deny
+
+    # F24 — admin separation of duties. When false (the shipped default),
+    # the admin ROLE grants no read of agent activity: visibility follows
+    # unit membership, and an admin in no unit sees policy/budgets/tokens/
+    # agents but no inbox, runs, or per-agent audit. When true, an admin
+    # reading activity is break-glass: every such read appends a chained
+    # admin_action. Deployments without a human plane (no OIDC) are the
+    # single-trust dev posture and are not gated. A runtime toggle (an
+    # event-sourced set_config admin_action) overrides this default.
+    admin_can_read_activity: bool = False
+
+    # F16 — SIEM forwarding, off by default. Never blocks the append path.
+    siem: str = "none"  # none | splunk | elastic | syslog
+    siem_endpoint: str | None = None
+    siem_token: str | None = None
+    siem_index: str = "primarypath-audit"
+    siem_syslog_host: str = "127.0.0.1"
+    siem_syslog_port: int = 6514
+    siem_syslog_protocol: str = "tcp"  # tcp | udp
+    siem_batch: int = 500
+    siem_interval_s: float = 2.0  # <= 0 disables the loop
+
+    # F07 — RBAC. Comma-separated. Default deny, always (auth.resolve_roles):
+    # once OIDC is on, a user matching none of these gets NO roles and no
+    # access. Set at least rbac_admin_emails before anyone can use the inbox.
+    rbac_admin_groups: str = ""
+    rbac_approver_groups: str = ""
+    rbac_admin_emails: str = ""
+
+    @staticmethod
+    def _csv(v: str) -> set[str]:
+        return {x.strip() for x in v.split(",") if x.strip()}
+
+    @property
+    def admin_groups(self) -> set[str]:
+        return self._csv(self.rbac_admin_groups)
+
+    @property
+    def approver_groups(self) -> set[str]:
+        return self._csv(self.rbac_approver_groups)
+
+    @property
+    def admin_emails(self) -> set[str]:
+        return self._csv(self.rbac_admin_emails)
+
+    @property
+    def rbac_enabled(self) -> bool:
+        return bool(self.admin_groups or self.approver_groups or self.admin_emails)
+
+    # F05
+    slack_bot_token: str | None = None
+    slack_signing_secret: str | None = None
+    slack_channel: str | None = None
+    # Slack user IDs allowed to decide (comma-separated). Empty = NOBODY can
+    # decide from Slack (fail closed): a verified signature proves the
+    # request came from Slack, not that the clicker is an approver.
+    slack_approvers: str = ""
+
+    @property
+    def slack_approver_ids(self) -> set[str]:
+        return {x.strip() for x in self.slack_approvers.split(",") if x.strip()}
+
+    # F10
+
+    @property
+    def alembic_url(self) -> str:
+        """SQLAlchemy URL for migrations (sync psycopg driver)."""
+        url = self.database_url
+        if url.startswith("postgresql://"):
+            return url.replace("postgresql://", "postgresql+psycopg://", 1)
+        if url.startswith("postgres://"):
+            return url.replace("postgres://", "postgresql+psycopg://", 1)
+        return url
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()