tripwire-server 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ea227f476d80187c6545059912b6a32a0adaa4f34bdc1bb47ee21e238c796515
+  data.tar.gz: c6790aad09a6b96e6fb25e8fe72e18797bd282e08207559967a817d6734d7a0f
+SHA512:
+  metadata.gz: 4c7e6cbb34ca5c959e712ee227d74027a988a4805e5046c47a59f8241c023144787448890df131d370d5fe76d4d2dba50579ec53e5e5c1c9de504e8d97621ad2
+  data.tar.gz: afe4dd7afb7436c186a4c3da2cf261403e1b160a40e6a12eea55f4a9d3d8af5b070f9eb17b9821d8a031bd5e14daa5c8d27a3cd25858dcbd89a73935e7a132bd

data/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/README.md

@@ -0,0 +1,99 @@
+# Tripwire Ruby Library
+
+![Preview](https://img.shields.io/badge/status-preview-111827)
+![Ruby 2.6+](https://img.shields.io/badge/ruby-2.6%2B-CC342D?logo=ruby&logoColor=white)
+![License: MIT](https://img.shields.io/badge/license-MIT-0f766e.svg)
+
+The Tripwire Ruby library provides convenient access to the Tripwire API from applications written in Ruby. It includes a client for Sessions, Fingerprints, Teams, Team API key management, and sealed token verification.
+
+The library also provides:
+
+- a fast configuration path using `TRIPWIRE_SECRET_KEY`
+- lazy helpers for cursor-based pagination
+- structured API errors and built-in sealed token verification
+
+## Documentation
+
+See the [Tripwire docs](https://tripwirejs.com/docs) and [API reference](https://tripwirejs.com/docs/api-reference/introduction).
+
+## Installation
+
+You don't need this source code unless you want to modify the gem. If you just want to use the package, run:
+
+```bash
+bundle add tripwire-server
+```
+
+## Requirements
+
+- Ruby 2.6+
+
+## Usage
+
+The library needs to be configured with your account's secret key. Set `TRIPWIRE_SECRET_KEY` in your environment or pass `secret_key` directly:
+
+```ruby
+require "tripwire/server"
+
+client = Tripwire::Server::Client.new(secret_key: "sk_live_...")
+
+page = client.sessions.list(verdict: "bot", limit: 25)
+session = client.sessions.get("sid_123")
+```
+
+### Sealed token verification
+
+```ruby
+result = Tripwire::Server.safe_verify_tripwire_token(sealed_token, "sk_live_...")
+
+if result[:ok]
+  puts "#{result[:data][:verdict]} #{result[:data][:score]}"
+else
+  warn result[:error].message
+end
+```
+
+### Pagination
+
+```ruby
+client.sessions.iter(search: "signup").each do |session|
+  puts "#{session[:id]} #{session[:latestResult][:verdict]}"
+end
+```
+
+### Fingerprints
+
+```ruby
+fingerprint = client.fingerprints.get("vis_123")
+puts fingerprint[:id]
+```
+
+### Teams
+
+```ruby
+team = client.teams.get("team_123")
+updated = client.teams.update("team_123", name: "New Name")
+
+puts updated[:name]
+```
+
+### Team API keys
+
+```ruby
+created = client.teams.api_keys.create("team_123", name: "Production")
+client.teams.api_keys.revoke("team_123", created[:id])
+```
+
+### Error handling
+
+```ruby
+begin
+  client.sessions.list(limit: 999)
+rescue Tripwire::Server::ApiError => error
+  warn "#{error.status} #{error.code} #{error.message}"
+end
+```
+
+## Support
+
+If you need help integrating Tripwire, start with [tripwirejs.com/docs](https://tripwirejs.com/docs).

data/lib/tripwire/server/client.rb

@@ -0,0 +1,265 @@
+require "cgi"
+require "json"
+require "net/http"
+require "uri"
+
+module Tripwire
+  module Server
+    class Client
+      DEFAULT_BASE_URL = "https://api.tripwirejs.com".freeze
+      DEFAULT_TIMEOUT = 30
+      SDK_CLIENT_HEADER = "tripwire-server-ruby/0.1.0".freeze
+
+      attr_reader :sessions, :fingerprints, :teams, :timeout
+
+      def initialize(secret_key: ENV["TRIPWIRE_SECRET_KEY"], base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT, user_agent: nil, transport: nil)
+        raise ConfigurationError, "Missing Tripwire secret key. Pass secret_key explicitly or set TRIPWIRE_SECRET_KEY." if secret_key.nil? || secret_key.empty?
+
+        @secret_key = secret_key
+        @base_url = base_url
+        @timeout = timeout
+        @user_agent = user_agent
+        @transport = transport
+
+        @sessions = SessionsResource.new(self)
+        @fingerprints = FingerprintsResource.new(self)
+        @teams = TeamsResource.new(self)
+      end
+
+      def request_json(method, path, query: {}, body: nil, expect_content: true)
+        url = build_url(path, query)
+        headers = {
+          "Authorization" => "Bearer #{@secret_key}",
+          "Accept" => "application/json",
+          "X-Tripwire-Client" => SDK_CLIENT_HEADER
+        }
+        headers["User-Agent"] = @user_agent if @user_agent
+        headers["Content-Type"] = "application/json" if body
+
+        status, response_headers, response_body =
+          if @transport
+            @transport.call(method: method, url: url.to_s, headers: headers, body: body.nil? ? nil : JSON.dump(body))
+          else
+            perform_http_request(method, url, headers, body)
+          end
+
+        request_id = response_headers["x-request-id"] || response_headers["X-Request-Id"]
+
+        if status >= 400
+          payload = parse_json(response_body)
+          if payload[:error].is_a?(Hash)
+            error = payload[:error]
+            details = error[:details].is_a?(Hash) ? error[:details] : {}
+            raise ApiError.new(
+              status: status,
+              code: error[:code] || "request.failed",
+              message: error[:message] || response_body.to_s,
+              request_id: request_id || error[:requestId],
+              field_errors: details[:fieldErrors] || [],
+              docs_url: error[:docsUrl],
+              body: payload
+            )
+          end
+
+          raise ApiError.new(status: status, code: "request.failed", message: response_body.to_s, request_id: request_id, body: payload)
+        end
+
+        return {} unless expect_content
+        return {} if status == 204 || response_body.nil? || response_body.empty?
+
+        parse_json(response_body)
+      end
+
+      def perform_http_request(method, url, headers, body)
+        http = Net::HTTP.new(url.host, url.port)
+        http.use_ssl = (url.scheme == "https")
+        http.read_timeout = @timeout
+        http.open_timeout = @timeout
+
+        request_class = case method
+        when "GET" then Net::HTTP::Get
+        when "POST" then Net::HTTP::Post
+        when "PATCH" then Net::HTTP::Patch
+        when "DELETE" then Net::HTTP::Delete
+        else
+          raise ArgumentError, "Unsupported method #{method}"
+        end
+
+        request = request_class.new(url)
+        headers.each { |key, value| request[key] = value }
+        request.body = JSON.dump(body) if body
+
+        response = http.request(request)
+        [response.code.to_i, response.to_hash.transform_values { |value| Array(value).first }, response.body.to_s]
+      end
+      private :perform_http_request
+
+      def build_url(path, query)
+        url = URI.join(@base_url.end_with?("/") ? @base_url : "#{@base_url}/", path.sub(%r{\A/}, ""))
+        compact_query = query.each_with_object({}) do |(key, value), memo|
+          memo[key] = value unless value.nil? || value == ""
+        end
+        url.query = URI.encode_www_form(compact_query) unless compact_query.empty?
+        url
+      end
+      private :build_url
+
+      def parse_json(body)
+        data = JSON.parse(body)
+        deep_symbolize(data)
+      rescue JSON::ParserError
+        {}
+      end
+      private :parse_json
+
+      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 :deep_symbolize
+    end
+
+    class BaseResource
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      def list_result(payload)
+        ListResult.new(
+          items: payload[:data],
+          limit: payload.fetch(:pagination).fetch(:limit),
+          has_more: payload.fetch(:pagination).fetch(:hasMore),
+          next_cursor: payload.fetch(:pagination)[:nextCursor]
+        )
+      end
+    end
+
+    class SessionsResource < BaseResource
+      def list(limit: nil, cursor: nil, verdict: nil, search: nil)
+        payload = @client.request_json("GET", "/v1/sessions", query: {
+          limit: limit,
+          cursor: cursor,
+          verdict: verdict,
+          search: search
+        })
+        list_result(payload)
+      end
+
+      def get(session_id)
+        @client.request_json("GET", "/v1/sessions/#{CGI.escape(session_id)}")[:data]
+      end
+
+      def iter(limit: nil, verdict: nil, search: nil)
+        Enumerator.new do |yielder|
+          cursor = nil
+          loop do
+            page = list(limit: limit, cursor: cursor, verdict: verdict, search: search)
+            page.items.each { |item| yielder << item }
+            break unless page.has_more && page.next_cursor
+
+            cursor = page.next_cursor
+          end
+        end
+      end
+    end
+
+    class FingerprintsResource < BaseResource
+      def list(limit: nil, cursor: nil, search: nil, sort: nil)
+        payload = @client.request_json("GET", "/v1/fingerprints", query: {
+          limit: limit,
+          cursor: cursor,
+          search: search,
+          sort: sort
+        })
+        list_result(payload)
+      end
+
+      def get(visitor_id)
+        @client.request_json("GET", "/v1/fingerprints/#{CGI.escape(visitor_id)}")[:data]
+      end
+
+      def iter(limit: nil, search: nil, sort: nil)
+        Enumerator.new do |yielder|
+          cursor = nil
+          loop do
+            page = list(limit: limit, cursor: cursor, search: search, sort: sort)
+            page.items.each { |item| yielder << item }
+            break unless page.has_more && page.next_cursor
+
+            cursor = page.next_cursor
+          end
+        end
+      end
+    end
+
+    class ApiKeysResource < BaseResource
+      def create(team_id, name: nil, is_test: nil, allowed_origins: nil, rate_limit: nil)
+        payload = @client.request_json("POST", "/v1/teams/#{CGI.escape(team_id)}/api-keys", body: compact({
+          name: name,
+          isTest: is_test,
+          allowedOrigins: allowed_origins,
+          rateLimit: rate_limit
+        }))
+        payload[:data]
+      end
+
+      def list(team_id, limit: nil, cursor: nil)
+        payload = @client.request_json("GET", "/v1/teams/#{CGI.escape(team_id)}/api-keys", query: {
+          limit: limit,
+          cursor: cursor
+        })
+        list_result(payload)
+      end
+
+      def revoke(team_id, key_id)
+        @client.request_json("DELETE", "/v1/teams/#{CGI.escape(team_id)}/api-keys/#{CGI.escape(key_id)}", expect_content: false)
+        nil
+      end
+
+      def rotate(team_id, key_id)
+        payload = @client.request_json("POST", "/v1/teams/#{CGI.escape(team_id)}/api-keys/#{CGI.escape(key_id)}/rotations")
+        payload[:data]
+      end
+
+      private
+
+      def compact(hash)
+        hash.reject { |_key, value| value.nil? }
+      end
+    end
+
+    class TeamsResource < BaseResource
+      attr_reader :api_keys
+
+      def initialize(client)
+        super(client)
+        @api_keys = ApiKeysResource.new(client)
+      end
+
+      def create(name:, slug:)
+        @client.request_json("POST", "/v1/teams", body: { name: name, slug: slug })[:data]
+      end
+
+      def get(team_id)
+        @client.request_json("GET", "/v1/teams/#{CGI.escape(team_id)}")[:data]
+      end
+
+      def update(team_id, name: nil, status: nil)
+        @client.request_json("PATCH", "/v1/teams/#{CGI.escape(team_id)}", body: {
+          name: name,
+          status: status
+        }.reject { |_key, value| value.nil? })[:data]
+      end
+    end
+  end
+end

data/lib/tripwire/server/errors.rb

@@ -0,0 +1,21 @@
+module Tripwire
+  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/tripwire/server/sealed_token.rb

@@ -0,0 +1,76 @@
+require "base64"
+require "digest"
+require "json"
+require "openssl"
+require "zlib"
+
+module Tripwire
+  module Server
+    module SealedToken
+      VERSION = 0x01
+
+      module_function
+
+      def verify_tripwire_token(sealed_token, secret_key = nil)
+        resolved_secret = secret_key || ENV["TRIPWIRE_SECRET_KEY"]
+        raise ConfigurationError, "Missing Tripwire secret key. Pass secret_key explicitly or set TRIPWIRE_SECRET_KEY." if resolved_secret.nil? || resolved_secret.empty?
+
+        raw = Base64.decode64(sealed_token)
+        raise TokenVerificationError, "Tripwire token is too short." if raw.bytesize < 29
+
+        version = raw.getbyte(0)
+        raise TokenVerificationError, "Unsupported Tripwire 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
+
+        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 Tripwire token: #{error.message}"
+      end
+
+      def safe_verify_tripwire_token(sealed_token, secret_key = nil)
+        { ok: true, data: verify_tripwire_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/tripwire/server/types.rb

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

data/lib/tripwire/server/version.rb

@@ -0,0 +1,5 @@
+module Tripwire
+  module Server
+    VERSION = "0.1.0".freeze
+  end
+end

data/lib/tripwire/server.rb

@@ -0,0 +1,19 @@
+require_relative "server/version"
+require_relative "server/errors"
+require_relative "server/types"
+require_relative "server/sealed_token"
+require_relative "server/client"
+
+module Tripwire
+  module Server
+    module_function
+
+    def verify_tripwire_token(sealed_token, secret_key = nil)
+      SealedToken.verify_tripwire_token(sealed_token, secret_key)
+    end
+
+    def safe_verify_tripwire_token(sealed_token, secret_key = nil)
+      SealedToken.safe_verify_tripwire_token(sealed_token, secret_key)
+    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,129 @@
+# Server SDK Spec
+
+This directory is the authoritative cross-language contract for Tripwire server SDKs.
+
+It defines:
+
+- the supported public server API surface
+- the shared sealed token verification behavior
+- golden fixtures for success, error, and pagination flows
+
+## Scope
+
+Server SDKs include only customer-facing public APIs:
+
+- `/v1/sessions`
+- `/v1/fingerprints`
+- `/v1/teams`
+- `/v1/teams/:teamId/api-keys`
+
+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
+- Teams
+  - create
+  - get
+  - update
+- Team API keys
+  - create
+  - list
+  - revoke
+  - rotate
+- sealed token helpers
+  - strict verify
+  - safe verify
+
+## Shared Defaults
+
+Every SDK should default to:
+
+- `base_url = https://api.tripwirejs.com`
+- `secret_key = env(TRIPWIRE_SECRET_KEY)`
+- secret-key-only auth via `Authorization: Bearer <secret>`
+- 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 public 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.
+
+## 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 Tripwire 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.tripwirejs.com`
+  - request timeout support
+  - no automatic retries
+- preserve pagination normalization:
+  - `items`
+  - `limit`
+  - `has_more`
+  - `next_cursor`
+- preserve structured public 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

data/spec/fixtures/errors/invalid-api-key.json

@@ -0,0 +1,10 @@
+{
+  "error": {
+    "code": "auth.invalid_api_key",
+    "message": "The provided API key is invalid. Check the key and retry.",
+    "status": 401,
+    "retryable": false,
+    "requestId": "req_invalid_api_key",
+    "docsUrl": "https://tripwire.com/docs/api-reference/introduction"
+  }
+}