linzer 0.8.0.beta1 → 0.8.0.beta2

data/lib/linzer/message/overlay.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Linzer
+  class Message
+    # Overlay provides a signing-time augmentation layer for HTTP headers.
+    #
+    # It allows additional headers to be introduced during HTTP Message
+    # Signature generation without mutating the underlying HTTP message.
+    #
+    # IMPORTANT SEMANTICS
+    #
+    # Overlay affects ONLY HTTP header resolution.
+    #
+    # It MUST NOT influence derived HTTP Message Signature components such as:
+    #   - @method
+    #   - @authority
+    #   - @target-uri
+    #
+    # These values are always computed from the underlying HTTP message.
+    #
+    # ---
+    #
+    # Resolution rules:
+    #
+    # Header lookup:
+    #   1. Underlying message headers
+    #   2. Overlay headers (fallback only)
+    #
+    # Derived components:
+    #   Always resolved from the underlying message only
+    #
+    # ---
+    #
+    # Purpose:
+    #
+    # This class exists to support signing-time augmentation of header values
+    # (e.g., injected or synthesized headers required by signing profiles)
+    # without altering the canonical representation of the HTTP message.
+    #
+    # This is NOT a full message override layer.
+    # It is a header-only augmentation mechanism used during signing.
+    #
+    # DESIGN NOTE:
+    # Overlay does not implement full HTTP message semantics.
+    # It only participates in header resolution for signing-time evaluation.
+    class Overlay
+      # Creates a new overlay message.
+      #
+      # @param message [Linzer::Message]
+      #   The underlying message to wrap
+      # @param overlay_headers [#to_h, Hash]
+      #   Additional headers to overlay onto the message
+      #   A hash-like object containing HTTP headers to use as an overlay layer.
+      #   Keys and values must be compatible with Net::HTTP header semantics.
+      def initialize(message, overlay_headers)
+        @message         = message
+        @overlay_headers = overlay_headers
+
+        # Internal adapter-backed overlay used to reuse Linzer's field
+        # resolution logic for header/field evaluation.
+        @overlay         = build_overlay_message(overlay_headers)
+      end
+
+      # Returns a header value from the signing-time resolution view.
+      #
+      # Overlay headers are only used if the underlying message does not
+      # provide a value for the requested header.
+      #
+      # Derived components (e.g. @authority, @target-uri) are not affected.
+      #
+      # @param name [String]
+      # @return [String, nil]
+      def header(name)
+        @message.header(name) || @overlay.header(name)
+      end
+
+      # Returns true if the field can be resolved from:
+      #
+      # - the underlying HTTP message (including derived fields), or
+      # - overlay headers (header fields only)
+      #
+      # NOTE:
+      # Overlay headers do not participate in derived component resolution
+      # (e.g. @method, @target-uri, @authority).
+      #
+      # @param field [Linzer::FieldId]
+      # @return [Boolean]
+      def field?(field)
+        @message.field?(field) || (!field.derived? && @overlay.field?(field))
+      end
+
+      # Attaches signature headers to the underlying HTTP message.
+      #
+      # Overlay headers are applied only as HTTP headers at attachment time.
+      # They do not affect derived HTTP Message Signature components.
+      #
+      # @param signature [Linzer::Signature] The signature to attach
+      # @return [Object]
+      #   The underlying message returned by Linzer::Message#attach!
+      def attach!(signature)
+        @message.attach!(signature, additional_headers: @overlay_headers.to_h)
+      end
+
+      # Retrieves a resolved header or field value from the signing-time view.
+      #
+      # Resolution order:
+      #
+      #   1. Underlying HTTP message
+      #   2. Overlay headers (fallback only)
+      #
+      # IMPORTANT:
+      # Overlay values are ONLY used when the underlying message does not
+      # provide a value. They do not override existing message values.
+      #
+      # Derived HTTP Message Signature components (e.g. @method,
+      # @target-uri, @authority) are always resolved exclusively from the
+      # underlying message and are never influenced by overlay headers.
+      #
+      # @param name [Linzer::FieldId]
+      # @return [Object, nil]
+      def [](name)
+        value = @message[name]
+        return value unless value.nil?
+
+        return nil if Linzer::FieldId.new(field_name: name).derived?
+        @overlay[name]
+      end
+
+      private
+
+      # Builds a synthetic Net::HTTP request used solely to reuse Linzer's
+      # Generic::Request field resolution logic.
+      #
+      # The URI is a placeholder because only header and field resolution
+      # behavior is required; no network request is performed.
+      def build_overlay_message(headers)
+        request = Net::HTTP::Get.new(URI("https://example.invalid/"))
+        request.initialize_http_header(headers.to_h)
+        Adapter::Generic::Request.new(request)
+      end
+    end
+  end
+end

data/lib/linzer/message.rb

@@ -113,6 +113,24 @@ module Linzer
     #     message.attach!(signature)
     def_delegators :@adapter, :attach!
 
+    # Returns a new message wrapper with additional or overridden headers.
+    #
+    # The returned message preserves the original message contents while
+    # overlaying the provided headers for component resolution and
+    # signature generation.
+    #
+    # @param headers [#to_h] Headers to overlay onto the message
+    # @return [Linzer::Message::Overlay] A message wrapper using the
+    #   merged header set
+    #
+    # @example Add related signature headers without mutating the message
+    #   signed_message = message.with_headers(
+    #     "signature-agent" => "https://example.org/automated-agent"
+    #   )
+    def with_headers(overlay_headers)
+      Overlay.new(self, overlay_headers)
+    end
+
     class << self
       # Registers a custom adapter for an HTTP message class.
       #

data/lib/linzer/signature/context.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Linzer
+  class Signature
+    # A mutable context object used during signature generation.
+    #
+    # The context represents all state required to produce a signature,
+    # including:
+    #
+    # - the HTTP message being signed
+    # - the signing key
+    # - covered signature components
+    # - signature parameters
+    # - optional overlay headers introduced by signing profiles
+    #
+    # Profiles may mutate this context before or during signing in order
+    # to influence the final signature output (e.g., adding headers,
+    # modifying components, or adjusting parameters).
+    #
+    # This object is intentionally mutable and is not thread-safe.
+    #
+    # @attr_reader [Linzer::Message] message
+    #   the HTTP message being signed
+    #
+    # @attr_reader [Object] key
+    #   the signing key used to generate the signature
+    #
+    # @attr_reader [Array<String>] components
+    #   list of covered signature components
+    #
+    # @attr_reader [Hash] params
+    #   signature parameters (may include :label if provided)
+    #
+    # @attr_reader [Hash] overlay_headers
+    #   Overlay headers are merged into the message view during signature
+    #   computation but do not mutate the underlying message.
+    class Context
+      # Creates a new signing context.
+      #
+      # @param message [Linzer::Message]
+      #   The HTTP message being signed
+      #
+      # @param key [Linzer::Key]
+      #   The signing key used to generate the signature
+      #
+      # @param label [String, nil]
+      #   Optional signature label. If provided, it is merged into params
+      #   as `:label`.
+      #
+      # @param components [Array<String>]
+      #   The list of HTTP components covered by the signature
+      #
+      # @param params [Hash]
+      #   Signature parameters passed to the signing algorithm
+      def initialize(message:, key:, label:, components:, params:)
+        @message         = message
+        @key             = key
+        @components      = components.dup
+        @params          = (label ? params.merge(label: label) : params).dup
+        @overlay_headers = {}
+      end
+      attr_reader :key, :components, :params, :overlay_headers
+
+      # Returns a message view that includes any overlay headers.
+      #
+      # The returned object is cached after first construction.
+      #
+      # Overlay headers are applied lazily and only affect the derived
+      # signing view; the original message remains unchanged.
+      #
+      # @return [Linzer::Message]
+      def message
+        return @overlay_message  if defined?(@overlay_message)
+        return @message          if @overlay_headers.empty?
+
+        @overlay_message = @message.with_headers(overlay_headers)
+      end
+    end
+  end
+end

data/lib/linzer/signature/profile/base.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Linzer
+  class Signature
+    module Profile
+      # Base class for all signing profiles.
+      #
+      # A signing profile encapsulates policy logic that can modify a
+      # {Linzer::Signature::Context} before signature generation.
+      #
+      # Subclasses are expected to implement {#apply}.
+      #
+      # ## Lifecycle
+      #
+      # 1. Context is created
+      # 2. Profile is resolved via {.resolve}
+      # 3. {#apply} is invoked with the signing context
+      # 4. Context is used to generate signature
+      #
+      # @abstract
+      class Base
+        # Applies the profile to a signing context.
+        #
+        # Implementations may:
+        #
+        # - modify context parameters
+        # - inject overlay headers
+        # - adjust covered components
+        #
+        # @param ctx [Linzer::Signature::Context]
+        #   The mutable signing context
+        #
+        # @return [void]
+        #
+        # @raise [Linzer::Error]
+        #   If the subclass does not implement this method
+        def apply(ctx)
+          raise Error, "Sub-classes are required to implement this method!"
+        end
+      end
+    end
+  end
+end

data/lib/linzer/signature/profile/example.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Linzer
+  class Signature
+    module Profile
+      # Example no-op signing profile.
+      #
+      # This profile exists solely for documentation and testing purposes.
+      # It does not modify the signing context in any way.
+      #
+      # It demonstrates the expected structure of a signing profile:
+      #
+      # - initializer receives configuration parameters
+      # - {#apply} mutates a {Linzer::Signature::Context}
+      #
+      # This profile is safe to use but has no effect on signature output.
+      class Example < Base
+        # Creates a new example profile instance.
+        #
+        # @param foo [Object] example configuration parameter (unused)
+        # @param bar [Object] example configuration parameter (unused)
+        def initialize(foo:, bar:)
+          @foo = foo
+          @bar = bar
+        end
+
+        # Applies this profile to the signing context.
+        #
+        # This implementation intentionally performs no modifications.
+        #
+        # @param ctx [Linzer::Signature::Context]
+        # @return [void]
+        def apply(ctx)
+          # no-op
+        end
+      end
+    end
+  end
+end

data/lib/linzer/signature/profile/web_bot_auth.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module Linzer
+  class Signature
+    module Profile
+      # Web Bot Auth signing profile implementation.
+      #
+      # This profile applies the behavior defined in the Web Bot Auth
+      # HTTP Message Signatures draft specification.
+      #
+      # It mutates a signing context to ensure compliance with the
+      # spec requirements, including:
+      #
+      # - selection of required signature components
+      # - generation of nonce values
+      # - enforcement of Web Bot Auth signature parameters
+      # - optional Signature-Agent header injection
+      #
+      # ## Lifecycle
+      #
+      # 1. Context is created
+      # 2. Profile is resolved
+      # 3. {#apply} mutates signing context
+      # 4. signature is generated using modified context
+      #
+      # @see https://datatracker.ietf.org/wg/webbotauth/documents/
+      class WebBotAuth < Base
+        # Creates a new Web Bot Auth signing profile.
+        #
+        # @param params [Symbol, nil]
+        #   Controls default Web Bot Auth signature parameters.
+        #
+        #   - :recommended → apply Web Bot Auth recommended defaults
+        #   - nil → do not modify signature parameters
+        #
+        # @param nonce [Symbol, nil]
+        #   Controls nonce generation behavior.
+        #
+        #   - :generate → inject a cryptographically random nonce
+        #   - nil → no nonce is added
+        #
+        # @param agent [String, nil]
+        #   Optional Signature-Agent identifier URI.
+        #
+        #   When provided, a structured Signature-Agent header is injected
+        #   and included as a covered signature component.
+        def initialize(params: :recommended, nonce: :generate, agent: nil)
+          @params = params
+          @nonce  = nonce
+          @agent  = agent
+          freeze
+        end
+
+        attr_reader :params, :nonce, :agent
+
+        SIGNATURE_AGENT = "signature-agent"
+        private_constant :SIGNATURE_AGENT
+
+        REQUIRED_AUTH_COMPONENTS = %w[@authority @target-uri].freeze
+
+        # Applies the Web Bot Auth profile to a signing context.
+        #
+        # This method mutates:
+        # - signature parameters (ctx.params)
+        # - covered components (ctx.components)
+        # - overlay headers (ctx.overlay_headers)
+        #
+        # @param ctx [Linzer::Signature::Context]
+        #   Mutable signing context
+        #
+        # @return [void]
+        # @raise [Linzer::Error]
+        #   If key or message are incompatible with Web Bot Auth rules
+        def apply(ctx)
+          validate ctx.key, ctx.message
+
+          if @params == :recommended
+            set_params!(ctx.key, ctx.components, ctx.params)
+          end
+
+          ctx.params[:nonce] = generate_nonce if @nonce == :generate
+
+          if @agent
+            set_agent!(
+              @agent,
+              ctx.params[:label],
+              ctx.message,
+              ctx.components,
+              ctx.overlay_headers
+            )
+          end
+        end
+
+        # Returns a default Web Bot Auth profile instance.
+        #
+        # This represents the standard recommended configuration:
+        #
+        # - recommended signature parameters enabled
+        # - nonce generation enabled
+        #
+        # @return [WebBotAuth]
+        def self.default
+          new(params: :recommended, nonce: :generate)
+        end
+
+        private
+
+        # Applies Web Bot Auth recommended signature parameter rules.
+        #
+        # This ensures compliance with Web Bot Auth requirements:
+        #
+        # - At least one of @authority or @target-uri must be covered
+        # - expires is set to a default lifetime if not provided
+        # - tag is set to "web-bot-auth"
+        # - keyid is derived from the signing key fingerprint
+        #
+        # @param key [Linzer::JWS::Key]
+        # @param components [Array<String>]
+        # @param params [Hash]
+        # @return [void]
+        def set_params!(key, components, params)
+          # 4.2. Generating HTTP Message Signature
+          #
+          # Agents MUST include at least one of the following components:
+          # - @authority
+          # - @target-uri
+          #
+          if (components & REQUIRED_AUTH_COMPONENTS).empty?
+            components << REQUIRED_AUTH_COMPONENTS.sample
+          end
+
+          # Agents MUST include the following @signature-params:
+          # - created
+          # - expires
+          # - keyid MUST be a base64url JWK SHA-256 Thumbprint
+          # - tag MUST be web-bot-auth
+          #
+          # options[:created] is set by default by linzer at signature creation time
+          #
+          params[:expires] ||= Time.now.to_i + 3600
+          params[:tag]     ||= "web-bot-auth"
+          params[:keyid]   ||= key.material.key_digest
+        end
+
+        # Injects and signs the Signature-Agent header.
+        #
+        # The header is only added if:
+        # - it is not already present, OR
+        # - its value differs from the configured agent
+        #
+        # When added:
+        # - a structured Signature-Agent header is written into overlay headers
+        # - the corresponding structured field is added to covered components
+        #
+        # @param agent [String]
+        # @param label [String]
+        # @param message [Linzer::Message]
+        # @param components [Array<String>]
+        # @param overlay_headers [Hash]
+        # @return [void]
+        # @raise [Linzer::Error]
+        #   If the header cannot be serialized as a structured field
+        def set_agent!(agent, label, message, components, overlay_headers)
+          if message[SIGNATURE_AGENT] != agent
+            overlay_headers[SIGNATURE_AGENT] =
+              HTTP::StructuredField.serialize_dictionary(label => agent)
+
+            field = HTTP::StructuredField::Item.new(SIGNATURE_AGENT, key: label)
+            serialized_field = HTTP::StructuredField.serialize(field)
+            if !components.include?(serialized_field)
+              components << serialized_field
+            end
+          end
+        rescue Error => ex
+          raise Error, "Invalid #{SIGNATURE_AGENT} header value!", cause: ex
+        end
+
+        # Validates that the context is compatible with Web Bot Auth.
+        #
+        # @param key [Object]
+        # @param message [Linzer::Message]
+        # @return [void]
+        # @raise [Linzer::Error]
+        def validate(key, message)
+          raise Error, "Unsupported/invalid key!" unless key.is_a?(Linzer::JWS::Key)
+          raise Error, "Web Bot Auth is defined only for requests!" unless message.request?
+        end
+
+        # Generates a cryptographically random nonce.
+        #
+        # The nonce is URL-safe and suitable for inclusion in HTTP signature
+        # parameters.
+        #
+        # @return [String]
+        def generate_nonce
+          SecureRandom.urlsafe_base64(64)
+        end
+      end
+    end
+  end
+end

data/lib/linzer/signature/profile.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "profile/base"
+require_relative "profile/web_bot_auth"
+
+module Linzer
+  class Signature
+    # A signing profile defines optional behavior that can modify a signing
+    # context prior to HTTP Message Signature generation.
+    #
+    # Profiles are used to encapsulate domain-specific signing rules such as:
+    #
+    # - default covered components
+    # - parameter enrichment
+    # - contextual header injection
+    # - policy-based adjustments to signing behavior
+    #
+    # Profiles are applied *before signature computation* and may mutate
+    # {Linzer::Signature::Context}.
+    module Profile
+      # Resolves a signing profile from a symbolic or object-based reference.
+      #
+      # This allows callers to pass either:
+      #
+      # - +nil+ (no profile)
+      # - an already constructed profile instance
+      # - a symbolic identifier for a registered profile
+      #
+      # @param profile [Symbol, Profile::Base, nil]
+      #   The profile identifier or instance to resolve
+      #
+      # @return [Profile::Base, nil]
+      #   A resolved profile instance, or +nil+ if no profile is used
+      #
+      # @raise [Linzer::Error]
+      #   If the profile symbol is unknown or unsupported
+      def self.resolve(profile)
+        unsupported = "Unknown/unsupported signing profile!"
+
+        case profile
+        when NilClass, Profile::Base
+          profile
+        when Symbol
+          case profile
+          when :web_bot_auth
+            WebBotAuth.default
+          else
+            raise Error, unsupported
+          end
+        else
+          raise Error, unsupported
+        end
+      end
+
+      # Convenience constructor for a Web Bot Auth signing profile.
+      #
+      # This is a helper for constructing a profile instance directly
+      # without using {Profile.resolve}.
+      #
+      # @param options [Hash]
+      #   Options passed through to WebBotAuth initializer
+      #
+      # @return [Profile::WebBotAuth]
+      #   A configured WebBotAuth profile instance
+      def self.web_bot_auth(**options)
+        WebBotAuth.new(**options)
+      end
+    end
+  end
+end