pq_crypto-seal 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f0508e0149f076a9f8d6c9a829b516a41e2998dc5af916db9d0d4696349d36c
-  data.tar.gz: ce0dd7ba92b94ae212f22ea73cc9754b2028da7037a46539c5408dd60bae961b
+  metadata.gz: 0e2f25bfc50a4e95892fb3c9e25992ff359bd16cc65535dacf3863d943c34e52
+  data.tar.gz: 40462d41fa188924ba4abbd5d76b4ad22c48377964d70a4544bae919ec4f5140
 SHA512:
-  metadata.gz: 248f9187168dd55054827e08dbfcf771555101e00f748cdcef55dbaed31ba4c4fb98ce6f6017c05c00bc5f78de23cfcd4c457541eda93cc2537be8be749711e6
-  data.tar.gz: b96cd381d599e6e9a52e0eba84de72500e6746e744183c5d383ed61d31305874393d640c8a1a79dbf288c7db1daeb1379ffc3c125443b5c0c4b2a39b14088402
+  metadata.gz: 8a3f087d4c922637fcbf5af86cae6a9e118b688215f9a218c6572e524555643e2d444f7452416575c2904f08a8c34742adc0e2cb4bfab6e33a0267015f03d177
+  data.tar.gz: e1746e895c1be25bd755fc358c4eac0291b21c6c638b7d87fb1603e08229783e942adcecbdc4c095e4ae1fde9ca00d49a7f472a89cc1ef183339a94f9546e025

data/CHANGELOG.md

@@ -1,7 +1,76 @@
 # Changelog
 
+## 0.1.2
+
+### Security
+
+- **Default padding enforcement on decrypt.** `decrypt` / `open` / `decrypt_io` /
+  `decrypt_file` now default to `required_padding: :from_header`. Padmé / none
+  get a full canonical size check from authenticated lengths. Fixed / buckets
+  are not self-describing on the wire, so `:from_header` only accepts the
+  authenticated policy id (envelope still opens); pass
+  `required_padding: { to: N }` / `{ buckets: [...] }` for full target
+  enforcement. Pass `required_padding: false` to opt out entirely.
+- **RUP-safe IO staging.** `decrypt_io` / `decrypt_file` / DEK rotation stage
+  **ciphertext** on the temporary 0600 file and only materialise plaintext after
+  the AEGIS tag verifies (second pass). Unauthenticated plaintext is no longer
+  written to disk before authentication.
+- **Honest recipient ACL API.** Removed `drop_recipient_stanza` and
+  `drop_recipient_stanza_file`. Those names suggested revocation while old copies
+  and the DEK remain valid. Use `rebuild_recipients` / `rebuild_recipients_file`
+  with the application's complete authoritative ACL for the current canonical
+  copy only; use `rotate_dek` when a new payload key is required.
+- **Capacity / slot growth path.** `recipient_capacity` and `slot_size` remain
+  immutable in the payload header for a given envelope, but `rotate_dek` /
+  `rotate_dek_file` now accept optional `recipient_capacity:` and `slot_size:`
+  overrides because they re-encrypt the authenticated plaintext under a new DEK.
+- **At-rest draft pinning documented.** SECURITY.md / FORMAT.md / VENDORING.md
+  state that suite 1 and content suite 1 are pinned to X-Wing draft-10 and
+  AEGIS-256 (IETF CFRG draft-18 vectors via libaegis 0.10.3), not to future RFC
+  text. External KATs are referenced; self-generated golden vectors pin Seal's
+  own wire layout only.
+- **CI / release hygiene matched to claims.** Workflow Actions pinned by full
+  commit SHA, top-level `permissions: contents: read`, and jobs for fuzz,
+  gem-smoke, and `release_contract_check`. `.DS_Store` is gitignored; the
+  release-contract checker rejects tracked copies.
+
+### Breaking (0.1.x experimental)
+
+- Default `required_padding` is `:from_header` (was effectively off / `nil`).
+- `drop_recipient_stanza` / `drop_recipient_stanza_file` removed from the public API.
+
+## 0.1.1
+
+- Release hygiene: CI Actions pinned by commit SHA, `permissions: contents: read`,
+  fuzz + gem-smoke + `release_contract_check` jobs; ignore `.DS_Store` / binaries.
+- Aggressive internal refactor: parsing, recipient wrapping, one-shot operations,
+  streaming, atomic files, padding policies, and resource limits now live in
+  focused objects instead of large branching methods. Public API and wire v1
+  remain unchanged.
+- Padding enforcement now validates both policy id and the canonical target;
+  parameterized fixed/bucket requirements cannot masquerade as one another.
+- Added exact deterministic envelope/stream equivalence, official X-Wing
+  draft-10 decapsulation KATs, partial-read/write regression tests, and a
+  release-contract checker.
+- Release gem contains production code plus only the AEGIS-256 sources needed
+  to compile; tests, CI, fuzz harnesses, RAF, and unused AEGIS families stay out.
+- CI restores pinned Actions, sanitizer fuzz smoke, and isolated built-gem E2E.
+
+- IO: all output paths use `write_all` (reject silent partial writes).
+- Decrypt APIs accept `required_padding:` and can enforce Padmé / none / fixed /
+  buckets after successful AEAD (wire format unchanged).
+- Runtime dependency pinned to `pq_crypto = 0.6.4`.
+- Resource limits applied to `inspect_envelope`, `rebuild_recipients`,
+  `rotate_dek`, and `rebuild_recipients_file`.
+- Default one-shot limits lowered to 64 MiB (use file/IO APIs for larger docs).
+- Document that `rotate_dek` allocates a new `payload_id`.
+- CI: Actions pinned by commit SHA; `permissions: contents: read`; fuzz and
+  gem-smoke jobs restored.
+- Repository hygiene: ignore `.DS_Store` and built binaries.
+
 ## 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.

data/FORMAT.md

@@ -38,9 +38,10 @@ The payload AEGIS associated data is exactly:
 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.
+Content suite `1` fixes AEGIS-256 (libaegis 0.10.3; CFRG draft-18 KATs), 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
 
@@ -53,9 +54,10 @@ chosen; it is authenticated as part of the header.
 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:
+Wrap suite `1` fixes MLKEM768-X25519/X-Wing **draft-10**-compatible encapsulation
+(`pq_crypto = 0.6.4` algorithm `:ml_kem_768_x25519_xwing`), HKDF-SHA256, AEGIS-256
+DEK wrapping, and 32-byte wrap nonces/tags. The suite id freezes that behaviour
+for at-rest data even if a later RFC text diverges. Exact sizes:
 
 | Value | Bytes |
 |---|---:|
@@ -121,8 +123,9 @@ 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.
+has been verified. Implementations stage the complete **ciphertext** inner frame,
+authenticate the tag, materialise plaintext only after verification, then parse
+lengths and publish content.
 
 ## Defaults
 
@@ -131,9 +134,21 @@ 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
+max_plaintext_bytes:64 MiB by default
 ```
 
 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`.
+
+
+## Receiver-side padding checks (0.1.2+)
+
+`padding_policy_id` is authenticated but does not by itself encode fixed targets
+or bucket lists. Decrypt APIs default to `required_padding: :from_header`:
+
+- Padmé / none — full canonical size enforcement
+- fixed / buckets — accept authenticated policy id; full target checks need
+  `required_padding: { to: N }` or `{ buckets: [...] }`
+
+Pass `required_padding: false` to skip enforcement.

data/GET_STARTED.md

@@ -19,12 +19,28 @@ 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.
+For files, use `encrypt_file` and `decrypt_file`; decryption stages ciphertext,
+verifies the AEGIS tag, then materialises plaintext before publishing. Use
+`recipient_capacity` and `slot_size` as long-lived application policy values:
+both are stored in the immutable payload header. To grow them after encryption,
+call `rotate_dek` / `rotate_dek_file` with new `recipient_capacity:` /
+`slot_size:` (full re-encryption under a new DEK).
 
 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.
+authoritative public-key ACL. They do not revoke access to plaintext, the DEK,
+or old envelope copies. Prefer `rebuild_recipients` over inventing “drop”
+helpers. Use `rotate_dek` when a new payload key is required.
+
+Decrypt defaults to `required_padding: :from_header`: Padmé/none get a full size
+check; fixed/buckets open with a policy-id check (pass `{ to: }` / `{ buckets: }`
+for full target enforcement).
+
+## Large documents
+
+Default one-shot limits are 64 MiB (`max_plaintext_bytes` / related staging and
+envelope ceilings). For larger objects use `encrypt_file` / `decrypt_file` or
+`encrypt_io` / `decrypt_io` and raise the limits explicitly, for example:
+
+```ruby
+PQCrypto::Seal.decrypt_file(src, dst, with: credentials, max_plaintext_bytes: 512 * 1024 * 1024)
+```

data/README.md

@@ -12,16 +12,17 @@ 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
+> **Status:** 0.1.2 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`.
+> `wrap_suite_id = 1` is pinned to `:ml_kem_768_x25519_xwing` and `pq_crypto = 0.6.4`
+> (X-Wing draft-10 wire sizes). Content suite 1 is AEGIS-256 via libaegis 0.10.3.
 
 ## Installation
 
 ```ruby
 gem "pq_crypto", "~> 0.6.4"
-gem "pq_crypto-seal", "~> 0.1.0"
+gem "pq_crypto-seal", "~> 0.1.2"
 ```
 
 Ruby `>= 2.7.1` and OpenSSL `>= 3.0` development files are required for a
@@ -96,17 +97,19 @@ PQCrypto::Seal.decrypt_file(
 )
 ```
 
-`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.
+`encrypt_io` accepts the exact plaintext `size:`. `decrypt_io` stages the
+**ciphertext** inner frame to a mode-0600 temporary file, verifies the AEGIS tag,
+then materialises plaintext and copies content to the caller's output. Decrypt
+APIs default to `required_padding: :from_header`.
 
 ## 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:
+public keys. The application owns and must synchronise the ACL. Any recipient-section
+rewrite therefore receives the **full** list:
 
 ```ruby
+# Remove bob from the *current* copy only — not a cryptographic revocation.
 updated = PQCrypto::Seal.rebuild_recipients(
   sealed,
   with: alice,
@@ -115,9 +118,9 @@ updated = PQCrypto::Seal.rebuild_recipients(
 ```
 
 `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.
+complete current ACL and rebuilds all slots. There is no `drop_recipient_*`
+helper: “drop” names falsely suggest revocation while old copies and the DEK
+remain valid.
 
 ```ruby
 rotated = PQCrypto::Seal.rotate_dek(
@@ -129,11 +132,15 @@ rotated = PQCrypto::Seal.rotate_dek(
 
 `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
+saved envelopes. `rotate_dek` creates a new DEK, a **new payload_id**, 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.
 
+`recipient_capacity` and `slot_size` are immutable for a given payload header.
+To grow either, re-encrypt via `rotate_dek` / `rotate_dek_file` with
+`recipient_capacity:` / `slot_size:` overrides.
+
 ## Wire-format v1
 
 The exact bytes are implemented in `PQCrypto::Seal::Format`:
@@ -187,9 +194,10 @@ The payload-and-section-scoped recipient hint avoids a stable global recipient i
 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.
+The wrapping KEM follows the MLKEM768-X25519/X-Wing construction (draft-10
+wire sizes pinned by suite id 1), targeting approximately 128-bit security.
+ML-KEM-768 supplies conservative margin; the full hybrid suite is not advertised
+as NIST category 3. See `SECURITY.md` for at-rest draft-pinning risk.
 
 ## Envelope identity
 
@@ -213,3 +221,20 @@ 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.
+
+
+## Padding enforcement on decrypt
+
+After AEAD verification, decrypt APIs **default** to
+`required_padding: :from_header`:
+
+- Padmé / none — full canonical size check
+- fixed / buckets — opens with policy-id check only; pass parameters for full
+  target enforcement
+
+```ruby
+PQCrypto::Seal.decrypt(envelope, with: credentials) # :from_header
+PQCrypto::Seal.decrypt(envelope, with: credentials, required_padding: :padme)
+PQCrypto::Seal.decrypt(envelope, with: credentials, required_padding: { to: 4096 })
+PQCrypto::Seal.decrypt(envelope, with: credentials, required_padding: false) # opt out
+```

data/RELEASING.md

@@ -1,15 +1,17 @@
 # Releasing
 
 1. Run `bundle exec ruby script/vendor_libs.rb --check`.
-2. Confirm `pq_crypto` dependency remains `~> 0.6.4` and `WRAP_KEM_ALGORITHM`
+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
+3. Run `bundle exec ruby script/release_contract_check.rb` (also enforced in CI).
+4. Run the full CI matrix: test, sanitize, fuzz, release_contract, gem-smoke.
+5. Build with `gem build pq_crypto-seal.gemspec`.
+6. Re-run the release-contract checker against the built gem path.
+7. 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.
+8. Confirm golden envelope vectors, X-Wing draft-10 KATs, and AEGIS draft-18
+   KATs pass, and that the CI fuzz job is green.
+9. 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

data/SECURITY.md

@@ -1,7 +1,7 @@
 # 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.
+audit. Do not treat version 0.1.2 as a substitute for a reviewed storage design.
 
 Experimental cryptographic software; format v1; not independently audited.
 
@@ -25,10 +25,34 @@ Successful opening does **not** authenticate:
 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.
+### Recipients, ACL ownership, and non-revocation
+
+The envelope is **not** an authoritative ACL. The application must store and
+synchronise the complete recipient public-key list itself. Every recipient-section
+rewrite (`rebuild_recipients` / `add_recipient` and the `*_file` variants)
+requires that full list and only protects the **current canonical copy**.
+
+Rebuilding the recipient section does **not** revoke:
+
+- plaintext already opened by a removed party
+- the DEK (unchanged across rebuilds)
+- older envelope bytes the removed party already copied
+
+`rotate_dek` allocates a new DEK and a new `payload_id`, re-encrypts the payload,
+and still cannot erase knowledge from prior copies. Treat any former recipient
+who retained an old envelope and their secret key as still able to open that old
+copy.
+
+There is intentionally **no** `drop_recipient_*` API: a “drop” name encourages
+the false belief that access was revoked.
+
+### Capacity and slot size
+
+`recipient_capacity` and `slot_size` are stored in the **immutable** payload
+header and are associated-data for the payload AEAD. They cannot change for a
+given encrypted payload without full re-encryption. Use `rotate_dek` /
+`rotate_dek_file` with optional `recipient_capacity:` / `slot_size:` when the
+application needs a larger slot table after authenticating the current payload.
 
 ## Side channels
 
@@ -44,6 +68,28 @@ 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.
 
+
+## payload_id stability
+
+`payload_id` is stable across `rebuild_recipients` / add operations.
+`rotate_dek` re-encrypts the payload with a fresh DEK and **allocates a new
+`payload_id`** — treat the result as a new document identity. Applications that
+need a stable external id across DEK rotation must track it outside the envelope.
+
+## Padding policy enforcement
+
+The authenticated header carries `padding_policy_id`. Decrypt/open APIs default
+to `required_padding: :from_header`:
+
+- Padmé / none — full check of policy id **and** canonical size from
+  authenticated inner lengths
+- fixed / buckets — policy id only (targets are not on the wire); pass
+  `required_padding: { to: N }` or `{ buckets: [...] }` for full target
+  enforcement
+
+Pass `required_padding: false` only when the application deliberately skips
+length-hiding checks.
+
 ## Envelope digests
 
 `Seal.digest` hashes the complete envelope, including the mutable recipient
@@ -65,21 +111,36 @@ unbounded staging or disk amplification before the final AEGIS tag fails.
 
 Applications may raise the limits explicitly when larger objects are required.
 
-## Staging
+## Staging (RUP)
+
+Large decryptions stage the **ciphertext** inner frame in a mode-0600 temporary
+file. On Unix the file is unlinked immediately after opening. Intermediate AEGIS
+streaming plaintext is wiped in memory and is not written to disk until the
+final tag has verified; only then is verified plaintext materialised for
+parsing and publication. Platforms that cannot unlink an open file, filesystem
+snapshots, and storage-layer forensics may still retain remnants (including
+ciphertext); use a suitably protected staging filesystem.
 
-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 and draft risk
 
-## Wire suite pinning
+At-rest envelopes outlive draft documents. Suite identifiers freeze behaviour
+independent of future RFC text:
 
-`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
+| Component | Pin |
+|---|---|
+| `wrap_suite_id = 1` | MLKEM768-X25519 / X-Wing **draft-10** compatible via `pq_crypto = 0.6.4` algorithm `:ml_kem_768_x25519_xwing` (PK 1216, CT 1120, SS 32) |
+| `content_suite_id = 1` | AEGIS-256, 32-byte nonce/tag, inner-frame-v1, via vendored **libaegis 0.10.3** |
+| AEGIS KATs | CFRG AEGIS draft-18 positive/negative vectors in `test/aegis_vectors_test.rb` |
+| X-Wing KATs | draft-10 decapsulation vectors in `test/fixtures/xwing-draft-10-vector-*.json` (see `test/xwing_kat_test.rb`) |
+
+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)`.
 
+If a final RFC diverges from these pins, a new suite id (and migration) is
+required; existing `PQCSEAL1` / suite-1 envelopes remain defined by this pin,
+not by later drafts. Envelope golden vectors in `test/golden_vectors_test.rb`
+are generated under a deterministic RNG to pin **Seal-controlled** layout and
+labels; they are not a substitute for the external KEM/AEAD KATs above.
+
 Report vulnerabilities privately to the repository owner.

data/VENDORING.md

@@ -8,7 +8,20 @@ libaegis 0.10.3.
 - Tag commit: `0bb1639`
 - Official tag archive SHA-256: `2f2682c1d08d9a5510caca1c82e3f8ea91f7085fef2ecbed0c398b2a921c79b1`
 - License: MIT
+- KATs exercised by this gem: CFRG AEGIS draft-18 vectors in
+  `test/aegis_vectors_test.rb` (content suite 1). Wire behaviour is pinned to
+  this snapshot, not to a future RFC that may diverge.
+
+X-Wing / MLKEM768-X25519 wrap suite 1 is supplied by runtime dependency
+`pq_crypto = 0.6.4` (not vendored here). External draft-10 decapsulation KATs
+live in `test/fixtures/xwing-draft-10-vector-*.json`.
 
 The complete source snapshot is retained, while the Ruby extension compiles only the AEGIS-256 and common implementation files it exposes. No system libaegis is
 loaded at runtime. Update the version, archive checksum, source snapshot, KATs,
 and cross-backend tests together.
+
+The git tree keeps the full upstream snapshot so `script/vendor_libs.rb --check`
+can prove byte-identity against the audited archive. The published gem package
+ships only the AEGIS-256 family plus shared `common`/`include` sources required
+to compile the extension (see `pq_crypto-seal.gemspec`); unused families and RAF
+remain in the repository for provenance and are not loaded at runtime.

data/lib/pq_crypto/seal/binary.rb

@@ -3,59 +3,68 @@
 module PQCrypto
   module Seal
     module Binary
-      module_function
+      INTEGER_TYPES = {
+        u8: [1, "C", 0xff],
+        u16: [2, "n", 0xffff],
+        u32: [4, "N", 0xffff_ffff],
+        u64: [8, "Q>", 0xffff_ffff_ffff_ffff]
+      }.freeze
 
-      def u8(value)
-        [integer!(value, 0xff)].pack("C")
-      end
+      class Reader
+        attr_reader :offset
 
-      def u16(value)
-        [integer!(value, 0xffff)].pack("n")
-      end
+        def initialize(bytes, offset = 0)
+          @bytes = String(bytes).b
+          @offset = Integer(offset)
+        end
 
-      def u32(value)
-        [integer!(value, 0xffff_ffff)].pack("N")
-      end
+        INTEGER_TYPES.each do |name, (length, directive, _max)|
+          define_method(name) { bytes(length).unpack1(directive) }
+        end
 
-      def u64(value)
-        [integer!(value, 0xffff_ffff_ffff_ffff)].pack("Q>")
-      end
+        def bytes(length)
+          length = Integer(length)
+          Binary.ensure_available!(@bytes, offset, length)
+          value = @bytes.byteslice(offset, length).b
+          @offset += length
+          value
+        end
 
-      def read_u8(bytes, offset)
-        ensure_available!(bytes, offset, 1)
-        [bytes.getbyte(offset), offset + 1]
+        def finished?
+          offset == @bytes.bytesize
+        end
       end
 
-      def read_u16(bytes, offset)
-        ensure_available!(bytes, offset, 2)
-        [bytes.byteslice(offset, 2).unpack1("n"), offset + 2]
-      end
+      class << self
+        INTEGER_TYPES.each do |name, (_length, directive, max)|
+          define_method(name) { |value| [integer!(value, max)].pack(directive) }
+          define_method("read_#{name}") { |bytes, offset| read_with(bytes, offset, &name) }
+        end
 
-      def read_u32(bytes, offset)
-        ensure_available!(bytes, offset, 4)
-        [bytes.byteslice(offset, 4).unpack1("N"), offset + 4]
-      end
+        def read_bytes(bytes, offset, length)
+          read_with(bytes, offset) { |reader| reader.bytes(length) }
+        end
 
-      def read_u64(bytes, offset)
-        ensure_available!(bytes, offset, 8)
-        [bytes.byteslice(offset, 8).unpack1("Q>"), offset + 8]
-      end
+        def ensure_available!(bytes, offset, length)
+          offset, length = Integer(offset), Integer(length)
 
-      def read_bytes(bytes, offset, length)
-        raise FormatError, "negative length" if length.negative?
-        ensure_available!(bytes, offset, length)
-        [bytes.byteslice(offset, length).b, offset + length]
-      end
+          raise FormatError, "invalid offset" if offset.negative? || length.negative?
+          raise FormatError, "truncated envelope" if offset > bytes.bytesize || length > bytes.bytesize - offset
+        end
 
-      def ensure_available!(bytes, offset, length)
-        raise FormatError, "invalid offset" if offset.negative? || length.negative?
-        raise FormatError, "truncated envelope" if offset > bytes.bytesize || length > bytes.bytesize - offset
-      end
+        def integer!(value, max)
+          number = Integer(value)
+          raise RangeError, "integer is out of range" if number.negative? || number > max
+
+          number
+        end
+
+        private
 
-      def integer!(value, max)
-        number = Integer(value)
-        raise RangeError, "integer is out of range" if number.negative? || number > max
-        number
+        def read_with(bytes, offset)
+          reader = Reader.new(bytes, offset)
+          [yield(reader), reader.offset]
+        end
       end
     end
   end