apertur-sdk 0.1.6 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eefd130f1dc0dfc251471d88510fb28d2464ddfe23b8a3c5055404708d1118a4
-  data.tar.gz: e33c04ea6e50216fe7988d2d5fd05e0327de309bbd26d6956098a86ef07afa4e
+  metadata.gz: 54295e7074aee323e8302c6024d025831ef1f37fd4fba2bd8663585be266759a
+  data.tar.gz: 14fc7f33d55226e794a53cb4608b7f4d3be6c2dc2af1ac94ed6cc889cbe8e7bd
 SHA512:
-  metadata.gz: '08c21fe268c9ddf93ddd2aa5d44e7a0312051287b272b639a7b131212384ef91c7020f13ae7ac86a7818ce6372a6e7a0fccbf8247df0102b4e5d20ae3f341685'
-  data.tar.gz: 62d086c9c4ab7c9122831fc579e5224764ed892874df7a686ed603ad7eeed2a7c8f50c2c1d41511c72c5922eb243ddd2345b140c9f1f32219a34b7eade389ed1
+  metadata.gz: 9c7b1b326a2dc9adf6ba246af70486777b548c9ad95e357d8c7535d98abd88d82daf49da40a35013628160c58dc6d52ee5f8d889c433c5d8c85144eed31bd472
+  data.tar.gz: 25eccfae7934a7178cf95aacaddff4b195f15205e34d1cc0b18b05460754fb417c63bb7b11840d5a1f77a4b165ac67e4fcbbafb6c52c463fc0713e5182fa3a99

data/README.md

@@ -52,6 +52,17 @@ You can override the base URL:
 client = Apertur::Client.new(api_key: "aptr_...", base_url: "http://localhost:3000")
 ```
 
+### Request Signing (optional)
+
+Pass `signing_secret:` to enable HMAC request signing. When set, every outgoing
+JSON or no-body request is automatically signed, adding `X-Aptr-Signature` and
+`X-Aptr-Timestamp` headers so the server can verify the request's authenticity.
+Omit it for backwards-compatible, unsigned requests.
+
+```ruby
+client = Apertur::Client.new(api_key: "aptr_...", signing_secret: "your_signing_secret")
+```
+
 ## Resources
 
 ### Sessions

data/lib/apertur/client.rb

@@ -51,15 +51,19 @@ module Apertur
     # @param oauth_token [String, nil] an OAuth bearer token (alternative to api_key)
     # @param base_url [String, nil] override the base URL; auto-detected from the
     #   key prefix when nil
+    # @param signing_secret [String, nil] optional request signing secret. When
+    #   present, every JSON request is automatically signed with
+    #   +X-Aptr-Signature+ / +X-Aptr-Timestamp+ headers. Backwards-compatible:
+    #   omit (or pass nil/empty) to send unsigned requests as before.
     # @raise [ArgumentError] if neither +api_key+ nor +oauth_token+ is provided
-    def initialize(api_key: nil, oauth_token: nil, base_url: nil)
+    def initialize(api_key: nil, oauth_token: nil, base_url: nil, signing_secret: nil)
       token = api_key || oauth_token
       raise ArgumentError, "Either api_key or oauth_token must be provided" if token.nil? || token.empty?
 
       @env = token.start_with?("aptr_test_") ? "test" : "live"
 
       resolved_url = base_url || (@env == "test" ? SANDBOX_BASE_URL : DEFAULT_BASE_URL)
-      http = HttpClient.new(resolved_url, token)
+      http = HttpClient.new(resolved_url, token, signing_secret: signing_secret)
 
       @sessions     = Resources::Sessions.new(http)
       @upload       = Resources::Upload.new(http)

data/lib/apertur/http_client.rb

@@ -4,18 +4,24 @@ require "net/http"
 require "uri"
 require "json"
 require "securerandom"
+require_relative "signature"
 
 module Apertur
   # Low-level HTTP wrapper around Net::HTTP for communicating with the Apertur API.
   #
   # Handles JSON serialization, Bearer token authentication, multipart uploads,
-  # and error mapping.
+  # request signing, and error mapping.
   class HttpClient
     # @param base_url [String] the API base URL (e.g. "https://api.aptr.ca")
     # @param token [String] the Bearer token (API key or OAuth token)
-    def initialize(base_url, token)
+    # @param signing_secret [String, nil] optional request signing secret. When
+    #   present (non-nil, non-empty), every JSON request is automatically
+    #   signed with +X-Aptr-Signature+ / +X-Aptr-Timestamp+ headers. Absent by
+    #   default for backwards compatibility.
+    def initialize(base_url, token, signing_secret: nil)
       @base_url = base_url.chomp("/")
       @token = token
+      @signing_secret = signing_secret
     end
 
     # Perform an API request and return the parsed JSON response.
@@ -38,6 +44,11 @@ module Apertur
         req.body = body.is_a?(String) ? body : JSON.generate(body)
       end
 
+      # Sign the full request-target (path + query) the server receives as
+      # req.url — build_uri may have appended a query string, and the server
+      # signs the query too. uri.request_uri is exactly what goes on the wire.
+      sign_headers(method, uri.request_uri, req.body).each { |k, v| req[k] = v }
+
       response = execute(uri, req, read_timeout: read_timeout)
       handle_response(response)
     end
@@ -53,6 +64,8 @@ module Apertur
       uri = build_uri(path, query)
       req = build_request(method, uri)
 
+      sign_headers(method, uri.request_uri, req.body).each { |k, v| req[k] = v }
+
       response = execute(uri, req)
       handle_error(response) unless response.is_a?(Net::HTTPSuccess)
       response.body
@@ -68,6 +81,13 @@ module Apertur
     # @param headers [Hash] additional request headers
     # @return [Hash, Array, nil] parsed JSON response
     # @raise [Apertur::Error] on API errors
+    #
+    # @note Multipart bodies are NOT signed. Net::HTTP streams the boundary
+    #   and part framing after this point, so the exact bytes on the wire
+    #   aren't available here to hash — signing an approximation would only
+    #   produce a signature that fails server-side verification. Multipart
+    #   uploads rely on Authorization (API key) auth instead; request signing
+    #   covers the JSON request path only (mirrors the Node SDK).
     def request_multipart(path, file_data, filename:, mime_type:, fields: {}, headers: {})
       uri = build_uri(path)
       boundary = "AperturRubySDK#{SecureRandom.hex(16)}"
@@ -169,6 +189,22 @@ module Apertur
       end
     end
 
+    # Compute +X-Aptr-Signature+ / +X-Aptr-Timestamp+ headers for a request, or
+    # +{}+ when no signing secret is configured.
+    #
+    # @param method [Symbol, String] the HTTP method
+    # @param path [String] the exact request path (no query string), verbatim
+    # @param body [String, nil] the exact bytes/string that will be sent on
+    #   the wire as the request body (or +nil+ for none) — the server hashes
+    #   whatever it actually receives, so an approximation here would just
+    #   produce a signature that fails verification.
+    # @return [Hash{String=>String}]
+    def sign_headers(method, path, body)
+      return {} if @signing_secret.nil? || @signing_secret.empty?
+
+      Signature.sign_request(@signing_secret, method, path, body, Time.now.to_i)
+    end
+
     # @param boundary [String]
     # @param file_data [String]
     # @param filename [String]

data/lib/apertur/signature.rb

@@ -63,6 +63,31 @@ module Apertur
       secure_compare(expected_b64, sig)
     end
 
+    # Sign an outgoing API request (HMAC SHA256 method).
+    #
+    # The signed payload is
+    # +"\#{timestamp}.\#{method.upcase}.\#{path}.\#{sha256hex(body)}"+ and the
+    # signature header is formatted as +sha256=<hex>+.
+    #
+    # @param secret [String] the request signing secret
+    # @param method [String, Symbol] the HTTP method (case-insensitive; uppercased)
+    # @param path [String] the exact request path, verbatim (for apertur this
+    #   includes the +/api/v1+ prefix, with no query string)
+    # @param body [String, nil] the exact serialized bytes/string sent as the
+    #   request body; +nil+ hashes as the empty string
+    # @param timestamp [Integer] unix seconds
+    # @return [Hash{String=>String}] +{ "X-Aptr-Signature" => "sha256=<hex>",
+    #   "X-Aptr-Timestamp" => "<unix seconds>" }+
+    def sign_request(secret, method, path, body, timestamp)
+      body_hash = OpenSSL::Digest::SHA256.hexdigest(body || "")
+      signature_base = "#{timestamp}.#{method.to_s.upcase}.#{path}.#{body_hash}"
+      signature = OpenSSL::HMAC.hexdigest("SHA256", secret, signature_base)
+      {
+        "X-Aptr-Signature" => "sha256=#{signature}",
+        "X-Aptr-Timestamp" => timestamp.to_s
+      }
+    end
+
     # Constant-time string comparison to prevent timing attacks.
     #
     # @param a [String]

data/lib/apertur/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Apertur
-  VERSION = "0.1.6"
+  VERSION = "0.1.8"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apertur-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.8
 platform: ruby
 authors:
 - Apertur
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-06-14 00:00:00.000000000 Z
+date: 2026-08-03 00:00:00.000000000 Z
 dependencies: []
 description: Official Ruby client for the Apertur image upload and delivery API. Supports
   session management, image uploads (including client-side encryption), polling, destinations,