requestshield 0.1.4 → 0.1.5

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

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