foil-server 0.3.3

data/spec/sealed-token.md

@@ -0,0 +1,114 @@
+# Sealed Token Specification
+
+Foil sealed tokens are encrypted server handoff payloads returned by `Foil.getSession()`.
+
+This document is the language-agnostic contract for verifying those tokens in public server SDKs.
+
+## Overview
+
+- Input: a base64-encoded sealed token string
+- Output: a JSON payload describing the verified Foil session decision for the current action
+- Confidentiality and integrity: AES-256-GCM
+- Compression: zlib deflate/inflate
+
+## Payload format
+
+After base64 decoding, the 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`.
+
+## Secret normalization
+
+The verifier accepts either:
+
+- a plaintext Foil secret key, such as `sk_live_...`
+- or the corresponding lowercase SHA-256 hex digest
+
+Normalization rules:
+
+- If the supplied secret matches `/^[0-9a-f]{64}$/i`, treat it as the secret hash and lowercase it
+- Otherwise compute the SHA-256 hex digest of the supplied secret key
+
+## Key derivation
+
+Derive the AES key as:
+
+- `sha256(normalized_secret + "\0sealed-results")`
+
+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
+
+Any failure in decoding, parsing, authentication, decompression, or JSON parsing must be treated as verification failure.
+
+## Payload shape
+
+The decrypted JSON payload currently includes:
+
+- `object`
+- `session_id`
+- `decision`
+- `request`
+- `visitor_fingerprint`
+- `signals`
+- `score_breakdown`
+- `attribution`
+- `embed`
+
+The payload is aligned to the same public vocabulary as the Sessions API:
+
+- `decision`
+  - `event_id`
+  - `verdict`
+  - `risk_score`
+  - `phase`
+  - `is_provisional`
+  - `manipulation`
+  - `evaluation_duration_ms`
+  - `evaluated_at`
+- `request`
+  - `url`
+  - `user_agent`
+  - `ip_address`
+  - `screen_size`
+  - `is_touch_capable`
+- `visitor_fingerprint`
+  - `object`
+  - `id`
+  - `confidence`
+  - `identified_at`
+- `score_breakdown`
+  - `categories`
+- `attribution`
+  - `bot`
+
+Public SDKs should treat the payload as forward-compatible:
+
+- preserve unknown fields
+- do not require fields beyond the documented stable surface
+
+## Fixtures
+
+Golden vectors live under `fixtures/sealed-token/`.
+
+Every language SDK must verify the shared vectors successfully and reject the invalid vectors it ships with.

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: foil-server
+version: !ruby/object:Gem::Version
+  version: 0.3.3
+platform: ruby
+authors:
+- ABXY Labs
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-22 00:00:00.000000000 Z
+dependencies: []
+description: Customer-facing Ruby SDK for Foil Sessions, Fingerprints, Organizations,
+  and sealed token verification.
+email:
+- support@usefoil.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/foil/server.rb
+- lib/foil/server/client.rb
+- lib/foil/server/crypto_support.rb
+- lib/foil/server/errors.rb
+- lib/foil/server/gate_delivery.rb
+- lib/foil/server/sealed_token.rb
+- lib/foil/server/types.rb
+- lib/foil/server/version.rb
+- spec/LICENSE
+- spec/README.md
+- spec/fixtures/api/fingerprints/detail.json
+- spec/fixtures/api/fingerprints/list.json
+- spec/fixtures/api/gate/agent-token-revoke.json
+- spec/fixtures/api/gate/agent-token-verify.json
+- spec/fixtures/api/gate/login-session-consume.json
+- spec/fixtures/api/gate/login-session-create.json
+- spec/fixtures/api/gate/registry-detail.json
+- spec/fixtures/api/gate/registry-list.json
+- spec/fixtures/api/gate/service-create.json
+- spec/fixtures/api/gate/service-detail.json
+- spec/fixtures/api/gate/service-disable.json
+- spec/fixtures/api/gate/service-update.json
+- spec/fixtures/api/gate/services-list.json
+- spec/fixtures/api/gate/session-ack.json
+- spec/fixtures/api/gate/session-create.json
+- spec/fixtures/api/gate/session-poll.json
+- spec/fixtures/api/organizations/api-key-create.json
+- spec/fixtures/api/organizations/api-key-list.json
+- spec/fixtures/api/organizations/api-key-revoke.json
+- spec/fixtures/api/organizations/api-key-rotate.json
+- spec/fixtures/api/organizations/api-key-update.json
+- spec/fixtures/api/organizations/organization-create.json
+- spec/fixtures/api/organizations/organization-update.json
+- spec/fixtures/api/organizations/organization.json
+- spec/fixtures/api/sessions/detail.json
+- spec/fixtures/api/sessions/list.json
+- spec/fixtures/errors/invalid-api-key.json
+- spec/fixtures/errors/missing-api-key.json
+- spec/fixtures/errors/not-found.json
+- spec/fixtures/errors/validation-error.json
+- spec/fixtures/gate-delivery/approved-webhook-payload.valid.json
+- spec/fixtures/gate-delivery/delivery-request.json
+- spec/fixtures/gate-delivery/env-policy.json
+- spec/fixtures/gate-delivery/vector.v1.json
+- spec/fixtures/gate-delivery/webhook-signature.json
+- spec/fixtures/manifest.json
+- spec/fixtures/sealed-token/invalid.json
+- spec/fixtures/sealed-token/vector.v1.json
+- spec/openapi.json
+- spec/sealed-token.md
+homepage: https://github.com/abxy-labs/foil-server-ruby
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Official Foil Ruby server SDK
+test_files: []