http_signature 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d7340510585b31400802574581fc40aa006889f7f43e67e6ac4d5c926ddc3ce
-  data.tar.gz: 3364453874b93eb6b37a2ef13208dbb2792b4b50975c872459fea1a1d70a68d7
+  metadata.gz: e704af788a9d55b85db708db52faef4107d793d289c36a7b8839837c59590841
+  data.tar.gz: 4941ab8b360a30f0e37d9e8de3377a1a83feaac39b995909947846e072e3b0a3
 SHA512:
-  metadata.gz: ba102a57a504be38d46ff962442d273dcee1866e5e49127927f638774dc30a66b92c063edb62670ba09b42b14bb2257772992183b606ef2abc7c1d1340677717
-  data.tar.gz: b2ee1d08d85958e663760b999c45a8865e2db4f43920fbf9a77bae78479a5192e939d0cfdab26a6d47dd936c1bb17311b809ac6b8278f92d1c8ced43de957d9d
+  metadata.gz: 312862f8f0a06de466c992cf422138b3676b23547f273ee3c0cd1ccc99111ad394f0a60ef6578c4701310dd4a423d8c4a70b1a1c66d11811b7dcac003823e5bc
+  data.tar.gz: 14d1e2b66bfa36e23efd38803d83104648e7bcc18dddadb7ee442ac5abf62a2d5653ca53bf4934255cf6521af84849fa66c5dc2ebba76705e0a2743b85f14838

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    http_signature (1.1.0)
+    http_signature (1.2.0)
       base64
 
 GEM

data/README.md

@@ -59,6 +59,23 @@ HTTPSignature.create(
 )
 ```
 
+#### Supported components
+
+Derived components (prefixed with `@`) per [RFC 9421 Section 2.2](https://www.rfc-editor.org/rfc/rfc9421#section-2.2):
+
+| Component | Description |
+|-----------|-------------|
+| `@method` | HTTP method (e.g., `GET`, `POST`) |
+| `@target-uri` | Full request URI (`https://example.com/foo?bar=1`) |
+| `@authority` | Host (and port if non-default) |
+| `@scheme` | URI scheme (`http` or `https`) |
+| `@path` | Request path (`/foo`) |
+| `@query` | Query string (including `?`; `?bar=1`) |
+| `@status` | Response status code (responses only) |
+
+Any lowercase header name (e.g., `content-type`, `date`) can also be used as a component.
+
+Default components are: `@method @target-uri content-digest content-type`
 
 ### Validate signature
 
@@ -76,6 +93,22 @@ HTTPSignature.valid?(
 # Raises `SignatureError` for invalid signatures
 ```
 
+#### Limiting signature age
+
+Use `max_age` to reject signatures older than a specified number of seconds, regardless of the signature's `expires` parameter. This helps protect against replay attacks.
+
+```ruby
+HTTPSignature.valid?(
+  url: "https://example.com/foo",
+  method: :get,
+  headers: headers,
+  key: "secret",
+  max_age: 300 # Reject signatures older than 5 minutes
+)
+
+# Raises `ExpiredError` if the signature was created more than 300 seconds ago
+```
+
 ## Outgoing request examples
 
 ### NET::HTTP

data/lib/http_signature/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HTTPSignature
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

data/lib/http_signature.rb

@@ -16,9 +16,12 @@ module HTTPSignature
 
   class SignatureError < StandardError; end
   class MissingComponent < SignatureError; end
+  class UnsupportedComponent < SignatureError; end
   class UnsupportedAlgorithm < SignatureError; end
   class ExpiredError < SignatureError; end
 
+  SUPPORTED_DERIVED_COMPONENTS = %w[@method @authority @target-uri @scheme @path @query @status].freeze
+
   Algorithm = Struct.new(:type, :digest_name, :curve)
   ALGORITHMS = {
     "hmac-sha256" => Algorithm.new(:hmac, "SHA256"),
@@ -48,7 +51,27 @@ module HTTPSignature
 
   # Create RFC 9421 Signature-Input and Signature headers
   #
+  # @param url [String] The full URL of the request being signed
+  # @param key [String, OpenSSL::PKey::PKey] The signing key (secret for HMAC, private key for asymmetric)
+  # @param key_id [String] Identifier for the key, included in the signature metadata
+  # @param method [Symbol] HTTP method (default: :get)
+  # @param headers [Hash] Request headers to potentially include in signature (default: {})
+  # @param body [String] Request body, used to generate content-digest if needed (default: "")
+  # @param algorithm [String] Signing algorithm (default: "hmac-sha256")
+  # @param components [Array<String>, nil] Components to sign. If nil, uses @method, @target-uri,
+  #   and includes content-digest/content-type when present
+  # @param created [Integer] Unix timestamp for signature creation (default: Time.now.to_i)
+  # @param expires [Integer, nil] Unix timestamp when signature expires (default: nil)
+  # @param nonce [String, nil] Random value for signature uniqueness (default: nil)
+  # @param label [String] Signature label in headers (default: "sig1")
+  # @param query_string_params [Hash] Additional query params to merge into URL (default: {})
+  # @param include_alg [Boolean] Whether to include alg in signature metadata (default: true)
+  # @param status [Integer, nil] HTTP status code, required when signing responses with @status component
   # @return [Hash] { 'Signature-Input' => header, 'Signature' => header }
+  # @raise [ArgumentError] If created/expires are not integers or expires < created
+  # @raise [UnsupportedAlgorithm] If the algorithm is not supported
+  # @raise [UnsupportedComponent] If a derived component (e.g. @foo) is not supported
+  # @raise [MissingComponent] If a required component is missing
   def self.create(
     url:,
     key:,
@@ -62,7 +85,9 @@ module HTTPSignature
     expires: nil,
     nonce: nil,
     label: DEFAULT_LABEL,
-    query_string_params: {}
+    query_string_params: {},
+    include_alg: true,
+    status: nil
   )
     unless created.is_a?(Integer)
       raise ArgumentError, "created must be a Unix timestamp integer"
@@ -80,6 +105,8 @@ module HTTPSignature
     components ||=
       default_components(normalized_headers, body:)
 
+    validate_components!(components)
+
     normalized_headers =
       if components.include?("content-digest")
         ensure_content_digest(normalized_headers, body)
@@ -91,7 +118,8 @@ module HTTPSignature
       uri:,
       method:,
       headers: normalized_headers,
-      components:
+      components:,
+      status:
     )
 
     signature_input_header, base_string = build_signature_input(
@@ -100,7 +128,7 @@ module HTTPSignature
       created:,
       expires:,
       key_id:,
-      alg: algorithm,
+      alg: include_alg ? algorithm : nil,
       nonce:,
       canonical_components:
     )
@@ -116,7 +144,23 @@ module HTTPSignature
 
   # Verify RFC 9421 Signature headers
   #
+  # @param url [String] The full URL of the request being verified
+  # @param method [Symbol] HTTP method of the request
+  # @param headers [Hash] Request headers, must include Signature-Input and Signature headers
+  # @param body [String] Request body (default: "")
+  # @param key [String, OpenSSL::PKey::PKey, nil] Verification key. If nil, uses key_resolver or configured keys
+  # @param key_resolver [Proc, nil] Callable that receives key_id and returns the key (default: nil)
+  # @param label [String] Signature label to verify (default: "sig1")
+  # @param query_string_params [Hash] Additional query params to merge into URL (default: {})
+  # @param max_age [Integer, nil] Maximum signature age in seconds. Takes precedence over
+  #   the expires timestamp in the signature (default: nil)
+  # @param algorithm [String, nil] Override algorithm for verification. If nil, uses alg from
+  #   signature params or defaults to hmac-sha256 (default: nil)
+  # @param status [Integer, nil] HTTP status code, required when verifying responses with @status component
   # @return [Boolean] true when signature verification succeeds
+  # @raise [ArgumentError] If max_age is not a non-negative integer
+  # @raise [SignatureError] If signature headers are missing, key is missing, or signature is invalid
+  # @raise [ExpiredError] If the signature has expired
   def self.valid?(
     url:,
     method:,
@@ -125,8 +169,14 @@ module HTTPSignature
     key: nil,
     key_resolver: nil,
     label: DEFAULT_LABEL,
-    query_string_params: {}
+    query_string_params: {},
+    max_age: nil,
+    algorithm: nil,
+    status: nil
   )
+    if max_age && (!max_age.is_a?(Integer) || max_age < 0)
+      raise ArgumentError, "max_age must be a non-negative integer"
+    end
     normalized_headers = normalize_headers(headers)
 
     signature_input_header = normalized_headers["signature-input"]
@@ -136,13 +186,14 @@ module HTTPSignature
     parsed_input = parse_signature_input(signature_input_header, label)
     parsed_signature = parse_signature(signature_header, label)
 
-    algorithm_entry = algorithm_entry_for(parsed_input[:params][:alg] || DEFAULT_ALGORITHM)
+    algorithm_entry = algorithm_entry_for(algorithm || parsed_input[:params][:alg] || DEFAULT_ALGORITHM)
     key_id = parsed_input[:params][:keyid]
     created = parsed_input[:params][:created].to_i
-    expires = parsed_input[:params][:expires]&.to_i
+    signature_expires = parsed_input[:params][:expires]&.to_i
+    effective_expires = max_age ? created + max_age : signature_expires
     now = Time.now.to_i
-    if expires && (created > expires || now > expires)
-      raise ExpiredError, "Signature expired at #{expires}"
+    if effective_expires && (created > effective_expires || now > effective_expires)
+      raise ExpiredError, "Signature expired at #{effective_expires}"
     end
     resolved_key = key || key_resolver&.call(key_id) || key_from_store(key_id)
     raise SignatureError, "Key is required for verification" unless resolved_key
@@ -156,14 +207,15 @@ module HTTPSignature
       uri:,
       method:,
       headers: normalized_headers,
-      components: parsed_input[:components]
+      components: parsed_input[:components],
+      status:
     )
 
     _, base_string = build_signature_input(
       label:,
       components: parsed_input[:components],
       created:,
-      expires:,
+      expires: signature_expires,
       key_id:,
       alg: parsed_input[:params][:alg],
       nonce: parsed_input[:params][:nonce],
@@ -192,6 +244,15 @@ module HTTPSignature
     new_uri
   end
 
+  def self.validate_components!(components)
+    components.each do |component|
+      next unless component.start_with?("@")
+      next if SUPPORTED_DERIVED_COMPONENTS.include?(component)
+
+      raise UnsupportedComponent, "Unsupported component: #{component}"
+    end
+  end
+
   def self.default_components(headers, body: nil)
     components = DEFAULT_COMPONENTS.dup
     DEFAULT_HEADERS.each do |header|
@@ -216,10 +277,10 @@ module HTTPSignature
     headers.merge("content-digest" => "sha-256=:#{Base64.strict_encode64(digest)}:")
   end
 
-  def self.build_components(uri:, method:, headers:, components:)
+  def self.build_components(uri:, method:, headers:, components:, status: nil)
     components.map do |component|
       if component.start_with?("@")
-        [component, derived_component(component, uri, method)]
+        [component, derived_component(component, uri, method, status:)]
       else
         value = headers[component]
         raise MissingComponent, "Missing required component: #{component}" unless value
@@ -229,7 +290,7 @@ module HTTPSignature
     end
   end
 
-  def self.derived_component(component, uri, method)
+  def self.derived_component(component, uri, method, status: nil)
     case component
     when "@method" then method.to_s.upcase
     when "@authority"
@@ -241,6 +302,9 @@ module HTTPSignature
     when "@scheme" then uri.scheme
     when "@path" then uri.path
     when "@query" then uri.query.to_s
+    when "@status"
+      raise MissingComponent, "@status requires a status code" unless status
+      status.to_s
     else
       raise MissingComponent, "Unsupported derived component: #{component}"
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: http_signature
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Joel Larsson