## Problem/Motivation Nothing in kessai counts requests. There is no use of core's `flood` service, no limit in any settings object, and no counter of any kind, in any of the five modules. Every endpoint will answer as often as it is asked. Four routes are reachable without authenticating at all: | Route | Access | What one anonymous request costs | |---|---|---| | `/kessai/worldline/webhook` | `_access: 'TRUE'` | Loads every Worldline account and its key, unmarshals and verifies the payload, and **writes a watchdog warning** when it does not hold | | `/kessai-client/notice/{account}` | `_access: 'TRUE'` | Looks up the remote, reads its notice secret, verifies the signature, and **writes a watchdog warning** on refusal | | `/kessai/pay/{payment}` | `_access: 'TRUE'` | Loads the payment through the route converter before the controller can check anything | | `/kessai/worldline/return/{payment}` | `_access: 'TRUE'` | Loads the payment | The signature checks themselves are right: an unsigned webhook or notice is refused, and the handoff validates its token before it does anything else. Refusing is not the same as being cheap to refuse, and that is the gap. A stranger can make this site load config entities, read keys and compute HMACs in a loop, for free and without limit. **The log is the amplifier.** Both refusal paths write a warning per request, so an attacker who cannot get in can still fill `watchdog` at the rate they can send. The logging is correct on its own terms — an operator needs to see a webhook that will not verify — and it becomes a liability only because nothing bounds how often it can happen. **A valid handoff token is not a one-shot.** `/kessai/pay/{payment}` opens a payment session at the provider, which is an outbound call, and the link carrying the token lives in the payer's browser history and often in an email. Reloading it repeatedly opens sessions at the provider repeatedly. Nothing on this side notices. **The API is authenticated but not metered.** `/kessai-api/*` is behind `_auth: ['oauth2']` and a permission, so this is not about strangers. It is about one consumer being able to exhaust the engine for every other consumer, which no permission expresses. There is no per-consumer quota. `simple_oauth` ships no flood control of its own either, so the token endpoint that guards those routes is itself uncounted. ## Proposed resolution A `FloodGuard` in `kessai`, beside `DeletionGuard`, for the same reason that one is there: it is the only module every other one already depends on, and the rule has to be the same wherever it is asked. It wraps core's `flood` service and answers one question — may this caller do this now — in **two tiers within one window**: - **Per caller**, which is what stops one consumer or one source from starving the rest. - **Global per endpoint**, which is what stops a distributed flood that stays under every per-caller limit. Who "the caller" is differs by endpoint and is the part worth settling deliberately: the consumer for the API routes, the payment for the handoff and the return, and the request source for the webhook and the notice, where there is no identity until the signature has already been checked. **A refused request has to count.** The work this is meant to bound is the work done *before* a request is rejected, so registering the hit only on success would leave the whole problem in place. The counter is registered before the expensive part, not after it. **And the warning becomes once per window per caller**, rather than once per request, so an operator still learns that something is sending bad signatures without the log being the payload. Limits live in config with sensible shipped defaults and a settings form, because the right number depends on how many consumers a site has and how chatty its provider is, and no default is right for every site. ### An allowlist where the caller is known Two of the four open routes have a *known* caller, and for those an allowlist is a better guard than a counter, because it refuses before any of the work: no account load, no key read, no HMAC, no log line. One `IpUtils::checkIp()` against an array. - `/kessai/worldline/webhook` is called by the provider. The list is **site-wide**, in `kessai_worldline.settings`. Not per account, which is where it looks like it belongs: a notification names the provider's own key id, and the verifier builds one key store across every enabled account, so which account it is can only be worked out by verifying it - after the work the list exists to avoid. - `/kessai-client/notice/{account}` is called by the kessai that took the payment, whose `base_url` the remote already records. The allowlist belongs on the **remote**, for the same reason: two remotes are two different callers. The other two cannot have one. `/kessai/pay/{payment}` and `/kessai/worldline/return/{payment}` are opened by the payer's browser, from wherever the payer is. That is precisely why the metering tier is still needed and why this does not replace it. **Empty means allow.** A site that configures nothing behaves exactly as it does today. An allowlist is a promise about the provider's infrastructure that only the site can make. **Checked before the counter**, so an off-list request costs an array comparison rather than a flood backend write. **And the trap that makes this worth writing down.** `Request::getClientIp()` returns a forwarded address only when `$settings['reverse_proxy']` and `$settings['reverse_proxy_addresses']` are set. Behind a proxy that has not been declared, every request appears to come from the proxy - so the allowlist either refuses the provider or admits the whole internet, and looks like it is working in both cases. An allowlist that reads a spoofable header is worse than none, because it is believed. So a site with an allowlist configured and no trusted proxies declared has to be told, in the status report, that the thing it configured is not protecting it. **Getting it wrong is silent and money-shaped.** A dropped webhook does not error; the payment settles only when the expiry sweep asks the provider, which the webhook controller already documents as "up to a whole cron interval late". So a refusal is logged - once per window, under the collapsing rule above - and the status report shows the allowlist is in force. ### Off has to mean off Every limit here is a guess about a site nobody has seen. So the whole tier is switchable, and switching it off has to restore today's behaviour exactly - not approximately. **A high limit is not off.** Setting a limit to a million still registers a hit on every request, which is a write to the flood backend per request: the same per-request cost the guard exists to avoid, now paid for nothing. So the guard short-circuits *before* it touches the flood service, rather than asking it a question whose answer is always yes. Three levels, because sites differ in which half they want: - **One switch for the tier.** Off means the guard is never consulted and nothing is counted anywhere. - **Per endpoint.** A site may want its API metered per consumer and its provider's webhook left alone, or the reverse. Each endpoint carries its own limits and can be off while the others are on. - **Per tier within an endpoint**, which comes free from encoding **0 as no limit**: a per-caller limit of 0 with a global limit set is a site that only wants a ceiling, and the reverse is a site that only wants fairness between consumers. **What turning it off costs, said plainly.** The once-per-window collapsing of refusal warnings uses the same counter, so a site that disables the tier gets today's logging back too, one line per refused request. That is the honest meaning of "restores today's behaviour", and it is the reason to reach for the allowlist first on the two endpoints that can have one - the allowlist has no counter and no per-request cost at all, and it is off by default already, because empty means allow. **The default is off, and the site is told so.** Every limit here is a guess about a site nobody has seen, and a wrong guess on a payment endpoint refuses the provider rather than an attacker - silently, with the payment settling only when the expiry sweep catches up. A guess that can delay money is not something to switch on for a site that never asked. So the tier ships off, and the status report says it is off, beside the allowlist checks: a protection nobody can see is a protection nobody turns on, and that, not the default itself, is what makes shipping it off irresponsible. The numbers are the MR's to justify when a site turns it on, not this issue's to invent. ### What this is not Not a replacement for a reverse proxy or a WAF. Those refuse a flood before it reaches PHP, and a site exposed to the internet should have one. This bounds the work reachable *inside* Drupal, which is the half kessai can be held responsible for, and it is the half that is still missing on a site that has both. Not access control. A caller under the limit authenticates exactly as it does today; nothing here decides who may do what. ## Remaining tasks - `FloodGuard` in `kessai`: the two tiers, the window, and the decision to count before doing the work. - Settings and a form, with shipped defaults. - Apply it to the four open routes and to the API routes, each with its own identifier and its own limits. - Collapse the refusal logging to once per window per caller. - Tests per endpoint: under the limit passes, over it refuses, the window expires, and **a request refused for a bad signature still counts** — that last one is the whole point and is the one a naive implementation gets wrong. - Allowlist on the account and on the remote, empty by default, checked ahead of the counter, with the CIDR parsing validated at save rather than at request time. - Status report: the metering tier is off; an allowlist is configured while `reverse_proxy` is not. Plus a test proving a spoofed `X-Forwarded-For` does not get past the allowlist on an undeclared-proxy site. - A test that the off state is genuinely off: with the tier disabled, the flood service is never called at all - asserted against a spy, not inferred from behaviour - and each endpoint answers exactly as it does today. - Document the limits and what to set them to, and say plainly that a public site wants a proxy in front as well. ## User interface changes A settings form for the limits. ## API changes A new `FloodGuard` service in `kessai`. Nothing existing changes shape. ## Data model changes None. Core's flood backend owns its own storage. AI-Generated: Yes (Claude Code was used to help draft this issue summary.)