ltcai 3.4.1 → 3.6.0

package/latticeai/core/oidc.py

@@ -0,0 +1,205 @@
+"""Self-contained OIDC ID-token validation.
+
+A JWT is ``base64url(header).base64url(claims).base64url(signature)``. The login
+flow must *never* trust a decoded payload on its own — without verifying the
+signature an attacker can forge any ``email``/``sub`` claim. This module verifies
+the RSA signature against the provider's published JWKS and then validates the
+standard registered claims plus the login ``nonce``.
+
+Design goals:
+
+* No third-party JWT dependency — only the standard library plus ``cryptography``
+  (already a transitive dependency, and pinned explicitly in ``pyproject.toml``).
+* **Fail-closed**: any anomaly raises :class:`OIDCValidationError`; the caller
+  must reject the login. There is no "best effort accept".
+* Asymmetric algorithms only (``RS256``/``RS384``/``RS512``). ``alg: none`` and
+  symmetric ``HS*`` tokens are rejected outright — the classic OIDC bypasses.
+* Pure and injectable: :func:`verify_id_token` takes the JWKS and clock as
+  arguments so every rejection path is unit-testable offline.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import time
+from typing import Any, Dict, List, Optional
+
+
+class OIDCValidationError(Exception):
+    """Raised when an OIDC ID token fails any validation step (fail-closed)."""
+
+
+# Asymmetric RSA algorithms only. Excluding HS*/none is deliberate: an attacker
+# who can set ``alg`` must not be able to downgrade to a symmetric or unsigned
+# token. Maps JWT alg name → cryptography hash name.
+_ALLOWED_ALGS: Dict[str, str] = {"RS256": "sha256", "RS384": "sha384", "RS512": "sha512"}
+
+
+def _b64url_decode(segment: str) -> bytes:
+    if not isinstance(segment, str) or not segment:
+        raise OIDCValidationError("empty JWT segment")
+    padding = "=" * (-len(segment) % 4)
+    try:
+        return base64.urlsafe_b64decode(segment + padding)
+    except Exception as exc:  # malformed base64
+        raise OIDCValidationError(f"invalid base64url segment: {exc}")
+
+
+def _b64url_uint(value: str) -> int:
+    return int.from_bytes(_b64url_decode(value), "big")
+
+
+def _split(token: str) -> List[str]:
+    parts = str(token or "").split(".")
+    if len(parts) != 3 or not all(parts):
+        raise OIDCValidationError("malformed JWT: expected three non-empty segments")
+    return parts
+
+
+def decode_unverified_header(token: str) -> Dict[str, Any]:
+    """Decode the JWT header WITHOUT verifying it (used only to pick the key)."""
+    header_b64 = _split(token)[0]
+    try:
+        header = json.loads(_b64url_decode(header_b64))
+    except Exception as exc:
+        raise OIDCValidationError(f"invalid JWT header: {exc}")
+    if not isinstance(header, dict):
+        raise OIDCValidationError("JWT header is not an object")
+    return header
+
+
+def _public_key_from_jwk(jwk: Dict[str, Any]):
+    if not isinstance(jwk, dict) or jwk.get("kty") != "RSA":
+        raise OIDCValidationError("unsupported JWK key type (RSA required)")
+    if not jwk.get("n") or not jwk.get("e"):
+        raise OIDCValidationError("JWK missing modulus/exponent")
+    from cryptography.hazmat.primitives.asymmetric.rsa import RSAPublicNumbers
+
+    numbers = RSAPublicNumbers(_b64url_uint(jwk["e"]), _b64url_uint(jwk["n"]))
+    return numbers.public_key()
+
+
+def _candidate_keys(jwks: Any, kid: Optional[str]) -> List[Dict[str, Any]]:
+    keys = jwks.get("keys") if isinstance(jwks, dict) else jwks
+    if not isinstance(keys, list) or not keys:
+        raise OIDCValidationError("JWKS contains no keys")
+    rsa_keys = [k for k in keys if isinstance(k, dict) and k.get("kty") == "RSA"]
+    if kid:
+        matched = [k for k in rsa_keys if k.get("kid") == kid]
+        if not matched:
+            raise OIDCValidationError("no JWKS key matches the token 'kid'")
+        return matched
+    return rsa_keys
+
+
+def _verify_signature(token: str, jwks: Any) -> Dict[str, Any]:
+    header_b64, payload_b64, sig_b64 = _split(token)
+    header = decode_unverified_header(token)
+    alg = header.get("alg")
+    if alg not in _ALLOWED_ALGS:
+        # Rejects 'none' and symmetric HS* — the canonical signature-bypass attacks.
+        raise OIDCValidationError(f"unsupported or unsafe JWT alg: {alg!r}")
+
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives import hashes
+    from cryptography.hazmat.primitives.asymmetric import padding
+
+    hash_obj = {"sha256": hashes.SHA256(), "sha384": hashes.SHA384(), "sha512": hashes.SHA512()}[
+        _ALLOWED_ALGS[alg]
+    ]
+    signature = _b64url_decode(sig_b64)
+    signing_input = f"{header_b64}.{payload_b64}".encode("ascii")
+
+    for jwk in _candidate_keys(jwks, header.get("kid")):
+        try:
+            public_key = _public_key_from_jwk(jwk)
+            public_key.verify(signature, signing_input, padding.PKCS1v15(), hash_obj)
+        except (InvalidSignature, OIDCValidationError):
+            continue
+        # Signature verified — now it is safe to parse the claims.
+        try:
+            claims = json.loads(_b64url_decode(payload_b64))
+        except Exception as exc:
+            raise OIDCValidationError(f"invalid JWT claims JSON: {exc}")
+        if not isinstance(claims, dict):
+            raise OIDCValidationError("JWT claims are not an object")
+        return claims
+
+    raise OIDCValidationError("signature verification failed against all JWKS keys")
+
+
+def verify_id_token(
+    id_token: str,
+    *,
+    jwks: Any,
+    issuer: str,
+    audience: str,
+    nonce: Optional[str] = None,
+    now: Optional[float] = None,
+    leeway: int = 60,
+) -> Dict[str, Any]:
+    """Verify an OIDC ID token and return its claims, or raise ``OIDCValidationError``.
+
+    Validates, in order: signature (against ``jwks``, RSA only), ``iss``, ``aud``
+    (and ``azp`` when multi-audience), ``exp``, ``iat``/``nbf``, and ``nonce``.
+    All checks are fail-closed.
+    """
+    if not id_token:
+        raise OIDCValidationError("missing id_token")
+    if not issuer:
+        raise OIDCValidationError("issuer not configured")
+    if not audience:
+        raise OIDCValidationError("audience (client_id) not configured")
+
+    claims = _verify_signature(id_token, jwks)
+    current = int(now if now is not None else time.time())
+
+    if claims.get("iss") != issuer:
+        raise OIDCValidationError("issuer mismatch")
+
+    aud = claims.get("aud")
+    audiences = aud if isinstance(aud, list) else [aud]
+    if audience not in audiences:
+        raise OIDCValidationError("audience mismatch")
+    if isinstance(aud, list) and len(aud) > 1 and claims.get("azp") not in (None, audience):
+        raise OIDCValidationError("azp (authorized party) mismatch")
+
+    exp = claims.get("exp")
+    if exp is None:
+        raise OIDCValidationError("token missing 'exp'")
+    if current > int(exp) + leeway:
+        raise OIDCValidationError("token expired")
+
+    iat = claims.get("iat")
+    if iat is not None and int(iat) - leeway > current:
+        raise OIDCValidationError("token 'iat' is in the future")
+
+    nbf = claims.get("nbf")
+    if nbf is not None and int(nbf) - leeway > current:
+        raise OIDCValidationError("token not yet valid ('nbf')")
+
+    if nonce is not None and claims.get("nonce") != nonce:
+        raise OIDCValidationError("nonce mismatch")
+
+    return claims
+
+
+async def fetch_jwks(jwks_uri: str, *, timeout: float = 15.0) -> Dict[str, Any]:
+    """Fetch a provider JWKS document. Network-only; injectable in tests."""
+    if not jwks_uri:
+        raise OIDCValidationError("discovery document has no 'jwks_uri'")
+    import httpx
+
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(jwks_uri, timeout=timeout)
+        resp.raise_for_status()
+        return resp.json()
+
+
+__all__ = [
+    "OIDCValidationError",
+    "verify_id_token",
+    "fetch_jwks",
+    "decode_unverified_header",
+]

package/latticeai/core/security.py

@@ -35,12 +35,66 @@ def host_is_loopback(host: str) -> bool:
         return False
 
 
+# ── Trusted-proxy handling ────────────────────────────────────────────────────
+# ``client_ip`` is the key used for IP rate limiting (login / register) and for
+# audit logging. A forwarded header (``X-Forwarded-For`` / ``CF-Connecting-IP``)
+# is *client-controllable*, so honoring it unconditionally lets anyone spoof
+# their source IP and bypass per-IP rate limits. We therefore trust those headers
+# ONLY when the direct peer is a configured trusted proxy (e.g. the Cloudflare /
+# Vercel edge in front of the app). Default: no trusted proxies → use the peer
+# address, which is the safe, local-first behaviour.
+_FORWARDED_HEADERS = ("CF-Connecting-IP", "X-Forwarded-For")
+_trusted_proxies: List["ipaddress._BaseNetwork"] = []
+
+
+def configure_trusted_proxies(values) -> int:
+    """Set the trusted-proxy allowlist from IPs / CIDRs. Returns the count parsed.
+
+    Accepts a comma-separated string or an iterable of IPs/CIDRs. Invalid entries
+    are skipped. Passing an empty value disables forwarded-header trust entirely.
+    """
+    global _trusted_proxies
+    if isinstance(values, str):
+        items = [v.strip() for v in values.split(",")]
+    else:
+        items = [str(v).strip() for v in (values or [])]
+    networks: List["ipaddress._BaseNetwork"] = []
+    for item in items:
+        if not item:
+            continue
+        try:
+            networks.append(ipaddress.ip_network(item, strict=False))
+        except ValueError:
+            continue
+    _trusted_proxies = networks
+    return len(networks)
+
+
+def _peer_is_trusted_proxy(peer: str) -> bool:
+    if not peer or not _trusted_proxies:
+        return False
+    try:
+        addr = ipaddress.ip_address(peer)
+    except ValueError:
+        return False
+    return any(addr in net for net in _trusted_proxies)
+
+
 def client_ip(request) -> str:
-    for header in ("CF-Connecting-IP", "X-Forwarded-For"):
-        val = request.headers.get(header)
-        if val:
-            return val.split(",")[0].strip()
-    return request.client.host if request.client else "unknown"
+    peer = request.client.host if request.client else ""
+    # Only a trusted proxy's forwarded headers are honoured; otherwise the
+    # client-supplied header is ignored so per-IP rate limits cannot be spoofed.
+    if _peer_is_trusted_proxy(peer):
+        for header in _FORWARDED_HEADERS:
+            val = request.headers.get(header)
+            if val:
+                candidate = val.split(",")[0].strip()
+                try:
+                    ipaddress.ip_address(candidate)
+                    return candidate
+                except ValueError:
+                    continue
+    return peer or "unknown"
 
 
 _FILE_MAGIC: Dict[str, List[bytes]] = {

package/latticeai/core/workspace_os.py

@@ -18,7 +18,7 @@ from pathlib import Path
 from typing import Any, Callable, Dict, Iterable, List, Optional
 
 
-WORKSPACE_OS_VERSION = "3.4.1"
+WORKSPACE_OS_VERSION = "3.6.0"
 
 # Workspace types separate single-user Personal workspaces from shared
 # Organization workspaces. Both keep the same local-first JSON store; the type

package/latticeai/server_app.py

@@ -40,6 +40,7 @@ from latticeai.core.security import (
     verify_password,
     host_is_loopback as _host_is_loopback_impl,
     client_ip as _client_ip_impl,
+    configure_trusted_proxies as _configure_trusted_proxies,
     bytes_match_extension as _bytes_match_extension_impl,
     redact_secret_text as _redact_secret_text,
     check_ip_rate_limit as _check_ip_rate_limit,
@@ -119,7 +120,11 @@ from latticeai.core.builtin_hooks import register_builtin_hook_runners
 from latticeai.api.agent_registry import create_agent_registry_router
 from latticeai.core.agent_registry import AgentRegistry
 from latticeai.api.memory import create_memory_router
+from latticeai.api.browser import create_browser_router
+from latticeai.api.portability import create_portability_router
 from latticeai.services.memory_service import MemoryService
+from latticeai.services.ingestion import IngestionPipeline
+from latticeai.services.kg_portability import KGPortabilityService
 from latticeai.services.tool_dispatch import (
     LOCAL_WRITE_BLOCKED_PREFIXES as _LOCAL_WRITE_BLOCKED_PREFIXES,
     TOOL_GOVERNANCE,
@@ -157,6 +162,12 @@ from datetime import datetime
 CONFIG = Config.from_env()
 APP_VERSION = WORKSPACE_OS_VERSION
 
+# Forwarded headers (X-Forwarded-For / CF-Connecting-IP) are only honoured for
+# IP rate limiting when the direct peer is one of these trusted proxies. Empty by
+# default (local-first): the peer address is used and client-supplied headers are
+# ignored, so per-IP rate limits cannot be spoofed.
+_configure_trusted_proxies(CONFIG.trusted_proxies)
+
 APP_MODE = CONFIG.app_mode
 IS_PUBLIC_MODE = CONFIG.is_public
 DEFAULT_HOST = CONFIG.host
@@ -315,6 +326,23 @@ MEMORY_SERVICE = MemoryService(
     enable_graph=ENABLE_GRAPH,
     history_file=HISTORY_FILE,
 )
+# ── v3.6.0 unified ingestion pipeline: the single write-side seam into the
+# Knowledge Graph. Every new source (web URL, browser tab, …) flows through this
+# so pre_tool/post_tool hooks fire on ingestion and provenance is captured
+# uniformly. Existing direct ingest callers keep working; new paths converge here.
+INGESTION_PIPELINE = IngestionPipeline(
+    KNOWLEDGE_GRAPH,
+    hooks=HOOKS_REGISTRY,
+    enable_graph=ENABLE_GRAPH,
+    audit=lambda action, detail, user: append_audit_event(action, user_email=user, **detail),
+)
+# ── v3.6.0 Knowledge Graph portability: local export / import / backup / restore.
+# The graph is the user's durable asset, so it must be portable with no cloud.
+KG_PORTABILITY = KGPortabilityService(
+    knowledge_graph=KNOWLEDGE_GRAPH,
+    data_dir=DATA_DIR,
+    enable_graph=ENABLE_GRAPH,
+)
 
 def _require_graph():
     if not ENABLE_GRAPH or KNOWLEDGE_GRAPH is None:
@@ -1501,6 +1529,17 @@ app.include_router(create_memory_router(
     append_audit_event=append_audit_event,
 ))
 
+app.include_router(create_browser_router(
+    pipeline=INGESTION_PIPELINE,
+    require_user=require_user,
+))
+
+app.include_router(create_portability_router(
+    service=KG_PORTABILITY,
+    require_user=require_user,
+    require_admin=require_admin,
+))
+
 app.include_router(create_garden_router(gardener=gardener, require_user=require_user))
 app.include_router(create_setup_router(model_router=router, require_user=require_user))
 

package/latticeai/services/ingestion.py

@@ -0,0 +1,271 @@
+"""Unified ingestion pipeline — the single write-side seam into the Knowledge Graph.
+
+v3.6.0 Knowledge Graph First principle: *no data source bypasses the Knowledge
+Graph and no source creates an isolated silo*. Every source — local files,
+connected folders, PDFs/Markdown/text/code, web URLs, browser tabs — is
+normalized into one :class:`IngestionItem` and pushed through one
+:meth:`IngestionPipeline.ingest` entrypoint:
+
+    Source → normalize → content hash → (file | text) ingest → provenance
+
+The pipeline is deliberately thin. It owns normalization, idempotency reporting,
+provenance capture, and — crucially — routing every ingest through the shared
+``dispatch_tool`` lifecycle so ``pre_tool``/``post_tool`` hooks fire on data
+ingestion exactly as they do on tool calls. The heavy graph construction lives in
+:class:`knowledge_graph.KnowledgeGraphStore` (``ingest_document`` for files,
+``ingest_source`` for text/web), which this module composes rather than
+re-implements.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from latticeai.core.hooks import dispatch_tool
+
+# Source types that arrive as a file on disk (read via ingest_document).
+FILE_SOURCE_TYPES = frozenset({"file", "local_file", "upload", "pdf"})
+# Source types that arrive as extracted text (read via ingest_source).
+TEXT_SOURCE_TYPES = frozenset(
+    {"web_url", "browser_tab", "text", "markdown", "note", "code", "clipboard"}
+)
+
+DEFAULT_MAX_TEXT_BYTES = 5 * 1024 * 1024  # 5 MB of extracted text per item
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+@dataclass
+class IngestionItem:
+    """A single thing to ingest, normalized across every source type."""
+
+    source_type: str
+    title: Optional[str] = None
+    text: Optional[str] = None          # text/web sources
+    path: Optional[str] = None          # file sources
+    source_uri: Optional[str] = None
+    mime_type: Optional[str] = None
+    owner: Optional[str] = None
+    workspace_id: Optional[str] = None
+    permissions: Optional[Dict[str, Any]] = None
+    captured_at: Optional[str] = None
+    modified_at: Optional[str] = None
+    conversation_id: Optional[str] = None
+    agent_used: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class IngestionResult:
+    """The outcome of one ingestion, including provenance and idempotency."""
+
+    status: str                         # ok | unavailable | blocked | failed
+    source_type: str
+    node_id: Optional[str] = None
+    source_node_id: Optional[str] = None
+    content_hash: Optional[str] = None
+    title: Optional[str] = None
+    chunk_ids: List[str] = field(default_factory=list)
+    chunk_count: int = 0
+    duplicate: bool = False
+    embedded: bool = False
+    indexing_status: str = "pending"    # indexed | skipped | failed | pending
+    provenance_id: Optional[str] = None
+    detail: Optional[str] = None
+
+    def as_dict(self) -> Dict[str, Any]:
+        return {
+            "status": self.status,
+            "source_type": self.source_type,
+            "node_id": self.node_id,
+            "source_node_id": self.source_node_id,
+            "content_hash": self.content_hash,
+            "title": self.title,
+            "chunk_ids": self.chunk_ids,
+            "chunk_count": self.chunk_count,
+            "duplicate": self.duplicate,
+            "embedded": self.embedded,
+            "indexing_status": self.indexing_status,
+            "provenance_id": self.provenance_id,
+            "detail": self.detail,
+        }
+
+
+class IngestionPipeline:
+    """Single normalized entrypoint that feeds every source into the graph."""
+
+    def __init__(
+        self,
+        knowledge_graph: Any,
+        *,
+        hooks: Any = None,
+        enable_graph: bool = True,
+        audit: Optional[Any] = None,
+        max_text_bytes: int = DEFAULT_MAX_TEXT_BYTES,
+        pipeline_name: str = "unified-ingestion",
+    ) -> None:
+        self._kg = knowledge_graph
+        self._hooks = hooks
+        self._enable = bool(enable_graph)
+        self._audit = audit
+        self._max_text_bytes = int(max_text_bytes)
+        self._pipeline_name = pipeline_name
+
+    def available(self) -> bool:
+        return self._enable and self._kg is not None
+
+    # ── public API ───────────────────────────────────────────────────────────
+    def ingest(self, item: IngestionItem, *, user_email: Optional[str] = None) -> IngestionResult:
+        """Normalize, hash, route through dispatch_tool, and record provenance."""
+        source_type = str(item.source_type or "text").strip()
+        if not self.available():
+            return IngestionResult(
+                status="unavailable", source_type=source_type,
+                indexing_status="skipped",
+                detail="Knowledge Graph is disabled (LATTICEAI_ENABLE_GRAPH).",
+            )
+
+        captured_at = item.captured_at or _now_iso()
+        owner = item.owner or user_email
+        tool_name = f"kg_ingest.{source_type}"
+        # Only the keys are read by the hook payload, so this dict is safe/cheap.
+        args = {
+            "source_type": source_type,
+            "source_uri": item.source_uri,
+            "owner": owner,
+            "workspace_id": item.workspace_id,
+        }
+
+        def _run() -> Dict[str, Any]:
+            if source_type in FILE_SOURCE_TYPES or (item.path and not item.text):
+                return self._ingest_file(item, source_type=source_type, owner=owner, captured_at=captured_at)
+            return self._ingest_text(item, source_type=source_type, owner=owner, captured_at=captured_at)
+
+        try:
+            raw = dispatch_tool(
+                self._hooks, tool_name, args, _run,
+                user_email=user_email, workspace_id=item.workspace_id, source="ingestion",
+            )
+        except PermissionError as exc:
+            return IngestionResult(
+                status="blocked", source_type=source_type,
+                indexing_status="skipped", detail=str(exc),
+            )
+        except FileNotFoundError as exc:
+            return IngestionResult(
+                status="failed", source_type=source_type,
+                indexing_status="failed", detail=str(exc),
+            )
+        except Exception as exc:  # noqa: BLE001 — surface as a failed result, never crash the caller
+            return IngestionResult(
+                status="failed", source_type=source_type,
+                indexing_status="failed", detail=str(exc),
+            )
+
+        node_id = raw.get("node_id")
+        content_hash = raw.get("content_hash") or raw.get("sha256")
+        chunk_ids = list(raw.get("chunk_ids") or [])
+        embedded = bool(self._kg.node_is_embedded(node_id)) if node_id else False
+        title = raw.get("title") or item.title
+
+        prov = self._kg.record_provenance(
+            node_id=node_id,
+            source_type=source_type,
+            pipeline=self._pipeline_name,
+            source_uri=item.source_uri,
+            content_hash=content_hash,
+            title=title,
+            owner=owner,
+            workspace_id=item.workspace_id,
+            captured_at=captured_at,
+            modified_at=item.modified_at,
+            embedded=embedded,
+            linked=bool(raw.get("source_node_id")),
+            duplicate=bool(raw.get("duplicate")),
+            agent_used=item.agent_used,
+            chunk_count=len(chunk_ids),
+            permissions=item.permissions,
+            metadata=item.metadata,
+        )
+        if self._audit is not None:
+            try:
+                self._audit(
+                    "kg_ingest",
+                    {
+                        "source_type": source_type, "node_id": node_id,
+                        "content_hash": content_hash, "duplicate": bool(raw.get("duplicate")),
+                    },
+                    user_email,
+                )
+            except Exception:  # noqa: BLE001 — audit must never break ingestion
+                pass
+
+        return IngestionResult(
+            status="ok",
+            source_type=source_type,
+            node_id=node_id,
+            source_node_id=raw.get("source_node_id"),
+            content_hash=content_hash,
+            title=title,
+            chunk_ids=chunk_ids,
+            chunk_count=len(chunk_ids),
+            duplicate=bool(raw.get("duplicate")),
+            embedded=embedded,
+            indexing_status="indexed",
+            provenance_id=prov.get("id"),
+        )
+
+    # ── routing helpers ──────────────────────────────────────────────────────
+    def _ingest_text(self, item, *, source_type, owner, captured_at) -> Dict[str, Any]:
+        text = item.text or ""
+        if len(text.encode("utf-8", "ignore")) > self._max_text_bytes:
+            raise ValueError(
+                f"Text payload exceeds the {self._max_text_bytes // (1024 * 1024)}MB ingestion limit."
+            )
+        title = item.title or item.source_uri or source_type
+        return self._kg.ingest_source(
+            source_type=source_type,
+            title=title,
+            text=text,
+            source_uri=item.source_uri,
+            owner=owner,
+            workspace_id=item.workspace_id,
+            permissions=item.permissions,
+            captured_at=captured_at,
+            modified_at=item.modified_at,
+            conversation_id=item.conversation_id,
+            metadata={"mime_type": item.mime_type, **(item.metadata or {})},
+        )
+
+    def _ingest_file(self, item, *, source_type, owner, captured_at) -> Dict[str, Any]:
+        if not item.path:
+            raise ValueError("File ingestion requires a path.")
+        path = Path(item.path)
+        if not path.exists():
+            raise FileNotFoundError(f"File not found: {path}")
+        return self._kg.ingest_document(
+            path,
+            original_filename=item.title or path.name,
+            mime_type=item.mime_type,
+            uploader=owner,
+            conversation_id=item.conversation_id,
+            extracted=item.metadata.get("extracted") if item.metadata else None,
+            source_type=source_type,
+            source_uri=item.source_uri or str(path),
+            captured_at=captured_at,
+            modified_at=item.modified_at,
+            owner=owner,
+            workspace_id=item.workspace_id,
+            permissions=item.permissions,
+        )
+
+
+def content_hash_text(text: str) -> str:
+    """Canonical content hash for a text payload (matches store hashing scheme)."""
+    return hashlib.sha256((text or "").encode("utf-8", "ignore")).hexdigest()