patchwork-rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e8b84f16b49af905d391e3f3d47e67339f1fec7cf28f6ee7d002d72b4d4c20aa
+  data.tar.gz: 9a0d2be627ba90e61da19d3512c1cf0e2520bf132cf11446199f029092958a9d
+SHA512:
+  metadata.gz: 61db91122e933dfbbe9a96370cd8a2b7db3529b4ffe62f07ba263a7911596cea23cbbc6902dac2a22ad250aca11c4ff185913c756a83dfb04d1d509c65472a52
+  data.tar.gz: e002d213489d59a7df24aa98aa0f45e5c41b0fbd61e7cffb2323911f04a750566f23c7d5e9c250dd2c030d3401a5c378655ddd10cef44dd06a5d73e276ed5885

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chromablue Labs
+
+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,348 @@
+# patchwork-rb
+
+The Ruby SDK for [Patchwork](https://usepatchwork.co). It mints session tokens for your users, verifies the tool calls Patchwork makes to your backend, and verifies webhook deliveries.
+
+**Scope, so you know what you are installing.** This version is the *inbound* half: everything Patchwork sends you, and the credentials you hand it. It is the part that is genuinely unpleasant to write by hand — the signature covers the raw body, a rotation puts two `v1=` values in one header, comparisons must be constant-time, and the token allowlist must never accept a symmetric algorithm. A client for *calling* the Patchwork API (`identify`, `extract`, threads, runs) lands in 0.2; until then those are ordinary HTTP calls with a bearer token.
+
+```ruby
+# Gemfile
+gem "patchwork-rb"
+```
+
+The gem is `patchwork-rb`, and you `require "patchwork"`. Don't add `gem "patchwork"`: that name belongs to an unrelated gem on RubyGems.
+
+Everything here is plain JWT and HMAC that you could write by hand. The gem exists so the security-sensitive parts are right by default: constant-time comparison, secret rotation, bounded clock skew, and an algorithm allowlist that can never accept a symmetric algorithm.
+
+It holds no opinion about who your users are. The subject you mint for is an opaque string of your choosing. The gem only interprets it when you ask it to, in a format you declare.
+
+## 1. Configure
+
+```ruby
+# config/initializers/patchwork.rb
+Patchwork.configure do |config|
+  config.signing_key    = ENV.fetch("PATCHWORK_SIGNING_KEY")     # RSA private key, PEM or base64 PEM
+  config.issuer         = ENV.fetch("PATCHWORK_API_KEY_ID")      # your API key's public id, key_…
+  config.audience       = "acme-api"                             # your own API's audience
+  config.request_secret = ENV.fetch("PATCHWORK_REQUEST_SECRET")  # the connection's shared secret
+end
+```
+
+| Setting | Required for | Notes |
+| --- | --- | --- |
+| `signing_key` | minting, tool calls | Never leaves your server. Patchwork only ever holds the public half. |
+| `issuer` | minting, tool calls | Routes a token to your workspace. It identifies a key and authorises nothing. |
+| `audience` | minting, tool calls | No default. Tokens carry `["patchwork", audience]`, and tool calls are verified against it. |
+| `request_secret` | tool calls, health check | Set `previous_request_secret` during a rotation. |
+| `signing_kid` | optional | Defaults to the key's RFC 7638 thumbprint, so a new key gets a new `kid` automatically. |
+| `token_ttl` | optional | Seconds. Defaults to 120. The browser remints as needed. |
+| `max_token_lifetime` | optional | Seconds. Defaults to 900. Verification refuses a token whose own `exp - iat` is longer, so a good signature over an absurd expiry is still rejected. `nil` turns the check off. |
+
+A missing setting raises `Patchwork::ConfigurationError` the first time it is needed. So does a blank secret. An empty string is a valid HMAC key, so accepting one would make every signature forgeable.
+
+## 2. Choose your subject
+
+A subject is the partition key for a user's threads and memory. Patchwork stores it byte for byte and never parses it. Pick the smallest unit that must never see another unit's data:
+
+```
+"usr_9f2"              one account per person
+"usr_9f2:ws_acme"      a person inside one of their workspaces
+"slack:T04AB:U0APP"    a Slack user, namespaced by team
+"ticket:8821"          a conversation, not a person
+"ws_acme"              a whole team, sharing one memory on purpose
+```
+
+The **Subjects** guide in the Patchwork docs covers how to choose. The gem supports every shape.
+
+**Single-value subjects** need nothing from the gem. Pass the string.
+
+**Composite subjects** are where mistakes happen: a flipped order, or an id that contains the delimiter. You can declare the format once instead:
+
+```ruby
+# config/initializers/patchwork.rb, next to Patchwork.configure
+WorkspaceSubject = Patchwork::Subject.define(:user_id, :workspace_id)
+
+WorkspaceSubject.encode(user_id: user.id, workspace_id: workspace.id)  # => "usr_9f2:ws_acme"
+WorkspaceSubject.decode("usr_9f2:ws_acme").workspace_id                # => "ws_acme"
+WorkspaceSubject.decode("usr_9f2")                                      # => nil
+```
+
+Define as many parts as your boundary needs, with an optional namespace prefix and your own delimiter:
+
+```ruby
+Patchwork::Subject.define(:ticket_id, prefix: "ticket")                  # "ticket:8821"
+Patchwork::Subject.define(:team_id, :user_id, prefix: "slack")           # "slack:T04AB:U0APP"
+Patchwork::Subject.define(:org_id, :user_id, :project_id, delimiter: "|") # "o1|u2|p3"
+```
+
+A format enforces the composition rules so a call site can't get them wrong:
+
+- **Order comes from the definition.** `encode` is keyword-only, so the order at the call site doesn't matter.
+- **A part containing the delimiter is refused** at encode time. Otherwise it would be split wrongly on decode.
+- **Empty or whitespace-padded parts are refused.** `"usr_9f2 "` would silently be a different subject, with an empty history.
+- **`decode` never guesses.** The prefix and the part count must match exactly, or it returns `nil`. `decode!` raises `Patchwork::UnknownSubject` instead.
+
+Every subject, composed or not, must be a non-empty, valid UTF-8 String with no leading or trailing whitespace (Unicode spaces included) and no control characters. `SessionToken.issue` checks this before it signs anything.
+
+Formats have two more rules:
+- **Part names** must be lowercase identifiers, and can't be the name of a Struct method (`hash`, `freeze`, `to_h` and so on).
+- **Delimiters** can't contain whitespace. With a delimiter longer than one character, a part that would make the string ambiguous (`"acme:"` with `"::"`) is refused, so each subject string decodes to exactly one set of parts.
+
+If you decode several formats that share a delimiter, try the prefixed ones first: `define(:a, :b)` will also match `"slack:x"`.
+
+## 3. Mint tokens for your users
+
+Your frontend asks your backend for a token, and your backend decides who the user is. Patchwork never sees how you authenticate.
+
+```ruby
+class PatchworkTokensController < ApplicationController
+  before_action :authenticate_user!
+
+  def create
+    # Every component comes from the server session, never from request params.
+    subject = WorkspaceSubject.encode(user_id: current_user.id, workspace_id: current_workspace.id)
+
+    render json: {
+      token: Patchwork::SessionToken.issue(subject: subject),
+      expires_in: Patchwork.config.token_ttl
+    }
+  end
+end
+```
+
+Pass `connection_id:` when the agent has unpinned customer tools. It takes a connection UUID, not a name.
+
+### Patchwork minting for you (relay)
+
+Patchwork also calls your mint endpoint, server to server, when it needs a token for a subject it already acts for. That covers relay connections and **every Playground run**. It sends a signed `POST` with `{"subject": "..."}` and expects a bare `{ token, expires_in }` back. Both callers share your one `mint_url`, and the signature is what tells them apart.
+
+Give the gateway your mint path and it answers Patchwork's call itself. Your frontend's unsigned request to the same path still reaches your controller above:
+
+```ruby
+Rails.application.config.middleware.use Patchwork::Gateway,
+  mint_path: "/patchwork/mint",
+  resolve: ...
+```
+
+Without the gateway, verify and mint in your own route:
+
+```ruby
+def create
+  if request.headers["Patchwork-Signature"].present?
+    return render json: Patchwork::Mint.relay(body: request.raw_post,
+                                              signature: request.headers["Patchwork-Signature"],
+                                              path: request.path), status: :created
+  end
+  # ...the direct branch above
+end
+```
+
+Either way the token is minted for exactly the subject Patchwork sent, never a default. An unusable subject is a 400.
+
+### Publish your key
+
+Publish your public key so Patchwork can verify what you signed, and set the URL on your workspace:
+
+```ruby
+get "/patchwork/jwks", to: ->(_env) {
+  [ 200, { "content-type" => "application/json" }, [ Patchwork::SigningKey.jwks.to_json ] ]
+}
+```
+
+## 4. Verify the tool calls Patchwork makes to you
+
+When an agent calls one of your tools, Patchwork sends the request with a `Patchwork-Signature` header and the session token you minted. `Patchwork::Gateway` is Rack middleware that verifies both. It then hands the token's subject to a `resolve` callable, which you write, to decide what the request acts as.
+
+```ruby
+# config/initializers/patchwork.rb
+Rails.application.config.middleware.use Patchwork::Gateway,
+  subject: WorkspaceSubject,
+  resolve: ->(ref) {
+    # Your own records, not the token's say-so.
+    Membership.find_by(user_id: ref.user_id, workspace_id: ref.workspace_id)
+  }
+```
+
+In Sinatra or bare Rack it's the same call: `use Patchwork::Gateway, subject: ..., resolve: ...`.
+
+```ruby
+class Api::Tools::OrdersController < ApplicationController
+  def index
+    membership = request.env["patchwork.principal"]   # whatever resolve returned
+    render json: membership.workspace.orders.recent
+  end
+end
+```
+
+**`resolve` is required, and it is where authorisation happens.** A valid token proves you minted it for that subject. It does not prove the pairing is still valid: the user may have left the workspace since. Look the subject up in your own records and return whatever the request should act as. Return `nil` or `false` to refuse. An empty collection or an empty string also refuses, so an accidental `where(...)` that matches nothing can't authorise a request. Return a record, not a relation.
+
+### In a controller instead of middleware
+
+Middleware is the right default: it covers every tool route at once. When you would rather verify per controller, the concern runs the same code in a `before_action`:
+
+```ruby
+require "patchwork/rails"
+
+class Api::Tools::OrdersController < ApplicationController
+  include Patchwork::Rails::Presented
+  patchwork_subject_format WorkspaceSubject
+
+  def index
+    render json: patchwork_principal.workspace.orders.recent
+  end
+
+  private
+
+  def patchwork_resolve(ref)
+    Membership.find_by(user_id: ref.user_id, workspace_id: ref.workspace_id)
+  end
+end
+```
+
+`patchwork_resolve` is the same contract as `resolve` above, and defining it is mandatory — a controller that forgets raises rather than quietly skipping authorisation. `patchwork_subject_format` is optional and matches `subject:`. Verification renders a 401 itself, so an action body only ever runs for a verified call, and `patchwork_subject`, `patchwork_claims` and `patchwork_principal` are available inside it.
+
+Unlike the middleware, a request with no `Patchwork-Signature` is a 401 here rather than a fall-through: you mounted the concern on this controller, so nothing else was expected to arrive.
+
+This is the only part of the gem that needs `activesupport`, and it loads only when you require `patchwork/rails`.
+
+**`subject:` is optional.** With a format, the gateway decodes first and passes `resolve` the decoded parts. A subject in any other shape is a 401, and your code never sees it. Without a format, `resolve` gets the raw string, and you can interpret it however you like:
+
+```ruby
+use Patchwork::Gateway, resolve: ->(subject, claims) {
+  case subject
+  when /\Aticket:(\d+)\z/ then Ticket.find_by(id: $1)
+  when /\Ajob:/           then :system
+  end
+}
+```
+
+`resolve` can take `(subject)` or `(subject, claims)`. Any object that responds to `call` works.
+
+After a successful call, the request env carries:
+
+| Key | Value |
+| --- | --- |
+| `patchwork.principal` | what `resolve` returned |
+| `patchwork.subject` | the raw `sub` string |
+| `patchwork.claims` | the verified token claims |
+
+Failure behaviour:
+
+- **Requests without a `Patchwork-Signature`** pass straight through to your own auth, untouched. The gateway doesn't read their bodies.
+- **Anything that fails after the signature is present** returns a 401 with a JSON error and never reaches your app. This covers a bad or stale signature, a missing, forged, expired or wrong-audience token, a subject in the wrong format, and a `resolve` that refuses.
+- **A missing `request_secret`** raises instead of rejecting quietly, so a broken deploy shows up as errors rather than as silently locked-out tools.
+- **A signed body over `max_body_bytes`** (1 MiB by default) is a 413, and the gateway reads no more than the limit. A malformed or stale signature header is refused before the body is read at all.
+- **401 bodies are generic** (`invalid signature`, `invalid token`, `subject not authorized`), so they don't reveal your audience or issuer.
+- **A signed request with no bearer token** is a 401, unless it is the relay mint above. Patchwork sends one only for the mint and for a Patch dry-run started without a session token.
+
+### What the signature does and doesn't cover
+
+The signature covers the method, the path and the raw body. **It does not cover the query string**, and Patchwork sends a GET tool's arguments as query parameters. So a GET tool's arguments are not integrity-protected. Anyone who can alter a request in flight (a TLS-terminating proxy, for example) can change them without breaking the signature. Give any tool whose arguments matter, such as ids, amounts or anything that writes, a `POST` binding, where the arguments travel in the signed body.
+
+The signed path is the one your app sees. If a proxy rewrites paths before your app does, mount the gateway where the original path is still intact.
+
+**Method overrides are refused.** A signed request that carries `X-HTTP-Method-Override`, or that `Rack::MethodOverride` has already rewritten, is a 401. Patchwork never sends one, and the header isn't signed.
+
+### Replays
+
+A signature is valid for 300 seconds, and a captured request can be replayed inside that window. For tools with side effects, pass a `replay_guard`. It is called with a key and a TTL, and must return truthy only the first time it sees that key:
+
+```ruby
+Rails.application.config.middleware.use Patchwork::Gateway,
+  resolve: ...,
+  replay_guard: ->(key, ttl) { Rails.cache.write(key, true, unless_exist: true, expires_in: ttl) }
+```
+
+Use a cache that every app process shares. A per-process cache only stops replays that land on the same process.
+
+## 5. Health check
+
+The gateway answers `POST /patchwork/up` (also when it's mounted under a prefix) with a proof that only the shared secret can produce. That's how **Test** on a connection in the Patchwork console reports **verified** rather than just reachable. Pass `health_check: false` to handle that route yourself with `Patchwork::HealthCheck.respond(body:)`.
+
+## 6. Verify webhooks
+
+Webhooks use the same signing scheme, keyed with the **webhook endpoint's own secret**, not the request secret.
+
+```ruby
+class PatchworkWebhooksController < ActionController::API
+  def create
+    event = Patchwork::Webhook.verify!(
+      body: request.raw_post,
+      signature: request.headers["Patchwork-Signature"],
+      secret: ENV.fetch("PATCHWORK_WEBHOOK_SECRET"),
+      path: "/hooks/patchwork"
+    )
+
+    case event.type
+    when "run.completed" then FulfilJob.perform_later(event.run_id)
+    when "run.failed"    then alert(event.data)
+    end
+
+    head :ok
+  rescue Patchwork::InvalidSignature
+    head :unauthorized
+  end
+end
+```
+
+- **Read the raw body.** `request.raw_post` is the signed bytes. Re-serialised params are not.
+- **Pass the path you registered.** A full URL works too. Use the registered path even if a proxy rewrites it.
+- **Rotate with `secrets: [new, old]`** instead of `secret:`.
+- **Deduplicate on `event.id`.** A delivery can arrive more than once.
+
+`verify!` raises `Patchwork::InvalidSignature`, or its subclass `Patchwork::StaleSignature`. `verify` returns `nil` instead.
+
+## 7. Rotating secrets and keys
+
+**Request secret:** set the new value as `request_secret` and the old one as `previous_request_secret`. Deploy, update the connection in Patchwork, then remove the previous value.
+
+**Signing key:** serve both public keys from your JWKS, and switch `signing_key` once Patchwork has fetched the new set. Never remove the old key first. With `signing_kid` unset, each key's `kid` is its thumbprint, so the two can't collide. To serve more than one key, build the document yourself from `Patchwork::SigningKey.public_jwk` plus the previous one.
+
+## MCP login bridge
+
+If you export an agent over MCP, Patchwork sends your user to a login bridge you host, and the bridge hands back a signed subject — the one step only you can do. It is signed with the same key you mint with:
+
+```ruby
+get "/patchwork/bridge" do
+  subject = WorkspaceSubject.encode(user_id: current_user.id, workspace_id: chosen_workspace.id)
+  assertion = Patchwork::BridgeAssertion.issue(
+    subject: subject,
+    nonce: params[:state],
+    audience: PATCHWORK_CALLBACK
+  )
+  redirect "#{PATCHWORK_CALLBACK}?state=#{params[:state]}&assertion=#{assertion}"
+end
+```
+
+Authenticate the user first, and bake the workspace choice into the subject — that decision is yours, and Patchwork never needs to know your tenants. The assertion is bound to the `state` nonce and the callback audience and lives 120 seconds at most, which is the ceiling the callback enforces; asking for longer raises.
+
+## Errors
+
+| Error | Means |
+| --- | --- |
+| `Patchwork::ConfigurationError` | A required setting or secret is missing or blank, or the signing key is not an unencrypted RSA private key of at least 2048 bits. Treat it as a deploy bug. |
+| `Patchwork::InvalidSignature` | The HMAC did not match any configured secret. |
+| `Patchwork::StaleSignature` | The signature timestamp is outside the 300-second window. It subclasses `InvalidSignature`. |
+| `Patchwork::InvalidToken` | The token was forged, expired, for another audience or issuer, or had no usable `sub`. |
+| `Patchwork::UnknownSubject` | A subject didn't match its declared format, or `resolve` refused it. |
+| `Patchwork::LifetimeExceeded` | The token's own lifetime is longer than `max_token_lifetime`. It subclasses `InvalidToken`. |
+| `ArgumentError` | A subject you tried to mint or encode breaks the rules in section 2. |
+
+All of them except `ArgumentError` inherit from `Patchwork::Error`. None of them carries key material in its message.
+
+## Lower level
+
+The primitives are public if you need to sign or verify outside Rack:
+
+```ruby
+Patchwork::Signature.header(secrets: [secret], timestamp: Time.now.to_i, method: "POST", path: "/v1/runs", body: body)
+Patchwork::Signature.verify!(secrets: [current, previous], header: header, method: "POST", path: path, body: raw_body)
+Patchwork::SessionToken.verify(token)   # => claims, or raises Patchwork::InvalidToken
+```
+
+## Compatibility
+
+Ruby 3.1+. One runtime dependency: `jwt` (>= 2.10.3, < 4, excluding 3.0.0–3.1.2, which are affected by GHSA-c32j-vqhx-rx3x). `Patchwork::Gateway` also needs `rack`, and is only defined when Rack is loaded. It works with any Rack app: Rails, Sinatra, Hanami or bare Rack. `Patchwork::Rails::Presented` needs `activesupport` and loads only when you require `patchwork/rails`.
+
+## Licence
+
+MIT.

data/lib/patchwork/bridge_assertion.rb

@@ -0,0 +1,64 @@
+require "jwt"
+
+module Patchwork
+  module BridgeAssertion
+    ALLOWED_ALGORITHMS = %w[RS256 RS384 RS512 ES256 ES384 ES512 PS256 PS384 PS512].freeze
+    MAX_TTL = 120
+    LEEWAY = 30
+
+    def self.issue(subject:, nonce:, audience:, ttl: MAX_TTL)
+      Subject.validate!(subject)
+      state = nonce.to_s
+      raise ArgumentError, "nonce is required" if state.empty?
+      raise ArgumentError, "audience is required" if audience.to_s.empty?
+      raise ArgumentError, "ttl must be #{MAX_TTL}s or less" if ttl > MAX_TTL
+
+      now = Time.now.to_i
+      claims = {
+        sub: subject,
+        aud: audience.to_s,
+        nonce: state,
+        iat: now,
+        exp: now + ttl
+      }
+
+      JWT.encode(claims, SigningKey.private_key, SigningKey::ALG, { kid: SigningKey.kid })
+    end
+
+    def self.verify(token, audience:, nonce:, key: nil)
+      expected = nonce.to_s
+      raise ArgumentError, "nonce is required" if expected.empty?
+
+      claims = decode(token, audience, key)
+      raise InvalidToken, "nonce mismatch" unless SecureCompare.call(claims["nonce"], expected)
+
+      validate_subject!(claims["sub"])
+      claims
+    end
+
+    def self.validate_subject!(subject)
+      Subject.validate!(subject)
+    rescue ArgumentError => e
+      raise InvalidToken, e.message
+    end
+    private_class_method :validate_subject!
+
+    def self.decode(token, audience, key)
+      JWT.decode(
+        token.to_s,
+        key || SigningKey.public_key,
+        true,
+        algorithms: ALLOWED_ALGORITHMS,
+        aud: audience.to_s,
+        verify_aud: true,
+        verify_expiration: true,
+        exp_leeway: LEEWAY,
+        nbf_leeway: LEEWAY,
+        required_claims: %w[sub aud exp nonce]
+      ).first
+    rescue JWT::DecodeError => e
+      raise InvalidToken, e.message
+    end
+    private_class_method :decode
+  end
+end

data/lib/patchwork/configuration.rb

@@ -0,0 +1,63 @@
+module Patchwork
+  class Configuration
+    # signing_key  — your RSA private key, PEM or base64-encoded PEM.
+    # signing_kid  — the JWKS key id. Defaults to the key's RFC 7638 thumbprint,
+    #                so rotating the key rotates the kid with it.
+    # issuer       — your Patchwork API key's public id (key_…).
+    # audience     — your own API's audience. Minted tokens carry it next to
+    #                "patchwork", and tool calls are verified against it.
+    # request_secret / previous_request_secret — the connection's shared secret,
+    #                and the one it replaced while a rotation is in flight.
+    attr_accessor :signing_key, :signing_kid, :issuer, :audience,
+                  :request_secret, :previous_request_secret, :token_ttl,
+                  :max_token_lifetime
+
+    DEFAULT_TTL = 120
+    DEFAULT_MAX_TOKEN_LIFETIME = 900
+
+    def initialize
+      @token_ttl = DEFAULT_TTL
+      @max_token_lifetime = DEFAULT_MAX_TOKEN_LIFETIME
+    end
+
+    def request_secrets
+      [ request_secret, previous_request_secret ].map(&:to_s).reject(&:empty?)
+    end
+
+    def signing_key?
+      !signing_key.to_s.empty?
+    end
+
+    def request_secret?
+      !request_secrets.empty?
+    end
+
+    def issuer!
+      fetch!(:issuer)
+    end
+
+    def audience!
+      fetch!(:audience)
+    end
+
+    SECRETS = %i[signing_key request_secret previous_request_secret].freeze
+
+    # Default #inspect prints every ivar, so a config that reaches a log line,
+    # an error tracker or a console would carry the private key with it.
+    def inspect
+      fields = %i[issuer audience signing_kid token_ttl max_token_lifetime].map { |name| "#{name}=#{public_send(name).inspect}" }
+      fields += SECRETS.map { |name| "#{name}=#{public_send(name).to_s.empty? ? 'nil' : '[REDACTED]'}" }
+      "#<Patchwork::Configuration #{fields.join(', ')}>"
+    end
+    alias to_s inspect
+
+    private
+
+    def fetch!(name)
+      value = public_send(name).to_s
+      raise ConfigurationError, "#{name} is not set — see Patchwork.configure" if value.empty?
+
+      value
+    end
+  end
+end

data/lib/patchwork/errors.rb

@@ -0,0 +1,9 @@
+module Patchwork
+  Error = Class.new(StandardError)
+  ConfigurationError = Class.new(Error)
+  InvalidToken = Class.new(Error)
+  LifetimeExceeded = Class.new(InvalidToken)
+  InvalidSignature = Class.new(Error)
+  StaleSignature = Class.new(InvalidSignature)
+  UnknownSubject = Class.new(Error)
+end