@intellifend/requestshieldjs 2.0.0-qat.197

package/LICENSE.txt

@@ -0,0 +1,116 @@
+REQUESTSHIELD JAVASCRIPT SDK LICENSE
+Version 1.0 - 2026-09-22
+
+Copyright (c) 2026 Request Shield. All rights reserved.
+
+1. Scope and ownership
+
+This license applies to the proprietary portions of the RequestShield Browser
+SDK, intended for distribution as @intellifend/requestshieldjs, including its
+JavaScript bundles, embedded WebAssembly, type declarations, and accompanying
+documentation (the "Software"). Request Shield, the legal entity
+providing IntelliFend RequestShield, is the "Licensor". "You" means the person
+or organization exercising the permissions below.
+
+Licensor and its licensors retain ownership of the Software. Public access to
+the Software through npm or a CDN does not make the proprietary portions open
+source. Third-party components are governed by section 5.
+
+2. Permitted use and delivery
+
+Subject to this license, Licensor grants You a worldwide, non-exclusive,
+royalty-free license to:
+
+(a) download, install, copy, and execute the Software to develop, test, and
+operate websites and applications that integrate, or are being developed to
+integrate, with IntelliFend RequestShield services You are authorized to use;
+
+(b) configure the Software through its documented interfaces, and bundle,
+minify, transpile, compress, or otherwise transform it as reasonably necessary
+for that integration, without changing its protection or verification logic;
+
+(c) host and deliver those copies with Your applications, including through
+Your servers, hosting providers, package caches, and CDNs, and permit Your
+application users and visitors to download, cache, and execute them as part
+of using those applications; and
+
+(d) allow Your contractors and service providers to perform these activities
+on Your behalf, subject to the same limits.
+
+Package registries, package managers, mirrors, and CDNs may copy, cache, and
+serve unmodified releases solely to facilitate the permitted uses above and
+must make this license and the applicable third-party notices available with
+those releases. Your applications may be commercial or non-commercial. No
+separate royalty is charged for the SDK permissions in this section.
+
+3. Conditions and limits
+
+You must retain copyright, license, and attribution notices in distributed
+copies. If a build process removes comments, preserve the notices in an
+accompanying license or notices file and make that file available with the
+delivered application or SDK assets.
+
+Except for the delivery expressly permitted in section 2, You may not sell,
+license, or republish the Software as a standalone SDK or library, claim it
+as Your own, or use its proprietary code to offer a competing SDK or service.
+You may not modify the proprietary Software beyond the integration
+transformations permitted above without Licensor's written permission.
+
+These limits do not restrict Your independently developed application code,
+rights granted by a third-party license, or rights that applicable law does
+not permit Licensor to restrict. No trademark rights are granted except to
+identify the Software accurately and preserve required notices.
+
+4. Service access is separate
+
+This license grants permission to use and deliver the SDK. It does not grant
+an account, credentials, service capacity, support commitment, or a service
+level agreement. Access to IntelliFend services, including any free or paid
+plan, remains subject to the applicable service agreement and usage terms.
+The free SDK license does not waive service charges or usage limits.
+
+This license does not itself obtain consent for processing personal data or
+replace applicable privacy terms, notices, or data-processing agreements.
+
+5. Third-party components
+
+Third-party components retain their own copyright and license terms, as
+identified in THIRD_PARTY_NOTICES.txt. Those terms govern the respective
+components and take precedence over any conflicting restriction here.
+Nothing in this license reduces permissions or obligations under those
+third-party licenses or claims ownership of third-party code.
+
+6. Warranty and liability
+
+Except as expressly agreed in writing and to the maximum extent permitted
+by applicable law, the Software is provided "AS IS" and "AS AVAILABLE",
+without warranties of merchantability, fitness for a particular purpose,
+non-infringement, uninterrupted operation, or error-free operation. The SDK
+does not guarantee that every automated or malicious request will be
+detected or blocked.
+
+To the maximum extent permitted by applicable law, Licensor is not liable
+for indirect, incidental, special, exemplary, or consequential damages, or
+loss of profits, revenue, data, or business opportunity arising from use of
+the Software. Nothing here excludes liability that cannot lawfully be
+excluded or overrides an express warranty or liability provision in an
+applicable written agreement with Licensor.
+
+7. Termination
+
+Licensor may terminate the permissions granted here if You materially breach
+this license and do not remedy the breach within 30 days after written
+notice. On termination, stop using and distributing the proprietary Software
+and remove copies under Your control, except copies required by law or kept
+solely in non-operational archives. You are not required to retrieve copies
+already cached on visitors' devices. Termination does not terminate rights
+granted independently by third-party licenses.
+
+8. Other agreements and reserved rights
+
+If an applicable written agreement with Licensor expressly addresses SDK
+licensing and conflicts with this license, that agreement controls the
+proprietary Software. Third-party terms continue to control their respective
+components. Rights not expressly granted are reserved. Distribution of a
+later SDK version does not retroactively change the terms accompanying an
+earlier version.

package/README.md

@@ -0,0 +1,264 @@
+# RequestShield Browser SDK
+
+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.
+
+## Install
+
+### npm / ESM
+
+Install the production release:
+
+```console
+npm install @intellifend/requestshieldjs
+```
+
+For testing, select the appropriate public prerelease channel:
+
+| Environment | Installation | `challengeUrl` |
+| --- | --- | --- |
+| QAT | `npm install @intellifend/requestshieldjs@qat` | `https://challenge-dev.intellifend.ai` |
+| STG | `npm install @intellifend/requestshieldjs@stg` | `https://challenge-stg.intellifend.ai` |
+| Production | `npm install @intellifend/requestshieldjs` | `https://challenge.intellifend.ai` |
+
+Import the API and initialize it with your environment's app key and Challenge
+Server URL. This example targets QAT:
+
+```javascript
+import { IntelliFend } from "@intellifend/requestshieldjs";
+
+IntelliFend.init({
+  appKey: "YOUR_QAT_APP_KEY",
+  challengeUrl: "https://challenge-dev.intellifend.ai",
+  protect: ["/api/register"],
+});
+```
+
+The `qat` and `stg` tags select prerelease packages; they do not configure service URLs.
+An installation without a tag selects the production `latest` release.
+Without `challengeUrl`, the SDK uses `https://challenge.intellifend.ai`. Use the
+app key and endpoint supplied for your environment. Pin the resolved version
+in your application's lockfile for reproducible installations.
+
+The ESM entry point exports `IntelliFend`, `IntelliFendError`, `VERSION`, and
+TypeScript types. It does not attach a global or initialize itself. Use it in
+browser applications with an ESM-capable toolchain.
+
+### Script tag
+
+You can also serve the packaged `dist/intellifend.js` file from your own static
+host, together with the license and third-party notices. For example:
+
+```html
+<script
+  src="/vendor/requestshield/intellifend.js"
+  integrity="sha384-<digest-from-checksums.json>"
+  crossorigin="anonymous"
+  data-app-key="YOUR_QAT_APP_KEY"
+  data-challenge-url="https://challenge-dev.intellifend.ai"
+  data-protect='["/api/register"]'
+  defer>
+</script>
+```
+
+Use the digest for `intellifend.js` from the packaged `dist/checksums.json`.
+The script-tag build creates the `IntelliFend` global and initializes it from
+script attributes. It never overwrites an existing `IntelliFend` global.
+For an IntelliFend-hosted script, use the immutable URL and matching integrity
+digest supplied for your SDK release.
+
+### WebAssembly requirement
+
+Version 2.0 requires WebAssembly, including when optional collection is disabled.
+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
+request without adding a token, and the backend applies its missing-token
+policy. Test this path together with your CSP and browser requirements.
+
+## Quick start
+
+### Seamless mode
+
+Pass the application endpoints that should receive a token in `protect`, as in
+the initialization example above. To protect endpoints on another origin,
+include their absolute HTTPS URLs:
+
+```javascript
+IntelliFend.init({
+  appKey: "YOUR_QAT_APP_KEY",
+  challengeUrl: "https://challenge-dev.intellifend.ai",
+  protect: ["/api/register", "https://api.example.com/login"],
+});
+```
+
+The SDK adds `X-IntelliFend-Token` to matching Fetch and asynchronous XHR requests
+when it obtains a non-empty token. Protect the corresponding business mutation
+on the backend; browser matching and token attachment are not authorization
+controls.
+
+### Manual mode
+
+Obtain a token immediately before the protected request and carry it unchanged. The header is the recommended carrier:
+
+```javascript
+const token = await IntelliFend.getToken({ action: "register" });
+const headers = new Headers({ "Content-Type": "application/json" });
+
+if (token) {
+  headers.set("X-IntelliFend-Token", token);
+}
+
+await fetch("/api/register", {
+  method: "POST",
+  headers,
+  body: JSON.stringify(formData),
+});
+```
+
+`getToken()` returns `""` when it cannot obtain a token and never rejects. Continue the application request so the backend can apply its configured missing-token or availability policy.
+
+## Configuration and API reference
+
+### `IntelliFend.init(config)`
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `appKey` | Yes | Public app key supplied by IntelliFend. |
+| `challengeUrl` | No | Absolute Challenge Server base URL. Defaults to `https://challenge.intellifend.ai`. It must use HTTP(S) and contain no credentials, query, or fragment. |
+| `fallbackChallengeUrl` | No | Approved absolute HTTPS secondary base URL, without credentials, query, or fragment. Omitted by default. An identical normalized primary URL adds no alternate endpoint. |
+| `timeoutMs` | No | Positive whole-flow time budget for create, solve, verify, and retries. Defaults to 5,000 ms. |
+| `protect` | No | Exact endpoint path or URL strings for Seamless mode. Omit or pass an empty list for Manual-only operation. |
+| `telemetry` | No | Enables the optional browser signal collection described below. Default `false`. |
+
+`init()` validates synchronously and throws `IntelliFendError` with code `invalid_config` for invalid input. Reinitialization replaces the previous valid configuration; a failing reinitialization leaves that configuration in place. Unknown configuration keys are ignored.
+
+Script-tag integrations use the equivalent attributes `data-app-key`, `data-challenge-url`, `data-protect`, and `data-fallback-challenge-url`. `data-protect` must be a JSON array of strings. The collector accepts only the exact `data-telemetry="true"` and `data-telemetry="false"` values; invalid supplied values use the same sanitized `invalid_config` auto-init warning.
+
+### Optional secondary domain
+
+Use the endpoint pair supplied by IntelliFend with a compatible approved bundle and service configuration:
+
+```javascript
+IntelliFend.init({
+  appKey: "YOUR_APP_KEY",
+  challengeUrl: "https://challenge.example.com",
+  fallbackChallengeUrl: "https://challenge-alt.example.com",
+});
+```
+
+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 `""`.
+
+### 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.
+
+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
+sends no separate telemetry request. Collection is disabled by default, and a
+collection failure does not fail token acquisition.
+
+### `IntelliFend.getToken(options?)`
+
+| Option | Description |
+| --- | --- |
+| `action` | Optional non-empty, case-sensitive action carried in the signed token. It is not an authorization decision by itself; compare it only with trusted backend configuration after normal token verification succeeds. |
+| `timeoutMs` | Optional per-call timeout. It may narrow, but never widen, the timeout set by `init()`. |
+| `signal` | Optional `AbortSignal` that cancels the complete token flow. |
+
+The method always resolves to a string: the issued token or `""` for validation, cancellation, timeout, transport, service, response, or solver failure.
+
+### Endpoint matching
+
+- A root-relative entry is resolved once against the current page origin.
+- An absolute entry must not contain credentials. Cross-origin entries require HTTPS, except for `localhost`, `127.0.0.1`, and `[::1]`; same-origin HTTP is allowed.
+- Query strings and fragments are ignored. Origin and pathname must otherwise match exactly, including case and trailing slash.
+- Relative application URLs use `document.baseURI` at the native call boundary: Fetch captures it when `fetch()` is called, and XHR captures it when `open()` is called. A later `<base>` change cannot retarget a delayed protected request.
+- Rules apply to every HTTP method.
+- Seamless mode covers Fetch and asynchronous XHR. It does not cover synchronous XHR, native form navigation, `sendBeacon`, WebSocket, EventSource, service-worker-owned traffic, or transports cached before SDK initialization.
+- Fetch requests whose effective mode is `no-cors` are sent unchanged because JavaScript cannot add the token header.
+
+## Integration behavior
+
+### Fail-through and header precedence
+
+If token acquisition, endpoint matching, interception, or header preparation fails, the SDK sends the original application request once without adding a token. A protected Fetch call is snapshotted synchronously, so mutating its URL, options, headers, or body after `fetch()` returns does not change a delayed dispatch. A pre-existing non-empty `X-IntelliFend-Token` value always wins and suppresses automatic token acquisition. This browser fail-through is not an allow decision; the backend owns missing-token policy and verification.
+
+Protected asynchronous XHR also captures its body when `send()` is called.
+Later edits to URLSearchParams, FormData, ArrayBuffer/view bytes, or a Document
+do not change the delayed request. Native XHR retains responsibility for body
+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.
+
+### CORS
+
+For a cross-origin protected application API, allow the `X-IntelliFend-Token` request header in that API's CORS policy. This is separate from the Challenge Server connection.
+
+### 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.
+
+### Challenge Server proxies
+
+A Challenge Server proxy must forward binary request and response bodies unchanged, accept `POST` requests with no request `Content-Type`, and preserve the browser `Origin`. Do not parse or reserialize the bodies as JSON. Challenge create and verify requests deliberately set no author headers so their normal cross-origin POSTs remain CORS simple requests without an OPTIONS preflight.
+
+### CSP
+
+For 2.0, pages with Content Security Policy need `'wasm-unsafe-eval'` in
+`script-src` alongside the approved script origin, `connect-src` permission for
+both configured Challenge Server origins, and `worker-src blob:` for the
+proof-of-work Web Worker. Keep JavaScript evaluation blocked; broad
+`'unsafe-eval'` is unnecessary. Configure the secondary URL as HTTPS directly;
+an HTTP redirect is insufficient on an HTTPS page.
+
+### Subresource Integrity
+
+Pin an immutable `requestshield/v<version>/intellifend.js` URL, use the matching `sha384-...` value from that release's `checksums.json`, and set `crossorigin="anonymous"`. Do not combine a fixed integrity value with `requestshield/latest/` or the mutable root alias. The static host must authorize the cross-origin script request through CORS.
+
+### Sensitive values
+
+Do not log raw tokens or raw challenges. Redact the selected token carrier in proxies and application logs without changing the value sent for verification.
+
+## Browser compatibility and performance
+
+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.
+
+## License
+
+The proprietary SDK is licensed by Request Shield under [LICENSE.txt](LICENSE.txt).
+Integration with authorized IntelliFend services has no SDK royalty; service
+access and charges remain separate. Public distribution does not make the SDK
+open source. Preserve the license and [third-party notices](THIRD_PARTY_NOTICES.txt) when
+bundling or redistributing it with your application.
+
+## Support
+
+Contact IntelliFend support for an application key, the approved Challenge Server URL, an immutable bundle URL and SRI digest, or integration assistance. Include the SDK version and sanitized error context; never include tokens, challenges, or credentials.