requestshield 0.1.4 → 0.1.5

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

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