API ideas

[oneiros]

I love how much consideration and hard work already went into this gem, but I cannot help to think it is bit too cumbersome to use 😕

Maybe I am missing a use case, but I mainly think of two:

1. I use a web framework (e.g. sinatra or rails) and want to verify incoming requests and/or sign outgoing responses.
2. I use an http library (e.g. net/http or httpx) to make requests and I want to sign those requests and/or verify the responses I get.

One thing those cases have in common is that the framework or library used has its own abstraction for requests and responses (e.g. sinatra has classes that inherit from Rack::Request and Rack::Response, rails has ActionDispatch::Request etc., net/http has Net::HTTPRequest and so on).

If I want to sign a request I currently need to:

1. Copy URI, method, headers (and possibly params, though that does not yet work currently) from the original request object.
2. User Linzer.new_request to create a Rack::Request object with the information gathered in 1.
3. Create a Linzer::Message from the request object created in 2.
4. Perform signing with the Linzer::Message object.
5. Copy the two resulting headers back into my original request object.

(The process for responses is quite similar.)

This is a 4-5 step process for something that from a developer's POV is a single operation: "Please sign this request."
Verification is quite similar.

All the frameworks and libraries mentioned above work quite similarly when it comes to requests and responses. Their respective objects do differ but at the end of the day there are only so many ways you can represent URIs, headers etc.

So I think it would be possible for linzer to ship with a tiny abstraction for these objects and pluggable adapters to work with all those different request and response objects. It could ship with support for maybe rack, rails and net/http and let users define their own adapters.

With that in place, the signing and verifying could then really be a single step each. Maybe with an API like this:

Linzer.sign!(
  request_or_response,
  key: my_key,
  components: %w[@method @target-uri content-digest],
  label: "sig1",
  params: {
    created: Time.now.to_i
  }
)

request_or_response is one of the supported request or response objects. key is mandatory, but all the other parameters can have sensible defaults.

Verification needs a way to retrieve a key for the given keyid. I thought that maybe it could use a block for that:

Linzer.verify(request_or_response) do |keyid|
  # Retrieve and return the matching key
end

I also have some ideas of how key handling could be a bit simpler, but I wanted to get this out of the way first.

Please let me know what you think. I am happy to prototype this idea a bit further and submit a PR if you think it could work.

[nomadium]

Thanks for the feedback. In general, I agree with you @oneiros, on its present state linzer is not ready yet as its a little cumbersome to use as you mentioned, since I started by focusing a lot on the concepts from the RFC.

I think in its current state linzer is just providing basic building blocks but is still missing a nicer and easy to use API to sign and verify HTTP requests.

I was planning to move on that direction earlier this year but got sidetracked, however I think this is a perfect time to polish this gem and get it closer to 1.0 and real users.

I'd be more than happy to work with you and/or folks interested on contributing and improving its API.

[nomadium]

A quick update on this issue:

I worked a little on use case 1. (use a web framework on the server side) recently and introduced a Rack middleware to effortlessly verify incoming requests. With that feature, the typical developer should not be concerned with verifying requests directly (although they still can do it, if they have the need or use-case), they should mostly include the middleware (example) and provide an optional configuration file if they want to customise or override (although the defaults should be sane enough). Any feedback on this is more than welcome @oneiros.

On the use case 2. (to sign outgoing requests and responses), I plan to work on a prototype soon to improve that area as well.

[oneiros]

Wow, that rack middleware looks really cool! Definitely a nice improvement.

That being said, I will probably not be able to use it, because for my use cases (and I imagine many others as well), being limited to a static list of acceptable keys will not work. In both my use cases, keys are being fetched from a database.

It might be possible to add an option to the middleware that takes a Proc as an argument and passes the keyid to the proc to retrieve the matching key (somewhat similar to the idea I sketched above).

That might work for one of my uses cases, but not the other. There we use Message Signatures to secure an API and use it for authentication at the same time. So after successful verification of a signature, we know which user made the request and need to access that info in the application code.

But I guess this is a general problem with HTTP Message Signatures: They look like a protocol-level concern on the surface, but in many slightly more complex implementations they are actually also an application-level concern 🤷‍♂

[nomadium]

It might be possible to add an option to the middleware that takes a Proc as an argument and passes the keyid to the proc to retrieve the matching key (somewhat similar to the idea I sketched above).

That's right. I imagined that potential users running real-world apps will operate keeping the key data in databases and/or caches. The new middleware can take a block to customize/override or expand any aspect of how access control is performed (including from where/how keys are retrieved). Probably I need to improve the docs to make it clearer but is already supported.

Something like the following should be possible:

use Rack::Auth::Signature, config_path: "app/config/linzer.yml" do
  def key
    key_id = params["keyid"]
    key_data = db_client.call("GET", keyid)
    # instantiate and return the key object
  end
end

That might work for one of my uses cases, but not the other. There we use Message Signatures to secure an API and use it for authentication at the same time. So after successful verification of a signature, we know which user made the request and need to access that info in the application code.

But I guess this is a general problem with HTTP Message Signatures: They look like a protocol-level concern on the surface, but in many slightly more complex implementations they are actually also an application-level concern 🤷‍♂

I agree, this is a reason why the initial version of the feature I mentioned just passes the signature object to the app for business-logic specific checks to be performed but I'm not sure yet if that's going to be enough or maybe the signature object that rack passes to the app should be augmented to be more useful to the typical app or API endpoint.

[nomadium]

@oneiros I just released a stable version for Linzer during the weekend, see: https://rubygems.org/gems/linzer/versions/0.7.1. 😀

Once you have a chance to test it, I'd appreciate feedback if you still consider this issue should remain open or can be closed, thanks!

[oneiros]

I am currently trying it out. I already love how some things become so much simpler! I found a smaller issue I will post later, but when it comes to this issue here, I think everything is done. Thank you so much!