signingflow 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 69511c1fa920936b6084ce36ce00041549b9c5355429684271af523e2842274c
+  data.tar.gz: 28b0122a3cbe4c369a23d89f8359e4ec23295497e58f70d978f510ea70480463
+SHA512:
+  metadata.gz: b899b5d35246dc3bd64830749f79528b81c3c132834f3401c3b85320d33b253233f81de30ac160f70eb641dbe3ea7aeaf31d916dc945ca8fbc3dd5a75acb0c54
+  data.tar.gz: 5d263d39d08b7f7933bb41a4d8cf4ea8ce21b9a4eab08bc00c1f5afd0384a86a3c3aa7b9c807c642ea0fea25d7443b49b9b2ac34d521951c4087e65c266fcd32

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0
+
+First Ruby SDK for sending a document, reading envelope status, downloading a completed file, and verifying webhook signatures.
+
+Install from GitHub with `gem "signingflow", github: "Signingflow/signingflow-ruby"` until the gem is on RubyGems.
+
+A query value that contains the API key is rejected, including when that key is percent-encoded. The API host is HTTPS `api.signingflow.com` unless `allow_custom_base_url` is set. A file path is read only from `upload_root`. A hard link is rejected, and the file is not opened when the runtime cannot refuse a symlink. `construct_event` returns `payload` and `body_sha256` of the raw body. A 409 is an idempotency error only when the body says the key was already used. A timed-out send is returned only when `sent_time` falls in the two minutes after the call started. The client sends `Accept-Encoding: identity` and stops reading an API response at 8 MB.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Signingflow
+
+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,96 @@
+# signingflow
+
+[![CI](https://github.com/Signingflow/signingflow-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/Signingflow/signingflow-ruby/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Signingflow/signingflow-ruby/badges/coverage.json)](https://github.com/Signingflow/signingflow-ruby/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Ruby SDK for the Signingflow calls used to send a document, read envelope status, and receive webhooks.
+
+The gem talks to `https://api.signingflow.com`. Keep the API key on your server. Ruby 3.2 or newer is required.
+
+```ruby
+gem "signingflow", github: "Signingflow/signingflow-ruby"
+```
+
+The gem name is `signingflow`. Install it from [GitHub](https://github.com/Signingflow/signingflow-ruby) until it is published on RubyGems.
+
+```ruby
+require "signingflow"
+
+client = Signingflow::Client.new(
+  ENV.fetch("SIGNINGFLOW_API_KEY"),
+  workspace_id: ENV.fetch("SIGNINGFLOW_WORKSPACE_ID"),
+  env: "sandbox",
+)
+
+envelope = client.envelopes.send_document(
+  title: "NDA",
+  file: pdf_bytes,
+  filename: "contract.pdf",
+  recipients: [{ name: "Ada Lovelace", email: "ada@example.com" }],
+  message: "Please sign",
+)
+```
+
+`file` is the raw bytes. A disk path is `path:`, and it is read only from `upload_root`. That directory must be one this process writes. The open refuses a symlink, a hard link, and a path that leaves the directory. If this Ruby cannot open a path without following a symlink, the read is refused.
+
+The client sends `Accept-Encoding: identity` and stops reading once an API response passes 8 MB.
+
+`env` is `sandbox` or `live`. The client always sends `X-Request-Env`. A missing environment header is treated as live by the API.
+
+`base_url` must be `https`. The host is `api.signingflow.com` unless `allow_custom_base_url` is set. A username or password on the URL is rejected.
+
+## Send and read
+
+`envelopes.prepare_draft` stores one PDF and creates a draft. It does not email anyone.
+
+`envelopes.send_document` stores the PDF, creates the draft, adds the recipients to the first document, and sends. `envelopes.send_from_template` starts from `templates/{id}`.
+
+If update or send fails, the error includes `envelope_name` for the draft that was saved. After a timeout, the client returns the envelope only when `sent_time` is within two minutes after the call started and not more than a minute ahead of this clock. An older or far-future timestamp is an error.
+
+`envelopes.list(directory: "needAction")` reads pages of 10. `page_size` can be from 1 to 1000.
+
+`envelopes.download_completed(name)` reads the envelope first. It requests the download URL only when the state is `COMPLETED`. The download call returns `uri`, `download_time`, and `etag`. This client does not GET `uri`. Treat that URL as untrusted until your application checks the host. Do not send the API key to it.
+
+`envelopes.remind(name)` notifies people who can still sign. The call is not idempotent.
+
+## Idempotency
+
+Creates and sends send a UUID `idempotencyKey` in the JSON body. The same key is stored for the whole environment. A repeat returns HTTP 409 and does not return the original resource. The SDK raises `Signingflow::IdempotencyError` with `resource_name` when the error includes one. It does not treat that response as success.
+
+Pass the same `idempotency_key` only to retry one request after a timeout. `update` and `remind` are not retried automatically.
+
+## Webhooks
+
+```ruby
+destination = client.webhook_urls.create(
+  display_name: "Envelope events",
+  http_request_uri: "https://example.com/webhooks/signingflow",
+  events: ["DOC_ENVELOPE_COMPLETED"],
+)
+
+secret = Signingflow.signing_secret_of(destination)
+```
+
+Store that secret from the create response. A later `retrieve` does not include it. Do not set `http_config`. `auth: "NONE"` is rejected.
+
+```ruby
+event = Signingflow.construct_event(raw_body, signature_header, secret, previous_secret: previous, previous_signature: previous_signature)
+event.payload
+event.body_sha256
+```
+
+The signature is lowercase hex HMAC-SHA256 of the raw body. There is no timestamp. Compare `X-Signingflow-Signature` or `X-Webhook-Signature`. During a grace window, also pass the previous header and secret. Parse JSON only after the MAC matches. `body_sha256` is the SHA-256 of those raw bytes. Store it and reject a delivery you have already seen.
+
+## Errors
+
+| Class | When |
+| --- | --- |
+| `Signingflow::AuthenticationError` | HTTP 401 |
+| `Signingflow::PermissionError` | HTTP 403 |
+| `Signingflow::IdempotencyError` | HTTP 409 whose body mentions idempotency |
+| `Signingflow::RateLimitError` | HTTP 429 |
+| `Signingflow::InvalidRequestError` | Other HTTP 4xx |
+| `Signingflow::APIError` | HTTP 5xx, or a response larger than 8 MB |
+| `Signingflow::ConnectionError` | The API could not be reached or timed out |
+| `Signingflow::SignatureVerificationError` | The webhook MAC does not match |

data/lib/signingflow/allowlist.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Signingflow
+  ALLOWLIST_PATH = File.expand_path("../../resources/allowlist.json", __dir__)
+  OPERATIONS = JSON.parse(File.read(ALLOWLIST_PATH)).fetch("operations").freeze
+  OPERATIONS_BY_ID = OPERATIONS.to_h { |operation| [operation.fetch("operationId"), operation] }.freeze
+
+  def self.operation(operation_id)
+    OPERATIONS_BY_ID.fetch(operation_id)
+  end
+end

data/lib/signingflow/client.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Signingflow
+  class Client
+    attr_reader :files, :envelopes, :templates, :webhook_urls, :webhook_deliveries
+
+    def initialize(api_key, workspace_id:, env:, **options)
+      config = ConfigResolver.resolve(api_key, workspace_id: workspace_id, env: env, **options)
+      requestor = Requestor.new(config)
+      @files = Resources::Files.new(requestor, config)
+      @templates = Resources::Templates.new(requestor)
+      @envelopes = Resources::Envelopes.new(requestor, @files, @templates)
+      @webhook_urls = Resources::WebhookUrls.new(requestor)
+      @webhook_deliveries = Resources::WebhookDeliveries.new(requestor)
+    end
+  end
+end

data/lib/signingflow/config.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Signingflow
+  Config = Data.define(
+    :api_key, :workspace_id, :env, :base_url, :timeout, :max_network_retries,
+    :channel, :funnel, :upload_hosts, :upload_root, :source
+  )
+
+  module ConfigResolver
+    DEFAULT_UPLOAD_HOSTS = ["storage.googleapis.com"].freeze
+    OFFICIAL_HOST = "api.signingflow.com"
+
+    module_function
+
+    def resolve(api_key, workspace_id:, env:, base_url: nil, allow_custom_base_url: false, timeout: 30_000,
+                max_network_retries: 2, channel: nil, funnel: nil, upload_hosts: nil, upload_root: nil)
+      key = api_key.to_s.strip
+      raise Error, "API key is required." if key.empty?
+      workspace = workspace_id.to_s.strip
+      raise Error, "workspace_id is required." if workspace.empty?
+
+      raw_base = base_url.to_s.strip
+      raw_base = "https://api.signingflow.com" if raw_base.empty?
+      raw_base = raw_base.sub(%r{/+\z}, "")
+      begin
+        parsed = URI.parse(raw_base)
+      rescue URI::InvalidURIError
+        raise Error, "base_url must be an absolute URL."
+      end
+      raise Error, "base_url must be an absolute URL." if parsed.host.nil? || parsed.scheme.nil?
+      raise Error, "base_url must be https." unless parsed.scheme == "https"
+      raise Error, "base_url must not include a username or password." if parsed.user || parsed.password
+      if parsed.host != OFFICIAL_HOST && !allow_custom_base_url
+        raise Error, "base_url host must be api.signingflow.com, or set allow_custom_base_url."
+      end
+      unless timeout.is_a?(Numeric) && timeout.positive?
+        raise Error, "timeout must be a positive number of milliseconds."
+      end
+      unless max_network_retries.is_a?(Integer) && max_network_retries >= 0
+        raise Error, "max_network_retries must be a whole number of zero or more."
+      end
+
+      Config.new(
+        api_key: key,
+        workspace_id: workspace,
+        env: normalize_env(env),
+        base_url: raw_base,
+        timeout: timeout,
+        max_network_retries: max_network_retries,
+        channel: blank(channel),
+        funnel: blank(funnel),
+        upload_hosts: upload_hosts_of(upload_hosts),
+        upload_root: blank(upload_root),
+        source: SOURCE
+      )
+    end
+
+    def normalize_env(env)
+      value = env.to_s
+      return "SANDBOX" if value == "sandbox" || value == "SANDBOX"
+      return "LIVE" if value == "live" || value == "LIVE"
+
+      raise Error, "env must be sandbox or live."
+    end
+
+    def upload_hosts_of(hosts)
+      list = (hosts || DEFAULT_UPLOAD_HOSTS).map { |host| host.to_s.strip.downcase }.reject(&:empty?)
+      list.each do |host|
+        dots = host.count(".")
+        if dots < 2 || host.start_with?(".") || host.end_with?(".") || host.include?("..")
+          raise Error, "Each upload_hosts entry must be a specific host, not a public suffix."
+        end
+      end
+      list.freeze
+    end
+
+    def blank(value)
+      trimmed = value.to_s.strip
+      trimmed.empty? ? nil : trimmed
+    end
+  end
+end

data/lib/signingflow/errors.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Signingflow
+  class Error < StandardError
+    attr_reader :status_code, :grpc_code, :trace_code, :request_id, :idempotency_key,
+                :capability, :resource_name, :retry_after, :field_violations
+    attr_accessor :envelope_name
+
+    def initialize(message = nil, status_code: nil, grpc_code: nil, trace_code: nil, request_id: nil,
+                   idempotency_key: nil, capability: nil, resource_name: nil, envelope_name: nil,
+                   retry_after: nil, field_violations: nil)
+      super(message)
+      @status_code = status_code
+      @grpc_code = grpc_code
+      @trace_code = trace_code
+      @request_id = request_id
+      @idempotency_key = idempotency_key
+      @capability = capability
+      @resource_name = resource_name
+      @envelope_name = envelope_name
+      @retry_after = retry_after
+      @field_violations = field_violations
+    end
+
+    def self.attach_envelope(error, envelope_name)
+      error.envelope_name = envelope_name if error.is_a?(Error)
+      raise error
+    end
+  end
+
+  class AuthenticationError < Error; end
+  class PermissionError < Error; end
+  class IdempotencyError < Error; end
+  class RateLimitError < Error; end
+  class InvalidRequestError < Error; end
+  class APIError < Error; end
+  class ConnectionError < Error; end
+  class SignatureVerificationError < Error; end
+end

data/lib/signingflow/jail.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Signingflow
+  module Jail
+    module_function
+
+    def read(root, requested, max_bytes)
+      base = File.realpath(root)
+      resolved = File.expand_path(requested.to_s, base)
+      parent_real = File.realpath(File.dirname(resolved))
+      raise Error, "outside root" if escapes?(base, parent_real)
+
+      leaf = File.basename(resolved)
+      raise Error, "outside root" if leaf.empty? || leaf == "." || leaf == ".."
+
+      path = File.join(parent_real, leaf)
+      raise Error, "outside root" if escapes?(base, path) || File.expand_path(path) == File.expand_path(base)
+      raise Error, "nofollow" unless Jail.nofollow_available?
+
+      io = IO.new(IO.sysopen(path, File::RDONLY | File::NOFOLLOW))
+      begin
+        info = io.stat
+        raise Error, "not a file" unless info.file?
+        raise Error, "hard link" if info.nlink > 1
+        raise Error, "too large" if info.size > max_bytes
+
+        io.read(info.size) || +""
+      ensure
+        io.close
+      end
+    end
+
+    def self.nofollow_available?
+      defined?(File::NOFOLLOW) == "constant"
+    end
+
+    def escapes?(base, target)
+      relative = Pathname(target).relative_path_from(Pathname(base)).to_s
+      return true if relative.empty?
+
+      relative.split(/[\\\/]/).include?("..")
+    end
+  end
+end

data/lib/signingflow/object.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Signingflow
+  class ResourceObject
+    def initialize(data)
+      @data = data.is_a?(Hash) ? data : {}
+    end
+
+    def [](key)
+      lookup(key.to_s)
+    end
+
+    def []=(key, value)
+      @data[key.to_s] = value
+    end
+
+    def to_h
+      @data
+    end
+
+    def key?(name)
+      !lookup(name.to_s).nil? || @data.key?(name.to_s) || @data.key?(camel(name.to_s))
+    end
+
+    def method_missing(name, *args)
+      return super if !args.empty? || name.to_s.end_with?("=")
+
+      lookup(name.to_s)
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      key?(name) || super
+    end
+
+    private
+
+    def lookup(key)
+      return @data[key] if @data.key?(key)
+
+      camel_key = camel(key)
+      return @data[camel_key] if @data.key?(camel_key)
+
+      nil
+    end
+
+    def camel(key)
+      key.gsub(/_([a-z])/) { Regexp.last_match(1).upcase }
+    end
+  end
+
+  class List
+    MAX_PAGES = 100
+
+    attr_reader :data, :next_page_token
+
+    def initialize(data:, next_page_token:, loader:)
+      @data = data
+      @next_page_token = next_page_token
+      @loader = loader
+    end
+
+    def auto_paging_each
+      page_data = @data
+      token = @next_page_token
+      seen = {}
+      pages = 0
+      loop do
+        page_data.each do |item|
+          keep = yield item
+          return if keep == false
+        end
+        return if token.nil? || token.empty? || seen[token]
+
+        pages += 1
+        raise InvalidRequestError, "Too many pages." if pages > MAX_PAGES
+
+        seen[token] = true
+        page = @loader.call(token)
+        page_data = page.data
+        token = page.next_page_token
+      end
+    end
+
+    def auto_paging_to_array(limit: nil)
+      items = []
+      auto_paging_each do |item|
+        break false if !limit.nil? && items.length >= limit
+
+        items << item
+        limit.nil? || items.length < limit
+      end
+      items
+    end
+  end
+end

data/lib/signingflow/path.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "uri"
+
+module Signingflow
+  module Path
+    SEGMENT = /\A[A-Za-z0-9_-]+\z/
+    MAX_DELAY_MS = 60_000
+
+    module_function
+
+    def fill(template, params)
+      template.gsub(/\{([^}]+)\}/) do
+        token = Regexp.last_match(1)
+        name = token.split("=").first.to_s
+        short = name.split(".").last.to_s
+        value = params[name].to_s
+        value = params[short].to_s if value.empty?
+        value = params["name"].to_s if value.empty? && (short == "name" || short.start_with?("name_"))
+        raise InvalidRequestError, "missing path param #{short}" if value.empty?
+
+        segments = value.split("/")
+        if segments.empty? || segments.any? { |segment| !SEGMENT.match?(segment) }
+          raise InvalidRequestError, "invalid path param #{short}"
+        end
+        segments.map { |segment| CGI.escape(segment).gsub("+", "%20") }.join("/")
+      end
+    end
+
+    def resolve(base_url, path, query = nil)
+      base = base_url.end_with?("/") ? base_url : "#{base_url}/"
+      uri = URI.join(base, path)
+      origin = URI(base)
+      raise InvalidRequestError, "invalid path" if uri.scheme != origin.scheme || uri.host != origin.host
+
+      parts = []
+      (query || {}).each do |key, value|
+        next if value.nil? || value.to_s.empty?
+
+        parts << "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"
+      end
+      uri.query = parts.join("&") unless parts.empty?
+      uri
+    end
+
+    # A raw substring misses a key once CGI.escape percent-encodes it.
+    def query_contains_secret(raw_query, secret)
+      query = raw_query.to_s.sub(/\A\?/, "")
+      key = secret.to_s
+      return false if key.empty? || query.empty?
+      escaped = CGI.escape(key)
+      return true if query.include?(key) || query.include?(escaped)
+      return true if broken_percent?(query)
+
+      URI.decode_www_form(query).any? { |_name, value| value.include?(key) }
+    rescue ArgumentError
+      true
+    end
+
+    def broken_percent?(query)
+      index = 0
+      while index < query.length
+        unless query[index] == "%"
+          index += 1
+          next
+        end
+        digits = query[index + 1, 2].to_s
+        return true if digits.length < 2 || digits.match?(/[^0-9a-f]/i)
+
+        index += 3
+      end
+      false
+    end
+
+    def allowed_upload_url(raw, hosts)
+      begin
+        uri = URI.parse(raw)
+      rescue URI::InvalidURIError
+        raise Error, "upload url rejected"
+      end
+      raise Error, "upload url rejected" if uri.host.nil?
+      raise Error, "upload url must be https" unless uri.scheme == "https"
+      raise Error, "upload url rejected" if uri.user || uri.password
+
+      host = uri.host.downcase
+      allowed = hosts.any? { |item| host == item || host.end_with?(".#{item}") }
+      raise Error, "upload host rejected" unless allowed
+
+      uri
+    end
+
+    def retry_delay_ms(retry_after, reset_after, now_ms = (Time.now.to_r * 1000).round)
+      when_ms = parse_time(retry_after) || parse_time(reset_after)
+      return 0 if when_ms.nil?
+
+      [[when_ms - now_ms, 0].max, MAX_DELAY_MS].min
+    end
+
+    def parse_time(value)
+      text = value.to_s.strip
+      return nil if text.empty?
+
+      parsed = Time.iso8601(text)
+      (parsed.to_r * 1000).round
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/signingflow/redact.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Signingflow
+  module Redact
+    SECRET_KEY = /df_sk_[A-Za-z0-9_-]+/
+    BEARER = /Bearer\s+\S+/i
+    SIGNED_QUERY = /([?&](?:X-Goog-Signature|Signature|sig|token)=)[^&\s"]+/i
+
+    module_function
+
+    def redact(value)
+      value.to_s
+           .gsub(SECRET_KEY, "df_sk_redacted")
+           .gsub(BEARER, "Bearer [redacted]")
+           .gsub(SIGNED_QUERY, "\\1[redacted]")
+    end
+
+    def message(value, limit = 500)
+      cleaned = redact(value)
+      cleaned.length > limit ? "#{cleaned[0, limit]}…" : cleaned
+    end
+
+    def violations(list)
+      return nil if list.nil?
+
+      list.map do |item|
+        { "field" => message(item["field"]), "description" => message(item["description"]) }
+      end
+    end
+  end
+end