puremethod 0.1.0__py3-none-any.whl

app/compose.py

@@ -0,0 +1,229 @@
+"""The composition root: workers build the clients a `Loop` is made from (08-app.md §8,
+KB-021). Worker side only; `app.api` may not import it (import-linter)."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from app import bundled, executor_config, model_endpoints, tunnels
+from app.repo import ExecutorRow, RunRow, TenantRepo
+from app.settings import Settings
+from app.setup import LOCAL, PURESCHOLAR_CREDENTIAL, PURETRACE_CREDENTIAL, service_url
+from app.unseal import unseal
+from executor import Executor, LocalDockerExecutor, LocalProcessExecutor, SSHExecutor
+from ledger import Ledger
+from llm import DEFAULT_PRICES, LLM, ModelPrice, PriceTable
+from loop import Loop, RunConfig
+from purescholar import PureScholar
+from puretrace import PureTrace
+from writer import Writer
+
+Lookup = Callable[[str], str]
+
+
+class ServiceUrls:
+    """Where a tenant's runs reach PureScholar and PureTrace (08 §4, KB-029): the tenant's
+    setting, else `PM_PURESCHOLAR_URL` / `PM_PURETRACE_URL`."""
+
+    def __init__(self, purescholar: str | None, puretrace: str | None, *,
+                 purescholar_local: bool = False) -> None:
+        self.purescholar, self.puretrace = purescholar, puretrace
+        self.purescholar_local = purescholar_local
+
+    def purescholar_options(self) -> dict[str, Any]:
+        """The request timeout `app` supplies for the bundled instance (01 §3)."""
+        return {"timeout_s": bundled.REQUEST_TIMEOUT_S} if self.purescholar_local else {}
+
+    @classmethod
+    def for_tenant(cls, repo: TenantRepo, settings: Settings) -> ServiceUrls:
+        lit = repo.service_setting("literature") or {}
+        local = lit.get("mode") == "local"
+        ps = bundled.url(repo) if local else \
+            service_url(repo, "literature", settings.purescholar_url)
+        return cls(ps, service_url(repo, "puretrace", settings.puretrace_url),
+                   purescholar_local=local)
+
+    @classmethod
+    def from_settings(cls, settings: Settings) -> ServiceUrls:
+        return cls(settings.purescholar_url, settings.puretrace_url)
+
+    @classmethod
+    def for_run(cls, run: RunRow, repo: TenantRepo, settings: Settings) -> ServiceUrls:
+        """The run's snapshot (made at creation); the tenant's current setting for runs made
+        before KB-029. A bundled PureScholar ("local") is reached at its current address."""
+        if run.services is None:
+            return cls.for_tenant(repo, settings)
+        ps = run.services.get("purescholar")
+        local = ps == LOCAL
+        if local:
+            ps = bundled.url(repo)  # its current address; None while it is not ready
+        return cls(ps, run.services.get("puretrace"), purescholar_local=local)
+
+
+class CredentialMissing(KeyError):
+    """A credential the run needs is not stored, or is not one this worker may read."""
+
+
+class Credentials:
+    """Decrypts only names on the allow list, for one tenant (§5 step 3), and remembers the
+    values it handed out so worker logs can be scrubbed."""
+
+    def __init__(self, repo: TenantRepo, master_key: bytes, allowed: set[str]) -> None:
+        self._repo = repo
+        self._key = master_key
+        self._allowed = frozenset(allowed)
+        self._cache: dict[str, str] = {}
+
+    def __call__(self, name: str) -> str:
+        if name not in self._allowed:
+            raise CredentialMissing(name)
+        if name not in self._cache:
+            sealed = self._repo.sealed(name)
+            if sealed is None:
+                raise CredentialMissing(name)
+            self._cache[name] = unseal(self._key, self._repo.tenant_id, sealed.id,
+                                       sealed.nonce, sealed.ciphertext)
+        return self._cache[name]
+
+    def scrub(self, text: str) -> str:
+        for value in sorted(self._cache.values(), key=len, reverse=True):
+            if value:
+                text = text.replace(value, "[secret]")
+        return text
+
+
+def run_config(run: RunRow) -> RunConfig:
+    return RunConfig.model_validate(run.config)
+
+
+def run_executor(run: RunRow) -> ExecutorRow:
+    """The executor as it was when the run was created: later edits to the executor never
+    reach a run that passed preflight consent checks with the old one (review finding 1)."""
+    x = run.executor
+    return ExecutorRow(str(x["id"]), str(x["name"]), str(x["kind"]), dict(x["config"]), "")
+
+
+def allowed_for_run(run: RunRow, config: RunConfig, settings: Settings,
+                    urls: ServiceUrls | None = None) -> set[str]:
+    """The run's LLM and job credentials, its executor's key, and the PureScholar and PureTrace
+    keys only when those services are configured and (PureTrace) used."""
+    urls = urls or ServiceUrls.from_settings(settings)
+    names = set(config.credential_names())
+    x = run_executor(run)
+    names |= set(executor_config.credentials_named(x.kind, x.config))
+    names |= set(model_endpoints.ssh_credentials(config.llm))  # model tunnels (KB-036)
+    if urls.purescholar:
+        names.add(PURESCHOLAR_CREDENTIAL)
+    if urls.puretrace and (config.puretrace.screening or config.puretrace.selfcheck):
+        names.add(PURETRACE_CREDENTIAL)
+    return names
+
+
+def client_credentials(run: RunRow, settings: Settings,
+                       urls: ServiceUrls | None = None) -> Callable[[RunConfig], list[str]]:
+    """The names `loop` registers as run secrets beyond the config's own (03-loop.md §3 Run
+    secrets, 08 §5 step 3, KB-022): the executor's key and the service keys in use."""
+    return lambda config: sorted(allowed_for_run(run, config, settings, urls)
+                                 - set(config.credential_names()))
+
+
+class GuardedLedger(Ledger):
+    """A `Ledger` whose writes first check the worker still holds the run's lease, so two
+    workers never both write one run (KB-021; review finding 3)."""
+
+    def __init__(self, storage_url: str, artifact_root: str | Path, guard: Callable[[], None],
+                 **kw: Any) -> None:
+        super().__init__(storage_url, artifact_root, **kw)
+        self._guard = guard
+
+    def open_run(self, config: dict[str, Any], secrets: list[str]) -> str:
+        self._guard()
+        return super().open_run(config, secrets)
+
+    def append(self, *args: Any, **kwargs: Any) -> Any:
+        self._guard()
+        return super().append(*args, **kwargs)
+
+    def close_dangling(self, run_id: str) -> Any:
+        self._guard()
+        return super().close_dangling(run_id)
+
+    def put_artifact(self, *args: Any, **kwargs: Any) -> Any:
+        self._guard()
+        return super().put_artifact(*args, **kwargs)
+
+
+def prices(overrides: dict[str, dict[str, float]]) -> PriceTable:
+    if not overrides:
+        return DEFAULT_PRICES
+    table = dict(DEFAULT_PRICES.prices)
+    for key, p in overrides.items():
+        provider, _, model = key.partition("/")
+        table[(provider, model)] = (ModelPrice.unmetered_price() if p.get("unmetered") else
+                                    ModelPrice(float(p["input"]), float(p["output"])))
+    return PriceTable(version=f"{DEFAULT_PRICES.version}+profile",
+                      source=f"{DEFAULT_PRICES.source}; profile overrides", prices=table)
+
+
+def build_executor(row: ExecutorRow, lookup: Lookup, settings: Settings) -> Executor:
+    cfg = executor_config.validate(row.kind, row.config, settings.mode)  # INV-5 again here
+    root = settings.executor_root / row.id
+    common: dict[str, Any] = {"executor_id": row.id, "concurrency": cfg.concurrency,
+                              "rate_usd_per_hour": cfg.rate_usd_per_hour}
+    if isinstance(cfg, executor_config.LocalDockerConfig):
+        return LocalDockerExecutor(lookup, root=root, network=cfg.network, **common)
+    if isinstance(cfg, executor_config.SSHConfig):
+        return SSHExecutor(lookup, host=cfg.host, user=cfg.user,
+                           key_credential=cfg.key_credential, port=cfg.port,
+                           remote_root=cfg.remote_root, use_docker=cfg.use_docker,
+                           network=cfg.network, known_hosts=cfg.known_hosts,
+                           accept_unknown_host=cfg.accept_unknown_host,
+                           host_key=cfg.host_key,
+                           jumps=[h.model_dump() for h in cfg.jumps], **common)
+    return LocalProcessExecutor(lookup, root=root, **common)
+
+
+def make_loop(settings: Settings, run: RunRow, lookup: Lookup,
+              guard: Callable[[], None], urls: ServiceUrls | None = None) -> Loop:
+    """A new `Loop` on its own guarded `Ledger` connection. Workers build one per thread."""
+    urls = urls or ServiceUrls.from_settings(settings)
+    ledger = GuardedLedger(settings.ledger_url, settings.artifact_root, guard)
+    table = prices(run.prices)
+    image = {"tectonic_image": settings.tectonic_image} if settings.tectonic_image else {}
+    snapshot = run_executor(run)
+
+    def executor(executor_id: str, look: Lookup) -> Executor:
+        if executor_id != snapshot.id:
+            raise ValueError(f"executor {executor_id} is not this run's")
+        return build_executor(snapshot, look, settings)
+
+    def purescholar() -> PureScholar:
+        if not urls.purescholar:
+            raise ValueError("PureScholar is not configured: finish setup")
+        return PureScholar(urls.purescholar, lookup(PURESCHOLAR_CREDENTIAL),
+                           **urls.purescholar_options())
+
+    def puretrace(ledger_run_id: str, uses: list[str]) -> PureTrace:
+        if not urls.puretrace:
+            raise ValueError("PureTrace is not configured: set its URL in setup")
+        return PureTrace(urls.puretrace, lookup(PURETRACE_CREDENTIAL), ledger_run_id, uses)
+
+    opened: dict[str, dict[str, dict[str, Any]]] = {}
+
+    def llm(profile: dict[str, dict[str, Any]], creds: dict[str, str]) -> LLM:
+        """`via_ssh` roles reach their model through this worker's tunnels (07 §5 step 9),
+        opened once per profile and closed when the worker process ends."""
+        if model_endpoints.ssh_credentials(profile):
+            key = json.dumps(profile, sort_keys=True)
+            if key not in opened:
+                opened[key], _ = tunnels.open_tunnels(profile, lookup)
+            profile = opened[key]
+        return LLM(profile, table, creds)
+
+    return Loop(ledger, lambda llm, ps: Writer(ledger, llm, ps, **image), llm=llm,
+                executor=executor, purescholar=purescholar, puretrace=puretrace,
+                credentials=lookup, output_root=settings.output_root,
+                client_credentials=client_credentials(run, settings, urls))

app/db.py

@@ -0,0 +1,186 @@
+"""The app's own database: tenants, sign-in, credentials, configuration, the run index,
+commands and leases (08-app.md §4). Not the ledger: `app` never writes ledger storage (INV-3).
+
+`Database` is the storage seam: v0.1 ships SQLite (self-hosted); hosted mode adds a
+PostgreSQL class with the same `tx` contract. SQL in `app` uses `?` placeholders and only
+syntax both engines accept."""
+
+from __future__ import annotations
+
+import json
+import secrets
+import sqlite3
+from collections.abc import Iterator, Sequence
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Protocol
+
+SCHEMA_VERSION = 1
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS schema_version (version INTEGER NOT NULL);
+CREATE TABLE IF NOT EXISTS tenants (
+    id TEXT PRIMARY KEY, created_at TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS tokens (
+    hash TEXT PRIMARY KEY, tenant_id TEXT NOT NULL REFERENCES tenants(id),
+    created_at TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS sessions (
+    hash TEXT PRIMARY KEY, tenant_id TEXT NOT NULL REFERENCES tenants(id),
+    expires_at REAL NOT NULL);
+CREATE TABLE IF NOT EXISTS credentials (
+    id TEXT PRIMARY KEY, tenant_id TEXT NOT NULL REFERENCES tenants(id),
+    name TEXT NOT NULL, type TEXT NOT NULL, nonce BLOB NOT NULL, ciphertext BLOB NOT NULL,
+    created_at TEXT NOT NULL, UNIQUE (tenant_id, name));
+CREATE TABLE IF NOT EXISTS executors (
+    id TEXT PRIMARY KEY, tenant_id TEXT NOT NULL REFERENCES tenants(id),
+    name TEXT NOT NULL, kind TEXT NOT NULL, config TEXT NOT NULL, created_at TEXT NOT NULL,
+    UNIQUE (tenant_id, name));
+CREATE TABLE IF NOT EXISTS ssh_machines (
+    id TEXT PRIMARY KEY, tenant_id TEXT NOT NULL REFERENCES tenants(id),
+    name TEXT NOT NULL, config TEXT NOT NULL, created_at TEXT NOT NULL,
+    UNIQUE (tenant_id, name));
+CREATE TABLE IF NOT EXISTS profile_checks (
+    id TEXT PRIMARY KEY, tenant_id TEXT NOT NULL REFERENCES tenants(id),
+    profile_id TEXT NOT NULL REFERENCES llm_profiles(id), state TEXT NOT NULL, report TEXT,
+    created_at TEXT NOT NULL, done_at TEXT, version INTEGER NOT NULL DEFAULT 1,
+    proposal TEXT, applied INTEGER NOT NULL DEFAULT 0);
+CREATE TABLE IF NOT EXISTS llm_searches (
+    id TEXT PRIMARY KEY, tenant_id TEXT NOT NULL REFERENCES tenants(id),
+    target TEXT NOT NULL, state TEXT NOT NULL, report TEXT, created_at TEXT NOT NULL,
+    done_at TEXT);
+CREATE TABLE IF NOT EXISTS rate_events (
+    tenant_id TEXT NOT NULL REFERENCES tenants(id), kind TEXT NOT NULL, at REAL NOT NULL);
+CREATE TABLE IF NOT EXISTS llm_profiles (
+    id TEXT PRIMARY KEY, tenant_id TEXT NOT NULL REFERENCES tenants(id),
+    name TEXT NOT NULL, roles TEXT NOT NULL, prices TEXT NOT NULL, created_at TEXT NOT NULL,
+    version INTEGER NOT NULL DEFAULT 1, deleted_at TEXT, UNIQUE (tenant_id, name));
+CREATE TABLE IF NOT EXISTS runs (
+    id TEXT PRIMARY KEY, tenant_id TEXT NOT NULL REFERENCES tenants(id),
+    title TEXT NOT NULL, ledger_run_id TEXT, state TEXT NOT NULL, start_error TEXT,
+    worker_error TEXT, config TEXT NOT NULL, prices TEXT NOT NULL, executor TEXT NOT NULL,
+    created_at TEXT NOT NULL, services TEXT, llm_profile_id TEXT);
+CREATE TABLE IF NOT EXISTS commands (
+    id TEXT PRIMARY KEY, tenant_id TEXT NOT NULL REFERENCES tenants(id),
+    run_id TEXT NOT NULL REFERENCES runs(id), seq INTEGER NOT NULL, kind TEXT NOT NULL,
+    payload TEXT NOT NULL, state TEXT NOT NULL, reason TEXT, created_at TEXT NOT NULL,
+    done_at TEXT, UNIQUE (run_id, seq));
+CREATE TABLE IF NOT EXISTS preflight_checks (
+    id TEXT PRIMARY KEY, tenant_id TEXT NOT NULL REFERENCES tenants(id),
+    executor_id TEXT NOT NULL REFERENCES executors(id), state TEXT NOT NULL,
+    report TEXT, created_at TEXT NOT NULL, done_at TEXT);
+CREATE TABLE IF NOT EXISTS leases (
+    key TEXT PRIMARY KEY, holder TEXT NOT NULL, expires_at REAL NOT NULL);
+CREATE TABLE IF NOT EXISTS signin_codes (
+    hash TEXT PRIMARY KEY, tenant_id TEXT NOT NULL REFERENCES tenants(id),
+    expires_at REAL NOT NULL);
+CREATE TABLE IF NOT EXISTS credential_checks (
+    id TEXT PRIMARY KEY, tenant_id TEXT NOT NULL REFERENCES tenants(id),
+    credential_id TEXT NOT NULL REFERENCES credentials(id), kind TEXT NOT NULL,
+    request TEXT NOT NULL, state TEXT NOT NULL, report TEXT, created_at TEXT NOT NULL,
+    done_at TEXT);
+CREATE TABLE IF NOT EXISTS bundled_services (
+    tenant_id TEXT PRIMARY KEY REFERENCES tenants(id), state TEXT NOT NULL, reason TEXT,
+    port INTEGER, key_sha256 TEXT, key_credential_id TEXT, updated_at TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS service_settings (
+    tenant_id TEXT NOT NULL REFERENCES tenants(id), service TEXT NOT NULL,
+    config TEXT NOT NULL, updated_at TEXT NOT NULL, PRIMARY KEY (tenant_id, service));
+"""
+
+
+_ADDED_COLUMNS = (
+    ("runs", "services", "TEXT"),
+    ("runs", "llm_profile_id", "TEXT"),
+    ("llm_profiles", "version", "INTEGER NOT NULL DEFAULT 1"),
+    ("llm_profiles", "deleted_at", "TEXT"),
+    ("profile_checks", "version", "INTEGER NOT NULL DEFAULT 1"),
+    ("profile_checks", "proposal", "TEXT"),
+    ("profile_checks", "applied", "INTEGER NOT NULL DEFAULT 0"),
+)
+
+_CONNECTION = ("host", "user", "key_credential", "port", "host_key", "known_hosts")
+
+
+def _machines_for_ssh_executors(conn: sqlite3.Connection) -> None:
+    """KB-036: every `ssh` executor names an SSH machine. Executors from before get one each,
+    made from their own connection fields, named after the executor."""
+    ids = [r[0] for r in conn.execute("SELECT id FROM executors WHERE kind = 'ssh'").fetchall()]
+    for xid in ids:
+        conn.execute("BEGIN IMMEDIATE")  # API and workers open the database concurrently
+        try:
+            row = conn.execute("SELECT tenant_id, name, config, created_at FROM executors "
+                               "WHERE id = ?", (xid,)).fetchone()
+            cfg = json.loads(row[2]) if row else {"machine": None}
+            if row is None or cfg.get("machine"):
+                conn.execute("COMMIT")
+                continue
+            tid, name, at = row[0], row[1], row[3]
+            machine = {k: cfg[k] for k in _CONNECTION if cfg.get(k) is not None}
+            machine.setdefault("port", 22)
+            taken = {r[0] for r in conn.execute(
+                "SELECT name FROM ssh_machines WHERE tenant_id = ?", (tid,)).fetchall()}
+            mname, n = name, 2
+            while mname in taken:
+                mname, n = f"{name}-{n}", n + 1
+            mid = "m_" + secrets.token_hex(8)
+            conn.execute("INSERT INTO ssh_machines VALUES (?, ?, ?, ?, ?)",
+                         (mid, tid, mname, json.dumps(machine), at))
+            conn.execute("UPDATE executors SET config = ? WHERE id = ?",
+                         (json.dumps({**cfg, "machine": mid, "jumps": []}), xid))
+            conn.execute("COMMIT")
+        except BaseException:
+            conn.execute("ROLLBACK")
+            raise
+
+
+class Conn(Protocol):
+    def execute(self, sql: str, params: Sequence[Any] = ()) -> list[tuple[Any, ...]]: ...
+    def rowcount(self, sql: str, params: Sequence[Any] = ()) -> int: ...
+
+
+class _SQLiteConn:
+    def __init__(self, conn: sqlite3.Connection) -> None:
+        self._c = conn
+
+    def execute(self, sql: str, params: Sequence[Any] = ()) -> list[tuple[Any, ...]]:
+        return list(self._c.execute(sql, tuple(params)).fetchall())
+
+    def rowcount(self, sql: str, params: Sequence[Any] = ()) -> int:
+        return self._c.execute(sql, tuple(params)).rowcount
+
+
+class Database:
+    """SQLite, one connection per transaction, so threads and processes share it safely."""
+
+    def __init__(self, path: str | Path) -> None:
+        self._path = str(path)
+        Path(self._path).parent.mkdir(parents=True, exist_ok=True)
+        conn = sqlite3.connect(self._path, isolation_level=None)
+        try:
+            conn.execute("PRAGMA journal_mode=WAL")
+            conn.executescript(SCHEMA)
+            # Columns added after a table was first created: KB-029 (runs' service snapshot)
+            # and KB-041 (profile versions, edit proposals, deletion, a run's profile).
+            for table, column, decl in _ADDED_COLUMNS:
+                cols = {r[1] for r in conn.execute(f"PRAGMA table_info({table})").fetchall()}
+                if column not in cols:
+                    conn.execute(f"ALTER TABLE {table} ADD COLUMN {column} {decl}")
+            _machines_for_ssh_executors(conn)
+            if not conn.execute("SELECT version FROM schema_version").fetchall():
+                conn.execute("INSERT INTO schema_version VALUES (?)", (SCHEMA_VERSION,))
+        finally:
+            conn.close()
+
+    @contextmanager
+    def tx(self, write: bool = False) -> Iterator[Conn]:
+        conn = sqlite3.connect(self._path, timeout=30, isolation_level=None)
+        try:
+            conn.execute("PRAGMA foreign_keys=ON")
+            conn.execute("BEGIN IMMEDIATE" if write else "BEGIN")
+            try:
+                yield _SQLiteConn(conn)
+            except BaseException:
+                conn.execute("ROLLBACK")
+                raise
+            conn.execute("COMMIT")
+        finally:
+            conn.close()

app/executor_config.py

@@ -0,0 +1,95 @@
+"""Executor configurations a tenant can store (08-app.md §3 `/executors`). The fields mirror
+the backend constructors in `05-executor.md`; job roots are always under the data directory,
+never user-chosen. Hosted mode accepts `ssh` only (INV-5)."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from app.settings import Mode
+from app.ssh_hosts import parse_host_key
+
+KINDS = ("local-docker", "local-process", "ssh")
+
+
+class _Strict(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class _Common(_Strict):
+    concurrency: Annotated[int, Field(ge=1, le=64)] = 1
+    rate_usd_per_hour: Annotated[float, Field(ge=0)] | None = None
+
+
+class LocalDockerConfig(_Common):
+    network: Literal["on", "off"] = "on"
+
+
+class LocalProcessConfig(_Common):
+    pass
+
+
+class JumpHop(_Strict):
+    """One jump host, resolved from its SSH machine (KB-036). Its host key is required."""
+    host: Annotated[str, Field(min_length=1, max_length=253)]
+    user: Annotated[str, Field(min_length=1, max_length=64)]
+    key_credential: Annotated[str, Field(min_length=1)]
+    port: Annotated[int, Field(ge=1, le=65535)] = 22
+    host_key: str
+
+    @field_validator("host_key")
+    @classmethod
+    def _valid_host_key(cls, v: str) -> str:
+        parse_host_key(v)
+        return v
+
+
+class SSHConfig(_Common):
+    host: Annotated[str, Field(min_length=1, max_length=253)]
+    user: Annotated[str, Field(min_length=1, max_length=64)]
+    key_credential: Annotated[str, Field(min_length=1)]
+    port: Annotated[int, Field(ge=1, le=65535)] = 22
+    remote_root: Annotated[str, Field(min_length=1)] = "puremethod"
+    use_docker: bool = False
+    network: Literal["on", "off"] = "on"
+    known_hosts: str | None = None  # self-hosted only; kept for configurations made before KB-035
+    accept_unknown_host: Literal[False] = False  # INV-10: never accept any host key
+    host_key: str | None = None  # the confirmed "<type> <base64>" (INV-10)
+    machine: str | None = None  # the SSH machine these fields are resolved from (KB-036)
+    jumps: Annotated[list[JumpHop], Field(max_length=4)] = []
+
+    @field_validator("host_key")
+    @classmethod
+    def _valid_host_key(cls, v: str | None) -> str | None:
+        if v is not None:
+            parse_host_key(v)  # raises SSHSetupError, a ValueError
+        return v
+
+
+MODELS: dict[str, type[_Common]] = {"local-docker": LocalDockerConfig,
+                                    "local-process": LocalProcessConfig, "ssh": SSHConfig}
+
+
+class ExecutorKindRefused(ValueError):
+    pass
+
+
+def validate(kind: str, config: dict[str, Any], mode: Mode) -> _Common:
+    if kind not in MODELS:
+        raise ValueError(f"unknown executor kind {kind!r}")
+    if mode == "hosted" and kind != "ssh":
+        raise ExecutorKindRefused("hosted mode allows only ssh executors (INV-5)")
+    cfg = MODELS[kind].model_validate(config)
+    if mode == "hosted" and isinstance(cfg, SSHConfig) and cfg.known_hosts is not None:
+        # A path names a file on the platform's server (KB-035).
+        raise ValueError("hosted mode does not accept known_hosts paths; confirm the host key")
+    return cfg
+
+
+def credentials_named(kind: str, config: dict[str, Any]) -> list[str]:
+    if kind != "ssh":
+        return []
+    return [str(config["key_credential"]),
+            *(str(h["key_credential"]) for h in config.get("jumps") or [])]

app/keys.py

@@ -0,0 +1,29 @@
+"""Sealing credentials and deriving the link key (08-app.md §5 steps 3, 10).
+
+There is no decrypt here: that lives in `app.unseal`, which `app.api` may not import
+(INV-2, enforced by import-linter)."""
+
+from __future__ import annotations
+
+import os
+
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+NONCE_BYTES = 12  # 96-bit nonce (KB-021)
+
+
+def aad(tenant_id: str, credential_id: str) -> bytes:
+    """Binds a ciphertext to its tenant and row, so a moved ciphertext does not decrypt."""
+    return f"puremethod-credential\x00{tenant_id}\x00{credential_id}".encode()
+
+
+def seal(master_key: bytes, tenant_id: str, credential_id: str, value: str) -> tuple[bytes, bytes]:
+    nonce = os.urandom(NONCE_BYTES)
+    return nonce, AESGCM(master_key).encrypt(nonce, value.encode(), aad(tenant_id, credential_id))
+
+
+def link_key(master_key: bytes) -> bytes:
+    return HKDF(algorithm=hashes.SHA256(), length=32, salt=None,
+                info=b"download-links").derive(master_key)