holdmyagent 0.2.0__tar.gz

holdmyagent-0.2.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: holdmyagent
+Version: 0.2.0
+Summary: Self-hosted, fail-closed approval server for AI agents (Arbiter)
+License: MIT
+Project-URL: Homepage, https://holdmyagent.com
+Project-URL: Repository, https://github.com/holdmyagent/arbiter
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn[standard]>=0.32
+Requires-Dist: httpx[http2]>=0.27
+Requires-Dist: pyjwt[crypto]>=2.9
+Requires-Dist: pydantic>=2.9
+Requires-Dist: segno>=1.6
+Requires-Dist: jinja2>=3.1
+Requires-Dist: itsdangerous>=2.2
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: tomlkit>=0.12
+Requires-Dist: click>=8.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+
+# Hold My Agent — Arbiter
+
+Self-hosted, fail-closed approval server for AI agents. Before your agent
+does something irreversible, it asks a human — Arbiter holds the request,
+pushes an alert to your phone (APNs, ntfy, or a webhook), and waits for a
+real decision. If the server is unreachable or the request times out, the
+answer defaults to **no**.
+
+```bash
+pip install holdmyagent
+hma init
+hma serve
+```
+
+- Homepage: https://holdmyagent.com
+- Source / issues: https://github.com/holdmyagent/arbiter

holdmyagent-0.2.0/README.md

@@ -0,0 +1,16 @@
+# Hold My Agent — Arbiter
+
+Self-hosted, fail-closed approval server for AI agents. Before your agent
+does something irreversible, it asks a human — Arbiter holds the request,
+pushes an alert to your phone (APNs, ntfy, or a webhook), and waits for a
+real decision. If the server is unreachable or the request times out, the
+answer defaults to **no**.
+
+```bash
+pip install holdmyagent
+hma init
+hma serve
+```
+
+- Homepage: https://holdmyagent.com
+- Source / issues: https://github.com/holdmyagent/arbiter

holdmyagent-0.2.0/arbiter/apns.py

@@ -0,0 +1,4 @@
+"""Compatibility shim: the APNs sender moved to arbiter.notify.apns."""
+from .notify.apns import APNsSender, build_payload, send_with_retry
+
+__all__ = ["APNsSender", "build_payload", "send_with_retry"]

holdmyagent-0.2.0/arbiter/app.py

@@ -0,0 +1,159 @@
+import asyncio
+import logging
+import secrets
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI, Depends, HTTPException, WebSocket, WebSocketDisconnect
+from fastapi.responses import RedirectResponse
+from fastapi.staticfiles import StaticFiles
+
+from .auth import require_agent, require_app, require_agent_or_app, SlidingWindowLimiter
+from .models import RequestCreate, Decision, DeviceRegister
+from .notify import Dispatcher
+from .stream import Hub
+from .web import build_router, session_valid
+
+log = logging.getLogger("arbiter.app")
+
+
+def create_app(cfg, db, sender, hub: Hub | None = None, ws_heartbeat: float = 30.0, dispatcher=None):
+    hub = hub or Hub()
+    dispatcher = dispatcher or Dispatcher(cfg, db, sender=sender)
+    notify_tasks: set = set()
+
+    def _spawn(coro):
+        # Hold a strong reference until done — a bare create_task() result is
+        # GC-eligible mid-flight (asyncio only keeps weak refs to tasks).
+        t = asyncio.create_task(coro)
+        notify_tasks.add(t)
+        t.add_done_callback(notify_tasks.discard)
+        return t
+
+    @asynccontextmanager
+    async def lifespan(app):
+        async def sweep():
+            while True:
+                try:
+                    for req in db.expire_due():
+                        _spawn(dispatcher.request_decided(req))
+                        await hub.publish("request.expired", "request", req)
+                except Exception as exc:
+                    log.warning("sweep iteration failed: %s", exc)
+                await asyncio.sleep(1)
+        task = asyncio.create_task(sweep())
+        yield
+        task.cancel()
+    app = FastAPI(title="Arbiter", lifespan=lifespan)
+    app.state.hub = hub
+    app.state.notify_tasks = notify_tasks
+    limiter = SlidingWindowLimiter(10, 60.0)
+    app.state.login_limiter = SlidingWindowLimiter(5, 60.0)
+    agent = Depends(require_agent(cfg, limiter))
+    appdep = Depends(require_app(cfg, limiter))
+    either = Depends(require_agent_or_app(cfg, limiter))
+
+    app.mount("/static", StaticFiles(directory=str(Path(__file__).parent / "web" / "static")), name="static")
+    app.include_router(build_router(cfg, db, hub))
+    app.state.session_check = lambda v: session_valid(cfg, v)
+
+    @app.middleware("http")
+    async def security_headers(request, call_next):
+        resp = await call_next(request)
+        resp.headers["X-Content-Type-Options"] = "nosniff"
+        resp.headers["Referrer-Policy"] = "no-referrer"
+        resp.headers["X-Frame-Options"] = "DENY"
+        ct = resp.headers.get("content-type", "")
+        if ct.startswith("text/html") and not request.url.path.startswith(("/docs", "/redoc", "/openapi")):
+            resp.headers["Content-Security-Policy"] = "default-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:"
+        return resp
+
+    # ── Utility / pairing ────────────────────────────────────────────────────
+
+    @app.get("/", include_in_schema=False)
+    def root():
+        return RedirectResponse("/dashboard", status_code=302)
+
+    @app.get("/dashboard", include_in_schema=False)
+    def dash_root():
+        return RedirectResponse("/dashboard/requests", status_code=302)
+
+    @app.get("/pair", include_in_schema=False)
+    def old_pair():
+        return RedirectResponse("/dashboard/pair", status_code=302)
+
+    @app.get("/health")
+    def health():
+        return {"ok": True}
+
+    # ── API v1 ───────────────────────────────────────────────────────────────
+
+    @app.post("/v1/requests", dependencies=[agent])
+    async def create(body: RequestCreate):
+        req = db.create_request(body)
+        _spawn(dispatcher.request_created(req))
+        await hub.publish("request.created", "request", req)
+        return req
+
+    @app.get("/v1/requests", dependencies=[appdep])
+    def list_(status: str | None = None):
+        return db.list_requests(status)
+
+    @app.get("/v1/requests/{rid}", dependencies=[either])
+    def get_(rid: str):
+        r = db.get_request(rid)
+        if not r:
+            raise HTTPException(404, "not found")
+        return r
+
+    @app.post("/v1/requests/{rid}/decision", dependencies=[appdep])
+    async def decide(rid: str, body: Decision):
+        r = db.get_request(rid)
+        if not r:
+            raise HTTPException(404, "not found")
+        devices = db.list_devices()
+        decided_by = devices[0]["name"] if len(devices) == 1 else "app"
+        updated = db.set_decision(rid, body.decision, decided_by)
+        if not updated:
+            raise HTTPException(409, f"not pending (status={r['status']})")
+        _spawn(dispatcher.request_decided(updated))
+        await hub.publish("request.decided", "request", updated)
+        return updated
+
+    @app.post("/v1/devices", dependencies=[appdep])
+    async def register(body: DeviceRegister):
+        dev = db.register_device(body.apns_token, body.name, body.min_severity,
+                                  body.notifications_enabled, body.sound)
+        await hub.publish("device.updated", "device", dev)
+        return dev
+
+    @app.get("/v1/devices", dependencies=[appdep])
+    def devices():
+        return db.list_devices()
+
+    @app.websocket("/v1/stream")
+    async def stream(ws: WebSocket):
+        auth = ws.headers.get("authorization", "")
+        cookie = ws.cookies.get("hma_session", "")
+        token_ok = auth.startswith("Bearer ") and secrets.compare_digest(
+            auth.removeprefix("Bearer ").encode(), cfg.auth.app_token.encode())
+        if not (token_ok or app.state.session_check(cookie)):
+            await ws.close(code=4401)
+            return
+        await ws.accept()
+        q = hub.subscribe()
+        async def heartbeat():
+            while True:
+                await asyncio.sleep(ws_heartbeat)
+                await hub.publish("ping", "data", {})
+        hb = asyncio.create_task(heartbeat())
+        try:
+            while True:
+                await ws.send_json(await q.get())
+        except WebSocketDisconnect:
+            pass
+        finally:
+            hb.cancel()
+            hub.unsubscribe(q)
+
+    return app

holdmyagent-0.2.0/arbiter/auth.py

@@ -0,0 +1,64 @@
+import logging
+import secrets
+import time
+from collections import defaultdict, deque
+from fastapi import Header, HTTPException, Request
+
+log = logging.getLogger("arbiter.auth")
+
+class SlidingWindowLimiter:
+    def __init__(self, limit: int, window: float, clock=time.monotonic):
+        self.limit, self.window, self.clock = limit, window, clock
+        self._hits: dict[str, deque] = defaultdict(deque)
+
+    def _prune(self, key: str):
+        q, now = self._hits[key], self.clock()
+        while q and now - q[0] > self.window:
+            q.popleft()
+
+    def record_failure(self, key: str):
+        self._prune(key)
+        self._hits[key].append(self.clock())
+
+    def blocked(self, key: str) -> bool:
+        q = self._hits.get(key)
+        if not q:
+            return False
+        now = self.clock()
+        while q and now - q[0] > self.window:
+            q.popleft()
+        if not q:
+            del self._hits[key]
+        return len(q) >= self.limit
+
+def _client_ip(request: Request) -> str:
+    return request.client.host if request.client else "unknown"
+
+def _check(request: Request, authorization: str | None, expected: tuple[str, ...], limiter: SlidingWindowLimiter):
+    ip = _client_ip(request)
+    if limiter.blocked(ip):
+        raise HTTPException(429, "too many failed auth attempts")
+    if not authorization or not authorization.startswith("Bearer "):
+        limiter.record_failure(ip)
+        log.warning("auth_failure ip=%s reason=missing_bearer", ip)
+        raise HTTPException(401, "missing bearer token")
+    supplied = authorization.removeprefix("Bearer ")
+    if not any(secrets.compare_digest(supplied.encode(), e.encode()) for e in expected):
+        limiter.record_failure(ip)
+        log.warning("auth_failure ip=%s reason=invalid_token", ip)  # never log the supplied value
+        raise HTTPException(403, "invalid token")
+
+def require_agent(cfg, limiter):
+    def dep(request: Request, authorization: str | None = Header(default=None)):
+        _check(request, authorization, (cfg.auth.agent_token,), limiter)
+    return dep
+
+def require_app(cfg, limiter):
+    def dep(request: Request, authorization: str | None = Header(default=None)):
+        _check(request, authorization, (cfg.auth.app_token,), limiter)
+    return dep
+
+def require_agent_or_app(cfg, limiter):
+    def dep(request: Request, authorization: str | None = Header(default=None)):
+        _check(request, authorization, (cfg.auth.agent_token, cfg.auth.app_token), limiter)
+    return dep

holdmyagent-0.2.0/arbiter/cli.py

@@ -0,0 +1,195 @@
+import json
+import logging
+import os
+import secrets as pysecrets
+import sys
+import time
+from pathlib import Path
+import click
+import httpx
+
+from .config import Config
+
+class _JsonFormatter(logging.Formatter):
+    def format(self, rec):
+        return json.dumps({"ts": self.formatTime(rec), "level": rec.levelname,
+                           "logger": rec.name, "msg": rec.getMessage()})
+
+CONFIG_TEMPLATE = """# Hold My Agent — Arbiter server configuration
+[server]
+host = "127.0.0.1"          # use "0.0.0.0" (or `hma serve --lan`) so phones can reach it
+port = 8000
+db_path = "~/.local/share/holdmyagent/arbiter.sqlite3"
+
+[auth]
+agent_token = "{agent}"
+app_token = "{app}"
+admin_password = "{admin}"
+session_secret = "{session}"
+
+[notify.apns]               # optional — bring your own Apple Developer key
+key_path = ""
+key_id = ""
+team_id = ""
+bundle_id = "com.holdmyagent.HoldMyAgent"
+sandbox = false
+
+[notify.ntfy]               # optional — phone alerts with no Apple account
+url = "https://ntfy.sh"
+topic = ""
+token = ""
+
+[notify.webhook]            # optional — generic integration
+url = ""
+secret = ""
+"""
+
+@click.group()
+def main():
+    """Hold My Agent — self-hosted, fail-closed approvals for AI agents."""
+
+@main.command()
+@click.option("--force", is_flag=True, help="Overwrite an existing config file.")
+def init(force):
+    """Write a fresh config with random credentials."""
+    path = Path(Config.default_path())
+    if path.exists():
+        if not force:
+            raise click.ClickException(f"{path} exists (use --force to overwrite)")
+        path.unlink()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    creds = dict(agent=pysecrets.token_hex(32), app=pysecrets.token_hex(32),
+                 admin=pysecrets.token_urlsafe(16), session=pysecrets.token_hex(32))
+    fd = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    with os.fdopen(fd, "w") as f:
+        f.write(CONFIG_TEMPLATE.format(**creds))
+    click.echo(f"Wrote {path}")
+    click.echo(f"  agent token:    {creds['agent']}")
+    click.echo(f"  app token:      {creds['app']}")
+    click.echo(f"  admin password: {creds['admin']}  (dashboard login)")
+    click.echo("Shown once — they live in the config file from now on.")
+
+@main.command()
+@click.option("--config", "config_path", default=None, help="Path to config.toml")
+@click.option("--lan", is_flag=True, help="Bind 0.0.0.0 and print the LAN pairing URL.")
+@click.option("--log-json", is_flag=True, help="Emit logs as JSON lines.")
+def serve(config_path, lan, log_json):
+    """Run the Arbiter server."""
+    import uvicorn
+    from .pair import local_ip
+    if log_json:
+        h = logging.StreamHandler()
+        h.setFormatter(_JsonFormatter())
+        logging.basicConfig(level=logging.INFO, handlers=[h])
+    else:
+        logging.basicConfig(level=logging.INFO,
+                            format="%(asctime)s %(name)s %(levelname)s %(message)s")
+    cfg = Config.load(config_path)
+    problems = cfg.validate_for_serve()
+    if problems:
+        raise click.ClickException("refusing to start:\n  - " + "\n  - ".join(problems))
+    host = "0.0.0.0" if lan else cfg.server.host
+    if lan or host == "0.0.0.0":
+        click.echo(f"Pair page: http://{local_ip()}:{cfg.server.port}/dashboard/pair")
+    from .db import Database
+    from .notify import Dispatcher, APNsSender
+    from .app import create_app
+    db = Database(cfg.db_path_expanded())
+    sender = APNsSender(cfg)
+    app = create_app(cfg, db, sender, dispatcher=Dispatcher(cfg, db, sender=sender))
+    # log_config=None: leave uvicorn's loggers unconfigured so they propagate to
+    # the root handler set up above (JSON or plain) instead of uvicorn's own
+    # dictConfig (which sets propagate=False with plain formatters).
+    uvicorn.run(app, host=host, port=cfg.server.port, log_config=None)
+
+@main.command()
+@click.option("--config", "config_path", default=None)
+@click.option("--host", "host_url", default=None, help="Server base URL for the QR (default http://<LAN-IP>:<port>)")
+def pair(config_path, host_url):
+    """Print the pairing QR code in the terminal."""
+    import segno
+    from .pair import build_pairing_payload, local_ip
+    cfg = Config.load(config_path)
+    if not cfg.auth.app_token:
+        raise click.ClickException("no app_token in config — run `hma init` first")
+    base = host_url or f"http://{local_ip()}:{cfg.server.port}"
+    payload = build_pairing_payload(base, cfg.auth.app_token)
+    click.echo(segno.make(payload).terminal(compact=True))
+    click.echo(f"URL:     {base}")
+    click.echo(f"Payload: {payload}")
+
+def _gather_status(client: httpx.Client, app_token: str) -> dict:
+    hdr = {"Authorization": f"Bearer {app_token}"}
+    r = client.get("/health")
+    r.raise_for_status()
+    d = client.get("/v1/devices", headers=hdr)
+    d.raise_for_status()
+    p = client.get("/v1/requests", headers=hdr, params={"status": "pending"})
+    p.raise_for_status()
+    return {"ok": r.json().get("ok", False), "devices": d.json(), "pending": p.json()}
+
+@main.command()
+@click.option("--config", "config_path", default=None)
+def status(config_path):
+    """Show server health, devices, and pending requests."""
+    cfg = Config.load(config_path)
+    base = f"http://127.0.0.1:{cfg.server.port}"
+    try:
+        with httpx.Client(base_url=base, timeout=5) as c:
+            st = _gather_status(c, cfg.auth.app_token)
+    except httpx.HTTPStatusError as exc:
+        raise click.ClickException(f"server error at {base}: {exc}")
+    except httpx.HTTPError as exc:
+        raise click.ClickException(f"server unreachable at {base}: {exc}")
+    ok, devices, pending = st["ok"], st["devices"], st["pending"]
+    click.echo(f"health:  {'ok' if ok else 'NOT OK'}")
+    click.echo(f"notifiers: apns={'on' if cfg.apns.configured else 'off'} "
+               f"ntfy={'on' if cfg.ntfy.enabled else 'off'} webhook={'on' if cfg.webhook.enabled else 'off'}")
+    click.echo(f"devices: {len(devices)}")
+    for d in devices:
+        click.echo(f"  - {d['name']} (min severity {d['min_severity']})")
+    click.echo(f"pending requests: {len(pending)}")
+
+def _ask(client: httpx.Client, agent_token: str, *, title: str, severity: str,
+         target: str | None, ttl: int, description: str) -> tuple[int, dict]:
+    hdr = {"Authorization": f"Bearer {agent_token}"}
+    try:
+        r = client.post("/v1/requests", headers=hdr, json={
+            "title": title, "description": description, "severity": severity,
+            "target": target, "ttl_seconds": ttl})
+        r.raise_for_status()
+        req = r.json()
+        deadline = time.time() + ttl + 5
+        while time.time() < deadline:
+            g = client.get(f"/v1/requests/{req['id']}", headers=hdr)
+            g.raise_for_status()
+            cur = g.json()
+            if cur["status"] != "pending":
+                return (0 if cur["status"] == "approved" else 1), cur
+            time.sleep(1)
+        return 1, {**req, "status": "expired"}
+    except Exception as exc:
+        return 2, {"error": str(exc)}
+
+@main.command()
+@click.argument("title")
+@click.option("--severity", type=click.Choice(["low", "medium", "high", "critical"]), default="medium")
+@click.option("--target", default=None)
+@click.option("--ttl", type=int, default=300)
+@click.option("--description", default="")
+@click.option("--config", "config_path", default=None)
+def ask(title, severity, target, ttl, description, config_path):
+    """Create an approval request and block until it is decided.
+
+    Exit codes: 0 approved · 1 denied/expired · 2 error (fail-closed: treat nonzero as no).
+    """
+    cfg = Config.load(config_path)
+    base = f"http://127.0.0.1:{cfg.server.port}"
+    with httpx.Client(base_url=base, timeout=10) as client:
+        code, decision = _ask(client, cfg.auth.agent_token, title=title,
+                              severity=severity, target=target, ttl=ttl, description=description)
+    click.echo(json.dumps(decision, indent=2))
+    sys.exit(code)
+
+if __name__ == "__main__":
+    main()

holdmyagent-0.2.0/arbiter/config.py

@@ -0,0 +1,128 @@
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+def _b(v: str) -> bool:
+    return v.strip().lower() in ("1", "true")
+
+@dataclass
+class ServerCfg:
+    host: str = "127.0.0.1"
+    port: int = 8000
+    db_path: str = "~/.local/share/holdmyagent/arbiter.sqlite3"
+
+@dataclass
+class AuthCfg:
+    agent_token: str = ""
+    app_token: str = ""
+    admin_password: str = ""
+    session_secret: str = ""
+
+@dataclass
+class ApnsCfg:
+    key_path: str = ""
+    key_id: str = ""
+    team_id: str = ""
+    bundle_id: str = "com.holdmyagent.HoldMyAgent"
+    sandbox: bool = False
+    @property
+    def configured(self) -> bool:
+        return bool(self.key_path and self.key_id and self.team_id)
+
+@dataclass
+class NtfyCfg:
+    url: str = "https://ntfy.sh"
+    topic: str = ""
+    token: str = ""
+    @property
+    def enabled(self) -> bool:
+        return bool(self.topic)
+
+@dataclass
+class WebhookCfg:
+    url: str = ""
+    secret: str = ""
+    @property
+    def enabled(self) -> bool:
+        return bool(self.url)
+
+_DEFAULT_TOKENS = {"dev-agent-token", "dev-app-token"}
+
+@dataclass
+class Config:
+    server: ServerCfg = field(default_factory=ServerCfg)
+    auth: AuthCfg = field(default_factory=AuthCfg)
+    apns: ApnsCfg = field(default_factory=ApnsCfg)
+    ntfy: NtfyCfg = field(default_factory=NtfyCfg)
+    webhook: WebhookCfg = field(default_factory=WebhookCfg)
+    loaded_path: str = ""
+
+    @staticmethod
+    def default_path() -> str:
+        return os.environ.get("HMA_CONFIG") or str(Path("~/.config/holdmyagent/config.toml").expanduser())
+
+    @staticmethod
+    def load(path: str | None = None) -> "Config":
+        cfg = Config()
+        p = Path(path or Config.default_path()).expanduser()
+        cfg.loaded_path = str(p)
+        if p.is_file():
+            with open(p, "rb") as f:
+                doc = tomllib.load(f)
+            s = doc.get("server", {})
+            a = doc.get("auth", {})
+            n = doc.get("notify", {})
+            for k in ("host", "port", "db_path"):
+                if k in s:
+                    setattr(cfg.server, k, s[k])
+            for k in ("agent_token", "app_token", "admin_password", "session_secret"):
+                if k in a:
+                    setattr(cfg.auth, k, a[k])
+            for k in ("key_path", "key_id", "team_id", "bundle_id", "sandbox"):
+                if k in n.get("apns", {}):
+                    setattr(cfg.apns, k, n["apns"][k])
+            for k in ("url", "topic", "token"):
+                if k in n.get("ntfy", {}):
+                    setattr(cfg.ntfy, k, n["ntfy"][k])
+            for k in ("url", "secret"):
+                if k in n.get("webhook", {}):
+                    setattr(cfg.webhook, k, n["webhook"][k])
+        env = os.environ
+        m = [("HMA_HOST", cfg.server, "host", str), ("HMA_PORT", cfg.server, "port", int),
+             ("HMA_DB_PATH", cfg.server, "db_path", str),
+             ("HMA_AGENT_TOKEN", cfg.auth, "agent_token", str), ("HMA_APP_TOKEN", cfg.auth, "app_token", str),
+             ("HMA_ADMIN_PASSWORD", cfg.auth, "admin_password", str),
+             ("HMA_SESSION_SECRET", cfg.auth, "session_secret", str),
+             ("HMA_APNS_KEY_PATH", cfg.apns, "key_path", str), ("HMA_APNS_KEY_ID", cfg.apns, "key_id", str),
+             ("HMA_APNS_TEAM_ID", cfg.apns, "team_id", str), ("HMA_APNS_BUNDLE_ID", cfg.apns, "bundle_id", str),
+             ("HMA_APNS_SANDBOX", cfg.apns, "sandbox", _b),
+             ("HMA_NTFY_URL", cfg.ntfy, "url", str), ("HMA_NTFY_TOPIC", cfg.ntfy, "topic", str),
+             ("HMA_NTFY_TOKEN", cfg.ntfy, "token", str),
+             ("HMA_WEBHOOK_URL", cfg.webhook, "url", str), ("HMA_WEBHOOK_SECRET", cfg.webhook, "secret", str)]
+        for name, obj, attr, cast in m:
+            if name in env:
+                setattr(obj, attr, cast(env[name]))
+        return cfg
+
+    def validate_for_serve(self) -> list[str]:
+        p: list[str] = []
+        a = self.auth
+        if not a.agent_token:
+            p.append("auth.agent_token is empty — run `hma init`")
+        if not a.app_token:
+            p.append("auth.app_token is empty — run `hma init`")
+        if not a.admin_password:
+            p.append("auth.admin_password is empty — run `hma init`")
+        if not a.session_secret:
+            p.append("auth.session_secret is empty — run `hma init`")
+        if a.agent_token in _DEFAULT_TOKENS or a.app_token in _DEFAULT_TOKENS:
+            p.append("refusing to run with default dev tokens")
+        if a.agent_token and a.agent_token == a.app_token:
+            p.append("agent_token and app_token must differ")
+        return p
+
+    def db_path_expanded(self) -> str:
+        path = Path(self.server.db_path).expanduser()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        return str(path)