filebridge 0.1.0__tar.gz

filebridge-0.1.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.3
+Name: filebridge
+Version: 0.1.0
+Summary: A Python library for interacting with the Filebridge daemon (filebridged).
+Author: Stefan Schönberger
+Author-email: Stefan Schönberger <stefan@sniner.dev>
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: cryptography>=46.0.0
+Requires-Dist: zstandard>=0.25.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# Filebridge Python Client
+
+A Python client library for interacting with the [Filebridge daemon](https://github.com/sniner/filebridge) (`filebridged`). Built on `httpx` and `pydantic`, it provides synchronous and asynchronous access to remote files via the filebridge REST API, including chunked streaming and transparent ChaCha20Poly1305 encryption when a token is configured.
+
+## Requirements
+
+- Python >= 3.13
+- `httpx` >= 0.28.1
+- `pydantic` >= 2.12.5
+- `cryptography` >= 44.0.0
+
+## Features
+
+- **Asynchronous & Synchronous Client**: Full native support for async and sync Python environments.
+- **Streaming Files**: Memory-efficient chunked streaming via `stream_read` and `write_stream`.
+- **Automatic Encryption**: Secure ChaCha20Poly1305 AEAD streaming encryption natively handled whenever a token is used.
+
+## Usage
+
+```python
+from filebridge import FileBridgeClient
+
+client = FileBridgeClient("http://localhost:8000")
+loc = client.location("demo", token="my-secret-token")
+
+# Read metadata for a file
+info = loc.info("/path/to/file.txt")
+print(f"File size: {info.size} bytes")
+
+# Read a file
+data = loc.read("/path/to/file.txt")
+
+# Write a file
+loc.write("/path/to/file.txt", b"Hello, World!")
+```

filebridge-0.1.0/README.md

@@ -0,0 +1,35 @@
+# Filebridge Python Client
+
+A Python client library for interacting with the [Filebridge daemon](https://github.com/sniner/filebridge) (`filebridged`). Built on `httpx` and `pydantic`, it provides synchronous and asynchronous access to remote files via the filebridge REST API, including chunked streaming and transparent ChaCha20Poly1305 encryption when a token is configured.
+
+## Requirements
+
+- Python >= 3.13
+- `httpx` >= 0.28.1
+- `pydantic` >= 2.12.5
+- `cryptography` >= 44.0.0
+
+## Features
+
+- **Asynchronous & Synchronous Client**: Full native support for async and sync Python environments.
+- **Streaming Files**: Memory-efficient chunked streaming via `stream_read` and `write_stream`.
+- **Automatic Encryption**: Secure ChaCha20Poly1305 AEAD streaming encryption natively handled whenever a token is used.
+
+## Usage
+
+```python
+from filebridge import FileBridgeClient
+
+client = FileBridgeClient("http://localhost:8000")
+loc = client.location("demo", token="my-secret-token")
+
+# Read metadata for a file
+info = loc.info("/path/to/file.txt")
+print(f"File size: {info.size} bytes")
+
+# Read a file
+data = loc.read("/path/to/file.txt")
+
+# Write a file
+loc.write("/path/to/file.txt", b"Hello, World!")
+```

filebridge-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "filebridge"
+version = "0.1.0"
+description = "A Python library for interacting with the Filebridge daemon (filebridged)."
+readme = "README.md"
+authors = [
+    { name = "Stefan Schönberger", email = "stefan@sniner.dev" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.12.5",
+    "cryptography>=46.0.0",
+    "zstandard>=0.25.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest (>=9.0.2,<10.0.0)",
+    "basedpyright (>=1.38.2,<2.0.0)",
+    "ruff>=0.15.4",
+]
+
+[tool.pyright]
+typeCheckingMode = "standard"
+useLibraryCodeForTypes = true
+venvPath = "."
+venv = ".venv"
+
+[tool.ruff]
+line-length = 96
+ignore = ["E402"]
+
+[tool.ruff.lint]
+per-file-ignores = { "__init__.py" = ["F401"] }
+
+[tool.pytest.ini_options]
+pythonpath = ["tests"]
+
+[build-system]
+requires = ["uv_build>=0.9.28,<0.10.0"]
+build-backend = "uv_build"

filebridge-0.1.0/src/filebridge/__init__.py

@@ -0,0 +1,35 @@
+from .async_client import (
+    AsyncFileBridgeClient,
+    AsyncLocation,
+)
+from .exceptions import (
+    AuthenticationError,
+    FileBridgeError,
+    FileBridgePermissionError,
+    IsDirectoryError,
+    NotFoundError,
+)
+from .io import (
+    AsyncFileBridgeReadStream,
+    FileBridgeReadStream,
+)
+from .models import (
+    Metadata,
+)
+from .sync_client import (
+    FileBridgeClient,
+    Location,
+)
+
+__all__ = [
+    "FileBridgeClient",
+    "AsyncFileBridgeClient",
+    "Location",
+    "AsyncLocation",
+    "FileBridgeError",
+    "AuthenticationError",
+    "NotFoundError",
+    "IsDirectoryError",
+    "FileBridgePermissionError",
+    "Metadata",
+]

filebridge-0.1.0/src/filebridge/async_client.py

@@ -0,0 +1,290 @@
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from typing import AsyncContextManager, List, Optional, overload
+
+import httpx
+
+from .core import (
+    build_encrypted_write_body,
+    decode_read_response,
+    get_api_path,
+    handle_response_errors,
+    parse_json_response,
+    prepare_request_kwargs,
+)
+from .exceptions import AuthenticationError, FileBridgeError, IsDirectoryError, NotFoundError
+from .io import AsyncFileBridgeReadStream
+from .models import ListResponse, Metadata
+
+
+class AsyncLocation:
+    def __init__(self, client: AsyncFileBridgeClient, dir_id: str, token: Optional[str] = None):
+        self.dir_id = dir_id
+        self.token = token
+        self._client = client
+
+    async def _send_request(
+        self, method: str, path: str, req_nonce: Optional[str] = None, **kwargs
+    ) -> httpx.Response:
+        url = f"{self._client.base_url.rstrip('/')}/{get_api_path(self.dir_id, path)}"
+        kwargs, generated_nonce = prepare_request_kwargs(
+            method=method,
+            url=url,
+            token=self.token,
+            kwargs=kwargs,
+        )
+        # Use the passed req_nonce if provided (e.g., from write/write_stream where kwargs is prepared early)
+        expected_nonce = req_nonce if req_nonce is not None else generated_nonce
+
+        resp = await self._client.client.request(method, url, **kwargs)
+
+        if not resp.is_success:
+            handle_response_errors(resp.status_code, resp.text)
+            raise FileBridgeError(f"HTTP Error {resp.status_code}: {resp.text}")
+
+        if self.token:
+            resp_nonce = resp.headers.get("X-Nonce")
+            if resp_nonce != expected_nonce:
+                raise AuthenticationError("Nonce mismatch")
+        return resp
+
+    async def read(
+        self, path: str, offset: Optional[int] = None, length: Optional[int] = None
+    ) -> bytes:
+        api_path = get_api_path(self.dir_id, path)
+        params = {}
+        if offset is not None:
+            params["offset"] = offset
+        if length is not None:
+            params["length"] = length
+
+        headers = {"Accept": "application/octet-stream"}
+        if self.token:
+            headers["Accept"] = "application/vnd.filebridge.stream"
+
+        resp = await self._send_request("GET", api_path, params=params, headers=headers)
+
+        return decode_read_response(
+            self.token,
+            resp.headers.get("Content-Type", ""),
+            resp.content,
+            resp.request.headers.get("X-Signature"),
+            path,
+        )
+
+    async def write(self, path: str, data: bytes, offset: Optional[int] = None):
+        api_path = get_api_path(self.dir_id, path)
+        params = {}
+        if offset is not None:
+            params["offset"] = offset
+
+        headers = {"Content-Type": "application/octet-stream"}
+        if self.token:
+            headers["Content-Type"] = "application/vnd.filebridge.stream"
+
+        url = f"{self._client.base_url.rstrip('/')}/{api_path}"
+        kwargs, _ = prepare_request_kwargs(
+            "PUT", url, self.token, {"params": params, "headers": headers}
+        )
+
+        if self.token:
+            sig = kwargs.get("headers", {}).get("X-Signature", "")
+            kwargs["content"] = build_encrypted_write_body(self.token, sig, data)
+            await self._send_request(
+                "PUT", path, req_nonce=kwargs.get("headers", {}).get("X-Nonce"), **kwargs
+            )
+        else:
+            kwargs["content"] = data
+            await self._send_request("PUT", path, **kwargs)
+
+    @overload
+    def stream_read(
+        self,
+        path: str,
+        offset: Optional[int] = ...,
+        length: Optional[int] = ...,
+        encoding: None = None,
+    ) -> AsyncContextManager[AsyncFileBridgeReadStream]: ...
+
+    @overload
+    def stream_read(
+        self,
+        path: str,
+        offset: Optional[int] = ...,
+        length: Optional[int] = ...,
+        *,
+        encoding: str,
+    ) -> AsyncContextManager[AsyncFileBridgeReadStream]: ...
+
+    @asynccontextmanager
+    async def stream_read(
+        self,
+        path: str,
+        offset: Optional[int] = None,
+        length: Optional[int] = None,
+        encoding: Optional[str] = None,
+    ):
+        api_path = get_api_path(self.dir_id, path)
+        params = {}
+        if offset is not None:
+            params["offset"] = offset
+        if length is not None:
+            params["length"] = length
+
+        headers = {"Accept": "application/octet-stream"}
+        if self.token:
+            headers["Accept"] = "application/vnd.filebridge.stream"
+
+        url = f"{self._client.base_url.rstrip('/')}/{api_path}"
+        kwargs, req_nonce = prepare_request_kwargs(
+            method="GET",
+            url=url,
+            token=self.token,
+            kwargs={"params": params, "headers": headers},
+        )
+        headers = kwargs.setdefault("headers", {})
+
+        async with self._client.client.stream("GET", url, **kwargs) as resp:
+            if not resp.is_success:
+                await resp.aread()
+                handle_response_errors(resp.status_code, resp.text)
+                raise FileBridgeError(f"HTTP Error {resp.status_code}: {resp.text}")
+
+            if self.token:
+                resp_nonce = resp.headers.get("X-Nonce")
+                if resp_nonce != req_nonce:
+                    raise AuthenticationError("Nonce mismatch")
+
+            content_type = resp.headers.get("Content-Type", "")
+            if "application/json" in content_type:
+                body = await resp.aread()
+                sig = resp.request.headers.get("X-Signature", "") if self.token else None
+                data = parse_json_response(self.token, sig, body)
+                if "items" in data:
+                    raise IsDirectoryError(f"{path} is a directory")
+
+            raw_stream = AsyncFileBridgeReadStream(resp, self.token)
+            if encoding:
+                raise NotImplementedError(
+                    "TextIOWrapper is not supported for async streams directly."
+                )
+            else:
+                async with raw_stream as stream:
+                    yield stream
+
+    async def write_stream(self, path: str, stream, offset: Optional[int] = None):
+        api_path = get_api_path(self.dir_id, path)
+        params = {}
+        if offset is not None:
+            params["offset"] = offset
+
+        async def chunk_generator():
+            import inspect
+
+            if hasattr(stream, "read"):
+                # If the method returns a coroutine, we await it
+                while True:
+                    result = stream.read(64 * 1024)
+                    if inspect.isawaitable(result):
+                        chunk = await result
+                    else:
+                        chunk = result
+                    if not chunk:
+                        break
+                    if isinstance(chunk, str):
+                        chunk = chunk.encode("utf-8")
+                    yield chunk
+            elif hasattr(stream, "__aiter__"):
+                async for chunk in stream:
+                    if isinstance(chunk, str):
+                        chunk = chunk.encode("utf-8")
+                    yield chunk
+            else:
+                for chunk in stream:
+                    if isinstance(chunk, str):
+                        chunk = chunk.encode("utf-8")
+                    yield chunk
+
+        headers = {"Content-Type": "application/octet-stream"}
+        if self.token:
+            headers["Content-Type"] = "application/vnd.filebridge.stream"
+
+        url = f"{self._client.base_url.rstrip('/')}/{api_path}"
+        kwargs, _ = prepare_request_kwargs(
+            "PUT", url, self.token, {"params": params, "headers": headers}
+        )
+
+        if self.token:
+            token = self.token
+
+            from .stream import (
+                StreamAead,
+                encode_data,
+                encode_stop,
+            )
+
+            async def signed_chunk_generator():
+                sig = kwargs.get("headers", {}).get("X-Signature", "")
+                aead = StreamAead(token, sig)
+                async for chunk in chunk_generator():
+                    encrypted_chunk = aead.encrypt(chunk)
+                    yield encode_data(encrypted_chunk)
+                yield encode_stop(aead.finalize())
+
+            kwargs["content"] = signed_chunk_generator()
+            await self._send_request(
+                "PUT", path, req_nonce=kwargs.get("headers", {}).get("X-Nonce"), **kwargs
+            )
+        else:
+            kwargs["content"] = chunk_generator()
+            await self._send_request("PUT", path, **kwargs)
+
+    async def list(self, path: Optional[str] = None) -> List[Metadata]:
+        api_path = get_api_path(self.dir_id, path)
+        resp = await self._send_request("GET", api_path)
+
+        sig = resp.request.headers.get("X-Signature", "") if self.token else None
+        data = parse_json_response(self.token, sig, resp.content)
+        if "items" not in data:
+            meta = Metadata(**data)
+            return [meta]
+
+        list_resp = ListResponse(**data)
+        return list_resp.items
+
+    async def info(self, path: str) -> Metadata:
+        api_path = get_api_path(self.dir_id, path)
+        resp = await self._send_request("GET", api_path)
+        sig = resp.request.headers.get("X-Signature", "") if self.token else None
+        data = parse_json_response(self.token, sig, resp.content)
+        return Metadata(**data)
+
+    async def exists(self, path: str) -> bool:
+        try:
+            await self.info(path)
+            return True
+        except NotFoundError:
+            return False
+
+    async def delete(self, path: str):
+        api_path = get_api_path(self.dir_id, path)
+        await self._send_request("DELETE", api_path)
+
+
+class AsyncFileBridgeClient:
+    def __init__(self, base_url: str):
+        self.base_url = base_url.rstrip("/") + "/"
+        self.client = httpx.AsyncClient(base_url=self.base_url)
+
+    def location(self, dir_id: str, token: Optional[str] = None) -> AsyncLocation:
+        return AsyncLocation(self, dir_id, token)
+
+    async def close(self):
+        await self.client.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()

filebridge-0.1.0/src/filebridge/core.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import secrets
+import time
+from typing import Any
+from urllib.parse import urlparse
+
+from .exceptions import (
+    AuthenticationError,
+    FileBridgeError,
+    FileBridgePermissionError,
+    IsDirectoryError,
+    NotFoundError,
+)
+
+
+def calculate_signature(
+    token: str | None, method: str, url: str, timestamp: str, nonce: str
+) -> str:
+    if not token:
+        return ""
+
+    parsed = urlparse(url)
+    path = parsed.path
+    if parsed.query:
+        path += "?" + parsed.query
+
+    mac = hmac.new(token.encode(), digestmod=hashlib.sha256)
+    mac.update(timestamp.encode())
+    mac.update(nonce.encode())
+    mac.update(method.upper().encode())
+    mac.update(path.encode())
+
+    return mac.hexdigest()
+
+
+def get_api_path(dir_id: str, path: str | None) -> str:
+    """Build the API path, stripping leading slashes from the requested path."""
+    if path:
+        # Ensure path doesn't start with / to avoid urljoin issues
+        clean_path = path.lstrip("/")
+        if clean_path:
+            return f"api/v1/fs/{dir_id}/{clean_path}"
+    return f"api/v1/fs/{dir_id}"
+
+
+def prepare_request_kwargs(
+    method: str, url: str, token: str | None, kwargs: dict[str, Any]
+) -> tuple[dict[str, Any], str]:
+    content = kwargs.get("content", b"")
+    if isinstance(content, str):
+        kwargs["content"] = content.encode()
+    elif kwargs.get("json") is not None:
+        kwargs["content"] = json.dumps(kwargs["json"], separators=(",", ":")).encode()
+        if "json" in kwargs:
+            del kwargs["json"]
+
+    nonce = ""
+    if token:
+        headers = kwargs.get("headers", {})
+        if "X-Signature" not in headers:
+            timestamp = str(int(time.time()))
+            nonce = secrets.token_hex(8)
+            signature = calculate_signature(token, method, url, timestamp, nonce)
+            headers.update(
+                {"X-Signature": signature, "X-Timestamp": timestamp, "X-Nonce": nonce}
+            )
+        kwargs["headers"] = headers
+
+    return kwargs, nonce
+
+
+def handle_response_errors(status_code: int, text: str):
+    if status_code == 401:
+        raise AuthenticationError(f"Authentication failed: {text}")
+    if status_code == 403:
+        raise FileBridgePermissionError(f"Access Forbidden: {text}")
+    if status_code == 404:
+        raise NotFoundError(f"Not Found: {text}")
+
+
+def parse_json_response(token: str | None, signature: str | None, body: bytes) -> dict:
+    """Parse a JSON response body, decrypting it first when token+signature are present."""
+    parsed = json.loads(body)
+    if token and signature:
+        from .stream import StreamError, decrypt_json_response
+
+        message = parsed.get("message")
+        if message is None:
+            raise FileBridgeError("Missing 'message' field in encrypted response")
+        try:
+            json_bytes = decrypt_json_response(token, signature, message)
+        except StreamError as e:
+            raise FileBridgeError(f"JSON response decryption failed: {e}")
+        return json.loads(json_bytes)
+    return parsed
+
+
+def decode_read_response(
+    token: str | None,
+    content_type: str,
+    content: bytes,
+    sig: str | None,
+    path: str,
+) -> bytes:
+    """Evaluate Content-Type and return decoded payload bytes.
+
+    Raises IsDirectoryError for directory JSON responses, FileBridgeError
+    for missing signature in stream mode.
+    """
+    if "application/json" in content_type:
+        data = parse_json_response(token, sig if token else None, content)
+        if "items" in data:
+            raise IsDirectoryError(f"{path} is a directory")
+
+    if "application/vnd.filebridge.stream" in content_type:
+        if not sig or not token:
+            raise FileBridgeError("Missing signature for stream verification")
+        return decode_verified_stream_content(token, sig, content)
+
+    return content
+
+
+def build_encrypted_write_body(token: str, sig: str, data: bytes) -> bytes:
+    """Pack `data` into signed stream frames (ChaCha20Poly1305)."""
+    from .stream import StreamAead, encode_data, encode_stop
+
+    CHUNK_SIZE = 64 * 1024
+    aead = StreamAead(token, sig)
+    buf = bytearray()
+    for i in range(0, len(data), CHUNK_SIZE):
+        buf.extend(encode_data(aead.encrypt(data[i : i + CHUNK_SIZE])))
+    buf.extend(encode_stop(aead.finalize()))
+    return bytes(buf)
+
+
+def decode_verified_stream_content(token: str, signature: str, content: bytes) -> bytes:
+    from .stream import StreamAead, StreamDecoder, StreamError
+
+    decoder = StreamDecoder()
+    aead = StreamAead(token, signature)
+    decoder.push(content)
+
+    result_bytes = bytearray()
+    while True:
+        frame = decoder.next_frame()
+        if not frame:
+            break
+        tag, sig_str, payload = frame
+        if tag == "DATA":
+            try:
+                result_bytes.extend(aead.decrypt(payload))
+            except StreamError:
+                raise FileBridgeError("Chunk Authenticated Decryption failed")
+        elif tag == "STOP":
+            if not sig_str:
+                raise FileBridgeError("Stop frame missing signature")
+            try:
+                aead.verify_stop(sig_str)
+            except StreamError:
+                raise FileBridgeError("Stop signature mismatch")
+            break
+    return bytes(result_bytes)

filebridge-0.1.0/src/filebridge/exceptions.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+
+class FileBridgeError(Exception):
+    """Base exception for FileBridge."""
+
+    pass
+
+
+class AuthenticationError(FileBridgeError):
+    """Raised when authentication fails (401/403)."""
+
+    pass
+
+
+class NotFoundError(FileBridgeError):
+    """Raised when a resource is not found (404)."""
+
+    pass
+
+
+class IsDirectoryError(FileBridgeError):
+    """Raised when a file operation is attempted on a directory."""
+
+    pass
+
+
+class FileBridgePermissionError(FileBridgeError):
+    """Raised when an operation is forbidden due to permissions (403)."""
+
+    pass

filebridge-0.1.0/src/filebridge/io.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+import io
+
+import httpx
+
+from .exceptions import FileBridgeError
+from .stream import StreamError
+
+
+class FileBridgeReadStream(io.RawIOBase):
+    def __init__(self, response: httpx.Response, token: str | None = None):
+        self._response = response
+        self._token = token
+        self._iter = response.iter_bytes()
+        self._buffer = bytearray()
+        self._eof = False
+
+        self._is_verified = "application/vnd.filebridge.stream" in response.headers.get(
+            "Content-Type", ""
+        )
+        self._decoder = None
+
+        if self._is_verified:
+            from .stream import StreamDecoder, StreamAead
+
+            signature = response.request.headers.get("X-Signature")
+            if not signature or not self._token:
+                raise FileBridgeError("Missing signature for stream verification")
+            self._decoder = StreamDecoder()
+            self._aead = StreamAead(self._token, signature)
+
+    @property
+    def name(self) -> str:
+        return self.__class__.__name__
+
+    def readable(self) -> bool:
+        return True
+
+    def close(self):
+        self._response.close()
+        super().close()
+
+    def _fill_buffer(self) -> bool:
+        """Reads from HTTP stream into buffer. Returns True if data was added, False if EOF."""
+        if self._eof:
+            return False
+
+        if not self._is_verified:
+            try:
+                chunk = next(self._iter)
+                if chunk:
+                    self._buffer.extend(chunk)
+                    return True
+                return False
+            except StopIteration:
+                self._eof = True
+                return False
+
+        # Verified stream logic
+        decoder = self._decoder
+        aead = self._aead
+        assert decoder is not None and aead is not None
+
+        while not self._eof:
+            frame = decoder.next_frame()
+            if frame:
+                tag, sig_str, payload = frame
+                if tag == "DATA":
+                    try:
+                        self._buffer.extend(aead.decrypt(payload))
+                        return True
+                    except StreamError:
+                        raise FileBridgeError("Chunk Authenticated Decryption Failed")
+                elif tag == "STOP":
+                    if not sig_str:
+                        raise FileBridgeError("Stop frame missing signature")
+                    try:
+                        aead.verify_stop(sig_str)
+                    except StreamError:
+                        raise FileBridgeError("Stop signature mismatch")
+                    self._eof = True
+                    return False
+            else:
+                try:
+                    decoder.push(next(self._iter))
+                except StopIteration:
+                    raise FileBridgeError("Unexpected EOF before STOP frame")
+
+        return bool(self._buffer)
+
+    def readinto(self, b) -> int:
+        if not self._buffer and not self._eof:
+            self._fill_buffer()
+
+        if not self._buffer:
+            return 0
+
+        length = min(len(b), len(self._buffer))
+        b[:length] = self._buffer[:length]
+        del self._buffer[:length]
+        return length
+
+    def read(self, size: int = -1) -> bytes:
+        if size == -1 or size is None:
+            while not self._eof:
+                self._fill_buffer()
+            res = bytes(self._buffer)
+            self._buffer.clear()
+            return res
+
+        while len(self._buffer) < size and not self._eof:
+            self._fill_buffer()
+
+        length = min(size, len(self._buffer))
+        res = bytes(self._buffer[:length])
+        del self._buffer[:length]
+        return res
+
+
+class AsyncFileBridgeReadStream:
+    def __init__(self, response: httpx.Response, token: str | None = None):
+        self._response = response
+        self._token = token
+        self._iter = response.aiter_bytes()
+        self._buffer = bytearray()
+        self._eof = False
+
+        self._is_verified = "application/vnd.filebridge.stream" in response.headers.get(
+            "Content-Type", ""
+        )
+        self._decoder = None
+
+        if self._is_verified:
+            from .stream import StreamDecoder, StreamAead
+
+            signature = response.request.headers.get("X-Signature")
+            if not signature or not self._token:
+                raise FileBridgeError("Missing signature for stream verification")
+            self._decoder = StreamDecoder()
+            self._aead = StreamAead(self._token, signature)
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()
+
+    async def close(self):
+        await self._response.aclose()
+
+    async def _fill_buffer(self) -> bool:
+        if self._eof:
+            return False
+
+        if not self._is_verified:
+            try:
+                chunk = await self._iter.__anext__()
+                if chunk:
+                    self._buffer.extend(chunk)
+                    return True
+                return False
+            except StopAsyncIteration:
+                self._eof = True
+                return False
+
+        # Verified stream logic
+        decoder = self._decoder
+        aead = self._aead
+        assert decoder is not None and aead is not None
+
+        while not self._eof:
+            frame = decoder.next_frame()
+            if frame:
+                tag, sig_str, payload = frame
+                if tag == "DATA":
+                    try:
+                        self._buffer.extend(aead.decrypt(payload))
+                        return True
+                    except StreamError:
+                        raise FileBridgeError("Chunk Authenticated Decryption Failed")
+                elif tag == "STOP":
+                    if not sig_str:
+                        raise FileBridgeError("Stop frame missing signature")
+                    try:
+                        aead.verify_stop(sig_str)
+                    except StreamError:
+                        raise FileBridgeError("Stop signature mismatch")
+                    self._eof = True
+                    return False
+            else:
+                try:
+                    decoder.push(await self._iter.__anext__())
+                except StopAsyncIteration:
+                    raise FileBridgeError("Unexpected EOF before STOP frame")
+
+        return bool(self._buffer)
+
+    async def read(self, size: int = -1) -> bytes:
+        if size == -1 or size is None:
+            while not self._eof:
+                await self._fill_buffer()
+            res = bytes(self._buffer)
+            self._buffer.clear()
+            return res
+
+        while len(self._buffer) < size and not self._eof:
+            await self._fill_buffer()
+
+        length = min(size, len(self._buffer))
+        res = bytes(self._buffer[:length])
+        del self._buffer[:length]
+        return res

filebridge-0.1.0/src/filebridge/models.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class Metadata(BaseModel):
+    name: str
+    is_dir: bool
+    size: int | None = None
+    mdate: str | None = None
+    sha256: str | None = None
+
+
+class ListResponse(BaseModel):
+    items: list[Metadata]
+    detail: str | None = None

filebridge-0.1.0/src/filebridge/stream.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import struct
+
+import zstandard
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305
+
+
+class StreamError(Exception):
+    pass
+
+
+class StreamAead:
+    def __init__(self, token: str, iv_hex: str):
+        key_hash = hashlib.sha256(token.encode()).digest()
+        self.cipher = ChaCha20Poly1305(key_hash)
+
+        iv_hasher = hashlib.sha256()
+        iv_hasher.update(token.encode())
+        iv_hasher.update(iv_hex.encode())
+        iv_hash = iv_hasher.digest()
+
+        self.nonce_base = bytearray(12)
+        copy_len = min(len(iv_hash), 12)
+        self.nonce_base[:copy_len] = iv_hash[:copy_len]
+        self.counter = 0
+
+    def _current_nonce(self) -> bytes:
+        nonce_bytes = bytearray(self.nonce_base)
+        counter_bytes = struct.pack(">Q", self.counter)
+        for i in range(8):
+            nonce_bytes[4 + i] ^= counter_bytes[i]
+        return bytes(nonce_bytes)
+
+    def encrypt(self, data: bytes) -> bytes:
+        nonce = self._current_nonce()
+        ciphertext = self.cipher.encrypt(nonce, data, None)
+        self.counter += 1
+        return ciphertext
+
+    def decrypt(self, data: bytes) -> bytes:
+        nonce = self._current_nonce()
+        try:
+            plaintext = self.cipher.decrypt(nonce, data, None)
+            self.counter += 1
+            return plaintext
+        except InvalidTag as e:
+            raise StreamError(f"Decryption failed: {e}")
+
+    def finalize(self) -> str:
+        final_block = self.encrypt(b"")
+        return final_block.hex()
+
+    def verify_stop(self, hex_sig: str):
+        try:
+            final_block = bytes.fromhex(hex_sig)
+            self.decrypt(final_block)
+        except (ValueError, StreamError) as e:
+            raise StreamError(f"Invalid stop signature: {e}")
+
+
+def encode_data(payload: bytes) -> bytes:
+    frame = bytearray(b"DATA")
+    frame.extend(struct.pack(">I", len(payload)))
+    frame.extend(payload)
+    return bytes(frame)
+
+
+def encode_stop(signature: str | None = None) -> bytes:
+    frame = bytearray(b"STOP")
+    if signature:
+        sig_bytes = signature.encode()
+        frame.extend(struct.pack(">I", len(sig_bytes)))
+        frame.extend(sig_bytes)
+    else:
+        frame.extend(struct.pack(">I", 0))
+    return bytes(frame)
+
+
+def _derive_block_nonce(token: str, iv_hex: str) -> tuple[ChaCha20Poly1305, bytes]:
+    """Shared key+nonce derivation for single-block JSON encryption (counter=0)."""
+    key_hash = hashlib.sha256(token.encode()).digest()
+    cipher = ChaCha20Poly1305(key_hash)
+    iv_hasher = hashlib.sha256()
+    iv_hasher.update(token.encode())
+    iv_hasher.update(iv_hex.encode())
+    nonce = iv_hasher.digest()[:12]
+    return cipher, nonce
+
+
+def encrypt_json_response(token: str, iv_hex: str, json_bytes: bytes) -> str:
+    """Compress, encrypt and base64-encode JSON bytes for a token-protected response."""
+    compressed = zstandard.ZstdCompressor(level=3).compress(json_bytes)
+    cipher, nonce = _derive_block_nonce(token, iv_hex)
+    ciphertext = cipher.encrypt(nonce, compressed, None)
+    return base64.b64encode(ciphertext).decode("ascii")
+
+
+def decrypt_json_response(token: str, iv_hex: str, encoded: str) -> bytes:
+    """Base64-decode, decrypt and decompress an encrypted JSON response."""
+    data = base64.b64decode(encoded)
+    cipher, nonce = _derive_block_nonce(token, iv_hex)
+    try:
+        compressed = cipher.decrypt(nonce, data, None)
+    except InvalidTag as e:
+        raise StreamError(f"JSON response decryption failed: {e}")
+    return zstandard.ZstdDecompressor().decompress(compressed)
+
+
+class StreamDecoder:
+    def __init__(self):
+        self.buffer = bytearray()
+        self.offset = 0
+
+    def push(self, chunk: bytes):
+        self.buffer.extend(chunk)
+
+    def next_frame(self) -> tuple[str, str | None, bytes] | None:
+        rem_len = len(self.buffer) - self.offset
+        if rem_len < 8:
+            return None
+
+        tag = bytes(self.buffer[self.offset : self.offset + 4]).decode("ascii")
+        length = struct.unpack(">I", self.buffer[self.offset + 4 : self.offset + 8])[0]
+
+        if rem_len < 8 + length:
+            return None
+
+        payload = bytes(self.buffer[self.offset + 8 : self.offset + 8 + length])
+
+        # Advance buffer offset
+        self.offset += 8 + length
+        
+        # Periodically compact buffer to release memory if we've processed a lot
+        if self.offset > 1024 * 1024:
+            del self.buffer[:self.offset]
+            self.offset = 0
+
+        sig_str = None
+        if tag == "STOP":
+            if length > 0:
+                sig_str = payload.decode("ascii", errors="replace")
+
+        return tag, sig_str, payload

filebridge-0.1.0/src/filebridge/sync_client.py

@@ -0,0 +1,290 @@
+from __future__ import annotations
+
+import io
+from contextlib import contextmanager
+from typing import ContextManager, List, Optional, overload
+
+import httpx
+
+from .core import (
+    build_encrypted_write_body,
+    decode_read_response,
+    get_api_path,
+    handle_response_errors,
+    parse_json_response,
+    prepare_request_kwargs,
+)
+from .exceptions import AuthenticationError, FileBridgeError, IsDirectoryError, NotFoundError
+from .io import FileBridgeReadStream
+from .models import ListResponse, Metadata
+
+
+class Location:
+    def __init__(
+        self,
+        client: "FileBridgeClient",
+        dir_id: str,
+        token: Optional[str] = None,
+    ):
+        self.dir_id = dir_id
+        self.token = token
+        self.http_client = client.client
+        self._client = client
+
+    def _send_request(
+        self, method: str, url: str, kwargs: dict, req_nonce: Optional[str] = None
+    ) -> httpx.Response:
+        response = self.http_client.request(method, url, **kwargs)
+        if not response.is_success:
+            handle_response_errors(response.status_code, response.text)
+            raise FileBridgeError(f"HTTP Error {response.status_code}: {response.text}")
+
+        if self.token:
+            resp_nonce = response.headers.get("X-Nonce")
+            if resp_nonce != req_nonce:
+                raise AuthenticationError("Nonce mismatch")
+        return response
+
+    def read(
+        self,
+        path: str,
+        offset: Optional[int] = None,
+        length: Optional[int] = None,
+    ) -> bytes:
+        api_path = get_api_path(self.dir_id, path)
+        params = {}
+        if offset is not None:
+            params["offset"] = offset
+        if length is not None:
+            params["length"] = length
+
+        url = f"{self._client.base_url.rstrip('/')}/{api_path}"
+        kwargs, req_nonce = prepare_request_kwargs(
+            method="GET",
+            url=url,
+            token=self.token,
+            kwargs={"params": params} if params else {},
+        )
+        headers = kwargs.setdefault("headers", {})
+        headers["Accept"] = "application/octet-stream"
+        if self.token:
+            headers["Accept"] = "application/vnd.filebridge.stream"
+
+        response = self._send_request("GET", url, kwargs, req_nonce)
+
+        return decode_read_response(
+            self.token,
+            response.headers.get("Content-Type", ""),
+            response.content,
+            response.request.headers.get("X-Signature"),
+            path,
+        )
+
+    def write(self, path: str, data: bytes, offset: Optional[int] = None):
+        api_path = get_api_path(self.dir_id, path)
+        params = {}
+        if offset is not None:
+            params["offset"] = offset
+
+        headers = {"Content-Type": "application/octet-stream"}
+        if self.token:
+            headers["Content-Type"] = "application/vnd.filebridge.stream"
+
+        url = f"{self._client.base_url.rstrip('/')}/{api_path}"
+        kwargs, req_nonce = prepare_request_kwargs(
+            "PUT", url, self.token, {"params": params, "headers": headers}
+        )
+
+        if self.token:
+            sig = kwargs.get("headers", {}).get("X-Signature", "")
+            kwargs["content"] = build_encrypted_write_body(self.token, sig, data)
+            self._send_request("PUT", url, kwargs, req_nonce)
+        else:
+            kwargs["content"] = data
+            self._send_request("PUT", url, kwargs, req_nonce)
+
+    @overload
+    def stream_read(
+        self,
+        path: str,
+        offset: Optional[int] = ...,
+        length: Optional[int] = ...,
+        encoding: None = None,
+    ) -> ContextManager[FileBridgeReadStream]: ...
+
+    @overload
+    def stream_read(
+        self,
+        path: str,
+        offset: Optional[int] = ...,
+        length: Optional[int] = ...,
+        *,
+        encoding: str,
+    ) -> ContextManager[io.TextIOWrapper]: ...
+
+    @contextmanager
+    def stream_read(
+        self,
+        path: str,
+        offset: Optional[int] = None,
+        length: Optional[int] = None,
+        encoding: Optional[str] = None,
+    ):
+        api_path = get_api_path(self.dir_id, path)
+        params = {}
+        if offset is not None:
+            params["offset"] = offset
+        if length is not None:
+            params["length"] = length
+
+        headers = {"Accept": "application/octet-stream"}
+        if self.token:
+            headers["Accept"] = "application/vnd.filebridge.stream"
+
+        url = f"{self._client.base_url.rstrip('/')}/{api_path}"
+        kwargs, req_nonce = prepare_request_kwargs(
+            method="GET",
+            url=url,
+            token=self.token,
+            kwargs={"params": params, "headers": headers},
+        )
+        headers = kwargs.setdefault("headers", {})
+
+        with self.http_client.stream("GET", url, **kwargs) as response:
+            if not response.is_success:
+                response.read()  # Ensure content is read before raising for error handling
+                handle_response_errors(response.status_code, response.text)
+                raise FileBridgeError(f"HTTP Error {response.status_code}: {response.text}")
+
+            if self.token:
+                resp_nonce = response.headers.get("X-Nonce")
+                if resp_nonce != req_nonce:
+                    raise AuthenticationError("Nonce mismatch")
+
+            content_type = response.headers.get("Content-Type", "")
+            if "application/json" in content_type:
+                body = response.read()
+                sig = response.request.headers.get("X-Signature", "") if self.token else None
+                data = parse_json_response(self.token, sig, body)
+                if "items" in data:
+                    raise IsDirectoryError(f"{path} is a directory")
+
+            raw_stream = FileBridgeReadStream(response, self.token)
+            if encoding:
+                wrapper = io.TextIOWrapper(raw_stream, encoding=encoding)
+                try:
+                    yield wrapper
+                finally:
+                    wrapper.close()
+            else:
+                try:
+                    yield raw_stream
+                finally:
+                    raw_stream.close()
+
+    def write_stream(self, path: str, stream, offset: Optional[int] = None):
+        api_path = get_api_path(self.dir_id, path)
+        params = {}
+        if offset is not None:
+            params["offset"] = offset
+
+        headers = {"Content-Type": "application/octet-stream"}
+        if self.token:
+            headers["Content-Type"] = "application/vnd.filebridge.stream"
+
+        url = f"{self._client.base_url.rstrip('/')}/{api_path}"
+        kwargs, req_nonce = prepare_request_kwargs(
+            "PUT", url, self.token, {"params": params, "headers": headers}
+        )
+
+        def chunk_generator():
+            if hasattr(stream, "read"):
+                while True:
+                    chunk = stream.read(64 * 1024)
+                    if not chunk:
+                        break
+                    if isinstance(chunk, str):
+                        chunk = chunk.encode("utf-8")
+                    yield chunk
+            else:
+                for chunk in stream:
+                    if isinstance(chunk, str):
+                        chunk = chunk.encode("utf-8")
+                    yield chunk
+
+        if self.token:
+            from .stream import (
+                StreamAead,
+                encode_data,
+                encode_stop,
+            )
+
+            token = self.token
+            assert token is not None
+
+            def signed_chunk_generator():
+                sig = kwargs.get("headers", {}).get("X-Signature", "")
+                aead = StreamAead(token, sig)
+                for chunk in chunk_generator():
+                    encrypted_chunk = aead.encrypt(chunk)
+                    yield encode_data(encrypted_chunk)
+
+                yield encode_stop(aead.finalize())
+
+            kwargs["content"] = signed_chunk_generator()
+            self._send_request("PUT", url, kwargs, req_nonce)
+        else:
+            kwargs["content"] = chunk_generator()
+            self._send_request("PUT", url, kwargs, req_nonce)
+
+    def list(self, path: Optional[str] = None) -> List[Metadata]:
+        url = f"{self._client.base_url.rstrip('/')}/{get_api_path(self.dir_id, path)}"
+        kwargs, req_nonce = prepare_request_kwargs("GET", url, self.token, {})
+        response = self._send_request("GET", url, kwargs, req_nonce)
+
+        sig = response.request.headers.get("X-Signature", "") if self.token else None
+        data = parse_json_response(self.token, sig, response.content)
+        if "items" not in data:
+            meta = Metadata(**data)
+            return [meta]
+
+        list_resp = ListResponse(**data)
+        return list_resp.items
+
+    def info(self, path: str) -> Metadata:
+        url = f"{self._client.base_url.rstrip('/')}/{get_api_path(self.dir_id, path)}"
+        kwargs, req_nonce = prepare_request_kwargs("GET", url, self.token, {})
+        response = self._send_request("GET", url, kwargs, req_nonce)
+        sig = response.request.headers.get("X-Signature", "") if self.token else None
+        data = parse_json_response(self.token, sig, response.content)
+        return Metadata(**data)
+
+    def exists(self, path: str) -> bool:
+        try:
+            self.info(path)
+            return True
+        except NotFoundError:
+            return False
+
+    def delete(self, path: str):
+        url = f"{self._client.base_url.rstrip('/')}/{get_api_path(self.dir_id, path)}"
+        kwargs, req_nonce = prepare_request_kwargs("DELETE", url, self.token, {})
+        self._send_request("DELETE", url, kwargs, req_nonce)
+
+
+class FileBridgeClient:
+    def __init__(self, base_url: str):
+        self.base_url = base_url.rstrip("/") + "/"
+        self.client = httpx.Client(base_url=self.base_url)
+
+    def location(self, dir_id: str, token: Optional[str] = None) -> Location:
+        return Location(self, dir_id, token)
+
+    def close(self):
+        self.client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()