hull-core 0.1.0b1__py3-none-any.whl

hull_core/__init__.py

@@ -0,0 +1,36 @@
+"""hull-core: shared auth, model config, limiter, storage, and MCP server core."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("hull-core")
+except PackageNotFoundError:  # package not installed (e.g. running from source tree)
+    __version__ = "0.0.0+unknown"
+
+from hull_core.auth.context import AuthContext, current_user
+from hull_core.auth.middleware import Authenticator
+from hull_core.auth.tokens import hash_token, verify_token
+from hull_core.auth.users import User, UserLimits, UsersError, load_users
+from hull_core.config.models import ModelCell, resolve_model_cells
+from hull_core.config.settings import HullSettings, ServerSettings, load_settings
+from hull_core.limits.limiter import SlidingWindowLimiter
+from hull_core.storage.sqlite import HullDatabase
+
+__all__ = [
+    "AuthContext",
+    "Authenticator",
+    "HullDatabase",
+    "HullSettings",
+    "ModelCell",
+    "ServerSettings",
+    "SlidingWindowLimiter",
+    "User",
+    "UserLimits",
+    "UsersError",
+    "current_user",
+    "hash_token",
+    "load_settings",
+    "load_users",
+    "resolve_model_cells",
+    "verify_token",
+]

hull_core/auth/__init__.py

@@ -0,0 +1,33 @@
+"""Token authentication: users.toml, three modes, ASGI middleware, identity context."""
+
+from hull_core.auth.asgi import HullAuthMiddleware
+from hull_core.auth.context import AuthContext, current_user, reset_current_user, set_current_user
+from hull_core.auth.middleware import Authenticator, AuthOutcome
+from hull_core.auth.tokens import TokenHashError, hash_token, verify_token
+from hull_core.auth.users import (
+    User,
+    UserLimits,
+    UsersError,
+    ensure_path_allowed,
+    find_user_by_token,
+    load_users,
+)
+
+__all__ = [
+    "AuthContext",
+    "AuthOutcome",
+    "Authenticator",
+    "HullAuthMiddleware",
+    "TokenHashError",
+    "User",
+    "UserLimits",
+    "UsersError",
+    "current_user",
+    "ensure_path_allowed",
+    "find_user_by_token",
+    "hash_token",
+    "load_users",
+    "reset_current_user",
+    "set_current_user",
+    "verify_token",
+]

hull_core/auth/asgi.py

@@ -0,0 +1,75 @@
+"""Pure-ASGI middleware that authenticates the request and binds the identity.
+
+Runs before the MCP endpoint (passed through FastMCP's ``http_app`` middleware
+list) and publishes :class:`AuthContext` via the module contextvar so tools
+can scope storage access per user. Rejections are JSON:
+``401`` (missing/invalid token), ``403`` (disabled user), ``429`` (over limit).
+"""
+
+from __future__ import annotations
+
+import json
+
+from hull_core.auth.context import set_current_user, reset_current_user
+from hull_core.auth.middleware import Authenticator
+
+_STATUS_TEXT = {
+    401: "unauthorized",
+    403: "forbidden",
+    429: "rate limit exceeded",
+    500: "server misconfiguration",
+}
+
+
+class HullAuthMiddleware:
+    """ASGI middleware: authenticate → bind contextvar → forward, or reject."""
+
+    def __init__(self, app, authenticator: Authenticator) -> None:
+        self.app = app
+        self.authenticator = authenticator
+
+    async def __call__(self, scope, receive, send) -> None:  # noqa: ANN001
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        authz = None
+        for name, value in scope.get("headers", []):
+            if name == b"authorization":
+                authz = value.decode("latin-1")
+                break
+
+        outcome = self.authenticator.authenticate(authz)
+        if not outcome.ok:
+            await self._reject(send, outcome.status or 500, outcome.detail)
+            return
+
+        context = outcome.context
+        if context is None:
+            # ok=True always carries a context; fail closed rather than bind a
+            # null identity into the contextvar for the rest of the request.
+            await self._reject(send, 500, "authenticator returned no context")
+            return
+
+        token = set_current_user(context)
+        try:
+            await self.app(scope, receive, send)
+        finally:
+            reset_current_user(token)
+
+    async def _reject(self, send, status: int, detail: str) -> None:  # noqa: ANN001
+        body = json.dumps({"error": _STATUS_TEXT.get(status, "error"), "detail": detail}).encode("utf-8")
+        headers = [
+            (b"content-type", b"application/json"),
+            (b"content-length", str(len(body)).encode()),
+        ]
+        if status == 401:
+            headers.append((b"www-authenticate", b"Bearer"))
+        await send(
+            {
+                "type": "http.response.start",
+                "status": status,
+                "headers": headers,
+            }
+        )
+        await send({"type": "http.response.body", "body": body})

hull_core/auth/context.py

@@ -0,0 +1,47 @@
+"""Request-scoped identity for MCP tools.
+
+The pure-ASGI auth middleware resolves the caller before the MCP endpoint
+runs and stores the resulting :class:`AuthContext` in a contextvar. Tools read
+it with :func:`current_user` and scope every storage access by its namespace.
+A pure-ASGI middleware (not Starlette's BaseHTTPMiddleware) is used so the
+contextvar propagates into the endpoint task without anyio task-group copies.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+from dataclasses import dataclass, field
+
+_CURRENT: ContextVar["AuthContext | None"] = ContextVar("hull_current_user", default=None)
+
+
+@dataclass(frozen=True)
+class AuthContext:
+    """Resolved caller identity attached to one HTTP request."""
+
+    uid: str
+    namespace: str
+    mode: str
+    allowed_roots: tuple[str, ...] = ()
+    rpm: int | None = None
+    disabled: bool = False
+    attributes: dict = field(default_factory=dict)
+
+    @staticmethod
+    def local() -> "AuthContext":
+        """Identity used in no-auth mode (and for in-process tool calls)."""
+        return AuthContext(uid="local", namespace="default", mode="no-auth")
+
+
+def set_current_user(ctx: AuthContext) -> Token:
+    return _CURRENT.set(ctx)
+
+
+def reset_current_user(token: Token) -> None:
+    _CURRENT.reset(token)
+
+
+def current_user() -> AuthContext:
+    """The caller's identity; falls back to the local identity when unset."""
+    ctx = _CURRENT.get()
+    return ctx if ctx is not None else AuthContext.local()

hull_core/auth/middleware.py

@@ -0,0 +1,105 @@
+"""Token authentication: one mechanism, three modes (spec §4).
+
+Mode is a config state, resolved by the host in ``config.toml``:
+
+- ``no-auth`` — localhost-only; one shared namespace; no Authorization header.
+- ``token``   — one shared token; still one shared namespace.
+- ``multi``   — users.toml; token → user → namespace; 401 wrong token,
+  403 disabled user, 429 over limit.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from hull_core.auth.context import AuthContext
+from hull_core.auth.tokens import verify_token
+from hull_core.auth.users import User, UsersError, find_user_by_token
+from hull_core.config.settings import HullSettings
+from hull_core.limits.limiter import SlidingWindowLimiter
+
+
+@dataclass(frozen=True)
+class AuthOutcome:
+    """Result of authenticating one request."""
+
+    context: AuthContext | None = None
+    status: int | None = None  # None = proceed; 401/403 = reject
+    detail: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.status is None and self.context is not None
+
+
+class Authenticator:
+    """Resolves bearer tokens to AuthContexts according to the configured mode."""
+
+    def __init__(
+        self,
+        settings: HullSettings,
+        users: dict[str, User] | None = None,
+        limiter: SlidingWindowLimiter | None = None,
+    ) -> None:
+        self._settings = settings
+        self._mode = settings.server.auth
+        self._users = users
+        self._limiter = limiter if limiter is not None else SlidingWindowLimiter()
+
+    @property
+    def mode(self) -> str:
+        return self._mode
+
+    @property
+    def limiter(self) -> SlidingWindowLimiter:
+        return self._limiter
+
+    @staticmethod
+    def _bearer(authz: str | None) -> str | None:
+        if not authz:
+            return None
+        scheme, _, value = authz.partition(" ")
+        if scheme.lower() != "bearer" or not value.strip():
+            return None
+        return value.strip()
+
+    def authenticate(self, authz: str | None) -> AuthOutcome:
+        if self._mode == "no-auth":
+            return AuthOutcome(context=AuthContext.local())
+
+        token = self._bearer(authz)
+        if token is None:
+            return AuthOutcome(status=401, detail="missing or malformed Authorization header")
+
+        if self._mode == "token":
+            token_hash = self._settings.server.token_hash
+            if token_hash is None or not verify_token(token, token_hash):
+                return AuthOutcome(status=401, detail="invalid token")
+            return self._admit(
+                AuthContext(uid="shared", namespace="default", mode="token", rpm=self._settings.server.rpm)
+            )
+
+        if self._mode == "multi":
+            if self._users is None:
+                raise UsersError("multi mode requires the users table (load users.toml first)")
+            user = find_user_by_token(self._users, token)
+            if user is None:
+                return AuthOutcome(status=401, detail="invalid token")
+            if not user.enabled:
+                return AuthOutcome(status=403, detail=f"user {user.uid!r} is disabled")
+            return self._admit(
+                AuthContext(
+                    uid=user.uid,
+                    namespace=user.namespace,
+                    mode="multi",
+                    allowed_roots=user.allowed_roots,
+                    rpm=user.limits.rpm,
+                )
+            )
+
+        return AuthOutcome(status=500, detail=f"unknown auth mode {self._mode!r}")
+
+    def _admit(self, ctx: AuthContext) -> AuthOutcome:
+        if not self._limiter.check(ctx.uid, ctx.rpm):
+            return AuthOutcome(status=429, detail="rate limit exceeded")
+        return AuthOutcome(context=ctx)

hull_core/auth/tokens.py

@@ -0,0 +1,83 @@
+"""Token hashing and verification (host-side credential material).
+
+Tokens never travel to disk in plaintext: the host stores a scrypt hash in
+``users.toml`` / ``config.toml`` and verifies presented bearer tokens against
+it. Format::
+
+    scrypt$<n>$<r>$<p>$<salt-hex>$<derived-key-hex>
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import secrets
+
+_SCRYPT_N = 2**15
+_SCRYPT_R = 8
+_SCRYPT_P = 1
+_DKLEN = 32
+_PREFIX = "scrypt"
+# 128 * N * r = 32 MiB working memory; OpenSSL's default cap is lower on some
+# builds, so grant an explicit 64 MiB ceiling.
+_MAXMEM = 64 * 1024 * 1024
+
+
+class TokenHashError(ValueError):
+    """Raised when an encoded token hash is malformed."""
+
+
+def hash_token(token: str) -> str:
+    """Hash a bearer token into the storable ``scrypt$...`` encoding."""
+    salt = secrets.token_bytes(16)
+    dk = hashlib.scrypt(
+        token.encode("utf-8"),
+        salt=salt,
+        n=_SCRYPT_N,
+        r=_SCRYPT_R,
+        p=_SCRYPT_P,
+        dklen=_DKLEN,
+        maxmem=_MAXMEM,
+    )
+    return "$".join(
+        [
+            _PREFIX,
+            str(_SCRYPT_N),
+            str(_SCRYPT_R),
+            str(_SCRYPT_P),
+            salt.hex(),
+            dk.hex(),
+        ]
+    )
+
+
+def verify_token(token: str, encoded: str) -> bool:
+    """Constant-time verify a presented token against an encoded hash."""
+    try:
+        prefix, n_s, r_s, p_s, salt_hex, dk_hex = encoded.split("$")
+        n, r, p = int(n_s), int(r_s), int(p_s)
+        salt = bytes.fromhex(salt_hex)
+        expected = bytes.fromhex(dk_hex)
+    except (ValueError, AttributeError) as exc:
+        raise TokenHashError(f"malformed token hash encoding: {encoded[:24]!r}") from exc
+    if prefix != _PREFIX or not salt or not expected:
+        raise TokenHashError(f"malformed token hash encoding: {encoded[:24]!r}")
+    actual = hashlib.scrypt(
+        token.encode("utf-8"),
+        salt=salt,
+        n=n,
+        r=r,
+        p=p,
+        dklen=len(expected),
+        maxmem=_MAXMEM,
+    )
+    return hmac.compare_digest(actual, expected)
+
+
+def is_valid_encoding(encoded: str) -> bool:
+    """True when ``encoded`` parses as a scrypt token hash."""
+    try:
+        verify_token("", encoded)
+    except TokenHashError:
+        return False
+    return True

hull_core/auth/users.py

@@ -0,0 +1,131 @@
+"""users.toml — the multi-user table (auth mode 3).
+
+Schema (spec §4)::
+
+    [users.<uid>]
+    token_hash = "scrypt$..."        # mint with `hull token hash`
+    enabled = true
+    namespace = "<uid-or-shared>"    # data isolation root
+    allowed_roots = ["/data/alice"]  # filesystem roots tools may touch
+    [users.<uid>.limits]
+    rpm = 60                         # optional per-minute request cap
+
+Admin is host-side only: edit the file, restart the server. There is no admin
+API and no self-service.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol
+
+from hull_core.auth.tokens import is_valid_encoding, verify_token
+
+
+class UsersError(ValueError):
+    """Raised when users.toml is missing, malformed, or semantically invalid."""
+
+
+@dataclass(frozen=True)
+class UserLimits:
+    rpm: int | None = None
+
+
+@dataclass(frozen=True)
+class User:
+    uid: str
+    token_hash: str
+    enabled: bool
+    namespace: str
+    allowed_roots: tuple[str, ...] = ()
+    limits: UserLimits = field(default_factory=UserLimits)
+
+
+def load_users(path: Path) -> dict[str, User]:
+    """Parse and validate users.toml into a ``uid → User`` mapping."""
+    if not path.is_file():
+        raise UsersError(f"users file not found: {path}")
+    try:
+        raw = tomllib.loads(path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        raise UsersError(f"users file is not valid TOML: {path}: {exc}") from exc
+
+    table = raw.get("users")
+    if not isinstance(table, dict) or not table:
+        raise UsersError("users file must contain a non-empty [users] table")
+
+    users: dict[str, User] = {}
+    for uid, entry in table.items():
+        if not isinstance(entry, dict):
+            raise UsersError(f"user {uid!r}: expected a table")
+        token_hash = entry.get("token_hash")
+        if not isinstance(token_hash, str) or not is_valid_encoding(token_hash):
+            raise UsersError(
+                f"user {uid!r}: token_hash missing or not a scrypt encoding (mint one with `hull token hash`)"
+            )
+        namespace = entry.get("namespace")
+        if not isinstance(namespace, str) or not namespace:
+            raise UsersError(f"user {uid!r}: namespace must be a non-empty string")
+        enabled = entry.get("enabled", True)
+        if not isinstance(enabled, bool):
+            raise UsersError(f"user {uid!r}: enabled must be a boolean")
+        roots = entry.get("allowed_roots", [])
+        if not isinstance(roots, list) or not all(isinstance(r, str) for r in roots):
+            raise UsersError(f"user {uid!r}: allowed_roots must be a list of strings")
+        limits_raw = entry.get("limits", {})
+        if not isinstance(limits_raw, dict):
+            raise UsersError(f"user {uid!r}: limits must be a table")
+        rpm = limits_raw.get("rpm")
+        if rpm is not None and (not isinstance(rpm, int) or rpm < 1):
+            raise UsersError(f"user {uid!r}: limits.rpm must be a positive integer")
+        users[uid] = User(
+            uid=uid,
+            token_hash=token_hash,
+            enabled=enabled,
+            namespace=namespace,
+            allowed_roots=tuple(roots),
+            limits=UserLimits(rpm=rpm),
+        )
+    return users
+
+
+def find_user_by_token(users: dict[str, User], token: str) -> User | None:
+    """Return the user whose token_hash verifies ``token``, else None."""
+    for user in users.values():
+        if verify_token(token, user.token_hash):
+            return user
+    return None
+
+
+class PathScope(Protocol):
+    """Anything carrying a caller's filesystem roots.
+
+    Both the users.toml row (:class:`User`) and the per-request
+    :class:`~hull_core.auth.context.AuthContext` reach ``ensure_path_allowed``,
+    so the guard takes the shape both already have instead of one of them.
+    """
+
+    @property
+    def uid(self) -> str:
+        """Caller id used in the denial message."""
+
+    @property
+    def allowed_roots(self) -> tuple[str, ...]:
+        """Roots the caller may touch; empty grants nothing."""
+
+
+def ensure_path_allowed(user: PathScope, path: Path) -> None:
+    """Enforce the user's allowed_roots (spec §4 Q6).
+
+    An empty allowed_roots list grants nothing. Roots are matched lexically
+    after resolving both sides, so symlinked escapes require the resolved
+    target to sit under a root too.
+    """
+    resolved = path.resolve()
+    for root in user.allowed_roots:
+        root_resolved = Path(root).resolve()
+        if resolved == root_resolved or root_resolved in resolved.parents:
+            return
+    raise PermissionError(f"path {resolved} is outside allowed roots for user {user.uid!r}")

hull_core/cli.py

@@ -0,0 +1,107 @@
+"""Host-side CLI: control plane + consumer.
+
+Subcommands: ``server start``, ``token hash``, ``config init|path|show``,
+``db path``. With the server down, consumers are told to start it first —
+there is no hidden local-core mode (spec §3).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from hull_core.auth.tokens import hash_token
+from hull_core.config.settings import (
+    CONFIG_TEMPLATE,
+    default_config_dir,
+    load_settings,
+    write_default_config,
+)
+from hull_core.server.run import ServerConfigError, run_server
+
+
+def _cmd_server_start(args: argparse.Namespace) -> int:
+    try:
+        run_server(host=args.host, port=args.port)
+    except ServerConfigError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        pass
+    return 0
+
+
+def _cmd_token_hash(args: argparse.Namespace) -> int:
+    print(hash_token(args.token))
+    return 0
+
+
+def _cmd_config_init(args: argparse.Namespace) -> int:
+    try:
+        path = write_default_config(force=args.force)
+    except FileExistsError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    print(f"wrote {path}")
+    return 0
+
+
+def _cmd_config_path(_args: argparse.Namespace) -> int:
+    print(default_config_dir() / "config.toml")
+    return 0
+
+
+def _cmd_config_show(_args: argparse.Namespace) -> int:
+    path = default_config_dir() / "config.toml"
+    if path.is_file():
+        print(path.read_text(encoding="utf-8"), end="")
+    else:
+        print(CONFIG_TEMPLATE, end="")
+    return 0
+
+
+def _cmd_db_path(_args: argparse.Namespace) -> int:
+    settings = load_settings()
+    print(settings.config_dir / "hull.db")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="hull", description="hull shared core control plane")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    server = sub.add_parser("server", help="server lifecycle")
+    server_sub = server.add_subparsers(dest="server_command", required=True)
+    start = server_sub.add_parser("start", help="start the HTTP MCP server (blocking)")
+    start.add_argument("--host", default=None, help="bind host (default from config)")
+    start.add_argument("--port", type=int, default=None, help="bind port (default from config)")
+    start.set_defaults(func=_cmd_server_start)
+
+    token = sub.add_parser("token", help="token utilities")
+    token_sub = token.add_subparsers(dest="token_command", required=True)
+    token_hash_p = token_sub.add_parser("hash", help="mint a scrypt token_hash from a plaintext token")
+    token_hash_p.add_argument("token", help="plaintext token (keep it out of shells that log history)")
+    token_hash_p.set_defaults(func=_cmd_token_hash)
+
+    config = sub.add_parser("config", help="instance config utilities")
+    config_sub = config.add_subparsers(dest="config_command", required=True)
+    init_p = config_sub.add_parser("init", help="write ~/.hull/config.toml from the template")
+    init_p.add_argument("--force", action="store_true", help="overwrite an existing config")
+    init_p.set_defaults(func=_cmd_config_init)
+    path_p = config_sub.add_parser("path", help="print the config file path")
+    path_p.set_defaults(func=_cmd_config_path)
+    show_p = config_sub.add_parser("show", help="print the effective config (template if absent)")
+    show_p.set_defaults(func=_cmd_config_show)
+
+    db = sub.add_parser("db", help="storage utilities")
+    db_sub = db.add_subparsers(dest="db_command", required=True)
+    db_path_p = db_sub.add_parser("path", help="print the SQLite database path")
+    db_path_p.set_defaults(func=_cmd_db_path)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return int(args.func(args))

hull_core/config/__init__.py

@@ -0,0 +1,39 @@
+"""Instance config: server mode + per-task model cells."""
+
+from hull_core.config.models import (
+    DEFAULT_BASE_URL,
+    DEFAULT_MODELS,
+    TASKS,
+    ModelCell,
+    api_key_env,
+    model_cell_from_config,
+    resolve_model_cells,
+)
+from hull_core.config.settings import (
+    AUTH_MODES,
+    CONFIG_TEMPLATE,
+    ConfigError,
+    HullSettings,
+    ServerSettings,
+    default_config_dir,
+    load_settings,
+    write_default_config,
+)
+
+__all__ = [
+    "AUTH_MODES",
+    "CONFIG_TEMPLATE",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_MODELS",
+    "TASKS",
+    "ConfigError",
+    "HullSettings",
+    "ModelCell",
+    "ServerSettings",
+    "api_key_env",
+    "default_config_dir",
+    "load_settings",
+    "model_cell_from_config",
+    "resolve_model_cells",
+    "write_default_config",
+]