onetime 0.5.1 → 0.6.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8a9d766fe9b66ef0f5617b2447910c268af2700b7bb70c59574f62033b712ad2
+  data.tar.gz: e1737aa5ee4f29fd5a63c8951bed264c614f9fb2f747e01c73396ac8e0a4bc27
+SHA512:
+  metadata.gz: 878bb56df14b1ede5daccac8f08c652c29a4eed12ea1295730f8e322bc44449b5333a8d2967db2ab52dd24908aeb77a28a73a79c9e2e7f0053ad776454e109bd
+  data.tar.gz: e27104bb9373e1f6b9e68b54f38927679f98e87e0b6730fd6bdb9621f88abe93222a4a1c2260682e8ed764c1f969bf6a00a12f637897992e19020c88b012c058

data/CHANGES.txt

@@ -1,5 +1,67 @@
 ONETIME, CHANGES
 
+#### 0.6.0 (unreleased; tag v0.6.0 to publish) #########
+
+  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.

data/README.md

@@ -1,101 +1,247 @@
-# One-Time Secret 0.5 #
+# OnetimeSecret Ruby Client
 
-**Keep sensitive info out of your chat logs & email.**
+The official Ruby client for the [OnetimeSecret](https://onetimesecret.com)
+API. Share sensitive information through a link that can only be viewed once.
 
-## Basic Usage ##
+The gem is **`onetime`**. 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.
 
-Use `onetime` to share something you know (a secret phrase, a special link, etc) or to generate a secret (e.g. a temporary password).
+- **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+**.
 
-### onetime share ###
+> The `onetime` command-line tool has moved to a separate `onetime-cli` gem so
+> that this library stays dependency-free.
 
-You can pipe it:
+## Installation
 
-    $ echo "I STILL WATCH NIGHT COURT." | onetime
-    https://onetimesecret.com/secret/mc5o2649tva6885wvyspm0flobsasin
+```sh
+gem install onetime
+```
 
-You can type it:
+Or in a Gemfile:
 
-    $ onetime
-    Paste secret here (hit control-D to continue):
-    I STILL WATCH NIGHT COURT.
-    https://onetimesecret.com/secret/3djys3b7tridrcvbiprqjejz0c2g07x
+```ruby
+gem "onetime", "~> 0.6"   # the constraint matters, see below
+```
 
-And you can read from a file:
 
-    $ <path/2/file onetime
-    https://onetimesecret.com/secret/8f8k3ajhax87ctln3h6y11nsb4vf0wq
+Maintainers: see [docs/releasing.md](docs/releasing.md).
 
-*Note that we don't use `cat` in that example! We don't want to provoke the [ire of Randal L. Schwartz](http://partmaps.org/era/unix/award.html).*
+## Quick start
 
+```ruby
+require "onetime"
 
-### onetime generate ###
+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)
+)
 
-    $ onetime generate
-    Your secret: CttenFwzVpjs
-    https://onetimesecret.com/secret/er5djg1wodsp5m32oyym489bnuhsfp6
+# 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)
 
-### onetime get ###
+# Reveal (consume) a secret — one-time only
+secret = client.secrets.reveal("abc123secretkey", passphrase: "pw12")
+secret.dig("record", "secret_value")
 
-You can retrieve a secret too:
+# Service status (works on v1 and v2)
+client.status
+```
 
-    $ onetime get er5djg1wodsp5m32oyym489bnuhsfp6
-    [...SECRET...]
+### Authentication
 
-The URI works too:
+Authentication uses HTTP Basic, where the **customer extid** is the username
+and your **API token** is the password.
 
-    $ onetime get https://onetimesecret.com/secret/er5djg1wodsp5m32oyym489bnuhsfp6
-    [...SECRET...]
+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.
 
-## Output Format ##
+The format is checked at construction, so a value of the wrong kind fails
+immediately rather than at the first request:
 
-`onetime` also supports YAML, JSON, and to a limited extent CSV outputs. Specify the format using the `-f ` global option:
+```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"). ...
+```
 
-    $ onetime -f yaml generate
-    ---
-    value: MhYcuge9VxtX
-    metadata_key: 4j1122kpd6clemp80gpobu9xfxsp7zu
-    secret_key: 8f8k3ajhax87ctln3h6y11nsb4vf0wq
-    ttl: 172800
-    passphrase_required: false
+> 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.
 
-## Installation ###
+### Base URL (required)
 
-    $ [sudo] gem install onetime
+`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.
 
-    However, in order to be sure the code you're installing hasn't been tampered with, it's recommended that you verify the signiture[http://docs.rubygems.org/read/chapter/21]. To do this, you need to add my public key as a trusted certificate (you only need to do this once):
+Regional API hosts:
 
-        # Add the public key as a trusted certificate
-        # (You only need to do this once)
-        $ curl -O https://raw.github.com/onetimesecret/onetime-ruby/master/gem-public_cert.pem
-        $ gem cert --add gem-public_cert.pem
-
-    Then, when install the gem, do so with high security:
-
-        $ gem install onetime -P HighSecurity
-
-    If you don't add the public key, you'll see an error like "Couldn't verify data signature". If you're still having trouble let me know and I'll give you a hand.
-
-## More Info ##
-
-* [API docs](https://onetimesecret.com/docs/api)
-* [Codes](https://github.com/onetimesecret/onetime-ruby)
-* [Rubgems](https://rubygems.org/gems/onetime)
-* [One-Time Secret](https://onetimesecret.com/)
-
-See also:
-
-    $ onetime -h
-    $ onetime show-commands
-    $ onetime share -h
-    $ onetime generate -h
-
-## Thanks ##
-
-* Kyle Dawkins for the [perl lib](https://github.com/quile/onetime-perl)
-* Drew Carey for [tweeting about us](https://twitter.com/DrewFromTV/status/142730130689761280)
-
-
-## License ##
-
-See LICENSE.txt
+| 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