synpath 0.1.0__py3-none-any.whl

synpath/server/models.py

@@ -0,0 +1,75 @@
+"""Wire shapes the HTTP layer adds on top of the library's types.
+
+Everything else on the wire is a library type serialized as-is. These three
+exist because HTTP needs to say things an in-process call does not: where the
+next page starts, what went wrong, and what a venue can do.
+"""
+from __future__ import annotations
+
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel, Field
+
+T = TypeVar("T")
+
+
+class PageResponse(BaseModel, Generic[T]):
+    """A page of results plus where the next one starts.
+
+    Lists are enveloped and single resources are not. The envelope earns its
+    place only when there is a cursor to carry; wrapping a single market in
+    `{"data": ...}` would be ceremony that every generated client has to unwrap
+    for nothing.
+    """
+
+    data: list[T]
+    next_cursor: str | None = Field(
+        default=None,
+        description=(
+            "Pass as `cursor` to fetch the next page. `null` means this venue "
+            "returned no continuation — for a search result that is normal, "
+            "since search is not paged."
+        ),
+    )
+    count: int = Field(description="Rows in `data`, for convenience.")
+
+
+class ErrorDetail(BaseModel):
+    code: str = Field(description="Machine-readable, snake_case: `insufficient_funds`, `risk_rejected`, "
+                                  "`unauthorized`, `validation_error`, ...")
+    message: str = Field(description="For people. Do not branch on it; branch on `code`.")
+    details: dict[str, Any] = Field(
+        default_factory=dict,
+        description=(
+            "Always `venue` (the venue that answered, or null) and `retryable` (true when the request never got a "
+            "verdict: timeout, rate limit, venue down). A risk refusal adds `rule`; a malformed request adds "
+            "`errors`, one entry per field; a rate limit may add `retry_after`."
+        ),
+    )
+
+
+class ErrorBody(BaseModel):
+    """What every non-2xx response carries, on every route of both apps:
+    `{"error": {"code", "message", "details"}}`."""
+
+    error: ErrorDetail
+
+
+class VenueInfo(BaseModel):
+    """What one venue is and what it can do.
+
+    A client should read `has` before calling rather than discovering a gap
+    through a 501. The values mirror the library's `Exchange.has` exactly:
+    `true`, `false` or `"partial"`.
+    """
+
+    id: str
+    name: str
+    book_model: str = Field(
+        description=(
+            "`shared_complement` when both sides of a market read one book "
+            "(Kalshi), `native_per_outcome` when each side owns its own "
+            "(Polymarket)."
+        )
+    )
+    has: dict[str, object]

synpath/server/serve.py

@@ -0,0 +1,236 @@
+"""`synpath serve`: everything a self-hosted synpath runs, in one process.
+
+```bash
+synpath serve                       # every venue whose credentials are in the environment or .env
+synpath serve --config engine.toml  # the venues, risk rules and journal the file names
+```
+
+One process, one event loop:
+
+* the **engine**, with every loop it publishes (`Engine.background()`): the
+  journal's lease, the in-doubt sweep, the poll, the managed-order clock;
+* the **feeds** (`synpath.engine.feeds`): each venue's market and account
+  streams, so stops see prices and parents hear their children fill;
+* **reconciliation**, the **end-of-day** close, **halt/resume** requests
+  written by `synpath halt`, and a periodic status line;
+* the **HTTP API**: the read app at `/` and the trading app at `/trading`,
+  with `/trading/ws/events`.
+
+With no configuration it trades every venue whose credentials it finds and
+still serves market data if it finds none. The first start on a new control
+database creates an owner access token; that token makes every other.
+`SIGINT`/`SIGTERM` stop the HTTP server, apply the halt policy (cancel
+everything resting, by default), close the streams, release the lease.
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import sys
+from dataclasses import dataclass, field
+from typing import Any
+
+from . import local
+
+log = logging.getLogger("synpath.serve")
+
+VENUES = ("kalshi", "polymarket", "polymarket_us")
+
+
+def venues_config(config: dict[str, Any], credentials: dict[str, Any]) -> dict[str, Any]:
+    """The configuration's venues if it names any; otherwise every venue
+    whose credentials are present. Nothing to write for the common case."""
+    if config.get("venues"):
+        return config
+    return {**config, "venues": {venue: {} for venue in VENUES if credentials.get(venue) is not None}}
+
+
+@dataclass
+class Stack:
+    engine: Any
+    feeds: Any | None
+    store: Any
+    app: Any
+    reconciler: Any
+    eod: Any
+    config: dict[str, Any]
+    owner_key: str | None = None
+    """The owner access token created on this start; `None` if the control database
+    already had users."""
+    local_key: str | None = None
+    """The access token on record in the local registry for this server's address."""
+    extra_tasks: dict[str, Any] = field(default_factory=dict)
+
+
+async def build(
+    *,
+    config: dict[str, Any] | None = None,
+    journal: str = "synpath.db",
+    control: str = "synpath-control.db",
+    dotenv: str | None = None,
+    streams: bool = True,
+    adapters: dict[str, Any] | None = None,
+    stream_map: dict[str, Any] | None = None,
+    host: str = "127.0.0.1",
+    port: int = 8000,
+    home_dir: str | None = None,
+) -> Stack:
+    """Assemble and start everything except the HTTP server. `adapters` and
+    `stream_map` let a test inject paper venues and fake streams."""
+    from ..engine.__main__ import build_adapters, risk_from
+    from ..engine.engine import Engine, EngineConfig
+    from ..engine.eod import EndOfDay
+    from ..engine.feeds import Feeds, default_streams
+    from ..engine.reconcile import Reconciler
+    from ..trading.credentials import load_credentials
+    from .api import create_app
+    from .store import ControlStore
+    from .trading import create_trading_app
+
+    config = dict(config or {})
+    credentials = load_credentials(dotenv=dotenv) if adapters is None or (streams and stream_map is None) else {}
+    if adapters is None:
+        config = venues_config(config, credentials)
+        adapters = build_adapters(config, dotenv=dotenv) if config.get("venues") else {}
+        if not adapters:
+            log.warning("synpath serve: no venue credentials found; serving market data only. "
+                        "Run `synpath doctor` to see what is missing.")
+    engine_config = EngineConfig(
+        journal_path=config.get("journal", journal),
+        poll_interval_s=float(config.get("poll_interval_s", 5)),
+        reconcile_interval_s=float(config.get("reconcile_interval_s", 60)),
+        sweep_interval_s=float(config.get("sweep_interval_s", 10)),
+        in_doubt_timeout_s=float(config.get("in_doubt_timeout_s", 20)),
+        halt_policy=config.get("halt_policy", "cancel"),
+    )
+    engine = Engine(adapters, engine_config, risk=risk_from(config))
+    feeds = None
+    if streams and config.get("streams", True):
+        feeds = Feeds(engine, stream_map if stream_map is not None else default_streams(adapters, credentials))
+    reconciler = Reconciler(engine, orphan_policy=config.get("orphan_policy", "report"))
+    eod = EndOfDay(engine, hour_utc=int(config.get("eod_hour_utc", 0)))
+
+    await engine.start()
+    store = await ControlStore(config.get("control", control)).open()
+    owner_key = None
+    if not await store.has_users():
+        _, issued = await store.bootstrap("owner")
+        owner_key = issued.secret
+    # Leave the token where clients on this machine find it (synpath.server.local).
+    stack_key = local.remember(host, port, control=config.get("control", control),
+                               journal=engine_config.journal_path, key=owner_key, home_dir=home_dir)
+    if feeds is not None:
+        await feeds.start()
+
+    app = create_app()
+    app.mount("/trading", create_trading_app(engine, store))
+    app.state.trading_path = "/trading"
+    return Stack(engine=engine, feeds=feeds, store=store, app=app, reconciler=reconciler, eod=eod,
+                 config=config, owner_key=owner_key, local_key=stack_key)
+
+
+def background(stack: Stack) -> dict[str, Any]:
+    """Every coroutine the stack needs running beside the HTTP server."""
+    from ..engine.__main__ import _control_loop, _reconcile_loop, _status_loop
+
+    engine = stack.engine
+    loops: dict[str, Any] = dict(engine.background())
+    if stack.feeds is not None:
+        loops.update(stack.feeds.background())
+    loops["reconcile"] = _reconcile_loop(engine, stack.reconciler, engine.config.reconcile_interval_s)
+    loops["control"] = _control_loop(engine, asyncio.Event())
+    loops["eod"] = stack.eod.loop()
+    loops["status"] = _status_loop(engine, float(stack.config.get("status_interval_s", 60)))
+    return loops
+
+
+async def shutdown(stack: Stack) -> None:
+    engine = stack.engine
+    if stack.config.get("halt_on_exit", True) and engine.running:
+        try:
+            await engine.halt("the server is shutting down", policy=engine.config.halt_policy)
+        except Exception:
+            log.exception("synpath serve: halting on exit failed")
+    if stack.feeds is not None:
+        await stack.feeds.close()
+    await engine.stop()
+    await stack.store.close()
+    for adapter in engine.adapters.values():
+        try:
+            await adapter.close()
+        except Exception:
+            pass
+
+
+async def serve(args: argparse.Namespace) -> int:
+    import uvicorn
+
+    from ..engine.__main__ import load_config
+    from ..engine.journal import LeaseLost
+
+    logging.basicConfig(level=getattr(logging, args.log_level.upper(), logging.INFO),
+                        format="%(asctime)s %(levelname)s %(message)s")
+    config = load_config(args.config) if args.config else {}
+    try:
+        stack = await build(config=config, journal=args.journal, control=args.control, dotenv=args.dotenv,
+                            streams=not args.no_streams, host=args.host, port=args.port)
+    except LeaseLost as exc:
+        print(str(exc), file=sys.stderr)
+        return 3
+    if args.host in local.LOOPBACK:
+        # On this machine the token is found, not typed: the library reads the
+        # registry. Only say where it is.
+        if stack.owner_key:
+            print(f"\n  A new control database. Its owner access token is in {local.registry_path()} (readable by you only);\n"
+                  "  synpath.Client(server=...) and the TypeScript client on this machine use it automatically.\n"
+                  "  To reach this server from elsewhere, send that token as `Authorization: Bearer <token>`.\n")
+    elif stack.owner_key:
+        print("\n  A new control database: this is the owner access token. It is shown once.\n"
+              f"    {stack.owner_key}\n"
+              "  Send it as `Authorization: Bearer <token>` to /trading; it can issue every other token.\n")
+    if args.host not in ("127.0.0.1", "localhost", "::1"):
+        print(f"warning: binding to {args.host}. The market-data routes at / have no authentication; "
+              "/trading requires an access token. Put a proxy with TLS in front of anything public.")
+
+    server = uvicorn.Server(uvicorn.Config(stack.app, host=args.host, port=args.port, log_level=args.log_level.lower()))
+    loop = asyncio.get_running_loop()
+    tasks = [loop.create_task(coro, name=f"synpath-{name}") for name, coro in background(stack).items()]
+
+    def _died(task: asyncio.Task) -> None:
+        if not task.cancelled() and task.exception() is not None:
+            log.error("synpath serve: %s failed: %s; stopping", task.get_name(), task.exception())
+            server.should_exit = True
+    for task in tasks:
+        task.add_done_callback(_died)
+
+    engine = stack.engine
+    print(f"synpath serving on http://{args.host}:{args.port} (trading at /trading), "
+          f"venues: {', '.join(sorted(engine.adapters)) or 'none'}, journal: {engine.config.journal_path}")
+    try:
+        await server.serve()
+    finally:
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        await shutdown(stack)
+        print("synpath stopped; the lease is released")
+    return 0
+
+
+def parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="synpath serve", description="Run the engine, the venues' streams and the "
+                                "HTTP API (market data at /, trading at /trading) in one process.")
+    p.add_argument("--host", default="127.0.0.1", help="default: 127.0.0.1")
+    p.add_argument("--port", type=int, default=8000, help="default: 8000")
+    p.add_argument("--config", default=None, help="TOML or JSON: venues, risk, journal. Optional")
+    p.add_argument("--journal", default="synpath.db", help="the engine's journal. Default: synpath.db")
+    p.add_argument("--control", default="synpath-control.db", help="users and keys. Default: synpath-control.db")
+    p.add_argument("--dotenv", default=None, help="a .env file with venue credentials")
+    p.add_argument("--no-streams", action="store_true", help="do not subscribe the venues' streams; poll only")
+    p.add_argument("--log-level", default="info")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    return asyncio.run(serve(parser().parse_args(argv)))

synpath/server/store.py

@@ -0,0 +1,363 @@
+"""Who may do what, and a record of every time that changed.
+
+The read API needs no accounts. The moment the server can place an order it
+needs to know who is asking, what they are allowed to touch, and -- when
+somebody later asks why a key could trade an account it should not have --
+what the permissions were at the time and who changed them.
+
+Three tables and one rule:
+
+**Keys are stored as hashes.** A key is shown once, when it is issued. What
+is kept is `sha256` of it, so a stolen database cannot be used to trade. Keys
+carry a prefix in clear (`sk_live_9f2a…`) purely so a human can tell two
+keys apart in a list.
+
+**Grants are per subaccount.** A grant is `(user, account, permission)`
+where the account is a `venue:name` key or `*`, and the permission is one of
+`view`, `trade`, `manage_credentials`, `manage_members`. Nothing is implied:
+a user who may trade may not grant, and a user who may grant may not trade.
+
+**The audit table is append-only, enforced by the database.** Every insert,
+update or delete on the keys or grants tables fires a trigger that writes
+the actor, the request, and the row before and after. Triggers on the audit
+table itself raise on update and delete, so no route, no bug and no hand at
+a SQL prompt can quietly change history -- and there is no route that tries.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import secrets
+import time
+from dataclasses import dataclass, field
+from typing import Any, Iterable, Literal
+
+Permission = Literal["view", "trade", "manage_credentials", "manage_members"]
+PERMISSIONS: tuple[Permission, ...] = ("view", "trade", "manage_credentials", "manage_members")
+ALL_ACCOUNTS = "*"
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS users (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL,
+    created_ts INTEGER NOT NULL,
+    disabled INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS api_keys (
+    id TEXT PRIMARY KEY,
+    user_id TEXT NOT NULL REFERENCES users(id),
+    prefix TEXT NOT NULL,
+    hash TEXT NOT NULL UNIQUE,
+    label TEXT,
+    created_ts INTEGER NOT NULL,
+    last_used_ts INTEGER,
+    revoked_ts INTEGER
+);
+CREATE INDEX IF NOT EXISTS api_keys_user ON api_keys(user_id);
+
+CREATE TABLE IF NOT EXISTS grants (
+    id TEXT PRIMARY KEY,
+    user_id TEXT NOT NULL REFERENCES users(id),
+    account TEXT NOT NULL,
+    permission TEXT NOT NULL,
+    granted_ts INTEGER NOT NULL,
+    UNIQUE (user_id, account, permission)
+);
+CREATE INDEX IF NOT EXISTS grants_user ON grants(user_id);
+
+CREATE TABLE IF NOT EXISTS audit (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts INTEGER NOT NULL,
+    actor TEXT,
+    request TEXT,
+    table_name TEXT NOT NULL,
+    action TEXT NOT NULL,
+    row_id TEXT,
+    before TEXT,
+    after TEXT
+);
+CREATE INDEX IF NOT EXISTS audit_ts ON audit(ts);
+
+-- One row, rewritten at the start of every request that changes anything, so
+-- the triggers can record who asked and under which request.
+CREATE TABLE IF NOT EXISTS audit_context (
+    id INTEGER PRIMARY KEY CHECK (id = 1),
+    actor TEXT,
+    request TEXT
+);
+INSERT INTO audit_context(id, actor, request) VALUES(1, NULL, NULL)
+    ON CONFLICT(id) DO NOTHING;
+"""
+
+TRIGGERS = """
+CREATE TRIGGER IF NOT EXISTS audit_grants_insert AFTER INSERT ON grants BEGIN
+    INSERT INTO audit(ts, actor, request, table_name, action, row_id, before, after)
+    VALUES (CAST(strftime('%s','now') AS INTEGER) * 1000,
+            (SELECT actor FROM audit_context WHERE id = 1),
+            (SELECT request FROM audit_context WHERE id = 1),
+            'grants', 'insert', NEW.id, NULL,
+            json_object('user_id', NEW.user_id, 'account', NEW.account, 'permission', NEW.permission));
+END;
+
+CREATE TRIGGER IF NOT EXISTS audit_grants_update AFTER UPDATE ON grants BEGIN
+    INSERT INTO audit(ts, actor, request, table_name, action, row_id, before, after)
+    VALUES (CAST(strftime('%s','now') AS INTEGER) * 1000,
+            (SELECT actor FROM audit_context WHERE id = 1),
+            (SELECT request FROM audit_context WHERE id = 1),
+            'grants', 'update', NEW.id,
+            json_object('user_id', OLD.user_id, 'account', OLD.account, 'permission', OLD.permission),
+            json_object('user_id', NEW.user_id, 'account', NEW.account, 'permission', NEW.permission));
+END;
+
+CREATE TRIGGER IF NOT EXISTS audit_grants_delete AFTER DELETE ON grants BEGIN
+    INSERT INTO audit(ts, actor, request, table_name, action, row_id, before, after)
+    VALUES (CAST(strftime('%s','now') AS INTEGER) * 1000,
+            (SELECT actor FROM audit_context WHERE id = 1),
+            (SELECT request FROM audit_context WHERE id = 1),
+            'grants', 'delete', OLD.id,
+            json_object('user_id', OLD.user_id, 'account', OLD.account, 'permission', OLD.permission), NULL);
+END;
+
+CREATE TRIGGER IF NOT EXISTS audit_keys_insert AFTER INSERT ON api_keys BEGIN
+    INSERT INTO audit(ts, actor, request, table_name, action, row_id, before, after)
+    VALUES (CAST(strftime('%s','now') AS INTEGER) * 1000,
+            (SELECT actor FROM audit_context WHERE id = 1),
+            (SELECT request FROM audit_context WHERE id = 1),
+            'api_keys', 'insert', NEW.id, NULL,
+            json_object('user_id', NEW.user_id, 'prefix', NEW.prefix, 'label', NEW.label));
+END;
+
+CREATE TRIGGER IF NOT EXISTS audit_keys_revoke AFTER UPDATE OF revoked_ts ON api_keys
+WHEN NEW.revoked_ts IS NOT NULL AND OLD.revoked_ts IS NULL BEGIN
+    INSERT INTO audit(ts, actor, request, table_name, action, row_id, before, after)
+    VALUES (CAST(strftime('%s','now') AS INTEGER) * 1000,
+            (SELECT actor FROM audit_context WHERE id = 1),
+            (SELECT request FROM audit_context WHERE id = 1),
+            'api_keys', 'revoke', NEW.id,
+            json_object('user_id', OLD.user_id, 'prefix', OLD.prefix, 'revoked_ts', OLD.revoked_ts),
+            json_object('user_id', NEW.user_id, 'prefix', NEW.prefix, 'revoked_ts', NEW.revoked_ts));
+END;
+
+-- History is written once. These are the reason there is no route that
+-- edits it: even a mistaken one cannot.
+CREATE TRIGGER IF NOT EXISTS audit_is_append_only_update BEFORE UPDATE ON audit BEGIN
+    SELECT RAISE(ABORT, 'the audit log is append-only');
+END;
+
+CREATE TRIGGER IF NOT EXISTS audit_is_append_only_delete BEFORE DELETE ON audit BEGIN
+    SELECT RAISE(ABORT, 'the audit log is append-only');
+END;
+"""
+
+
+def now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def hash_key(key: str) -> str:
+    return hashlib.sha256(key.encode()).hexdigest()
+
+
+def new_key(prefix: str = "sk") -> str:
+    """A key with enough entropy that the hash needs no salt."""
+    return f"{prefix}_{secrets.token_urlsafe(32)}"
+
+
+@dataclass(frozen=True, slots=True)
+class User:
+    id: str
+    name: str
+    created_ts: int
+    disabled: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class IssuedKey:
+    """What issuing a key returns. `secret` is shown once and never stored."""
+
+    id: str
+    user_id: str
+    prefix: str
+    secret: str
+    label: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Grant:
+    id: str
+    user_id: str
+    account: str
+    permission: Permission
+    granted_ts: int
+
+
+@dataclass(frozen=True, slots=True)
+class Principal:
+    """Who is asking, and what they may touch."""
+
+    user_id: str
+    name: str
+    key_id: str
+    grants: tuple[Grant, ...] = ()
+
+    def may(self, permission: Permission, account: str | None = None) -> bool:
+        for grant in self.grants:
+            if grant.permission != permission:
+                continue
+            if grant.account == ALL_ACCOUNTS or account is None or grant.account == account:
+                return True
+        return False
+
+    def accounts(self, permission: Permission) -> set[str]:
+        return {g.account for g in self.grants if g.permission == permission}
+
+
+class ControlStore:
+    """Users, keys, grants and the audit log."""
+
+    def __init__(self, path: str | os.PathLike[str] = "synpath-control.db"):
+        self.path = str(path)
+        self._db: Any = None
+
+    async def open(self) -> "ControlStore":
+        try:
+            import aiosqlite
+        except ImportError as exc:  # pragma: no cover - depends on the environment
+            raise ImportError("the server's account store needs aiosqlite: pip install synpath") from exc
+        connection = aiosqlite.connect(self.path, isolation_level=None)
+        connection.daemon = True
+        self._db = await connection
+        self._db.row_factory = aiosqlite.Row
+        await self._db.execute("PRAGMA journal_mode=WAL")
+        await self._db.execute("PRAGMA foreign_keys=ON")
+        await self._db.executescript(SCHEMA)
+        await self._db.executescript(TRIGGERS)
+        return self
+
+    async def close(self) -> None:
+        if self._db is not None:
+            await self._db.close()
+            self._db = None
+
+    async def __aenter__(self) -> "ControlStore":
+        return await self.open()
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+    # -- who is acting --------------------------------------------------------
+
+    async def acting_as(self, actor: str | None, request: str | None = None) -> None:
+        """Name the actor for the audit rows the next writes will produce."""
+        await self._db.execute("UPDATE audit_context SET actor=?, request=? WHERE id=1", (actor, request))
+
+    # -- users and keys -------------------------------------------------------
+
+    async def create_user(self, name: str, *, user_id: str | None = None) -> User:
+        user = User(id=user_id or f"u_{secrets.token_hex(8)}", name=name, created_ts=now_ms())
+        await self._db.execute("INSERT INTO users(id, name, created_ts, disabled) VALUES(?,?,?,0)",
+                               (user.id, user.name, user.created_ts))
+        return user
+
+    async def issue_key(self, user_id: str, *, label: str | None = None) -> IssuedKey:
+        secret = new_key()
+        key_id = f"k_{secrets.token_hex(8)}"
+        await self._db.execute(
+            "INSERT INTO api_keys(id, user_id, prefix, hash, label, created_ts) VALUES(?,?,?,?,?,?)",
+            (key_id, user_id, secret[:12], hash_key(secret), label, now_ms()),
+        )
+        return IssuedKey(id=key_id, user_id=user_id, prefix=secret[:12], secret=secret, label=label)
+
+    async def revoke_key(self, key_id: str) -> bool:
+        cursor = await self._db.execute(
+            "UPDATE api_keys SET revoked_ts=? WHERE id=? AND revoked_ts IS NULL", (now_ms(), key_id),
+        )
+        return cursor.rowcount > 0
+
+    async def principal(self, secret: str) -> Principal | None:
+        """Who a key belongs to, with the grants it carries right now."""
+        async with self._db.execute(
+            "SELECT k.id AS key_id, k.user_id, u.name, u.disabled FROM api_keys k JOIN users u ON u.id = k.user_id "
+            "WHERE k.hash=? AND k.revoked_ts IS NULL",
+            (hash_key(secret),),
+        ) as cursor:
+            row = await cursor.fetchone()
+        if row is None or row["disabled"]:
+            return None
+        await self._db.execute("UPDATE api_keys SET last_used_ts=? WHERE id=?", (now_ms(), row["key_id"]))
+        grants = await self.grants(row["user_id"])
+        return Principal(user_id=row["user_id"], name=row["name"], key_id=row["key_id"], grants=tuple(grants))
+
+    async def keys(self, user_id: str) -> list[dict[str, Any]]:
+        async with self._db.execute(
+            "SELECT id, prefix, label, created_ts, last_used_ts, revoked_ts FROM api_keys WHERE user_id=? ORDER BY created_ts",
+            (user_id,),
+        ) as cursor:
+            return [dict(row) async for row in cursor]
+
+    # -- grants ---------------------------------------------------------------
+
+    async def grant(self, user_id: str, account: str, permission: Permission) -> Grant:
+        if permission not in PERMISSIONS:
+            raise ValueError(f"{permission!r} is not a permission; known: {PERMISSIONS}")
+        row = Grant(id=f"g_{secrets.token_hex(8)}", user_id=user_id, account=account, permission=permission,
+                    granted_ts=now_ms())
+        await self._db.execute(
+            "INSERT INTO grants(id, user_id, account, permission, granted_ts) VALUES(?,?,?,?,?) "
+            "ON CONFLICT(user_id, account, permission) DO NOTHING",
+            (row.id, row.user_id, row.account, row.permission, row.granted_ts),
+        )
+        return row
+
+    async def revoke(self, user_id: str, account: str, permission: Permission) -> bool:
+        cursor = await self._db.execute(
+            "DELETE FROM grants WHERE user_id=? AND account=? AND permission=?", (user_id, account, permission),
+        )
+        return cursor.rowcount > 0
+
+    async def grants(self, user_id: str) -> list[Grant]:
+        async with self._db.execute(
+            "SELECT id, user_id, account, permission, granted_ts FROM grants WHERE user_id=? ORDER BY granted_ts",
+            (user_id,),
+        ) as cursor:
+            return [Grant(row["id"], row["user_id"], row["account"], row["permission"], row["granted_ts"])
+                    async for row in cursor]
+
+    # -- the audit log --------------------------------------------------------
+
+    async def audit(self, *, since_id: int = 0, limit: int = 200, table: str | None = None) -> list[dict[str, Any]]:
+        sql = "SELECT id, ts, actor, request, table_name, action, row_id, before, after FROM audit WHERE id > ?"
+        args: list[Any] = [since_id]
+        if table:
+            sql += " AND table_name = ?"
+            args.append(table)
+        sql += " ORDER BY id LIMIT ?"
+        args.append(limit)
+        async with self._db.execute(sql, args) as cursor:
+            rows = [dict(row) async for row in cursor]
+        for row in rows:
+            for key in ("before", "after"):
+                if row[key]:
+                    row[key] = json.loads(row[key])
+        return rows
+
+    async def has_users(self) -> bool:
+        """Whether anyone has been created yet: false on a new control database."""
+        async with self._db.execute("SELECT 1 FROM users LIMIT 1") as cursor:
+            return await cursor.fetchone() is not None
+
+    async def bootstrap(self, name: str = "owner") -> tuple[User, IssuedKey]:
+        """The first user, with every permission on every account.
+
+        Called once, by the operator starting the server, so there is a key to
+        make the next key with.
+        """
+        user = await self.create_user(name)
+        await self.acting_as(f"bootstrap:{user.id}", "bootstrap")
+        for permission in PERMISSIONS:
+            await self.grant(user.id, ALL_ACCOUNTS, permission)
+        key = await self.issue_key(user.id, label="bootstrap")
+        await self.acting_as(None, None)
+        return user, key