unshared-clientjs-sdk 2.3.0 → 3.0.0-rc.15

package/README.md

@@ -1,240 +1,437 @@
 # unshared-clientjs-sdk
 
-Server-side Node.js SDK for [Unshared](https://unshared.ai) — detect account sharing, analyze user events for fraud, and run email verification flows.
-
----
+Node.js SDK for Unshared v3 ingestion, risk checks, email verification, and application protection middleware.
 
 ## Install
 
 ```bash
-npm install unshared-clientjs-sdk
+npm install unshared-clientjs-sdk@^3
 ```
 
-**Requires Node.js 18+**
-
----
-
-## Quick Start
+Requires Node.js 20 or newer.
 
 ```typescript
 import { UnsharedClient } from 'unshared-clientjs-sdk';
 
 const client = new UnsharedClient({
-  apiKey: process.env.UNSHARED_API_KEY, // usk_…
+  apiKey: process.env.UNSHARED_API_KEY!, // usk_...
 });
 ```
 
----
+V3 fingerprint and user-event ingestion encrypts the complete JSON object with AES-256-GCM before sending it to Unshared. Check, Trigger, and Verify remain structured plaintext JSON over HTTPS.
+
+## V3 Methods
+
+### `submitFingerprint(payload)`
 
-## Methods
+Sends any JSON object to `POST /v3/submit-fingerprint-event` without reshaping it.
+
+```typescript
+const result = await client.submitFingerprint({
+  hash: 'full-456',
+  stable_hash: 'stable-123',
+  components: {},
+  custom_data: { nested: ['preserved', 1, false] },
+});
+```
 
-### `processUserEvent(params)`
+### `processUserEvent(payload)`
 
-Record a user event and get a fraud signal back. Call this on login, signup, or any high-value action.
+Sends any JSON object to `POST /v3/process-user-event` without reshaping it.
 
 ```typescript
 const result = await client.processUserEvent({
-  eventType:    'login',
-  userId:       'user_123',
-  emailAddress: 'user@example.com',
-  deviceId:     'device_abc',
-  sessionHash:  'session_xyz',
-  ipAddress:    '1.2.3.4',         // plaintext — not encrypted
-  userAgent:    req.headers['user-agent'],
+  event_type: 'LOGIN',
+  identity: { user_id: user.id, email_address: user.email },
+  identifiers: {
+    unshared_device_id: permanentDeviceId,
+    device_id: deviceId,
+    session_hash: sessionId,
+  },
+  custom_data: { plan: 'pro' },
 });
+```
 
-if (result.success && result.data?.analysis.is_user_flagged) {
-  // Block or challenge the user
+Both ingestion calls accept objects up to 1 MiB and return:
+
+```typescript
+{
+  event_id: string;
+  collected_at: string;
+  endpoint_version: 'v3';
 }
 ```
 
-**Fields encrypted before sending:** `emailAddress`, `deviceId`
+Ingestion is not automatically retried because an ambiguous failure may already have created an event.
 
----
+### `checkUser(...)`
 
-### `checkUser(emailAddress, deviceId)`
-
-Quick check to see if a user is flagged. Useful in middleware or route guards.
+Checks existing risk state through `POST /v3/check-user`.
 
 ```typescript
-const result = await client.checkUser('user@example.com', 'device_abc');
+const result = await client.checkUser('user@example.com', {
+  permanentDeviceId,
+  deviceId,
+  fingerprintId: stableHash,
+  fullHash,
+  sessionHash,
+});
 
 if (result.data?.is_user_flagged) {
-  // Deny access
+  // Block or challenge.
 }
 ```
 
-> **Safe default:** Returns `{ is_user_flagged: false }` on any failure (network error, outage). A backend outage will never accidentally block a legitimate user.
+You can also pass the v3 request object directly:
 
----
+```typescript
+await client.checkUser({
+  user_id: user.id,
+  email_address: user.email,
+  identifiers: { device_id: deviceId },
+});
+```
 
-### `triggerEmailVerification(emailAddress, deviceId)`
+`checkUser` is read-only and can retry. On transport or HTTP failure it deliberately returns a clean verdict with `failedOpen` metadata so an outage does not accidentally block users.
 
-Send a 6-digit verification code to the user's email.
+### Email Verification
 
-```typescript
-await client.triggerEmailVerification('user@example.com', 'device_abc');
-```
+Trigger returns a challenge ID that Verify must send back:
 
----
+```typescript
+const trigger = await client.triggerEmailVerification(user.email, deviceId, {
+  permanentDeviceId,
+  fingerprintId: stableHash,
+});
 
-### `verify(emailAddress, deviceId, code)`
+const verify = await client.verifyEmail({
+  verification_id: trigger.data!.verification_id!,
+  code: submittedCode, // string preserves leading zeroes
+});
+```
 
-Validate the code the user submitted.
+`verifyEmail(...)` is stateless and recommended for distributed deployments. The source-compatible methods retain the challenge in the current `UnsharedClient` instance:
 
 ```typescript
-const result = await client.verify('user@example.com', 'device_abc', '123456');
-
-if (!result.success) {
-  if (result.error?.code === 'VERIFICATION_FAILED') {
-    // Wrong or expired code — ask user to retry
-  } else {
-    // Transport error (DELIVERY_FAILED) — retry or show generic error
-  }
-} else {
-  // Verified — success: true means the code was correct
-}
+await client.triggerEmailVerification(user.email, deviceId);
+const verify = await client.verify(user.email, deviceId, submittedCode);
 ```
 
----
+Trigger and Verify are never automatically retried because the first request may have committed before an ambiguous response failure.
 
-### `submitFingerprintEvent(fingerprint, opts?)`
+## Compatibility Methods
 
-Submit a browser fingerprint collected by `unshared-frontend-sdk`. Typically called by the middleware — you usually won't call this directly.
+Existing v2 package call sites remain valid while using v3 routes and encrypted ingestion envelopes.
 
 ```typescript
-await client.submitFingerprintEvent(fingerprint, {
-  userId:      'user_123',
-  sessionHash: 'session_xyz',
-  eventType:   'page_view',
+const result = await client.processUserEvent({
+  eventType: 'login',
+  userId: user.id,
+  emailAddress: user.email,
+  deviceId,
+  sessionHash: sessionId,
+  ipAddress: req.ip,
+  userAgent: req.headers['user-agent'] ?? '',
 });
+
+if (result.success && result.data?.analysis.is_user_flagged) {
+  // Block or challenge.
+}
 ```
 
----
+`submitFingerprintEvent(fingerprint, opts)` is also retained. New proxy implementations should prefer `submitFingerprint(body)` so unknown future fields cannot be lost.
 
-## Protection Middleware (Recommended)
+## Protection Middleware
 
-`unsharedBoundToUser` is the full-featured middleware: auto-injects the fingerprint script, enforces verdicts, handles email verification flows, and dispatches events.
+`unsharedBoundToUser` injects browser fingerprint collection, protects routes, caches verdicts, and hosts the proxy verification flow.
 
 ```typescript
-import { UnsharedClient, unsharedBoundToUser, flaggedResponse } from 'unshared-clientjs-sdk';
-
+import express from 'express';
+import {
+  UnsharedClient,
+  unsharedBoundToUser,
+  flaggedResponse,
+} from 'unshared-clientjs-sdk';
+
+const app = express();
 app.set('trust proxy', 1);
-app.use(express.json());
+app.use(express.json()); // the default 100 KiB limit is supported
 
+// Mount your authentication/session middleware here, before Unshared.
 const client = new UnsharedClient({ apiKey: process.env.UNSHARED_API_KEY! });
-
-app.use(unsharedBoundToUser(client, {
-  userId: (req) => req.cookies?.userId,
-  emailAddress: (req) => req.cookies?.email,
-  includePathPrefix: ['/api/'],
+const middleware = unsharedBoundToUser(client, {
+  userId: (req) => req.user?.id,
+  emailAddress: (req) => req.user?.email,
   onFlagged: ({ emailAddress, res }) => {
     res.status(403).json(flaggedResponse(emailAddress));
   },
-}));
+});
+app.use(middleware);
+// Call middleware.destroy() on shutdown, test teardown, or before re-mounting.
 ```
 
-**Smoke test:** `curl http://localhost:3000/__unshared/status` — returns `{ "status": "anonymous" | "ok" | "flagged" }`.
-
-**Key options:**
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `userId` | `(req) => string \| undefined` | — | **Required.** Resolve the current user's ID |
-| `emailAddress` | `(req) => string \| undefined` | — | Resolve the current user's email |
-| `routePrefix` | `string` | `"/__unshared"` | Route mount prefix |
-| `includePathPrefix` | `string[]` | — | Only these path prefixes trigger verdicts and events |
-| `onFlagged` | `(ctx) => void` | — | Called when a flagged user makes a request |
-| `disableBotFilter` | `boolean` | `false` | Skip bot UA filter (enable for E2E testing) |
-| `checkUserTimeoutMs` | `number` | `500` | Timeout (ms) for checkUser API calls; fails open on timeout |
-| `skipPaths` | `string[]` | — | Paths to skip entirely (static assets, health checks) |
-| `corsOrigins` | `string \| string[]` | — | Allowed CORS origins; handles OPTIONS preflight |
-| `onError` | `(error, ctx) => void` | — | Called on background SDK errors for observability |
-
-`flaggedResponse(email)` formats the 403 body the inline script expects to trigger the `unshared:flagged` browser event. `ACCOUNT_FLAGGED_ERROR` is the error code string it uses, also exported for server-side checks.
-
-### Interstitial (proxy mode)
-
-`unsharedBoundToUser` mounts a `GET /__unshared/interstitial-flow` route that returns the company's published interstitial flow. It calls `client.getInterstitialFlow()` with the secret key and carries no user data. The browser SDK's `showInterstitial()` calls this route automatically when constructed with `baseUrl` (proxy mode), then runs the modal's OTP actions through the existing `/__unshared/verify-trigger` and `/__unshared/verify` routes. Identity is resolved server-side via your `emailAddress` resolver or the `__unshared_email` cookie — the browser sends only the OTP.
-
----
+Keep your existing parser order and limits. Mount authentication/session middleware
+needed by your resolvers before Unshared. The SDK also reads its own unparsed POST
+routes automatically, up to **1 MiB (1,048,576 UTF-8 bytes)**, without a configuration
+option or an Express dependency. Ordinary application routes are not parsed by the
+SDK. Existing parsed bodies are respected and checked against the same limit.
+Structured browser-to-proxy submissions (including the inline script) fit Express's
+default **100 KiB (102,400 serialized UTF-8 bytes)** without public configuration:
+send the full payload if it fits; otherwise empty both local/session storage lists
+while keeping every cookie; if still too large, omit `context.browser_storage`.
+The complete raw fingerprint, including future fields, and all core identity,
+device, session, SDK and event context are never trimmed. If those alone exceed
+100 KiB, the browser returns `REQUEST_TOO_LARGE`; the inline script logs that code
+and sends nothing. Cookies are never partially selected or truncated.
+
+Low-level browser `submitFingerprint(payload)` preserves arbitrary objects exactly
+and rejects proxy payloads above 100 KiB rather than reducing them. Direct browser
+submission retains full snapshots and its 1 MiB logical limit. An earlier parser
+or reverse proxy with a smaller limit can still reject a request before Unshared.
+
+Oversized SDK request bodies return 413, malformed JSON returns 400, and unfinished
+reads time out after 30 seconds with 408. Raw bodies must use identity encoding
+(compressed bodies return 415). Fingerprints and retained cookies are not truncated;
+duplicate SDK fingerprint caches are excluded from storage snapshots. The encrypted
+platform request retains its existing 1.5 MiB envelope limit; the full logical payload,
+including server-added context, must still fit within 1 MiB.
+
+### ProtectionConfig
+
+All public options for `unsharedBoundToUser(client, config)` are listed below.
+Resolvers receive your Node/Express request (`TReq`). The `@internal`
+`disableS3Fingerprint` switch is intentionally excluded from this public table.
+
+| Option | Default | Behavior / Trade-off |
+|---|---|---|
+| `userId` | Required | Server-side resolver; return `undefined` on logout/anonymous requests. Do not derive authentication from SDK cookies. Sentinel hydration IDs can briefly reuse a fresh identity cookie, but are not real user IDs. |
+| `emailAddress` | No resolver | Resolver first, then HttpOnly `__unshared_email`, then parsed `req.body.email`. Missing email skips ordinary checks/enforcement/events. Supply a trusted resolver for protection and verification instead of relying on body fallback. |
+| `routePrefix` | `/__unshared` | Prefix for SDK-owned routes. Gate, overlay and automatic interstitial require the default; browser proxy paths are fixed to it. |
+| `corsOrigins` | Unset (no CORS headers) | String or array of allowed origins for SDK routes. Specific matching origins allow credentials; `*` does not. Prefer an explicit allowlist; CORS is not authentication. |
+| `cacheTTL` | `60000` ms | Per-user, in-process verdict TTL with stale-while-revalidate. Longer TTLs reduce checks but delay risk changes. Defensive fail-open verdicts use a separate 5000 ms TTL. |
+| `maxCacheSize` | `10000` entries | Bounds verdict memory; evicts oldest-written entries at capacity. Smaller caches can cause more blocking misses. |
+| `streamingIdleMs` | `50` ms | Budget from first buffered HTML write to response end. Beyond it, stream through without fingerprint injection. Raise for slow partial rendering, accepting longer buffering. |
+| `skipPaths` | Built-in static skips only | Additional literal pathname prefixes that bypass identity reconciliation, injection, checks, enforcement and ordinary events entirely. Wins over includes; never put protected content here. See path rules below. |
+| `includePathPrefix` | Unset (all non-skipped paths) | Literal pathname prefixes for ordinary checks, enforcement and user events; `[]` includes none. Does not disable identity cookies, logout reconciliation, HTML injection or SDK-owned routes. |
+| `disableBotFilter` | `false` | Bypasses the middleware and injected-script UA bot filters, useful for Playwright/Puppeteer E2E. Does not disable platform-side filters; normally leave off in production. |
+| `debug` | `false` | Injected-script diagnostics in `window.__unshared.lastDecision` and `console.debug('[Unshared]', ...)`; reason codes and optional HTTP status only. See diagnostics below. |
+| `checkUserTimeoutMs` | `1500` ms | Hard check budget; underlying middleware checks use no retries. Lower values reduce latency but increase fail-open risk. |
+| `cacheMissStrategy` | `'block'` | `'block'` waits for a verdict or timeout. `'async'` serves uncached requests while warming the cache, leaving those requests unenforced; reported as `async_miss`. |
+| `sessionId` | Cookie fallback | Resolver first, then `__unshared_sid`. Missing/`unknown` sessions suppress ordinary user events, not verdict checks. |
+| `deviceId` | Header/cookie fallback | Resolver, then `X-Device-Id`, then `__unshared_stable_hash`, then legacy `__unshared_fp_id`. Missing values are omitted, not fabricated or replaced with the full hash. Client-provided identifiers are correlation signals, not authentication. |
+| `onFlagged` | Unset (pass through) | Receives `{ userId, emailAddress, verdict, req, res, next }` for flagged, unverified users. Own the response or call `next()`; exceptions pass through. Ignored by gate/overlay. |
+| `blockFlagged` | `false` | Shorthand for gate mode when `flaggedMode` is unset. Requires installed `unshared-frontend-sdk` and the default prefix. |
+| `flaggedMode` | Unset | `'gate'` withholds app content: HTML GET navigations receive a 200 verification-only page, other requests a 403 `account_flagged`. `'overlay'` delivers HTML with a cosmetic blur/modal but returns 403 for data requests. Wins over `blockFlagged`, ignores `onFlagged`; overlay implies `autoInterstitial`. Both require the browser SDK and default prefix. |
+| `autoInterstitial` | `false` (implied by overlay) | Boots a proxy browser SDK to show the published modal on intercepted 403s/deferred status flagging and reload on completion. UX only; pair with server enforcement. Requires browser SDK and default prefix. |
+| `interstitialFlowType` | `'email_verification'` | Flow requested by the automatic inline modal, including overlay. Does not override the standalone gate page's default flow. |
+| `onError` | Unset | Observer `(error, { operation, userId?, emailAddress? })` for SDK operation failures. Does not turn fail-open into fail-closed; keep callbacks defensive and redact identity data. |
+| `onFailOpen` | Throttled warning | Best-effort observer with `operation: 'checkUser'`, `reason`, optional `status`, `userId`, `emailAddress`. Reasons: `timeout`, `http_error`, `exception`, `no_device_id`, `async_miss`. Status 0 denotes transport failure. Without a callback, degraded reasons warn at most once/minute/reason; intentional `async_miss` does not warn. |
+
+### Scope and Enforcement
+
+Processing order is SDK-owned routes, static/custom skips, identity reconciliation,
+then the include filter and ordinary protection. Includes use `pathname.startsWith`,
+not globs or segment matching; use trailing slashes deliberately. Built-in skips
+cover JS/CSS/maps, images, fonts, WASM and prefixes `/static/`, `/assets/`, `/public/`,
+`/_next/`, `/__vite/`, `/favicon`. Media (`mp3`, `mp4`, `webm`, `ogg`), XML, TXT and PDF
+are also skipped unless gate/overlay enforcement is active. Custom skips always win.
+
+For a publisher that protects article data but keeps the reader's saved-list API usable:
 
-## Simple Fingerprint Middleware
+```typescript
+const middleware = unsharedBoundToUser(client, {
+  userId: (req) => req.user?.id,
+  emailAddress: (req) => req.user?.email,
+  flaggedMode: 'overlay',
+  includePathPrefix: ['/api/article/'],
+});
+app.use(middleware); // after authentication/session middleware
+// /api/article/123: checks and 403 enforcement for flagged, unverified readers.
+// /api/me/list: no ordinary check/enforcement/event; still reconciles identity.
+// HTML outside the include list: still eligible for fingerprint script injection.
+```
 
-`createUnsharedMiddleware` is a lightweight alternative that only proxies fingerprint events — no verdicts, no script injection, no verification flows. Use `unsharedBoundToUser` unless you have a specific reason not to.
+An excluded HTML shell can still collect/submit fingerprints and poll `/__unshared/status`:
+`includePathPrefix` is not a collection opt-out or a global API-call filter. Use
+`skipPaths` only when the request should truly bypass the SDK. In overlay mode never
+embed protected article text in delivered HTML; removing a modal reveals that HTML.
+Use gate mode (and include the HTML route) when the server must withhold the document.
+With no gate/overlay or blocking `onFlagged`, the default is collection, not blocking.
+Checks remain fail-open on availability failures; an already cached flagged verdict
+is preserved on a failed refresh. Neither SDK cookies nor a modal replace app auth.
+
+Before enabling the built-in remediation UI, publish the required web interstitial
+flow for your company in the Unshared dashboard (including `email_verification` for
+the standalone gate). A draft or missing flow cannot render. Install
+`unshared-frontend-sdk` and retain the default route prefix. Custom gate pages remain
+application-owned via `onFlagged` when built-in enforcement is off. This middleware
+does not add verification rate limiting. Confirm the platform's verification limits
+for your deployment and apply per-user/IP limits and auth checks in your app or
+gateway, including SDK verification routes. Dispatch backoff is not a verification
+abuse control.
+
+Retain the middleware instance and call `middleware.destroy()` on shutdown, test
+teardown or before hot-reload re-mounts to stop verdict-cache and asset-refresh timers.
+
+### Assets and Diagnostics
+
+The middleware exposes:
+
+- `POST /__unshared/submit-fp`
+- `GET /__unshared/status`
+- `POST /__unshared/verify-trigger`
+- `POST /__unshared/verify`
+- `GET /__unshared/fp.js`
+- `GET /__unshared/fingerprint.js`
+- `GET /__unshared/interstitial-flow`
+
+These are Node middleware routes (with the configured prefix). `fp.js` serves the
+installed browser SDK UMD; a missing bundle returns **503 with `Cache-Control: no-store`**,
+not an empty cacheable 200. `fingerprint.js` serves the S3-first fingerprint
+agent with a bundled fallback; if neither is available, it also returns **503 with
+`Cache-Control: no-store`**. Both support HEAD with the same status/headers and no body;
+successful assets are cacheable for one hour. Renderer modes validate the SDK bundle
+at startup and throw if it is missing.
+
+For injected-script troubleshooting, set `debug: true` on the middleware and inspect
+`window.__unshared.lastDecision` (`{ code, status? }`) or the `[Unshared]` debug log.
+Only the latest decision is retained; repeated identical logs are suppressed. Codes
+include `BOT_SKIPPED`, `MISSING_UID`, `SENTINEL_UID`, `COLLECTOR_NOT_READY`,
+`COLLECTION_STARTED`, `COLLECTION_ERROR`, `DEDUP_SKIPPED`, `REQUEST_TOO_LARGE`,
+`ASSET_LOAD_ERROR`, `SUBMIT_STARTED`, `SUBMIT_SUCCESS`, `SUBMIT_REJECTED`,
+`SUBMIT_INVALID_RESPONSE`, `SUBMIT_HTTP_ERROR`,
+`SUBMIT_NETWORK_ERROR`, `SUBMIT_ABORTED`, `SUBMIT_TIMEOUT`, `SUBMIT_FAILED` and
+`OUTER_EXCEPTION`. An HTTP 200 response with `success: false` or `accepted: false`
+is a rejection, not `SUBMIT_SUCCESS`. These diagnostics contain no PII, cookies, hashes, payloads or raw
+exception messages; server observer contexts can contain identity and need redaction.
+For automated-browser tests, also set `disableBotFilter: true`: it reaches the inline
+submitter, not just the server check. It is not a `BrowserConfig` option and does not
+turn off the standalone browser SDK's own bot filter.
+
+### Identity Retention
+
+Canonical readable cookies are `__unshared_stable_hash` (stable fingerprint),
+`__unshared_full_hash` (current full hash), and `__unshared_device_id` (independent
+`upid_<uuid-v4>` permanent ID, also retained in localStorage). The readable legacy
+`__unshared_fp_id` remains an alias for the stable hash. The server-written legacy
+`__unshared_fingerprint_id` is HttpOnly and preserves the **first full hash** already
+present, rather than replacing it with each collection. Checks, events and verification prefer
+the canonical stable/full cookies, falling back to their respective legacy aliases;
+stable, full and permanent identifiers are distinct and never substituted for one another.
+
+On eligible browser init/route activity, correlation cookies (including
+`__unshared_sid`) renew to a rolling **400 days, `Max-Age=34560000`**, before submission
+deduplication. Renewal does not require a new network event. Successful proxy submit
+handling also renews hash/permanent cookies; only a server response can renew the
+HttpOnly legacy full-hash cookie. Cookies use `Path=/`, `SameSite=Lax`, and `Secure`
+on HTTPS. Browser privacy controls, storage blocking or user deletion can shorten
+retention; 400 days is a requested maximum, not a guarantee.
+
+This does **not** extend authentication/session validity. SDK identity cookies
+`__unshared_uid`, `__unshared_uid_at`, and HttpOnly `__unshared_email` retain their
+existing 365-day server TTL; the HttpOnly `__unshared_verification_id` challenge
+cookie remains ten minutes. Logged-out server requests clear user/session/email and
+challenge cookies even outside the include list, but not on truly skipped paths.
+Permanent device/hash cookies are correlation only, not proof of a logged-in user.
+
+Collection caches retain both normalized wire data (`__unshared_fp`) and the complete
+raw result (`__unshared_fp_raw`) in per-tab sessionStorage, with an in-memory fallback.
+They are not 400-day collection caches. Browser init, MPA and SPA lifecycle paths reuse
+the pair; legacy wire-only caches are recollected. Consecutive `(user, pathname + query)`
+submissions share a last-key guard with the injected script; an A-to-B-to-A
+revisit can submit again. This is deduplication, not a delivery guarantee: there is
+no persistent replay queue, and ambiguous ingestion failures are not retried.
+
+## Simple Proxy Middleware
+
+`createUnsharedMiddleware` only proxies fingerprint events. It preserves arbitrary fields and augments trusted request context.
 
 ```typescript
-import { createUnsharedMiddleware } from 'unshared-clientjs-sdk';
+import { createUnsharedMiddleware } from 'unshared-clientjs-sdk/middleware';
 
-app.use(express.json());
 app.use(createUnsharedMiddleware(client, {
   userIdExtractor: (req) => req.user?.id,
+  corsOrigins: 'https://app.example.com',
 }));
+app.use(express.json());
 ```
 
-**Options:**
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `userIdExtractor` | `(req) => string \| undefined` | — | Pull user ID from your auth session |
-| `eventTypeExtractor` | `(req) => string \| undefined` | — | Override event type |
-| `sessionIdExtractor` | `(req) => string \| undefined` | — | Override session ID |
-| `ipAddressExtractor` | `(req) => string \| undefined` | — | Override IP address |
-| `defaultEventType` | `string` | `"browser_event"` | Fallback event type |
-| `routePrefix` | `string` | `"/unshared"` | Route mount prefix |
-| `corsOrigins` | `string \| string[]` | — | Allowed CORS origins; handles OPTIONS preflight automatically |
-
-> **Note:** This middleware uses a different default prefix (`/unshared`) and route (`submit-fingerprint-event`) than `unsharedBoundToUser` (`/__unshared`, `submit-fp`).
-
----
+Its default route is `POST /unshared/submit-fingerprint-event`.
 
-## Web / Edge Handler
+## Web Standard Handler
 
-For serverless and edge environments (Next.js App Router, Vercel Edge Functions, Cloudflare Workers), import from the `unshared-clientjs-sdk/web` entry point:
+Use the edge/serverless entry point with Next.js, Cloudflare Workers, Vercel Edge, or other Web Standard runtimes:
 
 ```typescript
 import { createWebProtectionMiddleware } from 'unshared-clientjs-sdk/web';
 ```
 
-`createWebProtectionMiddleware` accepts the same `disableBotFilter` and `checkUserTimeoutMs` options as `unsharedBoundToUser`, with Web Standard `Request`/`Response` types instead of Express ones.
-
----
-
-## Configuration
-
-```typescript
-new UnsharedClient({
-  apiKey:     'usk_…',                               // required
-  baseUrl:    'https://api.unshared.ai', // optional
-  timeout:    10_000,                                 // optional, ms
-  maxRetries: 3,                                      // optional
-});
-```
-
----
-
-## Response shape
-
-All methods return `ApiResult<T>`:
+It wraps `(request, next, ctx?)` using `Request` and `Response`. Supply
+`ctx.waitUntil` on edge runtimes to keep background work alive after returning the
+response. HTML injection requires an actual HTML response body; `NextResponse.next()`
+has none, so mount the browser/React SDK in the app for collection in that setup.
+
+### WebProtectionConfig
+
+This is the complete Web config, not the Node/Express interface. Shared scope,
+identity retention and enforcement trade-offs above apply, subject to the explicit
+Web differences here.
+
+| Option | Default | Behavior / Trade-off |
+|---|---|---|
+| `userId` | Required | Synchronous trusted resolver `(request: Request) => string \| undefined`; return `undefined` for logout/anonymous visitors. Same sentinel handling as Node. |
+| `emailAddress` | No resolver | Resolver, then HttpOnly `__unshared_email`. Parsed SDK POST handlers may additionally fall back to `body.email`; ordinary requests do not parse it. Prefer server-authenticated email. |
+| `routePrefix` | `/__unshared` | SDK route prefix; renderer modes require the default. |
+| `corsOrigins` | Unset | String/array allowlist for SDK routes. Matching explicit origins allow credentials; `*` does not. CORS does not authenticate callers. |
+| `cacheTTL` | `60000` ms | In-process verdict TTL with stale-while-revalidate; longer TTL delays changed risk. Defensive fail-open TTL is 5000 ms; capacity is fixed at 10000 entries. |
+| `skipPaths` | Built-in static skips only | Additional literal pathname prefixes that truly bypass identity, injection and protection; same built-in skip rules as Node. Wins over includes. |
+| `includePathPrefix` | Unset (all non-skipped paths) | Scopes ordinary checks, enforcement and events, not identity reconciliation, eligible HTML injection or SDK-owned routes. `[]` includes none. |
+| `disableBotFilter` | `false` | Bypasses middleware and injected-script UA filtering for E2E; does not disable platform/standalone-browser filters. |
+| `debug` | `false` | Same PII-free injected-script `window.__unshared.lastDecision` and `[Unshared]` diagnostics as Node. |
+| `checkUserTimeoutMs` | `1500` ms | Blocking cache-miss check budget, no middleware check retries; availability failures fail open. No async-miss strategy option. |
+| `sessionId` | Cookie fallback | Request resolver, then `__unshared_sid`; missing/`unknown` suppresses ordinary events, not checks. |
+| `deviceId` | Header/cookie fallback | Request resolver, `X-Device-Id`, canonical `__unshared_stable_hash`, then legacy `__unshared_fp_id`. Missing values omitted; these are not authentication credentials. |
+| `fingerprintSdkBundle` | `''` | Manually supply browser SDK UMD text, typically a bundler raw import. Required for fresh inline collection and all renderer modes; installing the package alone does not load it. Missing `/fp.js` returns 503 `no-store`. |
+| `blockFlagged` | `false` | Gate shorthand unless `flaggedMode` is set. Requires bundle and default prefix. |
+| `flaggedMode` | Unset | `'gate'` withholds HTML/data; `'overlay'` delivers HTML but withholds data with 403 and implies automatic modal. Wins over `blockFlagged`; both ignore `onFlagged`. Bundle/default prefix required; flow routing must be supplied separately (below). |
+| `autoInterstitial` | `false` (implied by overlay) | Automatic modal UX, not access control. Requires bundle, default prefix and your flow-route wiring. |
+| `interstitialFlowType` | `'email_verification'` | Automatic inline/overlay flow type, not the standalone gate's default flow. Must be published. |
+| `onFlagged` | Unset (pass through) | Receives `{ userId, emailAddress, verdict, request }`; return a `Response`/`Promise<Response>` to block or redirect, or `null` to pass through. Exceptions pass through. No Express `res`/`next` callback; ignored by gate/overlay. |
+| `onError` | Unset | `(error, { operation, userId?, emailAddress? })` observer; keep defensive and redact identities. Not an enforcement switch. |
+| `onFailOpen` | Unset (no default warning) | Best-effort observer with `operation: 'checkUser'`, `reason`, optional `status`, `userId`, `emailAddress`. Reasons: `timeout`, `http_error`, `exception`, `no_device_id`; no `async_miss`. Status 0 denotes transport failure. |
+
+The Web handler automatically serves only `fp.js`, `submit-fp`, `status`,
+`verify-trigger` and `verify` under the prefix (plus OPTIONS). It does **not** implement
+`fingerprint.js` or `interstitial-flow`; those paths return 404 here. Arrange separate
+asset/flow handlers **before** this middleware if your proxy collection or modal
+needs them. Passing `fingerprintSdkBundle` does not add those routes or publish a flow.
+For bundlers supporting raw imports, pass the string imported from
+`unshared-frontend-sdk/dist/index.umd.js?raw`; otherwise load it using your runtime's
+asset mechanism. There is no Node filesystem auto-discovery in this entry point.
+
+There are no Web options for `maxCacheSize`, `streamingIdleMs`, `cacheMissStrategy`
+or the internal `disableS3Fingerprint`, and no Express response interception or
+`middleware.destroy()` method on the returned `WebMiddleware`. Do not copy those
+Node-only features into a Web integration.
+
+## Result and Error Handling
 
 ```typescript
-{
+type ApiResult<T> = {
   success: boolean;
-  data?:   T;
-  error?:  { code: string; message: string; retryAfter?: number };
-  status:  number; // HTTP status code
-}
+  status: number; // 0 for a network failure
+  data?: T;
+  error?: {
+    code: string;
+    message: string;
+    retryAfter?: number;
+  };
+  failedOpen?: { status: number; reason?: 'no_device_id' };
+};
 ```
 
----
-
-## Security
-
-All PII is encrypted with **AES-256-GCM** before leaving your server. The encryption key is derived from your API key with SHA-256. Your API key is sent as the `X-API-Key` header — never in a URL or browser context.
-
----
-
-## See Also
-
-- [Quickstart](./docs/quickstart.md) — step-by-step Express setup from zero
-- [Flag semantics and testing](./docs/flag-semantics.md) — how flags work, E2E testing tips, timeout behavior
+- Success requires a valid `{ success: true, data }` response envelope.
+- Bodies larger than 1 MiB fail locally with `REQUEST_TOO_LARGE`.
+- `Retry-After` is exposed as `error.retryAfter` on 429 responses.
+- Protected same-origin submission routes never return 5xx to browser code.
+- Keep the secret API key server-side and exclude logical identity/event bodies from request logs before SDK encryption.