valved 0.1.0__py3-none-any.whl

valved/__init__.py

@@ -0,0 +1,5 @@
+"""Valved — AI-first data engineering framework."""
+
+from valved.version import __version__
+
+__all__ = ["__version__"]

valved/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m valved`."""
+
+from valved.cli.main import app
+
+if __name__ == "__main__":
+    app()

valved/api/__init__.py

@@ -0,0 +1,11 @@
+"""Valved's REST API — a FastAPI app over the shipped services.
+
+``create_app(state_store, config)`` (in :mod:`valved.api.main`) builds the app
+`valved serve` runs: bearer auth + idempotency middleware, problem+json errors,
+cursor pagination, the ``/api/v1`` router tree, run streaming (WebSocket/SSE),
+and the webhook publisher loop. See the rest-api capability spec.
+"""
+
+from valved.api.main import create_app
+
+__all__ = ["create_app"]

valved/api/auth.py

@@ -0,0 +1,141 @@
+"""Bearer-token authentication for the REST API.
+
+:class:`AuthMiddleware` gates every ``/api/v1/*`` request: it extracts the
+``Authorization: Bearer <token>`` header, resolves it to an :class:`Identity` via
+``state_store.tokens.find_by_token`` (argon2 verification against the active
+tokens), stashes the identity on ``request.state``, and stamps ``last_used_at``.
+Missing/invalid tokens → 401 problem+json.
+
+``Identity`` and the argon2 hashing / token-generation helpers are defined in the
+state layer (:mod:`valved.core.state.tokens`) so ``Tokens.create`` is
+self-contained and ``api`` depends on ``state`` (never the reverse); they are
+re-exported here as the module's public auth surface. This module also owns the
+OSS default-token bootstrap (:func:`ensure_default_token`) and rotation
+(:func:`rotate_token`), which write the plaintext to ``.valved/token``.
+
+Health/OpenAPI/docs routes (outside ``/api/v1``) are unauthenticated plumbing.
+WebSocket upgrades bypass ``BaseHTTPMiddleware`` entirely (Starlette only runs it
+for ``http`` scopes), so the stream handler authenticates at connection time.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import stat
+from typing import TYPE_CHECKING
+
+from starlette.concurrency import run_in_threadpool
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from valved.api.errors import problem
+
+# Re-exported public auth surface (defined in the state layer — see module docs).
+from valved.core.state.tokens import (
+    Identity,
+    generate_token,
+    hash_token,
+    verify_token,
+)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from starlette.requests import Request
+    from starlette.types import ASGIApp
+
+    from valved.core.state.store import StateStore
+
+logger = logging.getLogger(__name__)
+
+#: Everything under this prefix requires a valid bearer token.
+_PROTECTED_PREFIX = "/api/v1"
+
+
+class AuthMiddleware(BaseHTTPMiddleware):
+    """Reject unauthenticated ``/api/v1/*`` requests; attach the identity otherwise."""
+
+    def __init__(self, app: ASGIApp, *, state_store: StateStore) -> None:
+        super().__init__(app)
+        self._state_store = state_store
+
+    async def dispatch(self, request: Request, call_next):  # type: ignore[no-untyped-def]
+        path = request.url.path
+        if not path.startswith(_PROTECTED_PREFIX):
+            # Health / OpenAPI / docs are unauthenticated plumbing.
+            return await call_next(request)
+
+        auth_header = request.headers.get("authorization", "")
+        if not auth_header.startswith("Bearer "):
+            return problem(
+                401,
+                "missing-bearer-token",
+                "Missing bearer token",
+                detail="Provide an `Authorization: Bearer <token>` header.",
+                instance=path,
+            )
+        token_plain = auth_header[len("Bearer ") :].strip()
+        identity = await run_in_threadpool(self._state_store.tokens.find_by_token, token_plain)
+        if identity is None:
+            return problem(
+                401,
+                "invalid-token",
+                "Invalid or revoked token",
+                detail="The bearer token was not recognized.",
+                instance=path,
+            )
+        request.state.identity = identity
+        # Best-effort last-used stamp; a write hiccup must not fail the request.
+        try:
+            await run_in_threadpool(self._state_store.tokens.touch_last_used, identity.token_id)
+        except Exception:  # pragma: no cover - defensive
+            logger.warning("failed to stamp token last_used_at", exc_info=True)
+        return await call_next(request)
+
+
+def _write_token_file(token_path: Path, plaintext: str) -> None:
+    """Write the plaintext token to ``token_path`` with 0600 perms (owner-only)."""
+    token_path.parent.mkdir(parents=True, exist_ok=True)
+    token_path.write_text(plaintext + "\n")
+    try:
+        os.chmod(token_path, stat.S_IRUSR | stat.S_IWUSR)
+    except OSError:  # pragma: no cover - platform-dependent (e.g. Windows)
+        pass
+
+
+def ensure_default_token(state_store: StateStore, token_path: Path) -> str | None:
+    """Mint the OSS default token (scope ``["*"]``) iff none exists yet.
+
+    Idempotent: with an active default token already present it returns ``None``
+    and leaves ``.valved/token`` untouched. Otherwise it mints one, writes the
+    plaintext to ``token_path`` (0600), and returns it. Requires the ``tokens``
+    table (migrations at head) — call it from ``valved serve`` startup after
+    migrations, and best-effort at ``valved init`` when the DB is reachable.
+    """
+    if state_store.tokens.has_active_default():
+        return None
+    _token_id, plaintext = state_store.tokens.create(scopes=["*"], is_default=True)
+    _write_token_file(token_path, plaintext)
+    return plaintext
+
+
+def rotate_token(state_store: StateStore, token_path: Path) -> str:
+    """Mint a fresh full-scope token, rewrite ``.valved/token``, and return it.
+
+    Does not revoke prior tokens (the user may hold others); ``valved auth rotate``
+    prints the returned plaintext.
+    """
+    _token_id, plaintext = state_store.tokens.create(scopes=["*"])
+    _write_token_file(token_path, plaintext)
+    return plaintext
+
+
+__all__ = [
+    "AuthMiddleware",
+    "Identity",
+    "ensure_default_token",
+    "generate_token",
+    "hash_token",
+    "rotate_token",
+    "verify_token",
+]

valved/api/dependencies.py

@@ -0,0 +1,70 @@
+"""Shared FastAPI dependencies for the routers.
+
+The app stashes the :class:`StateStore` and :class:`Config` on ``app.state`` at
+:func:`valved.api.main.create_app` time; these accessors read them back.
+:func:`get_identity` returns the authenticated principal the
+:class:`valved.api.auth.AuthMiddleware` attached to ``request.state``.
+:func:`pagination_params` parses + clamps the ``?cursor=&limit=`` query pair.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fastapi import Query, Request
+
+from valved.api.errors import Unauthorized
+from valved.api.pagination import PageParams, make_page_params
+
+if TYPE_CHECKING:
+    from valved.core.config import Config
+    from valved.core.config.paths import ProjectPaths
+    from valved.core.state.store import StateStore
+    from valved.core.state.tokens import Identity
+
+
+def get_state_store(request: Request) -> StateStore:
+    """The process-wide :class:`StateStore` bundle."""
+    return request.app.state.state_store  # type: ignore[no-any-return]
+
+
+def get_config(request: Request) -> Config:
+    """The merged :class:`Config`."""
+    return request.app.state.config  # type: ignore[no-any-return]
+
+
+def get_project_paths(request: Request) -> ProjectPaths:
+    """The :class:`ProjectPaths` (filesystem roots for agents/skills/memory)."""
+    return request.app.state.project_paths  # type: ignore[no-any-return]
+
+
+def get_identity(request: Request) -> Identity:
+    """The authenticated principal (set by ``AuthMiddleware``).
+
+    NOTE(rest-api): see issue — hosted-forward per-tenant authorization / scope
+    enforcement (``scopes``) belongs here; OSS is single-user full-scope.
+    """
+    identity = getattr(request.state, "identity", None)
+    if identity is None:  # pragma: no cover - middleware guarantees it under /api/v1
+        raise Unauthorized("Authentication required.")
+    return identity  # type: ignore[no-any-return]
+
+
+def pagination_params(
+    cursor: str | None = Query(default=None, description="Opaque pagination cursor."),
+    limit: int | None = Query(
+        default=None,
+        description="Max items per page (default 50, max 200).",
+    ),
+) -> PageParams:
+    """Parse + clamp the pagination query pair."""
+    return make_page_params(cursor, limit)
+
+
+__all__ = [
+    "get_config",
+    "get_identity",
+    "get_project_paths",
+    "get_state_store",
+    "pagination_params",
+]

valved/api/errors.py

@@ -0,0 +1,333 @@
+"""RFC 9457 ``application/problem+json`` error handling for the REST API.
+
+Two responsibilities:
+
+* :func:`problem` — build a problem+json ``JSONResponse`` with a stable
+  ``https://valved.dev/errors/<slug>`` ``type`` URL, ``title``, ``status``,
+  optional ``detail``/``instance``, and arbitrary custom fields.
+* :class:`ProblemJsonExceptionHandler` + :func:`install_error_handlers` — turn
+  the codebase's *scattered* domain exceptions (there is **no** unified
+  ``ValvedError`` base) into problem+json.
+
+**Design decision (mapping table, not a base-class retrofit).** Rather than
+introduce a ``ValvedError`` base and retrofit every module in this slice, the
+handler keys an explicit ``exception → (type-slug, status, title)`` table by the
+exception's *fully-qualified class name* (walking the MRO). That means this
+module imports **none** of the heavy orchestrator/agent modules the exceptions
+live in — it matches by name and reads attributes with ``getattr``. An
+unrecognized exception becomes 500 ``.../errors/internal`` with the stack trace
+logged (never returned to the client). API-local signalling exceptions
+(:class:`ResourceNotFound`/:class:`BadRequest`/:class:`Conflict`) carry their own
+status/type and are handled by ``isinstance`` (same module, no import cost).
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from fastapi.exceptions import RequestValidationError
+from starlette.exceptions import HTTPException as StarletteHTTPException
+from starlette.responses import JSONResponse
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+    from starlette.requests import Request
+    from starlette.responses import Response
+
+logger = logging.getLogger(__name__)
+
+#: Every problem ``type`` is this base + a stable slug. Documented + versioned;
+#: clients switch on the slug, never on ``title``/``detail``.
+_ERROR_BASE = "https://valved.dev/errors/"
+
+PROBLEM_JSON_MEDIA_TYPE = "application/problem+json"
+
+
+def problem(
+    status: int,
+    type_slug: str,
+    title: str,
+    *,
+    detail: str | None = None,
+    instance: str | None = None,
+    **extra: Any,
+) -> JSONResponse:
+    """Build an RFC 9457 problem+json response.
+
+    ``type`` is ``_ERROR_BASE + type_slug``. ``detail``/``instance`` and any
+    non-``None`` ``extra`` custom fields (e.g. ``plan_id``,
+    ``expected_config_hash``) are merged into the body.
+    """
+    body: dict[str, Any] = {
+        "type": _ERROR_BASE + type_slug,
+        "title": title,
+        "status": status,
+    }
+    if detail is not None:
+        body["detail"] = detail
+    if instance is not None:
+        body["instance"] = instance
+    for key, value in extra.items():
+        if value is not None:
+            body[key] = value
+    return JSONResponse(status_code=status, content=body, media_type=PROBLEM_JSON_MEDIA_TYPE)
+
+
+# ---------------------------------------------------------------------------
+# API-local signalling exceptions (raised by routers)
+# ---------------------------------------------------------------------------
+
+
+class ApiError(Exception):
+    """Base for router-raised problems that carry their own status/type/title.
+
+    Subclasses set the class attributes; the instance carries an optional
+    ``detail`` and arbitrary problem-body ``extra`` fields.
+    """
+
+    status: int = 500
+    type_slug: str = "internal"
+    title: str = "Internal server error"
+
+    def __init__(self, detail: str | None = None, **extra: Any) -> None:
+        self.detail = detail
+        self.extra = extra
+        super().__init__(detail or self.title)
+
+
+class Unauthorized(ApiError):
+    """The request lacks valid authentication (→ 401)."""
+
+    status = 401
+    type_slug = "unauthorized"
+    title = "Unauthorized"
+
+
+class ResourceNotFound(ApiError):
+    """A requested resource does not exist (→ 404)."""
+
+    status = 404
+    type_slug = "not-found"
+    title = "Resource not found"
+
+
+class BadRequest(ApiError):
+    """The request was malformed or semantically invalid (→ 400)."""
+
+    status = 400
+    type_slug = "bad-request"
+    title = "Bad request"
+
+
+class Conflict(ApiError):
+    """The request conflicts with current state (→ 409)."""
+
+    status = 409
+    type_slug = "conflict"
+    title = "Conflict"
+
+
+# ---------------------------------------------------------------------------
+# Domain-exception mapping (by fully-qualified name — no heavy imports)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class _ErrorSpec:
+    type_slug: str
+    status: int
+    title: str
+
+
+#: Real, shipped exceptions → problem spec. Keyed by ``module.qualname`` so this
+#: module imports none of them; the MRO walk matches a subclass at its nearest
+#: registered ancestor (e.g. ``MaxTurnsExceeded`` → ``AgentError``).
+_ERROR_MAP: dict[str, _ErrorSpec] = {
+    "valved.cli.orchestrator.builder.ConfigDriftError": _ErrorSpec(
+        "config-drift", 409, "Plan was generated against a different config"
+    ),
+    "valved.cli.orchestrator.builder.PlanExpiredError": _ErrorSpec(
+        "plan-expired", 409, "Plan has expired"
+    ),
+    "valved.cli.orchestrator.builder.BuildError": _ErrorSpec(
+        "build-failed", 400, "Build could not proceed"
+    ),
+    "valved.cli.orchestrator.planner.PlanGenerationError": _ErrorSpec(
+        "plan-generation", 422, "Plan generation failed"
+    ),
+    "valved.core.memory.writer.DecisionAlreadyExists": _ErrorSpec(
+        "decision-exists", 409, "Decision already exists"
+    ),
+    "valved.core.config.exceptions.ConfigError": _ErrorSpec(
+        "config-invalid", 400, "Configuration error"
+    ),
+    "valved.core.config.pipeline_schema.PipelineError": _ErrorSpec(
+        "pipeline-invalid", 400, "Pipeline definition error"
+    ),
+    "valved.core.connectors.exceptions.SnowflakeError": _ErrorSpec(
+        "snowflake", 502, "Snowflake error"
+    ),
+    "valved.core.targets.resolution.TargetResolutionError": _ErrorSpec(
+        "target-resolution", 400, "Target resolution error"
+    ),
+    "valved.core.agents.exceptions.AgentError": _ErrorSpec("agent", 500, "Agent run failed"),
+    "valved.core.hooks.runner.HookExecutionError": _ErrorSpec(
+        "hook-execution", 500, "Hook execution failed"
+    ),
+    "valved.core.hooks.config.HookConfigError": _ErrorSpec(
+        "hook-config", 400, "Hook configuration error"
+    ),
+    "valved.core.deploy.ddl_applier.UnsafeDdlError": _ErrorSpec(
+        "unsafe-ddl", 400, "Unsafe DDL rejected"
+    ),
+    "valved.core.mcp.config.McpConfigError": _ErrorSpec(
+        "mcp-config", 400, "MCP configuration error"
+    ),
+    "valved.core.agents.loader.AgentLoadError": _ErrorSpec(
+        "agent-load", 400, "Agent definition error"
+    ),
+    "valved.core.skills.packs.SkillPackError": _ErrorSpec("skill-pack", 400, "Skill pack error"),
+    "valved.core.state.job_queue.PipelineAlreadyRunning": _ErrorSpec(
+        "pipeline-already-running", 409, "Pipeline is already running"
+    ),
+    "valved.core.state.job_queue.QueuedJobAlreadyExists": _ErrorSpec(
+        "job-already-queued", 409, "A job is already queued for this pipeline"
+    ),
+    "valved.core.state.schedules.ScheduleNotFound": _ErrorSpec(
+        "schedule-not-found", 404, "Schedule not found"
+    ),
+    "valved.init.plan.InitError": _ErrorSpec("init-failed", 400, "Initialization error"),
+}
+
+
+def _fqname(cls: type) -> str:
+    return f"{cls.__module__}.{cls.__qualname__}"
+
+
+def _lookup_spec(exc: BaseException) -> _ErrorSpec | None:
+    """Return the nearest registered spec for ``exc`` (walking its MRO)."""
+    for cls in type(exc).__mro__:
+        spec = _ERROR_MAP.get(_fqname(cls))
+        if spec is not None:
+            return spec
+    return None
+
+
+def _extra_fields(exc: BaseException) -> dict[str, Any]:
+    """Pull structured custom fields off known exceptions (by attribute).
+
+    Read with ``getattr`` so this stays import-free. The ``ConfigDriftError``
+    round-trip in the spec (``plan_id`` + ``expected_config_hash`` +
+    ``actual_config_hash`` + ``recovery_hint``) is produced here.
+    """
+    extra: dict[str, Any] = {}
+    if _fqname(type(exc)) == "valved.cli.orchestrator.builder.ConfigDriftError":
+        extra["plan_id"] = getattr(exc, "plan_id", None)
+        extra["expected_config_hash"] = getattr(exc, "plan_hash", None)
+        extra["actual_config_hash"] = getattr(exc, "current_hash", None)
+        extra["recovery_hint"] = "Run `valved plan --refine` to regenerate against current config."
+    # ConfigError carries a dotted ``field`` and a remediation ``hint``.
+    field = getattr(exc, "field", None)
+    if field is not None:
+        extra.setdefault("field", field)
+    hint = getattr(exc, "hint", None)
+    if hint is not None:
+        extra.setdefault("recovery_hint", hint)
+    return extra
+
+
+def _detail_of(exc: BaseException) -> str | None:
+    """Prefer a structured ``.message`` (e.g. ``ConfigError``) over ``str(exc)``."""
+    message = getattr(exc, "message", None)
+    if isinstance(message, str) and message:
+        return message
+    text = str(exc)
+    return text or None
+
+
+class ProblemJsonExceptionHandler:
+    """Convert any exception to problem+json; unrecognized → 500 (stack logged)."""
+
+    async def __call__(self, request: Request, exc: Exception) -> Response:
+        instance = request.url.path
+        if isinstance(exc, ApiError):
+            return problem(
+                exc.status,
+                exc.type_slug,
+                exc.title,
+                detail=exc.detail,
+                instance=instance,
+                **exc.extra,
+            )
+        spec = _lookup_spec(exc)
+        if spec is None:
+            # Never leak internals: log the stack, return an opaque 500.
+            logger.exception("unhandled exception serving %s", instance)
+            return problem(
+                500,
+                "internal",
+                "Internal server error",
+                detail="An unexpected error occurred.",
+                instance=instance,
+            )
+        return problem(
+            spec.status,
+            spec.type_slug,
+            spec.title,
+            detail=_detail_of(exc),
+            instance=instance,
+            **_extra_fields(exc),
+        )
+
+
+async def _validation_handler(request: Request, exc: Exception) -> Response:
+    """FastAPI request-validation errors → 422 problem+json."""
+    errors = exc.errors() if isinstance(exc, RequestValidationError) else []
+    return problem(
+        422,
+        "validation",
+        "Request validation failed",
+        detail="One or more request parameters were invalid.",
+        instance=request.url.path,
+        errors=errors,
+    )
+
+
+async def _http_exception_handler(request: Request, exc: Exception) -> Response:
+    """Starlette ``HTTPException`` (e.g. 404 on an unknown route) → problem+json."""
+    status = exc.status_code if isinstance(exc, StarletteHTTPException) else 500
+    detail = exc.detail if isinstance(exc, StarletteHTTPException) else None
+    slug = {
+        401: "unauthorized",
+        403: "forbidden",
+        404: "not-found",
+        405: "method-not-allowed",
+    }.get(status, "http-error")
+    return problem(
+        status,
+        slug,
+        str(detail) if detail else "HTTP error",
+        instance=request.url.path,
+    )
+
+
+def install_error_handlers(app: FastAPI) -> None:
+    """Register the problem+json handlers on ``app`` (validation, HTTP, catch-all)."""
+    app.add_exception_handler(RequestValidationError, _validation_handler)
+    app.add_exception_handler(StarletteHTTPException, _http_exception_handler)
+    app.add_exception_handler(Exception, ProblemJsonExceptionHandler())
+
+
+__all__ = [
+    "PROBLEM_JSON_MEDIA_TYPE",
+    "ApiError",
+    "BadRequest",
+    "Conflict",
+    "ProblemJsonExceptionHandler",
+    "ResourceNotFound",
+    "Unauthorized",
+    "install_error_handlers",
+    "problem",
+]