patchwork-rb 0.1.0

data/lib/patchwork/gateway.rb

@@ -0,0 +1,180 @@
+require "digest"
+require "json"
+require "rack"
+require "stringio"
+
+module Patchwork
+  # Rack middleware for the calls Patchwork makes to your backend.
+  #
+  #   use Patchwork::Gateway, resolve: ->(subject, claims) { ... }
+  #
+  # A request carrying a Patchwork-Signature is verified — signature first, then
+  # the session token you minted — and the token's subject is handed to your
+  # `resolve`. Whatever it returns is what the request acts as; nil, false or an
+  # empty collection is a 401. Requests without the header fall through to your
+  # own auth untouched.
+  #
+  # The gateway never interprets the subject. Pass `subject:` with a format from
+  # Patchwork::Subject.define and it decodes for you first, 401ing anything that
+  # is not in that format.
+  #
+  # Pass `mint_path:` and the gateway also answers Patchwork's server-to-server
+  # (relay) mint at that path; your own frontend's unsigned mint request at the
+  # same path still falls through to your app.
+  class Gateway
+    SUBJECT_KEY = "patchwork.subject".freeze
+    CLAIMS_KEY = "patchwork.claims".freeze
+    PRINCIPAL_KEY = "patchwork.principal".freeze
+    SIGNATURE_HEADER = "HTTP_PATCHWORK_SIGNATURE".freeze
+    MAX_BODY_BYTES = 1024 * 1024
+    MAX_CONTROL_BODY_BYTES = 16 * 1024
+
+    TooLarge = Class.new(Error)
+
+    def initialize(app, resolve:, subject: nil, mint_path: nil, health_check: true,
+                   max_body_bytes: MAX_BODY_BYTES, replay_guard: nil)
+      raise ArgumentError, "resolve must respond to #call" unless resolve.respond_to?(:call)
+      raise ArgumentError, "subject must respond to #decode" if subject && !subject.respond_to?(:decode)
+      raise ArgumentError, "replay_guard must respond to #call" if replay_guard && !replay_guard.respond_to?(:call)
+      raise ArgumentError, "mint_path must be an absolute path" if mint_path && !mint_path.to_s.start_with?("/")
+
+      @app = app
+      @resolve = resolve
+      @subject = subject
+      @mint_path = mint_path&.to_s
+      @health_check = health_check
+      @max_body_bytes = Integer(max_body_bytes)
+      @replay_guard = replay_guard
+    end
+
+    def call(env)
+      # Only this middleware may say a request is Patchwork's. Anything already
+      # in these keys came from somewhere else and is dropped, on every path.
+      [ SUBJECT_KEY, CLAIMS_KEY, PRINCIPAL_KEY ].each { |key| env.delete(key) }
+
+      request = Rack::Request.new(env)
+      signature = env[SIGNATURE_HEADER].to_s
+
+      return health(request, signature) if @health_check && at?(request, HealthCheck::PATH) && request.post?
+      return @app.call(env) if signature.empty?
+      return relay_mint(request, signature) if @mint_path && at?(request, @mint_path) && request.post?
+
+      authenticate!(env, request, signature)
+      @app.call(env)
+    rescue TooLarge
+      json(413, { error: "request body too large" })
+    rescue InvalidSignature
+      unauthorized("invalid signature")
+    rescue InvalidToken
+      unauthorized("invalid token")
+    rescue UnknownSubject
+      unauthorized("subject not authorized")
+    end
+
+    private
+
+    def authenticate!(env, request, signature)
+      verify_signature!(request, signature, limit: @max_body_bytes)
+
+      guard_replay!(request, signature)
+
+      result = Presented.authenticate!(
+        authorization: env["HTTP_AUTHORIZATION"],
+        resolve: @resolve,
+        subject: @subject
+      )
+
+      env[SUBJECT_KEY] = result.subject
+      env[CLAIMS_KEY] = result.claims
+      env[PRINCIPAL_KEY] = result.principal
+    end
+
+    # Patchwork's server-to-server mint (the mint-endpoint guide, relay branch):
+    # signed, no bearer, the subject in the body. Mint for exactly that subject.
+    def relay_mint(request, signature)
+      body = verify_signature!(request, signature, limit: MAX_CONTROL_BODY_BYTES)
+      subject = Mint.relay_subject(body)
+      json(201, { token: SessionToken.issue(subject: subject), expires_in: Patchwork.config.token_ttl })
+    rescue Mint::BadRequest => e
+      json(400, { error: e.message })
+    end
+
+    def health(request, signature)
+      body = if signature.empty?
+        read_body(request, MAX_CONTROL_BODY_BYTES)
+      else
+        verify_signature!(request, signature, limit: MAX_CONTROL_BODY_BYTES)
+      end
+
+      json(200, HealthCheck.respond(body: body))
+    rescue InvalidSignature
+      unauthorized("invalid signature")
+    rescue HealthCheck::BadRequest
+      json(400, { error: "invalid health check" })
+    end
+
+    # Header shape and freshness are checked before the body is read, so a
+    # garbage or stale header costs nothing but the header.
+    def verify_signature!(request, signature, limit:)
+      parsed = Signature.parse(signature)
+      raise InvalidSignature, "malformed signature" if parsed.nil?
+      raise StaleSignature, "stale signature" unless Signature.fresh?(parsed)
+
+      method = signed_method!(request)
+      body = read_body(request, limit)
+      Signature.verify!(
+        secrets: Patchwork.config.request_secrets,
+        header: signature,
+        method: method,
+        path: request.path,
+        body: body
+      )
+      body
+    end
+
+    # Patchwork signs the method it sent and never asks for an override. An
+    # override header is not covered by the signature, so a Rack::MethodOverride
+    # mounted after the gateway could turn a verified POST into a DELETE; one
+    # mounted before it has already rewritten REQUEST_METHOD. Refuse both.
+    def signed_method!(request)
+      Presented.signed_method!(request.env, request.request_method)
+    end
+
+    def guard_replay!(request, signature)
+      return unless @replay_guard
+
+      key = "patchwork:replay:#{Digest::SHA256.hexdigest("#{request.request_method} #{request.path} #{signature}")}"
+      raise InvalidSignature, "replayed request" unless @replay_guard.call(key, Signature::SKEW * 2)
+    end
+
+    # Reads at most `limit` bytes. The verified bytes are handed back to the app
+    # as a fresh StringIO, so it sees exactly what was verified whether or not
+    # the original input could rewind.
+    def read_body(request, limit)
+      length = request.content_length.to_i
+      raise TooLarge, "declared body exceeds #{limit} bytes" if length > limit
+
+      input = request.env["rack.input"]
+      body = input ? input.read(limit + 1).to_s : +""
+      raise TooLarge, "body exceeds #{limit} bytes" if body.bytesize > limit
+
+      request.env["rack.input"] = StringIO.new(body)
+      body
+    end
+
+    # The path Patchwork signed is SCRIPT_NAME + PATH_INFO; the route is
+    # matched on either, so the gateway also works mounted under a prefix.
+    def at?(request, path)
+      request.path == path || request.path_info == path
+    end
+
+    def unauthorized(message)
+      json(401, { error: message })
+    end
+
+    def json(status, payload)
+      body = JSON.generate(payload)
+      [ status, { "content-type" => "application/json", "content-length" => body.bytesize.to_s }, [ body ] ]
+    end
+  end
+end

data/lib/patchwork/health_check.rb

@@ -0,0 +1,36 @@
+require "json"
+require "openssl"
+
+module Patchwork
+  module HealthCheck
+    PATH = "/patchwork/up".freeze
+    PROOF_CONTEXT = "patchwork-up.v1:".freeze
+    MAX_NONCE_BYTES = 256
+
+    BadRequest = Class.new(Error)
+
+    # The context prefix keeps this proof from ever equalling a request
+    # signature, whose payload starts with a numeric timestamp — so answering
+    # unsigned probes is not a signing oracle.
+    def self.proof(secret:, nonce:)
+      key = secret.to_s
+      raise ConfigurationError, "request_secret is not set" if key.strip.empty?
+
+      OpenSSL::HMAC.hexdigest("SHA256", key, "#{PROOF_CONTEXT}#{nonce}")
+    end
+
+    def self.respond(body:, secret: nil)
+      parsed = JSON.parse(body.to_s)
+      raise BadRequest, "health check body must be a JSON object" unless parsed.is_a?(Hash)
+
+      nonce = parsed["nonce"]
+      unless nonce.is_a?(String) && !nonce.empty? && nonce.bytesize <= MAX_NONCE_BYTES
+        raise BadRequest, "health check nonce must be a string of 1-#{MAX_NONCE_BYTES} bytes"
+      end
+
+      { nonce: nonce, proof: proof(secret: secret || Patchwork.config.request_secret, nonce: nonce) }
+    rescue JSON::ParserError
+      raise BadRequest, "health check body is not JSON"
+    end
+  end
+end

data/lib/patchwork/mint.rb

@@ -0,0 +1,38 @@
+require "json"
+
+module Patchwork
+  # The relay half of your mint endpoint: Patchwork asking, server to server,
+  # for a token for a subject it already acts for. The Gateway answers it when
+  # given `mint_path:`; outside Rack, call Mint.relay from your own route.
+  #
+  #   result = Patchwork::Mint.relay(body: request.raw_post,
+  #                                  signature: request.headers["Patchwork-Signature"],
+  #                                  path: request.path)
+  #   render json: result, status: :created    # bare { token:, expires_in: }
+  module Mint
+    BadRequest = Class.new(Error)
+    MAX_BODY_BYTES = 16 * 1024
+
+    # Verifies the presenter signature, then mints for exactly the subject in
+    # the body — never a default, never a widened one. Raises InvalidSignature,
+    # StaleSignature or BadRequest.
+    def self.relay(body:, signature:, path:, secrets: Patchwork.config.request_secrets)
+      raise BadRequest, "mint body too large" if body.to_s.bytesize > MAX_BODY_BYTES
+
+      Signature.verify!(secrets: secrets, header: signature, method: "POST", path: path, body: body)
+      { token: SessionToken.issue(subject: relay_subject(body)), expires_in: Patchwork.config.token_ttl }
+    end
+
+    def self.relay_subject(body)
+      payload = JSON.parse(body.to_s)
+      raise BadRequest, "mint body must be a JSON object" unless payload.is_a?(Hash)
+
+      subject = payload["subject"]
+      Subject.validate!(subject)
+    rescue JSON::ParserError
+      raise BadRequest, "mint body is not JSON"
+    rescue ArgumentError
+      raise BadRequest, "mint body has no usable subject"
+    end
+  end
+end

data/lib/patchwork/presented.rb

@@ -0,0 +1,53 @@
+module Patchwork
+  module Presented
+    Result = Struct.new(:subject, :claims, :principal, keyword_init: true)
+
+    def self.authenticate!(authorization:, resolve:, subject: nil)
+      claims = SessionToken.verify(bearer(authorization))
+      presented = claims["sub"]
+      principal = resolve_principal(resolve, subject, presented, claims)
+      raise UnknownSubject, "subject was not resolved" if refused?(principal)
+
+      Result.new(subject: presented, claims: claims, principal: principal)
+    end
+
+    def self.signed_method!(env, request_method)
+      raise InvalidSignature, "method override on a signed request" if env.key?("HTTP_X_HTTP_METHOD_OVERRIDE")
+
+      original = env["rack.methodoverride.original_method"]
+      raise InvalidSignature, "method override on a signed request" if original && original != request_method
+
+      request_method
+    end
+
+    def self.bearer(authorization)
+      token = authorization.to_s[/\ABearer ([A-Za-z0-9_\-.=]+)\z/, 1]
+      raise InvalidToken, "no bearer token" if token.nil?
+
+      token
+    end
+
+    def self.resolve_principal(resolve, format, presented, claims)
+      argument = presented
+      if format
+        argument = format.decode(presented)
+        raise UnknownSubject, "subject is not in the expected format" if argument.nil?
+      end
+
+      takes_claims?(resolve) ? resolve.call(argument, claims) : resolve.call(argument)
+    end
+
+    def self.refused?(principal)
+      return true unless principal
+      return principal.empty? if principal.respond_to?(:empty?) && !principal.is_a?(String)
+
+      principal.is_a?(String) && principal.empty?
+    end
+
+    def self.takes_claims?(callable)
+      parameters = callable.respond_to?(:parameters) ? callable.parameters : callable.method(:call).parameters
+      positional = parameters.count { |type, _| type == :req || type == :opt }
+      parameters.any? { |type, _| type == :rest } || positional >= 2
+    end
+  end
+end

data/lib/patchwork/rails.rb

@@ -0,0 +1,70 @@
+require "active_support/concern"
+require "patchwork"
+
+module Patchwork
+  module Rails
+    module Presented
+      extend ActiveSupport::Concern
+
+      included do
+        before_action :verify_patchwork_call!
+      end
+
+      class_methods do
+        def patchwork_subject_format(format = nil)
+          @patchwork_subject_format = format if format
+          return @patchwork_subject_format if defined?(@patchwork_subject_format) && @patchwork_subject_format
+          return unless superclass.respond_to?(:patchwork_subject_format)
+
+          superclass.patchwork_subject_format
+        end
+      end
+
+      private
+
+      def verify_patchwork_call!
+        signature = request.headers[::Patchwork::Signature::HEADER].to_s
+        raise ::Patchwork::InvalidSignature, "missing signature" if signature.empty?
+
+        signed = ::Patchwork::Presented.signed_method!(request.env, request.request_method)
+        ::Patchwork::Signature.verify!(
+          secrets: ::Patchwork.config.request_secrets,
+          header: signature,
+          method: signed,
+          path: request.path,
+          body: request.raw_post
+        )
+
+        result = ::Patchwork::Presented.authenticate!(
+          authorization: request.headers["Authorization"],
+          resolve: method(:patchwork_resolve),
+          subject: self.class.patchwork_subject_format
+        )
+
+        @patchwork_subject = result.subject
+        @patchwork_claims = result.claims
+        @patchwork_principal = result.principal
+      rescue ::Patchwork::StaleSignature
+        deny_patchwork_call("stale signature")
+      rescue ::Patchwork::InvalidSignature
+        deny_patchwork_call("invalid signature")
+      rescue ::Patchwork::InvalidToken
+        deny_patchwork_call("invalid token")
+      rescue ::Patchwork::UnknownSubject
+        deny_patchwork_call("subject not authorized")
+      end
+
+      def patchwork_resolve(_subject)
+        raise ::Patchwork::ConfigurationError,
+              "#{self.class.name} must define patchwork_resolve(subject) — return the principal " \
+              "the call acts as, or nil to refuse it"
+      end
+
+      def deny_patchwork_call(message)
+        render json: { error: message }, status: :unauthorized
+      end
+
+      attr_reader :patchwork_subject, :patchwork_claims, :patchwork_principal
+    end
+  end
+end

data/lib/patchwork/secure_compare.rb

@@ -0,0 +1,13 @@
+require "openssl"
+
+module Patchwork
+  module SecureCompare
+    def self.call(expected, candidate)
+      expected = expected.to_s
+      candidate = candidate.to_s
+      return false unless expected.bytesize == candidate.bytesize
+
+      OpenSSL.fixed_length_secure_compare(expected, candidate)
+    end
+  end
+end

data/lib/patchwork/session_token.rb

@@ -0,0 +1,65 @@
+require "jwt"
+require "securerandom"
+
+module Patchwork
+  module SessionToken
+    PLATFORM_AUDIENCE = "patchwork".freeze
+
+    # Mints the token your frontend hands to Patchwork. `subject` is any string
+    # you choose — compose it with Patchwork::Subject.define if it has parts.
+    def self.issue(subject:, ttl: nil, connection_id: nil)
+      Subject.validate!(subject)
+
+      connection = connection_id.to_s
+      raise ArgumentError, "connection_id must be a connection id, not a wildcard" if connection == "*"
+
+      now = Time.now.to_i
+      claims = {
+        iss: Patchwork.config.issuer!,
+        aud: [ PLATFORM_AUDIENCE, Patchwork.config.audience! ],
+        sub: subject,
+        iat: now,
+        exp: now + (ttl || Patchwork.config.token_ttl),
+        jti: SecureRandom.uuid,
+        act: PLATFORM_AUDIENCE
+      }
+      claims[:conn] = connection unless connection.empty?
+
+      JWT.encode(claims, SigningKey.private_key, SigningKey::ALG, { kid: SigningKey.kid })
+    end
+
+    # Verifies a token you minted, as it comes back to you on a hosted tool
+    # call. The algorithm is pinned to RS256 against your own public key, so an
+    # HS256 token "signed" with that public key is refused.
+    def self.verify(token)
+      JWT.decode(
+        token.to_s,
+        SigningKey.public_key,
+        true,
+        algorithms: [ SigningKey::ALG ],
+        aud: Patchwork.config.audience!,
+        verify_aud: true,
+        iss: Patchwork.config.issuer!,
+        verify_iss: true,
+        verify_expiration: true,
+        required_claims: %w[sub aud exp iat iss]
+      ).first.tap do |claims|
+        Subject.validate!(claims["sub"])
+        enforce_lifetime!(claims)
+      end
+    rescue JWT::DecodeError, ArgumentError => e
+      raise InvalidToken, e.message
+    end
+
+    def self.enforce_lifetime!(claims)
+      bound = Patchwork.config.max_token_lifetime
+      return if bound.nil?
+
+      lifetime = claims["exp"].to_i - claims["iat"].to_i
+      return if lifetime <= bound
+
+      raise LifetimeExceeded, "token lifetime of #{lifetime}s exceeds the #{bound}s bound"
+    end
+    private_class_method :enforce_lifetime!
+  end
+end

data/lib/patchwork/signature.rb

@@ -0,0 +1,105 @@
+require "base64"
+require "openssl"
+
+module Patchwork
+  module Signature
+    SKEW = 300
+    HEADER = "Patchwork-Signature".freeze
+
+    # Patchwork sends one v1 per live secret — two during a rotation. The cap
+    # stops an unauthenticated header of thousands of candidates from turning
+    # verification into a CPU amplifier.
+    MAX_SIGNATURES = 8
+    MAX_HEADER_BYTES = 1024
+    TIMESTAMP = /\A\d{1,12}\z/
+    HEX_SHA256 = /\A\h{64}\z/
+
+    Parsed = Struct.new(:timestamp, :signatures, keyword_init: true)
+
+    def self.sign(secret:, timestamp:, method:, path:, body:)
+      secret = usable!([ secret ]).first
+      mac(secret, payload(timestamp, method, path, digest(body)))
+    end
+
+    def self.header(secrets:, timestamp:, method:, path:, body:)
+      base = payload(timestamp, method, path, digest(body))
+      signatures = usable!(secrets).map { |secret| mac(secret, base) }
+      "t=#{timestamp},#{signatures.map { |signature| "v1=#{signature}" }.join(",")}"
+    end
+
+    # Structural parse, with no secret and no body. Returns nil for anything
+    # Patchwork would never send, so a malformed header is rejected before the
+    # body is read.
+    def self.parse(header)
+      value = header.to_s
+      return nil if value.empty? || value.bytesize > MAX_HEADER_BYTES
+
+      pairs = value.split(",").map { |pair| pair.strip.split("=", 2) }
+      timestamps = pairs.select { |key, _| key == "t" }.map(&:last)
+      signatures = pairs.select { |key, _| key == "v1" }.map(&:last)
+      return nil unless timestamps.size == 1 && TIMESTAMP.match?(timestamps.first.to_s)
+      return nil if signatures.empty? || signatures.size > MAX_SIGNATURES
+
+      Parsed.new(timestamp: Integer(timestamps.first, 10), signatures: signatures)
+    end
+
+    def self.fresh?(parsed, skew: SKEW, now: Time.now.to_i)
+      (now - parsed.timestamp).abs <= skew
+    end
+
+    def self.verify(secrets:, header:, method:, path:, body:, skew: SKEW, now: Time.now.to_i)
+      secrets = usable!(secrets)
+      parsed = parse(header)
+      return :bad if parsed.nil?
+      return :stale unless fresh?(parsed, skew: skew, now: now)
+
+      # The body is hashed once and each secret MACs once, however many
+      # candidates the header carries.
+      base = payload(parsed.timestamp, method, path, digest(body))
+      expected = secrets.map { |secret| mac(secret, base) }
+      candidates = parsed.signatures.select { |candidate| HEX_SHA256.match?(candidate) }
+
+      matched = expected.product(candidates).any? { |mine, theirs| secure_compare(mine, theirs) }
+      matched ? :ok : :bad
+    end
+
+    def self.verify!(secrets:, header:, method:, path:, body:, skew: SKEW, now: Time.now.to_i)
+      case verify(secrets: secrets, header: header, method: method, path: path, body: body, skew: skew, now: now)
+      when :stale then raise StaleSignature, "signature timestamp outside the #{skew}s window"
+      when :bad then raise InvalidSignature, "signature did not match"
+      else true
+      end
+    end
+
+    def self.digest(body)
+      Base64.strict_encode64(OpenSSL::Digest::SHA256.digest(body.to_s))
+    end
+    private_class_method :digest
+
+    def self.payload(timestamp, method, path, digest)
+      "#{timestamp}.#{method.to_s.upcase}.#{path}.#{digest}"
+    end
+    private_class_method :payload
+
+    def self.mac(secret, payload)
+      OpenSSL::HMAC.hexdigest("SHA256", secret, payload)
+    end
+    private_class_method :mac
+
+    # An empty string is a valid HMAC key, so a secret read from an env var that
+    # is set but blank — or only whitespace, or a newline from a mounted file —
+    # would make every signature forgeable. Refuse it loudly.
+    def self.usable!(secrets)
+      usable = Array(secrets).map(&:to_s).reject { |secret| secret.strip.empty? }
+      raise ConfigurationError, "no signing secret — pass a non-empty secret" if usable.empty?
+
+      usable
+    end
+    private_class_method :usable!
+
+    def self.secure_compare(expected, candidate)
+      SecureCompare.call(expected, candidate)
+    end
+    private_class_method :secure_compare
+  end
+end

data/lib/patchwork/signing_key.rb

@@ -0,0 +1,69 @@
+require "base64"
+require "openssl"
+require "jwt"
+
+module Patchwork
+  module SigningKey
+    ALG = "RS256".freeze
+    MIN_BITS = 2048
+
+    def self.configured?
+      Patchwork.config.signing_key?
+    end
+
+    def self.private_key
+      @private_key ||= begin
+        material = Patchwork.config.signing_key
+        raise ConfigurationError, "signing_key is not set" if material.to_s.empty?
+
+        key = parse(decode(material))
+        raise ConfigurationError, "signing_key must be an RSA private key, not a public key" unless key.private?
+        raise ConfigurationError, "signing_key must be at least #{MIN_BITS} bits" if key.n.num_bits < MIN_BITS
+
+        key
+      end
+    end
+
+    def self.public_key
+      private_key.public_key
+    end
+
+    def self.kid
+      configured = Patchwork.config.signing_kid.to_s
+      return configured unless configured.empty?
+
+      @thumbprint ||= JWT::JWK.new(public_key, kid_generator: JWT::JWK::Thumbprint).kid
+    end
+
+    def self.public_jwk
+      JWT::JWK.new(public_key, kid: kid).export
+    end
+
+    def self.jwks
+      { keys: [ public_jwk ] }
+    end
+
+    def self.reset!
+      @private_key = nil
+      @thumbprint = nil
+    end
+
+    def self.parse(pem)
+      # An explicit empty passphrase: an encrypted key fails here instead of
+      # blocking on an interactive prompt at boot.
+      OpenSSL::PKey::RSA.new(pem, "")
+    rescue OpenSSL::PKey::PKeyError
+      raise ConfigurationError, "signing_key is not an RSA private key (an EC or encrypted key is not supported)"
+    end
+    private_class_method :parse
+
+    def self.decode(material)
+      return material if material.include?("-----BEGIN")
+
+      Base64.strict_decode64(material)
+    rescue ArgumentError
+      raise ConfigurationError, "signing_key is neither PEM nor base64-encoded PEM"
+    end
+    private_class_method :decode
+  end
+end