feat: add secure agent enrollment

backend/app/agent_auth/__init__.py

@@ -0,0 +1 @@
+"""Per-Agent authentication support."""

backend/app/agent_auth/exceptions.py

@@ -0,0 +1,21 @@
+"""Domain errors for Agent authentication."""
+
+
+class AgentAuthenticationError(Exception):
+    """Base Agent authentication error."""
+
+
+class AgentAuthenticationUnavailable(AgentAuthenticationError):
+    """Agent authentication cannot currently be performed."""
+
+
+class AgentAuthenticationFailed(AgentAuthenticationError):
+    """The supplied Agent secret is invalid."""
+
+
+class AgentIdentityUnauthorized(AgentAuthenticationError):
+    """The supplied Agent identity is not authorized."""
+
+
+class AgentCredentialRevoked(AgentAuthenticationError):
+    """The Agent's permanent credential has been revoked."""

backend/app/agent_auth/repository.py

@@ -0,0 +1,47 @@
+"""PostgreSQL persistence for Agent authentication."""
+
+from collections.abc import Callable
+
+import psycopg
+from psycopg.rows import dict_row
+
+from app.config import settings
+
+
+ConnectionFactory = Callable[[], psycopg.Connection]
+
+
+def default_connection_factory() -> psycopg.Connection:
+    return psycopg.connect(
+        host=settings.postgres_host,
+        port=settings.postgres_port,
+        dbname=settings.postgres_db,
+        user=settings.postgres_user,
+        password=settings.postgres_password,
+        connect_timeout=5,
+    )
+
+
+class AgentAuthRepository:
+    def __init__(self, connection_factory: ConnectionFactory | None = None):
+        self._connection_factory = connection_factory or default_connection_factory
+
+    def get_credential(self, agent_id: str) -> dict | None:
+        connection = self._connection_factory()
+        try:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    SELECT agent_id,
+                           agent_secret_hash,
+                           credential_created_at,
+                           credential_revoked_at
+                    FROM minerops_site_agents
+                    WHERE agent_id = %s
+                    """,
+                    (agent_id,),
+                )
+                row = cur.fetchone()
+                return dict(row) if row else None
+        finally:
+            connection.close()

backend/app/agent_auth/service.py

@@ -0,0 +1,66 @@
+"""Per-Agent authentication with bounded legacy compatibility."""
+
+import hashlib
+import hmac
+
+from app.agent_auth.exceptions import (
+    AgentAuthenticationFailed,
+    AgentAuthenticationUnavailable,
+    AgentCredentialRevoked,
+    AgentIdentityUnauthorized,
+)
+from app.config import settings
+
+
+def hash_agent_secret(secret: str) -> str:
+    """Hash a high-entropy machine-generated Agent secret for persistence."""
+    return hashlib.sha256(secret.encode("utf-8")).hexdigest()
+
+
+class AgentAuthService:
+    def __init__(self, repository):
+        self.repository = repository
+
+    def authenticate(self, agent_id: str | None, provided_secret: str | None) -> str:
+        identity = (agent_id or "").strip()
+        secret = (provided_secret or "").strip()
+
+        if not identity:
+            raise AgentAuthenticationFailed("Missing Agent identity")
+        if not secret:
+            raise AgentAuthenticationFailed("Invalid or missing Agent secret")
+
+        credential = self.repository.get_credential(identity)
+
+        # Any Agent with a per-Agent credential is permanently on the new
+        # authentication path. The legacy shared secret must never authenticate
+        # that identity, even if the Agent later becomes revoked.
+        if credential and credential.get("agent_secret_hash"):
+            if credential.get("credential_revoked_at") is not None:
+                raise AgentCredentialRevoked("Agent credential has been revoked")
+
+            supplied_hash = hash_agent_secret(secret)
+            if not hmac.compare_digest(
+                supplied_hash,
+                str(credential["agent_secret_hash"]),
+            ):
+                raise AgentAuthenticationFailed("Invalid or missing Agent secret")
+
+            return identity
+
+        # Temporary compatibility for the single pre-enrollment Agent.
+        legacy_id = settings.minerops_agent_id.strip()
+        legacy_secret = settings.minerops_agent_shared_secret.strip()
+
+        if not legacy_id or not legacy_secret:
+            raise AgentAuthenticationUnavailable(
+                "Legacy Agent authentication is not configured"
+            )
+
+        if not hmac.compare_digest(identity, legacy_id):
+            raise AgentIdentityUnauthorized("Agent identity is not authorized")
+
+        if not hmac.compare_digest(secret, legacy_secret):
+            raise AgentAuthenticationFailed("Invalid or missing Agent secret")
+
+        return identity

backend/app/agent_commands/dependencies.py

@@ -1,37 +1,46 @@
 """Dependencies for the authenticated Agent queue protocol."""
 
-import hmac
 from typing import Annotated
 
-from fastapi import Header, HTTPException
+from fastapi import Depends, Header, HTTPException
 
+from app.agent_auth.exceptions import (
+    AgentAuthenticationFailed,
+    AgentAuthenticationUnavailable,
+    AgentCredentialRevoked,
+    AgentIdentityUnauthorized,
+)
+from app.agent_auth.repository import AgentAuthRepository
+from app.agent_auth.service import AgentAuthService
 from app.agent_commands.repository import AgentCommandRepository
 from app.agent_commands.service import AgentCommandService
-from app.config import settings
 
 
 def get_agent_command_service() -> AgentCommandService:
     return AgentCommandService(AgentCommandRepository())
 
 
+def get_agent_auth_service() -> AgentAuthService:
+    return AgentAuthService(AgentAuthRepository())
+
+
 def require_agent_identity(
     agent_id: Annotated[str | None, Header(alias="X-MinerOps-Agent-ID")] = None,
     provided_secret: Annotated[
         str | None, Header(alias="X-MinerOps-Agent-Secret")
     ] = None,
+    service: AgentAuthService = Depends(get_agent_auth_service),
 ) -> str:
-    expected_id = settings.minerops_agent_id.strip()
-    expected_secret = settings.minerops_agent_shared_secret.strip()
-    if not expected_id or not expected_secret:
-        raise HTTPException(status_code=503, detail="Agent authentication is not configured")
-
-    secret = (provided_secret or "").strip()
-    if not secret or not hmac.compare_digest(secret, expected_secret):
-        raise HTTPException(status_code=401, detail="Invalid or missing Agent secret")
-
-    identity = (agent_id or "").strip()
-    if not identity:
-        raise HTTPException(status_code=401, detail="Missing Agent identity")
-    if not hmac.compare_digest(identity, expected_id):
-        raise HTTPException(status_code=403, detail="Agent identity is not authorized")
-    return identity
+    try:
+        return service.authenticate(agent_id, provided_secret)
+    except AgentAuthenticationUnavailable as exc:
+        raise HTTPException(
+            status_code=503,
+            detail="Agent authentication is not configured",
+        ) from exc
+    except AgentAuthenticationFailed as exc:
+        raise HTTPException(status_code=401, detail=str(exc)) from exc
+    except AgentCredentialRevoked as exc:
+        raise HTTPException(status_code=403, detail=str(exc)) from exc
+    except AgentIdentityUnauthorized as exc:
+        raise HTTPException(status_code=403, detail=str(exc)) from exc

backend/app/agent_enrollment/__init__.py

@@ -0,0 +1 @@
+"""Secure one-time Agent enrollment."""

backend/app/agent_enrollment/dependencies.py

@@ -0,0 +1,8 @@
+"""Dependency wiring for secure Agent enrollment."""
+
+from app.agent_enrollment.repository import AgentEnrollmentRepository
+from app.agent_enrollment.service import AgentEnrollmentService
+
+
+def get_agent_enrollment_service() -> AgentEnrollmentService:
+    return AgentEnrollmentService(AgentEnrollmentRepository())

backend/app/agent_enrollment/exceptions.py

@@ -0,0 +1,21 @@
+"""Domain exceptions for secure Agent enrollment."""
+
+
+class AgentEnrollmentError(Exception):
+    """Base Agent enrollment error."""
+
+
+class AgentEnrollmentNotFound(AgentEnrollmentError):
+    """The requested Site or Agent Zone does not exist."""
+
+
+class AgentEnrollmentConflict(AgentEnrollmentError):
+    """The requested enrollment conflicts with current Agent routing state."""
+
+
+class AgentEnrollmentTokenInvalid(AgentEnrollmentError):
+    """The supplied bootstrap token cannot be redeemed."""
+
+
+class AgentEnrollmentCredentialCollision(AgentEnrollmentError):
+    """A generated machine credential collided with an existing credential."""

backend/app/agent_enrollment/models.py

@@ -0,0 +1,94 @@
+"""Typed contracts for secure Agent enrollment."""
+
+from datetime import datetime
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class AgentEnrollmentCreateRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    site_id: UUID
+    agent_zone_id: UUID
+    display_name: str = Field(min_length=1, max_length=120)
+
+    @field_validator("display_name")
+    @classmethod
+    def normalize_display_name(cls, value: str) -> str:
+        normalized = value.strip()
+        if not normalized:
+            raise ValueError("display_name cannot be blank")
+        return normalized
+
+
+class AgentEnrollmentCreated(BaseModel):
+    id: UUID
+    site_id: UUID
+    site_name: str
+    agent_zone_id: UUID
+    agent_zone_name: str
+    display_name: str
+    created_at: datetime
+    expires_at: datetime
+    enrollment_token: str
+
+
+class AgentEnrollmentCreateResponse(BaseModel):
+    data: AgentEnrollmentCreated
+    meta: dict[str, object] = Field(default_factory=dict)
+    error: None = None
+
+
+class AgentEnrollmentSummary(BaseModel):
+    id: UUID
+    site_id: UUID
+    site_name: str
+    agent_zone_id: UUID
+    agent_zone_name: str
+    display_name: str
+    created_by_user_id: UUID | None = None
+    created_at: datetime
+    expires_at: datetime
+    used_at: datetime | None = None
+    revoked_at: datetime | None = None
+    enrolled_agent_id: str | None = None
+    status: Literal["waiting", "used", "revoked", "expired"]
+
+
+class AgentEnrollmentListResponse(BaseModel):
+    data: list[AgentEnrollmentSummary]
+    meta: dict[str, object] = Field(default_factory=dict)
+    error: None = None
+
+
+class AgentEnrollRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    token: str = Field(min_length=32, max_length=256)
+
+    @field_validator("token")
+    @classmethod
+    def normalize_token(cls, value: str) -> str:
+        normalized = value.strip()
+        if not normalized:
+            raise ValueError("token cannot be blank")
+        return normalized
+
+
+class AgentEnrollCredentials(BaseModel):
+    agent_id: str
+    agent_secret: str
+    site_id: UUID
+    site_name: str
+    agent_zone_id: UUID
+    agent_zone_name: str
+    display_name: str
+    ip_ranges: list[str] = Field(default_factory=list)
+
+
+class AgentEnrollResponse(BaseModel):
+    data: AgentEnrollCredentials
+    meta: dict[str, object] = Field(default_factory=dict)
+    error: None = None

backend/app/agent_enrollment/repository.py

@@ -0,0 +1,506 @@
+"""PostgreSQL persistence for secure Agent enrollment."""
+
+from collections.abc import Callable
+from uuid import UUID
+
+import psycopg
+from psycopg.errors import UniqueViolation
+from psycopg.rows import dict_row
+from psycopg.types.json import Jsonb
+
+from app.agent_enrollment.exceptions import (
+    AgentEnrollmentConflict,
+    AgentEnrollmentCredentialCollision,
+    AgentEnrollmentNotFound,
+    AgentEnrollmentTokenInvalid,
+)
+from app.config import settings
+
+
+ConnectionFactory = Callable[[], psycopg.Connection]
+
+TOKEN_HASH_CONSTRAINT = "uq_agent_enrollments_token_hash"
+OPEN_ZONE_CONSTRAINT = "uq_agent_enrollments_open_zone"
+AGENT_SECRET_HASH_CONSTRAINT = "uq_minerops_site_agents_agent_secret_hash"
+AGENT_ZONE_CONSTRAINT = "uq_minerops_site_agents_agent_zone_id"
+AGENT_ID_CONSTRAINT = "minerops_site_agents_pkey"
+
+
+def default_connection_factory() -> psycopg.Connection:
+    return psycopg.connect(
+        host=settings.postgres_host,
+        port=settings.postgres_port,
+        dbname=settings.postgres_db,
+        user=settings.postgres_user,
+        password=settings.postgres_password,
+        connect_timeout=5,
+    )
+
+
+class AgentEnrollmentRepository:
+    def __init__(self, connection_factory: ConnectionFactory | None = None):
+        self._connection_factory = connection_factory or default_connection_factory
+
+    def create_enrollment(
+        self,
+        *,
+        token_hash: str,
+        site_id: UUID,
+        agent_zone_id: UUID,
+        display_name: str,
+        actor_user_id: UUID,
+    ) -> dict:
+        connection = self._connection_factory()
+        try:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    SELECT zone.id,
+                           zone.site_id,
+                           zone.name AS agent_zone_name,
+                           zone.is_enabled,
+                           site.name AS site_name,
+                           agent.agent_id AS assigned_agent_id
+                    FROM agent_zones AS zone
+                    JOIN sites AS site ON site.id = zone.site_id
+                    LEFT JOIN minerops_site_agents AS agent
+                      ON agent.agent_zone_id = zone.id
+                    WHERE zone.id = %s
+                      AND zone.site_id = %s
+                    FOR UPDATE OF zone
+                    """,
+                    (agent_zone_id, site_id),
+                )
+                zone = cur.fetchone()
+
+                if not zone:
+                    raise AgentEnrollmentNotFound(
+                        "Agent Zone was not found for the selected Site"
+                    )
+
+                if zone["is_enabled"] is not True:
+                    raise AgentEnrollmentConflict(
+                        "Agent Zone is disabled"
+                    )
+
+                if zone["assigned_agent_id"]:
+                    raise AgentEnrollmentConflict(
+                        "Agent Zone already has an assigned Agent"
+                    )
+
+                cur.execute(
+                    "SELECT clock_timestamp() AS operation_now"
+                )
+                operation_now = cur.fetchone()["operation_now"]
+
+                cur.execute(
+                    """
+                    UPDATE agent_enrollments
+                    SET revoked_at = %s
+                    WHERE agent_zone_id = %s
+                      AND used_at IS NULL
+                      AND revoked_at IS NULL
+                    RETURNING id
+                    """,
+                    (operation_now, agent_zone_id),
+                )
+                replaced_ids = [
+                    str(row["id"]) for row in cur.fetchall()
+                ]
+
+                cur.execute(
+                    """
+                    INSERT INTO agent_enrollments (
+                        token_hash,
+                        site_id,
+                        agent_zone_id,
+                        display_name,
+                        created_by_user_id,
+                        created_at,
+                        expires_at
+                    )
+                    VALUES (
+                        %s,
+                        %s,
+                        %s,
+                        %s,
+                        %s,
+                        %s,
+                        %s + interval '30 minutes'
+                    )
+                    RETURNING
+                        id,
+                        site_id,
+                        agent_zone_id,
+                        display_name,
+                        created_at,
+                        expires_at
+                    """,
+                    (
+                        token_hash,
+                        site_id,
+                        agent_zone_id,
+                        display_name,
+                        actor_user_id,
+                        operation_now,
+                        operation_now,
+                    ),
+                )
+                enrollment = dict(cur.fetchone())
+
+                enrollment["site_name"] = zone["site_name"]
+                enrollment["agent_zone_name"] = zone["agent_zone_name"]
+
+                cur.execute(
+                    """
+                    INSERT INTO audit_logs (
+                        actor_user_id,
+                        action,
+                        entity_type,
+                        entity_id,
+                        new_value_json,
+                        created_at
+                    )
+                    VALUES (
+                        %s,
+                        'agent.enrollment.created',
+                        'agent_enrollment',
+                        %s,
+                        %s,
+                        %s
+                    )
+                    """,
+                    (
+                        actor_user_id,
+                        enrollment["id"],
+                        Jsonb(
+                            {
+                                "site_id": str(site_id),
+                                "agent_zone_id": str(agent_zone_id),
+                                "display_name": display_name,
+                                "expires_at": enrollment[
+                                    "expires_at"
+                                ].isoformat(),
+                                "replaced_enrollment_ids": replaced_ids,
+                            }
+                        ),
+                        operation_now,
+                    ),
+                )
+
+            connection.commit()
+            return enrollment
+
+        except UniqueViolation as exc:
+            connection.rollback()
+            constraint = exc.diag.constraint_name
+
+            if constraint == TOKEN_HASH_CONSTRAINT:
+                raise AgentEnrollmentCredentialCollision(
+                    "Generated enrollment token collided"
+                ) from exc
+
+            if constraint == OPEN_ZONE_CONSTRAINT:
+                raise AgentEnrollmentConflict(
+                    "An active enrollment already exists for this Agent Zone"
+                ) from exc
+
+            raise
+
+        except Exception:
+            connection.rollback()
+            raise
+
+        finally:
+            connection.close()
+
+    def list_enrollments(
+        self,
+        *,
+        site_id: UUID | None = None,
+        agent_zone_id: UUID | None = None,
+        limit: int = 100,
+    ) -> list[dict]:
+        connection = self._connection_factory()
+        try:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    SELECT
+                        enrollment.id,
+                        enrollment.site_id,
+                        site.name AS site_name,
+                        enrollment.agent_zone_id,
+                        zone.name AS agent_zone_name,
+                        enrollment.display_name,
+                        enrollment.created_by_user_id,
+                        enrollment.created_at,
+                        enrollment.expires_at,
+                        enrollment.used_at,
+                        enrollment.revoked_at,
+                        enrollment.enrolled_agent_id,
+                        CASE
+                            WHEN enrollment.used_at IS NOT NULL
+                                THEN 'used'
+                            WHEN enrollment.revoked_at IS NOT NULL
+                                THEN 'revoked'
+                            WHEN enrollment.expires_at <= now()
+                                THEN 'expired'
+                            ELSE 'waiting'
+                        END AS status
+                    FROM agent_enrollments AS enrollment
+                    JOIN sites AS site
+                      ON site.id = enrollment.site_id
+                    JOIN agent_zones AS zone
+                      ON zone.id = enrollment.agent_zone_id
+                    WHERE (%s::uuid IS NULL OR enrollment.site_id = %s::uuid)
+                      AND (
+                          %s::uuid IS NULL
+                          OR enrollment.agent_zone_id = %s::uuid
+                      )
+                    ORDER BY enrollment.created_at DESC, enrollment.id DESC
+                    LIMIT %s
+                    """,
+                    (
+                        site_id,
+                        site_id,
+                        agent_zone_id,
+                        agent_zone_id,
+                        limit,
+                    ),
+                )
+                return [dict(row) for row in cur.fetchall()]
+        finally:
+            connection.close()
+
+    def redeem_enrollment(
+        self,
+        *,
+        token_hash: str,
+        agent_id: str,
+        agent_secret_hash: str,
+    ) -> dict:
+        connection = self._connection_factory()
+        try:
+            with connection.cursor(row_factory=dict_row) as cur:
+                cur.execute(
+                    """
+                    SELECT
+                        id,
+                        site_id,
+                        agent_zone_id,
+                        display_name,
+                        expires_at,
+                        used_at,
+                        revoked_at
+                    FROM agent_enrollments
+                    WHERE token_hash = %s
+                    FOR UPDATE
+                    """,
+                    (token_hash,),
+                )
+                enrollment = cur.fetchone()
+
+                if not enrollment:
+                    raise AgentEnrollmentTokenInvalid(
+                        "Invalid or expired enrollment token"
+                    )
+
+                if (
+                    enrollment["used_at"] is not None
+                    or enrollment["revoked_at"] is not None
+                ):
+                    raise AgentEnrollmentTokenInvalid(
+                        "Invalid or expired enrollment token"
+                    )
+
+                cur.execute(
+                    """
+                    SELECT
+                        zone.id,
+                        zone.site_id,
+                        zone.name AS agent_zone_name,
+                        zone.is_enabled,
+                        site.name AS site_name
+                    FROM agent_zones AS zone
+                    JOIN sites AS site ON site.id = zone.site_id
+                    WHERE zone.id = %s
+                      AND zone.site_id = %s
+                    FOR UPDATE OF zone
+                    """,
+                    (
+                        enrollment["agent_zone_id"],
+                        enrollment["site_id"],
+                    ),
+                )
+                zone = cur.fetchone()
+
+                if not zone:
+                    raise AgentEnrollmentConflict(
+                        "Enrollment Agent Zone no longer exists"
+                    )
+
+                if zone["is_enabled"] is not True:
+                    raise AgentEnrollmentConflict(
+                        "Agent Zone is disabled"
+                    )
+
+                cur.execute(
+                    """
+                    SELECT agent_id
+                    FROM minerops_site_agents
+                    WHERE agent_zone_id = %s
+                    FOR UPDATE
+                    """,
+                    (enrollment["agent_zone_id"],),
+                )
+                existing_agent = cur.fetchone()
+
+                if existing_agent:
+                    raise AgentEnrollmentConflict(
+                        "Agent Zone already has an assigned Agent"
+                    )
+
+                cur.execute(
+                    "SELECT clock_timestamp() AS operation_now"
+                )
+                operation_now = cur.fetchone()["operation_now"]
+
+                if enrollment["expires_at"] <= operation_now:
+                    raise AgentEnrollmentTokenInvalid(
+                        "Invalid or expired enrollment token"
+                    )
+
+                cur.execute(
+                    """
+                    INSERT INTO minerops_site_agents (
+                        agent_id,
+                        site_id,
+                        agent_zone_id,
+                        site_name,
+                        display_name,
+                        agent_secret_hash,
+                        credential_created_at
+                    )
+                    VALUES (
+                        %s,
+                        %s,
+                        %s,
+                        %s,
+                        %s,
+                        %s,
+                        %s
+                    )
+                    """,
+                    (
+                        agent_id,
+                        enrollment["site_id"],
+                        enrollment["agent_zone_id"],
+                        zone["site_name"],
+                        enrollment["display_name"],
+                        agent_secret_hash,
+                        operation_now,
+                    ),
+                )
+
+                cur.execute(
+                    """
+                    UPDATE agent_enrollments
+                    SET used_at = %s,
+                        enrolled_agent_id = %s
+                    WHERE id = %s
+                    RETURNING used_at
+                    """,
+                    (operation_now, agent_id, enrollment["id"]),
+                )
+                used_at = cur.fetchone()["used_at"]
+
+                cur.execute(
+                    """
+                    SELECT network::text AS network
+                    FROM agent_zone_network_ranges
+                    WHERE agent_zone_id = %s
+                    ORDER BY network, id
+                    """,
+                    (enrollment["agent_zone_id"],),
+                )
+                networks = [
+                    row["network"] for row in cur.fetchall()
+                ]
+
+                cur.execute(
+                    """
+                    INSERT INTO audit_logs (
+                        actor_user_id,
+                        action,
+                        entity_type,
+                        entity_id,
+                        new_value_json,
+                        created_at
+                    )
+                    VALUES (
+                        NULL,
+                        'agent.enrollment.redeemed',
+                        'agent_enrollment',
+                        %s,
+                        %s,
+                        %s
+                    )
+                    """,
+                    (
+                        enrollment["id"],
+                        Jsonb(
+                            {
+                                "agent_id": agent_id,
+                                "site_id": str(enrollment["site_id"]),
+                                "agent_zone_id": str(
+                                    enrollment["agent_zone_id"]
+                                ),
+                                "display_name": enrollment[
+                                    "display_name"
+                                ],
+                                "used_at": used_at.isoformat(),
+                            }
+                        ),
+                        operation_now,
+                    ),
+                )
+
+                result = {
+                    "agent_id": agent_id,
+                    "site_id": enrollment["site_id"],
+                    "site_name": zone["site_name"],
+                    "agent_zone_id": enrollment["agent_zone_id"],
+                    "agent_zone_name": zone["agent_zone_name"],
+                    "display_name": enrollment["display_name"],
+                    "ip_ranges": networks,
+                }
+
+            connection.commit()
+            return result
+
+        except UniqueViolation as exc:
+            connection.rollback()
+            constraint = exc.diag.constraint_name
+
+            if constraint in {
+                AGENT_ID_CONSTRAINT,
+                AGENT_SECRET_HASH_CONSTRAINT,
+            }:
+                raise AgentEnrollmentCredentialCollision(
+                    "Generated Agent credential collided"
+                ) from exc
+
+            if constraint == AGENT_ZONE_CONSTRAINT:
+                raise AgentEnrollmentConflict(
+                    "Agent Zone already has an assigned Agent"
+                ) from exc
+
+            raise
+
+        except Exception:
+            connection.rollback()
+            raise
+
+        finally:
+            connection.close()

backend/app/agent_enrollment/router.py

@@ -0,0 +1,108 @@
+"""HTTP routes for Agent enrollment and bootstrap."""
+
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
+
+from app.agent_enrollment.dependencies import get_agent_enrollment_service
+from app.agent_enrollment.exceptions import (
+    AgentEnrollmentConflict,
+    AgentEnrollmentNotFound,
+    AgentEnrollmentTokenInvalid,
+)
+from app.agent_enrollment.models import (
+    AgentEnrollmentCreateRequest,
+    AgentEnrollmentCreateResponse,
+    AgentEnrollmentListResponse,
+    AgentEnrollRequest,
+    AgentEnrollResponse,
+)
+from app.agent_enrollment.service import AgentEnrollmentService
+from app.identity import require_permission
+
+
+router = APIRouter(tags=["agent-enrollment"])
+
+EnrollmentService = Annotated[
+    AgentEnrollmentService,
+    Depends(get_agent_enrollment_service),
+]
+EnrollmentViewer = Annotated[
+    dict,
+    Depends(require_permission("agents.view")),
+]
+EnrollmentManager = Annotated[
+    dict,
+    Depends(require_permission("agents.manage")),
+]
+
+
+@router.post(
+    "/api/agent-enrollments",
+    response_model=AgentEnrollmentCreateResponse,
+    status_code=status.HTTP_201_CREATED,
+)
+def create_agent_enrollment(
+    request: AgentEnrollmentCreateRequest,
+    response: Response,
+    current_user: EnrollmentManager,
+    service: EnrollmentService,
+) -> AgentEnrollmentCreateResponse:
+    response.headers["Cache-Control"] = "no-store"
+
+    try:
+        enrollment = service.create_enrollment(
+            request,
+            actor_user_id=UUID(str(current_user["id"])),
+        )
+        return AgentEnrollmentCreateResponse(data=enrollment)
+    except AgentEnrollmentNotFound as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except AgentEnrollmentConflict as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+
+
+@router.get(
+    "/api/agent-enrollments",
+    response_model=AgentEnrollmentListResponse,
+)
+def list_agent_enrollments(
+    current_user: EnrollmentViewer,
+    service: EnrollmentService,
+    site_id: UUID | None = Query(default=None),
+    agent_zone_id: UUID | None = Query(default=None),
+    limit: int = Query(default=100, ge=1, le=500),
+) -> AgentEnrollmentListResponse:
+    del current_user
+
+    return AgentEnrollmentListResponse(
+        data=service.list_enrollments(
+            site_id=site_id,
+            agent_zone_id=agent_zone_id,
+            limit=limit,
+        )
+    )
+
+
+@router.post(
+    "/api/agent/enroll",
+    response_model=AgentEnrollResponse,
+    status_code=status.HTTP_201_CREATED,
+)
+def enroll_agent(
+    request: AgentEnrollRequest,
+    response: Response,
+    service: EnrollmentService,
+) -> AgentEnrollResponse:
+    response.headers["Cache-Control"] = "no-store"
+
+    try:
+        return AgentEnrollResponse(data=service.redeem(request))
+    except AgentEnrollmentTokenInvalid as exc:
+        raise HTTPException(
+            status_code=401,
+            detail="Invalid or expired enrollment token",
+        ) from exc
+    except AgentEnrollmentConflict as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc

backend/app/agent_enrollment/service.py

@@ -0,0 +1,98 @@
+"""Application service for secure one-time Agent enrollment."""
+
+import secrets
+from uuid import UUID, uuid4
+
+from app.agent_auth.service import hash_agent_secret
+from app.agent_enrollment.exceptions import (
+    AgentEnrollmentConflict,
+    AgentEnrollmentCredentialCollision,
+)
+from app.agent_enrollment.models import (
+    AgentEnrollmentCreateRequest,
+    AgentEnrollRequest,
+)
+
+
+MAX_GENERATION_ATTEMPTS = 3
+
+
+def generate_enrollment_token() -> str:
+    return secrets.token_urlsafe(32)
+
+
+def generate_agent_secret() -> str:
+    return secrets.token_urlsafe(32)
+
+
+def generate_agent_id() -> str:
+    return f"agent-{uuid4().hex}"
+
+
+class AgentEnrollmentService:
+    def __init__(self, repository):
+        self.repository = repository
+
+    def create_enrollment(
+        self,
+        request: AgentEnrollmentCreateRequest,
+        *,
+        actor_user_id: UUID,
+    ) -> dict:
+        for _ in range(MAX_GENERATION_ATTEMPTS):
+            token = generate_enrollment_token()
+            try:
+                enrollment = self.repository.create_enrollment(
+                    token_hash=hash_agent_secret(token),
+                    site_id=request.site_id,
+                    agent_zone_id=request.agent_zone_id,
+                    display_name=request.display_name,
+                    actor_user_id=actor_user_id,
+                )
+                return {
+                    **enrollment,
+                    "enrollment_token": token,
+                }
+            except AgentEnrollmentCredentialCollision:
+                continue
+
+        raise AgentEnrollmentConflict(
+            "Unable to generate a unique enrollment token"
+        )
+
+    def list_enrollments(
+        self,
+        *,
+        site_id: UUID | None = None,
+        agent_zone_id: UUID | None = None,
+        limit: int = 100,
+    ) -> list[dict]:
+        return self.repository.list_enrollments(
+            site_id=site_id,
+            agent_zone_id=agent_zone_id,
+            limit=limit,
+        )
+
+    def redeem(self, request: AgentEnrollRequest) -> dict:
+        token_hash = hash_agent_secret(request.token)
+
+        for _ in range(MAX_GENERATION_ATTEMPTS):
+            agent_id = generate_agent_id()
+            agent_secret = generate_agent_secret()
+
+            try:
+                result = self.repository.redeem_enrollment(
+                    token_hash=token_hash,
+                    agent_id=agent_id,
+                    agent_secret_hash=hash_agent_secret(agent_secret),
+                )
+                return {
+                    **result,
+                    "agent_secret": agent_secret,
+                }
+            except AgentEnrollmentCredentialCollision:
+                continue
+
+        raise AgentEnrollmentConflict(
+            "Unable to generate unique Agent credentials"
+        )

backend/app/identity.py

@@ -699,8 +699,10 @@ def required_page_permission(path: str) -> str:
 
 def machine_agent_request(path: str) -> bool:
     exact = {
+        "/api/agent/enroll",
         "/api/agent/checkin",
         "/api/agent/config",
+        "/api/agent/known-miners",
         "/api/agent/miner-snapshots",
         "/api/agent/pool-snapshots",
         "/api/agent/commands/pending",
@@ -779,6 +781,8 @@ def required_api_permission(method: str, path: str) -> str | None:
         return "components.create" if method == "POST" else "components.read"
     if path == "/api/agent-zones":
         return "agents.view" if method == "GET" else "agents.manage"
+    if path == "/api/agent-enrollments":
+        return "agents.view" if method == "GET" else "agents.manage"
     if repair_parts_request(path):
         return "repairs.read" if method == "GET" else "repairs.parts.manage"
     if path.startswith("/api/admin/"):

backend/app/main.py

@@ -17,6 +17,7 @@ from app.agent_zones.dependencies import get_agent_zone_service
 from app.agent_zones.models import MinerZoneAssociationResult
 from app.agent_zones.service import AgentZoneService
 from app.agent_zones.router import router as agent_zones_router
+from app.agent_enrollment.router import router as agent_enrollment_router
 from app.miner_control.router import router as miner_control_router
 from app.dashboard.router import router as dashboard_router
 from app.identity import (
@@ -73,6 +74,7 @@ app.include_router(inventory_router)
 app.include_router(miner_control_router)
 app.include_router(agent_commands_router)
 app.include_router(agent_zones_router)
+app.include_router(agent_enrollment_router)
 app.include_router(components_router)
 app.include_router(locations_router)
 app.include_router(dashboard_router)
@@ -4167,24 +4169,27 @@ def minerops_ensure_pool_info_table():
 
 
 @app.post("/api/agent/pool-snapshots")
-async def agent_pool_snapshots(request: Request):
+async def agent_pool_snapshots(
+    request: Request,
+    authenticated_agent_id: str = Depends(require_agent_identity),
+    zone_service: AgentZoneService = Depends(get_agent_zone_service),
+):
     import json as _json
-    import os as _os
     import uuid as _uuid
 
-    expected_secret = (_os.getenv("MINEROPS_AGENT_SHARED_SECRET") or "").strip()
-    provided_secret = (
-        request.headers.get("X-MinerOps-Agent-Secret")
-        or request.headers.get("x-minerops-agent-secret")
-        or ""
-    ).strip()
-
-    if expected_secret and provided_secret != expected_secret:
-        raise HTTPException(status_code=401, detail="Invalid agent secret.")
+    routing = zone_service.routing_context(authenticated_agent_id)
+    if routing.routing_reason or routing.agent_zone_id is None:
+        raise HTTPException(
+            status_code=409,
+            detail=(
+                "Agent routing unavailable: "
+                + (routing.routing_reason or "agent_zone_unassigned")
+            ),
+        )
 
     body = await request.json()
 
-    agent_id = body.get("agent_id") or ""
+    agent_id = authenticated_agent_id
     snapshots = body.get("pool_snapshots") or body.get("snapshots") or []
 
     minerops_ensure_pool_info_table()
@@ -4236,28 +4241,34 @@ async def agent_pool_snapshots(request: Request):
                         """
                         SELECT id
                         FROM miners
-                        WHERE upper(current_mac) = upper(%s)
-                           OR host(current_ip) = %s
+                        WHERE agent_zone_id = %s
+                          AND (
+                              upper(current_mac) = upper(%s)
+                              OR host(current_ip) = %s
+                          )
                         LIMIT 1;
                         """,
-                        (mac, ip),
+                        (routing.agent_zone_id, mac, ip),
                     )
                 else:
                     cur.execute(
                         """
                         SELECT id
                         FROM miners
-                        WHERE host(current_ip) = %s
+                        WHERE agent_zone_id = %s
+                          AND host(current_ip) = %s
                         LIMIT 1;
                         """,
-                        (ip,),
+                        (routing.agent_zone_id, ip),
                     )
 
                 row = cur.fetchone()
 
-                if row:
-                    miner_id = row["id"]
-                    matched += 1
+                if not row:
+                    continue
+
+                miner_id = row["id"]
+                matched += 1
 
                 for pool in pools:
                     if not isinstance(pool, dict):
@@ -25402,8 +25413,19 @@ document.addEventListener("DOMContentLoaded", loadSetup);
 # -----------------------------
 
 @app.get("/api/agent/known-miners")
-async def minerops_agent_known_miners(request: Request):
-    minerops_require_agent_secret(request)
+async def minerops_agent_known_miners(
+    authenticated_agent_id: str = Depends(require_agent_identity),
+    zone_service: AgentZoneService = Depends(get_agent_zone_service),
+):
+    routing = zone_service.routing_context(authenticated_agent_id)
+    if routing.routing_reason or routing.agent_zone_id is None:
+        raise HTTPException(
+            status_code=409,
+            detail=(
+                "Agent routing unavailable: "
+                + (routing.routing_reason or "agent_zone_unassigned")
+            ),
+        )
 
     conn = await minerops_command_db_connect()
 
@@ -25420,8 +25442,10 @@ async def minerops_agent_known_miners(request: Request):
             FROM miners
             LEFT JOIN rooms ON rooms.id = miners.room_id
             WHERE miners.current_ip IS NOT NULL
+              AND miners.agent_zone_id = $1::uuid
             ORDER BY rooms.sort_order NULLS LAST, rooms.name NULLS LAST, miners.current_ip
-            """
+            """,
+            str(routing.agent_zone_id),
         )
     finally:
         await conn.close()
@@ -26964,10 +26988,22 @@ async def minerops_agent_discovery_review(
 
 
 @app.post("/api/agent/miner-enrichment")
-async def minerops_agent_miner_enrichment(request: Request):
+async def minerops_agent_miner_enrichment(
+    request: Request,
+    authenticated_agent_id: str = Depends(require_agent_identity),
+    zone_service: AgentZoneService = Depends(get_agent_zone_service),
+):
     import json
 
-    await minerops_require_agent_secret(request)
+    routing = zone_service.routing_context(authenticated_agent_id)
+    if routing.routing_reason or routing.agent_zone_id is None:
+        raise HTTPException(
+            status_code=409,
+            detail=(
+                "Agent routing unavailable: "
+                + (routing.routing_reason or "agent_zone_unassigned")
+            ),
+        )
 
     payload = await request.json()
 
@@ -27013,16 +27049,18 @@ async def minerops_agent_miner_enrichment(request: Request):
                 SELECT id::text AS id
                 FROM miners
                 WHERE id = $1::uuid
+                  AND agent_zone_id = $2::uuid
                 LIMIT 1
-            """, miner_id)
+            """, miner_id, str(routing.agent_zone_id))
 
         if miner is None and ip_address:
             miner = await conn.fetchrow("""
                 SELECT id::text AS id
                 FROM miners
                 WHERE current_ip = $1::inet
+                  AND agent_zone_id = $2::uuid
                 LIMIT 1
-            """, ip_address)
+            """, ip_address, str(routing.agent_zone_id))
 
         if miner is None:
             raise HTTPException(status_code=404, detail="Miner not found.")
@@ -27110,10 +27148,22 @@ async def minerops_agent_miner_enrichment(request: Request):
 
 
 @app.post("/api/agent/miner-enrichment-v2")
-async def minerops_agent_miner_enrichment_v2(request: Request):
+async def minerops_agent_miner_enrichment_v2(
+    request: Request,
+    authenticated_agent_id: str = Depends(require_agent_identity),
+    zone_service: AgentZoneService = Depends(get_agent_zone_service),
+):
     import json
 
-    await minerops_require_agent_secret(request)
+    routing = zone_service.routing_context(authenticated_agent_id)
+    if routing.routing_reason or routing.agent_zone_id is None:
+        raise HTTPException(
+            status_code=409,
+            detail=(
+                "Agent routing unavailable: "
+                + (routing.routing_reason or "agent_zone_unassigned")
+            ),
+        )
 
     payload = await request.json()
 
@@ -27175,16 +27225,18 @@ async def minerops_agent_miner_enrichment_v2(request: Request):
                 SELECT id::text AS id, host(current_ip) AS current_ip, current_mac, notes
                 FROM miners
                 WHERE id = $1::uuid
+                  AND agent_zone_id = $2::uuid
                 LIMIT 1
-            """, miner_id)
+            """, miner_id, str(routing.agent_zone_id))
 
         if source is None and ip_address:
             source = await conn.fetchrow("""
                 SELECT id::text AS id, host(current_ip) AS current_ip, current_mac, notes
                 FROM miners
                 WHERE current_ip = $1::inet
+                  AND agent_zone_id = $2::uuid
                 LIMIT 1
-            """, ip_address)
+            """, ip_address, str(routing.agent_zone_id))
 
         if source is None:
             raise HTTPException(status_code=404, detail="Source miner not found.")
@@ -27199,8 +27251,9 @@ async def minerops_agent_miner_enrichment_v2(request: Request):
                 SELECT id::text AS id, host(current_ip) AS current_ip, current_mac, notes
                 FROM miners
                 WHERE upper(current_mac) = upper($1)
+                  AND agent_zone_id = $2::uuid
                 LIMIT 1
-            """, mac)
+            """, mac, str(routing.agent_zone_id))
 
             if existing_mac_miner and existing_mac_miner["id"] != source_id:
                 target_id = existing_mac_miner["id"]
@@ -27285,7 +27338,8 @@ async def minerops_agent_miner_enrichment_v2(request: Request):
                         matched_miner_id = $2::uuid,
                         updated_at = now()
                     WHERE ip_address = $1::inet
-                """, ip_address, target_id)
+                      AND agent_zone_id = $3::uuid
+                """, ip_address, target_id, str(routing.agent_zone_id))
             except Exception:
                 pass
 
@@ -27324,10 +27378,22 @@ async def minerops_agent_miner_enrichment_v2(request: Request):
 
 
 @app.post("/api/agent/miner-enrichment-v3")
-async def minerops_agent_miner_enrichment_v3(request: Request):
+async def minerops_agent_miner_enrichment_v3(
+    request: Request,
+    authenticated_agent_id: str = Depends(require_agent_identity),
+    zone_service: AgentZoneService = Depends(get_agent_zone_service),
+):
     import json
 
-    await minerops_require_agent_secret(request)
+    routing = zone_service.routing_context(authenticated_agent_id)
+    if routing.routing_reason or routing.agent_zone_id is None:
+        raise HTTPException(
+            status_code=409,
+            detail=(
+                "Agent routing unavailable: "
+                + (routing.routing_reason or "agent_zone_unassigned")
+            ),
+        )
 
     payload = await request.json()
 
@@ -27384,8 +27450,9 @@ async def minerops_agent_miner_enrichment_v3(request: Request):
                 SELECT id::text AS id
                 FROM miners
                 WHERE upper(current_mac) = upper($1)
+                  AND agent_zone_id = $2::uuid
                 LIMIT 1
-            """, mac)
+            """, mac, str(routing.agent_zone_id))
 
             if row:
                 target_id = row["id"]
@@ -27396,8 +27463,9 @@ async def minerops_agent_miner_enrichment_v3(request: Request):
                 SELECT id::text AS id
                 FROM miners
                 WHERE id = $1::uuid
+                  AND agent_zone_id = $2::uuid
                 LIMIT 1
-            """, miner_id)
+            """, miner_id, str(routing.agent_zone_id))
 
             if row:
                 target_id = row["id"]
@@ -27408,8 +27476,9 @@ async def minerops_agent_miner_enrichment_v3(request: Request):
                 SELECT id::text AS id
                 FROM miners
                 WHERE current_ip = $1::inet
+                  AND agent_zone_id = $2::uuid
                 LIMIT 1
-            """, ip_address)
+            """, ip_address, str(routing.agent_zone_id))
 
             if row:
                 target_id = row["id"]
@@ -27473,6 +27542,7 @@ async def minerops_agent_miner_enrichment_v3(request: Request):
                         raw_payload = COALESCE(raw_payload, '{}'::jsonb) || $7::jsonb,
                         updated_at = now()
                     WHERE ip_address = $1::inet
+                      AND agent_zone_id = $8::uuid
                 """,
                     ip_address,
                     mac,
@@ -27480,7 +27550,8 @@ async def minerops_agent_miner_enrichment_v3(request: Request):
                     hostname,
                     miner_sn,
                     target_id,
-                    json.dumps({"enrichment": payload, "matched_by": matched_by})
+                    json.dumps({"enrichment": payload, "matched_by": matched_by}),
+                    str(routing.agent_zone_id)
                 )
 
             updated = await conn.fetchrow("""
@@ -27521,13 +27592,15 @@ async def minerops_agent_miner_enrichment_v3(request: Request):
                     raw_payload = COALESCE(raw_payload, '{}'::jsonb) || $6::jsonb,
                     updated_at = now()
                 WHERE ip_address = $1::inet
+                  AND agent_zone_id = $7::uuid
             """,
                 ip_address,
                 mac,
                 model,
                 hostname,
                 miner_sn,
-                json.dumps({"enrichment": payload, "reason": "no_inventory_match"})
+                json.dumps({"enrichment": payload, "reason": "no_inventory_match"}),
+                str(routing.agent_zone_id)
             )
 
         return {
@@ -29520,8 +29593,11 @@ async def minerops_inject_clean_detail_v3(request, call_next):
 from fastapi import Request as MinerOpsApi3Request, HTTPException as MinerOpsApi3HTTPException
 
 @app.post("/api/agent/api3-enrichment")
-async def minerops_agent_api3_enrichment(request: MinerOpsApi3Request):
-    import os
+async def minerops_agent_api3_enrichment(
+    request: MinerOpsApi3Request,
+    authenticated_agent_id: str = Depends(require_agent_identity),
+    zone_service: AgentZoneService = Depends(get_agent_zone_service),
+):
     import json
     import uuid
     import psycopg
@@ -29559,19 +29635,23 @@ async def minerops_agent_api3_enrichment(request: MinerOpsApi3Request):
             return value
         return [value]
 
-    expected_secret = os.getenv("MINEROPS_AGENT_SHARED_SECRET", "")
-    supplied_secret = (
-        request.headers.get("x-minerops-agent-secret")
-        or request.headers.get("x-agent-secret")
-        or ""
-    )
-
-    if expected_secret and supplied_secret != expected_secret:
-        raise MinerOpsApi3HTTPException(status_code=401, detail="Invalid agent secret.")
+    routing = zone_service.routing_context(authenticated_agent_id)
+    if (
+        routing.routing_reason
+        or routing.agent_zone_id is None
+        or routing.site_id is None
+    ):
+        raise MinerOpsApi3HTTPException(
+            status_code=409,
+            detail=(
+                "Agent routing unavailable: "
+                + (routing.routing_reason or "agent_zone_unassigned")
+            ),
+        )
 
     body = await request.json()
-    agent_id = as_text(body.get("agent_id")) or "unknown-agent"
-    site_name = as_text(body.get("site_name")) or "unknown-site"
+    agent_id = authenticated_agent_id
+    site_name = None
     items = body.get("items") or []
 
     if not isinstance(items, list):
@@ -29592,6 +29672,20 @@ async def minerops_agent_api3_enrichment(request: MinerOpsApi3Request):
         conn = get_db_connection()
 
         with conn.cursor(row_factory=psycopg.rows.dict_row) as cur:
+            cur.execute(
+                "SELECT name FROM sites WHERE id = %s",
+                (routing.site_id,),
+            )
+            site_row = cur.fetchone()
+
+            if not site_row:
+                raise MinerOpsApi3HTTPException(
+                    status_code=409,
+                    detail="Agent Site assignment no longer exists.",
+                )
+
+            site_name = str(site_row["name"])
+
             cur.execute(
                 """
                 ALTER TABLE miners
@@ -29772,10 +29866,11 @@ async def minerops_agent_api3_enrichment(request: MinerOpsApi3Request):
                         SELECT id
                         FROM miners
                         WHERE upper(current_mac) = upper(%s)
+                          AND agent_zone_id = %s
                         ORDER BY updated_at DESC NULLS LAST
                         LIMIT 1;
                         """,
-                        (mac,),
+                        (mac, routing.agent_zone_id),
                     )
                     row = cur.fetchone()
                     if row:
@@ -29787,15 +29882,19 @@ async def minerops_agent_api3_enrichment(request: MinerOpsApi3Request):
                         SELECT id
                         FROM miners
                         WHERE current_ip = %s::inet
+                          AND agent_zone_id = %s
                         ORDER BY updated_at DESC NULLS LAST
                         LIMIT 1;
                         """,
-                        (ip,),
+                        (ip, routing.agent_zone_id),
                     )
                     row = cur.fetchone()
                     if row:
                         miner_id = row["id"]
 
+                if miner_id is None:
+                    continue
+
                 if miner_id is not None:
                     matched += 1