apsimo 1.3.0__py3-none-any.whl

apsimo/gate/context_provenance.py

@@ -0,0 +1,170 @@
+"""Context provenance — the data layer behind the cross-context leak check.
+
+Records which (normalized) entities have appeared in which *conversation context*, so a
+response about to go to one context can be flagged for surfacing an entity that is known
+ONLY from a different, private context. This is the durable, populated replacement for the
+old gate's dead in-memory per-session entity sets.
+
+Generic by design: a ``conversation_key`` is any opaque string the embedding host uses to
+identify a context (e.g. a platform conversation id). Colony attaches no meaning to it.
+
+Privacy model:
+- An entity recorded with ``is_public=True`` in any context is never treated as a leak
+  (public knowledge: place names, public figures, etc.).
+- An entity present in the *current* conversation's provenance is fine (it belongs here).
+- An entity present only in *other* private conversations, surfaced in a reply to this one,
+  is the leak we flag.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import unicodedata
+from datetime import datetime, timezone
+from typing import List, Optional, Sequence
+
+from apsimo.gate.communication_policy import CommunicationPolicyContextV1
+from apsimo.gate.response_guard import CrossContextGuard, GuardFinding
+
+
+def _now() -> str:
+    return datetime.now(tz=timezone.utc).isoformat()
+
+
+def normalize_entity(name: str) -> str:
+    return unicodedata.normalize("NFKC", name or "").lower().strip()
+
+
+class ContextProvenanceStore:
+    """SQLite-backed index of entity -> conversation-context provenance."""
+
+    def __init__(self, db_path: str = ":memory:") -> None:
+        self._conn = sqlite3.connect(db_path)
+        self._conn.row_factory = sqlite3.Row
+        self._conn.execute("PRAGMA journal_mode=WAL")
+        self._create_tables()
+
+    def _create_tables(self) -> None:
+        self._conn.executescript(
+            """
+            CREATE TABLE IF NOT EXISTS context_entities (
+                entity_norm      TEXT NOT NULL,
+                conversation_key TEXT NOT NULL,
+                contact_id       TEXT,
+                is_public        INTEGER NOT NULL DEFAULT 0,
+                first_seen       TEXT NOT NULL,
+                last_seen        TEXT NOT NULL,
+                count            INTEGER NOT NULL DEFAULT 1,
+                PRIMARY KEY (entity_norm, conversation_key)
+            );
+            CREATE INDEX IF NOT EXISTS idx_ctx_entities_norm ON context_entities(entity_norm);
+            """
+        )
+        self._conn.commit()
+
+    def record(
+        self,
+        conversation_key: str,
+        entities: Sequence[str],
+        *,
+        contact_id: Optional[str] = None,
+        is_public: bool = False,
+        min_len: int = 3,
+        at: Optional[str] = None,
+    ) -> int:
+        """Record that ``entities`` appeared in ``conversation_key``. Returns the count kept."""
+        if not conversation_key:
+            return 0
+        now = at or _now()
+        kept = 0
+        for raw in entities or ():
+            n = normalize_entity(raw)
+            if len(n) < min_len:
+                continue
+            self._conn.execute(
+                "INSERT INTO context_entities "
+                "(entity_norm, conversation_key, contact_id, is_public, first_seen, last_seen, count) "
+                "VALUES (?,?,?,?,?,?,1) "
+                "ON CONFLICT(entity_norm, conversation_key) DO UPDATE SET "
+                "last_seen=excluded.last_seen, count=count+1, "
+                "is_public=MAX(is_public, excluded.is_public)",
+                (n, conversation_key, contact_id, 1 if is_public else 0, now, now),
+            )
+            kept += 1
+        self._conn.commit()
+        return kept
+
+    def contexts_for(self, entity: str) -> List[dict]:
+        """Contexts where this entity has appeared: [{conversation_key, is_public}]."""
+        n = normalize_entity(entity)
+        if not n:
+            return []
+        rows = self._conn.execute(
+            "SELECT conversation_key, is_public FROM context_entities WHERE entity_norm=?",
+            (n,),
+        ).fetchall()
+        return [dict(r) for r in rows]
+
+    def close(self) -> None:
+        try:
+            self._conn.close()
+        except Exception:
+            pass
+
+
+class ProvenanceCrossContextGuard(CrossContextGuard):
+    """Flags a reply that surfaces an entity known only from a different private context.
+
+    ``extractor`` (optional ``ConversationExtractor``) pulls entities from the response text
+    itself, so the host need only pass the text; any ``mentioned_entities`` passed in are
+    merged on top. Entities introduced earlier in the *same* conversation (recorded under the
+    same ``conversation_key`` on inbound) are never flagged.
+    """
+
+    def __init__(self, store: ContextProvenanceStore, extractor=None,
+                 public_entities: Optional[Sequence[str]] = None) -> None:
+        self._store = store
+        self._extractor = extractor
+        self._public = {normalize_entity(e) for e in (public_entities or ())}
+
+    async def _entities_in(self, response_text: str, mentioned_entities: Sequence[str]) -> set:
+        ents = {normalize_entity(e) for e in (mentioned_entities or ())}
+        if self._extractor is not None and response_text:
+            try:
+                res = await self._extractor.extract(response_text, "response_guard")
+                ents |= {normalize_entity(getattr(c, "text", None) or getattr(c, "name", ""))
+                         for c in getattr(res, "entities", [])}
+            except Exception:
+                pass
+        return {e for e in ents if e}
+
+    async def check(self, *, response_text: str, conversation_key: Optional[str],
+                    mentioned_entities: Sequence[str],
+                    communication_policy: Optional[
+                        CommunicationPolicyContextV1
+                    ] = None) -> List[GuardFinding]:
+        # The policy is a narrowing input made available to every configured
+        # checker.  Provenance rules intentionally do not use it as an
+        # exemption: even ``owner_explicit`` cannot confer authority here.
+        del communication_policy
+        if not conversation_key:
+            return []
+        findings: List[GuardFinding] = []
+        for ent in await self._entities_in(response_text, mentioned_entities):
+            if ent in self._public:
+                continue
+            contexts = self._store.contexts_for(ent)
+            if not contexts:
+                continue                                   # never seen -> can't be a leak
+            if any(c["is_public"] for c in contexts):
+                continue                                   # public knowledge
+            keys = {c["conversation_key"] for c in contexts}
+            if conversation_key in keys:
+                continue                                   # belongs to this conversation
+            findings.append(GuardFinding(
+                check="cross_context",
+                severity="block",
+                reason=f"entity {ent!r} is known only from another private conversation",
+                excerpt=f"[{ent}]",
+            ))
+        return findings

apsimo/gate/env_risk.py

@@ -0,0 +1,226 @@
+"""Environment-risk classifier (L1.2) — the auto-ratchet under leveled tom2.
+
+``classify()`` grades ONE conversation, as experienced by ONE reader, into
+R0..R3. It is the input that lets the effective-level resolver auto-degrade
+cross-contact rendering the moment the room gets bigger, stranger, or less
+certain — with no human in the loop.
+
+    R0 owner-private   — census ⊆ {owner}, DM, private gateway.
+    R1 trusted-private — DM with the owner; reader tier >= trusted, strongly
+                         resolved; no other non-owner participant.
+    R2 known-social    — strongly-resolved reader tier >= regular in a DM;
+                         OR a group where EVERY participant is strongly
+                         resolved and tier >= trusted. Private gateway.
+    R3 open/hostile    — the DEFAULT. Any unknown/shadow/peripheral/
+                         group_guest participant, any unresolved group
+                         member, a public/embodied/unclassified gateway, an
+                         unresolved/system/shadow reader, a missing census,
+                         a missing owner identity, or ANY classifier error.
+
+Design pins:
+
+* **Monotone.** Rules only RAISE risk: a lower class is granted solely on
+  positive, verified evidence; every missing signal leaves the conversation
+  at R3.
+* **Fail-closed.** Any exception anywhere (stores, env parsing, lookups)
+  returns R3 with a ``classifier-error`` reason — never a lower class.
+* **Deployment-configured gateways.** Colony ships NO gateway names.
+  ``COLONY_ENV_RISK_GATEWAY_CLASS`` (default empty) maps gateway families to
+  ``private`` / ``public`` / ``embodied``; an unclassified gateway is treated
+  as hostile, so a deployment must explicitly bless its private DM surfaces
+  before anything can grade below R3.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from apsimo.channels.presence import STRONG_METHODS
+from apsimo.identity.participants import SYSTEM_CONTACT_ID
+
+logger = logging.getLogger(__name__)
+
+R0, R1, R2, R3 = 0, 1, 2, 3
+
+_LABELS = {R0: "R0", R1: "R1", R2: "R2", R3: "R3"}
+
+#: Trust-tier ordering for floor checks. Anything unlisted ranks 0 (hostile).
+_TIER_RANK = {
+    "inner_circle": 5,
+    "trusted": 4,
+    "regular": 3,
+    "acquaintance": 2,
+    "group_guest": 2,
+    "peripheral": 1,
+    "unknown": 0,
+    "silenced": 0,
+}
+
+_GATEWAY_CLASSES = ("private", "public", "embodied")
+
+
+@dataclass
+class EnvRisk:
+    level: int
+    reasons: List[str] = field(default_factory=list)
+
+    @property
+    def label(self) -> str:
+        return _LABELS.get(self.level, "R3")
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"level": self.level, "label": self.label,
+                "reasons": list(self.reasons)}
+
+
+def env_risk_window_hours() -> float:
+    """COLONY_ENV_RISK_WINDOW_HOURS (default 48): census recency window."""
+    try:
+        v = float(os.environ.get("COLONY_ENV_RISK_WINDOW_HOURS", "48"))
+        return v if v > 0 else 48.0
+    except (TypeError, ValueError):
+        return 48.0
+
+
+def gateway_class(gateway: str) -> str:
+    """Deployment-declared class for a gateway family, or '' (unclassified).
+
+    COLONY_ENV_RISK_GATEWAY_CLASS is a comma list of ``gateway:class`` pairs
+    (class in private|public|embodied). Malformed entries are ignored — an
+    entry that fails to parse simply leaves its gateway unclassified, which
+    is the hostile default.
+    """
+    g = str(gateway or "").strip().lower()
+    if not g:
+        return ""
+    raw = os.environ.get("COLONY_ENV_RISK_GATEWAY_CLASS", "")
+    for pair in raw.split(","):
+        if ":" not in pair:
+            continue
+        name, cls = pair.split(":", 1)
+        if name.strip().lower() == g:
+            cls = cls.strip().lower()
+            return cls if cls in _GATEWAY_CLASSES else ""
+    return ""
+
+
+def _tier_rank(tier: Any) -> int:
+    return _TIER_RANK.get(str(tier or "").strip().lower(), 0)
+
+
+async def _contact_tier(contacts_store: Any, contact_id: str) -> Optional[str]:
+    """The contact's trust tier, or None when the contact does not resolve."""
+    c = await contacts_store.get(contact_id)
+    if c is None:
+        return None
+    return str(getattr(c, "trust_tier", "") or "")
+
+
+async def classify(conversation_key: str, reader_contact_id: str, *,
+                   presence_store: Any, contacts_store: Any,
+                   owner_id: Optional[str] = None) -> EnvRisk:
+    """Grade one (conversation, reader) pair into R0..R3. Never raises."""
+    try:
+        return await _classify(conversation_key, reader_contact_id,
+                               presence_store=presence_store,
+                               contacts_store=contacts_store,
+                               owner_id=owner_id)
+    except Exception as exc:
+        logger.debug("env-risk classification failed (=> R3): %s", exc,
+                     exc_info=True)
+        return EnvRisk(R3, [f"classifier-error:{type(exc).__name__}"])
+
+
+async def _classify(conversation_key: str, reader_contact_id: str, *,
+                    presence_store: Any, contacts_store: Any,
+                    owner_id: Optional[str]) -> EnvRisk:
+    reasons: List[str] = []
+    conversation_key = str(conversation_key or "").strip()
+    reader = str(reader_contact_id or "").strip()
+
+    # Hard preconditions: each missing signal is terminal (R3).
+    if not conversation_key:
+        return EnvRisk(R3, ["conversation-key-missing"])
+    if not reader or reader == SYSTEM_CONTACT_ID:
+        return EnvRisk(R3, ["reader-unresolved-or-system"])
+    if presence_store is None:
+        return EnvRisk(R3, ["presence-store-missing"])
+    if contacts_store is None:
+        return EnvRisk(R3, ["contacts-store-missing"])
+
+    if owner_id is None:
+        from apsimo.identity.resolver import get_owner_contact_id
+        owner_id = get_owner_contact_id()
+    owner = str(owner_id or "").strip()
+    if not owner:
+        return EnvRisk(R3, ["owner-identity-unset"])
+
+    gateway = conversation_key.split(":", 1)[0]
+    gclass = gateway_class(gateway)
+    if gclass != "private":
+        return EnvRisk(R3, [f"gateway-class:{gclass or 'unclassified'}"])
+
+    window = env_risk_window_hours()
+    census = presence_store.census(conversation_key, window_hours=window)
+    by_id = {str(r.get("contact_id") or ""): r for r in census}
+    if reader not in by_id:
+        # No verified sighting of the reader in this conversation's window —
+        # presence recording is either off or the reader never actually
+        # spoke here. Missing signal.
+        return EnvRisk(R3, ["reader-not-in-census"])
+
+    def _strong(cid: str) -> bool:
+        return str(by_id[cid].get("method") or "").lower() in STRONG_METHODS
+
+    if not _strong(reader):
+        return EnvRisk(R3, [
+            f"reader-resolution-weak:{by_id[reader].get('method') or 'none'}"])
+
+    non_owner = [cid for cid in by_id if cid != owner]
+    is_group = (len(non_owner) > 1
+                or any(str(r.get("group_id") or "").strip() for r in census))
+
+    # R0: an owner-private room — every participant in the window IS the
+    # owner, and the reader being rendered to IS the owner.
+    if reader == owner and not is_group and set(by_id) <= {owner}:
+        return EnvRisk(R0, ["owner-private"])
+
+    if reader == owner:
+        # Owner reading in a room with other people: grade by the room.
+        reasons.append("owner-with-company")
+
+    reader_tier = await _contact_tier(contacts_store, reader)
+    if reader_tier is None:
+        return EnvRisk(R3, ["reader-contact-unresolvable"])
+
+    if not is_group and set(non_owner) <= {reader}:
+        # A true DM between the owner and the (strongly-resolved) reader.
+        if _tier_rank(reader_tier) >= _TIER_RANK["trusted"]:
+            return EnvRisk(R1, ["trusted-private-dm"])
+        if _tier_rank(reader_tier) >= _TIER_RANK["regular"]:
+            return EnvRisk(R2, ["known-social-dm"])
+        return EnvRisk(R3, [f"reader-tier-below-regular:{reader_tier}"])
+
+    if is_group:
+        # R2 group: EVERY participant strongly resolved and tier >= trusted
+        # (the owner is exempt from the tier floor, not from resolution).
+        for cid in by_id:
+            if not _strong(cid):
+                return EnvRisk(R3, [f"group-member-unresolved:{cid}"])
+            if cid == owner:
+                continue
+            tier = await _contact_tier(contacts_store, cid)
+            if tier is None:
+                return EnvRisk(R3, [f"group-member-unresolvable:{cid}"])
+            if _tier_rank(tier) < _TIER_RANK["trusted"]:
+                return EnvRisk(R3, [f"group-member-below-trusted:{cid}"])
+        return EnvRisk(R2, ["known-social-group"])
+
+    # Not a group, but the non-owner set is not just the reader (e.g. a
+    # third party was sighted in the window): hostile.
+    others = sorted(set(non_owner) - {reader})
+    reasons.append("unexpected-co-presence:" + ",".join(others[:5]))
+    return EnvRisk(R3, reasons)