linzer 0.7.9 → 0.8.0.beta2

data/lib/linzer/helper.rb

@@ -16,12 +16,22 @@ module Linzer
     #
     # @param request_or_response [Net::HTTPRequest, Net::HTTPResponse, Rack::Request,
     #   Rack::Response, HTTP::Request] The HTTP message to sign
-    # @param args [Hash] Keyword arguments
-    # @option args [Linzer::Key] :key The private key to sign with (required)
-    # @option args [Array<String>] :components The components to include in the
-    #   signature (required). Example: `%w[@method @path content-type]`
-    # @option args [String] :label Optional signature label (defaults to "sig1")
-    # @option args [Hash] :params Additional signature parameters (created, nonce, etc.)
+    #
+    # @param key [Linzer::Key]
+    #   The private key to sign with (required)
+    #
+    # @param components [Array<String>]
+    #   The components to include in the signature (required).
+    #   Example: `%w[@method @path content-type]`
+    #
+    # @param label [String, nil]
+    #   Optional signature label (defaults to "sig1")
+    #
+    # @param params [Hash]
+    #   Additional signature parameters (created, nonce, etc.)
+    #
+    # @param profile [Symbol, Linzer::Signature::Profile::Base, nil]
+    #   Optional signing profile
     #
     # @return [Object] The original HTTP message with signature headers attached
     #
@@ -46,17 +56,26 @@ module Linzer
     #     label: "my-sig",
     #     params: { nonce: SecureRandom.hex(16), tag: "my-app" }
     #   )
-    def sign!(request_or_response, **args)
-      message = Message.new(request_or_response)
-      options = {}
+    def sign!(request_or_response, key:, components: nil, label: nil, params: {}, profile: nil)
+      ctx = Signature::Context.new(
+        message:    Message.new(request_or_response),
+        key:        key,
+        label:      label,
+        components: Array(components),
+        params:     Hash(params)
+      )
+
+      resolved_profile = Signature::Profile.resolve(profile)
+      resolved_profile&.apply(ctx)
 
-      label = args[:label]
-      options[:label] = label if label
-      options.merge!(args.fetch(:params, {}))
+      signature = Linzer::Signer.sign(
+        ctx.key,
+        ctx.message,
+        ctx.components,
+        ctx.params
+      )
 
-      key = args.fetch(:key)
-      signature = Linzer::Signer.sign(key, message, args.fetch(:components), options)
-      message.attach!(signature)
+      ctx.message.attach!(signature)
     end
 
     # Verifies a signed HTTP request or response.

data/lib/linzer/hmac.rb

@@ -54,18 +54,6 @@ module Linzer
         OpenSSL.secure_compare(signature, sign(data))
       end
 
-      # HMAC keys can always sign (they contain the secret).
-      # @return [Boolean] true if key material is present
-      def private?
-        !material.nil?
-      end
-
-      # HMAC keys are symmetric, not public/private.
-      # @return [Boolean] always false for HMAC keys
-      def public?
-        false
-      end
-
       # Returns a safe string representation that doesn't leak the secret.
       #
       # The key material is intentionally excluded from the output to prevent
@@ -82,6 +70,20 @@ module Linzer
         oid = Digest::SHA2.hexdigest(object_id.to_s)[48..63]
         "#<%s:0x%s %s>" % [self.class, oid, vars.join(", ")]
       end
+
+      private
+
+      # HMAC keys can always sign (they contain the secret).
+      # @return [Boolean] true if key material is present
+      def compute_private?
+        !material.nil?
+      end
+
+      # HMAC keys are symmetric, not public/private.
+      # @return [Boolean] always false for HMAC keys
+      def compute_public?
+        false
+      end
     end
   end
 end

data/lib/linzer/http/signature_feature.rb

@@ -53,12 +53,17 @@ module Linzer
       # @param covered_components [Array<String>] Components to include
       #   in the signature. Defaults to `@method`, `@request-target`,
       #   `@authority`, and `date`.
+      # @param profile [Symbol, Linzer::Signature::Profile::Base, nil]
+      #   Optional signing profile used when generating signatures.
+      #   When provided, the profile may supply default covered components
+      #   and signature parameters.
       #
       # @raise [HTTP::Error] If key is nil or invalid
-      def initialize(key:, params: {}, covered_components: default_components)
+      def initialize(key:, params: {}, covered_components: default_components, profile: nil)
         @fields = Array(covered_components)
         @key    = validate_key(key)
         @params = Hash(params)
+        @profile = profile
       end
 
       # @return [Array<String>] The components to include in signatures
@@ -67,6 +72,10 @@ module Linzer
       # @return [Hash] Additional signature parameters
       attr_reader :params
 
+      # @return [Linzer::Signature::Profile::Base, Symbol, nil]
+      #  Optional signing profile used during signature generation
+      attr_reader :profile
+
       # Wraps an outgoing request to add signature headers.
       #
       # Called automatically by http.rb for each request.
@@ -74,9 +83,11 @@ module Linzer
       # @param request [HTTP::Request] The outgoing request
       # @return [HTTP::Request] The request with signature headers added
       def wrap_request(request)
-        message   = Linzer::Message.new(request)
-        signature = Linzer.sign(key, message, fields, **params)
-        request.headers.merge!(signature.to_h)
+        Linzer.sign! request,
+                     key:        key,
+                     components: fields,
+                     params:     params,
+                     profile:    profile
         request
       end
 

data/lib/linzer/http/structured_field.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Linzer
+  module HTTP
+    # Utilities for serializing HTTP Structured Fields as defined in RFC 8941.
+    #
+    # This module currently provides helpers for serializing HTTP Message
+    # Signature parameters as used by RFC 9421.
+    #
+    # @see https://www.rfc-editor.org/rfc/rfc8941 RFC 8941
+    # @see https://www.rfc-editor.org/rfc/rfc9421 RFC 9421
+    module StructuredField
+      InnerList  = Starry::InnerList
+      Item       = Starry::Item
+
+      # Parses an RFC 8941 Structured Field Dictionary.
+      #
+      # @param str [String] the serialized dictionary value
+      # @param field_name [String, nil] optional field name for contextual errors
+      # @return [Hash<String, Object>] parsed structured field dictionary
+      # @raise [Linzer::Error] if the field cannot be parsed
+      #
+      # @see https://www.rfc-editor.org/rfc/rfc8941 RFC 8941
+      def self.parse_dictionary(str, field_name: nil)
+        Starry.parse_dictionary(str)
+      # rescue Starry::ParseError => ex
+      # https://github.com/takemar/starry/pull/4
+      rescue => ex
+        cannot_parse = "Cannot parse %sfield!"
+        raise Error,
+              cannot_parse % [field_name ? "\"#{field_name}\" " : nil],
+              cause: ex
+      end
+
+      # Parses an RFC 8941 Structured Field Item.
+      #
+      # @param item [String] serialized structured field item
+      # @return [Starry::Item] parsed structured field item
+      # @raise [Linzer::Error] if the item is invalid or unparseable
+      #
+      # @see https://www.rfc-editor.org/rfc/rfc8941 RFC 8941
+      def self.parse_item(item)
+        Starry.parse_item(item)
+      # rescue Starry::ParseError => ex
+      # https://github.com/takemar/starry/pull/4
+      rescue => ex
+        raise Error, "Invalid/unparseable HTTP field item", cause: ex
+      end
+
+      # Parses an RFC 8941 Structured Field List.
+      #
+      # @param list [String] serialized structured field list
+      # @return [Array<Object>] parsed structured field list members
+      # @raise [Linzer::Error] if the list is invalid or unparseable
+      #
+      # @see https://www.rfc-editor.org/rfc/rfc8941 RFC 8941
+      def self.parse_list(list)
+        Starry.parse_list(list)
+      # rescue Starry::ParseError => ex
+      # https://github.com/takemar/starry/pull/4
+      rescue => ex
+        raise Error, "Invalid/unparseable HTTP field list", cause: ex
+      end
+
+      # Serializes a dictionary into RFC 8941 Structured Field format.
+      #
+      # @param hsh [Hash] structured field dictionary
+      # @return [String] serialized structured field dictionary
+      # @raise [Linzer::Error] if the dictionary cannot be serialized
+      #
+      # @see https://www.rfc-editor.org/rfc/rfc8941 RFC 8941
+      def self.serialize_dictionary(hsh)
+        Starry.serialize_dictionary(hsh)
+      # rescue Starry::SerializeError => ex
+      # https://github.com/takemar/starry/pull/4
+      rescue => ex
+        raise Error, ex.message, cause: ex
+      end
+
+      # Serializes a list into RFC 8941 Structured Field format.
+      #
+      # @param arr [Array] structured field list members
+      # @return [String] serialized structured field list
+      # @raise [Linzer::Error] if the list cannot be serialized
+      #
+      # @see https://www.rfc-editor.org/rfc/rfc8941 RFC 8941
+      def self.serialize_list(arr)
+        Starry.serialize_list(arr)
+      # rescue Starry::SerializeError => ex
+      # https://github.com/takemar/starry/pull/4
+      rescue => ex
+        raise Error, ex.message, cause: ex
+      end
+
+      # Serializes an object into RFC 8941 Structured Field format.
+      #
+      # @param obj [Object] structured field value
+      # @return [String] serialized structured field value
+      # @raise [Linzer::Error] if the object cannot be serialized
+      #
+      # @see https://www.rfc-editor.org/rfc/rfc8941 RFC 8941
+      def self.serialize(obj)
+        Starry.serialize(obj)
+      rescue Starry::SerializeError => ex
+        raise Error, ex.message, cause: ex
+      end
+
+      # Serializes a Structured Field Item into RFC 8941 format.
+      #
+      # This helper serializes a single Structured Field Item, such as
+      # a string, integer, token, boolean, date, byte sequence, or
+      # an already constructed {Starry::Item}.
+      #
+      # @param item [Object] structured field item value
+      # @return [String] serialized structured field item
+      # @raise [Linzer::Error] if the item cannot be serialized
+      #
+      # @see https://www.rfc-editor.org/rfc/rfc8941 RFC 8941
+      def self.serialize_item(item)
+        Starry.serialize_item(item)
+      rescue Starry::SerializeError => ex
+        raise Error, ex.message, cause: ex
+      end
+
+      # Serializes Structured Field Parameters into RFC 8941 format.
+      #
+      # Parameters are serialized according to the Structured Fields
+      # parameter syntax defined in RFC 8941 Section 3.1.2.
+      #
+      # @param parameters [Hash{String,Symbol => Object}] parameter names
+      #   and values
+      # @return [String] serialized structured field parameters
+      # @raise [Linzer::Error] if the parameters cannot be serialized
+      #
+      # @see https://www.rfc-editor.org/rfc/rfc8941 RFC 8941
+      def self.serialize_parameters(parameters)
+        Starry.serialize_parameters(parameters)
+      # rescue Starry::SerializeError => ex
+      # https://github.com/takemar/starry/pull/4
+      rescue => ex
+        raise Error, ex.message, cause: ex
+      end
+    end
+  end
+end

data/lib/linzer/http.rb

@@ -100,12 +100,18 @@ module Linzer
 
       headers    = build_headers(options[:headers] || {})
       request    = build_request(verb, uri, headers)
-      message    = Linzer::Message.new(request)
       components = options[:covered_components] || default_components
       params     = options[:params] || {}
-      signature  = Linzer.sign(key, message, components, **params)
 
-      do_request(http, uri, verb, options[:data], signature, headers)
+      Linzer.sign! request,
+                   key:        key,
+                   components: components,
+                   params:     params,
+                   profile:    options[:profile]
+
+      signature_headers  = request.each_header.to_h.slice("signature-input", "signature")
+
+      do_request(http, uri, verb, options[:data], signature_headers, headers)
     end
 
     # Returns the default covered components for signing.
@@ -180,19 +186,19 @@ module Linzer
     # @param uri [String] the request URI
     # @param verb [Symbol] the HTTP method
     # @param data [String, nil] the request body
-    # @param signature [Linzer::Signature] the generated signature
+    # @param signature_headers [Hash] the generated signature headers
     # @param headers [Hash] request headers
     # @return [Net::HTTPResponse] the response
     # @raise [Linzer::Error] if a body is required but not provided
-    def do_request(http, uri, verb, data, signature, headers)
+    def do_request(http, uri, verb, data, signature_headers, headers)
       if with_body?(verb)
         if !data
           missed_body = "Missing request body on HTTP request: '#{verb.upcase}'"
           raise Linzer::Error, missed_body
         end
-        http.public_send(verb, uri, data, headers.merge(signature.to_h))
+        http.public_send(verb, uri, data, headers.merge(signature_headers))
       else
-        http.public_send(verb, uri,       headers.merge(signature.to_h))
+        http.public_send(verb, uri,       headers.merge(signature_headers))
       end
     end
   end

data/lib/linzer/jws.rb

@@ -101,18 +101,18 @@ module Linzer
         algo.verify(data: data, signature: signature, verification_key: verify_key)
       end
 
+      private
+
       # @return [Boolean] true if this key can verify signatures
-      def public?
+      def compute_public?
         !!verify_key
       end
 
       # @return [Boolean] true if this key can create signatures
-      def private?
+      def compute_private?
         !!signing_key
       end
 
-      private
-
       # Resolves the appropriate JWT algorithm implementation.
       # @return [JWT::JWA::SigningAlgorithm] The algorithm implementation
       # @raise [Error] If the algorithm cannot be determined

data/lib/linzer/key.rb

@@ -38,6 +38,8 @@ module Linzer
       @material = material
       @params   = Hash(params).clone.freeze
       validate
+      @is_private = compute_private?
+      @is_public  = compute_public?
       freeze
     end
 
@@ -84,14 +86,14 @@ module Linzer
     #
     # @return [Boolean] true if the key contains public key material
     def public?
-      material.public?
+      @is_public
     end
 
     # Checks if this key can be used for signing.
     #
     # @return [Boolean] true if the key contains private key material
     def private?
-      material.private?
+      @is_private
     end
 
     private
@@ -102,6 +104,22 @@ module Linzer
       !material.nil? or raise Error.new "Invalid key. No key material provided."
     end
 
+    # Computes whether the key contains private key material.
+    # Override in subclasses where the OpenSSL key object does not
+    # respond to +private?+ (e.g. Ed25519, RSA-PSS).
+    # @return [Boolean]
+    def compute_private?
+      material.respond_to?(:private?) ? material.private? : false
+    end
+
+    # Computes whether the key contains public key material.
+    # Override in subclasses where the OpenSSL key object does not
+    # respond to +public?+ (e.g. Ed25519, RSA-PSS).
+    # @return [Boolean]
+    def compute_public?
+      material.respond_to?(:public?) ? material.public? : false
+    end
+
     # Validates that a digest algorithm is configured.
     # @raise [Error] If no digest algorithm is set
     def validate_digest

data/lib/linzer/message/adapter/abstract.rb

@@ -70,7 +70,7 @@ module Linzer
         # @example With structured field parameter
         #   adapter['"example-dict";key="a"']  # => "1"
         def [](field)
-          field_id = field.is_a?(FieldId) ? field : parse_field_name(field)
+          field_id = (field.is_a?(FieldId) || field.is_a?(Field::FastIdentifier)) ? field : parse_field_name(field)
           return nil if field_id.nil? || field_id.item.nil?
           retrieve(field_id.item, field_id.derived? ? :derived : :field)
         end
@@ -97,26 +97,35 @@ module Linzer
         # Attaches a signature to the underlying HTTP message.
         #
         # @param signature [Signature] The signature to attach
+        # @param additional_headers [#each]
+        #   Additional headers to attach after signature processing.
+        #   Header values overwrite existing values with the same field name.
+        #
         # @return [Object] The underlying HTTP message
-        def attach!(signature)
+        def attach!(signature, additional_headers: {})
           signature_headers = signature.to_h
 
-          unless has_signature?
+          if !has_signature?
             signature_headers.each { |h, v| set_header!(h, v) }
-            return @operation
+          else
+            begin
+              signature_headers.each do |hdr, value|
+                merged = HTTP::StructuredField.parse_dictionary(String(header(hdr)))
+                merged.merge!(HTTP::StructuredField.parse_dictionary(value))
+                set_header!(hdr, HTTP::StructuredField.serialize_dictionary(merged))
+              end
+            rescue Error => ex
+              raise Error,
+                    "Cannot attach signature, invalid signature header(s)!",
+                    cause: ex
+            end
           end
 
-          signature_headers.each do |hdr, value|
-            merged = Starry.parse_dictionary(String(header(hdr)))
-            merged.merge!(Starry.parse_dictionary(value))
-            set_header!(hdr, Starry.serialize_dictionary(merged))
+          if !additional_headers.empty?
+            additional_headers.each { |h, v| set_header!(h, v) }
           end
 
           @operation
-        rescue Starry::ParseError => e
-          raise Error,
-                "Cannot attach signature, invalid signature header(s)!",
-                cause: e
         end
 
         private
@@ -190,18 +199,21 @@ module Linzer
         # @param method [Symbol] +:derived+ or +:field+
         # @return [String, Integer, nil] the component value
         def retrieve(name, method)
-          if !name.parameters.empty?
-            valid_params = validate_parameters(name, method)
-            return nil if !valid_params
-          end
+          # Fast path: no parameters means no special handling needed
+          return send(method, name) if name.parameters.empty?
+
+          valid_params = validate_parameters(name, method)
+          return nil if !valid_params
 
           has_req = name.parameters["req"]
           has_sf  = name.parameters["sf"] || name.parameters.key?("key")
           has_bs  = name.parameters["bs"]
 
           if has_req
-            name.parameters.delete("req")
-            return req(name, method)
+            request_field =
+              HTTP::StructuredField::Item.new(name.value,
+                                              name.parameters.except("req"))
+            return req(request_field, method)
           end
 
           value = send(method, name)
@@ -222,14 +234,16 @@ module Linzer
         # @return [String] the serialized structured field value
         # @see https://www.rfc-editor.org/rfc/rfc9421.html#section-2.1.1
         def sf(value, key = nil)
-          dict = Starry.parse_dictionary(value)
+          dict = HTTP::StructuredField.parse_dictionary(value)
 
           if key
             obj = dict[key]
-            Starry.serialize(obj.is_a?(Starry::InnerList) ? [obj] : obj)
+            HTTP::StructuredField.serialize(obj.is_a?(HTTP::StructuredField::InnerList) ? [obj] : obj)
           else
-            Starry.serialize(dict)
+            HTTP::StructuredField.serialize(dict)
           end
+        rescue Error => _ex
+          nil
         end
 
         # Binary-wraps a field value as a byte sequence.
@@ -238,7 +252,7 @@ module Linzer
         # @return [String] the serialized byte sequence
         # @see https://www.rfc-editor.org/rfc/rfc9421.html#section-2.1.3
         def bs(value)
-          Starry.serialize(value.encode(Encoding::ASCII_8BIT))
+          HTTP::StructuredField.serialize(value.encode(Encoding::ASCII_8BIT))
         end
 
         # Retrieves a trailer field value.

data/lib/linzer/message/adapter/generic/request.rb

@@ -72,6 +72,7 @@ module Linzer
           end
 
           def query_param(uri_query, name)
+            return nil if !uri_query
             param_name = name.parameters["name"]
             return nil if !param_name
             decoded_param_name = URI.decode_uri_component(param_name)

data/lib/linzer/message/adapter.rb

@@ -3,9 +3,6 @@
 require_relative "adapter/abstract"
 require_relative "adapter/generic/request"
 require_relative "adapter/generic/response"
-require_relative "adapter/rack/common"
-require_relative "adapter/rack/request"
-require_relative "adapter/rack/response"
 require_relative "adapter/net_http/request"
 require_relative "adapter/net_http/response"
 

data/lib/linzer/message/field/parser.rb

@@ -24,15 +24,15 @@ module Linzer
           def parse(field_name)
             case
             when field_name.match?(/";/), field_name.start_with?('"')
-              Starry.parse_item(field_name)
+              HTTP::StructuredField.parse_item(field_name)
             when field_name.match?(/;/)
               parse_unserialized_input(field_name)
             when field_name.start_with?("@"), field_name.match?(/^[a-z]/)
-              Starry.parse_item(Starry.serialize(field_name))
+              HTTP::StructuredField.parse_item(HTTP::StructuredField.serialize(field_name))
             else
               raise Error, "Invalid component identifier: '#{field_name}'!"
             end
-          rescue Starry::ParseError => ex
+          rescue Error => ex
             parse_error = "Failed to parse component identifier: '#{field_name}'!"
             raise Error, parse_error, cause: ex
           end
@@ -49,7 +49,7 @@ module Linzer
           # @return [Starry::Item] the parsed item with parameters
           def parse_unserialized_input(field_name)
             field, *raw_params = field_name.split(";")
-            item               = Starry.parse_item(Starry.serialize(field))
+            item               = HTTP::StructuredField.parse_item(HTTP::StructuredField.serialize(field))
             item.parameters    = collect_parameters(raw_params)
             item
           end
@@ -67,7 +67,7 @@ module Linzer
                 {param => true}
               else
                 Hash[*tokens.first(2)]                  # e.g.: ";key=\"foo\""
-                  .transform_values! { |v| Starry.parse_item(v).value }
+                  .transform_values! { |v| HTTP::StructuredField.parse_item(v).value }
               end
             end
             params.reduce({}, :merge)

data/lib/linzer/message/field.rb

@@ -34,7 +34,7 @@ module Linzer
         # @raise [Error] If the component identifier is invalid
         def serialize
           raise Error, "Invalid component identifier: '#{field_name}'!" unless item
-          Starry.serialize(@item)
+          @serialized || HTTP::StructuredField.serialize(@item)
         end
       end
 
@@ -54,6 +54,29 @@ module Linzer
 
       Identifier.include Message::Field::IdentifierMethods
 
+      # Lightweight FieldId for simple components (no parameters).
+      # Bypasses Starry parsing entirely. Duck-types with Identifier
+      # for use in the adapter's [] method.
+      # @api private
+      class FastIdentifier
+        def initialize(serialized, item)
+          @field_name = serialized
+          @item       = item
+          @serialized = serialized
+          freeze
+        end
+
+        attr_reader :field_name, :item
+
+        def derived?
+          @item.value.start_with?("@")
+        end
+
+        def serialize
+          @serialized
+        end
+      end
+
       class Identifier
         class << self
           # Serializes a single component identifier.
@@ -70,13 +93,42 @@ module Linzer
             components.map(&method(:serialize))
           end
 
+          # Serializes an array of component identifiers, returning both
+          # the serialized strings and the FieldId objects for reuse.
+          # @param components [Array<String>] Component names
+          # @return [Array(Array<String>, Array<Identifier>)] Serialized strings and FieldId objects
+          def serialize_components_with_field_ids(components)
+            serialized = Array.new(components.size)
+            field_ids  = Array.new(components.size)
+
+            components.each_with_index do |c, i|
+              if c.include?(";") || c.include?('"')
+                # Complex component with parameters or already serialized:
+                # fall back to full Starry parsing
+                fid = new(field_name: c)
+                field_ids[i]  = fid
+                serialized[i] = fid.serialize
+              else
+                # Simple component (e.g. "@method", "content-type"):
+                # build the Item and serialized string directly,
+                # bypassing Starry.parse_item + Starry.serialize
+                quoted = "\"#{c}\""
+                item   = HTTP::StructuredField::Item.new(c, {})
+                field_ids[i]  = FastIdentifier.new(quoted, item)
+                serialized[i] = quoted
+              end
+            end
+
+            [serialized, field_ids]
+          end
+
           # Deserializes component identifiers back to names.
           # @param components [Array<String>] Serialized identifiers
           # @return [Array<String>] Component names
           def deserialize_components(components)
             components.map do |c|
-              item = Starry.parse_item(c)
-              item.parameters.empty? ? item.value : Starry.serialize(item)
+              item = HTTP::StructuredField.parse_item(c)
+              item.parameters.empty? ? item.value : HTTP::StructuredField.serialize(item)
             end
           end
         end