bot-bottle/bot_bottle/paths.py

"""Foundational filesystem paths for bot-bottle.

`bot_bottle_root()` is the app data root — per-bottle state, git-gate
keys, the gateway CA, and the shared SQLite DB all live under it. It
defaults to `~/.bot-bottle` and is overridable with the
**`BOT_BOTTLE_ROOT`** env var.

Note that the supervise queue and the audit log are *tables in the shared
DB*, not directories under the root — see `queue_store.py` / `audit_store.py`.
The root held a `queue/` directory before the SQLite migration (PRD 0067);
nothing writes there now.

The env override is the single knob for redirecting the root: the test
suite points it at a throwaway dir instead of monkey-patching the function
(every module and every flat/package copy reads the same env var, so one
override covers them all), and operators can relocate the root if needed.

This module has no bot-bottle imports, so it is safe to import from any
layer (and to COPY flat into the gateway).
"""

from __future__ import annotations

import os
import secrets
import stat
from pathlib import Path

# The single shared host state DB. All bot-bottle SQLite stores (supervise
# queue, audit, the orchestrator registry) co-tenant this one file — the
# TableMigrations schema_key namespaces each store's tables.
HOST_DB_FILENAME = "bot-bottle.db"

# The per-host control-plane secret file, and the env var the launchers inject
# its value into. The control plane requires this secret on every mutating /
# reading route (see orchestrator/server.py); it is held only by the
# trusted callers (control plane, gateway, host CLI) and never handed to an
# agent, so an agent that can reach the control-plane port still can't drive it.
ORCHESTRATOR_TOKEN_FILENAME = "orchestrator-token"
# The env var carrying the orchestrator's *signing key* — held only by the
# orchestrator (to verify tokens) and the host CLI (to mint its own), never by
# the data plane. Same value as the host token file.
ORCHESTRATOR_TOKEN_ENV = "BOT_BOTTLE_ORCHESTRATOR_TOKEN"
# The env var carrying the data plane's pre-minted `gateway`-role token (a
# signed JWT the launcher mints from the signing key). The gateway presents this
# on /resolve + /supervise/{propose,poll}; it never holds the signing key, so it
# cannot forge a higher-privilege `cli` token (issue #469 review).
ORCHESTRATOR_AUTH_JWT_ENV = "BOT_BOTTLE_ORCHESTRATOR_AUTH_JWT"

# The host directory holding the gateway's persistent mitmproxy CA. Bind-mounted
# into the infra/gateway container at mitmproxy's confdir so the self-generated
# CA survives container recreation — every agent installs this one CA to trust
# the shared gateway's TLS interception, so it must not rotate on restart. See
# host_gateway_ca_dir() for why this is a host bind-mount, not a named volume.
GATEWAY_CA_DIRNAME = "gateway-ca"


def bot_bottle_root() -> Path:
    """The app data root — `$BOT_BOTTLE_ROOT` if set, else `~/.bot-bottle`."""
    override = os.environ.get("BOT_BOTTLE_ROOT")
    return Path(override) if override else Path.home() / ".bot-bottle"


def host_db_path() -> Path:
    """Path to the shared host state DB, `<root>/db/bot-bottle.db`.

    Kept in its own `db/` subdirectory (not directly under the root) so a
    backend that can only bind-mount *directories* can share this one file
    with a gateway without exposing the root's other contents (git-gate
    keys, per-bottle state, ...)."""
    return bot_bottle_root() / "db" / HOST_DB_FILENAME


def host_db_dir() -> Path:
    """The directory holding the shared host state DB, created if missing.
    Backends bind-mount this into their gateway so the supervise daemon writes
    to the one DB the orchestrator (and the operator over HTTP) reads."""
    db_dir = host_db_path().parent
    db_dir.mkdir(parents=True, exist_ok=True)
    return db_dir


def host_gateway_ca_dir() -> Path:
    """The directory holding the gateway's persistent mitmproxy CA, created if
    missing. Backends bind-mount this into the infra/gateway container at
    mitmproxy's confdir so the CA persists across container recreation.

    A host bind-mount under the app-data root — deliberately NOT a Docker
    named volume. A named volume survives `docker rm` but is silently wiped by
    `docker volume prune` / `docker system prune --volumes` during routine host
    maintenance; the gateway then mints a fresh CA that every already-running
    bottle distrusts, failing the TLS handshake even after it reconnects to the
    moved gateway (issue #450). A path under the root docker never prunes it,
    and it stays directly inspectable + rotatable from the host."""
    ca_dir = bot_bottle_root() / GATEWAY_CA_DIRNAME
    ca_dir.mkdir(parents=True, exist_ok=True)
    return ca_dir


def host_signing_key(filename: str) -> str:
    """A per-host signing key at `<root>/<filename>`, minted (256-bit, url-safe)
    and persisted 0600 on first use, then reused.

    The generic form of `host_orchestrator_token()`: a *trust domain*
    (`trust_domain.py`) names its own key file so each credential boundary gets a
    distinct host-canonical key — the orchestrator control plane names one file,
    a separate boundary (e.g. a host controller) names another, and neither can
    read the other's key (issues #476/#468). It is a *host* artifact: the file
    lives under the root the agent never mounts, and its value is injected only
    into the trusted control-plane process, so reading it here is safe on the
    host launch path but the value never reaches a bottle."""
    path = bot_bottle_root() / filename
    try:
        existing = path.read_text().strip()
        if existing:
            return existing
    except OSError:
        pass
    path.parent.mkdir(parents=True, exist_ok=True)
    token = secrets.token_urlsafe(32)
    # Create 0600 up front (O_EXCL loses a concurrent race harmlessly — we
    # re-read the winner's token below) so the secret is never briefly world-
    # readable between write and chmod.
    try:
        fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
    except FileExistsError:
        return path.read_text().strip()
    with os.fdopen(fd, "w") as f:
        f.write(token)
    os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)
    return token


def host_orchestrator_token() -> str:
    """The per-host control-plane signing key — the host-canonical key the
    launchers inject into the control-plane process and the host CLI mints its
    own `cli` token from. The `control-plane` trust domain's specialization of
    `host_signing_key()`."""
    return host_signing_key(ORCHESTRATOR_TOKEN_FILENAME)


__all__ = [
    "HOST_DB_FILENAME",
    "ORCHESTRATOR_TOKEN_FILENAME",
    "ORCHESTRATOR_TOKEN_ENV",
    "ORCHESTRATOR_AUTH_JWT_ENV",
    "GATEWAY_CA_DIRNAME",
    "bot_bottle_root",
    "host_db_path",
    "host_db_dir",
    "host_gateway_ca_dir",
    "host_signing_key",
    "host_orchestrator_token",
]