puremethod 0.1.0__py3-none-any.whl

app/accounts.py

@@ -0,0 +1,137 @@
+"""Tenants, sign-in and sessions (08-app.md §4, §5 step 9).
+
+Sign-in is behind `AuthProvider`: self-hosted uses `LocalTokenAuth`; hosted mode adds OIDC
+as another provider. Sessions are the same for both. Only SHA-256 hashes of tokens and
+session ids are stored."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import secrets
+import time
+from collections.abc import Callable
+from typing import Protocol
+
+from app.db import Database
+from app.repo import new_id, now_iso
+
+TOKEN_BYTES = 32  # 256-bit (KB-021)
+SESSION_TTL_S = 12 * 3600
+CODE_TTL_S = 120.0  # one-time sign-in codes (08-app.md §5 step 9, INV-9)
+
+
+def _hash(secret: str) -> str:
+    return hashlib.sha256(secret.encode()).hexdigest()
+
+
+class AuthProvider(Protocol):
+    def tenant_for(self, credential: str) -> str | None: ...
+
+
+class LocalTokenAuth:
+    """Self-hosted API clients: a bearer token, issued by `token rotate` (KB-021, KB-025)."""
+
+    def __init__(self, db: Database) -> None:
+        self._db = db
+
+    def tenant_for(self, credential: str) -> str | None:
+        if not credential:
+            return None
+        with self._db.tx() as c:
+            rows = c.execute("SELECT tenant_id FROM tokens WHERE hash = ?", (_hash(credential),))
+        return str(rows[0][0]) if rows else None
+
+
+def create_tenant(db: Database) -> str:
+    tid = new_id("t")
+    with db.tx(write=True) as c:
+        c.execute("INSERT INTO tenants VALUES (?, ?)", (tid, now_iso()))
+    return tid
+
+
+def issue_token(db: Database, tenant_id: str) -> str:
+    """Replaces the tenant's tokens and ends its sessions. Returns the new token once."""
+    token = secrets.token_urlsafe(TOKEN_BYTES)
+    with db.tx(write=True) as c:
+        c.execute("DELETE FROM tokens WHERE tenant_id = ?", (tenant_id,))
+        c.execute("DELETE FROM sessions WHERE tenant_id = ?", (tenant_id,))
+        c.execute("INSERT INTO tokens VALUES (?, ?, ?)", (_hash(token), tenant_id, now_iso()))
+    return token
+
+
+def tenants(db: Database) -> list[str]:
+    with db.tx() as c:
+        return [str(r[0]) for r in c.execute("SELECT id FROM tenants ORDER BY created_at, id")]
+
+
+def bootstrap(db: Database) -> tuple[str, str | None]:
+    """Self-hosted first start: one tenant and its API token. Later starts return no token.
+    The caller does not print it (KB-025): `token rotate` issues one for API clients."""
+    existing = tenants(db)
+    if existing:
+        return existing[0], None
+    tid = create_tenant(db)
+    return tid, issue_token(db, tid)
+
+
+class SigninCodes:
+    """One-time browser sign-in codes (08-app.md §5 step 9, INV-9): 256-bit, stored as their
+    SHA-256 only, valid once within 2 minutes. Redeeming deletes the row in the same write
+    transaction, so two requests with one code cannot both succeed."""
+
+    def __init__(self, db: Database, clock: Callable[[], float] = time.time) -> None:
+        self._db = db
+        self._clock = clock
+
+    def issue(self, tenant_id: str) -> str:
+        code = secrets.token_urlsafe(TOKEN_BYTES)
+        with self._db.tx(write=True) as c:
+            c.execute("DELETE FROM signin_codes WHERE expires_at < ?", (self._clock(),))
+            c.execute("INSERT INTO signin_codes VALUES (?, ?, ?)",
+                      (_hash(code), tenant_id, self._clock() + CODE_TTL_S))
+        return code
+
+    def redeem(self, code: str) -> str | None:
+        if not code:
+            return None
+        with self._db.tx(write=True) as c:
+            rows = c.execute("SELECT tenant_id, expires_at FROM signin_codes WHERE hash = ?",
+                             (_hash(code),))
+            c.execute("DELETE FROM signin_codes WHERE hash = ? OR expires_at < ?",
+                      (_hash(code), self._clock()))
+        if not rows or float(rows[0][1]) < self._clock():
+            return None
+        return str(rows[0][0])
+
+
+class Sessions:
+    def __init__(self, db: Database, clock: Callable[[], float] = time.time) -> None:
+        self._db = db
+        self._clock = clock
+
+    def open(self, tenant_id: str) -> str:
+        sid = secrets.token_urlsafe(TOKEN_BYTES)
+        with self._db.tx(write=True) as c:
+            c.execute("DELETE FROM sessions WHERE expires_at < ?", (self._clock(),))
+            c.execute("INSERT INTO sessions VALUES (?, ?, ?)",
+                      (_hash(sid), tenant_id, self._clock() + SESSION_TTL_S))
+        return sid
+
+    def tenant_for(self, session_id: str) -> str | None:
+        if not session_id:
+            return None
+        with self._db.tx() as c:
+            rows = c.execute("SELECT tenant_id, expires_at FROM sessions WHERE hash = ?",
+                             (_hash(session_id),))
+        if not rows or float(rows[0][1]) < self._clock():
+            return None
+        return str(rows[0][0])
+
+    def close(self, session_id: str) -> None:
+        with self._db.tx(write=True) as c:
+            c.execute("DELETE FROM sessions WHERE hash = ?", (_hash(session_id),))
+
+
+def same(a: str, b: str) -> bool:
+    return hmac.compare_digest(a.encode(), b.encode())

app/addresses.py

@@ -0,0 +1,30 @@
+"""Whether a host is a private address (08-app.md INV-11, KB-036). `llm` keeps its own copy
+for its call-time check; `app` uses this one, since the function is not part of `llm`'s
+declared interface (07-llm.md §3)."""
+
+from __future__ import annotations
+
+import ipaddress
+import socket
+
+
+def private_address(host: str) -> bool:
+    """True if `host` is, or resolves to, a loopback, link-local, private or otherwise
+    non-public address (IPv4, IPv6, IPv4-mapped). An unresolvable name counts as private:
+    refusing is the safe answer."""
+    name = host.strip("[]")
+    try:
+        addrs = [ipaddress.ip_address(name)]
+    except ValueError:
+        try:
+            infos = socket.getaddrinfo(name, None)
+        except OSError:
+            return True
+        addrs = [ipaddress.ip_address(str(i[4][0]).split("%")[0]) for i in infos]
+    for a in addrs:
+        mapped = getattr(a, "ipv4_mapped", None)
+        if mapped is not None:
+            a = mapped
+        if not a.is_global or a.is_multicast:
+            return True
+    return not addrs

app/api/__init__.py

@@ -0,0 +1,61 @@
+"""The engine API, `/api/v1` (08-app.md §3). Never decrypts and never writes the ledger
+(INV-2, INV-3): import-linter keeps `app.unseal`, `app.compose`, `app.worker`, `app.scan`,
+`app.leases` and `app.supervisor` out of this package, and it sees the ledger only through
+`ReadOnlyLedger` (built in `app.server`)."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from pathlib import Path
+
+from fastapi import FastAPI, Request, Response
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from fastapi.staticfiles import StaticFiles
+
+from app.api import auth_routes, config_routes, run_routes, setup_routes
+from app.api.common import Ctx, validation_errors
+from app.setup import LocalStatus, local_not_yet
+
+PREFIX = "/api/v1"
+WRITE_METHODS = frozenset({"POST", "PATCH", "PUT"})
+# The UI is a static export served from this origin; Next.js inlines its bootstrap scripts.
+SECURITY_HEADERS = {
+    "Content-Security-Policy": "default-src 'self'; script-src 'self' 'unsafe-inline'; "
+                               "style-src 'self' 'unsafe-inline'; img-src 'self' data:; "
+                               "connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; "
+                               "form-action 'self'",
+    "X-Content-Type-Options": "nosniff",
+    "X-Frame-Options": "DENY",
+    "Referrer-Policy": "no-referrer",
+}
+
+
+def create_app(ctx: Ctx, web_dir: Path | None = None,
+               local_status: LocalStatus = local_not_yet) -> FastAPI:
+    """The API under `/api/v1` and, when `web_dir` holds the built web UI, the UI at `/`
+    from the same origin (08-app.md §5 step 8: self-hosted is one process)."""
+    app = FastAPI(title="puremethod engine API", docs_url=None, redoc_url=None,
+                  openapi_url=f"{PREFIX}/openapi.json")
+    app.state.ctx = ctx
+    app.state.local_status = local_status  # the bundled PureScholar's state (08 §5 step 12)
+    app.add_exception_handler(RequestValidationError, validation_errors)
+
+    @app.middleware("http")
+    async def json_bodies_only(request: Request,
+                               call_next: Callable[[Request], Awaitable[Response]]) -> Response:
+        # With SameSite=Strict cookies, this blocks form posts from other sites (CSRF).
+        if request.method in WRITE_METHODS and request.url.path.startswith(PREFIX):
+            if not request.headers.get("content-type", "").startswith("application/json"):
+                return JSONResponse(status_code=415, content={"detail": "JSON bodies only"})
+        response = await call_next(request)
+        for name, value in SECURITY_HEADERS.items():
+            response.headers.setdefault(name, value)
+        return response
+
+    for router in (auth_routes.router, config_routes.router, run_routes.router,
+                   setup_routes.router):
+        app.include_router(router, prefix=PREFIX)
+    if web_dir is not None and (web_dir / "index.html").is_file():
+        app.mount("/", StaticFiles(directory=web_dir, html=True), name="web")
+    return app

app/api/auth_routes.py

@@ -0,0 +1,54 @@
+"""Sign-in (08-app.md §5 step 9): an API token or a one-time sign-in code is exchanged for an
+HttpOnly, SameSite=Strict session cookie."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, HTTPException, Request, Response
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, model_validator
+
+from app.accounts import SESSION_TTL_S
+from app.api.common import COOKIE, ctx
+
+router = APIRouter()
+Secret = Annotated[SecretStr, Field(min_length=1, max_length=512)]
+
+
+class SessionIn(BaseModel):
+    """Exactly one of `token` (the API token) or `code` (a one-time code from the launcher)."""
+    model_config = ConfigDict(extra="forbid")
+    token: Secret | None = None
+    code: Secret | None = None
+
+    @model_validator(mode="after")
+    def _one(self) -> SessionIn:
+        if (self.token is None) == (self.code is None):
+            raise ValueError("send token or code")
+        return self
+
+
+@router.post("/auth/session", status_code=204)
+def sign_in(request: Request, body: SessionIn) -> Response:
+    c = ctx(request)
+    tid: str | None = None
+    if body.code is not None:
+        tid = c.codes.redeem(body.code.get_secret_value())  # single use (INV-9)
+    elif body.token is not None:
+        tid = c.auth.tenant_for(body.token.get_secret_value())
+    if tid is None:
+        raise HTTPException(401, "sign in")
+    resp = Response(status_code=204)
+    resp.set_cookie(COOKIE, c.sessions.open(tid), max_age=SESSION_TTL_S, httponly=True,
+                    samesite="strict", secure=request.url.scheme == "https", path="/")
+    return resp
+
+
+@router.delete("/auth/session", status_code=204)
+def sign_out(request: Request) -> Response:
+    sid = request.cookies.get(COOKIE)
+    if sid:
+        ctx(request).sessions.close(sid)
+    resp = Response(status_code=204)
+    resp.delete_cookie(COOKIE, path="/")
+    return resp

app/api/common.py

@@ -0,0 +1,102 @@
+"""What every route shares: the context, sign-in, and errors that reveal nothing (INV-1)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, NoReturn
+
+from fastapi import HTTPException, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+
+from app.accounts import AuthProvider, Sessions, SigninCodes
+from app.db import Database
+from app.outputs import OutputStore
+from app.readonly import ReadOnlyLedger
+from app.repo import RunRow, TenantRepo
+from app.settings import Settings
+from app.statuses import TERMINAL
+from loop import Loop
+
+COOKIE = "pm_session"
+NOT_FOUND = {"detail": "not found"}
+
+
+@dataclass
+class Ctx:
+    settings: Settings
+    db: Database
+    ledger: ReadOnlyLedger
+    status: Loop  # status only: its factories and credential lookup refuse (readonly.py)
+    auth: AuthProvider
+    sessions: Sessions
+    outputs: OutputStore
+    link_key: bytes
+    codes: SigninCodes
+    events_poll_s: float = 1.0
+    heartbeat_s: float = 15.0
+
+
+def ctx(request: Request) -> Ctx:
+    c: Ctx = request.app.state.ctx
+    return c
+
+
+def tenant(request: Request) -> str:
+    c = ctx(request)
+    header = request.headers.get("authorization", "")
+    if header[:7].lower() == "bearer ":
+        tid = c.auth.tenant_for(header[7:].strip())
+    else:
+        tid = c.sessions.tenant_for(request.cookies.get(COOKIE, ""))
+    if tid is None:
+        raise HTTPException(401, "sign in")
+    return tid
+
+
+def repo(request: Request, tenant_id: str) -> TenantRepo:
+    c = ctx(request)
+    return TenantRepo(c.db, tenant_id, c.settings.master_key)
+
+
+def not_found() -> NoReturn:
+    """The same answer for a missing resource and another tenant's (INV-1)."""
+    raise HTTPException(404, NOT_FOUND["detail"])
+
+
+def unprocessable(message: str) -> NoReturn:
+    raise HTTPException(422, message)
+
+
+def conflict(message: str) -> NoReturn:
+    raise HTTPException(409, message)
+
+
+async def validation_errors(request: Request, exc: Exception) -> JSONResponse:
+    """FastAPI's default echoes the rejected input, which for `/credentials` is the value.
+    Keep only where and what (Auditor, design review)."""
+    errors = exc.errors() if isinstance(exc, RequestValidationError) else []
+    return JSONResponse(status_code=422, content={"detail": clean_errors(errors)})
+
+
+def clean_errors(errors: Any) -> list[dict[str, Any]]:
+    return [{"loc": list(e.get("loc", [])), "msg": str(e.get("msg", "")),
+             "type": str(e.get("type", ""))} for e in errors]
+
+
+def active_runs(request: Request, r: TenantRepo) -> list[RunRow]:
+    """Runs queued, starting, or started and not yet delivered or failed (08 §5 step 12,
+    KB-032). A run whose status cannot be read counts as active."""
+    status = ctx(request).status
+    out = []
+    for run in r.list_runs():
+        if run.state == "start_failed":
+            continue
+        if run.state == "started" and run.ledger_run_id:
+            try:
+                if status.status(run.ledger_run_id).status in TERMINAL:
+                    continue
+            except Exception:  # noqa: S110 (unreadable: refuse rather than move its service)
+                pass
+        out.append(run)
+    return out