unshared-clientjs-sdk 2.0.0-rc.2 → 2.0.0-rc.21

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

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

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

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

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/cookies.d.ts

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

package/dist/middleware/utils/cookies.js

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

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

@@ -0,0 +1,5 @@
+import type { Request } from 'express';
+/**
+ * Resolves device ID from: custom resolver → __unshared_fp_id cookie → X-Device-Id header.
+ */
+export declare function extractDeviceId(req: Request, resolveDeviceId?: (req: Request) => string | undefined): string;

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

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

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/secure.d.ts

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

package/dist/middleware/utils/secure.js

@@ -0,0 +1 @@
+"use strict";function isSecureRequest(e){return e.secure||"https"===e.headers["x-forwarded-proto"]}Object.defineProperty(exports,"t",{value:!0}),exports.isSecureRequest=isSecureRequest;

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",".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,47 @@
+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;
+    private readonly _maxSize;
+    private _sweepTimer;
+    constructor(defaultTTL?: number, maxSize?: 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;
+    /**
+     * Stops the periodic sweep timer. Call this when shutting down
+     * or when the middleware is no longer needed (e.g., in tests).
+     */
+    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. */
+    private _evictOldest;
+}

package/dist/middleware/verdict-cache.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.VerdictCache=void 0;const DEFAULT_TTL_MS=6e4,DEFAULT_MAX_SIZE=1e4,SWEEP_INTERVAL_MS=3e5;class VerdictCache{constructor(t=6e4,s=1e4){this.i=new Map,this.h=new Set,this.o=null,this.l=t,this.u=s,this.o=setInterval(()=>this._(),3e5),this.o&&"function"==typeof this.o.unref&&this.o.unref()}get(t){return this.i.get(t)}set(t,s,e){!this.i.has(t)&&this.i.size>=this.u&&this.p(),this.i.set(t,{...s,cachedAt:Date.now(),ttl:e??this.l})}update(t,s){const e=this.i.get(t);e?(void 0!==s.isFlagged&&(e.isFlagged=s.isFlagged),void 0!==s.isVerified&&(e.isVerified=s.isVerified),e.cachedAt=Date.now()):(this.i.size>=this.u&&this.p(),this.i.set(t,{isFlagged:s.isFlagged??!1,isVerified:s.isVerified??!1,emailAddress:"",sessionId:"",cachedAt:Date.now(),ttl:this.l}))}delete(t){this.i.delete(t),this.h.delete(t)}isStale(t){const s=this.i.get(t);return!!s&&Date.now()-s.cachedAt>s.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()}destroy(){this.o&&(clearInterval(this.o),this.o=null),this.clear()}_(){const t=Date.now();for(const[s,e]of this.i)t-e.cachedAt>2*e.ttl&&(this.i.delete(s),this.h.delete(s))}p(){let t=null,s=1/0;for(const[e,i]of this.i)i.cachedAt<s&&(s=i.cachedAt,t=e);t&&(this.i.delete(t),this.h.delete(t))}}exports.VerdictCache=VerdictCache;

package/dist/middleware.d.ts

@@ -1,4 +1,4 @@
-import type { Request, Response, NextFunction } from 'express';
+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. */
@@ -7,6 +7,8 @@ export interface MiddlewareOptions {
     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;
     /**
@@ -14,7 +16,30 @@ export interface MiddlewareOptions {
      * @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).
@@ -25,10 +50,10 @@ export interface MiddlewareOptions {
  * **Prerequisites:**
  * - Mount `express.json()` (or equivalent body-parser) **before** this middleware,
  *   otherwise `req.body` will be undefined and every request will return 400.
- * - Configure CORS on your `/unshared/*` routes separately — this middleware
- *   does not set any `Access-Control-*` headers.
- * - Disable request body logging on `/unshared/*` routes. `user_id` arrives in
- *   plaintext from the browser and must not be captured by logging middleware.
+ * - 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" } }.

package/dist/middleware.js

@@ -1 +1 @@
-"use strict";function createUnsharedMiddleware(e,r){const{userIdExtractor:s,eventTypeExtractor:t,sessionIdExtractor:c,defaultEventType:n="browser_event",routePrefix:o="/unshared"}=r??{},a=`${o}/submit-fingerprint-event`;return async(r,o,i)=>{if("POST"===r.method&&r.path===a)try{const a=r.body??{};if(!a.hash||!a.stable_hash||!a.collected_at)return void o.status(400).json({success:!1,error:{code:"VALIDATION_ERROR",message:"Missing required fingerprint fields: hash, stable_hash, collected_at"}});const i={full_hash:a.hash,fingerprint_id:a.stable_hash,timestamp:a.collected_at,isIncognito:a.is_incognito??!1,components:a.components??{},version:a.version??"unknown"};let d,u,l;try{d=(s?s(r):void 0)??a.user_id}catch{d=a.user_id}try{u=(t?t(r):void 0)??a.event_type??n}catch{u=a.event_type??n}try{l=(c?c(r):void 0)??r.headers["x-session-id"]?.toString()??a.session_id}catch{l=r.headers["x-session-id"]?.toString()??a.session_id}const h=await e.submitFingerprintEvent(i,{userId:d,sessionHash:l,eventType:u});if(!h.success)return void o.status(200).json({success:!1,error:{code:"UPSTREAM_ERROR",message:h.error?.message??"Upstream request failed"}});o.status(202).json({success:!0,data:h.data})}catch(e){o.status(200).json({success:!1,error:{code:"MIDDLEWARE_ERROR",message:e instanceof Error?e.message:"Middleware error"}})}else i()}}Object.defineProperty(exports,"t",{value:!0}),exports.createUnsharedMiddleware=createUnsharedMiddleware;
+"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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unshared-clientjs-sdk",
-  "version": "2.0.0-rc.2",
+  "version": "2.0.0-rc.21",
   "description": "Server-side Node.js SDK for the Unshared Labs V2 API",
   "main": "dist/index.js",
   "module": "dist/esm/index.mjs",
@@ -28,6 +28,16 @@
       "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": {
@@ -44,6 +54,9 @@
       "optional": true
     }
   },
+  "dependencies": {
+    "unshared-frontend-sdk": "2.0.0-rc.21"
+  },
   "devDependencies": {
     "@types/express": "^4.17.21",
     "@types/node": "^24.10.1",