vesant-sdk 1.7.0 → 1.7.1-dev.301c6df

package/dist/{client-BolQlL5e.d.ts → client-q9fN8Hhf.d.ts}

@@ -50,6 +50,80 @@ declare class CircuitBreaker {
     reset(): void;
 }
 
+/**
+ * Pluggable authentication for BaseClient.
+ *
+ * A TokenProvider supplies the credential used for the Authorization header on
+ * every request, resolved per-request (async) so callers can source short-lived
+ * or rotating credentials (OAuth2 client-credentials, STS, Vault / Secrets
+ * Manager) instead of a single static API key. The default StaticApiKeyProvider
+ * preserves the original `apiKey` behavior with zero change for existing callers.
+ */
+interface AuthCredential {
+    /** Authorization scheme (e.g. 'Bearer'); defaults to 'Bearer' when omitted. */
+    scheme?: string;
+    /** The credential value (bearer token / API key). */
+    token: string;
+}
+interface TokenProviderContext {
+    tenantId: string;
+    requestId: string;
+    /** When true, bypass any cache and obtain a fresh credential (e.g. after a 401). */
+    forceRefresh?: boolean;
+}
+interface TokenProvider {
+    /** Resolve the credential for a request, or null to send no Authorization header. */
+    getCredential(ctx: TokenProviderContext): Promise<AuthCredential | null>;
+    /** Whether this provider can obtain a fresh credential on demand (drives 401 retry). */
+    canRefresh?(): boolean;
+}
+/**
+ * Default provider: wraps a static API key. Returns null when the key is empty
+ * so the client sends no Authorization header, matching the pre-provider behavior.
+ */
+declare class StaticApiKeyProvider implements TokenProvider {
+    private readonly apiKey;
+    constructor(apiKey: string);
+    getCredential(): Promise<AuthCredential | null>;
+    canRefresh(): boolean;
+}
+interface CachedToken {
+    token: string;
+    expiresAt?: number;
+}
+interface RefreshingTokenProviderOptions {
+    /** Fetches a fresh token. `expiresAt` is epoch milliseconds (optional). */
+    fetchToken: () => Promise<CachedToken>;
+    /** Refresh this many ms before expiry (default: 30_000). */
+    skewMs?: number;
+    /** Authorization scheme to emit (default: 'Bearer'). */
+    scheme?: string;
+    /** Observe each successful (re)fetch — for logging / metrics. */
+    onRotate?: (meta: {
+        expiresAt?: number;
+    }) => void;
+    /** Injectable clock (default: Date.now). */
+    now?: () => number;
+}
+/**
+ * Caches a fetched token and refreshes it when it is within the skew window of
+ * expiry or when `forceRefresh` is requested. Concurrent refreshes are de-duped
+ * into a single in-flight fetch.
+ */
+declare class RefreshingTokenProvider implements TokenProvider {
+    private readonly opts;
+    private cached;
+    private inFlight;
+    private readonly skewMs;
+    private readonly scheme;
+    private readonly now;
+    constructor(opts: RefreshingTokenProviderOptions);
+    canRefresh(): boolean;
+    getCredential(ctx?: TokenProviderContext): Promise<AuthCredential | null>;
+    private isExpiring;
+    private refresh;
+}
+
 /**
  * Configuration types for Vesant SDK clients
  */
@@ -82,6 +156,16 @@ interface BaseClientConfig {
     tenantId: string;
     /** Optional API key for authentication */
     apiKey?: string;
+    /**
+     * Pluggable auth token provider. When set, it supplies the Authorization
+     * credential per-request (overriding `apiKey`), enabling OAuth2 / STS / rotating
+     * secrets and single-shot 401 re-auth. Defaults to a static-apiKey provider.
+     */
+    authProvider?: TokenProvider;
+    /** Observe credential rotation triggered by a 401 re-auth (logging / metrics). */
+    onCredentialRotated?: (meta: {
+        reason: string;
+    }) => void;
     /** Custom headers to include in all requests */
     headers?: Record<string, string>;
     /** Request timeout in milliseconds (default: 10000) */
@@ -108,6 +192,16 @@ interface VesantConfig {
     tenantId: string;
     /** Optional API key for authentication */
     apiKey?: string;
+    /**
+     * Pluggable auth token provider. When set, it supplies the Authorization
+     * credential per-request (overriding `apiKey`), enabling OAuth2 / STS / rotating
+     * secrets and single-shot 401 re-auth. Defaults to a static-apiKey provider.
+     */
+    authProvider?: TokenProvider;
+    /** Observe credential rotation triggered by a 401 re-auth (logging / metrics). */
+    onCredentialRotated?: (meta: {
+        reason: string;
+    }) => void;
     /** Custom headers to include in all requests */
     headers?: Record<string, string>;
     /** Request timeout in milliseconds (default: 10000) */
@@ -195,7 +289,15 @@ declare abstract class BaseClient {
     private interceptors;
     private circuitBreaker;
     private rateLimitTracker;
+    private authProvider;
     constructor(config: BaseClientConfig);
+    /**
+     * Resolve the Idempotency-Key for a request. Mutating methods (POST/PUT/PATCH)
+     * get the caller-supplied key or a freshly minted UUID; non-mutating methods get
+     * none. requestWithRetry resolves this once and injects it so every retry reuses
+     * one key (letting the server dedup replays); a direct request() resolves per call.
+     */
+    private resolveIdempotencyKey;
     /**
      * Make an HTTP request with timeout and error handling
      */
@@ -237,4 +339,4 @@ declare abstract class BaseClient {
     }>;
 }
 
-export { BaseClient as B, type CGSConfig as C, type Logger as L, type RequestOptions as R, type VesantConfig as V, type BaseClientConfig as a, CircuitBreaker as b, type CircuitBreakerConfig as c, type CircuitBreakerState as d, type CircuitBreakerStatus as e, type RateLimitStatus as f, RateLimitTracker as g, type RequestInterceptor as h, type RequiredBaseClientConfig as i, type RequiredCGSConfig as j, type RequiredVesantConfig as k };
+export { type AuthCredential as A, BaseClient as B, type CGSConfig as C, type Logger as L, type RequestOptions as R, StaticApiKeyProvider as S, type TokenProvider as T, type VesantConfig as V, type BaseClientConfig as a, CircuitBreaker as b, type CircuitBreakerConfig as c, type CircuitBreakerState as d, type CircuitBreakerStatus as e, type RateLimitStatus as f, RateLimitTracker as g, RefreshingTokenProvider as h, type RefreshingTokenProviderOptions as i, type RequestInterceptor as j, type RequiredBaseClientConfig as k, type RequiredCGSConfig as l, type RequiredVesantConfig as m, type TokenProviderContext as n };

package/dist/compliance/index.d.mts

@@ -1,8 +1,8 @@
 import { B as BlockReason } from '../types-CBQRNL-l.mjs';
-export { C as ComplianceClient, a as ComplianceLocationRequestInput, b as ComplianceLocationRequestResult, c as CurrencyRates, D as DEFAULT_CURRENCY_RATES, E as EventVerificationRequest, d as EventVerificationResponse, L as LoginVerificationRequest, e as LoginVerificationResponse, R as RegistrationVerificationRequest, f as RegistrationVerificationResponse, T as TransactionRiskResult, g as TransactionVerificationRequest, h as TransactionVerificationResponse } from '../client-B0qhE2kr.mjs';
-export { p as CreateLocationRequestRequest, H as LocationCaptureRequest, I as LocationCaptureResponse, a as LocationRequest, K as LocationRequestChannel, b as LocationRequestFilters, c as LocationRequestListResponse, M as LocationRequestResult, N as LocationRequestStatus, O as LocationShareInfo, R as ResendLocationRequestRequest } from '../client-DrjgZoH_.mjs';
+export { C as ComplianceClient, a as ComplianceLocationRequestInput, b as ComplianceLocationRequestResult, c as CurrencyRates, D as DEFAULT_CURRENCY_RATES, E as EventVerificationRequest, d as EventVerificationResponse, L as LoginVerificationRequest, e as LoginVerificationResponse, R as RegistrationVerificationRequest, f as RegistrationVerificationResponse, T as TransactionRiskResult, g as TransactionVerificationRequest, h as TransactionVerificationResponse } from '../client-D23KhWeh.mjs';
+export { p as CreateLocationRequestRequest, I as LocationCaptureRequest, K as LocationCaptureResponse, a as LocationRequest, M as LocationRequestChannel, b as LocationRequestFilters, c as LocationRequestListResponse, N as LocationRequestResult, O as LocationRequestStatus, P as LocationShareInfo, R as ResendLocationRequestRequest } from '../client-BwXMQA2a.mjs';
 import '../risk-profile/index.mjs';
-import '../client-BolQlL5e.mjs';
+import '../client-q9fN8Hhf.mjs';
 import '../types-BOFaMQxI.mjs';
 
 declare const sdkReasons: {

package/dist/compliance/index.d.ts

@@ -1,8 +1,8 @@
 import { B as BlockReason } from '../types-CBQRNL-l.js';
-export { C as ComplianceClient, a as ComplianceLocationRequestInput, b as ComplianceLocationRequestResult, c as CurrencyRates, D as DEFAULT_CURRENCY_RATES, E as EventVerificationRequest, d as EventVerificationResponse, L as LoginVerificationRequest, e as LoginVerificationResponse, R as RegistrationVerificationRequest, f as RegistrationVerificationResponse, T as TransactionRiskResult, g as TransactionVerificationRequest, h as TransactionVerificationResponse } from '../client-DtH2RLuy.js';
-export { p as CreateLocationRequestRequest, H as LocationCaptureRequest, I as LocationCaptureResponse, a as LocationRequest, K as LocationRequestChannel, b as LocationRequestFilters, c as LocationRequestListResponse, M as LocationRequestResult, N as LocationRequestStatus, O as LocationShareInfo, R as ResendLocationRequestRequest } from '../client-DF7hlMEz.js';
+export { C as ComplianceClient, a as ComplianceLocationRequestInput, b as ComplianceLocationRequestResult, c as CurrencyRates, D as DEFAULT_CURRENCY_RATES, E as EventVerificationRequest, d as EventVerificationResponse, L as LoginVerificationRequest, e as LoginVerificationResponse, R as RegistrationVerificationRequest, f as RegistrationVerificationResponse, T as TransactionRiskResult, g as TransactionVerificationRequest, h as TransactionVerificationResponse } from '../client-B3DCAHlg.js';
+export { p as CreateLocationRequestRequest, I as LocationCaptureRequest, K as LocationCaptureResponse, a as LocationRequest, M as LocationRequestChannel, b as LocationRequestFilters, c as LocationRequestListResponse, N as LocationRequestResult, O as LocationRequestStatus, P as LocationShareInfo, R as ResendLocationRequestRequest } from '../client-fy3trF2K.js';
 import '../risk-profile/index.js';
-import '../client-BolQlL5e.js';
+import '../client-q9fN8Hhf.js';
 import '../types-UGyDl1fd.js';
 
 declare const sdkReasons: {

package/dist/compliance/index.js

@@ -75,6 +75,19 @@ var sdkReasons = {
   })
 };
 
+// src/core/auth.ts
+var StaticApiKeyProvider = class {
+  constructor(apiKey) {
+    this.apiKey = apiKey;
+  }
+  async getCredential() {
+    return this.apiKey ? { scheme: "Bearer", token: this.apiKey } : null;
+  }
+  canRefresh() {
+    return false;
+  }
+};
+
 // src/core/errors.ts
 var VesantError = class _VesantError extends Error {
   constructor(message, code, statusCode, details) {
@@ -299,7 +312,7 @@ function createConsoleLogger() {
 }
 
 // src/core/version.ts
-var SDK_VERSION = "1.7.0";
+var SDK_VERSION = "1.7.1";
 
 // src/shared/browser-utils.ts
 function generateUUID() {
@@ -381,6 +394,12 @@ var BaseClient = class {
     if (!config.tenantId?.trim()) {
       throw new ValidationError("tenantId is required and must be a non-empty string", ["tenantId"]);
     }
+    if (typeof fetch === "undefined") {
+      throw new VesantError(
+        "The Vesant SDK requires a global fetch (Node.js >= 18). Upgrade Node or provide a fetch polyfill.",
+        "RUNTIME_UNSUPPORTED"
+      );
+    }
     this.interceptors = config.interceptors || [];
     this.logger = config.logger || createConsoleLogger();
     let environment = config.environment;
@@ -399,11 +418,12 @@ var BaseClient = class {
       environment,
       headers: config.headers || {},
       timeout: config.timeout || 1e4,
-      retries: config.retries || 3,
+      retries: config.retries ?? 3,
       debug: config.debug || false,
       interceptors: this.interceptors,
       logger: this.logger
     };
+    this.authProvider = config.authProvider ?? (apiKey ? new StaticApiKeyProvider(apiKey) : void 0);
     if (config.circuitBreaker) {
       this.circuitBreaker = new CircuitBreaker(config.circuitBreaker);
     }
@@ -411,6 +431,19 @@ var BaseClient = class {
       this.rateLimitTracker = new RateLimitTracker();
     }
   }
+  /**
+   * Resolve the Idempotency-Key for a request. Mutating methods (POST/PUT/PATCH)
+   * get the caller-supplied key or a freshly minted UUID; non-mutating methods get
+   * none. requestWithRetry resolves this once and injects it so every retry reuses
+   * one key (letting the server dedup replays); a direct request() resolves per call.
+   */
+  resolveIdempotencyKey(method, requestOptions) {
+    const isMutating = ["POST", "PUT", "PATCH"].includes((method || "GET").toUpperCase());
+    if (!isMutating) {
+      return void 0;
+    }
+    return requestOptions?.idempotencyKey ?? generateUUID();
+  }
   /**
    * Make an HTTP request with timeout and error handling
    */
@@ -436,15 +469,20 @@ var BaseClient = class {
       ...this.config.headers,
       ...options.headers || {}
     };
-    if (this.config.apiKey) {
-      headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+    const credential = await this.authProvider?.getCredential({
+      tenantId: this.config.tenantId,
+      requestId
+    });
+    if (credential) {
+      headers["Authorization"] = `${credential.scheme ?? "Bearer"} ${credential.token}`;
     }
     if (this.config.environment === "sandbox") {
       headers["X-Sandbox"] = "true";
     }
     const method = (options.method || "GET").toUpperCase();
-    if (["POST", "PUT", "PATCH"].includes(method)) {
-      headers["Idempotency-Key"] = requestOptions?.idempotencyKey || generateUUID();
+    const idempotencyKey = this.resolveIdempotencyKey(method, requestOptions);
+    if (idempotencyKey) {
+      headers["Idempotency-Key"] = idempotencyKey;
     }
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
@@ -465,10 +503,28 @@ var BaseClient = class {
       if (this.config.debug) {
         this.logger.debug(`${finalOptions.method || "GET"} ${endpoint}`);
       }
-      const response = await fetch(url, {
+      let response = await fetch(url, {
         ...finalOptions,
         signal: controller.signal
       });
+      if (response.status === 401 && this.authProvider?.canRefresh?.()) {
+        const refreshed = await this.authProvider.getCredential({
+          tenantId: this.config.tenantId,
+          requestId,
+          forceRefresh: true
+        });
+        if (refreshed) {
+          this.config.onCredentialRotated?.({ reason: "unauthorized" });
+          finalOptions = {
+            ...finalOptions,
+            headers: {
+              ...finalOptions.headers,
+              Authorization: `${refreshed.scheme ?? "Bearer"} ${refreshed.token}`
+            }
+          };
+          response = await fetch(url, { ...finalOptions, signal: controller.signal });
+        }
+      }
       clearTimeout(timeoutId);
       if (this.rateLimitTracker) {
         this.rateLimitTracker.updateFromHeaders(response.headers);
@@ -557,9 +613,11 @@ var BaseClient = class {
    */
   async requestWithRetry(endpoint, options = {}, serviceURL, retries = this.config.retries, requestOptions) {
     let lastError;
+    const idempotencyKey = this.resolveIdempotencyKey(options.method || "GET", requestOptions);
+    const attemptOptions = idempotencyKey ? { ...requestOptions, idempotencyKey } : requestOptions;
     for (let attempt = 0; attempt <= retries; attempt++) {
       try {
-        return await this.request(endpoint, options, serviceURL, requestOptions);
+        return await this.request(endpoint, options, serviceURL, attemptOptions);
       } catch (error) {
         lastError = error instanceof Error ? error : new Error("Unknown error");
         if (requestOptions?.signal?.aborted) {
@@ -656,6 +714,9 @@ var BaseClient = class {
     if (config.interceptors) {
       this.interceptors = config.interceptors;
     }
+    if (config.authProvider !== void 0 || config.apiKey !== void 0) {
+      this.authProvider = this.config.authProvider ?? (this.config.apiKey ? new StaticApiKeyProvider(this.config.apiKey) : void 0);
+    }
   }
   /**
    * Get current configuration (readonly)
@@ -683,27 +744,63 @@ var BaseClient = class {
   }
 };
 
-// src/geolocation/ciphertext.ts
-var CIPHER_TEXT_EXPIRY_MINUTES = 5;
-async function computeHMAC(key, message) {
-  if (typeof globalThis.crypto !== "undefined" && globalThis.crypto.subtle) {
-    const encoder = new TextEncoder();
-    const keyData = encoder.encode(key);
-    const msgData = encoder.encode(message);
-    const cryptoKey = await globalThis.crypto.subtle.importKey(
-      "raw",
-      keyData,
-      { name: "HMAC", hash: "SHA-256" },
-      false,
-      ["sign"]
-    );
-    const signature = await globalThis.crypto.subtle.sign("HMAC", cryptoKey, msgData);
-    const bytes = new Uint8Array(signature);
-    return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+// src/geolocation/integrity.ts
+var isNil = (v) => v === null || v === void 0;
+function assessGpsIntegrity(input, opts = {}) {
+  const flags = [];
+  const now = opts.now ?? (() => Date.now());
+  const maxAgeMs = opts.maxAgeMs ?? 6e4;
+  const minAccuracy = opts.minAccuracyMeters ?? 1;
+  const { accuracy, altitude, altitudeAccuracy, heading, speed, timestamp } = input;
+  if (isNil(accuracy)) {
+    flags.push("accuracy_missing");
+  } else if (accuracy === 0) {
+    flags.push("accuracy_zero");
+  } else if (accuracy < minAccuracy) {
+    flags.push("accuracy_implausibly_small");
+  }
+  const hasMotion = !isNil(heading) || !isNil(speed);
+  if (hasMotion && (isNil(accuracy) || accuracy === 0)) {
+    flags.push("motion_without_accuracy");
+  }
+  if (!isNil(altitude) && isNil(altitudeAccuracy)) {
+    flags.push("altitude_without_accuracy");
+  }
+  if (timestamp !== void 0 && now() - timestamp > maxAgeMs) {
+    flags.push("stale_timestamp");
+  }
+  if (opts.permissionState === "denied" || opts.permissionState === "prompt") {
+    flags.push(`permission_${opts.permissionState}`);
+  }
+  return { suspicious: flags.length > 0, flags };
+}
+function gpsIntegrityInputFromPosition(position) {
+  const c = position.coords;
+  return {
+    latitude: c.latitude,
+    longitude: c.longitude,
+    accuracy: c.accuracy,
+    altitude: c.altitude,
+    altitudeAccuracy: c.altitudeAccuracy,
+    heading: c.heading,
+    speed: c.speed,
+    timestamp: position.timestamp
+  };
+}
+async function probeGeolocationPermission() {
+  try {
+    if (typeof navigator === "undefined" || !navigator.permissions?.query) {
+      return "unavailable";
+    }
+    const status = await navigator.permissions.query({ name: "geolocation" });
+    return status.state;
+  } catch {
+    return "unavailable";
   }
-  const { createHmac } = await import('crypto');
-  return createHmac("sha256", key).update(message).digest("hex");
 }
+
+// src/geolocation/ciphertext.ts
+var CIPHER_TEXT_EXPIRY_MINUTES = 5;
 function getWebGLInfo() {
   if (typeof document === "undefined") return null;
   try {
@@ -735,6 +832,7 @@ async function requestGPSLocation(timeout = 1e4, highAccuracy = true) {
   if (typeof navigator === "undefined" || !navigator.geolocation) {
     return null;
   }
+  const permissionState = await probeGeolocationPermission();
   return new Promise((resolve) => {
     navigator.geolocation.getCurrentPosition(
       (position) => {
@@ -751,6 +849,7 @@ async function requestGPSLocation(timeout = 1e4, highAccuracy = true) {
           resolve(null);
           return;
         }
+        const { flags } = assessGpsIntegrity(gpsIntegrityInputFromPosition(position), { permissionState });
         resolve({
           latitude,
           longitude,
@@ -759,7 +858,8 @@ async function requestGPSLocation(timeout = 1e4, highAccuracy = true) {
           altitude_accuracy: position.coords.altitudeAccuracy ?? void 0,
           heading: position.coords.heading ?? void 0,
           speed: position.coords.speed ?? void 0,
-          timestamp: position.timestamp
+          timestamp: position.timestamp,
+          integrity_flags: flags.length ? flags : void 0
         });
       },
       () => {
@@ -826,6 +926,9 @@ async function generateCipherText(options, config) {
     );
     if (location) {
       locationData = location;
+      if (location.integrity_flags?.length) {
+        warnings.push(`GPS integrity flags (advisory): ${location.integrity_flags.join(", ")}`);
+      }
     } else if (gpsRequiredByConfig) {
       throw new VesantError(
         `GPS location is required for ${options.reason} by tenant configuration, but GPS was not available or permission was denied`,
@@ -855,15 +958,7 @@ async function generateCipherText(options, config) {
   };
   const encoded = encodePayload(payload);
   const timestamp = now.getTime().toString(36);
-  let cipherText;
-  const hmacKey = options.signingKey || options.apiKey;
-  if (hmacKey) {
-    const message = `02.${timestamp}.${encoded}`;
-    const hmac = await computeHMAC(hmacKey, message);
-    cipherText = `${message}.${hmac}`;
-  } else {
-    cipherText = `01.${timestamp}.${encoded}`;
-  }
+  const cipherText = `01.${timestamp}.${encoded}`;
   return {
     cipherText,
     locationCaptured: !!locationData,
@@ -920,8 +1015,8 @@ var GeolocationClient = class extends BaseClient {
    * ```
    */
   async verifyIP(request, requestOptions) {
-    if (!request.ip_address?.trim()) {
-      throw new ValidationError("ip_address is required and must be a non-empty string", ["ip_address"]);
+    if (request.ip_address !== void 0 && !request.ip_address.trim()) {
+      throw new ValidationError("ip_address, when provided, must be a non-empty string", ["ip_address"]);
     }
     return this.requestWithRetry("/api/v1/geo/verify", {
       method: "POST",
@@ -974,37 +1069,50 @@ var GeolocationClient = class extends BaseClient {
    * ```
    */
   async getGPSConfig(requestOptions) {
-    const config = await this.requestWithRetry("/api/v1/geo/config", void 0, void 0, void 0, requestOptions);
-    if (config.signing_key) {
-      this.cachedSigningKey = config.signing_key;
-    }
-    return config;
+    return this.requestWithRetry("/api/v1/geo/config", void 0, void 0, void 0, requestOptions);
   }
   /**
-   * Fetch the signing key from the dedicated authenticated endpoint.
+   * Mint a short-lived, single-use device-signals nonce.
    *
-   * Falls back to getGPSConfig() for backward compatibility with older servers
-   * that don't expose `/api/v1/geo/signing-key`.
+   * The nonce is bound to the tenant, user, and event type and is consumed
+   * server-side during validation, so a captured device-signals envelope cannot
+   * be replayed. `validateCipherText` mints and attaches one automatically; call
+   * this directly only if you manage the nonce yourself.
    *
-   * @returns The signing key string, or undefined if unavailable
+   * @param userId - User ID the nonce is bound to
+   * @param eventType - Event type the nonce is bound to (login, registration, ...)
+   * @returns The nonce and its expiry
    */
-  async fetchSigningKey(requestOptions) {
+  async fetchSignalsNonce(userId, eventType, requestOptions) {
+    if (!userId?.trim()) {
+      throw new ValidationError("userId is required and must be a non-empty string", ["userId"]);
+    }
+    const request = { user_id: userId, event_type: eventType };
+    return this.request(
+      "/api/v1/geo/signals-token",
+      {
+        method: "POST",
+        body: JSON.stringify(request)
+      },
+      void 0,
+      requestOptions
+    );
+  }
+  /**
+   * Best-effort nonce mint for validation. Returns undefined if minting fails —
+   * the server is the sole authority and blocks when a nonce is required, so this
+   * never downgrades security on the client's say-so.
+   */
+  async resolveSignalsNonce(userId, eventType, requestOptions) {
     try {
-      const response = await this.requestWithRetry(
-        "/api/v1/geo/signing-key",
-        void 0,
-        void 0,
-        void 0,
-        requestOptions
+      const { nonce } = await this.fetchSignalsNonce(userId, eventType, requestOptions);
+      return nonce;
+    } catch (err) {
+      this.logger.warn(
+        `Failed to mint device-signals nonce; proceeding without it: ${err instanceof Error ? err.message : String(err)}`
       );
-      if (response.signing_key) {
-        this.cachedSigningKey = response.signing_key;
-        return response.signing_key;
-      }
-    } catch {
+      return void 0;
     }
-    const config = await this.getGPSConfig(requestOptions);
-    return config.signing_key;
   }
   // ============================================================================
   // CipherText Validation
@@ -1057,12 +1165,14 @@ var GeolocationClient = class extends BaseClient {
     if (!userId?.trim()) {
       throw new ValidationError("userId is required and must be a non-empty string", ["userId"]);
     }
+    const nonce = await this.resolveSignalsNonce(userId, eventType, requestOptions);
     const request = {
       cipher_text: cipherText,
       user_id: userId,
       event_type: eventType,
       expected_ip: expectedIP,
-      customer_data: customerData
+      customer_data: customerData,
+      nonce
     };
     return this.requestWithRetry(
       "/api/v1/geo/validate-ciphertext",
@@ -1271,20 +1381,12 @@ var GeolocationClient = class extends BaseClient {
    *
    * @example
    * ```typescript
-   * // Using GPS (preferred)
+   * // GPS (the web SDK is GPS + IP only; the server handles the IP fallback)
    * const result = await client.captureLocation(token, {
    *   latitude: 37.7749,
    *   longitude: -122.4194,
    *   accuracy: 10
    * });
-   *
-   * // Using WiFi positioning (fallback)
-   * const result = await client.captureLocation(token, {
-   *   wifi_networks: [
-   *     { macAddress: "00:11:22:33:44:55", signalStrength: -50 },
-   *     { macAddress: "AA:BB:CC:DD:EE:FF", signalStrength: -70 }
-   *   ]
-   * });
    * ```
    */
   async captureLocation(token, capture, requestOptions) {
@@ -1297,34 +1399,22 @@ var GeolocationClient = class extends BaseClient {
   // CipherText Generation
   // ============================================================================
   /**
-   * Generate a signed cipherText containing device and location data.
+   * Generate a device-signals envelope containing device and location data,
+   * validated by the server.
    *
-   * Automatically passes the client's API key for HMAC signing (v02 format).
-   * If no API key is configured, falls back to unsigned v01 format.
-   *
-   * @param options - Options for cipherText generation
+   * @param options - Options for envelope generation
    * @param gpsConfig - Optional GPS config (from getGPSConfig)
-   * @returns CipherText result with the signed string
+   * @returns The device-signals envelope result
    *
    * @example
    * ```typescript
    * const result = await client.generateCipherText({ reason: 'login' });
-   * console.log(result.cipherText); // v02 signed cipherText
+   * console.log(result.cipherText); // device-signals envelope
    * ```
    */
   async generateCipherText(options, gpsConfig) {
-    let signingKey = this.cachedSigningKey;
-    let resolvedGpsConfig = gpsConfig;
-    if (!signingKey) {
-      signingKey = await this.fetchSigningKey();
-    }
-    if (!resolvedGpsConfig) {
-      resolvedGpsConfig = await this.getGPSConfig();
-    }
-    return generateCipherText(
-      { ...options, signingKey: signingKey || void 0 },
-      resolvedGpsConfig
-    );
+    const resolvedGpsConfig = gpsConfig ?? await this.getGPSConfig();
+    return generateCipherText(options, resolvedGpsConfig);
   }
   // ============================================================================
   // Utility Methods (inherited from BaseClient: healthCheck, updateConfig, getConfig, buildQueryString)