requestshield 0.1.4 → 0.1.5

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

@@ -1,62 +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 -->
+<!-- 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

@@ -1,128 +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.
+# 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.