botgate 0.1.0__py3-none-win_amd64.whl

botgate-0.1.0.dist-info/METADATA

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: botgate
+Version: 0.1.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Security
+Classifier: Topic :: Internet :: WWW/HTTP
+License-File: LICENSE-MIT
+Summary: Evidence-first Web Bot Auth conformance and coverage analyzer
+Keywords: web-bot-auth,http-signatures,rfc9421,security
+Home-Page: https://github.com/kraftaa/botgate
+License-Expression: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/kraftaa/botgate
+Project-URL: Issues, https://github.com/kraftaa/botgate/issues
+Project-URL: Repository, https://github.com/kraftaa/botgate
+
+# Botgate
+
+Botgate is an evidence-first conformance and coverage analyzer for Web Bot Auth and RFC 9421 HTTP Message Signatures.
+
+It answers four separate questions:
+
+1. Is the message shaped correctly for a selected protocol profile?
+2. Does the signature verify with an explicitly supplied key?
+3. Which request properties are cryptographically bound?
+4. Does that coverage satisfy the application's declared policy?
+
+Botgate deliberately does **not** infer authentication from an HTTP status code. A `200` response is not evidence that a server accepted a signature; the resource may simply be public.
+
+## Status
+
+This repository implements a focused v0.1:
+
+- current `draft-ietf-webbotauth-httpsig-protocol-00` inspection;
+- the current Cloudflare compatibility profile;
+- current dictionary-form and legacy string-form `Signature-Agent` handling;
+- RFC 9421 signature-base reconstruction for the common request components;
+- RFC 8941 canonicalization for selected Structured Field dictionary members;
+- Ed25519 signing and verification;
+- JWK thumbprint/key selection;
+- semantic coverage and configurable policy evaluation;
+- `Content-Digest` SHA-256 validation;
+- JSON output for CI;
+- a safe offline mutation matrix.
+
+It does not fetch untrusted key-directory URLs or send active mutations. Those operations require an SSRF-safe resolver and an explicit authentication oracle; pretending that response status alone is an oracle would produce misleading results.
+
+## Install
+
+You do not need Rust or Cargo to use Botgate.
+
+On macOS or Linux, install with Homebrew:
+
+```sh
+brew install kraftaa/tap/botgate
+```
+
+If you already use Python tooling, install the same native Botgate binary on
+macOS, Linux, or Windows with `pipx`:
+
+```sh
+pipx install botgate
+```
+
+Or with `uv`:
+
+```sh
+uv tool install botgate
+```
+
+Inside an existing Python virtual environment, ordinary pip works too:
+
+```sh
+python -m pip install botgate
+```
+
+These package-manager installs use prebuilt native binaries; they do not
+compile Botgate or install a Rust toolchain. Standalone archives, a Windows
+installer, a shell installer, and SHA-256 checksums are also available on the
+[Releases page](https://github.com/kraftaa/botgate/releases) as fallbacks.
+
+The download links become active when the first public release is published.
+Until then, authenticated repository collaborators can download private release
+assets with the GitHub CLI.
+
+Confirm the installation:
+
+```sh
+botgate --version
+botgate --help
+```
+
+## End-to-end example
+
+Generate a test key and policy:
+
+```sh
+botgate init
+```
+
+This creates:
+
+```text
+.botgate/
+├── private.key       # Ed25519 PKCS#8, mode 0600 on Unix
+├── public.jwk
+├── directory.json
+└── botgate.toml
+```
+
+The whole `.botgate/` directory is excluded by `.gitignore`. Botgate never prints the private key. A conformant remote key directory must be served over HTTPS.
+
+Running `botgate init --force` regenerates `public.jwk` and `directory.json` from the existing private key. It never overwrites `private.key` or an existing `botgate.toml`.
+
+On Unix, the private key is created atomically with mode `0600`. On Windows it is created with `create_new` but inherits the directory's ACL; restrict access to `.botgate/` yourself.
+
+Sign the example request using the current IETF form:
+
+```sh
+botgate sign examples/request.http \
+  --agent https://agent.example \
+  --components @authority,@method,@path,@query \
+  --output signed-request.http
+```
+
+Inspect declared coverage without loading a key:
+
+```sh
+botgate inspect signed-request.http \
+  --config examples/strict-policy.toml
+```
+
+Verify cryptographically using a local JWKS:
+
+```sh
+botgate verify signed-request.http \
+  --jwks .botgate/directory.json \
+  --config examples/strict-policy.toml
+```
+
+Show the offline mutation matrix:
+
+```sh
+botgate test signed-request.http \
+  --jwks .botgate/directory.json \
+  --config examples/strict-policy.toml
+```
+
+Nothing is sent by `test`. In particular, Botgate never turns a `GET` into a live `POST` or `DELETE` request.
+The matrix is generated independently for every signature in the request.
+
+## Cloudflare interoperability
+
+The September 2026 working-group draft requires new senders to emit dictionary-form `Signature-Agent`, keyed by the signature label:
+
+```http
+Signature-Agent: sig1="https://agent.example"
+Signature-Input: sig1=("@authority" "signature-agent";key="sig1");...
+```
+
+Cloudflare currently documents the older bare-string form. Generate and analyze that form explicitly:
+
+```sh
+botgate sign examples/request.http \
+  --agent https://agent.example \
+  --components @authority \
+  --legacy-agent \
+  --output cloudflare-request.http
+
+botgate inspect cloudflare-request.http --profile cloudflare
+botgate inspect cloudflare-request.http --profile ietf-draft-00
+```
+
+The second command reports why the same request is legacy rather than conformant for a new IETF-draft sender.
+
+## Policy
+
+Policy requirements are application requirements, not claims that every conforming Web Bot Auth signature must cover the same fields.
+Without `--config`, Botgate automatically loads `.botgate/botgate.toml` from the current directory when it exists; otherwise it uses the same built-in defaults produced by `init`. Every report names the policy it applied (`Policy:` in text, `policy_source` in JSON). In CI, pass `--config` explicitly so a change to `.botgate/` cannot silently alter the gate. Unknown keys and negative time limits are rejected.
+
+```toml
+[policy]
+require_authority = true
+require_method = true
+require_path = true
+query = "required"
+body = "ignore"
+max_age_seconds = 300
+max_lifetime_seconds = 300
+allowed_future_skew_seconds = 30
+require_nonce = false
+```
+
+Coverage is semantic rather than a flat string check. For example, `@target-uri` satisfies authority, path, and query coverage, while `@path` does not cover the query. Body integrity requires a covered `Content-Digest` (the whole field, or its `sha-256` member via `;key="sha-256"`) whose SHA-256 value matches the body bytes. Covering only another member, such as `sha-512`, does not count.
+Individual `@query-param` components are reported as partial evidence and do not satisfy a policy requiring the entire query to be bound. `@request-target` covers path and query for the raw HTTP/1.1 requests accepted by v0.1.
+
+## JSON and exit behavior
+
+Use `--format json` with `inspect`, `verify`, or `test`.
+
+```sh
+botgate inspect request.http --format json
+```
+
+Exit status is `0` when no error-level findings exist, `1` when conformance, compatibility, crypto, or policy findings fail, and `4` for input or configuration errors detected after argument parsing. Clap uses its conventional status `2` for command-line usage errors. JSON retains independent finding categories and cryptographic/identity states so CI does not need to infer meaning from prose.
+
+## Trust model
+
+Verification with `--jwks` establishes that the supplied key validates the signature. It intentionally reports identity as `key_only`: loading a local JWK does not prove that an HTTPS `Signature-Agent` URL published that key. URL attribution requires a safe HTTPS discovery operation and its cache state.
+
+The signing command derives the thumbprint from the private key and refuses to proceed if `--jwk` names a different key pair.
+
+Similarly, signing `Content-Digest` binds the digest header. Botgate separately recomputes the digest before reporting body integrity.
+
+## Supported signature components
+
+v0.1 reconstructs:
+
+- `@method`
+- `@authority`
+- `@scheme`
+- `@path`
+- `@query`
+- `@target-uri`
+- `@request-target`
+- `@query-param`;`name=...`
+- ordinary HTTP fields
+- dictionary field members selected with `;key=...`
+
+Unsupported derived components cause verification to fail explicitly rather than being guessed.
+Input files use a strict raw HTTP/1.0 or HTTP/1.1 request format; malformed control data, folded headers, and ambiguous authorities are rejected before analysis.
+
+## Non-goals
+
+Botgate does not impersonate commercial agents, bypass bot protection, solve CAPTCHAs, crawl sites, score “AI readiness,” or replace authorization and bot-management systems.
+
+## Development
+
+Rust and Cargo are required only when building Botgate from source or
+contributing to the project:
+
+```sh
+cargo build --release
+cargo fmt --check
+cargo clippy --all-targets -- -D warnings
+cargo test
+cargo deny check
+```
+
+The minimum supported Rust version is 1.86. CI runs the test suite on Linux, macOS, and Windows.
+
+`cargo test` includes property tests for the HTTP and Structured Fields parsers. Coverage-guided fuzz targets live in `fuzz/` and need a nightly toolchain and [`cargo-fuzz`](https://github.com/rust-fuzz/cargo-fuzz):
+
+```sh
+cargo install cargo-fuzz
+cargo +nightly fuzz run parse_request
+cargo +nightly fuzz run parse_signatures
+cargo +nightly fuzz run signature_base
+```
+
+See [SECURITY.md](SECURITY.md) for the trust model and how to report vulnerabilities.
+Maintainer release setup is documented in [RELEASING.md](RELEASING.md).
+
+The protocol is still an Internet-Draft. Profile-specific behavior is kept separate in the report engine, and `botgate protocol` identifies the implemented draft.
+
+## References
+
+- [Web Bot Auth working-group draft 00](https://datatracker.ietf.org/doc/html/draft-ietf-webbotauth-httpsig-protocol-00)
+- [RFC 9421: HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421.html)
+- [Cloudflare Web Bot Auth documentation](https://developers.cloudflare.com/bots/reference/bot-verification/web-bot-auth/)
+

botgate-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+botgate-0.1.0.data\scripts\botgate.exe,sha256=QtfXmQY8RPk1US7FG_QQF-x8I8svcXQdfGnvxs5XSzY,2099712
+botgate-0.1.0.dist-info\METADATA,sha256=g98PpOgiN_fKTkLtaFB_entH7yOq7MMc-WzQfN-Gitc,10570
+botgate-0.1.0.dist-info\WHEEL,sha256=jsSEiVNsW1dJj5gDaReR40i7mhgBjWtms6nAD6EViXU,94
+botgate-0.1.0.dist-info\licenses\LICENSE-MIT,sha256=94n4rBNhaAsDzk3LlfShpE9TJvQiSIdCO30ZdGPTmU8,1102
+botgate-0.1.0.dist-info\RECORD,,

botgate-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.11.5)
+Root-Is-Purelib: false
+Tag: py3-none-win_amd64

botgate-0.1.0.dist-info/licenses/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The botgate contributors
+
+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.