Merge pull request #26 from KGAudioLab/feat/2026-01-17-add-option-allow-persist-api-key-on-non-localhost

Feat/2026 01 17 add option allow persist api key on non localhost

README.md

@@ -48,7 +48,7 @@ This project investigates how AI-human collaboration can enhance creative music-
   - Click here to start using the app online: [K.G.Studio (kgaudiolab.github.io/kgstudio)](https://kgaudiolab.github.io/kgstudio)
   - [Click here to get a free OpenRouter API Key](https://openrouter.ai/keys) (you may need an OpenRouter account).
   - In **Settings ⚙️ → General → LLM Provider**, select **OpenAI Compatible**.
-  - In **OpenAI Compatible Server → Key**, paste your key. (Note: on non‑localhost, your key isn’t persisted; you’ll re‑enter it after refresh the page. Keep it safe.)
+  - In **OpenAI Compatible Server → Key**, paste your key. (Note: on non‑localhost, your key isn't persisted by default for security; you can enable "Persist API Keys on Non-Localhost" in Settings to persist them, though this may increase XSS risk.)
   - In **OpenAI Compatible Server → Model**, enter `qwen/qwen3-30b-a3b:free` or `qwen/qwen3-235b-a22b:free`. (Note: these are free models [qwen3-30b-a3b](https://openrouter.ai/qwen/qwen3-30b-a3b:free) and [qwen3-235b-a22b](https://openrouter.ai/qwen/qwen3-235b-a22b:free); non‑free models may require billing; some model providers may retain your data, check their privacy policies; this project is not affiliated with OpenRouter or any model provider.)
   - In **OpenAI Compatible Server → Base URL**, enter `https://openrouter.ai/api/v1/chat/completions`.
 
@@ -110,6 +110,7 @@ K.G.Studio loads defaults from `./public/config.json` (with an internal fallback
 - **General**
   - LLM provider: OpenAI, or OpenAI‑compatible
   - API keys and models for the selected provider
+  - Persist API Keys on Non-Localhost: Enable to persist API keys on non-localhost environments (security opt-in, not recommended for shared/production environments)
   - OpenAI‑compatible base URL (for self‑hosted gateways)
   - Soundfont base URL (CDN for instrument samples)
 - **Behavior**
@@ -125,7 +126,7 @@ K.G.Studio loads defaults from `./public/config.json` (with an internal fallback
   - Downloading instrument sound samples from the configured soundfont CDN
   - Communicating with the LLM provider you select (e.g., OpenAI or OpenAI‑compatible services)
 - Outside of the two cases above, the app functions locally. If you block those endpoints, the app still loads; instrument playback and AI features will not function until network access is restored.
-- For security, when running from a non‑local host we do not persist your API key in IndexedDB (to reduce XSS risk). You’ll be prompted to enter it each time you start K.G.Studio.
+- For security, when running from a non‑local host we do not persist your API key in IndexedDB by default (to reduce XSS risk). You'll be prompted to enter it each time you start K.G.Studio. To opt‑in to persistence on non‑local hosts, enable "Persist API Keys on Non-Localhost" in Settings (not recommended for shared/production environments).
 
 ## Using the App
 
@@ -223,7 +224,7 @@ OpenRouter is a platform that provides unified access to a wide range of languag
 
 Currently, based on our evaluation, OpenAI’s open‑source models (`gpt‑oss‑20b` and `gpt‑oss‑120b`) are not yet compatible with the current agent implementation; support is planned.
 
-For security, when using K.G.Studio from a non‑local host, API keys are not persisted in IndexedDB; you will need to input your API key each time you start K.G.Studio.
+For security, when using K.G.Studio from a non‑local host, API keys are not persisted in IndexedDB by default; you will need to input your API key each time you start K.G.Studio. To opt‑in to persistence on non‑local hosts, enable "Persist API Keys on Non-Localhost" in Settings (not recommended for shared/production environments).
 
 K.G.Studio does not provide or host any of the models listed above, nor is it affiliated with any model provider. All data is stored locally on your device; K.G.Studio does not collect or transmit your data. You are solely responsible for any data you provide to third‑party model providers.
 

docs/USER_GUIDE.md

@@ -36,7 +36,7 @@ A lightweight, browser‑based DAW with an AI Agent "K.G.Studio Musician Assista
 - K.G.Studio is fully client‑side. It connects to the network only to:
   - Download instrument soundfonts from the configured CDN
   - Communicate with your chosen LLM provider (OpenAI or OpenAI‑compatible)
-- API keys are not persisted when running from a non‑local host (to reduce XSS risk). You’ll be prompted to re‑enter them on each start in that scenario.
+- API keys are not persisted when running from a non‑local host (to reduce XSS risk). You'll be prompted to re‑enter them on each start in that scenario. To opt‑in to persistence on non‑local hosts, enable "Persist API Keys on Non-Localhost" in Settings > General (not recommended for shared/production environments).
 - Important: While K.G.Studio does not collect your data, different LLM providers may have different data‑retention policies. Review the policy of the provider you select before use.
 
 ## 5. User Interface Tour
@@ -125,10 +125,10 @@ A lightweight, browser‑based DAW with an AI Agent "K.G.Studio Musician Assista
 - If loading stalls, the overlay will time out; refresh to retry downloading.
 
 ## 13. Settings
-- General: LLM provider (OpenAI or OpenAI‑compatible), API key, model, soundfont base URL.
+- General: LLM provider (OpenAI or OpenAI‑compatible), API key, model, soundfont base URL, Persist API Keys on Non-Localhost.
 - Behavior: chatbox default open at startup.
 - Templates: custom instructions for the AI.
-- Settings persist in IndexedDB (local); API keys are not persisted on non‑local hosts.
+- Settings persist in IndexedDB (local); API keys are not persisted on non‑local hosts unless you opt‑in via the "Persist API Keys on Non-Localhost" setting (not recommended for shared/production environments).
 
 ## 14. AI Agent "K.G.Studio Musician Assistant"
 - Open the chat (toolbar). Describe goals in natural language (e.g., “Can you help me write a 4‑bar chord progression for the melody?”).

public/config.json

@@ -2,6 +2,7 @@
     "general": {
         "language": "en_us",
         "llm_provider": "openai",
+        "persist_api_keys_non_localhost": false,
         "openai": {
             "api_key": "",
             "flex": false,

src/components/settings/sections/GeneralSettings.tsx

@@ -13,6 +13,7 @@ const GeneralSettings: React.FC = () => {
   const [claudeOpenRouterBaseUrl, setClaudeOpenRouterBaseUrl] = useState<string>('');
   const [claudeOpenRouterModel, setClaudeOpenRouterModel] = useState<string>('');
   const [openaiFlex, setOpenaiFlex] = useState<boolean>(false);
+  const [persistApiKeysNonLocalhost, setPersistApiKeysNonLocalhost] = useState<boolean>(false);
   const [compatibleKey, setCompatibleKey] = useState<string>('');
   const [compatibleBaseUrl, setCompatibleBaseUrl] = useState<string>('');
   const [compatibleModel, setCompatibleModel] = useState<string>('');
@@ -45,6 +46,7 @@ const GeneralSettings: React.FC = () => {
       setOpenaiKey((configManager.get('general.openai.api_key') as string) || '');
       setOpenaiModel((configManager.get('general.openai.model') as string) || '');
       setOpenaiFlex((configManager.get('general.openai.flex') as boolean) ?? false);
+      setPersistApiKeysNonLocalhost((configManager.get('general.persist_api_keys_non_localhost') as boolean) ?? false);
       setGeminiKey((configManager.get('general.gemini.api_key') as string) || '');
       setGeminiModel((configManager.get('general.gemini.model') as string) || '');
       setClaudeKey((configManager.get('general.claude.api_key') as string) || '');
@@ -107,6 +109,17 @@ const GeneralSettings: React.FC = () => {
     }
   };
 
+  const handlePersistApiKeysNonLocalhostChange = async (value: string) => {
+    const boolValue = value === 'yes';
+    setPersistApiKeysNonLocalhost(boolValue);
+    try {
+      await configManager.set('general.persist_api_keys_non_localhost', boolValue);
+      console.log('Persist API Keys Non-Localhost changed to:', boolValue);
+    } catch (error) {
+      console.error('Failed to save Persist API Keys Non-Localhost:', error);
+    }
+  };
+
   const handleGeminiKeyChange = (value: string) => {
     setGeminiKey(value);
     debouncedSave('general.gemini.api_key', value);
@@ -189,6 +202,23 @@ const GeneralSettings: React.FC = () => {
               <option value="openai_compatible">OpenAI Compatible (e.g. OpenRouter, Ollama)</option>
             </select>
           </div>
+
+          <div className="settings-item">
+            <label className="settings-label">
+              Persist API Keys on Non-Localhost
+            </label>
+            <select
+              className="settings-select"
+              value={persistApiKeysNonLocalhost ? 'yes' : 'no'}
+              onChange={(e) => handlePersistApiKeysNonLocalhostChange(e.target.value)}
+            >
+              <option value="no">No</option>
+              <option value="yes">Yes</option>
+            </select>
+            <div className="settings-help" style={{ fontSize: '12px', color: '#888', marginTop: '4px' }}>
+              When enabled, API keys will be saved to browser storage even on non-localhost environments. Warning: This may increase security vulnerability to XSS attacks.
+            </div>
+          </div>
         </div>
 
         <div className="settings-group">
@@ -207,6 +237,8 @@ const GeneralSettings: React.FC = () => {
             />
             <div className="settings-help" style={{ fontSize: '12px', color: '#888', marginTop: '4px' }}>
               {isLocalEnvironment
+                ? 'Keys are persisted locally (the IndexedDB in your browser).'
+                : persistApiKeysNonLocalhost
                   ? 'Keys are persisted locally (the IndexedDB in your browser).'
                   : 'For security, keys are not persisted on non-local hosts and are kept in-memory for this session.'}
             </div>
@@ -322,6 +354,8 @@ const GeneralSettings: React.FC = () => {
             />
             <div className="settings-help" style={{ fontSize: '12px', color: '#888', marginTop: '4px' }}>
               {isLocalEnvironment
+                ? 'Keys are persisted locally (the IndexedDB in your browser).'
+                : persistApiKeysNonLocalhost
                   ? 'Keys are persisted locally (the IndexedDB in your browser).'
                   : 'For security, keys are not persisted on non-local hosts and are kept in-memory for this session.'}
             </div>
@@ -376,6 +410,8 @@ const GeneralSettings: React.FC = () => {
             />
             <div className="settings-help" style={{ fontSize: '12px', color: '#888', marginTop: '4px' }}>
               {isLocalEnvironment
+                ? 'Keys are persisted locally (the IndexedDB in your browser).'
+                : persistApiKeysNonLocalhost
                   ? 'Keys are persisted locally (the IndexedDB in your browser).'
                   : 'For security, keys are not persisted on non-local hosts and are kept in-memory for this session.'}
             </div>

src/core/config/ConfigManager.ts

@@ -8,6 +8,7 @@ interface AppConfig {
   general: {
     language: string;
     llm_provider: 'openai' | 'gemini' | 'claude' | 'claude_openrouter' | 'openai_compatible';
+    persist_api_keys_non_localhost: boolean;
     openai: {
       api_key: string;
       flex: boolean;
@@ -172,6 +173,7 @@ export class ConfigManager {
         general: {
           language: 'en_us',
           llm_provider: 'openai',
+          persist_api_keys_non_localhost: false,
           openai: {
             api_key: '',
             flex: false,
@@ -283,11 +285,11 @@ export class ConfigManager {
    */
   private async saveToStorage(): Promise<void> {
     try {
-      // For security: if not running on a local host, do not persist API keys.
+      const shouldSanitize = !this.isRunningOnLocalhost() &&
-      // We still keep them in memory (this.config) for runtime usage.
+        !this.config.general.persist_api_keys_non_localhost;
-      const configToPersist = this.isRunningOnLocalhost()
+      const configToPersist = shouldSanitize
-        ? this.config
+        ? this.getSanitizedConfigForStorage()
-        : this.getSanitizedConfigForStorage();
+        : this.config;
 
       await this.storage.save(
         DB_CONSTANTS.DB_NAME,
@@ -540,12 +542,12 @@ export class ConfigManager {
    * for persistence to storage in non-local environments.
    */
   private getSanitizedConfigForStorage(): AppConfig {
-    // Deep copy to avoid mutating in-memory config
     const copied: AppConfig = JSON.parse(JSON.stringify(this.config));
     if (copied?.general) {
       if (copied.general.openai) copied.general.openai.api_key = '';
       if (copied.general.gemini) copied.general.gemini.api_key = '';
       if (copied.general.claude) copied.general.claude.api_key = '';
+      if (copied.general.claude_openrouter) copied.general.claude_openrouter.api_key = '';
       if (copied.general.openai_compatible) copied.general.openai_compatible.api_key = '';
     }
     return copied;

vite.config.ts

@@ -16,4 +16,8 @@ export default defineConfig({
   define: {
     __APP_VERSION__: JSON.stringify(version),
   },
+  server: {
+    // IMPORTANT: MAKE SURE TO UPDATE YOUR OS HOSTS FILE TO POINT `testlocal.com` TO YOUR LOCAL IP (e.g. 127.0.0.1).
+    allowedHosts: ['testlocal.com', '.testlocal.com', 'localhost', '127.0.0.1'],
+  },
 })