apertur-sdk 0.1.5 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e13b276ea448173ed53e96ce31df30060b576c768acd1012bc9df6df2030375
-  data.tar.gz: ed633c8bd5e7509b7ef7f7a98e63fa2b8912048ca141e9230e184cff16eca960
+  metadata.gz: 54295e7074aee323e8302c6024d025831ef1f37fd4fba2bd8663585be266759a
+  data.tar.gz: 14fc7f33d55226e794a53cb4608b7f4d3be6c2dc2af1ac94ed6cc889cbe8e7bd
 SHA512:
-  metadata.gz: 617cd4b37d3da2fffe8292367cbd336d42076fed098eaa72e77360b1440911b73ba22bb664b104bf73c7d8bc41279c2d3656ae113ba7630ca4c598de3c3b44e9
-  data.tar.gz: 3806c669fb2bcb4eac40c7d4ecebed20a98993a6a19e82d13c2f290277e6b47b4d21122d9f525197cf2b65e17fb1d61bb31487e0fd2b5a066a762fa8bdc2dc8a
+  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/resources/polling.rb

@@ -35,7 +35,9 @@ module Apertur
       # @param image_id [String] the image ID
       # @return [Hash] acknowledgement status
       def ack(uuid, image_id)
-        @http.request(:post, "/api/v1/upload-sessions/#{uuid}/images/#{image_id}/ack")
+        # The server requires a JSON body on this endpoint; sending none
+        # results in a 500. An empty object is sufficient.
+        @http.request(:post, "/api/v1/upload-sessions/#{uuid}/images/#{image_id}/ack", body: {})
       end
 
       # Blocking polling loop that fetches, downloads, and acknowledges images.

data/lib/apertur/resources/upload.rb

@@ -59,18 +59,31 @@ module Apertur
         file_data = read_file(file)
         encrypted = Apertur::Crypto.encrypt_image(file_data, public_key)
 
-        payload = encrypted.merge(
-          "filename" => filename,
-          "mimeType" => mime_type,
-          "source" => source || "sdk"
+        # The server's "default" encryption mode expects a multipart file
+        # upload whose body is the JSON-serialized EncryptedPayload (camelCase
+        # keys), which it then decrypts with its private key. Sending a JSON
+        # request body instead yields a 500 ("No file uploaded").
+        payload_json = JSON.generate(
+          "encryptedKey" => encrypted["encrypted_key"],
+          "iv" => encrypted["iv"],
+          "encryptedData" => encrypted["encrypted_data"],
+          "algorithm" => encrypted["algorithm"]
         )
 
-        headers = {
-          "X-Aptr-Encrypted" => "default"
-        }
+        fields = {}
+        fields["source"] = source if source
+
+        headers = { "X-Aptr-Encrypted" => "default" }
         headers["x-session-password"] = password if password
 
-        @http.request(:post, "/api/v1/upload/#{uuid}/images", body: payload, headers: headers)
+        @http.request_multipart(
+          "/api/v1/upload/#{uuid}/images",
+          payload_json,
+          filename: "#{filename}.enc",
+          mime_type: "application/octet-stream",
+          fields: fields,
+          headers: headers
+        )
       end
 
       private
@@ -82,7 +95,7 @@ module Apertur
       def read_file(file)
         if file.respond_to?(:read)
           file.read.b
-        elsif file.is_a?(String) && File.exist?(file) && file.length < 1024
+        elsif file.is_a?(String) && looks_like_path?(file) && File.exist?(file)
           # Treat short strings that point to existing files as paths.
           # Raw image bytes will almost never be < 1024 bytes AND match an
           # existing filename, so this heuristic is safe in practice.
@@ -93,6 +106,17 @@ module Apertur
           raise ArgumentError, "Unsupported file input. Use a file path String, IO object, or raw String bytes."
         end
       end
+
+      # Heuristic: does this String plausibly name a file path (as opposed to
+      # raw image bytes)? Must be short and contain no NUL byte. Calling
+      # File.exist? on binary image data that contains a NUL byte raises
+      # "ArgumentError: path name contains null byte", so we must guard it.
+      #
+      # @param str [String]
+      # @return [Boolean]
+      def looks_like_path?(str)
+        str.length < 1024 && !str.include?("\x00")
+      end
     end
   end
 end

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.5"
+  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.5
+  version: 0.1.8
 platform: ruby
 authors:
 - Apertur
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-04-18 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,