marvisx-cli 0.1.0__py3-none-any.whl

core/api/security.py

@@ -0,0 +1,652 @@
+# v1.7.0 - 2026-03-10 - Add resolve_session_owner for session-based MCP client attribution
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import secrets
+import time
+import uuid
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+import aiosqlite
+import bcrypt
+import jwt
+from fastapi import Depends, HTTPException, Request
+from fastapi.responses import Response
+
+from core.api.config import settings
+from core.api.db import get_db
+from core.api.models import UserInfo
+
+logger = logging.getLogger(__name__)
+
+ALGORITHM = "HS256"
+
+# Static system identities always considered valid (not in DB).
+_SYSTEM_IDENTITIES: set[str] = {"marvis-local", "console-api"}
+
+# Valid agent names for X-Agent-Name header. Used by both auth functions.
+# Spoofable by anyone with the token — for attribution only, not access control.
+# Initialized with generic, name-free identities; extended dynamically from the
+# DB via get_valid_agent_names() and from settings.static_agent_identities
+# (deploy .env). OSS core hardcodes no tenant agent names here.
+_VALID_AGENT_NAMES = {"marvis-local", "console-api"}
+
+
+def _valid_static_agent_names() -> set[str]:
+    """Static agent identities: hardcoded generic set ∪ configured tenant names.
+
+    The configured names (settings.static_agent_identities) come from the deploy
+    .env. Read live so tests can override via monkeypatch. This list only matters
+    for the two paths that do NOT query the DB users table: the legacy shared
+    TASKS_API_TOKEN attribution and a stale-cache fallback. DB-backed agents
+    (e.g. seeded via migration) authenticate via get_valid_agent_names().
+    """
+    return _VALID_AGENT_NAMES | set(settings.static_agent_identities)
+
+# In-memory cache for dynamic agent names from DB
+_agent_names_cache: set[str] = set()
+_cache_expires_at: float = 0.0
+_CACHE_TTL_SECONDS: float = 300.0  # 5 minutes
+
+
+async def get_valid_agent_names(db: aiosqlite.Connection) -> set[str]:
+    """Return valid agent names: DB slugs union system identities. Cached for 5 minutes."""
+    global _agent_names_cache, _cache_expires_at
+    now = time.monotonic()
+    if now < _cache_expires_at and _agent_names_cache:
+        return _agent_names_cache | _SYSTEM_IDENTITIES
+    try:
+        async with db.execute(
+            "SELECT slug FROM users WHERE type = 'agent' AND deleted_at IS NULL"
+        ) as cur:
+            rows = await cur.fetchall()
+        _agent_names_cache = {row[0] for row in rows}
+        _cache_expires_at = now + _CACHE_TTL_SECONDS
+    except Exception:
+        logger.warning("get_valid_agent_names: DB query failed, using stale cache")
+    return _agent_names_cache | _SYSTEM_IDENTITIES
+
+
+def verify_password(password: str, hashed: str) -> bool:
+    """Verify password against bcrypt hash. bcrypt.checkpw is already constant-time."""
+    return bcrypt.checkpw(password.encode("utf-8"), hashed.encode("utf-8"))
+
+
+def create_session_jwt(
+    username: str,
+    extra_claims: dict | None = None,
+) -> tuple[str, str, datetime]:
+    """Create JWT session token. Returns (token, jti, expires_at).
+
+    extra_claims: optional dict merged into JWT payload (e.g. workspace_id for SSO).
+    """
+    jti = str(uuid.uuid4())
+    expires_at = datetime.now(timezone.utc) + timedelta(hours=settings.jwt_expiry_hours)
+    payload = {
+        "sub": username,
+        "jti": jti,
+        "exp": expires_at,
+        "iat": datetime.now(timezone.utc),
+    }
+    if extra_claims:
+        payload.update(extra_claims)
+    token = jwt.encode(payload, settings.pir_jwt_secret, algorithm=ALGORITHM)
+    return token, jti, expires_at
+
+
+def verify_session_jwt(token: str) -> dict:
+    """Verify and decode JWT. Raises jwt.exceptions on failure."""
+    return jwt.decode(
+        token,
+        settings.pir_jwt_secret,
+        algorithms=[ALGORITHM],
+    )
+
+
+async def is_token_blacklisted(jti: str, db: aiosqlite.Connection) -> bool:
+    """Check if token JTI is in blacklist."""
+    cursor = await db.execute("SELECT 1 FROM token_blacklist WHERE jti = ?", (jti,))
+    return await cursor.fetchone() is not None
+
+
+async def blacklist_token(
+    jti: str, expires_at: datetime, db: aiosqlite.Connection
+) -> None:
+    """Add token to persistent blacklist."""
+    await db.execute(
+        "INSERT OR IGNORE INTO token_blacklist (jti, expires_at) VALUES (?, ?)",
+        (jti, expires_at.isoformat()),
+    )
+    await db.commit()
+
+
+def set_auth_cookie(response: Response, token: str) -> None:
+    """Set httpOnly session cookie."""
+    response.set_cookie(
+        key="pir_session",
+        value=token,
+        httponly=True,
+        secure=True,
+        samesite="lax",
+        domain=settings.cookie_domain if settings.is_production else None,
+        path="/",
+        max_age=settings.jwt_expiry_hours * 3600,
+    )
+
+
+def clear_auth_cookie(response: Response) -> None:
+    """Remove session cookie."""
+    response.delete_cookie(
+        key="pir_session",
+        httponly=True,
+        secure=True,
+        samesite="lax",
+        domain=settings.cookie_domain if settings.is_production else None,
+        path="/",
+    )
+
+
+# In-memory WS ticket store (single-worker pir-api). Tickets are ephemeral
+# (30s TTL, single-use), so they do NOT need the transactional main DB — and
+# more importantly must NOT go through the shared _write_lock, whose contention
+# added 8.5s p95 lock-wait on terminal open/connect (diagnostic 2026-05-27).
+# A restart of pir-api drops pending tickets, which is fine: a restart also tears
+# down every WebSocket, so any pending ticket would be useless anyway.
+# Atomicity note: the asyncio event loop is single-threaded, so the check-then-set
+# in consume (used flag) is atomic as long as there is no `await` between them.
+_ws_tickets: dict[str, dict[str, Any]] = {}
+
+
+def _purge_expired_ws_tickets(now: datetime | None = None) -> None:
+    """Drop expired tickets from the in-memory store (lazy GC)."""
+    current = now or datetime.now(timezone.utc)
+    expired = [t for t, rec in _ws_tickets.items() if current > rec["expires_at"]]
+    for t in expired:
+        _ws_tickets.pop(t, None)
+
+
+def cleanup_expired_ws_tickets() -> int:
+    """Public hook for the periodic cleanup loop. Returns count purged."""
+    before = len(_ws_tickets)
+    _purge_expired_ws_tickets()
+    return before - len(_ws_tickets)
+
+
+async def create_ws_ticket(
+    username: str,
+    session_name: str,
+    *,
+    timings: dict[str, float | str] | None = None,
+) -> str:
+    """Create opaque WS ticket. 30s TTL, single-use. In-memory (no DB write_lock)."""
+    ticket = secrets.token_urlsafe(32)
+    expires_at = datetime.now(timezone.utc) + timedelta(
+        seconds=settings.ws_ticket_ttl_seconds
+    )
+    _purge_expired_ws_tickets()
+    _ws_tickets[ticket] = {
+        "user_id": username,
+        "session_name": session_name,
+        "expires_at": expires_at,
+        "used": False,
+    }
+    if timings is not None:
+        timings["insert_ms"] = 0.0
+        timings["commit_ms"] = 0.0
+    return ticket
+
+
+async def consume_ws_ticket(
+    ticket: str,
+    session_name: str,
+    *,
+    timings: dict[str, float | str] | None = None,
+) -> str | None:
+    """Consume WS ticket. Returns username if valid, None otherwise. Single-use."""
+    logger.info("consume_ws_ticket: ticket=%s... session=%s", ticket[:15], session_name)
+    if timings is not None:
+        timings["lookup_ms"] = 0.0
+
+    rec = _ws_tickets.get(ticket)
+    if rec is None:
+        logger.warning("consume_ws_ticket: ticket NOT FOUND")
+        if timings is not None:
+            timings["outcome"] = "not_found"
+        return None
+
+    if rec["used"]:
+        logger.warning("consume_ws_ticket: ticket already used")
+        if timings is not None:
+            timings["outcome"] = "used"
+        return None
+
+    if rec["session_name"] != session_name:
+        logger.warning(
+            "consume_ws_ticket: session mismatch: %s != %s",
+            rec["session_name"],
+            session_name,
+        )
+        if timings is not None:
+            timings["outcome"] = "session_mismatch"
+        return None
+
+    expires_at = rec["expires_at"]
+    if datetime.now(timezone.utc) > expires_at:
+        logger.warning("consume_ws_ticket: ticket expired at %s", expires_at)
+        _ws_tickets.pop(ticket, None)
+        if timings is not None:
+            timings["outcome"] = "expired"
+        return None
+
+    # Mark as used — single-use. Atomic: no `await` between the check above and
+    # this set on the single-threaded event loop.
+    rec["used"] = True
+    if timings is not None:
+        timings["update_ms"] = 0.0
+        timings["commit_ms"] = 0.0
+        timings["outcome"] = "ok"
+    return rec["user_id"]
+
+
+async def get_current_user(
+    request: Request, db: aiosqlite.Connection = Depends(get_db)
+) -> UserInfo:
+    """FastAPI dependency: extract and verify user from httpOnly cookie."""
+    token = request.cookies.get("pir_session")
+    if not token:
+        raise HTTPException(
+            status_code=401,
+            detail=(
+                "Not authenticated. Reason: no 'pir_session' cookie on the request. "
+                "Fix: POST /api/v1/auth/login with {email, password} to set the httpOnly cookie, "
+                "or call this endpoint with Authorization: Bearer <token> if you are an agent "
+                "(see get_current_user_or_agent for dual-auth endpoints)."
+            ),
+        )
+
+    try:
+        payload = verify_session_jwt(token)
+    except jwt.ExpiredSignatureError:
+        raise HTTPException(
+            status_code=401,
+            detail=(
+                "Token expired. Reason: the pir_session JWT exp claim is in the past "
+                f"(configured TTL: {settings.jwt_expiry_hours}h). "
+                "Fix: POST /api/v1/auth/login to obtain a fresh session cookie."
+            ),
+        )
+    except jwt.InvalidTokenError:
+        raise HTTPException(
+            status_code=401,
+            detail=(
+                "Invalid token. Reason: pir_session JWT signature verification failed "
+                "(wrong secret, tampered payload, or malformed token). "
+                "Fix: clear the cookie and POST /api/v1/auth/login to re-authenticate. "
+                "If the server was recently redeployed with a new PIR_JWT_SECRET, all old tokens are invalidated by design."
+            ),
+        )
+
+    jti = payload.get("jti")
+    if jti and await is_token_blacklisted(jti, db):
+        raise HTTPException(
+            status_code=401,
+            detail=(
+                "Token revoked. Reason: this token's jti is in the token_blacklist table (logout or admin revoke). "
+                "Fix: POST /api/v1/auth/login to obtain a fresh session."
+            ),
+        )
+
+    slug = payload.get("sub")
+    if not slug:
+        raise HTTPException(
+            status_code=401,
+            detail=(
+                "Invalid token payload. Reason: decoded JWT is missing the 'sub' claim (user slug). "
+                "Fix: this token was not issued by our auth flow — clear the cookie and POST /api/v1/auth/login."
+            ),
+        )
+
+    # DB lookup obbligatorio -- verifica utente esiste e non cancellato
+    async with db.execute(
+        "SELECT id, system_role, display_name, workspace_id FROM users WHERE slug = ? AND deleted_at IS NULL",
+        (slug,),
+    ) as cursor:
+        row = await cursor.fetchone()
+
+    if row is None:
+        raise HTTPException(
+            status_code=401,
+            detail=(
+                f"User not found or deactivated (slug='{slug}'). "
+                "Reason: JWT 'sub' claim references a users row that was deleted (deleted_at IS NOT NULL) or never existed. "
+                "Fix: clear the cookie and POST /api/v1/auth/login with a valid account. "
+                "If this was your account, contact an admin to restore it (UPDATE users SET deleted_at = NULL)."
+            ),
+        )
+
+    # workspace_id from JWT claim (future SSO) or from users table, fallback ws_default
+    ws_id = (
+        payload.get("workspace_id")
+        or (row["workspace_id"] if "workspace_id" in row.keys() else None)
+        or "ws_default"
+    )
+
+    return UserInfo(
+        username=slug,
+        user_id=row["id"],
+        system_role=row["system_role"],
+        display_name=row["display_name"],
+        workspace_id=ws_id,
+    )
+
+
+def _hash_token(token: str) -> str:
+    """Return SHA-256 hex digest of a raw bearer token."""
+    return hashlib.sha256(token.encode("utf-8")).hexdigest()
+
+
+async def _lookup_agent_token(
+    bearer_token: str, db: aiosqlite.Connection
+) -> tuple[str, list[str], str] | None:
+    """Check agent_tokens table for a matching active token.
+
+    Returns (agent_name, scopes, workspace_id) if found and active, else None.
+    Uses constant-time comparison via secrets.compare_digest on the hash.
+    """
+    token_hash = _hash_token(bearer_token)
+    try:
+        async with db.execute(
+            "SELECT id, agent_name, scopes, workspace_id FROM agent_tokens WHERE token_hash = ? AND is_active = 1",
+            (token_hash,),
+        ) as cursor:
+            row = await cursor.fetchone()
+    except Exception:
+        # agent_tokens table not yet migrated — fall through to legacy token fallback
+        return None
+    if row is None:
+        return None
+    # Auth read paths use a read-only DB pool under single-writer mode, so
+    # best-effort telemetry updates must not happen inline here.
+    scopes_raw = row["scopes"] or "[]"
+    try:
+        scopes = json.loads(scopes_raw)
+    except (json.JSONDecodeError, TypeError):
+        scopes = []
+    ws_id = row["workspace_id"] or "ws_default"
+    return row["agent_name"], scopes, ws_id
+
+
+async def _resolve_agent_userinfo(
+    agent_name: str,
+    db: aiosqlite.Connection,
+    scopes: list[str] | None = None,
+    workspace_id: str = "ws_default",
+) -> UserInfo:
+    """Resolve agent_name to UserInfo via DB lookup (users table).
+
+    Falls back to viewer role if agent not found.
+    workspace_id comes from the token lookup (authoritative), not from users table.
+    scopes propagated for downstream scope enforcement via require_scope().
+    """
+    valid_names = await get_valid_agent_names(db)
+    if agent_name not in valid_names and agent_name not in _valid_static_agent_names():
+        agent_name = "agent"
+
+    async with db.execute(
+        "SELECT id, system_role, display_name, type FROM users WHERE slug = ? AND deleted_at IS NULL",
+        (agent_name,),
+    ) as cursor:
+        row = await cursor.fetchone()
+
+    if row is None:
+        return UserInfo(
+            username=f"agent:{agent_name}",
+            user_id="",
+            system_role="viewer",
+            user_type="agent",
+            display_name=agent_name,
+            scopes=scopes or [],
+            workspace_id=workspace_id,
+        )
+
+    return UserInfo(
+        username=agent_name,
+        user_id=row["id"],
+        system_role=row["system_role"],
+        user_type=row["type"] or "agent",
+        display_name=row["display_name"],
+        scopes=scopes or [],
+        workspace_id=workspace_id,
+    )
+
+
+async def get_current_user_or_agent(
+    request: Request, db: aiosqlite.Connection = Depends(get_db)
+) -> UserInfo:
+    """Dual auth: cookie (Console PiR web) OR Bearer token (agent).
+
+    Used for read-only endpoints accessible by both humans and agents.
+    Bearer token resolution order:
+    1. Per-agent token: check agent_tokens table (SHA-256 hash lookup)
+    2. Legacy single token: compare against settings.tasks_api_token
+    3. Fall back to pir_session cookie (existing Console PiR auth)
+
+    X-Agent-Name is attribution-only here — not verified against token owner.
+    Strict X-Agent-Name enforcement is reserved for get_agent_user (operator endpoints).
+    """
+    # Path 1 & 2: Bearer token for agents
+    auth_header = request.headers.get("authorization", "")
+    if auth_header.startswith("Bearer "):
+        bearer_token = auth_header[7:]
+
+        # 1. Per-agent token lookup (DB)
+        result = await _lookup_agent_token(bearer_token, db)
+        if result is not None:
+            agent_name, scopes, ws_id = result
+            # X-Agent-Name is attribution-only for read endpoints — no mismatch check.
+            # Strict verification is in get_agent_user (operator-level write endpoints).
+            return await _resolve_agent_userinfo(agent_name, db, scopes, ws_id)
+
+        # 2. Legacy single shared token fallback — bound to ws_default (P1-3 review fix)
+        if settings.tasks_api_token and secrets.compare_digest(
+            bearer_token, settings.tasks_api_token
+        ):
+            agent_name = request.headers.get("x-agent-name", "agent")
+            return await _resolve_agent_userinfo(
+                agent_name, db, workspace_id="ws_default"
+            )
+
+        raise HTTPException(
+            status_code=401,
+            detail=(
+                "Invalid API token. "
+                "Reason: Bearer token in Authorization header not found in agent_tokens DB "
+                "and does not match legacy TASKS_API_TOKEN. "
+                "Fix: (1) verify the token in Authorization: Bearer <token> is correct; "
+                "(2) check TASKS_API_TOKEN env is set and matches in /data/pir/.env for the legacy fallback; "
+                "(3) if using a per-agent token, rotate via POST /api/v1/agent-tokens (must include agent_name + scopes). "
+                "Docs: api/security.py::get_current_user_or_agent for resolution order."
+            ),
+        )
+
+    # Path 3: Cookie for Console PiR web
+    return await get_current_user(request, db)
+
+
+async def get_agent_user(
+    request: Request, db: aiosqlite.Connection = Depends(get_db)
+) -> UserInfo:
+    """Bearer-only auth per router /agent. Nessun fallback cookie.
+
+    Policy esplicita: solo agenti, no console web. Se il token manca o e errato → 401
+    senza tentare il cookie. Questo rende la policy visibile nel codice.
+
+    Resolution order:
+    1. Per-agent token (agent_tokens table)
+    2. Legacy single shared token (settings.tasks_api_token)
+
+    For per-agent tokens (path 1): if X-Agent-Name header is present,
+    it MUST match the agent_name bound to the token in DB. Returns 403 on mismatch.
+    Legacy token (path 2): X-Agent-Name is attribution-only, not verified.
+    """
+    auth_header = request.headers.get("authorization", "")
+    if not auth_header.startswith("Bearer "):
+        raise HTTPException(
+            status_code=401,
+            detail=(
+                "Bearer token required. Reason: this endpoint is agent-only (no cookie fallback); "
+                "the Authorization header must be 'Bearer <token>'. "
+                "Fix: add `Authorization: Bearer $TASKS_API_TOKEN` (legacy) or a per-agent token. "
+                "For MCP clients, set X-Agent-Name header too so actions are correctly attributed."
+            ),
+        )
+    bearer_token = auth_header[7:]
+
+    # 1. Per-agent token lookup
+    result = await _lookup_agent_token(bearer_token, db)
+    if result is not None:
+        agent_name, scopes, ws_id = result
+        # Verify X-Agent-Name header matches the token owner when present
+        claimed_name = request.headers.get("x-agent-name", "").strip()
+        if claimed_name and claimed_name != agent_name:
+            raise HTTPException(
+                status_code=403,
+                detail=(
+                    f"X-Agent-Name '{claimed_name}' does not match token owner '{agent_name}'. "
+                    "Reason: per-agent tokens are bound to a specific agent_name in agent_tokens; "
+                    "spoofing another agent's name is rejected (strict check on operator endpoints). "
+                    f"Fix: either remove the X-Agent-Name header (defaults to token owner '{agent_name}'), "
+                    f"or set it exactly to '{agent_name}', or use a token issued for '{claimed_name}'."
+                ),
+            )
+        return await _resolve_agent_userinfo(agent_name, db, scopes, ws_id)
+
+    # 2. Legacy single shared token — bound to ws_default (P1-3 review fix)
+    if settings.tasks_api_token and secrets.compare_digest(
+        bearer_token, settings.tasks_api_token
+    ):
+        agent_name = request.headers.get("x-agent-name", "agent")
+        if (
+            agent_name not in _valid_static_agent_names()
+            and agent_name not in _SYSTEM_IDENTITIES
+        ):
+            agent_name = "agent"
+        return UserInfo(username=f"agent:{agent_name}", workspace_id="ws_default")
+
+    raise HTTPException(
+        status_code=401,
+        detail=(
+            "Invalid API token. "
+            "Reason: Bearer token in Authorization header not found in agent_tokens DB "
+            "and does not match legacy TASKS_API_TOKEN. This endpoint is agent-only (no cookie fallback). "
+            "Fix: (1) verify the token is correct; (2) check TASKS_API_TOKEN env in /data/pir/.env matches; "
+            "(3) rotate a per-agent token via POST /api/v1/agent-tokens (admin). "
+            "Docs: api/security.py::get_agent_user for resolution order."
+        ),
+    )
+
+
+def require_agent_token_scope(*required_scopes: str):
+    """Require a per-agent token with explicit scopes.
+
+    Unlike get_agent_user(), this rejects the legacy shared token and enforces that
+    every requested scope is present on the matched agent_tokens row.
+    """
+    if not required_scopes:
+        raise ValueError("require_agent_token_scope() requires at least one scope")
+
+    async def check(
+        request: Request,
+        db: aiosqlite.Connection = Depends(get_db),
+    ) -> UserInfo:
+        auth_header = request.headers.get("authorization", "")
+        if not auth_header.startswith("Bearer "):
+            raise HTTPException(
+                status_code=401,
+                detail=(
+                    "Bearer token required. Reason: this endpoint requires a scoped per-agent token "
+                    f"(needs scopes: {list(required_scopes)}). "
+                    "Fix: add `Authorization: Bearer <per-agent-token>` header — the legacy shared token "
+                    "is NOT accepted here, only tokens issued via POST /api/v1/agent-tokens with the right scopes."
+                ),
+            )
+
+        bearer_token = auth_header[7:]
+        result = await _lookup_agent_token(bearer_token, db)
+        if result is None:
+            raise HTTPException(
+                status_code=401,
+                detail=(
+                    "Per-agent token required. Reason: the Bearer token is not present in agent_tokens "
+                    f"(this endpoint needs scopes {list(required_scopes)} and the legacy shared token is not accepted). "
+                    "Fix: mint a per-agent token via POST /api/v1/agent-tokens (admin) with the required scopes, "
+                    "then retry."
+                ),
+            )
+
+        agent_name, scopes, ws_id = result
+        claimed_name = request.headers.get("x-agent-name", "").strip()
+        if claimed_name and claimed_name != agent_name:
+            raise HTTPException(
+                status_code=403,
+                detail=(
+                    f"X-Agent-Name '{claimed_name}' does not match token owner '{agent_name}'. "
+                    "Reason: per-agent tokens are bound to a specific agent_name; spoofing is rejected. "
+                    f"Fix: remove X-Agent-Name header, or set it to '{agent_name}', or use a token issued for '{claimed_name}'."
+                ),
+            )
+
+        missing = [scope for scope in required_scopes if scope not in scopes]
+        if missing:
+            raise HTTPException(
+                status_code=403,
+                detail=(
+                    f"Token missing required scopes: {missing}. "
+                    f"Reason: this endpoint needs {list(required_scopes)} but token '{agent_name}' only has {scopes}. "
+                    f"Fix: mint a new token for '{agent_name}' that includes {missing} "
+                    "(admin: POST /api/v1/agent-tokens with scopes=<full list>), or have an admin add the scopes."
+                ),
+            )
+
+        return await _resolve_agent_userinfo(agent_name, db, scopes, ws_id)
+
+    return check
+
+
+async def resolve_session_owner(
+    request: Request, db: aiosqlite.Connection
+) -> str | None:
+    """Resolve owner slug from X-Session-Name header -> sessions_meta.owner_id -> users.slug.
+
+    Used by task creation/update endpoints to attribute actions to the session's
+    owner (human user) instead of the agent identity.
+
+    Returns owner slug or None if not resolvable (no header, no owner_id set,
+    or pre-migration — safe to call before migration 033 is applied).
+    """
+    session_name = request.headers.get("x-session-name", "").strip()
+    if not session_name:
+        return None
+    try:
+        cursor = await db.execute(
+            "SELECT sm.owner_id, u.slug FROM sessions_meta sm "
+            "LEFT JOIN users u ON sm.owner_id = u.id "
+            "WHERE sm.name = ? AND sm.owner_id IS NOT NULL",
+            (session_name,),
+        )
+        row = await cursor.fetchone()
+        if row and row["slug"]:
+            return row["slug"]
+    except Exception:
+        pass  # pre-migration safety: owner_id column may not exist yet
+    return None
+
+
+# Aliases for declarative use in routers — semantic clarity over raw function names.
+# require_cookie_auth: human console sessions only (no bearer token fallback)
+# require_any_auth: cookie OR bearer token (agents + humans)
+require_cookie_auth = get_current_user
+require_any_auth = get_current_user_or_agent