dokeo 3.0.0__tar.gz

dokeo-3.0.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: dokeo
+Version: 3.0.0
+Summary: Pre-publish content quality gate (SEO, AEO, GEO) - API, CLI, MCP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: streamlit>=1.32.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: nltk>=3.8
+Requires-Dist: textstat>=0.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: trafilatura>=2.0.0
+Requires-Dist: feedparser>=6.0.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: lxml[html-clean]>=5.0.0
+Requires-Dist: anthropic>=0.40
+Requires-Dist: openai>=1.50
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn[standard]>=0.30
+Requires-Dist: httpx>=0.27
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+
+# Dokeo — Content Quality Gate
+
+Pre-publish content quality gate for SEO, AEO, and GEO. Scores every post,
+email, video script, and AI output against 8 core checks before it ships.
+
+## Surfaces
+
+Dokeo ships as four parallel surfaces that all hit the same gate engine:
+
+| Surface | Port / Transport | Best for |
+|---|---|---|
+| **FastAPI service** | `http://host:8000/api/v1/*` | Programmatic integrations, webhooks |
+| **Next.js web app** | `https://host/web/*` | End-user UI with Clerk auth |
+| **Streamlit UI** | `https://host/` | Legacy dashboard, single-user password |
+| **MCP server** | stdio | Claude / Cursor / any MCP client |
+| **CLI** | `dokeo` in your shell | Pipelines, n8n, Claude Code |
+
+The legacy webhook (port 8502, `/check`, `/check-url`, etc.) is kept for
+backward compatibility with existing n8n / Zapier / Make integrations.
+
+## Quickstart
+
+```bash
+# 1. Install
+pip install -e .
+
+# 2. Run the API
+uvicorn api.main:app --reload --port 8000
+# → http://localhost:8000/docs for OpenAPI
+
+# 3. Run the web app (separate terminal)
+cd web && bun install && bun run dev
+
+# 4. Run the Streamlit UI (separate terminal)
+streamlit run app.py
+
+# 5. Try the CLI
+echo "# My post\n\n## Question?\n\n..." | dokeo pipe
+
+# 6. Try the MCP server (Claude Desktop / Cursor will spawn it for you)
+dokeo-mcp-server
+```
+
+## Self-hosted with Docker
+
+```bash
+cp .env.example .env
+# Edit .env - set DOKEO_API_KEY, DOKEO_PASSWORD, Clerk keys
+docker compose up -d
+```
+
+Routes (via Caddy at ports 80/443):
+
+- `/` → Streamlit (port 8501)
+- `/web/*`, `/sign-in`, `/sign-up` → Next.js (port 3000)
+- `/api/v1/*` → FastAPI (port 8000)
+- `/check*`, `/check-url*`, `/check-blog*`, `/health*`, etc. → legacy webhook (port 8502)
+
+## Auth model
+
+| Surface | Auth |
+|---|---|
+| FastAPI (`/api/v1/*`) | Bearer token: `DOKEO_API_KEY` or `DOKEO_API_KEYS=key:tenant,...` |
+| Legacy webhook | Same Bearer token |
+| Streamlit | Cookie session via `DOKEO_PASSWORD` |
+| Next.js | Clerk (hosted) |
+| MCP | Filesystem only; no network exposure |
+| CLI | None (local) |
+
+`DOKEO_API_KEY` is required in any non-dev environment. Streamlit refuses
+to boot in production without `DOKEO_PASSWORD`.
+
+## Documentation
+
+- API: OpenAPI at `/docs` or `/redoc` when running
+- MCP: [docs/mcp.md](docs/mcp.md)
+- Engine config: `config.yaml`
+- Content-type definitions: `gate/content_types.py`
+
+## Tests
+
+```bash
+pytest                  # all tests
+pytest tests/test_mcp_server.py   # MCP only
+```

dokeo-3.0.0/README.md

@@ -0,0 +1,85 @@
+# Dokeo — Content Quality Gate
+
+Pre-publish content quality gate for SEO, AEO, and GEO. Scores every post,
+email, video script, and AI output against 8 core checks before it ships.
+
+## Surfaces
+
+Dokeo ships as four parallel surfaces that all hit the same gate engine:
+
+| Surface | Port / Transport | Best for |
+|---|---|---|
+| **FastAPI service** | `http://host:8000/api/v1/*` | Programmatic integrations, webhooks |
+| **Next.js web app** | `https://host/web/*` | End-user UI with Clerk auth |
+| **Streamlit UI** | `https://host/` | Legacy dashboard, single-user password |
+| **MCP server** | stdio | Claude / Cursor / any MCP client |
+| **CLI** | `dokeo` in your shell | Pipelines, n8n, Claude Code |
+
+The legacy webhook (port 8502, `/check`, `/check-url`, etc.) is kept for
+backward compatibility with existing n8n / Zapier / Make integrations.
+
+## Quickstart
+
+```bash
+# 1. Install
+pip install -e .
+
+# 2. Run the API
+uvicorn api.main:app --reload --port 8000
+# → http://localhost:8000/docs for OpenAPI
+
+# 3. Run the web app (separate terminal)
+cd web && bun install && bun run dev
+
+# 4. Run the Streamlit UI (separate terminal)
+streamlit run app.py
+
+# 5. Try the CLI
+echo "# My post\n\n## Question?\n\n..." | dokeo pipe
+
+# 6. Try the MCP server (Claude Desktop / Cursor will spawn it for you)
+dokeo-mcp-server
+```
+
+## Self-hosted with Docker
+
+```bash
+cp .env.example .env
+# Edit .env - set DOKEO_API_KEY, DOKEO_PASSWORD, Clerk keys
+docker compose up -d
+```
+
+Routes (via Caddy at ports 80/443):
+
+- `/` → Streamlit (port 8501)
+- `/web/*`, `/sign-in`, `/sign-up` → Next.js (port 3000)
+- `/api/v1/*` → FastAPI (port 8000)
+- `/check*`, `/check-url*`, `/check-blog*`, `/health*`, etc. → legacy webhook (port 8502)
+
+## Auth model
+
+| Surface | Auth |
+|---|---|
+| FastAPI (`/api/v1/*`) | Bearer token: `DOKEO_API_KEY` or `DOKEO_API_KEYS=key:tenant,...` |
+| Legacy webhook | Same Bearer token |
+| Streamlit | Cookie session via `DOKEO_PASSWORD` |
+| Next.js | Clerk (hosted) |
+| MCP | Filesystem only; no network exposure |
+| CLI | None (local) |
+
+`DOKEO_API_KEY` is required in any non-dev environment. Streamlit refuses
+to boot in production without `DOKEO_PASSWORD`.
+
+## Documentation
+
+- API: OpenAPI at `/docs` or `/redoc` when running
+- MCP: [docs/mcp.md](docs/mcp.md)
+- Engine config: `config.yaml`
+- Content-type definitions: `gate/content_types.py`
+
+## Tests
+
+```bash
+pytest                  # all tests
+pytest tests/test_mcp_server.py   # MCP only
+```

dokeo-3.0.0/api/auth.py

@@ -0,0 +1,55 @@
+"""API key auth - FastAPI dependency.
+
+Replaces the hand-rolled bearer check in gate/webhook.py with an idiomatic
+FastAPI dependency. Same env vars, same multi-tenant pattern, same
+constant-time compare.
+
+Usage in a route:
+    @router.get("/stats", dependencies=[Depends(require_api_key)])
+    def stats(): ...
+
+Or to read the tenant in the handler:
+    def stats(tenant: str = Depends(api_key_tenant)): ...
+"""
+from __future__ import annotations
+
+import hmac
+from typing import Optional
+
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+from api.config import settings
+
+_bearer = HTTPBearer(auto_error=False)
+
+
+async def require_api_key(
+    creds: Optional[HTTPAuthorizationCredentials] = Depends(_bearer),
+) -> str:
+    """Validate the Bearer token. Returns the tenant id (or 'default').
+
+    In dev (no keys configured) auth is open - same behavior as the existing
+    webhook. In prod, set DOKEO_API_KEY or DOKEO_API_KEYS.
+    """
+    if not settings.auth_enabled:
+        return "default"
+    if creds is None or not creds.credentials:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="missing Bearer token",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    token = creds.credentials
+    for key, tenant in settings.api_keys.items():
+        if hmac.compare_digest(token, key):
+            return tenant
+    raise HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="invalid API key",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+
+
+# Convenience aliases
+api_key_tenant = require_api_key

dokeo-3.0.0/api/config.py

@@ -0,0 +1,63 @@
+"""Settings - read once at startup from env vars.
+
+Mirrors the env vars already used by gate/webhook.py so the two services
+can share the same .env file during the transition:
+  DOKEO_API_KEY          single bearer token (dev / single-tenant)
+  DOKEO_API_KEYS         multi-tenant: key1:tenant1,key2:tenant2
+  DOKEO_CORS_ORIGIN      allowlist for browser clients (the Next.js app)
+  DOKEO_RATE_LIMIT       requests per minute per IP (default 120)
+  DOKEO_LOG_LEVEL        INFO / DEBUG / WARNING
+  ANTHROPIC_API_KEY      live mode for the builder (read by gate.listicle.llm)
+  OPENAI_API_KEY         live mode for the builder
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+
+def _parse_keys(raw: str) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for pair in raw.split(","):
+        pair = pair.strip()
+        if not pair:
+            continue
+        if ":" in pair:
+            k, t = pair.split(":", 1)
+            out[k.strip()] = t.strip()
+        else:
+            out[pair] = "tenant-" + pair[:6]
+    return out
+
+
+class Settings:
+    VERSION = "3.0.0"
+
+    # Auth
+    api_key: str = os.environ.get("DOKEO_API_KEY", "")
+    api_keys: dict[str, str] = {**( {api_key: "default"} if (api_key := os.environ.get("DOKEO_API_KEY", "")) else {}), **_parse_keys(os.environ.get("DOKEO_API_KEYS", ""))}
+
+    # CORS
+    cors_origin: str = os.environ.get("DOKEO_CORS_ORIGIN", "")
+
+    # Rate limit
+    rate_limit: int = int(os.environ.get("DOKEO_RATE_LIMIT", "120"))
+    rate_limit_tenant: int = int(os.environ.get("DOKEO_RATE_LIMIT_TENANT", "300"))
+    rate_window: int = 60
+
+    # Paths
+    base_dir: Path = ROOT
+    corpus_dir: Path = ROOT / "sample_corpus" / "published"
+    config_path: Path = ROOT / "config.yaml"
+
+    # Misc
+    log_level: str = os.environ.get("DOKEO_LOG_LEVEL", "INFO")
+
+    @property
+    def auth_enabled(self) -> bool:
+        return bool(self.api_keys)
+
+
+settings = Settings()

dokeo-3.0.0/api/deps.py

@@ -0,0 +1,41 @@
+"""Shared FastAPI dependencies - singletons for the engine + supporting stores.
+
+These wrap the gate/ package's own singletons so the HTTP layer never
+constructs engine objects itself. Keeps a single source of truth for config
+and the corpus index (which is expensive to build).
+"""
+from __future__ import annotations
+
+import yaml
+from functools import lru_cache
+
+from fastapi import Request
+
+from gate.gate import QualityGate
+from gate.audit_log import AuditLog
+from gate.knowledge_base import KnowledgeBase
+
+
+@lru_cache(maxsize=1)
+def get_quality_gate() -> QualityGate:
+    """The core content-quality engine. One instance per process."""
+    from api.config import settings
+    with open(settings.config_path) as f:
+        cfg = yaml.safe_load(f)
+    return QualityGate(str(settings.corpus_dir), cfg,
+                       custom_rules_path=str(settings.base_dir / "custom_rules.json"))
+
+
+@lru_cache(maxsize=1)
+def get_audit_log() -> AuditLog:
+    return AuditLog()
+
+
+@lru_cache(maxsize=1)
+def get_knowledge_base() -> KnowledgeBase:
+    from api.config import settings
+    return KnowledgeBase(str(settings.base_dir / "knowledge_base"))
+
+
+def get_request_id(request: Request) -> str:
+    return request.headers.get("x-request-id") or ""

dokeo-3.0.0/api/main.py

@@ -0,0 +1,90 @@
+"""Dokeo FastAPI service - the engine's new HTTP surface.
+
+Runs alongside Streamlit (port 8501) and the legacy webhook (port 8502).
+This service lives on port 8000 by default and exposes:
+
+  · Auto-generated OpenAPI docs at /docs and /redoc
+  · Same auth + rate-limit + CORS posture as the legacy webhook
+  · The full gate engine (8 checks, 17 content types)
+  · The listicle builder pipeline (research → generate → QA)
+  · Catalog endpoints (content types, engines, formats, categories)
+  · Audit log access
+
+Run:
+  uvicorn api.main:app --reload --port 8000
+"""
+from __future__ import annotations
+
+import logging
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from api.config import settings
+from api.rate_limit import RateLimitMiddleware
+from api.tracing import TraceMiddleware
+from api.routes import admin, audit, batch, builder, catalog, health, knowledge, rules, scan
+
+log = logging.getLogger("dokeo-api")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    log.info("dokeo-api v%s - auth=%s, rate_limit=%d/min, cors=%s",
+             settings.VERSION,
+             "ON" if settings.auth_enabled else "OFF",
+             settings.rate_limit,
+             settings.cors_origin or "same-origin")
+    yield
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(
+        title="Dokeo Content Quality API",
+        description=(
+            "Pre-publish content quality gate + listicle/comparison builder.\n\n"
+            "**Engines:** SEO · AEO · GEO across 17 content types.\n\n"
+            "**Auth:** Bearer token via `Authorization: Bearer <key>` header. "
+            "Set `DOKEO_API_KEY` in env (dev: open when unset).\n\n"
+            "**Rate limit:** per-IP token bucket. See `X-RateLimit-*` headers."
+        ),
+        version=settings.VERSION,
+        docs_url="/docs",
+        redoc_url="/redoc",
+        openapi_url="/openapi.json",
+        lifespan=lifespan,
+    )
+
+    # ── Middleware ────────────────────────────────────────────────────
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=[settings.cors_origin] if settings.cors_origin else [],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+    app.add_middleware(TraceMiddleware)
+    app.add_middleware(RateLimitMiddleware)
+
+    # ── Routes ────────────────────────────────────────────────────────
+    api_prefix = "/api/v1"
+    app.include_router(health.router, prefix=api_prefix)
+    app.include_router(catalog.router, prefix=api_prefix)
+    app.include_router(scan.router, prefix=api_prefix)
+    app.include_router(builder.router, prefix=api_prefix)
+    app.include_router(audit.router, prefix=api_prefix)
+    app.include_router(batch.router, prefix=api_prefix)
+    app.include_router(rules.router, prefix=api_prefix)
+    app.include_router(admin.router, prefix=api_prefix)
+    app.include_router(knowledge.router, prefix=api_prefix)
+
+    @app.get("/", include_in_schema=False)
+    def root():
+        return {"service": "dokeo-api", "version": settings.VERSION,
+                "docs": "/docs", "health": f"{api_prefix}/health"}
+
+    return app
+
+
+app = create_app()

dokeo-3.0.0/api/rate_limit.py

@@ -0,0 +1,115 @@
+"""Per-IP + per-tenant token-bucket rate limiter.
+
+Two layers:
+  1. Per-IP (60-120 req/min)        — same as the old webhook behavior.
+  2. Per-tenant (configurable)        — set DOKEO_RATE_LIMIT_TENANT=300 for
+                                       a higher per-tenant ceiling once
+                                       you've authenticated.
+
+X-RateLimit-* headers on every response tell clients when they can retry.
+"""
+from __future__ import annotations
+import threading
+import time
+from collections import defaultdict
+
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import Response
+
+from api.config import settings
+
+
+class RateLimitMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app, ip_limit: int | None = None, ip_window: int | None = None,
+                 tenant_limit: int | None = None, tenant_window: int | None = None):
+        super().__init__(app)
+        self.ip_limit = ip_limit or settings.rate_limit
+        self.ip_window = ip_window or settings.rate_window
+        self.tenant_limit = tenant_limit or settings.rate_limit_tenant
+        self.tenant_window = tenant_window or settings.rate_window
+        self._ip_buckets: dict[str, list[float]] = defaultdict(list)
+        self._tenant_buckets: dict[str, list[float]] = defaultdict(list)
+        self._lock = threading.Lock()
+
+    def _client_ip(self, request: Request) -> str:
+        fwd = request.headers.get("x-forwarded-for", "")
+        if fwd:
+            return fwd.split(",")[0].strip()
+        return request.client.host if request.client else "unknown"
+
+    def _check(self, key: str, buckets: dict, limit: int, window: int) -> tuple[bool, int, int]:
+        now = time.time()
+        with self._lock:
+            bucket = buckets[key]
+            while bucket and bucket[0] < now - window:
+                bucket.pop(0)
+            if len(bucket) >= limit:
+                reset = int(window - (now - bucket[0])) if bucket else window
+                return False, 0, max(reset, 1)
+            bucket.append(now)
+            return True, limit - len(bucket), window
+
+    def _tenant_key(self, request: Request) -> str | None:
+        """Pull tenant from Bearer token (set by the require_api_key dep
+        which runs after this middleware, so we re-parse here)."""
+        auth = request.headers.get("authorization", "")
+        if not auth.startswith("Bearer "):
+            return None
+        token = auth[7:]
+        for key, tenant in settings.api_keys.items():
+            # Use hmac.compare_digest via a small inline impl
+            import hmac
+            if hmac.compare_digest(token, key):
+                return tenant
+        return None
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        # 1. Per-IP
+        ip = self._client_ip(request)
+        ip_ok, ip_remaining, ip_reset = self._check(ip, self._ip_buckets, self.ip_limit, self.ip_window)
+        if not ip_ok:
+            from fastapi.responses import JSONResponse
+            return JSONResponse(
+                status_code=429,
+                content={"error": "rate limit exceeded (ip)", "limit": self.ip_limit,
+                         "reset_in_seconds": ip_reset},
+                headers={
+                    "X-RateLimit-Limit": str(self.ip_limit),
+                    "X-RateLimit-Remaining": "0",
+                    "X-RateLimit-Reset": str(ip_reset),
+                    "Retry-After": str(ip_reset),
+                },
+            )
+
+        # 2. Per-tenant (only if we can identify one)
+        tenant = self._tenant_key(request)
+        tenant_remaining = None
+        tenant_limit = None
+        if tenant and self.tenant_limit:
+            t_ok, t_remaining, t_reset = self._check(tenant, self._tenant_buckets,
+                                                       self.tenant_limit, self.tenant_window)
+            if not t_ok:
+                from fastapi.responses import JSONResponse
+                return JSONResponse(
+                    status_code=429,
+                    content={"error": "rate limit exceeded (tenant)", "tenant": tenant,
+                             "limit": self.tenant_limit, "reset_in_seconds": t_reset},
+                    headers={
+                        "X-RateLimit-Tenant-Limit": str(self.tenant_limit),
+                        "X-RateLimit-Tenant-Remaining": "0",
+                        "X-RateLimit-Tenant-Reset": str(t_reset),
+                        "Retry-After": str(t_reset),
+                    },
+                )
+            tenant_remaining = t_remaining
+            tenant_limit = self.tenant_limit
+
+        response = await call_next(request)
+        response.headers["X-RateLimit-Limit"] = str(self.ip_limit)
+        response.headers["X-RateLimit-Remaining"] = str(ip_remaining)
+        response.headers["X-RateLimit-Reset"] = str(ip_reset)
+        if tenant_limit is not None:
+            response.headers["X-RateLimit-Tenant-Limit"] = str(tenant_limit)
+            response.headers["X-RateLimit-Tenant-Remaining"] = str(tenant_remaining or 0)
+        return response

dokeo-3.0.0/api/tracing.py

@@ -0,0 +1,74 @@
+"""Lightweight distributed tracing.
+
+Adds a request-scoped trace_id (8 bytes hex) and span_id (4 bytes hex)
+to every request. Exposed as response headers (X-Trace-Id, X-Span-Id)
+and threaded through the audit log so every scan is correlated.
+
+For real OTel export, swap _start_span() for opentelemetry.trace
+calls and add an exporter. The audit-log enrichment stays.
+"""
+from __future__ import annotations
+import os
+import secrets
+import time
+import uuid
+from contextvars import ContextVar
+
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import Response
+
+
+_current_trace: ContextVar = ContextVar("trace_id", default="")
+_current_span: ContextVar = ContextVar("span_id", default="")
+_span_start: ContextVar = ContextVar("span_start", default=0.0)
+
+
+def current_trace_id() -> str:
+    return _current_trace.get()
+
+
+def current_span_id() -> str:
+    return _current_span.get()
+
+
+def _start_span() -> tuple[str, str, float]:
+    trace = _current_trace.get() or uuid.uuid4().hex[:16]
+    span = secrets.token_hex(4)
+    return trace, span, time.time()
+
+
+class TraceMiddleware(BaseHTTPMiddleware):
+    """Assigns a trace_id+span_id to every request. Logs duration."""
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        # Inherit trace from upstream header if present (so a load balancer
+        # or proxy can stitch traces together).
+        incoming_trace = request.headers.get("x-trace-id")
+        if incoming_trace:
+            tok_t = _current_trace.set(incoming_trace)
+        else:
+            tok_t = _current_trace.set(uuid.uuid4().hex[:16])
+        trace_id = _current_trace.get()
+        span_id = secrets.token_hex(4)
+        tok_s = _current_span.set(span_id)
+        start = time.time()
+        tok_start = _span_start.set(start)
+        response = await call_next(request)
+        duration_ms = round((time.time() - start) * 1000, 1)
+        _current_span.reset(tok_s)
+        _current_trace.reset(tok_t)
+        _span_start.reset(tok_start)
+        response.headers["X-Trace-Id"] = trace_id
+        response.headers["X-Span-Id"] = span_id
+        response.headers["X-Trace-Duration-Ms"] = str(duration_ms)
+        response.headers["X-Trace-Duration-Ms"] = str(duration_ms)
+        # Structured log line
+        import sys
+        print(
+            f'{{"event":"http.trace","service":"dokeo-api","trace_id":"{trace_id}",'
+            f'"span_id":"{span_id}","method":"{request.method}","path":"{request.url.path}",'
+            f'"status":{response.status_code},"duration_ms":{duration_ms}}}',
+            file=sys.stderr,
+        )
+        return response

dokeo-3.0.0/api/user.py

@@ -0,0 +1,49 @@
+"""Clerk user identity - extracted from headers injected by the Next.js proxy.
+
+The Next.js route handler reads the Clerk session server-side and forwards
+identity as headers. This module makes them available to FastAPI handlers
+as a dependency:
+
+    from api.user import current_user
+    def scan(user: User = Depends(current_user)): ...
+
+In dev (no headers), falls back to an anonymous user so the API still works
+when called directly without going through Next.js.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from fastapi import Depends, Header
+
+
+@dataclass
+class User:
+    """The caller's identity. `id` is the Clerk user ID, or 'anonymous' in dev."""
+    id: str = "anonymous"
+    email: str = ""
+    name: str = ""
+
+    @property
+    def is_anonymous(self) -> bool:
+        return self.id == "anonymous"
+
+    @property
+    def display_name(self) -> str:
+        return self.name or self.email or self.id
+
+
+def current_user(
+    x_dokeo_user_id: Optional[str] = Header(None, alias="X-Dokeo-User-Id"),
+    x_dokeo_user_email: Optional[str] = Header(None, alias="X-Dokeo-User-Email"),
+    x_dokeo_user_name: Optional[str] = Header(None, alias="X-Dokeo-User-Name"),
+) -> User:
+    """FastAPI dependency: the Clerk user making this request."""
+    if not x_dokeo_user_id:
+        return User()
+    return User(
+        id=x_dokeo_user_id,
+        email=x_dokeo_user_email or "",
+        name=x_dokeo_user_name or "",
+    )