coffrify 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7045ff71ac4b8f5fd52ef0bff58665f4b68041d352c0cff4c02d7309f3e7fe3b
+  data.tar.gz: fd2dd9783511a0c72928ff9c1ec6ee9885c500f8ce698f62b289138ac174add8
+SHA512:
+  metadata.gz: 5b12face4179600ad371f25e4590e964ef7de5d9d1704931f39db2452341aa35e23a696d2af1501625340b084f073aea6d4397dec73effd2e5a049d1ae364a30
+  data.tar.gz: c196306ce5ed50b891afb73c87b6486e2e601450af04da2ef395b3b6a5e1884198bfe4bcb6040bfae8ec19ca8f2ffcd427ad53cea5209d2fd4316748f9933d80

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Coffrify
+
+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,81 @@
+# Coffrify — Ruby SDK
+
+Official Ruby SDK for [Coffrify](https://coffrify.com), encrypted file transfer infrastructure.
+
+Pure stdlib (`net/http`, `openssl`, `json`). **Zero runtime dependencies.** Requires Ruby 2.7+.
+
+## Install
+
+```bash
+gem install coffrify
+# or in a Gemfile:
+#   gem "coffrify", "~> 0.1"
+```
+
+## Quickstart
+
+```ruby
+require "coffrify"
+
+coffrify = Coffrify::Client.new(api_key: ENV.fetch("COFFRIFY_API_KEY"))
+
+# Create a transfer
+transfer = coffrify.transfers.create(
+  [{ name: "rapport.pdf", size: 1_240_000, mime_type: "application/pdf" }],
+  expires_in_hours: 72,
+  max_downloads: 10,
+  password: "s3cret!",
+)
+puts transfer["share_url"]
+
+# List
+puts coffrify.transfers.list(limit: 5)
+
+# Webhooks
+hook = coffrify.webhooks.create(
+  name: "Production hook",
+  url: "https://app.example.com/hooks/coffrify",
+  events: ["transfer.created", "transfer.downloaded", "transfer.scan_infected"],
+)
+puts "Save this secret: #{hook['secret']}"
+
+# Catalog of every supported event
+coffrify.webhooks.events["data"].each { |e| puts "#{e['type']} (#{e['family']})" }
+```
+
+## Webhook signature verification
+
+```ruby
+require "sinatra"
+require "coffrify"
+
+post "/hooks/coffrify" do
+  raw = request.body.read
+  sig = request.env["HTTP_X_COFFRIFY_SIGNATURE"]
+  v   = Coffrify::Webhook.verify(raw, sig, ENV.fetch("COFFRIFY_WEBHOOK_SECRET"))
+  halt 400, v[:reason] unless v[:valid]
+
+  case v[:event]["type"]
+  when "transfer.downloaded" then handle_download(v[:event])
+  when "transfer.scan_infected" then quarantine!(v[:event])
+  end
+  status 200
+end
+```
+
+The header has the form `t=<timestamp>,v1=<hmac_hex>`. Verification:
+
+1. Confirms the timestamp is within ±5 minutes (replay protection).
+2. Recomputes `HMAC-SHA256(secret, "<timestamp>.<raw_body>")` in constant time.
+
+## API key rotation
+
+```ruby
+result = coffrify.api_keys.rotate("ak_…", grace_days: 7)
+puts "New key (save now): #{result['new_key']}"
+puts "Old key auto-revokes at: #{result['grace_until']}"
+```
+
+## License
+
+MIT.

data/lib/coffrify/client.rb

@@ -0,0 +1,154 @@
+module Coffrify
+  class Client
+    DEFAULT_API_URL = "https://api.coffrify.com".freeze
+    DEFAULT_TIMEOUT = 30
+
+    attr_reader :api_key, :api_url, :workspace_id, :timeout
+
+    def initialize(api_key:, api_url: DEFAULT_API_URL, workspace_id: nil, timeout: DEFAULT_TIMEOUT)
+      raise ArgumentError, "api_key must start with 'cfy_'" unless api_key.is_a?(String) && api_key.start_with?("cfy_")
+      @api_key = api_key
+      @api_url = api_url
+      @workspace_id = workspace_id
+      @timeout = timeout
+    end
+
+    # ── Resources ────────────────────────────────────────────────────────
+    def transfers; @transfers ||= Transfers.new(self); end
+    def webhooks;  @webhooks  ||= Webhooks.new(self);  end
+    def api_keys;  @api_keys  ||= ApiKeys.new(self);   end
+    def audit;     @audit     ||= Audit.new(self);     end
+
+    # ── HTTP plumbing ────────────────────────────────────────────────────
+    def request(method, path, body: nil, query: nil, headers: {})
+      uri = URI.parse("#{api_url}/v1#{path}")
+      uri.query = URI.encode_www_form(query) if query && !query.empty?
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.read_timeout = timeout
+      http.open_timeout = timeout
+
+      req = build_request(method, uri, body, headers)
+      attempts = 0
+      begin
+        attempts += 1
+        resp = http.request(req)
+        handle_response(resp)
+      rescue Net::OpenTimeout, Net::ReadTimeout, IOError, Errno::ECONNRESET => e
+        if attempts < 3
+          sleep(0.5 * (2 ** (attempts - 1)))
+          retry
+        end
+        raise Error, "Network error after #{attempts} attempts: #{e.message}"
+      end
+    end
+
+    private
+
+    def build_request(method, uri, body, extra_headers)
+      cls = case method.to_s.upcase
+            when "GET" then Net::HTTP::Get
+            when "POST" then Net::HTTP::Post
+            when "PATCH" then Net::HTTP::Patch
+            when "DELETE" then Net::HTTP::Delete
+            else raise ArgumentError, "Unsupported method: #{method}"
+            end
+      req = cls.new(uri.request_uri)
+      req["Authorization"] = "Bearer #{api_key}"
+      req["User-Agent"]    = "coffrify-ruby/#{VERSION}"
+      req["Content-Type"]  = "application/json"
+      req["Accept"]        = "application/json"
+      req["X-Coffrify-Workspace-Id"] = workspace_id if workspace_id
+      # Idempotency for non-GET
+      req["Idempotency-Key"] = "rb_#{SecureRandom.uuid}" unless method.to_s.upcase == "GET"
+      extra_headers.each { |k, v| req[k] = v }
+      req.body = body.to_json if body
+      req
+    end
+
+    def handle_response(resp)
+      status = resp.code.to_i
+      body = resp.body && !resp.body.empty? ? (JSON.parse(resp.body) rescue resp.body) : nil
+      return body if status >= 200 && status < 300
+
+      message = body.is_a?(Hash) ? (body["message"] || body["error"] || resp.message) : resp.message
+      code    = body.is_a?(Hash) ? body["code"] : nil
+      klass   = case status
+                when 401, 403 then AuthError
+                when 404      then NotFoundError
+                when 422, 400 then ValidationError
+                when 429      then RateLimitError
+                else ApiError
+                end
+      raise klass.new(status: status, message: message.to_s, code: code, details: body)
+    end
+  end
+
+  # ── Resources ──────────────────────────────────────────────────────────
+  class Transfers
+    def initialize(client); @c = client; end
+
+    def list(limit: 20, offset: 0, status: nil)
+      q = { limit: limit, offset: offset }
+      q[:status] = status if status
+      @c.request(:get, "/transfers", query: q)
+    end
+
+    def get(id);    @c.request(:get,    "/transfers/#{escape(id)}"); end
+    def delete(id); @c.request(:delete, "/transfers/#{escape(id)}"); end
+
+    def create(files, **options)
+      @c.request(:post, "/transfers", body: { files: files, **options })
+    end
+
+    private
+    def escape(s); URI.encode_www_form_component(s); end
+  end
+
+  class Webhooks
+    def initialize(client); @c = client; end
+
+    def list;            @c.request(:get,    "/webhooks"); end
+    def get(id);         @c.request(:get,    "/webhooks/#{escape(id)}"); end
+    def create(**body);  @c.request(:post,   "/webhooks", body: body); end
+    def update(id, **b); @c.request(:patch,  "/webhooks", body: b.merge(id: id)); end
+    def delete(id);      @c.request(:delete, "/webhooks", body: { id: id }); end
+    def test(id);        @c.request(:post,   "/webhooks/#{escape(id)}/test"); end
+    def deliveries(id, limit: 20)
+      @c.request(:get, "/webhooks/#{escape(id)}/deliveries", query: { limit: limit })
+    end
+    def replay(delivery_id)
+      @c.request(:post, "/webhooks/deliveries/#{escape(delivery_id)}/replay")
+    end
+    def events
+      @c.request(:get, "/webhooks/events")
+    end
+
+    private
+    def escape(s); URI.encode_www_form_component(s); end
+  end
+
+  class ApiKeys
+    def initialize(client); @c = client; end
+    def list;            @c.request(:get,    "/api-keys"); end
+    def create(**body);  @c.request(:post,   "/api-keys", body: body); end
+    def revoke(id);      @c.request(:delete, "/api-keys/#{escape(id)}"); end
+    def rotate(id, grace_days: 7)
+      @c.request(:post, "/api-keys/#{escape(id)}/rotate", body: { grace_days: grace_days })
+    end
+    private
+    def escape(s); URI.encode_www_form_component(s); end
+  end
+
+  class Audit
+    def initialize(client); @c = client; end
+    def list(action: nil, since: nil, until_: nil, limit: 100)
+      q = { limit: limit }
+      q[:action] = action if action
+      q[:since]  = since  if since
+      q[:until]  = until_ if until_
+      @c.request(:get, "/audit", query: q)
+    end
+  end
+end

data/lib/coffrify/errors.rb

@@ -0,0 +1,18 @@
+module Coffrify
+  class Error < StandardError; end
+
+  class ApiError < Error
+    attr_reader :status, :code, :details
+    def initialize(status:, message:, code: nil, details: nil)
+      super(message)
+      @status = status
+      @code = code
+      @details = details
+    end
+  end
+
+  class AuthError       < ApiError; end
+  class RateLimitError  < ApiError; end
+  class NotFoundError   < ApiError; end
+  class ValidationError < ApiError; end
+end

data/lib/coffrify/event_catalog.rb

@@ -0,0 +1,56 @@
+module Coffrify
+  # Static event catalog mirroring the JS SDK / REST `GET /v1/webhooks/events`.
+  EVENT_CATALOG = [
+    # Transfer
+    { type: "transfer.created",            family: "transfer",  stability: "stable" },
+    { type: "transfer.downloaded",         family: "transfer",  stability: "stable" },
+    { type: "transfer.expired",            family: "transfer",  stability: "stable" },
+    { type: "transfer.deleted",            family: "transfer",  stability: "stable" },
+    { type: "transfer.cloned",             family: "transfer",  stability: "stable" },
+    { type: "transfer.scanned",            family: "transfer",  stability: "stable" },
+    { type: "transfer.scan_clean",         family: "transfer",  stability: "stable", required_plan: "pro" },
+    { type: "transfer.scan_infected",      family: "transfer",  stability: "stable", required_plan: "pro" },
+    { type: "transfer.scan_quarantined",   family: "transfer",  stability: "stable", required_plan: "pro" },
+    { type: "transfer.limit_reached",      family: "transfer",  stability: "stable" },
+    { type: "transfer.password_failed",    family: "transfer",  stability: "stable" },
+    { type: "transfer.geo_blocked",        family: "transfer",  stability: "stable", required_plan: "ultra" },
+    { type: "transfer.preview_opened",     family: "transfer",  stability: "beta"   },
+    { type: "transfer.email_sent",         family: "transfer",  stability: "stable" },
+    { type: "transfer.e2e_created",        family: "transfer",  stability: "stable" },
+    # Workspace
+    { type: "workspace.created",           family: "workspace", stability: "stable" },
+    { type: "workspace.plan_changed",      family: "workspace", stability: "stable" },
+    { type: "workspace.payment_succeeded", family: "workspace", stability: "stable" },
+    { type: "workspace.payment_failed",    family: "workspace", stability: "stable" },
+    { type: "workspace.usage_limit_warning", family: "workspace", stability: "stable" },
+    { type: "workspace.usage_limit_reached", family: "workspace", stability: "stable" },
+    # Members
+    { type: "member.invited",              family: "member",    stability: "stable" },
+    { type: "member.accepted",             family: "member",    stability: "stable" },
+    { type: "member.removed",              family: "member",    stability: "stable" },
+    # API keys / tokens
+    { type: "api_key.created",             family: "api_key",   stability: "stable" },
+    { type: "api_key.revoked",             family: "api_key",   stability: "stable" },
+    { type: "api_key.rotated",             family: "api_key",   stability: "stable" },
+    { type: "api_key.expired",             family: "api_key",   stability: "stable" },
+    { type: "api_key.suspicious_usage",    family: "api_key",   stability: "beta",  required_plan: "ultra" },
+    { type: "api_token.created",           family: "api_token", stability: "stable" },
+    { type: "api_token.used",              family: "api_token", stability: "beta"   },
+    { type: "api_token.expired",           family: "api_token", stability: "stable" },
+    # Webhook self
+    { type: "webhook.delivery_failed_final", family: "webhook", stability: "stable" },
+    { type: "webhook.endpoint_disabled",     family: "webhook", stability: "stable" },
+    # SCIM/SAML
+    { type: "scim.user_provisioned",       family: "scim",      stability: "stable", required_plan: "enterprise" },
+    { type: "scim.user_deprovisioned",     family: "scim",      stability: "stable", required_plan: "enterprise" },
+    { type: "saml.login_succeeded",        family: "saml",      stability: "stable", required_plan: "enterprise" },
+    { type: "saml.login_failed",           family: "saml",      stability: "stable", required_plan: "enterprise" },
+    # Audit/GDPR
+    { type: "audit.exported",              family: "audit",     stability: "stable" },
+    { type: "audit.policy_violated",       family: "audit",     stability: "beta",  required_plan: "ultra" },
+    { type: "gdpr.deletion_requested",     family: "gdpr",      stability: "stable", required_plan: "pro" },
+    { type: "gdpr.export_requested",       family: "gdpr",      stability: "stable", required_plan: "pro" },
+    # System
+    { type: "ping",                        family: "system",    stability: "stable" },
+  ].freeze
+end

data/lib/coffrify/version.rb

@@ -0,0 +1,3 @@
+module Coffrify
+  VERSION = "0.2.0".freeze
+end

data/lib/coffrify/webhook.rb

@@ -0,0 +1,130 @@
+require "openssl"
+require "json"
+require "base64"
+
+module Coffrify
+  # Webhook signature verification.
+  #
+  # Two formats are auto-detected by `verify_from_headers`:
+  #
+  #  * **Standard Webhooks** (https://www.standardwebhooks.com/) — preferred.
+  #      headers: webhook-id / webhook-timestamp / webhook-signature
+  #      signed payload: "<id>.<ts>.<raw_body>"
+  #      signature : "v1,<base64>" (space-separated for rotation).
+  #
+  #  * **Coffrify legacy** — single header `X-Coffrify-Signature: t=<ts>,v1=<hex>`.
+  #      signed payload : "<ts>.<raw_body>"
+  #
+  # `secret` accepts a String OR an Array of Strings — pass multiple values to
+  # support rotation grace windows. Returns
+  #   { valid:, event:, reason:, matched_secret_index: }
+  module Webhook
+    DEFAULT_TOLERANCE_SECONDS = 300 # 5 minutes
+    SIGNATURE_VERSION = "v1".freeze
+
+    # Resolve a Coffrify secret to its raw key bytes.
+    # "whsec_<hex>" → bytes via hex decode (Standard Webhooks convention).
+    # Anything else returned as-is.
+    def self.resolve_key(secret)
+      if secret.is_a?(String) && secret.start_with?("whsec_") && secret.length > 8
+        hex = secret[6..]
+        return [hex].pack("H*") if hex =~ /\A[0-9a-f]+\z/i && hex.length.even?
+      end
+      secret
+    end
+
+    def self.normalise_secrets(secret)
+      arr = secret.is_a?(Array) ? secret : [secret]
+      arr.compact.reject { |s| !s.is_a?(String) || s.empty? }
+    end
+
+    # Legacy Coffrify header verification.
+    def self.verify(raw_body, signature_header, secret, tolerance_seconds: DEFAULT_TOLERANCE_SECONDS)
+      secrets = normalise_secrets(secret)
+      return result(false, reason: "missing signature") if signature_header.nil? || signature_header.empty?
+      return result(false, reason: "missing secret") if secrets.empty?
+
+      parts = signature_header.split(",").map { |p| p.strip.split("=", 2) }.to_h
+      timestamp = parts["t"]
+      sig_hex   = parts[SIGNATURE_VERSION]
+      return result(false, reason: "malformed signature header") if timestamp.nil? || sig_hex.nil?
+
+      ts = timestamp.to_i
+      return result(false, reason: "timestamp out of tolerance") if (Time.now.to_i - ts).abs > tolerance_seconds
+
+      signed = "#{timestamp}.#{raw_body}"
+      provided = sig_hex.downcase
+      secrets.each_with_index do |s, i|
+        expected = OpenSSL::HMAC.hexdigest("SHA256", resolve_key(s), signed)
+        if secure_compare(expected, provided)
+          event = JSON.parse(raw_body) rescue nil
+          return result(true, event: event, matched_secret_index: i)
+        end
+      end
+      result(false, reason: "signature mismatch")
+    end
+
+    # Auto-detect verification from a request headers hash (case-insensitive).
+    # Standard Webhooks is preferred when its three headers are present.
+    def self.verify_from_headers(raw_body, headers, secret, tolerance_seconds: DEFAULT_TOLERANCE_SECONDS)
+      secrets = normalise_secrets(secret)
+      return result(false, reason: "missing secret") if secrets.empty?
+
+      lookup = lambda do |name|
+        target = name.downcase
+        pair = headers.find { |k, _| k.to_s.downcase == target }
+        pair && pair[1].is_a?(Array) ? pair[1].first : (pair && pair[1])
+      end
+
+      std_id = lookup.call("webhook-id")
+      std_ts = lookup.call("webhook-timestamp")
+      std_sig = lookup.call("webhook-signature")
+
+      if std_id && std_ts && std_sig
+        return result(false, reason: "malformed timestamp") unless std_ts.to_s =~ /\A\d+\z/
+        ts = std_ts.to_i
+        return result(false, reason: "timestamp out of tolerance") if (Time.now.to_i - ts).abs > tolerance_seconds
+
+        candidates = std_sig.to_s.split(/\s+/).filter_map do |piece|
+          next nil unless piece.start_with?("#{SIGNATURE_VERSION},")
+          begin
+            Base64.strict_decode64(piece[(SIGNATURE_VERSION.length + 1)..])
+          rescue ArgumentError
+            nil
+          end
+        end
+        return result(false, reason: "malformed signature") if candidates.empty?
+
+        message = "#{std_id}.#{ts}.#{raw_body}"
+        secrets.each_with_index do |s, i|
+          expected = OpenSSL::HMAC.digest("SHA256", resolve_key(s), message)
+          candidates.each do |c|
+            if secure_compare(expected, c)
+              event = JSON.parse(raw_body) rescue nil
+              return result(true, event: event, matched_secret_index: i)
+            end
+          end
+        end
+        return result(false, reason: "signature mismatch")
+      end
+
+      # Fall back to legacy.
+      legacy = lookup.call("x-coffrify-signature")
+      return verify(raw_body, legacy, secrets, tolerance_seconds: tolerance_seconds) if legacy
+      result(false, reason: "malformed")
+    end
+
+    def self.result(valid, event: nil, reason: nil, matched_secret_index: nil)
+      { valid: valid, event: event, reason: reason, matched_secret_index: matched_secret_index }
+    end
+
+    # Constant-time comparison to thwart timing attacks
+    def self.secure_compare(a, b)
+      return false if a.bytesize != b.bytesize
+      l = a.unpack("C*")
+      res = 0
+      b.each_byte { |byte| res |= byte ^ l.shift }
+      res == 0
+    end
+  end
+end

data/lib/coffrify.rb

@@ -0,0 +1,28 @@
+# Coffrify Ruby SDK
+# https://coffrify.com  |  https://docs.coffrify.dev
+#
+# Pure stdlib — no runtime dependencies. Requires Ruby 2.7+.
+#
+# Quickstart:
+#   require "coffrify"
+#   coffrify = Coffrify::Client.new(api_key: ENV.fetch("COFFRIFY_API_KEY"))
+#   transfer = coffrify.transfers.create(
+#     [{ name: "report.pdf", size: 1_240_000, mime_type: "application/pdf" }],
+#     expires_in_hours: 72, max_downloads: 10
+#   )
+#   puts transfer["share_url"]
+
+require "net/http"
+require "uri"
+require "json"
+require "openssl"
+require "securerandom"
+
+require_relative "coffrify/version"
+require_relative "coffrify/errors"
+require_relative "coffrify/client"
+require_relative "coffrify/webhook"
+require_relative "coffrify/event_catalog"
+
+module Coffrify
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: coffrify
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Coffrify
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.20'
+description: Send transfers, manage webhooks, verify signatures, query audit logs
+  from Ruby. Webhooks signed with HMAC-SHA256, retries 72h.
+email: support@coffrify.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/coffrify.rb
+- lib/coffrify/client.rb
+- lib/coffrify/errors.rb
+- lib/coffrify/event_catalog.rb
+- lib/coffrify/version.rb
+- lib/coffrify/webhook.rb
+homepage: https://coffrify.com
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://docs.coffrify.dev
+  source_code_uri: https://github.com/coffrify/coffrify-ruby
+  bug_tracker_uri: https://github.com/coffrify/coffrify-ruby/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for Coffrify — encrypted file transfer infrastructure.
+test_files: []