x402-rails 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b70874283a564f69295e16df7dcb11d4764480c62151f130335ee3d116d62f5
-  data.tar.gz: e4462c35ac33efc1993f166fa407b1e06f1b1fa35e3ba6547afce9031c07d3c4
+  metadata.gz: 5ec0c7a3137f3d98d641403e48438dc35677587631197581e3574804df7f42fa
+  data.tar.gz: f1d3d3ed62e675ad0c818e0202066c95cdddbd2c13ce6be3cec9ef04c1a47e94
 SHA512:
-  metadata.gz: fb7d7df8bda864f433e062f41cc1e956c6a979446e02bd3bb88ef5bccc2ac42e06a2933a5cafe7b7475b53665d360b5bc034b80e4c9c9ff10b668df1f61a106d
-  data.tar.gz: ea4523288ae8c5242fb03c90f1bc83f41779d46c170354cf2a3ccfdbaaf34da3f6656a03ab4b47d01f0d11e01e4adf1da4a52b405ddf25aa12f91270f11a6eaf
+  metadata.gz: 888362993251583ffdf727c493468dc65ae6c97cff5017983b4b47675d80eed7ce2165a99fd78746d07a495d1a0ffa1dd641a2a4d0c36bb3ab5f5e55b5556899
+  data.tar.gz: dec329b07321b5c705a38ace0a90d5c9599f34eeb0f7fcb8b6f8b6ff4c51febe986c06da450486b31131252886145a3c00dedaeb2765d20cc8860bee84960c65

data/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.2.0] - Unreleased
+
+### Added
+- **Bazaar discovery** - `x402_discovery` controller macro declares discovery metadata per action; the extension is attached to every v2 402 the gem renders, echoed by paying clients, and indexed by facilitator catalogs (PayAI, Coinbase CDP Bazaar)
+- **`X402::DiscoveryExtension.declare`** - Builds the `extensions.bazaar` wire shape, matching `@x402/extensions` `declareDiscoveryExtension` (query and body forms)
+- **Coinbase CDP facilitator auth** - Requests to `api.cdp.coinbase.com` carry the required Bearer JWT (ES256 and Ed25519 keys, no new dependencies). Credentials via `CDP_API_KEY_ID` / `CDP_API_KEY_SECRET` or `config.cdp_api_key_id` / `config.cdp_api_key_secret`
+- **`FacilitatorClient#discovery_resources`** - Query a facilitator's discovery catalog
+- **`x402_payment_header` / `x402_payment_attempted?`** - Controller helpers for the version-appropriate payment header, for conditional paywall flows and idempotency fingerprints
+- `x402_discovery(description:)` sets the 402 `resource.description` facilitator catalogs display; `x402_paywall(extensions:)` attaches a prebuilt extensions hash directly
+
+### Changed
+- 402 responses set `Cache-Control: no-store`
+- Facilitator request/response bodies and settlement diagnostics log at `debug`; settlement outcomes stay at `info`/`error`
+
+### Fixed
+- **v2 PaymentPayload dropped client-echoed `extensions`** - `to_h` hardcoded `extensions: {}`, so the discovery extension never reached the facilitator on verify/settle and routes could not be indexed. Client extensions are now forwarded untouched
+- Settlement failures returning HTTP 400 from the facilitator no longer raise out of the settlement hook; they are logged and handled like other settlement errors
+- `rails generate x402:install` - the install generator was not discoverable (it lived outside Rails' generator load path)
+
+With no discovery declared and a non-CDP facilitator, the only wire change from 1.1.0 is the 402 `Cache-Control` header.
+
 ## [1.0.0] - 2026-01-07
 
 ### Added

data/README.md

@@ -8,7 +8,7 @@
 
 Accept instant blockchain micropayments in your Rails applications using the [x402 payment protocol](https://www.x402.org/).
 
-Supports Base, avalanche, and other blockchain networks.
+Supports 18 networks including Base, Polygon, Avalanche, Sei, Solana, and more.
 
 ## Features
 
@@ -18,7 +18,9 @@ Supports Base, avalanche, and other blockchain networks.
 - **$0.001 minimum** payment amounts
 - **Optimistic & non-optimistic** settlement modes
 - **Automatic settlement** after successful responses
-- **Browser paywall** and API support
+- **API paywall** with 402 payment-required responses
+- **Bazaar discovery** to list your routes in facilitator catalogs (PayAI, Coinbase CDP)
+- **Coinbase CDP facilitator** support with built-in auth
 - **Rails 7.0+** compatible
 
 ## Example Video
@@ -43,12 +45,18 @@ bundle install
 
 ### 1. Configure the gem
 
-Create `config/initializers/x402.rb`:
+Generate the initializer:
+
+```bash
+bin/rails generate x402:install
+```
+
+Then edit `config/initializers/x402.rb`:
 
 ```ruby
 X402.configure do |config|
   config.wallet_address = ENV['X402_WALLET_ADDRESS']  # Your recipient wallet
-  config.facilitator = "https://x402.org/facilitator"
+  config.facilitator = "https://www.x402.org/facilitator"
   config.chain = "base-sepolia"  # or "base" for base mainnet
   config.currency = "USDC"
   config.optimistic = false  # Forces to check for settlement before giving response.
@@ -75,6 +83,21 @@ end
 
 That's it! Your endpoint now requires payment.
 
+### 3. (Optional) Make it discoverable
+
+Declare discovery metadata and agents can find your route in facilitator catalogs (see [Bazaar Discovery](#bazaar-discovery)):
+
+```ruby
+class ApiController < ApplicationController
+  x402_discovery only: :weather,
+                 input: { "city" => "San Francisco" },
+                 input_schema: { "properties" => { "city" => { "type" => "string" } } },
+                 output: { example: { "temperature" => 72 } }
+end
+```
+
+Indexing happens when a client pays: the extension rides the 402, the paying client echoes it, and the facilitator catalogs the route on settle.
+
 ## Usage Patterns
 
 ### Direct Method Call
@@ -141,21 +164,24 @@ X402.configure do |config|
   # Required: Your wallet address where payments will be received
   config.wallet_address = ENV['X402_WALLET_ADDRESS']
 
-  # Facilitator service URL (default: "https://x402.org/facilitator")
-  config.facilitator = ENV.fetch("X402_FACILITATOR_URL", "https://x402.org/facilitator")
+  # Facilitator service URL (default: "https://www.x402.org/facilitator")
+  config.facilitator = ENV.fetch("X402_FACILITATOR_URL", "https://www.x402.org/facilitator")
 
   # Blockchain network (default: "base-sepolia")
-  # Options: "base-sepolia", "base", "avalanche-fuji", "avalanche"
+  # Built-in: base, base-sepolia, polygon, polygon-amoy, avalanche, avalanche-fuji,
+  #           sei, sei-testnet, iotex, peaq, xlayer, xlayer-testnet,
+  #           skale-base, skale-base-sepolia, kiteai, kiteai-testnet,
+  #           solana, solana-devnet
   config.chain = ENV.fetch("X402_CHAIN", "base-sepolia")
 
   # Payment token (default: "USDC")
   # Currently only USDC is supported
   config.currency = ENV.fetch("X402_CURRENCY","USDC")
 
-  # Optimistic mode (default: true)
+  # Optimistic mode (default: false)
   # true: Fast response, settle payment after response is sent
   # false: Wait for blockchain settlement before sending response
-  config.optimistic = ENV.fetch("X402_OPTIMISTIC",false)
+  config.optimistic = ENV.fetch("X402_OPTIMISTIC", "false") == "true"
 end
 ```
 
@@ -164,11 +190,13 @@ end
 | Attribute        | Required | Default                          | Description                                                                       |
 | ---------------- | -------- | -------------------------------- | --------------------------------------------------------------------------------- |
 | `wallet_address` | **Yes**  | -                                | Your Ethereum wallet address where payments will be received                      |
-| `facilitator`    | No       | `"https://x402.org/facilitator"` | Facilitator service URL for payment verification and settlement                   |
-| `chain`          | No       | `"base-sepolia"`                 | Blockchain network to use (`base-sepolia`, `base`, `avalanche-fuji`, `avalanche`) |
+| `facilitator`    | No       | `"https://www.x402.org/facilitator"` | Facilitator service URL for payment verification and settlement               |
+| `chain`          | No       | `"base-sepolia"`                 | Blockchain network (see built-in list above) |
 | `currency`       | No       | `"USDC"`                         | Payment token symbol (currently only USDC supported)                              |
-| `optimistic`     | No       | `true`                           | Settlement mode (see Optimistic vs Non-Optimistic Mode below)                     |
+| `optimistic`     | No       | `false`                          | `true`: respond before settlement; `false`: settle before responding             |
 | `version`        | No       | `2`                              | Protocol version (1 or 2). See Protocol Versions section                          |
+| `cdp_api_key_id` | No       | `ENV["CDP_API_KEY_ID"]`          | Coinbase CDP API key id — only used when the facilitator is CDP                   |
+| `cdp_api_key_secret` | No   | `ENV["CDP_API_KEY_SECRET"]`      | Coinbase CDP API key secret (ECDSA PEM or Ed25519 base64)                         |
 
 ### Custom Chains and Tokens
 
@@ -176,30 +204,30 @@ You can register custom EVM chains and tokens beyond the built-in options.
 
 #### Register a Custom Chain
 
-Add support for any EVM-compatible chain:
+Add support for any EVM-compatible chain beyond the 18 built-in networks:
 
 ```ruby
 X402.configure do |config|
   config.wallet_address = ENV['X402_WALLET_ADDRESS']
 
-  # Register Polygon mainnet
+  # Register Arbitrum (not built-in)
   config.register_chain(
-    name: "polygon",
-    chain_id: 137,
+    name: "arbitrum",
+    chain_id: 42161,
     standard: "eip155"
   )
 
   # Register the token for that chain
   config.register_token(
-    chain: "polygon",
+    chain: "arbitrum",
     symbol: "USDC",
-    address: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
+    address: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
     decimals: 6,
     name: "USD Coin",
     version: "2"
   )
 
-  config.chain = "polygon"
+  config.chain = "arbitrum"
   config.currency = "USDC"
 end
 ```
@@ -250,20 +278,21 @@ Allow clients to pay on any of several supported chains by using `config.accept(
 X402.configure do |config|
   config.wallet_address = ENV['X402_WALLET_ADDRESS']
 
-  # Register a custom chain
-  config.register_chain(name: "polygon-amoy", chain_id: 80002, standard: "eip155")
+  # Register a custom chain not included in the built-in list
+  config.register_chain(name: "arbitrum", chain_id: 42161, standard: "eip155")
   config.register_token(
-    chain: "polygon-amoy",
+    chain: "arbitrum",
     symbol: "USDC",
-    address: "0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582",
+    address: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
     decimals: 6,
     name: "USD Coin",
     version: "2"
   )
 
-  # Accept payments on multiple chains
+  # Accept payments on multiple chains (built-in + custom)
   config.accept(chain: "base-sepolia", currency: "USDC")
   config.accept(chain: "polygon-amoy", currency: "USDC")
+  config.accept(chain: "arbitrum", currency: "USDC")
 end
 ```
 
@@ -343,6 +372,157 @@ def legacy_v1
 end
 ```
 
+## Bazaar Discovery
+
+Facilitators with a discovery layer (PayAI, Coinbase CDP Bazaar) index your route into their public catalog when a payment carries the x402 Bazaar discovery extension. Declare it per action and the gem attaches it to every v2 402 for that action; paying clients echo it into their payment payload, and the gem forwards the echo to the facilitator on verify/settle — that's what creates the catalog entry.
+
+> **Note:** Parameterized routes (e.g. `/weather/:city`) are cataloged per concrete URL — the gem does not emit the optional `routeTemplate` field.
+
+### GET route (query params)
+
+Omit `body_type` for GET/HEAD/DELETE — `input` describes query params:
+
+```ruby
+class WeatherController < ApplicationController
+  x402_discovery only: :show,
+                 input: { "city" => "San Francisco", "units" => "celsius" },
+                 input_schema: {
+                   "type" => "object",
+                   "properties" => {
+                     "city" => { "type" => "string", "description" => "City name" },
+                     "units" => { "type" => "string", "enum" => ["celsius", "fahrenheit"] },
+                   },
+                   "required" => ["city"],
+                 },
+                 output: { example: { "weather" => "foggy", "temperature" => 15 } }
+
+  def show
+    x402_paywall(amount: 0.001)
+    return if performed?
+    render json: { weather: "foggy", temperature: 15 }
+  end
+end
+```
+
+### POST route (JSON body)
+
+Pass `body_type: "json"` — `input` is now an example request body. Give every field a `description`: it's what agents read in the catalog to call you correctly.
+
+```ruby
+class SearchController < ApplicationController
+  x402_discovery only: :create,
+                 body_type: "json",
+                 input: {
+                   "query" => "solar panels",
+                   "filters" => { "max_price" => 100 },
+                 },
+                 input_schema: {
+                   "type" => "object",
+                   "properties" => {
+                     "query" => { "type" => "string", "description" => "Search terms" },
+                     "filters" => {
+                       "type" => "object",
+                       "properties" => { "max_price" => { "type" => "number" } },
+                     },
+                   },
+                   "required" => ["query"],
+                 },
+                 output: {
+                   example: { "results" => [{ "title" => "…", "price" => 42 }] },
+                   schema: { "properties" => { "results" => { "type" => "array" } } },
+                 }
+
+  def create
+    x402_paywall(amount: 0.005)
+    return if performed?
+    render json: { results: search_results }
+  end
+end
+```
+
+### Multiple routes in one controller
+
+Each action gets its own declaration; undeclared actions emit no extension:
+
+```ruby
+class ReportsController < ApplicationController
+  x402_discovery only: :create, body_type: "json",
+                 input: { "ticker" => "AAPL" },
+                 input_schema: { "properties" => { "ticker" => { "type" => "string" } }, "required" => ["ticker"] },
+                 output: { example: { "report_id" => "rep_123" } }
+
+  x402_discovery only: :summary,
+                 input: { "report_id" => "rep_123" },
+                 input_schema: { "properties" => { "report_id" => { "type" => "string" } }, "required" => ["report_id"] },
+                 output: { example: { "summary" => "…" } }
+end
+```
+
+### Full control
+
+Build the extension yourself (e.g. to share schemas with your validators), or attach per-call:
+
+```ruby
+x402_discovery only: :create, extensions: X402::DiscoveryExtension.declare(
+  body_type: "json",
+  input: MyApi::EXAMPLE_BODY,
+  input_schema: MyApi::BODY_SCHEMA,
+  output: { example: MyApi::EXAMPLE_RESPONSE },
+)
+
+# or, inside an action:
+x402_paywall(amount: 0.005, extensions: my_extensions)
+```
+
+### Indexing rules
+
+- The example `input` **must validate against `input_schema`** — facilitators silently skip routes whose extension fails validation. Keep example and schema in sync.
+- `method` is stamped from the actual request at render time — omit it; a declared value is overwritten.
+- `description:` on `x402_discovery` sets the 402's `resource.description` — the text catalogs display for the route. A description alone just names the route; declaring input/output metadata is what makes it discoverable.
+- Catalogs are **per-facilitator** — an entry appears only in the catalog of the facilitator that settled the payment. To appear in both PayAI and CDP, settle at least one payment through each.
+- Indexing is a side-effect of a real payment; there is no registration API.
+
+Verify a listing:
+
+```ruby
+X402::FacilitatorClient.new.discovery_resources(type: "http")
+# or against a specific facilitator:
+X402::FacilitatorClient.new("https://facilitator.payai.network").discovery_resources
+```
+
+## Facilitators
+
+Any x402 facilitator works via `X402_FACILITATOR_URL` / `config.facilitator`. Auth is applied automatically:
+
+| Facilitator | URL | Auth |
+| ----------- | --- | ---- |
+| x402.org (default) | `https://www.x402.org/facilitator` | none |
+| PayAI | `https://facilitator.payai.network` | none |
+| Coinbase CDP | `https://api.cdp.coinbase.com/platform/v2/x402` | Bearer JWT, built in |
+
+### Using Coinbase CDP
+
+1. Create a project + API key at [cdp.coinbase.com](https://cdp.coinbase.com) (ECDSA and Ed25519 keys both work).
+2. Set the env vars CDP's own SDKs use — the gem picks them up automatically:
+
+```bash
+X402_FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402
+CDP_API_KEY_ID=your-key-id
+CDP_API_KEY_SECRET=your-key-secret
+```
+
+Or configure explicitly:
+
+```ruby
+X402.configure do |config|
+  config.facilitator = "https://api.cdp.coinbase.com/platform/v2/x402"
+  config.cdp_api_key_id = Rails.application.credentials.dig(:cdp, :api_key_id)
+  config.cdp_api_key_secret = Rails.application.credentials.dig(:cdp, :api_key_secret)
+end
+```
+
+Every verify/settle/supported/discovery request then carries a per-request, URI-bound Bearer JWT (2-minute expiry), matching `@coinbase/cdp-sdk`. Note: CDP's Bazaar discovery currently covers Base and Base Sepolia USDC.
+
 ## Environment Variables
 
 Configure via environment variables:
@@ -352,12 +532,34 @@ Configure via environment variables:
 X402_WALLET_ADDRESS=0xYourAddress
 
 # Optional (with defaults)
-X402_FACILITATOR_URL=https://x402.org/facilitator
+X402_FACILITATOR_URL=https://www.x402.org/facilitator
 X402_CHAIN=base-sepolia
 X402_CURRENCY=USDC
 X402_OPTIMISTIC=true  # "true" or "false"
+
+# Coinbase CDP facilitator auth (only needed when X402_FACILITATOR_URL is CDP)
+CDP_API_KEY_ID=
+CDP_API_KEY_SECRET=
+
+# Solana fee payer overrides (required when using a non-default facilitator)
+# The default fee payer is for the Coinbase facilitator (x402.org).
+# Each facilitator manages its own fee payer — check your facilitator's /supported endpoint.
+X402_FEE_PAYER=                     # Global override for all Solana chains
+X402_SOLANA_FEE_PAYER=              # Solana mainnet override
+X402_SOLANA_DEVNET_FEE_PAYER=       # Solana devnet override
+
+# Example: PayAI facilitator (https://facilitator.payai.network)
+# X402_FACILITATOR_URL=https://facilitator.payai.network
+# X402_SOLANA_FEE_PAYER=2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4
+# X402_SOLANA_DEVNET_FEE_PAYER=2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4
 ```
 
+Fee payer lookup priority:
+1. `config.fee_payer` (programmatic, global)
+2. Per-chain ENV variable (e.g., `X402_SOLANA_DEVNET_FEE_PAYER`)
+3. `X402_FEE_PAYER` (ENV, global)
+4. Built-in default from chain config
+
 ## Examples
 
 ### Weather API
@@ -419,6 +621,8 @@ The gem raises these errors:
 - [x402 Protocol Docs](https://docs.cdp.coinbase.com/x402)
 - [GitHub Repository](https://github.com/coinbase/x402)
 - [Facilitator API](https://x402.org/facilitator)
+- [Step-by-Step Rails Integration Guide](https://www.quicknode.com/guides/infrastructure/x402-payment-integration-with-rails)
+
 
 ## License
 

data/lib/generators/x402/install/install_generator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module X402
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates X402 initializer for your application"
+
+      def copy_initializer
+        template "x402_initializer.rb", "config/initializers/x402.rb"
+
+        puts ""
+        puts "✅ X402 initializer created at config/initializers/x402.rb"
+        puts ""
+        puts "Next steps:"
+        puts "1. Set your X402_WALLET_ADDRESS environment variable"
+        puts "2. Configure your preferred chain (base-sepolia for testing, base for production)"
+        puts "3. Add x402_paywall(amount: 0.001) to any controller action"
+        puts ""
+        puts "Example usage:"
+        puts "  def show"
+        puts "    x402_paywall(amount: 0.001)  # $0.001 payment required"
+        puts "    render json: @data"
+        puts "  end"
+        puts ""
+      end
+    end
+  end
+end

data/lib/{x402/rails/generators → generators/x402/install}/templates/x402_initializer.rb

@@ -19,7 +19,16 @@ X402.configure do |config|
 
   # Currency symbol (currently only USDC is supported)
   config.currency = ENV.fetch("X402_CURRENCY", "USDC")
+
+  # Coinbase CDP facilitator (https://api.cdp.coinbase.com/platform/v2/x402)
+  # requires API credentials. These are read automatically from CDP_API_KEY_ID /
+  # CDP_API_KEY_SECRET, or set them explicitly:
+  # config.cdp_api_key_id = ENV.fetch("CDP_API_KEY_ID", nil)
+  # config.cdp_api_key_secret = ENV.fetch("CDP_API_KEY_SECRET", nil)
 end
 
+# To list paywalled routes in facilitator Bazaar catalogs, declare discovery
+# metadata in the controller with `x402_discovery` — see the README.
+
 # Validate configuration on initialization
 X402.configuration.validate!

data/lib/x402/cdp_facilitator_auth.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+
+module X402
+  # Bearer JWT auth for the Coinbase CDP facilitator, mirroring
+  # @coinbase/cdp-sdk generateJwt: per-request, URI-bound claims, signed with
+  # ES256 (PEM EC key) or EdDSA (base64 Ed25519 seed+public key).
+  #
+  # Applied automatically by FacilitatorClient when the configured facilitator
+  # host is api.cdp.coinbase.com. Credentials come from `config.cdp_api_key_id`
+  # and `config.cdp_api_key_secret` (or the CDP_API_KEY_ID / CDP_API_KEY_SECRET
+  # env vars CDP's own SDKs use). Other facilitators are untouched.
+  class CdpFacilitatorAuth
+    CDP_HOST = "api.cdp.coinbase.com"
+    EXPIRY_SECONDS = 120
+
+    class << self
+      def headers_for(facilitator_url:, http_method:, endpoint:)
+        uri = URI(facilitator_url)
+        return {} unless uri.host == CDP_HOST
+
+        config = X402.configuration
+        key_id = config.cdp_api_key_id
+        secret = config.cdp_api_key_secret
+        if key_id.nil? || key_id.empty? || secret.nil? || secret.empty?
+          X402.logger.error(
+            "[x402] CDP facilitator requires cdp_api_key_id and cdp_api_key_secret " \
+            "(or CDP_API_KEY_ID / CDP_API_KEY_SECRET); sending the request unauthenticated",
+          )
+          return {}
+        end
+
+        jwt = bearer_jwt(
+          key_id: key_id,
+          secret: secret,
+          http_method: http_method,
+          request_host: uri.host,
+          request_path: "#{uri.path}/#{endpoint}",
+        )
+        jwt ? { "Authorization" => "Bearer #{jwt}" } : {}
+      end
+
+      private
+
+      def bearer_jwt(key_id:, secret:, http_method:, request_host:, request_path:)
+        now = Time.now.to_i
+        claims = {
+          sub: key_id,
+          iss: "cdp",
+          uris: ["#{http_method} #{request_host}#{request_path}"],
+          iat: now,
+          nbf: now,
+          exp: now + EXPIRY_SECONDS,
+        }
+        header = { kid: key_id, typ: "JWT", nonce: SecureRandom.hex(16) }
+
+        if (key = ec_key(secret))
+          signed_jwt(claims, header.merge(alg: "ES256")) { |input| ecdsa_raw_signature(key, input) }
+        elsif (key = ed25519_key(secret))
+          signed_jwt(claims, header.merge(alg: "EdDSA")) { |input| key.sign(nil, input) }
+        else
+          X402.logger.error("[x402] CDP_API_KEY_SECRET is neither a PEM EC key nor a base64 Ed25519 key")
+          nil
+        end
+      end
+
+      def signed_jwt(claims, header)
+        signing_input = [encode_segment(header.to_json), encode_segment(claims.to_json)].join(".")
+        [signing_input, encode_segment(yield(signing_input))].join(".")
+      end
+
+      def encode_segment(bytes)
+        Base64.urlsafe_encode64(bytes, padding: false)
+      end
+
+      def ec_key(secret)
+        pem = secret.gsub("\\n", "\n")
+        return nil unless pem.include?("PRIVATE KEY")
+
+        key = OpenSSL::PKey.read(pem)
+        key.is_a?(OpenSSL::PKey::EC) ? key : nil
+      rescue OpenSSL::PKey::PKeyError
+        nil
+      end
+
+      # CDP Ed25519 secrets are base64(seed(32) || public_key(32)); OpenSSL only
+      # imports the seed wrapped in PKCS#8 DER.
+      def ed25519_key(secret)
+        decoded = Base64.strict_decode64(secret)
+        return nil unless decoded.bytesize == 64
+
+        seed = decoded.byteslice(0, 32)
+        der = OpenSSL::ASN1::Sequence([
+          OpenSSL::ASN1::Integer(0),
+          OpenSSL::ASN1::Sequence([OpenSSL::ASN1::ObjectId("ED25519")]),
+          OpenSSL::ASN1::OctetString(OpenSSL::ASN1::OctetString(seed).to_der),
+        ]).to_der
+        OpenSSL::PKey.read(der)
+      rescue ArgumentError, OpenSSL::PKey::PKeyError
+        nil
+      end
+
+      # JWS ES256 signatures are raw r||s (32 bytes each); OpenSSL emits DER.
+      def ecdsa_raw_signature(key, signing_input)
+        der = key.sign(OpenSSL::Digest.new("SHA256"), signing_input)
+        r, s = OpenSSL::ASN1.decode(der).value.map(&:value)
+        [r, s].map { |bn| bn.to_s(2).rjust(32, "\x00".b) }.join
+      end
+    end
+  end
+end