New Features¶ ↑

The hmac_paths plugin allows protection of paths using an HMAC. This can be used to prevent users enumerating paths, since only paths with valid HMACs will be respected.

To use the plugin, you must provide a :secret option. This sets the secret for the HMACs. Make sure to keep this value secret, as this plugin does not provide protection against users who know the secret value. The secret must be at least 32 bytes.
```
plugin :hmac_paths, secret: 'some-secret-value-with-at-least-32-bytes'
```
To generate a valid HMAC path, you call the hmac_path method:
```
hmac_path('/widget/1')
# => "/0c2feaefdfc80cc73da19b060c713d4193c57022815238c6657ce2d99b5925eb/0/widget/1"
```
The first segment in the returned path is the HMAC. The second segment is flags for the type of paths (see below), and the rest of the path is as given.

To protect a path or any subsection in the routing tree, you wrap the related code in an r.hmac_path block.
```
route do |r|
  r.hmac_path do
    r.get 'widget', Integer do |widget_id|
      # ...
    end
  end
end
```
If first segment of the remaining path contains a valid HMAC for the rest of the path (considering the flags), then r.hmac_path will match and yield to the block, and routing continues inside the block with the HMAC and flags segments removed.

In the above example, if you provide a user a link for widget with ID 1, there is no way for them to guess the valid path for the widget with ID 2, preventing a user from enumerating widgets, without relying on custom access control. Users can only access paths that have been generated by the application and provided to them, either directly or indirectly.

In the above example, r.hmac_path is used at the root of the routing tree. If you would like to call it below the root of the routing tree, it works correctly, but you must pass hmac_path the :root option specifying where r.hmac_paths will be called from. Consider this example:
```
route do |r|
  r.on 'widget' do
    r.hmac_path do
      r.get Integer do |widget_id|
        # ...
      end
    end
  end

  r.on 'foobar' do
    r.hmac_path do
      r.get Integer do |foobar_id|
        # ...
      end
    end
  end
end
```
For security reasons, the hmac_path plugin does not allow an HMAC path designed for widgets to be a valid match in the r.hmac_path call inside the “r.on ‘foobar’” block, preventing users who have a valid HMAC for a widget from looking at the page for a foobar with the same ID. When generating HMAC paths where the matching r.hmac_path call is not at the root of the routing tree, you must pass the :root option:
```
hmac_path('/1', root: '/widget')
# => "/widget/daccafce3ce0df52e5ce774626779eaa7286085fcbde1e4681c74175ff0bbacd/0/1"

hmac_path('/1', root: '/foobar')
# => "/foobar/c5fdaf482771d4f9f38cc13a1b2832929026a4ceb05e98ed6a0cd5a00bf180b7/0/1"
```
Note how the HMAC changes even though the path is the same.

In addition to the :root option, there are additional options that further constrain use of the generated paths.

The :method option creates a path that can only be called with a certain request method:
```
hmac_path('/widget/1', method: :get)
# => "/d38c1e634ecf9a3c0ab9d0832555b035d91b35069efcbf2670b0dfefd4b62fdd/m/widget/1"
```
Note how this results in a different HMAC than the original hmac_path(‘/widget/1’) call. This sets the flags segment to “m”, which means r.hmac_path will consider the request mehod when checking the HMAC, and will only match if the provided request method is GET. This allows you to provide a user the ability to submit a GET request for the underlying path, without providing them the ability to submit a POST request for the underlying path, with no other access control.

The :params option accepts a hash of params, converts it into a query string, and includes the query string in the returned path. It sets the flags segment to p, which means r.hmac_path will check for that exact query string. Requests with an empty query string or a different string will not match.
```
hmac_path('/widget/1', params: {foo: 'bar'})
# => "/fe8d03f9572d5af6c2866295bd3c12c2ea11d290b1cbd016c3b68ee36a678139/p/widget/1?foo=bar"
```
For GET requests, which cannot have request bodies, that is sufficient to ensure that the submitted params are exactly as specified. However, POST requests can have request bodies, and request body params override query string params in r.params. So if you are using this for POST requests (or other HTTP verbs that can have request bodies), use r.GET instead of r.params to specifically check query string parameters.

You can use :root, :method, and :params at the same time:
```
hmac_path('/1', root: '/widget', method: :get, params: {foo: 'bar'})
# => "/widget/9169af1b8f40c62a1c2bb15b1b377c65bda681b8efded0e613a4176387468c15/mp/1?foo=bar"
```
This gives you a path only valid for a GET request with a root of “/widget” and a query string of “foo=bar”.

To handle secret rotation, you can provide an :old_secret option when loading the plugin.
```
plugin :hmac_paths, secret: 'some-secret-value-with-at-least-32-bytes',
                    old_secret: 'previous-secret-value-with-at-least-32-bytes'
```
This will use :secret for constructing new paths, but will respect paths generated by :old_secret.

Other Improvements¶ ↑

When not using cached templates in the render plugin, the render plugin now has better handling when a template is modified and results in an error. Previously, the error would be raised on the first request after the template modification, but subsequent requests would use the previous template value. The render plugin will no longer update the last modified time in this case, so if a template is modified and introduces an error (e.g. SyntaxError in an erb template), all future requests that use the template will result in the error being raised, until the template is fixed.

Backwards Compatibility¶ ↑

The internal TemplateMtimeWrapper API has been modified. As documented, this is an internal class and the API can change in any Roda version. However, if any code was relying on the previous implementation of TemplateMtimeWrapper#modified?, it will need to be modified, as that method has been replaced with TemplateMtimeWrapper#if_modified.

Additionally, the TemplateMtimeWrapper#compiled_method_lambda API has also changed.

3.79.0.txt

New Features¶ ↑

Other Improvements¶ ↑

Backwards Compatibility¶ ↑