pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/tenancy/vault.py

@@ -0,0 +1,204 @@
+"""The vault: the Fernet keys every secret is sealed under, and the vendors' credentials."""
+
+import json
+import logging
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from cryptography.fernet import Fernet, InvalidToken, MultiFernet
+from psycopg import sql
+from psycopg.types.json import Jsonb
+
+from pinecall.domain.names import Credentials, Json
+from pinecall.postgres.pool import Pool
+
+logger = logging.getLogger(__name__)
+
+# The box's own credentials sit beside its other settings, one row per vendor.
+BOX_CREDENTIALS = "credentials/"
+
+OWN = "SELECT vendor, ciphertext FROM provider_keys WHERE org = %(org)s ORDER BY vendor"
+PUT_OWN = """
+INSERT INTO provider_keys (org, vendor, ciphertext) VALUES (%(org)s, %(vendor)s, %(ciphertext)s)
+ON CONFLICT (org, vendor) DO UPDATE SET ciphertext = excluded.ciphertext, set_at = now()
+"""
+DROP_OWN = "DELETE FROM provider_keys WHERE org = %(org)s AND vendor = %(vendor)s RETURNING vendor"
+BOX = """
+SELECT substr(name, length(%(prefix)s) + 1) AS vendor, ciphertext FROM box_settings
+WHERE starts_with(name, %(prefix)s) AND ciphertext IS NOT NULL ORDER BY name
+"""
+PUT_BOX = """
+INSERT INTO box_settings (name, value, ciphertext) VALUES (%(name)s, %(value)s, %(ciphertext)s)
+ON CONFLICT (name) DO UPDATE SET ciphertext = excluded.ciphertext, set_at = now()
+"""
+DROP_BOX = "DELETE FROM box_settings WHERE name = %(name)s RETURNING name"
+
+
+# A row's ctid names it for one statement, and the value it still holds guards the write: a row
+# the gateway wrote meanwhile was written under the first key already, and is left as it is.
+TOKENS = "SELECT ctid::text AS row, {column} AS token FROM {table} WHERE {column} IS NOT NULL"
+RESEAL = "UPDATE {table} SET {column} = %(new)s WHERE ctid = %(row)s::tid AND {column} = %(old)s"
+
+
+@dataclass(frozen=True)
+class SealedColumn:
+    """A column a secret is kept sealed in, by its table."""
+
+    table: str
+    column: str
+
+    @property
+    def named(self) -> str:
+        """The column as a person reads it: table.column."""
+        return f"{self.table}.{self.column}"
+
+
+@dataclass(frozen=True)
+class Resealing:
+    """One column after a pass: re-sealed now, already under the first key, opened by no key."""
+
+    column: SealedColumn
+    resealed: int = 0
+    current: int = 0
+    unopened: int = 0
+
+
+# Every column of the schema a secret is sealed in. A test walks the schema and every Fernet token
+# in it, so a column added without its line here fails the suite.
+SEALED_COLUMNS: tuple[SealedColumn, ...] = (
+    SealedColumn("box_settings", "ciphertext"),
+    SealedColumn("call_private", "sealed"),
+    SealedColumn("carriers", "ciphertext"),
+    SealedColumn("hosted_apps", "sealed_key"),
+    SealedColumn("one_use_words", "sealed"),
+    SealedColumn("org_mail", "ciphertext"),
+    SealedColumn("org_secrets", "sealed"),
+    SealedColumn("org_sso", "ciphertext"),
+    SealedColumn("provider_keys", "ciphertext"),
+    SealedColumn("recording_keys", "sealed"),
+)
+
+
+def sealed(vault: MultiFernet, secret: Json) -> str:
+    """The secret as one Fernet token over its JSON."""
+    return vault.encrypt(json.dumps(secret).encode()).decode()
+
+
+# A token sealed under a key the list no longer holds reads as nothing, said in the log: one
+# stale row must not stop every call of the org.
+def opened(vault: MultiFernet, token: str) -> Json:
+    """The secret a token seals; None when no key listed opens it."""
+    try:
+        return json.loads(vault.decrypt(token.encode()))
+    except InvalidToken:
+        logger.warning(
+            "a secret sealed under a key PINECALL_VAULT_KEY no longer lists reads as unset"
+        )
+        return None
+
+
+async def credentials_of(pool: Pool, vault: MultiFernet, org: str) -> dict[str, Credentials]:
+    """The vendors' credentials the org brought, opened."""
+    async with pool.connection() as connection:
+        rows = await (await connection.execute(OWN, {"org": org})).fetchall()
+    return _opened_rows(vault, [(row["vendor"], row["ciphertext"]) for row in rows])
+
+
+async def vendors_of(pool: Pool, org: str) -> list[str]:
+    """The vendors the org brought its own credentials for, never the credentials."""
+    async with pool.connection() as connection:
+        rows = await (await connection.execute(OWN, {"org": org})).fetchall()
+    return [row["vendor"] for row in rows]
+
+
+async def put_credentials(
+    pool: Pool, vault: MultiFernet, org: str, vendor: str, credentials: Credentials
+) -> None:
+    """Keep the org's credentials for the vendor, replacing any it had."""
+    ciphertext = sealed(vault, credentials)
+    async with pool.connection() as connection:
+        await connection.execute(PUT_OWN, {"org": org, "vendor": vendor, "ciphertext": ciphertext})
+
+
+async def drop_credentials(pool: Pool, org: str, vendor: str) -> bool:
+    """Forget the org's credentials for the vendor; whether it had any."""
+    async with pool.connection() as connection:
+        dropped = await connection.execute(DROP_OWN, {"org": org, "vendor": vendor})
+        return await dropped.fetchone() is not None
+
+
+async def box_credentials(pool: Pool, vault: MultiFernet) -> dict[str, Credentials]:
+    """The credentials the box holds for the vendors it offers, opened."""
+    async with pool.connection() as connection:
+        rows = await (await connection.execute(BOX, {"prefix": BOX_CREDENTIALS})).fetchall()
+    return _opened_rows(vault, [(row["vendor"], row["ciphertext"]) for row in rows])
+
+
+async def put_box_credentials(
+    pool: Pool, vault: MultiFernet, vendor: str, credentials: Credentials
+) -> None:
+    """Keep the box's credentials for the vendor: offering it is holding its key."""
+    row = {
+        "name": f"{BOX_CREDENTIALS}{vendor}",
+        "value": Jsonb({}),
+        "ciphertext": sealed(vault, credentials),
+    }
+    async with pool.connection() as connection:
+        await connection.execute(PUT_BOX, row)
+
+
+async def drop_box_credentials(pool: Pool, vendor: str) -> bool:
+    """Stop offering the vendor on the box's key; whether the box held one."""
+    async with pool.connection() as connection:
+        dropped = await connection.execute(DROP_BOX, {"name": f"{BOX_CREDENTIALS}{vendor}"})
+        return await dropped.fetchone() is not None
+
+
+# Row by row, each its own statement: a pass cut short keeps what it did, and the next pass
+# finds those rows under the first key and leaves them. The first key must be first everywhere
+# (the gateway restarted on the new list) before the old one is taken out.
+async def resealed(pool: Pool, keyring: Sequence[Fernet]) -> list[Resealing]:
+    """Seal every sealed value of the schema under the keyring's first key, and count each."""
+    return [await _resealed_column(pool, keyring, column) for column in SEALED_COLUMNS]
+
+
+async def _resealed_column(
+    pool: Pool, keyring: Sequence[Fernet], column: SealedColumn
+) -> Resealing:
+    names = {"table": sql.Identifier(column.table), "column": sql.Identifier(column.column)}
+    ring, first = MultiFernet(keyring), keyring[0]
+    async with pool.connection() as connection:
+        rows = await (await connection.execute(sql.SQL(TOKENS).format(**names))).fetchall()
+    resealed = current = unopened = 0
+    for row in rows:
+        token = str(row["token"]).encode()
+        if _opens(first, token):
+            current += 1
+            continue
+        try:
+            new = ring.rotate(token).decode()
+        except InvalidToken:
+            unopened += 1
+            continue
+        values = {"new": new, "row": row["row"], "old": row["token"]}
+        async with pool.connection() as connection:
+            written = await connection.execute(sql.SQL(RESEAL).format(**names), values)
+        resealed += written.rowcount
+    return Resealing(column, resealed=resealed, current=current, unopened=unopened)
+
+
+def _opens(key: Fernet, token: bytes) -> bool:
+    try:
+        key.decrypt(token)
+    except InvalidToken:
+        return False
+    return True
+
+
+def _opened_rows(vault: MultiFernet, rows: list[tuple[str, str]]) -> dict[str, Credentials]:
+    kept: dict[str, Credentials] = {}
+    for vendor, ciphertext in rows:
+        secret = opened(vault, ciphertext)
+        if isinstance(secret, str | dict):
+            kept[vendor] = secret
+    return kept

pinecall/tenancy/words.py

@@ -0,0 +1,144 @@
+"""Words spent once, kept in Postgres: any gateway mints one, any gateway spends it."""
+
+import hashlib
+import secrets
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from cryptography.fernet import MultiFernet
+from pydantic import TypeAdapter
+
+from pinecall.postgres.pool import Pool
+
+WORD_BYTES = 24
+
+# The word is kept as its hash and the value sealed: a copy of the table opens nothing.
+KEPT = """
+insert into one_use_words (word_hash, kind, sealed, expires_at)
+values (%(hash)s, %(kind)s, %(sealed)s, %(expires_at)s)
+on conflict (word_hash) do update
+set kind = excluded.kind, sealed = excluded.sealed, expires_at = excluded.expires_at, attempts = 0
+"""
+
+READ = "select sealed, expires_at, attempts from one_use_words where word_hash = %(hash)s"
+
+# Spent once: of two gateways spending one word, one gets the value.
+SPENT = """
+delete from one_use_words where word_hash = %(hash)s and expires_at > %(now)s
+returning sealed, expires_at
+"""
+
+# The value changed in place, its end kept: a terminal given its key.
+FILLED = """
+update one_use_words set sealed = %(sealed)s
+where word_hash = %(hash)s and expires_at > %(now)s
+returning word_hash
+"""
+
+TRIED = """
+update one_use_words set attempts = attempts + 1 where word_hash = %(hash)s returning attempts
+"""
+
+FORGOTTEN = "delete from one_use_words where word_hash = %(hash)s"
+
+SWEPT = "delete from one_use_words where expires_at <= %(now)s"
+
+
+@dataclass(frozen=True)
+class Words:
+    """Where words are kept, the vault their values are sealed under, and the clock they die by."""
+
+    pool: Pool
+    vault: MultiFernet
+    clock: Callable[[], float] = time.time
+
+
+@dataclass(frozen=True)
+class OneUseValue[T]:
+    """A value kept under a one-use word, until when, and how often a guess at it failed."""
+
+    value: T
+    expires_at: float
+    attempts: int = 0
+
+
+class OneUse[T]:
+    """Words of one kind spent once, each dying on its own."""
+
+    def __init__(self, kind: tuple[str, float], adapter: TypeAdapter[T], words: Words) -> None:
+        """The kind is the words' prefix and how long they live; the adapter seals their values."""
+        self.prefix, self.ttl_s = kind
+        self.adapter = adapter
+        self.words = words
+
+    def word(self) -> str:
+        """A new word, not yet holding anything."""
+        return f"{self.prefix}{secrets.token_urlsafe(WORD_BYTES)}"
+
+    async def keep(self, word: str, value: T) -> float:
+        """Hold the value under the word until it dies, and say when."""
+        now = self.words.clock()
+        expires_at = now + self.ttl_s
+        row = {
+            "hash": _hashed(word),
+            "kind": self.prefix,
+            "sealed": self._sealed(value),
+            "expires_at": expires_at,
+        }
+        async with self.words.pool.connection() as connection, connection.transaction():
+            await connection.execute(SWEPT, {"now": now})
+            await connection.execute(KEPT, row)
+        return expires_at
+
+    async def mint(self, value: T) -> tuple[str, float]:
+        """A new word holding the value, and when it dies."""
+        word = self.word()
+        return word, await self.keep(word, value)
+
+    async def read(self, word: str) -> OneUseValue[T] | None:
+        """What the word holds, dead or not, without spending it."""
+        async with self.words.pool.connection() as connection:
+            row = await (await connection.execute(READ, {"hash": _hashed(word)})).fetchone()
+        if row is None:
+            return None
+        return OneUseValue(self._opened(row["sealed"]), row["expires_at"], row["attempts"])
+
+    async def alive(self, word: str) -> OneUseValue[T] | None:
+        """What the word holds while it lives, without spending it."""
+        found = await self.read(word)
+        return None if found is None or found.expires_at <= self.words.clock() else found
+
+    async def spend(self, word: str) -> T | None:
+        """What the word holds, spent: it opens nothing after."""
+        wanted = {"hash": _hashed(word), "now": self.words.clock()}
+        async with self.words.pool.connection() as connection:
+            row = await (await connection.execute(SPENT, wanted)).fetchone()
+        return None if row is None else self._opened(row["sealed"])
+
+    async def fill(self, word: str, value: T) -> bool:
+        """Change what a living word holds, its end kept; False for a dead one."""
+        wanted = {"hash": _hashed(word), "now": self.words.clock(), "sealed": self._sealed(value)}
+        async with self.words.pool.connection() as connection:
+            return await (await connection.execute(FILLED, wanted)).fetchone() is not None
+
+    async def tried(self, word: str) -> int:
+        """Count one more wrong guess at the word, and say how many there were."""
+        async with self.words.pool.connection() as connection:
+            row = await (await connection.execute(TRIED, {"hash": _hashed(word)})).fetchone()
+        return 0 if row is None else int(row["attempts"])
+
+    async def forget(self, word: str) -> None:
+        """The word opens nothing from now on."""
+        async with self.words.pool.connection() as connection:
+            await connection.execute(FORGOTTEN, {"hash": _hashed(word)})
+
+    def _sealed(self, value: T) -> str:
+        return self.words.vault.encrypt(self.adapter.dump_json(value)).decode()
+
+    def _opened(self, sealed: str) -> T:
+        return self.adapter.validate_json(self.words.vault.decrypt(sealed.encode()))
+
+
+def _hashed(word: str) -> bytes:
+    return hashlib.sha256(word.encode()).digest()

pinecall/wire/commands.py

@@ -0,0 +1,350 @@
+"""Every command an app sends, the supervise verbs, and the registry of them."""
+
+from typing import Annotated, Literal
+
+from pydantic import Field
+
+from pinecall.domain.errors import DeclarationRefused
+from pinecall.domain.names import JsonObject
+from pinecall.wire.frames import Command, WireModel
+from pinecall.wire.parts import (
+    AgentConfig,
+    Contact,
+    Route,
+    Supervisor,
+    ToolResult,
+    ToolSpec,
+    TransferMode,
+)
+
+# Which events a command lands in the log as, so a caller knows what to wait for.
+PRODUCES: dict[str, tuple[str, ...]] = {
+    "agent.configure": ("agent.configured",),
+    "agent.drain": ("agent.draining",),
+    "agent.register": ("agent.registered",),
+    "agent.reply": ("turn.agent",),
+    "agent.say": ("turn.agent",),
+    "call.attention": ("attention.requested", "call.line", "attention.answered"),
+    "call.callback": ("callback.requested",),
+    "call.claim": ("call.claimed",),
+    "call.dial": ("call.dialing",),
+    "call.dtmf": (),
+    "call.opt_out": (),
+    "call.event": ("event.received",),
+    "call.hangup": ("call.ended",),
+    "call.hold": ("call.line",),
+    "call.log": ("custom",),
+    "call.mute": ("call.line",),
+    "call.transfer": ("call.transferred",),
+    "call.unhold": ("call.line",),
+    "call.unmute": ("call.line",),
+    "dev.answer": (),
+    "participant.mute": ("track.unpublished",),
+    "participant.remove": ("participant.left",),
+    "ping": ("pong",),
+    "prompt.set": ("prompt.changed",),
+    "room.invite": ("participant.joined",),
+    "room.send": ("room.sent",),
+    "session.configure": ("state.changed", "agent.configured"),
+    "state.set": ("state.changed",),
+    "supervisor.verb": (
+        "supervisor.said",
+        "supervisor.whispered",
+        "supervisor.took_over",
+        "supervisor.released",
+        "supervisor.transferred",
+        "supervisor.ended",
+    ),
+    "tool.result": ("tool.result",),
+    "tools.set": ("tools.changed",),
+}
+
+
+class SayVerb(WireModel):
+    """Make the agent say this, verbatim, to the caller."""
+
+    verb: Literal["say"] = "say"
+    text: str
+
+
+class WhisperVerb(WireModel):
+    """Tell the agent something the caller never hears."""
+
+    verb: Literal["whisper"] = "whisper"
+    text: str
+
+
+class TakeoverVerb(WireModel):
+    """The supervisor takes the line."""
+
+    verb: Literal["takeover"] = "takeover"
+
+
+class ReleaseVerb(WireModel):
+    """The supervisor hands the line back to the agent."""
+
+    verb: Literal["release"] = "release"
+
+
+class TransferVerb(WireModel):
+    """Send the caller to another number."""
+
+    verb: Literal["transfer"] = "transfer"
+    to: str
+    mode: TransferMode | None = None
+
+
+class EndVerb(WireModel):
+    """Hang up on the caller's behalf, at once."""
+
+    verb: Literal["end"] = "end"
+    reason: str | None = None
+
+
+type Verb = Annotated[
+    SayVerb | WhisperVerb | TakeoverVerb | ReleaseVerb | TransferVerb | EndVerb,
+    Field(discriminator="verb"),
+]
+
+
+class AgentConfigure(WireModel):
+    """Declare or change what the agent is; only the fields sent change."""
+
+    config: AgentConfig
+
+
+class AgentDrain(WireModel):
+    """This socket is leaving, and its calls go on without it."""
+
+
+class AgentRegister(WireModel):
+    """The app's first message: this socket speaks for this agent and answers these doors."""
+
+    routes: list[Route]
+    sdk: str | None = None
+    host: str | None = None
+    takes_unclaimed: bool = True
+    answers_dev: bool = False
+
+
+class AgentReply(WireModel):
+    """Make the model speak now, guided by an instruction it reads and the caller never hears."""
+
+    instructions: str
+    allow_interruptions: bool | None = None
+
+
+class AgentSay(WireModel):
+    """Make the agent say this text now, verbatim, outside the model's turn."""
+
+    text: str
+    allow_interruptions: bool | None = None
+
+
+class CallAttention(WireModel):
+    """Ask for a person without sending the caller anywhere."""
+
+    reason: str
+    # Fifteen minutes at most: past it nobody is coming, and the call holds a worker's seat.
+    wait_s: float = Field(gt=0, le=900)
+
+
+class CallCallback(WireModel):
+    """Write down that the caller wants to be called back."""
+
+    number: str
+    when: str | None = None
+    note: str | None = None
+
+
+class CallClaim(WireModel):
+    """The code the caller said, to bind this call to the page that shows it."""
+
+    code: str = Field(pattern="^[0-9]{4}$")
+
+
+class CallDial(WireModel):
+    """Place an outbound call as this agent."""
+
+    to: str
+    from_: str | None = Field(None, alias="from")
+    caller: Contact | None = None
+    metadata: JsonObject | None = None
+
+
+class CallOptOut(WireModel):
+    """The caller asked never to be called again: their number joins the org's do-not-call list."""
+
+    note: str | None = Field(default=None, max_length=500)
+
+
+class CallDtmf(WireModel):
+    """Send touch tones down the line, for an IVR on the far end."""
+
+    digits: str
+
+
+class CallEvent(WireModel):
+    """Hand the agent a fact from the tenant's backend; lands as event.received."""
+
+    name: str
+    data: JsonObject
+
+
+class CallHangup(WireModel):
+    """End the call from the app's side."""
+
+    reason: str | None = None
+
+
+class CallHold(WireModel):
+    """Put the caller on hold: they hear hold audio, the agent hears nothing."""
+
+
+class CallLog(WireModel):
+    """Write a line of the app's own into the call's log."""
+
+    name: str
+    data: JsonObject
+
+
+class CallMute(WireModel):
+    """Mute the agent: it keeps listening and thinking, produces no audio."""
+
+
+class CallTransfer(WireModel):
+    """Send the caller to another number, or bring that number into the call."""
+
+    to: str
+    mode: TransferMode | None = None
+
+
+class CallUnhold(WireModel):
+    """Take the caller off hold."""
+
+
+class CallUnmute(WireModel):
+    """Unmute the agent."""
+
+
+class DevRefusal(WireModel):
+    """Why the verb did not run, in the words the console shows."""
+
+    status: int
+    detail: str
+
+
+class DevAnswer(WireModel):
+    """What came of one dev.request, named by its id."""
+
+    id: str
+    result: JsonObject | None = None
+    refused: DevRefusal | None = None
+
+
+class ParticipantMute(WireModel):
+    """Silence a participant for the rest of the call."""
+
+    identity: str
+
+
+class ParticipantRemove(WireModel):
+    """Put a participant out of the room; removing the caller ends the call."""
+
+    identity: str
+
+
+class Ping(WireModel):
+    """Is the socket alive? The gateway answers pong."""
+
+
+class PromptSet(WireModel):
+    """Rewrite one block of the prompt, whole, by name."""
+
+    name: str
+    text: str
+
+
+class RoomInvite(WireModel):
+    """Bring somebody else into the call's room."""
+
+    to: str
+    kind: Literal["sip", "participant"]
+
+
+class RoomSend(WireModel):
+    """Push a payload to a browser in the room over the DataChannel."""
+
+    topic: str
+    data: JsonObject
+    to: str | None = None
+
+
+class SessionConfigure(WireModel):
+    """Set up this one call before the first turn."""
+
+    state: JsonObject | None = None
+    config: AgentConfig | None = None
+
+
+class StateSet(WireModel):
+    """The app's state changed and this is all of it."""
+
+    state: JsonObject
+    changed: list[str] | None = None
+
+
+class SupervisorVerb(WireModel):
+    """One supervise verb, from the human the door named."""
+
+    by: Supervisor
+    verb: Verb
+
+
+class ToolsSet(WireModel):
+    """The tools the model may see now."""
+
+    tools: list[ToolSpec]
+
+
+COMMANDS: dict[str, type[WireModel]] = {
+    "agent.configure": AgentConfigure,
+    "agent.drain": AgentDrain,
+    "agent.register": AgentRegister,
+    "agent.reply": AgentReply,
+    "agent.say": AgentSay,
+    "call.attention": CallAttention,
+    "call.callback": CallCallback,
+    "call.claim": CallClaim,
+    "call.dial": CallDial,
+    "call.dtmf": CallDtmf,
+    "call.opt_out": CallOptOut,
+    "call.event": CallEvent,
+    "call.hangup": CallHangup,
+    "call.hold": CallHold,
+    "call.log": CallLog,
+    "call.mute": CallMute,
+    "call.transfer": CallTransfer,
+    "call.unhold": CallUnhold,
+    "call.unmute": CallUnmute,
+    "dev.answer": DevAnswer,
+    "participant.mute": ParticipantMute,
+    "participant.remove": ParticipantRemove,
+    "ping": Ping,
+    "prompt.set": PromptSet,
+    "room.invite": RoomInvite,
+    "room.send": RoomSend,
+    "session.configure": SessionConfigure,
+    "state.set": StateSet,
+    "supervisor.verb": SupervisorVerb,
+    "tool.result": ToolResult,
+    "tools.set": ToolsSet,
+}
+
+
+def command_of(command: Command) -> WireModel:
+    """Return the command's data as the model its type names; an unknown type is refused."""
+    model = COMMANDS.get(command.type)
+    if model is None:
+        raise DeclarationRefused(f"unknown command type: {command.type}")
+    return model.read(command.data, command.type)