unshared-clientjs-sdk 1.0.13 → 2.0.0-rc.10

package/dist/middleware/index.d.ts

@@ -0,0 +1,50 @@
+import type { Request, Response, NextFunction } from 'express';
+import type { UnsharedLabsClient } from '../client';
+import { VerdictCache } from './verdict-cache';
+import type { Verdict } from './verdict-cache';
+export interface ProtectionConfig {
+    /**
+     * 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.
+     * 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;
+    /** 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[];
+    /** 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 __unshared_fp_id cookie → X-Device-Id header.
+     */
+    deviceId?: (req: Request) => string | undefined;
+    /**
+     * Called when a flagged, unverified user makes a request.
+     * You own the response — block, redirect, or call next() to let it through.
+     *
+     * If not provided, flagged requests pass through (data collection only).
+     * Exceptions are caught and swallowed — the request passes through on error.
+     */
+    onFlagged?: (context: {
+        userId: string;
+        emailAddress: string;
+        verdict: Verdict;
+        req: Request;
+        res: Response;
+        next: NextFunction;
+    }) => void;
+}
+export type { Verdict };
+export { VerdictCache };
+export declare function unsharedBoundToUser(client: UnsharedLabsClient, config: ProtectionConfig): (req: Request, res: Response, next: NextFunction) => void;

package/dist/middleware/index.js

@@ -0,0 +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"),is_bot_1=require("./utils/is-bot"),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: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)(n,p);let v="";try{const e=require.resolve("unshared-frontend-sdk/dist/index.umd.js");v=(0,fs_1.readFileSync)(e,"utf8")}catch{}const h=(0,submit_fp_1.handleSubmitFingerprint)({client:e,verdictCache:l,rateLimitBackoff:f,resolveUserId:r,resolveEmailAddress:i,resolveSessionId:d,resolveDeviceId:a}),m=(0,verify_1.handleVerifyTrigger)({client:e,verdictCache:l,resolveEmailAddress:i,resolveDeviceId:a}),C=(0,verify_1.handleVerify)({client:e,verdictCache:l,resolveEmailAddress:i,resolveDeviceId:a}),I=s?Array.isArray(s)?s:[s]:null,g=`${n}/fp.js`,k=`${n}/submit-fp`,y=`${n}/verify-trigger`,A=`${n}/verify`;return function(t,s,o){const p=t.path;if(p.startsWith(n+"/"))return function(e,t){if(!I)return;const r=e.headers.origin??"",i=I.includes("*");(i||I.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?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(v)):"POST"===t.method&&p===k?void h(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,i);if(setUserIdCookie(s,S),T&&setEmailCookie(s,T),!T)return interceptForInjection(t,s,_),void o();const x=extractSessionId(t,d),E=extractDeviceId(t,a),b=extractFingerprintId(t),w=t.headers["user-agent"]??"",O=t.ip??"";if((0,is_bot_1.isBot)(w))return void o();f.isPaused()||dispatchUserEvent(e,l,f,{userId:S,emailAddress:T,sessionId:x,deviceId:E,fingerprintId:b,userAgent:w,ipAddress:O,eventType:`${t.method} ${t.path}`});const U=l.get(S);U?(l.isStale(S)&&!l.isRefreshing(S)&&(l.markRefreshing(S),fetchAndCacheVerdict(e,l,S,T,E,b,x).finally(()=>l.clearRefreshing(S))),applyVerdict(U,S,T,t,s,o,_,u)):fetchAndCacheVerdict(e,l,S,T,E,b,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 i=e.body?.email;return"string"==typeof i&&i?i:void 0}function applyVerdict(e,t,r,i,n,s,o,c){if(interceptForInjection(i,n,o),e.isFlagged&&!e.isVerified&&c)try{c({userId:t,emailAddress:r,verdict:e,req:i,res:n,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,...i){const n=t.getHeader("content-type");return n&&String(n).includes("text/html")&&(t.setHeader("Cache-Control","no-store"),t.removeHeader("ETag"),t.removeHeader("Last-Modified")),r(e,...i)}}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 i=e.toString("utf8"),n=i.lastIndexOf("</body>");return-1===n?i+r:i.slice(0,n)+r+i.slice(n)})}function dispatchUserEvent(e,t,r,i){e.processUserEvent({eventType:i.eventType,userId:i.userId,emailAddress:i.emailAddress,ipAddress:i.ipAddress,deviceId:i.deviceId,fingerprintId:i.fingerprintId,sessionHash:i.sessionId,userAgent:i.userAgent}).then(e=>{e.success&&e.data?.analysis&&t.update(i.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,i,n,s,o){const c={};n&&"unknown"!==n&&(c.deviceId=n),s&&(c.fingerprintId=s);const d=await Promise.race([e.checkUser(i,c),new Promise(e=>setTimeout(()=>e(null),500))]);if(!d)return{isFlagged:!1,isVerified:!1,emailAddress:i,sessionId:o,cachedAt:0,ttl:0};const a=d.data?.is_user_flagged??!1;return t.set(r,{isFlagged:a,isVerified:!1,emailAddress:i,sessionId:o}),t.get(r)}function parseCookie(e,t){const r=e.headers.cookie;if(!r)return;const i=r.match(new RegExp(`(?:^|; )${t}=([^;]*)`));return i?decodeURIComponent(i[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 i=e.headers["x-device-id"];return"string"==typeof i&&i?i:"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 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){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")}

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

@@ -0,0 +1,10 @@
+/**
+ * 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
+ *
+ * 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.
+ */
+export declare function generateFingerprintScript(routePrefix: string, version?: string): string;

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

@@ -0,0 +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;

package/dist/middleware/rate-limit-backoff.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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. */
+    pause(durationMs: number): void;
+    /** Returns true if processUserEvent calls should be skipped. */
+    isPaused(): boolean;
+}

package/dist/middleware/rate-limit-backoff.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.RateLimitBackoff=void 0;class RateLimitBackoff{constructor(){this.i=0}pause(t){const s=Date.now()+t;s>this.i&&(this.i=s)}isPaused(){return Date.now()<this.i}}exports.RateLimitBackoff=RateLimitBackoff;

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

@@ -0,0 +1,13 @@
+import type { Response } from 'express';
+/**
+ * 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.
+ *
+ * Does NOT monkey-patch res.send — uses the lower-level write/end API
+ * as required by the spec.
+ */
+export declare function interceptResponse(res: Response, transform: (body: Buffer, contentType: string | undefined) => Buffer | string | null): void;

package/dist/middleware/response-interceptor.js

@@ -0,0 +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;

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

@@ -0,0 +1,24 @@
+import type { Request, Response } from 'express';
+import type { UnsharedLabsClient } from '../../client';
+import type { VerdictCache } from '../verdict-cache';
+import type { RateLimitBackoff } from '../rate-limit-backoff';
+export interface SubmitFingerprintDependencies {
+    client: UnsharedLabsClient;
+    verdictCache: VerdictCache;
+    rateLimitBackoff: RateLimitBackoff;
+    resolveUserId?: (req: Request) => string | undefined;
+    resolveEmailAddress?: (req: Request) => string | undefined;
+    resolveSessionId?: (req: Request) => string | undefined;
+    resolveDeviceId?: (req: Request) => string | undefined;
+}
+/**
+ * Handles POST /__unshared/submit-fp
+ *
+ * Receives fingerprint data from the injected inline script and:
+ * 1. Forwards to Unshared API via client.submitFingerprintEvent() (fire-and-forget)
+ * 2. Calls processUserEvent with cache side-effect (fire-and-forget)
+ * 3. Sets __unshared_email HttpOnly cookie when email is resolved from body
+ *
+ * Always returns 200 (fire-and-forget from browser's perspective).
+ */
+export declare function handleSubmitFingerprint(dependencies: SubmitFingerprintDependencies): (req: Request, res: Response) => Promise<void>;

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

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.handleSubmitFingerprint=handleSubmitFingerprint;const is_bot_1=require("../utils/is-bot");function handleSubmitFingerprint(e){return async(t,n)=>{try{const i=t.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,c;try{s=e.resolveUserId?e.resolveUserId(t):void 0}catch{}s=s??i.user_id??void 0;try{r=e.resolveEmailAddress?e.resolveEmailAddress(t):void 0}catch{}r=r??parseCookie(t,"__unshared_email")??i.email??void 0;try{c=e.resolveSessionId?e.resolveSessionId(t):void 0}catch{}c=c??i.session_id??parseCookie(t,"__unshared_sid");const a=t.ip??"",d=t.headers["user-agent"]??"";if((0,is_bot_1.isBot)(d))return void n.status(200).json({success:!0});const u=extractDeviceId(t,e.resolveDeviceId),_=o.fingerprint_id||void 0,p=[];if(_&&!parseCookie(t,"__unshared_fingerprint_id")&&p.push(`__unshared_fingerprint_id=${encodeURIComponent(_)}; HttpOnly; Path=/; SameSite=Lax`),r&&!parseCookie(t,"__unshared_email")&&p.push(`__unshared_email=${encodeURIComponent(r)}; HttpOnly; Path=/; SameSite=Lax`),p.length>0){const e=n.getHeader("Set-Cookie");if(e){const t=Array.isArray(e)?[...e]:[String(e)];t.push(...p),n.setHeader("Set-Cookie",t)}else n.setHeader("Set-Cookie",p)}s&&e.client.submitFingerprintEvent(o,{userId:s,sessionHash:c,eventType:"auto_collect",ipAddress:a}).catch(()=>{}),s&&r&&!e.rateLimitBackoff.isPaused()&&e.client.processUserEvent({eventType:"auto_collect",userId:s,emailAddress:r,ipAddress:a,deviceId:u,fingerprintId:_,sessionHash:c??"unknown",userAgent:d}).then(t=>{t.success&&t.data?.analysis&&e.verdictCache.update(s,{isFlagged:t.data.analysis.is_user_flagged}),!t.success&&t.error?.retryAfter&&e.rateLimitBackoff.pause(1e3*t.error.retryAfter)}).catch(()=>{}),n.status(200).json({success:!0})}catch{n.status(200).json({success:!0})}}}function extractDeviceId(e,t){if(t)try{const n=t(e);if(n)return n}catch{}const n=parseCookie(e,"__unshared_fp_id");if(n)return n;const i=e.headers["x-device-id"];return"string"==typeof i&&i?i:"unknown"}function parseCookie(e,t){const n=e.headers.cookie;if(!n)return;const i=n.match(new RegExp(`(?:^|; )${t}=([^;]*)`));return i?decodeURIComponent(i[1]):void 0}

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

@@ -0,0 +1,28 @@
+import type { Request, Response } from 'express';
+import type { UnsharedLabsClient } from '../../client';
+import type { VerdictCache } from '../verdict-cache';
+export interface VerificationDependencies {
+    client: UnsharedLabsClient;
+    verdictCache: VerdictCache;
+    resolveEmailAddress?: (req: Request) => string | undefined;
+    resolveDeviceId?: (req: Request) => string | undefined;
+}
+/**
+ * POST /__unshared/verify-trigger
+ * Triggers email verification. Called by the blocker overlay UI.
+ *
+ * Body: { email: string }
+ *
+ * The deviceId is resolved via extractDeviceId (same as the middleware).
+ */
+export declare function handleVerifyTrigger(dependencies: VerificationDependencies): (req: Request, res: Response) => Promise<void>;
+/**
+ * POST /__unshared/verify
+ * Validates OTP code. Called by the blocker overlay UI.
+ *
+ * Body: { email: string, code: string }
+ *
+ * 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>;

package/dist/middleware/routes/verify.js

@@ -0,0 +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;

package/dist/middleware/utils/content-type.d.ts

@@ -0,0 +1,6 @@
+/** Check if a Content-Type header value indicates HTML. */
+export declare function isHtmlContentType(contentType: string | undefined): boolean;
+/** Check if a Content-Type header value indicates JSON. */
+export declare function isJsonContentType(contentType: string | undefined): boolean;
+/** Check if a Content-Type indicates a static asset (images, fonts, etc). */
+export declare function isStaticContentType(contentType: string | undefined): boolean;

package/dist/middleware/utils/content-type.js

@@ -0,0 +1 @@
+"use strict";function isHtmlContentType(t){return!!t&&t.includes("text/html")}function isJsonContentType(t){return!!t&&t.includes("application/json")}function isStaticContentType(t){return!!t&&["image/","font/","audio/","video/","application/javascript","text/javascript","text/css","application/wasm"].some(e=>t.includes(e))}Object.defineProperty(exports,"t",{value:!0}),exports.isHtmlContentType=isHtmlContentType,exports.isJsonContentType=isJsonContentType,exports.isStaticContentType=isStaticContentType;

package/dist/middleware/utils/is-bot.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Returns true if the User-Agent string matches a known bot, crawler,
+ * scanner, or HTTP client library pattern.
+ */
+export declare function isBot(userAgent: string): boolean;

package/dist/middleware/utils/is-bot.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.isBot=isBot;const BOT_PATTERNS=["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","nessus","nikto","sqlmap","burp","zap","qualys","openvas","nmap","masscan","facebookexternalhit","twitterbot","linkedinbot","whatsapp","telegrambot","slackbot","discordbot","bot","crawl","spider","scrape","fetch","scan"],BOT_RE=new RegExp(BOT_PATTERNS.join("|"),"i");function isBot(t){return!!t&&BOT_RE.test(t)}

package/dist/middleware/utils/skip-paths.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Returns true if the request path looks like a static asset and should be
+ * skipped by the middleware (no fingerprint injection, no verdict checks).
+ */
+export declare function shouldSkipPath(path: string, customSkipPaths?: string[]): boolean;

package/dist/middleware/utils/skip-paths.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.shouldSkipPath=shouldSkipPath;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",".json",".xml",".txt",".pdf"]),STATIC_PATH_PREFIXES=["/static/","/assets/","/public/","/_next/","/__vite/","/favicon"];function shouldSkipPath(t,s){if(s)for(const o of s)if(t.startsWith(o))return!0;const o=t.lastIndexOf(".");if(-1!==o){const s=t.slice(o).toLowerCase().split("?")[0];if(STATIC_EXTENSIONS.has(s))return!0}for(const s of STATIC_PATH_PREFIXES)if(t.startsWith(s))return!0;return!1}

package/dist/middleware/verdict-cache.d.ts

@@ -0,0 +1,36 @@
+export interface Verdict {
+    isFlagged: boolean;
+    isVerified: boolean;
+    emailAddress: string;
+    sessionId: string;
+    cachedAt: number;
+    ttl: number;
+}
+export declare class VerdictCache {
+    private readonly _entries;
+    private readonly _activeRefreshes;
+    private readonly _defaultTtlMs;
+    constructor(defaultTTL?: number);
+    get(userId: string): Verdict | undefined;
+    set(userId: string, verdict: Omit<Verdict, 'cachedAt' | 'ttl'>, ttl?: number): void;
+    /**
+     * Update an existing cache entry (e.g. from webhook).
+     * If the user is not in cache, creates a new entry.
+     */
+    update(userId: string, partial: Partial<Pick<Verdict, 'isFlagged' | 'isVerified'>>): void;
+    delete(userId: string): void;
+    /**
+     * Returns true if the entry exists but is past its TTL.
+     * Stale entries are served while a background refresh happens.
+     */
+    isStale(userId: string): boolean;
+    /**
+     * Returns true if a background refresh is already in flight for this user.
+     */
+    isRefreshing(userId: string): boolean;
+    markRefreshing(userId: string): void;
+    clearRefreshing(userId: string): void;
+    /** Number of cached entries. */
+    get size(): number;
+    clear(): void;
+}

package/dist/middleware/verdict-cache.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.VerdictCache=void 0;class VerdictCache{constructor(t=6e4){this.i=new Map,this.h=new Set,this.o=t}get(t){return this.i.get(t)}set(t,e,s){this.i.set(t,{...e,cachedAt:Date.now(),ttl:s??this.o})}update(t,e){const s=this.i.get(t);s?(void 0!==e.isFlagged&&(s.isFlagged=e.isFlagged),void 0!==e.isVerified&&(s.isVerified=e.isVerified),s.cachedAt=Date.now()):this.i.set(t,{isFlagged:e.isFlagged??!1,isVerified:e.isVerified??!1,emailAddress:"",sessionId:"",cachedAt:Date.now(),ttl:this.o})}delete(t){this.i.delete(t),this.h.delete(t)}isStale(t){const e=this.i.get(t);return!!e&&Date.now()-e.cachedAt>e.ttl}isRefreshing(t){return this.h.has(t)}markRefreshing(t){this.h.add(t)}clearRefreshing(t){this.h.delete(t)}get size(){return this.i.size}clear(){this.i.clear(),this.h.clear()}}exports.VerdictCache=VerdictCache;

package/dist/middleware.d.ts

@@ -0,0 +1,73 @@
+import type { Request, Response, NextFunction, Application } from 'express';
+import type { UnsharedLabsClient } from './client';
+export interface MiddlewareOptions {
+    /** Override userId extractor. Falls back to req.body.user_id. */
+    userIdExtractor?: (req: Request) => string | undefined;
+    /** Override eventType extractor. Falls back to req.body.event_type. */
+    eventTypeExtractor?: (req: Request) => string | undefined;
+    /** Override sessionId extractor. Falls back to X-Session-Id header, then req.body.session_id. */
+    sessionIdExtractor?: (req: Request) => string | undefined;
+    /** Override IP address extractor. Falls back to req.ip. */
+    ipAddressExtractor?: (req: Request) => string | undefined;
+    /** Default event type when none is extractable. @default "browser_event" */
+    defaultEventType?: string;
+    /**
+     * Route prefix the middleware is mounted 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 middleware handles OPTIONS preflight automatically when this is set.
+     * @example corsOrigins: "https://app.example.com"
+     * @example corsOrigins: ["https://app.example.com", "https://staging.example.com"]
+     */
+    corsOrigins?: string | string[];
+}
+/**
+ * Asserts that Express `trust proxy` is configured on the app.
+ * Call this once during application startup, before mounting any middleware.
+ *
+ * Throws synchronously if the setting is missing, killing the process before
+ * any requests are served.
+ *
+ * @example
+ * ```typescript
+ * assertTrustProxy(app);  // throws at startup if not set
+ * app.use(express.json());
+ * app.use(createUnsharedMiddleware(client, options));
+ * ```
+ */
+export declare function assertTrustProxy(app: Application): void;
+/**
+ * Creates an Express middleware that proxies browser fingerprint events to
+ * Unshared Labs. Mount this to handle the browser fingerprint route contract (§4 of spec).
+ *
+ * Handles POST <routePrefix>/submit-fingerprint-event.
+ * 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.
+ * - 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
+ *   downstream logging middleware will not capture plaintext PII.
+ *
+ * **Error contract:** Never returns 5xx to the browser. Upstream failures are
+ * returned as HTTP 200 with { success: false, error: { code: "UPSTREAM_ERROR" } }.
+ * Standard HTTP-level monitoring will not surface proxy errors — monitor the
+ * rate of `success: false` responses in your application layer instead.
+ *
+ * @example
+ * ```typescript
+ * import { createUnsharedMiddleware } from "@unshared-labs/sdk/middleware";
+ *
+ * app.use(express.json());  // must come first
+ * app.use(createUnsharedMiddleware(client, {
+ *   userIdExtractor: (req) => req.user?.id,
+ * }));
+ * ```
+ */
+export declare function createUnsharedMiddleware(client: UnsharedLabsClient, options?: MiddlewareOptions): (req: Request, res: Response, next: NextFunction) => Promise<void>;

package/dist/middleware.js

@@ -0,0 +1 @@
+"use strict";function assertTrustProxy(e){if(!e.get("trust proxy"))throw new Error('[unshared-labs] Express "trust proxy" is not set. Add `app.set("trust proxy", 1)` before calling assertTrustProxy, otherwise req.ip will reflect the proxy\'s IP instead of the real client IP.')}function createUnsharedMiddleware(e,r){const{userIdExtractor:s,eventTypeExtractor:t,sessionIdExtractor:o,ipAddressExtractor:i,defaultEventType:n="browser_event",routePrefix:c="/unshared",corsOrigins:d}=r??{},a=`${c}/submit-fingerprint-event`,l=d?Array.isArray(d)?d:[d]:null;let u=!1;return async(r,c,d)=>{if(!u&&(u=!0,r.app&&!r.app.get("trust proxy")))throw new Error('[unshared-labs] Express "trust proxy" is not set. Add `app.set("trust proxy", 1)` before mounting this middleware, otherwise req.ip will reflect the proxy\'s IP instead of the real client IP.');if(l&&r.path===a){const e=r.headers.origin??"",s=l.includes("*");if((s||l.includes(e))&&(c.setHeader("Access-Control-Allow-Origin",s?"*":e),c.setHeader("Access-Control-Allow-Methods","POST, OPTIONS"),c.setHeader("Access-Control-Allow-Headers","Content-Type, X-Idempotency-Key, X-Session-Id")),"OPTIONS"===r.method)return void c.status(204).end()}if("POST"===r.method&&r.path===a)try{const d=r.body??{};if(!d.hash||!d.stable_hash||!d.collected_at)return void c.status(400).json({success:!1,error:{code:"VALIDATION_ERROR",message:"Missing required fingerprint fields: hash, stable_hash, collected_at"}});if(!r.headers["x-session-id"])return void c.status(400).json({success:!1,error:{code:"VALIDATION_ERROR",message:"Missing required header: X-Session-Id"}});const a={full_hash:d.hash,fingerprint_id:d.stable_hash,timestamp:d.collected_at,isIncognito:d.is_incognito??!1,components:d.components??{},version:d.version??"unknown"};let l,u,p,f;try{l=(s?s(r):void 0)??d.user_id}catch{l=d.user_id}if(r.body&&"object"==typeof r.body&&"user_id"in r.body&&delete r.body.user_id,!l)return void c.status(400).json({success:!1,error:{code:"VALIDATION_ERROR",message:"Missing required field: user_id"}});try{u=(t?t(r):void 0)??d.event_type??n}catch{u=d.event_type??n}try{p=(o?o(r):void 0)??r.headers["x-session-id"]?.toString()??d.session_id}catch{p=r.headers["x-session-id"]?.toString()??d.session_id}try{f=(i?i(r):void 0)??r.ip}catch{f=r.ip}const h=await e.submitFingerprintEvent(a,{userId:l,sessionHash:p,eventType:u,ipAddress:f});if(!h.success)return void c.status(200).json({success:!1,error:{code:"UPSTREAM_ERROR",message:h.error?.message??"Upstream request failed"}});c.status(202).json({success:!0,data:h.data})}catch(e){c.status(200).json({success:!1,error:{code:"MIDDLEWARE_ERROR",message:e instanceof Error?e.message:"Middleware error"}})}else d()}}Object.defineProperty(exports,"t",{value:!0}),exports.assertTrustProxy=assertTrustProxy,exports.createUnsharedMiddleware=createUnsharedMiddleware;

package/dist/util.d.ts

@@ -1,2 +1 @@
-export declare function encryptData(data: string | null | undefined, clientCredentials: string): string;
-export declare function decryptData(encryptedData: string, clientCredentials: string): string | null;
+export declare function encryptData(data: string, key: Buffer): string;

package/dist/util.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.encryptData=encryptData,exports.decryptData=decryptData;const crypto_1=require("crypto");function encryptData(t,e){if(null==t)return"unknown";const r="string"==typeof t?t:JSON.stringify(t),a=(0,crypto_1.createHash)("sha256").update(e).digest(),n=(0,crypto_1.randomBytes)(16),c=(0,crypto_1.createCipheriv)("aes-256-cbc",a,n);let o=c.update(r,"utf8","base64");return o+=c.final("base64"),n.toString("base64")+":"+o}function decryptData(t,e){if("unknown"===t)return null;const r=t.split(":");if(2!==r.length)throw new Error("Invalid encrypted data format");const[a,n]=r,c=Buffer.from(a,"base64"),o=(0,crypto_1.createHash)("sha256").update(e).digest(),s=(0,crypto_1.createDecipheriv)("aes-256-cbc",o,c);let p=s.update(n,"base64","utf8");return p+=s.final("utf8"),p}
+"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.encryptData=encryptData;const crypto_1=require("crypto");function encryptData(t,e){const c=(0,crypto_1.randomBytes)(12),r=(0,crypto_1.createCipheriv)("aes-256-gcm",e,c);let s=r.update(t,"utf8","base64");s+=r.final("base64");const o=r.getAuthTag();return c.toString("base64")+":"+o.toString("base64")+":"+s}

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "unshared-clientjs-sdk",
-  "version": "1.0.13",
-  "description": "",
-  "main": "dist/client.js",
-  "types": "dist/client.d.ts",
+  "version": "2.0.0-rc.10",
+  "description": "Server-side Node.js SDK for the Unshared Labs V2 API",
+  "main": "dist/index.js",
+  "module": "dist/esm/index.mjs",
+  "types": "dist/index.d.ts",
   "scripts": {
     "build": "node scripts/build.js",
     "build:tsc": "tsc",
@@ -17,9 +18,45 @@
     "dist",
     "README.md"
   ],
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./middleware": {
+      "import": "./dist/esm/middleware.mjs",
+      "require": "./dist/middleware.js",
+      "types": "./dist/middleware.d.ts"
+    },
+    "./auto-middleware": {
+      "import": "./dist/esm/middleware/index.mjs",
+      "require": "./dist/middleware/index.js",
+      "types": "./dist/middleware/index.d.ts"
+    },
+    "./middleware/auto": {
+      "import": "./dist/esm/middleware/index.mjs",
+      "require": "./dist/middleware/index.js",
+      "types": "./dist/middleware/index.d.ts"
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  },
   "keywords": [],
   "author": "",
   "license": "MIT",
+  "peerDependencies": {
+    "@types/express": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "@types/express": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "unshared-frontend-sdk": "file:../frontend-sdk"
+  },
   "devDependencies": {
     "@types/express": "^4.17.21",
     "@types/node": "^24.10.1",