kiosk-reputation 0.5.20

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2c54f86a684320da6e9531f75045355e684195d3cea1fe21f446faa078803edc
+  data.tar.gz: 478787af3127d2ff0a839c9b121e815576fe3d99b1e316292246c64ceef81fd6
+SHA512:
+  metadata.gz: 65d3819b9a2e14b7409a9acb582d24e5bd5d63f9a161ae78a6138f4a6fc9d512e2df1a4ce17747a0914e84c808b05087236f1cb69e90d2933f6c8d91e53d1dd0
+  data.tar.gz: 5d86be174fc6b13babb23c5cdf476d637be020c618d9b9bfd7611c8405afb077cc464950faaff156b42e18ce2d7f3a341475affe446b4e7709a844a849952886

data/CHANGELOG.md

@@ -0,0 +1,121 @@
+# Changelog
+
+All notable changes follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [Semantic Versioning](https://semver.org/).
+
+How to write an entry, and what a release section means: `CHANGELOG-RULE.md` at
+the root of this repository —
+<https://github.com/kiosk-hq/kiosk/blob/main/CHANGELOG-RULE.md>. In short: under
+200 characters, one or two sentences, the essence rather than the content; write it
+under `## [Unreleased]`; a cut renames that heading to
+`## [MAJOR.MINOR.PATCH] — <date>` and opens a fresh empty one above it; nothing
+already written is edited.
+
+## [Unreleased]
+
+## [0.5.20] — 2026-10-20
+
+- 2026-10-20: Version 0.5.20, the tree cut that matches skill 0.5.20.
+
+## [0.5.19] — 2026-10-20
+
+- 2026-10-20: Version 0.5.19, the tree cut that matches skill 0.5.19.
+
+## [0.5.18] — 2026-10-18
+
+- 2026-10-18: Version 0.5.18, the tree cut that matches skill 0.5.18.
+
+## [0.5.17] — 2026-10-18
+
+- 2026-10-18: `RecentSpend` tolls every call of a caller whose token has no `iat` or `exp`, so a retry cannot fish for a free draw.
+- 2026-10-18: `Policies::RateAndReputation` is removed; `Factors` keeps only `settled_purchases_count` and `settled_purchases_cents`.
+- 2026-10-18: The README configures `RecentSpend`; `RateAndReputation` gets no factors behind the gate, and `on_bad_proof` records into a store the host owns.
+- 2026-10-18: `Policies::Backoff` and `BackoffStore` are removed.
+- 2026-10-18: `RecentSpend` draws once for each customer in each token lifetime, so a new access token in the same lifetime meets the same outcome.
+- 2026-10-18: `RecentSpend` draws once per access token: the token's `jti` fixes the draw, so every call made with the token meets one outcome. `random:` is removed.
+
+## [0.5.16] — 2026-10-18
+
+- 2026-10-18: The README names kiosk-pow-argon2id for the Argon2id backend and points to kiosk-pow's guide to add a backend.
+
+## [0.5.15] — 2026-10-18
+
+- `Policies::RecentSpend.new(within:, cap:)` tolls a session with the chance `max(0, (cap - spend) / cap)`, `cap` in whole currency units; `trusted_at:` and `count:` are gone.
+
+- The README says that `kiosk-pow-equihash` registers itself at Rails boot, and that the host registers any other backend.
+
+## [0.5.14] — 2026-10-18
+
+- 2026-10-18: Version 0.5.14, the tree cut that matches skill 0.5.14.
+
+- 2026-10-18: `Policies::RecentSpend` asks one toll per session and lowers it by the customer's recent spend, to none at `trusted_at`.
+
+- 2026-10-17: The docs say kiosk-pow-equihash registers itself in a Rails app; the ambiguity error no longer names the removed `registration_pow_params`.
+
+- 2026-10-17: `Challenge.check` runs the signature, expiry and parameter checks alone, without the proof evaluation.
+## [0.5.13] — 2026-10-11
+
+- 2026-10-11: Version 0.5.13, the tree cut that matches skill 0.5.13; this gem's surface is unchanged.
+
+## [0.5.12] — 2026-10-08
+
+- 2026-10-08: Version 0.5.12, the tree cut that matches skill 0.5.12; this gem's surface is unchanged.
+
+## [0.5.11] — 2026-10-08
+
+- 2026-10-08: Version 0.5.11, the tree cut that matches skill 0.5.11; this gem's surface is unchanged.
+
+## [0.5.10] — 2026-10-08
+
+- 2026-10-08: Version 0.5.10, the tree cut that matches skill 0.5.10; this gem's surface is unchanged.
+
+## [0.5.9] — 2026-10-08
+
+- 2026-10-08: Version 0.5.9, the tree cut that matches skill 0.5.9; this gem's surface is unchanged.
+
+## [0.5.8] — 2026-10-07
+
+- 2026-10-07: Version 0.5.8, the tree cut that matches skill 0.5.8; this gem's surface is unchanged.
+
+## [0.5.7] — 2026-10-07
+
+- 2026-10-07: Version 0.5.7, the tree cut that matches skill 0.5.7; this gem's surface is unchanged.
+
+## [0.5.6] — 2026-10-07
+
+- 2026-10-07: Version 0.5.6, the tree cut that matches skill 0.5.6; this gem's surface is unchanged.
+
+## [0.5.5] — 2026-10-07
+
+- 2026-10-07: Version 0.5.5, the tree cut that matches skill 0.5.5; this gem's surface is unchanged.
+
+## [0.5.4] — 2026-10-07
+
+- 2026-10-07: Version 0.5.4, the tree cut that matches skill 0.5.4; this gem's surface is unchanged.
+
+## [0.5.3] — 2026-10-06
+
+- 2026-10-06: Version 0.5.3, the tree cut that matches skill 0.5.3; this gem's surface is unchanged.
+
+## [0.5.2] — 2026-10-06
+
+- 2026-10-06: Version 0.5.2, the tree cut that matches skill 0.5.2; this gem's surface is unchanged.
+
+## [0.5.0] — 2026-09-26
+
+### Changed
+
+- README: every `gem` line in the install section now carries `github: "kiosk-hq/kiosk"`, so a copied line resolves before publication; the banner above them states what the block does rather than asking the reader to add it.
+- **Three packaged sentences priced a solve at «~9 s» with no solver, machine or parameters (K-1694).** The seconds are removed; the count-not-window argument is unchanged.
+- **A signed challenge could be re-partitioned into another alg/params split under its own HMAC (K-1693).** `Challenge` now refuses a canonical-string delimiter in any field.
+- **`Policy#challenge_for`'s `verb:` contract is stated as closed, and a wrong branch is no longer silent (K-1395).** The hook receives one of `:query`, `:run`, `:pay` and nothing else; a handler declared `kind :action` in kiosk-server arrives as `:run`. Branching on `:action` matched nothing and declined to toll every write with no error, log line or failing test. `kiosk-server` now refuses such a policy at configuration time. No behaviour change in this gem.
+
+### Added
+
+- Initial implementation.
+- `Kiosk::Reputation::Backends` — algorithm registry: `register` / `fetch` / `known` / `reset!`.
+- `Kiosk::Reputation::Backends.valid_params?(alg, params)` — the mint-time seam a gate asks before issuing a challenge (K-843). Duck-typed and opt-in: it answers `false` only when a registered backend says so itself, and `true` for an unregistered algorithm or one that expresses no opinion, so it can never invent a refusal.
+- `Kiosk::Reputation::Challenge` — stateless, request-bound wire challenge: `issue` / `verify` with anti-DoS cheap-before-expensive ordering (HMAC sig + expiry before backend eval).
+- `Kiosk::Reputation::Factors` — immutable Data class with all-nullable reputation fields; `.empty` constructor.
+- `Kiosk::Reputation::Policy` — base class (never challenge); providers subclass or replace.
+- `Kiosk::Reputation::Policies::RateAndReputation` — shipped EXAMPLE policy: escalates by Equihash proof COUNT (count-curve; no continuous difficulty dial) on high request rate, zero purchases, and bad-proof history; providers are expected to replace it.
+- RSpec suite covering: challenge round-trip, tampered fields, fingerprint mismatch, wrong secret, expiry ordering (spy backend proves backend NOT called before sig/expiry checks pass), wrong nonce, policy tier mapping, bad-proof escalation, backend registry.

data/LICENSE.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,310 @@
+# kiosk-reputation
+
+Policy and wire-challenge layer for Kiosk's proof-of-work system.
+
+## Overview
+
+`kiosk-reputation` decides *when* and *how hard* to challenge a request with a
+proof-of-work, issues and verifies the signed wire challenge, and provides a
+pluggable reputation policy interface.
+
+**Pure Ruby — no dependency on kiosk-pow or kiosk-core.** A PoW backend registers
+with `Kiosk::Reputation::Backends.register`. In a Rails app `kiosk-pow-equihash`
+registers itself at boot; the host registers any other backend (see
+[Installation](#installation)). This gem is backend-agnostic:
+the shipped default is **equihash** (`kiosk-pow-equihash`); `kiosk-pow-argon2id`
+provides Argon2id (legacy, registers as `argon2id`); `kiosk-pow-cuckoo` provides
+Cuckatoo Cycle (opt-in, registers as `cuckatoo`). Each backend is built on
+`kiosk-pow`, whose README tells how to add a backend.
+
+## Wire protocol
+
+### Challenge — HTTP 402 `pow_required`
+
+When the provider's reputation policy decides to challenge a request, the server
+responds with HTTP 402 instead of serving. The answer is an RFC 9457 problem
+document (`application/problem+json`, accompanied by
+`WWW-Authenticate: Kiosk-PoW realm="<issuer>"`) whose flat top-level `code` is
+`pow_required` and which carries a **`challenges` array** (plural) as an
+extension member — the policy demands `count` independent proofs (N×PoW). A
+policy that asks for more than one proof gets one challenge per proof:
+
+```json
+{
+  "type":   "https://kiosk.tech/problems/pow_required",
+  "title":  "Proof-of-work required",
+  "status": 402,
+  "detail": "proof-of-work required",
+  "code":   "pow_required",
+  "challenges": [
+    {
+      "id":     "<uuid>",
+      "alg":    "equihash",
+      "params": { "n": 168, "k": 7 },
+      "salt":   "<base64 of 16 raw bytes, fresh per challenge>",
+      "exp":    1750000600,
+      "sig":    "<HMAC-SHA256 hex over canonical(id|alg|params|salt|exp|request_fingerprint)>"
+    }
+  ]
+}
+```
+
+Key properties:
+
+- **`challenges` is a list of N independent challenges.** Equihash has no
+  continuous difficulty dial (memory is fixed by `(n, k)`) — the anti-abuse
+  lever is PROOF COUNT. Each challenge has its own `id` and fresh `salt`, so
+  there is no amortisation: all N must be solved to prove work for this request.
+- `alg` + `params` are **mandated** — no client negotiation field. `equihash`
+  is the shipped default; `argon2id` is legacy.
+- `salt` is fresh per challenge — prevents precomputation / rainbow tables.
+- `sig` is HMAC-SHA256 (provider `pow_secret`) over the challenge fields **and
+  a fingerprint of the original request**
+  (`SHA256(METHOD + " " + verb + "\n" + canonical_json(args))` — see the retry
+  section below for why that formula matches on retry by construction).
+  Each challenge is stateless-verifiable (no server storage needed to trust it)
+  and bound to that specific request (a proof cannot be replayed against a
+  different call).
+- `exp` bounds the replay window; when N > 1 the server scales the TTL with the
+  count so a slow client solving proofs sequentially does not race expiry.
+
+### Proof — client re-sends the same request, proof(s) in the `Kiosk-PoW` header
+
+The client solves each challenge and re-sends the SAME request — same method,
+same path, same query string, same body — with the proof(s) in a **`Kiosk-PoW`
+request header** as raw minified JSON, one `{challenge, nonce}` entry
+per solved challenge. The wire makes most calls GETs (a query is
+`GET <endpoint>/<query-name>`), and a GET has no body, so the header is the ONLY
+channel a proof can travel on:
+
+```http
+GET /kiosk/menu_by_restaurant?restaurant=Mamma%20Pizza
+Kiosk-PoW: [{"challenge":{ "...echoed verbatim...": true },"nonce":{"indices":[…]}}]
+```
+
+A single proof may be sent bare (`Kiosk-PoW: {"challenge":{…},"nonce":{…}}`), as a
+JSON array of N proofs, or as repeated `Kiosk-PoW` header lines (one proof each) —
+all flatten to one proofs list. Because the proof rides in the header, the
+request is byte-identical at issue time (no proof) and verify time (proof in the
+header), so the request fingerprint —
+`SHA256(METHOD + " " + verb + "\n" + canonical_json(args))` — matches on retry by
+construction; there is no `pow` body field to exclude. That formula binds a proof
+to the exact call: the method, the verb as it appears in the path, and the
+canonical arguments, so a proof solved for `GET /catalog?city=Lisbon` is
+spendable on nothing else.
+
+## Anti-DoS invariant: cheap checks before the expensive backend eval
+
+`Challenge.verify` enforces this order — always:
+
+1. Recompute + compare HMAC sig (constant-time `OpenSSL.fixed_length_secure_compare`)
+   → `:bad_sig` (tampered, wrong request binding, or forged challenge)
+2. Expiry check (`exp > now`) → `:expired`
+3. Parameter re-derivation against the caller's live config (`expect:`)
+   → `:bad_params` (see below)
+4. **Only then**: one backend eval (equihash verify — 2^k BLAKE2b hashes, ~ms + KB)
+   → `:ok` / `:bad_proof`
+
+Floods of forged, expired or off-spec proofs are rejected at steps 1/2/3 without
+burning a backend eval. This is not optional; it is tested.
+
+## Server-side parameter re-derivation (`expect:`)
+
+The challenge is stateless, so `alg`/`params` travel on the wire and come back
+from the client. The HMAC sig proves *we minted them*; it does **not** prove they
+are still the difficulty this server demands. Pass `expect:` — the spec the
+caller just re-derived from its own configuration for this request — and
+`verify` refuses any challenge naming other parameters, however valid its sig:
+
+```ruby
+Kiosk::Reputation::Challenge.verify(
+  challenge: challenge, nonce: solution,
+  request_fingerprint: fp, secret: secret, now: Time.now.to_i,
+  expect: { alg: "equihash", params: { n: 168, k: 7 } }   # from YOUR config, not the wire
+)
+```
+
+Two things this buys: a challenge minted just before a difficulty raise stops
+being solvable at the old cheap parameters for the rest of its TTL, and a leaked
+HMAC secret cannot let a self-signed `{n: 8, k: 1}` challenge turn the toll
+off — the toll degrades rather than vanishing. `kiosk-server`'s gate always
+passes `expect:`; `Challenge.verify` skips the check when it is omitted.
+
+Comparison uses the same canonical `k=v` rendering the sig covers, so key order,
+Symbol-vs-String keys and `168` vs `"168"` are all equal — it rejects a different
+difficulty and nothing else. `:bad_params` means **re-challenge, not bad faith**:
+`kiosk-server` releases the challenge id and answers 402 at current params
+(never 403).
+
+## Components
+
+### `Backends`
+
+Registry mapping algorithm names to PoW backend objects.
+
+```ruby
+Kiosk::Reputation::Backends.register("equihash", Kiosk::Pow::Equihash)
+Kiosk::Reputation::Backends.fetch("equihash")   # => Kiosk::Pow::Equihash
+Kiosk::Reputation::Backends.known               # => ["equihash"]
+```
+
+A registered backend need only respond to:
+- `.verify(salt:, params:, nonce:) → Boolean` — verify a submitted proof
+  (`Challenge.verify` resolves the backend via `fetch` and calls only this).
+
+Backends also expose a `.params` helper for building challenge params, but its
+signature is algorithm-specific (equihash `(n:, k:)`, argon2id `(d:, m:, t:, p:)`,
+cuckatoo `(edgebits:, proofsize:, target:)`) and it is called directly on the
+concrete backend by the host, never through this registry.
+
+### `Challenge`
+
+Stateless, request-bound wire challenge. The caller (`kiosk-server`) maintains a
+spent-id set (TTL ≤ `challenge[:exp]`) to prevent replay of a valid proof —
+`Challenge` itself does not track spent ids.
+
+```ruby
+challenge = Kiosk::Reputation::Challenge.issue(
+  alg:                  "equihash",
+  params:               { n: 168, k: 7 },
+  request_fingerprint:  "sha256:...",
+  secret:               "provider-hmac-key",
+  ttl:                  300            # seconds; exp = Time.now.to_i + ttl
+)
+# => { id:, alg:, params:, salt: <base64>, exp:, sig: }
+
+result = Kiosk::Reputation::Challenge.verify(
+  challenge:            challenge,
+  nonce:                client_solution,   # opaque to Challenge; passed to the backend .verify
+  request_fingerprint:  "sha256:...",
+  secret:               "provider-hmac-key",
+  now:                  Time.now.to_i,
+  expect:               { alg: "equihash", params: { n: 168, k: 7 } }  # optional; from live config
+)
+# => :ok | :bad_sig | :expired | :bad_params | :bad_proof
+```
+
+### `Factors`
+
+Immutable bundle of reputation inputs per request. Both fields may be nil.
+
+```ruby
+Kiosk::Reputation::Factors.new(
+  settled_purchases_count: 3,            # settlements and visits in the window
+  settled_purchases_cents: 65_00         # their value in cents, less refunds
+)
+
+Kiosk::Reputation::Factors.empty         # both fields nil
+```
+
+### `Policy` (base)
+
+```ruby
+class MyPolicy < Kiosk::Reputation::Policy
+  # @param identity [Object]  opaque identity value from the host
+  # @param verb     [Symbol]  the WIRE command — :query, :run or :pay. Not the
+  #   declaration name: a verb a handler declares as `kind :action` in
+  #   kiosk-server arrives here as :run (`Kiosk::Handler` serves an action
+  #   as `:run`), so branch on :run rather than on :action. The protocol
+  #   states the same mapping in its Reputation section. Branching on :action
+  #   would otherwise be silent: it matches
+  #   nothing, so the toll never applies to a write and no error, log line or
+  #   test says so. kiosk-server does not let it be silent: assigning a
+  #   policy whose #challenge_for compares the verb against :action raises
+  #   Kiosk::Server::Errors::ConfigurationError from
+  #   `Kiosk.configure`, at boot, naming :run.
+  # @param factors  [Factors] reputation inputs
+  # @return [Hash{alg:, params:, count:}] challenge spec, or nil to serve without challenge
+  #   (`count` is optional; the gate defaults it to 1 when omitted)
+  def challenge_for(identity:, verb:, factors:)
+    # example: always challenge unknown principals
+    return nil if factors.settled_purchases_count.to_i >= 5
+    { alg: "equihash", params: { n: 168, k: 7 }, count: 1 }
+  end
+end
+```
+
+The base `Policy` class returns `nil` for every request (never challenge).
+
+### `Policies::RecentSpend` — one toll per session, by a chance that recent spend lowers
+
+```ruby
+c.reputation_policy = Kiosk::Reputation::Policies::RecentSpend.new(within: 1.week, cap: 100)
+```
+
+A session pays one proof at the Equihash gem's default params, with the chance
+`max(0, (cap - spend) / cap)`. `spend` is what the customer spent here within
+`within`, and `cap` is in whole currency units. So a customer with no spend
+pays in every session, and a customer who spent `cap` or more pays in none.
+The draw is made once for each customer in each token lifetime. Token
+lifetimes are consecutive spans of `exp - iat` seconds from the Unix epoch, and
+the token's `iat` selects its span. So every call made with one token, and every
+new token issued to the customer in the same span, meets the same outcome.
+An operator that takes no payment records each fulfilled visit with
+`Kiosk::Visit.record!(user_id:, value_cents:)`, and the visit counts as spend.
+A refund through `Kiosk::Server::PaymentClaim#refund` is not spend.
+
+## kiosk-server configuration
+
+The server gate (`Kiosk::Server::PowGate`) reads these config slots:
+
+| Config slot | Type | Default | Description |
+|-------------|------|---------|-------------|
+| `reputation_policy` | `Kiosk::Reputation::Policy` instance (or duck type) | `nil` | Policy that decides when and how hard to challenge. `nil` = never challenge (zero overhead). |
+| `pow_secret` | String | required when policy is set | HMAC key for challenge signing. Load from env: `ENV.fetch("KIOSK_POW_SECRET")`. |
+| `pow_ttl` | Integer (seconds) | `300` | Challenge validity window. |
+| `pow_spent_store` | `#claim`/`#release`/`#spent?`/`#mark_spent` | `Kiosk::Server::PowSpentStores::ActiveRecord` (the `kiosk.pow_spent` table) | Tracks spent challenge ids so a proof is accepted once, across every process and deploy. See kiosk-server's README, "Multi-process deployments". |
+
+```ruby
+Kiosk.configure do |c|
+  c.reputation_policy = Kiosk::Reputation::Policies::RecentSpend.new(within: 1.week, cap: 100)
+  c.pow_secret        = ENV.fetch("KIOSK_POW_SECRET")
+  c.pow_ttl           = 300
+end
+```
+
+The engine supplies the factors. For a policy that answers `#within` (a window
+in seconds), it fills `settled_purchases_count` and `settled_purchases_cents`
+from the customer's own settlements and recorded visits in that window; for any
+other policy the factors are `Factors.empty`.
+
+The gate tolls once per access token: after one paid toll, every call made
+with that token proceeds until the token expires (`c.access_token_ttl`,
+default 3600 seconds).
+
+## Honesty / guardrails
+
+- **PoW is economic friction, not a wall.** A determined ASIC attacker still
+  gets in at some cost; the point is to make free-riding cost more than buying.
+  Combine it with a cheap path for genuine buyers: `RecentSpend` tolls a
+  customer less often as their recent spend grows.
+- **Reputation = a sum of factors the host supplies.** We ship tools and one
+  policy, not a mandated curve. Providers are expected to write
+  domain-specific policies that reflect their actual trust signals.
+- **The provider mandates the algorithm.** Clients comply or are denied — do
+  not add a negotiation path.
+- **Verify is cheap; the solve is the cost.** Equihash verify is a few ms + KB
+  (memory is the asymmetry: a few KB to verify, against a solve the reference
+  numpy solver runs in ~1.3 GiB at n=168 k=7 — that is THAT solver's
+  sorted-nonce table, not a floor those params impose on every solver, since a
+  memory-optimised solver trades the table for time, which is how Equihash
+  200/9's real footprint fell to ~144 MB), so the gate can check every request
+  — only *challenge* on suspicion/rate, since each challenge costs the client a
+  real solve.
+
+## Installation
+
+> **Not on RubyGems yet** — so every `gem` line below carries `github: "kiosk-hq/kiosk"`, which is what makes it copy-pasteable today. Publication status and the canonical install are stated once, in the monorepo README's [Install](https://github.com/kiosk-hq/kiosk#install) section.
+
+```ruby
+gem "kiosk-reputation",   github: "kiosk-hq/kiosk"
+gem "kiosk-pow-equihash", github: "kiosk-hq/kiosk"   # default backend
+# gem "kiosk-pow-argon2id", github: "kiosk-hq/kiosk" # legacy Argon2id backend, if you specifically want it
+```
+
+In a Rails app `kiosk-pow-equihash` registers itself as the `equihash`
+backend at boot. Any other backend is registered with `Backends.register`.
+
+## License
+
+Apache-2.0. See [LICENSE.txt](LICENSE.txt).

data/lib/kiosk/reputation/backends.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Reputation
+    # Registry of PoW backends by algorithm name; a backend answers `.verify(salt:, params:, nonce:)`.
+    # A backend is registered before the first challenge verify. In a Rails app
+    # kiosk-pow-equihash registers `equihash` itself at boot.
+    module Backends
+      @registry = {}
+
+      class << self
+        def register(alg_name, backend)
+          @registry[alg_name.to_s] = backend
+        end
+
+        def fetch(alg_name)
+          key = alg_name.to_s
+          @registry.fetch(key) do
+            raise KeyError,
+                  "Unknown PoW backend: #{key.inspect}. " \
+                  "Known algorithms: #{known.inspect}. " \
+                  "Register a backend with Kiosk::Reputation::Backends.register(#{key.inspect}, backend)."
+          end
+        end
+
+        # Could a challenge minted at `params` ever verify? False only when the
+        # registered backend's own optional `.valid_params?` says so.
+        def valid_params?(alg_name, params)
+          backend = @registry[alg_name.to_s]
+          return true unless backend.respond_to?(:valid_params?)
+
+          backend.valid_params?(params)
+        end
+
+        def known
+          @registry.keys.sort
+        end
+
+        def reset!
+          @registry = {}
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/reputation/challenge.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'base64'
+require 'securerandom'
+
+module Kiosk
+  module Reputation
+    # Stateless wire challenge for a `pow_required` answer: an HMAC over its fields
+    # and the request fingerprint, so it needs no storage and binds to one request.
+    # The caller keeps the spent-id set.
+    module Challenge
+      # Canonical-string delimiters; no field may contain one (see {delimiter_offence}).
+      OUTER_DELIM = '|'
+      PARAM_DELIM = ','
+      KV_DELIM = '='
+
+      DELIMITERS = [OUTER_DELIM, PARAM_DELIM, KV_DELIM].freeze
+
+      # The signed fields, in canonical-string order. `salt` is base64.
+      Fields = Data.define(:id, :alg, :params, :salt, :exp, :request_fingerprint)
+      private_constant :Fields
+
+      class << self
+        # @return [Hash] wire challenge: {id:, alg:, params:, salt: <base64>, exp:, sig:}
+        # @raise [ArgumentError] when a field carries a delimiter or `params` is not a Hash
+        def issue(alg:, params:, request_fingerprint:, secret:, ttl:, # rubocop:disable Metrics/ParameterLists -- public keyword signature; every keyword is part of it.
+                  now: Time.now.to_i,
+                  salt: SecureRandom.bytes(16),
+                  id: SecureRandom.uuid)
+          fields = Fields.new(id:, alg:, params:, salt: Base64.strict_encode64(salt), exp: now + ttl, request_fingerprint:)
+          offence = delimiter_offence(fields)
+          raise ArgumentError, ambiguity_message(offence) if offence
+
+          { id:, alg:, params:, salt: fields.salt, exp: fields.exp, sig: compute_sig(secret, fields) }
+        end
+
+        # Cheap checks run before the one expensive backend evaluation.
+        # `expect:` is the `{alg:, params:}` the caller re-derived from its live config.
+        # @return [Symbol] :ok | :bad_sig | :expired | :bad_params | :bad_proof
+        def verify(challenge:, nonce:, request_fingerprint:, secret:, now:, expect: nil) # rubocop:disable Metrics/ParameterLists -- public keyword signature; every keyword is part of it.
+          failure = check(challenge:, request_fingerprint:, secret:, now:, expect:)
+          return failure if failure
+
+          proof_valid?(fields_of(challenge, request_fingerprint), nonce) ? :ok : :bad_proof
+        end
+
+        # The cheap checks alone, so a caller can trust `id` and `exp` before it stores them.
+        # @return [Symbol, nil] :bad_sig | :expired | :bad_params, or nil when the challenge is ours and live
+        def check(challenge:, request_fingerprint:, secret:, now:, expect: nil)
+          cheap_failure(fields_of(challenge, request_fingerprint), challenge[:sig].to_s, secret, now, expect)
+        end
+
+        private
+
+        def fields_of(challenge, request_fingerprint)
+          Fields.new(id: challenge[:id], alg: challenge[:alg], params: challenge[:params],
+                     salt: challenge[:salt], exp: challenge[:exp], request_fingerprint:)
+        end
+
+        # The checks that cost no proof evaluation, in order. Nil when all pass.
+        def cheap_failure(fields, sig, secret, now, expect)
+          return :bad_sig unless constant_time_compare(compute_sig(secret, fields), sig)
+          return :expired unless fields.exp.to_i > now.to_i
+          # The signed string must have one pre-image.
+          return :bad_params if delimiter_offence(fields)
+
+          # The signature proves that we minted the challenge, not that we still demand it.
+          :bad_params unless matches_expected?(expect, fields.alg, fields.params)
+        end
+
+        # The one expensive step: a single backend evaluation.
+        def proof_valid?(fields, nonce)
+          Backends.fetch(fields.alg).verify(salt: Base64.strict_decode64(fields.salt),
+                                            params: fields.params.transform_keys(&:to_sym), nonce:)
+        end
+
+        def ambiguity_message(offence)
+          "challenge field would make the signed canonical string ambiguous: #{offence}. " \
+            'Fix the source of the value: the `alg`/`params` your reputation_policy returns ' \
+            'from #challenge_for.'
+        end
+
+        # A delimiter inside a value gives the canonical string a second pre-image,
+        # so one signature would cover two (alg, params) splits.
+        def delimiter_offence(fields)
+          outer_offence(fields) || params_offence(fields.params)
+        end
+
+        def outer_offence(fields)
+          field, value = fields.to_h.except(:params).find { |_, text| text.to_s.include?(OUTER_DELIM) }
+          "#{field} #{value.to_s.inspect} contains #{OUTER_DELIM.inspect}" if field
+        end
+
+        def params_offence(params)
+          return nil unless params.is_a?(Hash)
+
+          params.each do |key, value|
+            DELIMITERS.each do |delim|
+              return "params key #{key.to_s.inspect} contains #{delim.inspect}" if key.to_s.include?(delim)
+              return "params value #{value.to_s.inspect} (key #{key.to_s.inspect}) contains #{delim.inspect}" if value.to_s.include?(delim)
+            end
+          end
+          nil
+        end
+
+        # Compared in the signed rendering, so key order and key/value types never matter.
+        def matches_expected?(expect, alg, params)
+          return true if expect.nil?
+
+          expected_alg = expect[:alg] || expect['alg']
+          return false unless expected_alg.nil? || expected_alg.to_s == alg.to_s
+
+          expected_params = expect[:params] || expect['params']
+          return true if expected_params.nil?
+
+          params_string(expected_params) == params_string(params)
+        end
+
+        def compute_sig(secret, fields)
+          OpenSSL::HMAC.hexdigest('SHA256', secret, canonical_string(fields))
+        end
+
+        # id|alg|k=7,n=168|<salt_b64>|<exp>|<fingerprint>
+        def canonical_string(fields)
+          [fields.id, fields.alg, params_string(fields.params), fields.salt, fields.exp.to_s,
+           fields.request_fingerprint].join(OUTER_DELIM)
+        end
+
+        def params_string(params)
+          raise ArgumentError, "params must be a Hash (got #{params.inspect})" unless params.is_a?(Hash)
+
+          params
+            .sort_by { |k, _| k.to_s }
+            .map { |k, v| "#{k}#{KV_DELIM}#{v}" }
+            .join(PARAM_DELIM)
+        end
+
+        def constant_time_compare(expected, given)
+          return false if expected.bytesize != given.bytesize
+
+          OpenSSL.fixed_length_secure_compare(expected, given)
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/reputation/factors.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Reputation
+    # Reputation inputs per request. For a policy that answers `#within`, the
+    # engine fills both fields from its own settlements and recorded visits.
+    # Each field may be nil, so a policy reads them through `.to_i`.
+    Factors = Data.define(:settled_purchases_count, :settled_purchases_cents) do
+      def self.empty = new(settled_purchases_count: nil, settled_purchases_cents: nil)
+    end
+  end
+end

data/lib/kiosk/reputation/policies/recent_spend.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Kiosk
+  module Reputation
+    module Policies
+      # One proof-of-work toll per session, by chance. The chance falls linearly
+      # with what the customer spent here within `within` seconds: 1 with no
+      # spend, 0 at `cap` or more. The draw is made once per customer and token
+      # lifetime, so a new token minted in the same lifetime meets the same outcome.
+      class RecentSpend < Policy
+        attr_reader :within
+
+        # @param within [#to_i] the window in seconds, e.g. `1.week`
+        # @param cap [Integer] whole currency units of recent spend at which no session pays the toll
+        def initialize(within:, cap:)
+          super()
+          @within = within
+          @cap_cents = cap * 100
+        end
+
+        def challenge_for(identity:, factors:, **)
+          { alg: 'equihash', params: equihash_params, count: 1 } if draw(identity) < chance(factors.settled_purchases_cents.to_i)
+        end
+
+        # The chance that a session pays the toll: max(0, (cap - spend) / cap).
+        def chance(cents) = [(@cap_cents - cents).fdiv(@cap_cents), 0].max
+
+        private
+
+        # A number in [0, 1), set by the customer and the token lifetime that holds
+        # the token's `iat`: lifetimes are consecutive spans of `exp - iat` seconds
+        # from the Unix epoch. A caller whose token has no `iat` or `exp` draws 0,
+        # so it pays whenever its spend leaves a chance above 0.
+        def draw(identity)
+          claims = identity&.claims || {}
+          return 0 unless claims[:iat] && claims[:exp]
+
+          span = claims[:iat].div(claims[:exp] - claims[:iat])
+          Digest::SHA256.digest("#{identity.user_id}:#{span}").unpack1('Q>').fdiv(2**64)
+        end
+
+        # The Equihash gem's default params when it is loaded, so a test that shrinks them shrinks this toll too.
+        def equihash_params = defined?(::Kiosk::Pow::Equihash) ? ::Kiosk::Pow::Equihash.params : { n: 168, k: 7 }
+      end
+    end
+  end
+end

data/lib/kiosk/reputation/policy.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Reputation
+    # Base policy: never challenges. Providers subclass it.
+    class Policy
+      # The gate calls it with `identity:`, `verb:` and `factors:`. `verb` is the
+      # coarse CALL KIND: :query, :run or :pay (a `kind :action` handler arrives as :run).
+      # @return [Hash{alg: String, params: Hash, count: Integer}, nil] nil serves without challenge; `count` defaults to 1
+      def challenge_for(**)
+        nil
+      end
+    end
+  end
+end

data/lib/kiosk/reputation/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Reputation
+    VERSION = '0.5.20'
+  end
+end

data/lib/kiosk/reputation.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'kiosk/reputation/version'
+require 'kiosk/reputation/backends'
+require 'kiosk/reputation/challenge'
+require 'kiosk/reputation/factors'
+require 'kiosk/reputation/policy'
+require 'kiosk/reputation/policies/recent_spend'
+
+module Kiosk
+  # Policy and wire-challenge layer for proof of work, independent of any PoW
+  # algorithm. {Challenge} is stateless: the caller keeps the spent-id set.
+  module Reputation
+  end
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: kiosk-reputation
+version: !ruby/object:Gem::Version
+  version: 0.5.20
+platform: ruby
+authors:
+- Phil Pirozhkov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  kiosk-reputation decides *when* and *how hard* to challenge a request with a
+  proof-of-work, issues and verifies the signed wire challenge, and provides a
+  pluggable reputation policy interface.
+
+  Pure Ruby — no dependency on any PoW gem or kiosk-core. A PoW backend is
+  registered via Kiosk::Reputation::Backends.register: kiosk-pow-equihash
+  registers itself as "equihash" (the shipped default) in a Rails app; the host
+  registers kiosk-pow-argon2id as the legacy "argon2id" and kiosk-pow-cuckoo as
+  the opt-in "cuckatoo".
+
+  Anti-DoS invariant: Challenge.verify performs cheap HMAC-sig + expiry checks
+  BEFORE the one expensive backend eval, so floods of forged/expired proofs are
+  rejected without running a proof check.
+
+  Ships one policy, Policies::RecentSpend: it asks one proof of a session,
+  by a chance that the customer's recent spend lowers.
+email:
+- hello@fili.pp.ru
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/kiosk/reputation.rb
+- lib/kiosk/reputation/backends.rb
+- lib/kiosk/reputation/challenge.rb
+- lib/kiosk/reputation/factors.rb
+- lib/kiosk/reputation/policies/recent_spend.rb
+- lib/kiosk/reputation/policy.rb
+- lib/kiosk/reputation/version.rb
+homepage: https://kiosk.tech
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://kiosk.tech
+  source_code_uri: https://github.com/kiosk-hq/kiosk
+  changelog_uri: https://github.com/kiosk-hq/kiosk/blob/main/kiosk-reputation/CHANGELOG.md
+  bug_tracker_uri: https://github.com/kiosk-hq/kiosk/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Policy + wire-challenge layer for Kiosk's proof-of-work system
+test_files: []