pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/tenancy/mail.py

@@ -0,0 +1,458 @@
+"""Mail: the mailboxes a letter goes out through, the box's brand, and SMTP."""
+
+import asyncio
+import logging
+import re
+import smtplib
+import ssl
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from email.message import EmailMessage
+from email.utils import parseaddr
+from typing import Literal
+from urllib.parse import unquote, urlsplit
+
+from cryptography.fernet import MultiFernet
+from psycopg.types.json import Jsonb
+
+from pinecall.domain.errors import DeclarationRefused, UpstreamFailed
+from pinecall.domain.names import AN_ADDRESS, Json
+from pinecall.postgres.pool import Pool
+from pinecall.process import resolver
+from pinecall.process.connections import Connections
+from pinecall.tenancy.letters import Letter
+from pinecall.tenancy.vault import opened, sealed
+
+# starttls on 587, implicit TLS on 465; none only for a relay on this machine or a private network.
+type Security = Literal["starttls", "tls", "none"]
+
+
+# Where a mailbox was read from: the org's own, the one the operator stored, the environment's.
+type Source = Literal["org", "stored", "environment"]
+
+
+logger = logging.getLogger(__name__)
+
+
+# No spaces or slashes: it catches `smtp.example.com/`.
+A_HOST = re.compile(r"^[A-Za-z0-9.\-_\[\]:]+$")
+
+
+HIGHEST_PORT = 65535
+
+
+TIMEOUT_S = 10.0
+
+
+NOT_A_MAIL_URL = "a mail URL starts smtp:// (STARTTLS) or smtps:// (implicit TLS)"
+
+
+NO_SERVER = "the mail URL names no mail server after its `@`"
+
+
+NO_ADDRESS = "{written!r} carries no email address"
+
+
+# Never the URL itself in a refusal: it holds the password.
+REFUSED = "{host}:{port} refused it: {said}"
+
+
+UNREACHABLE = "{host}:{port} did not answer: {said}"
+
+
+TIMED_OUT = "{host}:{port} did not answer in {seconds:g}s"
+
+
+NOT_WRITTEN = "the letter could not be written: {said}"
+
+
+# The password travels in clear on a plain connection: never across the internet.
+NOT_PRIVATE = (
+    "{host} is not on this machine or a private network: a mailbox with no TLS sends its "
+    "password in clear, so it reaches only a relay there; use starttls or tls"
+)
+
+
+# An org's server is on the internet: one inside the box's network is the box's, not the org's.
+NOT_PUBLIC = (
+    "{host} resolves to no public address, or to one that is not: an org's mailbox is a mail "
+    "server on the internet"
+)
+
+
+NOT_PLAIN = (
+    "an org's mailbox is reached over TLS, starttls or tls: none is the box's own relay alone"
+)
+
+
+BOX_MAIL = "mail"
+
+
+ORG_MAIL = """
+SELECT host, port, security, username, sender, ciphertext, verified_at, last_error
+FROM org_mail WHERE org = %(org)s
+"""
+
+
+PUT_ORG_MAIL = """
+INSERT INTO org_mail (org, host, port, security, username, ciphertext, sender)
+VALUES (%(org)s, %(host)s, %(port)s, %(security)s, %(username)s, %(ciphertext)s, %(sender)s)
+ON CONFLICT (org) DO UPDATE SET
+    host = excluded.host, port = excluded.port, security = excluded.security,
+    username = excluded.username, ciphertext = excluded.ciphertext, sender = excluded.sender,
+    verified_at = NULL, last_error = NULL, set_at = now()
+"""
+
+
+DROP_ORG_MAIL = "DELETE FROM org_mail WHERE org = %(org)s RETURNING org"
+
+
+ORG_MAIL_WENT = """
+UPDATE org_mail SET last_error = %(error)s,
+       verified_at = CASE WHEN %(error)s::text IS NULL THEN now() ELSE verified_at END
+WHERE org = %(org)s
+"""
+
+
+SETTING = "SELECT value, ciphertext FROM box_settings WHERE name = %(name)s"
+
+
+PUT_SETTING = """
+INSERT INTO box_settings (name, value, ciphertext) VALUES (%(name)s, %(value)s, %(ciphertext)s)
+ON CONFLICT (name) DO UPDATE SET value = excluded.value, ciphertext = excluded.ciphertext,
+                                 set_at = now()
+"""
+
+
+DROP_SETTING = "DELETE FROM box_settings WHERE name = %(name)s RETURNING name"
+
+
+# The outcome is kept inside the box's row, beside what it names.
+BOX_MAIL_WENT = """
+UPDATE box_settings SET value = value || %(went)s WHERE name = %(name)s
+"""
+
+
+@dataclass(frozen=True)
+class Mailbox:
+    """An SMTP account: the server, the credentials, and who the letters are from."""
+
+    host: str
+    port: int
+    security: Security
+    # Empty for a relay that asks for nothing. The password is kept sealed, never shown.
+    username: str
+    password: str
+    sender: str
+
+    def __post_init__(self) -> None:
+        if not A_HOST.match(self.host):
+            raise DeclarationRefused(f"{self.host!r} is not a host: a mail server is named bare")
+        if not 1 <= self.port <= HIGHEST_PORT:
+            raise DeclarationRefused(f"a port is 1 to {HIGHEST_PORT}, not {self.port}")
+        address_of(self.sender)
+
+
+@dataclass(frozen=True)
+class MailboxStatus:
+    """A mailbox, how its last letter went, and where it was read from."""
+
+    mailbox: Mailbox
+    source: Source
+    verified_at: datetime | None = None
+    last_error: str | None = None
+
+
+class Outbox:
+    """Every letter the gateway sends, through the org's mailbox or the box's, in the background."""
+
+    def __init__(self, connections: Connections, environment: Mailbox | None) -> None:
+        """An outbox with nothing in flight."""
+        self.connections = connections
+        self.environment = environment
+        # Held so the loop cannot collect a letter halfway out.
+        self.in_flight: set[asyncio.Task[None]] = set()
+
+    async def mailbox_for(self, org: str | None) -> MailboxStatus | None:
+        """The org's mailbox, else the box's; with no org, only the box's."""
+        own = (
+            None
+            if org is None
+            else await mail_of(self.connections.pool, self.connections.vault, org)
+        )
+        return own or await box_mail_of(
+            self.connections.pool, self.connections.vault, self.environment
+        )
+
+    # Queued, not delivered: a request never waits on somebody's mail server.
+    async def post(self, org: str | None, letter: Letter) -> bool:
+        """Send the letter in the background; False when nothing here can send it."""
+        if await self.mailbox_for(org) is None:
+            return False
+        task = asyncio.create_task(self._posted(org, letter))
+        self.in_flight.add(task)
+        task.add_done_callback(self.in_flight.discard)
+        return True
+
+    async def sent(self, org: str | None, letter: Letter) -> str | None:
+        """Send and wait, as a test letter does: None when it went, else the server's reply."""
+        existing = await self.mailbox_for(org)
+        if existing is None:
+            return None
+        try:
+            if existing.source == "org":
+                await asyncio.to_thread(check_public, existing.mailbox)
+            await post(existing.mailbox, letter)
+        except UpstreamFailed as refused:
+            await self._went(org, existing.source, str(refused))
+            return str(refused)
+        await self._went(org, existing.source, None)
+        logger.info("mailed %s through %s", letter.subject, existing.mailbox.host)
+        return None
+
+    async def drained(self) -> None:
+        """Wait for every letter in flight."""
+        while self.in_flight:
+            await asyncio.gather(*self.in_flight, return_exceptions=True)
+
+    # A failure is said here: asyncio would say it only when the task is collected.
+    async def _posted(self, org: str | None, letter: Letter) -> None:
+        data = await self.sent(org, letter)
+        if data is not None:
+            logger.warning("could not mail %s: %s", letter.subject, data)
+
+    # Kept on the mailbox the letter went through, never on another.
+    async def _went(self, org: str | None, source: Source, error: str | None) -> None:
+        # independent: one of the two runs, on the mailbox the letter went through
+        async with self.connections.pool.connection() as connection:
+            if source == "org":
+                await connection.execute(ORG_MAIL_WENT, {"org": org, "error": error})
+            elif source == "stored":
+                went: dict[str, Json] = {"last_error": error}
+                if error is None:
+                    went["verified_at"] = datetime.now(UTC).isoformat()
+                await connection.execute(BOX_MAIL_WENT, {"name": BOX_MAIL, "went": Jsonb(went)})
+
+
+SCHEMES: Mapping[str, tuple[int, Security]] = {"smtp": (587, "starttls"), "smtps": (465, "tls")}
+
+
+def address_of(written: str) -> str:
+    """The address in `Name <a@b.c>` or a bare one; refused when there is none."""
+    _, address = parseaddr(written)
+    if not AN_ADDRESS.match(address):
+        raise DeclarationRefused(NO_ADDRESS.format(written=written))
+    return address
+
+
+# Split at the LAST `@`: an SES password is base64 and may hold a raw `/`, which would end a URL's
+# authority for urlsplit.
+def parse_mailbox_url(url: str, sender: str) -> Mailbox:
+    """`smtp://user:pass@host:587` or `smtps://…`, and who letters are from, as a mailbox."""
+    scheme, separated, rest = url.strip().partition("://")
+    if not separated or scheme not in SCHEMES:
+        raise DeclarationRefused(NOT_A_MAIL_URL)
+    port, security = SCHEMES[scheme]
+    userinfo, _, where = rest.rpartition("@")
+    parts = urlsplit(f"{scheme}://{where.split('/', 1)[0]}")
+    if not parts.hostname:
+        raise DeclarationRefused(NO_SERVER)
+    try:
+        named = parts.port
+    except ValueError:
+        raise DeclarationRefused("the mail URL's port is not a number") from None
+    username, _, password = userinfo.partition(":")
+    return Mailbox(
+        host=parts.hostname,
+        port=named or port,
+        security=security,
+        username=unquote(username),
+        password=unquote(password),
+        sender=sender,
+    )
+
+
+async def mail_of(pool: Pool, vault: MultiFernet, org: str) -> MailboxStatus | None:
+    """The org's own mailbox and how its last letter went."""
+    async with pool.connection() as connection:
+        row = await (await connection.execute(ORG_MAIL, {"org": org})).fetchone()
+    if row is None:
+        return None
+    return _status_of(row, opened(vault, row["ciphertext"]), "org")
+
+
+async def put_mail(pool: Pool, vault: MultiFernet, org: str, mailbox: Mailbox) -> None:
+    """Keep the org's own mailbox, the password sealed; how it went is forgotten."""
+    if mailbox.security == "none":
+        raise DeclarationRefused(NOT_PLAIN)
+    values = {**_fields(mailbox), "org": org, "ciphertext": sealed(vault, mailbox.password)}
+    async with pool.connection() as connection:
+        await connection.execute(PUT_ORG_MAIL, values)
+
+
+async def drop_mail(pool: Pool, org: str) -> bool:
+    """Forget the org's own mailbox; whether it had one."""
+    async with pool.connection() as connection:
+        return await (await connection.execute(DROP_ORG_MAIL, {"org": org})).fetchone() is not None
+
+
+async def box_mail_of(
+    pool: Pool, vault: MultiFernet, environment: Mailbox | None
+) -> MailboxStatus | None:
+    """The box's mailbox: the one the operator stored, else the environment's."""
+    async with pool.connection() as connection:
+        row = await (await connection.execute(SETTING, {"name": BOX_MAIL})).fetchone()
+    stored = None if row is None or row["ciphertext"] is None else row
+    if stored is not None:
+        found = _status_of(stored["value"], opened(vault, stored["ciphertext"]), "stored")
+        if found is not None:
+            return found
+    return None if environment is None else MailboxStatus(environment, "environment")
+
+
+async def put_box_mail(pool: Pool, vault: MultiFernet, mailbox: Mailbox) -> None:
+    """Keep the mailbox the box sends through, over the environment's; how it went is forgotten."""
+    values = {
+        "name": BOX_MAIL,
+        "value": Jsonb(_fields(mailbox)),
+        "ciphertext": sealed(vault, mailbox.password),
+    }
+    async with pool.connection() as connection:
+        await connection.execute(PUT_SETTING, values)
+
+
+async def drop_box_mail(pool: Pool) -> bool:
+    """Forget the box's stored mailbox, back to the environment's; whether one was stored."""
+    async with pool.connection() as connection:
+        dropped = await connection.execute(DROP_SETTING, {"name": BOX_MAIL})
+        return await dropped.fetchone() is not None
+
+
+# smtplib gets a timeout of its own: cancelling the thread's future does not stop the thread.
+async def post(mailbox: Mailbox, letter: Letter, *, within_s: float = TIMEOUT_S) -> None:
+    """Hand the letter to the mail server; its own reply when it refuses."""
+    try:
+        message = _message(mailbox, letter)
+    except ValueError as unwritable:
+        raise UpstreamFailed(NOT_WRITTEN.format(said=unwritable)) from unwritable
+    try:
+        await asyncio.wait_for(asyncio.to_thread(_handed, mailbox, message, within_s), within_s)
+    except TimeoutError:
+        text = TIMED_OUT.format(host=mailbox.host, port=mailbox.port, seconds=within_s)
+        raise UpstreamFailed(text) from None
+
+
+# Every address the name resolves to is checked, and a name that does not resolve is refused: the
+# server reached is on the internet, never a service inside the box's network.
+def check_public(mailbox: Mailbox) -> None:
+    """Refuse an org's mailbox that is plain, or that its name puts anywhere but the internet."""
+    if mailbox.security == "none":
+        raise UpstreamFailed(NOT_PLAIN)
+    try:
+        addresses = resolver.addresses_of(mailbox.host)
+    except OSError:
+        raise UpstreamFailed(NOT_PUBLIC.format(host=mailbox.host)) from None
+    if not resolver.all_public(addresses):
+        raise UpstreamFailed(NOT_PUBLIC.format(host=mailbox.host))
+
+
+def parse_security(word: str) -> Security:
+    """The word as how a mailbox is secured; refused when it is none of the three."""
+    match word:
+        case "starttls" | "tls" | "none":
+            return word
+        case _:
+            raise DeclarationRefused(f"a mailbox is secured by starttls, tls or none, not {word!r}")
+
+
+def _status_of(
+    fields: Mapping[str, object], password: Json, source: Source
+) -> MailboxStatus | None:
+    if not isinstance(password, str):
+        return None
+    try:
+        mailbox = Mailbox(
+            host=str(fields["host"]),
+            port=int(str(fields["port"])),
+            security=parse_security(str(fields["security"])),
+            username=str(fields["username"]),
+            password=password,
+            sender=str(fields["sender"]),
+        )
+    except (KeyError, ValueError, DeclarationRefused):
+        logger.warning("a stored mailbox does not read: it is left unused")
+        return None
+    verified = fields.get("verified_at")
+    if isinstance(verified, str):
+        verified = datetime.fromisoformat(verified)
+    error = fields.get("last_error")
+    return MailboxStatus(
+        mailbox=mailbox,
+        source=source,
+        verified_at=verified if isinstance(verified, datetime) else None,
+        last_error=error if isinstance(error, str) else None,
+    )
+
+
+def _fields(mailbox: Mailbox) -> dict[str, Json]:
+    return {
+        "host": mailbox.host,
+        "port": mailbox.port,
+        "security": mailbox.security,
+        "username": mailbox.username,
+        "sender": mailbox.sender,
+    }
+
+
+def _handed(mailbox: Mailbox, message: EmailMessage, timeout: float) -> None:
+    try:
+        with _connected(mailbox, timeout) as server:
+            if mailbox.security == "starttls":
+                server.starttls(context=ssl.create_default_context())
+            if mailbox.username:
+                server.login(mailbox.username, mailbox.password)
+            server.send_message(message)
+    except smtplib.SMTPResponseException as text:
+        spoken = (
+            text.smtp_error.decode("utf-8", "replace")
+            if isinstance(text.smtp_error, bytes)
+            else str(text.smtp_error)
+        )
+        reply = f"{text.smtp_code} {spoken.strip()}"
+        raise UpstreamFailed(
+            REFUSED.format(host=mailbox.host, port=mailbox.port, said=reply)
+        ) from text
+    except (OSError, smtplib.SMTPException) as down:
+        text = f"{type(down).__name__}: {down}"
+        raise UpstreamFailed(
+            UNREACHABLE.format(host=mailbox.host, port=mailbox.port, said=text)
+        ) from down
+
+
+def _connected(mailbox: Mailbox, timeout: float) -> smtplib.SMTP:
+    if mailbox.security == "tls":
+        context = ssl.create_default_context()
+        return smtplib.SMTP_SSL(mailbox.host, mailbox.port, timeout=timeout, context=context)
+    if mailbox.security == "none":
+        return smtplib.SMTP(_private_address(mailbox.host), mailbox.port, timeout=timeout)
+    return smtplib.SMTP(mailbox.host, mailbox.port, timeout=timeout)
+
+
+# Resolved once and connected to by the address checked: a name cannot point elsewhere between.
+def _private_address(host: str) -> str:
+    addresses = resolver.addresses_of(host)
+    if not addresses or not all(item.is_private or item.is_loopback for item in addresses):
+        raise UpstreamFailed(NOT_PRIVATE.format(host=host))
+    return str(addresses[0])
+
+
+# The text first: a client that shows one part shows it, and every link is written out in it.
+def _message(mailbox: Mailbox, letter: Letter) -> EmailMessage:
+    message = EmailMessage()
+    message["From"] = mailbox.sender
+    message["To"] = letter.to
+    message["Subject"] = letter.subject
+    message.set_content(letter.text)
+    message.add_alternative(letter.html, subtype="html")
+    return message

pinecall/tenancy/org_secrets.py

@@ -0,0 +1,123 @@
+"""An org's secrets in a world: the values its hosted apps are started with, kept sealed."""
+
+import re
+from dataclasses import dataclass
+from datetime import datetime
+
+from cryptography.fernet import MultiFernet
+
+from pinecall.domain.errors import DeclarationRefused, NotFound
+from pinecall.domain.names import Env
+from pinecall.postgres.pool import Pool
+from pinecall.tenancy.vault import opened, sealed
+
+# An environment variable's name, as a shell takes it.
+A_NAME = re.compile(r"^[A-Z][A-Z0-9_]*$")
+
+
+# What the box sets itself on every process it starts.
+RESERVED = "PINECALL_"
+
+
+LONGEST_VALUE = 16 * 1024
+
+
+NOT_A_NAME = "{name!r} is not a secret's name: capitals, digits and underscores, like CRM_TOKEN"
+
+
+IS_THE_BOXS = "{name} is the box's to set: a name starting with PINECALL_ is never an org's secret"
+
+
+TOO_LONG = "a secret is {limit} KB at most"
+
+
+NOT_SET = "the org has no secret called {name} in {env}"
+
+
+SECRETS = """
+SELECT name, set_by, set_at FROM org_secrets
+WHERE org = %(org)s AND env = %(env)s ORDER BY name
+"""
+
+
+SEALED = "SELECT name, sealed FROM org_secrets WHERE org = %(org)s AND env = %(env)s ORDER BY name"
+
+
+WRITE_ONE = """
+INSERT INTO org_secrets (org, env, name, sealed, set_by)
+VALUES (%(org)s, %(env)s, %(name)s, %(sealed)s, %(set_by)s)
+ON CONFLICT (org, env, name) DO UPDATE SET
+    sealed = excluded.sealed, set_by = excluded.set_by, set_at = now()
+"""
+
+
+DROP_ONE = """
+DELETE FROM org_secrets WHERE org = %(org)s AND env = %(env)s AND name = %(name)s RETURNING name
+"""
+
+
+@dataclass(frozen=True)
+class ListedSecret:
+    """A secret as the org's list shows it: its name, who set it and when; never its value."""
+
+    name: str
+    set_by: str
+    set_at: datetime
+
+
+@dataclass(frozen=True)
+class Secret:
+    """One secret written: the world it is for, its name and its value."""
+
+    env: Env
+    name: str
+    value: str
+
+    def __post_init__(self) -> None:
+        if not A_NAME.match(self.name):
+            raise DeclarationRefused(NOT_A_NAME.format(name=self.name))
+        if self.name.startswith(RESERVED):
+            raise DeclarationRefused(IS_THE_BOXS.format(name=self.name))
+        if len(self.value.encode()) > LONGEST_VALUE:
+            raise DeclarationRefused(TOO_LONG.format(limit=LONGEST_VALUE >> 10))
+
+
+async def put_secret(
+    pool: Pool, vault: MultiFernet, org: str, secret: Secret, *, set_by: str
+) -> None:
+    """Keep the org's secret, sealed, replacing the value it had."""
+    values = {
+        "org": org,
+        "env": secret.env,
+        "name": secret.name,
+        "sealed": sealed(vault, secret.value),
+        "set_by": set_by,
+    }
+    async with pool.connection() as connection:
+        await connection.execute(WRITE_ONE, values)
+
+
+async def secrets_of(pool: Pool, org: str, env: Env) -> list[ListedSecret]:
+    """The org's secrets in the world, by name: who set each and when, never a value."""
+    async with pool.connection() as connection:
+        rows = await (await connection.execute(SECRETS, {"org": org, "env": env})).fetchall()
+    return [
+        ListedSecret(name=row["name"], set_by=row["set_by"], set_at=row["set_at"]) for row in rows
+    ]
+
+
+# A value no listed vault key opens is left out: the process starts without it and says so itself.
+async def environment_of(pool: Pool, vault: MultiFernet, org: str, env: Env) -> dict[str, str]:
+    """The org's secrets in the world, opened, by name: what a hosted app is started with."""
+    async with pool.connection() as connection:
+        rows = await (await connection.execute(SEALED, {"org": org, "env": env})).fetchall()
+    values = {row["name"]: opened(vault, row["sealed"]) for row in rows}
+    return {name: value for name, value in values.items() if isinstance(value, str)}
+
+
+async def drop_secret(pool: Pool, org: str, env: Env, name: str) -> None:
+    """Forget one of the org's secrets; NotFound for a name nobody set."""
+    async with pool.connection() as connection:
+        dropped = await connection.execute(DROP_ONE, {"org": org, "env": env, "name": name})
+        if await dropped.fetchone() is None:
+            raise NotFound(NOT_SET.format(name=name, env=env))

pinecall/tenancy/orgs.py

@@ -0,0 +1,78 @@
+"""Orgs: their names, the quotas they are born with, and whether their calls are judged."""
+
+import secrets
+
+from psycopg.rows import DictRow
+
+from pinecall.domain.errors import Conflict
+from pinecall.domain.org import Org
+from pinecall.postgres.pool import Pool
+from pinecall.tenancy.admission import give_first_quotas
+
+CREATE = """
+INSERT INTO orgs (id, slug, name) VALUES (%(id)s, %(slug)s, %(name)s)
+ON CONFLICT (slug) DO NOTHING RETURNING id
+"""
+LISTED = "SELECT id, slug, name FROM orgs ORDER BY created_at, id"
+FIND = "SELECT id, slug, name FROM orgs WHERE id = %(named)s OR slug = %(named)s LIMIT 1"
+# The quotas, keys and secrets of the org go with it by the foreign keys' cascade.
+REMOVE = "DELETE FROM orgs WHERE id = %(org)s RETURNING id"
+# A column nobody set is on: judging is what an org turns off, never what it turns on.
+JUDGED = "SELECT judging IS NOT FALSE AS judged FROM orgs WHERE id = %(org)s"
+SET_JUDGING = "UPDATE orgs SET judging = %(on)s WHERE id = %(org)s"
+
+# An id is minted, never the slug, so a slug can be renamed without touching another row.
+ID_PREFIX = "org_"
+ID_BYTES = 6
+
+SLUG_TAKEN = "{slug} is taken: pick another name for the org"
+
+
+async def create(pool: Pool, slug: str, name: str, *, already: int = 0) -> Org:
+    """Make an org, with the limits the box's admission gives it in each world."""
+    org = Org(id=f"{ID_PREFIX}{secrets.token_hex(ID_BYTES)}", slug=slug, name=name)
+    async with pool.connection() as connection, connection.transaction():
+        row = await (
+            await connection.execute(CREATE, {"id": org.id, "slug": slug, "name": name})
+        ).fetchone()
+        if row is None:
+            raise Conflict(SLUG_TAKEN.format(slug=slug))
+        await give_first_quotas(connection, org.id, already=already)
+    return org
+
+
+async def listed(pool: Pool) -> list[Org]:
+    """Every org, oldest first."""
+    async with pool.connection() as connection:
+        rows = await (await connection.execute(LISTED)).fetchall()
+    return [_org(row) for row in rows]
+
+
+async def find(pool: Pool, named: str) -> Org | None:
+    """The org by its id or its slug."""
+    async with pool.connection() as connection:
+        row = await (await connection.execute(FIND, {"named": named})).fetchone()
+    return None if row is None else _org(row)
+
+
+async def remove(pool: Pool, org: str) -> bool:
+    """Forget the org and everything it holds; whether there was one."""
+    async with pool.connection() as connection:
+        return await (await connection.execute(REMOVE, {"org": org})).fetchone() is not None
+
+
+async def judged(pool: Pool, org: str) -> bool:
+    """Whether the org's calls are judged at hang-up."""
+    async with pool.connection() as connection:
+        row = await (await connection.execute(JUDGED, {"org": org})).fetchone()
+    return row is None or bool(row["judged"])
+
+
+async def set_judging(pool: Pool, org: str, *, on: bool) -> None:
+    """Turn the org's judging on or off."""
+    async with pool.connection() as connection:
+        await connection.execute(SET_JUDGING, {"org": org, "on": on})
+
+
+def _org(row: DictRow) -> Org:
+    return Org(id=row["id"], slug=row["slug"], name=row["name"])