pq_crypto-seal 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa301e0c50869cf3f9e1fec6924920573f895a4aa3ba9cf66cf63675a1ed0f60
-  data.tar.gz: 73f8cb33894474e63326d0ad43cad5e4e230c4c3050f5e145a7e67e9966ca027
+  metadata.gz: 0e2f25bfc50a4e95892fb3c9e25992ff359bd16cc65535dacf3863d943c34e52
+  data.tar.gz: 40462d41fa188924ba4abbd5d76b4ad22c48377964d70a4544bae919ec4f5140
 SHA512:
-  metadata.gz: 6749ce2e5b6e26d85bf33cd0aa93a4ce82b8fb710bbfc550404551567eab4006649e03f14088cc266786dbc9a6eb358367605eaf1145c6482857c0f6be1ba595
-  data.tar.gz: 61fbbb576c26adb08279357ed800d5245e80d3e6b264992e4afcc7a30972b8fdeae9621fd30bc9a5fcac407d004d72a07925c26e0614cfaaa38e2d504e3d5bf6
+  metadata.gz: 8a3f087d4c922637fcbf5af86cae6a9e118b688215f9a218c6572e524555643e2d444f7452416575c2904f08a8c34742adc0e2cb4bfab6e33a0267015f03d177
+  data.tar.gz: e1746e895c1be25bd755fc358c4eac0291b21c6c638b7d87fb1603e08229783e942adcecbdc4c095e4ae1fde9ca00d49a7f472a89cc1ef183339a94f9546e025

data/CHANGELOG.md

@@ -1,5 +1,44 @@
 # 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`,

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
 
@@ -139,10 +142,13 @@ 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.1+)
+## Receiver-side padding checks (0.1.2+)
 
 `padding_policy_id` is authenticated but does not by itself encode fixed targets
-or bucket lists. Decryptors that need enforcement pass `required_padding:`. The
-receiver verifies the authenticated policy id and recomputes the canonical target
-from the authenticated inner lengths. Fixed and bucket policies require the
-expected target or bucket list from the application.
+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,15 +19,21 @@ 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
 

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.1 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(
@@ -134,6 +137,10 @@ 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
 
@@ -217,15 +225,16 @@ limits.
 
 ## Padding enforcement on decrypt
 
-After AEAD verification you may require a padding policy:
+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: :from_header)
 PQCrypto::Seal.decrypt(envelope, with: credentials, required_padding: { to: 4096 })
+PQCrypto::Seal.decrypt(envelope, with: credentials, required_padding: false) # opt out
 ```
-
-Omitting `required_padding` keeps padding enforcement optional. When supplied,
-the decryptor verifies both the authenticated policy id and the canonical target
-computed from the authenticated content and metadata lengths. Fixed and bucket
-policies require the expected target or bucket list from the application.

data/RELEASING.md

@@ -3,13 +3,15 @@
 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
+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.1 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
 
@@ -47,18 +71,24 @@ responsibility after use.
 
 ## payload_id stability
 
-`payload_id` is stable across `rebuild_recipients` / add / drop operations.
+`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` only. Receivers that require
-a specific length-hiding policy should pass `required_padding:` to decrypt/open
-(for example `required_padding: :padme` or `required_padding: :from_header`).
-The receiver then checks both the policy id and the canonical target computed from
-authenticated inner lengths. Without that argument the field is informational.
+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
 
@@ -81,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 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.
+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.
 
-## Wire suite pinning
+## Wire suite pinning and draft risk
 
-`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
+At-rest envelopes outlive draft documents. Suite identifiers freeze behaviour
+independent of future RFC text:
+
+| 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,6 +8,13 @@ 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,

data/lib/pq_crypto/seal/core.rb

@@ -117,12 +117,15 @@ module PQCrypto
     end
 
     class DekRotator
-      def initialize(envelope, credentials:, recipients:, padding:, limits:)
+      def initialize(envelope, credentials:, recipients:, padding:, limits:,
+                     recipient_capacity: nil, slot_size: nil)
         @envelope = Envelope.parse(envelope, limits: limits)
         @credentials = credentials
         @recipients = recipients
         @padding = padding == :preserve ? { to: @envelope.size } : padding
         @limits = limits
+        @recipient_capacity = recipient_capacity
+        @slot_size = slot_size
       end
 
       def call
@@ -135,14 +138,28 @@ module PQCrypto
           to: @recipients,
           metadata: inner.metadata,
           public_metadata: @envelope.header.public_metadata,
-          recipient_capacity: @envelope.header.recipient_capacity,
-          slot_size: @envelope.header.slot_size,
+          recipient_capacity: capacity_for_reencrypt,
+          slot_size: slot_size_for_reencrypt,
           padding: @padding
         ).call
       ensure
         Secrets.wipe_each!(dek, inner_bytes)
         Secrets.wipe_each!(inner.content, inner.metadata) if inner
       end
+
+      private
+
+      def capacity_for_reencrypt
+        return @envelope.header.recipient_capacity if @recipient_capacity.nil?
+
+        Format.validate_capacity!(@recipient_capacity, KeyMaterial.public_keys(@recipients).length)
+      end
+
+      def slot_size_for_reencrypt
+        return @envelope.header.slot_size if @slot_size.nil?
+
+        Format.validate_slot_size!(@slot_size)
+      end
     end
 
     module_function
@@ -165,11 +182,11 @@ module PQCrypto
       ).call
     end
 
-    def decrypt(envelope, with:, required_padding: nil, **limit_options)
+    def decrypt(envelope, with:, required_padding: :from_header, **limit_options)
       open(envelope, with: with, required_padding: required_padding, **limit_options).data
     end
 
-    def open(envelope, with:, required_padding: nil, **limit_options)
+    def open(envelope, with:, required_padding: :from_header, **limit_options)
       OneShotOpener.new(
         envelope,
         credentials: with,
@@ -204,16 +221,15 @@ module PQCrypto
       )
     end
 
-    def drop_recipient_stanza(envelope, with:, remaining_recipients:, **limit_options)
-      rebuild_recipients(envelope, with: with, recipients: remaining_recipients, **limit_options)
-    end
-
-    def rotate_dek(envelope, with:, recipients:, padding: :preserve, **limit_options)
+    def rotate_dek(envelope, with:, recipients:, padding: :preserve,
+                   recipient_capacity: nil, slot_size: nil, **limit_options)
       DekRotator.new(
         envelope,
         credentials: with,
         recipients: recipients,
         padding: padding,
+        recipient_capacity: recipient_capacity,
+        slot_size: slot_size,
         limits: ResourceLimits.resolve(limit_options)
       ).call
     end
@@ -237,7 +253,7 @@ module PQCrypto
 
     PUBLIC_API = %i[
       credentials encrypt decrypt open inspect_envelope digest
-      rebuild_recipients add_recipient drop_recipient_stanza rotate_dek
+      rebuild_recipients add_recipient rotate_dek
     ].freeze
 
     private_class_method(*(singleton_methods(false).map(&:to_sym) - PUBLIC_API))

data/lib/pq_crypto/seal/files.rb

@@ -53,7 +53,8 @@ module PQCrypto
 
     class FileDekRotator
       def initialize(source, destination, credentials:, recipients:, padding:,
-                     staging_directory:, chunk_size:, limits:)
+                     staging_directory:, chunk_size:, limits:,
+                     recipient_capacity: nil, slot_size: nil)
         @source = source
         @destination = destination
         @credentials = credentials
@@ -62,6 +63,8 @@ module PQCrypto
         @staging_directory = staging_directory
         @chunk_size = IOHelpers.validate_chunk_size(chunk_size)
         @limits = limits
+        @recipient_capacity = recipient_capacity
+        @slot_size = slot_size
       end
 
       def call
@@ -88,6 +91,8 @@ module PQCrypto
       def rotate(verified)
         envelope = verified.stream_envelope
         padding = @padding == :preserve ? { to: envelope.envelope_bytes } : @padding
+        capacity = @recipient_capacity.nil? ? envelope.header.recipient_capacity : @recipient_capacity
+        slot = @slot_size.nil? ? envelope.header.slot_size : @slot_size
         AtomicDestination.new(@destination).write do |output|
           StreamingEncryptor.new(
             verified.content_io,
@@ -96,8 +101,8 @@ module PQCrypto
             to: @recipients,
             metadata: verified.inner.metadata,
             public_metadata: envelope.header.public_metadata,
-            recipient_capacity: envelope.header.recipient_capacity,
-            slot_size: envelope.header.slot_size,
+            recipient_capacity: capacity,
+            slot_size: slot,
             padding: padding,
             chunk_size: @chunk_size,
             strict_size: false

data/lib/pq_crypto/seal/io.rb

@@ -28,7 +28,7 @@ module PQCrypto
 
       def decrypt_io(input, output, with:, staging_directory: nil,
                      chunk_size: DEFAULT_CHUNK_SIZE, strict_eof: true,
-                     required_padding: nil, **limit_options)
+                     required_padding: :from_header, **limit_options)
         StreamingDecryptor.new(
           input,
           output,
@@ -55,7 +55,7 @@ module PQCrypto
       end
 
       def decrypt_file(source, destination, with:, staging_directory: nil,
-                       chunk_size: DEFAULT_CHUNK_SIZE, required_padding: nil,
+                       chunk_size: DEFAULT_CHUNK_SIZE, required_padding: :from_header,
                        **limit_options)
         FileOperations.decrypt(
           source,
@@ -90,13 +90,10 @@ module PQCrypto
         )
       end
 
-      def drop_recipient_stanza_file(source, destination, with:, remaining_recipients:, **options)
-        rebuild_recipients_file(source, destination, with: with, recipients: remaining_recipients, **options)
-      end
-
       def rotate_dek_file(source, destination, with:, recipients:,
                           padding: :preserve, staging_directory: nil,
-                          chunk_size: DEFAULT_CHUNK_SIZE, **limit_options)
+                          chunk_size: DEFAULT_CHUNK_SIZE,
+                          recipient_capacity: nil, slot_size: nil, **limit_options)
         FileDekRotator.new(
           source,
           destination,
@@ -105,6 +102,8 @@ module PQCrypto
           padding: padding,
           staging_directory: staging_directory,
           chunk_size: chunk_size,
+          recipient_capacity: recipient_capacity,
+          slot_size: slot_size,
           limits: ResourceLimits.resolve(limit_options)
         ).call
       end

data/lib/pq_crypto/seal/padding.rb

@@ -114,6 +114,21 @@ module PQCrypto
         end
       end
 
+      class PolicyIdRequirement
+        def initialize(policy_id)
+          @policy_id = Integer(policy_id)
+          freeze
+        end
+
+        def verify!(context)
+          actual = context.header.padding_policy_id
+          return true if actual == @policy_id
+
+          raise FormatError,
+                "header padding_policy_id=#{actual} does not match required policy #{@policy_id}"
+        end
+      end
+
       NONE = NonePolicy.new
       PADME = PadmePolicy.new
       NO_REQUIREMENT = NoRequirement.new.freeze
@@ -127,7 +142,9 @@ module PQCrypto
 
       HEADER_POLICIES = {
         Format::PADDING_NONE => NONE,
-        Format::PADDING_PADME => PADME
+        Format::PADDING_PADME => PADME,
+        Format::PADDING_FIXED => PolicyIdRequirement.new(Format::PADDING_FIXED),
+        Format::PADDING_BUCKETS => PolicyIdRequirement.new(Format::PADDING_BUCKETS)
       }.freeze
 
       module_function
@@ -191,8 +208,7 @@ module PQCrypto
 
       def policy_from_header(policy_id)
         HEADER_POLICIES.fetch(policy_id) do
-          raise InvalidConfigurationError,
-                "required_padding: :from_header cannot verify fixed/buckets without parameters"
+          raise FormatError, "unknown padding_policy_id in header: #{policy_id}"
         end
       end
 

data/lib/pq_crypto/seal/streaming.rb

@@ -186,17 +186,20 @@ module PQCrypto
       end
 
       def call
-        staging = IOHelpers.staging_file("pqcrypto-seal-inner", @staging_directory)
+        ciphertext_staging = IOHelpers.staging_file("pqcrypto-seal-ct", @staging_directory)
         envelope = StreamEnvelope.read(@input, @limits)
         dek = envelope.unwrap_dek(@credentials)
-        decrypt_payload(staging, envelope, dek)
-        staging.flush
-        inner = StagedInner.parse(staging, envelope.header.padded_inner_length)
+        tag = stage_and_authenticate_ciphertext(ciphertext_staging, envelope, dek)
+        plaintext_staging = materialize_verified_plaintext(ciphertext_staging, envelope, dek, tag)
+        IOHelpers.close_tempfile(ciphertext_staging)
+        ciphertext_staging = nil
+        inner = StagedInner.parse(plaintext_staging, envelope.header.padded_inner_length)
         @limits.check_plaintext!(inner.content_length)
-        VerifiedStream.new(staging, envelope, inner, @chunk_size)
+        VerifiedStream.new(plaintext_staging, envelope, inner, @chunk_size)
       rescue StandardError
         Secrets.wipe!(inner.metadata) if inner
-        IOHelpers.close_tempfile(staging) if staging
+        IOHelpers.close_tempfile(plaintext_staging) if plaintext_staging
+        IOHelpers.close_tempfile(ciphertext_staging) if ciphertext_staging
         raise
       ensure
         Secrets.wipe!(dek)
@@ -204,10 +207,33 @@ module PQCrypto
 
       private
 
-      def decrypt_payload(staging, envelope, dek)
-        envelope.stream_verified_payload(@input, dek, @chunk_size, strict_eof: @strict_eof) do |_ciphertext, plaintext|
-          IOHelpers.write_all(staging, plaintext)
+      def stage_and_authenticate_ciphertext(staging, envelope, dek)
+        envelope.stream_verified_payload(@input, dek, @chunk_size, strict_eof: @strict_eof) do |ciphertext, _plaintext|
+          IOHelpers.write_all(staging, ciphertext)
+        end
+      end
+
+      def materialize_verified_plaintext(ciphertext_staging, envelope, dek, tag)
+        staging = IOHelpers.staging_file("pqcrypto-seal-inner", @staging_directory)
+        decryptor = Native::Decryptor.new(dek, envelope.header.payload_nonce, envelope.header_hash)
+        ciphertext_staging.rewind
+        message = { message: "staged ciphertext is truncated" }
+        IOHelpers.each_exact_chunk(
+          ciphertext_staging, envelope.header.padded_inner_length, @chunk_size, **message
+        ) do |ciphertext|
+          plaintext = decryptor.update(ciphertext)
+          begin
+            IOHelpers.write_all(staging, plaintext)
+          ensure
+            Secrets.wipe!(plaintext)
+          end
         end
+        decryptor.final(tag)
+        staging.flush
+        staging
+      rescue StandardError
+        IOHelpers.close_tempfile(staging) if staging
+        raise
       end
     end
 

data/lib/pq_crypto/seal/version.rb

@@ -2,6 +2,6 @@
 
 module PQCrypto
   module Seal
-    VERSION = "0.1.1"
+    VERSION = "0.1.2"
   end
 end

data/lib/pq_crypto/seal.rb

@@ -23,7 +23,7 @@ module PQCrypto
     IO_DELEGATES = %i[
       encrypt_io decrypt_io encrypt_frame_io decrypt_frame_io
       encrypt_file decrypt_file rebuild_recipients_file
-      add_recipient_file drop_recipient_stanza_file rotate_dek_file
+      add_recipient_file rotate_dek_file
       inspect_file
     ].freeze
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pq_crypto-seal
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Roman Khaidarov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-20 00:00:00.000000000 Z
+date: 2026-07-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pq_crypto