footprinter-cli 1.0.0rc1__py3-none-any.whl

footprinter/services/access_service.py

@@ -0,0 +1,342 @@
+"""access_service — access gating, visibility filtering, and permission resolution.
+
+Combines the former ``read_service`` (3-stage gating) and ``visibility``
+(list filtering, inherit resolution, opaque field sets) into one module.
+
+Gating stages (for non-ADMIN roles):
+  1. Existence — item must exist in DB
+  2. Visibility — ``mcp_view`` must not be hidden/opaque
+  3. Permission — ``mcp_read`` must not be deny
+
+Visibility values: 'hidden' -> exclude, 'opaque' -> minimal fields,
+'visible' -> full.  'inherit' -> resolves to the global policy at query
+time (loaded by ``load_globals``).  Missing (None) -> treated as 'opaque'
+(fail-closed).
+"""
+
+import logging
+import sqlite3
+from typing import Any, Dict, List, Optional, Tuple
+
+from footprinter.db.chats import get_chat_detail
+from footprinter.db.emails import get_email
+from footprinter.db.files import get_file
+from footprinter.services.roles import Role
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    # Gating
+    "gate_access",
+    "VALID_TYPES",
+    # Visibility resolution
+    "load_globals",
+    "resolve_inherit_visibility",
+    "resolve_inherit_permission",
+    "has_global_permission",
+    "is_global_policy_loaded",
+    # List filtering
+    "filter_result",
+    "filter_results_list",
+    "strip_content_for_denied",
+    "get_opaque_metadata",
+    # Opaque field sets
+    "OPAQUE_FILE_FIELDS",
+    "OPAQUE_EMAIL_FIELDS",
+    "OPAQUE_CHAT_FIELDS",
+    "OPAQUE_FOLDER_FIELDS",
+    "OPAQUE_BROWSER_FIELDS",
+    "OPAQUE_PROJECT_FIELDS",
+    "OPAQUE_CLIENT_FIELDS",
+    "_read_visibility",
+    "_filter_to_opaque",
+    "_CONTENT_FIELDS",
+]
+
+VALID_TYPES = frozenset({"file", "email", "chat"})
+
+# ---------------------------------------------------------------------------
+# Global policy cache — refreshed per-request by load_globals()
+# ---------------------------------------------------------------------------
+
+_global_visibility: Optional[str] = None
+_global_permission: Optional[str] = None
+
+
+def load_globals(conn: sqlite3.Connection) -> None:
+    """Read global visibility and permission policies and cache them.
+
+    Called once per MCP request (from ``get_db()``).  Two PK lookups.
+    """
+    global _global_visibility, _global_permission
+
+    row = conn.execute("SELECT setting FROM visibility_policies WHERE scope = 'global'").fetchone()
+    _global_visibility = row["setting"] if row else None
+
+    row = conn.execute("SELECT setting FROM permission_policies WHERE scope = 'global'").fetchone()
+    _global_permission = row["setting"] if row else None
+
+
+def has_global_permission() -> bool:
+    """Return whether the cached global permission is 'allow'.
+
+    Public replacement for direct ``_global_permission`` access.
+    """
+    return _global_permission == "allow"
+
+
+def is_global_policy_loaded() -> bool:
+    """Return whether a global permission policy has been loaded.
+
+    Unlike ``has_global_permission()`` which checks if the policy is
+    specifically ``'allow'``, this checks whether *any* policy exists.
+    """
+    return _global_permission is not None
+
+
+# ---------------------------------------------------------------------------
+# Inherit resolution
+# ---------------------------------------------------------------------------
+
+
+def resolve_inherit_visibility(value: Optional[str]) -> str:
+    """Resolve a visibility value, mapping ``inherit`` to the global policy.
+
+    - ``None`` -> ``'opaque'`` (fail-closed: truly missing data)
+    - ``'inherit'`` -> cached global visibility, or ``'opaque'`` baseline
+    - Explicit values (``'hidden'``, ``'opaque'``, ``'visible'``) pass through
+    """
+    if value is None:
+        return "opaque"
+    if value == "inherit":
+        return _global_visibility or "opaque"
+    return value
+
+
+def resolve_inherit_permission(value: Optional[str]) -> str:
+    """Resolve a permission value, mapping ``inherit`` to the global policy.
+
+    - ``None`` -> ``'deny'`` (fail-closed: truly missing data)
+    - ``'inherit'`` -> cached global permission, or ``'allow'`` baseline
+      (``BASELINE_PERMISSION = True`` in permissions.py)
+    - Explicit values (``'allow'``, ``'deny'``) pass through
+    """
+    if value is None:
+        return "deny"
+    if value == "inherit":
+        return _global_permission or "allow"
+    return value
+
+
+# ---------------------------------------------------------------------------
+# Opaque field sets
+# ---------------------------------------------------------------------------
+
+OPAQUE_FILE_FIELDS = {"id", "content_type", "source", "project_id"}
+OPAQUE_EMAIL_FIELDS = {"id", "account", "project_id", "client_id"}
+OPAQUE_CHAT_FIELDS = {"id", "account", "project_id", "client_id"}
+OPAQUE_FOLDER_FIELDS = {"id", "direct_files", "direct_file_count", "source", "project_id"}
+OPAQUE_BROWSER_FIELDS = {"id", "browser", "project_id"}
+OPAQUE_PROJECT_FIELDS = {"id", "type", "project_type", "status", "client_id"}
+OPAQUE_CLIENT_FIELDS = {"id", "client_type", "status"}
+
+
+# ---------------------------------------------------------------------------
+# List filtering
+# ---------------------------------------------------------------------------
+
+
+def _read_visibility(result: Dict[str, Any]) -> str:
+    """Read mcp_view from a result dict, resolving ``inherit`` via global policy."""
+    return resolve_inherit_visibility(result.get("mcp_view"))
+
+
+def filter_result(item_type: str, full_result: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """Filter a single result dict based on its ``mcp_view`` value.
+
+    Returns None if hidden, minimal dict if opaque, full dict if visible.
+    """
+    visibility = _read_visibility(full_result)
+
+    if visibility == "hidden":
+        return None
+
+    if visibility == "opaque":
+        return _filter_to_opaque(item_type, full_result)
+
+    return full_result  # visible
+
+
+def filter_results_list(
+    item_type: str, results: List[Dict[str, Any]], id_key: str = "id"
+) -> Tuple[List[Dict[str, Any]], int]:
+    """Filter a list of results, returning filtered list and suppressed count.
+
+    Reads ``mcp_view`` from each result dict instead of querying the database.
+    """
+    filtered = []
+    suppressed = 0
+
+    for result in results:
+        visibility = _read_visibility(result)
+
+        if visibility == "hidden":
+            suppressed += 1
+            continue
+
+        if visibility == "opaque":
+            filtered.append(_filter_to_opaque(item_type, result))
+        else:
+            filtered.append(result)
+
+    return filtered, suppressed
+
+
+def _filter_to_opaque(item_type: str, result: Dict[str, Any]) -> Dict[str, Any]:
+    """Filter a result dict to only include opaque-allowed fields."""
+    if item_type == "file":
+        allowed = OPAQUE_FILE_FIELDS
+    elif item_type == "email":
+        allowed = OPAQUE_EMAIL_FIELDS
+    elif item_type == "chat":
+        allowed = OPAQUE_CHAT_FIELDS
+    elif item_type == "folder":
+        allowed = OPAQUE_FOLDER_FIELDS
+    elif item_type == "visit":
+        allowed = OPAQUE_BROWSER_FIELDS
+    elif item_type == "project":
+        allowed = OPAQUE_PROJECT_FIELDS
+    elif item_type == "client":
+        allowed = OPAQUE_CLIENT_FIELDS
+    else:
+        allowed = {"id"}
+
+    return {k: v for k, v in result.items() if k in allowed}
+
+
+# Content fields that listing tools must strip when mcp_read != 'allow'
+_CONTENT_FIELDS: Dict[str, List[str]] = {
+    "chat": ["snippet", "summary"],
+    "email": ["snippet"],
+    "file": ["snippet"],
+}
+
+
+def strip_content_for_denied(item_type: str, results: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Strip content fields from results where resolved permission is not 'allow'.
+
+    Uses ``resolve_inherit_permission`` so that ``inherit`` resolves to the
+    global policy (or baseline ``'allow'`` when no global policy is loaded).
+    ``NULL`` / missing values fail closed to ``'deny'``.  Items are NOT
+    removed — only content keys are deleted, preserving the "you matched
+    something" signal.
+    """
+    fields = _CONTENT_FIELDS.get(item_type, [])
+    if not fields:
+        return results
+
+    for result in results:
+        if resolve_inherit_permission(result.get("mcp_read")) != "allow":
+            for field in fields:
+                result.pop(field, None)
+    return results
+
+
+def get_opaque_metadata(conn: sqlite3.Connection, item_type: str, item_id: int) -> Dict[str, Any]:
+    """Get opaque metadata for an item, filtered to opaque-allowed fields.
+
+    Used by footprinter_read when returning visibility-restricted errors.
+    Delegates to db/ layer for the fetch, then filters to opaque fields.
+    """
+    if item_type == "file":
+        row = get_file(conn, item_id)
+    elif item_type == "email":
+        row = get_email(conn, item_id)
+    elif item_type == "chat":
+        row = get_chat_detail(conn, item_id)
+    else:
+        return {}
+
+    if not row:
+        return {}
+    return _filter_to_opaque(item_type, row)
+
+
+# ---------------------------------------------------------------------------
+# 3-stage access gating
+# ---------------------------------------------------------------------------
+
+
+def gate_access(
+    conn: sqlite3.Connection,
+    item_type: str,
+    item_id: int,
+    *,
+    role: Role = Role.ADMIN,
+) -> dict:
+    """3-stage access gating + content for a single item.
+
+    Returns dict with ``status`` key:
+
+    - ``ok`` — access granted; includes ``metadata`` (+ ``content`` for email/chat)
+    - ``hidden`` — item hidden from this role
+    - ``opaque`` — minimal ``metadata`` only
+    - ``denied`` — permission denied
+    - ``not_found`` — item doesn't exist
+    - ``invalid_type`` — unrecognised item_type
+    """
+    if item_type not in VALID_TYPES:
+        return {"status": "invalid_type"}
+
+    # Stage 1: Existence — fetch full detail via db/ layer
+    if item_type == "file":
+        metadata = get_file(conn, item_id)
+    elif item_type == "email":
+        metadata = get_email(conn, item_id)
+    else:
+        metadata = get_chat_detail(conn, item_id)
+
+    if not metadata:
+        return {"status": "not_found"}
+
+    # Stage 2: Visibility (ADMIN bypasses)
+    if not role.sees_all:
+        visibility = resolve_inherit_visibility(metadata.get("mcp_view"))
+        if visibility == "hidden":
+            return {"status": "hidden"}
+        if visibility == "opaque":
+            return {
+                "status": "opaque",
+                "metadata": _filter_to_opaque(item_type, metadata),
+            }
+
+    # Stage 3: Permission (ADMIN bypasses)
+    if not role.sees_all:
+        if resolve_inherit_permission(metadata.get("mcp_read")) == "deny":
+            return {
+                "status": "denied",
+                "metadata": _filter_to_opaque(item_type, metadata),
+            }
+
+    # Stage 4: Return content — reuse metadata already fetched
+    if item_type == "file":
+        return {"status": "ok", "metadata": metadata}
+    elif item_type == "email":
+        content = metadata.pop("body_preview", "") or ""
+        return {"status": "ok", "metadata": metadata, "content": content}
+    else:
+        messages = metadata.pop("messages", [])
+        summary = metadata.pop("summary", None) or ""
+        content_parts = []
+        if summary:
+            content_parts.append(f"Summary: {summary}")
+        for msg in messages:
+            role_name = msg.get("role") or "unknown"
+            text = msg.get("content") or ""
+            timestamp = msg.get("created_at") or ""
+            if timestamp:
+                content_parts.append(f"[{timestamp}] {role_name}: {text}")
+            else:
+                content_parts.append(f"{role_name}: {text}")
+        content = "\n\n".join(content_parts)
+        return {"status": "ok", "metadata": metadata, "content": content}

footprinter/services/chat_service.py

@@ -0,0 +1,85 @@
+"""Chat read service — get/list with role-based visibility filtering."""
+
+import sqlite3
+from typing import Optional
+
+from footprinter.db import chats as db
+from footprinter.services.access_service import (
+    filter_result,
+    filter_results_list,
+    strip_content_for_denied,
+)
+from footprinter.services.roles import Role
+
+
+def get(conn: sqlite3.Connection, chat_id: int, *, role: Role = Role.ADMIN) -> dict | None:
+    """Fetch a single chat with messages by ID, filtered by role."""
+    result = db.get_chat_detail(conn, chat_id)
+    if result is None:
+        return None
+    if role.sees_all:
+        return result
+    return filter_result("chat", result)
+
+
+def assign(
+    conn: sqlite3.Connection,
+    chat_id: int,
+    *,
+    role: Role = Role.ADMIN,
+    project_id: int | None = None,
+    client_id: int | None = None,
+) -> dict | None:
+    """Assign a chat to a project and/or client.
+
+    Returns result dict on success, None if not found.
+    Raises PermissionError if role cannot write.
+    """
+    if not role.can_write:
+        raise PermissionError("Role does not permit write operations")
+    result = db.update_chat_relationships(
+        conn,
+        chat_id,
+        project_id=project_id,
+        client_id=client_id,
+    )
+    if result is None:
+        return None
+    resp: dict = {"id": chat_id}
+    if project_id is not None:
+        resp["project_id"] = project_id
+    if client_id is not None:
+        resp["client_id"] = client_id
+    return resp
+
+
+def list_(
+    conn: sqlite3.Connection,
+    *,
+    role: Role = Role.ADMIN,
+    account: Optional[str] = None,
+    query: Optional[str] = None,
+    sort_by: str = "modified_at",
+    order: str = "desc",
+    status: Optional[str | list[str]] = None,
+    limit: int = 50,
+    page: int = 1,
+) -> dict:
+    """List chats with pagination, filtered by role."""
+    response = db.list_chats(
+        conn,
+        account=account,
+        query=query,
+        sort_by=sort_by,
+        order=order,
+        status=status,
+        limit=limit,
+        page=page,
+    )
+    if role.sees_all:
+        return response
+    filtered, suppressed = filter_results_list("chat", response["chats"])
+    filtered = strip_content_for_denied("chat", filtered)
+    response["chats"] = filtered
+    response["suppressed"] = suppressed
+    return response

footprinter/services/client_service.py

@@ -0,0 +1,267 @@
+"""Client service — get/list with role-based visibility, upsert and soft delete."""
+
+import sqlite3
+from typing import Optional
+
+from footprinter.db import clients as db
+from footprinter.services.access_service import (
+    _read_visibility,
+    filter_result,
+    filter_results_list,
+)
+from footprinter.services.includes import validate_include
+from footprinter.services.roles import Role
+
+VALID_INCLUDES = frozenset({"projects", "aggregates"})
+
+
+def _get_client_aggregates(client_name: str, conn: sqlite3.Connection, *, role: Role) -> dict:
+    """Compute per-project file counts for a client, respecting visibility.
+
+    Derives aggregates from the visibility-filtered project list rather
+    than raw SQL, so hidden/opaque projects are excluded for non-admin roles.
+    """
+    from footprinter.services import project_service
+
+    resp = project_service.list_(conn, role=role, client=client_name)
+    per_project = [
+        {
+            "project_id": p["id"],
+            "project_name": p["name"],
+            "file_count": p.get("file_count", 0),
+        }
+        for p in resp["projects"]
+        if "name" in p  # Exclude opaque projects (minimal dicts lack "name")
+    ]
+    return {
+        "project_count": len(per_project),
+        "file_count": sum(p["file_count"] for p in per_project),
+        "per_project": per_project,
+    }
+
+
+def get(
+    conn: sqlite3.Connection,
+    client_id: int,
+    *,
+    role: Role = Role.ADMIN,
+    include: list[str] | None = None,
+) -> dict | None:
+    """Fetch a single client by ID, filtered by role.
+
+    Pass ``include`` to attach nested data:
+    - ``"projects"`` — list of projects belonging to this client
+    - ``"aggregates"`` — file counts per project
+    """
+    includes = validate_include(include, VALID_INCLUDES)
+    result = db.get_client(conn, client_id)
+    if result is None:
+        return None
+
+    # Strip nested data that db layer embeds by default
+    result.pop("projects", None)
+    result.pop("file_count", None)
+
+    # Attach includes only when caller has full access to this entity
+    is_full = role.sees_all or _read_visibility(result) == "visible"
+    if is_full and includes:
+        if "projects" in includes:
+            from footprinter.services import project_service
+
+            resp = project_service.list_(conn, role=role, client=result["name"])
+            result["projects"] = resp["projects"]
+        if "aggregates" in includes:
+            result["aggregates"] = _get_client_aggregates(
+                result["name"],
+                conn,
+                role=role,
+            )
+
+    if role.sees_all:
+        return result
+    return filter_result("client", result)
+
+
+def list_(
+    conn: sqlite3.Connection,
+    *,
+    role: Role = Role.ADMIN,
+    include: list[str] | None = None,
+    status: Optional[str | list[str]] = None,
+    limit: int = 50,
+    page: int = 1,
+) -> dict:
+    """List clients with pagination, filtered by role."""
+    includes = validate_include(include, VALID_INCLUDES)
+    response = db.list_clients(conn, status=status, limit=limit, page=page)
+
+    # Track which items are fully visible before filtering strips fields
+    visible_ids: set[int] = set()
+    if includes and not role.sees_all:
+        visible_ids = {c["id"] for c in response["clients"] if _read_visibility(c) == "visible"}
+
+    if not role.sees_all:
+        filtered, suppressed = filter_results_list("client", response["clients"])
+        response["clients"] = filtered
+        response["suppressed"] = suppressed
+
+    if includes:
+        for client in response["clients"]:
+            # Only attach to fully-visible items (admin sees all)
+            if not role.sees_all and client["id"] not in visible_ids:
+                continue
+            if "projects" in includes:
+                from footprinter.services import project_service
+
+                resp = project_service.list_(conn, role=role, client=client["name"])
+                client["projects"] = resp["projects"]
+            if "aggregates" in includes:
+                client["aggregates"] = _get_client_aggregates(
+                    client["name"],
+                    conn,
+                    role=role,
+                )
+
+    return response
+
+
+def resolve_by_name(
+    conn: sqlite3.Connection,
+    name: str,
+    *,
+    role: Role = Role.ADMIN,
+) -> dict | None:
+    """Resolve a client by fuzzy name match, with navigation data.
+
+    Returns full client dict with projects and aggregates for single match,
+    disambiguation dict for multiple ambiguous matches, or None.
+    """
+    rows = db.find_by_name_fuzzy(conn, name)
+    if not rows:
+        return None
+
+    # Filter hidden for VIEWER
+    if not role.sees_all:
+        rows = [r for r in rows if _read_visibility(r) != "hidden"]
+    if not rows:
+        return None
+
+    if len(rows) == 1:
+        return _build_client_navigation(conn, rows[0], role=role)
+
+    # Check exact match
+    exact = [r for r in rows if r["name"].lower() == name.lower()]
+    if len(exact) == 1:
+        return _build_client_navigation(conn, exact[0], role=role)
+
+    # Disambiguation
+    from footprinter.services.access_service import resolve_inherit_visibility
+
+    matches = []
+    for r in rows:
+        vis = resolve_inherit_visibility(r.get("mcp_view"))
+        if vis == "opaque":
+            matches.append({"id": r["id"], "visibility": "restricted"})
+        else:
+            matches.append({"id": r["id"], "name": r["name"]})
+    return {
+        "disambiguation": True,
+        "message": f"Multiple matches for '{name}'. Please be more specific.",
+        "matches": matches,
+    }
+
+
+def _build_client_navigation(conn: sqlite3.Connection, row: dict, *, role: Role) -> dict:
+    """Build full client navigation dict from a client row."""
+    visibility = _read_visibility(row)
+    if not role.sees_all and visibility == "opaque":
+        return filter_result("client", row)
+
+    # Get projects for this client (hidden filtered)
+    from footprinter.services import project_service
+
+    proj_resp = project_service.list_(conn, role=role, client=row["name"])
+    projects = proj_resp["projects"]
+
+    result = {**row}
+    result["projects"] = projects
+
+    # Aggregate stats across all projects
+    project_ids = [p["id"] for p in projects if "id" in p]
+    nav = db.get_client_navigation(conn, row["id"], project_ids)
+    result.update(nav)
+
+    return result
+
+
+def upsert(
+    conn: sqlite3.Connection,
+    *,
+    name: str,
+    client_type: str,
+    role: Role = Role.ADMIN,
+    path_pattern: Optional[str] = None,
+    status: Optional[str] = None,
+    status_reason: Optional[str] = None,
+    slug: Optional[str] = None,
+) -> dict:
+    """Insert or update a client by name.
+
+    Matches on ``name`` (UNIQUE constraint). Returns dict with ``id``,
+    ``action`` ("created"|"updated"), and ``slug`` on create.
+    Raises PermissionError if role cannot write, ValueError on bad input.
+    """
+    if not role.can_write:
+        raise PermissionError("Role does not permit write operations")
+
+    name = (name or "").strip()
+    if not name:
+        raise ValueError("Name cannot be empty")
+
+    existing_id = db.find_client_id_by_name(conn, name)
+
+    if existing_id is None:
+        result = db.create_client(
+            conn,
+            name=name,
+            client_type=client_type,
+            path_pattern=path_pattern,
+        )
+        new_id = result["id"]
+        # Apply optional fields that create_client doesn't accept
+        post_update: dict = {}
+        if status is not None:
+            post_update["status"] = status
+        if post_update:
+            db.update_client(conn, new_id, **post_update)
+        return {"id": new_id, "slug": result["slug"], "action": "created"}
+
+    update_fields: dict = {"client_type": client_type}
+    if path_pattern is not None:
+        update_fields["path_pattern"] = path_pattern
+    if status is not None:
+        update_fields["status"] = status
+        if status_reason is not None:
+            update_fields["status_reason"] = status_reason
+    db.update_client(conn, existing_id, **update_fields)
+    return {"id": existing_id, "action": "updated"}
+
+
+def delete(
+    conn: sqlite3.Connection,
+    client_id: int,
+    *,
+    role: Role = Role.ADMIN,
+) -> dict | None:
+    """Soft-delete a client by setting status to 'removed'.
+
+    Returns ``{"id", "status"}`` on success, ``None`` if not found.
+    Raises PermissionError if role cannot write.
+    """
+    if not role.can_write:
+        raise PermissionError("Role does not permit write operations")
+
+    result = db.update_client(conn, client_id, status="removed", status_reason="cli:delete")
+    if result is None:
+        return None
+    return {"id": client_id, "status": "removed"}