vesant-sdk 1.7.0 → 1.7.1-dev.0520b46

package/dist/geolocation/index.js

@@ -1,5 +1,18 @@
 'use strict';
 
+// 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) {
@@ -216,7 +229,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() {
@@ -298,6 +311,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;
@@ -316,11 +335,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);
     }
@@ -328,6 +348,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
    */
@@ -353,15 +386,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);
@@ -382,10 +420,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);
@@ -474,9 +530,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) {
@@ -573,6 +631,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)
@@ -600,27 +661,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");
   }
-  const { createHmac } = await import('crypto');
-  return createHmac("sha256", key).update(message).digest("hex");
+  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";
+  }
+}
+
+// src/geolocation/ciphertext.ts
+var CIPHER_TEXT_EXPIRY_MINUTES = 5;
 function getWebGLInfo() {
   if (typeof document === "undefined") return null;
   try {
@@ -652,6 +749,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) => {
@@ -668,6 +766,7 @@ async function requestGPSLocation(timeout = 1e4, highAccuracy = true) {
           resolve(null);
           return;
         }
+        const { flags } = assessGpsIntegrity(gpsIntegrityInputFromPosition(position), { permissionState });
         resolve({
           latitude,
           longitude,
@@ -676,7 +775,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
         });
       },
       () => {
@@ -743,6 +843,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`,
@@ -772,15 +875,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,
@@ -789,6 +884,7 @@ async function generateCipherText(options, config) {
     expiresAt: expiry.toISOString()
   };
 }
+var collectDeviceSignals = generateCipherText;
 function decodeCipherText(cipherText) {
   try {
     const parts = cipherText.split(".");
@@ -816,6 +912,7 @@ function isCipherTextExpired(cipherText) {
 }
 
 // src/geolocation/client.ts
+var DEFAULT_GPS_CONFIG_TTL_MS = 5 * 60 * 1e3;
 var GeolocationClient = class extends BaseClient {
   constructor(config) {
     const baseConfig = {
@@ -831,6 +928,8 @@ var GeolocationClient = class extends BaseClient {
       environment: config.environment
     };
     super(baseConfig);
+    this.gpsConfigCache = null;
+    this.gpsConfigTtlMs = config.gpsConfigTtlMs ?? DEFAULT_GPS_CONFIG_TTL_MS;
   }
   // ============================================================================
   // IP Verification & Compliance
@@ -862,8 +961,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",
@@ -916,37 +1015,85 @@ 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;
+    const cached = this.gpsConfigCache;
+    if (cached && cached.expiresAt > Date.now()) {
+      return cached.value;
     }
-    return config;
+    return this.refreshGPSConfig(requestOptions);
   }
   /**
-   * Fetch the signing key from the dedicated authenticated endpoint.
+   * Re-read the tenant's GPS requirement configuration, ignoring any copy held
+   * from an earlier read.
    *
-   * Falls back to getGPSConfig() for backward compatibility with older servers
-   * that don't expose `/api/v1/geo/signing-key`.
+   * These requirements are edited in the compliance console while your
+   * application is running. `getGPSConfig` reuses a fetched copy for a short
+   * period so a long-lived session does not call the API on every event; call
+   * this when you need a change to take effect immediately — for example right
+   * after an administrator saves new settings.
    *
-   * @returns The signing key string, or undefined if unavailable
+   * @returns The current GPS requirement config per event type
+   *
+   * @example
+   * ```typescript
+   * const config = await client.refreshGPSConfig();
+   * if (config.require_gps.login) {
+   *   // GPS is now required for login
+   * }
+   * ```
+   */
+  async refreshGPSConfig(requestOptions) {
+    const value = await this.requestWithRetry(
+      "/api/v1/geo/config",
+      void 0,
+      void 0,
+      void 0,
+      requestOptions
+    );
+    this.gpsConfigCache = { value, expiresAt: Date.now() + this.gpsConfigTtlMs };
+    return value;
+  }
+  /**
+   * Mint a short-lived, single-use device-signals nonce.
+   *
+   * 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.
+   *
+   * @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 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 fetchSigningKey(requestOptions) {
+  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
@@ -999,12 +1146,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",
@@ -1213,20 +1362,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) {
@@ -1239,34 +1380,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)
@@ -1274,8 +1403,12 @@ var GeolocationClient = class extends BaseClient {
 };
 
 exports.GeolocationClient = GeolocationClient;
+exports.assessGpsIntegrity = assessGpsIntegrity;
+exports.collectDeviceSignals = collectDeviceSignals;
 exports.decodeCipherText = decodeCipherText;
 exports.generateCipherText = generateCipherText;
+exports.gpsIntegrityInputFromPosition = gpsIntegrityInputFromPosition;
 exports.isCipherTextExpired = isCipherTextExpired;
+exports.probeGeolocationPermission = probeGeolocationPermission;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map