m2m_keygen 0.4.9 → 0.5.1

data/README.md

@@ -2,6 +2,8 @@
 
 This gem exists for simplifying Machine to Machine signature generation and verification in a secure way.
 
+> If you are coming from a `0.4.x` version: the signature scheme changed in `0.5.0` and is not compatible anymore. See [docs/MIGRATING.md](docs/MIGRATING.md).
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -14,132 +16,116 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
-### Signature
-
-This gem provides a module for signing and checking signature for HTTP requests
+The 2 servers share the same secret key. The sender will sign the request it is about to send and put the signature (with an expiry and a nonce) in headers. The receiver will generate the same signature from the request it received and compare them.
 
-#### Initialization
+### Signing a request
 
-You should initialize the `Signature` once (in an initializer for example) with your secret key and eventually an encryption algorithm.
+You should use the `RequestSigner` on the sender side. It will build the query to send and the headers to add, and generate a nonce and an expiry for you.
 
-```ruby
-AuthSignature = M2mKeygen::Signature.new("my_secret_key", algorithm: "sha256")
-
-AuthSignature = M2mKeygen::Signature.new("my_secret_key") # => Will default algorithm to sha512
-```
-
-#### Signing
-
-Use the `sign` method to generate a new signature.
-
-- `params` is a params hash as used in Rack. The order of keys isn't important as the gem will reformat them.
 - `verb` is the http verb
 - `path` is the path for the request
-
-```ruby
-AuthSignature.sign(
-  params: {
-    "a" => "test",
-    :b => 1,
-    "d" => %w[a b],
-    "c" => {
-      "e" => 45
-    }
-  },
-  verb: "get",
-  path: "/path"
-) # => "a52168521868ebb37a38f90ec943163d9acb6ceb982206f437e1feb9ca32e7c1a8edef68f0ff4e195aeca1da93ae9afc8da214cb51a812fc6cc3730fdc7613fa"
-```
-
-After generating the signature send it alongside your request for verification on the receiver side.
-
-#### Verifying
-
-Use the `validate` method to verify that a received signature correspond to the HTTP request.
-
 - `params` is a params hash as used in Rack. The order of keys isn't important as the gem will reformat them.
-- `verb` is the http verb
-- `path` is the path for the request
-- `signature` is the received signature
+- `body` is optional, the raw body you will send
 
 ```ruby
-AuthSignature.validate(
-  params: {
-    "a" => "test",
-    :b => 1,
-    "d" => %w[a b],
-    "c" => {
-      "e" => 45
+Signer = M2mKeygen::RequestSigner.new("my_secret_key") # eventually algorithm: "sha256", defaults to sha512
+
+signed =
+  Signer.sign_request(
+    verb: "get",
+    path: "/orders",
+    params: {
+      "since" => "2026-01-01",
+      "limit" => 50
     }
-  },
-  verb: "get",
-  path: "/path",
-  signature:
-    "a52168521868ebb37a38f90ec943163d9acb6ceb982206f437e1feb9ca32e7c1a8edef68f0ff4e195aeca1da93ae9afc8da214cb51a812fc6cc3730fdc7613fa"
-) #=> true
+  )
+
+signed.query # => the query string to send
+signed.headers # => the X-Signature, X-M2M-Expiry and X-M2M-Nonce headers to add
 ```
 
-If the validation is true, the request was signed with the same algorithm and same secret key.
+After signing, send `signed.query` and `signed.headers` alongside your request.
 
-### RackValidator
+### Validating a request
 
-This module is here for directly validate Rack requests.
+You should initialize the `RackValidator` once (in an initializer for example) with your secret key, eventually an encryption algorithm, a header name for the signature, and a nonce store (see below).
 
 It will validate :
 
 - Signature matching
-- That the `expiry` parameter is present and between now and in 2 minutes.
-
-#### Initialization
-
-You should initialize the `RackValidator` once (in an initializer for example) with your secret key, eventually an encryption algorithm and a header name for the signature.
+- That the `expiry` (in the `X-M2M-Expiry` header) is present and between now and in 2 minutes.
+- That the `nonce` (in the `X-M2M-Nonce` header) has never been seen before, so the request can't be replayed.
 
 ```ruby
 RackSignatureValidator =
   M2mKeygen::RackValidator.new(
-    "secret",
+    "my_secret_key",
+    nonce_store: M2mKeygen::NonceStore::Memory.new,
     algorithm: "sha512", # Default value
-    header_name: "X-Signature" # Default value
+    header_name: "X-Signature", # Default value
+    window: 120 # Default value, in seconds
   )
 ```
 
-#### Validation
-
 You can then validate a Rack::Request or a Rails Request directly:
 
 ```ruby
 RackSignatureValidator.validate(request) # => true or false
 ```
 
-## How does it works
+### Choosing a nonce store
+
+The nonce is what really stops replay: a captured request can't be replayed because its nonce is remembered until it expires. You have to choose a store, there is no default value on purpose, so you don't end up without replay protection without knowing it.
+
+- `M2mKeygen::NonceStore::Memory` for a single process app or in development. Careful : with several workers or several hosts, each process has its own memory, so the replay protection is only partial. Use a shared store in production.
+- A shared store (Redis, Postgres, ...) for production. Ready to copy implementations are in [`examples/nonce_store/`](examples/nonce_store/).
+- `M2mKeygen::NonceStore::Disabled` if you explicitly don't want the replay protection (expiry only).
+
+### Signing without headers
+
+If you don't go through HTTP headers, `Signature` is the low level tool both helpers are built on.
+
+```ruby
+Signature = M2mKeygen::Signature.new("my_secret_key")
+
+hex =
+  Signature.sign(
+    verb: "get",
+    path: "/orders",
+    expiry: 1_700_000_000,
+    nonce: "a-nonce",
+    query: "a=1"
+  )
+```
+
+## How does it work
+
+This is intended for a secure discussion between 2 servers and not something in a browser as the secret key must be stored and used on both sides (and you don't want to send the secret key in the browser).
 
-This is intended for a secure discussion between 2 servers and not something in a browser as the secret key must be stored and used both side (and you don't want to send the secret key in the browser).
+Both servers will have the same secret key. The sender will generate a signature matching the HTTP request it will be sending (the verb, the path, the query and the body, with an expiry and a nonce) and add it to the request in designated headers. The receiver will generate the same signature from the HTTP request it has received and will compare it with the signature in the header.
 
-Both server will have the same secret key.
-The sender will generate a signature matching the HTTP request it will be sending and add it to the request in a designated header.
-The receiver will generate the same signature from the HTTP request it has received and will compare it with the signature in the header.
+The comparison will be done in constant time (i.e. secure) because both strings will be hexdigests from a HMAC with the same algorithm.
 
-The comparison will be done in constant time (i.e. secure) because both string will be hexdigest from a HMAC with the same algorithm.
+The exact byte format is described in [docs/SPEC.md](docs/SPEC.md), with golden vectors. This is the contract another implementation (the TypeScript one for example) will have to reproduce exactly.
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb` and the CHANGELOG, then push to `main` : the gem is published to [rubygems.org](https://rubygems.org) through trusted publishing.
 
 Every commit/push is checked by overcommit. You should (must) activate overcommit by using `overcommit -i` post installation.
 
-Tool used in dev:
+Tools used in dev:
 
 - Rubocop
-- Prettier
-- Yard
+- Syntax Tree
 - Sorbet
 - RSpec
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/zaratan/m2m_keygen. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/zaratan/m2m_keygen/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/zaratan/m2m_keygen_ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/zaratan/m2m_keygen_ruby/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -147,4 +133,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the M2mKeygen project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/zaratan/m2m_keygen/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the M2mKeygen project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/zaratan/m2m_keygen_ruby/blob/main/CODE_OF_CONDUCT.md).

data/docs/MIGRATING.md

@@ -0,0 +1,69 @@
+# Migrating from v1 to v2 (`m2m-keygen/2`)
+
+v2 replaces the signature scheme. A v1 signature does not validate under v2 and
+vice-versa, so **the sender and the receiver must be upgraded together** — plan a
+coordinated deploy (both ends share the secret; upgrade them in lockstep). If a
+TypeScript counterpart signs or verifies these requests, it must move to v2 too,
+following [SPEC.md](SPEC.md).
+
+## What changed and why
+
+v1 signed `"#{VERB}#{path}#{params_as_k=v}"`, which collided on unescaped
+delimiters, dropped empty values, confused types, and had no replay protection.
+v2 signs the request's **wire bytes** (method, path, byte-order-sorted query, raw
+body) length-prefixed, plus a **signed expiry and nonce**. See [SPEC.md](SPEC.md)
+for the full format.
+
+## API changes
+
+| v1 | v2 |
+|----|----|
+| `Signature#sign(params:, verb:, path:)` | `Signature#sign(verb:, path:, expiry:, nonce:, query: '', body: '')` |
+| `Signature#validate(params:, verb:, path:, signature:)` | `Signature#validate(signature:, verb:, path:, expiry:, nonce:, query: '', body: '')` |
+| `ParamsEncoder` | removed (internal `Canonicalizer`) |
+| `RackValidator.new(secret, algorithm:, header_name:)` | `RackValidator.new(secret, nonce_store:, algorithm:, header_name:, window:, expiry_header:, nonce_header:)` |
+| expiry passed as a request param | expiry sent in the `X-M2M-Expiry` header (signed) |
+| — | nonce sent in the `X-M2M-Nonce` header (signed) |
+| — | `RequestSigner` client helper |
+
+## On the sender
+
+Replace hand-built signatures with `RequestSigner`, which generates the nonce and
+expiry and returns the headers to send:
+
+```ruby
+signer = M2mKeygen::RequestSigner.new(secret)
+signed = signer.sign_request(verb: "GET", path: "/orders", params: { "since" => "2026-01-01" })
+
+# signed.query   => the query string to send
+# signed.headers => { "X-Signature" => ..., "X-M2M-Expiry" => ..., "X-M2M-Nonce" => ... }
+```
+
+For a body request, pass `body:` (the exact bytes you will send).
+
+## On the receiver
+
+`RackValidator` now **requires** a nonce store — pick one explicitly:
+
+```ruby
+# Single-process / development:
+M2mKeygen::RackValidator.new(secret, nonce_store: M2mKeygen::NonceStore::Memory.new)
+
+# Multi-worker / multi-host production: use a shared store
+# (see examples/nonce_store/redis.rb and postgres.rb):
+M2mKeygen::RackValidator.new(secret, nonce_store: RedisNonceStore.new(Redis.new))
+
+# Expiry-only, no replay protection — a deliberate, visible opt-out:
+M2mKeygen::RackValidator.new(secret, nonce_store: M2mKeygen::NonceStore::Disabled.new)
+```
+
+`validate(request)` still returns `true`/`false`; it now also rejects a replayed
+or missing nonce (unless the store is `Disabled`).
+
+## Checklist
+
+1. Upgrade the gem (and the TS lib, if any) on **both** ends.
+2. Sender: switch to `RequestSigner`; send the three headers and the returned query.
+3. Receiver: pass a `nonce_store:`; expect expiry/nonce in headers.
+4. Deploy sender and receiver together (a v1 sender against a v2 receiver, or the
+   reverse, will fail every signature).

data/docs/SPEC.md

@@ -0,0 +1,245 @@
+# m2m-keygen/2 — signature scheme specification
+
+This is the language-agnostic contract for the `m2m-keygen/2` request signing
+scheme. Any implementation (this Ruby gem, its TypeScript sibling, or any other)
+that produces or verifies signatures MUST follow it byte-for-byte. The
+[golden vectors](#golden-vectors) at the end are the conformance test set.
+
+## Overview
+
+A sender signs an HTTP request with an HMAC keyed by a shared secret and sends
+the signature (plus an expiry and a nonce) in headers. The receiver rebuilds the
+same signing input from the request it received and recomputes the HMAC. If they
+match (constant-time compare) and the expiry/nonce checks pass, the request is
+authentic and fresh.
+
+The signature commits to the request's **wire bytes** (method, path, the query
+string, and the raw body) rather than to a re-parsed data structure. This is
+what makes the scheme unambiguous and portable: there is no cross-language
+serialization to agree on — each side signs the bytes as they appear on the
+wire.
+
+## Canonical string
+
+The signed message is a single byte string built by concatenating these seven
+components, in this exact order:
+
+| # | Component        | Value                                                        |
+|---|------------------|--------------------------------------------------------------|
+| 1 | scheme           | the literal ASCII string `m2m-keygen/2`                      |
+| 2 | verb             | the HTTP method, uppercased (ASCII)                          |
+| 3 | path             | the request path exactly as it appears on the wire — **percent-encoded, not decoded** (as `Rack::Request#path` returns the raw `PATH_INFO`, and `new URL(...).pathname` returns it in JS). Signer and verifier must see the same bytes. |
+| 4 | expiry           | the expiry, an integer Unix timestamp (seconds), as its decimal string |
+| 5 | nonce            | the nonce string                                             |
+| 6 | canonical_query  | the canonicalized query string (see below)                  |
+| 7 | body             | the raw request body bytes, exactly as sent                 |
+
+Each component is **length-prefixed** with its **UTF-8 byte length** and a colon,
+then all seven are concatenated with no separator:
+
+```
+canonical = ""
+for component in components:
+    bytes      = utf8_bytes(component)      # for the body: the raw bytes as-is
+    canonical += ascii(bytes.length) + ":" + bytes
+signature = hex( HMAC(algorithm, secret, canonical) )
+```
+
+Length-prefixing makes every field boundary unambiguous: no `&`, `=`, `/` or any
+other byte in a value can be mistaken for a delimiter, and no field can "borrow"
+bytes from its neighbour.
+
+- `bytes.length` is the number of **bytes** (UTF-8 for text; raw for the body),
+  not the number of characters. In Node: `Buffer.byteLength(s, 'utf8')`.
+- The default `algorithm` is `sha512`. `hex` is lowercase hexadecimal.
+- The whole canonical string is assembled as raw bytes, so a binary body is
+  handled with no special casing.
+- The scheme string (component 1) carries the version. There is no version
+  negotiation: a verifier accepts exactly `m2m-keygen/2`, so senders and verifiers
+  move to a new version together (see [MIGRATING.md](MIGRATING.md)).
+- Verification compares the recomputed hex digest to the received one in
+  **constant time**; a signature of unexpected length is rejected (`false`)
+  without a length-dependent early branch.
+
+## canonical_query
+
+The query string is canonicalized by splitting it into its raw `key=value` pairs
+on `&`, sorting those pairs in **byte order**, and re-joining them with `&`:
+
+```
+canonical_query = query.split("&").sortByBytes().join("&")     # "" if query is empty
+```
+
+- The pairs are kept **exactly as they appear on the wire** (percent-encoded).
+  Values are never decoded, re-encoded, or type-converted for signing.
+- "Byte order" means comparing the UTF-8 byte sequences of the pairs. Ruby's
+  `Array#sort` on strings already does this. In JavaScript, the default
+  `Array.prototype.sort` compares UTF-16 code units, which agrees with byte
+  order for the Basic Multilingual Plane but **diverges for astral characters**
+  (> U+FFFF); a conformant implementation MUST sort by encoded bytes, e.g. by
+  comparing `Buffer`/`Uint8Array` representations, not raw JS string `<`/`>`.
+- Sorting means the sender may emit pairs in any order; both sides re-sort before
+  signing, so pair order in transit is irrelevant.
+
+## Value stringification (senders building a query from a map)
+
+When a helper builds the query string from a key/value map (the ergonomic
+sender path), values become strings as follows before percent-encoding:
+
+- **String** → itself.
+- **Integer** → its decimal string. Big integers are exact (no float rounding).
+- **Boolean** → `true` / `false`.
+- **Symbol** (Ruby) → its string form.
+- **Float** → its native string form (Ruby `Float#to_s`). Finite floats are
+  allowed but their textual form is language-specific (Ruby `1.0` → `"1.0"`,
+  JS `String(1.0)` → `"1"`). If you need byte-identical signatures from senders
+  in different languages, use strings or integers for numeric values. **NaN and
+  ±Infinity are rejected** (they have no stable representation).
+- **Array** → a repeated key (`k=v1&k=v2`), elements stringified as above.
+- **Hash / nested object** → not supported. v2 query params are flat `k=v`
+  wire pairs; there is no nested or JSON encoding in the signing path. (A
+  structured payload travels in the body, which is signed as raw bytes.)
+
+None of this applies to the receiver: it never rebuilds values, it signs the
+`query`/`body` bytes it received.
+
+### Query encoding is not part of the contract
+
+The signature covers the **query bytes on the wire**, not the map a sender started
+from. How a sender percent-encodes a map into a query string (space as `+` vs
+`%20`, which characters are escaped, …) is **not** specified here and may differ
+between languages — that is fine, because the receiver re-signs the raw query it
+received. What is guaranteed: a sender signs exactly the bytes it sends.
+
+Two consequences:
+
+- **Send the signed query (and path) verbatim.** Do not let your HTTP client
+  re-encode or reorder the query after signing, or the bytes sent will differ from
+  the bytes signed and validation will fail.
+- Two senders in different languages will not necessarily produce byte-identical
+  signatures for the same map. If you need that (e.g. shared idempotency keys),
+  agree on strings/integers and on the exact query form.
+
+## Transport
+
+Three headers carry the protocol metadata (names are configurable; defaults):
+
+| Header          | Contents                                        |
+|-----------------|-------------------------------------------------|
+| `X-Signature`   | the hex HMAC signature                          |
+| `X-M2M-Expiry`  | the expiry (integer Unix seconds), as a string  |
+| `X-M2M-Nonce`   | the nonce                                        |
+
+The expiry and nonce are **signed** (components 4 and 5), so they cannot be
+tampered with; the headers are just how they travel.
+
+## Expiry
+
+The expiry is a Unix timestamp (seconds) chosen by the sender. The receiver
+accepts the request only if it is strictly inside the window:
+
+```
+now < expiry < now + window          # window default: 120 seconds
+```
+
+Both bounds are strict (`expiry == now` and `expiry == now + window` are
+rejected). This bounds how long a captured request could be replayed; clocks on
+both ends are assumed roughly synchronized (NTP).
+
+## Nonce and anti-replay
+
+The expiry alone only *bounds* replay; a captured request can still be replayed
+until it expires. The nonce closes that window:
+
+- The sender generates a **unique, unpredictable** nonce per request (e.g.
+  `SecureRandom.hex(16)`, ≥ 128 bits) and signs it.
+- The receiver records nonces in a store and **rejects any nonce it has already
+  seen**. The store operation MUST be a single **atomic** check-and-set
+  (`add(nonce, ttl) -> was_new`); a separate "seen?" then "record" is a TOCTOU
+  race that lets two concurrent replays through.
+- The nonce's TTL in the store must cover at least the request's remaining
+  acceptance window (`expiry - now`, plus a small clock-skew margin).
+- **Fail closed**: if replay protection is enabled, a request with a missing or
+  empty nonce is rejected.
+- Nonce length should be bounded by the receiver to prevent store-memory abuse.
+
+An implementation MAY offer an explicit opt-out (expiry-only, no nonce store),
+but it must be a deliberate, visible choice — never a silent default.
+
+## Reproducing a signature with OpenSSL
+
+Build the canonical string and pipe it to `openssl`. For the first golden vector
+below (`secret = golden-vector-secret`):
+
+```sh
+printf '%s' \
+  '12:m2m-keygen/23:GET6:/users10:170000000016:nonce-simple-get7:a=1&b=20:' \
+  | openssl dgst -sha256 -hmac 'golden-vector-secret'
+# => 178ef6ed485b438422fa634c11e2a9497176d69abe98175ee9492503bed345ab
+```
+
+The canonical string reads: `12:` + `m2m-keygen/2`, `3:` + `GET`, `6:` + `/users`,
+`10:` + `1700000000`, `16:` + `nonce-simple-get`, `7:` + `a=1&b=2`, `0:` + `` (empty body).
+
+## Golden vectors
+
+Secret: `golden-vector-secret`. Each row lists the inputs and the expected
+lowercase-hex HMAC for both `sha256` and `sha512`. A conformant implementation
+must reproduce every digest. (These are kept in sync with
+`spec/support/golden_vectors.rb`.)
+
+### 1. Simple GET with a sorted query
+
+- verb `GET`, path `/users`, expiry `1700000000`, nonce `nonce-simple-get`, query `a=1&b=2`, body *(empty)*
+- sha256: `178ef6ed485b438422fa634c11e2a9497176d69abe98175ee9492503bed345ab`
+- sha512: `88fd787042faffd81584b534a9fb1f634907fc8ae742ff14b96da4b2f98dbddc25492776bbab30e37c59bb63a4ff84f1e22a359d015d463c1bbaa71f08319ae3`
+
+### 2. POST with a JSON body
+
+- verb `POST`, path `/users`, expiry `1700000100`, nonce `nonce-simple-post`, query *(empty)*, body `{"name":"Ada"}`
+- sha256: `d1e464edbae8637f7db51c0f858a9a64db2c93208381c8055c2e4787b3fc5589`
+- sha512: `c1f52dcfa6f880d1e601ff6db4889e64678e5057872e1a8e1831232e49ac2487a9c30981cbb67eff9e2dc3e7f54d4e05966bcd4d5bcb9b7f19a77204bd37ad6e`
+
+### 3. Percent-encoded (wire-form) path, with non-ASCII query and body
+
+The path is the wire form `/r%C3%A9sum%C3%A9` (the request-target for `/résumé`), **not** the decoded `/résumé`.
+
+- verb `POST`, path `/r%C3%A9sum%C3%A9`, expiry `1700000200`, nonce `nonce-non-ascii`, query `name=%C3%A9l%C3%A8ve`, body `café ☃ 日本語`
+- sha256: `4d521773b4b15bff07e73c4a4a8db483314b62725b42b653e2d887efdca78404`
+- sha512: `ec42e774af9730d59456fcf2909d7606a10d61d4187badf2b0f7b4b62047495daa4d9f5d286bdb1e4b9a61b8b23e5801e13b563177c3e7f3d6f553f6dad6f7f1`
+
+### 4. Body with control characters (tab, newline, NUL)
+
+- verb `POST`, path `/notes`, expiry `1700000300`, nonce `nonce-control-char`, query *(empty)*, body `control\tchars\n\x00end-of-line`
+- sha256: `841172d2cea40129d864b5f1ef078329d33b4221c2227ed05058716104e75ad7`
+- sha512: `49f58297da8599bc0d325d22cb1ed90ee7d5f67b13a9b13ca430820b8a09e08aff945129f6876bc0186002412eeae20b27dec1317c3f77f3eccb635899536b22`
+
+### 5. Big-integer amount in query and body
+
+- verb `POST`, path `/ledger`, expiry `1700000400`, nonce `nonce-bignum`, query `amount=123456789012345678901234567890`, body `{"amount":123456789012345678901234567890}`
+- sha256: `b07e7563ce1f7c4819f3052ba3628a1a5d155b77600a5765c40ca610784e7808`
+- sha512: `32078f4c96255ef99ca9e80ecb4ec800d4056ef136dbd42dc4c3bbfc33b153c3e2ef23a1a09b574d4ffd558ede3d30bcfc1c3cc041deaf5c76c70307e18a3c5d`
+
+### 6. Out-of-order multi-pair query (proves the pair sort)
+
+The query arrives as `b=2&a=10&a=1`; `canonical_query` sorts the pairs by bytes to `a=1&a=10&b=2`. An implementation that forgets to sort produces a different digest and fails here.
+
+- verb `GET`, path `/list`, expiry `1700000500`, nonce `nonce-sort`, query `b=2&a=10&a=1`, body *(empty)*
+- sha256: `f3da6c2db729b59fdbaa301eb1bebea55253afdcd6039e055849a6404ffdd845`
+- sha512: `db925510d0621073b4a37441f3f0df8697b08d204feae25f663a284840cbaceced9cd28acad09121f7d64749d4c6ab690c279dcc6b14b6a5ad81c0dce86d3cc2`
+
+### 7. Astral character in the query (proves byte-order, not UTF-16, sorting)
+
+Two pairs whose sort order differs by encoding: U+FFFD starts with byte `0xEF`, U+1F600 (😀) with `0xF0`, so byte order gives `�=bmp` first — canonical query `�=bmp&😀=astral`. A JS `.sort()` (UTF-16 code units: the 😀 surrogate `0xD83D` sorts before `0xFFFD`) would order them the other way and produce a different digest. The raw UTF-8 bytes of the two pairs are in the query.
+
+- verb `GET`, path `/emoji`, expiry `1700000600`, nonce `nonce-astral`, query `😀=astral&�=bmp` (raw UTF-8), body *(empty)*
+- sha256: `32f0e93a4f926293d232a0a81cebbe5206a9f7619413dd126bc7b9dd027bbb69`
+- sha512: `4109fcd615c1a6231d4d8dac08416d28e0bf324bc7b65f3b8193651e7eed8c6a072c08df2e6c3c16daf8a921e6b2a8102e04e726521ac6d98e9c6128a6e44a69`
+
+## Out of scope (threat model)
+
+The scheme protects request **integrity** and **freshness** (replay). It does
+**not** provide confidentiality (use TLS), does not bind the host/scheme (a
+signed request is valid against any deployment sharing the secret — use
+per-environment secrets), and assumes roughly synchronized clocks. Secret
+rotation and host binding are possible extensions, not part of v2.

data/examples/nonce_store/postgres.rb

@@ -0,0 +1,40 @@
+# typed: false
+# frozen_string_literal: true
+
+# Reference M2mKeygen::NonceStore backed by PostgreSQL. Requires the `pg` gem
+# and this table:
+#
+#   CREATE TABLE m2m_nonces (
+#     nonce      text        PRIMARY KEY,
+#     expires_at timestamptz NOT NULL
+#   );
+#   CREATE INDEX m2m_nonces_expires_at_idx ON m2m_nonces (expires_at);
+#
+#   store = PostgresNonceStore.new(PG.connect(ENV['DATABASE_URL']))
+#   RackValidator.new(secret, nonce_store: store)
+#
+# Like Redis, this store is shared across processes. `INSERT ... ON CONFLICT
+# DO NOTHING RETURNING` is the atomic check-and-set: a row is returned only when
+# this call actually inserted the nonce. Expired rows are inert (a fresh request
+# always carries a fresh random nonce), but should be reclaimed periodically —
+# call `#purge_expired` from a cron or background job.
+class PostgresNonceStore
+  def initialize(connection)
+    @connection = connection
+  end
+
+  def add(nonce, ttl:)
+    result =
+      @connection.exec_params(
+        'INSERT INTO m2m_nonces (nonce, expires_at) ' \
+          'VALUES ($1, now() + make_interval(secs => $2::int)) ' \
+          'ON CONFLICT (nonce) DO NOTHING RETURNING nonce',
+        [nonce, ttl],
+      )
+    result.ntuples.positive?
+  end
+
+  def purge_expired
+    @connection.exec('DELETE FROM m2m_nonces WHERE expires_at < now()')
+  end
+end

data/examples/nonce_store/redis.rb

@@ -0,0 +1,23 @@
+# typed: false
+# frozen_string_literal: true
+
+# Reference M2mKeygen::NonceStore backed by Redis. Requires the `redis` gem.
+#
+#   store = RedisNonceStore.new(Redis.new)
+#   RackValidator.new(secret, nonce_store: store)
+#
+# Redis is a good fit for multi-worker/multi-host production: the store is
+# shared across all processes, and `SET ... NX PX` gives the atomic
+# check-and-set the NonceStore contract requires, with the TTL handled natively
+# (no purge to run).
+class RedisNonceStore
+  def initialize(redis, prefix: 'm2m:nonce:')
+    @redis = redis
+    @prefix = prefix
+  end
+
+  # Returns true only if the key did not exist (nonce is new); false on replay.
+  def add(nonce, ttl:)
+    @redis.set("#{@prefix}#{nonce}", '1', nx: true, px: ttl * 1000) == true
+  end
+end

data/gemfiles/rack_2.gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+eval_gemfile File.expand_path('../Gemfile', __dir__)
+
+gem 'rack', '~> 2.2'

data/gemfiles/rack_3.gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+eval_gemfile File.expand_path('../Gemfile', __dir__)
+
+gem 'rack', '~> 3.0'

data/lib/m2m_keygen/canonicalizer.rb

@@ -0,0 +1,57 @@
+# typed: strict
+# frozen_string_literal: true
+
+module M2mKeygen
+  class Canonicalizer
+    extend T::Sig
+
+    SCHEME = 'm2m-keygen/2'
+
+    class << self
+      extend T::Sig
+
+      sig do
+        params(
+          verb: String,
+          path: String,
+          expiry: Integer,
+          nonce: String,
+          query: String,
+          body: String,
+        ).returns(String)
+      end
+      def canonical(verb:, path:, expiry:, nonce:, query: '', body: '')
+        join_length_prefixed(
+          [
+            SCHEME,
+            verb.upcase,
+            path,
+            expiry.to_s,
+            nonce,
+            canonical_query(query),
+            body,
+          ],
+        )
+      end
+
+      sig { params(query: String).returns(String) }
+      def canonical_query(query)
+        return '' if query.empty?
+
+        query.split('&').sort_by(&:b).join('&')
+      end
+
+      private
+
+      sig { params(components: T::Array[String]).returns(String) }
+      def join_length_prefixed(components)
+        buffer = String.new(encoding: Encoding::BINARY)
+        components.each do |component|
+          bytes = component.b
+          buffer << bytes.bytesize.to_s << ':' << bytes
+        end
+        buffer
+      end
+    end
+  end
+end