@ojolowoblue/lamba 1.0.5 → 1.0.7

package/README.md

@@ -167,7 +167,7 @@ const isNewHeader = useLambaEnv<boolean>('VITE_NEW_HEADER', false);
 
 ### `lamba.init(options?: LambaOptions): LambaManager`
 
-Initializes the lamba manager, hydrates saved overrides from `localStorage`, enables network interceptors, and mounts the floating Shadow DOM UI.
+Initializes the lamba manager, hydrates saved overrides from the configured storage backend, enables network interceptors, and mounts the floating Shadow DOM UI.
 
 | Option | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
@@ -178,6 +178,8 @@ Initializes the lamba manager, hydrates saved overrides from `localStorage`, ena
 | `autoFetchEnvFile` | `boolean` | `false` | Whether to attempt fetching root `/.env` file during local development. |
 | `interceptNetworkRequests` | `boolean` | `true` | Whether to implicitly intercept `fetch` & `XHR` calls matching original base URLs. |
 | `allowedPrefixes` | `string \| string[] \| RegExp \| null` | `null` | Optional prefix filter (e.g. `['VITE_', 'NEXT_PUBLIC_']`). Omitting allows ALL keys regardless of prefix. |
+| `storageStrategy` | `'local' \| 'session' \| 'memory'` | `'local'` | Where overrides and presets are persisted. See [Storage Strategies](#-storage-strategies) below. |
+| `storage` | `LambaStorageAdapter` | `undefined` | Provide a fully custom storage adapter. Takes precedence over `storageStrategy`. |
 
 ---
 
@@ -187,7 +189,7 @@ Initializes the lamba manager, hydrates saved overrides from `localStorage`, ena
 Returns the active value for the specified environment key (returns active override if present, otherwise default value or fallback). Preserves numbers, booleans, and objects.
 
 #### `lamba.set(key: string, value: any): void`
-Programmatically overrides an environment variable live at runtime with any data type. The change is persisted in `localStorage` and triggers UI and listener updates.
+Programmatically overrides an environment variable live at runtime with any data type. The change is persisted in the configured storage backend and triggers UI and listener updates.
 
 #### `lamba.remove(key: string): void`
 Removes an override for a specific environment variable key, reverting it to its default value.
@@ -212,6 +214,57 @@ Programmatically controls the visibility of the lamba modal panel.
 
 ---
 
+## 🔐 Storage Strategies
+
+Control where lamba persists overrides and presets via the `storageStrategy` option:
+
+| Strategy | Visibility in DevTools | Survives Tab Close? | XSS Storage Scraping Risk |
+| :--- | :--- | :--- | :--- |
+| `'local'` *(default)* | ⚠️ Visible (plain-text) | ✅ Yes (Indefinitely) | ⚠️ Yes |
+| `'session'` | ⚠️ Visible (plain-text) | ❌ No (Cleared on close) | ⚠️ Yes |
+| `'memory'` | ✅ **Not visible (0 bytes stored)** | ❌ No (GC'd on close) | ✅ **No** |
+
+### In-Memory (Most Secure)
+
+```typescript
+lamba.init({
+  storageStrategy: 'memory', // Nothing written to DevTools Storage
+  env: { VITE_API_URL: import.meta.env.VITE_API_URL },
+});
+```
+
+### Session (Tab-Ephemeral)
+
+```typescript
+lamba.init({
+  storageStrategy: 'session', // Cleared automatically when tab closes
+  env: { VITE_API_URL: import.meta.env.VITE_API_URL },
+});
+```
+
+### Custom Adapter
+
+Implement the `LambaStorageAdapter` interface to plug in any storage backend (encrypted storage, Electron keytar, IndexedDB, etc.):
+
+```typescript
+import lamba, { type LambaStorageAdapter } from '@ojolowoblue/lamba';
+
+// Example: an encrypted wrapper around sessionStorage
+const encryptedAdapter: LambaStorageAdapter = {
+  getItem: (key) => decrypt(sessionStorage.getItem(key)),
+  setItem: (key, value) => sessionStorage.setItem(key, encrypt(value)),
+  removeItem: (key) => sessionStorage.removeItem(key),
+  clear: () => sessionStorage.clear(),
+};
+
+lamba.init({
+  storage: encryptedAdapter,
+  env: { VITE_API_URL: import.meta.env.VITE_API_URL },
+});
+```
+
+---
+
 ## 🔒 Production Security Best Practice
 
 To prevent end-users from overriding environment variables in production, conditionally initialize `lamba` only in non-production environments:
@@ -221,6 +274,7 @@ import lamba from '@ojolowoblue/lamba';
 
 lamba.init({
   enabled: process.env.NODE_ENV !== 'production',
+  storageStrategy: 'memory', // Use memory storage so nothing lingers in DevTools
   env: {
     VITE_API_URL: import.meta.env.VITE_API_URL,
   },
@@ -233,12 +287,12 @@ lamba.init({
 
 <details>
 <summary><b>Does lamba modify my local <code>.env</code> files on disk?</b></summary>
-<p>No. <code>lamba</code> operates entirely in browser memory and persists overrides in <code>localStorage</code>. It does not write to disk, so your git status remains clean.</p>
+<p>No. <code>lamba</code> operates entirely in browser memory and optionally persists overrides in storage. It does not write to disk, so your git status remains clean.</p>
 </details>
 
 <details>
 <summary><b>Do overrides persist when I refresh the page?</b></summary>
-<p>Yes. Overrides and active preset profiles are saved in <code>localStorage</code> and automatically restored upon page reloads.</p>
+<p>It depends on the <code>storageStrategy</code>. With <code>'local'</code> (default), overrides persist indefinitely. With <code>'session'</code>, they survive reloads but clear when the tab is closed. With <code>'memory'</code>, overrides are lost on any page reload.</p>
 </details>
 
 <details>

package/dist/index.d.mts

@@ -1,3 +1,50 @@
+/**
+ * Abstract interface for pluggable storage backends used by lamba to persist
+ * overrides and presets. All methods are synchronous for simplicity (async
+ * adapters can wrap with Promises if needed in custom implementations).
+ */
+interface LambaStorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+/**
+ * LocalStorage-backed adapter (default).
+ * Overrides persist indefinitely across tabs and page reloads.
+ * Visible in DevTools → Application → Local Storage.
+ */
+declare class LocalStorageAdapter implements LambaStorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+/**
+ * SessionStorage-backed adapter.
+ * Overrides survive page reloads within the same tab, but are automatically
+ * destroyed when the tab is closed. Still visible in DevTools Storage panel.
+ */
+declare class SessionStorageAdapter implements LambaStorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+/**
+ * In-memory adapter.
+ * The most secure option: zero bytes written to any browser storage mechanism.
+ * Overrides exist only in JavaScript heap memory and are destroyed when the
+ * tab/page is closed or navigated away. Nothing appears in DevTools Storage.
+ */
+declare class MemoryStorageAdapter implements LambaStorageAdapter {
+    private store;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+
 interface EnvVariable {
     key: string;
     value: any;
@@ -46,6 +93,22 @@ interface LambaOptions {
      * If omitted, null, or empty, ALL environment variable keys are allowed and supported regardless of prefix.
      */
     allowedPrefixes?: string | string[] | RegExp | null;
+    /**
+     * Storage strategy for persisting overrides and presets across page reloads:
+     * - `'local'`   — (default) Standard `localStorage`. Persists indefinitely across tabs & reloads.
+     *               Visible in DevTools → Application → Local Storage.
+     * - `'session'` — `sessionStorage`. Survives page reloads within the same tab, but cleared
+     *               when the tab is closed. Visible in DevTools → Application → Session Storage.
+     * - `'memory'`  — In-memory only. Most secure option — zero bytes written to any browser storage.
+     *               Overrides are destroyed when the tab closes or navigates away.
+     *               Nothing appears in DevTools Storage.
+     */
+    storageStrategy?: 'local' | 'session' | 'memory';
+    /**
+     * Provide a fully custom storage adapter that conforms to the `LambaStorageAdapter` interface.
+     * When provided, this takes precedence over `storageStrategy`.
+     */
+    storage?: LambaStorageAdapter;
 }
 type EnvChangeListener = (key: string, value: any, isOverridden: boolean) => void;
 type StoreChangeListener = (variables: Record<string, EnvVariable>, presets: PresetProfile[], activePresetId: string | null) => void;
@@ -97,6 +160,15 @@ declare class LambaManager {
      * Resets all environment variable overrides.
      */
     reset(): void;
+    /**
+     * Removes ALL lamba data from storage (overrides, presets, active preset).
+     * Safe to call even when lamba has not been initialized.
+     * Useful when disabling lamba to ensure no stale data remains in the browser.
+     *
+     * @param options - Optionally pass storage options to target the correct adapter.
+     *                  Defaults to 'local' (localStorage) to cover the common case.
+     */
+    purge(options?: Pick<LambaOptions, 'storageStrategy' | 'storage'>): void;
     /**
      * Subscribes to environment variable changes.
      */
@@ -116,4 +188,4 @@ declare class LambaManager {
 }
 declare const lamba: LambaManager;
 
-export { type EnvChangeListener, type EnvVariable, LambaManager, type LambaOptions, type PresetProfile, type StoreChangeListener, lamba as default, lamba, parseEnvString, stringifyEnv };
+export { type EnvChangeListener, type EnvVariable, LambaManager, type LambaOptions, type LambaStorageAdapter, LocalStorageAdapter, MemoryStorageAdapter, type PresetProfile, SessionStorageAdapter, type StoreChangeListener, lamba as default, lamba, parseEnvString, stringifyEnv };

package/dist/index.d.ts

@@ -1,3 +1,50 @@
+/**
+ * Abstract interface for pluggable storage backends used by lamba to persist
+ * overrides and presets. All methods are synchronous for simplicity (async
+ * adapters can wrap with Promises if needed in custom implementations).
+ */
+interface LambaStorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+/**
+ * LocalStorage-backed adapter (default).
+ * Overrides persist indefinitely across tabs and page reloads.
+ * Visible in DevTools → Application → Local Storage.
+ */
+declare class LocalStorageAdapter implements LambaStorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+/**
+ * SessionStorage-backed adapter.
+ * Overrides survive page reloads within the same tab, but are automatically
+ * destroyed when the tab is closed. Still visible in DevTools Storage panel.
+ */
+declare class SessionStorageAdapter implements LambaStorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+/**
+ * In-memory adapter.
+ * The most secure option: zero bytes written to any browser storage mechanism.
+ * Overrides exist only in JavaScript heap memory and are destroyed when the
+ * tab/page is closed or navigated away. Nothing appears in DevTools Storage.
+ */
+declare class MemoryStorageAdapter implements LambaStorageAdapter {
+    private store;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+
 interface EnvVariable {
     key: string;
     value: any;
@@ -46,6 +93,22 @@ interface LambaOptions {
      * If omitted, null, or empty, ALL environment variable keys are allowed and supported regardless of prefix.
      */
     allowedPrefixes?: string | string[] | RegExp | null;
+    /**
+     * Storage strategy for persisting overrides and presets across page reloads:
+     * - `'local'`   — (default) Standard `localStorage`. Persists indefinitely across tabs & reloads.
+     *               Visible in DevTools → Application → Local Storage.
+     * - `'session'` — `sessionStorage`. Survives page reloads within the same tab, but cleared
+     *               when the tab is closed. Visible in DevTools → Application → Session Storage.
+     * - `'memory'`  — In-memory only. Most secure option — zero bytes written to any browser storage.
+     *               Overrides are destroyed when the tab closes or navigates away.
+     *               Nothing appears in DevTools Storage.
+     */
+    storageStrategy?: 'local' | 'session' | 'memory';
+    /**
+     * Provide a fully custom storage adapter that conforms to the `LambaStorageAdapter` interface.
+     * When provided, this takes precedence over `storageStrategy`.
+     */
+    storage?: LambaStorageAdapter;
 }
 type EnvChangeListener = (key: string, value: any, isOverridden: boolean) => void;
 type StoreChangeListener = (variables: Record<string, EnvVariable>, presets: PresetProfile[], activePresetId: string | null) => void;
@@ -97,6 +160,15 @@ declare class LambaManager {
      * Resets all environment variable overrides.
      */
     reset(): void;
+    /**
+     * Removes ALL lamba data from storage (overrides, presets, active preset).
+     * Safe to call even when lamba has not been initialized.
+     * Useful when disabling lamba to ensure no stale data remains in the browser.
+     *
+     * @param options - Optionally pass storage options to target the correct adapter.
+     *                  Defaults to 'local' (localStorage) to cover the common case.
+     */
+    purge(options?: Pick<LambaOptions, 'storageStrategy' | 'storage'>): void;
     /**
      * Subscribes to environment variable changes.
      */
@@ -116,4 +188,4 @@ declare class LambaManager {
 }
 declare const lamba: LambaManager;
 
-export { type EnvChangeListener, type EnvVariable, LambaManager, type LambaOptions, type PresetProfile, type StoreChangeListener, lamba as default, lamba, parseEnvString, stringifyEnv };
+export { type EnvChangeListener, type EnvVariable, LambaManager, type LambaOptions, type LambaStorageAdapter, LocalStorageAdapter, MemoryStorageAdapter, type PresetProfile, SessionStorageAdapter, type StoreChangeListener, lamba as default, lamba, parseEnvString, stringifyEnv };

package/dist/index.js

@@ -21,6 +21,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   LambaManager: () => LambaManager,
+  LocalStorageAdapter: () => LocalStorageAdapter,
+  MemoryStorageAdapter: () => MemoryStorageAdapter,
+  SessionStorageAdapter: () => SessionStorageAdapter,
   default: () => index_default,
   lamba: () => lamba,
   parseEnvString: () => parseEnvString,
@@ -32,34 +35,33 @@ module.exports = __toCommonJS(index_exports);
 var STORAGE_PRESETS_KEY = "__lamba_presets__";
 var STORAGE_ACTIVE_PRESET_KEY = "__lamba_active_preset__";
 var PresetManager = class {
-  constructor() {
+  constructor(storage) {
     this.presets = [];
     this.activePresetId = null;
+    this.storage = storage;
     this.loadFromStorage();
   }
   loadFromStorage() {
-    if (typeof localStorage === "undefined") return;
     try {
-      const rawPresets = localStorage.getItem(STORAGE_PRESETS_KEY);
+      const rawPresets = this.storage.getItem(STORAGE_PRESETS_KEY);
       if (rawPresets) {
         this.presets = JSON.parse(rawPresets);
       }
-      this.activePresetId = localStorage.getItem(STORAGE_ACTIVE_PRESET_KEY);
+      this.activePresetId = this.storage.getItem(STORAGE_ACTIVE_PRESET_KEY);
     } catch (e) {
-      console.warn("[lamba] Failed to parse presets from localStorage", e);
+      console.warn("[lamba] Failed to parse presets from storage", e);
     }
   }
   saveToStorage() {
-    if (typeof localStorage === "undefined") return;
     try {
-      localStorage.setItem(STORAGE_PRESETS_KEY, JSON.stringify(this.presets));
+      this.storage.setItem(STORAGE_PRESETS_KEY, JSON.stringify(this.presets));
       if (this.activePresetId) {
-        localStorage.setItem(STORAGE_ACTIVE_PRESET_KEY, this.activePresetId);
+        this.storage.setItem(STORAGE_ACTIVE_PRESET_KEY, this.activePresetId);
       } else {
-        localStorage.removeItem(STORAGE_ACTIVE_PRESET_KEY);
+        this.storage.removeItem(STORAGE_ACTIVE_PRESET_KEY);
       }
     } catch (e) {
-      console.warn("[lamba] Failed to save presets to localStorage", e);
+      console.warn("[lamba] Failed to save presets to storage", e);
     }
   }
   getPresets() {
@@ -211,6 +213,99 @@ async function tryFetchRootEnvFile() {
   return {};
 }
 
+// src/core/storage.ts
+var LocalStorageAdapter = class {
+  getItem(key) {
+    try {
+      return typeof localStorage !== "undefined" ? localStorage.getItem(key) : null;
+    } catch {
+      return null;
+    }
+  }
+  setItem(key, value) {
+    try {
+      if (typeof localStorage !== "undefined") localStorage.setItem(key, value);
+    } catch {
+    }
+  }
+  removeItem(key) {
+    try {
+      if (typeof localStorage !== "undefined") localStorage.removeItem(key);
+    } catch {
+    }
+  }
+  clear() {
+    try {
+      if (typeof localStorage !== "undefined") {
+        localStorage.removeItem("__lamba_overrides__");
+        localStorage.removeItem("__lamba_presets__");
+        localStorage.removeItem("__lamba_active_preset__");
+      }
+    } catch {
+    }
+  }
+};
+var SessionStorageAdapter = class {
+  getItem(key) {
+    try {
+      return typeof sessionStorage !== "undefined" ? sessionStorage.getItem(key) : null;
+    } catch {
+      return null;
+    }
+  }
+  setItem(key, value) {
+    try {
+      if (typeof sessionStorage !== "undefined") sessionStorage.setItem(key, value);
+    } catch {
+    }
+  }
+  removeItem(key) {
+    try {
+      if (typeof sessionStorage !== "undefined") sessionStorage.removeItem(key);
+    } catch {
+    }
+  }
+  clear() {
+    try {
+      if (typeof sessionStorage !== "undefined") {
+        sessionStorage.removeItem("__lamba_overrides__");
+        sessionStorage.removeItem("__lamba_presets__");
+        sessionStorage.removeItem("__lamba_active_preset__");
+      }
+    } catch {
+    }
+  }
+};
+var MemoryStorageAdapter = class {
+  constructor() {
+    this.store = /* @__PURE__ */ new Map();
+  }
+  getItem(key) {
+    return this.store.get(key) ?? null;
+  }
+  setItem(key, value) {
+    this.store.set(key, value);
+  }
+  removeItem(key) {
+    this.store.delete(key);
+  }
+  clear() {
+    this.store.clear();
+  }
+};
+function createStorageAdapter(strategy = "local", custom) {
+  if (custom) return custom;
+  switch (strategy) {
+    case "session":
+      return new SessionStorageAdapter();
+    case "memory":
+      return new MemoryStorageAdapter();
+    case "local":
+    default:
+      return new LocalStorageAdapter();
+  }
+}
+
 // src/core/store.ts
 var STORAGE_OVERRIDES_KEY = "__lamba_overrides__";
 var DEFAULT_SECRET_PATTERN = /(KEY|SECRET|TOKEN|PASSWORD|AUTH|PRIVATE|CREDENTIAL|SIGNATURE)/i;
@@ -222,7 +317,8 @@ var EnvStore = class {
     this.storeChangeListeners = /* @__PURE__ */ new Set();
     this.secretPattern = options.secretKeysPattern || DEFAULT_SECRET_PATTERN;
     this.allowedPrefixes = options.allowedPrefixes;
-    this.presetManager = new PresetManager();
+    this.storage = createStorageAdapter(options.storageStrategy ?? "local", options.storage);
+    this.presetManager = new PresetManager(this.storage);
     this.loadOverridesFromStorage();
     if (options.env) {
       this.mergeDefaults(options.env);
@@ -239,22 +335,20 @@ var EnvStore = class {
     this.patchProcessEnv();
   }
   loadOverridesFromStorage() {
-    if (typeof localStorage === "undefined") return;
     try {
-      const stored = localStorage.getItem(STORAGE_OVERRIDES_KEY);
+      const stored = this.storage.getItem(STORAGE_OVERRIDES_KEY);
       if (stored) {
         this.overrides = JSON.parse(stored);
       }
     } catch (e) {
-      console.warn("[lamba] Failed to parse overrides from localStorage", e);
+      console.warn("[lamba] Failed to parse overrides from storage", e);
     }
   }
   saveOverridesToStorage() {
-    if (typeof localStorage === "undefined") return;
     try {
-      localStorage.setItem(STORAGE_OVERRIDES_KEY, JSON.stringify(this.overrides));
+      this.storage.setItem(STORAGE_OVERRIDES_KEY, JSON.stringify(this.overrides));
     } catch (e) {
-      console.warn("[lamba] Failed to save overrides to localStorage", e);
+      console.warn("[lamba] Failed to save overrides to storage", e);
     }
   }
   /**
@@ -1475,7 +1569,10 @@ var LambaManager = class {
       interceptNetworkRequests: true,
       ...options
     };
-    if (this.options.enabled === false) return this;
+    if (this.options.enabled === false) {
+      this.purge(options);
+      return this;
+    }
     this.store = new EnvStore(this.options);
     if (this.options.interceptNetworkRequests !== false) {
       this.networkInterceptor = new NetworkInterceptor(this.store);
@@ -1532,6 +1629,18 @@ var LambaManager = class {
   reset() {
     this.store?.resetAllOverrides();
   }
+  /**
+   * Removes ALL lamba data from storage (overrides, presets, active preset).
+   * Safe to call even when lamba has not been initialized.
+   * Useful when disabling lamba to ensure no stale data remains in the browser.
+   *
+   * @param options - Optionally pass storage options to target the correct adapter.
+   *                  Defaults to 'local' (localStorage) to cover the common case.
+   */
+  purge(options) {
+    const adapter = this.store?.storage ?? createStorageAdapter(options?.storageStrategy ?? "local", options?.storage);
+    adapter.clear();
+  }
   /**
    * Subscribes to environment variable changes.
    */
@@ -1571,6 +1680,9 @@ var index_default = lamba;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   LambaManager,
+  LocalStorageAdapter,
+  MemoryStorageAdapter,
+  SessionStorageAdapter,
   lamba,
   parseEnvString,
   stringifyEnv