lean-memory-console 0.2.0__py3-none-any.whl

lean_memory_console/__init__.py

@@ -0,0 +1,3 @@
+"""lean-memory-console — agent-first read-only verification console."""
+
+__version__ = "0.2.0"

lean_memory_console/app.py

@@ -0,0 +1,142 @@
+"""FastAPI factory for the console (both modes).
+
+Local mode: 127.0.0.1 bind, per-launch session token (query param or
+X-Console-Token header). Docker mode: Authorization: Bearer <api_key>.
+Referrer-Policy: no-referrer on everything; local mode also validates the
+Host header (DNS-rebinding belt-and-suspenders).
+"""
+
+from __future__ import annotations
+
+import secrets
+from contextlib import AsyncExitStack, asynccontextmanager
+from pathlib import Path
+
+from fastapi import Depends, FastAPI, HTTPException, Request
+from fastapi.responses import JSONResponse, RedirectResponse
+from fastapi.staticfiles import StaticFiles
+
+from .config import ConsoleConfig
+from .engine import EngineGateway
+from .events import EventLog
+from .routes.data import build_data_router
+from .routes.mcp import build_mcp_mount
+from .routes.review import build_review_router
+from .routes.views import build_views_router
+
+# Loopback hostnames accepted in local mode (DNS-rebinding guard). Exact-match
+# only: a startswith check would wrongly admit e.g. "localhost.attacker.com".
+_ALLOWED_LOCAL_HOSTS = frozenset({"127.0.0.1", "localhost"})
+
+
+def _static_dir() -> Path:
+    """Directory of the built SPA (populated by the UI build). A seam so the
+    static-mount-ordering regression can be tested hermetically regardless of
+    whether the UI build has materialized ``static/`` on disk."""
+    return Path(__file__).parent / "static"
+
+
+def _ct_eq(presented: str | None, expected: str | None) -> bool:
+    """Constant-time string equality. False unless BOTH sides are non-None
+    strings (compare_digest raises on None/mismatched types), so a missing
+    credential or unconfigured secret never authenticates."""
+    if not isinstance(presented, str) or not isinstance(expected, str):
+        return False
+    return secrets.compare_digest(presented, expected)
+
+
+def _is_authenticated(request: Request, config: ConsoleConfig) -> bool:
+    if config.mode == "docker":
+        header = request.headers.get("Authorization", "")
+        expected = f"Bearer {config.api_key}" if config.api_key else None
+        return _ct_eq(header, expected)
+    # local mode: query token OR X-Console-Token header
+    token = request.query_params.get("token") or request.headers.get(
+        "X-Console-Token"
+    )
+    return _ct_eq(token, config.session_token)
+
+
+def require_auth(request: Request) -> None:
+    """FastAPI dependency: 401 unless valid credential is presented."""
+    config: ConsoleConfig = request.app.state.config
+    if not _is_authenticated(request, config):
+        raise HTTPException(status_code=401, detail="unauthorized")
+
+
+def create_app(
+    config: ConsoleConfig,
+    gateway: EngineGateway,
+    event_log: EventLog,
+) -> FastAPI:
+    # In Docker mode, build the streamable-HTTP MCP mount up front so its
+    # once-only session manager can be started by the app lifespan below — the
+    # only supported start path (run() cannot be re-entered per request). Under a
+    # real ASGI server (uvicorn) the lifespan runs; tests hitting /mcp must use a
+    # context-managed TestClient so the lifespan runs there too.
+    mcp_mount = (
+        build_mcp_mount(gateway, config) if config.mode == "docker" else None
+    )
+
+    @asynccontextmanager
+    async def _lifespan(_app: FastAPI):
+        async with AsyncExitStack() as stack:
+            if mcp_mount is not None:
+                await stack.enter_async_context(mcp_mount.session_manager.run())
+            yield
+
+    app = FastAPI(title="lean-memory-console", lifespan=_lifespan)
+    app.state.config = config
+    app.state.gateway = gateway
+    app.state.event_log = event_log
+
+    @app.middleware("http")
+    async def _security(request: Request, call_next):
+        # Local-mode Host guard (DNS-rebinding belt-and-suspenders).
+        if config.mode == "local":
+            host = request.headers.get("host", "")
+            hostname = host.split(":")[0]
+            if hostname not in _ALLOWED_LOCAL_HOSTS:
+                resp = JSONResponse(
+                    {"detail": "forbidden host"}, status_code=403
+                )
+                resp.headers["Referrer-Policy"] = "no-referrer"
+                return resp
+        response = await call_next(request)
+        response.headers["Referrer-Policy"] = "no-referrer"
+        return response
+
+    app.include_router(build_views_router())
+    # /views/*/review + /views/*/maintenance — per-route auth-gated, same prefix
+    # as views; registered before the static catch-all so its greedy "/" mount
+    # never shadows these paths.
+    app.include_router(build_review_router())
+    # /v1/* are POST handlers reading app.state.gateway; gate the whole router
+    # with the same auth dependency (local token / docker bearer).
+    app.include_router(
+        build_data_router(), dependencies=[Depends(require_auth)]
+    )
+
+    if mcp_mount is not None:
+        # A Starlette Mount("/mcp") only matches "/mcp/..." — a bare "/mcp"
+        # (what real MCP clients POST to, per the connect snippet) is NOT matched
+        # by the mount. Without a static "/" mount, Starlette's slash-redirect
+        # fallback used to bounce "/mcp" -> "/mcp/". But the greedy StaticFiles
+        # mount at "/" matches "/mcp" first and 405s every non-GET method before
+        # that fallback can run. Register an explicit 307 (method+body preserving)
+        # from "/mcp" to "/mcp/" so a bare POST reaches the bearer gate whether or
+        # not the SPA is present.
+        @app.post("/mcp", include_in_schema=False)
+        async def _mcp_slash_redirect() -> RedirectResponse:
+            return RedirectResponse(url="/mcp/", status_code=307)
+
+        app.mount("/mcp", mcp_mount)
+
+    # The SPA catch-all MUST be registered LAST so its greedy "/" mount never
+    # shadows /v1, /views, or /mcp (StaticFiles serves only GET/HEAD and 405s
+    # every other method on any path it matches).
+    static_dir = _static_dir()
+    if static_dir.is_dir():
+        app.mount("/", StaticFiles(directory=str(static_dir), html=True), name="spa")
+
+    return app

lean_memory_console/cli.py

@@ -0,0 +1,134 @@
+"""`lean-memory-console` CLI: serve | mcp, plus --print-compose-path."""
+
+from __future__ import annotations
+
+import argparse
+import importlib.resources
+import os
+import sys
+from pathlib import Path
+
+from .config import ConsoleConfig, load_config, resolve_data_root
+from .observe_mcp import run_stdio
+
+
+def _compose_path() -> Path:
+    """Path to the packaged docker-compose.yml.
+
+    Primary: importlib.resources over the installed package's deploy/ dir
+    (the wheel force-includes deploy/docker-compose.yml there). Dev fallback:
+    resolve the repo's deploy/docker-compose.yml relative to this file when
+    the packaged resource is missing (editable installs may not map the
+    force-include).
+    """
+    try:
+        res = importlib.resources.files("lean_memory_console").joinpath(
+            "deploy/docker-compose.yml"
+        )
+        if res.is_file():
+            return Path(str(res))
+    except (ModuleNotFoundError, FileNotFoundError):
+        pass
+    # Dev fallback: repo_root/deploy/docker-compose.yml.
+    # cli.py -> lean_memory_console -> src -> console -> repo_root
+    repo_root = Path(__file__).resolve().parents[3]
+    return repo_root / "deploy" / "docker-compose.yml"
+
+
+def _validate_serve_root(root: Path) -> None:
+    if not root.exists() or not os.access(root, os.R_OK):
+        sys.stderr.write(
+            f"error: data root not readable: {root}\n"
+        )
+        raise SystemExit(2)
+
+
+def _run_server(config: ConsoleConfig, no_open: bool) -> None:  # pragma: no cover
+    """Start uvicorn (real entry; monkeypatched in tests).
+
+    Host bind is mode-dependent:
+      local  -> 127.0.0.1  (loopback only; the app's Host guard is a second belt)
+      docker -> 0.0.0.0    (the container must be reachable via published ports;
+                            the local-mode Host guard does NOT run in docker mode,
+                            so the controls are the bearer gate (LM_API_KEY) plus
+                            the MCP transport-security Host allowlist).
+    Docker mode has no per-launch session token, so there is no tokened URL to
+    open and the browser-open path is skipped entirely (there is no browser in
+    the container regardless).
+    """
+    import uvicorn
+
+    from .app import create_app
+    from .engine import EngineGateway
+    from .events import EventLog
+
+    event_log = EventLog(config.data_root)
+    gateway = EngineGateway(config, event_log)
+    app = create_app(config, gateway, event_log)
+    if config.mode == "docker":
+        host = "0.0.0.0"  # noqa: S104 — intentional; see docstring (bearer + allowlist gate)
+        url = f"http://0.0.0.0:{config.port}/"
+    else:
+        host = "127.0.0.1"
+        url = f"http://127.0.0.1:{config.port}/?token={config.session_token}"
+        if not no_open:
+            import webbrowser
+
+            webbrowser.open(url)
+    sys.stdout.write(f"lean-memory-console serving at {url}\n")
+    try:
+        uvicorn.run(app, host=host, port=config.port, log_level="info")
+    finally:
+        gateway.close()
+        event_log.close()
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(prog="lean-memory-console")
+    parser.add_argument(
+        "--print-compose-path", action="store_true",
+        help="print the packaged docker-compose.yml path and exit",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    p_serve = sub.add_parser("serve", help="run the read-only console")
+    p_serve.add_argument("--root", default=None)
+    p_serve.add_argument("--port", type=int, default=None)
+    p_serve.add_argument("--no-open", action="store_true")
+    p_serve.add_argument(
+        "--docker",
+        action="store_true",
+        help=(
+            "run in Docker mode: bearer auth (LM_API_KEY required), bind 0.0.0.0, "
+            "register the /mcp mount. Explicit flag — no env-based magic detection."
+        ),
+    )
+
+    p_mcp = sub.add_parser("mcp", help="run the observing MCP stdio server")
+    p_mcp.add_argument("--root", default=None)
+
+    args = parser.parse_args(argv)
+
+    if args.print_compose_path:
+        sys.stdout.write(f"{_compose_path()}\n")
+        return 0
+
+    if args.command == "serve":
+        root = resolve_data_root(args.root)
+        _validate_serve_root(root)
+        # Explicit mode selection — no magic env detection. --docker selects the
+        # containerized entrypoint: bearer auth, 0.0.0.0 bind, /mcp mount. Boot
+        # validation (LM_API_KEY required -> SystemExit(2)) comes free from
+        # load_config("docker").
+        mode = "docker" if args.docker else "local"
+        config = load_config(mode, cli_root=args.root, port=args.port)
+        _run_server(config, no_open=args.no_open)
+        return 0
+
+    if args.command == "mcp":
+        config = load_config("local", cli_root=args.root)
+        run_stdio(config)
+        return 0
+
+    parser.print_help()
+    return 1

lean_memory_console/config.py

@@ -0,0 +1,121 @@
+"""Console configuration: data-root resolution, namespace sanitizer mirror,
+reserved-namespace guard, and mode-specific config loading (spec §5, §7, §10).
+
+SAFE_NS_RE and sanitize_namespace mirror the engine's private sanitizer
+(memory.py:38, 70-71). The mirror is guarded by the fail-loud tripwire in
+inspect_sql.py (spec §13) so engine drift turns the suite red.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import secrets
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# Mirror of engine memory.py:38  _SAFE_NS = re.compile(r"[^A-Za-z0-9_.-]")
+SAFE_NS_RE: re.Pattern = re.compile(r"[^A-Za-z0-9_.-]")
+
+DEFAULT_DATA_ROOT = Path("~/.lean_memory")
+DEFAULT_PORT = 8377
+
+
+def sanitize_namespace(name: str) -> str:
+    """Mirror of memory.py:70-71  safe = _SAFE_NS.sub("_", name) or "default"."""
+    return SAFE_NS_RE.sub("_", name) or "default"
+
+
+def is_reserved_namespace(name: str) -> bool:
+    """True when the sanitized namespace begins with '_' (collides with sidecars
+    like _events.db); the data plane rejects these (spec §5)."""
+    return sanitize_namespace(name).startswith("_")
+
+
+def ns_db_path(data_root: Path, namespace: str) -> Path:
+    """The engine store file for a namespace: root / f'{safe}.db'."""
+    return data_root / f"{sanitize_namespace(namespace)}.db"
+
+
+def resolve_data_root(cli_root: str | None) -> Path:
+    """One rule, both commands (spec §10): --root > LM_DATA_ROOT > ~/.lean_memory.
+    expanduser is applied; this function never creates the directory."""
+    if cli_root:
+        return Path(cli_root).expanduser()
+    env = os.environ.get("LM_DATA_ROOT")
+    if env:
+        return Path(env).expanduser()
+    return DEFAULT_DATA_ROOT.expanduser()
+
+
+def parse_allowed_hosts(raw: str | None) -> list[str]:
+    """Parse LM_MCP_ALLOWED_HOSTS (comma-separated host patterns) into a list.
+
+    Whitespace around each entry is stripped and empty entries dropped, so
+    "a:*, b:*" and "a:*,,b:*" both yield ["a:*", "b:*"]. None/empty → []. The
+    patterns are consumed verbatim by the MCP transport-security allow-list
+    (exact match or a trailing ":*" port wildcard — see routes/mcp.py)."""
+    if not raw:
+        return []
+    return [part.strip() for part in raw.split(",") if part.strip()]
+
+
+@dataclass
+class ConsoleConfig:
+    data_root: Path
+    mode: str  # "local" | "docker"
+    api_key: str | None = None
+    port: int = DEFAULT_PORT
+    models: str = "auto"  # "auto" | "stub"
+    session_token: str | None = None
+    # Docker mode only: extra Host patterns the MCP mount accepts, ADDED to the
+    # loopback defaults. Set via LM_MCP_ALLOWED_HOSTS so a container published on
+    # a LAN IP/hostname (the shipped compose flow, no reverse proxy) is reachable.
+    mcp_allowed_hosts: list[str] = field(default_factory=list)
+
+
+def load_config(
+    mode: str, cli_root: str | None = None, port: int | None = None
+) -> ConsoleConfig:
+    """Build a ConsoleConfig for the given mode.
+
+    docker: LM_API_KEY is required — a missing key raises SystemExit(2) with a
+            clear message. No per-launch session token.
+    local:  a fresh random session_token is minted (embedded in the tokened URL).
+    """
+    data_root = resolve_data_root(cli_root)
+    models = os.environ.get("LM_CONSOLE_MODELS", "auto")
+    if models not in ("auto", "stub"):
+        models = "auto"
+    resolved_port = port if port is not None else DEFAULT_PORT
+
+    if mode == "docker":
+        api_key = os.environ.get("LM_API_KEY")
+        if not api_key:
+            print(
+                "LM_API_KEY is required in Docker mode; refusing to boot.",
+                file=sys.stderr,
+            )
+            raise SystemExit(2)
+        return ConsoleConfig(
+            data_root=data_root,
+            mode="docker",
+            api_key=api_key,
+            port=resolved_port,
+            models=models,
+            session_token=None,
+            mcp_allowed_hosts=parse_allowed_hosts(
+                os.environ.get("LM_MCP_ALLOWED_HOSTS")
+            ),
+        )
+
+    # local mode
+    return ConsoleConfig(
+        data_root=data_root,
+        mode="local",
+        api_key=None,
+        port=resolved_port,
+        models=models,
+        session_token=secrets.token_urlsafe(24),
+    )

lean_memory_console/deploy/docker-compose.yml

@@ -0,0 +1,36 @@
+# deploy/docker-compose.yml — single-tenant lean-memory-console (Docker mode).
+#
+# Usage:
+#   LM_API_KEY=$(openssl rand -hex 24) docker compose -f deploy/docker-compose.yml up -d
+#
+# Single source of truth (spec §9): the console CLI packages this exact file
+# into the wheel; the plugin's /memory:server-up|down commands resolve it via
+#   docker compose -f "$(lean-memory-console --print-compose-path)" up -d
+services:
+  console:
+    build:
+      context: ..
+      dockerfile: deploy/Dockerfile
+      target: full            # full is the default first-run image (real models)
+    ports:
+      - "8377:8377"
+    environment:
+      # LM_API_KEY is required in Docker mode — compose refuses to start
+      # without it (the console also boot-checks it).
+      - LM_API_KEY=${LM_API_KEY:?set LM_API_KEY - e.g. openssl rand -hex 24}
+      - LM_DATA_ROOT=/data
+      - PORT=8377
+      - LM_CONSOLE_MODELS=auto
+      # Remote-host deployments (reached over the LAN, no reverse proxy) must
+      # list the hostname(s)/IP(s) the container is reached by, or the MCP mount
+      # 421s on the Host check. Comma-separated; ":*" matches any port. The
+      # bearer gate (LM_API_KEY) remains the primary access control.
+      # - LM_MCP_ALLOWED_HOSTS=myhost:*
+    volumes:
+      - lm_data:/data
+      - hf_cache:/root/.cache/huggingface
+    restart: unless-stopped
+
+volumes:
+  lm_data:
+  hf_cache: