ohauthcat 0.0.2

data/lib/ohauthcat/passkey_helpers.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module OhAuthCat
+  # Headless end-user passkey helpers: session sign-in and passkey rename.
+  class PasskeyHelpers
+    # The session a passkey sign-in created: the token set issued by the login host,
+    # audience the client ID, as /user_management/token would return it.
+    PasskeySession = Struct.new(:authentication, :session_id, :access_token, :refresh_token, :id_token,
+                                :token_type, :expires_in, keyword_init: true)
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Trims value and raises request_invalid when it is blank, longer than maximum
+    # characters or contains control characters.
+    def self.bounded(value, maximum)
+      raise Error.client("request_invalid") unless value.is_a?(String)
+
+      text = value.strip
+      raise Error.client("request_invalid") if text.empty? || text.length > maximum || text.match?(/[\x00-\x1f\x7f]/)
+
+      text
+    end
+
+    # Verifies a WebAuthn assertion (the decoded JSON credential) and creates a session for
+    # client_id (the configured publishable key by default). When the environment requires
+    # MFA and the assertion was not user-verified, the API answers mfa_required instead.
+    def authenticate_with_session(credential, client_id: nil)
+      raise Error.client("request_invalid") unless credential.is_a?(Hash)
+
+      audience = client_id.nil? ? @client.client_id : self.class.bounded(client_id, 256)
+      raise Error.client("request_invalid") if audience.nil?
+
+      body = { "credential" => credential, "session" => true, "client_id" => audience }
+      result = Models::EndUserPasskeyAuthentication.from_json(@client.request("authenticateEndUserPasskey", [], nil, body))
+      tokens = [result.session_id, result.access_token, result.refresh_token, result.id_token, result.expires_in]
+      raise Error.client("passkey_session_missing") if tokens.any?(&:nil?)
+
+      PasskeySession.new(authentication: result, session_id: result.session_id, access_token: result.access_token,
+                         refresh_token: result.refresh_token, id_token: result.id_token, token_type: "Bearer",
+                         expires_in: result.expires_in)
+    end
+
+    # Renames one of the user's passkeys (trimmed, 1 to 64 characters, no control characters).
+    # Another user's passkey answers resource_not_found.
+    def rename_passkey(user, passkey, name)
+      path = [self.class.bounded(user, 64), self.class.bounded(passkey, 64)]
+      body = { "name" => self.class.bounded(name, 64) }
+      Models::EndUserFactor.from_json(@client.request("updateEndUserPasskey", path, nil, body))
+    end
+  end
+end

data/lib/ohauthcat/route.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module OhAuthCat
+  # One API operation from the pinned spec.
+  Route = Struct.new(:name, :method, :path, :server, :auth, :media, :status, :idempotent_key, :list, keyword_init: true)
+end

data/lib/ohauthcat/sso_helpers.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module OhAuthCat
+  # SSO sign-in helpers: build the authorization URL with PKCE and exchange the code.
+  class SsoHelpers
+    VERIFIER = /\A[A-Za-z0-9._~-]{43,128}\z/
+    DOMAIN = /\A(?=.{1,253}\z)([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,63}\z/
+    ORG = /\Aorg_[0-9A-HJKMNP-TV-Z]{26}\z/
+    CONN = /\Aconn_[0-9A-HJKMNP-TV-Z]{26}\z/
+
+    def initialize(client)
+      @client = client
+    end
+
+    # RFC 7636 S256 challenge for a verifier.
+    def self.pkce_challenge(verifier)
+      raise Error.client("request_invalid") unless verifier.is_a?(String) && verifier.match?(VERIFIER)
+
+      [OpenSSL::Digest::SHA256.digest(verifier)].pack("m0").tr("+/", "-_").delete("=")
+    end
+
+    # Returns { url:, code_verifier:, state: }. Keep the verifier and state server-side;
+    # compare the callback state in constant time before the exchange. An empty state
+    # is replaced with a random one.
+    def get_authorization_url(redirect_uri:, state: "", organization: nil, connection: nil, domain: nil, login_hint: nil)
+      invalid = Error.client("request_invalid")
+      raise invalid if @client.client_id.nil?
+      raise invalid unless redirect_uri.is_a?(String) && !redirect_uri.empty? && redirect_uri.length <= 2048 && !redirect_uri.include?("#")
+
+      begin
+        uri = URI.parse(redirect_uri)
+      rescue URI::InvalidURIError
+        raise invalid
+      end
+      raise invalid unless %w[http https].include?(uri.scheme) && uri.host && !uri.host.empty? && uri.userinfo.nil?
+      raise invalid unless state.is_a?(String) && state.length <= 1024
+      raise invalid if organization && !organization.match?(ORG)
+      raise invalid if connection && !connection.match?(CONN)
+      raise invalid if domain && !domain.strip.match?(DOMAIN)
+
+      if login_hint
+        hint = login_hint.strip
+        parts = hint.split("@", -1)
+        raise invalid if hint.length > 320 || parts.length != 2 || parts[0].empty? || hint.match?(/[\s<>"]/) || !parts[1].match?(DOMAIN)
+      end
+      state = SecureRandom.urlsafe_base64(32, false) if state.empty?
+      verifier = SecureRandom.urlsafe_base64(32, false)
+      query = { "client_id" => @client.client_id, "redirect_uri" => redirect_uri, "response_type" => "code", "state" => state,
+                "code_challenge" => self.class.pkce_challenge(verifier), "code_challenge_method" => "S256" }
+      query["organization"] = organization if organization
+      query["connection"] = connection if connection
+      query["domain"] = domain if domain
+      query["login_hint"] = login_hint if login_hint
+      { url: "#{@client.standby.snapshot(true).origin}/sso/authorize?#{URI.encode_www_form(query)}", code_verifier: verifier, state: state }
+    end
+
+    # Exchanges the code once (never retried). Raises RestartSignInError when the user must sign in again.
+    def get_profile_and_token(code:, code_verifier:, redirect_uri:)
+      raise Error.client("request_invalid", "client_id") if @client.client_id.nil?
+      raise Error.client("request_invalid", "api_key") unless @client.api_key.start_with?("sk_")
+      raise Error.client("request_invalid", "code") unless code.is_a?(String) && !code.empty? && code.length <= 4096
+      raise Error.client("request_invalid", "redirect_uri") unless redirect_uri.is_a?(String) && !redirect_uri.empty? && redirect_uri.length <= 2048
+
+      self.class.pkce_challenge(code_verifier)
+      body = { "grant_type" => "authorization_code", "client_id" => @client.client_id, "code" => code,
+               "code_verifier" => code_verifier, "redirect_uri" => redirect_uri }
+      Models::SsoToken.from_json(@client.request("exchangeSsoCode", [], nil, body))
+    rescue Error => e
+      raise RestartSignInError, e if %w[invalid_grant flow_interrupted_retry pkce_verification_failed].include?(e.code) && !e.is_a?(RestartSignInError)
+
+      raise
+    end
+
+    TOKEN_TYPES = %w[urn:ietf:params:oauth:token-type:jwt urn:ietf:params:oauth:token-type:id_token].freeze
+
+    # A trusted-token profile with the OhAuthCat access token issued for it.
+    TrustedTokenAccess = Struct.new(:profile, :access_token, :token_type, :expires_in, keyword_init: true)
+
+    # Exchanges a trusted third-party token for its profile and an OhAuthCat access token whose
+    # audience is client_id (the configured publishable key by default). The token's sub is the
+    # profile ID (tprof_...), not an end-user ID; exchanged identities are not billable.
+    def exchange_trusted_token_for_access(subject_token:, subject_token_type: TOKEN_TYPES.first, client_id: nil)
+      invalid = Error.client("request_invalid")
+      raise invalid unless @client.api_key.start_with?("sk_")
+      raise invalid unless subject_token.is_a?(String) && !subject_token.strip.empty? && subject_token.length <= 16_384
+      raise invalid unless TOKEN_TYPES.include?(subject_token_type)
+
+      audience = client_id.nil? ? @client.client_id : PasskeyHelpers.bounded(client_id, 256)
+      raise invalid if audience.nil?
+
+      body = { "grant_type" => "urn:ietf:params:oauth:grant-type:token-exchange", "subject_token" => subject_token,
+               "subject_token_type" => subject_token_type, "client_id" => audience }
+      profile = Models::TrustedTokenProfile.from_json(@client.request("exchangeTrustedToken", [], nil, body))
+      raise Error.client("access_token_missing") if profile.access_token.nil? || profile.expires_in.nil?
+
+      TrustedTokenAccess.new(profile: profile, access_token: profile.access_token,
+                             token_type: profile.token_type || "Bearer", expires_in: profile.expires_in)
+    end
+  end
+end

data/lib/ohauthcat/standby.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module OhAuthCat
+  # Edge failover to the standby hosts (api./auth.oauthcat.com). After `threshold` consecutive
+  # edge failures (timeouts, transport errors, HTTP 520-539) requests go to the standby origins;
+  # the primary is re-probed at most every 60 s and used again once healthy. A failure on the
+  # standby path switches back and blocks failover for the cooldown.
+  class Standby
+    DEFAULT_API = "https://api.ohauthcat.com"
+    DEFAULT_AUTH = "https://auth.ohauthcat.com"
+    STANDBY_API = "https://api.oauthcat.com"
+    STANDBY_AUTH = "https://auth.oauthcat.com"
+    PROBE_INTERVAL = 60.0
+
+    Snapshot = Struct.new(:origin, :on_standby, :revision, :retained, keyword_init: true)
+
+    attr_reader :api, :auth, :fallback_api, :fallback_auth, :enabled
+
+    def initialize(api:, auth:, enabled:, fallback_api:, fallback_auth:, threshold:, cooldown:, clock:)
+      @api = api
+      @auth = auth
+      @fallback_api = self.class.trusted_origin(fallback_api || STANDBY_API)
+      @fallback_auth = self.class.trusted_origin(fallback_auth || STANDBY_AUTH)
+      custom = api != DEFAULT_API || auth != DEFAULT_AUTH
+      explicit = !fallback_api.nil? && !fallback_auth.nil?
+      raise ArgumentError, "invalid standby" unless [true, false, nil].include?(enabled)
+      raise ArgumentError, "custom primary origins require both standby origins" if enabled == true && custom && !explicit
+
+      @enabled = enabled != false && (!custom || explicit)
+      raise ArgumentError, "standby_threshold must be 1..100" unless threshold.is_a?(Integer) && threshold.between?(1, 100)
+      raise ArgumentError, "standby_cooldown must be 0.001..3600 s" unless cooldown.is_a?(Numeric) && cooldown >= 0.001 && cooldown <= 3600
+      if @enabled && (api == @fallback_api || auth == @fallback_auth)
+        raise ArgumentError, "standby origins must differ from primary origins"
+      end
+
+      @threshold = threshold
+      @cooldown = cooldown
+      @clock = clock
+      @lock = Mutex.new
+      @active = false
+      @failures = 0
+      @blocked_until = @probe_after = clock.call
+      @probing = false
+      @revision = 0
+      @primary_failure = nil
+    end
+
+    def self.trusted_origin(value)
+      uri = URI.parse(value.to_s)
+      local = uri.scheme == "http" && %w[localhost 127.0.0.1 ::1 [::1]].include?(uri.host)
+      unless (uri.scheme == "https" || local) && uri.host && !uri.host.empty? && uri.userinfo.nil? && uri.query.nil? &&
+             uri.fragment.nil? && ["", "/"].include?(uri.path.to_s) && uri.port != 0
+        raise ArgumentError, "invalid standby origin"
+      end
+
+      value.to_s.chomp("/")
+    rescue URI::InvalidURIError
+      raise ArgumentError, "invalid standby origin"
+    end
+
+    # Transport failures and Cloudflare 52x/53x, never API answers such as 429 or 503.
+    def self.edge_error?(error)
+      error.status.between?(520, 539) ||
+        (%w[transport_error request_timeout].include?(error.code) && ![429, 503].include?(error.status))
+    end
+
+    def snapshot(auth_host)
+      @lock.synchronize do
+        origin = if @active
+                   auth_host ? @fallback_auth : @fallback_api
+                 else
+                   auth_host ? @auth : @api
+                 end
+        Snapshot.new(origin: origin, on_standby: @active, revision: @revision, retained: @primary_failure)
+      end
+    end
+
+    def success(revision)
+      @lock.synchronize { @failures = 0 if revision == @revision && !@active }
+    end
+
+    def edge(revision, error)
+      @lock.synchronize do
+        return false if revision != @revision || !@enabled || @active
+
+        @failures += 1
+        return false if @failures < @threshold || @clock.call < @blocked_until
+
+        @active = true
+        @primary_failure = error
+        @probe_after = @clock.call + PROBE_INTERVAL
+        @revision += 1
+        true
+      end
+    end
+
+    def unavailable(revision)
+      @lock.synchronize do
+        next unless revision == @revision
+
+        @active = false
+        @failures = 0
+        @blocked_until = @clock.call + @cooldown
+        @revision += 1
+      end
+    end
+
+    def begin_probe
+      @lock.synchronize do
+        return nil if !@active || @probing || @clock.call < @probe_after
+
+        @probing = true
+        @probe_after = @clock.call + PROBE_INTERVAL
+        @revision
+      end
+    end
+
+    def finish_probe(revision, healthy)
+      @lock.synchronize do
+        @probing = false
+        if healthy && revision == @revision
+          @active = false
+          @failures = 0
+          @revision += 1
+        end
+      end
+    end
+  end
+end

data/lib/ohauthcat/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module OhAuthCat
+  VERSION = "0.0.2"
+end

data/lib/ohauthcat/webhooks.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module OhAuthCat
+  # Webhook signature verification (OhAuthCat-Signature: t=<unix>,v1=<hex>). Verify the raw
+  # body bytes before parsing; comparison is constant-time.
+  module Webhooks
+    SIGNATURE_HEADER = "OhAuthCat-Signature"
+    DEFAULT_TOLERANCE = 300
+    MAX_SAFE = (2**53) - 1
+
+    # Verification failed; #code never contains secrets, headers or the body.
+    class VerificationError < StandardError
+      attr_reader :code
+
+      def initialize(code)
+        super("Webhook verification failed: #{code}")
+        @code = code
+      end
+    end
+
+    module_function
+
+    def parse_header(header)
+      raise VerificationError, "header_missing" if !header.is_a?(String) || header.strip.empty?
+
+      timestamp = nil
+      signatures = []
+      header.split(",", -1).each do |part|
+        name, sep, value = part.strip.partition("=")
+        raise VerificationError, "header_invalid" if sep.empty?
+
+        case name
+        when "t"
+          raise VerificationError, "header_invalid" if timestamp || value.length > 20 || !value.match?(/\A[0-9]+\z/)
+
+          timestamp = value.to_i
+          raise VerificationError, "header_invalid" unless timestamp.positive? && timestamp <= MAX_SAFE
+        when "v1"
+          signature = value.downcase
+          signatures << signature if signature.bytesize == 64
+        end
+      end
+      raise VerificationError, "header_invalid" if timestamp.nil? || signatures.empty?
+
+      [timestamp, signatures]
+    end
+
+    # Hex HMAC-SHA256 over "<timestamp>.<body>", keyed by the whole UTF-8 secret.
+    def signature_digest(raw_body, timestamp, secret)
+      raise VerificationError, "body_invalid" unless raw_body.is_a?(String)
+      raise VerificationError, "secret_missing" unless secret.is_a?(String)
+
+      OpenSSL::HMAC.hexdigest("SHA256", secret.b, "#{timestamp}.".b + raw_body.b)
+    end
+
+    def verify_signature(raw_body, header, secrets, tolerance: DEFAULT_TOLERANCE, now: nil)
+      raise VerificationError, "body_invalid" unless raw_body.is_a?(String)
+      raise VerificationError, "options_invalid" unless tolerance.is_a?(Numeric) && tolerance.positive?
+
+      timestamp, signatures = parse_header(header)
+      current = now || Time.now.to_i
+      raise VerificationError, "timestamp_outside" if (current - timestamp).abs > tolerance
+
+      held = secrets.is_a?(String) ? [secrets] : secrets
+      raise VerificationError, "secret_missing" unless held.is_a?(Array) && held.all?(String)
+
+      matched = false
+      nonempty = false
+      held.each do |secret|
+        next if secret.empty?
+
+        nonempty = true
+        expected = signature_digest(raw_body, timestamp, secret)
+        signatures.each do |signature|
+          matched = OpenSSL.fixed_length_secure_compare(expected, signature) | matched
+        end
+      end
+      raise VerificationError, "secret_missing" unless nonempty
+      raise VerificationError, "signature_invalid" unless matched
+
+      nil
+    end
+
+    # Verifies the signature, then returns the decoded event Hash.
+    def verify(raw_body, header, secrets, tolerance: DEFAULT_TOLERANCE, now: nil)
+      verify_signature(raw_body, header, secrets, tolerance: tolerance, now: now)
+      event = begin
+        JSON.parse(raw_body.dup.force_encoding(Encoding::UTF_8))
+      rescue JSON::ParserError, EncodingError
+        raise VerificationError, "event_invalid"
+      end
+      raise VerificationError, "event_invalid" unless event.is_a?(Hash) && event["id"].is_a?(String) && event["type"].is_a?(String)
+
+      event
+    end
+  end
+end

data/lib/ohauthcat.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "securerandom"
+require "uri"
+
+require_relative "ohauthcat/version"
+require_relative "ohauthcat/errors"
+require_relative "ohauthcat/route"
+require_relative "ohauthcat/model"
+require_relative "ohauthcat/models"
+require_relative "ohauthcat/access_policy"
+require_relative "ohauthcat/standby"
+require_relative "ohauthcat/generated"
+require_relative "ohauthcat/webhooks"
+require_relative "ohauthcat/sso_helpers"
+require_relative "ohauthcat/passkey_helpers"
+require_relative "ohauthcat/client"

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: ohauthcat
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- OhAuthCat
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'Server-side SDK for OhAuthCat: enterprise SSO (SAML 2.0 and OIDC), SCIM
+  directory sync, webhooks and the management API.'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- THIRD_PARTY_LICENSES
+- lib/ohauthcat.rb
+- lib/ohauthcat/access_policy.rb
+- lib/ohauthcat/client.rb
+- lib/ohauthcat/errors.rb
+- lib/ohauthcat/generated.rb
+- lib/ohauthcat/model.rb
+- lib/ohauthcat/models.rb
+- lib/ohauthcat/passkey_helpers.rb
+- lib/ohauthcat/route.rb
+- lib/ohauthcat/sso_helpers.rb
+- lib/ohauthcat/standby.rb
+- lib/ohauthcat/version.rb
+- lib/ohauthcat/webhooks.rb
+homepage: https://ohauthcat.com
+licenses:
+- Nonstandard
+metadata:
+  homepage_uri: https://ohauthcat.com
+  documentation_uri: https://docs.ohauthcat.com
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: 'OhAuthCat server SDK: enterprise SSO and SCIM directory sync'
+test_files: []