torquests 1.0.0__tar.gz

torquests-1.0.0/.github/CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# Contributing
+
+Thanks for your interest in `torquests`. This document covers the development
+setup and the conventions the project holds to.
+
+## Development setup
+
+The project uses [uv](https://docs.astral.sh/uv/) for environments and
+[ruff](https://docs.astral.sh/ruff/) + [mypy](https://mypy-lang.org/) + pytest for
+quality gates.
+
+```bash
+git clone https://github.com/SafwanLjd/torquests
+cd torquests
+uv venv
+uv pip install -e ".[dev]"
+pre-commit install
+```
+
+Everyday commands run the tools installed above through `uv run`:
+
+```bash
+# lint, type-check, and test -- exactly what CI runs
+uv run ruff check src tests
+uv run ruff format --check src tests
+uv run mypy src
+uv run pytest
+
+# auto-fix lint and format in place
+uv run ruff check --fix src tests && uv run ruff format src tests
+
+# live-network suite (needs a reachable Tor network)
+uv run pytest --run-integration -m integration
+```
+
+## Test-driven, offline-first
+
+This is a network library, so its tests must not touch the network. The unit suite
+runs with sockets disabled (`--disable-socket`); a layer that seems to need the
+network to test needs a fake transport instead. The `FakeRelayTransport` in the test
+suite performs the link handshake and the server halves of the ntor and hs-ntor
+handshakes in process, so circuits, streams, the directory system, and the onion
+rendezvous flow are all exercised without a live relay.
+
+Protocol code is validated against gold vectors and generated fixtures, not
+against a running Tor: the official hs-ntor test vectors live in
+`tests/vectors/hs_ntor.json`, the ed25519 key-blinding regression vector is
+inline in `tests/test_ed25519_blind.py`, and the consensus/descriptor fixtures
+are generated by `tests/dir_fixtures.py` and `tests/onion_fixtures.py`.
+
+Write the failing test first, then the smallest code that passes it, then refactor.
+Do not open a pull request on a red build.
+
+Live-network checks are marked `@pytest.mark.integration` and are skipped unless you
+pass `--run-integration` (`uv run pytest --run-integration -m integration`). They need
+a reachable Tor network.
+
+## Style and scope
+
+- Target Python 3.10+ and modern typing. Every public function is typed and
+  documented.
+- Match the surrounding code. `ruff` and `mypy --strict` are authoritative; if they
+  pass and the tests pass, the style is right.
+- Errors fail loud: no bare `except`, no fabricated fallbacks, no silently-truncated
+  results. Tor-specific errors subclass the matching `requests` exception.
+- Verify protocol details against the Tor specifications and library behavior
+  against the library's own documentation. Cite the source in the code or the pull
+  request when the detail is non-obvious.
+
+## Commits and pull requests
+
+Keep commits small and focused. Subjects follow
+[Conventional Commits](https://www.conventionalcommits.org): a
+`type(scope): summary` line in the imperative mood, where `type` is one of `feat`,
+`fix`, `docs`, `test`, `refactor`, `perf`, `build`, `ci`, or `chore`. History reads
+as an intentional story, so squash fixups before opening a pull request.
+
+Run `pre-commit install` once (see the setup above). On every commit the hooks run
+`ruff` (lint and format) and a set of file-hygiene checks (trailing whitespace,
+end-of-file, YAML and TOML validity, large files); a Conventional Commits check runs
+on the commit message. Describe what changed and why in the pull
+request, and note the specification section or vector a protocol change rests on. CI
+runs lint, type-check, and the offline suite across Python 3.10 to 3.14, and all must
+pass.
+
+## Reporting security issues
+
+Because this library is used for privacy, please report suspected anonymity or
+cryptographic defects through a private GitHub Security Advisory (see
+[SECURITY.md](SECURITY.md)) rather than a public issue, so a fix can land before the
+details are public.

torquests-1.0.0/.github/SECURITY.md

@@ -0,0 +1,61 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Report suspected vulnerabilities privately. Do not open a public issue for a
+security problem, and do not disclose the details publicly until a fix has shipped.
+
+Report through **GitHub Security Advisories**: open a draft advisory at
+https://github.com/SafwanLjd/torquests/security/advisories/new.
+
+Please include the affected version, a description of the issue, and, where you can,
+a minimal reproduction. This project treats anonymity and cryptographic defects as
+security issues, not ordinary bugs, so report those through the same private channels.
+
+Expect an acknowledgement within a few days. We will keep you informed while a fix
+is prepared and will credit you in the advisory unless you ask otherwise. We welcome
+good-faith research and will not pursue reporters who follow this policy.
+
+## Supported versions
+
+Only the latest published release receives security fixes. There are no long-term
+support branches.
+
+| Version | Supported |
+| ------- | --------- |
+| Latest release | Yes |
+| Everything older | No |
+
+## Anonymity limitations
+
+torquests anonymizes the **transport**, not the application layer. It routes your
+connection through Tor circuits and reaches v3 onion services directly, but it does
+nothing to make the traffic it carries look like a browser's.
+
+Understand these limits before relying on the library for anonymity:
+
+- **The client is fingerprintable as non-browser Python.** torquests uses the
+  standard library `ssl` module for TLS and `http.client` for HTTP/1.1. Neither can
+  reproduce Tor Browser's TLS ClientHello (the cipher, extension, and curve ordering
+  that JA3/JA4 hash) or its HTTP/2 frame and header behaviour. A destination server
+  or a malicious exit relay can therefore fingerprint the client as a Python Tor
+  client rather than Tor Browser, and can distinguish it from the Tor Browser crowd.
+- **No application-layer or browser fingerprinting defenses.** The library does not
+  address JavaScript execution, canvas or font fingerprinting, cookies, referrers,
+  redirect chains, or any of the browser-level signals that deanonymize users. What
+  your code sends in headers, request timing, and payloads is your responsibility.
+- **No traffic-analysis or timing-correlation protection beyond what Tor circuits
+  provide.** A global adversary able to observe both ends of a circuit is outside the
+  threat model, as it is for Tor generally.
+- **Entry guards are not persisted.** To leave no on-disk trace, the client draws a
+  fresh guard set each process rather than pinning guards across runs as Tor does, which
+  trades reduced forensic residue for more entry-guard exposure over time.
+- **No warranty.** Do not use it where a deanonymization would put someone at risk
+  without independent review.
+
+To blend into the Tor Browser user base on the wire, enable **stealth mode** (the
+`torquests[stealth]` extra), which routes through curl_cffi to present a real Tor
+Browser TLS ClientHello and HTTP/2 fingerprint over Tor. For the full browser
+threat model (JavaScript, canvas and font fingerprinting, and the rest), use
+[Tor Browser](https://www.torproject.org/download/) itself. torquests is built for
+programmatic access to Tor and onion services from Python.