patchwork-rb 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8b84f16b49af905d391e3f3d47e67339f1fec7cf28f6ee7d002d72b4d4c20aa
-  data.tar.gz: 9a0d2be627ba90e61da19d3512c1cf0e2520bf132cf11446199f029092958a9d
+  metadata.gz: 02aaad7b12e53f7fd6eb119d03cb576a91cb80afa6d488eecd16dcd251839479
+  data.tar.gz: 4743b0e1a4841078b6a85db01048bc9a888a76707e9b746b3098657b7f777785
 SHA512:
-  metadata.gz: 61db91122e933dfbbe9a96370cd8a2b7db3529b4ffe62f07ba263a7911596cea23cbbc6902dac2a22ad250aca11c4ff185913c756a83dfb04d1d509c65472a52
-  data.tar.gz: e002d213489d59a7df24aa98aa0f45e5c41b0fbd61e7cffb2323911f04a750566f23c7d5e9c250dd2c030d3401a5c378655ddd10cef44dd06a5d73e276ed5885
+  metadata.gz: 865c4584db5879b87c9e6292ef356ec605e04667c072fa535bb2c715e3cfe1d5ee9e28199c06a71d943bb6a30f4dfc9ec1510c5b89cd080109763ceb4c18e40e
+  data.tar.gz: 8711b23744bb966e445103a154a5f827bbdd7a149942b3ffcbe24c25b8358a990c455412a74b88bffe0775af6c97df2ec55aae069637ea27d67cf086253b4617

data/README.md

@@ -2,18 +2,16 @@
 
 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.
+[Documentation](https://docs.usepatchwork.co) · [Changelog](CHANGELOG.md) · [Issues](https://github.com/chromablue-labs/patchwork-rb/issues)
 
 ```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.
+Install `patchwork-rb` and `require "patchwork"`. Do not add `gem "patchwork"` — that name belongs to an unrelated gem.
 
-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.
+The subject you mint for is an opaque string you choose. Patchwork stores it, partitions threads and memory on it, and hands it back on every tool call, without ever parsing it. Neither does this gem, unless you declare a format (section 2).
 
 ## 1. Configure
 
@@ -51,11 +49,11 @@ A subject is the partition key for a user's threads and memory. Patchwork stores
 "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.
+The [Subjects guide](https://docs.usepatchwork.co/guides/subjects) covers how to choose. Every shape works.
 
 **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:
+**Composite subjects** are worth declaring once, so a flipped order or an id containing the delimiter is caught at the call site:
 
 ```ruby
 # config/initializers/patchwork.rb, next to Patchwork.configure
@@ -74,7 +72,7 @@ Patchwork::Subject.define(:team_id, :user_id, prefix: "slack")           # "slac
 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:
+A format fixes the rules:
 
 - **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.
@@ -91,14 +89,23 @@ If you decode several formats that share a delimiter, try the prefixed ones firs
 
 ## 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
+# config/routes.rb
+post "patchwork/mint",    to: "patchwork#mint"
+get  "patchwork/jwks",    to: "patchwork#jwks"
+post "patchwork/webhook", to: "patchwork#webhook"
+```
+
+`mint` has two callers on one URL, and the signature tells them apart. Your frontend asks for a token for the signed-in user; Patchwork asks, server to server, for a token for a subject it already acts for — that covers relay connections and **every Playground run**. Patchwork's call is a signed `POST` carrying `{"subject": "..."}` and expects a bare `{ token, expires_in }` back. The [Session tokens guide](https://docs.usepatchwork.co/guides/session-tokens) has the wire format, and the [Mint endpoint guide](https://docs.usepatchwork.co/guides/mint-endpoint) covers both branches.
 
 ```ruby
-class PatchworkTokensController < ApplicationController
-  before_action :authenticate_user!
+class PatchworkController < ApplicationController
+  skip_forgery_protection
+
+  def mint
+    return relay_mint if request.headers["Patchwork-Signature"].present?
 
-  def create
-    # Every component comes from the server session, never from request params.
+    authenticate_user!
     subject = WorkspaceSubject.encode(user_id: current_user.id, workspace_id: current_workspace.id)
 
     render json: {
@@ -106,51 +113,38 @@ class PatchworkTokensController < ApplicationController
       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: ...
-```
+  def jwks
+    render json: Patchwork::SigningKey.jwks
+  end
 
-Without the gateway, verify and mint in your own route:
+  private
 
-```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
+  def relay_mint
+    render json: Patchwork::Mint.relay(
+      body: request.raw_post,
+      signature: request.headers["Patchwork-Signature"],
+      path: request.path
+    ), status: :created
+  rescue Patchwork::InvalidSignature
+    head :unauthorized
+  rescue Patchwork::Mint::BadRequest
+    head :bad_request
   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.
+Build the subject from server state, never from request params. On the direct branch that is the whole of your authorisation.
 
-### Publish your key
+`Mint.relay` mints for exactly the subject Patchwork sent, never a default, and verifies the signature before it reads the subject at all. Pass `connection_id:` to `issue` when the agent has unpinned customer tools; it takes a connection UUID, not a name.
 
-Publish your public key so Patchwork can verify what you signed, and set the URL on your workspace:
+`jwks` publishes the public half of your signing key, so Patchwork can verify what you minted. Set its URL on your workspace.
 
-```ruby
-get "/patchwork/jwks", to: ->(_env) {
-  [ 200, { "content-type" => "application/json" }, [ Patchwork::SigningKey.jwks.to_json ] ]
-}
-```
+If you mount the gateway in section 4, `mint_path: "/patchwork/mint"` makes it answer the relay call before your controller sees it, and you can drop `relay_mint`. Your frontend's unsigned request still reaches `mint`.
 
 ## 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.
+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. The [Tool calls guide](https://docs.usepatchwork.co/guides/tool-calls) describes what Patchwork sends.
 
 ```ruby
 # config/initializers/patchwork.rb
@@ -236,7 +230,7 @@ Failure behaviour:
 
 ### 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 signature covers the method, the path and the raw body, as specified in the [Signing guide](https://docs.usepatchwork.co/guides/signing). **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.
 
@@ -256,31 +250,43 @@ Use a cache that every app process shares. A per-process cache only stops replay
 
 ## 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:)`.
+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.
+
+Without the gateway, it is another action on the same controller. Route `post "patchwork/up", to: "patchwork#up"`:
+
+```ruby
+def up
+  render json: Patchwork::HealthCheck.respond(body: request.raw_post)
+rescue Patchwork::HealthCheck::BadRequest
+  head :bad_request
+end
+```
+
+Pass `health_check: false` if you want to own the route while still using the gateway for tool calls.
 
 ## 6. Verify webhooks
 
-Webhooks use the same signing scheme, keyed with the **webhook endpoint's own secret**, not the request secret.
+Webhooks use the same signing scheme, keyed with the **webhook endpoint's own secret**, not the request secret. The [Events guide](https://docs.usepatchwork.co/guides/events) lists the event types.
 
-```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"
-    )
+Deliveries land on the same controller:
 
-    case event.type
-    when "run.completed" then FulfilJob.perform_later(event.run_id)
-    when "run.failed"    then alert(event.data)
-    end
+```ruby
+def webhook
+  event = Patchwork::Webhook.verify!(
+    body: request.raw_post,
+    signature: request.headers["Patchwork-Signature"],
+    secret: ENV.fetch("PATCHWORK_WEBHOOK_SECRET"),
+    path: "/patchwork/webhook"
+  )
 
-    head :ok
-  rescue Patchwork::InvalidSignature
-    head :unauthorized
+  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
 ```
 
@@ -299,21 +305,28 @@ end
 
 ## 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:
+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. It is signed with the same key you mint with:
+
+Route `get "patchwork/bridge", to: "patchwork#bridge"` and add the action alongside the others:
 
 ```ruby
-get "/patchwork/bridge" do
+def bridge
+  authenticate_user!
   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}"
+
+  redirect_to "#{PATCHWORK_CALLBACK}?state=#{params[:state]}&assertion=#{assertion}",
+              allow_other_host: true
 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.
+`allow_other_host:` is required — the redirect leaves your domain.
+
+Authenticate the user first, and bake the workspace choice into the subject. The assertion is bound to the `state` nonce and the callback audience, and lives 120 seconds at most. That ceiling is enforced at the callback, so asking for longer raises.
 
 ## Errors
 
@@ -343,6 +356,10 @@ Patchwork::SessionToken.verify(token)   # => claims, or raises Patchwork::Invali
 
 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`.
 
+## Support
+
+Bugs and questions: [github.com/chromablue-labs/patchwork-rb/issues](https://github.com/chromablue-labs/patchwork-rb/issues). The platform documentation is at [docs.usepatchwork.co](https://docs.usepatchwork.co).
+
 ## Licence
 
 MIT.

data/lib/patchwork/version.rb

@@ -1,3 +1,3 @@
 module Patchwork
-  VERSION = "0.1.0".freeze
+  VERSION = "0.1.1".freeze
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: patchwork-rb
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Chromablue Labs
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jwt
@@ -55,9 +56,8 @@ dependencies:
         version: 3.1.2
 description: 'Server-side helpers for integrating with Patchwork: RS256 session tokens,
   HMAC request signing and verification, webhook signature verification, and Rack
-  middleware for hosted tool calls. This is the inbound half — everything Patchwork
-  sends you, and the credentials you hand it. A client for calling the Patchwork API
-  arrives in 0.2.'
+  middleware for the tool calls Patchwork makes to your backend.'
+email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -86,9 +86,12 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://usepatchwork.co
-  source_code_uri: https://github.com/chromablue-labs/crossbar
-  bug_tracker_uri: https://github.com/chromablue-labs/crossbar/issues
+  documentation_uri: https://github.com/chromablue-labs/patchwork-rb#readme
+  source_code_uri: https://github.com/chromablue-labs/patchwork-rb
+  changelog_uri: https://github.com/chromablue-labs/patchwork-rb/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/chromablue-labs/patchwork-rb/issues
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -103,7 +106,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Ruby SDK for Patchwork — mint session tokens, verify tool calls and webhooks
 test_files: []