Metadata-Version: 2.4
Name: xferry
Version: 0.4.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.4.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.

These commands require **xferry 0.3.2 or newer**. Existing `0.2.x` installations
use the [migration guide](docs/migration.md); [v0.2.0 instructions](docs/archive/0.2.0-installation.md)
remain archived. Obtain matching native/container artifacts from the
[versioned release](https://github.com/kgmnotes/xferry/releases/tag/v0.3.2).
Contributors can use a [source checkout](CONTRIBUTING.md).

## Start here

Install the CLI on the host where the server will run:

```console
pipx install xferry
xferry
```

The menu offers a foreground run, server setup, and configuration. For a quick
foreground run on <http://127.0.0.1:8080>:

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

For a persistent Linux service or Docker deployment:

```console
xferry setup
```

Setup checks prerequisites, asks for access and a files folder, starts the
server, and prints its URL. Public access configures HTTPS and generates a
12-character Basic Auth password. You can use a domain or an automatic address.
See the [quick start](docs/quick-start.md) for requirements and examples.

## 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.

## 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 `--config FILE` to select another 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.

## 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
