Phase 4: cloud backend — licensing, heartbeat, site management

- New cloud_backend/ FastAPI service on port 8001 (SQLite for dev, swappable to PostgreSQL)
- Endpoints: sysadmin auth (JWT), site registration, lock/unlock, heartbeat (X-Site-ID + X-Site-Key headers)
- Default sysadmin seeded on first startup from ADMIN_USERNAME/ADMIN_PASSWORD env vars
- cloud_backend added to docker-compose.yml with persistent data volume at ./data/cloud/
- local_backend cloud_sync.py updated to use correct /api/heartbeat/ endpoint with header auth
- local_backend config.py: added SITE_KEY setting
- Smoke tested: login, register site, heartbeat, lock, unlock, list all pass

cloud_backend/routers/auth.py

@@ -0,0 +1,18 @@
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.orm import Session
+
+from auth_utils import verify_password, create_access_token
+from database import get_db
+from models.admin import Admin
+from schemas.admin import LoginRequest, TokenOut
+
+router = APIRouter()
+
+
+@router.post("/login", response_model=TokenOut)
+def login(body: LoginRequest, db: Session = Depends(get_db)):
+    admin = db.query(Admin).filter(Admin.username == body.username).first()
+    if not admin or not verify_password(body.password, admin.password_hash):
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid credentials")
+    token = create_access_token({"sub": admin.username, "role": admin.role})
+    return TokenOut(access_token=token)

cloud_backend/routers/heartbeat.py

@@ -0,0 +1,37 @@
+from datetime import datetime, timezone
+from fastapi import APIRouter, Depends, HTTPException, Header, Request, status
+from passlib.context import CryptContext
+from sqlalchemy.orm import Session
+
+from database import get_db
+from models.site import Site
+from schemas.site import HeartbeatRequest, HeartbeatResponse
+
+router = APIRouter()
+_pwd = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+
+@router.post("/", response_model=HeartbeatResponse)
+def heartbeat(
+    body: HeartbeatRequest,
+    request: Request,
+    x_site_id: str = Header(..., alias="X-Site-ID"),
+    x_site_key: str = Header(..., alias="X-Site-Key"),
+    db: Session = Depends(get_db),
+):
+    site = db.query(Site).filter(Site.site_id == x_site_id).first()
+    if not site or not _pwd.verify(x_site_key, site.secret_key_hash):
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid site credentials")
+
+    now = datetime.now(timezone.utc)
+    site.last_seen_at = now
+    site.last_seen_ip = request.client.host if request.client else None
+    db.commit()
+
+    licensed = site.is_active and (site.license_expires_at.replace(tzinfo=timezone.utc) > now)
+    return HeartbeatResponse(
+        licensed=licensed,
+        locked=site.is_locked,
+        lock_reason=site.lock_reason,
+        expires_at=site.license_expires_at,
+    )

cloud_backend/routers/sites.py

@@ -0,0 +1,90 @@
+import secrets
+import uuid
+from passlib.context import CryptContext
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.orm import Session
+
+from auth_utils import get_current_admin
+from database import get_db
+from models.site import Site
+from schemas.site import SiteCreate, SiteUpdate, SiteOut, SiteCreatedOut, LockRequest
+
+router = APIRouter()
+_pwd = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+
+@router.get("/", response_model=list[SiteOut])
+def list_sites(db: Session = Depends(get_db), _=Depends(get_current_admin)):
+    return db.query(Site).all()
+
+
+@router.post("/", response_model=SiteCreatedOut, status_code=status.HTTP_201_CREATED)
+def create_site(body: SiteCreate, db: Session = Depends(get_db), _=Depends(get_current_admin)):
+    raw_key = secrets.token_urlsafe(32)
+    site = Site(
+        site_id=str(uuid.uuid4()),
+        name=body.name,
+        owner_name=body.owner_name,
+        contact_email=body.contact_email,
+        secret_key_hash=_pwd.hash(raw_key),
+        license_expires_at=body.license_expires_at,
+    )
+    db.add(site)
+    db.commit()
+    db.refresh(site)
+    data = SiteOut.model_validate(site).model_dump()
+    data["secret_key"] = raw_key
+    return SiteCreatedOut(**data)
+
+
+@router.get("/{site_id}", response_model=SiteOut)
+def get_site(site_id: str, db: Session = Depends(get_db), _=Depends(get_current_admin)):
+    site = db.query(Site).filter(Site.site_id == site_id).first()
+    if not site:
+        raise HTTPException(status_code=404, detail="Site not found")
+    return site
+
+
+@router.put("/{site_id}", response_model=SiteOut)
+def update_site(site_id: str, body: SiteUpdate, db: Session = Depends(get_db), _=Depends(get_current_admin)):
+    site = db.query(Site).filter(Site.site_id == site_id).first()
+    if not site:
+        raise HTTPException(status_code=404, detail="Site not found")
+    for field, value in body.model_dump(exclude_none=True).items():
+        setattr(site, field, value)
+    db.commit()
+    db.refresh(site)
+    return site
+
+
+@router.post("/{site_id}/lock", response_model=SiteOut)
+def lock_site(site_id: str, body: LockRequest, db: Session = Depends(get_db), _=Depends(get_current_admin)):
+    site = db.query(Site).filter(Site.site_id == site_id).first()
+    if not site:
+        raise HTTPException(status_code=404, detail="Site not found")
+    site.is_locked = True
+    site.lock_reason = body.reason
+    db.commit()
+    db.refresh(site)
+    return site
+
+
+@router.post("/{site_id}/unlock", response_model=SiteOut)
+def unlock_site(site_id: str, db: Session = Depends(get_db), _=Depends(get_current_admin)):
+    site = db.query(Site).filter(Site.site_id == site_id).first()
+    if not site:
+        raise HTTPException(status_code=404, detail="Site not found")
+    site.is_locked = False
+    site.lock_reason = None
+    db.commit()
+    db.refresh(site)
+    return site
+
+
+@router.delete("/{site_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_site(site_id: str, db: Session = Depends(get_db), _=Depends(get_current_admin)):
+    site = db.query(Site).filter(Site.site_id == site_id).first()
+    if not site:
+        raise HTTPException(status_code=404, detail="Site not found")
+    db.delete(site)
+    db.commit()