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

package/README.md

@@ -1,240 +1,265 @@
 # unshared-clientjs-sdk
 
-Server-side Node.js SDK for [Unshared](https://unshared.ai) — detect account sharing, analyze user events for fraud, and run email verification flows.
-
----
+Node.js SDK for Unshared v3 ingestion, risk checks, email verification, and application protection middleware.
 
 ## Install
 
 ```bash
-npm install unshared-clientjs-sdk
+npm install unshared-clientjs-sdk@^3
 ```
 
-**Requires Node.js 18+**
-
----
-
-## Quick Start
+Requires Node.js 20 or newer.
 
 ```typescript
 import { UnsharedClient } from 'unshared-clientjs-sdk';
 
 const client = new UnsharedClient({
-  apiKey: process.env.UNSHARED_API_KEY, // usk_…
+  apiKey: process.env.UNSHARED_API_KEY!, // usk_...
 });
 ```
 
----
+V3 fingerprint and user-event ingestion encrypts the complete JSON object with AES-256-GCM before sending it to Unshared. Check, Trigger, and Verify remain structured plaintext JSON over HTTPS.
+
+## V3 Methods
 
-## Methods
+### `submitFingerprint(payload)`
+
+Sends any JSON object to `POST /v3/submit-fingerprint-event` without reshaping it.
+
+```typescript
+const result = await client.submitFingerprint({
+  hash: 'full-456',
+  stable_hash: 'stable-123',
+  components: {},
+  custom_data: { nested: ['preserved', 1, false] },
+});
+```
 
-### `processUserEvent(params)`
+### `processUserEvent(payload)`
 
-Record a user event and get a fraud signal back. Call this on login, signup, or any high-value action.
+Sends any JSON object to `POST /v3/process-user-event` without reshaping it.
 
 ```typescript
 const result = await client.processUserEvent({
-  eventType:    'login',
-  userId:       'user_123',
-  emailAddress: 'user@example.com',
-  deviceId:     'device_abc',
-  sessionHash:  'session_xyz',
-  ipAddress:    '1.2.3.4',         // plaintext — not encrypted
-  userAgent:    req.headers['user-agent'],
+  event_type: 'LOGIN',
+  identity: { user_id: user.id, email_address: user.email },
+  identifiers: {
+    unshared_device_id: permanentDeviceId,
+    device_id: deviceId,
+    session_hash: sessionId,
+  },
+  custom_data: { plan: 'pro' },
 });
+```
 
-if (result.success && result.data?.analysis.is_user_flagged) {
-  // Block or challenge the user
+Both ingestion calls accept objects up to 1 MiB and return:
+
+```typescript
+{
+  event_id: string;
+  collected_at: string;
+  endpoint_version: 'v3';
 }
 ```
 
-**Fields encrypted before sending:** `emailAddress`, `deviceId`
-
----
+Ingestion is not automatically retried because an ambiguous failure may already have created an event.
 
-### `checkUser(emailAddress, deviceId)`
+### `checkUser(...)`
 
-Quick check to see if a user is flagged. Useful in middleware or route guards.
+Checks existing risk state through `POST /v3/check-user`.
 
 ```typescript
-const result = await client.checkUser('user@example.com', 'device_abc');
+const result = await client.checkUser('user@example.com', {
+  permanentDeviceId,
+  deviceId,
+  fingerprintId: stableHash,
+  fullHash,
+  sessionHash,
+});
 
 if (result.data?.is_user_flagged) {
-  // Deny access
+  // Block or challenge.
 }
 ```
 
-> **Safe default:** Returns `{ is_user_flagged: false }` on any failure (network error, outage). A backend outage will never accidentally block a legitimate user.
+You can also pass the v3 request object directly:
+
+```typescript
+await client.checkUser({
+  user_id: user.id,
+  email_address: user.email,
+  identifiers: { device_id: deviceId },
+});
+```
 
----
+`checkUser` is read-only and can retry. On transport or HTTP failure it deliberately returns a clean verdict with `failedOpen` metadata so an outage does not accidentally block users.
 
-### `triggerEmailVerification(emailAddress, deviceId)`
+### Email Verification
 
-Send a 6-digit verification code to the user's email.
+Trigger returns a challenge ID that Verify must send back:
 
 ```typescript
-await client.triggerEmailVerification('user@example.com', 'device_abc');
-```
-
----
+const trigger = await client.triggerEmailVerification(user.email, deviceId, {
+  permanentDeviceId,
+  fingerprintId: stableHash,
+});
 
-### `verify(emailAddress, deviceId, code)`
+const verify = await client.verifyEmail({
+  verification_id: trigger.data!.verification_id!,
+  code: submittedCode, // string preserves leading zeroes
+});
+```
 
-Validate the code the user submitted.
+`verifyEmail(...)` is stateless and recommended for distributed deployments. The source-compatible methods retain the challenge in the current `UnsharedClient` instance:
 
 ```typescript
-const result = await client.verify('user@example.com', 'device_abc', '123456');
-
-if (!result.success) {
-  if (result.error?.code === 'VERIFICATION_FAILED') {
-    // Wrong or expired code — ask user to retry
-  } else {
-    // Transport error (DELIVERY_FAILED) — retry or show generic error
-  }
-} else {
-  // Verified — success: true means the code was correct
-}
+await client.triggerEmailVerification(user.email, deviceId);
+const verify = await client.verify(user.email, deviceId, submittedCode);
 ```
 
----
+Trigger and Verify are never automatically retried because the first request may have committed before an ambiguous response failure.
 
-### `submitFingerprintEvent(fingerprint, opts?)`
+## Compatibility Methods
 
-Submit a browser fingerprint collected by `unshared-frontend-sdk`. Typically called by the middleware — you usually won't call this directly.
+Existing v2 package call sites remain valid while using v3 routes and encrypted ingestion envelopes.
 
 ```typescript
-await client.submitFingerprintEvent(fingerprint, {
-  userId:      'user_123',
-  sessionHash: 'session_xyz',
-  eventType:   'page_view',
+const result = await client.processUserEvent({
+  eventType: 'login',
+  userId: user.id,
+  emailAddress: user.email,
+  deviceId,
+  sessionHash: sessionId,
+  ipAddress: req.ip,
+  userAgent: req.headers['user-agent'] ?? '',
 });
+
+if (result.success && result.data?.analysis.is_user_flagged) {
+  // Block or challenge.
+}
 ```
 
----
+`submitFingerprintEvent(fingerprint, opts)` is also retained. New proxy implementations should prefer `submitFingerprint(body)` so unknown future fields cannot be lost.
 
-## Protection Middleware (Recommended)
+## Protection Middleware
 
-`unsharedBoundToUser` is the full-featured middleware: auto-injects the fingerprint script, enforces verdicts, handles email verification flows, and dispatches events.
+`unsharedBoundToUser` injects browser fingerprint collection, protects routes, caches verdicts, and hosts the proxy verification flow.
 
 ```typescript
-import { UnsharedClient, unsharedBoundToUser, flaggedResponse } from 'unshared-clientjs-sdk';
-
+import express from 'express';
+import {
+  UnsharedClient,
+  unsharedBoundToUser,
+  flaggedResponse,
+} from 'unshared-clientjs-sdk';
+
+const app = express();
 app.set('trust proxy', 1);
-app.use(express.json());
+app.use(express.json()); // the default 100 KiB limit is supported
 
 const client = new UnsharedClient({ apiKey: process.env.UNSHARED_API_KEY! });
-
 app.use(unsharedBoundToUser(client, {
-  userId: (req) => req.cookies?.userId,
-  emailAddress: (req) => req.cookies?.email,
-  includePathPrefix: ['/api/'],
+  userId: (req) => req.user?.id,
+  emailAddress: (req) => req.user?.email,
   onFlagged: ({ emailAddress, res }) => {
     res.status(403).json(flaggedResponse(emailAddress));
   },
 }));
 ```
 
-**Smoke test:** `curl http://localhost:3000/__unshared/status` — returns `{ "status": "anonymous" | "ok" | "flagged" }`.
-
-**Key options:**
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `userId` | `(req) => string \| undefined` | — | **Required.** Resolve the current user's ID |
-| `emailAddress` | `(req) => string \| undefined` | — | Resolve the current user's email |
-| `routePrefix` | `string` | `"/__unshared"` | Route mount prefix |
-| `includePathPrefix` | `string[]` | — | Only these path prefixes trigger verdicts and events |
-| `onFlagged` | `(ctx) => void` | — | Called when a flagged user makes a request |
-| `disableBotFilter` | `boolean` | `false` | Skip bot UA filter (enable for E2E testing) |
-| `checkUserTimeoutMs` | `number` | `500` | Timeout (ms) for checkUser API calls; fails open on timeout |
-| `skipPaths` | `string[]` | — | Paths to skip entirely (static assets, health checks) |
-| `corsOrigins` | `string \| string[]` | — | Allowed CORS origins; handles OPTIONS preflight |
-| `onError` | `(error, ctx) => void` | — | Called on background SDK errors for observability |
-
-`flaggedResponse(email)` formats the 403 body the inline script expects to trigger the `unshared:flagged` browser event. `ACCOUNT_FLAGGED_ERROR` is the error code string it uses, also exported for server-side checks.
-
-### Interstitial (proxy mode)
-
-`unsharedBoundToUser` mounts a `GET /__unshared/interstitial-flow` route that returns the company's published interstitial flow. It calls `client.getInterstitialFlow()` with the secret key and carries no user data. The browser SDK's `showInterstitial()` calls this route automatically when constructed with `baseUrl` (proxy mode), then runs the modal's OTP actions through the existing `/__unshared/verify-trigger` and `/__unshared/verify` routes. Identity is resolved server-side via your `emailAddress` resolver or the `__unshared_email` cookie — the browser sends only the OTP.
-
----
-
-## Simple Fingerprint Middleware
-
-`createUnsharedMiddleware` is a lightweight alternative that only proxies fingerprint events — no verdicts, no script injection, no verification flows. Use `unsharedBoundToUser` unless you have a specific reason not to.
+Keep your existing parser order and limits. Mount authentication/session middleware
+needed by your resolvers before Unshared. The SDK also reads its own unparsed POST
+routes automatically, up to **1 MiB (1,048,576 UTF-8 bytes)**, without a configuration
+option or an Express dependency. Ordinary application routes are not parsed by the
+SDK. Existing parsed bodies are respected and checked against the same limit.
+Structured browser-to-proxy submissions (including the inline script) fit Express's
+default **100 KiB (102,400 serialized UTF-8 bytes)** without public configuration:
+send the full payload if it fits; otherwise empty both local/session storage lists
+while keeping every cookie; if still too large, omit `context.browser_storage`.
+The complete raw fingerprint, including future fields, and all core identity,
+device, session, SDK and event context are never trimmed. If those alone exceed
+100 KiB, the browser returns `REQUEST_TOO_LARGE`; the inline script logs that code
+and sends nothing. Cookies are never partially selected or truncated.
+
+Low-level browser `submitFingerprint(payload)` preserves arbitrary objects exactly
+and rejects proxy payloads above 100 KiB rather than reducing them. Direct browser
+submission retains full snapshots and its 1 MiB logical limit. An earlier parser
+or reverse proxy with a smaller limit can still reject a request before Unshared.
+
+Oversized SDK request bodies return 413, malformed JSON returns 400, and unfinished
+reads time out after 30 seconds with 408. Raw bodies must use identity encoding
+(compressed bodies return 415). Fingerprints and retained cookies are not truncated;
+duplicate SDK fingerprint caches are excluded from storage snapshots. The encrypted
+platform request retains its existing 1.5 MiB envelope limit; the full logical payload,
+including server-added context, must still fit within 1 MiB.
+
+| Option | Description |
+|---|---|
+| `userId` | Required server-side user resolver |
+| `emailAddress` | Server-side email resolver used for checks and verification |
+| `routePrefix` | Internal route prefix; default `/__unshared` |
+| `includePathPrefix` | Paths that trigger verdict checks and events |
+| `onFlagged` | Custom blocked-user response |
+| `disableBotFilter` | Include known bot user agents, useful in E2E |
+| `checkUserTimeoutMs` | Bounded verdict-check timeout |
+| `corsOrigins` | Allowed cross-origin frontend origins |
+| `onError` | Background SDK error observer |
+
+The middleware exposes:
+
+- `POST /__unshared/submit-fp`
+- `GET /__unshared/status`
+- `POST /__unshared/verify-trigger`
+- `POST /__unshared/verify`
+- `GET /__unshared/fp.js`
+- `GET /__unshared/interstitial-flow`
+
+The verification trigger stores `verification_id` in an HttpOnly, ten-minute `__unshared_verification_id` cookie. The permanent readable `__unshared_device_id=upid_<uuid-v4>` cookie rolls for 400 days and is not tied to mutable fingerprint hashes.
+
+## Simple Proxy Middleware
+
+`createUnsharedMiddleware` only proxies fingerprint events. It preserves arbitrary fields and augments trusted request context.
 
 ```typescript
-import { createUnsharedMiddleware } from 'unshared-clientjs-sdk';
+import { createUnsharedMiddleware } from 'unshared-clientjs-sdk/middleware';
 
-app.use(express.json());
 app.use(createUnsharedMiddleware(client, {
   userIdExtractor: (req) => req.user?.id,
+  corsOrigins: 'https://app.example.com',
 }));
+app.use(express.json());
 ```
 
-**Options:**
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `userIdExtractor` | `(req) => string \| undefined` | — | Pull user ID from your auth session |
-| `eventTypeExtractor` | `(req) => string \| undefined` | — | Override event type |
-| `sessionIdExtractor` | `(req) => string \| undefined` | — | Override session ID |
-| `ipAddressExtractor` | `(req) => string \| undefined` | — | Override IP address |
-| `defaultEventType` | `string` | `"browser_event"` | Fallback event type |
-| `routePrefix` | `string` | `"/unshared"` | Route mount prefix |
-| `corsOrigins` | `string \| string[]` | — | Allowed CORS origins; handles OPTIONS preflight automatically |
-
-> **Note:** This middleware uses a different default prefix (`/unshared`) and route (`submit-fingerprint-event`) than `unsharedBoundToUser` (`/__unshared`, `submit-fp`).
-
----
+Its default route is `POST /unshared/submit-fingerprint-event`.
 
-## Web / Edge Handler
+## Web Standard Handler
 
-For serverless and edge environments (Next.js App Router, Vercel Edge Functions, Cloudflare Workers), import from the `unshared-clientjs-sdk/web` entry point:
+Use the edge/serverless entry point with Next.js, Cloudflare Workers, Vercel Edge, or other Web Standard runtimes:
 
 ```typescript
 import { createWebProtectionMiddleware } from 'unshared-clientjs-sdk/web';
 ```
 
-`createWebProtectionMiddleware` accepts the same `disableBotFilter` and `checkUserTimeoutMs` options as `unsharedBoundToUser`, with Web Standard `Request`/`Response` types instead of Express ones.
+It mirrors the protection and verification behavior using `Request` and `Response`.
 
----
-
-## Configuration
-
-```typescript
-new UnsharedClient({
-  apiKey:     'usk_…',                               // required
-  baseUrl:    'https://api.unshared.ai', // optional
-  timeout:    10_000,                                 // optional, ms
-  maxRetries: 3,                                      // optional
-});
-```
-
----
-
-## Response shape
-
-All methods return `ApiResult<T>`:
+## Result and Error Handling
 
 ```typescript
-{
+type ApiResult<T> = {
   success: boolean;
-  data?:   T;
-  error?:  { code: string; message: string; retryAfter?: number };
-  status:  number; // HTTP status code
-}
+  status: number; // 0 for a network failure
+  data?: T;
+  error?: {
+    code: string;
+    message: string;
+    retryAfter?: number;
+  };
+  failedOpen?: { status: number; reason?: 'no_device_id' };
+};
 ```
 
----
-
-## Security
-
-All PII is encrypted with **AES-256-GCM** before leaving your server. The encryption key is derived from your API key with SHA-256. Your API key is sent as the `X-API-Key` header — never in a URL or browser context.
-
----
-
-## See Also
-
-- [Quickstart](./docs/quickstart.md) — step-by-step Express setup from zero
-- [Flag semantics and testing](./docs/flag-semantics.md) — how flags work, E2E testing tips, timeout behavior
+- Success requires a valid `{ success: true, data }` response envelope.
+- Bodies larger than 1 MiB fail locally with `REQUEST_TOO_LARGE`.
+- `Retry-After` is exposed as `error.retryAfter` on 429 responses.
+- Protected same-origin submission routes never return 5xx to browser code.
+- Keep the secret API key server-side and exclude logical identity/event bodies from request logs before SDK encryption.

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { FingerprintWireFormat } from '@unshared-labs/shared-types';
+import type { CheckUserRequest, CheckUserResult as V3CheckUserResult, FingerprintWireFormat, IngestResult, JSONObject, VerifyEmailRequest, VerifyEmailResult } from './shared-types';
 export interface UnsharedClientConfig {
     /**
      * Secret API key. Must be kept server-side.
@@ -6,7 +6,7 @@ export interface UnsharedClientConfig {
      */
     apiKey: string;
     /**
-     * Base URL of the Unshared Labs V2 ingress.
+     * Base URL of the Unshared Labs ingress.
      * @default "https://api.unshared.ai"
      */
     baseUrl?: string;
@@ -70,14 +70,15 @@ export interface ApiResult<T = unknown> {
 }
 export interface SubmitFingerprintOptions {
     userId?: string;
-    /** SDK encrypts before sending. */
     emailAddress?: string;
     sessionHash?: string;
     eventType?: string;
-    /** SDK encrypts before sending. */
     ipAddress?: string;
-    /** SDK encrypts before sending. */
     userAgent?: string;
+    permanentDeviceId?: string;
+    deviceId?: string;
+    stableHash?: string;
+    fullHash?: string;
     /**
      * Client-supplied idempotency key, forwarded verbatim as X-Idempotency-Key.
      * NOTE: the middleware that calls this (submit-fp.ts / protection-handler.ts)
@@ -92,25 +93,21 @@ export interface SubmitFingerprintOptions {
 export interface SubmitFingerprintResult {
     hash: string;
     stable_hash: string;
-    collected_at: string;
-    /** Always present; set to "unknown" by the server if not provided. */
     version: string;
+    event_id: string;
+    collected_at: string;
+    endpoint_version: 'v3';
 }
 export interface ProcessUserEventParams {
     eventType: string;
-    /** SDK encrypts before sending. */
     userId: string;
-    /** SDK encrypts before sending. */
     ipAddress: string;
-    /** SDK encrypts before sending. */
     deviceId: string;
     sessionHash: string;
-    /** SDK encrypts before sending. */
     userAgent: string;
-    /** SDK encrypts before sending. */
     emailAddress: string;
-    /** SDK encrypts before sending. */
     fingerprintId?: string;
+    permanentDeviceId?: string;
     subscriptionStatus?: string | null;
     eventDetails?: Record<string, unknown> | null;
 }
@@ -121,6 +118,7 @@ export interface ProcessUserEventResult {
         email_address: string;
         ip_address: string;
         device_id: string;
+        permanent_device_id?: string;
         session_hash: string;
         user_agent: string;
         event_details?: string;
@@ -134,25 +132,31 @@ export interface ProcessUserEventResult {
 }
 export interface CheckUserResult {
     is_user_flagged: boolean;
+    /** Present on authoritative v3 responses; omitted by local fail-open defaults. */
+    decision_id?: string;
+    /** Present on authoritative v3 responses; omitted by local fail-open defaults. */
+    decision_code?: V3CheckUserResult['decision_code'];
 }
 export interface TriggerEmailVerificationResult {
     message: string;
+    verification_id?: string;
+    next_allowed_at?: string;
+    retry_after_seconds?: number;
 }
 export interface VerifyResult {
     verified: boolean;
-    reason?: 'not_found' | 'code_mismatch' | 'code_expired';
+    reason?: 'not_found' | 'code_mismatch' | 'code_expired' | 'invalid_code';
+    verification_scope?: 'email';
 }
 export declare class UnsharedClient {
     private readonly _apiKey;
     private readonly _baseUrl;
     private readonly _timeout;
     private readonly _maxRetries;
-    private _encryptionKey;
     private readonly _customFetch;
+    private _ingestionKey?;
+    private readonly _verificationIds;
     constructor(config: UnsharedClientConfig);
-    /** Lazily derive + memoize the imported AES-GCM CryptoKey (async via WebCrypto). */
-    private _getKey;
-    private _encrypt;
     /**
      * Core HTTP method with retry logic.
      * - 2xx → success result
@@ -161,22 +165,33 @@ export declare class UnsharedClient {
      * - Network/timeout → retried, NETWORK_ERROR result returned
      */
     private _fetch;
+    private _postIngestion;
+    /** Submit an arbitrary v3 fingerprint payload without reshaping it. */
+    submitFingerprint(payload: JSONObject, opts?: {
+        idempotencyKey?: string;
+    }): Promise<ApiResult<IngestResult>>;
     /**
-     * Submit a browser fingerprint event. Publishes asynchronously via Pub/Sub.
-     * Maps to: POST /v2/submit-fingerprint-event
+     * Submit a browser fingerprint event using the source-compatible v2 method.
+     * The wire payload and endpoint use the v3 contract.
      */
     submitFingerprintEvent(fingerprint: FingerprintWireFormat, opts?: SubmitFingerprintOptions): Promise<ApiResult<SubmitFingerprintResult>>;
     /**
-     * Record a user event and receive naughty-list analysis.
-     * Maps to: POST /v2/process-user-event
+     * Record a user event and receive the current risk decision.
+     * Maps to: POST /v3/process-user-event followed by POST /v3/check-user.
      */
     processUserEvent(params: ProcessUserEventParams, overrides?: {
         timeoutMs?: number;
         maxRetries?: number;
     }): Promise<ApiResult<ProcessUserEventResult>>;
+    processUserEvent(payload: JSONObject, overrides?: {
+        timeoutMs?: number;
+        maxRetries?: number;
+    }): Promise<ApiResult<IngestResult>>;
     /**
      * Check if a user is flagged in the naughty list.
-     * Maps to: GET /v2/check-user
+     * Maps to: POST /v3/check-user
+     * Requires a nonblank email_address; user_id cannot replace it. Invalid email
+     * returns a local VALIDATION_ERROR without making a request.
      *
      * **Defensive default:** On any failure (network error, 4xx, 5xx, timeout) this
      * method returns `{ success: true, data: { is_user_flagged: false } }` rather
@@ -190,19 +205,29 @@ export declare class UnsharedClient {
     checkUser(emailAddress: string, opts: {
         deviceId?: string;
         fingerprintId?: string;
+        permanentDeviceId?: string;
+        fullHash?: string;
+        sessionHash?: string;
+        timeoutMs?: number;
+        maxRetries?: number;
+    }): Promise<ApiResult<CheckUserResult>>;
+    checkUser(request: CheckUserRequest, opts?: {
         timeoutMs?: number;
         maxRetries?: number;
     }): Promise<ApiResult<CheckUserResult>>;
     /**
      * Send a 6-digit verification code to the user's email address.
-     * Maps to: POST /v2/trigger-email-verification
+     * Maps to: POST /v3/trigger-email-verification
      */
     triggerEmailVerification(emailAddress: string, deviceId: string, opts?: {
         fingerprintId?: string;
+        permanentDeviceId?: string;
+        fullHash?: string;
+        sessionHash?: string;
     }): Promise<ApiResult<TriggerEmailVerificationResult>>;
     /**
      * Verify a 6-digit code submitted by the user.
-     * Maps to: POST /v2/verify
+     * Maps to: POST /v3/verify
      *
      * `result.success` reliably indicates whether verification succeeded:
      * - `success: true`  → code was correct, user is verified
@@ -219,7 +244,11 @@ export declare class UnsharedClient {
      */
     verify(emailAddress: string, deviceId: string, code: string, opts?: {
         fingerprintId?: string;
+        permanentDeviceId?: string;
+        verificationId?: string;
     }): Promise<ApiResult<VerifyResult>>;
+    /** Verify a v3 email challenge without relying on process-local state. */
+    verifyEmail(request: VerifyEmailRequest): Promise<ApiResult<VerifyEmailResult>>;
     /**
      * Fetch the published interstitial flow for this company (secret key, server-side).
      * Returns the projected flow definition to hand to the browser for rendering.