pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/tenancy/policy.py

@@ -0,0 +1,65 @@
+"""An org's policy: retention, outbound calling rules, what a call says first; one row."""
+
+from pinecall.postgres.pool import Pool
+from pinecall.wire.rest.accounts import CallingHours, OrgPolicy, OrgPolicyRow
+
+POLICY = """
+SELECT retention_days, calling_from, calling_until, per_number_day, consent_everywhere,
+       disclosure, recording_notice, set_by, set_at
+FROM org_policy WHERE org = %(org)s
+"""
+
+PUT_POLICY = """
+INSERT INTO org_policy (org, retention_days, calling_from, calling_until, per_number_day,
+                        consent_everywhere, disclosure, recording_notice, set_by)
+VALUES (%(org)s, %(retention_days)s, %(calling_from)s, %(calling_until)s, %(per_number_day)s,
+        %(consent_everywhere)s, %(disclosure)s, %(recording_notice)s, %(set_by)s)
+ON CONFLICT (org) DO UPDATE SET retention_days = excluded.retention_days,
+    calling_from = excluded.calling_from, calling_until = excluded.calling_until,
+    per_number_day = excluded.per_number_day, consent_everywhere = excluded.consent_everywhere,
+    disclosure = excluded.disclosure, recording_notice = excluded.recording_notice,
+    set_by = excluded.set_by, set_at = now()
+"""
+
+
+async def policy_of(pool: Pool, org: str) -> OrgPolicyRow:
+    """The org's policy, and who set it last; an org nobody set has the platform's defaults."""
+    async with pool.connection() as connection:
+        row = await (await connection.execute(POLICY, {"org": org})).fetchone()
+    if row is None:
+        return OrgPolicyRow(policy=OrgPolicy(), set_by=None, set_at=None)
+    hours = None
+    if row["calling_from"] is not None:
+        hours = CallingHours.model_validate(
+            {"from": row["calling_from"], "until": row["calling_until"]}
+        )
+    return OrgPolicyRow(
+        policy=OrgPolicy(
+            retention_days=row["retention_days"],
+            calling_hours=hours,
+            per_number_day=row["per_number_day"],
+            consent_everywhere=row["consent_everywhere"],
+            disclosure=row["disclosure"],
+            recording_notice=row["recording_notice"],
+        ),
+        set_by=str(row["set_by"]),
+        set_at=row["set_at"].timestamp(),
+    )
+
+
+async def put_policy(pool: Pool, org: str, policy: OrgPolicy, *, by: str) -> None:
+    """Replace the org's policy whole."""
+    hours = policy.calling_hours
+    params = {
+        "org": org,
+        "retention_days": policy.retention_days,
+        "calling_from": None if hours is None else hours.from_,
+        "calling_until": None if hours is None else hours.until,
+        "per_number_day": policy.per_number_day,
+        "consent_everywhere": policy.consent_everywhere,
+        "disclosure": policy.disclosure,
+        "recording_notice": policy.recording_notice,
+        "set_by": by,
+    }
+    async with pool.connection() as connection:
+        await connection.execute(PUT_POLICY, params)

pinecall/tenancy/prompts.py

@@ -0,0 +1,48 @@
+"""Each distinct block of prompt an org's calls were told, kept once under its hash, read back."""
+
+from collections import OrderedDict
+from collections.abc import Collection
+
+from pinecall.domain.agent import block_hash
+from pinecall.postgres.pool import Pool
+
+# The texts this process wrote, remembered so a block is written once and not per call; past it
+# the oldest is forgotten and, met again, costs one insert that finds its row.
+REMEMBERED = 10_000
+
+
+KEPT = """
+INSERT INTO prompts (org, hash, text) VALUES (%(org)s, %(hash)s, %(text)s)
+ON CONFLICT (org, hash) DO NOTHING
+"""
+
+
+TEXTS = "SELECT hash, text FROM prompts WHERE org = %(org)s AND hash = ANY(%(hashes)s)"
+
+
+# Not durable on purpose: the table is the record, this spares it a round trip.
+class Prompts:
+    """The blocks this gateway process has kept already, by org and hash."""
+
+    def __init__(self) -> None:
+        """Nothing kept yet."""
+        self.kept: OrderedDict[tuple[str, str], None] = OrderedDict()
+
+    async def keep(self, pool: Pool, org: str, text: str) -> None:
+        """Keep the text under its hash for the org, once; an empty block is nothing to keep."""
+        key = (org, block_hash(text))
+        if not text or key in self.kept:
+            return
+        async with pool.connection() as connection:
+            await connection.execute(KEPT, {"org": org, "hash": key[1], "text": text})
+        self.kept[key] = None
+        if len(self.kept) > REMEMBERED:
+            self.kept.popitem(last=False)
+
+
+async def texts_of(pool: Pool, org: str, hashes: Collection[str]) -> dict[str, str]:
+    """The org's texts of these hashes, those it kept."""
+    async with pool.connection() as connection:
+        found = await connection.execute(TEXTS, {"org": org, "hashes": list(hashes)})
+        rows = await found.fetchall()
+    return {str(row["hash"]): str(row["text"]) for row in rows}

pinecall/tenancy/reads.py

@@ -0,0 +1,73 @@
+"""Who read what: a key's or the operator's read of a call, a number or memory, once an hour."""
+
+import logging
+from dataclasses import dataclass
+
+import psycopg
+
+from pinecall.domain.scope import Scope
+from pinecall.postgres.pool import Pool
+from pinecall.wire.rest.calls import ReadKind, ReadRow
+
+# The same reader reading the same thing again within the hour is the same read; an org erased
+# has no access log left to write to (a traceback still finds its calls' records).
+RECORD = """
+INSERT INTO reads (org, env, subject, what, reader)
+SELECT %(org)s, %(env)s, %(subject)s, %(what)s, %(reader)s
+WHERE EXISTS (SELECT 1 FROM orgs WHERE id = %(org)s) AND NOT EXISTS (
+    SELECT 1 FROM reads
+    WHERE org = %(org)s AND subject = %(subject)s AND what = %(what)s AND reader = %(reader)s
+      AND env IS NOT DISTINCT FROM %(env)s AND at > now() - interval '1 hour'
+)
+"""
+
+OF_ORG = """
+SELECT subject, what, env, reader, at FROM reads
+WHERE org = %(org)s AND (%(subject)s::text IS NULL OR subject = %(subject)s)
+ORDER BY at DESC, id DESC
+LIMIT %(limit)s
+"""
+
+# Who reads, or erases, on the box's own behalf: off the box, or through its own doors.
+OPERATOR = "operator"
+
+logger = logging.getLogger(__name__)
+
+A_PAGE = 200
+
+
+@dataclass(frozen=True)
+class Read:
+    """One read: the call or the number, what of it, and who."""
+
+    subject: str
+    what: ReadKind
+    reader: str
+
+
+# One statement, awaited: a read waits on its record and on nothing more. A record that cannot be
+# written (the database away, the pool spent) is said in the log and the read goes on: an audit
+# that fails a read would be a way to stop every read.
+async def record(pool: Pool, scope: Scope, read: Read) -> None:
+    """Write the read down, unless the same reader read the same thing within the hour."""
+    params = {"org": scope.org, "env": scope.env, **vars(read)}
+    try:
+        async with pool.connection() as connection:
+            await connection.execute(RECORD, params)
+    except psycopg.Error:
+        logger.warning(
+            "the read of %s by %s went unrecorded; the read goes on",
+            read.subject,
+            read.reader,
+            exc_info=True,
+        )
+
+
+async def of_org(
+    pool: Pool, org: str, *, subject: str | None = None, limit: int = A_PAGE
+) -> list[ReadRow]:
+    """The org's reads, newest first, of one call or number when named."""
+    params = {"org": org, "subject": subject, "limit": limit}
+    async with pool.connection() as connection:
+        rows = await (await connection.execute(OF_ORG, params)).fetchall()
+    return [ReadRow.model_validate({**row, "at": row["at"].timestamp()}) for row in rows]

pinecall/tenancy/recording_keys.py

@@ -0,0 +1,41 @@
+"""A recording's own key: made once per call, kept sealed under the vault, erased with the call."""
+
+import base64
+
+from cryptography.fernet import MultiFernet
+
+from pinecall.postgres.pool import Pool
+from pinecall.process.sealed_audio import new_key
+from pinecall.tenancy.vault import opened, sealed
+
+# The insert is the mint: of two asks at once, or a retry, the first key stands and is the answer.
+# Asked again, the same key; asked for another org's call, nothing (the update's WHERE fails).
+MINT = """
+INSERT INTO recording_keys (call, org, sealed) VALUES (%(call)s, %(org)s, %(sealed)s)
+ON CONFLICT (call) DO UPDATE SET call = excluded.call WHERE recording_keys.org = excluded.org
+RETURNING sealed
+"""
+
+KEY = "SELECT sealed FROM recording_keys WHERE call = %(call)s"
+
+
+async def key_for(pool: Pool, vault: MultiFernet, org: str, call: str) -> bytes | None:
+    """The call's recording key, made now or before; None for another org's, or one unopened."""
+    fresh = sealed(vault, base64.urlsafe_b64encode(new_key()).decode())
+    async with pool.connection() as connection:
+        row = await (
+            await connection.execute(MINT, {"call": call, "org": org, "sealed": fresh})
+        ).fetchone()
+    return None if row is None else _opened(vault, str(row["sealed"]))
+
+
+async def key_of(pool: Pool, vault: MultiFernet, call: str) -> bytes | None:
+    """The call's recording key; None when it has none, or the vault no longer opens it."""
+    async with pool.connection() as connection:
+        row = await (await connection.execute(KEY, {"call": call})).fetchone()
+    return None if row is None else _opened(vault, str(row["sealed"]))
+
+
+def _opened(vault: MultiFernet, token: str) -> bytes | None:
+    secret = opened(vault, token)
+    return base64.urlsafe_b64decode(secret) if isinstance(secret, str) else None

pinecall/tenancy/remembered.py

@@ -0,0 +1,148 @@
+"""A verified key remembered on this gateway for seconds, forgotten once it or its person change."""
+
+import asyncio
+import contextlib
+import logging
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+from pydantic import BaseModel
+
+from pinecall.domain.errors import NotAvailable
+from pinecall.postgres.pool import Pool, box_task
+from pinecall.process.signal import Signal
+from pinecall.tenancy import keys
+from pinecall.tenancy.keys import Bearer
+from pinecall.tenancy.people import fingerprint
+
+logger = logging.getLogger(__name__)
+
+
+# Verifying a key is a round trip per request, 15 % of a gateway's core under load (measured
+# 2026-09-30). A key is remembered this long; a revocation or a change to its person is said on the
+# signal and forgets it everywhere at once, so the seconds are only what a gateway that cannot hear
+# the signal keeps, and what a change made outside the doors (a shell, psql) waits.
+REMEMBERED_FOR_S = 5.0
+
+
+# What every gateway hears when a key is revoked, or a person's standing changes (a role, an agent
+# list, production, operator, disabled or removed): what it remembered of them no longer holds.
+CHANNEL = "keys:forgotten"
+
+
+RETRY_S = 1.0
+
+
+class Forgotten(BaseModel):
+    """What to forget: one key by its fingerprint, or every key of a person."""
+
+    fingerprint: str | None = None
+    subject: str | None = None
+
+
+@dataclass(frozen=True)
+class Remembered:
+    """A verified key, and the clock reading it is forgotten at."""
+
+    bearer: Bearer
+    until: float
+
+
+class RememberedKeys:
+    """The keys this gateway verified lately, by fingerprint, and the revocations it hears."""
+
+    def __init__(
+        self,
+        pool: Pool,
+        signal: Signal,
+        *,
+        for_s: float = REMEMBERED_FOR_S,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        """Nothing remembered yet; `start` listens for revocations."""
+        self.pool = pool
+        self.signal = signal
+        self.for_s = for_s
+        self.clock = clock
+        self.kept: dict[str, Remembered] = {}
+        self.listening: asyncio.Task[None] | None = None
+        self.swept_at = clock()
+
+    async def start(self) -> None:
+        """Listen for revocations said by any gateway."""
+        if self.listening is None:
+            self.listening = box_task(self._listened())
+
+    async def close(self) -> None:
+        """Stop listening and forget everything."""
+        if self.listening is not None:
+            self.listening.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self.listening
+            self.listening = None
+        self.kept.clear()
+
+    async def verify(self, bearer: str) -> Bearer | None:
+        """The key and its person, from memory within the seconds, else as keys.verify answers."""
+        hashed = fingerprint(bearer)
+        now = self.clock()
+        remembered = self.kept.get(hashed)
+        if remembered is not None and remembered.until > now:
+            return remembered.bearer
+        verified = await keys.verify(self.pool, bearer)
+        if verified is None:
+            self.kept.pop(hashed, None)
+            return None
+        until = now + self.for_s
+        if verified.key.expires_at is not None:
+            left = (verified.key.expires_at - datetime.now(UTC)).total_seconds()
+            until = min(until, now + max(left, 0.0))
+        self.kept[hashed] = Remembered(verified, until)
+        self._swept(now)
+        return verified
+
+    # Forgotten here before the door answers, and said to every other gateway: a signal that is
+    # away queues it, so the other gateways keep the key for the seconds and no longer.
+    def forget(self, *, fingerprint: str | None = None, subject: str | None = None) -> None:
+        """Forget a key, or a person's keys, on every gateway."""
+        forgotten = Forgotten(fingerprint=fingerprint, subject=subject)
+        self._forgotten(forgotten)
+        self.signal.publish(CHANNEL, forgotten.model_dump_json().encode())
+
+    def _forgotten(self, forgotten: Forgotten) -> None:
+        if forgotten.fingerprint is not None:
+            self.kept.pop(forgotten.fingerprint, None)
+        if forgotten.subject is not None:
+            for hashed in [h for h, kept in self.kept.items() if _of(kept, forgotten.subject)]:
+                del self.kept[hashed]
+
+    # Keys verified once and never again would stay: swept each period.
+    def _swept(self, now: float) -> None:
+        if now - self.swept_at < self.for_s:
+            return
+        self.swept_at = now
+        for hashed in [h for h, kept in self.kept.items() if kept.until <= now]:
+            del self.kept[hashed]
+
+    async def _listened(self) -> None:
+        while True:
+            try:
+                listening = await self.signal.subscribe(CHANNEL)
+            except NotAvailable:
+                await asyncio.sleep(RETRY_S)
+                continue
+            # What was revoked while the signal was away is unknown: nothing is trusted from before.
+            self.kept.clear()
+            try:
+                async for data in listening:
+                    self._forgotten(Forgotten.model_validate_json(data))
+            finally:
+                listening.close()
+            with contextlib.suppress(TimeoutError):
+                await asyncio.wait_for(self.signal.connected(), RETRY_S)
+
+
+def _of(kept: Remembered, subject: str) -> bool:
+    return kept.bearer.key.subject == subject

pinecall/tenancy/retention.py

@@ -0,0 +1,86 @@
+"""Retention: calls past their org's days (policy.py); call records and dials past 24 months."""
+
+from dataclasses import dataclass
+
+from pinecall.domain.names import parse_env
+from pinecall.domain.scope import Scope
+from pinecall.postgres.pool import Pool, unbounded
+from pinecall.process.recordings import Recordings
+from pinecall.tenancy import erasure
+
+# Every statement of the nightly run is unbounded: it reads and deletes across every org's years.
+# Sealed calls only: a call still running is the caller's, not the calendar's. Oldest first, so a
+# run cut short by its limit takes up where it stopped.
+DUE = """
+SELECT head.call, head.org, head.env, head.holder
+FROM call_log_head head JOIN org_policy policy ON policy.org = head.org
+WHERE head.call IS NOT NULL AND head.sealed AND head.started_at IS NOT NULL
+  AND policy.retention_days IS NOT NULL
+  AND head.started_at < %(now)s - policy.retention_days * 86400
+ORDER BY head.started_at
+LIMIT %(limit)s
+"""
+
+# An erased phone call's record (erasure.py) and every dial (dial_policy.py) are kept for a
+# carrier's traceback this long, then forgotten. A record of a call that never started goes by
+# when it ended, or when it was erased.
+RECORDS_KEPT_S = 730 * 86400
+
+FORGET_RECORDS = """
+DELETE FROM call_records
+WHERE coalesce(started_at, ended_at, extract(epoch FROM erased_at)) < %(before)s
+"""
+
+FORGET_DIALS = "DELETE FROM dials WHERE at < to_timestamp(%(before)s)"
+
+# Who asked, in the erasure trail, for what the calendar erased.
+RETENTION = "retention"
+
+# One night's work at most; what is left over is the next night's.
+A_RUN_ERASES = 5000
+
+
+@dataclass(frozen=True)
+class Due:
+    """A sealed call past its org's days: whose it is, and which."""
+
+    scope: Scope
+    call: str
+
+
+async def due(pool: Pool, now: float, *, limit: int = A_RUN_ERASES) -> list[Due]:
+    """The sealed calls whose org keeps fewer days than they have, oldest first."""
+    async with unbounded(pool) as connection:
+        rows = await (await connection.execute(DUE, {"now": now, "limit": limit})).fetchall()
+    return [
+        Due(
+            Scope(str(row["org"]), parse_env(str(row["env"])), str(row["holder"] or "")),
+            str(row["call"]),
+        )
+        for row in rows
+    ]
+
+
+async def purge(
+    pool: Pool, recordings: Recordings, now: float, *, limit: int = A_RUN_ERASES
+) -> list[str]:
+    """Erase every call past its org's days, one erasure each; the calls erased."""
+    erased: list[str] = []
+    for call in await due(pool, now, limit=limit):
+        await erasure.call(pool, recordings, call.scope, call.call, by=RETENTION)
+        erased.append(call.call)
+    return erased
+
+
+async def forget_records(pool: Pool, now: float) -> int:
+    """Forget the records of erased calls more than 24 months old; how many."""
+    async with unbounded(pool) as connection:
+        done = await connection.execute(FORGET_RECORDS, {"before": now - RECORDS_KEPT_S})
+    return done.rowcount
+
+
+async def forget_dials(pool: Pool, now: float) -> int:
+    """Forget the dials placed or refused more than 24 months ago; how many."""
+    async with unbounded(pool) as connection:
+        done = await connection.execute(FORGET_DIALS, {"before": now - RECORDS_KEPT_S})
+    return done.rowcount