voodoo-framework 2.5.2__tar.gz → 2.6.0__tar.gz

{voodoo_framework-2.5.2/src/voodoo_framework.egg-info → voodoo_framework-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voodoo-framework
-Version: 2.5.2
+Version: 2.6.0
 Summary: The programmable runtime for adaptive applications and operational systems — web, APIs, agents, workers, human workflows, distributed systems, and physical systems in one runtime.
 Author-email: Helder Perez <contact@helderperez.com>
 Maintainer-email: Helder Perez <contact@helderperez.com>
@@ -59,6 +59,8 @@ Requires-Dist: boto3>=1.34; extra == "s3"
 Requires-Dist: botocore>=1.34; extra == "s3"
 Provides-Extra: redis
 Requires-Dist: redis>=5.0; extra == "redis"
+Provides-Extra: edge
+Requires-Dist: paho-mqtt>=2.0; extra == "edge"
 Provides-Extra: otel
 Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
 Requires-Dist: opentelemetry-sdk>=1.20; extra == "otel"
@@ -232,6 +234,7 @@ if __name__ == "__main__":
 | **Observability everywhere** | Correlation IDs and telemetry built into every subsystem |
 | **Unified runtime engine** | Every operation (HTTP, Agent, Tool, MCP, Worker, Human, Event) produces an `Execution` record with full traceability |
 | **Human-in-the-Loop** | `ask_human()` + `approve()`/`deny()` — humans as compute participants, not afterthoughts |
+| **Physical devices as Entities** | `voodoo-edge/v1` protocol + Device Gateway over HTTP/MQTT — ESP32s, robots, and sensors join the same execution model as agents and workers |
 | **Adaptive execution** | Planner resolves capabilities to compute participants; supervisor steers with retry, fallback, budget control |
 | **Durable by default** | Tasks, executions, schedules, and events survive process restarts — backed by SQLite out of the box |
 | **Zero-config runtime** | `voodoo create` → `voodoo dev` → working app. No build step. Add `voodoo.toml` when you need configuration |
@@ -284,6 +287,7 @@ and [`ARCHITECTURE.md`](ARCHITECTURE.md) for the implementation model.
 - **Auth** — JWT tokens, API keys, session cookies, RBAC route guards
 - **Workers** — `@task` decorator with retries, timeout, and telemetry spans
 - **Voodoo Mesh** — Realtime event bus with local + remote boundaries
+- **Edge Devices** — Device Gateway (`voodoo-edge/v1` over HTTP & MQTT): devices emit events, trigger Executions, receive Effects — see [`docs/edge/overview.md`](docs/edge/overview.md)
 
 ### Runtime & Infrastructure
 - **Runtime Engine** — Unified `ExecutionEngine` producing `Execution` records for every operation
@@ -437,6 +441,14 @@ voodoo auth secret-key
 - [Mesh](docs/mesh.md)
 - [Workers](docs/workers.md)
 
+### Edge Devices
+- [Edge Overview](docs/edge/overview.md)
+- [Edge Protocol v1](docs/edge/protocol.md)
+- [HTTP Transport](docs/edge/http.md)
+- [MQTT Transport](docs/edge/mqtt.md)
+- [Device Security](docs/edge/security.md)
+- [Reliability](docs/edge/reliability.md)
+
 ### Runtime & Operations
 - [Runtime Engine](docs/runtime.md)
 - [Planner & Adaptive Runtime](docs/adaptive.md)

{voodoo_framework-2.5.2 → voodoo_framework-2.6.0}/README.md

@@ -165,6 +165,7 @@ if __name__ == "__main__":
 | **Observability everywhere** | Correlation IDs and telemetry built into every subsystem |
 | **Unified runtime engine** | Every operation (HTTP, Agent, Tool, MCP, Worker, Human, Event) produces an `Execution` record with full traceability |
 | **Human-in-the-Loop** | `ask_human()` + `approve()`/`deny()` — humans as compute participants, not afterthoughts |
+| **Physical devices as Entities** | `voodoo-edge/v1` protocol + Device Gateway over HTTP/MQTT — ESP32s, robots, and sensors join the same execution model as agents and workers |
 | **Adaptive execution** | Planner resolves capabilities to compute participants; supervisor steers with retry, fallback, budget control |
 | **Durable by default** | Tasks, executions, schedules, and events survive process restarts — backed by SQLite out of the box |
 | **Zero-config runtime** | `voodoo create` → `voodoo dev` → working app. No build step. Add `voodoo.toml` when you need configuration |
@@ -217,6 +218,7 @@ and [`ARCHITECTURE.md`](ARCHITECTURE.md) for the implementation model.
 - **Auth** — JWT tokens, API keys, session cookies, RBAC route guards
 - **Workers** — `@task` decorator with retries, timeout, and telemetry spans
 - **Voodoo Mesh** — Realtime event bus with local + remote boundaries
+- **Edge Devices** — Device Gateway (`voodoo-edge/v1` over HTTP & MQTT): devices emit events, trigger Executions, receive Effects — see [`docs/edge/overview.md`](docs/edge/overview.md)
 
 ### Runtime & Infrastructure
 - **Runtime Engine** — Unified `ExecutionEngine` producing `Execution` records for every operation
@@ -370,6 +372,14 @@ voodoo auth secret-key
 - [Mesh](docs/mesh.md)
 - [Workers](docs/workers.md)
 
+### Edge Devices
+- [Edge Overview](docs/edge/overview.md)
+- [Edge Protocol v1](docs/edge/protocol.md)
+- [HTTP Transport](docs/edge/http.md)
+- [MQTT Transport](docs/edge/mqtt.md)
+- [Device Security](docs/edge/security.md)
+- [Reliability](docs/edge/reliability.md)
+
 ### Runtime & Operations
 - [Runtime Engine](docs/runtime.md)
 - [Planner & Adaptive Runtime](docs/adaptive.md)

{voodoo_framework-2.5.2 → voodoo_framework-2.6.0}/pyproject.toml

@@ -93,6 +93,9 @@ s3 = [
 redis = [
     "redis>=5.0",
 ]
+edge = [
+    "paho-mqtt>=2.0",
+]
 otel = [
     "opentelemetry-api>=1.20",
     "opentelemetry-sdk>=1.20",

{voodoo_framework-2.5.2 → voodoo_framework-2.6.0}/src/voodoo/__init__.py

@@ -102,7 +102,7 @@ from .ui.styles import (
 from .ui.styles.theme import Theme, ThemeColors, create_theme
 from .workers import task
 
-__version__ = "2.5.2"
+__version__ = "2.6.0"
 
 __all__ = [
     # Core runtime

{voodoo_framework-2.5.2 → voodoo_framework-2.6.0}/src/voodoo/config.py

@@ -255,6 +255,37 @@ class AIConfig(BaseModel):
     aliases: dict[str, str] = Field(default_factory=dict)
 
 
+class EdgeConfig(BaseModel):
+    """Edge device gateway configuration (``edge:`` block) — Sprint 23.
+
+    Edge is disabled by default: users who never enable it pay zero
+    overhead and need no MQTT broker, device tables, or gateway
+    (EDGE §68 — backwards compatibility).
+    """
+
+    enabled: bool = False
+    http_enabled: bool = True
+    mqtt_enabled: bool = False
+    # Optional separate listener for the edge gateway; when empty the
+    # edge routes mount onto the main app instead.
+    http_host: str = ""
+    http_port: int = 0
+    # MQTT broker connection (EDGE §35, §38).
+    mqtt_broker_url: str = ""
+    mqtt_port: int = 1883
+    mqtt_tls: bool = False
+    mqtt_username: str = ""
+    mqtt_password: str = ""
+    mqtt_client_id: str = "voodoo-runtime"
+    mqtt_keepalive: int = 60
+    mqtt_qos: int = 1
+    # Resource limits (EDGE §76).
+    max_message_size: int = 262144  # 256 KiB
+    max_state_size: int = 65536  # 64 KiB
+    max_pending_effects: int = 1000
+    heartbeat_interval: int = 30
+
+
 class VoodooConfig(BaseModel):
     """Core configuration for the Voodoo framework."""
 
@@ -276,6 +307,7 @@ class VoodooConfig(BaseModel):
     cache: CacheConfig = Field(default_factory=CacheConfig)
     models: ModelsConfig = Field(default_factory=ModelsConfig)
     ai: AIConfig = Field(default_factory=AIConfig)
+    edge: EdgeConfig = Field(default_factory=EdgeConfig)
 
     seo: SEOConfig = Field(default_factory=SEOConfig)
     auth: AuthConfig = Field(default_factory=AuthConfig)
@@ -458,6 +490,54 @@ def _build_ai_config(file_data: dict[str, Any]) -> AIConfig:
     )
 
 
+def _build_edge_config(file_data: dict[str, Any]) -> EdgeConfig:
+    """Merge file ``edge:`` block with ``VOODOO_EDGE_*``/``MQTT_*`` env vars."""
+    edge_data = file_data.get("edge") or {}
+    if not isinstance(edge_data, dict):
+        edge_data = {"enabled": bool(edge_data)}
+
+    def _flag(key: str, env: str) -> bool | None:
+        if key in edge_data:
+            return bool(edge_data[key])
+        val = _env_flag(env)
+        return val
+
+    enabled = _flag("enabled", "VOODOO_EDGE_ENABLED")
+    mqtt = edge_data.get("mqtt") or {}
+    if not isinstance(mqtt, dict):
+        mqtt = {}
+
+    kwargs: dict[str, Any] = {
+        "enabled": enabled if enabled is not None else False,
+        "http_enabled": (_flag("http_enabled", "VOODOO_EDGE_HTTP_ENABLED") or False)
+        if "http_enabled" in edge_data or "VOODOO_EDGE_HTTP_ENABLED" in os.environ
+        else True,
+        "mqtt_enabled": (_flag("mqtt_enabled", "VOODOO_EDGE_MQTT_ENABLED") or False)
+        if "mqtt_enabled" in edge_data or "VOODOO_EDGE_MQTT_ENABLED" in os.environ
+        else (bool(mqtt) or "MQTT_BROKER_URL" in os.environ),
+        "mqtt_broker_url": mqtt.get("broker_url") or os.getenv("MQTT_BROKER_URL", ""),
+        "mqtt_port": int(mqtt.get("port") or os.getenv("MQTT_PORT", "1883")),
+        "mqtt_tls": bool(mqtt.get("tls") or _env_flag("MQTT_TLS") or False),
+        "mqtt_username": mqtt.get("username") or os.getenv("MQTT_USERNAME", ""),
+        "mqtt_password": mqtt.get("password") or os.getenv("MQTT_PASSWORD", ""),
+        "mqtt_client_id": mqtt.get("client_id")
+        or os.getenv("MQTT_CLIENT_ID", "voodoo-runtime"),
+        "mqtt_keepalive": int(mqtt.get("keepalive", 60)),
+        "mqtt_qos": int(mqtt.get("qos", 1)),
+    }
+    for key in (
+        "max_message_size",
+        "max_state_size",
+        "max_pending_effects",
+        "heartbeat_interval",
+        "http_host",
+        "http_port",
+    ):
+        if key in edge_data:
+            kwargs[key] = edge_data[key]
+    return EdgeConfig(**kwargs)
+
+
 def _pick(
     file_data: dict[str, Any],
     key: str,
@@ -551,6 +631,7 @@ def get_config(
     config_args["cache"] = _build_cache_config(file_data)
     config_args["models"] = _build_models_config(file_data)
     config_args["ai"] = _build_ai_config(file_data)
+    config_args["edge"] = _build_edge_config(file_data)
 
     # Existing sub-configurations
     if "seo" in file_data and isinstance(file_data["seo"], dict):
@@ -578,6 +659,7 @@ def get_config(
         "cache",
         "models",
         "ai",
+        "edge",
         "seo",
         "auth",
         "security",

{voodoo_framework-2.5.2 → voodoo_framework-2.6.0}/src/voodoo/core/app.py

@@ -241,6 +241,22 @@ def create_app(app_dir: str = "app") -> Starlette:  # noqa: C901
 
     routes.extend(voodoo_api.routes)
 
+    # --- Edge device gateway (Sprint 23, EDGE §68) -------------------------
+    # Entirely optional: when ``edge.enabled`` is False, no store, gateway,
+    # routes, or MQTT client are created — regular apps pay zero overhead.
+    edge_gateway: list = []  # mutable holder so lifespan can share/replace the gateway
+    if config.edge.enabled and config.edge.http_enabled:
+        from voodoo.edge import DeviceGateway, SQLiteDeviceStore
+
+        edge_store = SQLiteDeviceStore(".voodoo/state/devices.db")
+        from voodoo.runtime.engine import engine as _runtime_engine
+
+        gateway = DeviceGateway(edge_store, _runtime_engine)
+        edge_gateway.append(gateway)
+        from voodoo.edge.http import build_edge_routes as _build_edge_routes
+
+        routes.extend(_build_edge_routes(gateway))
+
     from voodoo.auth import AuthMiddleware
     from voodoo.i18n import I18nMiddleware
     from voodoo.security import (
@@ -290,8 +306,39 @@ def create_app(app_dir: str = "app") -> Starlette:  # noqa: C901
 
         if _workers:
             worker_task = asyncio.create_task(start_workers())
+
+        # Edge MQTT transport (Sprint 23) — optional, only when configured.
+        mqtt_transport = None
+        if config.edge.enabled and config.edge.mqtt_enabled:
+            try:
+                from voodoo.edge import DeviceGateway as _DG
+                from voodoo.edge import SQLiteDeviceStore as _SDS
+                from voodoo.edge.mqtt import EdgeMQTTTransport
+                from voodoo.runtime.engine import engine as _rt_engine
+
+                gateway = (
+                    edge_gateway[0]
+                    if edge_gateway
+                    else _DG(_SDS(".voodoo/state/devices.db"), _rt_engine)
+                )
+                mqtt_transport = EdgeMQTTTransport(
+                    gateway,
+                    broker_url=config.edge.mqtt_broker_url or "localhost",
+                    port=config.edge.mqtt_port,
+                    tls=config.edge.mqtt_tls,
+                    username=config.edge.mqtt_username or None,
+                    password=config.edge.mqtt_password or None,
+                    client_id=config.edge.mqtt_client_id,
+                    qos=config.edge.mqtt_qos,
+                )
+                await mqtt_transport.start()
+            except ImportError:
+                # paho-mqtt not installed — edge stays HTTP-only.
+                pass
         yield
         # Shutdown
+        if mqtt_transport is not None:
+            await mqtt_transport.stop()
         await stop_workers()
         if worker_task:
             worker_task.cancel()

voodoo_framework-2.6.0/src/voodoo/edge/__init__.py

@@ -0,0 +1,122 @@
+"""Voodoo Edge — external device boundary for the Voodoo Runtime (Sprint 23).
+
+Physical and distributed devices (ESP32, Raspberry Pi, robots, industrial
+controllers) participate as first-class Voodoo Entities through the
+versioned ``voodoo-edge/v1`` protocol over HTTP and MQTT transports.
+
+There is **no** DeviceExecutionEngine: device-triggered work enters the
+standard ExecutionEngine, device events use the standard event system,
+and device state uses standard State semantics.
+
+    from voodoo.edge import DeviceGateway, SQLiteDeviceStore
+
+    store = SQLiteDeviceStore("data/devices.db")
+    gateway = DeviceGateway(store, engine)
+"""
+
+from __future__ import annotations
+
+from voodoo.edge.auth import (
+    authenticate_device,
+    consume_enrollment,
+    create_enrollment,
+    generate_device_credential,
+    hash_device_credential,
+    rotate_device_credential,
+)
+from voodoo.edge.errors import (
+    AuthenticationFailedError,
+    AuthorizationFailedError,
+    DeviceNotFoundError,
+    DeviceRevokedError,
+    DuplicateMessageError,
+    EdgeError,
+    EffectExpiredError,
+    EffectNotFoundError,
+    InvalidCapabilityError,
+    InvalidMessageError,
+    InvalidProtocolVersionError,
+    InvalidStateVersionError,
+    TransportError,
+    error_response,
+)
+from voodoo.edge.gateway import DeviceGateway
+from voodoo.edge.models import (
+    AuthenticatedDeviceContext,
+    CredentialStatus,
+    Device,
+    DeviceCredential,
+    DeviceEnrollment,
+    DeviceSession,
+    DeviceStatus,
+    EnrollmentStatus,
+    TransportKind,
+)
+from voodoo.edge.protocol import (
+    PROTOCOL_NAME,
+    PROTOCOL_VERSION,
+    EdgeMessage,
+    EdgeMessageType,
+    EffectAckStatus,
+    decode_message,
+    encode_message,
+    make_message,
+)
+from voodoo.edge.store import (
+    DeviceStoreProtocol,
+    EffectDelivery,
+    InMemoryDeviceStore,
+    SQLiteDeviceStore,
+)
+
+__all__ = [
+    # Protocol identity
+    "PROTOCOL_NAME",
+    "PROTOCOL_VERSION",
+    # Models
+    "Device",
+    "DeviceStatus",
+    "DeviceCredential",
+    "CredentialStatus",
+    "DeviceEnrollment",
+    "EnrollmentStatus",
+    "DeviceSession",
+    "AuthenticatedDeviceContext",
+    "TransportKind",
+    # Protocol
+    "EdgeMessage",
+    "EdgeMessageType",
+    "EffectAckStatus",
+    "make_message",
+    "encode_message",
+    "decode_message",
+    # Store
+    "DeviceStoreProtocol",
+    "InMemoryDeviceStore",
+    "SQLiteDeviceStore",
+    "EffectDelivery",
+    # Auth
+    "authenticate_device",
+    "consume_enrollment",
+    "create_enrollment",
+    "generate_device_credential",
+    "hash_device_credential",
+    "rotate_device_credential",
+    # Gateway
+    "DeviceGateway",
+    # Errors
+    "EdgeError",
+    "error_response",
+    "AuthenticationFailedError",
+    "AuthorizationFailedError",
+    "DeviceNotFoundError",
+    "DeviceRevokedError",
+    "DuplicateMessageError",
+    "EffectExpiredError",
+    "EffectNotFoundError",
+    "InvalidCapabilityError",
+    "InvalidMessageError",
+    "InvalidProtocolVersionError",
+    "InvalidStateVersionError",
+    "TransportError",
+]

voodoo_framework-2.6.0/src/voodoo/edge/auth.py

@@ -0,0 +1,243 @@
+"""Edge device authentication — credentials and enrollment (EDGE §9–§11).
+
+Device authentication is deliberately separate from user authentication:
+devices present dedicated ``vdk_`` credentials issued at enrollment,
+never admin/user API keys. Only SHA-256 hashes are stored.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import secrets
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING
+
+from voodoo.edge.errors import (
+    AuthenticationFailedError,
+    DeviceNotFoundError,
+    DeviceRevokedError,
+)
+from voodoo.edge.models import (
+    AuthenticatedDeviceContext,
+    Device,
+    DeviceCredential,
+    DeviceEnrollment,
+    DeviceSession,
+    DeviceStatus,
+    TransportKind,
+    _iso_now,
+)
+from voodoo.edge.store import DeviceStoreProtocol
+
+if TYPE_CHECKING:
+    pass
+
+__all__ = [
+    "generate_device_credential",
+    "hash_device_credential",
+    "generate_enrollment_key",
+    "hash_enrollment_key",
+    "authenticate_device",
+    "create_enrollment",
+    "consume_enrollment",
+    "rotate_device_credential",
+]
+
+
+# ---------------------------------------------------------------------------
+# Credential generation & hashing
+# ---------------------------------------------------------------------------
+
+
+def generate_device_credential() -> tuple[str, str]:
+    """Generate a device credential. Returns ``(raw_credential, hash)``.
+
+    The raw credential is shown exactly once — at enrollment or rotation.
+    Prefix ``vdk_`` (Voodoo Device Key) distinguishes device credentials
+    from user API keys (``vd_live_``).
+    """
+    raw = f"vdk_{secrets.token_urlsafe(32)}"
+    return raw, hash_device_credential(raw)
+
+
+def hash_device_credential(credential: str) -> str:
+    """SHA-256 hash for safe storage."""
+    return hashlib.sha256(credential.encode("utf-8")).hexdigest()
+
+
+def generate_enrollment_key() -> tuple[str, str]:
+    """Generate a single-use enrollment key. Returns ``(raw_key, hash)``."""
+    raw = f"vde_{secrets.token_urlsafe(24)}"
+    return raw, hash_device_credential(raw)
+
+
+def hash_enrollment_key(key: str) -> str:
+    """SHA-256 hash of an enrollment key."""
+    return hashlib.sha256(key.encode("utf-8")).hexdigest()
+
+
+def _parse_expires(expires_at: str | None) -> datetime | None:
+    if expires_at is None:
+        return None
+    try:
+        return datetime.fromisoformat(expires_at)
+    except ValueError:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Enrollment (EDGE §10)
+# ---------------------------------------------------------------------------
+
+
+async def create_enrollment(
+    store: DeviceStoreProtocol,
+    *,
+    device_type: str = "generic",
+    device_name: str = "",
+    capabilities: list[str] | None = None,
+    expires_in_seconds: int = 3600,
+) -> str:
+    """Create a single-use, short-lived enrollment token.
+
+    Returns the **raw enrollment key** — store it securely; it cannot be
+    recovered from the runtime (only its hash is persisted).
+    """
+    raw_key, key_hash = generate_enrollment_key()
+    expires_at = (datetime.now(UTC) + timedelta(seconds=expires_in_seconds)).isoformat()
+    enrollment = DeviceEnrollment(
+        enrollment_key_hash=key_hash,
+        device_type=device_type,
+        device_name=device_name,
+        capabilities=list(capabilities or []),
+        expires_at=expires_at,
+    )
+    await store.create_enrollment(enrollment)
+    return raw_key
+
+
+async def consume_enrollment(
+    store: DeviceStoreProtocol,
+    enrollment_key: str,
+    *,
+    firmware_version: str | None = None,
+) -> tuple[Device, str]:
+    """Consume an enrollment key and issue device identity + credential.
+
+    Validates: key exists, is PENDING, and not expired. On success the
+    enrollment becomes CONSUMED (single-use), a Device entity is created,
+    and a device credential is issued. Returns ``(device, raw_credential)``.
+    """
+    key_hash = hash_enrollment_key(enrollment_key)
+    enrollment = await store.find_enrollment_by_hash(key_hash)
+    if enrollment is None:
+        raise AuthenticationFailedError("Unknown enrollment key")
+
+    expires = _parse_expires(enrollment.expires_at)
+    if expires is not None and datetime.now(UTC) > expires:
+        raise AuthenticationFailedError("Enrollment key expired")
+
+    # Single-use: only a PENDING enrollment can convert.
+    consumed = await store.consume_enrollment(enrollment.enrollment_id)
+    if not consumed:
+        raise AuthenticationFailedError("Enrollment key already used or revoked")
+
+    device = Device(
+        type=enrollment.device_type,
+        name=enrollment.device_name or f"{enrollment.device_type}-device",
+        capabilities=list(enrollment.capabilities),
+        metadata={"firmware_version": firmware_version} if firmware_version else {},
+    )
+    await store.register_device(device)
+
+    raw_credential, credential_hash = generate_device_credential()
+    await store.create_credential(
+        DeviceCredential(
+            device_id=device.device_id,
+            credential_hash=credential_hash,
+        )
+    )
+    return device, raw_credential
+
+
+async def rotate_device_credential(store: DeviceStoreProtocol, device_id: str) -> str:
+    """Rotate a device credential. Returns the new raw credential.
+
+    The old credential is marked ROTATED (no longer valid); the device
+    keeps operating with the new one.
+    """
+    old = await store.get_active_credential(device_id)
+    if old is not None:
+        await store.revoke_credential(old.credential_id)
+
+    raw, credential_hash = generate_device_credential()
+    await store.create_credential(
+        DeviceCredential(
+            device_id=device_id,
+            credential_hash=credential_hash,
+        )
+    )
+    return raw
+
+
+# ---------------------------------------------------------------------------
+# Authentication (EDGE §11)
+# ---------------------------------------------------------------------------
+
+
+async def authenticate_device(
+    store: DeviceStoreProtocol,
+    credential: str,
+    *,
+    claimed_device_id: str | None = None,
+    transport: TransportKind = TransportKind.HTTP,
+) -> tuple[AuthenticatedDeviceContext, DeviceSession]:
+    """Authenticate a device credential and establish a session.
+
+    The credential MUST bind to the claimed device — a message claiming
+    ``device_id`` without a matching credential is rejected (EDGE §11).
+
+    Returns ``(context, session)``. Raises:
+    - ``AuthenticationFailedError`` — unknown/invalid credential
+    - ``DeviceRevokedError`` — device has been revoked
+    - ``DeviceNotFoundError`` — claimed device does not exist
+    """
+    credential_hash = hash_device_credential(credential)
+    record = await store.find_credential_by_hash(credential_hash)
+    if record is None:
+        raise AuthenticationFailedError("Invalid device credential")
+
+    # Never trust a claimed device_id without validating the binding.
+    if claimed_device_id is not None and claimed_device_id != record.device_id:
+        raise AuthenticationFailedError(
+            "Credential does not belong to the claimed device"
+        )
+
+    device = await store.get_device(record.device_id)
+    if device is None:
+        raise DeviceNotFoundError(
+            f"Credential references missing device '{record.device_id}'"
+        )
+    if device.status == DeviceStatus.REVOKED:
+        raise DeviceRevokedError(f"Device '{device.device_id}' has been revoked")
+
+    await store.mark_credential_used(record.credential_id)
+
+    session = DeviceSession(
+        device_id=device.device_id,
+        transport=transport,
+        last_seen_at=_iso_now(),
+    )
+    await store.create_session(session)
+    await store.update_device_status(device.device_id, DeviceStatus.CONNECTED)
+    await store.update_last_seen(device.device_id)
+
+    context = AuthenticatedDeviceContext(
+        device_id=device.device_id,
+        device_type=device.type,
+        capabilities=list(device.capabilities),
+        session_id=session.session_id,
+        transport=transport,
+        metadata=dict(device.metadata),
+    )
+    return context, session