monkeybrain-runtime 1.0.0__py3-none-any.whl

services/iot/routers/servers.py

@@ -0,0 +1,141 @@
+from fastapi import APIRouter, HTTPException, Depends, Query, status
+from motor.motor_asyncio import AsyncIOMotorDatabase
+from services.common.db import get_database
+from services.common.auth import require_permission
+from services.iot.models.servers import (
+    EdgeServerCreate,
+    EdgeServerUpdate,
+    EdgeServerResponse,
+    PaginatedEdgeServerResponse,
+)
+from services.iot.models.sensors import SensorResponse
+from services.iot.helpers import servers as crud
+from services.iot.helpers import sensors as sensor_crud
+
+router = APIRouter()
+
+
+# ── List ──────────────────────────────────────────────────────────────────────
+
+@router.get("/", response_model=PaginatedEdgeServerResponse)
+async def list_edge_servers(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=100),
+    db: AsyncIOMotorDatabase = Depends(get_database),
+):
+    servers, total = await crud.get_all(db, page=page, page_size=page_size)
+    return PaginatedEdgeServerResponse(total=total, page=page, page_size=page_size, results=servers)
+
+
+# ── Get by facility ───────────────────────────────────────────────────────────
+
+@router.get("/by-facility/{facility}", response_model=list[EdgeServerResponse])
+async def list_edge_servers_by_facility(
+    facility: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+):
+    return await crud.get_by_facility(db, facility)
+
+
+# ── Get by parent server ──────────────────────────────────────────────────────
+
+@router.get("/by-parent/{parent_server_id}", response_model=list[EdgeServerResponse])
+async def list_edge_servers_by_parent(
+    parent_server_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+):
+    return await crud.get_by_parent(db, parent_server_id)
+
+
+# ── Get one ───────────────────────────────────────────────────────────────────
+
+@router.get("/{server_id}", response_model=EdgeServerResponse)
+async def get_edge_server(
+    server_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+):
+    record = await crud.get_by_id(db, server_id)
+    if not record:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Edge server '{server_id}' not found",
+        )
+    return record
+
+
+# ── Create ────────────────────────────────────────────────────────────────────
+
+@router.post("/", response_model=EdgeServerResponse, status_code=status.HTTP_201_CREATED)
+async def create_edge_server(
+    data: EdgeServerCreate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+):
+    if await crud.get_by_id(db, data.server_id):
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"Edge server '{data.server_id}' already exists",
+        )
+    return await crud.create(db, data)
+
+
+# ── Update ────────────────────────────────────────────────────────────────────
+
+@router.patch("/{server_id}", response_model=EdgeServerResponse)
+async def update_edge_server(
+    server_id: str,
+    data: EdgeServerUpdate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+):
+    updated = await crud.update(db, server_id, data)
+    if not updated:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Edge server '{server_id}' not found",
+        )
+    return updated
+
+
+# ── Delete ────────────────────────────────────────────────────────────────────
+
+@router.delete("/{server_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_edge_server(
+    server_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+):
+    if not await crud.delete(db, server_id):
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Edge server '{server_id}' not found",
+        )
+
+
+# ── List sensors by server ────────────────────────────────────────────────────
+
+@router.get("/{server_id}/sensors", response_model=list[SensorResponse])
+async def list_sensors_by_edge_server(
+    server_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-sensors")),
+):
+    if not await crud.get_by_id(db, server_id):
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Edge server '{server_id}' not found",
+        )
+    return await sensor_crud.get_by_edge_server(db, server_id)
+
+
+# ── Server health ─────────────────────────────────────────────────────────────
+
+@router.get("/{server_id}/health", response_model=EdgeServerResponse)
+async def get_edge_server_health(
+    server_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+):
+    record = await crud.get_by_id(db, server_id)
+    if not record:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Edge server '{server_id}' not found",
+        )
+    return record

services/iot/routers/uwb_device.py

@@ -0,0 +1,148 @@
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from motor.motor_asyncio import AsyncIOMotorDatabase
+
+from services.iot.helpers import uwb_device as crud
+from services.iot.models.uwb_device import (
+    PaginatedUWBDeviceResponse,
+    UWBDeviceCreate,
+    UWBDeviceResponse,
+    UWBDeviceUpdate,
+)
+from services.common.auth import require_permission
+from services.common.db import get_database
+
+
+router = APIRouter()
+
+
+@router.get("/", response_model=PaginatedUWBDeviceResponse)
+async def list_uwb_devices(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=100),
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-devices")),
+):
+    records, total = await crud.get_all(db, page=page, page_size=page_size)
+    return PaginatedUWBDeviceResponse(total=total, page=page, page_size=page_size, results=records)
+
+
+@router.get("/by-mac/{mac_address}", response_model=UWBDeviceResponse)
+async def get_uwb_device_by_mac_address(
+    mac_address: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-devices")),
+):
+    record = await crud.get_by_mac_address(db, mac_address)
+    if not record:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"UWB device '{mac_address}' not found")
+    return record
+
+
+@router.get("/by-serial/{serial_number}", response_model=UWBDeviceResponse)
+async def get_uwb_device_by_serial_number(
+    serial_number: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-devices")),
+):
+    record = await crud.get_by_serial_number(db, serial_number)
+    if not record:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"UWB device serial '{serial_number}' not found")
+    return record
+
+
+@router.get("/by-anchor/{anchor_id}", response_model=UWBDeviceResponse)
+async def get_uwb_device_by_anchor_id(
+    anchor_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-devices")),
+):
+    record = await crud.get_by_anchor_id(db, anchor_id)
+    if not record:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"UWB anchor '{anchor_id}' not found")
+    return record
+
+
+@router.get("/by-active/{active}", response_model=list[UWBDeviceResponse])
+async def list_uwb_devices_by_active(
+    active: bool,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-devices")),
+):
+    return await crud.get_by_active(db, active)
+
+
+@router.get("/by-tag/{tag}", response_model=list[UWBDeviceResponse])
+async def list_uwb_devices_by_tag(
+    tag: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-devices")),
+):
+    return await crud.get_by_tag(db, tag)
+
+
+@router.get("/{device_id}", response_model=UWBDeviceResponse)
+async def get_uwb_device(
+    device_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-view-devices")),
+):
+    record = await crud.get_by_id(db, device_id)
+    if not record:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"UWB device '{device_id}' not found")
+    return record
+
+
+@router.post("/", response_model=UWBDeviceResponse, status_code=status.HTTP_201_CREATED)
+async def create_uwb_device(
+    data: UWBDeviceCreate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-create-devices")),
+):
+    if not data.anchor_config:
+        raise HTTPException(status.HTTP_422_UNPROCESSABLE_ENTITY, detail="anchor_config is required")
+    device_id = str(data.id)
+    if await crud.get_by_id(db, device_id):
+        raise HTTPException(status.HTTP_409_CONFLICT, detail=f"UWB device '{device_id}' already exists")
+    if data.mac_address and await crud.get_by_mac_address(db, data.mac_address):
+        raise HTTPException(status.HTTP_409_CONFLICT, detail=f"UWB device '{data.mac_address}' already exists")
+    if data.serial_number and await crud.get_by_serial_number(db, data.serial_number):
+        raise HTTPException(status.HTTP_409_CONFLICT, detail=f"UWB device serial '{data.serial_number}' already exists")
+    if await crud.get_by_anchor_id(db, data.anchor_config.anchor_id):
+        raise HTTPException(status.HTTP_409_CONFLICT, detail=f"UWB anchor '{data.anchor_config.anchor_id}' already exists")
+    return await crud.create(db, data)
+
+
+@router.patch("/{device_id}", response_model=UWBDeviceResponse)
+async def update_uwb_device(
+    device_id: str,
+    data: UWBDeviceUpdate,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-update-devices")),
+):
+    if data.mac_address:
+        existing = await crud.get_by_mac_address(db, data.mac_address)
+        if existing and existing.get("id") != device_id:
+            raise HTTPException(status.HTTP_409_CONFLICT, detail=f"UWB device '{data.mac_address}' already exists")
+    if data.serial_number:
+        existing = await crud.get_by_serial_number(db, data.serial_number)
+        if existing and existing.get("id") != device_id:
+            raise HTTPException(status.HTTP_409_CONFLICT, detail=f"UWB device serial '{data.serial_number}' already exists")
+    if data.anchor_config:
+        existing = await crud.get_by_anchor_id(db, data.anchor_config.anchor_id)
+        if existing and existing.get("id") != device_id:
+            raise HTTPException(status.HTTP_409_CONFLICT, detail=f"UWB anchor '{data.anchor_config.anchor_id}' already exists")
+
+    updated = await crud.update(db, device_id, data)
+    if not updated:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"UWB device '{device_id}' not found")
+    return updated
+
+
+@router.delete("/{device_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_uwb_device(
+    device_id: str,
+    db: AsyncIOMotorDatabase = Depends(get_database),
+    _: dict = Depends(require_permission("perm-delete-devices")),
+):
+    if not await crud.delete(db, device_id):
+        raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f"UWB device '{device_id}' not found")

services/module_control/__init__.py

@@ -0,0 +1 @@
+

services/module_control/helpers/__init__.py

@@ -0,0 +1 @@
+

services/module_control/helpers/integration_config.py

@@ -0,0 +1,243 @@
+from __future__ import annotations
+
+import json
+import secrets
+from typing import Any
+from uuid import uuid4
+
+import yaml
+from fastapi import HTTPException, Request, status
+from motor.motor_asyncio import AsyncIOMotorDatabase
+
+from services.auth.helpers import nats_store
+from services.common.data_transformation import RAW_INTEGRATION_SUBJECT
+from services.common.module_control import utc_now
+from services.common.ontology_registry import list_integration_adapters
+
+
+INTEGRATION_CONFIG_COLLECTION = "integration_connection_manifests"
+INTEGRATION_CONFIG_AUDIT_COLLECTION = "integration_connection_manifest_audit"
+ALLOWED_AUTH_MODES = {"oauth2", "basic", "api_key", "bearer", "none"}
+SECRET_KEYS = {"password", "secret", "token", "api_key", "client_secret", "access_token", "refresh_token"}
+
+
+def _adapter_ids() -> set[str]:
+    return {str(adapter["adapter_id"]) for adapter in list_integration_adapters()}
+
+
+def parse_manifest_bytes(content: bytes, filename: str = "manifest.yaml") -> dict[str, Any]:
+    text = content.decode("utf-8")
+    if filename.lower().endswith(".json"):
+        data = json.loads(text)
+    else:
+        data = yaml.safe_load(text)
+    if not isinstance(data, dict):
+        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail="Integration manifest must be a YAML/JSON object.")
+    return data
+
+
+def _normalize_auth(auth: Any) -> dict[str, Any]:
+    if isinstance(auth, str):
+        mode = auth.strip().lower()
+        if mode not in ALLOWED_AUTH_MODES:
+            raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=f"Unsupported auth mode '{auth}'.")
+        return {"mode": mode}
+    if isinstance(auth, dict):
+        mode = str(auth.get("mode") or auth.get("type") or "").strip().lower()
+        if mode not in ALLOWED_AUTH_MODES:
+            raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=f"Unsupported auth mode '{mode}'.")
+        return {**auth, "mode": mode}
+    raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail="auth must be a string mode or object with mode/type.")
+
+
+def _redact(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {
+            key: ("***redacted***" if str(key).lower() in SECRET_KEYS else _redact(item))
+            for key, item in value.items()
+        }
+    if isinstance(value, list):
+        return [_redact(item) for item in value]
+    return value
+
+
+def redact_manifest(document: dict[str, Any]) -> dict[str, Any]:
+    clean = dict(document)
+    clean.pop("_id", None)
+    if "auth" in clean:
+        clean["auth"] = _redact(clean["auth"])
+    return clean
+
+
+def _webhook_path_and_source(webhook_key: str, value: Any) -> tuple[str, str]:
+    if isinstance(value, dict):
+        path = str(value.get("path") or value.get("url") or "").strip()
+        source_object = str(value.get("source_object") or webhook_key).strip()
+    else:
+        path = str(value or "").strip()
+        source_object = webhook_key
+    if not path:
+        raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=f"Webhook '{webhook_key}' requires a path.")
+    return path, source_object
+
+
+def validate_integration_config_manifest(manifest: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    valid_adapters = _adapter_ids()
+    normalized: dict[str, dict[str, Any]] = {}
+    for adapter_id, config in manifest.items():
+        adapter_id = str(adapter_id)
+        if adapter_id not in valid_adapters:
+            raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=f"Unknown integration adapter '{adapter_id}'.")
+        if not isinstance(config, dict):
+            raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=f"Config for '{adapter_id}' must be an object.")
+
+        base_url = str(config.get("base_url") or "").strip()
+        if not base_url:
+            raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=f"Config for '{adapter_id}' requires base_url.")
+        webhooks = config.get("webhooks") or {}
+        field_mappings = config.get("field_mappings") or {}
+        if not isinstance(webhooks, dict):
+            raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=f"webhooks for '{adapter_id}' must be an object.")
+        if not isinstance(field_mappings, dict):
+            raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=f"field_mappings for '{adapter_id}' must be an object.")
+        normalized_webhooks = {}
+        for webhook_key, value in webhooks.items():
+            path, source_object = _webhook_path_and_source(str(webhook_key), value)
+            normalized_webhooks[str(webhook_key)] = {"path": path, "source_object": source_object}
+
+        normalized[adapter_id] = {
+            "adapter_id": adapter_id,
+            "base_url": base_url.rstrip("/"),
+            "auth": _normalize_auth(config.get("auth") or "none"),
+            "webhooks": normalized_webhooks,
+            "field_mappings": {str(key): value for key, value in field_mappings.items()},
+        }
+    return normalized
+
+
+async def upsert_integration_config_manifest(
+    db: AsyncIOMotorDatabase,
+    manifest: dict[str, Any],
+    *,
+    actor: str,
+    source: str = "api",
+) -> dict[str, Any]:
+    normalized = validate_integration_config_manifest(manifest)
+    now = utc_now()
+    updated = []
+    for adapter_id, config in normalized.items():
+        document = {
+            **config,
+            "config_id": adapter_id,
+            "source": source,
+            "updated_at": now,
+            "updated_by": actor,
+        }
+        existing = await db[INTEGRATION_CONFIG_COLLECTION].find_one({"config_id": adapter_id})
+        document["created_at"] = existing.get("created_at") if existing else now
+        await db[INTEGRATION_CONFIG_COLLECTION].replace_one({"config_id": adapter_id}, document, upsert=True)
+        await db[INTEGRATION_CONFIG_AUDIT_COLLECTION].insert_one(
+            {
+                "event_type": "integration-config-upserted",
+                "adapter_id": adapter_id,
+                "actor": actor,
+                "source": source,
+                "created_at": now,
+            }
+        )
+        updated.append(redact_manifest(document))
+    return {"updated_count": len(updated), "integrations": updated}
+
+
+async def list_integration_configs(db: AsyncIOMotorDatabase) -> list[dict[str, Any]]:
+    cursor = db[INTEGRATION_CONFIG_COLLECTION].find({})
+    return [redact_manifest(document) async for document in cursor]
+
+
+async def get_integration_config(db: AsyncIOMotorDatabase, adapter_id: str) -> dict[str, Any] | None:
+    document = await db[INTEGRATION_CONFIG_COLLECTION].find_one({"config_id": adapter_id})
+    return redact_manifest(document) if document else None
+
+
+def _configured_secret(config: dict[str, Any]) -> str:
+    auth = config.get("auth") if isinstance(config.get("auth"), dict) else {}
+    for key in ("webhook_secret", "api_key", "secret", "token"):
+        value = auth.get(key)
+        if value:
+            return str(value)
+    return ""
+
+
+def _provided_secret(request: Request) -> str:
+    authorization = request.headers.get("authorization") or ""
+    if authorization.lower().startswith("bearer "):
+        return authorization.split(" ", 1)[1].strip()
+    return (
+        request.headers.get("x-sentinel-integration-secret")
+        or request.headers.get("x-api-key")
+        or request.query_params.get("secret")
+        or ""
+    )
+
+
+def _enrich_payload_with_field_mappings(payload: dict[str, Any], field_mappings: dict[str, Any]) -> dict[str, Any]:
+    enriched = dict(payload)
+    for key, value in field_mappings.items():
+        if str(key).endswith("_field"):
+            continue
+        enriched.setdefault(str(key), value)
+    return enriched
+
+
+async def publish_inbound_integration_webhook(
+    db: AsyncIOMotorDatabase,
+    *,
+    adapter_id: str,
+    webhook_key: str,
+    payload: dict[str, Any],
+    request: Request,
+) -> dict[str, Any]:
+    config = await db[INTEGRATION_CONFIG_COLLECTION].find_one({"config_id": adapter_id})
+    if not config:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Integration config '{adapter_id}' not found.")
+    webhooks = config.get("webhooks") if isinstance(config.get("webhooks"), dict) else {}
+    webhook = webhooks.get(webhook_key)
+    if not webhook:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Webhook '{webhook_key}' is not registered for '{adapter_id}'.")
+
+    configured_secret = _configured_secret(config)
+    if configured_secret and not secrets.compare_digest(configured_secret, _provided_secret(request)):
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid integration webhook secret.")
+
+    source_object = str(webhook.get("source_object") or webhook_key)
+    enriched_payload = _enrich_payload_with_field_mappings(payload, config.get("field_mappings") or {})
+    event = {
+        "event_id": f"integration-webhook-{uuid4().hex[:12]}",
+        "event_type": "integration-raw",
+        "source": "integration-webhook",
+        "adapter_id": adapter_id,
+        "source_object": source_object,
+        "webhook_key": webhook_key,
+        "payload": enriched_payload,
+        "field_mappings": config.get("field_mappings") or {},
+        "received_at": utc_now(),
+    }
+    await nats_store.publish_event(nats_store._event_bytes(event), subject=RAW_INTEGRATION_SUBJECT)
+    await db[INTEGRATION_CONFIG_AUDIT_COLLECTION].insert_one(
+        {
+            "event_type": "integration-webhook-received",
+            "adapter_id": adapter_id,
+            "webhook_key": webhook_key,
+            "source_object": source_object,
+            "event_id": event["event_id"],
+            "created_at": utc_now(),
+        }
+    )
+    return {
+        "queued": True,
+        "subject": RAW_INTEGRATION_SUBJECT,
+        "event_id": event["event_id"],
+        "adapter_id": adapter_id,
+        "webhook_key": webhook_key,
+        "source_object": source_object,
+    }

services/module_control/helpers/security.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import secrets
+from datetime import timedelta, timezone
+from typing import Any
+from uuid import uuid4
+
+from fastapi import Header, HTTPException, status
+from motor.motor_asyncio import AsyncIOMotorDatabase
+
+from services.common.config import settings
+from services.common.module_control import hash_secret, utc_now
+
+
+CHALLENGE_COLLECTION = "module_control_activation_challenges"
+SESSION_COLLECTION = "module_control_activation_sessions"
+
+
+def _configured_password_hash() -> str:
+    if settings.MODULE_CONTROL_ACTIVATION_PASSWORD_HASH:
+        return settings.MODULE_CONTROL_ACTIVATION_PASSWORD_HASH
+    return hash_secret(settings.MODULE_CONTROL_DEV_PASSWORD)
+
+
+def _actor_id(actor: dict[str, Any] | None) -> str:
+    if not actor:
+        return "anonymous"
+    return str(actor.get("user_id") or actor.get("sub") or actor.get("email") or "unknown-user")
+
+
+def _expired(value) -> bool:
+    if value is None:
+        return True
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=timezone.utc)
+    return value < utc_now()
+
+
+async def create_activation_challenge(db: AsyncIOMotorDatabase, *, actor: dict[str, Any] | None = None) -> dict[str, Any]:
+    code = f"{secrets.randbelow(1_000_000):06d}"
+    expires_at = utc_now() + timedelta(seconds=max(settings.MODULE_CONTROL_OTP_TTL_SECONDS, 30))
+    challenge = {
+        "challenge_id": f"mc_otp_{uuid4().hex[:16]}",
+        "otp_hash": hash_secret(code),
+        "actor": _actor_id(actor),
+        "used": False,
+        "created_at": utc_now(),
+        "expires_at": expires_at,
+    }
+    await db[CHALLENGE_COLLECTION].insert_one(challenge)
+    response = {
+        "challenge_id": challenge["challenge_id"],
+        "expires_at": expires_at.isoformat(),
+        "delivery_mode": "development_echo" if settings.MODULE_CONTROL_ECHO_OTP else "external_delivery_required",
+    }
+    if settings.MODULE_CONTROL_ECHO_OTP:
+        response["otp_code"] = code
+    return response
+
+
+async def verify_activation(
+    db: AsyncIOMotorDatabase,
+    *,
+    challenge_id: str,
+    otp_code: str,
+    password: str,
+    actor: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    challenge = await db[CHALLENGE_COLLECTION].find_one({"challenge_id": challenge_id})
+    if not challenge or challenge.get("used") or _expired(challenge.get("expires_at")):
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Activation challenge is invalid or expired.")
+    if not secrets.compare_digest(str(challenge.get("otp_hash")), hash_secret(otp_code)):
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid activation OTP.")
+    if not secrets.compare_digest(_configured_password_hash(), hash_secret(password)):
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid activation password.")
+
+    raw_token = f"mc_session_{secrets.token_urlsafe(32)}"
+    expires_at = utc_now() + timedelta(seconds=max(settings.MODULE_CONTROL_SESSION_TTL_SECONDS, 60))
+    await db[CHALLENGE_COLLECTION].update_one({"challenge_id": challenge_id}, {"$set": {"used": True, "used_at": utc_now()}})
+    await db[SESSION_COLLECTION].insert_one(
+        {
+            "token_hash": hash_secret(raw_token),
+            "actor": _actor_id(actor),
+            "created_at": utc_now(),
+            "expires_at": expires_at,
+            "revoked": False,
+        }
+    )
+    return {"activation_token": raw_token, "expires_at": expires_at.isoformat()}
+
+
+async def require_activation_session(
+    x_module_control_session: str = Header(default="", alias="X-Module-Control-Session"),
+) -> str:
+    if not x_module_control_session:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Module control activation token required.")
+    return x_module_control_session
+
+
+async def validate_activation_session(db: AsyncIOMotorDatabase, token: str) -> dict[str, Any]:
+    session = await db[SESSION_COLLECTION].find_one({"token_hash": hash_secret(token), "revoked": False})
+    if not session or _expired(session.get("expires_at")):
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Module control activation token is invalid or expired.")
+    return session

services/module_control/main.py

@@ -0,0 +1,44 @@
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from services.common.db import close_db, connect_db
+from services.common.logging import configure_service_logging, install_request_logging
+from services.common.tracing import install_route_tracing
+from services.module_control.routers.module_control import router as module_control_router
+
+
+logger = configure_service_logging("module_control")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await connect_db()
+    yield
+    await close_db()
+
+
+app = FastAPI(
+    title="Module Control Service",
+    description="Control plane for module activation, endpoint access, customer limits, and integration activation.",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+install_request_logging(app, "module_control")
+install_route_tracing(app, "module_control")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(module_control_router, prefix="/api/v1/module-control", tags=["Module Control"])
+
+
+@app.get("/health", tags=["Health"])
+async def health_check():
+    return {"status": "healthy"}