cassetta 0.30.0__py3-none-any.whl

cassetta/__init__.py

@@ -0,0 +1,16 @@
+"""Cassetta — a file exchange bus for AI agents.
+
+**Nothing is re-exported here, deliberately.** Importing any submodule executes this file first, so
+whatever it imports is imported by everyone — including the CLI client, which needs none of it. Two
+convenience aliases for names in `cassetta.defaults.factory` used to sit here, and they put FastAPI
+and the whole ASGI stack in front of `cassetta upload`: 57 packages installed where 16 will do.
+
+The public composition names live where ADR 002 puts them, in `cassetta.defaults.factory`, which is
+where every consumer already imports them from. Adding an alias back here would reintroduce the
+whole defect in exactly the same way, which is why the absence is a test rather than a habit —
+`tests/test_client_install.py`, and the 0.28.0 entry in `CHANGELOG.md` for what changed and why.
+"""
+
+__version__ = "0.30.0"
+
+__all__ = ["__version__"]

cassetta/app.py

@@ -0,0 +1,392 @@
+import asyncio
+import logging
+import time
+from collections.abc import AsyncIterator, Sequence
+from contextlib import asynccontextmanager
+from datetime import datetime
+
+from fastapi import FastAPI, Request, status
+from fastapi.responses import JSONResponse
+
+from cassetta import __version__
+from cassetta import gc as _gc
+from cassetta.auth.jwt_hot_reload import init_jwt_hot_reload, init_jwt_key_slots
+from cassetta.config import load_config
+from cassetta.defaults.default_limits import LimitsRejection
+from cassetta.defaults.factory import BackendConfig, build_core_defaults
+from cassetta.mcp_auth import MCPAuthMiddleware
+from cassetta.mcp_server import configure as configure_mcp
+from cassetta.mcp_server import create_mcp_server
+from cassetta.middleware import RequestIdMiddleware
+from cassetta.models import LimitsRejectionBody
+from cassetta.protocols.config import CoreConfig
+from cassetta.protocols.metrics import MetricsProvider
+from cassetta.protocols.storage import BundlePathConflictError, StorageBackend
+from cassetta.rate_limit.limiter import (
+    FanoutCapExceeded,
+    RateLimitExceeded,
+    _record_rate_limit_hit,
+    limiter,
+    recorded_rate_limit_route,
+)
+from cassetta.structured_log import configure_logging, safe_emit, struct_log
+
+logger = logging.getLogger("cassetta")
+
+_BUNDLE_NAMESPACES = ("store/", "inbox/")
+
+
+def _retry_after_seconds(exc: RateLimitExceeded) -> int:
+    """Best-effort window-in-seconds extraction from slowapi's exception.
+
+    slowapi attaches the parsed ``Limit`` (which carries the underlying
+    ``RateLimitItem``) on ``exc.limit``; its ``get_expiry`` reports the
+    bucket's window length. Falls back to 60s if the structure changes.
+    """
+    try:
+        limit_item = getattr(exc.limit, "limit", None)
+        if limit_item is not None:
+            return int(limit_item.get_expiry())
+    except Exception:
+        pass
+    return 60
+
+
+async def _lease_renewal_task(
+    backend: StorageBackend,
+    key: str,
+    lease_id: str,
+    interval: float = 30.0,
+) -> None:
+    """Periodically renew a lease to prevent expiry during long sweeps."""
+    while True:
+        await asyncio.sleep(interval)
+        renewed = await backend.renew_lease(key, lease_id)
+        if renewed:
+            struct_log(logger, logging.DEBUG, "ttl.lease_renewed", detail={"key": key})
+        else:
+            struct_log(logger, logging.WARNING, "ttl.lease_renewal_failed", detail={"key": key})
+            break
+
+
+async def _ttl_cleanup_loop(
+    backend: StorageBackend,
+    config: CoreConfig,
+    metrics: MetricsProvider | None = None,
+) -> None:
+    """Periodically remove expired bundles across store/ and inbox/ namespaces.
+
+    Uses lease-based coordination so that only one pod in a multi-pod
+    deployment runs the cleanup sweep at a time.
+    """
+    interval = 60
+    lease_key = "ttl-cleanup"
+    lease_ttl = 60
+
+    while True:
+        await asyncio.sleep(interval)
+        if config.default_ttl <= 0:
+            continue
+
+        lease_id = await backend.acquire_lease(lease_key, ttl_seconds=lease_ttl)
+        if lease_id is None:
+            struct_log(logger, logging.DEBUG, "ttl.lease_skipped", detail={"reason": "held by another pod"})
+            continue
+
+        struct_log(logger, logging.INFO, "ttl.sweep_started")
+
+        renewal = asyncio.create_task(_lease_renewal_task(backend, lease_key, lease_id))
+
+        deleted_count = 0
+        try:
+            now = time.time()
+            for prefix in _BUNDLE_NAMESPACES:
+                for ref in backend.list_bundles(prefix, include_orphans=False):
+                    try:
+                        meta = await backend.read_bundle_meta(ref.path)
+                    except FileNotFoundError:
+                        continue
+                    created_iso = str(meta.get("created_at", ""))
+                    try:
+                        created = datetime.fromisoformat(created_iso)
+                    except ValueError:
+                        continue
+                    if now - created.timestamp() > config.default_ttl:
+                        try:
+                            await backend.delete_bundle(ref.path)
+                            deleted_count += 1
+                            struct_log(
+                                logger, logging.INFO, "ttl.file_deleted", resource=f"bundle:{ref.path}", result="ok"
+                            )
+                        except FileNotFoundError:
+                            continue
+                        except Exception:
+                            struct_log(
+                                logger, logging.ERROR, "ttl.file_error", resource=f"bundle:{ref.path}", result="error"
+                            )
+        except Exception:
+            struct_log(logger, logging.ERROR, "ttl.sweep_error", result="error")
+        finally:
+            renewal.cancel()
+            try:
+                await renewal
+            except asyncio.CancelledError:
+                pass
+            if metrics is not None and deleted_count > 0:
+                safe_emit(
+                    metric_name="cassetta.ttl.cleanup.files_deleted",
+                    metric_value=deleted_count,
+                    metrics=metrics,
+                )
+
+            struct_log(logger, logging.INFO, "ttl.cleanup", result="ok", detail={"files_deleted": deleted_count})
+
+            released = await backend.release_lease(lease_key, lease_id)
+            if released:
+                struct_log(logger, logging.INFO, "ttl.lease_released")
+            else:
+                struct_log(logger, logging.WARNING, "ttl.lease_release_failed")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    """Application lifespan: initialise backends, run MCP + TTL + GC loops."""
+    config: CoreConfig = app.state.config
+    backends: BackendConfig = app.state.backends
+
+    struct_log(
+        logger,
+        logging.INFO,
+        "config_loaded",
+        detail={
+            "primary_key_source": config.jwt_primary_key_source,
+            "secondary_key": config.jwt_secondary_key is not None,
+            "public_base_url": config.public_base_url,
+            "dev_mode": app.state.dev_mode,
+            "rate_limit_broadcast": config.rate_limit_broadcast,
+            "broadcast_max_targets": config.broadcast_max_targets,
+            "jwt_key_overlap_ttl": config.jwt_key_overlap_ttl,
+        },
+    )
+    # JWT primary-key hot-reload + boot-time validation. Order
+    # matters — the validation warning must surface immediately after
+    # ``config_loaded`` so dashboards see them in operator-natural order.
+    init_jwt_hot_reload(app)
+    if app.state.dev_mode:
+        struct_log(logger, logging.WARNING, "dev_mode_enabled")
+
+    backend = backends.backend
+    if hasattr(backend, "initialize"):
+        await backend.initialize()
+
+    key_store = backends.key_store
+    if hasattr(key_store, "initialize"):
+        await key_store.initialize()
+
+    # claim_storage_backend emission via safe_emit so the record parses as
+    # JSON under CASSETTA_LOG_FORMAT=json. This is the single canonical
+    # emission — a duplicate on the downstream side was removed.
+    safe_emit(
+        logger,
+        logging.INFO,
+        "claim_storage_backend",
+        detail={"kind": backends.claim_store.kind},
+    )
+
+    configure_mcp(config, backends, jwt_keys=app.state.jwt_keys)
+
+    mcp_server = app.state.mcp_server
+    async with mcp_server.session_manager.run():
+        cleanup_task: asyncio.Task[None] | None = None
+        if config.default_ttl > 0:
+            cleanup_task = asyncio.create_task(
+                _ttl_cleanup_loop(
+                    backend,
+                    config,
+                    metrics=backends.metrics_provider,
+                )
+            )
+
+        gc_task: asyncio.Task[None] = _gc.schedule_reaper(
+            app,
+            backend,
+            backends.limits_policy,
+        )
+
+        yield
+
+        gc_task.cancel()
+        try:
+            await gc_task
+        except asyncio.CancelledError:
+            pass
+        if cleanup_task is not None:
+            cleanup_task.cancel()
+            try:
+                await cleanup_task
+            except asyncio.CancelledError:
+                pass
+        if hasattr(backend, "close"):
+            await backend.close()
+
+
+def create_app(
+    config: CoreConfig | None = None,
+    *,
+    backends: BackendConfig | None = None,
+    extra_log_trees: Sequence[str] = (),
+) -> FastAPI:
+    """Create and configure the FastAPI application.
+
+    Args:
+        config: application configuration — anything satisfying
+            :class:`~cassetta.protocols.config.CoreConfig`. Loaded from the
+            environment as an :class:`~cassetta.config.AppConfig` when omitted;
+            an application embedding this server passes its own settings object
+            here.
+        backends: ready-made backend implementations; the core defaults are
+            built from ``config`` when omitted.
+        extra_log_trees: names of additional logger trees to route through the
+            configured handler, forwarded verbatim to
+            :func:`cassetta.structured_log.configure_logging`. An application
+            embedding this server passes its own tree here so one process
+            produces one log stream. Empty by default.
+    """
+    if config is None:
+        config = load_config()
+
+    configure_logging(config.log_format, extra_log_trees)
+
+    if backends is None:
+        backends = build_core_defaults(config)
+
+    app = FastAPI(title="Cassetta", version=__version__, lifespan=lifespan)
+    app.state.config = config
+    app.state.backends = backends
+    app.state.dev_mode = config.dev_mode
+    app.state.setup_token = config.setup_token
+    # Shared limiter instance + decorator-friendly state hook.
+    # slowapi looks for ``app.state.limiter`` when the decorator runs.
+    app.state.limiter = limiter
+    # Populate the runtime JWT key holder so verify-call
+    # sites work even when the test client bypasses lifespan.
+    init_jwt_key_slots(app)
+
+    @app.exception_handler(BundlePathConflictError)
+    async def _bundle_conflict_handler(_request: Request, exc: BundlePathConflictError) -> JSONResponse:
+        return JSONResponse(
+            status_code=status.HTTP_409_CONFLICT,
+            content={
+                "error": "bundle_path_conflict",
+                "conflicting_path": exc.conflicting_path,
+                "kind": exc.kind,
+            },
+        )
+
+    @app.exception_handler(LimitsRejection)
+    async def _limits_rejection_handler(
+        _request: Request,
+        exc: LimitsRejection,
+    ) -> JSONResponse:
+        if exc.error == "cap_exceeded":
+            status_code = status.HTTP_413_CONTENT_TOO_LARGE
+        else:
+            status_code = status.HTTP_422_UNPROCESSABLE_CONTENT
+        return JSONResponse(
+            status_code=status_code,
+            content=LimitsRejectionBody(
+                error=exc.error,
+                constraint=exc.constraint,
+                limit=exc.limit,
+                observed=exc.observed,
+            ).model_dump(),
+        )
+
+    @app.exception_handler(RateLimitExceeded)
+    async def _rate_limit_handler(
+        request: Request,
+        exc: RateLimitExceeded,
+    ) -> JSONResponse:
+        # slowapi exposes the parsed Limit on `exc.limit`; we only need
+        # the per-bucket window in seconds for Retry-After.
+        retry_after = _retry_after_seconds(exc)
+        # The caller names its own route when it drives the limiter, so this
+        # handler attributes a route it does not serve without knowing the
+        # path. A rejection raised by a decorator never passes through that
+        # helper and records nothing; `broadcast` is what it counted before.
+        _record_rate_limit_hit(request, route=recorded_rate_limit_route(request), reason="rate")
+        return JSONResponse(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            content={"error": "rate_limit", "retry_after": retry_after},
+            headers={"Retry-After": str(retry_after)},
+        )
+
+    @app.exception_handler(FanoutCapExceeded)
+    async def _fanout_cap_handler(
+        request: Request,
+        exc: FanoutCapExceeded,
+    ) -> JSONResponse:
+        _record_rate_limit_hit(request, route="broadcast", reason="fanout_cap")
+        return JSONResponse(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            content={
+                "error": "rate_limit",
+                "reason": "fanout_cap",
+                "max_targets": exc.max_targets,
+            },
+            headers={"Retry-After": "0"},
+        )
+
+    from cassetta.routes.agents import router as agents_router
+    from cassetta.routes.capabilities import router as capabilities_router
+    from cassetta.routes.download import (
+        DownloadError,
+        download_error_handler,
+    )
+    from cassetta.routes.download import (
+        router as download_router,
+    )
+    from cassetta.routes.files import router as files_router
+    from cassetta.routes.inbox import router as inbox_router
+    from cassetta.routes.keys import router as keys_router
+    from cassetta.routes.upload import router as upload_router
+    from cassetta.routes.uploads import router as uploads_router
+
+    # Registered through the decorator, like the four handlers above it: it types
+    # as an identity over the callable, where `add_exception_handler` declares its
+    # handler as taking a bare `Exception` and rejects a narrower annotation.
+    app.exception_handler(DownloadError)(download_error_handler)
+
+    app.include_router(agents_router)
+    app.include_router(capabilities_router)
+    app.include_router(download_router)
+    app.include_router(files_router)
+    app.include_router(inbox_router)
+    app.include_router(keys_router)
+    app.include_router(upload_router)
+    app.include_router(uploads_router)
+
+    mcp_server = create_mcp_server(allowed_hosts=config.mcp_allowed_hosts)
+    app.state.mcp_server = mcp_server
+    mcp_asgi = mcp_server.streamable_http_app()
+    app.mount("/mcp", MCPAuthMiddleware(mcp_asgi, fastapi_app=app))
+
+    @app.get("/health")
+    async def health() -> dict[str, str | bool]:
+        key_store = app.state.backends.key_store
+        if hasattr(key_store, "is_healthy") and not key_store.is_healthy():
+            from fastapi.responses import JSONResponse
+
+            return JSONResponse(  # type: ignore[return-value]
+                status_code=503,
+                content={
+                    "status": "unhealthy",
+                    "reason": "key_store_unreachable",
+                    "dev_mode": app.state.dev_mode,
+                },
+            )
+        return {"status": "ok", "dev_mode": app.state.dev_mode}
+
+    app.add_middleware(RequestIdMiddleware)
+
+    return app

cassetta/auth/__init__.py

@@ -0,0 +1,52 @@
+"""Auth package -- public surface for FastAPI deps and key DTOs."""
+
+from typing import TYPE_CHECKING, Any
+
+from cassetta.auth.dependencies import (
+    get_current_identity,
+    get_current_key,
+    get_key_store,
+    http_bearer,
+    require_setup_token,
+)
+from cassetta.auth.models import KEY_PREFIX, KEY_PREFIX_LEN, KeyInfo, KeyRecord
+
+if TYPE_CHECKING:
+    from cassetta.backends.filesystem.keystore import (
+        FileKeyStore,
+    )
+
+    KeyStore = FileKeyStore
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy re-export to avoid the ``auth`` ↔ ``keystore`` circular.
+
+    ``cassetta.backends.filesystem.keystore`` imports ``KeyInfo`` /
+    ``KeyRecord`` from ``cassetta.auth.models``. Importing the submodule
+    initialises the ``cassetta.auth`` package, so if this ``__init__.py``
+    eagerly pulled ``FileKeyStore`` back from the Layer 3 module we would
+    re-enter a partially-loaded ``keystore`` module — fatal. Deferring
+    via PEP 562 sidesteps the cycle while preserving
+    ``from cassetta.auth import FileKeyStore`` / ``KeyStore``.
+    """
+    if name in {"FileKeyStore", "KeyStore"}:
+        from cassetta.backends.filesystem import keystore as _ks
+
+        return _ks.FileKeyStore
+    raise AttributeError(f"module 'cassetta.auth' has no attribute {name!r}")
+
+
+__all__ = [
+    "KEY_PREFIX",
+    "KEY_PREFIX_LEN",
+    "FileKeyStore",
+    "KeyInfo",
+    "KeyRecord",
+    "KeyStore",
+    "get_current_identity",
+    "get_current_key",
+    "get_key_store",
+    "http_bearer",
+    "require_setup_token",
+]

cassetta/auth/dependencies.py

@@ -0,0 +1,146 @@
+import logging
+from typing import TYPE_CHECKING, Annotated, cast
+
+from fastapi import Depends, HTTPException, Request, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+from cassetta.auth.models import KeyInfo
+from cassetta.auth.observability import Reason, emit_auth_failure
+
+if TYPE_CHECKING:
+    from cassetta.protocols.identity import Identity, IdentityProvider
+    from cassetta.protocols.keystore import KeyStoreProtocol
+
+http_bearer = HTTPBearer(auto_error=False)
+logger = logging.getLogger("cassetta.auth")
+
+
+def get_key_store(request: Request) -> "KeyStoreProtocol":
+    """FastAPI dependency to get the KeyStore instance."""
+    key_store = request.app.state.backends.key_store
+    return cast("KeyStoreProtocol", key_store)
+
+
+async def get_current_identity(
+    credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(http_bearer)],
+    request: Request,
+) -> "Identity":
+    """FastAPI dependency for unified authentication.
+
+    Accepts either an ``X-Setup-Token`` header or an ``Authorization: Bearer``
+    header and always produces an :class:`Identity`. Precedence when both
+    are present: setup-token wins (protects admin bootstrap from accidental
+    bearer-key shadowing).
+
+    - Dev mode -> dev identity with ``extra["dev"]=True``
+    - Valid setup token -> operator identity with ``extra["operator"]=True``
+    - Valid bearer key -> identity resolved via the pluggable IdentityProvider
+    - Neither / invalid -> 401
+    """
+    from cassetta.protocols.identity import Identity
+
+    dev_mode: bool = request.app.state.dev_mode
+    if dev_mode:
+        identity = Identity(label="dev", extra={"dev": True})
+        request.state.identity = identity
+        return identity
+
+    # Setup-token path wins if both are supplied.
+    x_setup_token = request.headers.get("X-Setup-Token")
+    setup_token: str = request.app.state.setup_token
+    if x_setup_token is not None and x_setup_token == setup_token:
+        identity = Identity(label="operator", extra={"operator": True})
+        request.state.identity = identity
+        return identity
+
+    # Bearer-token path.
+    if credentials is not None:
+        key_store = get_key_store(request)
+        info = await key_store.validate(credentials.credentials)
+        if info is not None:
+            identity_provider: IdentityProvider = request.app.state.backends.identity_provider
+            identity = await identity_provider.resolve(info)
+            # Attach the raw key info so callers that need it (e.g. keys.py)
+            # can still reach it without a second lookup.
+            request.state.key_info = info
+            request.state.identity = identity
+            return identity
+
+    # No valid credentials present — emit a single auth.failure event.
+    # Setup-token wins on reason precedence (matches the success-path
+    # precedence: setup-token is checked before bearer).
+    reason: Reason
+    identity_hint: str | None
+    if x_setup_token is not None:
+        reason = "invalid_setup_token"
+        identity_hint = None
+    elif credentials is not None:
+        reason = "invalid_key"
+        identity_hint = credentials.credentials[:12] if credentials.credentials else None
+    else:
+        reason = "missing_bearer"
+        identity_hint = None
+    emit_auth_failure(
+        metrics=request.app.state.backends.metrics_provider,
+        source="rest",
+        reason=reason,
+        identity_hint=identity_hint,
+    )
+    raise HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Missing or invalid authentication credentials",
+    )
+
+
+async def get_current_key(
+    credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(http_bearer)],
+    request: Request,
+) -> KeyInfo | None:
+    """Backwards-compat wrapper.
+
+    Thin shim over :func:`get_current_identity` that returns the validated
+    :class:`KeyInfo` when the caller authenticated via bearer token, and
+    ``None`` in dev mode. Returns None when the caller is an operator
+    (setup-token path) -- existing key-management routes do not need KeyInfo
+    in that case.
+
+    New code SHOULD depend on :func:`get_current_identity` directly.
+    """
+    from cassetta.protocols.identity import Identity
+
+    dev_mode: bool = request.app.state.dev_mode
+    if dev_mode:
+        request.state.identity = Identity(label="dev", extra={"dev": True})
+        return None
+
+    identity = await get_current_identity(credentials, request)
+    if identity.extra.get("operator"):
+        return None
+    return getattr(request.state, "key_info", None)
+
+
+def require_setup_token(request: Request, x_setup_token: str | None = None) -> None:
+    """Deprecated: use :func:`get_current_identity` + policy.check instead.
+
+    Retained for backwards compatibility with callers that have not yet
+    migrated. Does NOT run in dev mode. New admin routes must NOT depend
+    on this -- they depend on :func:`get_current_identity` and call
+    :meth:`AccessPolicy.check`.
+    """
+    dev_mode: bool = request.app.state.dev_mode
+    if dev_mode:
+        return
+
+    setup_token: str = request.app.state.setup_token
+    token = x_setup_token or request.headers.get("X-Setup-Token")
+    if token != setup_token:
+        emit_auth_failure(
+            metrics=request.app.state.backends.metrics_provider,
+            source="rest",
+            reason="invalid_setup_token",
+            identity_hint=None,
+        )
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Invalid setup token",
+        )