footprinter-cli 1.0.0rc1__py3-none-any.whl

footprinter/services/content_service.py

@@ -0,0 +1,181 @@
+"""content_service — file content I/O (disk reads, remote reads, text extraction).
+
+Extracted from the former ``read_service`` module.  This module owns all
+filesystem and remote storage I/O.  Access gating lives in ``access_service``.
+"""
+
+import logging
+import os
+import sqlite3
+from pathlib import Path
+from typing import Literal, Optional
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def read_file(
+    conn: sqlite3.Connection,
+    metadata: dict,
+    *,
+    format: Literal["text", "raw"] = "text",
+) -> dict:
+    """Read file content from disk or Drive.
+
+    Requires ``metadata`` from a prior ``gate_access()`` call (status ``ok``).
+    Returns dict with ``status`` (``ok`` or error), ``content``, ``metadata``.
+    """
+    from footprinter.mcp.extraction import extract_text, get_extractor_for_file
+    from footprinter.source_registry import SourceRegistry
+
+    meta = dict(metadata)
+    source = meta.get("source", "")
+    name = meta.get("name", "")
+    mime_type = meta.get("mime_type", "")
+
+    # Get raw bytes
+    registry = SourceRegistry(conn)
+    data: Optional[bytes] = None
+
+    if source == "local":
+        data = _read_local_file_bytes(meta.get("path", ""))
+    elif registry.is_remote_source(source):
+        external_id = meta.get("external_id")
+        account = meta.get("account")
+        if external_id and account:
+            data = _read_remote_file_bytes(source, external_id, account, mime_type)
+        else:
+            return {
+                "status": "read_failed",
+                "metadata": meta,
+                "message": f"file:{meta.get('id')} missing external_id or account",
+            }
+    else:
+        return {
+            "status": "read_failed",
+            "metadata": meta,
+            "message": f"file:{meta.get('id')} unknown source={source}",
+        }
+
+    if data is None:
+        return {
+            "status": "read_failed",
+            "metadata": meta,
+            "message": f"file:{meta.get('id')} null data from {source}",
+        }
+
+    # Determine if extraction is needed
+    extractor_type = get_extractor_for_file(name, mime_type)
+
+    if format == "raw" or extractor_type is None:
+        content = _decode_bytes(data)
+        if content is None:
+            return {
+                "status": "decode_failed",
+                "metadata": meta,
+                "message": f"file:{meta.get('id')} decode failed (raw mode)",
+            }
+        meta["extraction_method"] = "raw"
+        meta["extraction_success"] = True
+        meta["extraction_error"] = None
+        return {"status": "ok", "content": content, "metadata": meta}
+
+    # Text mode with extraction
+    extracted_text, error = extract_text(data, extractor_type)
+
+    if extracted_text is not None:
+        meta["extraction_method"] = extractor_type
+        meta["extraction_success"] = True
+        meta["extraction_error"] = None
+        return {"status": "ok", "content": extracted_text, "metadata": meta}
+
+    # Extraction failed — fall back to raw decode
+    logger.warning(f"Extraction failed for {name}: {error}, falling back to raw")
+    content = _decode_bytes(data)
+    if content is None:
+        meta["extraction_method"] = extractor_type
+        meta["extraction_success"] = False
+        meta["extraction_error"] = error
+        return {
+            "status": "extraction_failed",
+            "metadata": meta,
+            "message": f"file:{meta.get('id')} extraction+decode failed: {error}",
+        }
+
+    meta["extraction_method"] = "raw"
+    meta["extraction_success"] = False
+    meta["extraction_error"] = error
+    return {"status": "ok", "content": content, "metadata": meta}
+
+
+# ---------------------------------------------------------------------------
+# File I/O helpers
+# ---------------------------------------------------------------------------
+
+
+def _validate_local_path(path: str) -> Path:
+    """Validate that a local path falls within the home directory.
+
+    Defense-in-depth: prevents a corrupted database from being used
+    to read arbitrary files via the MCP server.
+    """
+    p = Path(path).resolve()
+    home = Path.home().resolve()
+    if not str(p).startswith(str(home) + os.sep) and p != home:
+        raise PermissionError(f"Path outside home directory: {p}")
+    return p
+
+
+def _read_local_file_bytes(path: str, max_bytes: int = 500_000) -> Optional[bytes]:
+    """Read a local file as raw bytes."""
+    try:
+        p = _validate_local_path(path)
+        if not p.exists():
+            return None
+        with open(p, "rb") as f:
+            data = f.read(max_bytes)
+        return data
+    except PermissionError as e:
+        logger.error(f"Path containment violation for {path}: {e}")
+        return None
+    except Exception as e:
+        logger.error(f"Error reading local file bytes {path}: {e}")
+        return None
+
+
+def _read_remote_file_bytes(
+    source: str,
+    external_id: str,
+    account: str,
+    mime_type: str = "",
+) -> Optional[bytes]:
+    """Download raw bytes from a remote source via connector hooks."""
+    from footprinter.connectors import discover_connectors, is_installed, resolve_hook
+
+    for name, spec in discover_connectors().items():
+        if not is_installed(spec) or not spec.read_file:
+            continue
+        try:
+            fn = resolve_hook(spec.read_file)
+            if fn:
+                return fn(external_id, account, mime_type)
+        except Exception:
+            logger.warning("read_file hook failed for connector %s", name, exc_info=True)
+
+    logger.error("No connector provides read_file for source=%s", source)
+    return None
+
+
+def _decode_bytes(data: bytes) -> Optional[str]:
+    """Decode bytes to string, trying UTF-8 then Latin-1."""
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError:
+        try:
+            return data.decode("latin-1")
+        except UnicodeDecodeError:
+            return None

footprinter/services/email_service.py

@@ -0,0 +1,89 @@
+"""Email read service — get/list with role-based visibility filtering."""
+
+import sqlite3
+from typing import Optional
+
+from footprinter.db import emails 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, email_id: int, *, role: Role = Role.ADMIN) -> dict | None:
+    """Fetch a single email by ID, filtered by role."""
+    result = db.get_email(conn, email_id)
+    if result is None:
+        return None
+    if role.sees_all:
+        return result
+    return filter_result("email", result)
+
+
+def assign(
+    conn: sqlite3.Connection,
+    email_id: int,
+    *,
+    role: Role = Role.ADMIN,
+    project_id: int | None = None,
+    client_id: int | None = None,
+) -> dict | None:
+    """Assign an email 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_email_relationships(
+        conn,
+        email_id,
+        project_id=project_id,
+        client_id=client_id,
+    )
+    if result is None:
+        return None
+    resp: dict = {"id": email_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,
+    client_id: Optional[int] = None,
+    project_id: Optional[int] = None,
+    query: Optional[str] = None,
+    has_attachments: Optional[bool] = None,
+    sort_by: str = "received_at",
+    order: str = "desc",
+    limit: int = 50,
+    page: int = 1,
+) -> dict:
+    """List emails with pagination, filtered by role."""
+    response = db.list_emails(
+        conn,
+        account=account,
+        client_id=client_id,
+        project_id=project_id,
+        query=query,
+        has_attachments=has_attachments,
+        sort_by=sort_by,
+        order=order,
+        limit=limit,
+        page=page,
+    )
+    if role.sees_all:
+        return response
+    filtered, suppressed = filter_results_list("email", response["emails"])
+    filtered = strip_content_for_denied("email", filtered)
+    response["emails"] = filtered
+    response["suppressed"] = suppressed
+    return response

footprinter/services/file_service.py

@@ -0,0 +1,83 @@
+"""File read service — get/list with role-based visibility filtering."""
+
+import sqlite3
+from typing import Optional
+
+from footprinter.db import files 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, file_id: int, *, role: Role = Role.ADMIN) -> dict | None:
+    """Fetch a single file by ID, filtered by role."""
+    result = db.get_file(conn, file_id)
+    if result is None:
+        return None
+    if role.sees_all:
+        return result
+    return filter_result("file", result)
+
+
+def assign(
+    conn: sqlite3.Connection,
+    file_id: int,
+    *,
+    role: Role = Role.ADMIN,
+    project_id: int | None = None,
+    client_id: int | None = None,
+) -> dict | None:
+    """Assign a file 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_file_relationships(
+        conn,
+        file_id,
+        project_id=project_id,
+        client_id=client_id,
+    )
+    if result is None:
+        return None
+    resp: dict = {"id": file_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,
+    project_id: Optional[int] = None,
+    source: Optional[list[str]] = None,
+    status: Optional[str | list[str]] = None,
+    content_type: Optional[str] = None,
+    limit: int = 50,
+    page: int = 1,
+) -> dict:
+    """List files with pagination, filtered by role."""
+    response = db.list_files(
+        conn,
+        project_id=project_id,
+        source=source,
+        status=status,
+        content_type=content_type,
+        limit=limit,
+        page=page,
+    )
+    if role.sees_all:
+        return response
+    filtered, suppressed = filter_results_list("file", response["files"])
+    filtered = strip_content_for_denied("file", filtered)
+    response["files"] = filtered
+    response["suppressed"] = suppressed
+    return response

footprinter/services/folder_service.py

@@ -0,0 +1,122 @@
+"""Folder read service — get/list with role-based visibility filtering."""
+
+import sqlite3
+from typing import Optional
+
+from footprinter.db import folders as db
+from footprinter.services.access_service import (
+    _read_visibility,
+    filter_result,
+    filter_results_list,
+)
+from footprinter.services.roles import Role
+
+
+def get(conn: sqlite3.Connection, folder_id: int, *, role: Role = Role.ADMIN) -> dict | None:
+    """Fetch a single folder by ID, filtered by role."""
+    result = db.get_folder(conn, folder_id)
+    if result is None:
+        return None
+    if role.sees_all:
+        return result
+    return filter_result("folder", result)
+
+
+def assign(
+    conn: sqlite3.Connection,
+    folder_id: int,
+    *,
+    role: Role = Role.ADMIN,
+    project_id: int | None = None,
+    client_id: int | None = None,
+) -> dict | None:
+    """Assign a folder to a project and/or client.
+
+    Returns result dict on success, None if not found.
+    Raises PermissionError if role cannot write, ValueError if project doesn't exist.
+    """
+    if not role.can_write:
+        raise PermissionError("Role does not permit write operations")
+    result = db.update_folder_relationships(
+        conn,
+        folder_id,
+        project_id=project_id,
+        client_id=client_id,
+    )
+    if result is None:
+        return None
+    resp: dict = {"id": folder_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,
+    project_id: Optional[int] = None,
+    depth: Optional[int] = 1,
+    include_hidden: bool = False,
+    sort_by: str = "size",
+    limit: int = 50,
+    page: int = 1,
+) -> dict:
+    """List folders with pagination, filtered by role."""
+    response = db.list_folders(
+        conn,
+        project_id=project_id,
+        depth=depth,
+        include_hidden=include_hidden,
+        sort_by=sort_by,
+        limit=limit,
+        page=page,
+    )
+    if role.sees_all:
+        return response
+    filtered, suppressed = filter_results_list("folder", response["folders"])
+    response["folders"] = filtered
+    response["suppressed"] = suppressed
+    return response
+
+
+def get_by_path(
+    conn: sqlite3.Connection,
+    path: str,
+    *,
+    role: Role = Role.ADMIN,
+) -> dict | None:
+    """Look up a folder by exact path with navigation data, filtered by role.
+
+    Returns None if folder doesn't exist or is hidden (for VIEWER).
+    Returns opaque dict (no children) for opaque folders (for VIEWER).
+    Returns full navigation dict for visible folders.
+    """
+    row = db.get_folder_by_path(conn, path)
+    if row is None:
+        return None
+
+    visibility = _read_visibility(row)
+
+    if not role.sees_all:
+        if visibility == "hidden":
+            return None
+        if visibility == "opaque":
+            return filter_result("folder", row)
+
+    # Fetch navigation data (files, subfolders, recursive count)
+    nav = db.get_folder_navigation(conn, row["id"], path)
+    result = {**row, **nav}
+
+    if role.sees_all:
+        return result
+
+    # Filter children by visibility
+    result["files"], file_sup = filter_results_list("file", result["files"])
+    result["subfolders"], sub_sup = filter_results_list("folder", result["subfolders"])
+    total_sup = file_sup + sub_sup
+    if total_sup:
+        result["suppressed"] = total_sup
+    return result

footprinter/services/includes.py

@@ -0,0 +1,19 @@
+"""Include parameter validation for the service layer."""
+
+
+def validate_include(
+    include: list[str] | None,
+    valid: frozenset[str],
+) -> frozenset[str]:
+    """Validate and normalize an include parameter.
+
+    Returns a frozenset of validated include names.
+    Raises ValueError for invalid values.
+    """
+    if include is None:
+        return frozenset()
+    result = frozenset(include)
+    invalid = result - valid
+    if invalid:
+        raise ValueError(f"Invalid include values: {', '.join(sorted(invalid))}. Valid: {', '.join(sorted(valid))}")
+    return result