unshared-clientjs-sdk 2.2.1 → 3.0.0-rc.14

package/dist/esm/middleware/rate-limit-backoff.d.mts

@@ -1,14 +1,17 @@
-/**
- * Global rate-limit backoff for processUserEvent calls.
- *
- * When the Unshared API returns 429 with a Retry-After header,
- * the middleware pauses processUserEvent calls for the specified duration.
- * checkUser calls are not affected — enforcement takes priority.
- */
 export declare class RateLimitBackoff {
     private _resumeAtTimestamp;
-    /** Pause processUserEvent calls for the given duration. */
+    private _failureResumeAtTimestamp;
+    private _consecutiveFailures;
+    /** Pause processUserEvent calls (server-directed 429), clamped to MAX_BACKOFF_MS. */
     pause(durationMs: number): void;
+    /** Record a network/5xx/timeout failure; engage failure backoff at the threshold. */
+    noteFailure(): void;
+    /** Record a success; resets the failure streak and lifts ONLY the failure-streak
+     *  pause. It deliberately does NOT touch a server-directed 429 pause (pause()),
+     *  so a success on one request can't wipe another request's legitimate 429 backoff. */
+    noteSuccess(): void;
     /** Returns true if processUserEvent calls should be skipped. */
     isPaused(): boolean;
+    /** Parse a Retry-After header value (delta-seconds OR HTTP-date) into ms, or null. */
+    static parseRetryAfter(headerValue: string | null, now?: number): number | null;
 }

package/dist/esm/middleware/rate-limit-backoff.mjs

@@ -1 +1 @@
-export class RateLimitBackoff{constructor(){this.t=0}pause(t){const s=Date.now()+t;s>this.t&&(this.t=s)}isPaused(){return Date.now()<this.t}}
+const MAX_BACKOFF_MS=3e5,FAILURE_THRESHOLD=3,FAILURE_BACKOFF_MS=1e4;export class RateLimitBackoff{constructor(){this.t=0,this.i=0,this.h=0}pause(t){const s=Math.min(Math.max(0,t),3e5),e=Date.now()+s;e>this.t&&(this.t=e)}noteFailure(){if(this.h++,this.h>=3){const t=Date.now()+1e4;t>this.i&&(this.i=t)}}noteSuccess(){this.h=0,this.i=0}isPaused(){const t=Date.now();return t<this.t||t<this.i}static parseRetryAfter(t,s=Date.now()){if(null==t)return null;const e=parseInt(t,10);if(!isNaN(e)&&String(e)===t.trim())return 1e3*e;const i=Date.parse(t);return isNaN(i)?null:Math.max(0,i-s)}}

package/dist/esm/middleware/response-interceptor.d.mts

@@ -1,4 +1,4 @@
-import type { UnsharedResponse } from '../types';
+import type { UnsharedResponse } from '../types.mjs';
 /**
  * Intercepts the response body by wrapping res.write() and res.end().
  *
@@ -19,4 +19,5 @@ import type { UnsharedResponse } from '../types';
  */
 export declare function interceptResponse(res: UnsharedResponse, transform: (body: Buffer, contentType: string | undefined) => Buffer | string | null, options?: {
     preventCaching?: boolean;
+    streamingIdleMs?: number;
 }): void;

package/dist/esm/middleware/response-interceptor.mjs

@@ -1 +1 @@
-const MAX_INJECT_BYTES=2e6;function findWriteHeadHeaders(e){return e.find(e=>e&&"object"==typeof e)}function readHeaderFromWriteHeadArgs(e,t){const n=findWriteHeadHeaders(e);if(!n)return;const r=t.toLowerCase();if(Array.isArray(n)){if(n.length&&Array.isArray(n[0])){for(const e of n)if(String(e[0]).toLowerCase()===r)return e[1]}else for(let e=0;e+1<n.length;e+=2)if(String(n[e]).toLowerCase()===r)return n[e+1]}else for(const e of Object.keys(n))if(e.toLowerCase()===r)return n[e]}function deleteHeaderFromWriteHeadArgs(e,t){const n=findWriteHeadHeaders(e);if(!n)return;const r=t.toLowerCase();if(Array.isArray(n))if(n.length&&Array.isArray(n[0]))for(let e=n.length-1;e>=0;e--)String(n[e][0]).toLowerCase()===r&&n.splice(e,1);else for(let e=n.length-2;e>=0;e-=2)String(n[e]).toLowerCase()===r&&n.splice(e,2);else for(const e of Object.keys(n))e.toLowerCase()===r&&delete n[e]}export function interceptResponse(e,t,n){const r=n?.preventCaching??!1,o=e.write.bind(e),f=e.end.bind(e),i=e.writeHead.bind(e),c=[];let u=0,l=!1,s=null;function d(){e.write=o,e.end=f;for(const e of c)o(e);c.length=0}function a(e,t){null===s&&null!=e&&(s=String(e).includes("text/html"),s&&t&&(s=!1),!1===s&&d())}function g(){a(e.getHeader("content-type"),e.getHeader("content-encoding"))}e.writeHead=function(t,...n){return a(readHeaderFromWriteHeadArgs(n,"content-type")??e.getHeader("content-type"),readHeaderFromWriteHeadArgs(n,"content-encoding")??e.getHeader("content-encoding")),s&&(r&&(e.setHeader("Cache-Control","no-store"),e.removeHeader("ETag"),e.removeHeader("Last-Modified")),e.removeHeader("Content-Length"),deleteHeaderFromWriteHeadArgs(n,"content-length")),i(t,...n)},e.write=function(e,t,n){if(g(),!1===s)return o(e,t,n);if(null!=e){const r=Buffer.isBuffer(e)?e:Buffer.from(e,"string"==typeof t?t:"utf8");if(u+=r.length,c.push(r),u>2e6)return d(),"function"==typeof t&&t(null),"function"==typeof n&&n(null),!0}return"function"==typeof t&&t(null),"function"==typeof n&&n(null),!0},e.end=function(n,r,i){if(l)return e;if(l=!0,g(),!1===s)return f(n,r,i);if(null!=n){const e=Buffer.isBuffer(n)?n:Buffer.from(n,"string"==typeof r?r:"utf8");u+=e.length,c.push(e)}if(u>2e6){d();const e="function"==typeof r?r:i;return e?f(e):f()}const a=Buffer.concat(c),y=e.getHeader("content-type");let p;try{p=t(a,y)}catch{p=null}if(null!=p){const t=Buffer.isBuffer(p)?p:Buffer.from(p,"utf8");e.headersSent||(e.setHeader("Content-Length",t.length),e.removeHeader("Content-Encoding")),o(t)}else a.length>0&&o(a);const H="function"==typeof r?r:i;return H?f(H):f(),e}}
+const MAX_INJECT_BYTES=2e6;function findWriteHeadHeaders(e){return e.find(e=>e&&"object"==typeof e)}function readHeaderFromWriteHeadArgs(e,t){const n=findWriteHeadHeaders(e);if(!n)return;const r=t.toLowerCase();if(Array.isArray(n)){if(n.length&&Array.isArray(n[0])){for(const e of n)if(String(e[0]).toLowerCase()===r)return e[1]}else for(let e=0;e+1<n.length;e+=2)if(String(n[e]).toLowerCase()===r)return n[e+1]}else for(const e of Object.keys(n))if(e.toLowerCase()===r)return n[e]}function deleteHeaderFromWriteHeadArgs(e,t){const n=findWriteHeadHeaders(e);if(!n)return;const r=t.toLowerCase();if(Array.isArray(n))if(n.length&&Array.isArray(n[0]))for(let e=n.length-1;e>=0;e--)String(n[e][0]).toLowerCase()===r&&n.splice(e,1);else for(let e=n.length-2;e>=0;e-=2)String(n[e]).toLowerCase()===r&&n.splice(e,2);else for(const e of Object.keys(n))e.toLowerCase()===r&&delete n[e]}export function interceptResponse(e,t,n){const r=n?.preventCaching??!1,o=n?.streamingIdleMs??50,f=e.write.bind(e),i=e.end.bind(e),u=e.writeHead.bind(e),c=[];let l=0,d=!1,s=null,a=null;function g(){s&&(clearTimeout(s),s=null),e.write=f,e.end=i;for(const e of c)f(e);c.length=0}function H(e,t){null===a&&null!=e&&(a=String(e).includes("text/html"),a&&t&&(a=!1),!1===a&&g())}function y(){H(e.getHeader("content-type"),e.getHeader("content-encoding"))}e.writeHead=function(t,...n){return H(readHeaderFromWriteHeadArgs(n,"content-type")??e.getHeader("content-type"),readHeaderFromWriteHeadArgs(n,"content-encoding")??e.getHeader("content-encoding")),a&&(r&&(e.setHeader("Cache-Control","no-store"),e.removeHeader("ETag"),e.removeHeader("Last-Modified"),deleteHeaderFromWriteHeadArgs(n,"cache-control"),deleteHeaderFromWriteHeadArgs(n,"etag"),deleteHeaderFromWriteHeadArgs(n,"last-modified")),e.removeHeader("Content-Length"),deleteHeaderFromWriteHeadArgs(n,"content-length")),u(t,...n)},e.write=function(e,t,n){if(y(),!1===a)return f(e,t,n);if(null!=e){const r=Buffer.isBuffer(e)?e:Buffer.from(e,"string"==typeof t?t:"utf8");if(l+=r.length,c.push(r),l>2e6)return g(),"function"==typeof t&&t(null),"function"==typeof n&&n(null),!0;s||d||(s=setTimeout(()=>{d||g()},o),"function"==typeof s.unref&&s.unref())}return"function"==typeof t&&t(null),"function"==typeof n&&n(null),!0},e.end=function(n,r,o){if(d)return e;if(d=!0,s&&(clearTimeout(s),s=null),y(),!1===a)return i(n,r,o);if(null!=n){const e=Buffer.isBuffer(n)?n:Buffer.from(n,"string"==typeof r?r:"utf8");l+=e.length,c.push(e)}if(l>2e6){g();const e="function"==typeof r?r:o;return e?i(e):i()}const u=Buffer.concat(c),H=e.getHeader("content-type");let p;try{p=t(u,H)}catch{p=null}if(null!=p){const t=Buffer.isBuffer(p)?p:Buffer.from(p,"utf8");e.headersSent||(e.setHeader("Content-Length",t.length),e.removeHeader("Content-Encoding")),f(t)}else u.length>0&&f(u);const m="function"==typeof r?r:o;return m?i(m):i(),e}}

package/dist/esm/middleware/routes/interstitial.d.mts

@@ -1,5 +1,5 @@
-import type { UnsharedRequest, UnsharedResponse } from '../../types';
-import type { UnsharedClient } from '../../client';
+import type { UnsharedRequest, UnsharedResponse } from '../../types.mjs';
+import type { UnsharedClient } from '../../client.mjs';
 export interface InterstitialDependencies {
     client: UnsharedClient;
 }

package/dist/esm/middleware/routes/interstitial.mjs

@@ -1 +1 @@
-import{sendJson}from"../utils/http-helpers";function isPublishedFlow(s){return!!s&&"object"==typeof s&&Object.keys(s).length>0}const FLOW_NOT_PUBLISHED={code:"FLOW_NOT_PUBLISHED",message:"No interstitial flow is published for this company."};export function handleGetInterstitialFlow(s){return async(e,o)=>{try{const t=e.url&&e.url.includes("?")?e.url.slice(e.url.indexOf("?")+1):"",r=new URLSearchParams(t),n=r.get("flow_type")||void 0,i=r.get("platform")||void 0,a=await s.client.getInterstitialFlow({flowType:n,platform:i});a.success?isPublishedFlow(a.data)?sendJson(o,200,{success:!0,data:a.data}):sendJson(o,200,{success:!1,error:{...FLOW_NOT_PUBLISHED}}):404===a.status?sendJson(o,200,{success:!1,error:{...FLOW_NOT_PUBLISHED}}):sendJson(o,200,{success:!1,error:a.error??{code:"FLOW_FETCH_FAILED",message:"Failed to load interstitial flow"}})}catch{sendJson(o,200,{success:!1,error:{code:"INTERNAL_ERROR",message:"Failed to load interstitial flow"}})}}}
+import{sendJson}from"../utils/http-helpers.mjs";function isPublishedFlow(s){return!!s&&"object"==typeof s&&Object.keys(s).length>0}const FLOW_NOT_PUBLISHED={code:"FLOW_NOT_PUBLISHED",message:"No interstitial flow is published for this company."};export function handleGetInterstitialFlow(s){return async(e,o)=>{try{const t=e.url&&e.url.includes("?")?e.url.slice(e.url.indexOf("?")+1):"",r=new URLSearchParams(t),n=r.get("flow_type")||void 0,i=r.get("platform")||void 0,a=await s.client.getInterstitialFlow({flowType:n,platform:i});a.success?isPublishedFlow(a.data)?sendJson(o,200,{success:!0,data:a.data}):sendJson(o,200,{success:!1,error:{...FLOW_NOT_PUBLISHED}}):404===a.status?sendJson(o,200,{success:!1,error:{...FLOW_NOT_PUBLISHED}}):sendJson(o,200,{success:!1,error:a.error??{code:"FLOW_FETCH_FAILED",message:"Failed to load interstitial flow"}})}catch{sendJson(o,200,{success:!1,error:{code:"INTERNAL_ERROR",message:"Failed to load interstitial flow"}})}}}

package/dist/esm/middleware/routes/submit-fp.d.mts

@@ -1,8 +1,8 @@
-import type { UnsharedRequest, UnsharedResponse } from '../../types';
-import type { UnsharedClient } from '../../client';
-import type { VerdictCache } from '../verdict-cache';
-import type { RateLimitBackoff } from '../rate-limit-backoff';
-import type { DispatchDedupe } from '../dispatch-dedupe';
+import type { UnsharedRequest, UnsharedResponse } from '../../types.mjs';
+import type { UnsharedClient } from '../../client.mjs';
+import type { VerdictCache } from '../verdict-cache.mjs';
+import type { RateLimitBackoff } from '../rate-limit-backoff.mjs';
+import type { DispatchDedupe } from '../dispatch-dedupe.mjs';
 export interface SubmitFingerprintDependencies<TReq extends UnsharedRequest = UnsharedRequest> {
     client: UnsharedClient;
     verdictCache: VerdictCache;

package/dist/esm/middleware/routes/submit-fp.mjs

@@ -1 +1 @@
-import{sha256Hex}from"../../util";import{isBot}from"../utils/is-bot";import{extractClientIp}from"../utils/client-ip";import{parseCookie}from"../utils/cookies";import{extractDeviceId}from"../utils/device-id";import{isSecureRequest}from"../utils/secure";import{isSentinelUserId}from"../utils/sentinel-user-id";import{sendJson}from"../utils/http-helpers";export function handleSubmitFingerprint(e){return async(i,t)=>{try{const s=i.body??{},n={full_hash:s.hash??"",fingerprint_id:s.stable_hash??"",timestamp:s.collected_at??(new Date).toISOString(),isIncognito:s.is_incognito??!1,components:s.components??{},version:s.version??"inline-1.0.0",..."remote"===s.source||"bundled"===s.source?{source:s.source}:{}};let o,r,d;try{const t=e.resolveUserId?e.resolveUserId(i):void 0;t&&!isSentinelUserId(t)&&(o=t)}catch{}if(!o){const e="string"==typeof s.user_id?s.user_id:void 0;e&&!isSentinelUserId(e)&&(o=e)}if(!o){const e=parseCookie(i,"__unshared_uid");e&&!isSentinelUserId(e)&&(o=e)}try{r=e.resolveEmailAddress?e.resolveEmailAddress(i):void 0}catch{}r=r??parseCookie(i,"__unshared_email")??s.email??void 0;try{d=e.resolveSessionId?e.resolveSessionId(i):void 0}catch{}d=d??s.session_id??parseCookie(i,"__unshared_sid");const a=extractClientIp(i),c=i.headers["user-agent"]??"";if(!e.disableBotFilter&&isBot(c))return void sendJson(t,200,{success:!0});const p=(n.fingerprint_id&&n.fingerprint_id.length>0?n.fingerprint_id:void 0)??extractDeviceId(i,e.resolveDeviceId),u=n.fingerprint_id||void 0,l=n.full_hash||void 0,m=isSecureRequest(i)?"; Secure":"",_=[];if(l&&!parseCookie(i,"__unshared_fingerprint_id")&&_.push(`__unshared_fingerprint_id=${encodeURIComponent(l)}; HttpOnly; Path=/; SameSite=Lax${m}`),u){const e=parseCookie(i,"__unshared_fp_id");e&&e===u||_.push(`__unshared_fp_id=${encodeURIComponent(u)}; Path=/; SameSite=Lax; Max-Age=31536000${m}`)}if(r&&!parseCookie(i,"__unshared_email")&&_.push(`__unshared_email=${encodeURIComponent(r)}; HttpOnly; Path=/; SameSite=Lax${m}`),_.length>0){const e=t.getHeader("Set-Cookie");if(e){const i=Array.isArray(e)?[...e]:[String(e)];i.push(..._),t.setHeader("Set-Cookie",i)}else t.setHeader("Set-Cookie",_)}let f;if("string"==typeof s.event_type&&s.event_type)f=s.event_type;else{const e=i.headers.referer??i.headers.referrer;let t="unknown";if("string"==typeof e&&e.length>0)try{const i=new URL(e);t=(i.pathname||"/")+(i.search||"")}catch{}f=t}const h=i.headers["x-idempotency-key"],v="string"==typeof h&&h.length>0?h:void 0,g=Date.now(),y=v?`${v}|${g}`:u&&o?`${sha256Hex(`${u}|${o}|${f}`)}|${g}`:void 0;if(o&&e.client.submitFingerprintEvent(n,{userId:o,emailAddress:r,sessionHash:d,eventType:f,ipAddress:a,userAgent:c,idempotencyKey:y}).catch(i=>{e.onError&&e.onError(i,{operation:"submitFingerprintEvent",userId:o,emailAddress:r})}),o&&r&&!e.rateLimitBackoff.isPaused()&&!e.dispatchDedupe.wasRecentlyDispatched(o,f))try{const i=await e.client.processUserEvent({eventType:f,userId:o,emailAddress:r,ipAddress:a,deviceId:p,fingerprintId:u,sessionHash:d??"unknown",userAgent:c});i.success&&i.data?.analysis&&e.verdictCache.update(o,{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:o,emailAddress:r})}sendJson(t,200,{success:!0})}catch(i){e.onError&&e.onError(i,{operation:"submitFingerprintEvent"}),sendJson(t,200,{success:!0})}}}
+import{sha256Hex}from"../../util.mjs";import{isBot}from"../utils/is-bot.mjs";import{extractClientIp}from"../utils/client-ip.mjs";import{parseCookie}from"../utils/cookies.mjs";import{extractDeviceId}from"../utils/device-id.mjs";import{isSecureRequest}from"../utils/secure.mjs";import{isSentinelUserId}from"../utils/sentinel-user-id.mjs";import{sendJson}from"../utils/http-helpers.mjs";import{resolveOrCreatePermanentDeviceId}from"../utils/permanent-device-id.mjs";import{runCheckUser,SUBMIT_FP_TIMEOUT_MS}from"../dispatch-processing.mjs";function asRecord(e){return null===e||"object"!=typeof e||Array.isArray(e)?{}:e}export function handleSubmitFingerprint(e){return async(t,i)=>{try{const s=asRecord(t.body),r=asRecord(s.fingerprint??s),o=asRecord(s.context),n=asRecord(o.identity),a=asRecord(o.identifiers),d=asRecord(o.event),c={...r,full_hash:r.hash??r.full_hash??"",fingerprint_id:r.stableHash??r.stable_hash??r.fingerprint_id??"",timestamp:r.timestamp??r.collected_at??(new Date).toISOString(),isIncognito:r.isIncognito??r.is_incognito??!1,components:r.components??{},version:r.version??"unknown",..."remote"===r.source||"bundled"===r.source?{source:r.source}:{}};let p,m,u;try{const i=e.resolveUserId?e.resolveUserId(t):void 0;i&&!isSentinelUserId(i)&&(p=i)}catch{}if(!p){const e="string"==typeof n.user_id?n.user_id:"string"==typeof s.user_id?s.user_id:void 0;e&&!isSentinelUserId(e)&&(p=e)}if(!p){const e=parseCookie(t,"__unshared_uid");e&&!isSentinelUserId(e)&&(p=e)}try{m=e.resolveEmailAddress?e.resolveEmailAddress(t):void 0}catch{}m=m??parseCookie(t,"__unshared_email")??n.email_address??s.email??void 0;try{u=e.resolveSessionId?e.resolveSessionId(t):void 0}catch{}u=u??a.session_hash??s.session_id??parseCookie(t,"__unshared_sid");const f=extractClientIp(t),_=t.headers["user-agent"]??"";if(!e.disableBotFilter&&isBot(_))return void sendJson(i,200,{success:!0,data:{skipped:!0}});const l=(c.fingerprint_id&&c.fingerprint_id.length>0?c.fingerprint_id:void 0)??extractDeviceId(t,e.resolveDeviceId),h=c.fingerprint_id||void 0,y=c.full_hash||void 0,g=resolveOrCreatePermanentDeviceId(t,a.unshared_device_id??s.permanent_device_id),v=isSecureRequest(t)?"; Secure":"",S=[];S.push(`__unshared_device_id=${encodeURIComponent(g.id)}; Path=/; SameSite=Lax; Max-Age=34560000${v}`);const I=parseCookie(t,"__unshared_fingerprint_id")||y;if(I&&S.push(`__unshared_fingerprint_id=${encodeURIComponent(I)}; HttpOnly; Path=/; SameSite=Lax; Max-Age=31536000${v}`),h&&S.push(`__unshared_fp_id=${encodeURIComponent(h)}; Path=/; SameSite=Lax; Max-Age=31536000${v}`),m&&S.push(`__unshared_email=${encodeURIComponent(m)}; HttpOnly; Path=/; SameSite=Lax; Max-Age=31536000${v}`),S.length>0){const e=i.getHeader("Set-Cookie");if(e){const t=Array.isArray(e)?[...e]:[String(e)];t.push(...S),i.setHeader("Set-Cookie",t)}else i.setHeader("Set-Cookie",S)}let j;if("string"==typeof d.type&&d.type)j=d.type;else if("string"==typeof s.event_type&&s.event_type)j=s.event_type;else{const e=t.headers.referer??t.headers.referrer;let i="unknown";if("string"==typeof e&&e.length>0)try{const t=new URL(e);i=(t.pathname||"/")+(t.search||"")}catch{}j=i}const C=t.headers["x-idempotency-key"],x="string"==typeof C&&C.length>0?C:void 0,R=Date.now(),k=x?`${x}|${R}`:h&&p?`${sha256Hex(`${h}|${p}|${j}`)}|${R}`:void 0,b={...a,unshared_device_id:g.id,...l?{device_id:l}:{},...h?{stable_hash:h}:{},...y?{full_hash:y}:{},...u?{session_hash:u}:{}},U="string"==typeof asRecord(o.sdk).name?asRecord(o.sdk).name:void 0,$="string"==typeof U&&U.startsWith("unshared-")&&Object.prototype.hasOwnProperty.call(s,"fingerprint")&&s.context&&"object"==typeof s.context&&!Array.isArray(s.context)&&o.identity&&"object"==typeof o.identity&&!Array.isArray(o.identity)&&o.identifiers&&"object"==typeof o.identifiers&&!Array.isArray(o.identifiers)&&o.event&&"object"==typeof o.event&&!Array.isArray(o.event),A=!Object.prototype.hasOwnProperty.call(s,"context")&&"string"==typeof s.hash&&"string"==typeof s.stable_hash&&"string"==typeof s.collected_at&&s.components&&"object"==typeof s.components&&!Array.isArray(s.components),M=$||A?{...s,fingerprint:r,context:{...o,sdk:asRecord(o.sdk),identity:{...n,...p?{user_id:p}:{},...m?{email_address:m}:{}},identifiers:b,event:{...d,type:j,ip_address:f,user_agent:_}}}:s,O=await e.client.submitFingerprint(M,{idempotencyKey:k});O.success||e.onError?.(O.error,{operation:"submitFingerprintEvent",userId:p,emailAddress:m}),p&&m&&!e.rateLimitBackoff.isPaused()&&!e.dispatchDedupe.wasRecentlyDispatched(p,j)&&await runCheckUser({client:e.client,cache:e.verdictCache,backoff:e.rateLimitBackoff,onError:e.onError},{user_id:p,email_address:m,identifiers:b},p,m,SUBMIT_FP_TIMEOUT_MS),O.success?sendJson(i,200,{success:!0,data:O.data}):sendJson(i,200,{success:!1,error:O.error})}catch(t){e.onError&&e.onError(t,{operation:"submitFingerprintEvent"}),sendJson(i,200,{success:!0,data:{accepted:!1}})}}}

package/dist/esm/middleware/routes/verify.d.mts

@@ -1,6 +1,6 @@
-import type { UnsharedRequest, UnsharedResponse } from '../../types';
-import type { UnsharedClient } from '../../client';
-import type { VerdictCache } from '../verdict-cache';
+import type { UnsharedRequest, UnsharedResponse } from '../../types.mjs';
+import type { UnsharedClient } from '../../client.mjs';
+import type { VerdictCache } from '../verdict-cache.mjs';
 export interface VerificationDependencies<TReq extends UnsharedRequest = UnsharedRequest> {
     client: UnsharedClient;
     verdictCache: VerdictCache;

package/dist/esm/middleware/routes/verify.mjs

@@ -1 +1 @@
-import{parseCookie}from"../utils/cookies";import{extractDeviceId}from"../utils/device-id";import{sendJson}from"../utils/http-helpers";export function handleVerifyTrigger(e){return async(r,i)=>{try{const s=resolveEmail(r,r.body??{},e.resolveEmailAddress);if(!s)return void sendJson(i,400,{success:!1,error:{code:"VALIDATION_ERROR",message:"Email is required"}});const o=extractDeviceId(r,e.resolveDeviceId),n=parseCookie(r,"__unshared_fingerprint_id")||void 0,t=await e.client.triggerEmailVerification(s,o,{fingerprintId:n});t.success?sendJson(i,200,{success:!0,data:t.data}):sendJson(i,200,{success:!1,error:t.error??{code:"TRIGGER_FAILED",message:"Failed to send verification email"}})}catch(r){e.onError&&e.onError(r,{operation:"verifyTrigger"}),sendJson(i,200,{success:!1,error:{code:"INTERNAL_ERROR",message:"Failed to trigger verification"}})}}}export function handleVerify(e){return async(r,i)=>{try{const s=r.body??{},o=resolveEmail(r,s,e.resolveEmailAddress),n=s.code;if(!o||!n)return void sendJson(i,400,{success:!1,error:{code:"VALIDATION_ERROR",message:"Email and code are required"}});const t=extractDeviceId(r,e.resolveDeviceId),c=parseCookie(r,"__unshared_fingerprint_id")||void 0,a=await e.client.verify(o,t,n,{fingerprintId:c});if(a.success){let s;try{s=e.resolveUserId?.(r)}catch{}s&&e.verdictCache.update(s,{isVerified:!0}),sendJson(i,200,{success:!0,data:{verified:!0}})}else sendJson(i,200,{success:!1,error:a.error??{code:"VERIFICATION_FAILED",message:"Verification failed"}})}catch(r){e.onError&&e.onError(r,{operation:"verify"}),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=parseCookie(e,"__unshared_email");if(s)return s;const o=r.email;return"string"==typeof o&&o?o:void 0}
+import{parseCookie}from"../utils/cookies.mjs";import{extractDeviceId}from"../utils/device-id.mjs";import{sendJson}from"../utils/http-helpers.mjs";import{extractPermanentDeviceId}from"../utils/permanent-device-id.mjs";import{isSecureRequest}from"../utils/secure.mjs";const VERIFICATION_COOKIE="__unshared_verification_id";function appendCookie(e,i){const s=e.getHeader("Set-Cookie"),r=s?Array.isArray(s)?[...s]:[String(s)]:[];r.push(i),e.setHeader("Set-Cookie",r)}export function handleVerifyTrigger(e){return async(i,s)=>{try{const r=resolveEmail(i,i.body??{},e.resolveEmailAddress);if(!r)return void sendJson(s,400,{success:!1,error:{code:"VALIDATION_ERROR",message:"Email is required"}});const o=extractDeviceId(i,e.resolveDeviceId),t=parseCookie(i,"__unshared_fp_id")||void 0,n=parseCookie(i,"__unshared_fingerprint_id")||void 0,a=extractPermanentDeviceId(i),c=await e.client.triggerEmailVerification(r,o,{fingerprintId:t,fullHash:n,permanentDeviceId:a});if(c.success){if(c.data?.verification_id){const e=isSecureRequest(i)?"; Secure":"";appendCookie(s,`${VERIFICATION_COOKIE}=${encodeURIComponent(c.data.verification_id)}; HttpOnly; Path=/; SameSite=Lax; Max-Age=600${e}`)}sendJson(s,200,{success:!0,data:c.data})}else sendJson(s,200,{success:!1,error:c.error??{code:"TRIGGER_FAILED",message:"Failed to send verification email"}})}catch(i){e.onError&&e.onError(i,{operation:"verifyTrigger"}),sendJson(s,200,{success:!1,error:{code:"INTERNAL_ERROR",message:"Failed to trigger verification"}})}}}export function handleVerify(e){return async(i,s)=>{try{const r=(i.body??{}).code,o=parseCookie(i,VERIFICATION_COOKIE);if(!o||!r)return void sendJson(s,400,{success:!1,error:{code:"VALIDATION_ERROR",message:"Verification ID and code are required"}});const t=await e.client.verifyEmail({verification_id:o,code:r});if(t.success&&t.data?.verified){let r,o=!1;try{r=e.resolveUserId?.(i)}catch{}const n=resolveEmail(i,{},e.resolveEmailAddress),a=extractDeviceId(i,e.resolveDeviceId),c=parseCookie(i,"__unshared_fp_id")||void 0,d=parseCookie(i,"__unshared_fingerprint_id")||void 0,u=extractPermanentDeviceId(i);if(r&&n){const i={...a?{device_id:a}:{},...c?{stable_hash:c}:{},...d?{full_hash:d}:{},...u?{unshared_device_id:u}:{}},s=await e.client.checkUser({user_id:r,email_address:n,identifiers:i},{maxRetries:0});s.success&&s.data&&!s.failedOpen&&!s.data.is_user_flagged&&(e.verdictCache.update(r,{isVerified:!0}),o=!0)}const f=isSecureRequest(i)?"; Secure":"";appendCookie(s,`${VERIFICATION_COOKIE}=; HttpOnly; Path=/; SameSite=Lax; Max-Age=0${f}`),o&&s.setHeader("X-Unshared-Enforcement-Reconciled","clean"),sendJson(s,200,{success:!0,data:t.data})}else t.success?sendJson(s,200,{success:!0,data:t.data}):sendJson(s,200,{success:!1,error:t.error??{code:"VERIFICATION_FAILED",message:"Verification failed"}})}catch(i){e.onError&&e.onError(i,{operation:"verify"}),sendJson(s,200,{success:!1,error:{code:"INTERNAL_ERROR",message:"Verification failed"}})}}}function resolveEmail(e,i,s){if(s)try{const i=s(e);if(i)return i}catch{}const r=parseCookie(e,"__unshared_email");if(r)return r;const o=i.email;return"string"==typeof o&&o?o:void 0}

package/dist/esm/middleware/utils/client-ip.d.mts

@@ -1,4 +1,4 @@
-import type { UnsharedRequest } from '../../types';
+import type { UnsharedRequest } from '../../types.mjs';
 /**
  * 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.

package/dist/esm/middleware/utils/cookies.d.mts

@@ -1,4 +1,4 @@
-import type { UnsharedRequest } from '../../types';
+import type { UnsharedRequest } from '../../types.mjs';
 /**
  * Reads a single cookie value from the raw Cookie header.
  * Works without cookie-parser middleware.

package/dist/esm/middleware/utils/device-id.d.mts

@@ -1,4 +1,4 @@
-import type { UnsharedRequest } from '../../types';
+import type { UnsharedRequest } from '../../types.mjs';
 /**
  * Resolves device ID from: custom resolver → X-Device-Id header → __unshared_fp_id cookie.
  *

package/dist/esm/middleware/utils/device-id.mjs

@@ -1 +1 @@
-import{parseCookie}from"./cookies";export function extractDeviceId(e,r){return extractDeviceIdOrUndefined(e,r)??"unknown"}export function extractDeviceIdOrUndefined(e,r){if(r)try{const t=r(e);if(t)return t}catch{}const t=e.headers["x-device-id"];if("string"==typeof t&&t)return t;return parseCookie(e,"__unshared_fp_id")||void 0}
+import{parseCookie}from"./cookies.mjs";export function extractDeviceId(e,r){return extractDeviceIdOrUndefined(e,r)??"unknown"}export function extractDeviceIdOrUndefined(e,r){if(r)try{const t=r(e);if(t)return t}catch{}const t=e.headers["x-device-id"];if("string"==typeof t&&t)return t;return parseCookie(e,"__unshared_fp_id")||void 0}

package/dist/esm/middleware/utils/flagged-response.mjs

@@ -1 +1 @@
-import{maskEmail}from"./mask-email";export const ACCOUNT_FLAGGED_ERROR="account_flagged";export function flaggedResponse(a){return{error:"account_flagged",email:maskEmail(a)}}
+import{maskEmail}from"./mask-email.mjs";export const ACCOUNT_FLAGGED_ERROR="account_flagged";export function flaggedResponse(a){return{error:"account_flagged",email:maskEmail(a)}}

package/dist/esm/middleware/utils/http-helpers.d.mts

@@ -1,4 +1,4 @@
-import type { UnsharedResponse } from '../../types';
+import type { UnsharedResponse } from '../../types.mjs';
 /**
  * Send a JSON response. Framework-agnostic replacement for Express's
  * `res.status(code).json(data)`.

package/dist/esm/middleware/utils/permanent-device-id.d.mts

@@ -0,0 +1,7 @@
+import type { UnsharedRequest } from '../../types.mjs';
+export declare function isPermanentDeviceId(value: unknown): value is string;
+export declare function extractPermanentDeviceId(req: UnsharedRequest): string | undefined;
+export declare function resolveOrCreatePermanentDeviceId(req: UnsharedRequest, candidate?: unknown): {
+    id: string;
+    shouldSetCookie: boolean;
+};

package/dist/esm/middleware/utils/permanent-device-id.mjs

@@ -0,0 +1 @@
+import{randomUUID}from"crypto";import{parseCookie}from"./cookies.mjs";const PERMANENT_DEVICE_ID_PATTERN=/^upid_[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;export function isPermanentDeviceId(e){return"string"==typeof e&&PERMANENT_DEVICE_ID_PATTERN.test(e)}export function extractPermanentDeviceId(e){const i=parseCookie(e,"__unshared_device_id");if(isPermanentDeviceId(i))return i;const r=e.headers["x-permanent-device-id"];return isPermanentDeviceId(r)?r:void 0}export function resolveOrCreatePermanentDeviceId(e,i){const r=parseCookie(e,"__unshared_device_id");if(isPermanentDeviceId(r))return{id:r,shouldSetCookie:!1};const n=e.headers["x-permanent-device-id"];return{id:isPermanentDeviceId(n)?n:isPermanentDeviceId(i)?i:`upid_${randomUUID()}`,shouldSetCookie:!0}}

package/dist/esm/middleware/utils/read-json-body.d.mts

@@ -0,0 +1,3 @@
+import type { UnsharedRequest, UnsharedResponse } from '../../types.mjs';
+/** Only call for SDK-owned routes, never for application requests. */
+export declare function readJsonBody(req: UnsharedRequest, res: UnsharedResponse): Promise<boolean>;

package/dist/esm/middleware/utils/read-json-body.mjs

@@ -0,0 +1 @@
+import{sendJson}from"./http-helpers.mjs";const MAX_REQUEST_BYTES=1<<20;export async function readJsonBody(e,t){const o=e,r=(e,r,s)=>{if(!o.destroyed&&!o.readableEnded&&o.resume&&o.once&&o.removeListener&&o.destroy){const e=setTimeout(()=>o.destroy(),3e4);e.unref();const t=()=>{clearTimeout(e),o.removeListener("end",t),o.removeListener("close",t),o.removeListener("error",t)};o.once("end",t),o.once("close",t),o.once("error",t),o.resume()}return sendJson(t,e,{success:!1,error:{code:r,message:s}}),!1},s=()=>r(413,"REQUEST_TOO_LARGE","Request body exceeds 1 MiB");if(void 0!==e.body)try{return!(Buffer.byteLength(JSON.stringify(e.body),"utf8")>1048576)||s()}catch{return r(400,"INVALID_JSON","Request body is not valid JSON.")}return o.on&&o.removeListener&&o.pause?o.destroyed||o.readableEnded?r(400,"INVALID_JSON","Request body is unavailable or incomplete."):Number(e.headers["content-length"])>1048576?s():e.headers["content-encoding"]&&"identity"!==e.headers["content-encoding"]?r(415,"UNSUPPORTED_ENCODING","Request body must use identity encoding."):new Promise(t=>{const s=[];let d=0,n=!1;const u=(e,d,u)=>{n||(n=!0,clearTimeout(N),o.removeListener("data",a),o.removeListener("end",c),o.removeListener("aborted",i),o.removeListener("error",i),o.removeListener("close",i),s.length=0,t(!e||r(e,d,u)))},i=()=>u(400,"INVALID_JSON","Request body is unavailable or incomplete."),a=e=>{const t=Buffer.isBuffer(e)?e:Buffer.from(e,"utf8");d+=t.length,d>1048576?u(413,"REQUEST_TOO_LARGE","Request body exceeds 1 MiB"):s.push(t)},c=()=>{try{e.body=JSON.parse(Buffer.concat(s,d).toString("utf8"))}catch{return void u(400,"INVALID_JSON","Request body is not valid JSON.")}u()},N=setTimeout(()=>u(408,"REQUEST_TIMEOUT","Timed out reading request body."),3e4);N.unref(),o.on("data",a),o.on("end",c),o.on("aborted",i),o.on("error",i),o.on("close",i)}):r(400,"BODY_PARSER_MISSING","Provide a readable Node request stream or a parsed JSON body.")}

package/dist/esm/middleware/utils/secure.d.mts

@@ -1,3 +1,3 @@
-import type { UnsharedRequest } from '../../types';
+import type { UnsharedRequest } from '../../types.mjs';
 /** Returns true if the request arrived over HTTPS (direct or via reverse proxy). */
 export declare function isSecureRequest(req: UnsharedRequest): boolean;

package/dist/esm/middleware/utils/skip-paths.d.mts

@@ -1,5 +1,9 @@
 /**
  * Returns true if the request path looks like a static asset and should be
  * skipped by the middleware (no fingerprint injection, no verdict checks).
+ *
+ * Content-bearing extensions (pdf/txt/xml/media) are only skipped when no
+ * enforcement mode is active — otherwise a flagged user could pull protected
+ * downloads/media straight through a `blockFlagged`/`flaggedMode` gate.
  */
-export declare function shouldSkipPath(path: string, customSkipPaths?: string[]): boolean;
+export declare function shouldSkipPath(path: string, customSkipPaths?: string[], enforcementActive?: boolean): boolean;

package/dist/esm/middleware/utils/skip-paths.mjs

@@ -1 +1 @@
-const STATIC_EXTENSIONS=new Set([".js",".mjs",".cjs",".css",".map",".png",".jpg",".jpeg",".gif",".svg",".ico",".webp",".avif",".woff",".woff2",".ttf",".otf",".eot",".mp3",".mp4",".webm",".ogg",".wasm",".xml",".txt",".pdf"]),STATIC_PATH_PREFIXES=["/static/","/assets/","/public/","/_next/","/__vite/","/favicon"];export function shouldSkipPath(t,f){if(f)for(const o of f)if(t.startsWith(o))return!0;const o=t.lastIndexOf(".");if(-1!==o){const f=t.slice(o).toLowerCase().split("?")[0];if(STATIC_EXTENSIONS.has(f))return!0}for(const f of STATIC_PATH_PREFIXES)if(t.startsWith(f))return!0;return!1}
+const STATIC_ASSET_EXTENSIONS=new Set([".js",".mjs",".cjs",".css",".map",".png",".jpg",".jpeg",".gif",".svg",".ico",".webp",".avif",".woff",".woff2",".ttf",".otf",".eot",".wasm"]),CONTENT_EXTENSIONS=new Set([".mp3",".mp4",".webm",".ogg",".xml",".txt",".pdf"]),STATIC_PATH_PREFIXES=["/static/","/assets/","/public/","/_next/","/__vite/","/favicon"];export function shouldSkipPath(t,f,S=!1){if(f)for(const S of f)if(t.startsWith(S))return!0;const T=t.lastIndexOf(".");if(-1!==T){const f=t.slice(T).toLowerCase().split("?")[0];if(STATIC_ASSET_EXTENSIONS.has(f))return!0;if(!S&&CONTENT_EXTENSIONS.has(f))return!0}for(const f of STATIC_PATH_PREFIXES)if(t.startsWith(f))return!0;return!1}

package/dist/esm/middleware/verdict-cache.d.mts

@@ -13,6 +13,7 @@ export declare class VerdictCache {
     private readonly _maxSize;
     private _sweepTimer;
     constructor(defaultTTL?: number, maxSize?: number);
+    private _ensureSweepTimer;
     get(userId: string): Verdict | undefined;
     set(userId: string, verdict: Omit<Verdict, 'cachedAt' | 'ttl'>, ttl?: number): void;
     /**
@@ -42,6 +43,12 @@ export declare class VerdictCache {
     destroy(): void;
     /** Remove all entries that are past their TTL + a 2x grace period. */
     private _sweep;
-    /** Evict the oldest entry by cachedAt to make room. */
+    /**
+     * Evict the oldest entry by last WRITE (set/update) — O(1). Map preserves
+     * insertion order, and both set() and update() re-append an existing key on
+     * write, so the first key in iteration order is the least-recently-written.
+     * Reads (get/isStale/isRefreshing) don't refresh recency — this is LRU-by-write,
+     * not LRU-by-read.
+     */
     private _evictOldest;
 }

package/dist/esm/middleware/verdict-cache.mjs

@@ -1 +1 @@
-const DEFAULT_TTL_MS=6e4,DEFAULT_MAX_SIZE=1e4,SWEEP_INTERVAL_MS=3e5;export class VerdictCache{constructor(t=6e4,s=1e4){this.t=new Map,this.i=new Set,this.h=null,this.l=t,this.o=s,this.h=setInterval(()=>this.u(),3e5),this.h&&"function"==typeof this.h.unref&&this.h.unref()}get(t){return this.t.get(t)}set(t,s,i){!this.t.has(t)&&this.t.size>=this.o&&this._(),this.t.set(t,{...s,cachedAt:Date.now(),ttl:i??this.l})}update(t,s){const i=this.t.get(t);i?(void 0!==s.isFlagged&&(i.isFlagged=s.isFlagged),void 0!==s.isVerified&&(i.isVerified=s.isVerified),i.cachedAt=Date.now()):(this.t.size>=this.o&&this._(),this.t.set(t,{isFlagged:s.isFlagged??!1,isVerified:s.isVerified??!1,emailAddress:"",sessionId:"",cachedAt:Date.now(),ttl:this.l}))}delete(t){this.t.delete(t),this.i.delete(t)}isStale(t){const s=this.t.get(t);return!!s&&Date.now()-s.cachedAt>s.ttl}isRefreshing(t){return this.i.has(t)}markRefreshing(t){this.i.add(t)}clearRefreshing(t){this.i.delete(t)}get size(){return this.t.size}clear(){this.t.clear(),this.i.clear()}destroy(){this.h&&(clearInterval(this.h),this.h=null),this.clear()}u(){const t=Date.now();for(const[s,i]of this.t)t-i.cachedAt>2*i.ttl&&(this.t.delete(s),this.i.delete(s))}_(){let t=null,s=1/0;for(const[i,e]of this.t)e.cachedAt<s&&(s=e.cachedAt,t=i);t&&(this.t.delete(t),this.i.delete(t))}}
+const DEFAULT_TTL_MS=6e4,DEFAULT_MAX_SIZE=1e4,SWEEP_INTERVAL_MS=3e5;export class VerdictCache{constructor(t=6e4,s=1e4){this.t=new Map,this.i=new Set,this.h=null,this.l=t,this.o=s}u(){if(!this.h)try{this.h=setInterval(()=>this._(),3e5),this.h&&"function"==typeof this.h.unref&&this.h.unref()}catch{this.h=null}}get(t){return this.t.get(t)}set(t,s,i){this.u(),!this.t.has(t)&&this.t.size>=this.o?this.A():this.t.has(t)&&this.t.delete(t),this.t.set(t,{...s,cachedAt:Date.now(),ttl:i??this.l})}update(t,s){this.u();const i=this.t.get(t);i?(void 0!==s.isFlagged&&(i.isFlagged=s.isFlagged),void 0!==s.isVerified&&(i.isVerified=s.isVerified),i.cachedAt=Date.now(),this.t.delete(t),this.t.set(t,i)):(this.t.size>=this.o&&this.A(),this.t.set(t,{isFlagged:s.isFlagged??!1,isVerified:s.isVerified??!1,emailAddress:"",sessionId:"",cachedAt:Date.now(),ttl:this.l}))}delete(t){this.t.delete(t),this.i.delete(t)}isStale(t){const s=this.t.get(t);return!!s&&Date.now()-s.cachedAt>s.ttl}isRefreshing(t){return this.i.has(t)}markRefreshing(t){this.i.add(t)}clearRefreshing(t){this.i.delete(t)}get size(){return this.t.size}clear(){this.t.clear(),this.i.clear()}destroy(){this.h&&(clearInterval(this.h),this.h=null),this.clear()}_(){const t=Date.now();for(const[s,i]of this.t)t-i.cachedAt>2*i.ttl&&(this.t.delete(s),this.i.delete(s))}A(){const t=this.t.keys().next().value;void 0!==t&&(this.t.delete(t),this.i.delete(t))}}

package/dist/esm/middleware.d.mts

@@ -1,5 +1,5 @@
-import type { UnsharedRequest, UnsharedResponse, UnsharedNextFunction } from './types';
-import type { UnsharedClient } from './client';
+import type { UnsharedRequest, UnsharedResponse, UnsharedNextFunction } from './types.mjs';
+import type { UnsharedClient } from './client.mjs';
 export interface MiddlewareOptions<TReq extends UnsharedRequest = UnsharedRequest> {
     /** Override userId extractor. Falls back to req.body.user_id. */
     userIdExtractor?: (req: TReq) => string | undefined;
@@ -38,7 +38,6 @@ export interface MiddlewareOptions<TReq extends UnsharedRequest = UnsharedReques
  * @example
  * ```typescript
  * assertTrustProxy(app);  // throws at startup if not set
- * app.use(express.json());
  * app.use(createUnsharedMiddleware(client, options));
  * ```
  */
@@ -51,8 +50,8 @@ export declare function assertTrustProxy(app: any): void;
  * Passes all other requests to next().
  *
  * **Prerequisites:**
- * - Mount `express.json()` (or equivalent body-parser) **before** this middleware,
- *   otherwise `req.body` will be undefined and every request will return 400.
+ * - Existing default JSON parser order is supported by the browser's 100 KiB
+ *   proxy limit. Unparsed SDK routes are also read automatically up to 1 MiB.
  * - For cross-origin frontends, pass `corsOrigins` instead of configuring CORS
  *   separately — the middleware handles OPTIONS preflight automatically.
  * - `user_id` is automatically scrubbed from `req.body` after it is read, so
@@ -67,10 +66,10 @@ export declare function assertTrustProxy(app: any): void;
  * ```typescript
  * import { createUnsharedMiddleware } from "unshared-clientjs-sdk";
  *
- * app.use(express.json());  // must come first
  * app.use(createUnsharedMiddleware(client, {
  *   userIdExtractor: (req) => req.user?.id,
  * }));
+ * app.use(express.json()); // application routes keep their own default limit
  * ```
  */
 export declare function createUnsharedMiddleware<TReq extends UnsharedRequest = UnsharedRequest>(client: UnsharedClient, options?: MiddlewareOptions<TReq>): (req: TReq, res: UnsharedResponse, next: UnsharedNextFunction) => Promise<void>;

package/dist/esm/middleware.mjs

@@ -1 +1 @@
-import{sendJson,sendEmpty,getRequestPath}from"./middleware/utils/http-helpers";export function assertTrustProxy(e){if(!e?.get?.("trust proxy"))throw new Error('[unshared-labs] Express "trust proxy" is not set.\n\n  Fix: add this line before mounting any middleware:\n    app.set("trust proxy", 1);\n\n  Why: without it, req.ip returns the proxy/load-balancer IP instead of\n  the real client IP, which degrades account-sharing detection accuracy.\n  Set to 1 if behind a single reverse proxy (Nginx, ALB, CloudFront),\n  or the number of trusted proxies in your chain.')}export function createUnsharedMiddleware(e,s){const{userIdExtractor:r,eventTypeExtractor:t,sessionIdExtractor:n,ipAddressExtractor:o,defaultEventType:i="browser_event",routePrefix:d="/unshared",corsOrigins:c}=s??{},a=`${d}/submit-fingerprint-event`,u=c?Array.isArray(c)?c:[c]:null;return async(s,d,c)=>{const l=getRequestPath(s.url);if(u&&l===a){const e=s.headers.origin??"",r=u.includes("*");if((r||u.includes(e))&&(d.setHeader("Access-Control-Allow-Origin",r?"*":e),d.setHeader("Access-Control-Allow-Methods","POST, OPTIONS"),d.setHeader("Access-Control-Allow-Headers","Content-Type, X-Idempotency-Key, X-Session-Id")),"OPTIONS"===s.method)return void sendEmpty(d,204)}if("POST"===s.method&&l===a)try{if(void 0===s.body)return void sendJson(d,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."}});const c=s.body??{};if(!c.hash||!c.stable_hash||!c.collected_at)return void sendJson(d,400,{success:!1,error:{code:"VALIDATION_ERROR",message:"Missing required fingerprint fields: hash, stable_hash, collected_at"}});if(!s.headers["x-session-id"])return void sendJson(d,400,{success:!1,error:{code:"VALIDATION_ERROR",message:"Missing required header: X-Session-Id"}});const a={full_hash:c.hash,fingerprint_id:c.stable_hash,timestamp:c.collected_at,isIncognito:c.is_incognito??!1,components:c.components??{},version:c.version??"unknown"};let u,l,h,p;try{u=(r?r(s):void 0)??c.user_id}catch{u=c.user_id}if(s.body&&"object"==typeof s.body&&"user_id"in s.body&&delete s.body.user_id,!u)return void sendJson(d,400,{success:!1,error:{code:"VALIDATION_ERROR",message:"Missing required field: user_id"}});try{l=(t?t(s):void 0)??c.event_type??i}catch{l=c.event_type??i}try{h=(n?n(s):void 0)??s.headers["x-session-id"]?.toString()??c.session_id}catch{h=s.headers["x-session-id"]?.toString()??c.session_id}const f=s.ip??s.socket?.remoteAddress??"";try{p=(o?o(s):void 0)??f}catch{p=f}const y=await e.submitFingerprintEvent(a,{userId:u,sessionHash:h,eventType:l,ipAddress:p});if(!y.success)return void sendJson(d,200,{success:!1,error:{code:"UPSTREAM_ERROR",message:y.error?.message??"Upstream request failed"}});sendJson(d,202,{success:!0,data:y.data})}catch(e){sendJson(d,200,{success:!1,error:{code:"MIDDLEWARE_ERROR",message:e instanceof Error?e.message:"Middleware error"}})}else c()}}
+import{sendJson,sendEmpty,getRequestPath}from"./middleware/utils/http-helpers.mjs";import{readJsonBody}from"./middleware/utils/read-json-body.mjs";export function assertTrustProxy(e){if(!e?.get?.("trust proxy"))throw new Error('[unshared-labs] Express "trust proxy" is not set.\n\n  Fix: add this line before mounting any middleware:\n    app.set("trust proxy", 1);\n\n  Why: without it, req.ip returns the proxy/load-balancer IP instead of\n  the real client IP, which degrades account-sharing detection accuracy.\n  Set to 1 if behind a single reverse proxy (Nginx, ALB, CloudFront),\n  or the number of trusted proxies in your chain.')}export function createUnsharedMiddleware(e,t){const{userIdExtractor:r,eventTypeExtractor:o,sessionIdExtractor:s,ipAddressExtractor:n,defaultEventType:i="browser_event",routePrefix:c="/unshared",corsOrigins:d}=t??{},a=`${c}/submit-fingerprint-event`,y=d?Array.isArray(d)?d:[d]:null;return async(t,c,d)=>{const p=getRequestPath(t.url);if(y&&p===a){const e=t.headers.origin??"",r=y.includes("*");if((r||y.includes(e))&&(c.setHeader("Access-Control-Allow-Origin",r?"*":e),c.setHeader("Access-Control-Allow-Methods","POST, OPTIONS"),c.setHeader("Access-Control-Allow-Headers","Content-Type, X-Idempotency-Key, X-Session-Id, X-Permanent-Device-Id")),"OPTIONS"===t.method)return void sendEmpty(c,204)}if("POST"===t.method&&p===a)try{if(!await readJsonBody(t,c))return;const d=t.body??{};if(!d||"object"!=typeof d||Array.isArray(d))return void sendJson(c,400,{success:!1,error:{code:"VALIDATION_ERROR",message:"Request body must be a JSON object"}});const a=d.context&&"object"==typeof d.context?d.context:{},y=a.identity&&"object"==typeof a.identity?a.identity:{},p=a.identifiers&&"object"==typeof a.identifiers?a.identifiers:{},u=a.event&&"object"==typeof a.event?a.event:{};let f,l,h,b;try{f=(r?r(t):void 0)??y.user_id}catch{f=y.user_id}try{l=(o?o(t):void 0)??u.type??i}catch{l=u.type??i}try{h=(s?s(t):void 0)??t.headers["x-session-id"]?.toString()??p.session_hash}catch{h=t.headers["x-session-id"]?.toString()??p.session_hash}const m=t.ip??t.socket?.remoteAddress??"";try{b=(n?n(t):void 0)??m}catch{b=m}const x=t.headers["x-permanent-device-id"]?.toString()??p.unshared_device_id,A=a.sdk&&"object"==typeof a.sdk?a.sdk.name:void 0,g="string"==typeof A&&A.startsWith("unshared-")&&d.fingerprint&&"object"==typeof d.fingerprint&&d.context&&"object"==typeof d.context&&!Array.isArray(d.context)&&d.context.identity&&"object"==typeof d.context.identity&&!Array.isArray(d.context.identity)&&d.context.identifiers&&"object"==typeof d.context.identifiers&&!Array.isArray(d.context.identifiers)&&d.context.event&&"object"==typeof d.context.event&&!Array.isArray(d.context.event),j=!Object.prototype.hasOwnProperty.call(d,"context")&&"string"==typeof d.hash&&"string"==typeof d.stable_hash&&"string"==typeof d.collected_at&&d.components&&"object"==typeof d.components&&!Array.isArray(d.components),v=g||j?{...d,context:{...a,identity:{...y,...f?{user_id:f}:{}},identifiers:{...p,...h?{session_hash:h}:{},...x?{unshared_device_id:x}:{}},event:{...u,type:l,...b?{ip_address:b}:{},user_agent:t.headers["user-agent"]?.toString()??""}}}:d,E=await e.submitFingerprint(v,{idempotencyKey:t.headers["x-idempotency-key"]?.toString()});if(!E.success)return void sendJson(c,200,{success:!1,error:E.error??{code:"UPSTREAM_ERROR",message:"Upstream request failed"}});sendJson(c,202,{success:!0,data:E.data})}catch(e){sendJson(c,200,{success:!1,error:{code:"MIDDLEWARE_ERROR",message:e instanceof Error?e.message:"Middleware error"}})}else d()}}

package/dist/esm/shared-types.d.mts

@@ -0,0 +1,148 @@
+/**
+ * Canonical wire-format for fingerprint data transmitted from the browser SDK to the backend.
+ *
+ * Single source of truth shared by:
+ *   - @unshared-labs/frontend-fingerprint  (serializer: _buildBody in browser.ts)
+ *   - @unshared-labs/sdk                   (submitFingerprintEvent in client.ts)
+ *
+ * SCHEMA AUTHORITY: The browser SDK serializer is the writer. The Node.js SDK is the
+ * reader. Any field added here must be produced by the browser SDK and consumed by the
+ * server SDK. Do not add fields that only one side uses.
+ */
+export type JSONPrimitive = string | number | boolean | null;
+export type JSONValue = JSONPrimitive | JSONObject | JSONValue[];
+export interface JSONObject {
+  [key: string]: JSONValue;
+}
+
+export interface BrowserStorageEntry extends JSONObject {
+  name: string;
+  value: string;
+}
+
+export interface BrowserStorageSnapshot extends JSONObject {
+  cookies: BrowserStorageEntry[];
+  local_storage: BrowserStorageEntry[];
+  session_storage: BrowserStorageEntry[];
+}
+
+export interface EncryptedEventEnvelope {
+  encrypted_data: string;
+}
+
+export interface FingerprintEventContext extends JSONObject {
+  sdk: JSONObject;
+  identity: JSONObject;
+  identifiers: JSONObject;
+  event: JSONObject;
+  browser_storage?: BrowserStorageSnapshot;
+}
+
+export type V3Identifiers = Record<string, string>;
+
+export interface V3Success<T> {
+  success: true;
+  data: T;
+}
+
+export interface V3Error {
+  success: false;
+  error: {
+    code: string;
+    message: string;
+    retryAfter?: number;
+    nextAllowedAt?: string;
+  };
+}
+
+export type V3Result<T> = V3Success<T> | V3Error;
+
+export interface IngestResult {
+  event_id: string;
+  collected_at: string;
+  endpoint_version: 'v3';
+}
+
+export interface TriggerEmailRequest {
+  email_address: string;
+  identifiers: V3Identifiers;
+}
+
+export interface TriggerEmailResult {
+  verification_id: string;
+  next_allowed_at: string;
+  retry_after_seconds: number;
+}
+
+export interface VerifyEmailRequest {
+  verification_id: string;
+  code: string;
+}
+
+export type VerifyEmailResult =
+  | { verified: true; verification_scope: 'email' }
+  | { verified: false; verification_scope: 'email'; reason: 'invalid_code' };
+
+export interface CheckUserRequest {
+  user_id?: string;
+  email_address: string;
+  identifiers: V3Identifiers;
+}
+
+export type CheckDecisionCode =
+  | 'FLAGGED_RISK_MATCH'
+  | 'NO_ENFORCING_RISK'
+  | 'NO_IDENTITY_MATCH'
+  | 'IDENTITY_UNCERTAIN'
+  | 'CHECK_UNAVAILABLE';
+
+export interface CheckUserResult {
+  is_user_flagged: boolean;
+  decision_id: string;
+  decision_code: CheckDecisionCode;
+}
+
+export interface FingerprintEventPayload extends JSONObject {
+  fingerprint: JSONObject;
+  context: FingerprintEventContext;
+}
+
+export interface FingerprintWireFormat {
+  [key: string]: unknown;
+  /**
+   * Primary device identifier — stable hash excluding volatile signals (audio, timing).
+   * Consistent across normal and incognito sessions on the same device.
+   * 32-character hex string.
+   */
+  fingerprint_id: string;
+  /**
+   * Full hash including all active signals (volatile signals included).
+   * Maximum entropy; may vary slightly between sessions on the same device.
+   * 32-character hex string.
+   */
+  full_hash: string;
+  /**
+   * Raw browser signal data keyed by signal name (e.g. `webgl`, `hardware`, `audio`).
+   *
+   * This blob is forwarded as-is in the `components` JSON field and stored verbatim
+   * in a `components JSONB` column on `fingerprint_events`. No server-side decomposition
+   * is performed; the full component tree is preserved for querying.
+   */
+  components: Record<string, unknown>;
+  /** ISO timestamp when the fingerprint was collected. */
+  timestamp: string;
+  /** Whether private/incognito browsing was detected at collection time. */
+  isIncognito: boolean;
+  /** Fingerprint library semver, e.g. "1.0.0". */
+  version: string;
+  /**
+   * Where the fingerprint agent that produced this result was loaded from:
+   *   - `'remote'`  — the runtime-loaded UMD (S3 directly in browser direct mode,
+   *                   or the Node SDK's same-origin proxy of S3).
+   *   - `'bundled'` — the copy compiled into the SDK, used as the fallback when
+   *                   the remote load failed/timed out.
+   * Optional: older SDK artifacts and the mobile SDKs omit it, so the reader
+   * must tolerate its absence. Observability for S3 fast-path vs fallback rates.
+   */
+  source?: 'remote' | 'bundled';
+}

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

@@ -10,9 +10,9 @@
  * is compatible with all frameworks that expose `http.IncomingMessage`/
  * `http.ServerResponse` objects.
  */
-export { createWebSubmitHandler } from './submit-handler';
-export { createWebProtectionMiddleware } from './protection-handler';
-export { flaggedResponse, ACCOUNT_FLAGGED_ERROR } from '../middleware/utils/flagged-response';
-export type { WebHandler, WebMiddleware, WebSubmitOptions, WebProtectionConfig, } from './types';
-export { VerdictCache } from '../middleware/verdict-cache';
-export type { Verdict } from '../middleware/verdict-cache';
+export { createWebSubmitHandler } from './submit-handler.mjs';
+export { createWebProtectionMiddleware } from './protection-handler.mjs';
+export { flaggedResponse, ACCOUNT_FLAGGED_ERROR } from '../middleware/utils/flagged-response.mjs';
+export type { WebHandler, WebMiddleware, WebSubmitOptions, WebProtectionConfig, } from './types.mjs';
+export { VerdictCache } from '../middleware/verdict-cache.mjs';
+export type { Verdict } from '../middleware/verdict-cache.mjs';

package/dist/esm/web/index.mjs

@@ -1 +1 @@
-export{createWebSubmitHandler}from"./submit-handler";export{createWebProtectionMiddleware}from"./protection-handler";export{flaggedResponse,ACCOUNT_FLAGGED_ERROR}from"../middleware/utils/flagged-response";export{VerdictCache}from"../middleware/verdict-cache";
+export{createWebSubmitHandler}from"./submit-handler.mjs";export{createWebProtectionMiddleware}from"./protection-handler.mjs";export{flaggedResponse,ACCOUNT_FLAGGED_ERROR}from"../middleware/utils/flagged-response.mjs";export{VerdictCache}from"../middleware/verdict-cache.mjs";

package/dist/esm/web/protection-handler.d.mts

@@ -1,5 +1,7 @@
-import type { UnsharedClient } from '../client';
-import type { WebMiddleware, WebProtectionConfig } from './types';
+import type { UnsharedClient } from '../client.mjs';
+import { VerdictCache } from '../middleware/verdict-cache.mjs';
+import type { Verdict } from '../middleware/verdict-cache.mjs';
+import type { WebMiddleware, WebProtectionConfig } from './types.mjs';
 /**
  * Web Standard equivalent of `unsharedBoundToUser` from src/middleware/index.ts.
  *
@@ -11,7 +13,15 @@ import type { WebMiddleware, WebProtectionConfig } from './types';
  * handler calls `next(request)` to get the downstream Response, transforms
  * it (injects the fingerprint script into HTML), and returns a new Response.
  *
- * @example Next.js App Router (in middleware.ts)
+ * NOTE: In Next.js middleware, `next(request)` is typically `() => NextResponse.next()`,
+ * which is a passthrough with a null body and no Content-Type — there is no HTML to
+ * inject a script into. This middleware still resolves the verdict and enforces it
+ * (gate/overlay/403), but fingerprint COLLECTION must be done by the browser/React SDK
+ * mounted in your app, not by injection here. See the Next.js section of the
+ * integration guide.
+ *
+ * @example Next.js App Router (in middleware.ts) — verdict + enforcement only;
+ * mount the browser/React SDK client-side to collect fingerprints.
  * ```typescript
  * import { createWebProtectionMiddleware } from 'unshared-clientjs-sdk/web';
  *
@@ -26,3 +36,21 @@ import type { WebMiddleware, WebProtectionConfig } from './types';
  * ```
  */
 export declare function createWebProtectionMiddleware(client: UnsharedClient, config: WebProtectionConfig): WebMiddleware;
+/** Mutable holder for the one-time passthrough-injection warning (see below). */
+interface InjectWarnState {
+    emitted: boolean;
+}
+/**
+ * Read the response body, inject the fingerprint script into HTML responses,
+ * merge Set-Cookie headers, and return a new Response. For non-HTML responses,
+ * only the cookies and cache-control override are applied.
+ *
+ * `warnState` scopes the one-time "passthrough, nothing injected" warning to a
+ * single middleware instance; when omitted, the module-level default is used.
+ */
+declare function injectIntoHtmlResponse(response: Response, fingerprintScript: string, extraCookies?: string[], warnState?: InjectWarnState): Promise<Response>;
+declare function fetchAndCacheVerdict(client: UnsharedClient, cache: VerdictCache, userId: string, emailAddress: string, deviceId: string, fingerprintId: string | undefined, permanentDeviceId: string | undefined, sessionId: string, timeoutMs?: number, reportFailOpen?: (reason: 'timeout' | 'http_error' | 'no_device_id', status?: number) => void): Promise<Verdict>;
+export declare const __test_fetchAndCacheVerdict: typeof fetchAndCacheVerdict;
+export declare const __test_injectIntoHtmlResponse: typeof injectIntoHtmlResponse;
+export declare function __test_resetInjectWarning(): void;
+export {};