fileclip 0.1.0__tar.gz

fileclip-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Osama Masoud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fileclip-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: fileclip
+Version: 0.1.0
+Summary: Local clipboard-envelope file transfer helper
+Keywords: clipboard,file-transfer,fastapi,local-web-app
+Author: Osama Masoud
+Author-email: Osama Masoud <osama.masoud@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Requires-Dist: fastapi>=0.138.0
+Requires-Dist: typer>=0.26.7
+Requires-Dist: uvicorn>=0.49.0
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/omasoud/fileclip
+Project-URL: Repository, https://github.com/omasoud/fileclip
+Project-URL: Issues, https://github.com/omasoud/fileclip/issues
+Description-Content-Type: text/markdown
+
+# FileClip
+
+FileClip is a small local web app for moving one file through text clipboard synchronization. It packages a dropped file into a self-contained `FILECLIP/1` text envelope, copies that envelope to the local clipboard, and can later hydrate a compatible envelope back into a downloadable file.
+
+FileClip does not sync clipboards, upload files, or store file contents on disk. It assumes another system already syncs clipboard text between the environments you care about.
+
+## Install
+
+For CLI use:
+
+```bash
+uv tool install fileclip
+```
+
+Or with pipx:
+
+```bash
+pipx install fileclip
+```
+
+## Run
+
+```bash
+fileclip
+```
+
+By default the server binds to `127.0.0.1`, chooses an available port, and opens the browser.
+
+Useful options:
+
+```bash
+fileclip --port 8080
+fileclip --no-open
+fileclip --passphrase-prompt
+```
+
+## Plain Mode
+
+Without a passphrase, FileClip creates plain base64 clipboard envelopes. This is convenient for trusted local clipboard-sync paths, but the file bytes are visible to anything that can read the clipboard envelope.
+
+## Passphrase Mode
+
+With `--passphrase` or `--passphrase-prompt`, FileClip encrypts file bytes in the browser with PBKDF2/SHA-256 and AES-GCM before building the clipboard envelope.
+
+`--passphrase-prompt` avoids putting the passphrase in shell history or the process list. The browser still receives the passphrase through local launch configuration so it can encrypt and decrypt files. Passphrase mode is a practical guardrail, not a high-assurance security boundary.
+
+Encrypted mode protects payload bytes but does not hide envelope metadata such as filename, MIME type, file size, or SHA-256 hash.
+
+## Limits
+
+FileClip has no artificial file-size limit, but browsers, clipboards, clipboard managers, and external clipboard-sync channels do. Large payloads may fail to copy, paste, or sync.
+
+Only schema `1` envelopes are supported. FileClip intentionally rejects unknown schema versions and mode mismatches.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run fileclip --no-open
+```
+
+## License
+
+FileClip is distributed under the MIT License.

fileclip-0.1.0/README.md

@@ -0,0 +1,65 @@
+# FileClip
+
+FileClip is a small local web app for moving one file through text clipboard synchronization. It packages a dropped file into a self-contained `FILECLIP/1` text envelope, copies that envelope to the local clipboard, and can later hydrate a compatible envelope back into a downloadable file.
+
+FileClip does not sync clipboards, upload files, or store file contents on disk. It assumes another system already syncs clipboard text between the environments you care about.
+
+## Install
+
+For CLI use:
+
+```bash
+uv tool install fileclip
+```
+
+Or with pipx:
+
+```bash
+pipx install fileclip
+```
+
+## Run
+
+```bash
+fileclip
+```
+
+By default the server binds to `127.0.0.1`, chooses an available port, and opens the browser.
+
+Useful options:
+
+```bash
+fileclip --port 8080
+fileclip --no-open
+fileclip --passphrase-prompt
+```
+
+## Plain Mode
+
+Without a passphrase, FileClip creates plain base64 clipboard envelopes. This is convenient for trusted local clipboard-sync paths, but the file bytes are visible to anything that can read the clipboard envelope.
+
+## Passphrase Mode
+
+With `--passphrase` or `--passphrase-prompt`, FileClip encrypts file bytes in the browser with PBKDF2/SHA-256 and AES-GCM before building the clipboard envelope.
+
+`--passphrase-prompt` avoids putting the passphrase in shell history or the process list. The browser still receives the passphrase through local launch configuration so it can encrypt and decrypt files. Passphrase mode is a practical guardrail, not a high-assurance security boundary.
+
+Encrypted mode protects payload bytes but does not hide envelope metadata such as filename, MIME type, file size, or SHA-256 hash.
+
+## Limits
+
+FileClip has no artificial file-size limit, but browsers, clipboards, clipboard managers, and external clipboard-sync channels do. Large payloads may fail to copy, paste, or sync.
+
+Only schema `1` envelopes are supported. FileClip intentionally rejects unknown schema versions and mode mismatches.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run fileclip --no-open
+```
+
+## License
+
+FileClip is distributed under the MIT License.

fileclip-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "fileclip"
+version = "0.1.0"
+description = "Local clipboard-envelope file transfer helper"
+readme = "README.md"
+authors = [
+    { name = "Osama Masoud", email = "osama.masoud@gmail.com" }
+]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["clipboard", "file-transfer", "fastapi", "local-web-app"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Web Environment",
+    "Framework :: FastAPI",
+    "Intended Audience :: End Users/Desktop",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Utilities",
+]
+requires-python = ">=3.14"
+dependencies = [
+    "fastapi>=0.138.0",
+    "typer>=0.26.7",
+    "uvicorn>=0.49.0",
+]
+
+[project.scripts]
+fileclip = "fileclip.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/omasoud/fileclip"
+Repository = "https://github.com/omasoud/fileclip"
+Issues = "https://github.com/omasoud/fileclip/issues"
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv]
+exclude-newer = "2 days" # Exclude packages released in the last 2 days as a protection against undiscovered supply chain vulnerabilities.
+
+[dependency-groups]
+dev = [
+    "httpx2>=2.4.0",
+    "packaging>=26.2",
+    "pytest>=9.1.1",
+]

fileclip-0.1.0/src/fileclip/__init__.py

@@ -0,0 +1,8 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("fileclip")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

fileclip-0.1.0/src/fileclip/__main__.py

@@ -0,0 +1,6 @@
+"""Module entry point for `python -m fileclip`."""
+
+from fileclip.cli import main
+
+if __name__ == "__main__":
+    main()

fileclip-0.1.0/src/fileclip/cli.py

@@ -0,0 +1,228 @@
+"""Command-line interface for FileClip."""
+
+from __future__ import annotations
+
+import ipaddress
+import socket
+import webbrowser
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Annotated
+
+import typer
+import uvicorn
+
+from fileclip.server import LaunchConfig, create_app
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 0
+
+app = typer.Typer(
+    add_completion=False,
+    help="Run the local FileClip clipboard-envelope web app.",
+    no_args_is_help=False,
+)
+
+
+@dataclass(frozen=True)
+class ServerLaunch:
+    """Resolved server launch details."""
+
+    host: str
+    requested_port: int
+    port: int
+    url: str
+    sockets: list[socket.socket] | None = None
+
+
+def is_loopback_host(host: str) -> bool:
+    """Return whether host is an accepted loopback bind address."""
+
+    normalized = host.strip().lower()
+    if normalized == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(normalized).is_loopback
+    except ValueError:
+        return False
+
+
+def format_host_for_url(host: str) -> str:
+    """Format a host for use in an HTTP URL."""
+
+    if ":" in host and not host.startswith("["):
+        return f"[{host}]"
+    return host
+
+
+def build_app_url(host: str, port: int) -> str:
+    """Build the browser URL for a FileClip server."""
+
+    return f"http://{format_host_for_url(host)}:{port}/"
+
+
+def _bind_socket(host: str) -> socket.socket:
+    """Bind and listen on an available port for the requested host."""
+
+    last_error: OSError | None = None
+    for family, socktype, proto, _canonname, sockaddr in socket.getaddrinfo(
+        host,
+        0,
+        type=socket.SOCK_STREAM,
+    ):
+        sock = socket.socket(family, socktype, proto)
+        try:
+            sock.bind(sockaddr)
+            sock.listen()
+        except OSError as exc:
+            last_error = exc
+            sock.close()
+            continue
+        return sock
+    if last_error is not None:
+        raise last_error
+    raise OSError(f"Could not resolve a bind address for {host!r}.")
+
+
+def close_sockets(sockets: list[socket.socket] | None) -> None:
+    """Close sockets that were pre-bound for uvicorn."""
+
+    if sockets is None:
+        return
+    for sock in sockets:
+        try:
+            sock.close()
+        except OSError:
+            pass
+
+
+def prepare_server_launch(host: str, port: int) -> ServerLaunch:
+    """Validate bind options and resolve the actual browser URL."""
+
+    if not is_loopback_host(host):
+        raise typer.BadParameter(
+            "Loopback-only host required.",
+            param_hint="--host",
+        )
+    if port < 0 or port > 65535:
+        raise typer.BadParameter(
+            "Port must be between 0 and 65535.",
+            param_hint="--port",
+        )
+    if port == 0:
+        sock = _bind_socket(host)
+        actual_port = int(sock.getsockname()[1])
+        return ServerLaunch(
+            host=host,
+            requested_port=port,
+            port=actual_port,
+            url=build_app_url(host, actual_port),
+            sockets=[sock],
+        )
+    return ServerLaunch(
+        host=host,
+        requested_port=port,
+        port=port,
+        url=build_app_url(host, port),
+    )
+
+
+def _prompt_passphrase() -> str:
+    """Prompt for a passphrase without echoing it to the terminal."""
+
+    return str(typer.prompt("Passphrase", hide_input=True))
+
+
+def resolve_passphrase(
+    passphrase: str | None,
+    passphrase_prompt: bool,
+    prompt_func: Callable[[], str] = _prompt_passphrase,
+) -> str | None:
+    """Resolve passphrase options into the configured passphrase."""
+
+    if passphrase is not None and passphrase_prompt:
+        raise typer.BadParameter(
+            "Use either --passphrase or --passphrase-prompt, not both.",
+            param_hint="--passphrase",
+        )
+    resolved = prompt_func() if passphrase_prompt else passphrase
+    if resolved == "":
+        raise typer.BadParameter(
+            "Passphrase cannot be empty.",
+            param_hint="--passphrase",
+        )
+    return resolved
+
+
+def run_local_server(
+    *,
+    host: str,
+    port: int,
+    open_browser: bool,
+    passphrase: str | None,
+    passphrase_prompt: bool,
+    browser_open: Callable[[str], bool] = webbrowser.open,
+) -> None:
+    """Run the local FileClip server."""
+
+    resolved_passphrase = resolve_passphrase(passphrase, passphrase_prompt)
+    launch = prepare_server_launch(host, port)
+    asgi_app = create_app(LaunchConfig(passphrase=resolved_passphrase))
+    uvicorn_config = uvicorn.Config(
+        asgi_app,
+        host=launch.host,
+        port=launch.port,
+        access_log=False,
+        log_level="info",
+    )
+    server = uvicorn.Server(uvicorn_config)
+    try:
+        typer.echo(f"Serving FileClip at {launch.url}")
+        if open_browser:
+            browser_open(launch.url)
+        server.run(sockets=launch.sockets)
+    finally:
+        close_sockets(launch.sockets)
+
+
+@app.command()
+def root(
+    host: Annotated[
+        str,
+        typer.Option("--host", help="Loopback host to bind."),
+    ] = DEFAULT_HOST,
+    port: Annotated[
+        int,
+        typer.Option("--port", min=0, max=65535, help="Port to bind; 0 chooses one."),
+    ] = DEFAULT_PORT,
+    open_browser: Annotated[
+        bool,
+        typer.Option("--open/--no-open", help="Open the browser after launch."),
+    ] = True,
+    passphrase: Annotated[
+        str | None,
+        typer.Option("--passphrase", help="Enable encrypted mode with this passphrase."),
+    ] = None,
+    passphrase_prompt: Annotated[
+        bool,
+        typer.Option(
+            "--passphrase-prompt",
+            help="Prompt for a passphrase without echoing it.",
+        ),
+    ] = False,
+) -> None:
+    """Start the local FileClip browser app."""
+
+    run_local_server(
+        host=host,
+        port=port,
+        open_browser=open_browser,
+        passphrase=passphrase,
+        passphrase_prompt=passphrase_prompt,
+    )
+
+
+def main() -> None:
+    """Run the Typer application."""
+
+    app()

fileclip-0.1.0/src/fileclip/server.py

@@ -0,0 +1,88 @@
+"""FastAPI application factory for FileClip."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+
+from fileclip import __version__
+
+APP_NAME = "fileclip"
+SCHEMA_VERSION = 1
+PLAIN_MODE = "plain"
+ENCRYPTED_MODE = "encrypted"
+CONFIG_CACHE_CONTROL = "no-store"
+
+
+@dataclass(frozen=True)
+class LaunchConfig:
+    """Runtime configuration exposed to the browser app."""
+
+    passphrase: str | None = None
+    app_name: str = APP_NAME
+    schema: int = SCHEMA_VERSION
+    version: str = __version__
+
+    @property
+    def mode(self) -> str:
+        """Return the public launch mode."""
+
+        if self.passphrase is None:
+            return PLAIN_MODE
+        return ENCRYPTED_MODE
+
+    def as_public_config(self) -> dict[str, Any]:
+        """Return the JSON-safe browser launch configuration."""
+
+        config: dict[str, Any] = {
+            "app": self.app_name,
+            "version": self.version,
+            "schema": self.schema,
+            "mode": self.mode,
+        }
+        if self.passphrase is not None:
+            config["passphrase"] = self.passphrase
+        return config
+
+
+def static_dir() -> Path:
+    """Return the packaged static asset directory."""
+
+    return Path(__file__).with_name("static")
+
+
+def create_app(config: LaunchConfig | None = None) -> FastAPI:
+    """Create the local FileClip ASGI application."""
+
+    launch_config = config or LaunchConfig()
+    assets = static_dir()
+    app = FastAPI(
+        title="FileClip",
+        docs_url=None,
+        redoc_url=None,
+        openapi_url=None,
+    )
+    app.state.launch_config = launch_config
+
+    @app.get("/", include_in_schema=False)
+    def index() -> FileResponse:
+        """Serve the browser app shell."""
+
+        return FileResponse(assets / "index.html", media_type="text/html")
+
+    @app.get("/config.json", include_in_schema=False)
+    def config_json() -> JSONResponse:
+        """Serve launch configuration without allowing browser caching."""
+
+        return JSONResponse(
+            launch_config.as_public_config(),
+            headers={"Cache-Control": CONFIG_CACHE_CONTROL},
+        )
+
+    app.mount("/static", StaticFiles(directory=assets), name="static")
+    return app