chuk-artifacts 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

chuk_artifacts/session_operations.py

@@ -0,0 +1,445 @@
+# -*- coding: utf-8 -*-
+# chuk_artifacts/session_operations.py (SECURE VERSION)
+"""
+Session-based file operations with strict session isolation.
+NO cross-session operations allowed for security.
+"""
+
+from __future__ import annotations
+
+import uuid, hashlib, json, logging
+from datetime import datetime
+from typing import Any, Dict, Optional, Union, List
+
+from .base import BaseOperations
+from .exceptions import (
+    ArtifactStoreError, ArtifactNotFoundError, ArtifactExpiredError, 
+    ProviderError, SessionError
+)
+
+logger = logging.getLogger(__name__)
+
+_ANON_PREFIX = "anon"
+_DEFAULT_TTL = 900
+
+
+class SessionOperations(BaseOperations):
+    """Session-based file operations with strict session isolation."""
+
+    async def move_file(
+        self,
+        artifact_id: str,
+        *,
+        new_filename: str = None,
+        new_session_id: str = None,
+        new_meta: Dict[str, Any] = None
+    ) -> Dict[str, Any]:
+        """
+        Move a file within the SAME session or rename it.
+        
+        Parameters
+        ----------
+        artifact_id : str
+            Source artifact ID
+        new_filename : str, optional
+            New filename (renames the file)
+        new_session_id : str, optional
+            Target session (BLOCKED - always raises error if different)
+        new_meta : dict, optional
+            Additional metadata to merge
+            
+        Returns
+        -------
+        dict
+            Updated artifact metadata
+            
+        Raises
+        ------
+        ArtifactStoreError
+            If trying to move across sessions (always blocked)
+        """
+        self._check_closed()
+        
+        try:
+            # Get current metadata
+            record = await self._get_record(artifact_id)
+            current_session = record.get("session_id")
+            
+            # STRICT SECURITY: Block ALL cross-session moves
+            if new_session_id and new_session_id != current_session:
+                raise ArtifactStoreError(
+                    f"Cross-session moves are not permitted for security reasons. "
+                    f"Artifact {artifact_id} belongs to session '{current_session}', "
+                    f"cannot move to session '{new_session_id}'. Use copy operations within "
+                    f"the same session only."
+                )
+            
+            # Update metadata fields (only filename and meta allowed)
+            updates = {}
+            if new_filename:
+                updates["filename"] = new_filename
+            if new_meta:
+                existing_meta = record.get("meta", {})
+                existing_meta.update(new_meta)
+                updates["new_meta"] = existing_meta
+                updates["merge"] = True
+            
+            if updates:
+                # Use the metadata operations to update
+                from .metadata import MetadataOperations
+                metadata_ops = MetadataOperations(self._artifact_store)
+                return await metadata_ops.update_metadata(artifact_id, **updates)
+            
+            return record
+            
+        except (ArtifactNotFoundError, ArtifactExpiredError):
+            raise
+        except Exception as e:
+            logger.error(
+                "File move failed",
+                extra={
+                    "artifact_id": artifact_id,
+                    "new_filename": new_filename,
+                    "new_session_id": new_session_id,
+                    "error": str(e)
+                }
+            )
+            raise ProviderError(f"Move operation failed: {e}") from e
+
+    async def copy_file(
+        self,
+        artifact_id: str,
+        *,
+        new_filename: str = None,
+        target_session_id: str = None,
+        new_meta: Dict[str, Any] = None,
+        summary: str = None
+    ) -> str:
+        """
+        Copy a file WITHIN THE SAME SESSION only.
+        
+        Parameters
+        ----------
+        artifact_id : str
+            Source artifact ID
+        new_filename : str, optional
+            Filename for the copy (defaults to original + "_copy")
+        target_session_id : str, optional
+            Target session (BLOCKED - must be same as source session)
+        new_meta : dict, optional
+            Additional metadata to merge
+        summary : str, optional
+            New summary for the copy
+            
+        Returns
+        -------
+        str
+            New artifact ID of the copy
+            
+        Raises
+        ------
+        ArtifactStoreError
+            If trying to copy across sessions (always blocked)
+        """
+        self._check_closed()
+        
+        try:
+            # Get original metadata first to check session
+            original_meta = await self._get_record(artifact_id)
+            original_session = original_meta.get("session_id")
+            
+            # STRICT SECURITY: Block ALL cross-session copies
+            if target_session_id and target_session_id != original_session:
+                raise ArtifactStoreError(
+                    f"Cross-session copies are not permitted for security reasons. "
+                    f"Artifact {artifact_id} belongs to session '{original_session}', "
+                    f"cannot copy to session '{target_session_id}'. Files can only be "
+                    f"copied within the same session."
+                )
+            
+            # Ensure target session is the same as source
+            copy_session = original_session  # Always use source session
+            
+            # Get original data
+            original_data = await self._retrieve_data(artifact_id)
+            
+            # Prepare copy metadata
+            copy_filename = new_filename or (
+                (original_meta.get("filename", "file") or "file") + "_copy"
+            )
+            copy_summary = summary or f"Copy of {original_meta.get('summary', 'artifact')}"
+            
+            # Merge metadata
+            copy_meta = {**original_meta.get("meta", {})}
+            if new_meta:
+                copy_meta.update(new_meta)
+            
+            # Add copy tracking
+            copy_meta["copied_from"] = artifact_id
+            copy_meta["copy_timestamp"] = datetime.utcnow().isoformat(timespec="seconds") + "Z"
+            copy_meta["copy_within_session"] = original_session
+            
+            # Store the copy using core operations
+            from .core import CoreStorageOperations
+            core_ops = CoreStorageOperations(self._artifact_store)
+            
+            new_artifact_id = await core_ops.store(
+                data=original_data,
+                mime=original_meta["mime"],
+                summary=copy_summary,
+                filename=copy_filename,
+                session_id=copy_session,  # Always same session
+                meta=copy_meta
+            )
+            
+            logger.info(
+                "File copied within session",
+                extra={
+                    "source_artifact_id": artifact_id,
+                    "new_artifact_id": new_artifact_id,
+                    "session": copy_session,
+                    "security_level": "same_session_only"
+                }
+            )
+            
+            return new_artifact_id
+            
+        except (ArtifactNotFoundError, ArtifactExpiredError):
+            raise
+        except Exception as e:
+            logger.error(
+                "File copy failed",
+                extra={
+                    "artifact_id": artifact_id,
+                    "new_filename": new_filename,
+                    "target_session_id": target_session_id,
+                    "error": str(e)
+                }
+            )
+            raise ProviderError(f"Copy operation failed: {e}") from e
+
+    async def read_file(
+        self,
+        artifact_id: str,
+        *,
+        encoding: str = "utf-8",
+        as_text: bool = True
+    ) -> Union[str, bytes]:
+        """
+        Read file content directly.
+        
+        Note: This operation inherently respects session boundaries since
+        you can only read files you have artifact IDs for.
+        """
+        self._check_closed()
+        
+        try:
+            data = await self._retrieve_data(artifact_id)
+            
+            if as_text:
+                try:
+                    return data.decode(encoding)
+                except UnicodeDecodeError as e:
+                    logger.warning(f"Failed to decode with {encoding}: {e}")
+                    raise ProviderError(f"Cannot decode file as text with {encoding} encoding") from e
+            else:
+                return data
+                
+        except (ArtifactNotFoundError, ArtifactExpiredError):
+            raise
+        except Exception as e:
+            logger.error(
+                "File read failed",
+                extra={"artifact_id": artifact_id, "error": str(e)}
+            )
+            raise ProviderError(f"Read operation failed: {e}") from e
+
+    async def write_file(
+        self,
+        content: Union[str, bytes],
+        *,
+        filename: str,
+        mime: str = "text/plain",
+        summary: str = "",
+        session_id: str = None,
+        meta: Dict[str, Any] = None,
+        encoding: str = "utf-8",
+        overwrite_artifact_id: str = None
+    ) -> str:
+        """
+        Write content to a new file or overwrite existing WITHIN THE SAME SESSION.
+        
+        Parameters
+        ----------
+        content : str or bytes
+            Content to write
+        filename : str
+            Filename for the new file
+        mime : str, optional
+            MIME type (default: text/plain)
+        summary : str, optional
+            File summary
+        session_id : str, optional
+            Session for the file
+        meta : dict, optional
+            Additional metadata
+        encoding : str, optional
+            Text encoding for string content (default: utf-8)
+        overwrite_artifact_id : str, optional
+            If provided, overwrite this existing artifact (must be in same session)
+            
+        Returns
+        -------
+        str
+            Artifact ID of the written file
+            
+        Raises
+        ------
+        ArtifactStoreError
+            If trying to overwrite a file in a different session
+        """
+        self._check_closed()
+        
+        try:
+            # Convert content to bytes if needed
+            if isinstance(content, str):
+                data = content.encode(encoding)
+            else:
+                data = content
+            
+            # Handle overwrite case with session security check
+            if overwrite_artifact_id:
+                try:
+                    existing_meta = await self._get_record(overwrite_artifact_id)
+                    existing_session = existing_meta.get("session_id")
+                    
+                    # STRICT SECURITY: Can only overwrite files in the same session
+                    if session_id and session_id != existing_session:
+                        raise ArtifactStoreError(
+                            f"Cross-session overwrite not permitted. Artifact {overwrite_artifact_id} "
+                            f"belongs to session '{existing_session}', cannot overwrite from "
+                            f"session '{session_id}'. Overwrite operations must be within the same session."
+                        )
+                    
+                    # Use the existing session if no session_id provided
+                    session_id = session_id or existing_session
+                    
+                    # Delete old version (within same session)
+                    from .metadata import MetadataOperations
+                    metadata_ops = MetadataOperations(self._artifact_store)
+                    await metadata_ops.delete(overwrite_artifact_id)
+                    
+                except (ArtifactNotFoundError, ArtifactExpiredError):
+                    pass  # Original doesn't exist, proceed with new creation
+            
+            # Store new content using core operations
+            from .core import CoreStorageOperations
+            core_ops = CoreStorageOperations(self._artifact_store)
+            
+            write_meta = {**(meta or {})}
+            if overwrite_artifact_id:
+                write_meta["overwrote"] = overwrite_artifact_id
+                write_meta["overwrite_timestamp"] = datetime.utcnow().isoformat(timespec="seconds") + "Z"
+                write_meta["overwrite_within_session"] = session_id
+            
+            artifact_id = await core_ops.store(
+                data=data,
+                mime=mime,
+                summary=summary or f"Written file: {filename}",
+                filename=filename,
+                session_id=session_id,
+                meta=write_meta
+            )
+            
+            logger.info(
+                "File written successfully",
+                extra={
+                    "artifact_id": artifact_id,
+                    "filename": filename,
+                    "bytes": len(data),
+                    "overwrite": bool(overwrite_artifact_id),
+                    "session_id": session_id,
+                    "security_level": "session_isolated"
+                }
+            )
+            
+            return artifact_id
+            
+        except Exception as e:
+            logger.error(
+                "File write failed",
+                extra={
+                    "filename": filename,
+                    "overwrite_artifact_id": overwrite_artifact_id,
+                    "session_id": session_id,
+                    "error": str(e)
+                }
+            )
+            raise ProviderError(f"Write operation failed: {e}") from e
+
+    async def get_directory_contents(
+        self,
+        session_id: str,
+        directory_prefix: str = "",
+        limit: int = 100
+    ) -> List[Dict[str, Any]]:
+        """
+        List files in a directory-like structure within a session.
+        
+        This operation is inherently session-safe since it requires
+        explicit session_id parameter.
+        """
+        try:
+            from .metadata import MetadataOperations
+            metadata_ops = MetadataOperations(self._artifact_store)
+            return await metadata_ops.list_by_prefix(session_id, directory_prefix, limit)
+        except Exception as e:
+            logger.error(
+                "Directory listing failed",
+                extra={
+                    "session_id": session_id,
+                    "directory_prefix": directory_prefix,
+                    "error": str(e)
+                }
+            )
+            raise ProviderError(f"Directory listing failed: {e}") from e
+
+    async def _retrieve_data(self, artifact_id: str) -> bytes:
+        """Helper to retrieve artifact data using core operations."""
+        from .core import CoreStorageOperations
+        core_ops = CoreStorageOperations(self._artifact_store)
+        return await core_ops.retrieve(artifact_id)
+
+    # NEW: Session security validation helper
+    async def _validate_session_access(self, artifact_id: str, expected_session_id: str = None) -> Dict[str, Any]:
+        """
+        Validate that an artifact belongs to the expected session.
+        
+        Parameters
+        ----------
+        artifact_id : str
+            Artifact to check
+        expected_session_id : str, optional
+            Expected session ID (if None, just returns the session)
+            
+        Returns
+        -------
+        dict
+            Artifact metadata
+            
+        Raises
+        ------
+        ArtifactStoreError
+            If artifact belongs to different session
+        """
+        record = await self._get_record(artifact_id)
+        actual_session = record.get("session_id")
+        
+        if expected_session_id and actual_session != expected_session_id:
+            raise ArtifactStoreError(
+                f"Session access violation: Artifact {artifact_id} belongs to "
+                f"session '{actual_session}', but access was attempted from "
+                f"session '{expected_session_id}'. Cross-session access is not permitted."
+            )
+        
+        return record

chuk_artifacts/store.py

@@ -1,13 +1,13 @@
 # -*- coding: utf-8 -*-
-# chuk_artifacts/store.py
+# chuk_artifacts/store.py (ENHANCED)
 """
-Asynchronous, object-store-backed artefact manager with proper modularization.
+Asynchronous, object-store-backed artefact manager with MCP server support.
 """
 
 from __future__ import annotations
 
 import os, logging
-from typing import Any, Dict, List, Callable, AsyncContextManager, Optional
+from typing import Any, Dict, List, Callable, AsyncContextManager, Optional, Union
 
 try:
     import aioboto3
@@ -51,15 +51,9 @@ def _default_session_factory() -> Callable[[], AsyncContextManager]:
 # ─────────────────────────────────────────────────────────────────────
 class ArtifactStore:
     """
-    FINAL FIXED: Asynchronous artifact storage with modularized operations.
+    Asynchronous artifact storage with MCP server support.
     
-    The circular reference issue has been resolved by fixing BaseOperations.
-    Now properly delegates operations to specialized modules:
-    - CoreStorageOperations: store() and retrieve()
-    - PresignedURLOperations: presign*() methods
-    - MetadataOperations: metadata(), exists(), delete()
-    - BatchOperations: store_batch()
-    - AdminOperations: validate_configuration(), get_stats()
+    Enhanced with MCP-specific operations for file management within sessions.
     """
 
     def __init__(
@@ -129,22 +123,23 @@ class ArtifactStore:
         self._session_provider_name = session_provider or "memory"
         self._closed = False
 
-        # Initialize operation modules (import here to avoid circular dependencies)
-        # FIXED: Now works correctly with the fixed BaseOperations
+        # Initialize operation modules
         from .core import CoreStorageOperations
         from .presigned import PresignedURLOperations
         from .metadata import MetadataOperations
         from .batch import BatchOperations
         from .admin import AdminOperations
+        from .session_operations import SessionOperations 
         
         self._core = CoreStorageOperations(self)
         self._presigned = PresignedURLOperations(self)
         self._metadata = MetadataOperations(self)
         self._batch = BatchOperations(self)
         self._admin = AdminOperations(self)
+        self._session = SessionOperations(self)
 
         logger.info(
-            "ArtifactStore initialized with fixed modular operations",
+            "ArtifactStore initialized with session operations support",
             extra={
                 "bucket": bucket,
                 "storage_provider": self._storage_provider_name,
@@ -284,15 +279,20 @@ class ArtifactStore:
         summary: str = None,
         meta: Dict[str, Any] = None,
         filename: str = None,
-        ttl: int = None
+        ttl: int = None,
+        # NEW: MCP-specific parameters
+        new_meta: Dict[str, Any] = None,
+        merge: bool = True
     ) -> Dict[str, Any]:
-        """Update artifact metadata without changing the stored data."""
+        """Update artifact metadata with MCP server compatibility."""
         return await self._metadata.update_metadata(
             artifact_id,
             summary=summary,
             meta=meta,
             filename=filename,
-            ttl=ttl
+            ttl=ttl,
+            new_meta=new_meta,
+            merge=merge
         )
 
     async def extend_ttl(self, artifact_id: str, additional_seconds: int) -> Dict[str, Any]:
@@ -303,6 +303,15 @@ class ArtifactStore:
         """List artifacts for a specific session."""
         return await self._metadata.list_by_session(session_id, limit)
 
+    async def list_by_prefix(
+        self, 
+        session_id: str, 
+        prefix: str = "", 
+        limit: int = 100
+    ) -> List[Dict[str, Any]]:
+        """List artifacts in a session with filename prefix filtering."""
+        return await self._metadata.list_by_prefix(session_id, prefix, limit)
+
     # ─────────────────────────────────────────────────────────────────
     # Batch operations (delegated to BatchOperations)
     # ─────────────────────────────────────────────────────────────────
@@ -328,6 +337,95 @@ class ArtifactStore:
         """Get storage statistics."""
         return await self._admin.get_stats()
 
+    # ─────────────────────────────────────────────────────────────────
+    # Session-based file operations (delegated to SessionOperations)
+    # ─────────────────────────────────────────────────────────────────
+
+    async def move_file(
+        self,
+        artifact_id: str,
+        *,
+        new_filename: str = None,
+        new_session_id: str = None,
+        new_meta: Dict[str, Any] = None
+    ) -> Dict[str, Any]:
+        """Move a file within sessions or rename it."""
+        return await self._session.move_file(
+            artifact_id,
+            new_filename=new_filename,
+            new_session_id=new_session_id,
+            new_meta=new_meta
+        )
+
+    async def copy_file(
+        self,
+        artifact_id: str,
+        *,
+        new_filename: str = None,
+        target_session_id: str = None,
+        new_meta: Dict[str, Any] = None,
+        summary: str = None
+    ) -> str:
+        """Copy a file within or across sessions."""
+        return await self._session.copy_file(
+            artifact_id,
+            new_filename=new_filename,
+            target_session_id=target_session_id,
+            new_meta=new_meta,
+            summary=summary
+        )
+
+    async def read_file(
+        self,
+        artifact_id: str,
+        *,
+        encoding: str = "utf-8",
+        as_text: bool = True
+    ) -> Union[str, bytes]:
+        """Read file content directly."""
+        return await self._session.read_file(
+            artifact_id,
+            encoding=encoding,
+            as_text=as_text
+        )
+
+    async def write_file(
+        self,
+        content: Union[str, bytes],
+        *,
+        filename: str,
+        mime: str = "text/plain",
+        summary: str = "",
+        session_id: str = None,
+        meta: Dict[str, Any] = None,
+        encoding: str = "utf-8",
+        overwrite_artifact_id: str = None
+    ) -> str:
+        """Write content to a new file or overwrite existing."""
+        return await self._session.write_file(
+            content,
+            filename=filename,
+            mime=mime,
+            summary=summary,
+            session_id=session_id,
+            meta=meta,
+            encoding=encoding,
+            overwrite_artifact_id=overwrite_artifact_id
+        )
+
+    async def get_directory_contents(
+        self,
+        session_id: str,
+        directory_prefix: str = "",
+        limit: int = 100
+    ) -> List[Dict[str, Any]]:
+        """List files in a directory-like structure within a session."""
+        return await self._session.get_directory_contents(
+            session_id,
+            directory_prefix,
+            limit
+        )
+
     # ─────────────────────────────────────────────────────────────────
     # Resource management
     # ─────────────────────────────────────────────────────────────────