linzer 0.7.9.beta1 → 0.7.9.beta3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e68e3de6c89b69da86e383a47e365ab275597440ac71ffb6ce261cd10ad9f51
-  data.tar.gz: d036d8264a8bba7a7d964432e187725da146f228ee81335d3db5c3659d1578ee
+  metadata.gz: d39f9d5f600453197afb744fc030afc2325f40d580540f9fbbca2ba81e0275e2
+  data.tar.gz: 0ab05a81ade047eb116e0527c8647bce22008a04684b6dae5bdd37a9441b0fa8
 SHA512:
-  metadata.gz: b635cf2b46a0235a7e4131719b225df2a8c03b689c175baf4d9d234dcb1e1ad9f2b4ad1b52da19296444e2883064dbf11e69509ebce96695e3ee51fe7aa31f45
-  data.tar.gz: 729797295ce7a27128046cd6ae9714d0a74e6ba64f3db74e9f4fe48106548fd911c60a2f9442e387a5a04e82c54644294587f5b61e2d3aaa21d6a09aa5e1681e
+  metadata.gz: 52adbd0af86067b700fd60e2666675134bf58a8ed611b60087ecd3c74da64b50f83232271e4a8a4c2af6162558fd880598fb15af6cd201f9621ff4cd976bbdc5
+  data.tar.gz: b351287249fb050bb06bc08a5312b24bf9876dc555fd7c2ee69edbab15e0b43bec5d0cbc3ab852c1766c2eede159a1bd8c6c2ba963558e308b2ec7e73ad469d5

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [Unreleased]
 
+## [0.7.9.beta3] - 2026-04-27
+
+- Enforce `expires` signature parameter validation in Verifier.
+
+- Add Faraday middleware and adapters for HTTP message signatures.
+
+## [0.7.9.beta2] - 2026-04-19
+
+- Add support for http gem 6.x while maintaining compatibility with 5.x.
+  Handles API differences introduced in 6.0.
+- Improve README clarity and align it with current behavior and production usage.
+
 ## [0.7.9.beta1] - 2026-03-03
 
 (Beta release to test gem release automation; no functional changes)

data/README.md

@@ -9,7 +9,12 @@
 [rubydoc-badge]: https://img.shields.io/badge/docs-RubyDoc.info-blue
 [rubydoc-link]: https://www.rubydoc.info/gems/linzer
 
-Linzer is a Ruby library for [HTTP Message Signatures (RFC 9421)](https://www.rfc-editor.org/rfc/rfc9421.html).
+Linzer is a Ruby library for [HTTP Message Signatures (RFC 9421)](https://www.rfc-editor.org/rfc/rfc9421.html),
+allowing you to sign and verify HTTP requests and responses with
+standard-compliant cryptographic signatures.
+
+Useful for APIs, webhooks, and services that need to verify request
+authenticity or prevent tampering.
 
 ## Install
 
@@ -23,48 +28,92 @@ Or just `gem install linzer`.
 
 ## Usage
 
-### TL;DR: I just want to protect my application!!
+### Quick start
+
+- To sign/verify HTTP requests and responses, see the
+[Signing Requests](#signing-http-requests-and-responses) and
+[Verifying HTTP signatures](#verifying-http-signatures) or
+[Verifying responses (client-side)](#verifying-responses-client-side)
+sections.
+
+- For a more hands-off approach to enforcing request authentication
+  with HTTP signatures in Rack applications (such as Rails),
+  see the examples in the next section.
+
+### Rack middleware
 
-Add the following middleware to your Rack application and configure it
-as needed, e.g.:
+Add the middleware to your Rack application:
 
 ```ruby
 # config.ru
-use Rack::Auth::Signature, except: "/login",
-  default_key: {material: Base64.strict_decode64(ENV["MYAPP_KEY"]), alg: "hmac-sha256"}
-  # or: default_key: {material: IO.read("app/config/pubkey.pem"), "ed25519"}
+use Rack::Auth::Signature,
+  except: "/login",
+  default_key: {
+    material: Base64.strict_decode64(ENV["MYAPP_KEY"]),
+    alg: "hmac-sha256"
+  }
+  # or using a public/private key pair:
+  # default_key: { material: IO.read("app/config/pubkey.pem"), alg: "ed25519" }
 ```
 
-or on more complex scenarios:
+In this example, the middleware requires a valid HTTP Message Signature
+for all endpoints except /login.
+
+#### Using a configuration file
+
+For more complex setups, you can load configuration from a file, e.g.:
 
 ```ruby
 # config.ru
-use Rack::Auth::Signature, except: "/login",
+use Rack::Auth::Signature,
+  except: "/login",
   config_path: "app/configuration/http-signatures.yml"
 ```
 
-or with a typical Rails application:
+#### Rails
+
+In a Rails application, add the middleware in your configuration:
 
 ```ruby
 # config/application.rb
-config.middleware.use Rack::Auth::Signature, except: "/login",
+config.middleware.use Rack::Auth::Signature,
+  except: "/login",
   config_path: "http-signatures.yml"
 ```
 
-And that's it, all routes in the example app (except `/login`) above will
-require a valid signature created with the respective private key held by a
-client. For more details on what configuration options are available, take a
-look at
-[examples/sinatra/http-signatures.yml](https://github.com/nomadium/linzer/tree/master/examples/sinatra/http-signatures.yml) to get started and/or
-[lib/rack/auth/signature.rb](https://github.com/nomadium/linzer/tree/master/lib/rack/auth/signature.rb) for full implementation details.
+#### What this does?
+
+Once enabled, all protected routes will require a valid signature
+generated by a client using the corresponding private key. Requests
+without a valid signature will be rejected.
+
+#### Next steps
+
+- See how to [sign HTTP messages](#signing-http-requests-and-responses)
+or [verify HTTP requests and responses](#verifying-responses-client-side).
+
+- See a full configuration example:
+[examples/sinatra/http-signatures.yml](https://github.com/nomadium/linzer/tree/master/examples/sinatra/http-signatures.yml)
+
+- Browse the Rack middleware implementation for all options:
+[lib/rack/auth/signature.rb](https://github.com/nomadium/linzer/tree/master/lib/rack/auth/signature.rb)
+
+- For more specific scenarios and use cases, continue below.
+
+### Signing HTTP requests and responses
 
-To learn about more specific scenarios or use cases, keep reading on below.
+Linzer signs HTTP requests by adding the required `Signature` and
+`Signature-Input` headers based on selected request components (e.g.
+method, path, headers, etc).
 
-### To sign a HTTP request:
+Choose your client:
 
-There are several options:
+- Use the [http gem](https://github.com/httprb/http) → recommended (simplest)
+- Use Faraday and the provided middleware → also recommended (very simple)
+- Use `Net::HTTP` → lower-level control
+- Use `Linzer::HTTP` → quick experiments / debugging
 
-#### If you are using http gem:
+#### Using [http gem](https://github.com/httprb/http)
 
 ```ruby
 # first require http signatures feature class ready to be used with http gem:
@@ -85,7 +134,36 @@ response.body.to_s
 => "protected content..."
 ```
 
-#### If you are using plain old Net::HTTP:
+#### Using Faraday
+
+Linzer ships Faraday middleware for signing outbound requests and verifying
+signed responses.
+
+To sign requests:
+
+```ruby
+require "linzer/faraday"
+
+api_url = "https://example.com/api/service"
+components = %w[@target-uri @authority date cache-control]
+signature_params = {alg: "rsa-pss-sha512", keyid: "test-key-rsa-pss",
+                    expires: Time.now.to_i + 300}
+
+conn = Faraday.new(url: api_url) do |builder|
+  builder.headers["Cache-control"] = "no-cache"
+  builder.headers["Date"] = Time.now.httpdate
+  builder.request :http_signature, key: signing_key,
+                                   components: components,
+                                   params: signature_params
+end
+response = conn.post("/task")
+```
+
+This signs the request automatically before dispatch. In this example,
+`Date` and `Cache-Control` are included in the signature to protect
+freshness-related metadata from modification.
+
+#### Using `Net::HTTP` (manual control)
 
 ```ruby
 key = Linzer.generate_ed25519_key
@@ -111,7 +189,7 @@ request["signature-input"]
 # => "sig1=(\"@method\" \"@request-target\" \"date\" ..."}
 ```
 
-Then you can submit the signed request with Net::HTTP client:
+Then send the request:
 
 ```ruby
 require "net/http"
@@ -152,10 +230,7 @@ response = http.request(request)
 # => #<Net::HTTPOK 200 OK readbody=true>
 ```
 
-#### Or you can also use the simple HTTP client bundled with this library:
-
-(This client is probably not suitable for production use but could be useful
-enough to get started. It's build on top of Net::HTTP.)
+#### Using the built-in client
 
 ```ruby
 key = Linzer.generate_rsa_pss_sha512_key(4096)
@@ -172,13 +247,62 @@ response =
 => #<Net::HTTPOK 200 OK readbody=true>
 ```
 
-### To verify an incoming request on the server side:
+(This client is intended for testing and exploration.
+For production use, prefer a full-featured HTTP client).
 
-The middleware `Rack::Auth::Signature` can be used for this scenario
-[as shown above](#tldr-i-just-want-to-protect-my-application).
+#### Signing HTTP responses (server-side)
 
-Or directly in the application controller (or routes), the incoming request can
-be verified with the following approach:
+You can sign responses using the same API as for requests, e.g.:
+
+```ruby
+put "/baz" do
+  ...
+  response
+  # => #<Sinatra::Response:0x0000000109ac40b8 ...
+  response.headers["x-custom-app-header"] = "..."
+  Linzer.sign!(response,
+    key: my_key,
+    components: %w[@status content-type content-digest x-custom-app-header],
+    label: "sig1",
+    params: {
+      created: Time.now.to_i
+    }
+  )
+  response["signature"]
+  # => "sig1=:2TPCzD4l48bg6LMcVXdV9u..."
+  response["signature-input"]
+  # => "sig1=(\"@status\" \"content-type\" \"content-digest\"..."
+  ...
+end
+```
+
+### Verifying HTTP signatures
+
+Linzer verifies incoming requests (or responses) by checking:
+
+- the signature is valid for the given key
+- the signed components match the actual request
+- any signature parameters (e.g. created, expires) are valid
+
+If verification fails, an exception is raised explaining the reason.
+
+#### Recommended: Rack middleware
+
+The easiest way to verify incoming requests is via middleware:
+
+```ruby
+use Rack::Auth::Signature, except: "/login"
+```
+
+This automatically:
+
+- verifies all incoming requests
+- rejects invalid or unsigned requests
+- integrates cleanly with Rack-based frameworks (Rails, Sinatra, etc.)
+
+#### Manual verification (controller / route level)
+
+If you need more control, you can verify incoming requests manually:
 
 ```ruby
 post "/foo" do
@@ -190,18 +314,31 @@ post "/foo" do
   #   "PATH_INFO" => "/api",
   # ...
 
-  result = Linzer.verify!(request, key: some_client_key)
+  result = Linzer.verify!(request, key: some_client_key) rescue false
   # => true
   ...
+  # proceed with trusted request
+end
+```
+
+If the signature is missing or invalid, verify! will raise an exception.
+
+```ruby
+head "/bar" do
+  begin
+    Linzer.verify!(request, key: key)
+  rescue Linzer::VerifyError => e
+    halt 401, e.message
+  end
 end
 ```
 
-If the signature is missing or invalid, the verification method will raise an
-exception with a message clarifying why the request signature failed verification.
+#### Dynamic key lookup
+
+In many cases, the verification key depends on the `keyid` parameter
+provided in the signature.
 
-Also, for additional flexibility on the server side, the method above can take
-a block with the `keyid` parameter extracted from the signature (if any) as argument.
-This can be useful to retrieve key data from databases/caches on the server side, e.g.:
+You can supply a block to resolve keys dynamically:
 
 ```ruby
 get "/bar" do
@@ -211,14 +348,22 @@ get "/bar" do
   end
   # => true
   ...
+  # request is now verified
 end
 ```
 
-### To verify a received response on the client side:
+This is useful when:
+
+- you have multiple clients
+- keys are stored in a database or external service
+- keys rotate over time
+
+#### Verifying responses (client-side)
 
-It's similar to verifying requests, the same method is used, see example below:
+As expected, signed responses are verified using the same API shown previously:
 
 ```ruby
+...
 response
 # => #<Net::HTTPOK 200 OK readbody=true>
 response.body
@@ -228,43 +373,60 @@ result = Linzer.verify!(response, key: pubkey, no_older_than: 600)
 # => true
 ```
 
-### To sign an outgoing response on the server side:
-
-Again, the same principle used to sign outgoing requests, the same method is used,
-see example below:
+Or if you are using Faraday, response verification can be handled by
+middleware as well:
 
 ```ruby
-put "/baz" do
-  ...
-  response
-  # => #<Sinatra::Response:0x0000000109ac40b8 ...
-  response.headers["x-custom-app-header"] = "..."
-  Linzer.sign!(response,
-    key: my_key,
-    components: %w[@status content-type content-digest x-custom-app-header],
-    label: "sig1",
-    params: {
-      created: Time.now.to_i
-    }
-  )
-  response["signature"]
-  # => "sig1=:2TPCzD4l48bg6LMcVXdV9u..."
-  response["signature-input"]
-  # => "sig1=(\"@status\" \"content-type\" \"content-digest\"..."
-  ...
+require "linzer/faraday"
+
+...
+
+conn = Faraday.new(url: api_url) do |builder|
+  builder.response :http_signature, key: verify_key
 end
+response = conn.post("/task")
+
+response.env[:http_signature_verified]
+# => true
+
+response.env[:http_signature]
+# => #<Linzer::Signature ...>
 ```
 
-### What do you do if you want to sign/verify requests and responses with your preferred HTTP ruby library/framework (not using Rack or `Net::HTTP`, for example)?
+After verification, the middleware stores:
+
+- `env[:http_signature_verified]` — whether verification succeeded
+
+- `env[:http_signature]` — the parsed `Linzer::Signature` object (when valid)
+
+Verification failures can optionally raise instead of returning status;
+see middleware options below.
+
+### Using a custom HTTP library
+
+If you are using another HTTP library, you may not need a custom Linzer
+adapter at all. Because Linzer integrates with Faraday middleware, you can
+often use Faraday together with the appropriate Faraday adapter for your
+HTTP client of choice.
 
-You can provide an adapter class and then register it with this library.
-For guidance on how to implement such adapters, you can consult an
-[example adapter for http gem response](https://github.com/nomadium/linzer/blob/master/lib/linzer/message/adapter/http_gem/response.rb)
-included with this gem or the ones
-[provided out of the box](https://github.com/nomadium/linzer/blob/master/lib/linzer/message/adapter).
+If you need tighter integration or are not using Faraday, you can also
+implement a native Linzer adapter directly.
 
-For how to register a custom adapter and how to verify signatures in a response,
-see this example:
+In most cases, implementing an adapter just means mapping your library's
+request/response objects to the small interface Linzer expects, then
+registering it.
+
+To do this:
+
+- implement a simple adapter for your request/response objects
+- register it with `Linzer::Message`
+
+You can use the existing adapters as references:
+
+- [HTTP gem response adapter](https://github.com/nomadium/linzer/blob/master/lib/linzer/message/adapter/http_gem/response.rb)
+- [Built-in adapters](https://github.com/nomadium/linzer/blob/master/lib/linzer/message/adapter)
+
+Example of how to register an adapter before using a custom HTTP library:
 
 ```ruby
 Linzer::Message.register_adapter(HTTP::Response, Linzer::Message::Adapter::HTTPGem::Response)
@@ -278,89 +440,96 @@ response["signature-input"]
 result = Linzer.verify!(response, key: my_key)
 # => true
 ```
----
 
-Furthermore, on some low-level scenarios where a user wants or needs additional
-control on how the signing and verification routines are performed, Linzer allows
-to manipulate instances of internal HTTP messages (requests & responses, see
-`Linzer::Message` class and available adapters), signature objects
-(`Linzer::Signature`) and how to register additional message adapters for any
-HTTP ruby library not supported out of the box by this gem.
+### Advanced verification
 
-See below for a few examples of these scenarios.
+For low-level control over signing and verification, Linzer
+exposes internal message and signature objects. This allows
+you to work directly with `Linzer::Message` and `Linzer::Signature`,
+or integrate custom HTTP adapters if needed.
 
-#### To verify a valid signature:
+#### Verifying a signature manually
 
 ```ruby
 test_ed25519_key_pub = key.material.public_to_pem
-# => "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAK1ZrC4JqC356pRsUiLVJdFZ3dAjo909VfWs1li33MCQ=\n-----END PUBLIC KEY-----\n"
+# => "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAK1ZrC4JqC356pRs..."
 
 pubkey = Linzer.new_ed25519_public_key(test_ed25519_key_pub, "some-key-ed25519")
 # => #<Linzer::Ed25519::Key:0x00000fe19b9384b0
 
 message = Linzer::Message.new(request)
 
-signature = Linzer::Signature.build(message.headers)
+signature = Linzer::Signature.build(request.headers)
 
 Linzer.verify(pubkey, message, signature)
 # => true
 ```
 
-To mitigate the risk of "replay attacks" (i.e. an attacker capturing a message with a valid signature and re-sending it at a later point) applications may want to validate the `created` parameter of the signature. Linzer can do this automatically when given the optional `no_older_than` keyword argument:
-
-```ruby
-Linzer.verify(pubkey, message, signature, no_older_than: 500)
-```
+#### Preventing replay attacks
 
-`no_older_than` expects a number of seconds, but you can pass anything that to responds to `#to_i`, including an `ActiveSupport::Duration`.
-`::verify` will raise if the `created` parameter of the signature is older than the given number of seconds.
+To reduce the risk of replay attacks (e.g. reusing a captured
+valid request), you can validate the `created` timestamp in the signature.
 
-#### What if an invalid signature if verified?
+Linzer supports this via the `no_older_than` option:
 
 ```ruby
-result = Linzer.verify(pubkey, message, signature)
-lib/linzer/verifier.rb:38:in `verify_or_fail': Failed to verify message: Invalid signature. (Linzer::Error)
+Linzer.verify(pubkey, message, signature, no_older_than: 500)
 ```
 
-#### HTTP responses are also supported
+`no_older_than` expects a number of seconds, but you can pass
+anything that to responds to `#to_i`, including an `ActiveSupport::Duration`.
 
-HTTP responses can also be signed and verified in the same way as requests.
+If the signature is older than the allowed window, verification
+fails with an error.
 
-```ruby
-headers = {
-  "date" => "Sat, 30 Mar 2024 21:40:13 GMT",
-  "x-response-custom" => "bar"
-}
+## Supported algorithms
 
-response = Linzer.new_response("request body", 200, headers)
-# or just use the response object exposed by your HTTP framework
+Linzer currently supports the following signature algorithms:
 
-message = Linzer::Message.new(response)
-fields  = %w[@status date x-response-custom]
+- RSASSA-PSS (SHA-512)
+- RSASSA-PKCS1-v1_5 (SHA-256)
+- HMAC-SHA256
+- Ed25519
+- ECDSA (P-256 and P-384 curves).
 
-signature = Linzer.sign(key, message, fields)
+Of the JSON Web Signature (JWS) algorithms mentioned in RFC 9421,
+only Ed25519 is currently supported. Support for additional
+algorithms is planned and should be straightforward to add.
 
-pp signature.to_h
-# => {"signature"=>
-#   "sig1=:tCldwXqbISktyABrmbhszo...",
-#  "signature-input"=>"sig1=(\"@status\" \"date\" ..."}
+The goal is to support as much of the RFC as possible before the 1.0 release.
 
-```
-
-For now, to consult additional details just take a look at source code and/or the unit tests.
+## Documentation
 
-Please note that is still early days and extensive testing is still ongoing. For now the following algorithms are supported: RSASSA-PSS using SHA-512, RSASSA-PKCS1-v1_5 using SHA-256, HMAC-SHA256, Ed25519 and ECDSA (P-256 and P-384 curves). JSON Web Signature (JWS) algorithms mentioned in the RFC are not supported yet.
+The codebase is well-documented, and the Ruby API documentation is
+available on [Rubydoc](https://www.rubydoc.info/gems/linzer).
 
-I'll be expanding the library to cover more functionality specified in the RFC
-in subsequent releases.
+For deeper details or edge cases, the source code and unit tests are also a good reference.
 
 ## Ruby version compatibility
 
 linzer is built in [Continuous Integration](https://github.com/nomadium/linzer/actions/workflows/main.yml) on Ruby 3.0+.
 
+> [!NOTE]
+>
+> Ruby 3.0 is supported and tested in CI, but RSA-based signature algorithms
+> (RSA-PSS and RSA PKCS#1 v1.5) may not work correctly due to its older
+> OpenSSL bindings. If you need RSA algorithms, use Ruby 3.1 or later.
+> Ruby 3.0 has been EOL since March 2024 — users are advised to upgrade
+> to a supported Ruby release.
+
 ## Security
 
-This gem is provided “as is” without any warranties. It has not been audited for security vulnerabilities. Users are advised to review the code and assess its suitability for their use case, particularly in production environments.
+This gem is provided “as is” without any warranties. It has not
+been independently audited for security vulnerabilities. Users
+are advised to review the code and assess its suitability for their
+use case, particularly in production environments.
+
+Despite this, Linzer is already used in production by other projects
+with security-sensitive requirements, including
+[Mastodon](https://github.com/mastodon/mastodon)
+([since version 4.5.0](https://docs.joinmastodon.org/spec/security/#http-message-signatures)).
+This does not constitute a security guarantee or endorsement,
+but it may be useful context when evaluating adoption.
 
 ## Development
 

data/flake.lock

@@ -2,7 +2,9 @@
   "nodes": {
     "bundix": {
       "inputs": {
-        "nixpkgs": "nixpkgs"
+        "nixpkgs": [
+          "nixpkgs"
+        ]
       },
       "locked": {
         "lastModified": 1762235257,
@@ -20,25 +22,11 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1761880412,
-        "narHash": "sha256-QoJjGd4NstnyOG4mm4KXF+weBzA2AH/7gn1Pmpfcb0A=",
+        "lastModified": 1775710090,
+        "narHash": "sha256-ar3rofg+awPB8QXDaFJhJ2jJhu+KqN/PRCXeyuXR76E=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "a7fc11be66bdfb5cdde611ee5ce381c183da8386",
-        "type": "github"
-      },
-      "original": {
-        "id": "nixpkgs",
-        "type": "indirect"
-      }
-    },
-    "nixpkgs_2": {
-      "locked": {
-        "lastModified": 1770115704,
-        "narHash": "sha256-KHFT9UWOF2yRPlAnSXQJh6uVcgNcWlFqqiAZ7OVlHNc=",
-        "owner": "NixOS",
-        "repo": "nixpkgs",
-        "rev": "e6eae2ee2110f3d31110d5c222cd395303343b08",
+        "rev": "4c1018dae018162ec878d42fec712642d214fdfa",
         "type": "github"
       },
       "original": {
@@ -48,31 +36,19 @@
         "type": "github"
       }
     },
-    "nixpkgs_3": {
-      "locked": {
-        "lastModified": 1678875422,
-        "narHash": "sha256-T3o6NcQPwXjxJMn2shz86Chch4ljXgZn746c2caGxd8=",
-        "owner": "NixOS",
-        "repo": "nixpkgs",
-        "rev": "126f49a01de5b7e35a43fd43f891ecf6d3a51459",
-        "type": "github"
-      },
-      "original": {
-        "id": "nixpkgs",
-        "type": "indirect"
-      }
-    },
     "root": {
       "inputs": {
         "bundix": "bundix",
-        "nixpkgs": "nixpkgs_2",
+        "nixpkgs": "nixpkgs",
         "ruby-nix": "ruby-nix",
         "systems": "systems"
       }
     },
     "ruby-nix": {
       "inputs": {
-        "nixpkgs": "nixpkgs_3"
+        "nixpkgs": [
+          "nixpkgs"
+        ]
       },
       "locked": {
         "lastModified": 1755059052,