foil-server 0.3.5 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d41b78e23e89f77b68f871a2454fb7d3ee87828a66e76fc95c6baca12127ff2
-  data.tar.gz: ba257476579665aa554305f16a98793b5a9b98726d90784c5d5ae4b643ba04e2
+  metadata.gz: 142ee8a11ee7b38b933aab55b22188e9f2a6ef73186097a5ea708d93fa0be2b8
+  data.tar.gz: cbcf119648d0de7699f30ff12894ed6303e7a6c1a874178db73e6a706a828b6a
 SHA512:
-  metadata.gz: 5a979d1b334c0c7331fcd3f174b3ddece6f371d200ee7cd4ffe4287b8e651cadada1ae15cc495b14c849e290de9384ab53cc826c80e5d5e49b4ae56fde1659d3
-  data.tar.gz: 70a38a2b6466c9e184b67629e9d45cdce7d620e032737d8c5cad9d6c96eba590c7a58b80ed22573b976ae1fb2ebad215e70f9edfea8cee6f0f9bf0eb65784f85
+  metadata.gz: 899d02338303288f518178bb8c1a72e815dd2372ef428534fe3c36a2574a09eecb021164ebda90f90439d74ce0bdd112d5d2301ddf393dd837fe4bf18e91103a
+  data.tar.gz: c88c199301d6c99dc1e612824b3d96caddaec9fd70b1dee9abc31f29ac071e75fcfba2d4bc55055ee7c2f75b8ca394b2bd8e01d0d7cc3eeacb5b779b2dc4465c

data/README.md

@@ -4,16 +4,14 @@
 ![Ruby 3.3+](https://img.shields.io/badge/ruby-3.3%2B-CC342D?logo=ruby&logoColor=white)
 ![License: MIT](https://img.shields.io/badge/license-MIT-0f766e.svg)
 
-The Foil Ruby library provides convenient access to the Foil API from applications written in Ruby. It includes a client for Sessions, visitor fingerprints, Organizations, Organization API key management, sealed token verification, Gate, and Gate delivery/webhook helpers.
+The Foil Ruby library provides convenient access to the Foil API from applications written in Ruby. It includes a client for Sessions, visitor fingerprints, Organizations, Organization API key management, webhook endpoints, and sealed token verification.
 
 The library also provides:
 
 - a fast configuration path using `FOIL_SECRET_KEY`
 - lazy helpers for cursor-based pagination
 - structured API errors and built-in sealed token verification
-- webhook endpoint management, test sends, and event delivery history
-- public, bearer-token, and secret-key auth modes for Gate flows
-- Gate delivery/webhook helpers
+- webhook endpoint management, test sends, event delivery history, and webhook signature verification
 
 ## Documentation
 
@@ -33,7 +31,7 @@ bundle add foil-server
 
 ## Usage
 
-Use `FOIL_SECRET_KEY` or `secret_key:` for core detect APIs. For public or bearer-auth Gate flows, the client can also be created without a secret key:
+Use `FOIL_SECRET_KEY` or `secret_key:`:
 
 ```ruby
 require "foil/server"
@@ -98,7 +96,7 @@ endpoint = client.webhooks.create_endpoint(
   "org_0123456789abcdefghjkmnpqrs",
   name: "Production alerts",
   url: "https://example.com/foil/webhook",
-  event_types: ["session.result.persisted", "gate.session.approved"]
+  event_types: ["session.result.persisted"]
 )
 
 events = client.webhooks.list_events(
@@ -110,37 +108,34 @@ events = client.webhooks.list_events(
 puts events.items.first[:webhook_deliveries].first[:status]
 ```
 
-### Gate APIs
+#### Verifying webhook deliveries
 
-```ruby
-delivery_key_pair = Foil::Server::GateDelivery.create_delivery_key_pair
+Every webhook delivery is signed with your endpoint's signing secret. Verify the `X-Foil-Timestamp` and `X-Foil-Signature` headers against the raw request body before trusting the payload:
 
-services = client.gate.registry.list
-session = client.gate.sessions.create(
-  service_id: "foil",
-  account_name: "my-project",
-  delivery: delivery_key_pair[:delivery]
+```ruby
+valid = Foil::Server.verify_webhook_signature(
+  secret: ENV.fetch("FOIL_WEBHOOK_SECRET"),
+  timestamp: request.headers["X-Foil-Timestamp"],
+  raw_body: raw_body,
+  signature: request.headers["X-Foil-Signature"]
 )
 
-puts "#{services.first[:id]} #{session[:consent_url]}"
-```
-
-### Gate delivery and webhook helpers
-
-```ruby
-key_pair = Foil::Server::GateDelivery.create_delivery_key_pair
-response = Foil::Server::GateDelivery.create_gate_approved_webhook_response(
-  delivery: key_pair[:delivery],
-  outputs: {
-    "FOIL_PUBLISHABLE_KEY" => "pk_live_...",
-    "FOIL_SECRET_KEY" => "sk_live_..."
-  }
+# Verify and parse in one step. Raises ArgumentError if the signature is invalid or expired.
+event = Foil::Server.verify_and_parse_webhook_event(
+  secret: ENV.fetch("FOIL_WEBHOOK_SECRET"),
+  timestamp: request.headers["X-Foil-Timestamp"],
+  raw_body: raw_body,
+  signature: request.headers["X-Foil-Signature"]
 )
-payload = Foil::Server::GateDelivery.decrypt_gate_delivery_envelope(key_pair[:private_key], response[:encrypted_delivery])
 
-puts payload[:outputs]["FOIL_SECRET_KEY"]
+puts event[:data] if event[:type] == "session.result.persisted"
+
+# Parse a payload you have already verified.
+parsed = Foil::Server.parse_webhook_event(raw_body)
 ```
 
+Signatures older than five minutes are rejected by default. Pass `max_age_seconds:` to change the tolerance.
+
 ### Error handling
 
 ```ruby

data/lib/foil/server/client.rb

@@ -10,7 +10,7 @@ module Foil
       DEFAULT_TIMEOUT = 30
       SDK_CLIENT_HEADER = "foil-server-ruby/0.1.0".freeze
 
-      attr_reader :sessions, :fingerprints, :organizations, :gate, :webhooks, :timeout
+      attr_reader :sessions, :fingerprints, :organizations, :webhooks, :timeout
 
       def initialize(secret_key: ENV["FOIL_SECRET_KEY"], base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT, user_agent: nil, transport: nil)
         @secret_key = secret_key
@@ -22,11 +22,10 @@ module Foil
         @sessions = SessionsResource.new(self)
         @fingerprints = FingerprintsResource.new(self)
         @organizations = OrganizationsResource.new(self)
-        @gate = GateResource.new(self)
         @webhooks = WebhooksResource.new(self)
       end
 
-      def request_json(method, path, query: {}, body: nil, expect_content: true, auth: { kind: :secret })
+      def request_json(method, path, query: {}, body: nil, expect_content: true)
         url = build_url(path, query)
         headers = {
           "Accept" => "application/json",
@@ -34,7 +33,7 @@ module Foil
         }
         headers["User-Agent"] = @user_agent if @user_agent
         headers["Content-Type"] = "application/json" if body
-        apply_auth_headers(headers, auth)
+        apply_auth_headers(headers)
 
         status, response_headers, response_body =
           if @transport
@@ -126,21 +125,10 @@ module Foil
       end
       private :deep_symbolize
 
-      def apply_auth_headers(headers, auth)
-        kind = (auth[:kind] || :secret).to_sym
-        case kind
-        when :none
-          headers
-        when :bearer
-          token = auth[:token]
-          raise ConfigurationError, "Missing bearer token for this Foil request." if token.nil? || token.empty?
+      def apply_auth_headers(headers)
+        raise ConfigurationError, "Missing Foil secret key. Pass secret_key explicitly or set FOIL_SECRET_KEY." if @secret_key.nil? || @secret_key.empty?
 
-          headers["Authorization"] = "Bearer #{token}"
-        else
-          raise ConfigurationError, "Missing Foil secret key. Pass secret_key explicitly or set FOIL_SECRET_KEY." if @secret_key.nil? || @secret_key.empty?
-
-          headers["Authorization"] = "Bearer #{@secret_key}"
-        end
+        headers["Authorization"] = "Bearer #{@secret_key}"
       end
       private :apply_auth_headers
     end
@@ -300,82 +288,6 @@ module Foil
       end
     end
 
-    class GateResource < BaseResource
-      attr_reader :registry, :services, :sessions, :login_sessions, :agent_tokens
-
-      def initialize(client)
-        super(client)
-        @registry = GateRegistryResource.new(client)
-        @services = GateServicesResource.new(client)
-        @sessions = GateSessionsResource.new(client)
-        @login_sessions = GateLoginSessionsResource.new(client)
-        @agent_tokens = GateAgentTokensResource.new(client)
-      end
-    end
-
-    class GateRegistryResource < BaseResource
-      def list
-        @client.request_json("GET", "/v1/gate/registry", auth: { kind: :none })[:data]
-      end
-
-      def get(service_id)
-        @client.request_json("GET", "/v1/gate/registry/#{CGI.escape(service_id)}", auth: { kind: :none })[:data]
-      end
-    end
-
-    class GateServicesResource < BaseResource
-      def list
-        @client.request_json("GET", "/v1/gate/services")[:data]
-      end
-
-      def get(service_id)
-        @client.request_json("GET", "/v1/gate/services/#{CGI.escape(service_id)}")[:data]
-      end
-
-      def create(id:, name:, description:, website:, webhook_endpoint_id:, discoverable: nil, dashboard_login_url: nil, env_vars: nil, docs_url: nil, sdks: nil, branding: nil, consent: nil)
-        @client.request_json("POST", "/v1/gate/services", body: compact({
-          id: id,
-          discoverable: discoverable,
-          name: name,
-          description: description,
-          website: website,
-          dashboard_login_url: dashboard_login_url,
-          webhook_endpoint_id: webhook_endpoint_id,
-          env_vars: env_vars,
-          docs_url: docs_url,
-          sdks: sdks,
-          branding: branding,
-          consent: consent
-        }))[:data]
-      end
-
-      def update(service_id, discoverable: nil, name: nil, description: nil, website: nil, dashboard_login_url: nil, webhook_endpoint_id: nil, env_vars: nil, docs_url: nil, sdks: nil, branding: nil, consent: nil)
-        @client.request_json("PATCH", "/v1/gate/services/#{CGI.escape(service_id)}", body: compact({
-          discoverable: discoverable,
-          name: name,
-          description: description,
-          website: website,
-          dashboard_login_url: dashboard_login_url,
-          webhook_endpoint_id: webhook_endpoint_id,
-          env_vars: env_vars,
-          docs_url: docs_url,
-          sdks: sdks,
-          branding: branding,
-          consent: consent
-        }))[:data]
-      end
-
-      def disable(service_id)
-        @client.request_json("DELETE", "/v1/gate/services/#{CGI.escape(service_id)}")[:data]
-      end
-
-      private
-
-      def compact(hash)
-        hash.reject { |_key, value| value.nil? }
-      end
-    end
-
     class WebhooksResource < BaseResource
       def list_endpoints(organization_id)
         payload = @client.request_json("GET", "/v1/organizations/#{CGI.escape(organization_id)}/webhooks/endpoints")
@@ -419,66 +331,5 @@ module Foil
         @client.request_json("GET", "/v1/organizations/#{CGI.escape(organization_id)}/events/#{CGI.escape(event_id)}")[:data]
       end
     end
-
-    class GateSessionsResource < BaseResource
-      def create(service_id:, account_name:, delivery:, metadata: nil)
-        body = {
-          service_id: service_id,
-          account_name: account_name,
-          delivery: delivery
-        }
-        body[:metadata] = metadata unless metadata.nil?
-
-        @client.request_json("POST", "/v1/gate/sessions", body: body, auth: { kind: :none })[:data]
-      end
-
-      def poll(gate_session_id, poll_token:)
-        @client.request_json(
-          "GET",
-          "/v1/gate/sessions/#{CGI.escape(gate_session_id)}",
-          auth: { kind: :bearer, token: poll_token }
-        )[:data]
-      end
-
-      def acknowledge(gate_session_id, poll_token:, ack_token:)
-        @client.request_json(
-          "POST",
-          "/v1/gate/sessions/#{CGI.escape(gate_session_id)}/ack",
-          body: { ack_token: ack_token },
-          auth: { kind: :bearer, token: poll_token }
-        )[:data]
-      end
-    end
-
-    class GateLoginSessionsResource < BaseResource
-      def create(service_id:, agent_token:)
-        @client.request_json(
-          "POST",
-          "/v1/gate/login-sessions",
-          body: { service_id: service_id },
-          auth: { kind: :bearer, token: agent_token }
-        )[:data]
-      end
-
-      def consume(code:)
-        @client.request_json("POST", "/v1/gate/login-sessions/consume", body: { code: code })[:data]
-      end
-    end
-
-    class GateAgentTokensResource < BaseResource
-      def verify(agent_token:)
-        @client.request_json("POST", "/v1/gate/agent-tokens/verify", body: { agent_token: agent_token })[:data]
-      end
-
-      def revoke(agent_token:)
-        @client.request_json(
-          "POST",
-          "/v1/gate/agent-tokens/revoke",
-          body: { agent_token: agent_token },
-          expect_content: false
-        )
-        nil
-      end
-    end
   end
 end

data/lib/foil/server/version.rb

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

data/lib/foil/server/webhooks.rb

@@ -0,0 +1,71 @@
+require "json"
+require "openssl"
+
+module Foil
+  module Server
+    module Webhooks
+      WEBHOOK_EVENT_TYPES = %w[
+        session.result.persisted
+        webhook.test
+      ].freeze
+
+      module_function
+
+      def verify_webhook_signature(secret:, timestamp:, raw_body:, signature:, max_age_seconds: 300, now_seconds: nil)
+        return false if secret.to_s.empty?
+
+        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.to_s)
+      rescue ArgumentError, TypeError
+        false
+      end
+
+      def parse_webhook_event(raw_body)
+        envelope = symbolize(JSON.parse(raw_body))
+        raise ArgumentError, "webhook event envelope must be an object" unless envelope.is_a?(Hash)
+        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
+      end
+
+      def verify_and_parse_webhook_event(secret:, timestamp:, raw_body:, signature:, max_age_seconds: 300, now_seconds: nil)
+        unless verify_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 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.rb

@@ -3,7 +3,7 @@ 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/webhooks"
 require_relative "server/client"
 
 module Foil
@@ -18,14 +18,16 @@ module Foil
       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)
+    def verify_webhook_signature(**options)
+      Webhooks.verify_webhook_signature(**options)
+    end
 
-      super
+    def parse_webhook_event(raw_body)
+      Webhooks.parse_webhook_event(raw_body)
     end
 
-    def respond_to_missing?(name, include_private = false)
-      GateDelivery.respond_to?(name) || super
+    def verify_and_parse_webhook_event(**options)
+      Webhooks.verify_and_parse_webhook_event(**options)
     end
   end
 end

data/spec/README.md

@@ -6,7 +6,7 @@ It defines:
 
 - the supported server API surface
 - the shared sealed token verification behavior
-- the shared Gate delivery/webhook helper behavior
+- the shared webhook signature verification behavior
 - golden fixtures for success, error, pagination, and helper flows
 
 ## Scope
@@ -17,11 +17,6 @@ Server SDKs include only customer-facing APIs:
 - `/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:
 
@@ -53,24 +48,13 @@ Every server SDK should expose these top-level capabilities:
   - 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
+- webhook helpers
   - verify webhook signature
-  - derive agent-token env keys
-  - check blocked/managed Gate env vars
+  - parse webhook event
+  - verify and parse webhook event
 
 ## Shared Defaults
 
@@ -78,7 +62,6 @@ 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
 
@@ -120,15 +103,17 @@ Use both:
 
 to validate correctness and failure behavior.
 
-## Gate Delivery Helper Coverage
+## Webhook Signature Verification
 
-Use the shared fixtures in `fixtures/gate-delivery/` to validate:
+Every Foil webhook delivery carries `X-Foil-Timestamp` and `X-Foil-Signature`. The signature is the lowercase hex HMAC-SHA256 of `${timestamp}.${rawBody}`, keyed with the endpoint's signing secret. SDK helpers must:
 
-- delivery request validation and key-id derivation
-- envelope encrypt/decrypt roundtrips
-- approved webhook payload validation
-- webhook signature verification
-- Gate env-var policy helpers
+- compute the HMAC over the raw request body bytes
+- compare signatures in constant time
+- reject a timestamp more than 300 seconds from the current time by default
+- reject an empty signing secret
+- parse only the event types in the spec's `WebhookDeliveryEventType` schema and reject any other type
+
+Use `fixtures/webhooks/signature.json` to validate the valid, tampered, expired and malformed cases.
 
 ## Sync Model
 
@@ -156,5 +141,6 @@ When changing any server SDK:
   - `next_cursor`
 - preserve structured API errors
 - keep sealed token golden-vector coverage
+- keep webhook signature fixture 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

data/spec/fixtures/api/organizations/api-key-create.json

@@ -7,6 +7,7 @@
     "environment": "live",
     "status": "active",
     "allowed_origins": null,
+    "client_target": null,
     "scopes": [
       "sessions:list",
       "sessions:read",

data/spec/fixtures/api/organizations/api-key-list.json

@@ -10,6 +10,7 @@
       "allowed_origins": [
         "https://example.com"
       ],
+      "client_target": "browser",
       "scopes": null,
       "rate_limit": null,
       "key_preview": "pk_live_[example]...",

data/spec/fixtures/api/organizations/api-key-revoke.json

@@ -9,6 +9,7 @@
     "allowed_origins": [
       "https://example.com"
     ],
+    "client_target": "browser",
     "scopes": null,
     "rate_limit": null,
     "key_preview": "pk_live_[example]...",

data/spec/fixtures/api/organizations/api-key-rotate.json

@@ -7,6 +7,7 @@
     "environment": "live",
     "status": "active",
     "allowed_origins": null,
+    "client_target": null,
     "scopes": [
       "sessions:list",
       "sessions:read",

data/spec/fixtures/api/organizations/api-key-update.json

@@ -10,6 +10,7 @@
       "https://example.com",
       "https://app.example.com"
     ],
+    "client_target": "browser",
     "scopes": [
       "sessions:list",
       "sessions:read"

data/spec/fixtures/api/sessions/detail.json

@@ -4,6 +4,7 @@
     "id": "sid_0123456789abcdefghjkmnpqrs",
     "created_at": "2026-03-24T20:00:00.000Z",
     "client_user_id": "user_123",
+    "behavior": null,
     "decision": {
       "event_id": "evt_23456789abcdefghjkmnpqrstv",
       "automation_status": "automated",
@@ -198,6 +199,10 @@
       "id": "vid_456789abcdefghjkmnpqrstvwx",
       "confidence": 93,
       "identified_at": "2026-03-24T20:00:01.000Z",
+      "resolution": {
+        "method": "continuity",
+        "basis": "deterministic"
+      },
       "lifecycle": {
         "first_seen_at": "2026-03-01T18:22:11.000Z",
         "last_seen_at": "2026-03-24T20:00:05.000Z",
@@ -257,7 +262,8 @@
       "name": "Chromium",
       "version": "123.0.0.0",
       "major_version": "123",
-      "engine": "blink"
+      "engine": "blink",
+      "app_name": null
     },
     "device": {
       "form_factor": "desktop",
@@ -347,6 +353,7 @@
     ],
     "client_telemetry": {
       "navigator": {
+        "model": null,
         "platform": "macOS",
         "vendor": "Google Inc.",
         "hardware_concurrency": null,