spillgate 0.1.0__tar.gz

spillgate-0.1.0/.gitattributes

@@ -0,0 +1,10 @@
+# Text is LF everywhere so hashes and golden files are identical on every OS.
+* text=auto eol=lf
+
+# Conformance vectors are byte-exact; never normalize them.
+conformance/vectors/** -text
+*.gz -text
+*.zz -text
+*.br -text
+*.zst -text
+*.bin -text

spillgate-0.1.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @FelixMiddelhoff

spillgate-0.1.0/.github/dependabot.yml

@@ -0,0 +1,8 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule: { interval: weekly }
+  - package-ecosystem: pip
+    directory: /
+    schedule: { interval: weekly }

spillgate-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,72 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.11", "3.12", "3.13", "3.14"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with: { persist-credentials: false }
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with: { python-version: "${{ matrix.python }}" }
+      - run: python -m pip install pytest hypothesis "brotli>=1.2.1,<2" "zstandard>=0.25.0,<1"
+      - name: tests (all 354 conformance vectors with brotli and zstd, properties, traps)
+        run: python -m pytest
+        env:
+          SPILLGATE_NO_SKIPS: "1"  # a missing codec fails the run instead of skipping vectors
+  core-only:
+    # The core must work and test cleanly without any optional dependency.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with: { persist-credentials: false }
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with: { python-version: "3.11" }
+      - run: python -m pip install pytest hypothesis
+      - run: python -m pytest -m "not large"
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with: { persist-credentials: false }
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with: { python-version: "3.13" }
+      - run: python -m pip install pip-audit "brotli>=1.2.1,<2" "zstandard>=0.25.0,<1"
+      - name: known vulnerabilities in the optional dependencies
+        run: python -m pip_audit
+
+  static:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with: { persist-credentials: false }
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with: { python-version: "3.13" }
+      - run: python -m pip install ruff mypy pytest hypothesis build brotli zstandard
+      - run: python -m ruff check .
+      - run: python -m ruff format --check .
+      - run: python -m mypy
+      - name: every rule of the specification is covered
+        run: python tools/spectrace.py
+      - name: the package builds and installs into a clean environment
+        run: |
+          python -m build
+          python -m venv /tmp/clean
+          /tmp/clean/bin/python -m pip install dist/*.whl
+          /tmp/clean/bin/python -I -c "import spillgate; print(spillgate.Limits(max_output=1))"

spillgate-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,25 @@
+name: codeql
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "41 3 * * 1"
+
+permissions:
+  contents: read
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with: { persist-credentials: false }
+      - uses: github/codeql-action/init@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3
+        with: { languages: python, build-mode: none }
+      - uses: github/codeql-action/analyze@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3

spillgate-0.1.0/.github/workflows/nightly-fuzz.yml

@@ -0,0 +1,25 @@
+name: nightly-fuzz
+
+# Property tests with a much larger example budget than the pull-request run.
+on:
+  schedule:
+    - cron: "27 2 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  hypothesis:
+    runs-on: ubuntu-latest
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with: { persist-credentials: false }
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with: { python-version: "3.13" }
+      - run: python -m pip install pytest hypothesis
+      - name: properties with a large budget
+        run: python -m pytest tests/test_properties.py
+        env:
+          SPILLGATE_HYPOTHESIS_EXAMPLES: "200000"

spillgate-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,61 @@
+name: release
+
+# Publishes to PyPI with Trusted Publishing (OpenID Connect): no API token is stored anywhere.
+# It runs only for a tag like v0.1.0 that the maintainer pushes, builds exactly once, checks
+# that the tag equals the package version, tests the built wheel in a clean environment and
+# then publishes the same files from a protected environment.
+on:
+  push:
+    tags: ["v[0-9]+.[0-9]+.[0-9]+"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with: { persist-credentials: false }
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with: { python-version: "3.13" }
+      - run: python -m pip install build twine pytest hypothesis "brotli>=1.2.1,<2" "zstandard>=0.25.0,<1"
+      - name: the tag must equal the package version
+        run: |
+          version=$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          test "v$version" = "$GITHUB_REF_NAME" || { echo "tag $GITHUB_REF_NAME != version $version"; exit 1; }
+      - name: the full suite passes, nothing skipped
+        run: python -m pytest
+        env:
+          SPILLGATE_NO_SKIPS: "1"
+      - run: python -m build
+      - run: python -m twine check --strict dist/*
+      - name: the wheel works in a clean environment
+        run: |
+          python -m venv /tmp/clean
+          /tmp/clean/bin/python -m pip install dist/*.whl
+          /tmp/clean/bin/python -I -c "import spillgate; print(spillgate.Limits(max_output=1))"
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # The environment "pypi" is created in the repository settings and requires the maintainer's
+    # approval before this job runs. The PyPI project trusts exactly this workflow and
+    # environment (see RELEASING.md).
+    environment:
+      name: pypi
+      url: https://pypi.org/p/spillgate
+    permissions:
+      id-token: write # the only permission that lets this job publish
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
+        # Attestations (build provenance) are produced by default and uploaded with the files.

spillgate-0.1.0/.github/workflows/scorecard.yml

@@ -0,0 +1,27 @@
+name: scorecard
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "23 4 * * 2"
+
+permissions: read-all
+
+jobs:
+  analysis:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with: { persist-credentials: false }
+      - uses: ossf/scorecard-action@fa7117db83c52d787ae5a89f350999701505d78e # v2.5.0
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+      - uses: github/codeql-action/upload-sarif@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3
+        with: { sarif_file: results.sarif }

spillgate-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+dist/
+build/
+*.egg-info/
+.venv/

spillgate-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+Versions below 1.0 may still change the API.
+
+## 0.1.0 - 2026-11-11
+
+First version. The Python implementation of the spillgate specification.
+
+- `Limits` with a required `max_output`, ratio, layer, input limits; typed, sticky errors (one exception class per outcome kind).
+- gzip, deflate and identity in the standard-library-only core; own gzip and zlib framing over `zlib.decompressobj` with `max_length` always greater than zero.
+- Optional extras `spillgate[brotli]` (brotli >= 1.2.1) and `spillgate[zstd]` (zstandard >= 0.25.0) with window caps and bounded steps.
+- Passes the full conformance corpus (354 vectors) of the reference implementation.
+- Integration guide in `docs/how-to.md`.

spillgate-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contributing
+
+## Run the checks
+
+```
+python -m pip install pytest hypothesis ruff mypy
+python -m pytest                    # everything, including the large generated vectors (about 40 s)
+python -m pytest -m "not large"     # without the GiB-scale vectors
+python tools/spectrace.py           # every rule of the specification is named by a test or vector
+SPILLGATE_NO_SKIPS=1 python -m pytest   # with brotli and zstandard installed: no vector may be skipped
+python -m ruff check . && python -m ruff format --check .
+python -m mypy
+```
+
+## Rules
+
+- The specification comes first. Behavior that the spec does not describe is not added here: change `spec/SPEC.md` in the reference repository, add vectors there, then sync.
+- `spectrace` counts a rule as covered when a test docstring or a vector names it; that is a checklist, not proof that the test asserts everything the rule says. Review the assertions too.
+- Test first for every bug. A test names the rules it protects in its docstring (`Covers: SG-R-...`); `tools/spectrace.py` reads that line.
+- Never weaken a test or a conformance vector to make code pass.
+- `conformance/` and `spec/` are copies. Do not edit them here; update them from the reference repository and record the release in `conformance/SOURCE`.
+- The core has no dependencies and starts no threads. Optional codecs are extras.
+- Never call an unbounded standard-library API (`zlib.decompress`, `gzip.decompress`, `GzipFile`, `decompress()` without `max_length`, `flush()`); `tests/test_python_traps.py` fails if the source does.
+- Code is read by people: short functions, a docstring that explains why, rule IDs where a rule applies.

spillgate-0.1.0/LICENSE

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

spillgate-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.5
+Name: spillgate
+Version: 0.1.0
+Summary: Decode untrusted compressed data with mandatory limits (decompression-bomb gate).
+Project-URL: Homepage, https://github.com/FelixMiddelhoff/spillgate-python
+Project-URL: Specification, https://github.com/FelixMiddelhoff/spillgate/blob/main/spec/SPEC.md
+Author: Felix Middelhoff
+License: MIT License
+        
+        Copyright (c) 2026 Felix Middelhoff
+        
+        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.
+License-File: LICENSE
+Keywords: brotli,content-encoding,decompression-bomb,deflate,gzip,security,zstd
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Archiving :: Compression
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: brotli
+Requires-Dist: brotli<2,>=1.2.1; extra == 'brotli'
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: zstd
+Requires-Dist: zstandard<1,>=0.25.0; extra == 'zstd'
+Description-Content-Type: text/markdown
+
+# spillgate (Python)
+
+Decode untrusted compressed data in Python with mandatory limits. A decompression bomb
+ends in a typed exception instead of exhausting memory.
+
+```python
+from spillgate import Limits, OutputLimitError, decode_all
+
+try:
+    body = decode_all(response_bytes, "gzip", Limits(max_output=8 * 2**20))
+except OutputLimitError:
+    ...  # refuse the response
+```
+
+- `Content-Encoding` chains: `gzip` (and `x-gzip`), `deflate`, `identity`; `br` and `zstd` as
+  optional extras (see below).
+- `max_output` is required. There is no unlimited setting.
+- Every layer is limited, including the intermediate layers of a chain.
+- Expansion ratio and chain length are limited by default.
+- Unknown, malformed or too deep `Content-Encoding` headers are refused, never passed through.
+- The core has no dependencies and starts no threads.
+
+This is the Python implementation of the language-neutral
+[spillgate specification](https://github.com/FelixMiddelhoff/spillgate/blob/main/spec/SPEC.md).
+It passes the same conformance corpus as the Go reference implementation.
+
+Python 3.11 or newer. **Integrating it into your service: [docs/how-to.md](docs/how-to.md).**
+
+## Use
+
+```python
+from spillgate import Decoder, Limits
+
+decoder = Decoder(Limits(max_output=8 * 2**20))  # build once, share between threads
+
+with decoder.reader(resp.raw, resp.headers.get_all("Content-Encoding", [])) as body:
+    for chunk in iter(lambda: body.read(65536), b""):
+        handle(chunk)  # any exception: discard everything
+```
+
+`decode_all` / `Decoder.read_all` return the whole body or raise, never partial data.
+`Decoder.reader` streams; bytes can arrive before a later error, so treat any
+`SpillgateError` as failure of the whole body.
+
+`source` is `bytes` or any object with `read(n)`. It is not closed by spillgate.
+
+### Brotli and zstd
+
+```
+pip install "spillgate[brotli]"   # brotli >= 1.2.1
+pip install "spillgate[zstd]"     # zstandard >= 0.25.0
+```
+
+```python
+from spillgate import Decoder, Limits, br, zstd
+
+decoder = Decoder(
+    Limits(max_output=8 * 2**20),
+    codecs={"br": br.codec(), "zstd": zstd.codec()},  # offer only what you installed
+)
+```
+
+Both decoders are C libraries and are treated as untrusted: spillgate reads the window size
+(brotli) or the whole frame structure (zstd) itself, refuses oversized windows as `memory_limit`
+before anything is decoded, and gives the library bounded steps. The window costs memory per
+request: up to 16 MiB for brotli and 8 MiB for zstd by default. Lower them with
+`br.codec(max_window_bits=22)` and `zstd.codec(max_window_bytes=2**21)` when a server decodes
+many requests at once. Older `brotli` versions are refused at import time: before 1.2.1 they
+had no output limit and a memory-corruption bug in the decoder (CVE-2026-111497).
+Always close readers (`with ... as body`) so the decoder state is released.
+
+CPU: frames and blocks that produce no output cost CPU but neither output nor ratio limit sees
+them. A zstd body made of millions of empty frames costs about one second per MB of input
+(gzip: milliseconds). Bound the compressed size with `max_input` or your server's body limit.
+
+### Limits
+
+| Field | Meaning | Default |
+| --- | --- | --- |
+| `max_output` | bytes one layer may produce, `1 .. 2**63-1` (required) | none |
+| `max_layers` | longest chain, `1 .. 16` | 5 |
+| `max_ratio` | output bytes per input byte the codec consumed | 1000 |
+| `ratio_grace` | output below which the ratio is not checked | 64 KiB |
+| `max_input` | cap on compressed bytes taken from the source | none |
+| `disable_ratio_limit` | the one named opt-out of the ratio check | `False` |
+
+`Limits` is immutable and validated when created. No number disables a limit: `0`, negative
+values, floats, strings and `bool` are all refused with `InvalidLimitsError`.
+
+### Errors
+
+Every refusal is a `SpillgateError` with a `kind` (`spillgate.Kind`), a `layer` and a
+`limit`; there is one subclass per kind: `OutputLimitError`, `RatioLimitError`,
+`LayerLimitError`, `InputLimitError`, `MemoryLimitError`, `UnsupportedEncodingError`,
+`MalformedEncodingError`, `CorruptError`, `InternalError`, `CanceledError`, `SourceError`,
+`InvalidLimitsError`. Errors are sticky: after one, every later read raises the same error.
+Error messages never contain more than 32 bytes of attacker data, and that data is escaped.
+
+`cancel=callable` on `reader` / `read_all` is polled before every read and every 4 KiB of
+input. It cannot interrupt one step inside the decoder; the limits bound the work there.
+
+### Why not `zlib.decompress` or `gzip.GzipFile`?
+
+Because they have no bound. The traps this library avoids: `decompressobj().decompress(data)`
+without `max_length` (and `max_length=0`, which means *unlimited*), `flush()`, one-shot
+`gzip.decompress`, and `GzipFile.read()` without a size. `tests/test_python_traps.py` scans the
+source for them.
+
+## What it does not cover
+
+Archives (zip, tar), bounding the compressed input (use `max_input` or limit the request body
+size), connection timeouts, encrypted content, and memory-safety bugs in the C libraries
+behind `zlib` and the optional codecs beyond what the limits contain. See
+[docs/memory.md](docs/memory.md) for the memory bounds.
+
+## Specification and tests
+
+`spec/SPEC.md` and `conformance/` are copies of the reference repository at the release named
+in `conformance/SOURCE`. The suite runs all vectors (bombs, malformed streams, header attacks,
+lying size fields), property tests, a scan for unbounded standard-library calls, and memory
+measurements with `tracemalloc`. `python tools/spectrace.py` checks that every rule of the
+specification is covered.
+
+## License
+
+MIT, see [LICENSE](LICENSE). Report vulnerabilities as described in [SECURITY.md](SECURITY.md).

spillgate-0.1.0/README.md

@@ -0,0 +1,126 @@
+# spillgate (Python)
+
+Decode untrusted compressed data in Python with mandatory limits. A decompression bomb
+ends in a typed exception instead of exhausting memory.
+
+```python
+from spillgate import Limits, OutputLimitError, decode_all
+
+try:
+    body = decode_all(response_bytes, "gzip", Limits(max_output=8 * 2**20))
+except OutputLimitError:
+    ...  # refuse the response
+```
+
+- `Content-Encoding` chains: `gzip` (and `x-gzip`), `deflate`, `identity`; `br` and `zstd` as
+  optional extras (see below).
+- `max_output` is required. There is no unlimited setting.
+- Every layer is limited, including the intermediate layers of a chain.
+- Expansion ratio and chain length are limited by default.
+- Unknown, malformed or too deep `Content-Encoding` headers are refused, never passed through.
+- The core has no dependencies and starts no threads.
+
+This is the Python implementation of the language-neutral
+[spillgate specification](https://github.com/FelixMiddelhoff/spillgate/blob/main/spec/SPEC.md).
+It passes the same conformance corpus as the Go reference implementation.
+
+Python 3.11 or newer. **Integrating it into your service: [docs/how-to.md](docs/how-to.md).**
+
+## Use
+
+```python
+from spillgate import Decoder, Limits
+
+decoder = Decoder(Limits(max_output=8 * 2**20))  # build once, share between threads
+
+with decoder.reader(resp.raw, resp.headers.get_all("Content-Encoding", [])) as body:
+    for chunk in iter(lambda: body.read(65536), b""):
+        handle(chunk)  # any exception: discard everything
+```
+
+`decode_all` / `Decoder.read_all` return the whole body or raise, never partial data.
+`Decoder.reader` streams; bytes can arrive before a later error, so treat any
+`SpillgateError` as failure of the whole body.
+
+`source` is `bytes` or any object with `read(n)`. It is not closed by spillgate.
+
+### Brotli and zstd
+
+```
+pip install "spillgate[brotli]"   # brotli >= 1.2.1
+pip install "spillgate[zstd]"     # zstandard >= 0.25.0
+```
+
+```python
+from spillgate import Decoder, Limits, br, zstd
+
+decoder = Decoder(
+    Limits(max_output=8 * 2**20),
+    codecs={"br": br.codec(), "zstd": zstd.codec()},  # offer only what you installed
+)
+```
+
+Both decoders are C libraries and are treated as untrusted: spillgate reads the window size
+(brotli) or the whole frame structure (zstd) itself, refuses oversized windows as `memory_limit`
+before anything is decoded, and gives the library bounded steps. The window costs memory per
+request: up to 16 MiB for brotli and 8 MiB for zstd by default. Lower them with
+`br.codec(max_window_bits=22)` and `zstd.codec(max_window_bytes=2**21)` when a server decodes
+many requests at once. Older `brotli` versions are refused at import time: before 1.2.1 they
+had no output limit and a memory-corruption bug in the decoder (CVE-2026-111497).
+Always close readers (`with ... as body`) so the decoder state is released.
+
+CPU: frames and blocks that produce no output cost CPU but neither output nor ratio limit sees
+them. A zstd body made of millions of empty frames costs about one second per MB of input
+(gzip: milliseconds). Bound the compressed size with `max_input` or your server's body limit.
+
+### Limits
+
+| Field | Meaning | Default |
+| --- | --- | --- |
+| `max_output` | bytes one layer may produce, `1 .. 2**63-1` (required) | none |
+| `max_layers` | longest chain, `1 .. 16` | 5 |
+| `max_ratio` | output bytes per input byte the codec consumed | 1000 |
+| `ratio_grace` | output below which the ratio is not checked | 64 KiB |
+| `max_input` | cap on compressed bytes taken from the source | none |
+| `disable_ratio_limit` | the one named opt-out of the ratio check | `False` |
+
+`Limits` is immutable and validated when created. No number disables a limit: `0`, negative
+values, floats, strings and `bool` are all refused with `InvalidLimitsError`.
+
+### Errors
+
+Every refusal is a `SpillgateError` with a `kind` (`spillgate.Kind`), a `layer` and a
+`limit`; there is one subclass per kind: `OutputLimitError`, `RatioLimitError`,
+`LayerLimitError`, `InputLimitError`, `MemoryLimitError`, `UnsupportedEncodingError`,
+`MalformedEncodingError`, `CorruptError`, `InternalError`, `CanceledError`, `SourceError`,
+`InvalidLimitsError`. Errors are sticky: after one, every later read raises the same error.
+Error messages never contain more than 32 bytes of attacker data, and that data is escaped.
+
+`cancel=callable` on `reader` / `read_all` is polled before every read and every 4 KiB of
+input. It cannot interrupt one step inside the decoder; the limits bound the work there.
+
+### Why not `zlib.decompress` or `gzip.GzipFile`?
+
+Because they have no bound. The traps this library avoids: `decompressobj().decompress(data)`
+without `max_length` (and `max_length=0`, which means *unlimited*), `flush()`, one-shot
+`gzip.decompress`, and `GzipFile.read()` without a size. `tests/test_python_traps.py` scans the
+source for them.
+
+## What it does not cover
+
+Archives (zip, tar), bounding the compressed input (use `max_input` or limit the request body
+size), connection timeouts, encrypted content, and memory-safety bugs in the C libraries
+behind `zlib` and the optional codecs beyond what the limits contain. See
+[docs/memory.md](docs/memory.md) for the memory bounds.
+
+## Specification and tests
+
+`spec/SPEC.md` and `conformance/` are copies of the reference repository at the release named
+in `conformance/SOURCE`. The suite runs all vectors (bombs, malformed streams, header attacks,
+lying size fields), property tests, a scan for unbounded standard-library calls, and memory
+measurements with `tracemalloc`. `python tools/spectrace.py` checks that every rule of the
+specification is covered.
+
+## License
+
+MIT, see [LICENSE](LICENSE). Report vulnerabilities as described in [SECURITY.md](SECURITY.md).

spillgate-0.1.0/RELEASING.md

@@ -0,0 +1,46 @@
+# Releasing to PyPI
+
+Releases use PyPI **Trusted Publishing**: the workflow `.github/workflows/release.yml` proves its
+identity to PyPI with a short-lived OpenID Connect token. No password or API token exists in the
+repository, in GitHub secrets or on a developer machine.
+
+## One-time setup (maintainer)
+
+1. **GitHub environment.** Repository **Settings → Environments → New environment**, name `pypi`.
+   Add yourself under *Required reviewers* so that every publish needs an explicit approval.
+   Optionally restrict *Deployment branches and tags* to the pattern `v*`.
+2. **PyPI pending publisher.** On <https://pypi.org/manage/account/publishing/> add a *pending
+   publisher* (this creates the project name `spillgate` on the first publish):
+   - PyPI project name: `spillgate`
+   - Owner: `FelixMiddelhoff`
+   - Repository name: `spillgate-python`
+   - Workflow name: `release.yml`
+   - Environment name: `pypi`
+3. Turn on two-factor authentication for the PyPI account and keep the recovery codes safe.
+
+The PyPI name is reserved only when the first release is published, so do step 2 and the first
+release close together.
+
+## Each release
+
+1. Update `CHANGELOG.md` and set `version` in `pyproject.toml` (for example `0.1.0`). Commit to `main` and wait for a green CI.
+2. Tag exactly that version and push the tag:
+   ```
+   git tag -a v0.1.0 -m "v0.1.0"
+   git push origin v0.1.0
+   ```
+3. The `release` workflow builds once, checks that the tag equals the version, runs the whole suite
+   with brotli and zstd installed and nothing skipped, checks the wheel in a clean environment, and
+   waits for your approval in the `pypi` environment. After the approval it publishes the same
+   files, with build attestations, to PyPI.
+4. Check from a clean directory:
+   ```
+   python -m venv t && t/bin/python -m pip install "spillgate[brotli,zstd]==0.1.0"
+   ```
+5. Create the GitHub release from the tag with the changelog text.
+
+## Never
+
+Never delete or move a published tag, and never re-upload a version: PyPI refuses it. A wrong
+release is yanked on PyPI and fixed with the next patch version. Versions at or above 1.0 need
+separate, explicit consent.