foil-server 0.3.4 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da4f138fa11fe95c669393d0cc561cae5579e63566cb76eea6ce39af012f84f3
-  data.tar.gz: dc77719ea3fbc1ee8e5e4bf6473ef23cdc07be49184849573a197821b7e6b720
+  metadata.gz: 5d41b78e23e89f77b68f871a2454fb7d3ee87828a66e76fc95c6baca12127ff2
+  data.tar.gz: ba257476579665aa554305f16a98793b5a9b98726d90784c5d5ae4b643ba04e2
 SHA512:
-  metadata.gz: 8a0baeff8b13ea7756aac49c718d241951d5affe0f5680bec246ce7ee4c6b204c220e5e5ff26060c24f003f954065cc0560c41def17da3aeaa2fb2af22c83e87
-  data.tar.gz: 16fd177450ade1814ca13c381ba01545a07347f1d0fdfada56e43e8a40f893d2d3303715a4af1369d2b682f1be75bc1f51f3b9ba1dc7687b8fcc1a1e894929e4
+  metadata.gz: 5a979d1b334c0c7331fcd3f174b3ddece6f371d200ee7cd4ffe4287b8e651cadada1ae15cc495b14c849e290de9384ab53cc826c80e5d5e49b4ae56fde1659d3
+  data.tar.gz: 70a38a2b6466c9e184b67629e9d45cdce7d620e032737d8c5cad9d6c96eba590c7a58b80ed22573b976ae1fb2ebad215e70f9edfea8cee6f0f9bf0eb65784f85

data/lib/foil/server/sealed_token.rb

@@ -7,7 +7,17 @@ require "zlib"
 module Foil
   module Server
     module SealedToken
-      VERSION = 0x01
+      LEGACY_VERSION = 0x01
+      MULTI_RECIPIENT_VERSION = 0x02
+      NONCE_BYTES = 12
+      TAG_BYTES = 16
+      CONTENT_KEY_BYTES = 32
+      RECIPIENT_ID_BYTES = 32
+      MAX_RECIPIENTS = 256
+      V2_HEADER_BYTES = 1 + 2 + NONCE_BYTES + 4
+      V2_RECIPIENT_BYTES = RECIPIENT_ID_BYTES + NONCE_BYTES + CONTENT_KEY_BYTES + TAG_BYTES
+      V2_PAYLOAD_AAD_PREFIX = "foil-sealed-results-v2\0payload\0".b
+      V2_WRAP_AAD_PREFIX = "foil-sealed-results-v2\0recipient\0".b
 
       module_function
 
@@ -19,21 +29,7 @@ module Foil
         raw = Base64.decode64(sealed_token)
         raise TokenVerificationError, "Foil token is too short." if raw.bytesize < 29
 
-        version = raw.getbyte(0)
-        raise TokenVerificationError, "Unsupported Foil token version: #{version}" if version != VERSION
-
-        nonce = raw.byteslice(1, 12)
-        ciphertext = raw.byteslice(13, raw.bytesize - 29)
-        tag = raw.byteslice(raw.bytesize - 16, 16)
-
-        cipher = OpenSSL::Cipher.new("aes-256-gcm")
-        cipher.decrypt
-        cipher.key = derive_key(resolved_secret)
-        cipher.iv = nonce
-        cipher.auth_tag = tag
-        cipher.auth_data = ""
-
-        compressed = cipher.update(ciphertext) + cipher.final
+        compressed = decrypt_payload(raw, resolved_secret)
         payload = JSON.parse(Zlib::Inflate.inflate(compressed))
         deep_symbolize(payload)
       rescue ConfigurationError, TokenVerificationError
@@ -53,6 +49,77 @@ module Foil
       end
       private_class_method :derive_key
 
+      def decrypt_gcm(ciphertext, key, nonce, tag, aad = "".b)
+        cipher = OpenSSL::Cipher.new("aes-256-gcm")
+        cipher.decrypt
+        cipher.key = key
+        cipher.iv = nonce
+        cipher.auth_tag = tag
+        cipher.auth_data = aad
+        cipher.update(ciphertext) + cipher.final
+      end
+      private_class_method :decrypt_gcm
+
+      def decrypt_payload(raw, secret_key)
+        version = raw.getbyte(0)
+        if version == LEGACY_VERSION
+          return decrypt_gcm(
+            raw.byteslice(13, raw.bytesize - 29),
+            derive_key(secret_key),
+            raw.byteslice(1, NONCE_BYTES),
+            raw.byteslice(raw.bytesize - TAG_BYTES, TAG_BYTES)
+          )
+        end
+        raise TokenVerificationError, "Unsupported Foil token version: #{version}" unless version == MULTI_RECIPIENT_VERSION
+        raise TokenVerificationError, "Foil token is too short." if raw.bytesize < V2_HEADER_BYTES + TAG_BYTES + V2_RECIPIENT_BYTES
+
+        recipient_count = raw.byteslice(1, 2).unpack1("n")
+        raise TokenVerificationError, "Foil token has an invalid recipient count." unless recipient_count.between?(1, MAX_RECIPIENTS)
+
+        payload_length = raw.byteslice(15, 4).unpack1("N")
+        payload_start = V2_HEADER_BYTES
+        payload_tag_start = payload_start + payload_length
+        recipients_start = payload_tag_start + TAG_BYTES
+        expected_length = recipients_start + (recipient_count * V2_RECIPIENT_BYTES)
+        raise TokenVerificationError, "Foil token has an invalid length." if payload_length < 1 || expected_length != raw.bytesize
+
+        expected_id = Digest::SHA256.digest("#{normalize_secret(secret_key)}\0sealed-results-recipient-id")
+        recipient_ids = recipient_count.times.map do |index|
+          raw.byteslice(
+            recipients_start + (index * V2_RECIPIENT_BYTES),
+            RECIPIENT_ID_BYTES
+          )
+        end.join
+        content_key = nil
+        recipient_count.times do |index|
+          entry_start = recipients_start + (index * V2_RECIPIENT_BYTES)
+          recipient_id = raw.byteslice(entry_start, RECIPIENT_ID_BYTES)
+          next unless OpenSSL.fixed_length_secure_compare(recipient_id, expected_id)
+
+          nonce_start = entry_start + RECIPIENT_ID_BYTES
+          wrapped_key_start = nonce_start + NONCE_BYTES
+          tag_start = wrapped_key_start + CONTENT_KEY_BYTES
+          content_key = decrypt_gcm(
+            raw.byteslice(wrapped_key_start, CONTENT_KEY_BYTES),
+            derive_key(secret_key),
+            raw.byteslice(nonce_start, NONCE_BYTES),
+            raw.byteslice(tag_start, TAG_BYTES),
+            V2_WRAP_AAD_PREFIX + recipient_id
+          )
+          break
+        end
+        raise TokenVerificationError, "Secret key is not a recipient of this Foil token." unless content_key&.bytesize == CONTENT_KEY_BYTES
+
+        decrypt_gcm(
+          raw.byteslice(payload_start, payload_length),
+          content_key,
+          raw.byteslice(3, NONCE_BYTES),
+          raw.byteslice(payload_tag_start, TAG_BYTES),
+          V2_PAYLOAD_AAD_PREFIX + raw.byteslice(0, V2_HEADER_BYTES) + recipient_ids
+        )
+      end
+      private_class_method :decrypt_payload
+
       def normalize_secret(secret_key_or_hash)
         return secret_key_or_hash.downcase if /\A[0-9a-fA-F]{64}\z/.match?(secret_key_or_hash)
 

data/lib/foil/server/version.rb

@@ -1,5 +1,5 @@
 module Foil
   module Server
-    VERSION = "0.3.4".freeze
+    VERSION = "0.3.5".freeze
   end
 end

data/spec/fixtures/sealed-token/vector.v2.json

@@ -0,0 +1,59 @@
+{
+  "secretKeys": [
+    "sk_live_fixture_secret",
+    "sk_live_fixture_secondary"
+  ],
+  "secretHashes": [
+    "c173e2c1467e446744e3b6aba8fc07e639008fdf3c4b82e32dceef9b41217dc3",
+    "7b7f1904e9f78f93fdaf5cb739b84a549f379774dce8e48d2e7318a38a71619d"
+  ],
+  "token": "AgACkGnTY6/gdAPOSejTAAABueItTz8WCgMBzOUeaG8XiLTGYNZ6/n+XKodAEavsB4nr/HXdLMPNin6k99VSMt4pm7xQDgq00NHf4pcUX98bVtrD9McjaPVhN0PQOcbwBncRqEXPQDLvdevFp6SvNcThP7F0LNnCN4WikARAYD/5hoJcfi3qpehcDRxIkFWXy9Rn5D7WnSAY1Ef2/2v3wT/aP2D89xjs9xIGmavfGNJaUq3eXRMdddQYaB1V5wtmRBZIkgePubsbcCptBtgma3ZObp5A8cdb9PQFvNxBR/B2ttKupMQ/uiVN05/RNPHziKm+aada8+gPwRJR8PDNbNy/TEA8L82iB8LgCMmPnqyVefqm+VoNYa/AmDefcWrBogQ7lIB49KezbRiXIbZ5RiAPq2VgqUTHq2cRAN6BprH89g2FajBs5I7wj7nTQwtPu74FRu3BRHF9k8Vgf4A4jdocn4sU/GCH5Gm1x7d1Rxd8T4OkyQtJ1YaRLwksf/lkttqoOD+fZ3twJxXtYKVKt0wmavVlMUl5+IP3Yrl8SdfmGENMyfkjjuhfPq/TpA00PDoB4RXf2MAh6fTVF+sVw7vXndQ8tYMLFjBgLx2y++W6LT+glvHhROf3LWnk3EgrhhB6FxEpmfuogp2y3pZ8fkMaKplOFFfw0AnVDRbCqx+0u6P9JiQmV0hUl4LHn7rqPNPbtv7adX778RptvMjWG87rwFiU/whhVWbIoF4P0W8081lVDTEe9V3LRNd9t7U9Ca/pIowEzXe5X5rWrlqm/CtCYLzT6apTMLXuacGYBJY7VfY+8uXG0WymZ8GfcMUrFpvF8bwPMs0nPaq3i1Jm+zVy9QMz9pl6xTKwN2CwfIFeHOp8",
+  "payload": {
+    "object": "session_verification",
+    "session_id": "sid_0123456789abcdefghjkmnpqrs",
+    "decision": {
+      "event_id": "evt_0123456789abcdefghjkmnpqrs",
+      "verdict": "human",
+      "risk_score": 7,
+      "phase": "behavioral",
+      "is_provisional": false,
+      "manipulation": {
+        "score": 0,
+        "verdict": "none"
+      },
+      "evaluation_duration_ms": 123,
+      "evaluated_at": "2026-03-24T20:00:00.000Z"
+    },
+    "request": {
+      "user_agent": "Mozilla/5.0",
+      "url": "https://example.com/signup",
+      "screen_size": "1440x900",
+      "is_touch_capable": false,
+      "ip_address": "203.0.113.9"
+    },
+    "visitor_fingerprint": {
+      "object": "visitor_fingerprint",
+      "id": "vid_0123456789abcdefghjkmnpqrs",
+      "confidence": 94,
+      "identified_at": "2026-03-24T19:59:59.000Z"
+    },
+    "signals": [
+      {
+        "id": "E6",
+        "category": "environment",
+        "confidence": "strong",
+        "score": 20
+      }
+    ],
+    "score_breakdown": {
+      "categories": {
+        "behavioral": 9,
+        "environment": 20
+      }
+    },
+    "attribution": {
+      "bot": null
+    },
+    "embed": null
+  }
+}

data/spec/sealed-token.md

@@ -11,20 +11,44 @@ This document is the language-agnostic contract for verifying those tokens in pu
 - Confidentiality and integrity: AES-256-GCM
 - Compression: zlib deflate/inflate
 
-## Payload format
+## Payload formats
 
-After base64 decoding, the byte layout is:
+After base64 decoding, use the first byte to select the token version. Reject
+any version other than `0x01` or `0x02`.
+
+### Version `0x01`
+
+The legacy single-recipient byte layout is:
 
 - `version` - 1 byte
 - `nonce` - 12 bytes
 - `ciphertext` - variable length
 - `tag` - 16 bytes
 
-Current version:
-
-- `0x01`
-
-Reject any token whose version byte is not `0x01`.
+### Version `0x02`
+
+The multi-recipient envelope used for independently issued and rotating secret
+keys has this byte layout:
+
+- `version` - 1 byte (`0x02`)
+- `recipient_count` - unsigned 16-bit big-endian integer, 1 through 256
+- `payload_nonce` - 12 bytes
+- `payload_ciphertext_length` - unsigned 32-bit big-endian integer
+- `payload_ciphertext` - zlib-compressed JSON encrypted with a random 32-byte content key
+- `payload_tag` - 16 bytes
+- one fixed-size recipient entry per recipient:
+  - `recipient_id` - `sha256(UTF8(normalized_secret) || 0x00 || UTF8("sealed-results-recipient-id"))`; `0x00` is one NUL byte, and this domain-separated identifier must never expose `normalized_secret`
+  - `wrap_nonce` - 12 bytes
+  - `wrapped_content_key` - 32 bytes
+  - `wrap_tag` - 16 bytes
+
+The payload cipher authenticates
+`UTF8("foil-sealed-results-v2") || 0x00 || UTF8("payload") || 0x00 || header || ordered_recipient_ids`
+as AAD, where each `0x00` is one NUL byte. This binds the complete recipient
+set to the payload. Each content-key wrapper uses the existing derived token key
+and authenticates
+`UTF8("foil-sealed-results-v2") || 0x00 || UTF8("recipient") || 0x00 || recipient_id`
+as AAD.
 
 ## Secret normalization
 
@@ -42,22 +66,27 @@ Normalization rules:
 
 Derive the AES key as:
 
-- `sha256(normalized_secret + "\0sealed-results")`
+- `sha256(UTF8(normalized_secret) || 0x00 || UTF8("sealed-results"))`, where `0x00` is one NUL byte
 
 Use the raw 32-byte digest as the AES-256-GCM key.
 
 ## Verification steps
 
-1. Base64 decode the token
-2. Parse the version byte, nonce, ciphertext, and tag
-3. Normalize the caller's secret material
-4. Derive the AES-256-GCM key
-5. Decrypt using:
-   - algorithm: `aes-256-gcm`
-   - nonce: parsed 12-byte nonce
-   - tag: parsed 16-byte authentication tag
-6. Inflate the decrypted bytes with zlib
-7. Parse the inflated UTF-8 JSON payload
+1. Base64 decode the token.
+2. Parse the version byte.
+3. Normalize the caller's secret material and derive the AES-256-GCM token key.
+4. For version `0x01`:
+   - parse the 12-byte nonce, ciphertext, and 16-byte authentication tag
+   - decrypt the ciphertext with the derived token key, parsed nonce, and tag
+5. For version `0x02`:
+   - parse and bounds-check the header, payload ciphertext, payload tag, and exactly `recipient_count` fixed-size recipient entries
+   - compute the caller's `recipient_id` and select its matching entry; reject the token if no entry matches
+   - build the wrapper AAD from the fixed prefix, NUL separators, and matching `recipient_id`
+   - decrypt `wrapped_content_key` with the derived token key, matching `wrap_nonce`, `wrap_tag`, and wrapper AAD
+   - concatenate every recipient entry's `recipient_id` in encoded order and build the payload AAD from the fixed prefix, NUL separators, encoded header, and ordered IDs
+   - decrypt `payload_ciphertext` with the unwrapped 32-byte content key, `payload_nonce`, `payload_tag`, and payload AAD
+6. Inflate the decrypted payload bytes with zlib.
+7. Parse the inflated UTF-8 JSON payload.
 
 Any failure in decoding, parsing, authentication, decompression, or JSON parsing must be treated as verification failure.
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: foil-server
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.3.5
 platform: ruby
 authors:
 - ABXY Labs
@@ -68,6 +68,7 @@ files:
 - spec/fixtures/manifest.json
 - spec/fixtures/sealed-token/invalid.json
 - spec/fixtures/sealed-token/vector.v1.json
+- spec/fixtures/sealed-token/vector.v2.json
 - spec/openapi.json
 - spec/sealed-token.md
 homepage: https://github.com/abxy-labs/foil-server-ruby