requestshield 0.0.0-stage → 1.0.0-stg.276

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

@@ -0,0 +1,107 @@
+<!-- Optional repository guidance template. Agent setup installs the personal skill; it does not write this file. -->
+## 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 `~/.agents/skills/requestshield/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.
+
+Choose Seamless or Manual independently at each layer:
+
+- **Frontend Seamless** uses `data-protect` with supported page-scope `fetch` or async
+  XHR requests; **frontend Manual** uses `getToken()` and application token transport.
+- **Backend Seamless** uses the Spring Boot 3 MVC starter and annotation on Java 17+;
+  **backend Manual** uses explicit Java core SDK verification and enforcement on Java
+  17+, including Spring Boot applications.
+
+Honor explicit valid preferences and preserve supported existing integrations,
+including mixed pairs. For two new, unselected layers, recommend Seamless + Seamless
+when the release, stack, and transport support it; otherwise recommend Manual + Manual
+when supported. Never silently replace an unsupported explicit choice. Follow the
+planning reference for partial integrations and capability limits. Before integration
+edits, present the supported options and recommendation for any unselected layer,
+ask the user to choose, and wait for their answer. Keep already confirmed choices
+and supported existing modes without asking again. Frontend Manual
+with backend Seamless must use the token header; a body carrier needs backend Manual.
+`BLOCK` and `MONITOR` describe enforcement, not these integration styles.
+Check both halves before proposing edits — finding a backend blocker afterwards leaves
+tokens flowing with nothing enforcing them. Java below 17 blocks both backend modes.
+
+For Install, if the request does not
+already name an intentionally narrow endpoint set, scan the application read-only for
+abuse-sensitive browser-to-backend operations. Rank the complete candidate inventory by
+business impact, automation attractiveness, exposure, cost, and trace confidence.
+Present the candidates through the host's native interactive multi-select, each
+showing priority, exact method/path, reason, and current state (a numbered list only
+when the host has no interactive multi-select), then wait. Only the selected operations authorize integration
+edits. Install browser and backend wiring without creating or configuring credentials,
+then run static checks and available focused builds/tests. Do not run runtime or
+negative tests as part of Install. Report runtime activation and enforcement as
+unverified, and recommend that the user configure the canonical App Key and API Secret
+names, restart or redeploy, and test afterwards.
+
+For Uninstall, detect the existing integration, present its exact integration-only
+removal inventory, and wait for confirmation before editing.
+
+For Test / negative testing, use the existing runtime configuration. Require a fresh,
+successful, non-degraded control before the tokenless comparison. If the control fails,
+report the failure and stop before that comparison without starting credential management.
+
+Orientation:
+
+- `~/.agents/skills/requestshield/SKILL.md` — the procedure. Start here.
+- `~/.agents/skills/requestshield/references/integration-planning.md` — the planning flow:
+  ranked endpoint discovery and selection, detecting an existing integration, gating
+  on the backend stack (Java version, Spring MVC vs WebFlux, other frameworks), and
+  choosing the two modes.
+  Read it before any install, verify, or uninstall.
+- `~/.agents/skills/requestshield/references/cli.md` — supported commands and their
+  availability. `service status` checks public HTTP liveness without login;
+  passing checks do not establish application protection. `billing get <app-key>`
+  reads account-wide approximate usage and cost estimates after sign-in;
+  credential-status metadata remains unavailable.
+- `~/.agents/skills/requestshield/references/browser-seamless.md` — frontend Seamless: exact-endpoint
+  matching, and the transports it does not cover.
+- `~/.agents/skills/requestshield/references/browser-manual.md` — frontend Manual, carriers, CORS, CSP.
+- `~/.agents/skills/requestshield/references/backend-spring-boot.md` — backend Seamless:
+  Spring Boot 3 MVC with `@RequestShieldProtected`.
+- `~/.agents/skills/requestshield/references/backend-java-core.md` — backend Manual:
+  explicit `verify()` and enforcement on Java 17+, including Spring Boot.
+- `~/.agents/skills/requestshield/references/troubleshooting.md` — reason codes and diagnosis.
+
+Six rules worth carrying without opening a file:
+
+- **Use native Yes/No choices for every binary interaction.** When the host supports
+  interactive choices, present exactly **Yes** and **No** and do not ask for a typed or
+  free-text answer. Fall back to a plain-text `Yes`/`No` question only when the host has
+  no interactive-choice capability, and always wait for an explicitly submitted
+  choice.
+- The **API Secret** never enters source control, logs, or a reply. It belongs in backend
+  runtime secret storage, and `requestshield secret rotate <app-key>` is the fix if it leaks. The
+  **App Key** is public and must be identical in browser and backend.
+- **Keep secret output out of tool transcripts.** Before create, rotate, or reveal,
+  warn that the API Secret is displayed only once and obtain confirmation with the
+  native **Yes**/**No** interaction rule above. Run the
+  command only in a private user-visible terminal whose output is unavailable to the
+  agent; otherwise tell the user to run it in their own terminal. Never capture or
+  redirect the output, and ask only whether the user stored the secret successfully.
+- 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 frontend Manual, 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.
+
+Use `requestshield contract --json` and its documentation links before changing
+the script URL, matching integrity, header, modes or backend baseline. It is a public
+read with no login. Use the intended environment, merge CSP additions and preserve
+the selected release; report missing metadata instead of inventing values.

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

@@ -0,0 +1,152 @@
+# Backend Manual — 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.
+
+Backend Manual uses the framework-neutral core SDK: application code extracts the
+token, calls `verify()`, and **enforces the returned decision**. It works on Spring Boot
+3 MVC as well as other Java frameworks. Backend Seamless uses the declarative Spring
+Boot 3 starter → `backend-spring-boot.md`. Apply the pairing rules in
+`integration-planning.md`; do not switch an existing backend merely to match names.
+
+**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.
+
+The Install flow wires the canonical environment-variable references without requiring
+credential values. Do not start or deploy the credential-dependent runtime until the
+user has configured `INTELLIFEND_REQUESTSHIELD_APP_KEY` and the backend-only
+`INTELLIFEND_REQUESTSHIELD_API_SECRET`.
+
+Use the backend values already established by
+[Contract check](integration-planning.md#contract-check), then follow the contract's
+Java SDK documentation link. Do not promise an undocumented backend path; a
+browser-only install protects nothing.
+
+Either frontend Seamless or frontend Manual can deliver the token. Application code
+extracts it and passes the value unchanged to `verify()`. Backend Manual does not
+require frontend Manual; an explicit or existing frontend Seamless integration remains
+valid when its transport and release requirements are met.
+
+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
+
+For the dependency version, replace `BACKEND_SDK_VERSION_FROM_CONTRACT` below with the
+exact `data.backend.sdkVersion` value retained from **Contract check**. Do not rerun the
+contract, infer a version, use `latest`, or leave the placeholder in the customer build
+file. If Contract check did not establish that field, stop and report the problem.
+
+```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>BACKEND_SDK_VERSION_FROM_CONTRACT</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.
+
+Java SDK 2.0.0 uses API v2 for verification and availability checks. It has no
+API-version option or fallback to v1.
+Preserve existing Java 1.0.0/v1 integrations. See `integration-planning.md` for
+the supported version combinations and mixed-version availability behavior.
+
+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.
+
+Backend Manual names this explicit integration style. The core SDK has no starter
+`mode` property; documentation should describe the application's observed handling of
+`isAllowed()` rather than inventing a `BLOCK` or `MONITOR` configuration option.
+
+  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 frontend mode for the same operation — frontend Seamless
+(`browser-seamless.md`) or frontend Manual (`browser-manual.md`). Browser configuration does not
+create backend protection, and a `verify()` call does not create browser configuration.
+For a new integration, land both halves in the same change. For a cross-origin API,
+configure CORS for the request's actual headers; allow `X-IntelliFend-Token` when using
+the header carrier. A documented body carrier does not require that unused 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.

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

@@ -0,0 +1,158 @@
+# Backend Seamless — 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.
+
+Backend Seamless uses the Spring Boot 3 starter to extract, verify, and enforce the
+token before an annotated handler runs. Backend Manual uses the framework-neutral
+core SDK → `backend-java-core.md`. Select the pair using `integration-planning.md`;
+availability of the starter does not override an explicit preference or existing mode.
+
+**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.
+
+The Install flow wires the canonical environment-variable references without requiring
+credential values. Do not start or deploy the credential-dependent runtime until the
+user has configured `INTELLIFEND_REQUESTSHIELD_APP_KEY` and the backend-only
+`INTELLIFEND_REQUESTSHIELD_API_SECRET`.
+
+Use `requestshield contract --json` for the selected release's Java baseline,
+Maven coordinates and challenge URL, then follow its Java SDK documentation link.
+Do not promise an undocumented backend path; a browser-only install protects nothing.
+
+Either frontend Seamless or frontend Manual can deliver the token in
+`X-IntelliFend-Token`; the starter reads that header in both cases. Frontend Manual
+with a request-body carrier needs backend Manual extraction instead. Keep an existing
+supported frontend mode; configuring backend Seamless does not migrate the frontend.
+
+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 enforcement mode, `BLOCK` or `MONITOR`. Defaults to `BLOCK`; this setting does not accept `Seamless` or `Manual`. |
+
+Java SDK 2.0.0 uses API v2 for verification and availability checks; there is no
+API-version setting. Existing Java 1.0.0 integrations continue using v1.
+
+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
+
+| Enforcement 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.
+
+Use `BLOCK` by default for the first live deployment and for subsequent deployments.
+Deployment order is not a reason to select `MONITOR`; `BLOCK` is the mode that enforces
+the decision. Choose `MONITOR` only as an explicit, time-bounded rollout when the team
+accepts that the endpoint is not protected during that period. State clearly whenever
+an endpoint is in `MONITOR`, and define the evidence and owner for switching it to
+`BLOCK` because `MONITOR` evaluates requests but allows them to continue.
+
+## 5. Align the browser side
+
+Configure exactly one frontend integration mode for the same operation:
+
+- Frontend Seamless → add the endpoint URL to `data-protect`. See `browser-seamless.md`.
+- Frontend Manual → 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. For a new integration, land both halves in the same change. For a cross-origin
+API, configure CORS to allow the token header.
+
+## Migrating from backend Manual
+
+Migrate only when requested or needed to correct an incompatibility; a mixed pair alone
+does not require migration. For an endpoint 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.

package/skills/requestshield/references/browser-manual.md

@@ -0,0 +1,244 @@
+# Frontend Manual — Browser SDK
+
+Frontend Manual gives the application control over **when** a token is obtained and
+**how** it is carried to the backend. It supports explicit token timing and supported
+application-controlled carriers. Use the selection rules in `integration-planning.md`
+for preferences, existing integrations, and the default pairing recommendation.
+
+Prerequisites: a public App Key, a backend integration that extracts the chosen carrier,
+and a protected operation that is **not** also configured for frontend Seamless. One
+operation uses one frontend mode. Frontend Manual pairs with backend Seamless through
+`X-IntelliFend-Token`, or with backend Manual through the documented carrier the
+application extracts. A request-body carrier requires backend Manual.
+
+The Install flow may wire this integration before credentials are created. Use the
+application's public configuration mechanism for the App Key when possible. Otherwise
+leave the explicit `YOUR_APP_KEY` placeholder and report its exact location. Do not run
+runtime checks until the user has supplied the real App Key; they belong to the
+explicit Test flow, never Verify.
+After static installation, recommend supplying the real App Key at the reported
+binding or placeholder, configuring the backend variables in its reference, restarting
+or redeploying, and testing the selected endpoint. Perform these steps only when
+separately requested.
+
+## 1. Load the hosted SDK
+
+Place the hosted SDK once in `<head>` before any application bundle that can issue a
+protected request. Use the selected contract URL (`data.browser.scriptUrlVersion` or
+`data.browser.scriptUrlLatest`) and only its matching integrity when provided.
+Bind `data-app-key` or `init()`'s `appKey` through public application configuration when
+it can be wired without a value; otherwise keep `YOUR_APP_KEY` and report its location.
+
+`defer` preserves ordering relative to other `defer` and module scripts. If a protected
+request can come from a classic script without `defer` or an `async` bundle, add `defer`
+to that bundle or remove it from the SDK tag.
+
+Omit `data-protect` when the page uses frontend Manual only — its presence is what turns
+on frontend Seamless interception:
+
+```html
+<script
+  src="SDK_SCRIPT_URL_FROM_RELEASE_DOCS"
+  data-app-key="YOUR_APP_KEY"
+  defer
+></script>
+```
+
+| Attribute | Required | Notes |
+| --- | --- | --- |
+| `src` | Yes | Use the selected `data.browser.scriptUrlVersion` or `data.browser.scriptUrlLatest` from `requestshield contract --json`; use `data.browser.integrity` only when the selected URL is the immutable versioned script. Follow the manifest's Browser SDK documentation link for the selected release. |
+| `data-app-key` | Yes | Public App Key. Must match the backend's configured key. |
+| `defer` | Recommended | Keeps HTML parsing unblocked. |
+
+The SDK reads configuration from `document.currentScript`, so use **exactly one tag**.
+A second tag re-initializes rather than merging, and the last one to run wins.
+
+In templated or bundled apps, put the tag in the HTML entry point (`index.html`,
+`_document.tsx`, the base Django/Rails/Thymeleaf layout) rather than injecting it from
+component code, so it is present before any protected request can fire.
+
+Applications with a custom script loader may configure the same setup in JavaScript
+instead:
+
+```javascript
+IntelliFend.init({appKey: 'YOUR_APP_KEY'});
+```
+
+Use script attributes *or* explicit initialization for initial setup, not both.
+
+Browser SDK 2.0.0 accepts `apiVersion: 'v1' | 'v2'` or
+`data-api-version="v1" | "v2"` and defaults to v2. Existing Browser 1.0.0
+integrations use v1 without this option. Preserve existing pins and API choices.
+API selection is independent of Seamless/Manual mode and does not change the
+2.0.0 WebAssembly or CSP requirements. See `integration-planning.md` for
+mixed-version limits.
+
+## 2. Obtain a token immediately before the request
+
+For the recommended header carrier, call `getToken()` right before the protected
+operation, and attach the header **only when the returned string is non-empty**:
+
+```javascript
+async function createAccount(payload) {
+  const token = await IntelliFend.getToken();
+  const headers = {'Content-Type': 'application/json'};
+
+  if (token) {
+    headers['X-IntelliFend-Token'] = token;
+  }
+
+  return fetch('/api/register', {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(payload),
+  });
+}
+```
+
+`getToken()` resolves to a string. A non-empty value is that request's token; an empty
+value means the header is omitted and **the backend applies its configured policy**.
+
+That last part is why the empty case needs no client-side handling. The decision about
+what an absent token means already lives at the backend, so wrapping this in a retry
+loop, blocking the submit, showing an error, or substituting a placeholder all move
+policy into the browser — the one place it must not be. Attach it when present, omit it
+when not, and let the backend decide.
+
+### Optional action
+
+```javascript
+const token = await IntelliFend.getToken({action: 'create-account'});
+```
+
+Case-sensitive. Use an action **only** when IntelliFend has supplied a corresponding
+backend integration rule — a browser-supplied value is not backend configuration, and
+inventing one has no effect on the decision.
+
+## 3. Backend extracts the carrier
+
+Backend Seamless (Spring Boot starter) reads `X-IntelliFend-Token` from the request
+itself, so no extraction code is needed. With backend Manual (Java core SDK),
+application code extracts the header and passes the value unchanged to `verify()`.
+
+A dedicated request-body field is available when the application contract requires it;
+backend Manual must then extract that field before verification. Prefer the header
+unless there is a real constraint — it keeps the browser and backend halves symmetric
+and works with the starter as-is.
+
+See `backend-spring-boot.md` or `backend-java-core.md` for the extraction side.
+
+## Framework call-site patterns
+
+The recurring failure is attaching the token in one place while some requests reach the
+endpoint through another. Enumerate every path to the endpoint before editing. Cover
+each call site and retry when frontend Manual is selected; the number of call sites
+does not override the user's choice or authorize migrating an existing integration.
+
+**Axios interceptor** — covers calls made through one Axios instance. Resolve both the
+allow-list and each request to an origin-plus-pathname key. Pathname-only matching can
+attach a token to the wrong origin, and resolving `config.url` against `location.origin`
+ignores the instance's `baseURL`:
+
+```javascript
+const protectedEndpointKeys = new Set(
+  PROTECTED_ENDPOINTS.map((endpoint) => {
+    const url = new URL(endpoint, location.origin);
+    return `${url.origin}${url.pathname}`;
+  }),
+);
+
+api.interceptors.request.use(async (config) => {
+  let requestUrl;
+
+  try {
+    requestUrl = new URL(api.getUri(config), document.baseURI);
+  } catch {
+    // An unresolved destination must never receive a RequestShield token.
+    return config;
+  }
+
+  const requestKey = `${requestUrl.origin}${requestUrl.pathname}`;
+  if (protectedEndpointKeys.has(requestKey)) {
+    // Remove a token retained by a reused Axios request config.
+    for (const headerName of Object.keys(config.headers)) {
+      if (headerName.toLowerCase() === 'x-intellifend-token') {
+        delete config.headers[headerName];
+      }
+    }
+    const token = await IntelliFend.getToken();
+    if (token) {
+      config.headers['X-IntelliFend-Token'] = token;
+    }
+  }
+  return config;
+});
+```
+
+`api.getUri(config)` applies that Axios instance's request configuration, including
+`baseURL`; resolving its result against `location.origin` also handles a root-relative
+base URL. Query strings and fragments are deliberately absent from the comparison, but
+the origin is mandatory.
+
+Before shipping the interceptor, verify both directions against the actual instance:
+
+- With `axios.create({baseURL: '/api'})`, a call to `post('/register')` resolves to the
+  current origin plus `/api/register` and matches that protected endpoint.
+- A call to `https://other.example/api/register` does not match the current origin's
+  `/api/register`, does not call `getToken()`, and receives no RequestShield header.
+
+**React / TanStack Query** — obtain the token inside the mutation function, never in a
+`useEffect` or component state. A token held in state goes stale, gets reused across
+retries, and comes back `token_replayed`.
+
+**Retries** — any retry wrapper must call `getToken()` again on each attempt. Reusing
+the first token is the most common cause of a retry being blocked while the original
+attempt succeeded.
+
+**Server-rendered forms** — a native form POST cannot carry a header. Either move the
+submission to `fetch`, or agree a request-body carrier with IntelliFend. Never put the
+token in a hidden field improvised on your own, and never in a query parameter.
+
+## Cross-origin application APIs
+
+When the protected endpoint is on another origin, configure CORS for the page origin,
+intended HTTP methods, and headers actually sent. If the token uses
+`X-IntelliFend-Token`, include that header in `Access-Control-Allow-Headers`; otherwise
+the browser can block the cross-origin request. A documented body carrier does not
+require allowing the unused token header, but other request headers may still require
+preflight permission.
+
+## Content Security Policy
+
+If the app sends a CSP, merge these sources into the existing directives — never replace
+the policy, and keep every source the app already declares:
+
+```http
+Content-Security-Policy:
+  script-src 'self' SCRIPT_SRC_FROM_CONTRACT;
+  connect-src 'self' CONNECT_SRC_FROM_CONTRACT;
+  worker-src 'self' WORKER_SRC_FROM_CONTRACT;
+```
+
+Take each value from `data.browser.cspAdditions` in `requestshield contract --json`:
+`scriptSrc` → `script-src`, `connectSrc` → `connect-src`, `workerSrc` → `worker-src`.
+Add every entry, including keywords such as `'wasm-unsafe-eval'`. `'self'` stands for
+the sources the app already declares; keep them. Take every host **and directive** from
+the contract — this skill is not the authority on either. If `getToken()` returns an empty string on a page that sends a CSP, a blocked
+directive is the first thing to check: the browser console names what it refused, which
+beats guessing at the policy.
+
+Applications that do not send a CSP need no header changes.
+
+## Token handling rules
+
+- One token for one protected request.
+- A new token before retrying a protected operation.
+- Forward a non-empty token unchanged; when using the header carrier, omit the header
+  if the token is empty.
+- Never cache, persist, transform, or log a token.
+- Never place a token in a URL path, query string, or fragment.
+- Never verify the same request with both `@RequestShieldProtected` and a direct
+  `RequestShieldClient.verify()`.
+- Exclude `X-IntelliFend-Token` from logs, analytics, and error reporting — check the
+  error-reporting SDK's header allowlist, which often captures request headers by
+  default.