xitzin 0.3.0__tar.gz → 0.4.0__tar.gz

{xitzin-0.3.0 → xitzin-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: xitzin
-Version: 0.3.0
+Version: 0.4.0
 Summary: A Gemini Application Framework
 Keywords: gemini,protocol,framework,async,geminispace
 Author: Alan Velasco
@@ -25,11 +25,11 @@ Requires-Dist: typing-extensions>=4.15.0
 Requires-Dist: sqlmodel>=0.0.22 ; extra == 'sqlmodel'
 Requires-Dist: croniter>=1.0.0 ; extra == 'tasks'
 Requires-Python: >=3.10
-Project-URL: Changelog, https://xitzin.readthedocs.io/changelog/
-Project-URL: Documentation, https://xitzin.readthedocs.io
 Project-URL: Homepage, https://github.com/alanbato/xitzin
-Project-URL: Issues, https://github.com/alanbato/xitzin/issues
+Project-URL: Documentation, https://xitzin.readthedocs.io
 Project-URL: Repository, https://github.com/alanbato/xitzin.git
+Project-URL: Issues, https://github.com/alanbato/xitzin/issues
+Project-URL: Changelog, https://xitzin.readthedocs.io/changelog/
 Provides-Extra: sqlmodel
 Provides-Extra: tasks
 Description-Content-Type: text/markdown

{xitzin-0.3.0 → xitzin-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xitzin"
-version = "0.3.0"
+version = "0.4.0"
 description = "A Gemini Application Framework"
 readme = "README.md"
 license = { text = "MIT" }

{xitzin-0.3.0 → xitzin-0.4.0}/src/xitzin/__init__.py

@@ -42,7 +42,7 @@ from .exceptions import (
     TaskConfigurationError,
     TemporaryFailure,
 )
-from .requests import Request
+from .requests import Request, TitanRequest
 from .responses import Input, Link, Redirect, Response
 
 __all__ = [
@@ -50,6 +50,7 @@ __all__ = [
     "Xitzin",
     # Request/Response
     "Request",
+    "TitanRequest",
     "Response",
     "Input",
     "Redirect",

{xitzin-0.3.0 → xitzin-0.4.0}/src/xitzin/application.py

@@ -11,13 +11,19 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any, Callable
 
 from nauyaca.protocol.request import GeminiRequest
+from nauyaca.protocol.request import TitanRequest as NauyacaTitanRequest
 from nauyaca.protocol.response import GeminiResponse
 from nauyaca.protocol.status import StatusCode
 
-from .exceptions import GeminiException, NotFound, TaskConfigurationError
-from .requests import Request
+from .exceptions import (
+    CertificateRequired,
+    GeminiException,
+    NotFound,
+    TaskConfigurationError,
+)
+from .requests import Request, TitanRequest
 from .responses import Input, Redirect, convert_response
-from .routing import MountedRoute, Route, Router
+from .routing import MountedRoute, Route, Router, TitanRoute
 
 if TYPE_CHECKING:
     from .tasks import BackgroundTask
@@ -227,6 +233,45 @@ class Xitzin:
 
         return decorator
 
+    def titan(
+        self,
+        path: str,
+        *,
+        name: str | None = None,
+        auth_tokens: list[str] | None = None,
+    ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        """Register a Titan upload handler.
+
+        Titan is the upload companion protocol to Gemini. This decorator
+        registers a handler for Titan upload requests.
+
+        Args:
+            path: URL path pattern (e.g., "/upload/{filename}").
+            name: Optional route name. Defaults to function name.
+            auth_tokens: List of valid authentication tokens. If provided,
+                requests without a valid token are rejected with status 60.
+
+        Returns:
+            Decorator function.
+
+        Example:
+            @app.titan("/upload/{filename}", auth_tokens=["secret123"])
+            def upload(request: TitanRequest, content: bytes,
+                       mime_type: str, token: str | None, filename: str):
+                if request.is_delete():
+                    Path(f"./uploads/{filename}").unlink()
+                    return "# Deleted"
+                Path(f"./uploads/{filename}").write_bytes(content)
+                return "# Upload successful"
+        """
+
+        def decorator(handler: Callable[..., Any]) -> Callable[..., Any]:
+            route = TitanRoute(path, handler, name=name, auth_tokens=auth_tokens)
+            self._router.add_titan_route(route)
+            return handler
+
+        return decorator
+
     def mount(
         self,
         path: str,
@@ -563,24 +608,69 @@ class Xitzin:
 
         except GeminiException as e:
             return GeminiResponse(status=e.status_code, meta=e.message)
-        except Exception as e:
+        except Exception:
             # Log the error and return a generic failure
             import traceback
 
             traceback.print_exc()
             return GeminiResponse(
                 status=StatusCode.TEMPORARY_FAILURE,
-                meta=f"Internal error: {type(e).__name__}",
+                meta="Internal server error",
+            )
+
+    async def _handle_titan_request(
+        self, raw_request: NauyacaTitanRequest
+    ) -> GeminiResponse:
+        """Handle an incoming Titan upload request.
+
+        This is the Titan request processing logic, separate from Gemini.
+        """
+        request = TitanRequest(raw_request, self)
+
+        try:
+            # Match Titan route
+            match = self._router.match_titan(request.path)
+            if match is None:
+                raise NotFound(f"No Titan route matches: {request.path}")
+
+            route, params = match
+
+            # Validate auth token if required
+            if route.auth_tokens is not None:
+                if not request.token or request.token not in route.auth_tokens:
+                    raise CertificateRequired("Valid authentication token required")
+
+            # Build middleware chain
+            async def call_handler(req: TitanRequest) -> GeminiResponse:
+                result = await route.call_handler(req, params)
+                return convert_response(result, req)
+
+            # Apply middleware (in reverse order so first registered runs first)
+            handler = call_handler
+            for mw in reversed(self._middleware):
+                handler = self._wrap_middleware(mw, handler)
+
+            return await handler(request)
+
+        except GeminiException as e:
+            return GeminiResponse(status=e.status_code, meta=e.message)
+        except Exception:
+            import traceback
+
+            traceback.print_exc()
+            return GeminiResponse(
+                status=StatusCode.TEMPORARY_FAILURE,
+                meta="Internal server error",
             )
 
     def _wrap_middleware(
         self,
         middleware: Callable[..., Any],
-        next_handler: Callable[[Request], Any],
-    ) -> Callable[[Request], Any]:
+        next_handler: Callable[..., Any],
+    ) -> Callable[..., Any]:
         """Wrap a handler with middleware."""
 
-        async def wrapped(request: Request) -> GeminiResponse:
+        async def wrapped(request: Any) -> GeminiResponse:
             if asyncio.iscoroutinefunction(middleware):
                 return await middleware(request, next_handler)
             return middleware(request, next_handler)
@@ -659,11 +749,30 @@ class Xitzin:
             async def handle(request: GeminiRequest) -> GeminiResponse:
                 return await self._handle_request(request)
 
+            # Create Titan upload handler if Titan routes are registered
+            upload_handler = None
+            if self._router.has_titan_routes():
+                from nauyaca.server.handler import UploadHandler
+
+                class XitzinUploadHandler(UploadHandler):
+                    """Wrapper to route Titan uploads to Xitzin handlers."""
+
+                    def __init__(self, app: "Xitzin") -> None:
+                        self._app = app
+
+                    async def handle_upload(
+                        self, request: NauyacaTitanRequest
+                    ) -> GeminiResponse:
+                        return await self._app._handle_titan_request(request)
+
+                upload_handler = XitzinUploadHandler(self)
+                print("[Xitzin] Titan upload support enabled")
+
             # Use TLSServerProtocol for manual TLS handling
             # (supports self-signed client certs)
             def create_protocol() -> TLSServerProtocol:
                 return TLSServerProtocol(
-                    lambda: GeminiServerProtocol(handle, None),  # type: ignore[arg-type]
+                    lambda: GeminiServerProtocol(handle, None, upload_handler),
                     ssl_context,
                 )
 

{xitzin-0.3.0 → xitzin-0.4.0}/src/xitzin/auth.py

@@ -6,6 +6,7 @@ Gemini client certificate authentication.
 
 from __future__ import annotations
 
+import hmac
 from dataclasses import dataclass
 from functools import wraps
 from typing import TYPE_CHECKING, Any, Callable
@@ -89,6 +90,27 @@ def require_certificate(handler: Callable[..., Any]) -> Callable[..., Any]:
     return wrapper
 
 
+def _timing_safe_fingerprint_check(fingerprint: str, allowed: list[str]) -> bool:
+    """Check if fingerprint matches any allowed value using timing-safe comparison.
+
+    This prevents timing attacks that could reveal valid fingerprints.
+
+    Args:
+        fingerprint: The fingerprint to check.
+        allowed: List of allowed fingerprints.
+
+    Returns:
+        True if fingerprint matches any allowed value.
+    """
+    # Encode once for comparison
+    fp_bytes = fingerprint.encode("utf-8")
+
+    for allowed_fp in allowed:
+        if hmac.compare_digest(fp_bytes, allowed_fp.encode("utf-8")):
+            return True
+    return False
+
+
 def require_fingerprint(
     *allowed_fingerprints: str,
 ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
@@ -97,6 +119,8 @@ def require_fingerprint(
     If the client certificate fingerprint is not in the allowed list,
     returns status 61 (certificate not authorized).
 
+    Uses timing-safe comparison to prevent fingerprint enumeration attacks.
+
     Args:
         *allowed_fingerprints: SHA-256 fingerprints that are allowed.
 
@@ -111,7 +135,7 @@ def require_fingerprint(
         def admin_panel(request: Request):
             return "# Admin Panel"
     """
-    allowed_set = set(allowed_fingerprints)
+    allowed_list = list(allowed_fingerprints)
 
     def decorator(handler: Callable[..., Any]) -> Callable[..., Any]:
         @wraps(handler)
@@ -119,7 +143,9 @@ def require_fingerprint(
             if not request.client_cert_fingerprint:
                 raise CertificateRequired("Client certificate required")
 
-            if request.client_cert_fingerprint not in allowed_set:
+            if not _timing_safe_fingerprint_check(
+                request.client_cert_fingerprint, allowed_list
+            ):
                 raise CertificateNotAuthorized("Certificate not authorized")
 
             return handler(request, *args, **kwargs)

{xitzin-0.3.0 → xitzin-0.4.0}/src/xitzin/cgi.py

@@ -26,10 +26,13 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+import structlog
 from nauyaca.protocol.response import GeminiResponse
 
 from .exceptions import BadRequest, CGIError, NotFound
 
+logger = structlog.get_logger("xitzin.cgi")
+
 if TYPE_CHECKING:
     from .requests import Request
 
@@ -56,7 +59,7 @@ class CGIConfig:
     max_header_size: int = 8192
     streaming: bool = False
     check_execute_permission: bool = True
-    inherit_environment: bool = True
+    inherit_environment: bool = False
     app_state_keys: list[str] = field(default_factory=list)
 
 
@@ -379,10 +382,14 @@ class CGIHandler:
 
             # Check exit code
             if process.returncode != 0:
-                error_msg = stderr.decode("utf-8", errors="replace")[:200]
-                if error_msg:
-                    raise CGIError(
-                        f"CGI script exited with code {process.returncode}: {error_msg}"
+                # Log stderr server-side but don't expose to client
+                if stderr:
+                    error_detail = stderr.decode("utf-8", errors="replace")[:500]
+                    logger.error(
+                        "cgi_script_failed",
+                        script=str(script_path),
+                        returncode=process.returncode,
+                        stderr=error_detail,
                     )
                 raise CGIError(f"CGI script exited with code {process.returncode}")
 
@@ -420,7 +427,7 @@ class CGIScript:
         *,
         timeout: float = 30.0,
         check_execute_permission: bool = True,
-        inherit_environment: bool = True,
+        inherit_environment: bool = False,
         app_state_keys: list[str] | None = None,
     ) -> None:
         """Create a single-script CGI handler.
@@ -530,10 +537,14 @@ class CGIScript:
                 ) from None
 
             if process.returncode != 0:
-                error_msg = stderr.decode("utf-8", errors="replace")[:200]
-                if error_msg:
-                    raise CGIError(
-                        f"CGI script exited with code {process.returncode}: {error_msg}"
+                # Log stderr server-side but don't expose to client
+                if stderr:
+                    error_detail = stderr.decode("utf-8", errors="replace")[:500]
+                    logger.error(
+                        "cgi_script_failed",
+                        script=str(self.script_path),
+                        returncode=process.returncode,
+                        stderr=error_detail,
                     )
                 raise CGIError(f"CGI script exited with code {process.returncode}")
 

{xitzin-0.3.0 → xitzin-0.4.0}/src/xitzin/middleware.py

@@ -202,7 +202,9 @@ class RateLimitMiddleware(BaseMiddleware):
         """Get a unique identifier for the client."""
         if request.client_cert_fingerprint:
             return f"cert:{request.client_cert_fingerprint}"
-        # Fall back to a placeholder (in production, use IP from transport)
+        # Use IP address when available for anonymous clients
+        if request.remote_addr:
+            return f"ip:{request.remote_addr}"
         return "unknown"
 
     def _is_rate_limited(self, client_id: str) -> bool:
@@ -309,7 +311,7 @@ class UserSessionMiddleware(BaseMiddleware):
             return self._async_cache[fingerprint]
 
         self._cache_misses += 1
-        user = await self._user_loader(fingerprint)  # type: ignore[misc]
+        user = await self._user_loader(fingerprint)
 
         # Add to cache
         self._async_cache[fingerprint] = user

{xitzin-0.3.0 → xitzin-0.4.0}/src/xitzin/requests.py

@@ -9,6 +9,7 @@ from typing import TYPE_CHECKING, Any
 from urllib.parse import unquote_plus
 
 from nauyaca.protocol.request import GeminiRequest
+from nauyaca.protocol.request import TitanRequest as NauyacaTitanRequest
 
 if TYPE_CHECKING:
     from cryptography.x509 import Certificate
@@ -148,3 +149,105 @@ class Request:
 
     def __repr__(self) -> str:
         return f"Request({self._raw_request.raw_url!r})"
+
+
+class TitanRequest:
+    """Wraps a Nauyaca TitanRequest for Titan upload handlers.
+
+    Handlers receive this object as their first argument for @app.titan routes.
+
+    Example:
+        @app.titan("/upload/{filename}", auth_tokens=["secret"])
+        def upload(request: TitanRequest, content: bytes,
+                   mime_type: str, token: str | None, filename: str):
+            if request.is_delete():
+                return "# Deleted"
+            Path(f"./uploads/{filename}").write_bytes(content)
+            return "# Upload successful"
+
+    Attributes:
+        app: The Xitzin application instance.
+        state: Arbitrary state storage for this request.
+        path: The URL path component.
+        content: The uploaded content bytes.
+        mime_type: Content MIME type.
+        token: Authentication token (if provided).
+        size: Content size in bytes.
+    """
+
+    def __init__(
+        self, raw_request: NauyacaTitanRequest, app: Xitzin | None = None
+    ) -> None:
+        self._raw_request = raw_request
+        self._app = app
+        self._state = RequestState()
+
+    @property
+    def app(self) -> Xitzin:
+        """The Xitzin application handling this request."""
+        if self._app is None:
+            msg = "Request is not bound to an application"
+            raise RuntimeError(msg)
+        return self._app
+
+    @property
+    def state(self) -> RequestState:
+        """Arbitrary state storage for this request."""
+        return self._state
+
+    @property
+    def path(self) -> str:
+        """The URL path component."""
+        return self._raw_request.path
+
+    @property
+    def content(self) -> bytes:
+        """The uploaded content bytes."""
+        return self._raw_request.content
+
+    @property
+    def mime_type(self) -> str:
+        """Content MIME type."""
+        return self._raw_request.mime_type
+
+    @property
+    def token(self) -> str | None:
+        """Authentication token (if provided)."""
+        return self._raw_request.token
+
+    @property
+    def size(self) -> int:
+        """Content size in bytes."""
+        return self._raw_request.size
+
+    def is_delete(self) -> bool:
+        """Check if this is a delete request (zero-byte upload)."""
+        return self._raw_request.is_delete()
+
+    @property
+    def hostname(self) -> str:
+        """The server hostname from the URL."""
+        return self._raw_request.hostname
+
+    @property
+    def port(self) -> int:
+        """The server port from the URL."""
+        return self._raw_request.port
+
+    @property
+    def client_cert(self) -> Certificate | None:
+        """The client's TLS certificate, if provided."""
+        return self._raw_request.client_cert
+
+    @property
+    def client_cert_fingerprint(self) -> str | None:
+        """SHA-256 fingerprint of the client certificate."""
+        return self._raw_request.client_cert_fingerprint
+
+    @property
+    def raw_url(self) -> str:
+        """The original URL from the request."""
+        return self._raw_request.raw_url
+
+    def __repr__(self) -> str:
+        return f"TitanRequest({self._raw_request.raw_url!r})"

{xitzin-0.3.0 → xitzin-0.4.0}/src/xitzin/responses.py

@@ -14,7 +14,6 @@ from nauyaca.protocol.status import StatusCode
 
 if TYPE_CHECKING:
     from .application import Xitzin
-    from .requests import Request
 
 
 class ResponseConvertible(Protocol):
@@ -156,7 +155,7 @@ class Link:
         return self.to_gemtext()
 
 
-def convert_response(result: Any, request: Request | None = None) -> GeminiResponse:
+def convert_response(result: Any, request: Any = None) -> GeminiResponse:
     """Convert a handler return value to a GeminiResponse.
 
     Handlers can return:
@@ -168,7 +167,7 @@ def convert_response(result: Any, request: Request | None = None) -> GeminiRespo
 
     Args:
         result: The return value from a handler.
-        request: The current request (for URL tracking).
+        request: The current request (Request or TitanRequest, for URL tracking).
 
     Returns:
         A GeminiResponse instance.

{xitzin-0.3.0 → xitzin-0.4.0}/src/xitzin/routing.py

@@ -282,6 +282,143 @@ class MountedRoute:
         return f"MountedRoute({self.path_prefix!r}, name={self.name!r})"
 
 
+class TitanRoute:
+    """Route for Titan upload handlers with integrated authentication.
+
+    Similar to Route, but designed for Titan uploads with:
+    - Token-based authentication
+    - Explicit content/mime_type/token parameters passed to handlers
+
+    Example:
+        route = TitanRoute(
+            "/upload/{filename}",
+            upload_handler,
+            auth_tokens=["secret123"]
+        )
+    """
+
+    def __init__(
+        self,
+        path: str,
+        handler: Callable[..., Any],
+        *,
+        name: str | None = None,
+        auth_tokens: list[str] | None = None,
+    ) -> None:
+        """Create a new Titan route.
+
+        Args:
+            path: Path template with optional parameters (e.g., "/upload/{filename}").
+            handler: The handler function to call.
+            name: Route name for identification. Defaults to handler function name.
+            auth_tokens: List of valid authentication tokens. If provided,
+                requests without a valid token are rejected with status 60.
+        """
+        self.path = path
+        self.handler = handler
+        self.name = (
+            name if name is not None else getattr(handler, "__name__", "<anonymous>")
+        )
+        self.auth_tokens = set(auth_tokens) if auth_tokens else None
+
+        self._param_pattern, self._param_names = self._compile_path(path)
+        self._type_hints = self._get_handler_type_hints(handler)
+        self._is_async = asyncio.iscoroutinefunction(handler)
+
+    def _compile_path(self, path: str) -> tuple[re.Pattern[str], list[str]]:
+        """Convert a path template to a regex pattern.
+
+        Same logic as Route._compile_path().
+        """
+        param_names: list[str] = []
+
+        def replace_param(match: re.Match[str]) -> str:
+            name = match.group(1)
+            param_type = match.group(2)
+            param_names.append(name)
+
+            if param_type == "path":
+                return f"(?P<{name}>.+)"
+            return f"(?P<{name}>[^/]+)"
+
+        escaped = re.escape(path)
+        escaped = escaped.replace(r"\{", "{").replace(r"\}", "}")
+        regex_path = PATH_PARAM_PATTERN.sub(replace_param, escaped)
+
+        return re.compile(f"^{regex_path}$"), param_names
+
+    def _get_handler_type_hints(self, handler: Callable[..., Any]) -> dict[str, type]:
+        """Extract type hints from handler function.
+
+        Excludes 'request', 'content', 'mime_type', 'token', and 'return'.
+        """
+        try:
+            hints = get_type_hints(handler)
+            # Remove non-path-parameter hints
+            hints.pop("request", None)
+            hints.pop("content", None)
+            hints.pop("mime_type", None)
+            hints.pop("token", None)
+            hints.pop("return", None)
+            return hints
+        except Exception:
+            return {}
+
+    def matches(self, path: str) -> bool:
+        """Check if this route matches the given path."""
+        return self._param_pattern.match(path) is not None
+
+    def extract_params(self, path: str) -> dict[str, Any]:
+        """Extract and type-convert path parameters."""
+        match = self._param_pattern.match(path)
+        if not match:
+            return {}
+
+        params: dict[str, Any] = {}
+        for name, value in match.groupdict().items():
+            target_type = self._type_hints.get(name, str)
+            try:
+                if target_type is int:
+                    params[name] = int(value)
+                elif target_type is float:
+                    params[name] = float(value)
+                elif target_type is bool:
+                    params[name] = value.lower() in ("true", "1", "yes")
+                else:
+                    params[name] = value
+            except (ValueError, TypeError):
+                params[name] = value
+
+        return params
+
+    async def call_handler(self, request: Any, params: dict[str, Any]) -> Any:
+        """Call the handler with request and explicit Titan parameters.
+
+        Args:
+            request: TitanRequest object (typed as Any to avoid circular imports).
+            params: Path parameters extracted from the URL.
+
+        Handler receives: (request, content, mime_type, token, **path_params)
+        """
+        # Add Titan-specific parameters
+        handler_params = {
+            "content": request.content,
+            "mime_type": request.mime_type,
+            "token": request.token,
+            **params,
+        }
+
+        if self._is_async:
+            return await self.handler(request, **handler_params)
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            None, lambda: self.handler(request, **handler_params)
+        )
+
+    def __repr__(self) -> str:
+        return f"TitanRoute({self.path!r}, name={self.name!r})"
+
+
 class Router:
     """Collection of routes with matching logic.
 
@@ -293,6 +430,7 @@ class Router:
         self._routes: list[Route] = []
         self._routes_by_name: dict[str, Route] = {}
         self._mounted_routes: list[MountedRoute] = []
+        self._titan_routes: list[TitanRoute] = []
 
     def add_route(self, route: Route) -> None:
         """Add a route to the router.
@@ -351,6 +489,33 @@ class Router:
                 return route, params
         return None
 
+    def add_titan_route(self, route: TitanRoute) -> None:
+        """Add a Titan upload route to the router.
+
+        Args:
+            route: The Titan route to add.
+        """
+        self._titan_routes.append(route)
+
+    def match_titan(self, path: str) -> tuple[TitanRoute, dict[str, Any]] | None:
+        """Find a matching Titan route and extract parameters.
+
+        Args:
+            path: URL path to match.
+
+        Returns:
+            Tuple of (titan_route, params) if found, None otherwise.
+        """
+        for route in self._titan_routes:
+            if route.matches(path):
+                params = route.extract_params(path)
+                return route, params
+        return None
+
+    def has_titan_routes(self) -> bool:
+        """Check if any Titan routes are registered."""
+        return len(self._titan_routes) > 0
+
     def reverse(self, name: str, **params: Any) -> str:
         """Build URL for a named route.
 

{xitzin-0.3.0 → xitzin-0.4.0}/src/xitzin/scgi.py

@@ -49,7 +49,7 @@ class SCGIConfig:
     timeout: float = 30.0
     max_response_size: int | None = 1048576  # 1MB default
     buffer_size: int = 8192
-    inherit_environment: bool = True
+    inherit_environment: bool = False
     app_state_keys: list[str] = field(default_factory=list)
 
 

{xitzin-0.3.0 → xitzin-0.4.0}/src/xitzin/testing.py

@@ -13,6 +13,7 @@ from typing import TYPE_CHECKING, Generator
 from urllib.parse import quote_plus
 
 from nauyaca.protocol.request import GeminiRequest
+from nauyaca.protocol.request import TitanRequest as NauyacaTitanRequest
 from nauyaca.protocol.response import GeminiResponse
 
 if TYPE_CHECKING:
@@ -153,10 +154,15 @@ class TestClient:
         # Handle request through the app
         response = self._handle_sync(request)
 
+        # Convert bytes body to str for TestResponse
+        body = response.body
+        if isinstance(body, bytes):
+            body = body.decode("utf-8")
+
         return TestResponse(
             status=response.status,
             meta=response.meta,
-            body=response.body,
+            body=body,
         )
 
     def get_input(
@@ -210,6 +216,100 @@ class TestClient:
         new_client._default_fingerprint = fingerprint
         return new_client
 
+    def upload(
+        self,
+        path: str,
+        content: bytes | str,
+        *,
+        mime_type: str = "text/gemini",
+        token: str | None = None,
+        cert_fingerprint: str | None = None,
+    ) -> TestResponse:
+        """Make a Titan upload request.
+
+        Args:
+            path: The request path (e.g., "/upload/file.gmi").
+            content: Content to upload (str will be UTF-8 encoded).
+            mime_type: Content MIME type (default: text/gemini).
+            token: Authentication token (if required by route).
+            cert_fingerprint: Mock client certificate fingerprint.
+
+        Returns:
+            TestResponse with status, meta, and body.
+
+        Example:
+            response = client.upload(
+                "/files/test.gmi",
+                "# Hello World",
+                mime_type="text/gemini",
+                token="secret123"
+            )
+            assert response.is_success
+        """
+        # Convert str to bytes
+        if isinstance(content, str):
+            content_bytes = content.encode("utf-8")
+        else:
+            content_bytes = content
+
+        # Build Titan URL
+        size = len(content_bytes)
+        url = f"titan://testserver{path};size={size};mime={mime_type}"
+        if token:
+            url += f";token={token}"
+
+        # Create TitanRequest
+        request = NauyacaTitanRequest.from_line(url)
+        request.content = content_bytes
+
+        # Set certificate info
+        fingerprint = cert_fingerprint or self._default_fingerprint
+        if fingerprint:
+            request.client_cert_fingerprint = fingerprint
+
+        # Handle through app
+        response = self._handle_titan_sync(request)
+
+        # Convert bytes body to str for TestResponse
+        body = response.body
+        if isinstance(body, bytes):
+            body = body.decode("utf-8")
+
+        return TestResponse(
+            status=response.status,
+            meta=response.meta,
+            body=body,
+        )
+
+    def delete(
+        self,
+        path: str,
+        *,
+        token: str | None = None,
+        cert_fingerprint: str | None = None,
+    ) -> TestResponse:
+        """Make a Titan delete request (zero-byte upload).
+
+        Args:
+            path: The request path to delete.
+            token: Authentication token (if required by route).
+            cert_fingerprint: Mock client certificate fingerprint.
+
+        Returns:
+            TestResponse with status, meta, and body.
+
+        Example:
+            response = client.delete("/files/old.gmi", token="secret123")
+            assert response.is_success
+        """
+        return self.upload(
+            path,
+            b"",
+            mime_type="text/gemini",
+            token=token,
+            cert_fingerprint=cert_fingerprint,
+        )
+
     def _handle_sync(self, request: GeminiRequest) -> GeminiResponse:
         """Handle a request synchronously."""
         try:
@@ -220,6 +320,16 @@ class TestClient:
 
         return loop.run_until_complete(self._app._handle_request(request))
 
+    def _handle_titan_sync(self, request: NauyacaTitanRequest) -> GeminiResponse:
+        """Handle a Titan request synchronously."""
+        try:
+            loop = asyncio.get_event_loop()
+        except RuntimeError:
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+
+        return loop.run_until_complete(self._app._handle_titan_request(request))
+
 
 @contextmanager
 def test_app(app: "Xitzin") -> Generator[TestClient, None, None]: