torii-backend 0.0.2

data/src/torii/backend/generated/lib/torii-backend-generated/version.rb

@@ -0,0 +1,15 @@
+=begin
+#OpenAPI definition
+
+#No description provided (generated by Openapi Generator https://github.com/openapitools/openapi-generator)
+
+The version of the OpenAPI document: v0
+
+Generated by: https://openapi-generator.tech
+Generator version: 7.22.0
+
+=end
+
+module ToriiBackendGenerated
+  VERSION = '1.0.0'
+end

data/src/torii/backend/generated/lib/torii-backend-generated.rb

@@ -0,0 +1,49 @@
+=begin
+#OpenAPI definition
+
+#No description provided (generated by Openapi Generator https://github.com/openapitools/openapi-generator)
+
+The version of the OpenAPI document: v0
+
+Generated by: https://openapi-generator.tech
+Generator version: 7.22.0
+
+=end
+
+# Common files
+require 'torii-backend-generated/api_client'
+require 'torii-backend-generated/api_error'
+require 'torii-backend-generated/api_model_base'
+require 'torii-backend-generated/version'
+require 'torii-backend-generated/configuration'
+
+# Models
+require 'torii-backend-generated/models/create_user_request'
+require 'torii-backend-generated/models/cursor_page_response_user_response'
+require 'torii-backend-generated/models/problem_detail'
+require 'torii-backend-generated/models/server_user_search_request'
+require 'torii-backend-generated/models/update_user_request'
+require 'torii-backend-generated/models/user_response'
+require 'torii-backend-generated/models/user_session_response'
+
+# APIs
+require 'torii-backend-generated/api/server_sessions_api'
+require 'torii-backend-generated/api/server_users_api'
+
+module ToriiBackendGenerated
+  class << self
+    # Customize default settings for the SDK using block.
+    #   ToriiBackendGenerated.configure do |config|
+    #     config.username = "xxx"
+    #     config.password = "xxx"
+    #   end
+    # If no block given, return the default Configuration object.
+    def configure
+      if block_given?
+        yield(Configuration.default)
+      else
+        Configuration.default
+      end
+    end
+  end
+end

data/src/torii/backend/patch.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Torii
+  module Backend
+    # Tri-state wrapper for PATCH body fields. Mirrors the server-side
+    # Kotlin PatchValue<T> (Included + NotIncluded; Included(nil) clears).
+    #
+    # - Patch.set(value) with a non-nil value -> server updates field
+    # - Patch.set(nil)                        -> server clears field (JSON null)
+    # - omit the kwarg entirely               -> server leaves field unchanged
+    class Patch
+      attr_reader :value
+
+      def initialize(value)
+        @value = value
+      end
+
+      def self.set(value)
+        new(value)
+      end
+    end
+  end
+end

data/src/torii/backend/rack.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'json'
+
+require_relative 'authenticate_request'
+require_relative 'errors'
+
+module Torii
+  module Backend
+    # Rack middleware. Rails-compatible — mount with
+    #
+    #   config.middleware.use Torii::Backend::Rack::RequireAuth,
+    #     issuer: 'https://acme.torii.so'
+    #
+    # On success the verified +Torii::Backend::Auth+ is placed at
+    # +env['torii.auth']+ before the rest of the stack runs. On failure
+    # the middleware short-circuits with a 401 JSON body matching the
+    # shape used by Node/Python SDKs:
+    #
+    #   { "error": { "code": "authentication_failed", "message": "..." } }
+    module Rack
+      class RequireAuth
+        # @param app [#call] the inner Rack app.
+        # @param issuer [String] required — the per-tenant issuer URL.
+        # @param audience [String, Array<String>, nil] optional +aud+ to
+        #   enforce.
+        # @param leeway [Integer] clock-skew tolerance in seconds.
+        # @param header [String] which incoming header to read the bearer
+        #   token from. Defaults to the Rack-canonical
+        #   +HTTP_AUTHORIZATION+; pass a friendlier name like
+        #   +"authorization"+ if you prefer.
+        def initialize(app, issuer:, audience: nil, leeway: 30, header: 'HTTP_AUTHORIZATION')
+          raise ArgumentError, 'issuer is required' if !issuer.is_a?(String) || issuer.empty?
+
+          @app = app
+          @issuer = issuer
+          @audience = audience
+          @leeway = leeway
+          @header = header
+        end
+
+        def call(env)
+          auth = Torii::Backend.authenticate_request(
+            env,
+            issuer: @issuer,
+            audience: @audience,
+            leeway: @leeway,
+            header: @header,
+          )
+          env['torii.auth'] = auth
+          @app.call(env)
+        rescue Torii::Backend::AuthError => e
+          unauthorized(e.message)
+        end
+
+        private
+
+        def unauthorized(message)
+          body = JSON.generate(error: { code: 'authentication_failed', message: message })
+          [
+            401,
+            { 'content-type' => 'application/json', 'content-length' => body.bytesize.to_s },
+            [body],
+          ]
+        end
+      end
+    end
+  end
+end

data/src/torii/backend/verify.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require 'jwt'
+require 'json'
+require 'net/http'
+require 'uri'
+
+require_relative 'auth'
+require_relative 'errors'
+
+module Torii
+  module Backend
+    # Networkless JWT verification. The first call to +verify_token+ for a
+    # given issuer fetches that issuer's JWKS; subsequent calls reuse the
+    # cached set until the TTL expires or a kid miss forces a re-fetch.
+    #
+    # This is the core DX win behind a backend SDK — verify_token has no
+    # per-request round trip to torii.
+    module_function
+
+    # Time-to-live for the JWKS cache, in seconds. Matches the Node and
+    # Python SDKs (5 minutes).
+    JWKS_TTL_SECONDS = 300
+
+    # Internal: cached JWKS entry. +jwks+ is a JWT::JWK::Set, +fetched_at+ is
+    # a monotonic timestamp so cache TTL is robust against wall-clock changes.
+    @jwks_cache = {}
+    @jwks_cache_mutex = Mutex.new
+
+    class << self
+      attr_accessor :jwks_cache
+      attr_reader :jwks_cache_mutex
+    end
+
+    # Verify a torii-issued JWT against the issuer's JWKS.
+    #
+    # @param token [String] Compact JWS as received from the customer frontend.
+    # @param issuer [String] Expected issuer URL (per-tenant), e.g.
+    #   +https://acme.torii.so+ or +https://auth.acme.com+.
+    # @param audience [String, Array<String>, nil] Optional +aud+ claim to
+    #   enforce. torii doesn't set +aud+ today, so +nil+ skips the check.
+    # @param leeway [Integer] Clock-skew tolerance in seconds for +exp+/+nbf+.
+    # @return [Torii::Backend::Auth]
+    # @raise [Torii::Backend::AuthError] if signature, issuer, expiry, or
+    #   required claims fail validation.
+    def verify_token(token, issuer:, audience: nil, leeway: 30)
+      raise AuthError, 'verify_token: token must be a non-empty string' if !token.is_a?(String) || token.empty?
+      raise AuthError, 'verify_token: issuer is required' if !issuer.is_a?(String) || issuer.empty?
+
+      jwks = jwks_for_issuer(issuer)
+      verify_options = {
+        algorithm: 'ES256',
+        iss: issuer,
+        verify_iss: true,
+        verify_iat: true,
+        leeway: leeway,
+        jwks: jwks,
+      }
+      if audience
+        verify_options[:aud] = audience
+        verify_options[:verify_aud] = true
+      end
+
+      payload, =
+        begin
+          ::JWT.decode(token, nil, true, verify_options)
+        rescue ::JWT::JWKError, ::JWT::DecodeError, ::JWT::VerificationError => e
+          # kid miss can happen after rotation; flush this issuer's cache and
+          # retry once before giving up.
+          if e.is_a?(::JWT::DecodeError) && e.message.include?('Could not find public key')
+            invalidate_jwks(issuer)
+            begin
+              ::JWT.decode(token, nil, true, verify_options.merge(jwks: jwks_for_issuer(issuer)))
+            rescue ::JWT::DecodeError => retry_err
+              raise AuthError.new("JWT verification failed: #{retry_err.message}", cause: retry_err)
+            end
+          else
+            raise AuthError.new("JWT verification failed: #{e.message}", cause: e)
+          end
+        end
+
+      user_id = payload['sub']
+      environment_id = payload['pid']
+      iss = payload['iss']
+      unless user_id.is_a?(String) && environment_id.is_a?(String) && iss.is_a?(String)
+        raise AuthError,
+              "JWT is missing required string claims (sub=#{!user_id.nil?}, pid=#{!environment_id.nil?}, iss=#{!iss.nil?})"
+      end
+      raise AuthError, 'JWT missing iat claim' unless payload['iat']
+      raise AuthError, 'JWT missing exp claim' unless payload['exp']
+
+      locale = payload['locale']
+      Auth.new(
+        user_id: user_id,
+        environment_id: environment_id,
+        issuer: iss,
+        email_verified: payload['email_verified'] == true,
+        # profile_complete defaults to true when claim is absent (mirrors Node/Python SDK).
+        profile_complete: payload['profile_complete'] != false,
+        impersonating: payload['impersonating'] == true,
+        locale: locale.is_a?(String) ? locale : nil,
+        raw: payload,
+      )
+    end
+
+    # Internal: fetch+cache the JWKS for an issuer.
+    def jwks_for_issuer(issuer)
+      normalized = issuer.sub(%r{/+\z}, '')
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @jwks_cache_mutex.synchronize do
+        entry = @jwks_cache[normalized]
+        return entry[:jwks] if entry && (now - entry[:fetched_at]) < JWKS_TTL_SECONDS
+      end
+
+      fetched = fetch_jwks(normalized)
+      @jwks_cache_mutex.synchronize do
+        @jwks_cache[normalized] = { jwks: fetched, fetched_at: now }
+      end
+      fetched
+    end
+
+    # Internal: HTTP-fetch and parse the issuer's JWKS document.
+    def fetch_jwks(normalized_issuer)
+      url = URI.parse("#{normalized_issuer}/_torii/.well-known/jwks.json")
+      response =
+        begin
+          http = Net::HTTP.new(url.host, url.port)
+          http.use_ssl = (url.scheme == 'https')
+          http.open_timeout = 10
+          http.read_timeout = 10
+          http.request_get(url.request_uri, { 'accept' => 'application/json' })
+        rescue StandardError => e
+          raise AuthError.new("Failed to fetch JWKS from #{url}: #{e.message}", cause: e)
+        end
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise AuthError, "Failed to fetch JWKS from #{url}: HTTP #{response.code}"
+      end
+
+      begin
+        parsed = JSON.parse(response.body)
+      rescue JSON::ParserError => e
+        raise AuthError.new("JWKS at #{url} is not valid JSON: #{e.message}", cause: e)
+      end
+
+      ::JWT::JWK::Set.new(parsed)
+    end
+
+    # Internal: drop the cache entry for a specific issuer.
+    def invalidate_jwks(issuer)
+      normalized = issuer.sub(%r{/+\z}, '')
+      @jwks_cache_mutex.synchronize { @jwks_cache.delete(normalized) }
+    end
+
+    # Test-only: clear all cached JWKS. Production code should not need
+    # this — the cache TTL plus rotation-on-kid-miss handles real-world
+    # key rotation automatically.
+    def clear_jwks_cache_for_tests
+      @jwks_cache_mutex.synchronize { @jwks_cache.clear }
+    end
+  end
+end

data/src/torii/backend/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Torii
+  module Backend
+    VERSION = '0.0.2'
+  end
+end

data/src/torii/backend/webhook.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+module Torii
+  module Backend
+    module_function
+
+    # Verify an outbound torii webhook signature.
+    #
+    # WARNING: torii's outbound webhook subsystem is not yet available. This
+    # stub reserves the SDK surface so adopting it later won't be a breaking
+    # change for callers.
+    def verify_webhook(secret:, headers:, payload:) # rubocop:disable Lint/UnusedMethodArgument
+      raise AuthError,
+            "verifyWebhook: torii's outbound webhook subsystem is not yet available."
+    end
+  end
+end

data/src/torii/backend.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Public entry point for torii-backend. Requires lazy-load all
+# sub-modules — load order matters only to keep cycles out, not for
+# correctness, since each sub-module +require_relative+s its own
+# dependencies.
+
+require_relative 'backend/version'
+require_relative 'backend/errors'
+require_relative 'backend/auth'
+require_relative 'backend/verify'
+require_relative 'backend/authenticate_request'
+require_relative 'backend/webhook'
+require_relative 'backend/patch'
+require_relative 'backend/client'
+require_relative 'backend/rack'
+
+module Torii
+  # Backend SDK for torii. See {https://torii.so torii.so} for documentation.
+  module Backend
+  end
+end

data/src/torii-backend-generated.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Bridge shim: the openapi-generator output is vendored under
+# +lib/torii/backend/generated/lib+ to keep it isolated from
+# hand-written code. We add that directory to +$LOAD_PATH+ here and
+# then load the generated entry point so callers can simply
+# +require 'torii-backend-generated'+ from anywhere in the gem.
+
+generated_root = File.expand_path('torii/backend/generated/lib', __dir__)
+$LOAD_PATH.unshift(generated_root) unless $LOAD_PATH.include?(generated_root)
+
+require 'torii-backend-generated/api_client'
+require 'torii-backend-generated/api_error'
+require 'torii-backend-generated/api_model_base'
+require 'torii-backend-generated/version'
+require 'torii-backend-generated/configuration'
+
+require 'torii-backend-generated/models/create_user_request'
+require 'torii-backend-generated/models/cursor_page_response_user_response'
+require 'torii-backend-generated/models/server_user_search_request'
+require 'torii-backend-generated/models/update_user_request'
+require 'torii-backend-generated/models/user_response'
+require 'torii-backend-generated/models/user_session_response'
+
+require 'torii-backend-generated/api/server_sessions_api'
+require 'torii-backend-generated/api/server_users_api'

metadata

@@ -0,0 +1,163 @@
+--- !ruby/object:Gem::Specification
+name: torii-backend
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- torii
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: typhoeus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+description: |
+  Backend SDK for torii. Verify end-user JWTs without a per-request
+  round-trip, call /api/server/v1/** with a secret key, and react to
+  events from torii. Ships with Rack middleware that works with Rails,
+  Sinatra, Roda, and anything else Rack-compatible.
+email:
+- hello@torii.so
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- spec/server-v1.json
+- src/torii-backend-generated.rb
+- src/torii/backend.rb
+- src/torii/backend/auth.rb
+- src/torii/backend/authenticate_request.rb
+- src/torii/backend/client.rb
+- src/torii/backend/errors.rb
+- src/torii/backend/generated/lib/torii-backend-generated.rb
+- src/torii/backend/generated/lib/torii-backend-generated/api/server_sessions_api.rb
+- src/torii/backend/generated/lib/torii-backend-generated/api/server_users_api.rb
+- src/torii/backend/generated/lib/torii-backend-generated/api_client.rb
+- src/torii/backend/generated/lib/torii-backend-generated/api_error.rb
+- src/torii/backend/generated/lib/torii-backend-generated/api_model_base.rb
+- src/torii/backend/generated/lib/torii-backend-generated/configuration.rb
+- src/torii/backend/generated/lib/torii-backend-generated/models/create_user_request.rb
+- src/torii/backend/generated/lib/torii-backend-generated/models/cursor_page_response_user_response.rb
+- src/torii/backend/generated/lib/torii-backend-generated/models/problem_detail.rb
+- src/torii/backend/generated/lib/torii-backend-generated/models/server_user_search_request.rb
+- src/torii/backend/generated/lib/torii-backend-generated/models/update_user_request.rb
+- src/torii/backend/generated/lib/torii-backend-generated/models/user_response.rb
+- src/torii/backend/generated/lib/torii-backend-generated/models/user_session_response.rb
+- src/torii/backend/generated/lib/torii-backend-generated/version.rb
+- src/torii/backend/patch.rb
+- src/torii/backend/rack.rb
+- src/torii/backend/verify.rb
+- src/torii/backend/version.rb
+- src/torii/backend/webhook.rb
+homepage: https://github.com/Torii-ApS/torii-sdk-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Torii-ApS/torii-sdk-ruby
+  source_code_uri: https://github.com/Torii-ApS/torii-sdk-ruby
+  bug_tracker_uri: https://github.com/Torii-ApS/torii-sdk-ruby/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- src
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.27
+signing_key:
+specification_version: 4
+summary: Backend SDK for torii — verify JWTs and call the server API.
+test_files: []