ohauthcat 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a0c59afce443365c755849cc1d3091effaab35db9c2cbaefe66b5f236fedc146
+  data.tar.gz: 6e04987049f21d722eb0dfcefd7b312ab46503d3935e2e6d76d5dab20b583d05
+SHA512:
+  metadata.gz: 626c678287200914a7bb4685ee3df8e5ea2bfe038de5dd54d30d57a984245ae59a3de854bdb0ad99cf0e718df82d87b99b3a66369002e494f5ce414f3db16345
+  data.tar.gz: 3c07a3d8924eb21990bbd7a61154f90386bca15e8cd3fbee952c30b99d8fdf10306d7202601af2ac93741a222707f80ff7f805142d3ee4a262e8b41046ad16ca

data/LICENSE

@@ -0,0 +1,35 @@
+OhAuthCat SDK and CLI Licence
+
+Copyright (c) 2026 Generic Technologies Private Limited. All rights reserved.
+OhAuthCat is a product of Generic Technologies Private Limited.
+
+This software development kit (the "Software") is licensed, not sold, under
+the OhAuthCat SDK and CLI Licence, version 1.0, published at
+https://ohauthcat.com/legal/sdk-licence (the "Licence"). By downloading,
+installing or using the Software you accept the Licence. The summary below is
+for convenience; if it differs from the Licence, the Licence prevails.
+
+While you have an active agreement with OhAuthCat for its hosted service, you
+may use, copy, read, modify and make derivative works of the Software, and
+distribute it, modified or not, only as an integrated part of your own
+application, solely to access and use the OhAuthCat service.
+
+You must not:
+
+1. use the Software, or any modified version or part of it, with any service
+   other than the OhAuthCat service;
+2. distribute, publish or make the Software, or any modified version or part
+   of it, available on its own, as a standalone library, package, SDK, fork or
+   tool;
+3. remove or alter any copyright notice, this file or THIRD_PARTY_LICENSES;
+4. use the Software or its source code to build or help build a product or
+   service that competes with the OhAuthCat service; or
+5. license or distribute the Software under terms that would require it to be
+   disclosed or licensed as open source or distributed free of charge.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, TO THE EXTENT THE LAW ALLOWS. LIABILITY IS LIMITED AS SET OUT IN THE
+LICENCE.
+
+Third-party components distributed with the Software are listed in
+THIRD_PARTY_LICENSES and are governed by their own licences.

data/README.md

@@ -0,0 +1,94 @@
+# OhAuthCat Ruby SDK
+
+Server-side SDK for OhAuthCat enterprise SSO (SAML, OIDC) and SCIM directory sync.
+Ruby 3.2+, standard library only (no runtime gem dependencies).
+
+## Install
+
+```sh
+gem install ohauthcat -v 0.0.2
+```
+
+### Before the first release
+
+The `ohauthcat` gem is not published to RubyGems yet, so the install command above fails until the first release. Until then, install it from the source repository. The repository is private: you need read access to `bitbucket.org/the-genie-team/ohauthcat-sdk-ruby` over SSH. Run these commands from your project directory; the `v0.0.2` tag matches the version above (until that tag exists, replace `--branch v0.0.2` with `--branch dev` in the `git clone` command).
+
+```sh
+git clone --depth 1 --branch v0.0.2 git@bitbucket.org:the-genie-team/ohauthcat-sdk-ruby.git
+(cd ohauthcat-sdk-ruby && gem build ohauthcat.gemspec)
+gem install ./ohauthcat-sdk-ruby/ohauthcat-0.0.2.gem
+```
+
+Documentation: https://docs.ohauthcat.com. Licensed under the OhAuthCat SDK Licence (see `LICENSE`); third-party notices are in `THIRD_PARTY_LICENSES`.
+
+```ruby
+require "ohauthcat"
+
+client = OhAuthCat::Client.new(api_key: ENV.fetch("OHAUTHCAT_API_KEY"), client_id: "pk_...")
+
+org = client.organizations.get_organization("org_...")
+client.directories.list_directory_users_auto_paging("dir_...", query: { limit: 100 }).each { |user| }
+
+# Webhooks: verify the raw body before parsing.
+event = OhAuthCat::Webhooks.verify(request.raw_post, request.headers["OhAuthCat-Signature"], secret)
+```
+
+## Sign-in
+
+Every sign-in needs a random `state` that you keep in the user's session and compare on the callback, or an attacker can sign your user into the attacker's account (login CSRF). `get_authorization_url` generates one when you pass none and returns it as `auth[:state]`, with the PKCE `auth[:code_verifier]`. Refuse a missing or different state before exchanging the code (Rails controller shown):
+
+```ruby
+REDIRECT_URI = "https://app.example.com/callback"
+
+def sso_start
+  auth = client.sso_helpers.get_authorization_url(redirect_uri: REDIRECT_URI, domain: "customer.com")
+  session[:sso_state] = auth[:state]
+  session[:sso_verifier] = auth[:code_verifier]
+  redirect_to auth[:url], allow_other_host: true
+end
+
+def sso_callback
+  expected = session.delete(:sso_state).to_s
+  verifier = session.delete(:sso_verifier).to_s
+  unless !expected.empty? && !verifier.empty? &&
+         ActiveSupport::SecurityUtils.secure_compare(expected, params[:state].to_s)
+    return head :bad_request # never exchange the code
+  end
+
+  result = client.sso_helpers.get_profile_and_token(code: params[:code].to_s, code_verifier: verifier,
+                                                    redirect_uri: REDIRECT_URI)
+  # result.profile.email: create your session for this user
+rescue OhAuthCat::RestartSignInError
+  redirect_to "/login" # the code was used or expired; start again
+end
+```
+
+Outside Rails, compare with `OpenSSL.fixed_length_secure_compare` after checking both strings have the same length.
+
+Guests: a sign-in admitted under the organization's guest policy (an email domain outside its verified domains) has `OhAuthCat::AccessPolicy.guest?(result.profile)` true (`access_policy` is `AccessPolicy::GUEST`); for every other sign-in the field is absent. `email_domain_verified` stays true for guests, so check this field when guests must get less access.
+
+## Portal links
+
+A setup link lasts `expires_in` seconds, 300 (5 minutes) to 2,592,000 (30 days); leave it out for the default of 604,800 (7 days). A link created with a secret key opens once; revoke it to end it early, and `expires_at` on the result says when it ends. `ttl` (60 to 300 seconds) is only for sealed single-use embed links; never send both.
+
+```ruby
+link = client.portal.create_portal_link({ "organization" => "org_...", "intents" => ["sso"], "expires_in" => 86_400 })
+link.url
+```
+
+- Every v1 operation is generated from the pinned spec. Responses are typed models
+  (`OhAuthCat::Models::*`, for example `org.name`), validated against the spec; `model.to_h` is the raw
+  JSON escape hatch. Request bodies take a model or a Hash.
+- Standby failover: after 3 consecutive edge failures the client moves to `api.oauthcat.com` /
+  `auth.oauthcat.com`, re-probes the primary every 60 s and returns when healthy (`standby:`,
+  `standby_api_base_url:`, `standby_auth_base_url:`, `standby_threshold:`, `standby_cooldown:`).
+- Errors are `OhAuthCat::Error` subclasses by type (`NotFoundError`, `RateLimitedError`, ...)
+  with the stable `code` (see `OhAuthCat::Generated::ERROR_CODES`).
+- Writes carry an `Idempotency-Key` (generated, or `idempotency_key:`). GETs and keyed writes retry
+  on 429/503 with backoff; the SSO code exchange is never retried.
+
+Development: `make ruby-test` and `make ruby-contract` from the repository root.
+
+## Development
+
+This repository holds only the ruby SDK. Contributor commands, the generator and the rules are in [AGENTS.md](AGENTS.md); releases in [RELEASING.md](RELEASING.md). Generated code comes from the pinned API spec in `spec/`; never edit it by hand.

data/THIRD_PARTY_LICENSES

@@ -0,0 +1,5 @@
+The OhAuthCat Ruby SDK uses only the Ruby standard library (net/http, json,
+openssl, securerandom, uri). It bundles and depends on no third-party gems.
+
+Development-only (never a gem dependency): minitest (MIT), run from the
+Ruby installation's bundled gems.

data/lib/ohauthcat/access_policy.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module OhAuthCat
+  # Values of Profile#access_policy.
+  module AccessPolicy
+    # The sign-in was admitted under the organization's guest policy (a domain outside its verified domains).
+    GUEST = "guest"
+
+    # True when the profile signed in as a guest. email_domain_verified stays true for guests.
+    def self.guest?(profile)
+      !profile.nil? && profile.access_policy == GUEST
+    end
+  end
+end

data/lib/ohauthcat/client.rb

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+
+module OhAuthCat
+  # The OhAuthCat server SDK. Every v1 operation is on a resource group, for example
+  # client.organizations.get_organization("org_..."). Responses are decoded JSON (Hash, Array, ...).
+  class Client
+    include Generated::ResourceAccessors
+
+    API_VERSION = /\A1\.[0-9]+\z/
+
+    attr_reader :api_key, :client_id, :api_base_url, :auth_base_url, :api_version, :timeout, :max_retries, :max_pages
+
+    # transport: optional callable (method, uri, headers, body, timeout) -> [status, headers, body].
+    # sleeper: optional callable(seconds) used between retries.
+    def initialize(api_key:, client_id: nil, api_base_url: "https://api.ohauthcat.com",
+                   auth_base_url: "https://auth.ohauthcat.com", api_version: nil, timeout: 30,
+                   max_retries: 2, max_pages: 1000, transport: nil, sleeper: nil, standby: nil,
+                   standby_api_base_url: nil, standby_auth_base_url: nil, standby_threshold: 3,
+                   standby_cooldown: 60, clock: nil)
+      raise ArgumentError, "api_key is required" unless api_key.is_a?(String) && !api_key.strip.empty? && header_text?(api_key)
+      if client_id && !(client_id.start_with?("pk_") && client_id.length > 3 && header_text?(client_id))
+        raise ArgumentError, "client_id must be a publishable key (pk_...)"
+      end
+      raise ArgumentError, "api_version must look like 1.N" if api_version && !api_version.match?(API_VERSION)
+      raise ArgumentError, "timeout must be positive" unless timeout.is_a?(Numeric) && timeout.positive?
+      raise ArgumentError, "max_retries must be 0..10" unless max_retries.is_a?(Integer) && max_retries.between?(0, 10)
+      raise ArgumentError, "max_pages must be positive" unless max_pages.is_a?(Integer) && max_pages.positive?
+
+      @api_key = api_key
+      @client_id = client_id
+      @api_base_url = base(api_base_url)
+      @auth_base_url = base(auth_base_url)
+      @api_version = api_version
+      @timeout = timeout
+      @max_retries = max_retries
+      @max_pages = max_pages
+      @transport = transport || method(:net_http)
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+      @standby = Standby.new(api: @api_base_url, auth: @auth_base_url, enabled: standby,
+                             fallback_api: standby_api_base_url, fallback_auth: standby_auth_base_url,
+                             threshold: standby_threshold, cooldown: standby_cooldown,
+                             clock: clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+    end
+
+    # The edge failover state (see Standby).
+    attr_reader :standby
+
+    def sso_helpers
+      @sso_helpers ||= SsoHelpers.new(self)
+    end
+
+    def passkey_helpers
+      @passkey_helpers ||= PasskeyHelpers.new(self)
+    end
+
+    def webhooks
+      Webhooks
+    end
+
+    # Sends one operation by name. Options: idempotency_key:, timeout:, max_retries:, access_token:.
+    def request(operation, path, query, body, **options)
+      send_request(operation, path, query, body, **options)[:value]
+    end
+
+    # Enumerates every item of a list operation, following next_cursor.
+    def paginate(operation, path, query, model: nil, **options)
+      route = route(operation)
+      raise Error.client("invalid_pagination") unless route.list
+
+      start = (query || {}).transform_keys(&:to_s)
+      raise Error.client("invalid_pagination") if start.key?("before")
+
+      Enumerator.new do |out|
+        q = start.dup
+        seen = {}
+        seen[q["after"]] = true if q["after"].is_a?(String) && !q["after"].empty?
+        pages = 0
+        loop do
+          raise Error.client("invalid_pagination") if (pages += 1) > @max_pages
+
+          result = request(operation, path, q, nil, **options)
+          raise Error.client("response_invalid") unless result.is_a?(Hash) && result["data"].is_a?(Array)
+
+          data = result["data"]
+          more = result["has_more"] == true
+          cursor = result["next_cursor"]
+          if more && (!cursor.is_a?(String) || cursor.empty? || data.empty? || seen[cursor])
+            raise Error.client("invalid_pagination")
+          end
+
+          data.each { |item| out << (model ? model.from_json(item) : item) }
+          break unless more
+
+          seen[cursor] = true
+          q["after"] = cursor
+        end
+      end
+    end
+
+    # Operations whose request body is not JSON, with the media type sent as Content-Type.
+    # The pinned contract does not carry request media, so a test checks this list against the spec.
+    RAW_BODY_MEDIA = {
+      "confirmDirectorySourceOAuth" => "application/x-www-form-urlencoded",
+      "importDirectoryCSV" => "text/csv",
+      "importPortalDirectoryCSV" => "text/csv",
+      "removeFromWaitlistOneClick" => "application/x-www-form-urlencoded",
+      "unsubscribeSubprocessorNoticesOneClick" => "application/x-www-form-urlencoded"
+    }.freeze
+
+    # Replaces the users and groups of a directory whose provider is csv with the content of the
+    # file (a String, sent as-is), as a text/csv body. The generated
+    # directories.import_directory_c_s_v cannot send this body. Options as for #request.
+    def import_directory_csv(directory, csv, dry_run: nil, **options)
+      raise Error.client("request_invalid") unless directory.is_a?(String) && !directory.strip.empty?
+      raise Error.client("request_invalid") unless csv.is_a?(String) && !csv.empty?
+      raise Error.client("request_invalid") unless dry_run.nil? || dry_run == true || dry_run == false
+
+      query = dry_run.nil? ? nil : { "dry_run" => dry_run }
+      value = send_request("importDirectoryCSV", [directory], query, nil, raw_body: csv, **options)[:value]
+      Models::DirectorySyncResult.from_json(value)
+    end
+
+    def send_request(operation, path, query, body, idempotency_key: nil, timeout: nil, max_retries: nil, access_token: nil, raw_body: nil)
+      raise Error.client("request_invalid") if !raw_body.nil? && (!body.nil? || !RAW_BODY_MEDIA.key?(operation) || !raw_body.is_a?(String))
+
+      route = route(operation)
+      build_uri(route, path, query, @api_base_url)
+      token = @api_key
+      if route.auth == "accessToken"
+        raise Error.client("request_invalid") unless access_token.is_a?(String) && !access_token.strip.empty? && header_text?(access_token)
+
+        token = access_token
+      elsif access_token
+        raise Error.client("request_invalid")
+      end
+      headers = {
+        "Authorization" => "Bearer #{token}",
+        "Accept" => route.media.empty? ? "application/json" : route.media,
+        "User-Agent" => "ohauthcat-sdk-ruby/#{VERSION}"
+      }
+      headers["OhAuthCat-Version"] = @api_version if @api_version
+      retryable = %w[GET HEAD].include?(route.method)
+      if route.method != "GET"
+        key = idempotency_key || SecureRandom.uuid
+        raise Error.client("request_invalid") if !key.is_a?(String) || key.strip.empty? || key.length > 255 || !header_text?(key)
+
+        headers["Idempotency-Key"] = key
+        retryable = route.idempotent_key
+      end
+      # A consumed authorization code must never be replayed.
+      retryable = false if operation == "exchangeSsoCode"
+      payload = nil
+      if !raw_body.nil?
+        payload = raw_body.b
+        headers["Content-Type"] = RAW_BODY_MEDIA.fetch(operation)
+      elsif !body.nil?
+        payload = JSON.generate(Model.encode(body))
+        headers["Content-Type"] = "application/json"
+      end
+      retries = max_retries || @max_retries
+      request_timeout = timeout || @timeout
+      probe(request_timeout)
+      primary_error = nil
+      2.times do
+        snap = @standby.snapshot(route.server == :auth)
+        uri = build_uri(route, path, query, snap.origin)
+        begin
+          result = attempt(route, uri, headers, payload, request_timeout, retries, retryable, snap)
+          @standby.success(snap.revision) unless snap.on_standby
+          return result
+        rescue Error => e
+          unless Standby.edge_error?(e)
+            @standby.success(snap.revision) if !snap.on_standby && e.status >= 400
+            raise
+          end
+          if snap.on_standby
+            @standby.unavailable(snap.revision)
+            raise(primary_error || snap.retained || e)
+          end
+          switched = @standby.edge(snap.revision, e)
+          if primary_error.nil? && switched && retryable
+            primary_error = e
+            next
+          end
+          raise
+        end
+      end
+      raise ConnectionError.new("The request could not be sent", code: "transport_error")
+    end
+
+    def attempt(route, uri, headers, payload, request_timeout, retries, retryable, snap)
+      attempt = 0
+      loop do
+        status, response_headers, raw = call_transport(route.method, uri, headers, payload, request_timeout)
+        @standby.success(snap.revision) if !snap.on_standby && [429, 503].include?(status)
+        if [429, 503].include?(status) && retryable && attempt < retries
+          delay = self.class.retry_delay(header(response_headers, "Retry-After"), attempt)
+          if delay
+            @sleeper.call(delay)
+            attempt += 1
+            next
+          end
+        end
+        request_id = header(response_headers, "Request-Id")
+        raise Error.from_response(status, raw, request_id) unless status.between?(200, 299)
+        return { status: status, value: nil, request_id: request_id } if status == 204 || raw.nil? || raw.empty?
+
+        text = raw.dup.force_encoding(Encoding::UTF_8)
+        return { status: status, value: text, request_id: request_id } if !route.media.empty? && route.media != "application/json"
+
+        begin
+          return { status: status, value: JSON.parse(text), request_id: request_id }
+        rescue JSON::ParserError, EncodingError
+          raise Error.new("The response was not valid JSON", code: "response_invalid", status: status, request_id: request_id)
+        end
+      end
+    end
+
+    # Re-probes the primary origins while on standby: both must answer /healthz with {"status":"ok"}.
+    def probe(request_timeout)
+      revision = @standby.begin_probe
+      return if revision.nil?
+
+      healthy = false
+      begin
+        cap = [request_timeout, 1].min
+        healthy = [@standby.api, @standby.auth].all? do |origin|
+          status, _headers, raw = @transport.call("GET", URI.parse("#{origin}/healthz"), { "Accept" => "application/json" }, nil, cap)
+          status == 200 && raw.to_s.bytesize <= 1024 && JSON.parse(raw.to_s) == { "status" => "ok" }
+        end
+      rescue StandardError
+        healthy = false
+      ensure
+        @standby.finish_probe(revision, healthy)
+      end
+    end
+
+    # Retry-After seconds or HTTP date, else jittered exponential backoff; nil when too long.
+    def self.retry_delay(value, attempt)
+      if value.is_a?(String)
+        text = value.strip
+        if text.match?(/\A\d+(\.\d+)?\z/)
+          seconds = text.to_f
+          return seconds > 60 ? nil : seconds
+        end
+        begin
+          seconds = Time.httpdate(text) - Time.now
+          return seconds > 60 ? nil : seconds if seconds >= 0
+        rescue ArgumentError
+          nil
+        end
+      end
+      limit = [10.0, 2**attempt.clamp(0, 4)].min
+      (limit / 2) + (rand * limit / 2)
+    end
+
+    private :attempt, :probe
+
+    private
+
+    def route(operation)
+      Generated::ROUTES[operation] || raise(Error.client("unknown_operation"))
+    end
+
+    def base(url)
+      uri = URI.parse(url.to_s)
+      raise ArgumentError, "invalid base URL" unless %w[http https].include?(uri.scheme) && uri.host && uri.query.nil? && uri.fragment.nil?
+
+      url.to_s.chomp("/")
+    rescue URI::InvalidURIError
+      raise ArgumentError, "invalid base URL"
+    end
+
+    def header_text?(value)
+      value.match?(/\A[\x20-\x7e]*\z/)
+    end
+
+    def header(headers, name)
+      headers&.each { |k, v| return v if k.to_s.casecmp?(name) }
+      nil
+    end
+
+    def encode(value)
+      URI.encode_www_form_component(value.to_s).gsub("+", "%20")
+    end
+
+    def build_uri(route, path, query, base_url)
+      values = Array(path)
+      index = 0
+      built = route.path.gsub(/\{[^}]+\}/) do
+        value = values[index]
+        index += 1
+        raise Error.client("request_invalid") unless value.is_a?(String) && !value.strip.empty?
+
+        encode(value)
+      end
+      raise Error.client("request_invalid") unless index == values.length
+
+      pairs = []
+      (query || {}).each do |key, value|
+        Array(value).each do |item|
+          next if item.nil?
+          raise Error.client("request_invalid") if item.is_a?(Hash) || item.is_a?(Array)
+
+          pairs << "#{encode(key)}=#{encode(item)}"
+        end
+      end
+      URI.parse(base_url + built + (pairs.empty? ? "" : "?#{pairs.join("&")}"))
+    end
+
+    def call_transport(http_method, uri, headers, payload, timeout)
+      @transport.call(http_method, uri, headers, payload, timeout)
+    rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, Timeout::Error
+      raise ConnectionError.new("The request timed out", code: "request_timeout")
+    rescue Error
+      raise
+    rescue StandardError
+      raise ConnectionError.new("The request could not be sent", code: "transport_error")
+    end
+
+    def net_http(http_method, uri, headers, payload, timeout)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = [timeout, 10].min
+      http.read_timeout = timeout
+      http.write_timeout = timeout
+      request = Net::HTTPGenericRequest.new(http_method, !payload.nil?, true, uri.request_uri, headers)
+      request.body = payload if payload
+      response = http.start { |connection| connection.request(request) }
+      [response.code.to_i, response.each_header.to_h, response.body.to_s]
+    end
+  end
+end

data/lib/ohauthcat/errors.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module OhAuthCat
+  UNKNOWN_ERROR = "unknown_error"
+
+  # An error returned by, or while talking to, the OhAuthCat API. Subclasses follow the
+  # catalogue's error type; #code is the stable code (see Generated::ERROR_CODES).
+  class Error < StandardError
+    attr_reader :code, :status, :type, :param, :doc_url, :request_id
+
+    def initialize(message, code:, status: 0, type: nil, param: nil, doc_url: nil, request_id: nil)
+      super(message)
+      @code = code
+      @status = status
+      @type = type
+      @param = param
+      @doc_url = doc_url
+      @request_id = request_id
+    end
+
+    # Error catalogue page for a code.
+    def self.doc_url_for(code)
+      "https://docs.ohauthcat.com/errors/#{code}"
+    end
+
+    # A refusal raised by the SDK before any request. With param, the message and #param
+    # name the argument that was wrong.
+    def self.client(code, param = nil)
+      message = "OhAuthCat SDK error: #{code}"
+      message += " (#{param} is missing or invalid)" if param
+      Error.new(message, code: code, param: param, doc_url: doc_url_for(code))
+    end
+
+    # Builds the typed error from a raw error body. Never raises.
+    def self.from_response(status, body, request_id_header = nil)
+      header_id = trimmed(request_id_header)
+      parsed = begin
+        JSON.parse(body.to_s)
+      rescue JSON::ParserError, EncodingError
+        nil
+      end
+      inner = parsed.is_a?(Hash) ? parsed["error"] : nil
+      unless inner.is_a?(Hash)
+        return Error.new("Unexpected error response (HTTP #{status})", code: UNKNOWN_ERROR, status: status, request_id: header_id)
+      end
+
+      field = ->(key) { trimmed(inner[key]) }
+      code = field.call("code") || UNKNOWN_ERROR
+      klass = code == "plan_limit_reached" ? PlanLimitReachedError : TYPES.fetch(field.call("type"), Error)
+      klass.new(field.call("message") || "OhAuthCat API error: #{code}",
+                code: code, status: status, type: field.call("type"), param: field.call("param"),
+                doc_url: field.call("doc_url"), request_id: field.call("request_id") || header_id)
+    end
+
+    def self.trimmed(value)
+      return nil unless value.is_a?(String)
+
+      text = value.strip
+      text.empty? ? nil : text
+    end
+  end
+
+  class InvalidRequestError < Error; end
+  class AuthenticationError < Error; end
+  class PermissionError < Error; end
+  # plan_limit_reached: the plan refuses this growth. #metric is the enforced monthly ceiling
+  # named in param, or nil when the refusal is about a resource count or a missing feature.
+  # Existing resources and users keep working.
+  class PlanLimitReachedError < PermissionError
+    METRICS = %w[monthly_active_users audit_log_events pipes_token_fetches].freeze
+
+    def metric
+      METRICS.include?(param) ? param : nil
+    end
+  end
+
+  class NotFoundError < Error; end
+  class ConflictError < Error; end
+  class RateLimitedError < Error; end
+  class IdpError < Error; end
+  class UnavailableError < Error; end
+  # The network failed or timed out (codes transport_error, request_timeout).
+  class ConnectionError < Error; end
+
+  # The authorization code cannot be reused: start a fresh sign-in.
+  class RestartSignInError < Error
+    def initialize(cause_error)
+      super("Restart the sign-in flow", code: cause_error.code, status: cause_error.status, type: cause_error.type,
+                                        param: cause_error.param, doc_url: cause_error.doc_url, request_id: cause_error.request_id)
+    end
+  end
+
+  Error::TYPES = {
+    "invalid_request" => InvalidRequestError, "authentication" => AuthenticationError,
+    "permission" => PermissionError, "not_found" => NotFoundError, "conflict" => ConflictError,
+    "rate_limited" => RateLimitedError, "idp_error" => IdpError, "unavailable" => UnavailableError
+  }.freeze
+end