patchwork-rb 0.1.0

data/lib/patchwork/subject.rb

@@ -0,0 +1,162 @@
+module Patchwork
+  # A subject is an opaque string you choose. Patchwork stores it, partitions
+  # threads and memory on it, and hands it back on every tool call — it never
+  # parses it. So this gem never parses it either, unless you ask it to.
+  #
+  # Two levels:
+  #
+  #   Patchwork::Subject.validate!("ticket:8821")   # any shape, just checked
+  #
+  #   Membership = Patchwork::Subject.define(:user_id, :workspace_id)
+  #   Membership.encode(user_id: "usr_1", workspace_id: "ws_acme")  # => "usr_1:ws_acme"
+  #   Membership.decode("usr_1:ws_acme").workspace_id                # => "ws_acme"
+  #
+  # A definition is a format *you* declare, with as many parts as your isolation
+  # boundary needs, an optional namespace prefix, and your own delimiter.
+  module Subject
+    DEFAULT_DELIMITER = ":".freeze
+
+    # The rules every subject obeys, composed or not. Patchwork itself rejects
+    # only the empty string; the gem also rejects surrounding whitespace, because
+    # a trailing space from a template silently creates a second partition.
+    def self.validate!(subject)
+      raise ArgumentError, "subject must be a String, got #{subject.class}" unless subject.is_a?(String)
+
+      text = utf8(subject)
+      raise ArgumentError, "subject must be valid UTF-8" if text.nil?
+      raise ArgumentError, "subject must not be empty" if text.empty?
+      raise ArgumentError, "subject must not have leading or trailing whitespace" if padded?(text)
+      raise ArgumentError, "subject must not contain control characters" if CONTROL.match?(text)
+
+      subject
+    end
+
+    # Unicode whitespace, not just ASCII: a non-breaking space pasted from HTML
+    # is the same silent second partition as a trailing ASCII space.
+    EDGE_SPACE = /\A[[:space:]\u200B\u2060\uFEFF]|[[:space:]\u200B\u2060\uFEFF]\z/
+    # CR and LF matter beyond hygiene: in relay the subject travels in a header.
+    CONTROL = /[[:cntrl:]]/
+
+    def self.padded?(text)
+      EDGE_SPACE.match?(text)
+    end
+
+    # Returns a UTF-8 copy, or nil when the bytes are not valid in their own
+    # encoding or have no UTF-8 form. Never raises on hostile input.
+    def self.utf8(value)
+      return nil unless value.valid_encoding?
+
+      text = value.encoding == Encoding::UTF_8 ? value : value.encode(Encoding::UTF_8)
+      text.valid_encoding? ? text : nil
+    rescue EncodingError
+      nil
+    end
+
+    def self.define(*parts, delimiter: DEFAULT_DELIMITER, prefix: nil)
+      Format.new(parts, delimiter: delimiter, prefix: prefix)
+    end
+
+    class Format
+      attr_reader :parts, :delimiter, :prefix
+
+      def initialize(parts, delimiter:, prefix:)
+        raise ArgumentError, "define at least one part" if parts.empty?
+        raise ArgumentError, "parts must be symbols" unless parts.all?(Symbol)
+        raise ArgumentError, "parts must be unique" unless parts.uniq.size == parts.size
+        parts.each { |part| name!(part) }
+        raise ArgumentError, "delimiter must be a non-empty String" unless delimiter.is_a?(String) && !delimiter.empty?
+
+        text = Subject.utf8(delimiter)
+        if text.nil? || /[[:space:][:cntrl:]]/.match?(text)
+          raise ArgumentError, "delimiter must be valid UTF-8 with no whitespace or control characters"
+        end
+
+        @parts = parts.freeze
+        @delimiter = text.dup.freeze
+        @prefix = prefix&.to_s&.then { |value| component!(:prefix, value) }&.freeze
+        @ref = Struct.new(*parts, keyword_init: true)
+        freeze
+      end
+
+      # Keyword-only, so the order of the parts is fixed by the definition and
+      # never by a call site — a flipped order is a different subject.
+      def encode(**values)
+        missing = parts - values.keys
+        unknown = values.keys - parts
+        raise ArgumentError, "missing subject parts: #{missing.join(', ')}" if missing.any?
+        raise ArgumentError, "unknown subject parts: #{unknown.join(', ')}" if unknown.any?
+
+        segments = parts.map { |part| component!(part, values[part].to_s) }
+        subject = [ prefix, *segments ].compact.join(delimiter)
+
+        # With a multi-character delimiter a part can end with half of it
+        # ("acme:" + "::" + "x"), making two tuples encode to one string. The
+        # only complete check is that the string decodes back to what went in.
+        unless decode(subject)&.to_h == parts.zip(segments).to_h
+          raise ArgumentError, "subject parts are ambiguous with the delimiter #{delimiter.inspect}"
+        end
+
+        subject
+      end
+
+      # Returns a struct with one reader per part, or nil when the subject is not
+      # in this format. Never guesses: the part count must match exactly.
+      def decode(subject)
+        return nil unless subject.is_a?(String)
+
+        body = Subject.utf8(subject)
+        return nil if body.nil?
+        if prefix
+          head = "#{prefix}#{delimiter}"
+          return nil unless body.start_with?(head)
+
+          body = body.delete_prefix(head)
+        end
+
+        segments = body.split(delimiter, -1)
+        return nil unless segments.size == parts.size
+        return nil if segments.any? { |segment| segment.empty? || Subject.padded?(segment) || CONTROL.match?(segment) }
+
+        @ref.new(**parts.zip(segments).to_h).freeze
+      end
+
+      def decode!(subject)
+        decode(subject) || raise(UnknownSubject, "subject is not in the #{inspect} format")
+      end
+
+      def match?(subject)
+        !decode(subject).nil?
+      end
+
+      def inspect
+        "#<Patchwork::Subject #{[ prefix, *parts.map { |part| "<#{part}>" } ].compact.join(delimiter)}>"
+      end
+      alias to_s inspect
+
+      private
+
+      # A part containing the delimiter makes the string ambiguous to decode, so
+      # it is refused at encode time rather than mis-split later.
+      def component!(name, value)
+        text = Subject.utf8(value)
+        raise ArgumentError, "subject part #{name} must be valid UTF-8" if text.nil?
+        raise ArgumentError, "subject part #{name} is empty" if text.empty?
+        raise ArgumentError, "subject part #{name} contains the delimiter #{delimiter.inspect}" if text.include?(delimiter)
+        raise ArgumentError, "subject part #{name} has leading or trailing whitespace" if Subject.padded?(text)
+        raise ArgumentError, "subject part #{name} contains control characters" if CONTROL.match?(text)
+
+        text
+      end
+
+      # A part named like a Struct method (:freeze, :hash, :class, :to_h)
+      # would shadow it on the decoded ref, so decode could hand back a part's
+      # raw string where a frozen ref was expected.
+      RESERVED = Struct.new(:placeholder).new.public_methods.freeze
+
+      def name!(part)
+        raise ArgumentError, "part #{part.inspect} must be a lowercase identifier" unless /\A[a-z_][a-z0-9_]*\z/.match?(part)
+        raise ArgumentError, "part #{part.inspect} clashes with a Struct method" if RESERVED.include?(part)
+      end
+    end
+  end
+end

data/lib/patchwork/version.rb

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

data/lib/patchwork/webhook.rb

@@ -0,0 +1,77 @@
+require "json"
+require "uri"
+
+module Patchwork
+  module Webhook
+    EVENT_HEADER = "Patchwork-Event".freeze
+    DELIVERY_HEADER = "Patchwork-Delivery".freeze
+
+    Event = Struct.new(:id, :type, :created_at, :origin, :source, :context, :data, :payload, keyword_init: true) do
+      def run_id = payload["run_id"]
+      def thread_id = payload["thread_id"]
+      def workspace_id = context.is_a?(Hash) ? context["workspace_id"] : nil
+      def test? = type == "endpoint.test"
+    end
+
+    # Webhooks are keyed with the endpoint's own secret, not the request secret.
+    # Pass `secret:`, or `secrets:` with the current and previous during a
+    # rotation.
+    def self.verify!(body:, signature:, path:, secret: nil, secrets: nil, skew: Signature::SKEW, now: Time.now.to_i)
+      raise ArgumentError, "pass secret: or secrets:, not both" if secret && secrets
+
+      Signature.verify!(
+        secrets: secrets || [ secret ],
+        header: signature,
+        method: "POST",
+        path: normalize(path),
+        body: body,
+        skew: skew,
+        now: now
+      )
+
+      parse(body)
+    end
+
+    # Like verify!, but returns nil for a bad or stale signature. A missing
+    # secret still raises: that is a deploy problem, not a forged delivery.
+    def self.verify(**options)
+      verify!(**options)
+    rescue InvalidSignature
+      nil
+    end
+
+    def self.parse(body)
+      payload = JSON.parse(body.to_s)
+      raise Error, "webhook body is not a JSON object" unless payload.is_a?(Hash)
+
+      Event.new(
+        id: payload["id"],
+        type: payload["type"],
+        created_at: payload["created_at"],
+        origin: payload["origin"],
+        source: payload["source"],
+        context: payload["context"],
+        data: payload["data"],
+        payload: payload
+      )
+    rescue JSON::ParserError => e
+      raise Error, "webhook body is not JSON: #{e.message}"
+    end
+
+    # Only the path is signed — never the host, query or fragment — so accept a
+    # registered URL, a path, or request.fullpath and reduce each to the path.
+    def self.normalize(path)
+      value = path.to_s
+      if value.match?(%r{\Ahttps?://}i)
+        begin
+          value = URI(value).path.to_s
+        rescue URI::InvalidURIError
+          raise ArgumentError, "path is not a valid URL: #{value.inspect}"
+        end
+      end
+      value = value.split(/[?#]/, 2).first.to_s
+      value.empty? ? "/" : value
+    end
+    private_class_method :normalize
+  end
+end

data/lib/patchwork-rb.rb

@@ -0,0 +1 @@
+require "patchwork"

data/lib/patchwork.rb

@@ -0,0 +1,41 @@
+require "patchwork/version"
+require "patchwork/errors"
+require "patchwork/configuration"
+require "patchwork/secure_compare"
+require "patchwork/signature"
+require "patchwork/signing_key"
+require "patchwork/subject"
+require "patchwork/session_token"
+require "patchwork/presented"
+require "patchwork/webhook"
+require "patchwork/health_check"
+require "patchwork/mint"
+require "patchwork/bridge_assertion"
+
+module Patchwork
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+      SigningKey.reset!
+      config
+    end
+
+    def reset!
+      @config = Configuration.new
+      SigningKey.reset!
+    end
+  end
+end
+
+# The gateway is optional: it is defined only when Rack is available. Only a
+# missing Rack is tolerated — any other LoadError in the gateway still raises.
+begin
+  require "rack"
+rescue LoadError
+  nil
+end
+require "patchwork/gateway" if defined?(Rack)

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: patchwork-rb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chromablue Labs
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.10.3
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "!="
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+    - - "!="
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+    - - "!="
+      - !ruby/object:Gem::Version
+        version: 3.1.1
+    - - "!="
+      - !ruby/object:Gem::Version
+        version: 3.1.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.10.3
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "!="
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+    - - "!="
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+    - - "!="
+      - !ruby/object:Gem::Version
+        version: 3.1.1
+    - - "!="
+      - !ruby/object:Gem::Version
+        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.'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/patchwork-rb.rb
+- lib/patchwork.rb
+- lib/patchwork/bridge_assertion.rb
+- lib/patchwork/configuration.rb
+- lib/patchwork/errors.rb
+- lib/patchwork/gateway.rb
+- lib/patchwork/health_check.rb
+- lib/patchwork/mint.rb
+- lib/patchwork/presented.rb
+- lib/patchwork/rails.rb
+- lib/patchwork/secure_compare.rb
+- lib/patchwork/session_token.rb
+- lib/patchwork/signature.rb
+- lib/patchwork/signing_key.rb
+- lib/patchwork/subject.rb
+- lib/patchwork/version.rb
+- lib/patchwork/webhook.rb
+homepage: https://usepatchwork.co
+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
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby SDK for Patchwork — mint session tokens, verify tool calls and webhooks
+test_files: []