pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/tenancy/tokens.py

@@ -0,0 +1,400 @@
+"""The JWTs the gateway signs: a room token and its dispatch, a seat, a log token, a code token."""
+
+import secrets
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import timedelta
+from typing import Literal
+
+import jwt
+from livekit.api import AccessToken, VideoGrants
+from livekit.protocol.room import RoomConfiguration
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from pinecall.domain.names import Env
+from pinecall.domain.person import RoomScope
+from pinecall.domain.scope import SCOPE_ATTRIBUTE, Scope
+from pinecall.postgres.pool import Pool
+from pinecall.tenancy.keys import (
+    A_SEAT,
+    A_SEAT_LASTS_S,
+    A_VISITOR,
+    AGENT_ATTRIBUTE,
+    BOUND_TO_ONE_CALL,
+    CODE_ATTRIBUTE,
+    ENV_ATTRIBUTE,
+    JWT_PARTS,
+    MINTED,
+    NAME_ATTRIBUTE,
+    PROJECTION_ATTRIBUTE,
+    SUBJECT_ATTRIBUTE,
+    THE_MICROPHONE,
+    Bearer,
+)
+from pinecall.wire.parts import Projection
+
+# One statement on every open: the update is the spend, atomic (of two dispatches racing, one
+# updates the row), and the join says what the ledger held before it. A token is spent only by the
+# org, the world and the agent it was minted for; one minted before its world was kept (no env) is
+# held to its org and agent.
+SPEND = """
+WITH spent AS (
+    UPDATE tokens SET spent_at = now()
+    WHERE call = %(call)s AND spent_at IS NULL AND org = %(org)s AND agent = %(agent)s
+      AND (env IS NULL OR env = %(env)s)
+    RETURNING call
+)
+SELECT (SELECT count(*) FROM spent) AS spent, tokens.call AS minted, tokens.spent_at
+FROM (SELECT 1) AS probe LEFT JOIN tokens ON tokens.call = %(call)s
+"""
+
+
+IDENTITY_BYTES = 6
+
+
+type Spending = Literal["spent", "already_spent", "never_minted", "minted_elsewhere"]
+
+
+ONE_VISIT_TTL_S = 60
+
+
+# The header of a token the gateway signs with its own key; a LiveKit token names no key id.
+OUR_KEY_ID = "pinecall"
+
+
+# Longer than any call, short enough that a copied link dies the same day.
+READ_TTL_S = 4 * 60 * 60
+
+
+@dataclass(frozen=True)
+class Signer:
+    """The LiveKit pair a room token is signed with, and the gateway's own key for every other."""
+
+    api_key: str
+    secret: str
+    # A log token and a code token open no room, so LiveKit never reads them: they are signed with
+    # this key, which no worker holds, and the pair every worker holds forges none.
+    own: str
+
+
+@dataclass(frozen=True)
+class Visitor:
+    """Who a room token seats, until when, and the dispatch it carries."""
+
+    expires_at: float
+    identity: str | None = None
+    subject: str | None = None
+    name: str | None = None
+    # Signed inside the token, so the browser cannot change the agent, org or world it reaches.
+    dispatch: RoomConfiguration | None = None
+
+
+@dataclass(frozen=True)
+class Visit:
+    """What a checked room token says."""
+
+    call: str
+    scope: RoomScope
+    expires_at: float
+    identity: str | None = None
+    subject: str | None = None
+    name: str | None = None
+    projection: Projection | None = None
+    # A code token names its code, agent and world instead of a call; `call` is "" for it.
+    code: str | None = None
+    agent: str | None = None
+    env: Env | None = None
+
+
+class _Room(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    room: str = ""
+
+
+class _Answer(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    scope: RoomScope = Field(alias=SCOPE_ATTRIBUTE)
+    subject: str | None = Field(None, alias=SUBJECT_ATTRIBUTE)
+    name: str | None = Field(None, alias=NAME_ATTRIBUTE)
+    projection: Projection | None = Field(None, alias=PROJECTION_ATTRIBUTE)
+    code: str | None = Field(None, alias=CODE_ATTRIBUTE)
+    agent: str | None = Field(None, alias=AGENT_ATTRIBUTE)
+    env: Env | None = Field(None, alias=ENV_ATTRIBUTE)
+
+
+# livekit's claims, the ones a token of ours carries; its verifier drops `exp`.
+class _Claims(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    exp: float
+    sub: str | None = None
+    video: _Room = _Room()
+    attributes: _Answer
+
+
+@dataclass(frozen=True)
+class SupervisorSeat:
+    """A person's seat in a live call: the token and who it says they are."""
+
+    call: str
+    identity: str
+    token: str
+    subject: str | None
+    name: str | None
+
+
+@dataclass(frozen=True)
+class MintedToken:
+    """A room token as the ledger keeps it: one call, spent once."""
+
+    call: str
+    org: str
+    env: Env
+    agent: str
+    scope: RoomScope
+    expires_at: float
+
+
+@dataclass(frozen=True, kw_only=True)
+class Grant:
+    """What a room token of one scope may do."""
+
+    connects: bool
+    audio: bool
+    reads_log: bool
+    own_call_only: bool
+    ttl_s: int | None
+    # `audio` publishes and subscribes; `hears` only subscribes; `hidden` is not seen in the room;
+    # `writes` sends on the call's data channel, which the agent reads as the caller's words.
+    hears: bool = False
+    hidden: bool = False
+    writes: bool = False
+
+
+GRANTS: Mapping[RoomScope, Grant] = {
+    # It reads its own call's log too, so a browser holds one token.
+    "talk": Grant(
+        connects=True,
+        audio=True,
+        writes=True,
+        reads_log=True,
+        own_call_only=True,
+        ttl_s=ONE_VISIT_TTL_S,
+    ),
+    # It subscribes: livekit delivers its text streams to subscribers only.
+    "chat": Grant(
+        connects=True,
+        audio=False,
+        hears=True,
+        writes=True,
+        reads_log=True,
+        own_call_only=True,
+        ttl_s=ONE_VISIT_TTL_S,
+    ),
+    "observe": Grant(
+        connects=False,
+        audio=False,
+        hears=True,
+        hidden=True,
+        reads_log=True,
+        own_call_only=False,
+        ttl_s=None,
+    ),
+    # Not hidden: livekit delivers no track of a hidden seat, so a takeover would be silent.
+    "supervise": Grant(
+        connects=False,
+        audio=True,
+        reads_log=True,
+        own_call_only=False,
+        ttl_s=None,
+    ),
+    "read": Grant(
+        connects=False,
+        audio=False,
+        reads_log=True,
+        own_call_only=True,
+        ttl_s=READ_TTL_S,
+    ),
+    "participate": Grant(
+        connects=False,
+        audio=False,
+        writes=True,
+        reads_log=True,
+        own_call_only=True,
+        ttl_s=None,
+    ),
+}
+
+
+# From the credential, never from a parameter: a scope that reads beyond its own call is the
+# tenant's; an API key is the tenant.
+PROJECTION_OF: Mapping[RoomScope, Projection] = {
+    scope: "tenant" if grant.reads_log and not grant.own_call_only else "public"
+    for scope, grant in GRANTS.items()
+}
+
+
+# What POST /v1/tokens may mint: the scopes that join a room.
+MINTED_FOR_A_VISIT: frozenset[RoomScope] = frozenset(
+    scope for scope, grant in GRANTS.items() if grant.connects
+)
+
+
+def is_a_jwt(bearer: str) -> bool:
+    """Whether the bearer is shaped like a token, not a key: its shape, not its signature."""
+    parts = bearer.split(".")
+    return len(parts) == JWT_PARTS and all(parts)
+
+
+def room_token(signer: Signer, call: str, scope: RoomScope, visitor: Visitor) -> str:
+    """A token that seats the visitor in the call's room with the scope's grants."""
+    grant = GRANTS[scope]
+    grants = VideoGrants(
+        room=call,
+        room_join=True,
+        can_publish=grant.audio,
+        can_subscribe=grant.audio or grant.hears,
+        # A widget writes to its call over the data channel; one that watches or listens does not.
+        can_publish_data=grant.writes,
+        can_publish_sources=[THE_MICROPHONE] if grant.audio else [],
+        hidden=grant.hidden,
+    )
+    who = {
+        attribute: value
+        for attribute, value in (
+            (SUBJECT_ATTRIBUTE, visitor.subject),
+            (NAME_ATTRIBUTE, visitor.name),
+        )
+        if value
+    }
+    token = (
+        AccessToken(signer.api_key, signer.secret)
+        .with_identity(visitor.identity or _identity(A_VISITOR))
+        .with_grants(grants)
+        # livekit takes a lifetime and stamps the expiry itself.
+        .with_ttl(timedelta(seconds=visitor.expires_at - time.time()))
+        .with_attributes({**who, SCOPE_ATTRIBUTE: scope})
+    )
+    if visitor.dispatch is not None:
+        token = token.with_room_config(visitor.dispatch)
+    return token.to_jwt()
+
+
+def seat(signer: Signer, call: str, scope: RoomScope, bearer: Bearer) -> SupervisorSeat:
+    """A seat for the key's person in a live call, to listen or to supervise."""
+    identity = _identity(A_SEAT)
+    name = bearer.member.name if bearer.member is not None else bearer.key.name
+    visitor = Visitor(
+        expires_at=time.time() + A_SEAT_LASTS_S,
+        identity=identity,
+        subject=bearer.key.subject,
+        name=name,
+    )
+    token = room_token(signer, call, scope, visitor)
+    return SupervisorSeat(
+        call=call, identity=identity, token=token, subject=bearer.key.subject, name=name
+    )
+
+
+# It names the call's room without the right to join it: livekit refuses it, and our doors read
+# it as the call's.
+def log_token(signer: Signer, call: str, projection: Projection) -> str:
+    """A token that reads one call's log and recording, through the projection named."""
+    attributes = {SCOPE_ATTRIBUTE: "read", PROJECTION_ATTRIBUTE: projection}
+    return _unjoinable(signer, call, READ_TTL_S, attributes)
+
+
+def code_token(signer: Signer, code: str, agent: str, world: Env, expires_at: float) -> str:
+    """A token that asks after one caller code until the code dies; it opens no room."""
+    attributes = {
+        SCOPE_ATTRIBUTE: "read",
+        CODE_ATTRIBUTE: code,
+        AGENT_ATTRIBUTE: agent,
+        ENV_ATTRIBUTE: world,
+    }
+    return _unjoinable(signer, f"code:{code}", expires_at - time.time(), attributes)
+
+
+def read(signer: Signer, token: str) -> Visit | None:
+    """What a token of ours says; None for anything else, whatever the reason."""
+    try:
+        ours = jwt.get_unverified_header(token).get("kid") == OUR_KEY_ID
+        decoded = jwt.decode(
+            token,
+            signer.own if ours else signer.secret,
+            algorithms=["HS256"],
+            options={"require": ["exp"]},
+            leeway=0,
+        )
+        claims = _Claims.model_validate(decoded)
+    except (jwt.PyJWTError, ValidationError):
+        return None
+    data = claims.attributes
+    # A livekit token minted for another purpose with the same pair reads nothing here, and a
+    # listener hears the room but reads no log. A reading token is the gateway's own key's alone:
+    # one in its shape under the pair is a worker's forgery.
+    if (
+        not claims.video.room
+        or data.scope not in BOUND_TO_ONE_CALL
+        or ours != (data.scope == "read")
+    ):
+        return None
+    return Visit(
+        call="" if data.code is not None else claims.video.room,
+        scope=data.scope,
+        expires_at=claims.exp,
+        identity=claims.sub,
+        subject=data.subject,
+        name=data.name,
+        projection=data.projection,
+        code=data.code,
+        agent=data.agent,
+        env=data.env,
+    )
+
+
+async def minted(pool: Pool, token: MintedToken) -> None:
+    """Keep a room token the ledger will spend once, when its call opens."""
+    values = {
+        "call": token.call,
+        "org": token.org,
+        "env": token.env,
+        "agent": token.agent,
+        "scope": token.scope,
+        "expires_at": token.expires_at,
+    }
+    async with pool.connection() as connection:
+        await connection.execute(MINTED, values)
+
+
+async def spend(pool: Pool, call: str, scope: Scope, agent: str) -> Spending:
+    """Spend the call's token in the scope the worker names, once; otherwise say why not."""
+    wanted = {"call": call, "org": scope.org, "env": scope.env, "agent": agent}
+    async with pool.connection() as connection:
+        row = await (await connection.execute(SPEND, wanted)).fetchone()
+    if row is not None and row["spent"]:
+        return "spent"
+    if row is None or row["minted"] is None:
+        return "never_minted"
+    return "minted_elsewhere" if row["spent_at"] is None else "already_spent"
+
+
+# The shape LiveKit gives a token (sub, exp, video, attributes), so one reader reads both; signed
+# with the gateway's own key under its key id, and joining no room.
+def _unjoinable(signer: Signer, room: str, ttl_s: float, attributes: dict[str, str]) -> str:
+    now = int(time.time())
+    claims = {
+        "sub": _identity(A_VISITOR),
+        "iat": now,
+        "exp": now + int(ttl_s),
+        "video": {"room": room, "roomJoin": False},
+        "attributes": attributes,
+    }
+    return jwt.encode(claims, signer.own, algorithm="HS256", headers={"kid": OUR_KEY_ID})
+
+
+def _identity(prefix: str) -> str:
+    return f"{prefix}{secrets.token_hex(IDENTITY_BYTES)}"

pinecall/tenancy/traceback.py

@@ -0,0 +1,70 @@
+"""A number's calls for a carrier's traceback: the calls kept, the calls erased, every dial."""
+
+import time
+from datetime import datetime
+
+from psycopg.rows import DictRow
+
+from pinecall.domain.names import parse_e164, parse_env
+from pinecall.domain.scope import Scope
+from pinecall.postgres.pool import Pool
+from pinecall.tenancy import reads
+from pinecall.tenancy.reads import Read
+from pinecall.tenancy.retention import RECORDS_KEPT_S
+from pinecall.wire.rest.ops import Traceback, TracebackCall, TracebackDial
+
+# A kept call's facts, then an erased call's record: the same columns, oldest first. A call that
+# never started (a dial nobody answered) is placed by when it ended.
+CALLS = """
+SELECT call, org, env, direction, from_number, to_number, started_at, ended_at, end_reason, erased
+FROM (
+    SELECT head.call, head.org, head.env, facts.direction, facts.from_number, facts.to_number,
+           head.started_at, facts.ended_at, facts.end_reason, false AS erased
+    FROM call_facts facts JOIN call_log_head head ON head.call = facts.call
+    WHERE facts.channel = 'phone'
+      AND (facts.from_number = %(number)s OR facts.to_number = %(number)s)
+    UNION ALL
+    SELECT call, org, env, direction, from_number, to_number, started_at, ended_at, end_reason, true
+    FROM call_records WHERE from_number = %(number)s OR to_number = %(number)s
+) found
+WHERE coalesce(started_at, ended_at, 0) >= %(since)s
+ORDER BY coalesce(started_at, ended_at, 0)
+"""
+
+# Every dial to the number, placed or refused, with who asked.
+DIALS = """
+SELECT org, env, agent, call, shown, asked_by, refused, at FROM dials
+WHERE dialled = %(number)s AND at >= to_timestamp(%(since)s)
+ORDER BY at
+"""
+
+
+async def of_number(pool: Pool, number: str, since: float | None = None) -> Traceback:
+    """Every phone call with the number and every dial to it, since an epoch second or 24 months."""
+    kept = parse_e164(number)
+    start = time.time() - RECORDS_KEPT_S if since is None else since
+    params = {"number": kept, "since": start}
+    # independent: the calls and the dials of a number, read apart
+    async with pool.connection() as connection:
+        calls = await (await connection.execute(CALLS, params)).fetchall()
+        dials = await (await connection.execute(DIALS, params)).fetchall()
+    return Traceback(
+        number=kept,
+        since=start,
+        calls=[TracebackCall.model_validate(row) for row in calls],
+        dials=[_dial(row) for row in dials],
+    )
+
+
+async def read_by(pool: Pool, found: Traceback, reader: str) -> None:
+    """Write the lookup into the access log of every org whose calls or dials it showed."""
+    seen = {(call.org, call.env) for call in found.calls if call.org is not None}
+    seen |= {(dial.org, dial.env) for dial in found.dials}
+    for org, env in sorted(seen, key=str):
+        scope = Scope(org, parse_env(env) if env else "production")
+        await reads.record(pool, scope, Read(found.number, "traceback", reader))
+
+
+def _dial(row: DictRow) -> TracebackDial:
+    at: datetime = row["at"]
+    return TracebackDial.model_validate({**row, "at": at.timestamp()})

pinecall/tenancy/usage.py

@@ -0,0 +1,136 @@
+"""What an org used in a world, month by month: the totals admission reads, and their refold."""
+
+from dataclasses import dataclass
+from datetime import UTC, date, datetime
+
+from psycopg.rows import DictRow
+
+from pinecall.domain.names import Env, parse_env
+from pinecall.log.reduce import Metered, Usage, usage_row
+from pinecall.log.store import entry_of
+from pinecall.postgres.pool import Pool, unbounded
+
+# A quota is the month's: what the org used in the world in one calendar month, one row.
+USED = """
+SELECT calls, minutes, messages, input_tokens, output_tokens, characters, cost_usd
+FROM usage_totals WHERE org = %(org)s AND env = %(env)s AND period = %(month)s
+"""
+
+# A budget is the org's in both worlds: a month's spend is every world's row of that month.
+SPENT_IN = """
+SELECT coalesce(sum(cost_usd), 0) AS spent FROM usage_totals
+WHERE org = %(org)s AND period = %(month)s
+"""
+
+# The refold holds the table while it reads the log, so a summary written meanwhile waits and is
+# counted after the table is rewritten, never twice and never lost.
+HELD = "LOCK TABLE usage_totals IN EXCLUSIVE MODE"
+
+SUMMARIES = """
+SELECT head.org, head.env, entry.call, entry.seq, entry.ts, entry.agent, entry.type,
+       entry.ephemeral, entry.data
+FROM call_log entry JOIN call_log_head head ON head.log = entry.log
+WHERE entry.type = 'call.summary' AND head.org IS NOT NULL AND head.env IS NOT NULL
+"""
+
+FORGOTTEN = "DELETE FROM usage_totals"
+
+WRITTEN = """
+INSERT INTO usage_totals
+    (org, env, period, calls, minutes, messages, input_tokens, output_tokens, characters, cost_usd)
+VALUES (%(org)s, %(env)s, %(period)s, %(calls)s, %(minutes)s, %(messages)s, %(input_tokens)s,
+        %(output_tokens)s, %(characters)s, %(cost_usd)s)
+"""
+
+ROWS = """
+SELECT org, env, period, calls, minutes, messages, input_tokens, output_tokens, characters,
+       cost_usd
+FROM usage_totals
+"""
+
+
+@dataclass(frozen=True, order=True)
+class Month:
+    """Whose a row of the totals is: the org, the world, the calendar month (UTC)."""
+
+    org: str
+    env: Env
+    period: date
+
+
+async def used(pool: Pool, org: str, env: Env, month: date) -> Usage:
+    """What the org's calls in the world consumed in the month: one row read."""
+    params = {"org": org, "env": env, "month": month.replace(day=1)}
+    async with pool.connection() as connection:
+        row = await (await connection.execute(USED, params)).fetchone()
+    return Usage() if row is None else _usage(row)
+
+
+async def spent_in(pool: Pool, org: str, month: date) -> float:
+    """What the org's calls in both worlds cost in the month their summaries were written."""
+    params = {"org": org, "month": month.replace(day=1)}
+    async with pool.connection() as connection:
+        row = await (await connection.execute(SPENT_IN, params)).fetchone()
+    return 0.0 if row is None else float(row["spent"])
+
+
+async def rebuild(pool: Pool) -> dict[Month, Usage]:
+    """Refold the totals from every summary in the log, as the usage feed folds each one."""
+    async with unbounded(pool) as connection:
+        await connection.execute(HELD)
+        rows = await (await connection.execute(SUMMARIES)).fetchall()
+        refolded: dict[Month, Usage] = {}
+        for row in rows:
+            month = Month(str(row["org"]), parse_env(str(row["env"])), month_of(row["ts"]))
+            consumed = usage_row(Metered(position=0, org=month.org, entry=entry_of(row))).used
+            refolded[month] = refolded.get(month, Usage()) + consumed
+        await connection.execute(FORGOTTEN)
+        async with connection.cursor() as cursor:
+            await cursor.executemany(
+                WRITTEN,
+                [
+                    {**vars(month), **_columns(consumed)}
+                    for month, consumed in sorted(refolded.items())
+                ],
+            )
+    return refolded
+
+
+async def totals(pool: Pool) -> dict[Month, Usage]:
+    """Every row of the totals, as the database keeps them."""
+    async with pool.connection() as connection:
+        rows = await (await connection.execute(ROWS)).fetchall()
+    return {
+        Month(str(row["org"]), parse_env(str(row["env"])), row["period"]): _usage(row)
+        for row in rows
+    }
+
+
+def month_of(ts: float) -> date:
+    """The calendar month, in UTC, a summary written at that time is counted in."""
+    return datetime.fromtimestamp(ts, UTC).date().replace(day=1)
+
+
+def _usage(row: DictRow) -> Usage:
+    return Usage(
+        calls=int(row["calls"]),
+        minutes=float(row["minutes"]),
+        messages=int(row["messages"]),
+        input_tokens=int(row["input_tokens"]),
+        output_tokens=int(row["output_tokens"]),
+        characters=int(row["characters"]),
+        cost_usd=float(row["cost_usd"]),
+    )
+
+
+# A summary's usage has no judge calls: they are its score's, which the totals do not count.
+def _columns(used: Usage) -> dict[str, object]:
+    return {
+        "calls": used.calls,
+        "minutes": used.minutes,
+        "messages": used.messages,
+        "input_tokens": used.input_tokens,
+        "output_tokens": used.output_tokens,
+        "characters": used.characters,
+        "cost_usd": used.cost_usd,
+    }