onetimesecret 0.7.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f1df67fea362be27b61836f79fa41f0988658791171961427d10acf221af30a7
+  data.tar.gz: 39cca2de91250e4db32e68758c4718b687b90e7ef82ff05f934f1b15c3993c75
+SHA512:
+  metadata.gz: e5b5a3c0ed18e4fb7f811eb56894b90a1a6bb9336c734137e333bce0588be900f02904eb5d13d78e002af2c11fe0334b722757e1471a725cbafb198994ee445c
+  data.tar.gz: 8c1db673913c37a5c7317ea8969ad8956199455ac7ef67b7dc8788c6a9d1fc231e1a1358a08404e04396603dbf907350b73f4370a7b387be91c3474bdf009b0e

data/CHANGES.txt

@@ -0,0 +1,110 @@
+ONETIMESECRET, CHANGES
+
+#### 0.7.0 (unreleased; tag v0.7.0 to publish) #########
+
+* CHANGE: The canonical RubyGems package is now `onetimesecret`. Replace
+  `gem "onetime"` with `gem "onetimesecret"` in Gemfiles. The Ruby namespace
+  remains `Onetime`, and both `require "onetimesecret"` and `require "onetime"`
+  are supported. See docs/releasing.md for release and migration details.
+
+* DEPRECATED: `onetime` 0.7 is a dependency-only compatibility package that
+  installs `onetimesecret` and directs users to the canonical package.
+
+#### 0.6.0 (2026-07-30) ###############################
+
+  The first release of the `onetime` gem since 0.5.1 (2013): the same gem,
+  cleaned up and brought current. The API surface changes completely, and
+  the command-line tool moves out to `onetime-cli`, so treat this as a
+  rewrite rather than a drop-in upgrade. See docs/releasing.md for the
+  RubyGems publishing steps.
+
+* REWRITE: Modern, zero-dependency client built on stdlib Net::HTTP.
+  A clean break from 0.5.x (2013); no backward compatibility is maintained.
+
+* ADDED: Onetime::AccountRequiredError for responses that require an
+  authenticated account. The service reports this inside a 400 form-error
+  body (field "requires_account"), which previously surfaced as
+  BadRequestError and sent callers auditing a request body that was fine.
+  It subclasses AuthenticationError and preserves #field. Also matched via
+  error_key, code (e.g. GUEST_CONCEAL_REQUIRES_ACCOUNT) and the
+  RequiresAccount / AccountRequired error types.
+
+* ADDED: customer extid format validation at client construction. Values
+  that don't match the "ur..." extid shape are rejected immediately, with a
+  message that says where to find the right one.
+
+* ADDED: Release workflow (.github/workflows/release.yml) publishing to
+  RubyGems via Trusted Publishing on a v* tag, with a tag/version guard,
+  plus docs/releasing.md.
+
+* CHANGE: README installation instructions now ask for the `~> 0.6`
+  version constraint, and say why: the previous release under this gem
+  name is the 2013 command-line tool (0.5.1), which an unconstrained
+  dependency can still resolve to.
+
+* CHANGE: README authentication section now describes the customer extid
+  format up front, rather than contrasting it with the pre-1.0 email custid.
+
+* ADDED: Onetime::Client with secrets/receipts resources and meta methods.
+* ADDED: Support for the v1 and v2 APIs (selectable via api_version).
+* ADDED: Typed error hierarchy mapped to the ADR-013 wire format
+  ({ error, error_type, ... }) and legacy v1 { message } responses.
+* ADDED: Indifferent-access Onetime::Response wrapper.
+* ADDED: Anonymous / guest endpoint support for v2.
+* ADDED: Retries with exponential backoff for idempotent requests.
+* ADDED: Minitest test suite (unit + real Net::HTTP integration).
+
+* CHANGE: Authentication uses the customer extid (the "ur..." identifier at
+  the bottom of the user menu) as the HTTP Basic username, with the API
+  token as the password. Set it via `customer:` / ONETIME_CUSTOMER_EXTID.
+* CHANGE: base_url is now required (no default). Region-isolated deployments
+  mean there is no safe default; the apex onetimesecret.com (company website)
+  is rejected with guidance toward regional/self-hosted/custom hosts.
+* CHANGE: Requires Ruby 3.1+.
+* CHANGE: The `onetime` CLI moves to a separate `onetime-cli` gem.
+
+* REMOVED: httparty, drydock, jeweler, and yajl dependencies.
+* REMOVED: Legacy Onetime::API / OT::API shim, the OT top-level alias, the
+  `username:` option alias, and the old ONETIME_HOST / ONETIME_CUSTID /
+  ONETIME_APIKEY environment variables.
+* REMOVED: The drydock-based `bin/onetime` executable and the gem signing
+  certificate.
+* REMOVED: The redundant top-level VERSION file; lib/onetime/version.rb is
+  the single source of version truth.
+
+#### 0.5.1 (2013-02-12) ###############################
+
+* ADDED: global recipient parameter for 'generate' and 'share' commands.
+
+#### 0.5.0 (2013-02-12) ###############################
+
+* ADDED: Support for getting secrets based on the URI
+* ADDED: Command alias 'get' for 'secret'
+* ADDED: Explicit support for string format
+* FIXED: Confusion around csv support (there is no csv support)
+* CHANGE: Disabled checking for tty. Just assume string format.
+* CHANGE: 'secret' command returns just the secret message by default (not yaml)
+
+
+#### 0.4.1 (2013-02-12) ###############################
+
+* CHANGE: All releases will now be signed. See "Installation" in the readme.
+* CHANGE: json dependency upgraded from 1.6.4 to 1.6.8
+
+#### 0.4.0 (2012-01-07) ###############################
+
+* ADDED: Support for ttl, passphrase, and email recipient
+* ADDED: Better error handling
+* CHANGE: env variable ONETIME_ACCOUNT -> ONETIME_CUSTID
+* CHANGE: global option -u is now -H
+
+
+#### 0.3.1 (2012-01-06) ###############################
+
+* FIXED: Added httparty to gemspec dependencies
+* ADDED: X-Onetime-Client header
+
+
+#### 0.3.0 (2012-01-06) ###############################
+
+Initial public release

data/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2011,2012 Delano Mandelbaum
+
+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,251 @@
+# Onetime Secret Ruby Client
+
+The official Ruby client for the [OnetimeSecret](https://onetimesecret.com)
+API. Share sensitive information through a link that can only be viewed once.
+
+The canonical gem is **`onetimesecret`**. This repository, **`onetime-ruby`**,
+is the Ruby SDK in the OnetimeSecret SDK family — each language has its own
+repository, and the repository name is not the package name.
+
+- **Zero runtime dependencies** — built entirely on the Ruby standard library
+  (`net/http`, `uri`, `json`), so it drops into any environment without pulling
+  transitive gems.
+- **Supports API v1 and v2** — pick a version per client. The same resource
+  methods exist for both, but each version returns its own response shape (they
+  are different APIs; the client does not normalize them). **v1 is deprecated**
+  and included only because the service still serves it — use v2 for new work.
+- **Ruby 3.1+**.
+
+> The `onetime` command-line tool has moved to a separate `onetime-cli` gem so
+> that this library stays dependency-free.
+
+## Installation
+
+```sh
+gem install onetimesecret
+```
+
+Or in a Gemfile:
+
+```ruby
+gem "onetimesecret", "~> 0.7.0"
+```
+
+The package was published as `onetime` through version 0.6.0. The `onetime`
+0.7 compatibility package installs `onetimesecret`, but existing applications
+should update their Gemfiles directly. The Ruby namespace remains `Onetime`,
+and `require "onetime"` remains supported.
+
+Maintainers: see [docs/releasing.md](docs/releasing.md).
+
+## Quick start
+
+```ruby
+require "onetimesecret"
+
+client = Onetime::Client.new(
+  base_url:    "https://ca.onetimesecret.com", # choose your region's API host (required)
+  customer:    "ur1abc23defghijklmnop",        # customer extid (see below)
+  api_token:   ENV["ONETIME_API_TOKEN"],       # API token from your account page
+  api_version: :v2,                            # :v1 or :v2 (default)
+)
+
+# Conceal a secret you already have
+res = client.secrets.conceal(secret: "hunter2", ttl: 3600, passphrase: "pw12")
+res.dig("record", "receipt", "identifier")  # the receipt (creator) key
+res.dig("record", "secret", "identifier")   # the secret (recipient) key
+
+# Generate a random secret server-side
+client.secrets.generate(ttl: 86_400)
+
+# Reveal (consume) a secret — one-time only
+secret = client.secrets.reveal("abc123secretkey", passphrase: "pw12")
+secret.dig("record", "secret_value")
+
+# Service status (works on v1 and v2)
+client.status
+```
+
+### Authentication
+
+Authentication uses HTTP Basic, where the **customer extid** is the username
+and your **API token** is the password.
+
+The customer extid is a short, opaque identifier that begins with `ur` — for
+example `ur1abc23def`. It is shown, with a copy button, at the bottom of the
+user menu when you are signed in. Other identifiers the API uses are not
+interchangeable with it.
+
+The format is checked at construction, so a value of the wrong kind fails
+immediately rather than at the first request:
+
+```ruby
+Onetime::Client.new(base_url: "https://ca.onetimesecret.com",
+                    customer: "acct-123", api_token: ENV["ONETIME_API_TOKEN"])
+# => Onetime::ConfigurationError: customer "acct-123" is not a customer extid:
+#    extids begin with "ur" (e.g. "ur1abc23def"). ...
+```
+
+> Self-hosted servers older than
+> [onetimesecret#3945](https://github.com/onetimesecret/onetimesecret/pull/3945)
+> silently accept invalid credentials and create the secret **anonymously**
+> instead of returning 401 — the call succeeds, but the secret never appears in
+> your account. Current servers return 401.
+
+### Base URL (required)
+
+`base_url` must be the API host for your region, your self-hosted domain, or
+your custom domain. There is no default: deployments are region-isolated for
+data sovereignty, so the client cannot guess one for you.
+
+Regional API hosts:
+
+| Region | Host |
+|---|---|
+| United States | `https://us.onetimesecret.com` |
+| Europe | `https://eu.onetimesecret.com` |
+| United Kingdom | `https://uk.onetimesecret.com` |
+| Canada | `https://ca.onetimesecret.com` |
+| Aotearoa New Zealand | `https://nz.onetimesecret.com` |
+
+> The apex `onetimesecret.com` is the company website, not an API host, and
+> is rejected with a helpful error.
+
+### Configuration
+
+| Option         | Default                                       | Notes                                   |
+|----------------|-----------------------------------------------|-----------------------------------------|
+| `base_url`     | — (**required**)                              | Region/self-hosted/custom domain        |
+| `api_version`  | `:v2`                                          | `:v1` or `:v2`                          |
+| `customer`     | `ENV["ONETIME_CUSTOMER_EXTID"]`                | Customer extid (`ur...`)                |
+| `api_token`    | `ENV["ONETIME_API_TOKEN"]`                     | API token                               |
+| `timeout`      | `30`                                           | Read timeout (seconds)                  |
+| `open_timeout` | `10`                                           | Connect timeout (seconds)               |
+| `max_retries`  | `2`                                            | Retries for idempotent (GET) requests   |
+| `logger`       | `nil`                                          | Receives per-request `debug` lines      |
+
+Environment fallbacks: `base_url` ← `ONETIME_BASE_URL`; `customer` ←
+`ONETIME_CUSTOMER_EXTID`; `api_token` ← `ONETIME_API_TOKEN`.
+
+Clients are thread-safe: they hold only configuration and a stateless
+transport, opening a fresh connection per request.
+
+## Anonymous and guest usage
+
+A client created without credentials is anonymous and can use public and guest
+endpoints:
+
+```ruby
+guest = Onetime::Client.new(base_url: "https://ca.onetimesecret.com")  # no credentials
+guest.secrets.conceal(secret: "no account needed", guest: true)
+```
+
+## Resources
+
+### `client.secrets`
+
+| Method | v1 | v2 |
+|---|----|----|
+| `conceal(secret:, ttl:, passphrase:, recipient:, share_domain:)` | yes | yes |
+| `generate(ttl:, passphrase:, recipient:, share_domain:)` | yes | yes |
+| `reveal(key, passphrase:, continue:)` | yes | yes |
+| `show(key)` | — | yes |
+| `status(key)` | — | yes |
+| `status_list(keys)` | — | yes |
+
+`conceal` is also available as `share`. `reveal`/`show` accept either a bare
+key or a full secret URL.
+
+### `client.receipts`
+
+| Method | v1 | v2 |
+|---|----|----|
+| `show(key)` | yes | yes |
+| `recent` | yes | yes |
+| `burn(key, passphrase:, continue:)` | yes | yes |
+| `update(key, memo:)` | — | yes |
+
+### Meta
+
+`client.status` (v1 & v2), `client.version` / `client.supported_locales`
+(v2 only), `client.authcheck` (v1 only).
+
+## Responses
+
+Resource methods return an `Onetime::Response` with indifferent (String or
+Symbol) key access:
+
+```ruby
+res = client.secrets.conceal(secret: "hi")
+res["record"]                                   # Hash
+res.dig(:record, :secret, :secret_value)        # deep access
+res.success?                                     # 2xx?
+res.http_status                                  # Integer
+res.to_h                                         # the parsed body
+```
+
+The response shape is the API's, unchanged. v1 and v2 differ on purpose —
+v1 returns flat, all-string fields; v2 nests data under `record`/`details`
+with richer typing — and the client does not reconcile them. Read the
+[API docs](https://docs.onetimesecret.com/) for the shape of the version
+you target.
+
+## Errors
+
+HTTP errors (status >= 400) raise typed exceptions following the API's
+ADR-013 error contract (`{ error:, error_type:, ... }`):
+
+```ruby
+begin
+  client.secrets.reveal("missing")
+rescue Onetime::NotFoundError => e
+  e.message      # human-readable message ("error" field)
+  e.error_type   # machine-readable type ("RecordNotFound")
+  e.http_status  # 404
+rescue Onetime::RateLimitError => e
+  e.retry_after
+rescue Onetime::APIError => e
+  # any other API error
+end
+```
+
+| Exception | When |
+|---|---|
+| `Onetime::BadRequestError` | 400 / `FormError` (see `#field`) |
+| `Onetime::AuthenticationError` | 401 |
+| `Onetime::AccountRequiredError` | the operation needs an authenticated account (`requires_account`); subclasses `AuthenticationError`, keeps `#field` |
+| `Onetime::ForbiddenError` | 403 / `Forbidden`, `GuestRoutesDisabled` |
+| `Onetime::EntitlementError` | `EntitlementRequired` (see `#entitlement`) |
+| `Onetime::NotFoundError` | 404 / `RecordNotFound` |
+| `Onetime::RateLimitError` | 429 / `LimitExceeded` (see `#retry_after`) |
+| `Onetime::ServerError` | 5xx |
+| `Onetime::TransportError` / `TimeoutError` | network failures |
+| `Onetime::ConfigurationError` | bad `base_url`, malformed `customer` extid, incomplete credentials (raised at construction) |
+
+All inherit from `Onetime::Error`.
+
+`AccountRequiredError` exists because the service reports "this needs an
+account" inside a `400` form-error body (`field: "requires_account"`). Mapping
+that to `BadRequestError` sent people auditing their request payload for a
+problem that was never there, so it gets its own class under
+`AuthenticationError`:
+
+```ruby
+begin
+  client.secrets.conceal(secret: "hi")
+rescue Onetime::AccountRequiredError => e
+  e.field        # "requires_account" — preserved
+  e.http_status  # whatever the server sent (400 today)
+end
+```
+
+## Development
+
+```sh
+bundle install
+rake test
+```
+
+## License
+
+See [LICENSE.txt](LICENSE.txt).

data/lib/onetime/client.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative "configuration"
+require_relative "transport"
+require_relative "resources/secrets"
+require_relative "resources/receipts"
+
+module Onetime
+  # The main entry point for the OnetimeSecret API client.
+  #
+  #   client = Onetime::Client.new(
+  #     base_url:     "https://ca.onetimesecret.com",
+  #     customer:     "ur1abc23def", # customer extid
+  #     api_token:    ENV["ONETIME_API_TOKEN"],
+  #     api_version:  :v2,           # :v1 or :v2
+  #   )
+  #
+  #   client.secrets.conceal(secret: "hunter2", ttl: 3600)
+  #   client.receipts.recent
+  #   client.status
+  #
+  # A client is safe to share across threads: it holds configuration and a
+  # stateless transport, and creates a fresh Net::HTTP connection per request.
+  class Client
+    attr_reader :config, :transport
+
+    # Accepts the same keyword arguments as Onetime::Configuration, or an
+    # already-built Configuration via `config:`.
+    def initialize(config: nil, **options)
+      @config = config || Configuration.new(**options)
+      @config.validate!
+      @transport = @config.transport || Transport.new(@config)
+    end
+
+    def api_version
+      config.api_version
+    end
+
+    # Secret resource accessor (conceal/generate/reveal/show/status).
+    def secrets
+      @secrets ||= Resources::Secrets.new(self)
+    end
+
+    # Receipt resource accessor (show/recent/burn/update).
+    def receipts
+      @receipts ||= Resources::Receipts.new(self)
+    end
+
+    # --- Meta / public endpoints -------------------------------------------
+
+    # Service status. Available on both v1 and v2.
+    def status
+      request(:get, "/status")
+    end
+
+    # Service version. (v2 only)
+    def version
+      require_version!(:v2, "version")
+      request(:get, "/version")
+    end
+
+    # Locales supported by the service. (v2 only)
+    def supported_locales
+      require_version!(:v2, "supported_locales")
+      request(:get, "/supported-locales")
+    end
+
+    # Verify the configured credentials are valid. (v1 only)
+    def authcheck
+      require_version!(:v1, "authcheck")
+      request(:get, "/authcheck")
+    end
+
+    # --- Low-level request helper ------------------------------------------
+
+    # Issue a request against the configured API version. The path is
+    # relative to the version prefix (e.g. "/secret/conceal").
+    #
+    # @return [Onetime::Response]
+    def request(method, path, query: nil, body: nil, form: nil, raise_on_error: true)
+      transport.request(
+        method, full_path(path),
+        query: query, body: body, form: form, raise_on_error: raise_on_error
+      )
+    end
+
+    private
+
+    def full_path(path)
+      "#{config.api_path_prefix}#{path}"
+    end
+
+    def require_version!(expected, operation)
+      return if api_version == expected
+
+      raise UnsupportedOperationError,
+            "#{operation} is only available on API #{expected}; client is configured for #{api_version}"
+    end
+  end
+end

data/lib/onetime/configuration.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Onetime
+  # Immutable-ish configuration for a Client instance.
+  #
+  # Authentication uses HTTP Basic, where the username slot carries the
+  # *customer external id* (extid) — the identifier that begins with "ur" and
+  # is shown (with a copy button) at the bottom of the user menu when signed
+  # in. The password slot carries your API token.
+  #
+  # #validate! checks the extid's format, so a value of the wrong kind fails
+  # at construction rather than as an opaque 401.
+  #
+  # Values fall back to environment variables:
+  #   ONETIME_BASE_URL        -> base_url
+  #   ONETIME_CUSTOMER_EXTID  -> customer
+  #   ONETIME_API_TOKEN       -> api_token
+  class Configuration
+    DEFAULT_API_VERSION  = :v2
+    SUPPORTED_VERSIONS   = %i[v1 v2].freeze
+    DEFAULT_TIMEOUT      = 30  # read timeout, seconds
+    DEFAULT_OPEN_TIMEOUT = 10  # connect timeout, seconds
+    DEFAULT_MAX_RETRIES  = 2   # retries for idempotent requests
+
+    # A customer extid is a short, opaque, case-insensitive identifier that
+    # always begins with "ur" — e.g. "ur1abc23def".
+    CUSTOMER_EXTID_PATTERN = /\Aur[a-z0-9]+\z/i
+
+    # Included in the rejection message: an invalid-format error is only
+    # actionable if it says where the valid value lives.
+    CUSTOMER_EXTID_HINT =
+      'Your customer extid is the "ur…" identifier at the bottom of the ' \
+      "user menu when you are signed in (there is a copy button next to it). " \
+      "Pass it as customer: or set ONETIME_CUSTOMER_EXTID."
+
+    # The apex domain and its www host serve the company website, not the
+    # API. Regional deployments each have their own host.
+    APEX_HOSTS = %w[onetimesecret.com www.onetimesecret.com].freeze
+
+    # Known regional API hosts (per the API's published server list),
+    # surfaced in error messages. Self-hosted and custom domains are also
+    # valid base URLs.
+    EXAMPLE_REGIONAL_HOSTS = %w[
+      us.onetimesecret.com eu.onetimesecret.com uk.onetimesecret.com
+      ca.onetimesecret.com nz.onetimesecret.com
+    ].freeze
+
+    attr_accessor :base_url, :api_version, :customer, :api_token,
+                  :timeout, :open_timeout, :max_retries,
+                  :user_agent, :logger, :transport, :default_headers
+
+    def initialize(base_url: nil, api_version: nil, customer: nil,
+                   api_token: nil, timeout: nil, open_timeout: nil, max_retries: nil,
+                   user_agent: nil, logger: nil, transport: nil, default_headers: nil)
+      @base_url        = base_url || ENV["ONETIME_BASE_URL"]
+      @api_version     = normalize_version(api_version || DEFAULT_API_VERSION)
+      @customer    = customer || ENV["ONETIME_CUSTOMER_EXTID"]
+      @api_token       = api_token || ENV["ONETIME_API_TOKEN"]
+      @timeout         = timeout || DEFAULT_TIMEOUT
+      @open_timeout    = open_timeout || DEFAULT_OPEN_TIMEOUT
+      @max_retries     = max_retries.nil? ? DEFAULT_MAX_RETRIES : max_retries
+      @user_agent      = user_agent
+      @logger          = logger
+      @transport       = transport
+      @default_headers = default_headers || {}
+    end
+
+    # True when no credentials are configured. Anonymous clients can still
+    # use public and /guest/* endpoints.
+    def anonymous?
+      customer.to_s.empty? && api_token.to_s.empty?
+    end
+
+    # The mount prefix for the configured API version, e.g. "/api/v2".
+    def api_path_prefix
+      "/api/#{api_version}"
+    end
+
+    def validate!
+      validate_api_version!
+      validate_base_url!
+      validate_credentials!
+      self
+    end
+
+    private
+
+    def validate_api_version!
+      return if SUPPORTED_VERSIONS.include?(api_version)
+
+      raise ConfigurationError,
+            "Unsupported api_version #{api_version.inspect}; supported: #{SUPPORTED_VERSIONS.join(', ')}"
+    end
+
+    def validate_base_url!
+      if base_url.to_s.empty?
+        examples = EXAMPLE_REGIONAL_HOSTS.first(3).map { |h| "https://#{h}" }.join(", ")
+        raise ConfigurationError,
+              "base_url is required. Use your region's API host " \
+              "(e.g. #{examples}), your self-hosted domain, or your custom " \
+              "domain. Set it via the base_url: option or the ONETIME_BASE_URL " \
+              "environment variable."
+      end
+
+      begin
+        uri = URI.parse(base_url)
+      rescue URI::InvalidURIError => e
+        raise ConfigurationError, "Invalid base_url #{base_url.inspect}: #{e.message}"
+      end
+
+      unless uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
+        raise ConfigurationError, "base_url must be an absolute http(s) URL, got #{base_url.inspect}"
+      end
+
+      return unless APEX_HOSTS.include?(uri.host.downcase)
+
+      raise ConfigurationError,
+            "#{uri.host} is the OneTimeSecret company website, not an API host. " \
+            "Use a regional subdomain (e.g. https://#{EXAMPLE_REGIONAL_HOSTS.first}), " \
+            "your self-hosted domain, or your custom domain."
+    end
+
+    def validate_credentials!
+      validate_customer_format! unless customer.to_s.empty?
+
+      # Partial credentials are almost always a mistake; fail loudly.
+      return unless customer.to_s.empty? ^ api_token.to_s.empty?
+
+      missing = customer.to_s.empty? ? "customer" : "api_token"
+      raise ConfigurationError, "Incomplete credentials: #{missing} is missing"
+    end
+
+    # Catch an identifier of the wrong kind at construction time rather than
+    # as a 401 several calls later.
+    def validate_customer_format!
+      value = customer.to_s
+      return if CUSTOMER_EXTID_PATTERN.match?(value)
+
+      raise ConfigurationError,
+            "customer #{value.inspect} is not a customer extid: extids begin " \
+            'with "ur" (e.g. "ur1abc23def"). ' \
+            "#{CUSTOMER_EXTID_HINT}"
+    end
+
+    def normalize_version(version)
+      case version
+      when Symbol then version
+      when String then version.start_with?("v") ? version.to_sym : :"v#{version}"
+      when Integer then :"v#{version}"
+      else version
+      end
+    end
+  end
+end