unshared-clientjs-sdk 2.0.0-rc.9 → 2.0.0

package/dist/esm/web/types.d.mts

@@ -0,0 +1,110 @@
+/**
+ * Web Standard Request/Response handler types for serverless/edge environments.
+ *
+ * These types use the global `Request` and `Response` from the Fetch API,
+ * available in: Next.js App Router Route Handlers, Vercel Edge Functions,
+ * Cloudflare Workers, Deno Deploy, Bun, and Node.js 18+.
+ *
+ * The DOM lib reference above scopes the Fetch API globals to this file only,
+ * avoiding `window`/`document` pollution in the Node.js middleware code.
+ */
+import type { Verdict } from '../middleware/verdict-cache';
+/** A downstream handler that returns a Response. */
+export type WebHandler = (request: Request) => Response | Promise<Response>;
+/** Middleware that wraps a downstream handler, optionally intercepting the response. */
+export type WebMiddleware = (request: Request, next: WebHandler) => Response | Promise<Response>;
+export interface WebSubmitOptions {
+    /** Override userId extractor. Falls back to body.user_id. */
+    userIdExtractor?: (req: Request) => string | undefined;
+    /** Override eventType extractor. Falls back to body.event_type. */
+    eventTypeExtractor?: (req: Request) => string | undefined;
+    /** Override sessionId extractor. Falls back to X-Session-Id header, then body.session_id. */
+    sessionIdExtractor?: (req: Request) => string | undefined;
+    /** Override IP address extractor. Falls back to CF-Connecting-IP / X-Real-IP / X-Forwarded-For headers. */
+    ipAddressExtractor?: (req: Request) => string | undefined;
+    /** Default event type when none is extractable. @default "browser_event" */
+    defaultEventType?: string;
+    /**
+     * Route prefix the handler responds under.
+     * @default "/unshared"
+     */
+    routePrefix?: string;
+    /**
+     * Allowed CORS origins for the fingerprint route.
+     * Use `"*"` to allow all origins, or pass a specific origin / array of origins.
+     * The handler handles OPTIONS preflight automatically when this is set.
+     */
+    corsOrigins?: string | string[];
+}
+export interface WebProtectionConfig {
+    /**
+     * Required. Resolves the current user's ID from the request.
+     * Return undefined for anonymous/logged-out visitors.
+     */
+    userId: (req: Request) => string | undefined;
+    /**
+     * Resolves the current user's email address from the request.
+     * Falls back to HttpOnly cookie → request body when not configured.
+     */
+    emailAddress?: (req: Request) => string | undefined;
+    /** Route prefix for internal routes. @default "/__unshared" */
+    routePrefix?: string;
+    /** Allowed CORS origins for /__unshared/* routes. */
+    corsOrigins?: string | string[];
+    /** Verdict cache TTL in ms. @default 60000 */
+    cacheTTL?: number;
+    /** Paths to skip entirely (static assets, health checks). */
+    skipPaths?: string[];
+    /** When set, only paths matching one of these prefixes get events dispatched and checkUser called. */
+    includePathPrefix?: string[];
+    /** Resolves a custom session ID. Falls back to __unshared_sid cookie. */
+    sessionId?: (req: Request) => string | undefined;
+    /**
+     * Resolves a device ID from the request.
+     * Falls back to X-Device-Id header → __unshared_fp_id cookie.
+     */
+    deviceId?: (req: Request) => string | undefined;
+    /**
+     * Inline JavaScript bundle for the frontend SDK, served at /__unshared/fp.js.
+     *
+     * In Node.js environments the middleware reads this from node_modules via
+     * `require.resolve('unshared-frontend-sdk/dist/index.umd.js')`. Edge runtimes
+     * do not have filesystem access, so the bundle must be passed as a string
+     * (typically imported via a bundler):
+     *
+     * ```typescript
+     * import fingerprintSdkBundle from 'unshared-frontend-sdk/dist/index.umd.js?raw';
+     * createWebProtectionMiddleware(client, { ..., fingerprintSdkBundle });
+     * ```
+     *
+     * If omitted, the fp.js route returns 404. The inline script degrades
+     * gracefully — the cached-fingerprint path still works.
+     */
+    fingerprintSdkBundle?: string;
+    /**
+     * Called when a flagged, unverified user makes a request.
+     *
+     * Return a `Response` to block/redirect, or `null` to pass through (injection
+     * still happens). Exceptions are caught — the request passes through on error.
+     *
+     * This differs from the Node.js middleware: in Web Standard environments
+     * Response objects are immutable, so the callback returns a new Response
+     * rather than mutating an existing one.
+     */
+    onFlagged?: (context: {
+        userId: string;
+        emailAddress: string;
+        verdict: Verdict;
+        request: Request;
+    }) => Response | Promise<Response> | null;
+    /**
+     * Called when a background SDK operation fails (fire-and-forget API calls,
+     * verdict refreshes, etc.). Use this to pipe errors to your logging or
+     * monitoring system for observability.
+     */
+    onError?: (error: unknown, context: {
+        operation: 'processUserEvent' | 'submitFingerprintEvent' | 'checkUser' | 'verifyTrigger' | 'verify';
+        userId?: string;
+        emailAddress?: string;
+    }) => void;
+}

package/dist/esm/web/types.mjs

@@ -0,0 +1 @@
+export{};

package/dist/esm/web/web-helpers.d.mts

@@ -0,0 +1,55 @@
+/**
+ * Thin adapter functions that bridge Web Standard `Request`/`Response` to the
+ * data shapes the rest of the SDK expects. These mirror the Node.js
+ * `src/middleware/utils/*` functions but read from Web Standard Headers
+ * instead of Node.js `req.headers` objects.
+ */
+/**
+ * Reads a single cookie value from the raw Cookie header.
+ * Mirrors `parseCookie(req, name)` in src/middleware/utils/cookies.ts.
+ */
+export declare function parseCookieFromRequest(request: Request, name: string): string | undefined;
+/**
+ * Extract the real client IP from proxy headers. Web Standard has no
+ * equivalent of `req.ip` or `req.socket.remoteAddress`, so we rely entirely
+ * on standard proxy headers (which all edge platforms populate).
+ *
+ * Priority: CF-Connecting-IP → X-Real-IP → X-Forwarded-For (first entry).
+ */
+export declare function extractClientIpFromRequest(request: Request): string;
+/**
+ * Resolves device ID from: custom resolver → X-Device-Id header → __unshared_fp_id cookie.
+ * Mirrors `extractDeviceIdOrUndefined` in src/middleware/utils/device-id.ts.
+ */
+export declare function extractDeviceIdFromRequest(request: Request, resolveDeviceId?: (req: Request) => string | undefined): string | undefined;
+/** Same as extractDeviceIdFromRequest but returns "unknown" when nothing is available. */
+export declare function extractDeviceIdFromRequestOrUnknown(request: Request, resolveDeviceId?: (req: Request) => string | undefined): string;
+/**
+ * Returns true if the request arrived over HTTPS.
+ *
+ * Web Standard has no `socket.encrypted`, so this checks:
+ * 1. The `x-forwarded-proto` header (set by reverse proxies / load balancers)
+ * 2. The URL protocol (for direct HTTPS requests)
+ */
+export declare function isSecureWebRequest(request: Request): boolean;
+/**
+ * Build a JSON response. Mirrors `sendJson(res, status, data)` in
+ * src/middleware/utils/http-helpers.ts, but returns a new Response instead
+ * of mutating one.
+ */
+export declare function jsonResponse(statusCode: number, data: unknown, extraHeaders?: HeadersInit): Response;
+/** Build a status-only response with no body. */
+export declare function emptyResponse(statusCode: number, extraHeaders?: HeadersInit): Response;
+/** Build a raw-body response (for the fp.js bundle). */
+export declare function bodyResponse(statusCode: number, body: string, extraHeaders?: HeadersInit): Response;
+/**
+ * Append a Set-Cookie header to a Headers object. Web Standard `Headers`
+ * supports multiple Set-Cookie values via `.append()`.
+ */
+export declare function appendCookieToHeaders(headers: Headers, cookieValue: string): void;
+/**
+ * Merge a downstream Response's headers with additional Set-Cookie entries
+ * and overrides. Preserves multiple Set-Cookie values from the source
+ * response via `getSetCookie()` (Node 20+, all modern edge runtimes).
+ */
+export declare function mergeResponseHeaders(source: Headers, overrides?: Record<string, string>, extraCookies?: string[]): Headers;

package/dist/esm/web/web-helpers.mjs

@@ -0,0 +1 @@
+export function parseCookieFromRequest(e,t){const o=e.headers.get("cookie");if(!o)return;const n=o.match(new RegExp(`(?:^|; )${t}=([^;]*)`));return n?decodeURIComponent(n[1]):void 0}export function extractClientIpFromRequest(e){const t=e.headers.get("cf-connecting-ip");if(t)return t;const o=e.headers.get("x-real-ip");if(o)return o;const n=e.headers.get("x-forwarded-for");if(n){const e=n.split(",")[0]?.trim();if(e)return e}return""}export function extractDeviceIdFromRequest(e,t){if(t)try{const o=t(e);if(o)return o}catch{}const o=e.headers.get("x-device-id");if(o)return o;return parseCookieFromRequest(e,"__unshared_fp_id")||void 0}export function extractDeviceIdFromRequestOrUnknown(e,t){return extractDeviceIdFromRequest(e,t)??"unknown"}export function isSecureWebRequest(e){if("https"===e.headers.get("x-forwarded-proto"))return!0;try{return"https:"===new URL(e.url).protocol}catch{return!1}}export function jsonResponse(e,t,o){const n=new Headers(o);return n.set("Content-Type","application/json"),new Response(JSON.stringify(t),{status:e,headers:n})}export function emptyResponse(e,t){return new Response(null,{status:e,headers:new Headers(t)})}export function bodyResponse(e,t,o){return new Response(t,{status:e,headers:new Headers(o)})}export function appendCookieToHeaders(e,t){e.append("Set-Cookie",t)}export function mergeResponseHeaders(e,t,o){const n=new Headers;e.forEach((e,t)=>{"set-cookie"!==t.toLowerCase()&&n.set(t,e)});const r="function"==typeof e.getSetCookie?e.getSetCookie():[];for(const e of r)n.append("Set-Cookie",e);if(o)for(const e of o)n.append("Set-Cookie",e);if(t)for(const[e,o]of Object.entries(t))n.set(e,o);return n}

package/dist/index.d.ts

@@ -1,6 +1,8 @@
-export { UnsharedLabsClient } from './client';
+export { UnsharedClient } from './client';
 export { createUnsharedMiddleware, assertTrustProxy } from './middleware';
 export type { MiddlewareOptions } from './middleware';
 export { unsharedBoundToUser, VerdictCache, } from './middleware/index';
 export type { ProtectionConfig, Verdict } from './middleware/index';
-export type { UnsharedLabsClientConfig, ApiResult, UnsharedLabsError, SubmitFingerprintOptions, SubmitFingerprintResult, ProcessUserEventParams, ProcessUserEventResult, CheckUserResult, TriggerEmailVerificationResult, VerifyResult, VerificationFlowStep, VerificationFlowConfigResult, } from './client';
+export type { UnsharedClientConfig, ApiResult, UnsharedError, SubmitFingerprintOptions, SubmitFingerprintResult, ProcessUserEventParams, ProcessUserEventResult, CheckUserResult, TriggerEmailVerificationResult, VerifyResult, } from './client';
+export type { UnsharedRequest, UnsharedResponse, UnsharedNextFunction } from './types';
+export { sendJson } from './middleware/utils/http-helpers';

package/dist/index.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.VerdictCache=exports.unsharedBoundToUser=exports.assertTrustProxy=exports.createUnsharedMiddleware=exports.UnsharedLabsClient=void 0;var client_1=require("./client");Object.defineProperty(exports,"UnsharedLabsClient",{enumerable:!0,get:function(){return client_1.UnsharedLabsClient}});var middleware_1=require("./middleware");Object.defineProperty(exports,"createUnsharedMiddleware",{enumerable:!0,get:function(){return middleware_1.createUnsharedMiddleware}}),Object.defineProperty(exports,"assertTrustProxy",{enumerable:!0,get:function(){return middleware_1.assertTrustProxy}});var index_1=require("./middleware/index");Object.defineProperty(exports,"unsharedBoundToUser",{enumerable:!0,get:function(){return index_1.unsharedBoundToUser}}),Object.defineProperty(exports,"VerdictCache",{enumerable:!0,get:function(){return index_1.VerdictCache}});
+"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.sendJson=exports.VerdictCache=exports.unsharedBoundToUser=exports.assertTrustProxy=exports.createUnsharedMiddleware=exports.UnsharedClient=void 0;var client_1=require("./client");Object.defineProperty(exports,"UnsharedClient",{enumerable:!0,get:function(){return client_1.UnsharedClient}});var middleware_1=require("./middleware");Object.defineProperty(exports,"createUnsharedMiddleware",{enumerable:!0,get:function(){return middleware_1.createUnsharedMiddleware}}),Object.defineProperty(exports,"assertTrustProxy",{enumerable:!0,get:function(){return middleware_1.assertTrustProxy}});var index_1=require("./middleware/index");Object.defineProperty(exports,"unsharedBoundToUser",{enumerable:!0,get:function(){return index_1.unsharedBoundToUser}}),Object.defineProperty(exports,"VerdictCache",{enumerable:!0,get:function(){return index_1.VerdictCache}});var http_helpers_1=require("./middleware/utils/http-helpers");Object.defineProperty(exports,"sendJson",{enumerable:!0,get:function(){return http_helpers_1.sendJson}});

package/dist/middleware/dispatch-dedupe.d.ts

@@ -0,0 +1,11 @@
+export declare class DispatchDedupe {
+    private readonly _entries;
+    private readonly _ttlMs;
+    constructor(ttlMs?: number);
+    private _key;
+    mark(userId: string, eventType: string): void;
+    wasRecentlyDispatched(userId: string, eventType: string): boolean;
+    clear(): void;
+    get size(): number;
+    private _sweep;
+}

package/dist/middleware/dispatch-dedupe.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.DispatchDedupe=void 0;const DEFAULT_TTL_MS=1e4,SWEEP_THRESHOLD=1e3;class DispatchDedupe{constructor(t=1e4){this.i=new Map,this.h=t}o(t,s){return`${t}|${s}`}mark(t,s){this.i.set(this.o(t,s),Date.now()),this.i.size>1e3&&this.p()}wasRecentlyDispatched(t,s){const e=this.o(t,s),i=this.i.get(e);return!(void 0===i||Date.now()-i>this.h&&(this.i.delete(e),1))}clear(){this.i.clear()}get size(){return this.i.size}p(){const t=Date.now()-this.h;for(const[s,e]of this.i)e<t&&this.i.delete(s)}}exports.DispatchDedupe=DispatchDedupe;

package/dist/middleware/index.d.ts

@@ -1,19 +1,19 @@
-import type { Request, Response, NextFunction } from 'express';
-import type { UnsharedLabsClient } from '../client';
+import type { UnsharedRequest, UnsharedResponse, UnsharedNextFunction } from '../types';
+import type { UnsharedClient } from '../client';
 import { VerdictCache } from './verdict-cache';
 import type { Verdict } from './verdict-cache';
-export interface ProtectionConfig {
+export interface ProtectionConfig<TReq extends UnsharedRequest = UnsharedRequest> {
     /**
      * Required. Resolves the current user's ID from the request.
      * Return undefined for anonymous/logged-out visitors.
      */
-    userId: (req: Request) => string | undefined;
+    userId: (req: TReq) => string | undefined;
     /**
      * Resolves the current user's email address from the request.
      * Required in Tier 2 (backend-only). Recommended in Tier 1.
      * Falls back to HttpOnly cookie → req.body.email when not configured.
      */
-    emailAddress?: (req: Request) => string | undefined;
+    emailAddress?: (req: TReq) => string | undefined;
     /** Route prefix for internal routes. @default "/__unshared" */
     routePrefix?: string;
     /** Allowed CORS origins for /__unshared/* routes. */
@@ -22,13 +22,15 @@ export interface ProtectionConfig {
     cacheTTL?: number;
     /** Paths to skip entirely (static assets, health checks). */
     skipPaths?: string[];
+    /** When set, only paths matching one of these prefixes get events dispatched and checkUser called. */
+    includePathPrefix?: string[];
     /** Resolves a custom session ID. Falls back to __unshared_sid cookie. */
-    sessionId?: (req: Request) => string | undefined;
+    sessionId?: (req: TReq) => string | undefined;
     /**
      * Resolves a device ID from the request.
-     * Falls back to __unshared_fp_id cookie → X-Device-Id header.
+     * Falls back to X-Device-Id header → __unshared_fp_id cookie.
      */
-    deviceId?: (req: Request) => string | undefined;
+    deviceId?: (req: TReq) => string | undefined;
     /**
      * Called when a flagged, unverified user makes a request.
      * You own the response — block, redirect, or call next() to let it through.
@@ -40,11 +42,24 @@ export interface ProtectionConfig {
         userId: string;
         emailAddress: string;
         verdict: Verdict;
-        req: Request;
-        res: Response;
-        next: NextFunction;
+        req: TReq;
+        res: UnsharedResponse;
+        next: UnsharedNextFunction;
+    }) => void;
+    /**
+     * Called when a background SDK operation fails (fire-and-forget API calls,
+     * verdict refreshes, etc.). Use this to pipe errors to your logging or
+     * monitoring system for observability.
+     *
+     * Without this callback, background errors are silently swallowed (fail-open).
+     * The middleware never blocks requests due to these errors regardless.
+     */
+    onError?: (error: unknown, context: {
+        operation: 'processUserEvent' | 'submitFingerprintEvent' | 'checkUser' | 'verifyTrigger' | 'verify';
+        userId?: string;
+        emailAddress?: string;
     }) => void;
 }
 export type { Verdict };
 export { VerdictCache };
-export declare function unsharedBoundToUser(client: UnsharedLabsClient, config: ProtectionConfig): (req: Request, res: Response, next: NextFunction) => void;
+export declare function unsharedBoundToUser<TReq extends UnsharedRequest = UnsharedRequest>(client: UnsharedClient, config: ProtectionConfig<TReq>): (req: TReq, res: UnsharedResponse, next: UnsharedNextFunction) => void;

package/dist/middleware/index.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.VerdictCache=void 0,exports.unsharedBoundToUser=unsharedBoundToUser;const fs_1=require("fs"),verdict_cache_1=require("./verdict-cache");Object.defineProperty(exports,"VerdictCache",{enumerable:!0,get:function(){return verdict_cache_1.VerdictCache}});const rate_limit_backoff_1=require("./rate-limit-backoff"),response_interceptor_1=require("./response-interceptor"),fingerprint_script_1=require("./injection/fingerprint-script"),submit_fp_1=require("./routes/submit-fp"),verify_1=require("./routes/verify"),content_type_1=require("./utils/content-type"),skip_paths_1=require("./utils/skip-paths"),CHECK_USER_TIMEOUT_MS=500;function unsharedBoundToUser(e,t){if(!t.userId)throw new Error("[Unshared] userId resolver is required");if(!t.emailAddress){let e=!1;try{require.resolve("unshared-frontend-sdk"),e=!0}catch{}e||console.warn("[Unshared] Warning: emailAddress resolver is not configured and unshared-frontend-sdk is not installed.\nNo user events will be submitted. Either install unshared-frontend-sdk (Tier 1) or\nprovide emailAddress in your middleware config (Tier 2).")}const{userId:r,emailAddress:n,routePrefix:i="/__unshared",corsOrigins:s,cacheTTL:o=6e4,skipPaths:c,sessionId:d,deviceId:a,onFlagged:u}=t,l=new verdict_cache_1.VerdictCache(o),f=new rate_limit_backoff_1.RateLimitBackoff,p=Date.now().toString(36),_=(0,fingerprint_script_1.generateFingerprintScript)(i,p);let h="";try{const e=require.resolve("unshared-frontend-sdk/dist/index.umd.js");h=(0,fs_1.readFileSync)(e,"utf8")}catch{}const v=(0,submit_fp_1.handleSubmitFingerprint)({client:e,verdictCache:l,rateLimitBackoff:f,resolveUserId:r,resolveEmailAddress:n,resolveSessionId:d,resolveDeviceId:a}),m=(0,verify_1.handleVerifyTrigger)({client:e,verdictCache:l,resolveEmailAddress:n,resolveDeviceId:a}),C=(0,verify_1.handleVerify)({client:e,verdictCache:l,resolveEmailAddress:n,resolveDeviceId:a}),I=s?Array.isArray(s)?s:[s]:null,g=`${i}/fp.js`,k=`${i}/submit-fp`,y=`${i}/verify-trigger`,A=`${i}/verify`;return function(t,s,o){const p=t.path;if(p.startsWith(i+"/"))return function(e,t){if(!I)return;const r=e.headers.origin??"",n=I.includes("*");(n||I.includes(r))&&(t.setHeader("Access-Control-Allow-Origin",n?"*":r),t.setHeader("Access-Control-Allow-Methods","POST, OPTIONS"),t.setHeader("Access-Control-Allow-Headers","Content-Type, X-Idempotency-Key, X-Session-Id, X-Device-Id"),t.setHeader("Access-Control-Allow-Credentials","true"))}(t,s),"OPTIONS"===t.method?void s.status(204).end():"GET"===t.method&&p===g?(s.setHeader("Content-Type","application/javascript"),s.setHeader("Cache-Control","public, max-age=3600"),void s.status(200).end(h)):"POST"===t.method&&p===k?void v(t,s):"POST"===t.method&&p===y?void m(t,s):"POST"===t.method&&p===A?void C(t,s):void s.status(404).json({success:!1,error:{code:"NOT_FOUND",message:"Unknown route"}});if((0,skip_paths_1.shouldSkipPath)(p,c))return void o();let S;try{S=r(t)}catch{}if(!S)return clearEmailCookieIfPresent(t,s),interceptForInjection(t,s,_),void o();const T=resolveEmail(t,n);if(setUserIdCookie(s,S),T&&setEmailCookie(s,T),!T)return interceptForInjection(t,s,_),void o();const x=extractSessionId(t,d),E=extractDeviceId(t,a),w=extractFingerprintId(t),O=t.headers["user-agent"]??"",U=t.ip??"";f.isPaused()||dispatchUserEvent(e,l,f,{userId:S,emailAddress:T,sessionId:x,deviceId:E,fingerprintId:w,userAgent:O,ipAddress:U,eventType:`${t.method} ${t.path}`});const P=l.get(S);P?(l.isStale(S)&&!l.isRefreshing(S)&&(l.markRefreshing(S),fetchAndCacheVerdict(e,l,S,T,E,w,x).finally(()=>l.clearRefreshing(S))),applyVerdict(P,S,T,t,s,o,_,u)):fetchAndCacheVerdict(e,l,S,T,E,w,x).then(e=>{applyVerdict(e,S,T,t,s,o,_,u)}).catch(()=>{interceptForInjection(t,s,_),o()})}}function resolveEmail(e,t){if(t)try{const r=t(e);if(r)return r}catch{}const r=parseCookie(e,"__unshared_email");if(r)return r;const n=e.body?.email;return"string"==typeof n&&n?n:void 0}function applyVerdict(e,t,r,n,i,s,o,c){if(interceptForInjection(n,i,o),e.isFlagged&&!e.isVerified&&c)try{c({userId:t,emailAddress:r,verdict:e,req:n,res:i,next:s})}catch{s()}else s()}function preventHtmlCaching(e,t){delete e.headers["if-none-match"],delete e.headers["if-modified-since"];const r=t.writeHead.bind(t);t.writeHead=function(e,...n){const i=t.getHeader("content-type");return i&&String(i).includes("text/html")&&(t.setHeader("Cache-Control","no-store"),t.removeHeader("ETag"),t.removeHeader("Last-Modified")),r(e,...n)}}function interceptForInjection(e,t,r){preventHtmlCaching(e,t),(0,response_interceptor_1.interceptResponse)(t,(e,t)=>{if(!(0,content_type_1.isHtmlContentType)(t))return null;const n=e.toString("utf8"),i=n.lastIndexOf("</body>");return-1===i?n+r:n.slice(0,i)+r+n.slice(i)})}function dispatchUserEvent(e,t,r,n){e.processUserEvent({eventType:n.eventType,userId:n.userId,emailAddress:n.emailAddress,ipAddress:n.ipAddress,deviceId:n.deviceId,fingerprintId:n.fingerprintId,sessionHash:n.sessionId,userAgent:n.userAgent}).then(e=>{e.success&&e.data?.analysis&&t.update(n.userId,{isFlagged:e.data.analysis.is_user_flagged}),!e.success&&e.error?.retryAfter&&r.pause(1e3*e.error.retryAfter)}).catch(()=>{})}async function fetchAndCacheVerdict(e,t,r,n,i,s,o){const c={};i&&"unknown"!==i&&(c.deviceId=i),s&&(c.fingerprintId=s);const d=await Promise.race([e.checkUser(n,c),new Promise(e=>setTimeout(()=>e(null),500))]);if(!d)return{isFlagged:!1,isVerified:!1,emailAddress:n,sessionId:o,cachedAt:0,ttl:0};const a=d.data?.is_user_flagged??!1;return t.set(r,{isFlagged:a,isVerified:!1,emailAddress:n,sessionId:o}),t.get(r)}function parseCookie(e,t){const r=e.headers.cookie;if(!r)return;const n=r.match(new RegExp(`(?:^|; )${t}=([^;]*)`));return n?decodeURIComponent(n[1]):void 0}function extractSessionId(e,t){if(t)try{const r=t(e);if(r)return r}catch{}return parseCookie(e,"__unshared_sid")??"unknown"}function extractDeviceId(e,t){if(t)try{const r=t(e);if(r)return r}catch{}const r=parseCookie(e,"__unshared_fp_id");if(r)return r;const n=e.headers["x-device-id"];return"string"==typeof n&&n?n:"unknown"}function extractFingerprintId(e){return parseCookie(e,"__unshared_fingerprint_id")||void 0}function appendSetCookie(e,t){const r=e.getHeader("Set-Cookie");if(r){const n=Array.isArray(r)?[...r]:[String(r)];n.push(t),e.setHeader("Set-Cookie",n)}else e.setHeader("Set-Cookie",t)}function setUserIdCookie(e,t){appendSetCookie(e,`__unshared_uid=${encodeURIComponent(t)}; Path=/; SameSite=Lax`)}function setEmailCookie(e,t){appendSetCookie(e,`__unshared_email=${encodeURIComponent(t)}; HttpOnly; Path=/; SameSite=Lax`)}function clearEmailCookieIfPresent(e,t){parseCookie(e,"__unshared_email")&&appendSetCookie(t,"__unshared_email=; HttpOnly; Path=/; SameSite=Lax; Max-Age=0")}
+"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.VerdictCache=void 0,exports.unsharedBoundToUser=unsharedBoundToUser;const fs_1=require("fs"),verdict_cache_1=require("./verdict-cache");Object.defineProperty(exports,"VerdictCache",{enumerable:!0,get:function(){return verdict_cache_1.VerdictCache}});const rate_limit_backoff_1=require("./rate-limit-backoff"),dispatch_dedupe_1=require("./dispatch-dedupe"),response_interceptor_1=require("./response-interceptor"),fingerprint_script_1=require("./injection/fingerprint-script"),submit_fp_1=require("./routes/submit-fp"),verify_1=require("./routes/verify"),http_helpers_1=require("./utils/http-helpers"),content_type_1=require("./utils/content-type"),skip_paths_1=require("./utils/skip-paths"),include_path_1=require("./utils/include-path"),is_bot_1=require("./utils/is-bot"),client_ip_1=require("./utils/client-ip"),cookies_1=require("./utils/cookies"),device_id_1=require("./utils/device-id"),secure_1=require("./utils/secure"),sentinel_user_id_1=require("./utils/sentinel-user-id"),CHECK_USER_TIMEOUT_MS=500;function unsharedBoundToUser(e,t){if(!t.userId)throw new Error("[Unshared] userId resolver is required");if(!t.emailAddress){let e=!1;try{require.resolve("unshared-frontend-sdk"),e=!0}catch{}e||console.warn("[Unshared] Warning: emailAddress resolver is not configured and unshared-frontend-sdk is not installed.\nNo user events will be submitted. Either install unshared-frontend-sdk (Tier 1) or\nprovide emailAddress in your middleware config (Tier 2).")}const{userId:r,emailAddress:i,routePrefix:n="/__unshared",corsOrigins:s,cacheTTL:o=6e4,skipPaths:d,includePathPrefix:c,sessionId:a,deviceId:u,onFlagged:_,onError:l}=t,p=new verdict_cache_1.VerdictCache(o),h=new rate_limit_backoff_1.RateLimitBackoff,f=new dispatch_dedupe_1.DispatchDedupe,v=Date.now().toString(36),m=(0,fingerprint_script_1.generateFingerprintScript)(n,v);let I="";try{const e=require.resolve("unshared-frontend-sdk/dist/index.umd.js");I=(0,fs_1.readFileSync)(e,"utf8")}catch{}const S=(0,submit_fp_1.handleSubmitFingerprint)({client:e,verdictCache:p,rateLimitBackoff:h,dispatchDedupe:f,resolveUserId:r,resolveEmailAddress:i,resolveSessionId:a,resolveDeviceId:u,onError:l}),k=(0,verify_1.handleVerifyTrigger)({client:e,verdictCache:p,resolveEmailAddress:i,resolveDeviceId:u,onError:l}),g=(0,verify_1.handleVerify)({client:e,verdictCache:p,resolveEmailAddress:i,resolveDeviceId:u,onError:l}),y=s?Array.isArray(s)?s:[s]:null,A=`${n}/fp.js`,C=`${n}/submit-fp`,x=`${n}/verify-trigger`,q=`${n}/verify`,w=`${n}/status`;return function(t,s,o){const v=(0,http_helpers_1.getRequestPath)(t.url),E=t.url||v;if(v.startsWith(n+"/")){if(function(e,t){if(!y)return;const r=e.headers.origin??"",i=y.includes("*");(i||y.includes(r))&&(t.setHeader("Access-Control-Allow-Origin",i?"*":r),t.setHeader("Access-Control-Allow-Methods","POST, OPTIONS"),t.setHeader("Access-Control-Allow-Headers","Content-Type, X-Idempotency-Key, X-Session-Id, X-Device-Id"),t.setHeader("Access-Control-Allow-Credentials","true"))}(t,s),"OPTIONS"===t.method)return void(0,http_helpers_1.sendEmpty)(s,204);if("GET"===t.method&&v===A)return s.setHeader("Content-Type","application/javascript"),s.setHeader("Cache-Control","public, max-age=3600"),void(0,http_helpers_1.sendBody)(s,200,I);if("POST"===t.method&&(v===C||v===x||v===q))return void 0===t.body?void(0,http_helpers_1.sendJson)(s,400,{success:!1,error:{code:"BODY_PARSER_MISSING",message:"req.body is undefined. Mount a JSON body-parsing middleware (e.g., express.json()) before the Unshared middleware."}}):v===C?void S(t,s):v===x?void k(t,s):void g(t,s);if("GET"===t.method&&v===w){let n;try{n=r(t)}catch{}if(!n)return void(0,http_helpers_1.sendJson)(s,200,{status:"anonymous"});const o=resolveEmail(t,i);return void(async()=>{let r=p.get(n);if((!r||p.isStale(n))&&o&&!h.isPaused()&&!p.isRefreshing(n)){p.markRefreshing(n);try{const i=(0,device_id_1.extractDeviceIdOrUndefined)(t,u),s=extractFingerprintId(t),d=extractSessionId(t,a),c=i??s??"unknown";await fetchAndCacheVerdict(e,p,n,o,c,s,d),r=p.get(n)}catch(e){l&&l(e,{operation:"checkUser",userId:n,emailAddress:o})}finally{p.clearRefreshing(n)}}r&&r.isFlagged&&!r.isVerified&&_&&o?(0,http_helpers_1.sendJson)(s,200,{status:"flagged",email:o}):(0,http_helpers_1.sendJson)(s,200,{status:"ok"})})()}return void(0,http_helpers_1.sendJson)(s,404,{success:!1,error:{code:"NOT_FOUND",message:"Unknown route"}})}if((0,skip_paths_1.shouldSkipPath)(v,d))return void o();if(!(0,include_path_1.shouldIncludePath)(v,c))return interceptForInjection(t,s,m),void o();let b;try{b=r(t)}catch{}if((0,sentinel_user_id_1.isSentinelUserId)(b)){const e=(0,cookies_1.parseCookie)(t,"__unshared_uid"),r=(0,cookies_1.parseCookie)(t,"__unshared_uid_at"),i=r?Number(r):NaN,n=Number.isFinite(i)&&Date.now()-i<=sentinel_user_id_1.SENTINEL_STICKINESS_TTL_MS;b=e&&n?e:void 0}if(!b){const e=(0,secure_1.isSecureRequest)(t)?"; Secure":"";return appendSetCookie(s,`__unshared_uid=; Path=/; SameSite=Lax; Max-Age=0${e}`),appendSetCookie(s,`__unshared_uid_at=; Path=/; SameSite=Lax; Max-Age=0${e}`),appendSetCookie(s,`__unshared_sid=; Path=/; SameSite=Lax; Max-Age=0${e}`),appendSetCookie(s,`__unshared_email=; Path=/; SameSite=Lax; Max-Age=0${e}`),interceptForInjection(t,s,m),void o()}const T=resolveEmail(t,i);if(setUserIdCookie(t,s,b),T&&setEmailCookie(t,s,T),!T)return interceptForInjection(t,s,m),void o();const P=extractSessionId(t,a),U=(0,device_id_1.extractDeviceIdOrUndefined)(t,u),O=extractFingerprintId(t),$=t.headers["user-agent"]??"",F=(0,client_ip_1.extractClientIp)(t),j=U??O;if((0,is_bot_1.isBot)($))return void o();const N=p.get(b);function D(){"unknown"!==P&&j&&(h.isPaused()||dispatchUserEvent(e,p,h,f,{userId:b,emailAddress:T,sessionId:P,deviceId:j,fingerprintId:O,userAgent:$,ipAddress:F,eventType:E},l))}N?(p.isStale(b)&&!p.isRefreshing(b)&&(p.markRefreshing(b),fetchAndCacheVerdict(e,p,b,T,j??"unknown",O,P).finally(()=>p.clearRefreshing(b))),N.isFlagged||D(),applyVerdict(N,b,T,t,s,o,m,_)):fetchAndCacheVerdict(e,p,b,T,j??"unknown",O,P).then(e=>{e.isFlagged||D(),applyVerdict(e,b,T,t,s,o,m,_)}).catch(()=>{D(),interceptForInjection(t,s,m),o()})}}function resolveEmail(e,t){if(t)try{const r=t(e);if(r)return r}catch{}const r=(0,cookies_1.parseCookie)(e,"__unshared_email");if(r)return r;const i=e.body?.email;return"string"==typeof i&&i?i:void 0}function applyVerdict(e,t,r,i,n,s,o,d){if(interceptForInjection(i,n,o),e.isFlagged&&!e.isVerified&&d)try{d({userId:t,emailAddress:r,verdict:e,req:i,res:n,next:s})}catch{s()}else s()}function interceptForInjection(e,t,r){delete e.headers["if-none-match"],delete e.headers["if-modified-since"],(0,response_interceptor_1.interceptResponse)(t,(e,t)=>{if(!(0,content_type_1.isHtmlContentType)(t))return null;const i=e.toString("utf8"),n=i.lastIndexOf("</body>");return-1===n?i+r:i.slice(0,n)+r+i.slice(n)},{preventCaching:!0})}function dispatchUserEvent(e,t,r,i,n,s){i.mark(n.userId,n.eventType),e.processUserEvent({eventType:n.eventType,userId:n.userId,emailAddress:n.emailAddress,ipAddress:n.ipAddress,deviceId:n.deviceId,fingerprintId:n.fingerprintId,sessionHash:n.sessionId,userAgent:n.userAgent}).then(e=>{e.success&&e.data?.analysis&&t.update(n.userId,{isFlagged:e.data.analysis.is_user_flagged}),!e.success&&e.error?.retryAfter&&r.pause(1e3*e.error.retryAfter)}).catch(e=>{s&&s(e,{operation:"processUserEvent",userId:n.userId,emailAddress:n.emailAddress})})}async function fetchAndCacheVerdict(e,t,r,i,n,s,o){const d={};let c;n&&"unknown"!==n&&(d.deviceId=n),s&&(d.fingerprintId=s);const a=await Promise.race([e.checkUser(i,d),new Promise(e=>{c=setTimeout(()=>e(null),500)})]);if(clearTimeout(c),!a)return{isFlagged:!1,isVerified:!1,emailAddress:i,sessionId:o,cachedAt:0,ttl:0};const u=a.data?.is_user_flagged??!1;return t.set(r,{isFlagged:u,isVerified:!1,emailAddress:i,sessionId:o}),t.get(r)}function extractSessionId(e,t){if(t)try{const r=t(e);if(r)return r}catch{}return(0,cookies_1.parseCookie)(e,"__unshared_sid")??"unknown"}function extractFingerprintId(e){return(0,cookies_1.parseCookie)(e,"__unshared_fingerprint_id")||void 0}function appendSetCookie(e,t){const r=e.getHeader("Set-Cookie");if(r){const i=Array.isArray(r)?[...r]:[String(r)];i.push(t),e.setHeader("Set-Cookie",i)}else e.setHeader("Set-Cookie",t)}function setUserIdCookie(e,t,r){const i=(0,secure_1.isSecureRequest)(e)?"; Secure":"";appendSetCookie(t,`__unshared_uid=${encodeURIComponent(r)}; Path=/; SameSite=Lax${i}`),appendSetCookie(t,`__unshared_uid_at=${Date.now()}; Path=/; SameSite=Lax${i}`)}function setEmailCookie(e,t,r){const i=(0,secure_1.isSecureRequest)(e)?"; Secure":"";appendSetCookie(t,`__unshared_email=${encodeURIComponent(r)}; HttpOnly; Path=/; SameSite=Lax${i}`)}

package/dist/middleware/injection/fingerprint-script.d.ts

@@ -1,10 +1,16 @@
 /**
- * Generates a small inline loader script that:
- *   1. Loads the real fingerprint SDK from /__unshared/fp.js
- *   2. Collects a full fingerprint (31+ signals, MurmurHash3 Merkle tree)
- *   3. POSTs the result to /__unshared/submit-fp
+ * Generates an inline loader script that:
+ *   1. Loads the fingerprint SDK from /__unshared/fp.js
+ *   2. Collects a fingerprint and POSTs to /__unshared/submit-fp
+ *   3. Caches fingerprint in sessionStorage for reuse on SPA navigations
+ *   4. Patches History API to detect SPA route changes → re-submits fingerprint
+ *   5. Patches fetch/XHR to detect 403 account_flagged → dispatches "unshared:flagged" event
  *
  * The actual SDK UMD bundle is served by the middleware at /__unshared/fp.js.
- * This keeps the injected HTML small (~500 bytes) while using the full library.
+ *
+ * Event contract:
+ *   window.addEventListener("unshared:flagged", (e) => {
+ *     e.detail.email — the flagged user's email (from 403 response body)
+ *   });
  */
 export declare function generateFingerprintScript(routePrefix: string, version?: string): string;

package/dist/middleware/injection/fingerprint-script.js

@@ -1 +1 @@
-"use strict";function generateFingerprintScript(e,n){const t=n?`?v=${escapeJavaScript(n)}`:"";return`<script>\n(function(){\ntry{\nvar pfx="${escapeJavaScript(e)}";\n\n// Session cookie helpers\nfunction getCookie(n){var m=document.cookie.match(new RegExp("(?:^|; )"+n+"=([^;]*)"));return m?decodeURIComponent(m[1]):null}\nfunction setCookie(n,v,d){var e="";if(d){var dt=new Date();dt.setTime(dt.getTime()+d*864e5);e="; expires="+dt.toUTCString()}document.cookie=n+"="+encodeURIComponent(v)+e+"; path=/; SameSite=Lax"}\n\n// UUID helper\nfunction uuid(){return(typeof crypto!=="undefined"&&crypto.randomUUID)?crypto.randomUUID():("xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g,function(c){var r=Math.random()*16|0;return(c==="x"?r:r&0x3|0x8).toString(16)}))}\n\n// Ensure session ID cookie exists\nvar sid=getCookie("__unshared_sid");\nif(!sid){sid=uuid();setCookie("__unshared_sid",sid,365)}\n\n// Persistent device ID (survives across sessions via localStorage)\nvar did="";\ntry{did=localStorage.getItem("__unshared_device_id")||"";if(!did){did=uuid();localStorage.setItem("__unshared_device_id",did)}}catch(e){did=did||uuid()}\n\nvar uid=getCookie("__unshared_uid")||"";\n\n// Collect on every page load if a userId is present\nif(uid){\n  var s=document.createElement("script");\n  s.src=pfx+"/fp.js${t}";\n  s.onload=function(){\n    try{\n      var client=new UnsharedLabsBrowser.UnsharedLabsBrowser({baseUrl:""});\n      client.collect({exclude:["timing","navigatorConnection"]}).then(function(fp){\n        var body={\n          hash:fp.full_hash,\n          stable_hash:fp.fingerprint_id,\n          collected_at:fp.timestamp,\n          is_incognito:fp.isIncognito,\n          components:fp.components,\n          version:fp.version,\n          session_id:sid,\n          user_id:uid\n        };\n        var xhr=new XMLHttpRequest();\n        xhr.open("POST",pfx+"/submit-fp",true);\n        xhr.setRequestHeader("Content-Type","application/json");\n        xhr.setRequestHeader("X-Session-Id",sid);\n        xhr.setRequestHeader("X-Device-Id",did);\n        xhr.send(JSON.stringify(body));\n      });\n    }catch(e){}\n  };\n  document.head.appendChild(s);\n}\n}catch(e){}\n})();\n<\/script>`}function escapeJavaScript(e){return e.replace(/\\/g,"\\\\").replace(/"/g,'\\"').replace(/'/g,"\\'")}Object.defineProperty(exports,"t",{value:!0}),exports.generateFingerprintScript=generateFingerprintScript;
+"use strict";function generateFingerprintScript(e,t){const n=t?`?v=${escapeJavaScript(t)}`:"";return`<script>\n(function(){\ntry{\n// --- Bot drop (defense-in-depth) ---\n// Must be the first statement: we do not want to write cookies, localStorage,\n// session IDs, or any network requests for known-bot traffic. Mirrors the\n// regex in unshared-fingerprint-lib/src/detect/bot.ts and Node middleware\n// utils/is-bot.ts. Keep all three in sync.\nvar BOT_RE=/googlebot|bingbot|slurp|baiduspider|duckduckbot|yandex|sogou|exabot|ia_archiver|curl|wget|python-requests|python-urllib|axios|node-fetch|go-http-client|java\\/|libwww-perl|okhttp|apache-httpclient|http_request|httpie|headlesschrome|phantomjs|puppeteer|playwright|cypress|selenium|webdriver|electron|jsdom|vercel-screenshot|screenshot|prerender|lighthouse|chrome-lighthouse|pagespeed|gtmetrix|pingdom|nessus|nikto|sqlmap|burp|zap|qualys|openvas|nmap|masscan|facebookexternalhit|twitterbot|linkedinbot|whatsapp|telegrambot|slackbot|discordbot|bot|crawl|spider|scrape|fetch|scan/i;\nif(typeof navigator!=="undefined"&&navigator.userAgent&&BOT_RE.test(navigator.userAgent))return;\n\nvar pfx="${escapeJavaScript(e)}";\nvar SS_FP="__unshared_fp";\nvar SS_LAST_SUBMIT="__unshared_last_submit";\n\n// Dedup state: skip submit if (user_id + URL) matches last submission.\n// Modern SPAs (Next.js App Router, React Router, etc.) call replaceState\n// 3-5 times during hydration with the same URL — without this guard,\n// each call generates a redundant FP row with identical stable_hash.\n// Persisted to sessionStorage so hard reloads and framework double-boots\n// inside the same tab still dedupe (the in-memory value resets on reload).\nvar lastSubmitKey="";\ntry{lastSubmitKey=sessionStorage.getItem(SS_LAST_SUBMIT)||""}catch(e){}\n\n// --- Helpers ---\nfunction gC(n){var m=document.cookie.match(new RegExp("(?:^|; )"+n+"=([^;]*)"));return m?decodeURIComponent(m[1]):null}\nfunction sC(n,v,d){var e="";if(d){var dt=new Date();dt.setTime(dt.getTime()+d*864e5);e="; expires="+dt.toUTCString()}document.cookie=n+"="+encodeURIComponent(v)+e+"; path=/; SameSite=Lax"}\nfunction uuid(){return(typeof crypto!=="undefined"&&crypto.randomUUID)?crypto.randomUUID():("xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g,function(c){var r=Math.random()*16|0;return(c==="x"?r:r&0x3|0x8).toString(16)}))}\n// Sentinel user IDs that must never be treated as real users. Mirrors\n// the Set in sentinel-user-id.ts — keep in sync. Empty string is handled\n// by the separate !uid checks below.\nvar SENTINEL_UIDS={"__pre_auth__":1,"anonymous":1,"guest":1,"undefined":1,"null":1};\nfunction isSentinelUid(v){return typeof v==="string"&&SENTINEL_UIDS.hasOwnProperty(v)}\n\n// --- Session + device IDs ---\n// Session ID is a UUID because it's supposed to be tab-scoped and random.\n// Device ID is intentionally NOT a UUID — Issue 9: random UUIDs wrote\n// meaningless device_ids to every fingerprint row. Instead we read the\n// stable fingerprint hash from localStorage if a previous submission\n// already persisted it; otherwise we leave did empty and let submitFP()\n// reconcile on the first successful collection. The Node middleware's\n// Issue 8 bootstrap-skip branch handles the empty-device_id window so we\n// never dispatch with a random or "unknown" value.\nvar sid=gC("__unshared_sid");\nif(!sid){sid=uuid();sC("__unshared_sid",sid,365)}\nvar did="";\ntry{did=localStorage.getItem("__unshared_device_id")||""}catch(e){}\nif(did){sC("__unshared_fp_id",did,365)}\n\n// --- Fingerprint cache (sessionStorage) ---\nfunction getFP(){try{var r=sessionStorage.getItem(SS_FP);return r?JSON.parse(r):null}catch(e){return null}}\nfunction setFP(fp){try{sessionStorage.setItem(SS_FP,JSON.stringify(fp))}catch(e){}}\n\n// --- Submit fingerprint to backend ---\nfunction submitFP(fp){\n  var uid=gC("__unshared_uid");\n  if(!uid||isSentinelUid(uid))return;\n  // Issue 9: reconcile device_id to the stable fingerprint hash. This runs\n  // before we send the X-Device-Id header so the very first submission\n  // already carries the real value. Persist to localStorage so other tabs\n  // (and future reloads) pick up the same stable ID without needing to\n  // re-collect the fingerprint.\n  if(fp.fingerprint_id){\n    did=fp.fingerprint_id;\n    try{localStorage.setItem("__unshared_device_id",did)}catch(e){}\n    sC("__unshared_fp_id",did,365);\n  }\n  // event_type is the SPA route, not a fixed enum. Page-level event names\n  // (page_load/route_change) collapsed every row into one of two buckets;\n  // the URL is more useful for analytics and matches the frontend SDK.\n  var route=(location.pathname||"/")+(location.search||"");\n  var key=uid+"|"+route;\n  if(key===lastSubmitKey)return;\n  lastSubmitKey=key;\n  try{sessionStorage.setItem(SS_LAST_SUBMIT,key)}catch(e){}\n  // collected_at is stamped fresh at submit time rather than carried from fp.timestamp,\n  // because fp is cached per-tab in sessionStorage — reusing its original timestamp would\n  // freeze collected_at at first load and drift against server created_at as the tab ages.\n  // The server authoritatively overwrites this value again on ingress.\n  var body={hash:fp.full_hash,stable_hash:fp.fingerprint_id,collected_at:(new Date()).toISOString(),is_incognito:fp.isIncognito,components:fp.components,version:fp.version,session_id:sid,user_id:uid,event_type:route};\n  // Deterministic idempotency key: (stable_hash, user_id, event_type) fully\n  // identifies one logical submission. A stable key lets the backend's\n  // ON CONFLICT (idempotency_key) DO NOTHING actually catch duplicates across\n  // reloads, tabs, and concurrent SDK instances — a fresh UUID could not.\n  var idem=fp.fingerprint_id+"|"+uid+"|"+route;\n  var xhr=new XMLHttpRequest();\n  xhr.open("POST",pfx+"/submit-fp",true);\n  xhr.setRequestHeader("Content-Type","application/json");\n  xhr.setRequestHeader("X-Session-Id",sid);\n  if(did)xhr.setRequestHeader("X-Device-Id",did);\n  xhr.setRequestHeader("X-Idempotency-Key",idem);\n  xhr.send(JSON.stringify(body));\n}\n\n// --- Collect fingerprint (loads fp.js if needed) then submit ---\nvar fpReady=false;\nfunction collectAndSubmit(){\n  var uid=gC("__unshared_uid");\n  if(!uid||isSentinelUid(uid))return;\n  var cached=getFP();\n  if(cached){submitFP(cached);return}\n  if(!fpReady)return;\n  try{\n    var c=new UnsharedBrowser.UnsharedBrowser({baseUrl:""});\n    c.collect({exclude:["timing","speech"]}).then(function(fp){setFP(fp);submitFP(fp)});\n  }catch(e){}\n}\n\n// --- Load fp.js (always — browser caches it for 1h) ---\n// Submit cached FP immediately if available; load fp.js for fresh collection\nvar pageLoadSubmitted=false;\nvar _boot_uid=gC("__unshared_uid");\nif(getFP()&&_boot_uid&&!isSentinelUid(_boot_uid)){submitFP(getFP());pageLoadSubmitted=true;deferredCheck()}\nvar s=document.createElement("script");\ns.src=pfx+"/fp.js${n}";\ns.onload=function(){fpReady=true;if(!pageLoadSubmitted){collectAndSubmit();deferredCheck()}};\ndocument.head.appendChild(s);\n\n// --- Deferred verdict check ---\n// After fingerprint submission, the backend processes the event async.\n// If the user was just flagged, the initial page load may have beaten\n// the verdict update. Re-check after a delay so newly flagged sessions\n// get caught without waiting for user interaction.\n// The endpoint always returns 200 so browsers don't log a scary red\n// network error — we inspect the body and dispatch the flagged event\n// ourselves when status==="flagged".\nfunction deferredCheck(){\n  var uid=gC("__unshared_uid");\n  if(!uid||isSentinelUid(uid))return;\n  setTimeout(function(){\n    try{fetch(pfx+"/status",{method:"GET",credentials:"same-origin"}).then(function(r){return r.json()}).then(function(b){if(b&&b.status==="flagged")emitFlagged(b)}).catch(function(){})}catch(e){}\n  },500);\n}\n\n// --- SPA route change tracking (History API + popstate) ---\nvar oPush=history.pushState,oReplace=history.replaceState;\nhistory.pushState=function(){oPush.apply(this,arguments);try{collectAndSubmit()}catch(e){}};\nhistory.replaceState=function(){oReplace.apply(this,arguments);try{collectAndSubmit()}catch(e){}};\nwindow.addEventListener("popstate",function(){try{collectAndSubmit()}catch(e){}});\n\n// --- 403 interception: dispatch "unshared:flagged" event ---\nfunction emitFlagged(body){\n  try{window.dispatchEvent(new CustomEvent("unshared:flagged",{detail:{email:body.email||""}}))}catch(e){}\n}\n\n// Patch fetch\nvar oFetch=window.fetch;\nif(oFetch){window.fetch=function(){return oFetch.apply(this,arguments).then(function(r){if(r.status===403){try{var cl=r.clone();cl.json().then(function(b){if(b&&b.error==="account_flagged")emitFlagged(b)}).catch(function(){})}catch(e){}}return r})}}\n\n// Patch XMLHttpRequest\nvar oXSend=XMLHttpRequest.prototype.send;\nXMLHttpRequest.prototype.send=function(){var x=this;x.addEventListener("load",function(){if(x.status===403){try{var b=JSON.parse(x.responseText);if(b&&b.error==="account_flagged")emitFlagged(b)}catch(e){}}});return oXSend.apply(this,arguments)};\n\n}catch(e){}\n})();\n<\/script>`}function escapeJavaScript(e){return e.replace(/\\/g,"\\\\").replace(/"/g,'\\"').replace(/'/g,"\\'")}Object.defineProperty(exports,"t",{value:!0}),exports.generateFingerprintScript=generateFingerprintScript;

package/dist/middleware/response-interceptor.d.ts

@@ -1,13 +1,15 @@
-import type { Response } from 'express';
+import type { UnsharedResponse } from '../types';
 /**
  * Intercepts the response body by wrapping res.write() and res.end().
  *
- * Collects all chunks written to the response. When res.end() is called,
- * invokes the `transform` callback with the complete body buffer and the
- * Content-Type header. The transform can return modified content or null
- * to pass through unchanged.
+ * Only buffers HTML responses (text/html). Non-HTML responses (JSON, images,
+ * CSS, JS, etc.) pass through to the original write/end without buffering,
+ * avoiding unnecessary memory usage on large payloads.
  *
- * Does NOT monkey-patch res.send — uses the lower-level write/end API
- * as required by the spec.
+ * When res.end() is called on an HTML response, invokes the `transform`
+ * callback with the complete body buffer and the Content-Type header.
+ * The transform can return modified content or null to pass through unchanged.
  */
-export declare function interceptResponse(res: Response, transform: (body: Buffer, contentType: string | undefined) => Buffer | string | null): void;
+export declare function interceptResponse(res: UnsharedResponse, transform: (body: Buffer, contentType: string | undefined) => Buffer | string | null, options?: {
+    preventCaching?: boolean;
+}): void;

package/dist/middleware/response-interceptor.js

@@ -1 +1 @@
-"use strict";function interceptResponse(t,n){const e=[],f=t.write.bind(t),u=t.end.bind(t);let o=!1;t.write=function(t,n,f){if(null!=t){const f=Buffer.isBuffer(t)?t:Buffer.from(t,"string"==typeof n?n:"utf8");e.push(f)}return"function"==typeof n&&n(null),"function"==typeof f&&f(null),!0},t.end=function(r,c,s){if(o)return t;if(o=!0,null!=r){const t=Buffer.isBuffer(r)?r:Buffer.from(r,"string"==typeof c?c:"utf8");e.push(t)}const l=Buffer.concat(e),i=t.getHeader("content-type");let p;try{p=n(l,i)}catch{p=null}if(null!=p){const n=Buffer.isBuffer(p)?p:Buffer.from(p,"utf8");t.setHeader("Content-Length",n.length),t.removeHeader("Content-Encoding"),f(n)}else l.length>0&&f(l);const y="function"==typeof c?c:s;return y?u(y):u(),t}}Object.defineProperty(exports,"t",{value:!0}),exports.interceptResponse=interceptResponse;
+"use strict";function interceptResponse(t,n,e){const f=e?.preventCaching??!1,o=t.write.bind(t),u=t.end.bind(t),r=t.writeHead.bind(t),c=[];let i=!1,l=null;function s(){if(null!==l)return;const n=t.getHeader("content-type");null!=n&&(l=String(n).includes("text/html"),l||function(){t.write=o,t.end=u;for(const t of c)o(t);c.length=0}())}t.writeHead=function(n,...e){return s(),f&&l&&(t.setHeader("Cache-Control","no-store"),t.removeHeader("ETag"),t.removeHeader("Last-Modified")),r(n,...e)},t.write=function(t,n,e){if(s(),!1===l)return o(t,n,e);if(null!=t){const e=Buffer.isBuffer(t)?t:Buffer.from(t,"string"==typeof n?n:"utf8");c.push(e)}return"function"==typeof n&&n(null),"function"==typeof e&&e(null),!0},t.end=function(e,f,r){if(i)return t;if(i=!0,s(),!1===l)return u(e,f,r);if(null!=e){const t=Buffer.isBuffer(e)?e:Buffer.from(e,"string"==typeof f?f:"utf8");c.push(t)}const p=Buffer.concat(c),y=t.getHeader("content-type");let B;try{B=n(p,y)}catch{B=null}if(null!=B){const n=Buffer.isBuffer(B)?B:Buffer.from(B,"utf8");t.setHeader("Content-Length",n.length),t.removeHeader("Content-Encoding"),o(n)}else p.length>0&&o(p);const g="function"==typeof f?f:r;return g?u(g):u(),t}}Object.defineProperty(exports,"t",{value:!0}),exports.interceptResponse=interceptResponse;

package/dist/middleware/routes/submit-fp.d.ts

@@ -1,15 +1,22 @@
-import type { Request, Response } from 'express';
-import type { UnsharedLabsClient } from '../../client';
+import type { UnsharedRequest, UnsharedResponse } from '../../types';
+import type { UnsharedClient } from '../../client';
 import type { VerdictCache } from '../verdict-cache';
 import type { RateLimitBackoff } from '../rate-limit-backoff';
-export interface SubmitFingerprintDependencies {
-    client: UnsharedLabsClient;
+import type { DispatchDedupe } from '../dispatch-dedupe';
+export interface SubmitFingerprintDependencies<TReq extends UnsharedRequest = UnsharedRequest> {
+    client: UnsharedClient;
     verdictCache: VerdictCache;
     rateLimitBackoff: RateLimitBackoff;
-    resolveUserId?: (req: Request) => string | undefined;
-    resolveEmailAddress?: (req: Request) => string | undefined;
-    resolveSessionId?: (req: Request) => string | undefined;
-    resolveDeviceId?: (req: Request) => string | undefined;
+    dispatchDedupe: DispatchDedupe;
+    resolveUserId?: (req: TReq) => string | undefined;
+    resolveEmailAddress?: (req: TReq) => string | undefined;
+    resolveSessionId?: (req: TReq) => string | undefined;
+    resolveDeviceId?: (req: TReq) => string | undefined;
+    onError?: (error: unknown, context: {
+        operation: 'processUserEvent' | 'submitFingerprintEvent' | 'checkUser' | 'verifyTrigger' | 'verify';
+        userId?: string;
+        emailAddress?: string;
+    }) => void;
 }
 /**
  * Handles POST /__unshared/submit-fp
@@ -21,4 +28,4 @@ export interface SubmitFingerprintDependencies {
  *
  * Always returns 200 (fire-and-forget from browser's perspective).
  */
-export declare function handleSubmitFingerprint(dependencies: SubmitFingerprintDependencies): (req: Request, res: Response) => Promise<void>;
+export declare function handleSubmitFingerprint<TReq extends UnsharedRequest = UnsharedRequest>(dependencies: SubmitFingerprintDependencies<TReq>): (req: TReq, res: UnsharedResponse) => Promise<void>;

package/dist/middleware/routes/submit-fp.js

@@ -1 +1 @@
-"use strict";function handleSubmitFingerprint(e){return async(n,t)=>{try{const i=n.body??{},o={full_hash:i.hash??"",fingerprint_id:i.stable_hash??"",timestamp:i.collected_at??(new Date).toISOString(),isIncognito:i.is_incognito??!1,components:i.components??{},version:i.version??"inline-1.0.0"};let s,r,a;try{s=e.resolveUserId?e.resolveUserId(n):void 0}catch{}s=s??i.user_id??void 0;try{r=e.resolveEmailAddress?e.resolveEmailAddress(n):void 0}catch{}r=r??parseCookie(n,"__unshared_email")??i.email??void 0;try{a=e.resolveSessionId?e.resolveSessionId(n):void 0}catch{}a=a??i.session_id??parseCookie(n,"__unshared_sid");const c=n.ip??"",d=n.headers["user-agent"]??"",u=extractDeviceId(n,e.resolveDeviceId),_=o.fingerprint_id||void 0,p=[];if(_&&!parseCookie(n,"__unshared_fingerprint_id")&&p.push(`__unshared_fingerprint_id=${encodeURIComponent(_)}; HttpOnly; Path=/; SameSite=Lax`),r&&!parseCookie(n,"__unshared_email")&&p.push(`__unshared_email=${encodeURIComponent(r)}; HttpOnly; Path=/; SameSite=Lax`),p.length>0){const e=t.getHeader("Set-Cookie");if(e){const n=Array.isArray(e)?[...e]:[String(e)];n.push(...p),t.setHeader("Set-Cookie",n)}else t.setHeader("Set-Cookie",p)}s&&e.client.submitFingerprintEvent(o,{userId:s,sessionHash:a,eventType:"auto_collect",ipAddress:c}).catch(()=>{}),s&&r&&!e.rateLimitBackoff.isPaused()&&e.client.processUserEvent({eventType:"auto_collect",userId:s,emailAddress:r,ipAddress:c,deviceId:u,fingerprintId:_,sessionHash:a??"unknown",userAgent:d}).then(n=>{n.success&&n.data?.analysis&&e.verdictCache.update(s,{isFlagged:n.data.analysis.is_user_flagged}),!n.success&&n.error?.retryAfter&&e.rateLimitBackoff.pause(1e3*n.error.retryAfter)}).catch(()=>{}),t.status(200).json({success:!0})}catch{t.status(200).json({success:!0})}}}function extractDeviceId(e,n){if(n)try{const t=n(e);if(t)return t}catch{}const t=parseCookie(e,"__unshared_fp_id");if(t)return t;const i=e.headers["x-device-id"];return"string"==typeof i&&i?i:"unknown"}function parseCookie(e,n){const t=e.headers.cookie;if(!t)return;const i=t.match(new RegExp(`(?:^|; )${n}=([^;]*)`));return i?decodeURIComponent(i[1]):void 0}Object.defineProperty(exports,"t",{value:!0}),exports.handleSubmitFingerprint=handleSubmitFingerprint;
+"use strict";Object.defineProperty(exports,"i",{value:!0}),exports.handleSubmitFingerprint=handleSubmitFingerprint;const is_bot_1=require("../utils/is-bot"),client_ip_1=require("../utils/client-ip"),cookies_1=require("../utils/cookies"),device_id_1=require("../utils/device-id"),secure_1=require("../utils/secure"),sentinel_user_id_1=require("../utils/sentinel-user-id"),http_helpers_1=require("../utils/http-helpers");function handleSubmitFingerprint(e){return async(i,s)=>{try{const t=i.body??{},n={full_hash:t.hash??"",fingerprint_id:t.stable_hash??"",timestamp:t.collected_at??(new Date).toISOString(),isIncognito:t.is_incognito??!1,components:t.components??{},version:t.version??"inline-1.0.0"};let r,o,_;try{const s=e.resolveUserId?e.resolveUserId(i):void 0;s&&!(0,sentinel_user_id_1.isSentinelUserId)(s)&&(r=s)}catch{}if(!r){const e="string"==typeof t.user_id?t.user_id:void 0;e&&!(0,sentinel_user_id_1.isSentinelUserId)(e)&&(r=e)}if(!r){const e=(0,cookies_1.parseCookie)(i,"__unshared_uid");e&&!(0,sentinel_user_id_1.isSentinelUserId)(e)&&(r=e)}try{o=e.resolveEmailAddress?e.resolveEmailAddress(i):void 0}catch{}o=o??(0,cookies_1.parseCookie)(i,"__unshared_email")??t.email??void 0;try{_=e.resolveSessionId?e.resolveSessionId(i):void 0}catch{}_=_??t.session_id??(0,cookies_1.parseCookie)(i,"__unshared_sid");const d=(0,client_ip_1.extractClientIp)(i),c=i.headers["user-agent"]??"";if((0,is_bot_1.isBot)(c))return void(0,http_helpers_1.sendJson)(s,200,{success:!0});const u=(n.fingerprint_id&&n.fingerprint_id.length>0?n.fingerprint_id:void 0)??(0,device_id_1.extractDeviceId)(i,e.resolveDeviceId),a=n.fingerprint_id||void 0,p=n.full_hash||void 0,l=(0,secure_1.isSecureRequest)(i)?"; Secure":"",h=[];if(p&&!(0,cookies_1.parseCookie)(i,"__unshared_fingerprint_id")&&h.push(`__unshared_fingerprint_id=${encodeURIComponent(p)}; HttpOnly; Path=/; SameSite=Lax${l}`),a){const e=(0,cookies_1.parseCookie)(i,"__unshared_fp_id");e&&e===a||h.push(`__unshared_fp_id=${encodeURIComponent(a)}; Path=/; SameSite=Lax; Max-Age=31536000${l}`)}if(o&&!(0,cookies_1.parseCookie)(i,"__unshared_email")&&h.push(`__unshared_email=${encodeURIComponent(o)}; HttpOnly; Path=/; SameSite=Lax${l}`),h.length>0){const e=s.getHeader("Set-Cookie");if(e){const i=Array.isArray(e)?[...e]:[String(e)];i.push(...h),s.setHeader("Set-Cookie",i)}else s.setHeader("Set-Cookie",h)}let f;if("string"==typeof t.event_type&&t.event_type)f=t.event_type;else{const e=i.headers.referer??i.headers.referrer;let s="unknown";if("string"==typeof e&&e.length>0)try{const i=new URL(e);s=(i.pathname||"/")+(i.search||"")}catch{}f=s}const v=i.headers["x-idempotency-key"],m="string"==typeof v&&v.length>0?v:void 0,g=Date.now(),y=m?`${m}|${g}`:a&&r?`${a}|${r}|${f}|${g}`:void 0;if(r&&e.client.submitFingerprintEvent(n,{userId:r,emailAddress:o,sessionHash:_,eventType:f,ipAddress:d,userAgent:c,idempotencyKey:y}).catch(i=>{e.onError&&e.onError(i,{operation:"submitFingerprintEvent",userId:r,emailAddress:o})}),r&&o&&!e.rateLimitBackoff.isPaused()&&!e.dispatchDedupe.wasRecentlyDispatched(r,f))try{const i=await e.client.processUserEvent({eventType:f,userId:r,emailAddress:o,ipAddress:d,deviceId:u,fingerprintId:a,sessionHash:_??"unknown",userAgent:c});i.success&&i.data?.analysis&&e.verdictCache.update(r,{isFlagged:i.data.analysis.is_user_flagged}),!i.success&&i.error?.retryAfter&&e.rateLimitBackoff.pause(1e3*i.error.retryAfter)}catch(i){e.onError&&e.onError(i,{operation:"processUserEvent",userId:r,emailAddress:o})}(0,http_helpers_1.sendJson)(s,200,{success:!0})}catch{(0,http_helpers_1.sendJson)(s,200,{success:!0})}}}

package/dist/middleware/routes/verify.d.ts

@@ -1,11 +1,16 @@
-import type { Request, Response } from 'express';
-import type { UnsharedLabsClient } from '../../client';
+import type { UnsharedRequest, UnsharedResponse } from '../../types';
+import type { UnsharedClient } from '../../client';
 import type { VerdictCache } from '../verdict-cache';
-export interface VerificationDependencies {
-    client: UnsharedLabsClient;
+export interface VerificationDependencies<TReq extends UnsharedRequest = UnsharedRequest> {
+    client: UnsharedClient;
     verdictCache: VerdictCache;
-    resolveEmailAddress?: (req: Request) => string | undefined;
-    resolveDeviceId?: (req: Request) => string | undefined;
+    resolveEmailAddress?: (req: TReq) => string | undefined;
+    resolveDeviceId?: (req: TReq) => string | undefined;
+    onError?: (error: unknown, context: {
+        operation: 'processUserEvent' | 'submitFingerprintEvent' | 'checkUser' | 'verifyTrigger' | 'verify';
+        userId?: string;
+        emailAddress?: string;
+    }) => void;
 }
 /**
  * POST /__unshared/verify-trigger
@@ -15,7 +20,7 @@ export interface VerificationDependencies {
  *
  * The deviceId is resolved via extractDeviceId (same as the middleware).
  */
-export declare function handleVerifyTrigger(dependencies: VerificationDependencies): (req: Request, res: Response) => Promise<void>;
+export declare function handleVerifyTrigger<TReq extends UnsharedRequest = UnsharedRequest>(dependencies: VerificationDependencies<TReq>): (req: TReq, res: UnsharedResponse) => Promise<void>;
 /**
  * POST /__unshared/verify
  * Validates OTP code. Called by the blocker overlay UI.
@@ -25,4 +30,4 @@ export declare function handleVerifyTrigger(dependencies: VerificationDependenci
  * On successful verification, updates the verdict cache to mark
  * the user as verified so subsequent requests pass through.
  */
-export declare function handleVerify(dependencies: VerificationDependencies): (req: Request, res: Response) => Promise<void>;
+export declare function handleVerify<TReq extends UnsharedRequest = UnsharedRequest>(dependencies: VerificationDependencies<TReq>): (req: TReq, res: UnsharedResponse) => Promise<void>;

package/dist/middleware/routes/verify.js

@@ -1 +1 @@
-"use strict";function handleVerifyTrigger(e){return async(r,i)=>{try{const s=resolveEmail(r,r.body??{},e.resolveEmailAddress);if(!s)return void i.status(400).json({success:!1,error:{code:"VALIDATION_ERROR",message:"Email is required"}});const t=extractDeviceId(r,e.resolveDeviceId),n=parseCookie(r,"__unshared_fingerprint_id")||void 0,o=await e.client.triggerEmailVerification(s,t,{fingerprintId:n});o.success?i.status(200).json({success:!0,data:o.data}):i.status(200).json({success:!1,error:o.error??{code:"TRIGGER_FAILED",message:"Failed to send verification email"}})}catch{i.status(200).json({success:!1,error:{code:"INTERNAL_ERROR",message:"Failed to trigger verification"}})}}}function handleVerify(e){return async(r,i)=>{try{const s=r.body??{},t=resolveEmail(r,s,e.resolveEmailAddress),n=s.code;if(!t||!n)return void i.status(400).json({success:!1,error:{code:"VALIDATION_ERROR",message:"Email and code are required"}});const o=extractDeviceId(r,e.resolveDeviceId),c=parseCookie(r,"__unshared_fingerprint_id")||void 0,a=await e.client.verify(t,o,n,{fingerprintId:c});if(a.success){const s=parseCookie(r,"__unshared_uid");s&&e.verdictCache.update(s,{isVerified:!0}),i.status(200).json({success:!0,data:{verified:!0}})}else i.status(200).json({success:!1,error:a.error??{code:"VERIFICATION_FAILED",message:"Verification failed"}})}catch{i.status(200).json({success:!1,error:{code:"INTERNAL_ERROR",message:"Verification failed"}})}}}function resolveEmail(e,r,i){if(i)try{const r=i(e);if(r)return r}catch{}const s=parseCookie(e,"__unshared_email");if(s)return s;const t=r.email;return"string"==typeof t&&t?t:void 0}function extractDeviceId(e,r){if(r)try{const i=r(e);if(i)return i}catch{}const i=parseCookie(e,"__unshared_fp_id");if(i)return i;const s=e.headers["x-device-id"];return"string"==typeof s&&s?s:"unknown"}function parseCookie(e,r){const i=e.headers.cookie;if(!i)return;const s=i.match(new RegExp(`(?:^|; )${r}=([^;]*)`));return s?decodeURIComponent(s[1]):void 0}Object.defineProperty(exports,"i",{value:!0}),exports.handleVerifyTrigger=handleVerifyTrigger,exports.handleVerify=handleVerify;
+"use strict";Object.defineProperty(exports,"i",{value:!0}),exports.handleVerifyTrigger=handleVerifyTrigger,exports.handleVerify=handleVerify;const cookies_1=require("../utils/cookies"),device_id_1=require("../utils/device-id"),http_helpers_1=require("../utils/http-helpers");function handleVerifyTrigger(e){return async(r,i)=>{try{const s=resolveEmail(r,r.body??{},e.resolveEmailAddress);if(!s)return void(0,http_helpers_1.sendJson)(i,400,{success:!1,error:{code:"VALIDATION_ERROR",message:"Email is required"}});const t=(0,device_id_1.extractDeviceId)(r,e.resolveDeviceId),o=(0,cookies_1.parseCookie)(r,"__unshared_fingerprint_id")||void 0,c=await e.client.triggerEmailVerification(s,t,{fingerprintId:o});c.success?(0,http_helpers_1.sendJson)(i,200,{success:!0,data:c.data}):(0,http_helpers_1.sendJson)(i,200,{success:!1,error:c.error??{code:"TRIGGER_FAILED",message:"Failed to send verification email"}})}catch(r){e.onError&&e.onError(r,{operation:"verifyTrigger"}),(0,http_helpers_1.sendJson)(i,200,{success:!1,error:{code:"INTERNAL_ERROR",message:"Failed to trigger verification"}})}}}function handleVerify(e){return async(r,i)=>{try{const s=r.body??{},t=resolveEmail(r,s,e.resolveEmailAddress),o=s.code;if(!t||!o)return void(0,http_helpers_1.sendJson)(i,400,{success:!1,error:{code:"VALIDATION_ERROR",message:"Email and code are required"}});const c=(0,device_id_1.extractDeviceId)(r,e.resolveDeviceId),_=(0,cookies_1.parseCookie)(r,"__unshared_fingerprint_id")||void 0,n=await e.client.verify(t,c,o,{fingerprintId:_});if(n.success){const s=(0,cookies_1.parseCookie)(r,"__unshared_uid");s&&e.verdictCache.update(s,{isVerified:!0}),(0,http_helpers_1.sendJson)(i,200,{success:!0,data:{verified:!0}})}else(0,http_helpers_1.sendJson)(i,200,{success:!1,error:n.error??{code:"VERIFICATION_FAILED",message:"Verification failed"}})}catch(r){e.onError&&e.onError(r,{operation:"verify"}),(0,http_helpers_1.sendJson)(i,200,{success:!1,error:{code:"INTERNAL_ERROR",message:"Verification failed"}})}}}function resolveEmail(e,r,i){if(i)try{const r=i(e);if(r)return r}catch{}const s=(0,cookies_1.parseCookie)(e,"__unshared_email");if(s)return s;const t=r.email;return"string"==typeof t&&t?t:void 0}

package/dist/middleware/utils/client-ip.d.ts

@@ -0,0 +1,6 @@
+import type { UnsharedRequest } from '../../types';
+/**
+ * Extract the real client IP from proxy headers, falling back to req.ip or socket address.
+ * Checked in order: CF-Connecting-IP (Cloudflare) → X-Real-IP (nginx/ALB) → req.ip → socket.
+ */
+export declare function extractClientIp(req: UnsharedRequest): string;

package/dist/middleware/utils/client-ip.js

@@ -0,0 +1 @@
+"use strict";function extractClientIp(t){const e=t.headers["cf-connecting-ip"];if("string"==typeof e&&e)return e;const r=t.headers["x-real-ip"];return"string"==typeof r&&r?r:t.ip??t.socket?.remoteAddress??""}Object.defineProperty(exports,"t",{value:!0}),exports.extractClientIp=extractClientIp;

package/dist/middleware/utils/cookies.d.ts

@@ -0,0 +1,6 @@
+import type { UnsharedRequest } from '../../types';
+/**
+ * Reads a single cookie value from the raw Cookie header.
+ * Works without cookie-parser middleware.
+ */
+export declare function parseCookie(req: UnsharedRequest, name: string): string | undefined;

package/dist/middleware/utils/cookies.js

@@ -0,0 +1 @@
+"use strict";function parseCookie(e,o){const t=e.headers.cookie;if(!t)return;const n=t.match(new RegExp(`(?:^|; )${o}=([^;]*)`));return n?decodeURIComponent(n[1]):void 0}Object.defineProperty(exports,"o",{value:!0}),exports.parseCookie=parseCookie;

package/dist/middleware/utils/device-id.d.ts

@@ -0,0 +1,19 @@
+import type { UnsharedRequest } from '../../types';
+/**
+ * Resolves device ID from: custom resolver → X-Device-Id header → __unshared_fp_id cookie.
+ *
+ * Returns the literal string `"unknown"` when no source provides a value.
+ * Callers that can tolerate a tri-state should use `extractDeviceIdOrUndefined`
+ * instead — the "unknown" sentinel polluted 19% of FP rows in production
+ * because it was being dispatched as-if-real during the first request of a
+ * session, before the inline script had a chance to set `__unshared_fp_id`.
+ * Kept for API compatibility.
+ */
+export declare function extractDeviceId<TReq extends UnsharedRequest = UnsharedRequest>(req: TReq, resolveDeviceId?: (req: TReq) => string | undefined): string;
+/**
+ * Resolves device ID from: custom resolver → X-Device-Id header → __unshared_fp_id cookie.
+ * Returns `undefined` when nothing is available. Use this at any call site
+ * that can take a "skip dispatch" branch during the bootstrap window, so we
+ * stop writing `device_id="unknown"` rows to the analytics table on first request.
+ */
+export declare function extractDeviceIdOrUndefined<TReq extends UnsharedRequest = UnsharedRequest>(req: TReq, resolveDeviceId?: (req: TReq) => string | undefined): string | undefined;

package/dist/middleware/utils/device-id.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.extractDeviceId=extractDeviceId,exports.extractDeviceIdOrUndefined=extractDeviceIdOrUndefined;const cookies_1=require("./cookies");function extractDeviceId(e,t){return extractDeviceIdOrUndefined(e,t)??"unknown"}function extractDeviceIdOrUndefined(e,t){if(t)try{const r=t(e);if(r)return r}catch{}const r=e.headers["x-device-id"];if("string"==typeof r&&r)return r;return(0,cookies_1.parseCookie)(e,"__unshared_fp_id")||void 0}