Upload 18 files

core/auth.py

@@ -0,0 +1,37 @@
+from typing import Literal
+
+from fastapi import Header, HTTPException
+from pydantic import BaseModel
+
+
+class AuthUser(BaseModel):
+    username: str
+    role: Literal["admin", "sensitive_admin"]
+
+
+def issue_token(user: AuthUser) -> str:
+    return f"dev-token::{user.username}::{user.role}"
+
+
+def parse_token(token: str) -> AuthUser | None:
+    parts = token.split("::")
+    if len(parts) != 3 or parts[0] != "dev-token":
+        return None
+
+    username = parts[1]
+    role = parts[2]
+    if role not in {"admin", "sensitive_admin"}:
+        return None
+
+    return AuthUser(username=username, role=role)
+
+
+def get_current_web_user(authorization: str | None = Header(default=None)) -> AuthUser:
+    if not authorization or not authorization.lower().startswith("bearer "):
+        raise HTTPException(status_code=401, detail="Missing bearer token")
+
+    token = authorization[7:]
+    user = parse_token(token)
+    if user is None:
+        raise HTTPException(status_code=401, detail="Invalid token")
+    return user

core/config.py

@@ -0,0 +1,22 @@
+import os
+from pydantic import BaseModel
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    app_name: str = "G-Solution Backend"
+    api_prefix: str = "/api/v1"
+    mongo_uri: str = "mongodb://localhost:27017"
+    mongo_db: str = "g_solution"
+    storage_dir: str = "storage/screenshots"
+    media_prefix: str = "/media"
+    hf_token: str = ""
+    warmup_game_models: bool = False
+
+    class Config:
+        env_file = ".env"
+        env_file_encoding = "utf-8"
+        case_sensitive = False
+
+
+settings = Settings()

core/db.py

@@ -0,0 +1,51 @@
+from datetime import timezone
+
+from motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorDatabase
+from pymongo.errors import OperationFailure
+
+from app.core.config import settings
+
+_client: AsyncIOMotorClient | None = None
+
+
+def get_db() -> AsyncIOMotorDatabase:
+    global _client
+    if _client is None:
+        _client = AsyncIOMotorClient(
+            settings.mongo_uri,
+            tz_aware=True,
+            tzinfo=timezone.utc,
+        )
+    return _client[settings.mongo_db]
+
+
+async def ensure_indexes() -> None:
+    db = get_db()
+
+    async def safe_create_index(collection, keys, **options) -> None:
+        """Create index and ignore already-existing/conflicting definitions."""
+        try:
+            await collection.create_index(keys, **options)
+        except OperationFailure as exc:
+            # Atlas/PyMongo can raise conflicts when an index with same name/key
+            # already exists but with different options (e.g., unique vs non-unique).
+            if exc.code in {85, 86}:
+                return
+            raise
+
+    await safe_create_index(db.devices, "device_id", unique=True)
+    await safe_create_index(db.policies, "device_id", unique=True)
+    await safe_create_index(db.key_states, "device_id", unique=True)
+    await safe_create_index(db.key_states, "expires_at")
+    await safe_create_index(db.key_states, "lock_until")
+    await safe_create_index(db.violations, "device_id")
+    await safe_create_index(db.violations, "timestamp")
+    await safe_create_index(db.violations, "expires_at")
+    await safe_create_index(db.screenshot_audit, "created_at")
+    await safe_create_index(db.alert_audit, "created_at")
+    await safe_create_index(db.alert_audit, "type")
+    await safe_create_index(db.url_verdicts, "url", unique=True)
+    await safe_create_index(db.url_verdicts, "verdict")
+    await safe_create_index(db.game_lock_reviews, "review_id", unique=True)
+    await safe_create_index(db.game_lock_reviews, "status")
+    await safe_create_index(db.game_lock_reviews, "created_at")

models/schemas.py

@@ -0,0 +1,146 @@
+from datetime import datetime, timedelta, timezone
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class LoginRequest(BaseModel):
+    username: str
+    password: str
+
+
+class LoginResponse(BaseModel):
+    token: str
+    role: Literal["admin", "sensitive_admin"] = "admin"
+    expires_in_seconds: int = 3600
+
+
+class RegisterDeviceRequest(BaseModel):
+    device_id: str
+    hostname: str
+    os_version: str
+    agent_version: str
+
+
+class RegisterDeviceResponse(BaseModel):
+    registered: bool = True
+    session_token: str
+
+
+class HeartbeatRequest(BaseModel):
+    device_id: str
+    active_restriction_window: bool
+    uptime_seconds: int = 0
+
+
+class HeartbeatResponse(BaseModel):
+    accepted: bool = True
+    server_time: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+class DeviceStatusRow(BaseModel):
+    device_id: str
+    hostname: str
+    agent_version: str
+    os_version: str
+    last_heartbeat_at: datetime | None = None
+    active_restriction_window: bool = False
+
+
+class DeviceStatusResponse(DeviceStatusRow):
+    is_online: bool = False
+
+
+class TimeWindow(BaseModel):
+    day_of_week: Literal["mon", "tue", "wed", "thu", "fri", "sat", "sun"]
+    start: str = Field(description="HH:MM")
+    end: str = Field(description="HH:MM")
+
+
+class DevicePolicy(BaseModel):
+    blocked_executables: list[str] = []
+    blocked_domains: list[str] = []
+    restriction_windows: list[TimeWindow] = []
+
+
+class UpdatePolicyRequest(BaseModel):
+    device_id: str
+    policy: DevicePolicy
+
+
+class ScreenshotIngestResponse(BaseModel):
+    screenshot_id: str
+    queued: bool = True
+
+
+class ViolationScreenshot(BaseModel):
+    screenshot_id: str
+    device_id: str
+    timestamp: str
+    filename: str
+    created_at: str
+    image_url: str
+    confidence: float
+    reason: str
+    visibility_scope: Literal["admin", "sensitive_admin"] = "admin"
+    ocr_urls: list[str] = []
+
+
+class GameReviewItem(BaseModel):
+    review_id: str
+    screenshot_id: str
+    device_id: str
+    timestamp: str
+    status: Literal["pending", "approved", "rejected"]
+    reason: str
+    ocr_urls: list[str] = []
+    created_at: datetime
+
+
+class GameReviewDecisionRequest(BaseModel):
+    review_id: str
+    approve_lock: bool
+
+
+class GameReviewDecisionResponse(BaseModel):
+    updated: bool
+
+
+class KeyGenerateRequest(BaseModel):
+    device_id: str
+
+
+class KeyGenerateResponse(BaseModel):
+    device_id: str
+    key: str
+    expires_at: datetime
+
+
+class KeyValidateRequest(BaseModel):
+    device_id: str
+    key: str
+
+
+class KeyValidateResponse(BaseModel):
+    valid: bool
+    lock_until: datetime | None = None
+
+
+class AlertEvent(BaseModel):
+    device_id: str
+    type: Literal[
+        "wrong_key",
+        "policy_violation",
+        "process_killed",
+        "info",
+        "device_status",
+        "sensitive_detected",
+        "game_lock_review_required",
+        "game_lock_review_decision",
+    ]
+    message: str
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+def lock_until_5_minutes() -> datetime:
+    return datetime.now(timezone.utc) + timedelta(minutes=5)

routers/__init__.py

@@ -0,0 +1,3 @@
+from app.routers import alerts, auth, devices, keys, policy, reviews, screenshots
+
+__all__ = ["auth", "devices", "policy", "screenshots", "keys", "alerts", "reviews"]

routers/alerts.py

@@ -0,0 +1,33 @@
+from fastapi import APIRouter, WebSocket, WebSocketDisconnect
+
+from app.services.alert_hub import alert_hub
+
+router = APIRouter(prefix="/alerts", tags=["alerts"])
+
+
+@router.websocket("/ws/admin")
+async def ws_admin(websocket: WebSocket) -> None:
+    await alert_hub.connect_admin(websocket)
+    try:
+        while True:
+            message = await websocket.receive_text()
+            if message == "ping":
+                await websocket.send_text("pong")
+    except WebSocketDisconnect:
+        alert_hub.disconnect_admin(websocket)
+    except Exception:
+        alert_hub.disconnect_admin(websocket)
+
+
+@router.websocket("/ws/device/{device_id}")
+async def ws_device(websocket: WebSocket, device_id: str) -> None:
+    await alert_hub.connect_device(device_id, websocket)
+    try:
+        while True:
+            message = await websocket.receive_text()
+            if message == "ping":
+                await websocket.send_text("pong")
+    except WebSocketDisconnect:
+        alert_hub.disconnect_device(device_id, websocket)
+    except Exception:
+        alert_hub.disconnect_device(device_id, websocket)

routers/auth.py

@@ -0,0 +1,19 @@
+from fastapi import APIRouter, HTTPException
+
+from app.core.auth import AuthUser, issue_token
+from app.models.schemas import LoginRequest, LoginResponse
+
+router = APIRouter(prefix="/auth", tags=["auth"])
+
+
+@router.post("/login", response_model=LoginResponse)
+def login(payload: LoginRequest) -> LoginResponse:
+    if payload.username == "admin" and payload.password == "admin123":
+        user = AuthUser(username="admin", role="admin")
+        return LoginResponse(token=issue_token(user), role=user.role)
+
+    if payload.username == "admin_sensitive" and payload.password == "safe123":
+        user = AuthUser(username="admin_sensitive", role="sensitive_admin")
+        return LoginResponse(token=issue_token(user), role=user.role)
+
+    raise HTTPException(status_code=401, detail="Invalid credentials")

routers/devices.py

@@ -0,0 +1,86 @@
+from datetime import datetime, timedelta, timezone
+
+from fastapi import APIRouter
+
+from app.models.schemas import (
+    DeviceStatusResponse,
+    DeviceStatusRow,
+    HeartbeatRequest,
+    HeartbeatResponse,
+    RegisterDeviceRequest,
+    RegisterDeviceResponse,
+)
+from app.services.alert_hub import alert_hub
+from app.services.repos import device_repo
+
+router = APIRouter(prefix="/devices", tags=["devices"])
+
+
+def _to_utc_aware(value: object) -> datetime | None:
+    if not isinstance(value, datetime):
+        return None
+    if value.tzinfo is None:
+        return value.replace(tzinfo=timezone.utc)
+    return value.astimezone(timezone.utc)
+
+
+@router.post("/register", response_model=RegisterDeviceResponse)
+async def register_device(payload: RegisterDeviceRequest) -> RegisterDeviceResponse:
+    await device_repo.upsert(
+        {
+            **payload.model_dump(),
+            "active_restriction_window": False,
+            "last_heartbeat_at": None,
+            "uptime_seconds": 0,
+        }
+    )
+    return RegisterDeviceResponse(session_token=f"session-{payload.device_id}")
+
+
+@router.post("/heartbeat", response_model=HeartbeatResponse)
+async def heartbeat(payload: HeartbeatRequest) -> HeartbeatResponse:
+    now = datetime.now(timezone.utc)
+    await device_repo.heartbeat(
+        payload.device_id,
+        payload.active_restriction_window,
+        payload.uptime_seconds,
+    )
+    await alert_hub.broadcast_admin(
+        {
+            "type": "device_status",
+            "device_id": payload.device_id,
+            "message": "Device heartbeat received",
+            "active_restriction_window": payload.active_restriction_window,
+            "uptime_seconds": payload.uptime_seconds,
+            "last_heartbeat_at": now.isoformat(),
+            "is_online": True,
+        }
+    )
+    return HeartbeatResponse()
+
+
+@router.get("", response_model=list[DeviceStatusResponse])
+async def list_devices() -> list[DeviceStatusResponse]:
+    now = datetime.now(timezone.utc)
+    online_threshold = now - timedelta(seconds=90)
+    rows = await device_repo.list()
+    output: list[DeviceStatusResponse] = []
+    for row in rows:
+        last_heartbeat_at = _to_utc_aware(row.get("last_heartbeat_at"))
+        output.append(
+            DeviceStatusResponse(
+                device_id=row.get("device_id", ""),
+                hostname=row.get("hostname", ""),
+                agent_version=row.get("agent_version", ""),
+                os_version=row.get("os_version", ""),
+                last_heartbeat_at=last_heartbeat_at,
+                active_restriction_window=bool(
+                    row.get("active_restriction_window", False)
+                ),
+                is_online=bool(
+                    last_heartbeat_at is not None
+                    and last_heartbeat_at >= online_threshold
+                ),
+            )
+        )
+    return output

routers/keys.py

@@ -0,0 +1,33 @@
+from fastapi import APIRouter
+from datetime import datetime, timezone
+
+from app.models.schemas import KeyGenerateRequest, KeyGenerateResponse, KeyValidateRequest, KeyValidateResponse
+from app.services.alert_hub import alert_hub
+from app.services.key_service import key_service
+from app.core.db import get_db
+
+router = APIRouter(prefix="/keys", tags=["keys"])
+
+
+@router.post("/generate", response_model=KeyGenerateResponse)
+async def generate_key(payload: KeyGenerateRequest) -> KeyGenerateResponse:
+    key, expires_at = await key_service.generate(payload.device_id)
+    return KeyGenerateResponse(device_id=payload.device_id, key=key, expires_at=expires_at)
+
+
+@router.post("/validate", response_model=KeyValidateResponse)
+async def validate_key(payload: KeyValidateRequest) -> KeyValidateResponse:
+    valid, lock_until, attempts = await key_service.validate(payload.device_id, payload.key)
+    if not valid:
+        event = {
+            "type": "wrong_key",
+            "device_id": payload.device_id,
+            "attempts": attempts,
+            "message": "Wrong key attempt detected. Local UI locked for 5 minutes.",
+            "created_at": datetime.now(timezone.utc),
+        }
+        await get_db().alert_audit.insert_one(event)
+        await alert_hub.broadcast_admin(
+            event
+        )
+    return KeyValidateResponse(valid=valid, lock_until=lock_until)

routers/policy.py

@@ -0,0 +1,20 @@
+from fastapi import APIRouter
+
+from app.models.schemas import DevicePolicy, UpdatePolicyRequest
+from app.services.repos import policy_repo
+
+router = APIRouter(prefix="/policy", tags=["policy"])
+
+
+@router.post("/update")
+async def update_policy(payload: UpdatePolicyRequest) -> dict[str, str]:
+    await policy_repo.set(payload.device_id, payload.policy.model_dump())
+    return {"status": "updated"}
+
+
+@router.get("/{device_id}", response_model=DevicePolicy)
+async def get_policy(device_id: str) -> DevicePolicy:
+    doc = await policy_repo.get(device_id)
+    if doc is None:
+        return DevicePolicy()
+    return DevicePolicy(**doc.get("policy", {}))

routers/reviews.py

@@ -0,0 +1,52 @@
+from fastapi import APIRouter, Depends, HTTPException
+
+from app.core.auth import AuthUser, get_current_web_user
+from app.models.schemas import GameReviewDecisionRequest, GameReviewDecisionResponse, GameReviewItem
+from app.services.alert_hub import alert_hub
+from app.services.repos import review_repo
+
+router = APIRouter(prefix="/reviews", tags=["reviews"])
+
+
+def _require_admin(user: AuthUser) -> None:
+    if user.role != "admin":
+        raise HTTPException(status_code=403, detail="Only admin account can review game lock requests")
+
+
+@router.get("/pending", response_model=list[GameReviewItem])
+async def list_pending_reviews(user: AuthUser = Depends(get_current_web_user)) -> list[GameReviewItem]:
+    _require_admin(user)
+    rows = await review_repo.list_pending()
+    return [
+        GameReviewItem(
+            review_id=str(row.get("review_id", "")),
+            screenshot_id=str(row.get("screenshot_id", "")),
+            device_id=str(row.get("device_id", "")),
+            timestamp=str(row.get("timestamp", "")),
+            status=str(row.get("status", "pending")),
+            reason=str(row.get("reason", "")),
+            ocr_urls=[str(x) for x in row.get("ocr_urls", [])],
+            created_at=row.get("created_at"),
+        )
+        for row in rows
+    ]
+
+
+@router.post("/decision", response_model=GameReviewDecisionResponse)
+async def decide_review(
+    payload: GameReviewDecisionRequest,
+    user: AuthUser = Depends(get_current_web_user),
+) -> GameReviewDecisionResponse:
+    _require_admin(user)
+    updated = await review_repo.decide(payload.review_id, payload.approve_lock, user.username)
+    if updated:
+        await alert_hub.broadcast_admin(
+            {
+                "type": "game_lock_review_decision",
+                "device_id": "n/a",
+                "message": "Admin submitted lock decision",
+                "review_id": payload.review_id,
+                "approve_lock": payload.approve_lock,
+            }
+        )
+    return GameReviewDecisionResponse(updated=updated)

routers/screenshots.py

@@ -0,0 +1,269 @@
+import asyncio
+import logging
+import uuid
+from datetime import datetime, timedelta, timezone
+
+from fastapi import APIRouter, Depends, File, Form, UploadFile
+
+from app.core.auth import AuthUser, get_current_web_user
+from app.core.config import settings
+from app.models.schemas import ScreenshotIngestResponse, ViolationScreenshot
+from app.services.alert_hub import alert_hub
+from app.services.classifier import (
+    classify_game_with_ocr_llm,
+    classify_sensitive_content,
+    filter_cacheable_game_urls,
+)
+from app.services.policy_window import is_restriction_active
+from app.services.repos import (
+    audit_repo,
+    policy_repo,
+    review_repo,
+    url_verdict_repo,
+    violation_repo,
+)
+from app.services.storage import storage_service
+
+router = APIRouter(prefix="/screenshots", tags=["screenshots"])
+logger = logging.getLogger(__name__)
+
+
+async def _cleanup_expired_violations() -> None:
+    expired = await violation_repo.list_expired()
+    for row in expired:
+        absolute_path = row.get("absolute_path")
+        if isinstance(absolute_path, str):
+            storage_service.delete(absolute_path)
+    await violation_repo.delete_expired()
+
+
+@router.post("/ingest", response_model=ScreenshotIngestResponse)
+async def ingest_screenshot(
+    device_id: str = Form(...),
+    timestamp: str = Form(...),
+    suspected_game: bool = Form(False),
+    file: UploadFile = File(...),
+) -> ScreenshotIngestResponse:
+    screenshot_id = str(uuid.uuid4())
+    _, absolute_path, stored_name = await storage_service.save_upload(file)
+    logger.info(
+        "ingest start screenshot_id=%s device_id=%s filename=%s suspected_game=%s",
+        screenshot_id,
+        device_id,
+        file.filename or "unknown.png",
+        suspected_game,
+    )
+
+    try:
+        moment = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
+    except ValueError:
+        moment = datetime.now(timezone.utc)
+    policy_doc = await policy_repo.get(device_id)
+    policy_payload = policy_doc.get("policy", {}) if policy_doc else {}
+    windows = policy_payload.get("restriction_windows", [])
+    if not is_restriction_active(windows, moment):
+        storage_service.delete(absolute_path)
+        logger.info(
+            "ingest drop screenshot_id=%s reason=outside_restriction_window",
+            screenshot_id,
+        )
+        await audit_repo.log(
+            {
+                "screenshot_id": screenshot_id,
+                "device_id": device_id,
+                "timestamp": timestamp,
+                "filename": file.filename or "unknown.png",
+                "action": "deleted_outside_window",
+                "reason": "outside_restriction_window",
+                "created_at": datetime.now(timezone.utc),
+            }
+        )
+        return ScreenshotIngestResponse(screenshot_id=screenshot_id)
+
+    game_task = asyncio.to_thread(
+        classify_game_with_ocr_llm,
+        absolute_path,
+        file.filename or "capture.png",
+        suspected_game,
+    )
+    sensitive_task = asyncio.to_thread(
+        classify_sensitive_content,
+        absolute_path,
+        file.filename or "capture.png",
+    )
+    game_raw, sensitive_raw = await asyncio.gather(game_task, sensitive_task, return_exceptions=True)
+
+    if isinstance(game_raw, Exception):
+        logger.warning("ingest game-check-error screenshot_id=%s err=%s", screenshot_id, repr(game_raw))
+        game_result = {
+            "verdict": "not_game",
+            "confidence": 0.1,
+            "reason": "game-check-error",
+            "urls": [],
+            "source": "error-fallback",
+        }
+    else:
+        game_result = game_raw
+
+    if isinstance(sensitive_raw, Exception):
+        logger.warning("ingest sensitive-check-error screenshot_id=%s err=%s", screenshot_id, repr(sensitive_raw))
+        sensitive_detected, sensitive_confidence, sensitive_reason = (False, 0.0, "sensitive-check-error")
+    else:
+        sensitive_detected, sensitive_confidence, sensitive_reason = sensitive_raw
+
+    ocr_urls = [str(x) for x in game_result.get("urls", [])]
+    cacheable_urls = filter_cacheable_game_urls(ocr_urls)
+
+    cached_game_url = await url_verdict_repo.get_cached_game_url(cacheable_urls)
+    if cached_game_url:
+        logger.info(
+            "ingest cache-hit screenshot_id=%s game_url=%s",
+            screenshot_id,
+            cached_game_url,
+        )
+        game_result = {
+            **game_result,
+            "verdict": "game",
+            "confidence": 0.99,
+            "reason": f"cached-game-url:{cached_game_url}",
+            "source": "url-cache",
+        }
+
+    verdict = str(game_result.get("verdict", "not_game"))
+    confidence = float(game_result.get("confidence", 0.1))
+    reason = str(game_result.get("reason", "no-game-evidence"))
+
+    if sensitive_detected:
+        logger.info(
+            "ingest verdict screenshot_id=%s verdict=sensitive confidence=%.2f reason=%s",
+            screenshot_id,
+            sensitive_confidence,
+            sensitive_reason,
+        )
+        image_url = f"{settings.media_prefix}/{stored_name}"
+        await violation_repo.insert(
+            {
+                "screenshot_id": screenshot_id,
+                "device_id": device_id,
+                "timestamp": timestamp,
+                "filename": file.filename or "unknown.png",
+                "created_at": datetime.now(timezone.utc).isoformat(),
+                "image_url": image_url,
+                "confidence": sensitive_confidence,
+                "reason": sensitive_reason,
+                "absolute_path": absolute_path,
+                "visibility_scope": "sensitive_admin",
+                "ocr_urls": ocr_urls,
+                "expires_at": datetime.now(timezone.utc) + timedelta(hours=24),
+            }
+        )
+        await alert_hub.broadcast_admin(
+            {
+                "type": "sensitive_detected",
+                "device_id": device_id,
+                "message": "Sensitive content detected. Routed to sensitive admin scope.",
+                "visibility_scope": "sensitive_admin",
+            }
+        )
+        await _cleanup_expired_violations()
+        return ScreenshotIngestResponse(screenshot_id=screenshot_id)
+
+    if verdict == "game":
+        await url_verdict_repo.upsert_game_urls(cacheable_urls, source=str(game_result.get("source", "llm")))
+
+    if verdict == "not_game":
+        storage_service.delete(absolute_path)
+        logger.info(
+            "ingest verdict screenshot_id=%s verdict=not_game confidence=%.2f reason=%s urls=%d",
+            screenshot_id,
+            confidence,
+            reason,
+            len(ocr_urls),
+        )
+        await audit_repo.log(
+            {
+                "screenshot_id": screenshot_id,
+                "device_id": device_id,
+                "timestamp": timestamp,
+                "filename": file.filename or "unknown.png",
+                "action": "deleted_non_violation",
+                "reason": reason,
+                "created_at": datetime.now(timezone.utc),
+            }
+        )
+        return ScreenshotIngestResponse(screenshot_id=screenshot_id)
+
+    image_url = f"{settings.media_prefix}/{stored_name}"
+    logger.info(
+        "ingest verdict screenshot_id=%s verdict=%s confidence=%.2f reason=%s urls=%d",
+        screenshot_id,
+        verdict,
+        confidence,
+        reason,
+        len(ocr_urls),
+    )
+    await violation_repo.insert(
+        {
+            "screenshot_id": screenshot_id,
+            "device_id": device_id,
+            "timestamp": timestamp,
+            "filename": file.filename or "unknown.png",
+            "created_at": datetime.now(timezone.utc).isoformat(),
+            "image_url": image_url,
+            "confidence": confidence,
+            "reason": reason,
+            "absolute_path": absolute_path,
+            "visibility_scope": "admin",
+            "ocr_urls": ocr_urls,
+            "expires_at": datetime.now(timezone.utc) + timedelta(hours=24),
+        }
+    )
+
+    if verdict == "uncertain":
+        review_id = str(uuid.uuid4())
+        await review_repo.create_pending(
+            {
+                "review_id": review_id,
+                "screenshot_id": screenshot_id,
+                "device_id": device_id,
+                "timestamp": timestamp,
+                "status": "pending",
+                "reason": reason,
+                "ocr_urls": ocr_urls,
+                "created_at": datetime.now(timezone.utc),
+            }
+        )
+        await alert_hub.broadcast_admin(
+            {
+                "type": "game_lock_review_required",
+                "device_id": device_id,
+                "message": "Model uncertain. Admin confirmation is required before lock.",
+                "review_id": review_id,
+                "screenshot_id": screenshot_id,
+                "ocr_urls": ocr_urls,
+            }
+        )
+
+    await _cleanup_expired_violations()
+    return ScreenshotIngestResponse(screenshot_id=screenshot_id)
+
+
+@router.get("/violations", response_model=list[ViolationScreenshot])
+async def list_violations(user: AuthUser = Depends(get_current_web_user)) -> list[ViolationScreenshot]:
+    await _cleanup_expired_violations()
+    rows = await violation_repo.list_active(user.role)
+    return [
+        ViolationScreenshot(
+            screenshot_id=row.get("screenshot_id", ""),
+            device_id=row.get("device_id", ""),
+            timestamp=row.get("timestamp", ""),
+            filename=row.get("filename", ""),
+            created_at=row.get("created_at", ""),
+            image_url=row.get("image_url", ""),
+            confidence=float(row.get("confidence", 0.0)),
+            reason=row.get("reason", ""),
+            visibility_scope=row.get("visibility_scope", "admin"),
+            ocr_urls=[str(x) for x in row.get("ocr_urls", [])],
+        )
+        for row in rows
+    ]

services/alert_hub.py

@@ -0,0 +1,48 @@
+from collections import defaultdict
+from typing import Any
+
+from fastapi import WebSocket
+
+
+class AlertHub:
+    def __init__(self) -> None:
+        self.admin_clients: set[WebSocket] = set()
+        self.device_clients: dict[str, set[WebSocket]] = defaultdict(set)
+
+    async def connect_admin(self, websocket: WebSocket) -> None:
+        await websocket.accept()
+        self.admin_clients.add(websocket)
+
+    async def connect_device(self, device_id: str, websocket: WebSocket) -> None:
+        await websocket.accept()
+        self.device_clients[device_id].add(websocket)
+
+    def disconnect_admin(self, websocket: WebSocket) -> None:
+        self.admin_clients.discard(websocket)
+
+    def disconnect_device(self, device_id: str, websocket: WebSocket) -> None:
+        if device_id in self.device_clients:
+            self.device_clients[device_id].discard(websocket)
+
+    async def broadcast_admin(self, payload: dict[str, Any]) -> None:
+        stale: list[WebSocket] = []
+        for client in self.admin_clients:
+            try:
+                await client.send_json(payload)
+            except Exception:
+                stale.append(client)
+        for client in stale:
+            self.disconnect_admin(client)
+
+    async def send_device(self, device_id: str, payload: dict[str, Any]) -> None:
+        stale: list[WebSocket] = []
+        for client in self.device_clients.get(device_id, set()):
+            try:
+                await client.send_json(payload)
+            except Exception:
+                stale.append(client)
+        for client in stale:
+            self.disconnect_device(device_id, client)
+
+
+alert_hub = AlertHub()

services/classifier.py

@@ -0,0 +1,1056 @@
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+MODELS_DIR = Path(__file__).resolve().parents[2] / "models"
+NSFW_CONFIG_PATH = MODELS_DIR / "config.json"
+NSFW_WEIGHTS_PATH = MODELS_DIR / "model.safetensors"
+NSFW_THRESHOLD = 0.75
+
+def _parse_csv_env(raw_value: str, default_csv: str) -> list[str]:
+    value = (raw_value or "").strip() or default_csv
+    return [x.strip() for x in value.split(",") if x.strip()]
+
+
+LOCAL_GAME_LLM_MODEL = os.getenv("GAME_LOCAL_LLM_MODEL", "Qwen/Qwen2.5-7B-Instruct")
+LOCAL_GAME_LLM_MODELS = _parse_csv_env(
+    os.getenv("GAME_LOCAL_LLM_MODELS", ""),
+    "Qwen/Qwen2.5-7B-Instruct,microsoft/Phi-3.5-mini-instruct,Qwen/Qwen2.5-0.5B-Instruct",
+)
+GAME_VLM_ENABLED = os.getenv("GAME_VLM_ENABLED", "1").strip().lower() not in {"0", "false", "no"}
+GAME_VLM_MODEL = os.getenv("GAME_VLM_MODEL", "Qwen/Qwen2.5-VL-3B-Instruct")
+GAME_VLM_MODELS = _parse_csv_env(
+    os.getenv("GAME_VLM_MODELS", ""),
+    f"{GAME_VLM_MODEL},HuggingFaceTB/SmolVLM2-2.2B-Instruct,Qwen/Qwen2.5-VL-7B-Instruct",
+)
+GAME_VLM_MAX_NEW_TOKENS = int(os.getenv("GAME_VLM_MAX_NEW_TOKENS", "120"))
+GAME_VLM_NOT_GAME_TRUST = float(os.getenv("GAME_VLM_NOT_GAME_TRUST", "0.70"))
+GAME_VLM_GAME_TRUST = float(os.getenv("GAME_VLM_GAME_TRUST", "0.88"))
+GAME_VLM_ALLOW_CPU = os.getenv("GAME_VLM_ALLOW_CPU", "0").strip().lower() in {"1", "true", "yes"}
+GAME_VLM_MIN_OCR_CHARS = int(os.getenv("GAME_VLM_MIN_OCR_CHARS", "40"))
+LOCAL_GAME_LLM_MAX_NEW_TOKENS = int(os.getenv("GAME_LOCAL_LLM_MAX_NEW_TOKENS", "160"))
+LOCAL_GAME_LLM_MAX_INPUT_TOKENS = int(os.getenv("GAME_LOCAL_LLM_MAX_INPUT_TOKENS", "2048"))
+LLM_MAX_CHARS = 3000
+
+_nsfw_runtime: dict[str, Any] | None = None
+_nsfw_error: str | None = None
+_ocr_reader: dict[str, Any] | None = None
+_ocr_error: str | None = None
+_game_llm_runtime: dict[str, Any] | None = None
+_game_llm_error: str | None = None
+_game_vlm_runtime: dict[str, Any] | None = None
+_game_vlm_error: str | None = None
+
+logger = logging.getLogger(__name__)
+
+GAME_KEYWORDS = {
+    "valorant",
+    "steam",
+    "roblox",
+    "league",
+    "dota",
+    "cs2",
+    "minecraft",
+    "epicgames",
+    "riot",
+    "crazygames",
+    "y8",
+    "miniclip",
+    "poki",
+    "friv",
+    "game",
+    "games",
+    "doodle",
+}
+
+SENSITIVE_KEYWORDS = {
+    "porn",
+    "sex",
+    "xxx",
+    "nsfw",
+    "adult",
+    "nude",
+    "erotic",
+}
+
+NON_DOMAIN_TLDS = {
+    "png",
+    "jpg",
+    "jpeg",
+    "gif",
+    "webp",
+    "svg",
+    "bmp",
+    "ico",
+    "mp4",
+    "mov",
+    "mkv",
+    "avi",
+    "webm",
+    "mp3",
+    "wav",
+    "json",
+    "xml",
+    "txt",
+    "pdf",
+    "zip",
+    "rar",
+    "7z",
+    "exe",
+    "dll",
+    "msi",
+    "css",
+    "js",
+    "ts",
+}
+
+STRONG_GAME_DOMAIN_HINTS = {
+    "crazygames",
+    "poki",
+    "y8",
+    "miniclip",
+    "friv",
+    "roblox",
+    "steam",
+    "steampowered",
+    "epicgames",
+    "riotgames",
+    "playvalorant",
+    "minecraft",
+    "leagueoflegends",
+    "dota2",
+}
+
+STRONG_GAME_UI_TERMS = {
+    "battle pass",
+    "matchmaking",
+    "ranked",
+    "headshot",
+    "crosshair",
+    "kill streak",
+    "victory",
+    "defeat",
+    "mission complete",
+    "level up",
+    "minimap",
+    "xp",
+    "hp",
+    "inventory",
+    "riot client",
+    "steam library",
+    "roblox",
+}
+
+MEDIUM_GAME_UI_TERMS = {
+    "new game",
+    "continue",
+    "start game",
+    "play now",
+    "arcade",
+    "lobby",
+    "multiplayer",
+}
+
+URL_REGEX = re.compile(r"(?:https?://)?(?:www\.)?[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}(?:/[^\s]*)?")
+
+ALLOWED_REASON_CODES = {
+        "game_domain_match",
+        "game_ui_terms",
+        "signal_plus_ocr",
+        "weak_generic_terms",
+        "conflicting_signals",
+        "no_game_evidence",
+}
+
+GAME_PROMPT = """
+You are a high-precision parental-control classifier.
+Primary objective: minimize false positives.
+Input fields:
+- suspected_game_signal: boolean
+- extracted_urls: list of urls/domains from OCR
+- ocr_text: raw OCR text from screenshot
+Decision policy:
+1) Return "game" only if at least one strong signal exists:
+     - known game domain/platform in extracted_urls, OR
+     - explicit in-game UI terms in ocr_text (ranked, lobby, battle pass, matchmaking, etc.), OR
+     - suspected_game_signal=true AND at least one medium OCR signal.
+2) Return "uncertain" only when signals are conflicting and neither side is clearly dominant.
+3) Return "not_game" for weak/generic words (game, games, play) without concrete game context.
+4) Prioritize precision over recall.
+Output:
+Return EXACT JSON only using this schema:
+{
+  "verdict": "game" | "not_game" | "uncertain",
+  "confidence": 0.0-1.0,
+    "reason": "reason_code"
+}
+Allowed reason codes:
+- game_domain_match
+- game_ui_terms
+- signal_plus_ocr
+- weak_generic_terms
+- conflicting_signals
+- no_game_evidence
+Do not output markdown, prose, or extra keys.
+""".strip()
+
+GAME_VLM_PROMPT = """
+You are a high-precision parental-control image classifier.
+Task: Determine whether the screenshot is a game screen.
+You are given:
+- screenshot image
+- suspected_game_signal: boolean
+- extracted_urls: OCR domains/urls
+- ocr_text_excerpt: OCR text from screenshot
+Rules:
+1) Output game only with clear visual/game evidence (game HUD, minimap, score, battle/menu, game site page).
+2) Output not_game for admin dashboards, IDEs, office docs, chat sites, social feeds, and generic browser pages.
+3) Prefer precision; avoid false positives.
+Return exact JSON:
+{
+    "verdict": "game" | "not_game" | "uncertain",
+    "confidence": 0.0-1.0,
+    "reason": "reason_code"
+}
+Allowed reason codes:
+- game_domain_match
+- game_ui_terms
+- signal_plus_ocr
+- weak_generic_terms
+- conflicting_signals
+- no_game_evidence
+No markdown. No extra keys.
+""".strip()
+
+
+def warmup_game_classifiers() -> dict[str, str]:
+    status: dict[str, str] = {}
+
+    if GAME_VLM_ENABLED:
+        vlm_runtime = _load_local_game_vlm_runtime()
+        if vlm_runtime is not None:
+            status["vlm"] = f"ready:{vlm_runtime.get('model_name', GAME_VLM_MODEL)}"
+        else:
+            status["vlm"] = f"unavailable:{_game_vlm_error or 'unknown'}"
+    else:
+        status["vlm"] = "disabled"
+
+    llm_runtime = _load_local_game_llm_runtime()
+    if llm_runtime is not None:
+        status["llm"] = f"ready:{llm_runtime.get('model_name', LOCAL_GAME_LLM_MODEL)}"
+    else:
+        status["llm"] = f"unavailable:{_game_llm_error or 'unknown'}"
+
+    ocr_runtime = _load_ocr_reader()
+    if ocr_runtime is not None:
+        status["ocr"] = f"ready:{ocr_runtime.get('backend', 'unknown')}"
+    else:
+        status["ocr"] = f"unavailable:{_ocr_error or 'unknown'}"
+
+    logger.info("game-classifier warmup status=%s", status)
+    return status
+
+
+def classify_screenshot(file_path: str, filename: str, suspected_game: bool) -> tuple[bool, float, str]:
+    game_result = classify_game_with_ocr_llm(file_path, filename, suspected_game)
+    verdict = game_result["verdict"]
+    confidence = float(game_result["confidence"])
+    reason = str(game_result["reason"])
+    if verdict == "game":
+        return True, confidence, reason
+    if verdict == "uncertain":
+        return True, max(confidence, 0.51), "uncertain-review"
+    return False, confidence, reason
+
+
+def classify_game_with_ocr_llm(file_path: str, filename: str, suspected_game: bool) -> dict[str, Any]:
+    ocr_text, urls = extract_ocr_text_and_urls(file_path)
+    logger.info(
+        "game-detect start file=%s suspected_game=%s ocr_len=%d urls=%d",
+        filename,
+        suspected_game,
+        len(ocr_text),
+        len(urls),
+    )
+
+    vlm = _classify_game_with_vlm(file_path, ocr_text, urls, suspected_game)
+    if vlm is not None:
+        vlm = _apply_precision_guard(vlm, ocr_text, urls, suspected_game)
+        logger.info(
+            "game-detect vlm verdict=%s confidence=%.2f reason=%s source=%s",
+            vlm["verdict"],
+            float(vlm["confidence"]),
+            vlm["reason"],
+            vlm.get("source", "vlm"),
+        )
+        if _should_accept_vlm_alone(vlm):
+            return {
+                "verdict": vlm["verdict"],
+                "confidence": vlm["confidence"],
+                "reason": vlm["reason"],
+                "ocr_text": ocr_text,
+                "urls": urls,
+                "source": vlm.get("source", "vlm"),
+            }
+
+    llm = _classify_game_with_llm(ocr_text, urls, suspected_game)
+    if llm is not None:
+        llm = _apply_precision_guard(llm, ocr_text, urls, suspected_game)
+        if vlm is not None:
+            llm = _merge_vlm_with_llm(vlm, llm)
+        logger.info(
+            "game-detect llm verdict=%s confidence=%.2f reason=%s source=%s",
+            llm["verdict"],
+            float(llm["confidence"]),
+            llm["reason"],
+            llm.get("source", "llm"),
+        )
+        return {
+            "verdict": llm["verdict"],
+            "confidence": llm["confidence"],
+            "reason": llm["reason"],
+            "ocr_text": ocr_text,
+            "urls": urls,
+            "source": llm.get("source", "llm"),
+        }
+
+    # Fallback heuristic path when model call is unavailable.
+    text_lower = ocr_text.lower()
+    keyword_hit = any(word in text_lower for word in GAME_KEYWORDS)
+    domain_hit = any(_is_game_like_domain(url) for url in urls)
+    if domain_hit or (suspected_game and keyword_hit):
+        logger.info(
+            "game-detect fallback verdict=game reason=ocr-keyword-heuristic domain_hit=%s keyword_hit=%s",
+            domain_hit,
+            keyword_hit,
+        )
+        return {
+            "verdict": "game",
+            "confidence": 0.78,
+            "reason": "ocr-keyword-heuristic",
+            "ocr_text": ocr_text,
+            "urls": urls,
+            "source": "heuristic",
+        }
+
+    if suspected_game:
+        logger.info(
+            "game-detect fallback verdict=uncertain reason=signal-without-clear-ocr"
+        )
+        return {
+            "verdict": "uncertain",
+            "confidence": 0.55,
+            "reason": "signal-without-clear-ocr",
+            "ocr_text": ocr_text,
+            "urls": urls,
+            "source": "heuristic",
+        }
+
+    logger.info("game-detect fallback verdict=not_game reason=no-game-evidence")
+    return {
+        "verdict": "not_game",
+        "confidence": 0.2,
+        "reason": "no-game-evidence",
+        "ocr_text": ocr_text,
+        "urls": urls,
+        "source": "heuristic",
+    }
+
+
+def _should_accept_vlm_alone(vlm_result: dict[str, Any]) -> bool:
+    verdict = str(vlm_result.get("verdict", ""))
+    confidence = float(vlm_result.get("confidence", 0.0))
+    if verdict == "not_game" and confidence >= GAME_VLM_NOT_GAME_TRUST:
+        return True
+    if verdict == "game" and confidence >= GAME_VLM_GAME_TRUST:
+        return True
+    return False
+
+
+def _merge_vlm_with_llm(vlm_result: dict[str, Any], llm_result: dict[str, Any]) -> dict[str, Any]:
+    vlm_verdict = str(vlm_result.get("verdict", ""))
+    llm_verdict = str(llm_result.get("verdict", ""))
+    vlm_conf = float(vlm_result.get("confidence", 0.0))
+
+    # Conservative merge: a high-confidence VLM not_game can veto LLM game.
+    if llm_verdict == "game" and vlm_verdict == "not_game" and vlm_conf >= GAME_VLM_NOT_GAME_TRUST:
+        return {
+            "verdict": "not_game",
+            "confidence": min(vlm_conf, 0.92),
+            "reason": "no_game_evidence",
+            "source": "vlm-veto",
+        }
+
+    return llm_result
+
+
+def extract_ocr_text_and_urls(file_path: str) -> tuple[str, list[str]]:
+    runtime = _load_ocr_reader()
+    if runtime is None:
+        logger.warning("ocr unavailable: reader is None")
+        return "", []
+
+    try:
+        backend = runtime["backend"]
+        reader = runtime["reader"]
+        if backend == "easyocr":
+            results = reader.readtext(file_path, detail=0, paragraph=True)
+            ocr_text = "\n".join(str(x) for x in results).strip()
+        elif backend == "rapidocr":
+            results, _elapsed = reader(file_path)
+            if not results:
+                ocr_text = ""
+            else:
+                # RapidOCR result item: [box, text, score]
+                ocr_text = "\n".join(str(item[1]) for item in results if len(item) > 1).strip()
+        else:
+            logger.warning("ocr unknown backend=%s", backend)
+            return "", []
+    except Exception:
+        logger.exception("ocr read failed for file=%s", file_path)
+        return "", []
+
+    raw_urls = URL_REGEX.findall(ocr_text)
+    normalized = []
+    for value in raw_urls:
+        item = _normalize_ocr_url(value)
+        if item is None:
+            continue
+        normalized.append(item)
+
+    # Keep order stable while deduplicating.
+    urls: list[str] = []
+    seen: set[str] = set()
+    for item in normalized:
+        if item in seen:
+            continue
+        seen.add(item)
+        urls.append(item)
+
+    logger.info("ocr extracted text_len=%d urls=%d", len(ocr_text), len(urls))
+
+    return ocr_text[:LLM_MAX_CHARS], urls
+
+
+def _load_ocr_reader() -> Any | None:
+    global _ocr_reader
+    global _ocr_error
+
+    if _ocr_reader is not None:
+        return _ocr_reader
+    if _ocr_error is not None:
+        return None
+
+    try:
+        from rapidocr_onnxruntime import RapidOCR
+
+        _ocr_reader = {
+            "backend": "rapidocr",
+            "reader": RapidOCR(),
+        }
+        logger.info("ocr reader initialized backend=rapidocr")
+        return _ocr_reader
+    except Exception as exc:
+        rapidocr_error = str(exc)
+        logger.warning("ocr rapidocr init failed: %s", rapidocr_error)
+
+    try:
+        import easyocr
+
+        _ocr_reader = {
+            "backend": "easyocr",
+            "reader": easyocr.Reader(["en","vi"], gpu=False),
+        }
+        logger.info("ocr reader initialized backend=easyocr")
+        return _ocr_reader
+    except Exception as exc:
+        _ocr_error = f"rapidocr={rapidocr_error}; easyocr={exc}"
+        logger.warning("ocr reader init failed all backends: %s", _ocr_error)
+        return None
+
+
+def _classify_game_with_vlm(
+    file_path: str,
+    ocr_text: str,
+    urls: list[str],
+    suspected_game: bool,
+) -> dict[str, Any] | None:
+    if not GAME_VLM_ENABLED:
+        return None
+    if not _should_run_vlm(ocr_text, urls, suspected_game):
+        return None
+
+    runtime = _load_local_game_vlm_runtime()
+    if runtime is None:
+        return None
+
+    model_name = str(runtime.get("model_name", GAME_VLM_MODEL))
+
+    payload = {
+        "suspected_game_signal": suspected_game,
+        "extracted_urls": urls,
+        "ocr_text_excerpt": ocr_text[:800],
+    }
+
+    try:
+        content = _run_local_game_vlm_generation(runtime, file_path, payload)
+    except Exception as exc:
+        logger.warning("vlm generation failed model=%s err=%s", model_name, repr(exc))
+        return None
+
+    parsed = _parse_llm_json(content)
+    if parsed is None:
+        logger.warning("vlm invalid json model=%s content=%s", model_name, content[:300])
+        return None
+
+    parsed["source"] = f"local-vlm:{model_name}"
+    return parsed
+
+
+def _should_run_vlm(ocr_text: str, urls: list[str], suspected_game: bool) -> bool:
+    if suspected_game:
+        return True
+    if any(_is_game_like_domain(url) for url in urls):
+        return True
+    if _has_any_term(ocr_text, STRONG_GAME_UI_TERMS):
+        return True
+    if len(ocr_text.strip()) >= GAME_VLM_MIN_OCR_CHARS:
+        return True
+    return False
+
+
+def _load_local_game_vlm_runtime() -> dict[str, Any] | None:
+    global _game_vlm_runtime
+    global _game_vlm_error
+
+    if _game_vlm_runtime is not None:
+        return _game_vlm_runtime
+    if _game_vlm_error is not None:
+        return None
+
+    try:
+        import torch
+        from PIL import Image
+        from transformers import AutoProcessor
+
+        try:
+            from transformers import Qwen2_5_VLForConditionalGeneration as QwenVLMClass
+        except Exception:
+            QwenVLMClass = None
+
+        try:
+            from transformers import AutoModelForImageTextToText as GenericVLMClass
+        except Exception:
+            GenericVLMClass = None
+
+        if QwenVLMClass is None and GenericVLMClass is None:
+            _game_vlm_error = "no-vlm-class-available-in-transformers"
+            logger.warning("vlm runtime unavailable: %s", _game_vlm_error)
+            return None
+
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+        if device == "cpu" and not GAME_VLM_ALLOW_CPU:
+            _game_vlm_error = "cpu-disabled-for-vlm"
+            logger.warning("vlm runtime skipped err=%s", _game_vlm_error)
+            return None
+
+        dtype = torch.float16 if device == "cuda" else torch.float32
+
+        errors: list[str] = []
+        for model_name in GAME_VLM_MODELS:
+            try:
+                processor = AutoProcessor.from_pretrained(model_name)
+
+                model = None
+                load_errors: list[str] = []
+                for candidate in (QwenVLMClass, GenericVLMClass):
+                    if candidate is None:
+                        continue
+                    try:
+                        kwargs: dict[str, Any] = {"torch_dtype": dtype}
+                        if device == "cuda":
+                            kwargs["device_map"] = "auto"
+                        else:
+                            kwargs["low_cpu_mem_usage"] = True
+                        model = candidate.from_pretrained(model_name, **kwargs)
+                        break
+                    except TypeError:
+                        try:
+                            kwargs = {"torch_dtype": dtype}
+                            model = candidate.from_pretrained(model_name, **kwargs)
+                            break
+                        except Exception as exc:
+                            load_errors.append(str(exc))
+                    except Exception as exc:
+                        load_errors.append(str(exc))
+
+                if model is None:
+                    raise RuntimeError(" | ".join(load_errors) if load_errors else "vlm-load-failed")
+
+                if device == "cpu":
+                    model.to(device)
+                model.eval()
+
+                _game_vlm_runtime = {
+                    "torch": torch,
+                    "Image": Image,
+                    "processor": processor,
+                    "model": model,
+                    "device": device,
+                    "model_name": model_name,
+                }
+                logger.info("vlm runtime initialized model=%s device=%s", model_name, device)
+                return _game_vlm_runtime
+            except Exception as exc:
+                logger.warning("vlm runtime init failed model=%s err=%s", model_name, str(exc))
+                errors.append(f"{model_name}: {exc}")
+
+        _game_vlm_error = " | ".join(errors) if errors else "vlm-load-failed"
+        logger.warning("vlm runtime init failed for all models err=%s", _game_vlm_error)
+        return None
+    except Exception as exc:
+        _game_vlm_error = str(exc)
+        logger.warning("vlm runtime init failed err=%s", _game_vlm_error)
+        return None
+
+
+def _run_local_game_vlm_generation(
+    runtime: dict[str, Any],
+    file_path: str,
+    payload: dict[str, Any],
+) -> str:
+    torch = runtime["torch"]
+    Image = runtime["Image"]
+    processor = runtime["processor"]
+    model = runtime["model"]
+    device = runtime["device"]
+
+    prompt = (
+        f"{GAME_VLM_PROMPT}\n\n"
+        "Input JSON:\n"
+        f"{json.dumps(payload, ensure_ascii=True)}\n\n"
+        "Return exact JSON only."
+    )
+
+    with Image.open(file_path) as img:
+        image = img.convert("RGB")
+
+        if hasattr(processor, "apply_chat_template"):
+            messages = [
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "image", "image": image},
+                        {"type": "text", "text": prompt},
+                    ],
+                }
+            ]
+            text = processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+            inputs = processor(text=[text], images=[image], padding=True, return_tensors="pt")
+        else:
+            inputs = processor(images=image, text=prompt, return_tensors="pt")
+
+        if hasattr(inputs, "to"):
+            inputs = inputs.to(device)
+        else:
+            inputs = {k: v.to(device) if hasattr(v, "to") else v for k, v in inputs.items()}
+
+        with torch.no_grad():
+            output_ids = model.generate(
+                **inputs,
+                max_new_tokens=GAME_VLM_MAX_NEW_TOKENS,
+                do_sample=False,
+            )
+
+    if hasattr(inputs, "get") and inputs.get("input_ids") is not None:
+        prompt_tokens = int(inputs["input_ids"].shape[1])
+        generated = output_ids[0][prompt_tokens:]
+        return processor.decode(generated, skip_special_tokens=True).strip()
+
+    return processor.batch_decode(output_ids, skip_special_tokens=True)[0].strip()
+
+
+def _classify_game_with_llm(ocr_text: str, urls: list[str], suspected_game: bool) -> dict[str, Any] | None:
+    if not ocr_text and not urls:
+        return None
+
+    user_payload = {
+        "suspected_game_signal": suspected_game,
+        "extracted_urls": urls,
+        "ocr_text": ocr_text,
+    }
+
+    runtime = _load_local_game_llm_runtime()
+    if runtime is None:
+        logger.warning("llm local runtime unavailable; fallback to heuristic")
+        return None
+
+    model_name = str(runtime.get("model_name", LOCAL_GAME_LLM_MODEL))
+    try:
+        content = _run_local_game_llm_generation(runtime, user_payload)
+    except Exception as exc:
+        logger.warning("llm local generation failed model=%s err=%s", model_name, repr(exc))
+        return None
+
+    parsed = _parse_llm_json(content)
+    if parsed is None:
+        logger.warning("llm invalid json model=%s content=%s", model_name, content[:300])
+        return None
+
+    parsed["source"] = f"local-llm:{model_name}"
+    return parsed
+
+
+def _build_game_prompt(user_payload: dict[str, Any]) -> str:
+    return (
+        f"{GAME_PROMPT}\n\n"
+        "Input JSON:\n"
+        f"{json.dumps(user_payload, ensure_ascii=True)}\n\n"
+        "Return exact JSON only."
+    )
+
+
+def _build_game_messages(user_payload: dict[str, Any]) -> list[dict[str, str]]:
+    return [
+        {"role": "system", "content": GAME_PROMPT},
+        {"role": "user", "content": json.dumps(user_payload, ensure_ascii=True)},
+    ]
+
+
+def _load_local_game_llm_runtime() -> dict[str, Any] | None:
+    global _game_llm_runtime
+    global _game_llm_error
+
+    if _game_llm_runtime is not None:
+        return _game_llm_runtime
+    if _game_llm_error is not None:
+        return None
+
+    try:
+        import torch
+        from transformers import AutoModelForCausalLM, AutoTokenizer
+
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+        dtype = torch.float16 if device == "cuda" else torch.float32
+
+        errors: list[str] = []
+        for model_name in LOCAL_GAME_LLM_MODELS:
+            try:
+                tokenizer = AutoTokenizer.from_pretrained(model_name)
+
+                kwargs: dict[str, Any] = {"torch_dtype": dtype}
+                if device == "cuda":
+                    kwargs["device_map"] = "auto"
+                else:
+                    kwargs["low_cpu_mem_usage"] = True
+
+                try:
+                    model = AutoModelForCausalLM.from_pretrained(model_name, **kwargs)
+                except TypeError:
+                    # Older transformers may not support low_cpu_mem_usage/device_map in this path.
+                    kwargs.pop("device_map", None)
+                    kwargs.pop("low_cpu_mem_usage", None)
+                    model = AutoModelForCausalLM.from_pretrained(model_name, **kwargs)
+
+                if device == "cpu":
+                    model.to(device)
+                model.eval()
+
+                _game_llm_runtime = {
+                    "torch": torch,
+                    "tokenizer": tokenizer,
+                    "model": model,
+                    "device": device,
+                    "model_name": model_name,
+                }
+                logger.info("llm local runtime initialized model=%s device=%s", model_name, device)
+                return _game_llm_runtime
+            except Exception as exc:
+                logger.warning("llm local runtime init failed model=%s err=%s", model_name, str(exc))
+                errors.append(f"{model_name}: {exc}")
+
+        _game_llm_error = " | ".join(errors) if errors else "no-model-candidate"
+        logger.warning("llm local runtime init failed for all models err=%s", _game_llm_error)
+        return None
+    except Exception as exc:
+        _game_llm_error = str(exc)
+        logger.warning("llm local runtime import/init failed err=%s", _game_llm_error)
+        return None
+
+
+def _run_local_game_llm_generation(runtime: dict[str, Any], user_payload: dict[str, Any]) -> str:
+    torch = runtime["torch"]
+    tokenizer = runtime["tokenizer"]
+    model = runtime["model"]
+    device = runtime["device"]
+
+    messages = _build_game_messages(user_payload)
+    if hasattr(tokenizer, "apply_chat_template"):
+        prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+    else:
+        prompt = _build_game_prompt(user_payload)
+
+    inputs = tokenizer(
+        prompt,
+        return_tensors="pt",
+        truncation=True,
+        max_length=LOCAL_GAME_LLM_MAX_INPUT_TOKENS,
+    )
+    inputs = {k: v.to(device) for k, v in inputs.items()}
+
+    pad_token_id = tokenizer.pad_token_id if tokenizer.pad_token_id is not None else tokenizer.eos_token_id
+    with torch.no_grad():
+        output_ids = model.generate(
+            **inputs,
+            max_new_tokens=LOCAL_GAME_LLM_MAX_NEW_TOKENS,
+            do_sample=False,
+            pad_token_id=pad_token_id,
+            eos_token_id=tokenizer.eos_token_id,
+        )
+
+    prompt_tokens = inputs["input_ids"].shape[1]
+    generated_ids = output_ids[0][prompt_tokens:]
+    return tokenizer.decode(generated_ids, skip_special_tokens=True).strip()
+
+
+def _parse_llm_json(content: str) -> dict[str, Any] | None:
+    if not content:
+        return None
+
+    text = content.strip()
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        match = re.search(r"\{.*\}", text, re.DOTALL)
+        if not match:
+            return None
+        try:
+            data = json.loads(match.group(0))
+        except json.JSONDecodeError:
+            return None
+
+    verdict = str(data.get("verdict", "")).lower()
+    if verdict not in {"game", "not_game", "uncertain"}:
+        return None
+
+    confidence_raw = data.get("confidence", 0.5)
+    try:
+        confidence = float(confidence_raw)
+    except (TypeError, ValueError):
+        confidence = 0.5
+
+    confidence = max(0.0, min(1.0, confidence))
+    raw_reason = str(data.get("reason", "")).strip().lower()
+    reason = _normalize_reason_code(verdict, raw_reason)
+
+    return {"verdict": verdict, "confidence": confidence, "reason": reason}
+
+
+def _normalize_reason_code(verdict: str, reason: str) -> str:
+    if reason in ALLOWED_REASON_CODES:
+        return reason
+
+    if verdict == "game":
+        return "game_ui_terms"
+    if verdict == "uncertain":
+        return "conflicting_signals"
+    return "no_game_evidence"
+
+
+def _domain_from_url(url: str) -> str:
+    parsed = urlparse(url)
+    host = parsed.netloc or parsed.path
+    host = host.lower().replace("www.", "")
+    parts = host.split(".")
+    if not parts:
+        return host
+    return parts[0]
+
+
+def _is_game_like_domain(url: str) -> bool:
+    parsed = urlparse(url)
+    host = (parsed.netloc or parsed.path).lower().replace("www.", "")
+    first_label = _domain_from_url(url)
+
+    if first_label in GAME_KEYWORDS and first_label not in {"game", "games", "play"}:
+        return True
+
+    if host.endswith(".games"):
+        return True
+
+    # Precision-first: require explicit game-platform/domain hints.
+    host_tokens = re.split(r"[^a-z0-9]+", host)
+    for token in host_tokens:
+        if not token:
+            continue
+        if token in STRONG_GAME_DOMAIN_HINTS:
+            return True
+
+    return False
+
+
+def filter_cacheable_game_urls(urls: list[str]) -> list[str]:
+    deduped: list[str] = []
+    seen: set[str] = set()
+    for item in urls:
+        if item in seen:
+            continue
+        seen.add(item)
+        if _is_game_like_domain(item):
+            deduped.append(item)
+    return deduped
+
+
+def _normalize_ocr_url(value: str) -> str | None:
+    item = value.strip().rstrip(".,)").lower()
+    if not item:
+        return None
+    if not item.startswith("http://") and not item.startswith("https://"):
+        item = f"https://{item}"
+
+    parsed = urlparse(item)
+    host = (parsed.netloc or "").strip().lower()
+    if not host or "." not in host:
+        return None
+    if "_" in host:
+        return None
+
+    tld = host.rsplit(".", 1)[-1]
+    if not tld.isalpha() or len(tld) < 2 or len(tld) > 24:
+        return None
+    if tld in NON_DOMAIN_TLDS:
+        return None
+
+    if parsed.query:
+        return f"{parsed.scheme}://{host}{parsed.path}?{parsed.query}"
+    return f"{parsed.scheme}://{host}{parsed.path}"
+
+
+def _has_any_term(text: str, terms: set[str]) -> bool:
+    if not text:
+        return False
+    lower = text.lower()
+    return any(term in lower for term in terms)
+
+
+def _apply_precision_guard(
+    llm_result: dict[str, Any],
+    ocr_text: str,
+    urls: list[str],
+    suspected_game: bool,
+) -> dict[str, Any]:
+    verdict = str(llm_result.get("verdict", "")).lower()
+    if verdict != "game":
+        return llm_result
+
+    strong_domain_hit = any(_is_game_like_domain(url) for url in urls)
+    strong_ui_hit = _has_any_term(ocr_text, STRONG_GAME_UI_TERMS)
+    medium_ui_hit = _has_any_term(ocr_text, MEDIUM_GAME_UI_TERMS)
+
+    if strong_domain_hit or strong_ui_hit or (suspected_game and medium_ui_hit):
+        return llm_result
+
+    confidence = float(llm_result.get("confidence", 0.5))
+    return {
+        "verdict": "not_game",
+        "confidence": min(confidence, 0.35),
+        "reason": "no_game_evidence",
+        "source": "rule-guard",
+    }
+
+
+def classify_sensitive_content(file_path: str, filename: str) -> tuple[bool, float, str]:
+    # First pass with image model inference; fallback to keyword signal only if unavailable.
+    model_result = _classify_sensitive_with_model(file_path)
+    if model_result is not None:
+        return model_result
+
+    name_text = f"{Path(file_path).name} {filename}".lower()
+    keyword_hit = any(word in name_text for word in SENSITIVE_KEYWORDS)
+    if keyword_hit:
+        return True, 0.65, "sensitive-keyword-fallback"
+    return False, 0.05, "no-sensitive-signal"
+
+
+def _load_nsfw_runtime() -> dict[str, Any] | None:
+    global _nsfw_runtime
+    global _nsfw_error
+
+    if _nsfw_runtime is not None:
+        return _nsfw_runtime
+    if _nsfw_error is not None:
+        return None
+
+    try:
+        import timm
+        import torch
+        from PIL import Image
+        from safetensors.torch import load_file
+
+        if not NSFW_CONFIG_PATH.exists() or not NSFW_WEIGHTS_PATH.exists():
+            _nsfw_error = "missing-local-model-files"
+            return None
+
+        config_data = json.loads(NSFW_CONFIG_PATH.read_text(encoding="utf-8"))
+        architecture = str(config_data.get("architecture", "vit_tiny_patch16_384"))
+        num_classes = int(config_data.get("num_classes", 2))
+        label_names = [str(x).lower() for x in config_data.get("label_names", ["nsfw", "sfw"])]
+        pretrained_cfg = config_data.get("pretrained_cfg", {})
+
+        model = timm.create_model(architecture, pretrained=False, num_classes=num_classes).eval()
+        state_dict = load_file(str(NSFW_WEIGHTS_PATH), device="cpu")
+        model.load_state_dict(state_dict, strict=False)
+
+        # Use local config for preprocessing so inference does not depend on remote metadata.
+        model.pretrained_cfg = {**getattr(model, "pretrained_cfg", {}), **pretrained_cfg, "label_names": label_names}
+
+        data_config = timm.data.resolve_model_data_config(model)
+        transforms = timm.data.create_transform(**data_config, is_training=False)
+
+        _nsfw_runtime = {
+            "torch": torch,
+            "Image": Image,
+            "model": model,
+            "transforms": transforms,
+            "label_names": [str(x).lower() for x in label_names],
+        }
+        return _nsfw_runtime
+    except Exception as exc:
+        _nsfw_error = str(exc)
+        return None
+
+
+def _classify_sensitive_with_model(file_path: str) -> tuple[bool, float, str] | None:
+    runtime = _load_nsfw_runtime()
+    if runtime is None:
+        return None
+
+    torch = runtime["torch"]
+    Image = runtime["Image"]
+    model = runtime["model"]
+    transforms = runtime["transforms"]
+    label_names = runtime["label_names"]
+
+    with Image.open(file_path) as img:
+        img = img.convert("RGB")
+        with torch.no_grad():
+            output = model(transforms(img).unsqueeze(0)).softmax(dim=-1).cpu()[0]
+
+    scores = [float(x) for x in output.tolist()]
+    nsfw_score = _extract_nsfw_score(scores, label_names)
+    return (nsfw_score >= NSFW_THRESHOLD, nsfw_score, "timm-marqo-nsfw")
+
+
+def _extract_nsfw_score(scores: list[float], labels: list[str]) -> float:
+    for idx, label in enumerate(labels):
+        if "nsfw" in label:
+            return scores[idx]
+    if len(scores) >= 2:
+        return scores[1]
+    return scores[0] if scores else 0.0

services/key_service.py

@@ -0,0 +1,100 @@
+import secrets
+from hashlib import sha256
+from datetime import datetime, timedelta, timezone
+
+from app.services.repos import key_state_repo
+
+
+def _hash_key(raw: str) -> str:
+    return sha256(raw.encode("utf-8")).hexdigest()
+
+
+def _to_utc_aware(value: datetime | None) -> datetime | None:
+    if not isinstance(value, datetime):
+        return None
+    if value.tzinfo is None:
+        return value.replace(tzinfo=timezone.utc)
+    return value.astimezone(timezone.utc)
+
+
+class KeyService:
+    def __init__(self, *, ttl_seconds: int = 60, lock_minutes: int = 5) -> None:
+        self.ttl_seconds = ttl_seconds
+        self.lock_minutes = lock_minutes
+
+    async def generate(self, device_id: str) -> tuple[str, datetime]:
+        key = secrets.token_urlsafe(8)
+        expires_at = datetime.now(timezone.utc) + timedelta(seconds=self.ttl_seconds)
+        await key_state_repo.upsert(
+            device_id,
+            {
+                "key_hash": _hash_key(key),
+                "expires_at": expires_at,
+                "wrong_attempts": 0,
+                "lock_until": None,
+            },
+        )
+        return key, expires_at
+
+    async def validate(self, device_id: str, candidate: str) -> tuple[bool, datetime | None, int]:
+        state = await key_state_repo.get(device_id)
+        now = datetime.now(timezone.utc)
+
+        if state is None:
+            lock_until = now + timedelta(minutes=self.lock_minutes)
+            await key_state_repo.upsert(
+                device_id,
+                {
+                    "wrong_attempts": 1,
+                    "lock_until": lock_until,
+                    "expires_at": now,
+                    "key_hash": "",
+                },
+            )
+            return False, lock_until, 1
+
+        lock_until_value = _to_utc_aware(state.get("lock_until"))
+        if lock_until_value is not None and now < lock_until_value:
+            return False, lock_until_value, int(state.get("wrong_attempts", 0))
+
+        expires_at = _to_utc_aware(state.get("expires_at"))
+        if expires_at is None or now > expires_at:
+            lock_until = now + timedelta(minutes=self.lock_minutes)
+            attempts = int(state.get("wrong_attempts", 0)) + 1
+            await key_state_repo.upsert(
+                device_id,
+                {
+                    "wrong_attempts": attempts,
+                    "lock_until": lock_until,
+                    "expires_at": now,
+                },
+            )
+            return False, lock_until, attempts
+
+        candidate_hash = _hash_key(candidate)
+        expected_hash = str(state.get("key_hash", ""))
+        if not secrets.compare_digest(candidate_hash, expected_hash):
+            attempts = int(state.get("wrong_attempts", 0)) + 1
+            lock_until = now + timedelta(minutes=self.lock_minutes)
+            await key_state_repo.upsert(
+                device_id,
+                {
+                    "wrong_attempts": attempts,
+                    "lock_until": lock_until,
+                },
+            )
+            return False, lock_until, attempts
+
+        await key_state_repo.upsert(
+            device_id,
+            {
+                "wrong_attempts": 0,
+                "lock_until": None,
+                "expires_at": now,
+                "key_hash": "",
+            },
+        )
+        return True, None, 0
+
+
+key_service = KeyService()

services/policy_window.py

@@ -0,0 +1,55 @@
+from datetime import datetime
+from typing import Any
+
+_DAY_INDEX = {
+    "mon": 0,
+    "tue": 1,
+    "wed": 2,
+    "thu": 3,
+    "fri": 4,
+    "sat": 5,
+    "sun": 6,
+}
+
+
+def _parse_hhmm(value: str) -> tuple[int, int]:
+    hour_text, minute_text = value.split(":", 1)
+    return int(hour_text), int(minute_text)
+
+
+def _minutes_of_day(moment: datetime) -> int:
+    return moment.hour * 60 + moment.minute
+
+
+def is_restriction_active(windows: list[dict[str, Any]], moment: datetime) -> bool:
+    if not windows:
+        return False
+
+    weekday = moment.weekday()
+    now_minutes = _minutes_of_day(moment)
+
+    for window in windows:
+        day = window.get("day_of_week")
+        start = str(window.get("start", "00:00"))
+        end = str(window.get("end", "00:00"))
+        if day not in _DAY_INDEX:
+            continue
+
+        start_h, start_m = _parse_hhmm(start)
+        end_h, end_m = _parse_hhmm(end)
+        start_minutes = start_h * 60 + start_m
+        end_minutes = end_h * 60 + end_m
+        window_day = _DAY_INDEX[day]
+
+        if start_minutes <= end_minutes:
+            if weekday == window_day and start_minutes <= now_minutes <= end_minutes:
+                return True
+            continue
+
+        # Overnight window: e.g. 22:00 -> 02:00
+        if weekday == window_day and now_minutes >= start_minutes:
+            return True
+        if weekday == (window_day + 1) % 7 and now_minutes <= end_minutes:
+            return True
+
+    return False

services/repos.py

@@ -0,0 +1,190 @@
+from datetime import datetime, timezone
+from typing import Any
+
+from app.core.db import get_db
+
+
+def _clean(doc: dict[str, Any] | None) -> dict[str, Any] | None:
+    if doc is None:
+        return None
+    doc.pop("_id", None)
+    return doc
+
+
+class DeviceRepo:
+    async def upsert(self, data: dict[str, Any]) -> None:
+        db = get_db()
+        await db.devices.update_one(
+            {"device_id": data["device_id"]},
+            {"$set": {**data, "updated_at": datetime.now(timezone.utc)}},
+            upsert=True,
+        )
+
+    async def list(self) -> list[dict[str, Any]]:
+        db = get_db()
+        rows = await db.devices.find({}, {"_id": 0}).to_list(length=200)
+        return rows
+
+    async def heartbeat(self, device_id: str, active_restriction_window: bool, uptime_seconds: int) -> None:
+        db = get_db()
+        now = datetime.now(timezone.utc)
+        await db.devices.update_one(
+            {"device_id": device_id},
+            {
+                "$set": {
+                    "device_id": device_id,
+                    "active_restriction_window": active_restriction_window,
+                    "uptime_seconds": uptime_seconds,
+                    "last_heartbeat_at": now,
+                    "updated_at": now,
+                }
+            },
+            upsert=True,
+        )
+
+
+class PolicyRepo:
+    async def set(self, device_id: str, policy: dict[str, Any]) -> None:
+        db = get_db()
+        await db.policies.update_one(
+            {"device_id": device_id},
+            {
+                "$set": {
+                    "device_id": device_id,
+                    "policy": policy,
+                    "updated_at": datetime.now(timezone.utc),
+                }
+            },
+            upsert=True,
+        )
+
+    async def get(self, device_id: str) -> dict[str, Any] | None:
+        db = get_db()
+        doc = await db.policies.find_one({"device_id": device_id}, {"_id": 0})
+        return _clean(doc)
+
+
+class ViolationRepo:
+    async def insert(self, doc: dict[str, Any]) -> None:
+        db = get_db()
+        await db.violations.insert_one(doc)
+
+    async def list_active(self, visibility_scope: str) -> list[dict[str, Any]]:
+        db = get_db()
+        now = datetime.now(timezone.utc)
+        query = {"expires_at": {"$gt": now}, "visibility_scope": visibility_scope}
+        rows = (
+            await db.violations.find(query, {"_id": 0})
+            .sort("timestamp", -1)
+            .to_list(length=500)
+        )
+        return rows
+
+    async def list_expired(self) -> list[dict[str, Any]]:
+        db = get_db()
+        now = datetime.now(timezone.utc)
+        return await db.violations.find({"expires_at": {"$lte": now}}).to_list(length=500)
+
+    async def delete_expired(self) -> int:
+        db = get_db()
+        now = datetime.now(timezone.utc)
+        result = await db.violations.delete_many({"expires_at": {"$lte": now}})
+        return result.deleted_count
+
+
+class AuditRepo:
+    async def log(self, doc: dict[str, Any]) -> None:
+        db = get_db()
+        await db.screenshot_audit.insert_one(doc)
+
+
+class KeyStateRepo:
+    async def get(self, device_id: str) -> dict[str, Any] | None:
+        db = get_db()
+        doc = await db.key_states.find_one({"device_id": device_id})
+        return _clean(doc)
+
+    async def upsert(self, device_id: str, patch: dict[str, Any]) -> None:
+        db = get_db()
+        await db.key_states.update_one(
+            {"device_id": device_id},
+            {
+                "$set": {
+                    **patch,
+                    "device_id": device_id,
+                    "updated_at": datetime.now(timezone.utc),
+                }
+            },
+            upsert=True,
+        )
+
+
+class UrlVerdictRepo:
+    async def get_cached_game_url(self, urls: list[str]) -> str | None:
+        if not urls:
+            return None
+        db = get_db()
+        doc = await db.url_verdicts.find_one(
+            {"url": {"$in": urls}, "verdict": "game"},
+            {"_id": 0, "url": 1},
+        )
+        if not doc:
+            return None
+        return str(doc.get("url", ""))
+
+    async def upsert_game_urls(self, urls: list[str], source: str) -> None:
+        if not urls:
+            return
+        db = get_db()
+        now = datetime.now(timezone.utc)
+        for url in urls:
+            await db.url_verdicts.update_one(
+                {"url": url},
+                {
+                    "$set": {
+                        "url": url,
+                        "verdict": "game",
+                        "source": source,
+                        "updated_at": now,
+                    }
+                },
+                upsert=True,
+            )
+
+
+class ReviewRepo:
+    async def create_pending(self, doc: dict[str, Any]) -> None:
+        db = get_db()
+        await db.game_lock_reviews.insert_one(doc)
+
+    async def list_pending(self, limit: int = 200) -> list[dict[str, Any]]:
+        db = get_db()
+        rows = (
+            await db.game_lock_reviews.find({"status": "pending"}, {"_id": 0})
+            .sort("created_at", -1)
+            .to_list(length=limit)
+        )
+        return rows
+
+    async def decide(self, review_id: str, approve_lock: bool, decided_by: str) -> bool:
+        db = get_db()
+        result = await db.game_lock_reviews.update_one(
+            {"review_id": review_id, "status": "pending"},
+            {
+                "$set": {
+                    "status": "approved" if approve_lock else "rejected",
+                    "decided_by": decided_by,
+                    "decided_at": datetime.now(timezone.utc),
+                }
+            },
+        )
+        return result.modified_count > 0
+
+
+device_repo = DeviceRepo()
+policy_repo = PolicyRepo()
+violation_repo = ViolationRepo()
+audit_repo = AuditRepo()
+key_state_repo = KeyStateRepo()
+url_verdict_repo = UrlVerdictRepo()
+review_repo = ReviewRepo()

services/storage.py

@@ -0,0 +1,30 @@
+from pathlib import Path
+from uuid import uuid4
+
+from fastapi import UploadFile
+
+from app.core.config import settings
+
+
+class StorageService:
+    def __init__(self, base_dir: str) -> None:
+        self.base_dir = Path(base_dir)
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+
+    async def save_upload(self, file: UploadFile) -> tuple[str, str, str]:
+        extension = Path(file.filename or "capture.png").suffix or ".png"
+        image_id = str(uuid4())
+        stored_name = f"{image_id}{extension}"
+        target_path = self.base_dir / stored_name
+
+        content = await file.read()
+        target_path.write_bytes(content)
+        return image_id, str(target_path), stored_name
+
+    def delete(self, absolute_path: str) -> None:
+        target = Path(absolute_path)
+        if target.exists():
+            target.unlink()
+
+
+storage_service = StorageService(settings.storage_dir)