sharedserver 0.1.0__tar.gz

sharedserver-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Kyi Wong
+
+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.
+

sharedserver-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include sharedserver.example.yaml
+

sharedserver-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: sharedserver
+Version: 0.1.0
+Summary: Zero-configuration LAN file sharing and real-time text clipboard
+Author: Kyi Wong
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/NihaoKangkang/sharedserver
+Project-URL: Repository, https://github.com/NihaoKangkang/sharedserver
+Project-URL: Issues, https://github.com/NihaoKangkang/sharedserver/issues
+Keywords: file-sharing,clipboard,lan,fastapi,websocket
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: PyYAML<7,>=6
+Requires-Dist: uvicorn<1,>=0.30
+Requires-Dist: websockets<17,>=13
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == "dev"
+Requires-Dist: httpx2<3,>=2; extra == "dev"
+Requires-Dist: pytest<9,>=8; extra == "dev"
+Requires-Dist: twine<7,>=5; extra == "dev"
+Dynamic: license-file
+
+# SharedServer
+
+SharedServer is a zero-configuration, login-free LAN file server and real-time text clipboard. It is as easy to start as `python -m http.server`, while adding uploads, directory browsing, live text synchronization, and allowlisted clipboard actions.
+
+> SharedServer has no authentication. Run it only on a trusted home, lab, or development network. Never expose it directly to the public internet.
+
+## Features
+
+- A shared text clipboard synchronized between all open pages over WebSocket
+- A responsive file browser with directory navigation, file sizes, and modification times
+- File uploads from desktop and mobile browsers with live progress
+- Folder creation and safe, non-overwriting uploads
+- Copy actions for allowlisted text and image formats
+- Download-only behavior for other formats such as ZIP, RAR, 7z, EXE, APK, and ISO
+- Protection against path traversal, directory escape, symlink escape, and unsafe filenames
+- No accounts, database, device discovery, template engine, or frontend framework
+
+## Requirements
+
+- Python 3.10 or newer
+- A modern desktop or mobile browser
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install sharedserver
+```
+
+Install from source:
+
+```bash
+git clone https://github.com/NihaoKangkang/sharedserver.git
+cd sharedserver
+pip install .
+```
+
+## Quick start
+
+Run this command from the directory you want to share:
+
+```bash
+python -m sharedserver 8080
+```
+
+
+## CLI reference
+
+```text
+usage: sharedserver [-h] [--host HOST] [-d DIRECTORY] [-c CONFIG]
+                    [--max-upload-size MB] [--version]
+                    [port]
+```
+
+| Argument | Description |
+| --- | --- |
+| `port` | Listening port. Uses the configuration value or `8000` by default. |
+| `--host HOST` | Bind address. Defaults to `0.0.0.0`. |
+| `-d, --directory PATH` | Directory to share. Defaults to the current directory. |
+| `-c, --config PATH` | YAML configuration file. |
+| `--max-upload-size MB` | Maximum upload size in MiB. Defaults to 1024 MiB. |
+| `--version` | Print the installed version. |
+
+CLI arguments override configuration file values. Without `--config`, SharedServer automatically loads `sharedserver.yaml` from the current directory when it exists.
+
+## Configuration
+
+Copy `sharedserver.example.yaml` to `sharedserver.yaml` and edit it as needed:
+
+```yaml
+server:
+  host: 0.0.0.0
+  port: 8080
+
+share:
+  directory: ./
+  max_upload_size: 1073741824
+
+clipboard:
+  max_text_size: 2097152
+  text_extensions:
+    - .txt
+    - .md
+  image_extensions:
+    - .png
+    - .jpg
+```
+
+Relative shared directory paths are resolved from the configuration file's directory. Custom extension lists replace the defaults, and matching is case-insensitive.
+
+Default text extensions:
+
+```text
+.txt .md .json .xml .yaml .yml .csv .log .py .js .html .css .java .c .cpp
+```
+
+Default image extensions:
+
+```text
+.png .jpg .jpeg .webp
+```
+
+## Security model
+
+- Every user-supplied path is resolved with `Path.resolve()` and checked against the shared root.
+- Absolute paths and `..` path segments are rejected.
+- Symlinks are hidden from directory listings and rejected by file operations.
+- Upload filenames are stripped of path components, control characters, and unsafe cross-platform characters.
+- Uploads are written to a temporary file and published without overwriting an existing file.
+- Both `Content-Length` validation and streamed byte counting enforce the upload limit.
+- Clipboard actions and server read endpoints use the same strict extension allowlists.
+- Browser WebSocket connections from a different origin are rejected.
+- Shared text exists only in process memory and is cleared when the server stops.
+
+SharedServer intentionally has no login or authorization layer. Every device that can reach the server can read and write the shared directory and shared text.
+
+## Development
+
+Clone the project and create a virtual environment:
+
+```bash
+git clone https://github.com/NihaoKangkang/sharedserver.git
+cd sharedserver
+python -m venv .venv
+```
+
+Activate the environment, then install development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Start a development server:
+
+```bash
+python -m sharedserver 8080 --directory .
+```
+
+
+## License
+
+[MIT](LICENSE)

sharedserver-0.1.0/README.md

@@ -0,0 +1,143 @@
+# SharedServer
+
+SharedServer is a zero-configuration, login-free LAN file server and real-time text clipboard. It is as easy to start as `python -m http.server`, while adding uploads, directory browsing, live text synchronization, and allowlisted clipboard actions.
+
+> SharedServer has no authentication. Run it only on a trusted home, lab, or development network. Never expose it directly to the public internet.
+
+## Features
+
+- A shared text clipboard synchronized between all open pages over WebSocket
+- A responsive file browser with directory navigation, file sizes, and modification times
+- File uploads from desktop and mobile browsers with live progress
+- Folder creation and safe, non-overwriting uploads
+- Copy actions for allowlisted text and image formats
+- Download-only behavior for other formats such as ZIP, RAR, 7z, EXE, APK, and ISO
+- Protection against path traversal, directory escape, symlink escape, and unsafe filenames
+- No accounts, database, device discovery, template engine, or frontend framework
+
+## Requirements
+
+- Python 3.10 or newer
+- A modern desktop or mobile browser
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install sharedserver
+```
+
+Install from source:
+
+```bash
+git clone https://github.com/NihaoKangkang/sharedserver.git
+cd sharedserver
+pip install .
+```
+
+## Quick start
+
+Run this command from the directory you want to share:
+
+```bash
+python -m sharedserver 8080
+```
+
+
+## CLI reference
+
+```text
+usage: sharedserver [-h] [--host HOST] [-d DIRECTORY] [-c CONFIG]
+                    [--max-upload-size MB] [--version]
+                    [port]
+```
+
+| Argument | Description |
+| --- | --- |
+| `port` | Listening port. Uses the configuration value or `8000` by default. |
+| `--host HOST` | Bind address. Defaults to `0.0.0.0`. |
+| `-d, --directory PATH` | Directory to share. Defaults to the current directory. |
+| `-c, --config PATH` | YAML configuration file. |
+| `--max-upload-size MB` | Maximum upload size in MiB. Defaults to 1024 MiB. |
+| `--version` | Print the installed version. |
+
+CLI arguments override configuration file values. Without `--config`, SharedServer automatically loads `sharedserver.yaml` from the current directory when it exists.
+
+## Configuration
+
+Copy `sharedserver.example.yaml` to `sharedserver.yaml` and edit it as needed:
+
+```yaml
+server:
+  host: 0.0.0.0
+  port: 8080
+
+share:
+  directory: ./
+  max_upload_size: 1073741824
+
+clipboard:
+  max_text_size: 2097152
+  text_extensions:
+    - .txt
+    - .md
+  image_extensions:
+    - .png
+    - .jpg
+```
+
+Relative shared directory paths are resolved from the configuration file's directory. Custom extension lists replace the defaults, and matching is case-insensitive.
+
+Default text extensions:
+
+```text
+.txt .md .json .xml .yaml .yml .csv .log .py .js .html .css .java .c .cpp
+```
+
+Default image extensions:
+
+```text
+.png .jpg .jpeg .webp
+```
+
+## Security model
+
+- Every user-supplied path is resolved with `Path.resolve()` and checked against the shared root.
+- Absolute paths and `..` path segments are rejected.
+- Symlinks are hidden from directory listings and rejected by file operations.
+- Upload filenames are stripped of path components, control characters, and unsafe cross-platform characters.
+- Uploads are written to a temporary file and published without overwriting an existing file.
+- Both `Content-Length` validation and streamed byte counting enforce the upload limit.
+- Clipboard actions and server read endpoints use the same strict extension allowlists.
+- Browser WebSocket connections from a different origin are rejected.
+- Shared text exists only in process memory and is cleared when the server stops.
+
+SharedServer intentionally has no login or authorization layer. Every device that can reach the server can read and write the shared directory and shared text.
+
+## Development
+
+Clone the project and create a virtual environment:
+
+```bash
+git clone https://github.com/NihaoKangkang/sharedserver.git
+cd sharedserver
+python -m venv .venv
+```
+
+Activate the environment, then install development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Start a development server:
+
+```bash
+python -m sharedserver 8080 --directory .
+```
+
+
+## License
+
+[MIT](LICENSE)

sharedserver-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sharedserver"
+version = "0.1.0"
+description = "Zero-configuration LAN file sharing and real-time text clipboard"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kyi Wong" }]
+keywords = ["file-sharing", "clipboard", "lan", "fastapi", "websocket"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Web Environment",
+  "Framework :: FastAPI",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+]
+dependencies = [
+  "fastapi>=0.115,<1",
+  "PyYAML>=6,<7",
+  "uvicorn>=0.30,<1",
+  "websockets>=13,<17",
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2,<2",
+  "httpx2>=2,<3",
+  "pytest>=8,<9",
+  "twine>=5,<7",
+]
+
+[project.scripts]
+sharedserver = "sharedserver.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/NihaoKangkang/sharedserver"
+Repository = "https://github.com/NihaoKangkang/sharedserver"
+Issues = "https://github.com/NihaoKangkang/sharedserver/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+sharedserver = ["templates/*.html", "static/*.css", "static/*.js"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

sharedserver-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sharedserver-0.1.0/sharedserver.example.yaml

@@ -0,0 +1,32 @@
+server:
+  host: 0.0.0.0
+  port: 8080
+
+share:
+  directory: ./
+  max_upload_size: 1073741824  # bytes, default 1 GiB
+
+clipboard:
+  max_text_size: 2097152       # bytes, default 2 MiB
+  text_extensions:
+    - .txt
+    - .md
+    - .json
+    - .xml
+    - .yaml
+    - .yml
+    - .csv
+    - .log
+    - .py
+    - .js
+    - .html
+    - .css
+    - .java
+    - .c
+    - .cpp
+  image_extensions:
+    - .png
+    - .jpg
+    - .jpeg
+    - .webp
+

sharedserver-0.1.0/src/sharedserver/__init__.py

@@ -0,0 +1,4 @@
+"""SharedServer package."""
+
+__version__ = "0.1.0"
+

sharedserver-0.1.0/src/sharedserver/__main__.py

@@ -0,0 +1,6 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()
+

sharedserver-0.1.0/src/sharedserver/cli.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import argparse
+import copy
+import socket
+from pathlib import Path
+from typing import Sequence
+
+import uvicorn
+
+from . import __version__
+from .config import load_config
+from .server import create_app
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="sharedserver",
+        description="LAN file sharing and real-time text clipboard",
+    )
+    parser.add_argument("port", nargs="?", type=int, help="port to listen on")
+    parser.add_argument("--host", help="host to bind (default: 0.0.0.0)")
+    parser.add_argument("-d", "--directory", type=Path, help="directory to share")
+    parser.add_argument("-c", "--config", type=Path, help="YAML configuration file")
+    parser.add_argument(
+        "--max-upload-size",
+        type=int,
+        metavar="MB",
+        help="maximum upload size in MiB",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return parser
+
+
+def get_lan_ip() -> str:
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        sock.connect(("8.8.8.8", 80))
+        return str(sock.getsockname()[0])
+    except OSError:
+        try:
+            return socket.gethostbyname(socket.gethostname())
+        except OSError:
+            return "127.0.0.1"
+    finally:
+        sock.close()
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        config = load_config(args.config).with_cli_overrides(
+            host=args.host,
+            port=args.port,
+            directory=args.directory.expanduser().resolve() if args.directory else None,
+            max_upload_size=(
+                args.max_upload_size * 1024 * 1024
+                if args.max_upload_size is not None
+                else None
+            ),
+        )
+        app = create_app(config)
+    except (FileNotFoundError, NotADirectoryError, ValueError) as exc:
+        parser.error(str(exc))
+
+    port = config.server.port
+    print(
+        "SharedServer running:\n\n"
+        f"Local:\nhttp://127.0.0.1:{port}\n\n"
+        f"LAN:\nhttp://{get_lan_ip()}:{port}\n\n"
+        f"Sharing: {config.share.directory}\n"
+    )
+    log_config = copy.deepcopy(uvicorn.config.LOGGING_CONFIG)
+    log_config["loggers"]["uvicorn.error"]["level"] = "WARNING"
+    uvicorn.run(app, host=config.server.host, port=port, log_config=log_config)

sharedserver-0.1.0/src/sharedserver/clipboard.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from .config import ClipboardConfig
+
+CopyKind = Literal["text", "image"]
+
+
+class ClipboardPolicy:
+    def __init__(self, config: ClipboardConfig):
+        self.text_extensions = frozenset(config.text_extensions)
+        self.image_extensions = frozenset(config.image_extensions)
+        self.max_text_size = config.max_text_size
+
+    def copy_kind(self, path: Path) -> CopyKind | None:
+        suffix = path.suffix.lower()
+        if suffix in self.text_extensions:
+            return "text"
+        if suffix in self.image_extensions:
+            return "image"
+        return None
+
+    def read_text(self, path: Path) -> str:
+        if self.copy_kind(path) != "text":
+            raise ValueError("file type is not allowed for text copying")
+        with path.open("rb") as source:
+            content = source.read(self.max_text_size + 1)
+        if len(content) > self.max_text_size:
+            raise ValueError("text file is too large to copy")
+        return content.decode("utf-8-sig", errors="replace")