native-update 1.4.9 → 3.1.0

package/dist/esm/live-update/version-manager.js

@@ -2,8 +2,6 @@ import { ConfigManager } from '../core/config';
 import { Logger } from '../core/logger';
 import { SecurityValidator } from '../core/security';
 import { ValidationError, ErrorCode } from '../core/errors';
-import { FirestoreClient } from '../firestore/firestore-client';
-import { ManifestReader } from '../firestore/manifest-reader';
 /**
  * Manages version checking and comparison
  */
@@ -13,8 +11,6 @@ export class VersionManager {
         this.CACHE_DURATION = 5 * 60 * 1000; // 5 minutes
         this.preferences = null;
         this.memoryCache = new Map();
-        this.firestoreClient = null;
-        this.manifestReader = null;
         this.logger = Logger.getInstance();
         this.configManager = ConfigManager.getInstance();
         this.securityValidator = SecurityValidator.getInstance();
@@ -78,69 +74,6 @@ export class VersionManager {
         if (!this.preferences) {
             throw new ValidationError(ErrorCode.MISSING_DEPENDENCY, 'Preferences not configured. Please configure the plugin first.');
         }
-        // Initialize Firestore client if configured
-        const backendType = this.configManager.get('backendType');
-        if (backendType === 'firestore') {
-            const firestoreConfig = this.configManager.get('firestore');
-            if (!firestoreConfig) {
-                throw new ValidationError(ErrorCode.INVALID_CONFIG, 'Firestore configuration required when using firestore backend');
-            }
-            this.firestoreClient = new FirestoreClient(firestoreConfig);
-            this.manifestReader = new ManifestReader(this.firestoreClient);
-            this.logger.debug('Firestore backend initialized');
-        }
-    }
-    /**
-     * Check for updates from Firestore backend
-     * Uses ManifestReader for efficient single-document reads
-     */
-    async checkForUpdatesFromFirestore(currentVersion, deviceInfo) {
-        if (!this.manifestReader) {
-            throw new ValidationError(ErrorCode.INVALID_CONFIG, 'Firestore backend not initialized. Call initialize() first or configure firestore backend.');
-        }
-        // Validate current version
-        this.securityValidator.validateVersion(currentVersion);
-        const options = {
-            currentVersion,
-            deviceInfo,
-            checkDeltas: this.configManager.get('enableDeltaUpdates'),
-        };
-        try {
-            const response = await this.manifestReader.checkForUpdates(options);
-            if (response) {
-                this.logger.info('Firestore update check completed', {
-                    currentVersion,
-                    latestVersion: response.version,
-                    updateAvailable: response.updateAvailable,
-                    eligible: response.rolloutEligible,
-                });
-            }
-            return response;
-        }
-        catch (error) {
-            this.logger.error('Failed to check for updates from Firestore', error);
-            return null;
-        }
-    }
-    /**
-     * Get the appropriate update checker based on backend type
-     */
-    async checkForUpdatesAuto(currentVersion, deviceInfo) {
-        const backendType = this.configManager.get('backendType') || 'http';
-        if (backendType === 'firestore') {
-            if (!deviceInfo) {
-                throw new ValidationError(ErrorCode.INVALID_CONFIG, 'Device info is required for Firestore backend');
-            }
-            return this.checkForUpdatesFromFirestore(currentVersion, deviceInfo);
-        }
-        // Fall back to HTTP-based update check
-        const serverUrl = this.configManager.get('serverUrl');
-        const channel = this.configManager.get('channel') || 'production';
-        const appId = this.configManager.get('appId');
-        if (!serverUrl || !appId) {
-            throw new ValidationError(ErrorCode.INVALID_CONFIG, 'Server URL and App ID are required for HTTP backend');
-        }
-        return this.checkForUpdates(serverUrl, channel, currentVersion, appId);
     }
     /**
      * Check for latest version from server
@@ -398,5 +331,44 @@ export class VersionManager {
             return true;
         }
     }
+    /**
+     * Persisted high-water-mark version per channel. Survives reinstalls that
+     * leave Preferences intact; protects against an attacker feeding an older
+     * (and potentially vulnerable) bundle even after a full cache wipe of
+     * downloaded bundles. Paired with `rememberAppliedVersion`.
+     */
+    maxVersionKey(channel) {
+        return `nu_max_version_${channel}`;
+    }
+    async getMaxSeenVersion(channel) {
+        if (!this.preferences)
+            return null;
+        try {
+            const { value } = await this.preferences.get({
+                key: this.maxVersionKey(channel),
+            });
+            return value !== null && value !== void 0 ? value : null;
+        }
+        catch (error) {
+            this.logger.warn('Failed to read max-seen version', error);
+            return null;
+        }
+    }
+    async rememberAppliedVersion(channel, version) {
+        if (!this.preferences)
+            return;
+        const current = await this.getMaxSeenVersion(channel);
+        if (current && VersionManager.compareVersions(current, version) >= 0) {
+            return;
+        }
+        try {
+            await this.preferences.set({
+                key: this.maxVersionKey(channel),
+                value: version,
+            });
+        }
+        catch (error) {
+            this.logger.warn('Failed to persist max-seen version', error);
+        }
+    }
 }
-//# sourceMappingURL=version-manager.js.map

package/dist/esm/plugin.js

@@ -2,7 +2,6 @@ import { registerPlugin } from '@capacitor/core';
 import { SyncStatus, BundleStatus, UpdateErrorCode } from './definitions';
 import { PluginManager } from './core/plugin-manager';
 import { NativeUpdateError, ErrorCode } from './core/errors';
-import { CryptoUtils } from './security/crypto';
 /**
  * Web implementation of the Native Update Plugin
  */
@@ -53,8 +52,6 @@ class NativeUpdatePluginWeb {
                 requireSignature: liveUpdate === null || liveUpdate === void 0 ? void 0 : liveUpdate.requireSignature,
                 checksumAlgorithm: liveUpdate === null || liveUpdate === void 0 ? void 0 : liveUpdate.checksumAlgorithm,
                 checkInterval: liveUpdate === null || liveUpdate === void 0 ? void 0 : liveUpdate.checkInterval,
-                backendType: liveUpdate === null || liveUpdate === void 0 ? void 0 : liveUpdate.backendType,
-                firestore: liveUpdate === null || liveUpdate === void 0 ? void 0 : liveUpdate.firestore,
                 security: config.security,
                 appStoreId: appUpdate === null || appUpdate === void 0 ? void 0 : appUpdate.appStoreId,
                 packageName: appUpdate === null || appUpdate === void 0 ? void 0 : appUpdate.packageName,
@@ -128,23 +125,33 @@ class NativeUpdatePluginWeb {
         const downloadManager = this.pluginManager.getDownloadManager();
         const bundleManager = this.pluginManager.getBundleManager();
         const blob = await downloadManager.downloadWithRetry(options.url, options.version);
-        const path = await downloadManager.saveBlob(options.version, blob);
+        // Verify checksum/signature against ACTUAL downloaded bytes before
+        // persisting. Without this, an attacker who swaps the URL or proxies
+        // a tampered bundle can plant arbitrary code and the next set() will
+        // activate it. validateBundleData throws on mismatch.
+        const bundleData = await blob.arrayBuffer();
+        await this.validateBundleData(bundleData, options.checksum, options.signature);
+        const validatedBlob = new Blob([bundleData], { type: blob.type });
+        const path = await downloadManager.saveBlob(options.version, validatedBlob);
         const bundleInfo = {
             bundleId: options.version,
             version: options.version,
             path,
             downloadTime: Date.now(),
-            size: blob.size,
+            size: validatedBlob.size,
             status: BundleStatus.READY,
             checksum: options.checksum,
             signature: options.signature,
-            verified: false,
+            verified: true,
         };
         await bundleManager.saveBundleInfo(bundleInfo);
         return bundleInfo;
     }
     async set(bundle) {
         const bundleManager = this.pluginManager.getBundleManager();
+        if (!bundle.verified) {
+            throw new NativeUpdateError(ErrorCode.SIGNATURE_INVALID, `Refusing to activate unverified bundle ${bundle.bundleId}`);
+        }
         await bundleManager.setActiveBundle(bundle.bundleId);
     }
     async reload() {
@@ -206,22 +213,50 @@ class NativeUpdatePluginWeb {
             });
         }
     }
+    /**
+     * @deprecated since v2. The update server URL is fixed at `initialize()`
+     *   time and cannot be mutated at runtime. Runtime mutation is an XSS
+     *   attack vector — a compromised WebView could repoint updates to a
+     *   malicious host. Call `initialize()` again with the new config if you
+     *   legitimately need to switch servers.
+     */
     async setUpdateUrl(url) {
-        const configManager = this.pluginManager.getConfigManager();
-        configManager.configure({ baseUrl: url });
+        void url;
+        const logger = this.pluginManager.getLogger();
+        logger.warn('setUpdateUrl() is deprecated and ignored. Update URL is locked after initialize(). ' +
+            'Call initialize() again with an updated serverUrl to switch servers.');
     }
     async validateUpdate(options) {
         const securityValidator = this.pluginManager.getSecurityValidator();
+        const downloadManager = this.pluginManager.getDownloadManager();
         try {
-            // Validate checksum
-            const isValid = await securityValidator.validateChecksum(new ArrayBuffer(0), // Placeholder for bundle data
-            options.checksum);
+            // bundlePath may be either a stored path (`bundles/<id>/bundle.zip`)
+            // or a bare bundleId. Normalize to bundleId so we can read the
+            // persisted blob.
+            const pathMatch = options.bundlePath.match(/bundles\/([^/]+)\/bundle\.zip$/);
+            const bundleId = pathMatch ? pathMatch[1] : options.bundlePath;
+            const blob = await downloadManager.loadBlob(bundleId);
+            if (!blob) {
+                return {
+                    isValid: false,
+                    error: `Bundle not found at ${options.bundlePath}`,
+                };
+            }
+            const bundleData = await blob.arrayBuffer();
+            const checksumValid = await securityValidator.verifyChecksum(bundleData, options.checksum);
+            let signatureValid = true;
+            if (options.signature) {
+                signatureValid = await securityValidator.verifySignature(bundleData, options.signature);
+            }
+            const sizeValid = options.maxSize
+                ? bundleData.byteLength <= options.maxSize
+                : true;
             return {
-                isValid,
+                isValid: checksumValid && signatureValid && sizeValid,
                 details: {
-                    checksumValid: isValid,
-                    signatureValid: true,
-                    sizeValid: true,
+                    checksumValid,
+                    signatureValid,
+                    sizeValid,
                     versionValid: true,
                 },
             };
@@ -242,31 +277,9 @@ class NativeUpdatePluginWeb {
     async checkForUpdate() {
         const bundleManager = this.pluginManager.getBundleManager();
         const configManager = this.pluginManager.getConfigManager();
-        const versionManager = this.pluginManager.getVersionManager();
         try {
             const currentBundle = await bundleManager.getActiveBundle();
             const currentVersion = (currentBundle === null || currentBundle === void 0 ? void 0 : currentBundle.version) || '1.0.0';
-            const backendType = configManager.get('backendType');
-            if (backendType === 'firestore') {
-                const result = (await versionManager.checkForUpdatesAuto(currentVersion, this.getDeviceInfo(currentVersion)));
-                if (!(result === null || result === void 0 ? void 0 : result.updateAvailable)) {
-                    return {
-                        available: false,
-                        currentVersion,
-                    };
-                }
-                return {
-                    available: true,
-                    currentVersion,
-                    latestVersion: result.version,
-                    url: result.bundleUrl,
-                    mandatory: result.mandatory,
-                    notes: result.releaseNotes,
-                    size: result.size,
-                    checksum: result.checksum,
-                    signature: result.signature,
-                };
-            }
             const baseUrl = configManager.get('baseUrl');
             if (!baseUrl) {
                 return {
@@ -274,11 +287,26 @@ class NativeUpdatePluginWeb {
                     currentVersion,
                 };
             }
-            const response = await fetch(`${baseUrl}/updates/latest`, {
+            // Laravel backend contract: GET /v1/updates/check with X-API-Key,
+            // X-Device-ID, X-Current-Version, X-Platform headers. The
+            // backend returns either {available: false} or {available: true,
+            // version, downloadUrl, checksum, signature, size, ...}.
+            const apiKey = configManager.get('apiKey');
+            if (!apiKey) {
+                throw new NativeUpdateError(ErrorCode.INVALID_CONFIG, 'apiKey is required when using Laravel backend');
+            }
+            const channel = configManager.get('channel') || 'production';
+            const deviceInfo = this.getDeviceInfo(currentVersion);
+            const url = `${baseUrl.replace(/\/$/, '')}/v1/updates/check?channel=${encodeURIComponent(channel)}`;
+            const response = await fetch(url, {
                 method: 'GET',
                 headers: {
                     'Content-Type': 'application/json',
+                    'X-API-Key': apiKey,
+                    'X-Device-ID': deviceInfo.deviceId,
                     'X-Current-Version': currentVersion,
+                    'X-Platform': deviceInfo.platform,
+                    'X-App-Version': deviceInfo.appVersion,
                 },
             });
             if (!response.ok) {
@@ -288,15 +316,19 @@ class NativeUpdatePluginWeb {
                 };
             }
             const data = await response.json();
-            const latestVersion = data.version || data.latestVersion;
-            const isNewer = this.compareVersions(currentVersion, latestVersion) < 0;
+            if (!data.available) {
+                return {
+                    available: false,
+                    currentVersion,
+                };
+            }
             return {
-                available: isNewer,
+                available: true,
                 currentVersion,
-                latestVersion: isNewer ? latestVersion : undefined,
-                url: isNewer ? data.url || data.downloadUrl : undefined,
+                latestVersion: data.version,
+                url: data.downloadUrl,
                 mandatory: data.mandatory,
-                notes: data.notes || data.releaseNotes,
+                notes: data.releaseNotes,
                 size: data.size,
                 checksum: data.checksum,
                 signature: data.signature,
@@ -337,10 +369,8 @@ class NativeUpdatePluginWeb {
         };
         // Download the bundle
         const blob = await downloadManager.downloadWithRetry(url, version, onProgress);
-        // Get ArrayBuffer for decryption and validation
-        let bundleData = await blob.arrayBuffer();
-        // Decrypt if encryption is enabled
-        bundleData = await this.decryptBundleIfNeeded(bundleData);
+        // Get ArrayBuffer for validation
+        const bundleData = await blob.arrayBuffer();
         // Validate checksum and signature before saving
         await this.validateBundleData(bundleData, checksum, signature || undefined);
         // Convert back to Blob for storage
@@ -416,9 +446,12 @@ class NativeUpdatePluginWeb {
         return downloadManager.getActiveDownloadCount();
     }
     /**
-     * Compare two semantic versions
+     * Compare two semantic versions. Currently unused — the Laravel
+     * backend decides update availability server-side. Retained as a
+     * helper for advanced consumers that need client-side comparison.
      * Returns: -1 if v1 < v2, 0 if equal, 1 if v1 > v2
      */
+    // @ts-expect-error retained as a helper for advanced consumers
     compareVersions(v1, v2) {
         const parts1 = v1.split('.').map(Number);
         const parts2 = v2.split('.').map(Number);
@@ -442,45 +475,6 @@ class NativeUpdatePluginWeb {
             locale: typeof navigator !== 'undefined' ? navigator.language : 'en-US',
         };
     }
-    /**
-     * Decrypt bundle data if encryption is enabled
-     * Returns the decrypted data or the original data if encryption is not enabled
-     */
-    async decryptBundleIfNeeded(bundleData) {
-        const configManager = this.pluginManager.getConfigManager();
-        const enableEncryption = configManager.get('enableEncryption');
-        const encryptionKey = configManager.get('encryptionKey');
-        const encryptionSalt = configManager.get('encryptionSalt');
-        if (!enableEncryption) {
-            return bundleData;
-        }
-        // Validate encryption configuration
-        if (!encryptionKey) {
-            throw new NativeUpdateError(ErrorCode.INVALID_CONFIG, 'Encryption is enabled but encryptionKey is not configured');
-        }
-        if (!encryptionSalt) {
-            throw new NativeUpdateError(ErrorCode.INVALID_CONFIG, 'Encryption is enabled but encryptionSalt is not configured');
-        }
-        try {
-            // Try to parse as encrypted bundle JSON
-            const decoder = new TextDecoder();
-            const jsonString = decoder.decode(bundleData);
-            const encryptedBundle = JSON.parse(jsonString);
-            // Verify it's an encrypted bundle
-            if (!CryptoUtils.isEncryptedBundle(encryptedBundle)) {
-                throw new NativeUpdateError(ErrorCode.VALIDATION_ERROR, 'Encryption is enabled but bundle is not encrypted');
-            }
-            // Decrypt the bundle
-            const decryptedData = await CryptoUtils.decryptBundle(encryptedBundle, encryptionKey, encryptionSalt);
-            return decryptedData;
-        }
-        catch (error) {
-            if (error instanceof NativeUpdateError) {
-                throw error;
-            }
-            throw new NativeUpdateError(ErrorCode.VALIDATION_ERROR, `Failed to decrypt bundle: ${error instanceof Error ? error.message : 'Unknown error'}`);
-        }
-    }
     /**
      * Validate bundle data using SecurityValidator
      * Returns true if valid, throws error if invalid
@@ -656,4 +650,3 @@ const NativeUpdate = registerPlugin('NativeUpdate', {
     web: () => new NativeUpdatePluginWeb(),
 });
 export { NativeUpdate };
-//# sourceMappingURL=plugin.js.map

package/dist/esm/security/crypto.js

@@ -26,25 +26,30 @@ export class CryptoUtils {
      */
     static async verifySignature(data, signature, publicKey) {
         try {
-            // Convert base64 strings to ArrayBuffer
+            // Accept either PEM (`-----BEGIN PUBLIC KEY-----...`) or raw base64
+            // SPKI. Two callers existed historically and they passed different
+            // formats; standardize on PEM-aware parsing here so both work.
+            const pemBody = publicKey
+                .replace(/-----BEGIN PUBLIC KEY-----/g, '')
+                .replace(/-----END PUBLIC KEY-----/g, '')
+                .replace(/\s+/g, '');
             const signatureBuffer = this.base64ToArrayBuffer(signature);
-            const publicKeyBuffer = this.base64ToArrayBuffer(publicKey);
-            // Import public key
+            const publicKeyBuffer = this.base64ToArrayBuffer(pemBody);
             const key = await crypto.subtle.importKey('spki', publicKeyBuffer, {
                 name: 'RSA-PSS',
                 hash: 'SHA-256',
             }, false, ['verify']);
-            // Prepare data
             const encoder = new TextEncoder();
             const dataBuffer = typeof data === 'string' ? encoder.encode(data) : data;
-            // Verify signature
             return await crypto.subtle.verify({
                 name: 'RSA-PSS',
                 saltLength: 32,
             }, key, signatureBuffer, dataBuffer);
         }
         catch (error) {
-            console.error('Signature verification failed:', error);
+            // Verification failure must NOT throw — we want a clean false so
+            // upstream code can refuse the bundle without crashing.
+            void error;
             return false;
         }
     }
@@ -224,4 +229,3 @@ export class CryptoUtils {
         return btoa(binary);
     }
 }
-//# sourceMappingURL=crypto.js.map

package/dist/esm/security/validator.js

@@ -140,4 +140,3 @@ export class Validator {
         return { valid: true };
     }
 }
-//# sourceMappingURL=validator.js.map

package/dist/esm/types/rollout.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Rollout + update-check types.
+ *
+ * These types describe staged-rollout configuration and the response
+ * shape the Laravel backend returns from `GET /v1/updates/check`.
+ * They were previously co-located with the Firestore schema; v3 of the
+ * plugin dropped Firestore as a backend, so the types live here in a
+ * backend-neutral location.
+ */
+/**
+ * A point in time in a rollout config. Accepts ISO-8601 strings (what
+ * the Laravel backend returns), epoch milliseconds, or a `Date` for
+ * convenience when constructing config in code.
+ */
+export type RolloutTimestamp = number | string | Date;
+/**
+ * Convert a `RolloutTimestamp` to epoch milliseconds. Throws on a
+ * value that doesn't parse — callers are expected to validate before
+ * persisting rollout config.
+ */
+export declare function toEpochMs(value: RolloutTimestamp): number;
+/**
+ * Staged rollout configuration returned by the backend on update checks.
+ */
+export interface RolloutConfig {
+    enabled: boolean;
+    percentage: number;
+    startTime: RolloutTimestamp;
+    endTime: RolloutTimestamp | null;
+    targetSegments?: RolloutTargetSegments;
+    schedule?: RolloutSchedule;
+}
+export interface RolloutTargetSegments {
+    platforms?: ('ios' | 'android' | 'web')[];
+    minAppVersion?: string;
+    maxAppVersion?: string;
+    deviceIds?: string[];
+    regions?: string[];
+}
+export interface RolloutSchedule {
+    type: 'immediate' | 'gradual' | 'scheduled';
+    gradualSteps?: number[];
+    gradualInterval?: number;
+    scheduledTime?: RolloutTimestamp;
+}
+/**
+ * Device information used for rollout eligibility checks. Sent to the
+ * backend on `/v1/updates/check` via `X-Device-ID`, `X-Platform`,
+ * `X-App-Version` headers and used locally by `RolloutChecker` for
+ * deterministic percentile bucketing.
+ */
+export interface DeviceInfo {
+    deviceId: string;
+    platform: 'ios' | 'android' | 'web';
+    appVersion: string;
+    bundleVersion: string;
+    osVersion: string;
+    region?: string;
+    locale: string;
+}
+/**
+ * Normalized response from `GET /v1/updates/check`. The Laravel
+ * backend returns this exact shape (snake_case fields are mapped on
+ * the wire — this interface is the camelCase local form).
+ */
+export interface UpdateCheckResponse {
+    updateAvailable: boolean;
+    version?: string;
+    bundleUrl?: string;
+    minNativeVersion?: string;
+    releaseNotes?: string;
+    signature?: string;
+    checksum?: string;
+    mandatory?: boolean;
+    size?: number;
+    delta?: {
+        available: boolean;
+        patchUrl?: string;
+        patchSize?: number;
+        patchChecksum?: string;
+        targetChecksum?: string;
+    };
+    rolloutEligible?: boolean;
+    rolloutReason?: string;
+}

package/dist/esm/types/rollout.js

@@ -0,0 +1,25 @@
+/**
+ * Rollout + update-check types.
+ *
+ * These types describe staged-rollout configuration and the response
+ * shape the Laravel backend returns from `GET /v1/updates/check`.
+ * They were previously co-located with the Firestore schema; v3 of the
+ * plugin dropped Firestore as a backend, so the types live here in a
+ * backend-neutral location.
+ */
+/**
+ * Convert a `RolloutTimestamp` to epoch milliseconds. Throws on a
+ * value that doesn't parse — callers are expected to validate before
+ * persisting rollout config.
+ */
+export function toEpochMs(value) {
+    if (typeof value === 'number')
+        return value;
+    if (value instanceof Date)
+        return value.getTime();
+    const parsed = new Date(value).getTime();
+    if (Number.isNaN(parsed)) {
+        throw new Error(`Invalid rollout timestamp: ${String(value)}`);
+    }
+    return parsed;
+}

package/dist/esm/web.d.ts

@@ -11,6 +11,7 @@ export declare class NativeUpdateWeb extends WebPlugin implements NativeUpdateCo
     private backgroundCheckInterval;
     private configManager;
     private isConfigured;
+    private downloadedBundleBytes;
     constructor();
     /**
      * Configuration and Core Methods
@@ -33,6 +34,10 @@ export declare class NativeUpdateWeb extends WebPlugin implements NativeUpdateCo
     notifyAppReady(): Promise<void>;
     getLatest(): Promise<LatestVersion>;
     setChannel(channel: string): Promise<void>;
+    /**
+     * @deprecated since v2. See NativeUpdatePluginWeb.setUpdateUrl in plugin.ts.
+     * Update URL is locked after initialize(); this method is a no-op.
+     */
     setUpdateUrl(url: string): Promise<void>;
     validateUpdate(options: ValidateOptions): Promise<ValidationResult>;
     /**
@@ -82,7 +87,11 @@ export declare class NativeUpdateWeb extends WebPlugin implements NativeUpdateCo
      */
     private validateChecksum;
     /**
-     * Validate digital signature using RSA-PSS or ECDSA
+     * Validate digital signature using RSA-PSS or ECDSA.
+     *
+     * Fails closed: if the host app configured a public key or
+     * requireSignature, a missing signature throws. Silent-pass was a P0 gap.
+     *
      * @param data - The data that was signed (as string path or ArrayBuffer)
      * @param signature - The signature to verify (base64 encoded)
      */
@@ -99,8 +108,24 @@ export declare class NativeUpdateWeb extends WebPlugin implements NativeUpdateCo
      * Import ECDSA public key from PEM format
      */
     private importPublicKeyECDSA;
+    /**
+     * Safe localStorage accessor. Returns `null` in environments where
+     * `localStorage` isn't available — SSR, Node-only test runners that
+     * stub `window` without storage, or sandboxed iframes. All callers
+     * MUST tolerate a `null` return and skip persistence.
+     */
+    private getLocalStorage;
     private loadStoredData;
     private saveStoredData;
+    /**
+     * Strip secrets before persisting config to localStorage. A browser's
+     * localStorage is accessible to any script running in the page (XSS,
+     * compromised deps) — an `apiKey` or `publicKey` sitting there is a
+     * ready-to-use credential. Host apps must pass these on every
+     * `initialize()` call; they are never cached cross-session.
+     */
+    private static readonly SENSITIVE_CONFIG_PATHS;
+    private sanitizeConfigForPersistence;
     private saveConfiguration;
     private getInstallDate;
     private incrementLaunchCount;