primarypath-server 1.0.0__py3-none-any.whl

app/teams.py

@@ -0,0 +1,276 @@
+"""Microsoft Teams routing: post the case as an Adaptive Card, decide from
+Teams, land in the same tamper-evident log as web and Slack decisions.
+
+Same discipline as Slack:
+- Incoming activities carry a Bot Framework JWT; it is validated against
+  Microsoft's JWKS (iss + aud + exp) before anything else. Unverified =
+  approval forgery = 401, nothing written.
+- The clicker must be in the PRIMARYPATH_TEAMS_APPROVERS allowlist of AAD object
+  ids; empty means NOBODY (fail closed). Unauthorized attempts are
+  refused, answered inline, and recorded as annotations.
+- The decision is an ordinary approval_granted/denied via the shared
+  ChatRouter path; only the reviewer string carries the Teams identity.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import time
+
+import httpx
+import jwt
+from fastapi import HTTPException
+
+from .chat import ChatRouter
+from .ledger import Ledger
+
+log = logging.getLogger("primarypath.teams")
+
+BOTFRAMEWORK_OPENID = "https://login.botframework.com/v1/.well-known/openidconfiguration"
+BOTFRAMEWORK_ISSUER = "https://api.botframework.com"
+LOGIN_URL = ("https://login.microsoftonline.com/botframework.com"
+             "/oauth2/v2.0/token")
+
+
+# -- adaptive cards ---------------------------------------------------------------
+
+
+def _args_summary(arguments: dict, max_items: int = 6) -> str:
+    items = list(arguments.items())
+    shown = "\n".join(f"- **{k}**: {json.dumps(v, ensure_ascii=False)}"
+                      for k, v in items[:max_items])
+    return shown + ("\n- …" if len(items) > max_items else "")
+
+
+def case_card(approval: dict, public_url: str) -> dict:
+    reasoning = approval.get("reasoning") or "(no reasoning recorded)"
+    if len(reasoning) > 600:
+        reasoning = reasoning[:600] + "…"
+    aid = approval["approval_id"]
+    return {
+        "type": "AdaptiveCard", "version": "1.4",
+        "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
+        "body": [
+            {"type": "TextBlock", "weight": "Bolder",
+             "text": f"Approval requested: {approval['tool']}"},
+            {"type": "TextBlock", "wrap": True,
+             "text": _args_summary(approval.get("arguments", {}))},
+            {"type": "TextBlock", "wrap": True, "text": reasoning},
+            {"type": "TextBlock", "isSubtle": True, "size": "Small",
+             "text": f"run {approval['run_id']} · "
+                     f"[open in inbox]({public_url}/?approval={aid})"},
+            {"type": "Input.Text", "id": "reason", "isMultiline": True,
+             "placeholder": "reason (required to reject)"},
+        ],
+        "actions": [
+            {"type": "Action.Submit", "title": "Approve",
+             "data": {"verb": "primarypath_approve", "approval_id": aid}},
+            {"type": "Action.Submit", "title": "Reject",
+             "data": {"verb": "primarypath_reject", "approval_id": aid}},
+        ],
+    }
+
+
+def decided_card(approval: dict, public_url: str) -> dict:
+    icon = "✅" if approval["status"] == "granted" else "⛔"
+    line = (f"{icon} **{approval['status']}** by {approval.get('reviewer')}"
+            + (f": {approval['reason']}" if approval.get("reason") else ""))
+    aid = approval["approval_id"]
+    return {
+        "type": "AdaptiveCard", "version": "1.4",
+        "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
+        "body": [
+            {"type": "TextBlock", "wrap": True,
+             "text": f"`{approval['tool']}` — {line}"},
+            {"type": "TextBlock", "isSubtle": True, "size": "Small",
+             "text": f"run {approval['run_id']} · "
+                     f"[audit in inbox]({public_url}/?approval={aid})"},
+        ],
+        "actions": [],
+    }
+
+
+def _card_activity(card: dict) -> dict:
+    return {"type": "message", "attachments": [{
+        "contentType": "application/vnd.microsoft.card.adaptive",
+        "content": card}]}
+
+
+# -- request verification -------------------------------------------------------------
+
+
+class TeamsRequestVerifier:
+    """Validate the Bot Framework JWT on incoming activities."""
+
+    def __init__(self, app_id: str, openid_config_url: str = BOTFRAMEWORK_OPENID,
+                 issuer: str = BOTFRAMEWORK_ISSUER):
+        self.app_id = app_id
+        self.openid_config_url = openid_config_url
+        self.issuer = issuer
+        self.http = httpx.AsyncClient(timeout=10)
+        self._jwks: dict | None = None
+
+    async def _jwk_key(self, kid: str | None):
+        for attempt in range(2):
+            if self._jwks is None or attempt == 1:
+                cfg = (await self.http.get(self.openid_config_url)).json()
+                self._jwks = (await self.http.get(cfg["jwks_uri"])).json()
+            for k in self._jwks.get("keys", []):
+                if kid is None or k.get("kid") == kid:
+                    return jwt.PyJWK(k).key
+        raise HTTPException(401, "no matching key for bot token")
+
+    async def verify(self, authorization: str) -> dict:
+        if not authorization.startswith("Bearer "):
+            raise HTTPException(401, "missing bot authorization")
+        token = authorization.removeprefix("Bearer ").strip()
+        try:
+            header = jwt.get_unverified_header(token)
+            key = await self._jwk_key(header.get("kid"))
+            return jwt.decode(token, key=key, algorithms=["RS256"],
+                              audience=self.app_id, issuer=self.issuer)
+        except HTTPException:
+            raise
+        except jwt.PyJWTError as e:
+            raise HTTPException(401, f"invalid bot token: {e}") from None
+
+
+# -- the API + router ---------------------------------------------------------------
+
+
+class TeamsAPI:
+    """Thin Bot Framework REST client; tests swap in a stub."""
+
+    def __init__(self, app_id: str, app_password: str, service_url: str):
+        self.app_id = app_id
+        self.app_password = app_password
+        self.service_url = service_url.rstrip("/")
+        self.http = httpx.AsyncClient(timeout=10)
+        self._token: str | None = None
+        self._token_expiry: float = 0.0  # epoch seconds
+
+    async def _bearer(self) -> str:
+        # Bot Framework tokens expire (~1h); refresh a minute early so
+        # notifications don't start failing silently after the first hour.
+        if self._token is None or time.time() >= self._token_expiry:
+            r = await self.http.post(LOGIN_URL, data={
+                "grant_type": "client_credentials",
+                "client_id": self.app_id, "client_secret": self.app_password,
+                "scope": "https://api.botframework.com/.default"})
+            r.raise_for_status()
+            body = r.json()
+            self._token = body["access_token"]
+            self._token_expiry = time.time() + max(0, body.get("expires_in", 3600) - 60)
+        return self._token
+
+    async def post_activity(self, conversation_id: str, activity: dict) -> dict:
+        r = await self.http.post(
+            f"{self.service_url}/v3/conversations/{conversation_id}/activities",
+            json=activity,
+            headers={"Authorization": f"Bearer {await self._bearer()}"})
+        r.raise_for_status()
+        return r.json()  # {"id": activity_id}
+
+    async def update_activity(self, conversation_id: str, activity_id: str,
+                              activity: dict) -> dict:
+        r = await self.http.put(
+            f"{self.service_url}/v3/conversations/{conversation_id}"
+            f"/activities/{activity_id}",
+            json=activity,
+            headers={"Authorization": f"Bearer {await self._bearer()}"})
+        r.raise_for_status()
+        return r.json()
+
+
+class TeamsRouter(ChatRouter):
+    def __init__(self, api, pool, ledger: Ledger, conversation_id: str,
+                 public_url: str, approver_ids: set[str] | None = None,
+                 tenant: str = "default"):
+        super().__init__(ledger, tenant=tenant)
+        self.api = api
+        self.pool = pool
+        self.conversation_id = conversation_id
+        self.public_url = public_url
+        # AAD object ids; empty = nobody can decide from Teams (fail closed)
+        self.approver_ids = approver_ids or set()
+
+    # -- notify + reflect --------------------------------------------------------
+
+    def notify(self, approval: dict) -> None:
+        self._spawn(self._notify(approval))
+
+    async def _notify(self, approval: dict) -> None:
+        out = await self.api.post_activity(
+            self.conversation_id,
+            _card_activity(case_card(approval, self.public_url)))
+        if out.get("id"):
+            async with self.pool.connection() as conn:
+                await conn.execute(
+                    "INSERT INTO teams_messages (tenant_id, approval_id, "
+                    "conversation_id, activity_id) VALUES (%s, %s, %s, %s) "
+                    "ON CONFLICT (tenant_id, approval_id) DO NOTHING",
+                    (approval.get("tenant_id", "default"),
+                     approval["approval_id"], self.conversation_id, out["id"]))
+
+    def reflect(self, approval: dict) -> None:
+        self._spawn(self._reflect(approval))
+
+    async def _reflect(self, approval: dict) -> None:
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(
+                "SELECT conversation_id, activity_id FROM teams_messages "
+                "WHERE tenant_id = %s AND approval_id = %s",
+                (approval.get("tenant_id", "default"),
+                 approval["approval_id"]))
+            ref = await cur.fetchone()
+        if ref:
+            await self.api.update_activity(
+                ref[0], ref[1],
+                _card_activity(decided_card(approval, self.public_url)))
+
+    # -- interactions -----------------------------------------------------------------
+
+    @staticmethod
+    def _reviewer(activity: dict) -> str:
+        frm = activity.get("from", {})
+        name = frm.get("name") or "unknown"
+        aad = frm.get("aadObjectId") or frm.get("id") or "?"
+        return f"{name} (aad:{aad})"
+
+    def _authorized(self, activity: dict) -> bool:
+        frm = activity.get("from", {})
+        return (frm.get("aadObjectId") or frm.get("id")) in self.approver_ids
+
+    async def handle_activity(self, activity: dict) -> dict | None:
+        """Returns a reply activity dict (or None for silent 200)."""
+        value = activity.get("value") or {}
+        verb = {"primarypath_approve": "approve", "primarypath_reject": "reject"}.get(
+            value.get("verb", ""))
+        approval_id = value.get("approval_id", "")
+        if verb is None or not approval_id:
+            return None
+
+        reviewer = self._reviewer(activity)
+        if not self._authorized(activity):
+            await self.record_refusal(approval_id, reviewer, "Teams", verb)
+            return {"type": "message",
+                    "text": "You are not an authorized approver for this "
+                            "workspace; the attempt was recorded in the "
+                            "audit log."}
+
+        reason = (value.get("reason") or "").strip()
+        if verb == "reject" and not reason:
+            return {"type": "message",
+                    "text": "A reason is required to reject — add it in the "
+                            "card's reason box and click Reject again."}
+
+        try:
+            approval = await self.decide_from_chat(
+                approval_id, approved=(verb == "approve"),
+                reviewer=reviewer, reason=reason)
+        except self.ChatNotPermitted as e:
+            await self.record_refusal(approval_id, reviewer, "Teams", verb)
+            return {"type": "message", "text": str(e)}
+        if approval is not None:
+            await self._reflect(approval)
+        return None

app/tokens.py

@@ -0,0 +1,117 @@
+"""Issued API tokens (F22): the agent plane (service) and operator plane
+(admin) kept distinct, exactly like the static env tokens.
+
+Only the sha256 of a token is stored; the plaintext is returned once at
+issue time and never recoverable. A `kind=service` token never satisfies
+admin, and a `kind=admin` token never creates approvals — the token-split
+invariant (F03/F06) holds for issued tokens too. Issuance and revocation
+are recorded as admin_action events in the chain.
+
+F24: a service token carries the agent-to-unit map. `agent_id` and `unit`
+are set at issue time by an admin and resolved server-side on every
+request — the agent cannot claim a different agent or unit, the same
+discipline as the tenant seam.
+"""
+from __future__ import annotations
+
+import hashlib
+import secrets
+import time
+
+DEFAULT_TENANT = "default"
+
+
+def _sha256(token: str) -> str:
+    return hashlib.sha256(token.encode("utf-8")).hexdigest()
+
+
+class TokenStore:
+    def __init__(self, pool):
+        self.pool = pool
+
+    async def any_active(self, kind: str | None = None) -> bool:
+        """Whether any live issued token exists (any tenant). The moment
+        one does, the token planes count as CONFIGURED: a deployment that
+        issued its tokens from the console and set no env token must not
+        keep running with every open-dev fallback wide open.
+
+        Read from the database on every call, deliberately uncached: this
+        is an authentication boundary and the answer is shared state. A
+        per-process cache would let one replica issue a token while
+        another kept the open-dev fallback until restart (and revoking
+        the last token on one replica would leave the others locked).
+        The cost is one EXISTS over a partial index, and only on
+        deployments with no env credential at all — configured
+        deployments short-circuit before reaching here."""
+        q = ("SELECT EXISTS (SELECT 1 FROM api_tokens "
+             "WHERE revoked_ts_ms IS NULL")
+        params: tuple = ()
+        if kind is not None:
+            q += " AND kind = %s"
+            params = (kind,)
+        q += ")"
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(q, params)
+            row = await cur.fetchone()
+        return bool(row[0])
+
+    async def issue(self, kind: str, label: str, by: str,
+                    tenant: str = DEFAULT_TENANT,
+                    agent_id: str | None = None,
+                    unit: str | None = None) -> tuple[str, str]:
+        """Returns (id, plaintext). The plaintext is shown once."""
+        if kind not in ("service", "admin"):
+            raise ValueError("kind must be 'service' or 'admin'")
+        if kind != "service" and (agent_id or unit):
+            raise ValueError("agent/unit apply to service tokens only")
+        token_id = "tok_" + secrets.token_hex(6)
+        plaintext = f"pp_{kind}_{secrets.token_urlsafe(32)}"
+        async with self.pool.connection() as conn:
+            await conn.execute(
+                "INSERT INTO api_tokens (id, tenant_id, kind, token_sha256, "
+                "label, created_ts_ms, created_by, agent_id, unit) "
+                "VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s)",
+                (token_id, tenant, kind, _sha256(plaintext), label,
+                 int(time.time() * 1000), by, agent_id, unit))
+        return token_id, plaintext
+
+    async def revoke(self, token_id: str,
+                     tenant: str = DEFAULT_TENANT) -> bool:
+        """Tenant-scoped: an admin of one tenant cannot revoke another's
+        token by id (the F20 seam; inert while there is one default tenant)."""
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(
+                "UPDATE api_tokens SET revoked_ts_ms = %s "
+                "WHERE id = %s AND tenant_id = %s AND revoked_ts_ms IS NULL",
+                (int(time.time() * 1000), token_id, tenant))
+            return cur.rowcount > 0
+
+    async def verify(self, presented: str, kind: str) -> dict | None:
+        """The live token's record if a token of this kind matches — the
+        server-side source of the agent/unit stamp (never the request
+        body) and of the credential identity that decisions are
+        attributed to (id + label, P3)."""
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(
+                "SELECT tenant_id, agent_id, unit, id, label FROM api_tokens "
+                "WHERE token_sha256 = %s AND kind = %s "
+                "AND revoked_ts_ms IS NULL",
+                (_sha256(presented), kind))
+            row = await cur.fetchone()
+        if row is None:
+            return None
+        return {"tenant_id": row[0], "agent_id": row[1], "unit": row[2],
+                "id": row[3], "label": row[4]}
+
+    async def list(self, tenant: str = DEFAULT_TENANT) -> list[dict]:
+        """Metadata only — never the token or its hash."""
+        async with self.pool.connection() as conn:
+            cur = await conn.execute(
+                "SELECT id, kind, label, created_ts_ms, created_by, "
+                "revoked_ts_ms, agent_id, unit FROM api_tokens "
+                "WHERE tenant_id = %s ORDER BY created_ts_ms DESC", (tenant,))
+            rows = await cur.fetchall()
+        return [{"id": r[0], "kind": r[1], "label": r[2],
+                 "created_ts_ms": r[3], "created_by": r[4],
+                 "revoked": r[5] is not None, "agent": r[6], "unit": r[7]}
+                for r in rows]