avo-inspector 2.2.2-alpha.9 → 3.0.0-alpha.2

package/CHANGELOG.md

@@ -5,12 +5,47 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.0-alpha.1] - 2025-12-09
+
+### Changed
+
+- **Encryption Migration**: Migrated encryption implementation from `eciesjs` (secp256k1) to `@noble/curves` + Web Crypto API (prime256v1 / NIST P-256) for browser compatibility
+  - Uses `@noble/curves` library for ECDH operations (lightweight, modern, audited - ~20KB)
+  - Uses Web Crypto API for AES-256-GCM encryption/decryption
+  - Updated curve to prime256v1 (NIST P-256), standard for Web Crypto API
+  - Updated CLI tool to use Node.js crypto (Node-only, so crypto module is fine)
+  - Maintains same encryption format specification: `[Version(1b)] + [EphemeralPubKey(65b)] + [IV(16b)] + [AuthTag(16b)] + [Ciphertext]`
+  - Maintains same key format (Hex strings) for compatibility with other languages
+
+### Breaking Changes
+
+- **[Breaking]** `extractSchema()` is now an async function and returns `Promise<EventProperty[]>`
+  - All callers must now use `await` when calling `extractSchema()`
+  - Example migration:
+    ```javascript
+    // Before (v2.x)
+    const schema = inspector.extractSchema(eventProperties);
+    
+    // After (v3.0)
+    const schema = await inspector.extractSchema(eventProperties);
+    ```
+- **[Breaking]** `shouldRegisterSchemaFromManually()` in `AvoDeduplicator` is now async. It should not be used in the client code though.
+
+### Removed
+
+- Removed `eciesjs` dependency (replaced with `@noble/curves`)
+- Removed `elliptic` dependency (replaced with `@noble/curves`)
+
+### Added
+
+- Added `@noble/curves` dependency for browser-compatible ECDH operations (lightweight, modern, audited)
+
 ## [2.2.1-alpha] - 2025-11-24
 
 ### Added
 
 - **ECC Property Value Encryption**: Optional `publicEncryptionKey` parameter on SDK initialization enables zero-knowledge encryption of property values in dev/staging environments using ECIES (Elliptic Curve Integrated Encryption Scheme). Avo never has access to the private key, ensuring complete data privacy.
-  - Uses secp256k1 curve with AES-256-GCM for hybrid encryption
+  - Uses prime256v1 (NIST P-256) curve with AES-256-GCM for hybrid encryption (standard for Web Crypto API)
   - Only encrypts in dev/staging environments (production sends schema only)
   - Adds optional `encryptedPropertyValue` field to event schema
   - CLI tool for key generation: `npx avo-inspector generate-keys`
@@ -27,10 +62,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Production environment now optimized: no property values, no encryption, no EventSpec API calls
 - Dev/Staging environments now support rich debugging with encrypted values and event specs
 
-### Dependencies
-
-- Added `eciesjs` ^0.4.11 for ECC/ECIES encryption
-
 ## 2.2.0
 
 - Add anonymous ID support to track events without user identification

package/README.md

@@ -104,7 +104,7 @@ Inspector supports encrypting property values in development and staging environ
 
 ## Key Features
 
-- Uses ECC (Elliptic Curve Cryptography) with secp256k1 for strong security
+- Uses ECC (Elliptic Curve Cryptography) with prime256v1 (NIST P-256) for strong security, standard for Web Crypto API
 - Zero-knowledge architecture: Avo never has access to your private key
 - No message size limitations
 - Only active in dev/staging environments (production is unaffected)

package/bin/avo-inspector.js

@@ -1,20 +1,18 @@
 #!/usr/bin/env node
 
-// Use eciesjs directly for ECC key generation
-const { PrivateKey } = require('eciesjs');
+// Use Node.js crypto for ECC key generation (prime256v1 / NIST P-256)
+const { createECDH } = require('crypto');
 const fs = require('fs');
 const path = require('path');
 
 function generateKeyPair() {
-  // Generate a new random private key (32 bytes / 256 bits)
-  const privateKey = new PrivateKey();
-
-  // Derive the public key from the private key
-  const publicKey = privateKey.publicKey;
+  // Generate a new random private key (32 bytes) via ECDH on prime256v1
+  const ecdh = createECDH('prime256v1');
+  ecdh.generateKeys();
 
   return {
-    publicKey: publicKey.toHex(),
-    privateKey: privateKey.toHex()
+    publicKey: ecdh.getPublicKey('hex'),
+    privateKey: ecdh.getPrivateKey('hex')
   };
 }
 
@@ -48,7 +46,7 @@ Examples:
 function generateKeys(writeToFiles = false) {
   console.log(`
 ╔═══════════════════════════════════════════════════════════════╗
-║           Generating ECC Key Pair (secp256k1)...             ║
+║      Generating ECC Key Pair (prime256v1 / NIST P-256)...     ║
 ╚═══════════════════════════════════════════════════════════════╝
 `);
 

package/dist/AvoDeduplicator.d.ts

@@ -12,7 +12,7 @@ export declare class AvoDeduplicator {
         propertyName: string;
         propertyType: string;
         children?: any;
-    }>): boolean;
+    }>): Promise<boolean>;
     private hasSameShapeInAvoFunctionsAs;
     private lookForEventSchemaIn;
     private clearOldEvents;

package/dist/AvoEncryption.d.ts

@@ -1,6 +1,6 @@
 /**
  * Generates a new ECC key pair for encryption/decryption.
- * Uses secp256k1 curve (P-256 family) which provides 128-bit security.
+ * Uses P-256 (prime256v1 / NIST P-256) curve which is standard for Web Crypto API.
  *
  * @returns An object containing the private and public keys as hex strings
  */
@@ -18,16 +18,30 @@ export declare function generateKeyPair(): {
  * - Fast encryption even for large values
  * - Strong authentication via GCM
  *
+ * SPECIFICATION (Standard Web Crypto Profile):
+ * 1. Curve: P-256 (prime256v1 / NIST P-256)
+ * 2. Key Derivation (KDF): SHA-256(SharedSecret)
+ * 3. Cipher: AES-256-GCM
+ * 4. Serialization: [Version(1b)] + [EphemeralPubKey(33 or 65b)] + [IV(16b)] + [AuthTag(16b)] + [Ciphertext]
+ *    Version 0x00 = Standard Web Profile
+ *    EphemeralPubKey: 0x04 (uncompressed) + 64 bytes = 65 bytes total, or compressed format (33 bytes)
+ *
  * @param value - The value to encrypt (any type - will be JSON stringified)
  * @param publicKey - The ECC public key in hex format provided by the client
- * @returns Base64-encoded encrypted string that can only be decrypted with the private key
+ * @returns Promise resolving to base64-encoded encrypted string that can only be decrypted with the private key
  */
-export declare function encryptValue(value: any, publicKey: string): string;
+export declare function encryptValue(value: any, publicKey: string): Promise<string>;
 /**
  * Decrypts a value that was encrypted with encryptValue.
  *
+ * SPECIFICATION (Standard Web Crypto Profile):
+ * 1. Curve: P-256 (prime256v1 / NIST P-256)
+ * 2. Key Derivation (KDF): SHA-256(SharedSecret)
+ * 3. Cipher: AES-256-GCM
+ * 4. Deserialization: [Version(1b)] + [EphemeralPubKey(33 or 65b)] + [IV(16b)] + [AuthTag(16b)] + [Ciphertext]
+ *
  * @param encryptedValue - The base64-encoded encrypted string
  * @param privateKey - The ECC private key in hex format
- * @returns The original decrypted value (parsed from JSON)
+ * @returns Promise resolving to the original decrypted value (parsed from JSON)
  */
-export declare function decryptValue(encryptedValue: string, privateKey: string): any;
+export declare function decryptValue(encryptedValue: string, privateKey: string): Promise<any>;

package/dist/AvoInspector.d.ts

@@ -44,12 +44,12 @@ export declare class AvoInspector {
     }>): Promise<void>;
     private trackSchemaInternal;
     enableLogging(enable: boolean): void;
-    extractSchema(eventProperties: Record<string, any>, shouldLogIfEnabled?: boolean): Array<{
+    extractSchema(eventProperties: Record<string, any>, shouldLogIfEnabled?: boolean): Promise<Array<{
         propertyName: string;
         propertyType: string;
         encryptedPropertyValue?: string;
         children?: any;
-    }>;
+    }>>;
     setBatchSize(newBatchSize: number): void;
     setBatchFlushSeconds(newBatchFlushSeconds: number): void;
     /**

package/dist/AvoNetworkCallsHandler.d.ts

@@ -33,6 +33,8 @@ export interface BaseBody {
     samplingRate: number;
     /** Event spec metadata from EventSpecResponse (moved from EventSchemaBody) */
     eventSpecMetadata?: EventSpecMetadata;
+    /** RSA public encryption key - allows Inspector to validate encrypted values against tracking plan */
+    publicEncryptionKey?: string;
 }
 export interface SessionStartedBody extends BaseBody {
     type: "sessionStarted";
@@ -55,10 +57,11 @@ export declare class AvoNetworkCallsHandler {
     private readonly appName;
     private readonly appVersion;
     private readonly libVersion;
+    private readonly publicEncryptionKey?;
     private samplingRate;
     private sending;
     private static readonly trackingEndpoint;
-    constructor(apiKey: string, envName: string, appName: string, appVersion: string, libVersion: string);
+    constructor(apiKey: string, envName: string, appName: string, appVersion: string, libVersion: string, publicEncryptionKey?: string);
     callInspectorWithBatchBody(inEvents: Array<SessionStartedBody | EventSchemaBody>, onCompleted: (error: Error | null) => any): void;
     private fixStreamIds;
     bodyForSessionStartedCall(): SessionStartedBody;

package/dist/AvoSchemaParser.d.ts

@@ -10,7 +10,7 @@ export declare class AvoSchemaParser {
      * Never returns unencrypted values - only encrypted or nothing.
      */
     private static getEncryptedPropertyValueIfEnabled;
-    static extractSchema(eventProperties: Record<string, any>, publicEncryptionKey?: string, env?: string): EventProperty[];
+    static extractSchema(eventProperties: Record<string, any>, publicEncryptionKey?: string, env?: string): Promise<EventProperty[]>;
     private static removeDuplicates;
     private static getPropValueType;
 }

package/dist/browser.js.LICENSE.txt

@@ -0,0 +1,5 @@
+/*! noble-ciphers - MIT License (c) 2023 Paul Miller (paulmillr.com) */
+
+/*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
+
+/*! noble-hashes - MIT License (c) 2022 Paul Miller (paulmillr.com) */

package/dist/eventSpec/AvoEventSpecFetchTypes.d.ts

@@ -1,67 +1,54 @@
 /**
- * Wire format - Property constraints from the API.
- *
- * The API returns constraints in a compact format:
- * - `t`: Type - either a string ("string", "int", "float", "boolean") or an object (for nested object types)
- * - `r`: Required flag
- * - `l`: List flag - true if this is an array/list of the type
- * - `v`: Allowed values - array of allowed string values
- * - `min`/`max`: Numeric range constraints
- *
- * For list of objects, `t` is an object containing child property schemas and `l` is true.
+ * This file is generated. Internal development changes should be made in the generator
+ * and the file should be re-generated. External contributions are welcome to submit
+ * changes directly to this file, and we'll apply them to the generator internally.
+ */
+/**
+ * Wire format - Property constraints with short field names.
+ * At most one constraint type will be present per property.
  */
 export interface PropertyConstraintsWire {
-    /**
-     * Type - either a string type name ("string", "int", "float", "boolean")
-     * or an object containing nested property schemas (for object/list of objects)
-     */
-    t: string | Record<string, PropertyConstraintsWire>;
-    /** Required flag */
+    /** Type name (for reference only, not validated) */
+    t: string;
+    /** Required flag (for reference only, not validated) */
     r: boolean;
     /** List flag - true if this is an array/list of the type */
     l?: boolean;
-    /** Allowed values - array of allowed string values */
-    v?: Array<string>;
-    /** Minimum value for numeric types */
-    min?: number;
-    /** Maximum value for numeric types */
-    max?: number;
+    /** Pinned values: pinnedValue -> eventIds that require this exact value */
+    p?: Record<string, Array<string>>;
+    /** Allowed values: JSON array string -> eventIds that accept these values */
+    v?: Record<string, Array<string>>;
+    /** Regex patterns: pattern -> eventIds that require matching this regex */
+    rx?: Record<string, Array<string>>;
+    /** Min/max ranges: "min,max" -> eventIds that require value in this range */
+    minmax?: Record<string, Array<string>>;
+    /** Nested property constraints for object properties */
+    children?: Record<string, PropertyConstraintsWire>;
 }
 /**
- * Wire format - Base event from the API.
+ * Wire format - Event spec entry with short field names.
+ * A single event entry (base event + its variants).
+ * Multiple events can match the same name request due to name mapping.
  */
-export interface BaseEventWire {
-    /** Event name */
-    name: string;
-    /** Event ID */
+export interface EventSpecEntryWire {
+    /** Branch identifier */
+    b: string;
+    /** Base event ID */
     id: string;
+    /** Variant IDs (baseEventId + variantIds = complete set) */
+    vids: Array<string>;
     /** Property constraints keyed by property name */
-    props: Record<string, PropertyConstraintsWire>;
-}
-/**
- * Wire format - Event variant from the API.
- */
-export interface EventVariantWire {
-    /** Variant ID */
-    variantId: string;
-    /** Name suffix for this variant */
-    nameSuffix: string;
-    /** Full event ID (baseEventId.variantId) */
-    eventId: string;
-    /** Property constraints for this variant */
-    props: Record<string, PropertyConstraintsWire>;
+    p: Record<string, PropertyConstraintsWire>;
 }
 /**
  * Wire format - Response from getEventSpec endpoint.
- * Contains the base event and its variants.
+ * Contains array of events that match the requested name (due to name mapping).
  */
 export interface EventSpecResponseWire {
-    /** Branch identifier */
-    branchId: string;
-    /** Base event definition */
-    baseEvent: BaseEventWire;
-    /** Event variants */
-    variants: Array<EventVariantWire>;
+    /** Array of events matching the requested name */
+    events: Array<EventSpecEntryWire>;
+    /** Schema metadata (keeps long names - small, one per response) */
+    metadata: EventSpecMetadata;
 }
 /**
  * Internal - Property constraints with meaningful field names.
@@ -72,6 +59,8 @@ export interface PropertyConstraints {
     type: string;
     /** Required flag (for reference only, not validated) */
     required: boolean;
+    /** List flag - true if this is an array/list of items */
+    isList?: boolean;
     /** Pinned values: pinnedValue -> eventIds that require this exact value */
     pinnedValues?: Record<string, Array<string>>;
     /** Allowed values: JSON array string -> eventIds that accept these values */
@@ -80,7 +69,7 @@ export interface PropertyConstraints {
     regexPatterns?: Record<string, Array<string>>;
     /** Min/max ranges: "min,max" -> eventIds that require value in this range */
     minMaxRanges?: Record<string, Array<string>>;
-    /** Nested property constraints for object properties */
+    /** Nested property constraints for object properties (for objects or list of objects) */
     children?: Record<string, PropertyConstraints>;
 }
 /**

package/dist/eventSpec/AvoEventSpecFetcher.d.ts

@@ -1,3 +1,8 @@
+/**
+ * This file is generated. Internal development changes should be made in the generator
+ * and the file should be re-generated. External contributions are welcome to submit
+ * changes directly to this file, and we'll apply them to the generator internally.
+ */
 import type { EventSpecResponse, FetchEventSpecParams } from "./AvoEventSpecFetchTypes";
 /**
  * EventSpecFetcher handles fetching event specifications from the Avo API.
@@ -43,43 +48,13 @@ export declare class AvoEventSpecFetcher {
     private makeRequest;
     /**
      * Basic shape check for wire format - ensures response has the minimum expected structure.
-     * API returns: { branchId, baseEvent: { name, id, props }, variants: [...] }
+     * Uses short field names from wire format.
      */
     private hasExpectedShape;
-    /**
-     * Parses the wire format response into internal format.
-     *
-     * The API returns a single event with its variants. We transform this into
-     * our internal format which has an array of EventSpecEntry (one entry containing
-     * the base event ID and all variant IDs, with merged property constraints).
-     */
+    /** Parses the wire format response into internal format with meaningful field names. */
     private static parseEventSpecResponse;
-    /**
-     * Parses and merges property constraints from base event and variants.
-     *
-     * For each property, we need to:
-     * 1. Parse the wire format into internal format
-     * 2. Convert allowed values array to Record<string, eventIds>
-     * 3. Convert min/max to Record<string, eventIds>
-     * 4. Track which event IDs have which constraints
-     */
-    private static parseAndMergeProps;
-    /**
-     * Merges property constraints from base event and variants into a single PropertyConstraints.
-     */
-    private static mergePropertyConstraints;
-    /**
-     * Gets the type string from a wire property.
-     * If `t` is an object (for nested objects), returns "object".
-     */
-    private static getTypeString;
-    /**
-     * Gets the nested schema from a wire property.
-     * Returns the nested property schemas if `t` is an object, otherwise undefined.
-     */
-    private static getNestedSchema;
-    /**
-     * Adds constraints from a wire property to the accumulator maps.
-     */
-    private static addConstraintsFromProp;
+    /** Parses a single event spec entry from wire format. */
+    private static parseEventSpecEntry;
+    /** Parses property constraints from wire format. */
+    private static parsePropertyConstraints;
 }

package/dist/eventSpec/AvoGuid.d.ts

@@ -0,0 +1,3 @@
+export default class AvoGuid {
+    static newGuid(): string;
+}