@intellifend/requestshieldjs 2.0.0-stg.263 → 2.0.0-stg.279

package/README.md

@@ -144,7 +144,7 @@ await fetch("/api/register", {
 | `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. |
+| `protect` | No | Endpoint paths or URLs for Seamless mode, optionally containing named path parameters as described below. Omit or pass an empty list for Manual-only operation. |
 | `telemetry` | No | Enables the optional browser signal collection on API v2. Default `false`; collection stays disabled on v1. |
 
 `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.
@@ -199,14 +199,63 @@ The method always resolves to a string: the issued token or `""` for validation,
 
 ### Endpoint matching
 
+Use named path parameters for endpoints whose path contains an identifier.
+
+For npm/ESM initialization:
+
+```javascript
+import { IntelliFend } from "@intellifend/requestshieldjs";
+
+IntelliFend.init({
+  appKey: "YOUR_APP_KEY",
+  protect: ["/api/orders/:orderId/items"],
+});
+```
+
+For script-tag initialization, use the equivalent attribute:
+
+```html
+data-protect='["/api/orders/:orderId/items"]'
+```
+
 - 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.
+- Origin must match exactly. A parameter such as `:orderId` occupies a whole pathname segment and matches exactly one non-empty segment, never a `/`. Names start with an ASCII letter or `_`, followed by ASCII letters, digits, or `_`.
+- Multiple parameters are allowed, for example `/api/accounts/:accountId/orders/:orderId`. Names are descriptive; repeating a name does not require equal values. Parameters are allowed only in the pathname, never in the origin.
+- Every other segment matches literally. Rules without parameters keep exact matching; rules never become prefix matches. Path case and trailing slash remain significant.
+- Escape a literal leading colon by doubling it: `/api/orders/::orderId` matches `/api/orders/:orderId` only, and `/api/orders/:::orderId` matches `/api/orders/::orderId` only. When upgrading from exact-only matching, change any existing literal colon-leading segment to this escaped form before enabling the new syntax.
+- A colon-leading segment that is neither a valid parameter nor a `::` escape is invalid configuration, including `:`, `:123`, and `:order-id`. Invalid raw path segments are rejected even if URL dot-segment normalization would remove them. Other punctuation is literal; wildcard hosts, wildcard paths, regular expressions, and catch-all parameters are not supported.
+- Query strings and fragments in rules and requests are ignored. `/api/orders/:id?include=details` still requires one `:id` segment; `?` does not make the parameter optional.
+- Browser URL normalization applies, including dot-segment removal. The SDK does not decode percent escapes: `%2F` and `%5C` remain within one segment, and a literal `%3AorderId` differs from `:orderId`. Literal encoded segments must match their normalized URL spelling, including percent-escape case.
 - 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.
 
+For `/api/orders/:orderId/items` on the page origin:
+
+| Request URL | Matches? |
+| --- | --- |
+| `/api/orders/12345/items` | Yes |
+| `/api/orders/abc-123/items` | Yes |
+| `/api/orders/12345/items?include=details` | Yes |
+| `/api/orders//items` | No: empty segment |
+| `/api/orders/12345/items/extra` | No: extra segment |
+| `/api/orders/12345/items/` | No: trailing slash |
+| `/api/orders/12345/Items` | No: different case |
+| Same pathname on another origin | No |
+
+Absolute rules such as
+`https://api.example.com/api/orders/:orderId/items` use the same
+path syntax and require that exact origin. Exact rules and parameter rules can
+coexist; overlapping rules still produce only one application request and one
+token attachment. Invalid patterns follow the normal `invalid_config` behavior
+of `init()` or script-tag initialization.
+
+Matching only decides whether the frontend attaches a token. Configure backend
+verification for every corresponding route, including dynamic routes; a browser
+rule does not enable backend protection or bind token claims to that route.
+
 ## Integration behavior
 
 ### Fail-through and header precedence

package/dist/checksums.json

@@ -1,18 +1,18 @@
 {
-  "version": "2.0.0-stg.263",
+  "version": "2.0.0-stg.279",
   "algorithm": "sha384",
   "bundles": [
     {
       "name": "intellifend",
       "path": "intellifend.js",
-      "version": "2.0.0-stg.263",
-      "integrity": "sha384-E+o9twhbhpyu9Lefsc/acu+W9lhsd8HEFnz/7c/BxjCG1zgv682pQUwFMROELUFp"
+      "version": "2.0.0-stg.279",
+      "integrity": "sha384-TtARvTM567xNuCnn/jpph7nt6QmJwtZz+VFtu6Nj80tyTMDA3SIL++nNVB2k4tIJ"
     },
     {
       "name": "intellifend-esm",
       "path": "intellifend.mjs",
-      "version": "2.0.0-stg.263",
-      "integrity": "sha384-0fDXcTFm0c7pEpNb+ZbKG0D0LSGSs2LDVp7i/1CJ/rFenYZbi9qXOeglfg7Jo4Me"
+      "version": "2.0.0-stg.279",
+      "integrity": "sha384-mhSDs1GM9oafWm4Bxd9DTWPNbSkR1Qms+DOoZWQ8M7uDiHPNZH+fdzWc1U0Ij/Oe"
     }
   ]
 }

package/dist/index.d.ts

@@ -11,7 +11,11 @@ export interface InitConfig {
     /** Overall time budget for one getToken() flow (create + solve + verify),
      * including retries, in milliseconds. Default 5 000. */
     timeoutMs?: number;
-    /** Exact endpoint paths/URLs protected automatically through Fetch and async XHR. */
+    /** Endpoint paths/URLs protected automatically through Fetch and async XHR.
+     * Origin and literal path segments match exactly; :name matches one non-empty
+     * segment. Names use [A-Za-z_][A-Za-z0-9_]*; :: escapes a literal leading colon.
+     * Query/fragment are ignored; case and trailing slashes remain significant.
+     * Matching attaches tokens only; protect the corresponding backend routes too. */
     protect?: string[];
     /** Opts into bounded, page-memory-only browser signal collection. Default false. */
     telemetry?: boolean;
@@ -31,7 +35,8 @@ export declare const IntelliFend: {
     /**
      * Validates and stores the configuration. Synchronous: throws
      * IntelliFendError("invalid_config") on bad input. Unknown keys are ignored;
-     * `protect` enables exact endpoint interception; `telemetry` opts into the
+     * `protect` enables exact-origin endpoint interception with optional named
+     * path parameters; `telemetry` opts into the
      * bounded signal collector.
      *
      * Re-init is allowed and replaces the configuration (last init wins); a