requestshield 0.1.2 → 0.1.3

package/skills/requestshield/references/cli.md

@@ -0,0 +1,182 @@
+# `requestshield` CLI reference
+
+Every RequestShield platform action goes through this CLI. There is no supported way
+to create keys, read the contract, or check traffic by hand-crafting HTTP calls, so if
+a task needs one of these values, run the command rather than guessing.
+
+Commands marked **auth** require a signed-in session (`requestshield signin`). The CLI
+also exposes local commands that do not need platform API access, such as `--help`,
+`--version`, and agent setup. Check once with `auth status` before a multi-step
+platform task instead of discovering it halfway through an edit.
+
+Most commands print JSON shaped `{"ok": true, "data": {...}}`. Parse `data`; treat
+`ok: false` as a hard stop and surface the message rather than continuing with edits.
+
+## Contents
+
+- [General](#general)
+- [Authentication](#authentication)
+- [Key management](#key-management)
+- [Integration contract](#integration-contract)
+- [Applications](#applications)
+- [Credentials](#credentials)
+- [Service and monitoring](#service-and-monitoring)
+- [Billing](#billing)
+- [Agent integration](#agent-integration)
+
+## General
+
+| Command | Purpose |
+| --- | --- |
+| `requestshield --help` | Usage and the full command list. Run this if a command below is rejected — the installed CLI may be older or newer than this file. |
+| `requestshield --version` | Installed CLI version, e.g. `requestshield 1.0.0`. |
+| `requestshield update check` | Latest available version. Use it when behaviour disagrees with this reference. |
+
+## Authentication
+
+```bash
+requestshield signin
+requestshield auth status
+```
+
+**auth/API.**
+
+`signin` is interactive and stores a session on the machine. **Never try to automate
+it or ask for the user's credentials** — if the user is signed out, tell them to run it
+themselves and wait.
+
+`auth status` returns `{"ok":true,"data":{"authenticated":true,"customer_id":"customer_456"}}`.
+The `customer_id` is useful context to echo back so the user can confirm they are
+operating on the right account before you create or deactivate anything.
+
+## Key management
+
+**The user runs these, not you.** They print the API Secret or change state for a live
+App Key, so hand over the exact command and let them run it in their own terminal. See
+"Key and secret management" in `SKILL.md` for the hand-off and the follow-up
+presence check.
+
+```bash
+requestshield keys create --app-name <name>
+requestshield keys deactive --app-key <app-key>      # or --app-name <name>
+requestshield app key rotate --app-key <app-key>     # or --app-name <name>
+```
+
+`keys create` returns both halves:
+
+```
+App Key: app_123
+Secret Key: rs_sk_xxxxx
+Save this Secret Key now. It will not be shown again.
+```
+
+The Secret Key appears exactly once. Warn the user *before* they run the command that
+they need somewhere to put it, and afterwards point them at the environment variable
+rather than repeating the value. Never ask them to paste the secret back — confirm it
+only by presence. See the secret-handling rules in `SKILL.md`.
+
+`keys deactive` (spelled that way in the CLI) needs at least one of `--app-key` or
+`--app-name`; if both are given, `--app-key` wins. Deactivation stops traffic being
+verified for that key, so name the affected app explicitly when you hand the command
+over and make sure the user means that key.
+
+`app key rotate` issues a new Secret Key for an existing App Key and deactivates the
+previous one. This is the correct response to a leaked or lost secret — it keeps the
+App Key stable, so no browser or config change is needed beyond the new secret. Like
+`keys create`, the user runs it.
+
+## Integration contract
+
+```bash
+requestshield contract
+```
+
+**auth.** The authoritative integration surface — run this before writing any
+integration code. The block below is an **illustration of the shape only**; never read
+values out of it, and in particular do not treat its `available_modes` as the modes your
+customer has:
+
+```json
+{"ok":true,"data":{
+  "contract_version":"2026-08-27",
+  "browser":{"script_url":"https://.../intellifend.js","token_header":"X-IntelliFend-Token",
+             "available_modes":["manual"]},
+  "backend":{"supported_languages":["java"],"min_jdk":17},
+  "release_state":"..."}}
+```
+
+Use `script_url` and `token_header` verbatim. Check `available_modes` before committing
+to seamless or manual — a mode absent from that list is not released, and writing an
+integration against it produces code that will not work. Check `supported_languages`
+before promising a backend integration for a stack that is not listed; the browser side
+alone provides no protection, so an unsupported backend means the honest answer is
+"not yet supported here".
+
+## Applications
+
+```bash
+requestshield apps list
+requestshield apps get <app-key>
+```
+
+**auth.** `apps list` returns the applications the current user can access, each with
+`app_key`, `name`, and `status`. Use it to resolve a human-supplied app name to a key
+rather than asking the user to retype one.
+
+`apps get <app-key>` returns `app_id`, `app_name`, and `status`. Status distinguishes a
+key that has never seen traffic (`ready`) from one in normal service (`active`) — which
+is exactly the difference between "the integration is not wired up yet" and "it is
+working", so check it before spending time debugging code.
+
+## Credentials
+
+```bash
+requestshield credentials status <app-key>
+```
+
+**auth.** Returns metadata only — `provisioned`, `active`, `shared` — and never the
+secret value. Use it to answer "is the secret configured?" without anyone having to
+paste a credential. A key that is `provisioned: false` explains backend failures far
+faster than reading code.
+
+## Service and monitoring
+
+```bash
+requestshield server
+requestshield challenge volume <app-key> [--from <time>] [--to <time>] [--granularity <value>]
+```
+
+**auth.** `server` reports `healthy` or `degraded`. Check it first when an integration
+that was working starts behaving oddly — a degraded platform explains fail-open
+behaviour on the backend without anything being wrong in the customer's code.
+
+`challenge volume` is runtime evidence that the browser/platform half is active. It is
+not proof that the protected backend enforces a blocking decision; the controlled
+negative test in `SKILL.md` provides that evidence. Times are ISO-8601
+(`2026-08-01T00:00:00Z`); `--granularity` takes values such as `hour` or `day`. A
+`challenge_count` of zero after the user has exercised the endpoint means the browser
+half is not firing — that is a browser-side bug, not a backend one, so start with the
+mode's reference file.
+
+## Billing
+
+```bash
+requestshield get billing
+```
+
+**auth.** Current plan and usage for the application. Read-only; surface it when the
+user asks about cost or limits.
+
+## Agent integration
+
+```bash
+requestshield agent setup
+requestshield agent setup --agent claude
+requestshield agent setup --agent codex
+```
+
+Local setup. Installs this skill for the named agent. With no `--agent`, the CLI detects
+which agent is in use. Run it when the user wants the skill available in another repo or
+for the other agent; it is the supported alternative to copying files by hand. It should
+not require a RequestShield App Key or API Secret, and it must not create, rotate, or
+deactivate customer credentials.

package/skills/requestshield/references/integration-planning.md

@@ -0,0 +1,389 @@
+# Integration planning
+
+Use this reference before writing or removing RequestShield integration code. It owns the
+planning steps that are too detailed for `SKILL.md`.
+
+## Workflow by operation
+
+- **Install** -> `integration-planning.md` full flow: **Credentials check** ->
+  **Detect existing integration** -> **Contract check** -> **Gate** -> **Then act on
+  what you found** -> **Choosing the mode** -> **Installing** -> **Verifying** ->
+  **Negative test**.
+- **Verify / Troubleshoot** -> `integration-planning.md` (Detect existing integration
+  only) -> **Verifying**. If a reason code, degraded result, browser mode, backend path,
+  or unknown state is involved, read only the matching reference files.
+- **Uninstall** -> `integration-planning.md` (Detect existing integration only) ->
+  **Uninstalling**.
+
+Do not couple browser mode to backend path. They are independent axes:
+
+- Browser mode: Seamless (`browser-seamless.md`) or Manual (`browser-manual.md`).
+- Backend path: Spring Boot 3 starter (`backend-spring-boot.md`) or Java core SDK
+  (`backend-java-core.md`).
+
+Either browser mode may pair with either supported backend path. The backend stack
+selects the backend path. The way the browser issues the protected request selects the
+browser mode.
+
+## Credentials check
+
+The **pre-edit** check: confirm a credential source exists before touching backend
+integration code. This step belongs to the Install full flow.
+
+- **Install** — always, before editing backend code.
+- **Verify / Troubleshoot** — do not run this as part of the operation route. Start with
+  **Detect existing integration only**, then use `troubleshooting.md` if the evidence
+  points to a credential failure.
+- **Uninstall** — do not run this step; detect the existing integration only.
+
+Diagnosing a credential *failure* is a different question, and `troubleshooting.md`
+owns it — go there for `consume_unauthorized`, `unknown_customer`, or a backend
+rejecting every token, whether or not this check has already passed.
+
+RequestShield requires:
+
+- an App Key
+- an API Secret
+
+Check for credential sources without printing, reading, or echoing their values. Confirm
+presence only; never print, cat, or echo either value:
+
+```bash
+# Presence check only. Never print secret values.
+
+if env | grep -Eq '^(INTELLIFEND_)?REQUESTSHIELD_(APP_KEY|KEY)='; then
+  echo "RequestShield App Key: present"
+else
+  echo "RequestShield App Key: not found in current environment"
+fi
+
+if env | grep -Eq '^(INTELLIFEND_)?REQUESTSHIELD_(API_SECRET|SECRET)='; then
+  echo "RequestShield API Secret: present"
+else
+  echo "RequestShield API Secret: not found in current environment"
+fi
+```
+
+Common variable names are `INTELLIFEND_REQUESTSHIELD_APP_KEY`,
+`REQUESTSHIELD_APP_KEY`, `REQUESTSHIELD_KEY`,
+`INTELLIFEND_REQUESTSHIELD_API_SECRET`, `REQUESTSHIELD_API_SECRET`, and
+`REQUESTSHIELD_SECRET`. A matching non-canonical name is only a credential candidate.
+Confirm that the backend actually reads or maps that variable before treating it as a
+valid RequestShield credential.
+
+If the App Key is known, also confirm server-side credential state without exposing the
+secret:
+
+```bash
+requestshield credentials status <app-key>
+```
+
+A credential that is not present in the current shell is not necessarily missing from
+the deployed backend. It may be injected at runtime by a secret manager, CI/CD system,
+container runtime, Kubernetes Secret, or deployment environment.
+
+Report only what was confirmed:
+
+| Finding | Action |
+| --- | --- |
+| Both credential sources are confirmed | Continue. Never read their values. |
+| A non-canonical variable is found and its backend mapping is confirmed | Report the mapping and continue. |
+| Credentials are provisioned, but the runtime source is unknown | Ask how the deployed backend receives them before editing backend integration code. |
+| No credential source can be confirmed | Report the uncertainty and ask before proceeding. |
+| No credential pair has been provisioned | Ask the user to provision credentials before continuing with backend setup. |
+
+If no pair has been provisioned yet, the user creates it. You may run the read-only
+`requestshield apps list` to see whether an application already exists. Everything that
+mints or changes a secret stays with the user; see **Key and secret management** in
+`SKILL.md`.
+
+## Detect existing integration
+
+Search for existing RequestShield code before install, verify/troubleshoot, or uninstall.
+Use `rg` when available. Use `rg -l` for filename-only discovery.
+
+
+Browser markers:
+
+```bash
+rg -l "data-app-key|data-protect|IntelliFend|X-IntelliFend-Token" \
+  -g "*.html" -g "*.htm" -g "*.js" -g "*.jsx" -g "*.ts" -g "*.tsx" \
+  -g "*.vue" -g "*.svelte" -g "*.astro" \
+  -g "*.erb" -g "*.haml" -g "*.php" -g "*.jinja*" -g "*.j2" -g "*.twig" \
+  -g "*.hbs" -g "*.ejs" -g "*.pug" -g "*.blade.php" \
+  -g "!node_modules/**" -g "!**/skills/**" -g "!**/.requestshield/**" .
+```
+
+The tag often lives in a server-rendered layout rather than a static `.html` — a Django,
+Rails, Laravel, or Thymeleaf base template — so a scan limited to `.html`/`.js` reports
+"not integrated" on a codebase that already has one, and the install then adds a second
+tag. If the app's templates use an extension not listed above, add it before concluding.
+
+Backend markers:
+
+```bash
+rg -l "RequestShieldClient|RequestShieldProtected|intellifend|requestshield" \
+  -g "*.java" -g "*.kt" -g "*.xml" -g "*.yml" -g "*.yaml" \
+  -g "*.gradle" -g "*.gradle.kts" \
+  -g "!**/skills/**" -g "!**/.requestshield/**" .
+```
+
+`rg -l` returns candidate filenames only. Do not follow it with `cat`, an unrestricted
+`sed`, plain `rg -n` without `-o`, or another command that exposes complete matching
+lines or the entire file.
+
+Locate known markers without returning the rest of their lines:
+
+```bash
+rg -n -o \
+  "data-app-key|data-protect|IntelliFend|getToken|X-IntelliFend-Token" \
+  <browser-candidate-file>
+
+rg -n -o \
+  "RequestShieldClient|RequestShieldProtected|verify|isAllowed|intellifend|requestshield" \
+  <backend-candidate-file>
+
+rg -n -o \
+  "(INTELLIFEND_)?REQUESTSHIELD_(APP_KEY|KEY|API_SECRET|SECRET)" \
+  <candidate-configuration-file>
+```
+-o prints only the matched marker or environment-variable name, not the surrounding
+value. Environment-variable names are safe to report; their values are not.
+
+When configuration context is required, inspect it only through a secret-aware parser
+or redacted view that masks sensitive values before stdout reaches the agent. Its output
+may contain the filename, line number, configuration key, environment-variable name,
+App Key when needed to identify the integration, and whether the source is an
+environment reference, secret-manager reference, or literal.
+
+Replace every API Secret, RequestShield token, session value, CSRF value,
+authorization credential, and other credential literal with <redacted>.
+
+If no secret-aware parser or redacted view is available, do not read the candidate
+configuration file verbatim. Ask the user for a sanitized excerpt instead. Switching
+to rg -l and then reading the entire candidate file is not safe.
+
+The exclusions matter when this skill is installed inside the repo being scanned —
+browser and backend reference files contain marker strings and would otherwise read as
+an existing integration.
+
+Report one of:
+
+- **Not integrated**: no browser or backend markers.
+- **Browser only**: tokens may be obtained or attached, but no backend enforcement was
+  found. This looks protected and is not.
+- **Backend only**: enforcement exists, but no page sends a token. In BLOCK mode this can
+  reject legitimate users.
+- **Fully integrated**: browser mode and backend path are both present. Name both.
+
+If a script tag already exists, update it instead of adding a second one. The SDK
+initializes from `document.currentScript`; two tags mean two configurations, and the
+last one to run wins rather than the two merging.
+
+## Contract check
+
+Run this **after** detection and **before** the Gate: detection says what the codebase
+already does, the contract says what the platform currently allows, and the browser-mode
+decision needs both.
+
+```bash
+requestshield contract
+```
+
+It is authoritative for `browser.script_url`, `browser.token_header`,
+`browser.available_modes`, `backend.supported_languages`, and `backend.min_jdk`. Use
+those values verbatim; a stale hardcoded script URL produces a page that loads nothing
+and fails silently.
+
+Treat every array as an **allow-list**. There is no "unavailable" flag, so something is
+unavailable when it is absent — and an absent, empty, or unparseable array is
+unavailable, not permission. If the contract is missing or returns `ok: false`, stop and
+report what the CLI returned.
+
+### Backend consequences — these feed the Gate
+
+- `backend.supported_languages` missing the customer's backend language → **stop.** No
+  backend path exists, and a browser-only install protects nothing.
+- `backend.min_jdk` above the project's Java target → **stop.** The JDK upgrade is the
+  prerequisite; do not fall back to an older SDK version.
+
+### Browser-mode consequences — these decide the mode
+
+Read `browser.available_modes` together with what detection found in the codebase:
+
+| Released modes | Codebase today | Do this |
+| --- | --- | --- |
+| **One mode** | already uses that mode | Keep it. Nothing to change on the browser side. |
+| **One mode** | uses the *other* mode | **This is a finding, not a preference.** The mode in the codebase is not released, so it cannot be relied on. Report it and migrate the client to the released mode. |
+| **One mode** | not integrated | No choice to make. Install that mode, and say which one and why. |
+| **Both modes** | already uses one of them | **Keep the mode already in use.** Change it only for a concrete reason — the transport is one Seamless cannot cover, or the user asks. A mode switch rewrites working call sites and risks leaving an endpoint half-migrated. |
+| **Both modes** | not integrated | A genuine choice. Go to **Choosing the mode** below. |
+| **Neither** | any | **Stop.** No browser mode is released; report the contract output. |
+
+Per-endpoint, not per-repo: a page may legitimately run Seamless on one endpoint and
+Manual on another. Apply the table to the operation being worked on, not to the codebase
+as a whole.
+
+## Gate
+
+The backend path is decided by the backend stack, not by browser preference. Establish
+this before proposing edits. Discovering a backend blocker after the browser half is
+written leaves tokens flowing with nothing enforcing them.
+
+An integration is one backend path plus one browser mode, and they are independent
+choices. A non-Spring-MVC backend does not rule out Seamless mode; it only rules out the
+Spring Boot 3 starter backend path.
+
+Backend path:
+
+| Backend path | Requirement | Reference |
+| --- | --- | --- |
+| **Spring Boot 3 starter** | Spring Boot 3 with Spring MVC, and Java 17+ | `backend-spring-boot.md` |
+| **Java core SDK** | Java 17+ | `backend-java-core.md` |
+
+Browser mode:
+
+| Browser mode | Use when | Reference |
+| --- | --- | --- |
+| **Seamless** | The page reaches the endpoint with `fetch` or async `XMLHttpRequest` | `browser-seamless.md` |
+| **Manual** | The call needs explicit token timing, or a non-header carrier | `browser-manual.md` |
+
+Either browser mode pairs with either backend path. The token travels in
+`X-IntelliFend-Token` regardless. Java below 17 blocks both backend paths, and no amount
+of browser-side work substitutes for backend enforcement.
+
+### Run the check
+
+Find the build file for the module that serves the protected endpoint, not the first one
+in the tree. In a monorepo, locate the route first:
+
+```bash
+find . -maxdepth 4 \( -name pom.xml -o -name "build.gradle*" \) \
+  -not -path "*/node_modules/*" -not -path "*/build/*" -not -path "*/target/*"
+rg -n "/api/register" -g "*.java" -g "*.kt" .
+```
+
+One build file, inspect it. Several, and the route cannot be tied to one of them — or
+several backends could plausibly serve it — **stop and ask which service owns the
+endpoint.** Two backends in a monorepo can differ in both Java version and framework, so
+a guess here invalidates the whole integration rather than needing a tweak.
+
+Use repo-wide build-file scans only for discovery. Do not combine a route found in one
+module with Java or Spring evidence from another module.
+
+#### Java target version
+
+Read the *project's target*, never the machine's JDK.
+
+```bash
+rg -n "maven\.compiler\.(release|source|target)|<release>|<java\.version>" <owning-pom.xml>
+rg -n "languageVersion|sourceCompatibility|jvmToolchain|JavaVersion" <owning-build.gradle*>
+```
+
+- **Maven** — `maven.compiler.release`, or the compiler plugin's `<release>`, is
+  authoritative. Spring Boot's parent POM exposes `<java.version>`, which is the
+  idiomatic place in a Boot app. **Check the parent POM too** when the module inherits;
+  the value is often not in the module's own file.
+- **Gradle** — `java.toolchain.languageVersion = JavaLanguageVersion.of(21)` and
+  `kotlin { jvmToolchain(21) }` are both authoritative, and both easy to miss because
+  they sit inside a block rather than on a property line.
+- **When the build file says nothing** — `.java-version`, `.sdkmanrc`, `.tool-versions`,
+  a `setup-java` step's `java-version` in `.github/workflows/`, or a JDK base image in a
+  `Dockerfile`. These are **hints, not answers**: they describe an environment, which can
+  differ from what the build compiles against. A build file that yields only hints is the
+  ambiguous row below — ask.
+- `java -version` reports the **local** JDK. A repo targeting 11 builds fine on a machine
+  with 21 installed, so it is a last-resort hint and never evidence.
+
+Java below 17 blocks **both** backend paths. Report the version and its source and name
+the upgrade as the prerequisite; do not fall back to an older SDK version or write a
+partial browser-only integration.
+
+#### Spring Boot 3, and separately Spring MVC
+
+Two conditions. Both must hold for the Spring Boot starter.
+
+```bash
+rg -n "spring-boot-starter-parent|spring-boot-dependencies|org\.springframework\.boot" \
+  <owning-pom.xml-or-build.gradle*> | rg "3\.[0-9]+"
+rg -n "spring-boot-starter-web[\"' :<]|spring-boot-starter-webflux|spring-webmvc" \
+  <owning-pom.xml-or-build.gradle*>
+```
+
+Read the parent version, the `spring-boot-dependencies` BOM version, or the Gradle plugin
+version. **Spring Boot 2.x does not qualify** — the starter is a Boot 3 artifact, so a
+2.x app needs the core SDK path even though it is Spring.
+
+Then MVC versus WebFlux — the trap worth checking every time:
+
+- `spring-boot-starter-web` → Spring MVC. The starter is available when the app is also
+  Spring Boot 3 on Java 17+.
+- `spring-boot-starter-webflux` with no `-web` → **not** Spring MVC. The starter protects
+  Spring MVC handler methods, so `@RequestShieldProtected` does not apply. Such an app is
+  Spring Boot 3 on Java 17+ and still needs the Java core SDK — say so explicitly,
+  because "Spring Boot 3, Java 21" reads like a starter green light and quietly is not.
+  Browser mode is unaffected; Seamless remains available when the request transport
+  matches.
+- **Both present** → determine which stack serves the protected route. A
+  `@RestController` returning `Mono`/`Flux`, or a `RouterFunction`, indicates the
+  reactive path. Ask if it stays unclear.
+
+Also not Spring MVC, and therefore the Java core SDK backend path: **Quarkus, Micronaut,
+Dropwizard, Helidon, Ktor, Vert.x, Jakarta EE / JAX-RS on its own, and a plain servlet
+application.**
+
+## Then act on what you found
+
+This decision chooses the backend path only. Pick the browser mode separately from how
+the page issues the protected request.
+
+| Detected | Do this |
+| --- | --- |
+| Java < 17, or no Java backend | Stop before editing. Report the finding and its source; no backend path is available, so nothing can enforce. Name the upgrade as the prerequisite. |
+| Java 17+, no Spring Boot 3 MVC | Use Java core SDK. It is the only backend option; state it rather than asking a fake choice. |
+| Java 17+ and Spring Boot 3 MVC | Both backend paths are viable. Recommend the starter and confirm once. |
+| Ambiguous module, missing build file, version only in environment hints, or unclear MVC/WebFlux ownership | Ask, showing what you found. |
+
+Always report the evidence with file and line references:
+
+```text
+Backend: theair-customer-backend/build.gradle.kts
+  Java 21           - java.toolchain.languageVersion (line 14)
+  Spring Boot 3.2.1 - org.springframework.boot plugin (line 3)
+  Spring MVC        - spring-boot-starter-web (line 20)
+Backend path: Spring Boot 3 starter. Browser mode still depends on released modes and request transport.
+```
+
+Detection is inference from build files. If any line would read "unknown", ask rather
+than assume.
+
+## Choosing the mode
+
+Reach this section only when **Contract check** left a genuine choice: both modes
+released, and this operation not already integrated. If it landed on any other row of
+that table, the mode is already decided — do not re-open it here.
+
+This is the browser half. Backend path does not constrain it. Both browser modes deliver
+the token in `X-IntelliFend-Token`, which either backend path reads.
+
+| | **Seamless** | **Manual** |
+| --- | --- | --- |
+| Browser | `data-protect` lists exact endpoints; the SDK attaches tokens to matching `fetch` and async XHR requests. | `await IntelliFend.getToken()` at each protected call site, attached in application code. |
+| Requires | The request travels by `fetch` or async XHR from page scope. | Nothing beyond the SDK and a supported carrier. |
+| Code touched | One line of HTML. | Every protected call site, plus every retry path. |
+| Backend work | Identical either way: whichever backend path the Gate selected. | Identical either way: whichever backend path the Gate selected. |
+
+Released-mode availability was already settled at **Contract check**. One question is
+left: does the protected request travel by `fetch` or asynchronous `XMLHttpRequest` from
+page scope? Native form POST, `sendBeacon`, WebSocket/EventSource, synchronous XHR,
+`no-cors`, and service-worker-owned requests are not intercepted — read
+`browser-seamless.md` for the full coverage list.
+
+Recommend Seamless when that check passes. It touches one line instead of every call
+site, so there is no missed call site or retry path. If it fails, use Manual and give
+the reason; that is a finding, not a preference.
+
+A given protected operation uses one mode, not both. Different endpoints on the same
+page may use different modes when necessary. Never use two backend verification paths on
+one request; `@RequestShieldProtected` and manual `RequestShieldClient.verify()` both
+consume the token, so the second returns `token_replayed`.