requestshield 0.1.4 → 0.1.5

package/skills/requestshield/references/backend-spring-boot.md

@@ -1,145 +1,145 @@
-# Backend SDK — Spring Boot 3 starter
-
-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 the declarative one, and it removes the most
-common hand-rolled mistakes, so prefer it whenever the stack allows. The other is the
-framework-neutral core SDK → `backend-java-core.md`.
-
-**Requires Spring Boot 3 with Spring MVC, and Java 17 or newer.** A Spring Boot 3 app
-built on WebFlux is not Spring MVC and cannot use this path. Confirm the stack before
-writing anything — the detection recipes are in `integration-planning.md`, under **Gate
--> Run the check**. Also needed: the same
-App Key the browser uses, and the backend-only API Secret.
-
-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 in `X-IntelliFend-Token`, and the starter reads that header without caring how it
-got there.
-
-Use exactly **one** verification path per request. A RequestShield token is used once, so
-a handler covered by the annotation must not also call `verify()`.
-
-## 1. Repository and 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-spring-boot3-starter</artifactId>
-  <version>2.0.0</version>
-</dependency>
-```
-
-```kotlin title="build.gradle.kts"
-repositories {
-    maven { url = uri("https://sdk.intellifend.com/packages/maven") }
-}
-
-dependencies {
-    implementation("com.intellifend.requestshield:requestshield-spring-boot3-starter:2.0.0")
-}
-```
-
-The starter includes `requestshield-backend-sdk:2.0.0` — do not declare both.
-
-## 2. Configure
-
-```yaml title="application.yml"
-intellifend:
-  requestshield:
-    app-key: ${INTELLIFEND_REQUESTSHIELD_APP_KEY}
-    api-secret: ${INTELLIFEND_REQUESTSHIELD_API_SECRET}
-    challenge-server-url: https://challenge.intellifend.ai
-    mode: BLOCK
-```
-
-| Property | Required | Notes |
-| --- | --- | --- |
-| `app-key` | Yes | Must be the same value as the browser's `data-app-key`. |
-| `api-secret` | Yes | Backend runtime secret storage. Pass the supplied value unchanged. |
-| `challenge-server-url` | No | Defaults to the RequestShield service. |
-| `mode` | No | Global mode, `BLOCK` or `MONITOR`. Defaults to `BLOCK`. |
-
-Bind the secret with no fallback default, so an environment that fails to inject it
-fails at startup. 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. Annotate the protected method
-
-```java
-import com.intellifend.requestshield.spring.boot.ProtectionMode;
-import com.intellifend.requestshield.spring.boot.RequestShieldProtected;
-
-@PostMapping("/api/register")
-@RequestShieldProtected(mode = ProtectionMode.DEFAULT)
-public RegisterResponse register(@RequestBody RegisterRequest request) {
-    return accountService.create(request);
-}
-```
-
-The annotation applies to methods. Put it on the handler that performs the protected
-mutation — not on a wrapper or a read-only route in front of it, where the mutation
-could still be reached another way.
-
-The annotation declares no path, action, domain, or browser URL list. It creates no
-browser configuration.
-
-## 4. Enforcement mode
-
-| Mode | Behaviour |
-| --- | --- |
-| `BLOCK` | Enforce the decision before the method runs. |
-| `MONITOR` | Evaluate the request while allowing the method to continue. |
-| `DEFAULT` | Inherit the global mode. |
-
-The global property accepts `BLOCK` or `MONITOR` and defaults to `BLOCK`. A method-level
-`BLOCK` or `MONITOR` overrides the global setting.
-
-`MONITOR` is the right first deploy on live traffic: it produces real decisions and
-volume data with no risk of turning away genuine users, so you can confirm tokens are
-arriving before switching to `BLOCK`. State clearly whenever an endpoint is in
-`MONITOR` — it is protection-shaped and is not protection, and it is easy to forget.
-
-## 5. Align the browser side
-
-Configure exactly one browser mode for the same operation:
-
-- Seamless mode → add the endpoint URL to `data-protect`. See `browser-seamless.md`.
-- Manual mode → send the obtained token in `X-IntelliFend-Token`. See
-  `browser-manual.md`.
-
-Browser configuration does not create backend protection, and the annotation does not
-create browser configuration. Land both halves in the same change. For a cross-origin
-API, configure CORS to allow the token header.
-
-## Migrating from manual verification
-
-For an endpoint already calling `RequestShieldClient.verify()`, remove that call and add
-the annotation **in the same backend release**. Running both consumes the same
-single-use token twice, so every request fails — and it fails only once both are
-deployed, which makes it look like the annotation broke the endpoint.
-
-Reason codes and what each means for debugging: `troubleshooting.md`.
-
-## 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 — Spring Boot 3 starter
+
+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 the declarative one, and it removes the most
+common hand-rolled mistakes, so prefer it whenever the stack allows. The other is the
+framework-neutral core SDK → `backend-java-core.md`.
+
+**Requires Spring Boot 3 with Spring MVC, and Java 17 or newer.** A Spring Boot 3 app
+built on WebFlux is not Spring MVC and cannot use this path. Confirm the stack before
+writing anything — the detection recipes are in `integration-planning.md`, under **Gate
+-> Run the check**. Also needed: the same
+App Key the browser uses, and the backend-only API Secret.
+
+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 in `X-IntelliFend-Token`, and the starter reads that header without caring how it
+got there.
+
+Use exactly **one** verification path per request. A RequestShield token is used once, so
+a handler covered by the annotation must not also call `verify()`.
+
+## 1. Repository and 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-spring-boot3-starter</artifactId>
+  <version>2.0.0</version>
+</dependency>
+```
+
+```kotlin title="build.gradle.kts"
+repositories {
+    maven { url = uri("https://sdk.intellifend.com/packages/maven") }
+}
+
+dependencies {
+    implementation("com.intellifend.requestshield:requestshield-spring-boot3-starter:2.0.0")
+}
+```
+
+The starter includes `requestshield-backend-sdk:2.0.0` — do not declare both.
+
+## 2. Configure
+
+```yaml title="application.yml"
+intellifend:
+  requestshield:
+    app-key: ${INTELLIFEND_REQUESTSHIELD_APP_KEY}
+    api-secret: ${INTELLIFEND_REQUESTSHIELD_API_SECRET}
+    challenge-server-url: https://challenge.intellifend.ai
+    mode: BLOCK
+```
+
+| Property | Required | Notes |
+| --- | --- | --- |
+| `app-key` | Yes | Must be the same value as the browser's `data-app-key`. |
+| `api-secret` | Yes | Backend runtime secret storage. Pass the supplied value unchanged. |
+| `challenge-server-url` | No | Defaults to the RequestShield service. |
+| `mode` | No | Global mode, `BLOCK` or `MONITOR`. Defaults to `BLOCK`. |
+
+Bind the secret with no fallback default, so an environment that fails to inject it
+fails at startup. 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. Annotate the protected method
+
+```java
+import com.intellifend.requestshield.spring.boot.ProtectionMode;
+import com.intellifend.requestshield.spring.boot.RequestShieldProtected;
+
+@PostMapping("/api/register")
+@RequestShieldProtected(mode = ProtectionMode.DEFAULT)
+public RegisterResponse register(@RequestBody RegisterRequest request) {
+    return accountService.create(request);
+}
+```
+
+The annotation applies to methods. Put it on the handler that performs the protected
+mutation — not on a wrapper or a read-only route in front of it, where the mutation
+could still be reached another way.
+
+The annotation declares no path, action, domain, or browser URL list. It creates no
+browser configuration.
+
+## 4. Enforcement mode
+
+| Mode | Behaviour |
+| --- | --- |
+| `BLOCK` | Enforce the decision before the method runs. |
+| `MONITOR` | Evaluate the request while allowing the method to continue. |
+| `DEFAULT` | Inherit the global mode. |
+
+The global property accepts `BLOCK` or `MONITOR` and defaults to `BLOCK`. A method-level
+`BLOCK` or `MONITOR` overrides the global setting.
+
+`MONITOR` is the right first deploy on live traffic: it produces real decisions and
+volume data with no risk of turning away genuine users, so you can confirm tokens are
+arriving before switching to `BLOCK`. State clearly whenever an endpoint is in
+`MONITOR` — it is protection-shaped and is not protection, and it is easy to forget.
+
+## 5. Align the browser side
+
+Configure exactly one browser mode for the same operation:
+
+- Seamless mode → add the endpoint URL to `data-protect`. See `browser-seamless.md`.
+- Manual mode → send the obtained token in `X-IntelliFend-Token`. See
+  `browser-manual.md`.
+
+Browser configuration does not create backend protection, and the annotation does not
+create browser configuration. Land both halves in the same change. For a cross-origin
+API, configure CORS to allow the token header.
+
+## Migrating from manual verification
+
+For an endpoint already calling `RequestShieldClient.verify()`, remove that call and add
+the annotation **in the same backend release**. Running both consumes the same
+single-use token twice, so every request fails — and it fails only once both are
+deployed, which makes it look like the annotation broke the endpoint.
+
+Reason codes and what each means for debugging: `troubleshooting.md`.
+
+## 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.