foil-server 0.3.3

data/lib/foil/server/errors.rb

@@ -0,0 +1,21 @@
+module Foil
+  module Server
+    class ConfigurationError < StandardError; end
+
+    class TokenVerificationError < StandardError; end
+
+    class ApiError < StandardError
+      attr_reader :status, :code, :request_id, :field_errors, :docs_url, :body
+
+      def initialize(status:, code:, message:, request_id: nil, field_errors: [], docs_url: nil, body: nil)
+        super(message)
+        @status = status
+        @code = code
+        @request_id = request_id
+        @field_errors = field_errors
+        @docs_url = docs_url
+        @body = body
+      end
+    end
+  end
+end

data/lib/foil/server/gate_delivery.rb

@@ -0,0 +1,325 @@
+require "base64"
+require "digest"
+require "json"
+require "openssl"
+
+module Foil
+  module Server
+    module GateDelivery
+      GATE_DELIVERY_VERSION = 1
+      GATE_DELIVERY_ALGORITHM = "x25519-hkdf-sha256/aes-256-gcm"
+      GATE_AGENT_TOKEN_ENV_SUFFIX = "_GATE_AGENT_TOKEN"
+      BLOCKED_GATE_ENV_VAR_KEYS = %w[
+        BASH_ENV
+        BROWSER
+        CDPATH
+        DYLD_INSERT_LIBRARIES
+        DYLD_LIBRARY_PATH
+        EDITOR
+        ENV
+        GIT_ASKPASS
+        GIT_SSH_COMMAND
+        HOME
+        LD_LIBRARY_PATH
+        LD_PRELOAD
+        NODE_OPTIONS
+        NODE_PATH
+        PATH
+        PERL5OPT
+        PERLLIB
+        PROMPT_COMMAND
+        PYTHONHOME
+        PYTHONPATH
+        PYTHONSTARTUP
+        RUBYLIB
+        RUBYOPT
+        SHELLOPTS
+        SSH_ASKPASS
+        VISUAL
+        XDG_CONFIG_HOME
+      ].freeze
+      BLOCKED_GATE_ENV_VAR_PREFIXES = %w[NPM_CONFIG_ BUN_CONFIG_ GIT_CONFIG_].freeze
+      WEBHOOK_EVENT_TYPES = %w[
+        session.fingerprint.calculated
+        session.result.persisted
+        gate.session.approved
+        webhook.test
+      ].freeze
+      GATE_DELIVERY_HKDF_INFO = "foil-gate-delivery:v1".b.freeze
+      X25519_SPKI_PREFIX = ["302a300506032b656e032100"].pack("H*").freeze
+
+      module_function
+
+      def derive_gate_agent_token_env_key(service_id)
+        normalized = service_id.to_s.strip.gsub(/[^A-Za-z0-9]+/, "_").gsub(/^_+|_+$/, "").gsub(/_+/, "_").upcase
+        raise ArgumentError, "service_id is required to derive a Gate agent token env key" if normalized.empty?
+
+        return "FOIL#{GATE_AGENT_TOKEN_ENV_SUFFIX}" if ["FOIL", "FOIL"].include?(normalized)
+
+        "#{normalized}#{GATE_AGENT_TOKEN_ENV_SUFFIX}"
+      end
+
+      def is_gate_managed_env_var_key(key)
+        key == "FOIL_AGENT_TOKEN" || key.to_s.end_with?(GATE_AGENT_TOKEN_ENV_SUFFIX)
+      end
+
+      def is_blocked_gate_env_var_key(key)
+        normalized = key.to_s.strip.upcase
+        BLOCKED_GATE_ENV_VAR_KEYS.include?(normalized) || BLOCKED_GATE_ENV_VAR_PREFIXES.any? { |prefix| normalized.start_with?(prefix) }
+      end
+
+      def raw_x25519_public_key_from_key_object(public_key)
+        der = public_key.public_to_der
+        raise ArgumentError, "Unexpected X25519 public key encoding" unless der.bytesize == X25519_SPKI_PREFIX.bytesize + 32
+        raise ArgumentError, "Unexpected X25519 public key prefix" unless der.byteslice(0, X25519_SPKI_PREFIX.bytesize) == X25519_SPKI_PREFIX
+
+        der.byteslice(X25519_SPKI_PREFIX.bytesize, 32)
+      end
+
+      def key_id_for_raw_x25519_public_key(raw_public_key)
+        raise ArgumentError, "X25519 public key must be 32 bytes" unless raw_public_key.bytesize == 32
+
+        Base64.urlsafe_encode64(Digest::SHA256.digest(raw_public_key), padding: false)
+      end
+
+      def create_delivery_key_pair
+        CryptoSupport.ensure_supported_runtime!
+        private_key = OpenSSL::PKey.generate_key("X25519")
+        raw_public_key = raw_x25519_public_key_from_key_object(private_key.public_key)
+        {
+          delivery: {
+            version: GATE_DELIVERY_VERSION,
+            algorithm: GATE_DELIVERY_ALGORITHM,
+            key_id: key_id_for_raw_x25519_public_key(raw_public_key),
+            public_key: Base64.urlsafe_encode64(raw_public_key, padding: false)
+          },
+          private_key: private_key
+        }
+      end
+
+      def export_delivery_private_key_pkcs8(private_key)
+        CryptoSupport.ensure_supported_runtime!
+        Base64.urlsafe_encode64(private_key.private_to_der, padding: false)
+      end
+
+      def import_delivery_private_key_pkcs8(value)
+        CryptoSupport.ensure_supported_runtime!
+        OpenSSL::PKey.read(b64url_decode(value, "delivery.private_key_pkcs8"))
+      end
+
+      def validate_gate_delivery_request(value)
+        candidate = symbolize(value)
+        raise ArgumentError, "delivery.version must be 1" unless candidate[:version] == GATE_DELIVERY_VERSION
+        raise ArgumentError, "delivery.algorithm must be #{GATE_DELIVERY_ALGORITHM}" unless candidate[:algorithm] == GATE_DELIVERY_ALGORITHM
+        raise ArgumentError, "delivery.public_key is required" if candidate[:public_key].to_s.empty?
+        raise ArgumentError, "delivery.key_id is required" if candidate[:key_id].to_s.empty?
+
+        raw_public_key = b64url_decode(candidate[:public_key], "delivery.public_key")
+        raise ArgumentError, "delivery.public_key must be a raw X25519 public key" unless raw_public_key.bytesize == 32
+        raise ArgumentError, "delivery.key_id does not match delivery.public_key" unless key_id_for_raw_x25519_public_key(raw_public_key) == candidate[:key_id]
+
+        {
+          version: GATE_DELIVERY_VERSION,
+          algorithm: GATE_DELIVERY_ALGORITHM,
+          key_id: candidate[:key_id],
+          public_key: candidate[:public_key]
+        }
+      end
+
+      def create_encrypted_delivery_response(input)
+        {
+          encrypted_delivery: encrypt_gate_delivery_payload(
+            input.fetch(:delivery),
+            {
+              version: GATE_DELIVERY_VERSION,
+              outputs: input.fetch(:outputs)
+            }
+          )
+        }
+      end
+
+      def create_gate_approved_webhook_response(input)
+        create_encrypted_delivery_response(input)
+      end
+
+      def validate_encrypted_gate_delivery_envelope(value)
+        candidate = symbolize(value)
+        raise ArgumentError, "encrypted_delivery.version must be 1" unless candidate[:version] == GATE_DELIVERY_VERSION
+        raise ArgumentError, "encrypted_delivery.algorithm must be #{GATE_DELIVERY_ALGORITHM}" unless candidate[:algorithm] == GATE_DELIVERY_ALGORITHM
+        %i[key_id ephemeral_public_key salt iv ciphertext tag].each do |field|
+          raise ArgumentError, "encrypted_delivery.#{field} is required" if candidate[field].to_s.empty?
+        end
+        raise ArgumentError, "encrypted_delivery.ephemeral_public_key must be 32 bytes" unless b64url_decode(candidate[:ephemeral_public_key], "encrypted_delivery.ephemeral_public_key").bytesize == 32
+        raise ArgumentError, "encrypted_delivery.salt must be 32 bytes" unless b64url_decode(candidate[:salt], "encrypted_delivery.salt").bytesize == 32
+        raise ArgumentError, "encrypted_delivery.iv must be 12 bytes" unless b64url_decode(candidate[:iv], "encrypted_delivery.iv").bytesize == 12
+        raise ArgumentError, "encrypted_delivery.tag must be 16 bytes" unless b64url_decode(candidate[:tag], "encrypted_delivery.tag").bytesize == 16
+
+        candidate
+      end
+
+      def encrypt_gate_delivery_payload(delivery, payload)
+        CryptoSupport.ensure_supported_runtime!
+        validated_delivery = validate_gate_delivery_request(delivery)
+        payload = symbolize(payload)
+        raise ArgumentError, "Gate delivery payload version must be 1" unless payload[:version] == GATE_DELIVERY_VERSION
+
+        recipient_public_key = OpenSSL::PKey.read(X25519_SPKI_PREFIX + b64url_decode(validated_delivery[:public_key], "delivery.public_key"))
+        ephemeral_private_key = OpenSSL::PKey.generate_key("X25519")
+        shared_secret = ephemeral_private_key.derive(recipient_public_key)
+        salt = OpenSSL::Random.random_bytes(32)
+        iv = OpenSSL::Random.random_bytes(12)
+        key = OpenSSL::KDF.hkdf(shared_secret, salt: salt, info: GATE_DELIVERY_HKDF_INFO, length: 32, hash: "SHA256")
+
+        cipher = OpenSSL::Cipher.new("aes-256-gcm")
+        cipher.encrypt
+        cipher.key = key
+        cipher.iv = iv
+        ciphertext = cipher.update(JSON.generate(compact_payload(payload))) + cipher.final
+        tag = cipher.auth_tag
+
+        {
+          version: GATE_DELIVERY_VERSION,
+          algorithm: GATE_DELIVERY_ALGORITHM,
+          key_id: validated_delivery[:key_id],
+          ephemeral_public_key: Base64.urlsafe_encode64(raw_x25519_public_key_from_key_object(ephemeral_private_key.public_key), padding: false),
+          salt: Base64.urlsafe_encode64(salt, padding: false),
+          iv: Base64.urlsafe_encode64(iv, padding: false),
+          ciphertext: Base64.urlsafe_encode64(ciphertext, padding: false),
+          tag: Base64.urlsafe_encode64(tag, padding: false)
+        }
+      end
+
+      def decrypt_gate_delivery_envelope(private_key, envelope)
+        CryptoSupport.ensure_supported_runtime!
+        validated = validate_encrypted_gate_delivery_envelope(envelope)
+        shared_secret = private_key.derive(
+          OpenSSL::PKey.read(X25519_SPKI_PREFIX + b64url_decode(validated[:ephemeral_public_key], "encrypted_delivery.ephemeral_public_key"))
+        )
+        key = OpenSSL::KDF.hkdf(
+          shared_secret,
+          salt: b64url_decode(validated[:salt], "encrypted_delivery.salt"),
+          info: GATE_DELIVERY_HKDF_INFO,
+          length: 32,
+          hash: "SHA256"
+        )
+        cipher = OpenSSL::Cipher.new("aes-256-gcm")
+        cipher.decrypt
+        cipher.key = key
+        cipher.iv = b64url_decode(validated[:iv], "encrypted_delivery.iv")
+        cipher.auth_tag = b64url_decode(validated[:tag], "encrypted_delivery.tag")
+        cipher.auth_data = ""
+        plaintext = cipher.update(b64url_decode(validated[:ciphertext], "encrypted_delivery.ciphertext")) + cipher.final
+        payload = JSON.parse(plaintext)
+        raise ArgumentError, "encrypted_delivery payload must be an object" unless payload.is_a?(Hash)
+
+        symbolize(payload).tap do |candidate|
+          raise ArgumentError, "encrypted_delivery payload version must be 1" unless candidate[:version] == GATE_DELIVERY_VERSION
+          raise ArgumentError, "encrypted_delivery payload outputs must be an object" unless candidate[:outputs].is_a?(Hash)
+          candidate[:outputs].each do |key_name, item|
+            raise ArgumentError, "encrypted_delivery output #{key_name} must be a string" unless item.is_a?(String)
+          end
+        end
+      rescue JSON::ParserError
+        raise ArgumentError, "encrypted_delivery decrypted to invalid JSON"
+      end
+
+      def validate_gate_approved_webhook_payload(value)
+        candidate = symbolize(value)
+        raise ArgumentError, "webhook payload must not include event; use the webhook event envelope type" if candidate.key?(:event)
+        raise ArgumentError, "service_id is required" if candidate[:service_id].to_s.empty?
+        raise ArgumentError, "gate_session_id is required" if candidate[:gate_session_id].to_s.empty?
+        raise ArgumentError, "gate_account_id is required" if candidate[:gate_account_id].to_s.empty?
+        raise ArgumentError, "account_name is required" if candidate[:account_name].to_s.empty?
+        raise ArgumentError, "metadata must be an object or null" unless candidate[:metadata].nil? || candidate[:metadata].is_a?(Hash)
+        raise ArgumentError, "foil must be an object" unless candidate[:foil].is_a?(Hash)
+        verdict = candidate[:foil][:verdict]
+        raise ArgumentError, "foil.verdict is invalid" unless %w[bot human inconclusive].include?(verdict)
+        score = candidate[:foil][:score]
+        raise ArgumentError, "foil.score must be a number or null" unless score.nil? || score.is_a?(Numeric)
+
+        {
+          service_id: candidate[:service_id],
+          gate_session_id: candidate[:gate_session_id],
+          gate_account_id: candidate[:gate_account_id],
+          account_name: candidate[:account_name],
+          metadata: candidate[:metadata]&.dup,
+          foil: {
+            verdict: verdict,
+            score: score
+          },
+          delivery: validate_gate_delivery_request(candidate[:delivery])
+        }
+      end
+
+      def verify_gate_webhook_signature(secret:, timestamp:, raw_body:, signature:, max_age_seconds: 300, now_seconds: nil)
+        parsed_timestamp = Integer(timestamp)
+        current = now_seconds || Time.now.to_i
+        return false if (current - parsed_timestamp).abs > max_age_seconds
+
+        expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{raw_body}")
+        secure_compare(expected, signature)
+      rescue ArgumentError
+        false
+      end
+
+      def parse_webhook_event(raw_body)
+        envelope = symbolize(JSON.parse(raw_body))
+        raise ArgumentError, "webhook event object must be webhook_event" unless envelope[:object] == "webhook_event"
+        raise ArgumentError, "webhook event id is required" if envelope[:id].to_s.empty?
+        raise ArgumentError, "webhook event type is required" if envelope[:type].to_s.empty?
+        raise ArgumentError, "unsupported webhook event type: #{envelope[:type]}" unless WEBHOOK_EVENT_TYPES.include?(envelope[:type])
+        raise ArgumentError, "webhook event created timestamp is required" if envelope[:created].to_s.empty?
+        raise ArgumentError, "webhook event data must be an object" unless envelope[:data].is_a?(Hash)
+
+        envelope[:data] = validate_gate_approved_webhook_payload(envelope[:data]) if envelope[:type] == "gate.session.approved"
+        envelope
+      end
+
+      def verify_and_parse_webhook_event(secret:, timestamp:, raw_body:, signature:, max_age_seconds: 300, now_seconds: nil)
+        unless verify_gate_webhook_signature(secret: secret, timestamp: timestamp, raw_body: raw_body, signature: signature, max_age_seconds: max_age_seconds, now_seconds: now_seconds)
+          raise ArgumentError, "Invalid Foil webhook signature"
+        end
+        parse_webhook_event(raw_body)
+      end
+
+      def symbolize(value)
+        case value
+        when Array
+          value.map { |item| symbolize(item) }
+        when Hash
+          value.each_with_object({}) do |(key, item), memo|
+            memo[key.to_sym] = symbolize(item)
+          end
+        else
+          value
+        end
+      end
+      private_class_method :symbolize
+
+      def compact_payload(payload)
+        {
+          version: payload[:version],
+          outputs: payload[:outputs],
+          **(payload[:ack_token] ? { ack_token: payload[:ack_token] } : {})
+        }
+      end
+      private_class_method :compact_payload
+
+      def b64url_decode(value, label)
+        Base64.urlsafe_decode64(value.to_s)
+      rescue ArgumentError => error
+        raise ArgumentError, "Invalid #{label}: #{error.message}"
+      end
+      private_class_method :b64url_decode
+
+      def secure_compare(left, right)
+        return false unless left.bytesize == right.bytesize
+
+        result = 0
+        left.bytes.zip(right.bytes) { |a, b| result |= a ^ b }
+        result.zero?
+      end
+      private_class_method :secure_compare
+    end
+  end
+end

data/lib/foil/server/sealed_token.rb

@@ -0,0 +1,78 @@
+require "base64"
+require "digest"
+require "json"
+require "openssl"
+require "zlib"
+
+module Foil
+  module Server
+    module SealedToken
+      VERSION = 0x01
+
+      module_function
+
+      def verify_foil_token(sealed_token, secret_key = nil)
+        CryptoSupport.ensure_supported_runtime!
+        resolved_secret = secret_key || ENV["FOIL_SECRET_KEY"]
+        raise ConfigurationError, "Missing Foil secret key. Pass secret_key explicitly or set FOIL_SECRET_KEY." if resolved_secret.nil? || resolved_secret.empty?
+
+        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
+        payload = JSON.parse(Zlib::Inflate.inflate(compressed))
+        deep_symbolize(payload)
+      rescue ConfigurationError, TokenVerificationError
+        raise
+      rescue StandardError => error
+        raise TokenVerificationError, "Failed to verify Foil token: #{error.message}"
+      end
+
+      def safe_verify_foil_token(sealed_token, secret_key = nil)
+        { ok: true, data: verify_foil_token(sealed_token, secret_key) }
+      rescue ConfigurationError, TokenVerificationError => error
+        { ok: false, error: error }
+      end
+
+      def derive_key(secret_key_or_hash)
+        Digest::SHA256.digest("#{normalize_secret(secret_key_or_hash)}\0sealed-results")
+      end
+      private_class_method :derive_key
+
+      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)
+
+        Digest::SHA256.hexdigest(secret_key_or_hash)
+      end
+      private_class_method :normalize_secret
+
+      def deep_symbolize(value)
+        case value
+        when Array
+          value.map { |item| deep_symbolize(item) }
+        when Hash
+          value.each_with_object({}) do |(key, item), memo|
+            memo[key.to_sym] = deep_symbolize(item)
+          end
+        else
+          value
+        end
+      end
+      private_class_method :deep_symbolize
+    end
+  end
+end

data/lib/foil/server/types.rb

@@ -0,0 +1,5 @@
+module Foil
+  module Server
+    ListResult = Struct.new(:items, :limit, :has_more, :next_cursor, keyword_init: true)
+  end
+end

data/lib/foil/server/version.rb

@@ -0,0 +1,5 @@
+module Foil
+  module Server
+    VERSION = "0.3.3".freeze
+  end
+end

data/lib/foil/server.rb

@@ -0,0 +1,31 @@
+require_relative "server/version"
+require_relative "server/errors"
+require_relative "server/crypto_support"
+require_relative "server/types"
+require_relative "server/sealed_token"
+require_relative "server/gate_delivery"
+require_relative "server/client"
+
+module Foil
+  module Server
+    module_function
+
+    def verify_foil_token(sealed_token, secret_key = nil)
+      SealedToken.verify_foil_token(sealed_token, secret_key)
+    end
+
+    def safe_verify_foil_token(sealed_token, secret_key = nil)
+      SealedToken.safe_verify_foil_token(sealed_token, secret_key)
+    end
+
+    def method_missing(name, *args, **kwargs, &block)
+      return GateDelivery.public_send(name, *args, **kwargs, &block) if GateDelivery.respond_to?(name)
+
+      super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      GateDelivery.respond_to?(name) || super
+    end
+  end
+end

data/spec/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ABXY Labs
+
+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/spec/README.md

@@ -0,0 +1,160 @@
+# Server SDK Spec
+
+This directory is the authoritative cross-language contract for Foil server SDKs.
+
+It defines:
+
+- the supported server API surface
+- the shared sealed token verification behavior
+- the shared Gate delivery/webhook helper behavior
+- golden fixtures for success, error, pagination, and helper flows
+
+## Scope
+
+Server SDKs include only customer-facing APIs:
+
+- `/v1/sessions`
+- `/v1/fingerprints`
+- `/v1/organizations`
+- `/v1/organizations/:organizationId/api-keys`
+- `/v1/gate/registry`
+- `/v1/gate/services`
+- `/v1/gate/sessions`
+- `/v1/gate/login-sessions`
+- `/v1/gate/agent-tokens/*`
+
+Server SDKs do **not** include:
+
+- collect endpoints
+- internal scoring APIs
+- dashboard/internal APIs
+- framework adapters
+- retry middleware
+- policy helpers like `shouldBlock`
+
+## Required Namespaces
+
+Every server SDK should expose these top-level capabilities:
+
+- Sessions
+  - list
+  - get
+  - iterator / auto-pagination helper
+- Fingerprints
+  - list
+  - get
+  - iterator / auto-pagination helper
+- Organizations
+  - create
+  - get
+  - update
+- Organization API keys
+  - create
+  - list
+  - revoke
+  - rotate
+- Gate
+  - registry list/get
+  - services list/get/create/update/disable
+  - sessions create/poll/acknowledge
+  - login sessions create/consume
+  - agent tokens verify/revoke
+- sealed token helpers
+  - strict verify
+  - safe verify
+- Gate delivery/webhook helpers
+  - generate delivery keypair
+  - import/export delivery private key
+  - validate delivery request
+  - encrypt/decrypt delivery envelopes
+  - validate approved webhook payload
+  - verify webhook signature
+  - derive agent-token env keys
+  - check blocked/managed Gate env vars
+
+## Shared Defaults
+
+Every SDK should default to:
+
+- `base_url = https://api.usefoil.com`
+- `secret_key = env(FOIL_SECRET_KEY)`
+- support for public, bearer-token, and secret-key auth as required by the Gate surface
+- request timeout support
+- no automatic retries
+
+## Pagination Normalization
+
+List APIs should normalize cursor pagination into these fields using each language's native style:
+
+- `items`
+- `limit`
+- `has_more`
+- `next_cursor`
+
+The underlying API responses remain cursor-based. SDKs may expose helper iterators/enumerators/page walkers on top.
+
+## Error Model
+
+SDKs should parse API failures into structured errors with, at minimum:
+
+- `status`
+- `code`
+- `message`
+- `request_id`
+- `field_errors`
+- `docs_url`
+- parsed raw body
+
+Use the fixtures in `fixtures/errors/` as the source of truth for error-shape behavior.
+
+## Sealed Token Verification
+
+`sealed-token.md` is the cross-language source of truth for verification behavior.
+
+SDKs must implement verification natively in their own language runtime. They should not depend on another SDK implementation.
+
+Use both:
+
+- `fixtures/sealed-token/vector.v1.json`
+- `fixtures/sealed-token/invalid.json`
+
+to validate correctness and failure behavior.
+
+## Gate Delivery Helper Coverage
+
+Use the shared fixtures in `fixtures/gate-delivery/` to validate:
+
+- delivery request validation and key-id derivation
+- envelope encrypt/decrypt roundtrips
+- approved webhook payload validation
+- webhook signature verification
+- Gate env-var policy helpers
+
+## Sync Model
+
+This repo is the source of truth for the shared server SDK contract.
+
+Each language SDK repo carries a synced copy of this repository in `spec/`, and the Foil monorepo vendors this repository as a submodule at `sdk-spec/server`.
+
+Keep the synced copies and the monorepo submodule pointer current before advancing them.
+
+## SDK Authoring Checklist
+
+When changing any server SDK:
+
+- sync `spec/` before changing SDK code or tests
+- do not expose collect or internal-only endpoints
+- preserve the shared defaults:
+  - env-based secret key fallback
+  - `https://api.usefoil.com`
+  - request timeout support
+  - no automatic retries
+- preserve pagination normalization:
+  - `items`
+  - `limit`
+  - `has_more`
+  - `next_cursor`
+- preserve structured API errors
+- keep sealed token golden-vector coverage
+- keep one live smoke suite per SDK
+- only update the vendored SDK `spec/` copies or the monorepo submodule pointer after the relevant CI is green