topos-node 0.1.0__py3-none-any.whl

topos/api/uma_data.py

@@ -0,0 +1,311 @@
+# Topos UMA scoped data endpoints (US-3.8) and filter enforcement (US-3.6)
+# Sprint 05: scope resolution — return data only for tables allowed by RPT scopes.
+# See: control_plane/uma/uma_sprints/SPRINT_3_USER_SHARING.md, sprints_roles_scopes_stage_1/SPRINT_05_TOPOS_SCOPE_RESOLUTION.md
+
+from __future__ import annotations
+
+import hashlib
+
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+from fastapi import APIRouter, HTTPException, Query, Request, status
+
+from ..core.state import get_db_connection
+from ..uma_rpt import RPTValidationError, get_control_plane_http_base, introspect_for_resource
+from ..uma_filters import UMAFilterError, apply_filter_manifest, apply_filters, extract_field_transforms, extract_filter_manifest, get_limit_cap
+from ..scope_resolution import resolve_scopes_to_tables, may_access_table
+from ..uma_contact_enrichment import apply_message_contact_pipeline, strip_contact_runtime_filters
+from ..uma_resource_id import parse_dataset_id_from_uma_dataset_resource_id
+from ..engine.usage_observation import emit_usage_observation
+
+router = APIRouter(prefix="/v1/uma/resources", tags=["uma-data"])
+
+
+def _table_exists(conn, table_name: str) -> bool:
+    try:
+        cursor = conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name=?",
+            (table_name,),
+        )
+        return cursor.fetchone() is not None
+    except Exception:
+        return False
+
+
+def _sqlite_table_columns(conn, table: str) -> Set[str]:
+    try:
+        cur = conn.execute('PRAGMA table_info("{}")'.format(table.replace('"', "")))
+        return {str(row[1]) for row in cur.fetchall()}
+    except Exception:
+        return set()
+
+
+def _message_time_order_column(conn, table: str) -> str:
+    """Prefer event_at when present; else ts (Stage 6 seed uses ts-only)."""
+    cols = _sqlite_table_columns(conn, table)
+    if "event_at" in cols:
+        return "event_at"
+    if "ts" in cols:
+        return "ts"
+    return "message_id"
+
+
+def _get_messages_from_db(
+    conn,
+    dataset_id: Optional[str],
+    limit: int,
+    offset: int,
+    allowed_tables: Optional[Set[str]] = None,
+) -> List[Dict[str, Any]]:
+    """Query only the message-like tables permitted by the granted scopes."""
+
+    def _fetch_rows(query: str, params: Tuple[int, int]) -> List[Dict[str, Any]]:
+        cursor = conn.execute(query, params)
+        columns = [d[0] for d in cursor.description]
+        return [dict(zip(columns, row)) for row in cursor.fetchall()]
+
+    def _allowed_message_sources() -> List[str]:
+        if not allowed_tables:
+            candidates = []
+            if _table_exists(conn, "conversation_messages"):
+                candidates.append("conversation_messages")
+            elif _table_exists(conn, "messages"):
+                candidates.append("messages")
+            if _table_exists(conn, "ai_chat_messages"):
+                candidates.append("ai_chat_messages")
+            return candidates
+
+        candidates: List[str] = []
+        if "messages" in allowed_tables:
+            if _table_exists(conn, "conversation_messages"):
+                candidates.append("conversation_messages")
+            elif _table_exists(conn, "messages"):
+                candidates.append("messages")
+        if "conversation_messages" in allowed_tables and _table_exists(conn, "conversation_messages"):
+            if "conversation_messages" not in candidates:
+                candidates.append("conversation_messages")
+        if (
+            {"ai_chat", "ai_messages", "ai_chat_messages"} & set(allowed_tables)
+            and _table_exists(conn, "ai_chat_messages")
+        ):
+            candidates.append("ai_chat_messages")
+        return candidates
+
+    sources = _allowed_message_sources()
+    if not sources:
+        return []
+
+    # Keep single-table queries paginated in SQL; when multiple tables are allowed,
+    # fetch and merge in Python so limit/offset apply to the combined result set.
+    if sources == ["conversation_messages"]:
+        oc = _message_time_order_column(conn, "conversation_messages")
+        return _fetch_rows(
+            f"SELECT * FROM conversation_messages ORDER BY {oc} DESC LIMIT ? OFFSET ?",
+            (limit, offset),
+        )
+    if sources == ["messages"]:
+        return _fetch_rows(
+            "SELECT * FROM messages ORDER BY ts DESC LIMIT ? OFFSET ?",
+            (limit, offset),
+        )
+    if sources == ["ai_chat_messages"]:
+        oc = _message_time_order_column(conn, "ai_chat_messages")
+        return _fetch_rows(
+            f"SELECT * FROM ai_chat_messages ORDER BY {oc} DESC LIMIT ? OFFSET ?",
+            (limit, offset),
+        )
+
+    merged: List[Dict[str, Any]] = []
+    if "conversation_messages" in sources:
+        oc_cm = _message_time_order_column(conn, "conversation_messages")
+        merged.extend(
+            _fetch_rows(
+                f"SELECT * FROM conversation_messages ORDER BY {oc_cm} DESC LIMIT ? OFFSET ?",
+                (limit + offset, 0),
+            )
+        )
+    if "messages" in sources:
+        merged.extend(
+            _fetch_rows(
+                "SELECT * FROM messages ORDER BY ts DESC LIMIT ? OFFSET ?",
+                (limit + offset, 0),
+            )
+        )
+    if "ai_chat_messages" in sources:
+        oc_ac = _message_time_order_column(conn, "ai_chat_messages")
+        merged.extend(
+            _fetch_rows(
+                f"SELECT * FROM ai_chat_messages ORDER BY {oc_ac} DESC LIMIT ? OFFSET ?",
+                (limit + offset, 0),
+            )
+        )
+    merged.sort(key=lambda row: (row.get("event_at") or row.get("ts") or "", row.get("message_id") or ""), reverse=True)
+    return merged[offset:offset + limit]
+
+
+def _get_oplog_from_db(
+    conn,
+    dataset_id: Optional[str],
+    limit: int,
+    offset: int,
+) -> List[Dict[str, Any]]:
+    """Query oplog table if it exists; otherwise return empty list."""
+    if not _table_exists(conn, "oplog"):
+        return []
+    query = "SELECT * FROM oplog ORDER BY hlc_ts LIMIT ? OFFSET ?"
+    try:
+        cursor = conn.execute(query, (limit, offset))
+        columns = [d[0] for d in cursor.description]
+        return [dict(zip(columns, row)) for row in cursor.fetchall()]
+    except Exception:
+        return []
+
+
+def _extract_bearer(request: Request) -> Optional[str]:
+    auth = request.headers.get("authorization")
+    if not auth or not auth.startswith("Bearer "):
+        return None
+    return auth[7:].strip() or None
+
+
+async def require_uma_rpt(request: Request, resource_id: str) -> Dict[str, Any]:
+    """
+    Dependency: validate RPT for this resource_id via Control Plane introspect_for_resource.
+    Sets request.state.uma_introspection and returns it. Raises 401/403 if invalid.
+    """
+    base = get_control_plane_http_base()
+    if not base:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="UMA not configured: TOPOS_CONTROL_PLANE_URL required for RPT validation",
+        )
+    token = _extract_bearer(request)
+    if not token:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Missing or invalid Authorization: Bearer <RPT>",
+        )
+    try:
+        payload = await introspect_for_resource(resource_id=resource_id, token=token)
+    except RPTValidationError as e:
+        raise HTTPException(status_code=e.status_code, detail=str(e))
+    request.state.uma_introspection = payload
+    await emit_usage_observation(
+        action="uma.permission_ticket.validated",
+        quantity=1,
+        producer="api.uma_data",
+        canonical_action_identity={
+            "resource_id": resource_id,
+            "rpt_token_sha": hashlib.sha256(token.encode("utf-8")).hexdigest(),
+            "scope_count": len(payload.get("allowed_scopes") or []),
+        },
+        topos_id=parse_dataset_id_from_uma_dataset_resource_id(resource_id),
+        trust_class="observe_only",
+        metadata={"endpoint": "uma_introspect_for_resource"},
+    )
+    return payload
+
+
+@router.get("/{resource_id}/data/messages")
+async def get_uma_messages(
+    request: Request,
+    resource_id: str,
+    limit: int = Query(100, ge=1, le=1000),
+    offset: int = Query(0, ge=0),
+    dataset_id: Optional[str] = Query(None),
+):
+    """
+    Return messages for the UMA resource, filtered by the permission's filters.
+    Sprint 05: returns data only if RPT allows messages, ai_messages, or ai_chat scope.
+    """
+    resource_id = resource_id.strip()
+    payload = await require_uma_rpt(request, resource_id)
+    allowed_scopes = payload.get("allowed_scopes") or []
+    allowed_tables = resolve_scopes_to_tables(allowed_scopes)
+    if not allowed_tables:
+        return {"messages": [], "count": 0}
+    if not (
+        may_access_table(allowed_tables, "messages")
+        or may_access_table(allowed_tables, "conversation_messages")
+        or may_access_table(allowed_tables, "ai_chat_messages")
+        or may_access_table(allowed_tables, "ai_chat")
+        or may_access_table(allowed_tables, "ai_messages")
+    ):
+        return {"messages": [], "count": 0}
+    conn = get_db_connection()
+    if not conn:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Database not initialized",
+        )
+    filters = (request.state.uma_introspection or {}).get("filters")
+    manifest = extract_filter_manifest(filters if isinstance(filters, dict) else None)
+    ai_only = bool(
+        allowed_tables & {"ai_chat_messages", "ai_messages", "ai_chat"}
+    ) and not bool(allowed_tables & {"messages", "conversation_messages"})
+    conv_only = bool(allowed_tables & {"messages", "conversation_messages"}) and not bool(
+        allowed_tables & {"ai_chat_messages", "ai_messages", "ai_chat"}
+    )
+    logical_table = "ai_chat_messages" if ai_only else "conversation_messages" if conv_only else None
+    limited = get_limit_cap(limit, manifest, logical_table)
+    effective_dataset_id = (dataset_id or "").strip() or parse_dataset_id_from_uma_dataset_resource_id(
+        resource_id
+    )
+    items = _get_messages_from_db(conn, effective_dataset_id, limited, offset, allowed_tables=allowed_tables)
+    try:
+        items, uma_contact_sidecar = apply_message_contact_pipeline(
+            items,
+            conn=conn,
+            dataset_id=effective_dataset_id,
+            allowed_scopes=allowed_scopes,
+            manifest=manifest,
+            filters=filters if isinstance(filters, dict) else None,
+        )
+        manifest_for_generic = strip_contact_runtime_filters(manifest)
+        fts = extract_field_transforms(filters if isinstance(filters, dict) else None)
+        filtered = apply_filter_manifest(
+            list(items),
+            manifest_for_generic,
+            field_transforms=fts,
+            table_id=logical_table,
+        )
+    except UMAFilterError as exc:
+        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc)) from exc
+    return {
+        "messages": filtered,
+        "count": len(filtered),
+        "message_owner": uma_contact_sidecar.get("message_owner") or {},
+    }
+
+
+@router.get("/{resource_id}/data/oplog")
+async def get_uma_oplog(
+    request: Request,
+    resource_id: str,
+    limit: int = Query(100, ge=1, le=1000),
+    offset: int = Query(0, ge=0),
+    dataset_id: Optional[str] = Query(None),
+):
+    """
+    Return oplog entries for the UMA resource, filtered by the permission's filters.
+    Sprint 05: returns data only if RPT has at least one allowed scope (any read access).
+    """
+    resource_id = resource_id.strip()
+    payload = await require_uma_rpt(request, resource_id)
+    allowed_scopes = payload.get("allowed_scopes") or []
+    allowed_tables = resolve_scopes_to_tables(allowed_scopes)
+    if not allowed_tables:
+        return {"ops": [], "count": 0}
+    conn = get_db_connection()
+    if not conn:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Database not initialized",
+        )
+    items = _get_oplog_from_db(conn, dataset_id, limit, offset)
+    filters = (request.state.uma_introspection or {}).get("filters")
+    try:
+        filtered = apply_filters(items, filters)
+    except UMAFilterError as exc:
+        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=str(exc)) from exc
+    return {"ops": filtered, "count": len(filtered)}

topos/api/usage.py

@@ -0,0 +1,49 @@
+"""Engine-owned request counts: UMA + MCP. GET /api/request-counts (requires API key)."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Query
+
+from ..auth import require_api_key
+from ..core.handlers import handle_control_plane_request
+
+router = APIRouter(prefix="/api", tags=["usage"])
+
+
+@router.get("/request-counts")
+async def get_request_counts(
+    owner_user_id: str | None = Query(None, description="Resource owner (default: engine's linked user)"),
+    since_days: int = Query(90, ge=1, le=365),
+    _: None = Depends(require_api_key),  # noqa: B008
+) -> dict:
+    """
+    Return UMA and MCP request counts from the engine's DB.
+    Same data as get_request_counts message type (for direct frontend or CP proxy).
+    """
+    import uuid
+    msg = {
+        "id": str(uuid.uuid4()),
+        "type": "get_request_counts",
+        "payload": {"owner_user_id": owner_user_id or "", "since_days": since_days},
+    }
+    out = await handle_control_plane_request(msg)
+    if out.get("status") == "error":
+        return {
+            "uma": {
+                "total_read_requests": 0,
+                "total_write_requests": 0,
+                "by_app": [],
+                "by_requesting_user": [],
+                "access_attribution": {
+                    "window_days": since_days,
+                    "owner_self_reads": 0,
+                    "owner_self_writes": 0,
+                    "grantee_reads": 0,
+                    "grantee_writes": 0,
+                    "unknown_reads": 0,
+                    "unknown_writes": 0,
+                },
+            },
+            "mcp": {"by_source": [], "by_tool": [], "by_access_context": [], "total": 0},
+        }
+    return out.get("payload", {})

topos/api/user_identity.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import APIRouter, Body, Depends, Query
+
+from ..auth import require_api_key
+from ..core.state import get_db_connection
+from ..storage.user_identity import get_user_identity, put_user_identity
+
+router = APIRouter(tags=["user-identity"])
+
+
+@router.get("/v1/user-identity", dependencies=[Depends(require_api_key)])
+async def get_user_identity_endpoint(
+    dataset_id: Optional[str] = Query(default=None, description="Dataset scope for owner identity"),
+):
+    if not dataset_id:
+        return {"status": "error", "error": "dataset_id required"}
+    conn = get_db_connection()
+    if not conn:
+        return {"status": "error", "error": "Database not available"}
+    identity = get_user_identity(conn, dataset_id)
+    if identity is None:
+        return {"status": "ok", "dataset_id": dataset_id, "display_name": None}
+    return {"status": "ok", "dataset_id": dataset_id, **identity}
+
+
+@router.put("/v1/user-identity", dependencies=[Depends(require_api_key)])
+async def put_user_identity_endpoint(
+    dataset_id: Optional[str] = Query(default=None),
+    display_name: Optional[str] = Query(default=None),
+    body: Optional[dict] = Body(default=None),
+):
+    if not dataset_id and body:
+        dataset_id = body.get("dataset_id")
+    if not dataset_id:
+        return {"status": "error", "error": "dataset_id required"}
+    next_display_name = display_name if display_name is not None else (body.get("display_name") if body else None)
+    if isinstance(next_display_name, str):
+        next_display_name = next_display_name.strip() or None
+    conn = get_db_connection()
+    if not conn:
+        return {"status": "error", "error": "Database not available"}
+    put_user_identity(conn, dataset_id, display_name=next_display_name)
+    return {"status": "ok", "dataset_id": dataset_id, "display_name": next_display_name}

topos/app.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+import asyncio
+import importlib.util
+import logging
+import sys
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from .__version__ import __version__
+from .api import (
+    analytics as analytics_routes,
+    app_registry as app_registry_routes,
+    backup as backup_routes,
+    compute_remote as compute_remote_routes,
+    data_commit as data_commit_routes,
+    db as db_routes,
+    device as device_routes,
+    enrichment as enrichment_routes,
+    health as health_routes,
+    ingestion_compat as ingestion_compat_routes,
+    ingestion_api as ingestion_routes,
+    ingestion_sources as ingestion_sources_routes,
+    local_mcp as local_mcp_routes,
+    llm as llm_routes,
+    messenger_analytics as messenger_analytics_routes,
+    query_api as query_routes,
+    source_install as source_install_routes,
+    sources as sources_routes,
+    sync as sync_routes,
+    uma_data as uma_data_routes,
+    user_identity as user_identity_routes,
+    usage as usage_routes,
+    ui_config as ui_config_routes,
+    data_explorer_table_prefs as data_explorer_table_prefs_routes,
+    sanitization_ollama_config as sanitization_ollama_config_routes,
+    filter_lab as filter_lab_routes,
+)
+from .config.settings import settings
+from .core.logging import configure_logging
+from .core import state
+from .core.handlers import handle_control_plane_request
+from .control_plane_client import ControlPlaneClient
+from .engine.registration import build_engine_heartbeat_message, build_engine_register_message
+from .hosted_pool_lease import HostedPoolLeaseClient
+from .services.container import get_services
+from .sync import SyncClient
+from .sync_handlers import handle_sync_op
+
+configure_logging()
+logger = logging.getLogger("topos.app")
+
+app = FastAPI(
+    title="Topos",
+    description="Topos node: Topos Database (data plane) and Topos Engine (compute plane), typically co-deployed in this process.",
+    version=__version__,
+)
+
+logger.info("CORS allowed origins: %s", settings.allowed_origins)
+if settings.allowed_origin_regex:
+    logger.info("CORS allowed origin regex: %s", settings.allowed_origin_regex)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.allowed_origins,
+    allow_origin_regex=settings.allowed_origin_regex,
+    allow_credentials=False,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(health_routes.router)
+app.include_router(local_mcp_routes.router)
+app.include_router(llm_routes.router)
+app.include_router(db_routes.router)
+app.include_router(sync_routes.router)
+app.include_router(device_routes.router)
+app.include_router(backup_routes.router)
+app.include_router(analytics_routes.router)
+app.include_router(sources_routes.router)
+app.include_router(source_install_routes.router, prefix="/v1")
+app.include_router(app_registry_routes.router)
+app.include_router(ingestion_compat_routes.router)
+app.include_router(enrichment_routes.router, prefix="/v1")
+app.include_router(ingestion_routes.router, prefix="/v1")
+app.include_router(ingestion_sources_routes.router)
+app.include_router(query_routes.router, prefix="/v1")
+app.include_router(messenger_analytics_routes.router, prefix="/v1")
+app.include_router(uma_data_routes.router)
+app.include_router(usage_routes.router)
+app.include_router(ui_config_routes.router)
+app.include_router(data_explorer_table_prefs_routes.router)
+app.include_router(user_identity_routes.router)
+app.include_router(sanitization_ollama_config_routes.router)
+app.include_router(filter_lab_routes.router)
+app.include_router(compute_remote_routes.router)
+app.include_router(data_commit_routes.router)
+
+
+@app.on_event("startup")
+async def startup_event() -> None:
+    logger.info("Runtime Python executable: %s", sys.executable)
+    logger.info(
+        "Runtime deps available: transformers=%s torch=%s",
+        bool(importlib.util.find_spec("transformers")),
+        bool(importlib.util.find_spec("torch")),
+    )
+    # Tests may inject an in-memory connection before startup.
+    # Avoid initializing file-backed services in that case.
+    if state.db_conn is None:
+        _ = get_services()
+    # Run Stage 9 column renames at startup so request handlers never block the event loop on migration.
+    try:
+        from .core.state import db_conn, get_db_connection
+        from .storage.db.migrations.stage9_column_renames import run_stage9_migrations
+        # Respect pre-injected test connections; avoid replacing test DB handles during startup.
+        conn = db_conn if db_conn is not None else get_db_connection()
+        if conn:
+            result = run_stage9_migrations(conn)
+            if result.get("applied"):
+                logger.info("Stage 9 migrations applied at startup: %d renames", len(result["applied"]))
+    except Exception as e:
+        logger.debug("Stage 9 migrations at startup (non-fatal): %s", e)
+    if settings.topos_control_plane_url:
+        if settings.hosted_pool_lease_enabled:
+            try:
+                state.hosted_pool_lease_client = HostedPoolLeaseClient(
+                    control_plane_ws_url=settings.topos_control_plane_url
+                )
+                lease = await state.hosted_pool_lease_client.issue()
+                settings.topos_key = lease.connector_key
+                logger.info(
+                    "Hosted pool lease issued key=%s... ttl=%ss",
+                    lease.connector_key[:8],
+                    lease.lease_ttl_seconds,
+                )
+
+                async def _lease_renew_loop() -> None:
+                    while True:
+                        try:
+                            current = state.hosted_pool_lease_client.lease
+                            ttl_seconds = int(current.lease_ttl_seconds) if current else 300
+                            sleep_seconds = max(
+                                15,
+                                ttl_seconds - max(5, int(settings.hosted_pool_lease_renew_skew_seconds)),
+                            )
+                            await asyncio.sleep(sleep_seconds)
+                            renewed = await state.hosted_pool_lease_client.renew()
+                            logger.debug(
+                                "Hosted pool lease renewed key=%s... expires_at=%s",
+                                renewed.connector_key[:8],
+                                renewed.lease_expires_at.isoformat() if renewed.lease_expires_at else "unknown",
+                            )
+                        except asyncio.CancelledError:
+                            raise
+                        except Exception as lease_exc:  # noqa: BLE001
+                            logger.warning("Hosted pool lease renew failed: %s", lease_exc)
+                            await asyncio.sleep(10.0)
+
+                state.hosted_pool_lease_task = asyncio.create_task(_lease_renew_loop())
+            except Exception as lease_exc:  # noqa: BLE001
+                logger.error("Hosted pool lease issue failed: %s", lease_exc, exc_info=True)
+                raise
+        state.control_plane_client = ControlPlaneClient(
+            control_plane_url=settings.topos_control_plane_url,
+            api_key=str(settings.topos_key or ""),
+            handler=handle_control_plane_request,
+            verify_ssl=settings.control_plane_verify_ssl,
+        )
+        state.control_plane_client.start()
+        if settings.wait_for_control_plane_on_startup:
+            connected = await state.control_plane_client.wait_until_connected(
+                timeout_s=settings.connection_readiness_timeout_seconds
+            )
+            if not connected:
+                logger.warning(
+                    "Control plane client did not become ready within %.1fs",
+                    settings.connection_readiness_timeout_seconds,
+                )
+        async def _presence_loop() -> None:
+            # Registration/heartbeat are unsolicited presence messages.
+            # CP may ignore them in legacy mode; they are required for split-identity rollout scaffolding.
+            await asyncio.sleep(0.1)
+            while True:
+                if state.control_plane_client:
+                    await state.control_plane_client.send_message(build_engine_register_message())
+                    break
+                await asyncio.sleep(1.0)
+            while True:
+                await asyncio.sleep(30.0)
+                if state.control_plane_client:
+                    await state.control_plane_client.send_message(build_engine_heartbeat_message())
+
+        state.engine_presence_task = asyncio.create_task(_presence_loop())
+    if settings.enable_sync and settings.topos_user_id:
+        state.sync_client = SyncClient(
+            sync_url=settings.get_sync_url(),
+            api_key=str(settings.topos_key or ""),
+            user_id=settings.topos_user_id,
+            dataset_id=f"{settings.topos_user_id}:{settings.topos_default_dataset_id}",
+            on_op_received=handle_sync_op,
+            verify_ssl=settings.control_plane_verify_ssl,
+        )
+        state.sync_client.start()
+        if settings.wait_for_sync_on_startup:
+            connected = await state.sync_client.wait_until_connected(
+                timeout_s=settings.connection_readiness_timeout_seconds
+            )
+            if not connected:
+                logger.warning(
+                    "Sync client did not become ready within %.1fs",
+                    settings.connection_readiness_timeout_seconds,
+                )
+
+
+@app.on_event("shutdown")
+async def shutdown_event() -> None:
+    if state.engine_presence_task:
+        state.engine_presence_task.cancel()
+        try:
+            await state.engine_presence_task
+        except asyncio.CancelledError:
+            pass
+        state.engine_presence_task = None
+    if state.control_plane_client:
+        await state.control_plane_client.stop()
+    if state.hosted_pool_lease_task:
+        state.hosted_pool_lease_task.cancel()
+        try:
+            await state.hosted_pool_lease_task
+        except asyncio.CancelledError:
+            pass
+        state.hosted_pool_lease_task = None
+    if state.hosted_pool_lease_client:
+        await state.hosted_pool_lease_client.revoke()
+        state.hosted_pool_lease_client = None
+    if state.sync_client:
+        await state.sync_client.stop()

topos/auth.py

@@ -0,0 +1,17 @@
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+bearer_scheme = HTTPBearer(auto_error=False)
+
+
+def require_api_key(credentials: HTTPAuthorizationCredentials = Depends(bearer_scheme)) -> None:
+    """Validate incoming Bearer token against TOPOS_KEY."""
+    # Resolve settings at call-time so tests that reload env/modules
+    # see the latest TOPOS_KEY value.
+    from .config.settings import settings as runtime_settings
+
+    if credentials is None or credentials.scheme.lower() != "bearer":
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Missing authorization")
+
+    if credentials.credentials != str(runtime_settings.topos_key or ""):
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid authorization token")

topos/canonicalization/__init__.py

@@ -0,0 +1 @@
+"""Canonicalization layer for Topos."""