requestshield 0.1.0 → 0.1.3

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

@@ -0,0 +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.

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

@@ -0,0 +1,210 @@
+# Browser SDK — Manual mode
+
+Manual mode gives the application control over **when** a token is obtained and **how**
+it is carried to the backend. Choose it when the request escapes Seamless interception,
+or when the application must carry the token in an application-controlled header or
+request-body field.
+
+Prerequisites: a public App Key, a backend integration that extracts the chosen carrier,
+and a protected operation that is **not** also configured for Seamless mode. One
+operation uses one mode.
+
+## 1. Load the hosted SDK
+
+Omit `data-protect` when the page uses Manual mode only — its presence is what turns on
+Seamless interception:
+
+```html
+<script
+  src="SCRIPT_URL_FROM_CONTRACT"
+  data-app-key="YOUR_APP_KEY"
+  defer
+></script>
+```
+
+| Attribute | Required | Notes |
+| --- | --- | --- |
+| `src` | Yes | Take it from `requestshield contract` → `browser.script_url`. Currently `https://static.intellifend.ai/intellifend.js`; read the contract rather than trusting this line. |
+| `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.
+
+## 2. Obtain a token immediately before the request
+
+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
+
+The Spring Boot starter reads `X-IntelliFend-Token` from the request itself, so no
+extraction code is needed. With the 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;
+application code 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 — and if
+there are several, that is a strong signal Seamless mode is the better fit.
+
+**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, its CORS response must allow the page
+origin, the intended HTTP methods, and the `X-IntelliFend-Token` header. Without the
+header in `Access-Control-Allow-Headers`, the browser strips it and the backend sees
+every request as missing a token — which reads as a browser-integration bug but is a
+CORS configuration bug.
+
+## 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' https://static.intellifend.ai;
+  connect-src 'self' https://challenge.intellifend.ai;
+  worker-src 'self' blob:;
+```
+
+Confirm the hosts **and the directive list** against `requestshield contract` and the
+customer deployment guide before editing a live policy — 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; omit the header when it 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 manual
+  `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.

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

@@ -0,0 +1,164 @@
+# Browser SDK — Seamless mode
+
+Seamless mode is the recommended browser integration for applications that use `fetch`
+or asynchronous `XMLHttpRequest`. Browser SDK 1.1 matches configured application
+endpoints and adds `X-IntelliFend-Token` automatically, so no call site changes.
+
+Prerequisites: a public App Key, the **exact** application API endpoints to protect, and
+backend protection configured for the corresponding operations.
+
+## 1. Load the hosted SDK
+
+Place the script before any application bundle that can issue a protected request —
+otherwise an early request leaves the page before interception is installed:
+
+```html
+<script
+  src="SCRIPT_URL_FROM_CONTRACT"
+  data-app-key="YOUR_APP_KEY"
+  data-protect='["/api/register"]'
+  defer
+></script>
+```
+
+`data-protect` is a **JSON array** — note the single quotes around the attribute so the
+inner double quotes survive. Each entry is either a root-relative pathname beginning
+with `/`, or an absolute URL without embedded credentials. Malformed JSON is a configuration
+error — validate the attribute before shipping rather than assuming a parse failure will
+announce itself.
+
+Applications with a custom script loader can configure the same behaviour after the
+hosted script loads:
+
+```javascript
+IntelliFend.init({
+  appKey: 'YOUR_APP_KEY',
+  protect: ['/api/register'],
+});
+```
+
+Use script attributes *or* explicit initialization for initial setup, not both.
+
+## 2. Match application endpoints exactly
+
+RequestShield compares the **exact origin and exact pathname**. This is where a Seamless
+install either works or quietly does nothing, so resolve it before writing the attribute:
+
+- Query strings and fragments are ignored on both sides.
+- **Pathname case and trailing slash are significant.**
+- Root-relative entries resolve against the page origin.
+- Cross-origin entries use HTTPS, except for loopback development.
+- The same endpoint rule applies to every HTTP method.
+
+So `/api/register` matches `/api/register?source=campaign`, but it does **not** match
+`/api/Register` or `/api/register/`.
+
+The practical consequence: **list the URL the application passes to `fetch` or
+asynchronous `XMLHttpRequest`.** With a normal development proxy, the application
+requests `/api/register` on the frontend origin. The proxy then rewrites and forwards
+that request to an upstream route such as `https://api.example.com/register`. The
+rewrite happens outside the browser and does not change the URL matched by Seamless.
+Configure `/api/register`, and ensure the proxy forwards `X-IntelliFend-Token`
+unchanged.
+
+If the application directly requests `https://api.example.com/register`, configure
+that absolute URL instead and configure CORS to allow the page origin, request method,
+and `X-IntelliFend-Token`.
+
+A redirect is different from a proxy rewrite. With an HTTP redirect, the server returns
+a `3xx` response and the browser follows its `Location`. Seamless matches the original
+URL passed by application code; it does not separately match the browser's internal
+redirect request. Do not configure only the redirect destination when the application
+initially requests `/api/register`. Avoid redirects for protected mutation endpoints
+when possible, or verify the method, header, and CORS behavior end to end.
+
+A path built with an ID or slug (`/api/orders/42`) has no wildcard support — list every
+concrete path, or use Manual mode for that operation.
+
+## 3. Send requests normally
+
+Application code does not call `getToken()` or construct the header for a
+Seamless-mode endpoint:
+
+```javascript
+const response = await fetch('/api/register', {
+  method: 'POST',
+  headers: {'Content-Type': 'application/json'},
+  body: JSON.stringify({email, password}),
+});
+```
+
+Browser configuration controls token attachment only. Configure the corresponding
+backend operation independently — `data-protect` creates no backend protection.
+
+## What Seamless covers
+
+Supported: `fetch` (string, `URL`, and `Request` inputs) and asynchronous
+`XMLHttpRequest`.
+
+Do not rely on Seamless and a Manual call site coexisting on the same endpoint. One
+protected operation uses one mode — see the prerequisites in `browser-manual.md`.
+
+## What Seamless does not cover
+
+Any of these means the request leaves without a token, with no error — which is why
+they are worth checking *before* choosing the mode:
+
+- Synchronous XHR.
+- Native form navigation (a plain `<form>` submit).
+- `navigator.sendBeacon`.
+- WebSocket and EventSource.
+- Service-worker-owned requests. Web workers and server-side rendering have their own
+  global scope too — in Next.js, Nuxt, Remix and similar, confirm the protected call
+  runs in the browser.
+- A `fetch` using `no-cors`, which cannot carry a custom header at all.
+
+For an operation on this list, use Manual mode **only if** the application can carry the
+token in a supported header or request-body field. Otherwise the right answer is an
+application-specific integration agreed with IntelliFend — say that plainly rather than
+improvising a carrier.
+
+## Cross-origin APIs
+
+When the protected endpoint is on another origin, its CORS response must allow the page
+origin, the intended methods, and the `X-IntelliFend-Token` header. Missing that header
+in `Access-Control-Allow-Headers` means the browser strips it and every request reads as
+missing a token.
+
+## Verifying Seamless
+
+Static checks:
+
+1. Exactly one script tag, loaded before application bundles, with valid JSON in
+   `data-protect`.
+2. Every listed entry matches a URL the browser actually requests — origin, case, and
+   trailing slash included.
+3. Every protected endpoint reaches the network via `fetch` or async XHR from page
+   scope.
+
+Runtime check: exercise the endpoint, confirm the network request carries a non-empty
+`X-IntelliFend-Token`, then confirm the platform saw it. This proves the browser half is
+firing; the negative test in `SKILL.md` proves backend enforcement.
+
+```bash
+requestshield challenge volume <app-key> \
+  --from <start> \
+  --to <end> \
+  --granularity hour
+```
+
+Zero volume with a correct-looking `data-protect` is nearly always a path mismatch
+(trailing slash, case, a different origin than assumed) or one of the uncovered
+transports above. Re-read the actual request URL before changing anything else.
+
+## Expected result
+
+Matching requests carry one non-empty `X-IntelliFend-Token` header; requests outside the
+configured list are unchanged.
+
+## CSP and token handling
+
+Identical to Manual mode — see the CSP and token-handling sections of
+`browser-manual.md`. The `worker-src 'self' blob:` directive matters just as much here:
+without it, every intercepted request attaches an empty token and the backend blocks
+traffic that looks correctly integrated.