Metadata-Version: 2.4
Name: xferry
Version: 0.5.0
Summary: Controlled HTTP toolkit for Secure Web Gateway testing
License-Expression: MIT
Project-URL: Repository, https://github.com/kgmnotes/xferry
Project-URL: Issues, https://github.com/kgmnotes/xferry/issues
Keywords: http,server,tls,https,security-research,authorized-testing,controlled-testing,http-testing,secure-web-gateway,swg,file-upload,file-server,advanced-upload,custom-methods
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Information Technology
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: acme<6,>=5.5
Requires-Dist: cryptography>=50.0
Requires-Dist: defusedxml==0.7.1
Requires-Dist: josepy<3,>=2.2
Provides-Extra: dev
Requires-Dist: build>=1.3; extra == "dev"
Requires-Dist: pytest>=9.0; extra == "dev"
Requires-Dist: pytest-cov>=6.0; extra == "dev"
Requires-Dist: hypothesis>=6.0; extra == "dev"
Requires-Dist: pre-commit>=4.6.0; python_version >= "3.11" and extra == "dev"
Requires-Dist: setuptools>=75.0; extra == "dev"
Requires-Dist: wheel>=0.45; extra == "dev"
Provides-Extra: lint
Requires-Dist: ruff>=0.15.5; extra == "lint"
Requires-Dist: mypy>=1.20.1; extra == "lint"
Provides-Extra: test
Requires-Dist: hypothesis>=6.0; extra == "test"
Requires-Dist: pytest-benchmark>=5.0; extra == "test"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Provides-Extra: all
Requires-Dist: xferry[dev,docs,lint,test]; extra == "all"
Dynamic: license-file

# xferry

[![CI](https://github.com/kgmnotes/xferry/actions/workflows/ci.yml/badge.svg)](https://github.com/kgmnotes/xferry/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/Python-3.10--3.14-blue.svg)](https://www.python.org/)
![Source version](https://img.shields.io/badge/version-0.5.0-orange.svg)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

xferry is an HTTP toolkit for testing Secure Web Gateways on systems you are
authorized to test. Its web UI provides **Upload**, **Download**, **Requests**,
**Advanced**, and **Notepad** tabs.

This checkout documents the **unpublished 0.5.0 candidate**. The commands below
apply to that version; published older packages use their own release documentation.
To try the candidate before publication, use a [source checkout](CONTRIBUTING.md).

## Choose a way to run

Install the CLI on the machine where files will be served:

```console
pipx install xferry
```

**Run once** as a portable foreground process on your computer. Open the printed
URL and stop with `Ctrl+C`:

```console
xferry run --open
```

Choose another shared folder explicitly:

```console
xferry run --files-dir ~/Shared --open
```

**Persistent Linux service** on a [supported host](docs/managed-hosts.md) or VPS:

```console
xferry setup --backend native --files-dir /srv/share
```

**Container** on a host with Docker Engine and its Compose plugin:

```console
xferry setup --backend docker --files-dir /srv/share
```

Setup previews the installation, checks the selected folder, starts the server,
and prints its deployment ID, URL and generated Basic Auth password. Public
setup uses browser-trusted TLS on port **443**. Choose an automatic address or
your own domain; inbound TCP 80 must also be reachable for certificates.

Run `xferry` for an interactive menu. The menu distinguishes running, stopped,
incomplete and retained installations, and offers the matching next action.
See the [quick start](docs/quick-start.md) for all three journeys, a first transfer
and removal. A [source checkout](CONTRIBUTING.md) and manual Compose are operator
workflows. Existing deployments must follow the [upgrade notes](docs/migration.md);
the current interface does not convert legacy configuration or deployment state.

## Choose where files live

```console
xferry run --files-dir /srv/share
xferry run --files-dir .
```

The selected directory is used directly: existing files can be downloaded, new
uploads are saved there, and deletion actions affect its contents. With no
folder specified, foreground runs use your user data directory; a new Linux
service uses `/var/lib/xferry/files`. These defaults do not depend on the current
directory. Notes, passwords and certificate state are kept separately. Use a separate
shared folder for each persistent instance.

## Change settings and manage the server

```console
xferry config
xferry config explain files_dir
xferry status
xferry logs
xferry stop
xferry start
```

Configuration changes automatically apply to a running installed server. A
stopped server stays stopped. Use `--instance ID` to select a persistent
deployment, or `config --config FILE` for a foreground profile.
[All settings](docs/settings.md) includes defaults, units and examples;
`xferry --help` shows common commands and `xferry run --help-all` shows all launch
options.

`xferry uninstall` removes the selected runtime and retains configuration,
credentials, private state and the shared folder for reinstall. `xferry uninstall
--purge --yes` removes resources recorded as owned by xferry; the shared folder
and its files remain, including the default files folder. Both commands print
the resources they retain. Purge requires an explicit confirmation; declining
the prompt cancels it, and scripts must pass `--yes`.
The separately installed pipx CLI is removed with `pipx uninstall xferry`.

## Try a transfer

```bash
printf 'authorized test\n' > sample.txt
curl --fail-with-body -H 'X-File-Name: sample.txt' \
  --data-binary @sample.txt http://127.0.0.1:8080/uploads
curl --fail-with-body http://127.0.0.1:8080/uploads/sample.txt
```

For authenticated HTTPS, add `--user USER` and use the URL printed by setup.

- [Common scenarios](docs/scenarios.md): methods, files, notes and transport artifacts
- [API reference](API.md): Advanced Sessions, custom HTTP methods such as `SYNCDATA`, and payload protection (`none`, XOR, AES-256-GCM)
- [Operations](docs/operations.md), [public deployment](docs/public-direct.md), [managed hosts](docs/managed-hosts.md)
- [CLI reference](docs/cli-reference.md), [migration](docs/migration.md), [security](SECURITY.md)

Documentation: <https://xferry.kgmnotes.ru/> · License: MIT
