This commit mitigates rate limit bypasses in the configuration
docs by normalizing the email throttle key. (The normalization process
used is the same as used by the Clearance gem.)
---
Often an authentication process normalizes email addresses and usernames
before look up, say by downcasing and removing any whitespace.
Throttles that do not perform the same normalization are vulnerable
to rate limit bypasses.
For example, an attacker can bypass a vulnerable throttle by using
unlimited case and whitespace variants for the same email address:
- Variant 1: `victim@example.org`
- Variant 2: `victim@example. org` (one whitespace)
- Variant 3: `victim@example. org` (two whitespaces)
- Variant 4: `ViCtIm@eXaMpLe.org`
- etc, etc.
All of these variants resolve to the same email address, but allow
an attacker to bypass a vulnerable throttle. To mitigate, the email
throttle key should be normalized using the same logic the
authentication process uses for normalizing emails.
* Clarify Calling HTTP_ header in example
In trying to track down a bug here turns out I was trying to reference the wrong header shown in the readme.
Printing our `request.env` it becomes clear this is just the full request object:
```
{"rack.version"=>[1, 3],
"rack.errors"=>#<IO:<STDERR>>,
"rack.multithread"=>true,
"rack.multiprocess"=>false,
"rack.run_once"=>false,
"SCRIPT_NAME"=>"",
"QUERY_STRING"=>"",
"SERVER_PROTOCOL"=>"HTTP/1.1",
"SERVER_SOFTWARE"=>"puma 4.3.5 Mysterious Traveller",
"GATEWAY_INTERFACE"=>"CGI/1.2",
"REQUEST_METHOD"=>"POST",
"REQUEST_PATH"=>"/api/v1/....",
"REQUEST_URI"=>"/api/v1/...",
"HTTP_VERSION"=>"HTTP/1.1",
"HTTP_HOST"=>"example.com",
"HTTP_APIKEY"=>"secret_key",
"CONTENT_TYPE"=>"application/json",
"HTTP_USER_AGENT"=>"PostmanRuntime/7.25.0",
"HTTP_ACCEPT"=>"*/*",
"HTTP_CACHE_CONTROL"=>"no-cache",
...
```
* Update README.md
The IETF decided the X- style custom headers have caused more headache than the value: https://tools.ietf.org/html/rfc6648 so this tool (which is very popular and much loved) shouldn't suggest using an old style.
* docs: Improve Getting Started section
* docs: Following Getting Started show Usage to the README reader
* docs: Move the configuration tip to the Usage section
* docs: Move the cache store configuration comment to Usage
* docs: Clarify Responses title
* docs: allow2ban also uses the cache store
* docs: Improve Usage docs for blocking, safelisting and throttling
* docs: Don't give the impression that the gem is not being maintained when it actually is
* docs: Be a bit more clear about cache store in README
* docs: Attempt to be a bit more concise in the README intro
* docs: Clarify sentence
This is allows access to the same time that the cache uses for the count. This can be important for clients that want to provide rate limit information for well-behaved clients
