requestshield 0.1.2 → 0.1.3

package/skills/requestshield/SKILL.md

@@ -1,44 +1,307 @@
 ---
 name: requestshield
-description: Set up or remove IntelliFend RequestShield protection in a customer application using the repository's Browser SDK and supported backend SDK. Use when the user asks an AI agent to integrate, configure, validate, or remove RequestShield protection.
+description: Install, verify, troubleshoot, or remove IntelliFend RequestShield bot protection in a customer codebase — the browser SDK in Seamless or Manual mode, plus Java backend enforcement via the Spring Boot 3 starter or the Java core SDK — driving the `requestshield` CLI for sign-in, app keys, the integration contract, and traffic checks. Use this skill whenever the user mentions RequestShield, IntelliFend, `X-IntelliFend-Token`, `IntelliFend.getToken()`, `data-protect`, `@RequestShieldProtected`, App Key or API Secret setup, or asks to protect an endpoint such as registration, sign-in, password reset, checkout, or form submission from bots, scripted abuse, or credential stuffing — even when they never name the product. Also use it before hand-editing any file that already contains a RequestShield script tag, `verify()` call, or protection annotation.
 ---
 
-# RequestShield Integration
-
-Work only inside the customer's application repository. Do not access or modify
-IntelliFend operator infrastructure, Cloudflare resources, or customer records.
-
-Before editing, identify the frontend and backend frameworks and inspect the
-relevant dependency and configuration files. Explain the files that will change.
-Do not place the backend Secret Key in source, browser configuration, URLs, logs,
-or committed files. The public App Key may be included in browser configuration.
-
-## Set up protection
-
-1. Obtain the public App Key, backend-only Secret Key, and Challenge Server URL
-   from the customer. If the Secret Key is unavailable, stop and ask the user to
-   put it in their backend secret manager; never ask them to paste it into chat.
-2. Configure the Browser SDK with the App Key, Challenge Server URL, and exact
-   protected endpoint URLs. Query strings and fragments do not participate in
-   matching; path case and trailing slash do.
-3. Configure the supported backend SDK with the same App Key and a secret-store
-   reference for the Secret Key. For Spring Boot 3 MVC, protect the actual
-   mutation method with `@RequestShieldProtected`.
-4. For a new endpoint, start in `MONITOR`; move to `BLOCK` only after verifying
-   browser matching, backend outcomes, and CORS. Cross-origin customer APIs must
-   allow `X-IntelliFend-Token`.
-5. Run the project's normal lint, build, and tests. Report any manual secret or
-   deployment step without performing external deployment unless requested.
-
-Do not combine a manual `RequestShieldClient.verify(token)` call with annotation
-enforcement on the same request: the token is single-use and would be consumed
-twice.
-
-## Remove protection
-
-Remove only RequestShield-owned integration: browser initialization/protected
-URL entries, backend annotation/configuration, and dependencies that have no
-remaining callers. Preserve unrelated CORS, environment, build, and application
-configuration. Never delete or rotate remote keys as part of source removal.
-Run the project's normal validation after the change.
+# RequestShield integration
 
+Every RequestShield integration has two halves, and the split is the thing to
+understand before writing any code:
+
+1. **The browser** obtains a short-lived token and transports it with the protected
+   request, as the `X-IntelliFend-Token` header.
+2. **The backend** evaluates that token and enforces the decision before the protected
+   operation runs.
+
+The browser half is a *transport*, never a gate. A page that obtains tokens whose
+backend never verifies them has zero protection while looking fully integrated — the
+most common way this integration silently fails. Equally, an annotation on a handler
+creates no browser configuration. **Browser configuration and backend protection are
+configured independently, and neither one implies the other.** Land both halves in the
+same change and verify both.
+
+Protect the operation that performs the business mutation — registration, sign-in,
+password reset, checkout, form submission — not a read-only route in front of it.
+
+## Before touching integration files
+
+```bash
+requestshield --version          # is the CLI present?
+requestshield auth status        # {"authenticated":true,...} — most commands need this
+```
+
+
+If `requestshield --version` fails, the CLI is not installed. **Stop and say so.** Ask
+the user to install it; do not substitute hand-crafted HTTP calls, and do not fall back
+to the example values in this skill — the contract is the only authoritative source for
+the script URL, header name, and released modes, and a guessed script URL produces a
+page that silently loads nothing.
+
+If `auth status` shows the user signed out, ask them to run `requestshield signin`
+themselves — it is interactive. Never script around it or ask for credentials.
+
+Those commands are the preflight for integration-changing work. For read-only CLI
+questions, go to **Classify the request** and run only the matching command.
+
+## Classify the request
+
+Only **Install** and **Uninstall** are step-locked sequences. Every other intent is a
+single CLI call or a short answer. Match on what the user wants, not on exact wording.
+
+| Intent | Sounds like | Do this |
+| --- | --- | --- |
+| **General info** | "what version", "is there a newer CLI", "am I up to date" | `requestshield --version`, then `requestshield update check`. Report both and the gap between them. No credentials check, no repo scan. |
+| **Authentication** | "sign me in", or preflight `auth status` came back unauthenticated | Ask the user to run `requestshield signin` in their own terminal, and wait. It is interactive — never automate it, never run it for them, never ask for credentials. Re-run `auth status` once they confirm. |
+| **Key / secret management** | "create an app key", "I need an API Secret", "rotate the secret", "deactivate a key" | **Hand the command over; do not run it.** → "Key and secret management" below. |
+| **Install** | "add RequestShield", "protect /api/register" | `references/integration-planning.md` full flow → **Installing** → **Verifying** → **Negative test**. Do not reorder or skip a step. |
+| **Uninstall** | "remove it", "roll it back" | `references/integration-planning.md` (Detect existing integration only) → **Uninstalling**. |
+| **Verify / troubleshoot** | "is it set up right?", "why is it not blocking?", a reason code | `references/integration-planning.md` (Detect existing integration only) → **Verifying**. For a reason code, also read `references/troubleshooting.md`. |
+| **Challenge volume** | "how much traffic", "how many challenges", "show me the volume" | Ask for the time range first. `challenge volume` takes `--from`/`--to`/`--granularity`; a guessed window produces a confident wrong answer. Then run it with the App Key. |
+| **Billing** | "am I being charged", "what plan", "what are my limits" | `requestshield get billing`. |
+| **Service health** | "is the service up", "is it degraded" | `requestshield server`. |
+| **Agent setup** | "set this up for Codex too", "install the skill for Claude" | Run `requestshield agent setup` for auto-detection, or pass the requested agent: `--agent codex` or `--agent claude`. This installs agent guidance; it does not mint keys or edit customer application code. |
+| **Anything else** | | Look the command up in `references/cli.md`. If it is not there, run `requestshield --help` rather than guessing at a flag. |
+
+Full CLI surface, output shapes, and which commands need auth: `references/cli.md`.
+
+
+For Install, `references/integration-planning.md` owns the full planning sequence:
+Credentials check, Detect existing integration, Contract check, Gate, Then act on what
+you found, and Choosing the mode. Keep the browser-mode and backend-path decisions
+independent.
+
+## Key and secret management
+
+`keys create`, `app key rotate`, and `keys deactive` are the one place you do **not**
+drive the CLI. Two independent reasons, and each is sufficient on its own:
+
+- `keys create` and `app key rotate` print the API Secret to stdout exactly once. A
+  command you run puts that value in your tool output and transcript.
+- `keys deactive` and `app key rotate` change state for a live App Key. Deactivating the
+  wrong one stops verifying real traffic.
+
+So hand it over. Tell the user which command to run in their own terminal:
+
+```bash
+requestshield keys create --app-name <name>          # new App Key + API Secret pair
+requestshield app key rotate --app-key <app-key>     # new secret, App Key unchanged
+requestshield keys deactive --app-key <app-key>      # stops verification for that key
+```
+
+Warn them **before** they run secret creation or rotation that the secret appears once
+and they need somewhere to put it. Afterwards, confirm by presence only and use
+`requestshield credentials status <app-key>` for the server-side view. Never ask the
+user to paste the secret back, and never read it out of a file or the environment.
+
+A lost or exposed secret cannot be re-displayed. The fix is `app key rotate`, run by
+the user. Deleting a leaked value from a repo, log, artifact, or transcript does not
+un-expose it.
+
+## Installing
+
+For Install, run the full planning flow in `references/integration-planning.md` before
+writing integration code: **Credentials check** → **Detect existing integration** →
+**Contract check** → **Gate** → **Then act on what you found** → **Choosing the mode**.
+It must settle the App Key, the existing-integration state, the contract values, the
+backend path, and the browser mode before step 1 below.
+
+1. **Browser side** — add the hosted script once in `<head>`, using the `script_url`
+   from `requestshield contract`, then follow the chosen browser reference:
+   - Seamless → `references/browser-seamless.md`
+   - Manual → `references/browser-manual.md`
+2. **Backend side** — add the dependency, configure `app-key` and `api-secret` from
+   environment variables, and enforce the decision before the mutation:
+   - Spring Boot 3 starter → `references/backend-spring-boot.md`
+   - Java core SDK → `references/backend-java-core.md`
+3. **Cross-origin API**, if the protected endpoint is on another origin — its CORS
+   response must allow the page origin, intended methods, and `X-IntelliFend-Token`.
+4. **CSP**, if the app sends one — merge, never replace. See
+   `references/browser-manual.md`.
+5. **Verify** — run the checklist below, then the negative test when safe.
+
+## Handling the App Key and API Secret
+
+These two values have opposite handling rules:
+
+- **App Key** is public. It belongs in the browser script tag and backend configuration.
+  The same value must appear on both sides or every token fails.
+- **API Secret** is backend-only. It must reach the backend through an environment
+  variable or secret manager. Never write it into a source file, a committed `.env`, an
+  image layer, a CI config in the repo, or the chat transcript — and never echo it back
+  after reading it.
+
+You never run the commands that display the API Secret, and you never read it back. The
+hand-off and warning are in **Key and secret management** above. Afterwards refer to it
+only as "the secret you just received".
+
+If a secret has already reached a repo, a log, an artifact, or this transcript, the fix
+is `requestshield app key rotate --app-key <app-key>`, run by the user.
+
+## Verifying
+
+For standalone Verify / Troubleshoot, first run **Detect existing integration only** in
+`references/integration-planning.md`. You are observing which browser mode and backend
+path are in use, not choosing them — **Credentials check**, **Contract check**,
+**Gate**, and **Choosing the mode** belong to the Install flow unless troubleshooting
+evidence specifically points to a credential failure or an unreleased mode.
+
+Then the static checks. They are deterministic and catch most real breakage.
+
+- Exactly **one** SDK script tag, in `<head>`, loaded before any bundle that can issue a
+  protected request, with a real `data-app-key`.
+- Seamless: every protected endpoint appears in `data-protect`, spelled as the exact
+  origin and pathname the browser actually requests — case and trailing slash included.
+- Manual: every protected call site obtains a fresh token immediately before the request
+  and attaches it, including retry paths.
+- Neither mode applied twice to the same operation.
+- Backend: the dependency resolves, the App Key matches the browser's, the secret comes
+  from the environment, and the decision gates the mutation rather than only being
+  logged. Exactly one verification path per request.
+- Cross-origin endpoints: CORS allows `X-IntelliFend-Token`.
+- No token or secret in logs, analytics, URLs, or error reporting.
+
+Structural correctness is not proof of enforcement. For runtime evidence, exercise the
+endpoint and confirm the platform saw the traffic:
+
+```bash
+requestshield challenge volume <app-key> \
+  --from <start> \
+  --to <end> \
+  --granularity hour
+```
+
+Report static correctness and platform traffic separately. A flat zero after real
+traffic means the browser half is not firing; go back to the selected browser reference
+before changing backend code.
+
+### The negative test — the only proof of enforcement
+
+Neither static checks nor `challenge volume` can prove the backend refuses a tokenless
+mutation. The proof is a request the backend should reject.
+
+Before running it, establish:
+
+1. `requestshield server` is healthy. This reports platform health only; it does not prove
+   that the backend under test can reach the Challenge Server or that its local circuit
+   has closed. A healthy platform can still produce a degraded result at that backend.
+2. The endpoint's effective mode is `BLOCK`, not `MONITOR`. Include any method-level
+   override when resolving the effective mode. `MONITOR` allows every request by design.
+3. A valid control request is available. Its authentication, session, CSRF state, route,
+   method, and body must remain valid during the comparison.
+4. Establish a way to observe degradation for the backend instance and App Key under
+   test. For the Spring Boot starter, use the `intellifend.requestshield.requests` metric and distinguish
+   `outcome=allowed, reason=ok` from `outcome=degraded, reason=service_unavailable`. For
+   the Java core SDK, use existing safe metrics or logs derived from `isDegraded()` and
+   `getReason().getCode()`. Never log the raw token, API Secret, session, or CSRF value.
+
+**Confirm with the user before running this anywhere shared.** It exercises a real
+mutation, so use a local or staging environment, or an endpoint whose write can be
+undone. Do not fire it at production to "just check", and do not invent a body that
+could create a real account.
+
+First, send the control request through the normal integrated path with a fresh
+RequestShield token. Confirm that it succeeds, reaches the intended mutation, and records
+a non-degraded `ok` decision at the backend. A successful response produced by degraded
+fail-open is not a valid control. Use a new token for every control attempt because
+RequestShield tokens are single-use.
+
+Then repeat the same request while preserving its valid authentication, session, CSRF
+state, route, method, body, and other relevant headers. Remove only
+`X-IntelliFend-Token`. Send it through a client that bypasses the Browser SDK so Seamless
+mode cannot attach another token:
+
+```bash
+curl -i -X POST https://<host>/api/register \
+  -H '<the same valid authentication and CSRF context>' \
+  -H 'Content-Type: application/json' \
+  -d '{ ...the same valid test body... }'
+```
+
+Attribute the result to RequestShield rather than treating every 4xx as a pass.
+Authentication, authorization, CSRF, and request validation can independently return a
+401, 403, or 400 before the protected mutation.
+
+- **Spring Boot 3 starter:** pass only when the response is HTTP 403 with
+  `CHALLENGE_FAILED` and reason `missing_token`, and the handler produced no side effect.
+- **Java core SDK:** read the handler before testing. Confirm that its
+  `!result.isAllowed()` branch rejects before the mutation, then verify that the
+  observed rejection corresponds to RequestShield's `missing_token` decision and
+  produced no side effect.
+- **Any unrelated or unattributable 4xx:** inconclusive, not a pass. Fix the control
+  request or add safe RequestShield-specific observability before drawing a conclusion.
+- **Any backend-specific degraded evidence, including `service_unavailable`:**
+  inconclusive. The SDK intentionally allows the request under its availability policy; 
+  restore the backend's Challenge Server connectivity, wait for its circuit to recover, 
+  and repeat with a new control token.
+
+A `2xx`, or evidence that the mutation happened, is a confirmed missing-token
+enforcement bypass only when backend-specific degradation has been ruled out for that
+request. If backend-specific degradation evidence is absent or cannot be checked, 
+report the test as inconclusive—not as proof that enforcement is absent. When degradation 
+is ruled out, treat the bypass as the finding and go to `references/troubleshooting.md`.
+
+## Uninstalling
+
+Run `references/integration-planning.md` Detect existing integration only before this
+section. Remove only what RequestShield introduced, and confirm the list with the user
+first:
+
+1. The script tag, including `data-protect` and any other RequestShield attributes.
+2. Manual-mode `getToken()` calls and the header lines they feed — leave the surrounding
+   request intact.
+3. The backend dependency, client configuration, and the enforcement: `verify()` calls
+   or `@RequestShieldProtected` annotations.
+4. RequestShield entries in the CSP header and in CORS allowed headers — leave every
+   other source and header in place.
+5. Configuration keys and environment variable references.
+
+Then ask whether to also deactivate the keys server-side:
+`requestshield keys deactive --app-key <app-key>`. That is not reversible the way a
+code edit is, so it stays the user's explicit call.
+
+## Non-negotiables
+
+These separate an integration that protects traffic from one that only looks like it:
+
+- **Enforcement lives in the backend.** Application code in the browser must never
+  decide to allow, block, retry around, or interpret a token.
+- **Browser configuration and backend protection are independent.** Neither implies the
+  other.
+- **One browser mode and one backend path are selected independently.** Seamless is not
+  Spring Boot, and Manual is not Java core. Either browser mode may pair with either
+  supported backend path.
+- **One token per protected request; a new token before every retry.** Tokens are
+  single-use; replaying one returns `token_replayed` and blocks the request.
+- **One verification per request.** Never combine `@RequestShieldProtected` with a
+  manual `RequestShieldClient.verify()` on the same handler.
+- **Forward a non-empty token unchanged.** Do not trim, re-encode, inspect, cache,
+  persist, log, or place it in a URL.
+- When `getToken()` returns an empty string in Manual mode, omit the header and let the
+  backend apply its configured policy.
+- **The API Secret stays at the backend.** Never put it in browser code,
+  client-visible responses, source control, logs, build artifacts, or chat transcripts.
+- **You never run a command that mints, rotates, or deactivates a key.** Hand those
+  commands to the user and verify by presence only.
+
+## Reference files
+
+| File | Read it when |
+| --- | --- |
+| `references/cli.md` | Any CLI invocation — exact syntax, output shape, auth requirements |
+| `references/integration-planning.md` | Credentials check, existing-integration detection, the contract check, backend gating (Java version, Spring Boot 3 MVC vs WebFlux, other frameworks), and browser-mode selection |
+| `references/browser-manual.md` | Installing or auditing Manual mode; CSP rules |
+| `references/browser-seamless.md` | Installing or auditing Seamless mode; matching and coverage limits |
+| `references/backend-spring-boot.md` | Backend work on Spring Boot 3 MVC — the annotation path |
+| `references/backend-java-core.md` | Backend work on any other Java 17 backend — the `verify()` path |
+| `references/troubleshooting.md` | A block, a degraded result, or a reason code to explain |
+
+## For agent setup
+
+`requestshield agent setup` installs this skill for the detected or requested agent.
+Use `--agent codex` or `--agent claude` when the user names the target agent. For Codex
+repositories that also use `AGENTS.md`, the CLI can write the managed block from
+`assets/AGENTS.codex.md` so repo-local guidance points back to the installed skill and
+the same reference files.
+
+Agent setup installs guidance only. It does not mint keys, rotate secrets, deactivate
+keys, or edit customer application code.

package/skills/requestshield/assets/AGENTS.codex.md

@@ -0,0 +1,62 @@
+<!-- requestshield:begin — managed by `requestshield agent setup --agent codex`. Edit the skill source, not this block. -->
+## RequestShield integration
+
+This repository uses IntelliFend RequestShield to protect selected operations from
+automated abuse. Before installing, verifying, changing, or removing that protection —
+and before hand-editing any file that already contains a RequestShield script tag,
+`data-protect`, `X-IntelliFend-Token`, `IntelliFend.getToken()`, `verify()`, or
+`@RequestShieldProtected` — read `.requestshield/skill/SKILL.md` and follow it.
+
+The procedure exists because the failure mode here is silent. Every integration has two
+halves: the browser obtains and transports a token, and the backend evaluates it before
+the protected operation. They are configured **independently and neither implies the
+other** — a page that obtains tokens whose backend never verifies them has zero
+protection and looks fully integrated, and an annotated handler creates no browser
+configuration.
+
+The backend path is decided by the backend stack, not by browser preference: the
+**Spring Boot 3 starter** needs Spring Boot 3 with Spring MVC and Java 17+, while the
+**Java core SDK** needs Java 17+. The browser mode is a separate transport choice:
+Seamless needs a released Seamless mode and a protected request sent by `fetch` or
+asynchronous XHR; Manual is for explicit token timing or other supported carriers.
+Check both halves before proposing edits — finding a backend blocker afterwards leaves
+tokens flowing with nothing enforcing them. Java below 17 blocks both backend paths.
+
+Orientation:
+
+- `.requestshield/skill/SKILL.md` — the procedure. Start here.
+- `.requestshield/skill/references/integration-planning.md` — the planning flow:
+  credentials check, detecting an existing integration, gating on the backend stack
+  (Java version, Spring MVC vs WebFlux, other frameworks), and choosing the browser mode.
+  Read it before any install, verify, or uninstall.
+- `.requestshield/skill/references/cli.md` — the `requestshield` CLI; every platform
+  action (sign-in, keys, contract, traffic checks) goes through it.
+- `.requestshield/skill/references/browser-seamless.md` — Seamless mode: exact-endpoint
+  matching, and the transports it does not cover.
+- `.requestshield/skill/references/browser-manual.md` — Manual mode, carriers, CORS, CSP.
+- `.requestshield/skill/references/backend-spring-boot.md` — enforcement on Spring Boot 3
+  MVC: the `@RequestShieldProtected` annotation path.
+- `.requestshield/skill/references/backend-java-core.md` — enforcement on any other
+  Java 17 backend: the `verify()` path.
+- `.requestshield/skill/references/troubleshooting.md` — reason codes and diagnosis.
+
+Five rules worth carrying without opening a file:
+
+- The **API Secret** never enters source control, logs, or a reply. It belongs in backend
+  runtime secret storage, and `requestshield app key rotate` is the fix if it leaks. The
+  **App Key** is public and must be identical in browser and backend.
+- **Never run `keys create`, `app key rotate`, or `keys deactive` yourself.** They print
+  the secret or change state for a live key. Hand the command to the user, have them
+  export `INTELLIFEND_REQUESTSHIELD_APP_KEY` and
+  `INTELLIFEND_REQUESTSHIELD_API_SECRET`, and confirm by presence only.
+- Every protected request needs its **own token, verified exactly once**. Reuse or a
+  second verification path returns `token_replayed` and blocks a legitimate request.
+- **Enforcement lives in the backend.** Never put allow/block/retry logic in the browser,
+  and never build a decision table from reason codes in application code.
+- In Manual mode, attach `X-IntelliFend-Token` **only when `getToken()` returns a
+  non-empty string**; when it is empty, omit the header and let the backend apply its
+  configured policy.
+
+Run `requestshield contract` before writing integration code — it is authoritative for
+the script URL, header name, released modes, and backend baseline.
+<!-- requestshield:end -->

package/skills/requestshield/references/backend-java-core.md

@@ -0,0 +1,128 @@
+# Backend SDK — Java core SDK
+
+The backend is where protection actually happens. Everything the browser does is
+transport to deliver a token here; this file is where the request is allowed or refused.
+
+This is one of two backend paths. It is framework-neutral: the SDK returns a decision and
+**the application enforces it**. The other path is the declarative Spring Boot 3 starter
+→ `backend-spring-boot.md`; prefer that one when the stack allows it, because it removes
+the enforcement code below and the mistakes that come with it.
+
+**Requires Java 17 or newer** — nothing else. So this is the path for every backend that
+is not Spring Boot 3 MVC, including a Spring Boot 3 app built on WebFlux, which is not
+Spring MVC. Also needed: the same App Key the browser uses, the backend-only API Secret,
+and a web framework that can extract the token carrier.
+
+Confirm the baseline and supported languages with `requestshield contract` first. If the
+customer's backend language is not listed, the honest answer is that the integration is
+not supported yet, because a browser-only install protects nothing.
+
+The browser mode does not decide this path. Either Seamless or Manual mode delivers the
+token, and the application extracts it and passes the value unchanged to `verify()`.
+
+Use exactly **one** verification path per request. A RequestShield token is used once, so
+a handler already covered by `@RequestShieldProtected` must not also call `verify()`.
+
+## 1. Dependency
+
+```xml title="pom.xml"
+<repositories>
+  <repository>
+    <id>intellifend-maven</id>
+    <url>https://sdk.intellifend.com/packages/maven</url>
+  </repository>
+</repositories>
+
+<dependency>
+  <groupId>com.intellifend.requestshield</groupId>
+  <artifactId>requestshield-backend-sdk</artifactId>
+  <version>2.0.0</version>
+</dependency>
+```
+
+## 2. One reusable client
+
+```java
+RequestShieldClient requestShield = RequestShieldClient.builder()
+    .appKey(appKey)
+    .apiSecret(apiSecret)
+    .build();
+```
+
+One client per App Key, reused across requests, rather than one per request. Keep the
+API secret in backend runtime secret storage.
+
+Bind the secret with no fallback default. A backend that starts with a placeholder
+secret rejects every real token, which surfaces days later as "RequestShield is blocking
+all our users" — a startup failure is far cheaper to diagnose than that.
+
+## 3. Verify before the protected operation
+
+```java
+String token = request.getHeader("X-IntelliFend-Token");
+VerificationResult result = requestShield.verify(token);
+
+if (!result.isAllowed()) {
+    rejectRequest(result.getReason().getCode());
+    return;
+}
+
+continueProtectedOperation();
+```
+
+  Pass the extracted value unchanged. Do not trim, decode, or pre-validate the shape;
+  `verify()` owns that, and pre-parsing only adds a way to reject a valid token.If the
+  header is absent, `null`, or empty, pass that value to `verify()` as-is. Do not add a
+  separate decision based on token presence.
+
+  Always enforce `isAllowed()`. Use `getReason().getCode()` for controlled diagnostics or
+  a sanitized response contract only — **do not build a separate decision table in
+  application code.** Reason codes explain a decision; they do not amend it, and an
+  override that allows a blocked reason quietly removes the protection.
+
+  If the application contract carries the token in a request-body field instead of the
+  header, extract that field before verification; everything after that is identical.
+
+## 4. Validate the request path
+
+1. Browser and backend use the same App Key.
+2. A token reaches the backend unchanged.
+3. The protected operation runs only after `isAllowed()` is checked.
+4. A new browser token is obtained before each application retry.
+5. Tokens and the API secret are excluded from logs.
+
+## VerificationResult
+
+| Method | Returns | Use |
+| --- | --- | --- |
+| `isAllowed()` | `boolean` | The decision to enforce. Never override it based on a reason code. |
+| `getReason()` | `VerificationReason` | Stable reason; `getReason().getCode()` is safe to log and chart. |
+| `isDegraded()` | `boolean` | The decision was made under a platform availability failure rather than from a real token. |
+
+`isDegraded()` deserves attention on first integration. Confirm the exact behaviour in
+the customer documentation before relying on it, and tell the user which behaviour you
+assumed. The documented intent is that a degraded result reflects a platform
+availability failure rather than a real token decision — so a degraded result is not
+evidence that a token was valid. Log the degraded count as its own metric; a persistent nonzero rate is an
+infrastructure signal, not a bot signal.
+
+Reason codes and what each means for debugging: `troubleshooting.md`.
+
+## Align the browser side
+
+Configure exactly one browser mode for the same operation — Seamless
+(`browser-seamless.md`) or Manual (`browser-manual.md`). Browser configuration does not
+create backend protection, and a `verify()` call does not create browser configuration.
+Land both halves in the same change. For a cross-origin API, configure CORS to allow the
+token header.
+
+## Security requirements
+
+- The API Secret lives in backend runtime secret storage only — never in source, a
+  committed `.env`, an image layer, a client-visible response, or a log line.
+- The App Key must be identical in browser and backend, or every token fails.
+- One token per protected request, verified exactly once.
+- Never log or persist raw tokens, decoded claims, or the secret. Reason codes exist so
+  diagnostics need none of that.
+- Enforce the decision before the business mutation, not after — verification that runs
+  after the order is written is an audit log, not protection.