@intellifend/requestshieldjs 2.0.0-qat.202 → 2.0.0-qat.211

package/README.md

@@ -2,6 +2,24 @@
 
 The RequestShield Browser SDK obtains single-use proof-of-work tokens and either attaches them automatically to configured Fetch and asynchronous XHR requests or returns them for application-controlled transport. The customer backend remains the authority that verifies a token and decides how to handle a missing token.
 
+## Choose integration modes
+
+Choose the frontend and backend modes independently:
+
+| Side | Seamless | Manual |
+| --- | --- | --- |
+| Frontend (Browser SDK) | Configure `protect`; the SDK obtains and attaches a token to matching Fetch and asynchronous XHR requests. | Call `getToken()` and attach the returned token in application code. |
+| Java backend | Use the Spring Boot 3 MVC starter and annotate the protected handler; the starter extracts the header, verifies the token and applies its enforcement policy. | Extract the token, call the Java core SDK's `verify(token)` and apply `VerificationResult` before the protected operation. |
+
+For a new integration, prefer Seamless on both sides when the browser transport
+is supported and the backend uses Spring Boot 3 MVC. Otherwise, prefer Manual
+on both sides. All four combinations are supported, so an existing combination
+or an explicit choice can be kept. Backend Seamless requires the token in
+`X-IntelliFend-Token`, including when the frontend uses Manual mode.
+
+`BLOCK` and `MONITOR` are Spring starter enforcement policies, separate from these
+integration modes. Choosing frontend Seamless does not enable backend protection.
+
 ## Install
 
 ### npm / ESM
@@ -63,9 +81,8 @@ The module is embedded in the SDK bundle; it adds no separate module URL or
 download. Pages enforcing CSP must allow `'wasm-unsafe-eval'` in `script-src`.
 Existing script, service, and Web Worker permissions remain necessary.
 
-`init()` remains synchronous. Token acquisition waits for module readiness
-within the existing whole-flow deadline. If WebAssembly is unavailable, blocked,
-or fails, `getToken()` resolves to `""`. Seamless mode sends the application
+`init()` is synchronous. If WebAssembly is unavailable, blocked, or fails,
+`getToken()` resolves to `""`. Seamless mode sends the application
 request without adding a token, and the backend applies its missing-token
 policy. Test this path together with your CSP and browser requirements.
 
@@ -142,19 +159,16 @@ IntelliFend.init({
 
 URLs are normalized for surrounding whitespace and trailing slashes while retaining path prefixes. No secondary hostname is inferred automatically. A missing or identical fallback preserves the existing single-endpoint behavior.
 
-With a distinct fallback, each create or verify operation still gets at most two attempts. Its first network attempt, including the response-body read, has at most `min(1000 ms, remaining flow budget / 2)`. An eligible failure tries the other endpoint after bounded retry jitter if enough time remains. The second attempt uses the remaining budget. The configured whole-flow deadline includes create, solve, verify, and retries; it defaults to 5,000 ms and never resets on a switch.
-
-Eligible failures are network rejection, individual attempt timeout, HTTP 5xx, interrupted successful response-body reads, and non-binary HTTP 2xx proxy responses. Received 4xx, fully read malformed binary, invalid challenge scope/shape, solver failure, cancellation, and whole-flow expiry stop acquisition. Verify starts on the endpoint that supplied the validated challenge; a verify retry reuses that challenge and solution without repeating PoW.
-
-Successful token acquisition through secondary establishes a fixed 60-second preference in page memory. Further secondary successes, including overlapping fallback flows, do not extend an active window. After expiry the next flow tries primary; recovery clears the preference. Reinitialization resets it. Among overlapping successful flows, the later-started flow determines preference; a late completion from an older flow cannot replace it. No cookies, browser storage, or health-polling requests are used. Both endpoints bypass Seamless interception and preserve omitted credentials and header-free challenge requests. `getToken()` still returns a token or `""`.
+The SDK can retry eligible connection failures through the alternate service.
+All attempts share the configured token timeout, which defaults to 5,000 ms.
+Switching services does not restart that timeout. No cookies or browser storage
+are used. `getToken()` returns a token or `""` if acquisition fails.
 
 ### Optional browser signal collection
 
 `telemetry: true` collects a bounded summary of browser
 interaction and timezone information in page memory for up to five minutes.
-Each token flow samples the current numeric timezone offset and sends one
-snapshot with the challenge request. The optional timezone name is resolved
-during idle work and may reflect an earlier timezone setting.
+This summary accompanies token requests and includes timezone information.
 
 The collector does not retain raw events, typed text, key values, DOM references,
 or mouse paths. It uses no cookies, browser storage, or persistent identity and
@@ -194,13 +208,9 @@ serialization, file names, MIME types, and document charset handling. GET/HEAD
 bodies remain ignored. If capture fails, the original native `send()` runs
 immediately with the original body and retains its native validation errors.
 
-Challenge hostname validation uses the server's canonical DNS spelling,
-including removal of one terminal root dot. This does not change exact-origin
-Seamless endpoint matching.
-
 ### Token lifetime and single use
 
-Tokens are short-lived and single-use. Use one token for one protected application request, obtain a fresh token for a retry, and never reuse a token after native Fetch or XHR dispatch may have sent it. Seamless mode manages one warm token and never gives the same token to two requests.
+Tokens are short-lived and single-use. Use one token for one protected application request, obtain a fresh token for a retry, and never reuse a token after native Fetch or XHR dispatch may have sent it. Seamless mode never gives the same token to two requests.
 
 ### CORS
 
@@ -208,7 +218,11 @@ For a cross-origin protected application API, allow the `X-IntelliFend-Token` re
 
 ### Manual transport
 
-`X-IntelliFend-Token` is the recommended Manual-mode carrier. A dedicated request-body or form field is also valid when the backend extracts it before verification. Never place a token in a URL path, query string, or fragment because those locations are commonly logged and cached.
+`X-IntelliFend-Token` is the recommended carrier for frontend Manual mode and is
+required by backend Seamless. A dedicated request-body or form field is also
+valid with backend Manual, where application code extracts it before verification.
+Never place a token in a URL path, query string, or fragment because those
+locations are commonly logged and cached.
 
 ### Challenge Server proxies
 
@@ -237,9 +251,9 @@ The SDK targets Chrome/Edge 97+, Firefox 102+, and Safari/iOS 16+ with
 WebAssembly and the required CSP permission. Test your integration on the
 browsers and devices your application supports. Proof-of-work runs off the
 main thread in a Web Worker.
-Completion time depends on the device and service-selected challenge. Module
-readiness shares the default five-second token budget; expiry returns `""`,
-and the backend remains responsible for its missing-token policy.
+Completion time depends on the device and service-selected challenge. Token
+acquisition has a configurable timeout of five seconds by default. On timeout,
+`getToken()` returns `""`, and the backend applies its missing-token policy.
 
 ## License
 

package/dist/checksums.json

@@ -1,18 +1,18 @@
 {
-  "version": "2.0.0-qat.202",
+  "version": "2.0.0-qat.211",
   "algorithm": "sha384",
   "bundles": [
     {
       "name": "intellifend",
       "path": "intellifend.js",
-      "version": "2.0.0-qat.202",
-      "integrity": "sha384-07fZD+6GSgdB2lZNewxUvyN2kD0P1rK8Abih3JUDDA+OQ8S3qH2OypOyE24PvY/5"
+      "version": "2.0.0-qat.211",
+      "integrity": "sha384-uSFJiosGxa7BN8DIl3XvpILMhGXyWGuf1bSdW3zszbJc2dnURhUbhPWxMOGxTeHi"
     },
     {
       "name": "intellifend-esm",
       "path": "intellifend.mjs",
-      "version": "2.0.0-qat.202",
-      "integrity": "sha384-4NdnZYE3ax6ELSqwpjmrbLTsmcNGMRVhHusKNV+8pympCdd+pIOpPOB6+7/GVKjD"
+      "version": "2.0.0-qat.211",
+      "integrity": "sha384-dFwy9vbHXbjtmymion5tAnmawA+1kqXUMDLUsDqQjktg2fTpfS+Vj7WN7RLQ8QXA"
     }
   ]
 }