ravenrelay 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9ed3b9550d082bbb323c241ce1e32cd48ee55b6e080f5b689b58aedf0297fe2c
+  data.tar.gz: d147f655e47e876dafdb462abee31ea34e7558a4a3a1388edb7c2826e68724b9
+SHA512:
+  metadata.gz: afa9effda2080d0c7b9dabb211424161e3b03f542bf068d5e1cc798ab2116083d9a08a6a35dd02bb7898520d043df14976c8d4d5b45fcf5327cdfc2373924666
+  data.tar.gz: 07bc0a0412f6e5dcd98e28f3719bf359774278b1017ea68a3a99e452cc6046b53850a04c88fb659a3bc5276352dd15d8e7736345c9aec306d09ce196fc613d58

data/README.md

@@ -0,0 +1,29 @@
+# RavenRelay Ruby SDK
+
+Ruby 3.1+. Source is implemented; RubyGems publication is separate. Build and install locally:
+
+```sh
+cd sdks/ruby
+ gem build ravenrelay.gemspec
+ gem install ./ravenrelay-0.1.0.gem
+```
+
+```ruby
+require 'ravenrelay'
+client = RavenRelay::Client.new(api_key: ENV.fetch('RAVENRELAY_API_KEY'), base_url: ENV.fetch('RAVENRELAY_API_URL'))
+result = client.emails.send({from: 'hello@example.com', to: 'user@example.com', subject: 'Welcome', text: 'Hello'}, idempotency_key: 'welcome-123')
+email = client.emails.get(result['id'])
+page = client.emails.list(status: 'sent', recipient: 'user@example.com')
+```
+
+Saved templates use `template`/`variables` instead of subject/body. Responses are hashes with string keys, preserving API fields. `RavenRelay::APIError` exposes `status`/`code`. `TransportError` means acceptance may be uncertain; `ProtocolError` indicates an invalid successful response. No automatic retries; retry only with the same idempotency key and body. The ten-second default timeout covers the whole request. Redirects are refused. Default origin: `https://api.ravenrelay.com`; supply your deployed origin explicitly. Keep API keys server-side.
+
+`RavenRelay.verify_webhook_signature(secret:, timestamp:, signature:, body:)` verifies original bytes with HMAC-SHA256, constant-time comparison, and a five-minute tolerance. Verify before parsing JSON and durably deduplicate event IDs. Optional `now` is Unix seconds for testing.
+
+```sh
+python3 sdks/testing/contract_server.py ruby sdks/ruby/test/contract.rb
+```
+
+Publish with `gem push ravenrelay-0.1.0.gem` after account/name and license review. No reuse license has been granted.
+
+Security: remote origins must use HTTPS. Plain HTTP is accepted only for literal `localhost`, `127.0.0.1` and IPv6 loopback hosts. Credentials/query/fragment, whitespace and backslashes are rejected in API origins. Authentication/idempotency headers must be printable ASCII; `.` and `..` email IDs are rejected. Response bodies are limited to 16 MiB, valid UTF-8 and 64 JSON nesting levels. TLS certificate verification stays enabled. Use vendor-supported runtimes with current security patches; the compatibility floor does not promise that an old runtime is secure. See `docs/sdk-security-review.md` for dependency and release controls.

data/lib/ravenrelay.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+require 'net/http'
+require 'json'
+require 'openssl'
+require 'uri'
+require 'timeout'
+
+module RavenRelay
+  VERSION = '0.1.0'
+  class APIError < StandardError
+    attr_reader :status, :code
+    def initialize(status, code, message)
+      super(message)
+      @status, @code = status, code
+    end
+  end
+  class TransportError < StandardError; end
+  class ProtocolError < StandardError; end
+
+  class Client
+    attr_reader :emails
+    def initialize(api_key:, base_url: 'https://api.ravenrelay.com', timeout: 10)
+      validate_header(api_key)
+      raise ArgumentError, 'Invalid base_url' if base_url.match?(/[\\\x00-\x20\x7f]/)
+      url = URI.parse(base_url)
+      unless %w[http https].include?(url.scheme) && url.host && !url.userinfo && !url.query && !url.fragment
+        raise ArgumentError, 'base_url must be an absolute HTTP(S) URL without credentials, query or fragment'
+      end
+      raise ArgumentError, 'Use HTTPS; HTTP is only allowed on literal loopback hosts' if url.scheme == 'http' && !%w[localhost 127.0.0.1 ::1].include?(url.hostname)
+      raise ArgumentError, 'timeout must be finite and positive' unless timeout.is_a?(Numeric) && timeout.finite? && timeout.positive?
+      @api_key, @base_url, @timeout = api_key, base_url.sub(%r{/+\z}, ''), timeout
+      @emails = Emails.new(self)
+    end
+
+    # Internal transport. No retries or redirect following, even on connection failures.
+    def request(method, path, body = nil, idempotency_key = nil)
+      url = URI.parse(@base_url + path)
+      request = (method == 'POST' ? Net::HTTP::Post : Net::HTTP::Get).new(url)
+      request['Authorization'] = "Bearer #{@api_key}"
+      request['Content-Type'] = 'application/json'
+      request['Accept-Encoding'] = 'identity'
+      unless idempotency_key.nil?
+        validate_header(idempotency_key)
+        request['Idempotency-Key'] = idempotency_key
+      end
+      request.body = JSON.generate(body) unless body.nil?
+      http = Net::HTTP.new(url.host, url.port, nil)
+      http.use_ssl = url.scheme == 'https'
+      http.open_timeout = http.read_timeout = http.write_timeout = @timeout
+      http.max_retries = 0
+      raw = +''.b
+      status = nil
+      expected_length = nil
+      begin
+        Timeout.timeout(@timeout) do
+          http.start do |connection|
+            connection.request(request) do |response|
+              status = response.code.to_i
+              length = response['Content-Length']
+              expected_length = length.to_i if length&.match?(/\A[0-9]+\z/)
+              response.read_body do |chunk|
+                raise ProtocolError, 'RavenRelay response exceeds 16 MiB' if raw.bytesize + chunk.bytesize > 16 * 1024 * 1024
+                raw << chunk
+              end
+            end
+          end
+        end
+      rescue Timeout::Error, IOError, SystemCallError, SocketError, OpenSSL::SSL::SSLError, Net::HTTPBadResponse, EOFError => error
+        raise TransportError, 'RavenRelay network request failed; acceptance may be uncertain', cause: error
+      end
+      raise TransportError, 'RavenRelay response ended before the declared body length' if expected_length && raw.bytesize < expected_length
+      raw.force_encoding(Encoding::UTF_8)
+      raise ProtocolError, 'Invalid UTF-8 response' unless raw.valid_encoding?
+      begin
+        parsed = JSON.parse(raw, create_additions: false, max_nesting: 64)
+      rescue JSON::ParserError, EncodingError
+        parsed = nil
+      end
+      unless (200...300).cover?(status)
+        error = parsed.is_a?(Hash) && parsed['error'].is_a?(Hash) ? parsed['error'] : {}
+        code = error['code'].is_a?(String) ? error['code'] : 'unknown_error'
+        message = error['message'].is_a?(String) ? error['message'] : 'Request failed'
+        raise APIError.new(status, code, message)
+      end
+      raise ProtocolError, 'RavenRelay response must be a JSON object' unless parsed.is_a?(Hash)
+      parsed
+    end
+
+    private
+    def validate_header(value)
+      raise ArgumentError, 'Header values must be nonempty without control characters' unless value.is_a?(String) && !value.empty? && !value.match?(/[^\x20-\x7e]/)
+    end
+  end
+
+  class Emails
+    def initialize(client)
+      @client = client
+    end
+    def send(email, idempotency_key: nil)
+      raise ArgumentError, 'email must be a Hash' unless email.is_a?(Hash)
+      @client.request('POST', '/v1/emails', email, idempotency_key)
+    end
+    def get(id)
+      raise ArgumentError, 'Email ID must be nonempty' unless id.is_a?(String) && !id.empty? && !%w[. ..].include?(id)
+      encoded = URI.encode_www_form_component(id).gsub('+', '%20')
+      @client.request('GET', '/v1/emails/' + encoded)
+    end
+    def list(status: nil, recipient: nil, cursor: nil)
+      query = URI.encode_www_form({ status: status, recipient: recipient, cursor: cursor }.reject { |_, v| v.nil? })
+      @client.request('GET', '/v1/emails' + (query.empty? ? '' : '?' + query))
+    end
+  end
+
+  # Use original request bytes before parsing JSON and durably deduplicate event IDs.
+  def self.verify_webhook_signature(secret:, timestamp:, signature:, body:, now: Time.now.to_f)
+    return false unless secret.is_a?(String) && !secret.empty? && timestamp.is_a?(String) && timestamp.match?(/\A[0-9]{1,12}\z/)
+    return false unless signature.is_a?(String) && signature.match?(/\Av1=[a-f0-9]{64}\z/)
+    return false unless now.is_a?(Numeric) && now.finite? && (now - timestamp.to_i).abs <= 300
+    expected = OpenSSL::HMAC.hexdigest('SHA256', secret, timestamp.b + '.'.b + body.b)
+    OpenSSL.fixed_length_secure_compare(expected, signature[3..])
+  end
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: ravenrelay
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- RavenRelay
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: net-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.19.9
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.19.9
+- !ruby/object:Gem::Dependency
+  name: openssl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 4.0.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 4.0.2
+- !ruby/object:Gem::Dependency
+  name: uri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.1.1
+description: Send and read RavenRelay email, use saved templates, and verify signed
+  webhooks.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/ravenrelay.rb
+homepage: https://ravenrelay.joshlab.site
+licenses:
+- Nonstandard
+metadata:
+  allowed_push_host: https://rubygems.org
+  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: Server-side Ruby SDK for the RavenRelay email API
+test_files: []