pq_crypto-seal 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9f0508e0149f076a9f8d6c9a829b516a41e2998dc5af916db9d0d4696349d36c
+  data.tar.gz: ce0dd7ba92b94ae212f22ea73cc9754b2028da7037a46539c5408dd60bae961b
+SHA512:
+  metadata.gz: 248f9187168dd55054827e08dbfcf771555101e00f748cdcef55dbaed31ba4c4fb98ce6f6017c05c00bc5f78de23cfcd4c457541eda93cc2537be8be749711e6
+  data.tar.gz: b96cd381d599e6e9a52e0eba84de72500e6746e744183c5d383ed61d31305874393d640c8a1a79dbf288c7db1daeb1379ffc3c125443b5c0c4b2a39b14088402

data/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, macos-14]
+        ruby: ["2.7.1", "3.1", "3.3", "3.4", "4.0"]
+        exclude:
+          - os: macos-14
+            ruby: "2.7.1"
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y libssl-dev
+      - if: runner.os == 'macOS'
+        run: brew install openssl@3 || true
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+        env:
+          PKG_CONFIG_PATH: /opt/homebrew/opt/openssl@3/lib/pkgconfig:/usr/local/opt/openssl@3/lib/pkgconfig
+      - run: bundle exec rake
+      - name: Verify OpenSSL 3 linkage on Linux Ruby 2.7.1
+        if: matrix.os == 'ubuntu-24.04' && matrix.ruby == '2.7.1'
+        shell: bash
+        run: |
+          set -euxo pipefail
+          extension="lib/pq_crypto/seal/pq_crypto_seal.so"
+          test -f "${extension}"
+          ldd "${extension}" | tee linked-libraries.txt
+          grep -E 'libcrypto\.so\.3([[:space:]]|$)' linked-libraries.txt
+      - name: Show mkmf logs on failure
+        if: failure()
+        run: find tmp -name mkmf.log -print -exec cat {} \; || true
+      - run: bundle exec ruby script/vendor_libs.rb --check
+
+  sanitize:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - run: sudo apt-get update && sudo apt-get install -y libssl-dev
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+      - run: bundle exec rake clean
+      - run: PQC_SEAL_SANITIZE=1 bundle exec rake compile
+      - name: Show mkmf logs on compile failure
+        if: failure()
+        run: find tmp -name mkmf.log -print -exec cat {} \; || true
+      - name: Run sanitizer tests
+        env:
+          N: "0"
+        run: |
+          export LD_PRELOAD="$(gcc -print-file-name=libasan.so)"
+          export ASAN_OPTIONS="detect_leaks=0:halt_on_error=1:abort_on_error=1"
+          export UBSAN_OPTIONS="halt_on_error=1:print_stacktrace=1"
+          bundle exec rake test

data/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+## 0.1.0
+
+- AEGIS streaming state rejects `update`/`final` before `initialize` (`mode` guard).
+- Encrypt path wipes the internal plaintext copy in `ensure` (caller buffers unchanged).
+- CI: Actions pinned by commit SHA, `permissions: contents: read`, fuzz + gem-smoke jobs.
+- Repository hygiene: `.DS_Store` / build artifacts ignored; no tracked binaries.
+
+- Initial versioned `PQCSEAL1` envelope format.
+- Multi-recipient DEK wrapping through `PQCrypto::HybridKEM` algorithm
+  `:ml_kem_768_x25519_xwing` (pinned; not `CANONICAL_ALGORITHM`).
+- Runtime dependency pinned to `pq_crypto ~> 0.6.4` so suite ID 1 cannot drift
+  with a future 0.7+ line.
+- Exact X-Wing size checks: public key 1216, ciphertext 1120, shared secret 32.
+- HKDF-SHA256 key separation and AEGIS-256 payload/DEK encryption.
+- Authenticated `padding_policy_id` in the immutable header (`none` / `padme` /
+  fixed / buckets).
+- String, IO, and atomic file APIs with strict EOF/size defaults; framed helpers
+  `encrypt_frame_io` / `decrypt_frame_io` for embedded envelopes.
+- Resource limits: `max_staging_bytes`, `max_plaintext_bytes`, `max_envelope_bytes`
+  with safe defaults against payload amplification.
+- Full-envelope Padmé padding.
+- Recipient-section rebuild and DEK rotation operations.
+- Public API hygiene: internal helpers (`unwrap_dek`, `derive_kek`, …) are
+  private class methods.
+- Malformed wire fields raise `FormatError` (not `InvalidConfigurationError`).
+- `ResourceLimitError` for ceiling violations.
+- Golden-vector suite pinning the X-Wing wire contract, the immutable-header
+  byte layout, the payload AD derivation, and byte-identical one-shot vs
+  incremental output under a deterministic RNG (`test/golden_vectors_test.rb`).
+- Self-driving decrypt/parser fuzz job in CI (mutated and random envelopes),
+  failing on any error outside the documented classes.
+- CI GitHub Actions pinned by commit SHA; workflow `permissions` reduced to
+  `contents: read`.
+- Robust OpenSSL 3 selection for Homebrew Intel/Apple Silicon, `pkg-config`,
+  environment roots, and explicit extconf paths.
+- Remove OpenSSL 1.1 include paths inherited from Ruby 2.7 and link the selected
+  OpenSSL 3 `libcrypto` by absolute path.
+- Avoid unreliable OpenSSL link probes in legacy Ruby 2.7 `mkmf`; verify headers
+  at configure time and the linked runtime in the extension initializer.
+- Disable Minitest's parallel executor only in the ASan job (`N=0`) to avoid a
+  known teardown conflict caused by preloading ASan into an otherwise unsanitized
+  Ruby executable.

data/FORMAT.md

@@ -0,0 +1,139 @@
+# PQCSEAL1 wire format
+
+All integers are unsigned big-endian. Parsers reject trailing bytes, unknown
+flags, unsupported suites, noncanonical lengths, and arithmetic overflow before
+allocating from untrusted lengths.
+
+## Immutable payload header
+
+| Field | Size |
+|---|---:|
+| magic (`PQCSEAL1`) | 8 |
+| format version (`1`) | 1 |
+| header length | 4 |
+| content suite ID (`1`) | 2 |
+| lookup mode (`1`, scoped hint) | 1 |
+| flags (`0`) | 2 |
+| padding policy ID | 1 |
+| payload ID | 32 |
+| payload nonce | 32 |
+| recipient capacity | 2 |
+| slot size | 2 |
+| padded inner length | 8 |
+| public metadata length | 4 |
+| public metadata | variable |
+
+Padding policy IDs:
+
+| ID | Meaning |
+|---:|---|
+| 0 | none |
+| 1 | Padmé over the complete final envelope size |
+| 2 | fixed target (`padding: { to: N }`) |
+| 3 | application buckets (`padding: { buckets: [...] }`) |
+
+The payload AEGIS associated data is exactly:
+
+```text
+SHA-256(exact immutable payload header bytes)
+```
+
+Content suite `1` fixes AEGIS-256, a 32-byte nonce, a 32-byte tag, and
+inner-frame-v1. The padding policy ID records how the final envelope length was
+chosen; it is authenticated as part of the header.
+
+## Mutable recipient section
+
+| Field | Size |
+|---|---:|
+| wrap suite ID (`1`) | 2 |
+| random section ID | 32 |
+| fixed slots | `recipient_capacity * slot_size` |
+
+Every complete recipient-section rebuild creates a new random section ID and
+recreates all real and dummy slots. Mixed wrapping suites are forbidden.
+
+Wrap suite `1` fixes MLKEM768-X25519/X-Wing-compatible encapsulation
+(`pq_crypto` algorithm `:ml_kem_768_x25519_xwing`), HKDF-SHA256, AEGIS-256 DEK
+wrapping, and 32-byte wrap nonces/tags. Exact sizes:
+
+| Value | Bytes |
+|---|---:|
+| public key | 1216 |
+| KEM ciphertext | 1120 |
+| shared secret | 32 |
+
+## Slot layout for wrap suite 1
+
+| Field | Size |
+|---|---:|
+| recipient hint | 32 |
+| KEM ciphertext | 1120 |
+| wrap nonce | 32 |
+| encrypted DEK | 32 |
+| wrap tag | 32 |
+| authenticated random slot padding | `slot_size - 1248` |
+
+The hint is:
+
+```text
+SHA-256(
+  "PQC-SEAL-V1-RECIPIENT-HINT\0" ||
+  payload_id || section_id || uint16(wrap_suite_id) || canonical_public_key
+)
+```
+
+The 32-byte KEK is derived with RFC 5869 HKDF-SHA256. Salt is the RFC 5869
+default of 32 zero bytes (HashLen zeros). `info` is:
+
+```text
+"PQC-SEAL-V1-WRAP-KEY\0" ||
+payload_id || section_id || uint16(wrap_suite_id) || uint16(slot_index)
+```
+
+The AEGIS AD for wrapping is:
+
+```text
+SHA-256(
+  "PQC-SEAL-V1-WRAP-AD\0" ||
+  payload_header_hash || section_id || uint16(slot_index) ||
+  uint16(wrap_suite_id) || recipient_hint || slot_padding
+)
+```
+
+Dummy slots execute the same full KEM/HKDF/AEGIS pipeline against disposable
+keypairs and random dummy DEKs. No recipient count is serialized.
+
+## Encrypted inner frame
+
+| Field | Size |
+|---|---:|
+| inner version (`1`) | 1 |
+| inner flags (`0`) | 1 |
+| real content length | 8 |
+| private metadata length | 4 |
+| private metadata | variable |
+| content | variable |
+| random encrypted padding | variable |
+
+The final field following the encrypted inner frame is the 32-byte payload tag.
+The padding amount is chosen so the size of the complete final envelope reaches
+the configured Padmé/fixed/bucket target.
+
+During incremental decryption, all inner bytes are untrusted until the final tag
+has been verified. Implementations stage the complete inner frame, authenticate
+it, then parse lengths and publish content.
+
+## Defaults
+
+```text
+slot_size:          2048 bytes (configurable 2048..8192, multiple of 256)
+recipient_capacity: 4 (maximum 32; never derived automatically from ACL size)
+padding:            Padmé over the complete final envelope size
+max_staging_bytes:  ~1 GiB + private-metadata ceiling
+max_plaintext_bytes:~1 GiB
+```
+
+Parsers reject trailing bytes on the one-shot and default IO paths. Framed
+stream consumers that intentionally embed one envelope inside a larger stream
+must use `encrypt_frame_io` / `decrypt_frame_io`.

data/GET_STARTED.md

@@ -0,0 +1,30 @@
+# Getting started
+
+## Build prerequisites
+
+Ruby 2.7.1+ and OpenSSL 3.0+ development files are required. On macOS the
+build automatically searches Homebrew `openssl@3`. For a custom installation:
+
+```bash
+bundle config set --local build.pq_crypto-seal \
+  "--with-openssl-dir=$(brew --prefix openssl@3)"
+bundle exec rake clean compile
+```
+
+```ruby
+require "pq_crypto/seal"
+
+recipient = PQCrypto::HybridKEM.generate(PQCrypto::Seal::WRAP_KEM_ALGORITHM)
+envelope = PQCrypto::Seal.encrypt("secret bytes", to: recipient.public_key)
+plaintext = PQCrypto::Seal.decrypt(envelope, with: recipient)
+```
+
+For files, use `encrypt_file` and `decrypt_file`; decryption stages and verifies
+the complete inner frame before publishing plaintext. Use `recipient_capacity`
+and `slot_size` as long-lived application policy values because both are stored
+in the immutable payload header.
+
+Recipient-section rebuilds always require the application's complete,
+authoritative public-key ACL. They do not revoke access to plaintext or old
+envelope copies. Use `rotate_dek`/`rotate_dek_file` when a new payload key and
+full re-encryption are required.

data/Gemfile

@@ -0,0 +1,7 @@
+source "https://rubygems.org"
+
+if ENV["PQ_CRYPTO_PATH"]
+  gem "pq_crypto", path: ENV.fetch("PQ_CRYPTO_PATH")
+end
+
+gemspec

data/LICENSE.txt

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

data/README.md

@@ -0,0 +1,215 @@
+# pq_crypto-seal
+
+Post-quantum envelope encryption for Ruby 2.7.1+.
+
+The gem turns `pq_crypto`'s hybrid KEM into practical document encryption:
+
+```text
+MLKEM768-X25519 shared secret → HKDF-SHA256 → KEK → wrap random DEK
+random DEK → AEGIS-256 → document
+```
+
+`libaegis` 0.10.3 is vendored and compiled into the extension. The existing
+`pq_crypto` gem supplies the hybrid KEM and OpenSSL-backed primitives.
+
+> **Status:** 0.1.0 is experimental cryptographic software; format v1; not
+> independently audited. Read `SECURITY.md` before using it for irreplaceable data.
+>
+> `wrap_suite_id = 1` is pinned to `:ml_kem_768_x25519_xwing` and `pq_crypto ~> 0.6.4`.
+
+## Installation
+
+```ruby
+gem "pq_crypto", "~> 0.6.4"
+gem "pq_crypto-seal", "~> 0.1.0"
+```
+
+Ruby `>= 2.7.1` and OpenSSL `>= 3.0` development files are required for a
+source build.
+
+On macOS, `extconf.rb` automatically searches Homebrew `openssl@3` on both
+Apple Silicon and Intel installations. If OpenSSL 3 is installed in a custom
+location, configure it explicitly:
+
+```bash
+brew install openssl@3
+bundle config set --local build.pq_crypto-seal \
+  "--with-openssl-dir=$(brew --prefix openssl@3)"
+bundle exec rake clean compile
+```
+
+`OPENSSL_ROOT_DIR` and `OPENSSL_DIR` are also supported. An explicit
+`--with-openssl-dir`, `--with-openssl-include`, or `--with-openssl-lib` always
+takes precedence over automatic discovery.
+
+## String API
+
+```ruby
+require "pq_crypto/seal"
+
+alice = PQCrypto::HybridKEM.generate(PQCrypto::Seal::WRAP_KEM_ALGORITHM)
+bob   = PQCrypto::HybridKEM.generate(PQCrypto::Seal::WRAP_KEM_ALGORITHM)
+
+sealed = PQCrypto::Seal.encrypt(
+  image_bytes,
+  to: [alice.public_key, bob.public_key],
+  metadata: { mime: "image/png" }.to_json,
+  public_metadata: "tenant-7",
+  recipient_capacity: 4,
+  slot_size: 2048,
+  padding: :padme
+)
+
+opened = PQCrypto::Seal.open(sealed, with: alice) # keypair supplies secret + public hint material
+opened.data
+opened.metadata
+opened.public_metadata
+
+PQCrypto::Seal.decrypt(sealed, with: bob)
+```
+
+All random keys and nonces are generated internally. There is no public API for
+supplying a DEK or nonce. Because scoped hint lookup needs the matching public
+key, `with:` accepts a `HybridKEM::Keypair`. When keys are stored separately:
+
+```ruby
+credentials = PQCrypto::Seal.credentials(
+  secret_key: loaded_secret_key,
+  public_key: loaded_public_key
+)
+PQCrypto::Seal.decrypt(sealed, with: credentials)
+```
+
+## Files and IO
+
+```ruby
+PQCrypto::Seal.encrypt_file(
+  "scan.tiff",
+  "scan.tiff.pqcseal",
+  to: alice.public_key
+)
+
+PQCrypto::Seal.decrypt_file(
+  "scan.tiff.pqcseal",
+  "restored.tiff",
+  with: alice
+)
+```
+
+`encrypt_io` accepts the exact plaintext `size:`. `decrypt_io` stages the entire
+unauthenticated inner frame to a mode-0600 temporary file and copies content to
+the caller's output only after the final AEGIS tag is valid.
+
+## Recipients and key lifecycle
+
+The envelope intentionally does not contain an authoritative list of recipient
+public keys. The application owns the ACL. Any complete recipient-section
+rewrite therefore receives the full list:
+
+```ruby
+updated = PQCrypto::Seal.rebuild_recipients(
+  sealed,
+  with: alice,
+  recipients: [alice.public_key, carol.public_key]
+)
+```
+
+`add_recipient(..., recipient:, current_recipients:)` still requires the
+complete current ACL and rebuilds all slots.
+`drop_recipient_stanza(..., remaining_recipients:)` describes exactly what it
+does. It does **not** revoke plaintext, a DEK, or old copies already obtained.
+
+```ruby
+rotated = PQCrypto::Seal.rotate_dek(
+  sealed,
+  with: alice,
+  recipients: [alice.public_key, carol.public_key]
+) # preserves the existing envelope size by default
+```
+
+`rebuild_recipients` preserves the DEK and encrypted payload. It is an
+operational migration of the current canonical copy, not protection against old
+saved envelopes. `rotate_dek` creates a new DEK and re-encrypts the payload; it
+still cannot erase knowledge from prior copies. Rotation preserves the current
+final envelope size by default (`padding: :preserve`); pass `:padme`, `:none`, or
+an explicit padding policy to recalculate it.
+
+## Wire-format v1
+
+The exact bytes are implemented in `PQCrypto::Seal::Format`:
+
+```text
+immutable payload header
+  magic "PQCSEAL1"
+  version
+  content_suite_id = AEGIS-256 payload profile
+  lookup_mode = payload-scoped recipient hint
+  payload_id, payload_nonce
+  recipient_capacity, slot_size
+  padded_inner_length
+  public metadata
+
+mutable recipient section
+  wrap_suite_id = MLKEM768-X25519 + HKDF-SHA256 + AEGIS-256 wrap
+  random section_id (changes on every complete rebuild)
+  fixed-capacity, fixed-size slots
+
+slot
+  recipient_hint
+  1120-byte hybrid KEM ciphertext
+  wrap nonce
+  wrapped 32-byte DEK
+  32-byte tag
+  authenticated random slot padding
+
+AEGIS-encrypted inner frame
+  authenticated content length and private metadata length
+  private metadata
+  content
+  encrypted Padmé padding
+
+32-byte payload tag
+```
+
+`content_suite_id` and `wrap_suite_id` are deliberately independent. A recipient
+section can be rebuilt without changing payload AD as long as the new wrapping
+stanza fits the immutable `slot_size`.
+
+Defaults:
+
+```text
+slot_size:          2048 bytes (configurable 2048..8192, multiple of 256)
+recipient_capacity: 4 (maximum 32; never derived automatically from ACL size)
+padding:            Padmé over the complete final envelope size
+```
+
+The payload-and-section-scoped recipient hint avoids a stable global recipient identifier and prevents stable hints from revealing real slots across recipient-section rebuilds.
+Anyone who already knows a candidate public key can test for its presence. No
+formal recipient anonymity is claimed.
+
+The wrapping KEM follows the MLKEM768-X25519/X-Wing construction, targeting
+approximately 128-bit security. ML-KEM-768 supplies conservative margin; the
+full hybrid suite is not advertised as NIST category 3.
+
+## Envelope identity
+
+`PQCrypto::Seal.digest(envelope)` is SHA-256 over the **complete** envelope
+bytes. The recipient section is intentionally mutable, so
+`rebuild_recipients` / `rotate_dek` change the digest even when the encrypted
+payload is unchanged. Use `opened.payload_id` (or `inspect_envelope`) for a
+stable document identifier.
+
+High `recipient_capacity` makes encryption slower: every empty slot still runs
+a full X-Wing encapsulation against a disposable keypair.
+
+## Tests
+
+```bash
+bundle install
+bundle exec rake
+```
+
+Set `PQC_SEAL_SANITIZE=1` when compiling under ASan/UBSan. The suite covers
+AEGIS one-shot/incremental equivalence, tampering, multi-recipient opening,
+full-envelope padding, recipient rebuilds, staged file publication, and parser
+limits.

data/RELEASING.md

@@ -0,0 +1,34 @@
+# Releasing
+
+1. Run `bundle exec ruby script/vendor_libs.rb --check`.
+2. Confirm `pq_crypto` dependency remains `~> 0.6.4` and `WRAP_KEM_ALGORITHM`
+   is still `:ml_kem_768_x25519_xwing` with the documented sizes.
+3. Run the full CI matrix and sanitizer job.
+4. Build with `gem build pq_crypto-seal.gemspec`.
+5. Install the exact built gem into an empty `GEM_HOME` together with the
+   supported `pq_crypto` gem and run String and File round trips.
+6. Confirm golden envelope vectors and pinned X-Wing wire-contract checks in
+   `test/golden_vectors_test.rb` pass, and that the CI fuzz job is green.
+7. Publish only from a signed tag through RubyGems Trusted Publishing.
+
+Vendored libaegis sources are pinned by archive SHA-256 and a deterministic
+source-tree digest (`vendor/libaegis/TREE_SHA256`). The full upstream snapshot
+ships intact — including families and the RAF sources that this gem does not
+compile — so `script/vendor_libs.rb --check` can prove the vendored tree is
+byte-identical to the audited archive. Never delete vendored files to slim the
+gem; that would break the provenance guarantee. Never update the snapshot
+without rerunning official KATs, cross-backend equivalence checks, envelope
+golden vectors, and fuzz tests.
+
+The golden vectors fix every value this gem controls (recipient keys, DEK,
+nonces, section id, padding bytes, metadata, plaintext) and assert the derived
+header bytes, associated data, and one-shot/incremental equivalence. A fully
+frozen "plaintext to exact bytes" vector is intentionally not asserted for the
+KEM ciphertext region, because X-Wing encapsulation randomness originates inside
+`pq_crypto` and is not injectable here; the wire-contract check pins its exact
+sizes and round-trip instead.
+
+The ASan job sets `detect_leaks=0` because ASan is preloaded into an otherwise
+unsanitized Ruby interpreter; host-process allocator noise would otherwise fail
+the job. Memory-safety errors still abort via `halt_on_error`.
+

data/Rakefile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+require "rake/extensiontask"
+require_relative "lib/pq_crypto/seal/version"
+
+Rake::ExtensionTask.new("pq_crypto_seal", Gem::Specification.load("pq_crypto-seal.gemspec")) do |ext|
+  ext.lib_dir = "lib/pq_crypto/seal"
+end
+
+Rake::TestTask.new do |task|
+  task.libs << "lib"
+  task.libs << "test"
+  task.pattern = "test/**/*_test.rb"
+  task.warning = false
+end
+
+task test: :compile
+task default: :test

data/SECURITY.md

@@ -0,0 +1,85 @@
+# Security
+
+This project has not received an independent cryptographic or implementation
+audit. Do not treat version 0.1.0 as a substitute for a reviewed storage design.
+
+Experimental cryptographic software; format v1; not independently audited.
+
+## Threat model
+
+The v1 format protects confidentiality and integrity of the **payload** when an
+attacker obtains a passive copy of envelopes but not a recipient secret key.
+
+Successful opening authenticates:
+
+- the immutable payload header
+- the selected recipient stanza that yielded the DEK
+- the encrypted inner frame (private metadata + content + encrypted padding)
+
+Successful opening does **not** authenticate:
+
+- the integrity of other recipients' stanzas
+- the completeness or correctness of the application ACL
+- absence of rollback against a replaceable canonical envelope
+
+It does not claim recipient anonymity. Anyone who already knows a candidate
+public key can test for its presence via the scoped recipient hint.
+
+Removing a recipient stanza does not revoke plaintext, a DEK, or an older copy
+already obtained by that recipient. Rebuilding recipient stanzas protects the
+current copy only. Rotating the DEK creates a new protected version but cannot
+remove knowledge from older copies.
+
+## Side channels
+
+Recipient lookup short-circuits slots whose hint does not match. The number of
+full KEM decapsulations therefore depends on how many slots share the expected
+hint. Against a purely passive adversary holding only the envelope bytes this is
+out of scope. Local timing, cache, or power side channels on a machine that
+already holds a recipient secret key are not mitigated. `AmbiguousRecipientStanzas`
+is raised when more than one slot opens successfully.
+
+Caller-owned plaintext and metadata buffers are not wiped by the encrypt path;
+callers that need residual-data hygiene must clear their own buffers.
+`Opened#data` / `Opened#metadata` returned from `open` are the caller's
+responsibility after use.
+
+## Envelope digests
+
+`Seal.digest` hashes the complete envelope, including the mutable recipient
+section. Prefer `payload_id` (exposed on `Opened` and `Inspection`) when a
+stable document identifier is required.
+
+## Resource limits
+
+Untrusted envelopes declare `padded_inner_length` as a uint64. Decrypt APIs
+enforce default ceilings (`max_staging_bytes`, `max_plaintext_bytes`,
+`max_envelope_bytes`) so a sender who knows a recipient public key cannot force
+unbounded staging or disk amplification before the final AEGIS tag fails.
+
+- `max_staging_bytes` / `max_envelope_bytes` are checked **before** AEAD
+  verification (pre-auth).
+- `max_plaintext_bytes` is enforced **after** the payload tag verifies
+  (post-auth), because the real content length is authenticated inside the
+  inner frame.
+
+Applications may raise the limits explicitly when larger objects are required.
+
+## Staging
+
+Large decryptions stage unauthenticated plaintext in a mode-0600 temporary file.
+On Unix the file is unlinked immediately after opening. The staged bytes are
+never returned or published before the final AEGIS tag is verified. Platforms
+that cannot unlink an open file, filesystem snapshots, and storage-layer
+forensics may still retain remnants; use a suitably protected staging filesystem.
+
+## Wire suite pinning
+
+`wrap_suite_id = 1` is permanently bound to MLKEM768-X25519 / X-Wing (draft-10
+compatible) with fixed public-key (1216), ciphertext (1120), and shared-secret
+(32) sizes, as implemented by `pq_crypto ~> 0.6.4`. Seal does not follow
+`HybridKEM::CANONICAL_ALGORITHM`; a future change of that constant must not
+alter suite 1 wire bytes. Always generate keys with
+`PQCrypto::HybridKEM.generate(PQCrypto::Seal::WRAP_KEM_ALGORITHM)`.
+
+Report vulnerabilities privately to the repository owner.