Security Architecture and CORS

Relevant source files

• README.md
• README_EN.md
• docker-compose.yml
• docs/user/mcp-server.md
• docs/user/mcp-server_en.md
• env.local.example
• mkdocs/docs/zh/user/mcp-server.md
• packages/core/src/services/model/defaults.ts
• packages/core/src/services/prompt/electron-proxy.ts
• packages/core/tests/unit/model/defaults.test.ts
• packages/desktop/main.js
• packages/desktop/preload.js
• packages/mcp-server/src/config/models.ts
• packages/ui/src/components/DataManager.vue
• packages/ui/src/components/LanguageSwitchDropdown.vue
• packages/ui/src/components/UpdaterIcon.vue
• packages/ui/src/i18n/README.md
• packages/ui/src/plugins/i18n.ts
• packages/ui/src/types/electron.d.ts
• vercel.json

This document describes the security architecture of the Prompt Optimizer application, with emphasis on Cross-Origin Resource Sharing (CORS) challenges and their solutions across different deployment platforms. It covers authentication mechanisms, data privacy model, and platform-specific security considerations.

For information about deployment configuration, see Environment Configuration and API Keys. For platform-specific implementations, see Platform Implementations.

Overview of Security Model

Prompt Optimizer implements a client-side security architecture where all sensitive operations occur within the user's environment. The application never routes API keys or user prompts through intermediate servers.

Security Principles:

Principle	Implementation
Zero Server Transit	API keys and prompts never pass through application servers
Client-Side Storage	All configuration and history stored locally (IndexedDB or file system)
Direct API Communication	Browser/desktop app communicates directly with AI providers
No Telemetry	No analytics or tracking beyond optional Vercel Analytics

Sources: README.md51-52 README.md79

CORS Challenges in Browser Environments

Cross-Origin Resource Sharing (CORS) is the primary security challenge for browser-based deployments. Modern browsers enforce the Same-Origin Policy, which blocks requests from a web application to a different domain unless explicitly allowed by the target server.

CORS Problem Space

CORS Failure Scenarios:

Scenario	Root Cause	Error Type
Local Ollama Connection	Default CORS policy blocks browser origins	Access-Control-Allow-Origin missing
Commercial APIs	Vendors don't enable browser CORS (security policy)	CORS preflight rejection
Mixed Content	HTTPS site → HTTP localhost blocked by browser	Mixed content violation

Sources: README.md355-357 README.md381-383

Mixed Content Security Policy

When the web application is served over HTTPS (e.g., online version, Vercel deployment), browsers enforce Mixed Content restrictions:

This security policy prevents HTTPS pages from making requests to HTTP endpoints, even if CORS is properly configured on the target server.

Sources: README.md381-389

CORS Solutions by Platform

Solution Matrix

Deployment Platform	CORS Constraint	Solution Mechanism
Desktop Application	None	Native app bypasses browser security
Chrome Extension	Partial	Extended permissions in manifest
Docker (HTTP)	Same-protocol only	HTTP app → HTTP APIs allowed
Vercel/Online (HTTPS)	Full browser restrictions	Cannot connect to HTTP services

Desktop Application (Recommended)

The desktop application using Electron provides the most robust solution to CORS challenges through a three-tier architecture with strict security boundaries.

Architecture and CORS Bypass

Electron Architecture with Code Entities

CORS Bypass Mechanisms:

Capability	Implementation	Code Location
No CORS Enforcement	Core services run in Node.js main process, bypass browser security	packages/desktop/main.js528-649
HTTP/HTTPS Mixed Content	Native app allows both protocols	Core adapters use Node.js fetch
Local Service Access	Direct socket connections to localhost services	packages/core/src/services/llm/
File System Access	FileStorageProvider writes to userData	packages/desktop/main.js589-594

System Proxy Support

Desktop app automatically detects and uses system proxy configuration for outbound requests:

Implementation at packages/desktop/main.js190-276:

• Resolves system proxy via session.defaultSession.resolveProxy()
• Supports PROXY, HTTPS, SOCKS5, DIRECT
• Configures undici.setGlobalDispatcher() for SDK requests
• Handles PAC/WPAD proxy auto-configuration

Sources: packages/desktop/main.js190-276 packages/desktop/main.js528-649 README.md102-106

Docker Deployment with HTTP

Docker deployments can serve the application over HTTP, allowing same-protocol communication with local HTTP services.

Configuration for Local Ollama:

Sources: README.md359-364 README.md385-388

Chrome Extension

The Chrome extension has intermediate CORS capabilities through browser extension APIs.

Manifest Permissions:

Extensions can request broad host permissions that bypass some CORS restrictions, though they still cannot violate Mixed Content policies from HTTPS extension pages.

Sources: README.md107-109

API Proxy Solutions

For web deployments requiring access to CORS-restricted APIs, users can deploy an API proxy service.

Proxy Configuration:

• Configure proxy URL as "Custom API" in Model Manager
• Proxy handles CORS headers and request routing
• Common proxies: OneAPI, NewAPI

Sources: README.md373-378

Electron Context Isolation and Preload Security

Electron enforces context isolation to prevent the renderer process from accessing privileged Node.js APIs. The preload.js script acts as the security boundary.

Context Isolation Architecture

Security Boundary Diagram

Sources: packages/desktop/preload.js1-10 packages/desktop/main.js25

Preload Script Security Model

The preload script at packages/desktop/preload.js implements strict IPC exposure:

IPC Handler Pattern

Key Security Patterns:

Pattern	Implementation	Purpose
Explicit API Surface	contextBridge.exposeInMainWorld('electronAPI', {...})	Only explicitly exposed APIs accessible
No Direct Node.js	Renderer cannot require() Node modules	Prevent arbitrary code execution
IPC Serialization	safeSerialize() at packages/desktop/preload.js23-36	Strip Vue reactivity, prevent object injection
Response Validation	createIpcError() at packages/desktop/preload.js43-78	Structured error handling across IPC boundary
Timeout Protection	withTimeout() at packages/desktop/preload.js23-36	Prevent hanging IPC calls

WebPreferences Configuration at packages/desktop/main.js409-413:

Exposed API Structure at packages/desktop/preload.js88-239:

• electronAPI.llm.* - LLM service methods
• electronAPI.model.* - Model manager methods
• electronAPI.template.* - Template manager methods
• electronAPI.history.* - History manager methods
• electronAPI.preference.* - Preference service methods
• electronAPI.image.* - Image service methods
• electronAPI.context.* - Context repository methods
• electronAPI.favorite.* - Favorite manager methods
• electronAPI.data.* - Data export/import methods

Each method validates input, invokes IPC, and handles errors consistently.

Sources: packages/desktop/preload.js1-239 packages/desktop/main.js405-414

Authentication and Access Control

Vercel Password Protection

Vercel deployments can enable password protection through the ACCESS_PASSWORD environment variable in Vercel project settings.

Configuration:

• Environment variable: ACCESS_PASSWORD=your_secure_password
• Middleware intercepts requests at edge before serving static files
• Single shared password (no per-user authentication)

Sources: README.md90-91 vercel.json24-31

Docker Basic Authentication

Docker deployments implement HTTP Basic Authentication via nginx, with special handling for the MCP endpoint.

Authentication Flow with MCP Bypass

Implementation Details

Authentication Script: docker/generate-auth.sh1-46

The script executes during container startup:

1. Check Password Configuration docker/generate-auth.sh4-14

2. Generate htpasswd File docker/generate-auth.sh22-25

3. Create Nginx Configuration docker/generate-auth.sh31-35

Nginx Location Blocks in docker/nginx.conf:

Location	Auth Requirement	Purpose
/	auth_basic (if enabled)	Web application access
/mcp	auth_basic off	MCP protocol endpoint (bypasses auth)

MCP Authentication Bypass:

The MCP endpoint explicitly disables authentication because:

• MCP protocol does not support HTTP Basic Authentication
• Used by local tools like Claude Desktop
• Protected by network isolation (typically localhost binding)

Configuration: Docker container exposes port 80 with nginx routing /mcp to internal port 3000.

Environment Variables:

Variable	Default	Purpose
ACCESS_USERNAME	admin	Basic auth username
ACCESS_PASSWORD	(none)	Basic auth password (required to enable)
NGINX_PORT	80	Internal nginx listening port

Docker Compose Configuration: docker-compose.yml39-42

Security Considerations:

• HTTP Basic Auth: Credentials in Authorization header (base64 encoded, not encrypted)
• Plaintext without HTTPS: Use reverse proxy (nginx, Caddy) with TLS termination
• Network Binding: Bind to 127.0.0.1 for localhost-only access
• MCP Endpoint: Exposed without auth; secure via network isolation
• Single Credential: No per-user authentication or session management

Recommended Production Setup:

With HTTPS reverse proxy handling TLS termination.

Sources: docker/generate-auth.sh1-46 docker-compose.yml39-42 README.md120-126 docs/user/mcp-server.md169-183

Data Privacy and Storage Security

Client-Side Storage Model

All user data persists locally without server synchronization. Storage backends implement the IStorageProvider interface.

Storage Implementation by Platform

Storage Format by Data Type:

Data Type	Browser Storage	Desktop Storage	Encryption
API Keys	IndexedDB via DexieStorageProvider	models.json in userData	None (OS-level protection)
Prompt History	IndexedDB collection	history.json	None
Templates	IndexedDB collection	templates.json	None
Preferences	IndexedDB collection	preferences.json	None
Context Data	IndexedDB collection	contexts.json	None

Storage Paths (Desktop):

• Windows: %APPDATA%/prompt-optimizer/ (resolved via app.getPath('userData'))
• macOS: ~/Library/Application Support/prompt-optimizer/
• Linux: ~/.config/prompt-optimizer/

Implementation: packages/desktop/main.js589-594

Backup and Recovery (Desktop):

FileStorageProvider implements automatic backups:

• Main data: <dataType>.json
• Backup: <dataType>.json.backup
• Recovery on corruption: automatic fallback to backup

Data Isolation:

Each deployment platform maintains independent storage:

• Browser instances isolated by origin (domain-specific IndexedDB)
• Desktop app has separate file system storage from browser versions
• Chrome extension uses chrome.storage.local API

Storage Information API (Desktop Only):

Desktop app exposes storage metadata via packages/desktop/preload.js786-793:

Used by DataManager.vue to display storage usage: packages/ui/src/components/DataManager.vue300-324

Sources: README.md79 packages/desktop/main.js589-594 packages/desktop/preload.js786-793 packages/ui/src/components/DataManager.vue14-52

API Key Security

API keys are stored in plaintext in local storage. Security relies on platform-specific protections and the zero-server-transit architecture.

Security Model:

1. OS-Level Protection: File system permissions (desktop) or browser security model (web)
2. No Network Transmission: Keys never sent to application servers
3. Direct API Usage: Keys used only for direct requests to AI providers
4. Local Storage Only: No cloud synchronization or backups

Configuration Hierarchy and Key Flow:

Configuration Priority: User-modified config in storage > Environment variables

Key resolution flow:

1. getDefaultTextModels() reads environment variables at packages/core/src/services/model/defaults.ts40-96
2. ModelManager persists configs to storage
3. User can override via Model Manager UI
4. LLMService retrieves keys from ModelManager at request time
5. Provider adapters inject keys into HTTP headers

Environment Variable Scanning:

Desktop and Docker deployments support dynamic custom model detection:

• Pattern: VITE_CUSTOM_API_KEY_<suffix>, VITE_CUSTOM_API_BASE_URL_<suffix>, VITE_CUSTOM_API_MODEL_<suffix>
• Scanning implementation: packages/desktop/main.js555-578
• Shared constants: CUSTOM_API_PATTERN, SUFFIX_PATTERN from @prompt-optimizer/core

Runtime Injection (Desktop):

Electron main process builds runtime_config object injected into renderer:

• Function: buildRuntimeConfigScriptFromEnv() at packages/desktop/main.js355-378
• Injects all VITE_* environment variables as window.runtime_config
• Dual key format: both VITE_OPENAI_API_KEY and OPENAI_API_KEY

Sources: README.md248-289 packages/core/src/services/model/defaults.ts1-119 packages/desktop/main.js355-378 packages/desktop/main.js555-578

Security Best Practices by Deployment

Web/Vercel Deployment

CORS Limitations:

Constraint	Impact	Mitigation
HTTPS → HTTP blocked	Cannot access local Ollama	Use desktop app or Docker (HTTP)
Strict CORS policies	Commercial APIs may block browser requests	Use API proxy or desktop app
Public API only	Limited to CORS-enabled cloud services	Configure Custom API with proxy

Security Recommendations:

1. Enable Password Protection: Set ACCESS_PASSWORD in Vercel environment variables
2. Use HTTPS-Only APIs: Ensure all API providers support HTTPS
3. No Local Services: Avoid local model configurations (will fail)
4. Client-Side Storage: All data in browser IndexedDB, no server persistence

Vercel Configuration: vercel.json24-31

Sources: README.md379-382 vercel.json1-33

Docker Deployment

Security Checklist:

• Set Strong Password: ACCESS_PASSWORD with 16+ characters
• Bind to Localhost: -p 127.0.0.1:8081:80 (not 0.0.0.0)
• HTTPS Reverse Proxy: nginx/Caddy with TLS termination
• Firewall Rules: Block direct container access
• Regular Updates: docker pull linshen/prompt-optimizer:latest
• Volume Permissions: Read-only mounts where possible

Secure Docker Compose Configuration:

Reverse Proxy Example (nginx with TLS):

Sources: docker-compose.yml1-44 README.md112-156

Desktop Application

Security Profile:

Aspect	Status	Notes
System Access	Full Node.js privileges	Runs in Electron main process
CORS	Bypassed completely	Direct Node.js HTTP requests
File System	Full read/write	userData directory permissions
Code Signing	Unsigned (macOS/Windows)	Source code is auditable (AGPL-3.0)
Auto-Updates	Enabled via electron-updater	Update files from GitHub Releases

macOS Gatekeeper Bypass:

Apple's Gatekeeper blocks unsigned applications. Manual bypass required:

Windows SmartScreen:

Windows Defender SmartScreen may show warning for unsigned .exe. Users must click "More info" → "Run anyway".

Update Verification:

Auto-updater downloads from GitHub Releases:

• Configuration: packages/desktop/config/update-config.js1-70
• Release validation via electron-updater (checks signatures if available)
• Users can verify SHA-256 checksums in release notes

User Data Security:

• Storage Location: OS-dependent (see Data Privacy section)
• Permissions: Restricted to user account
• Backup: Manual via Data Manager export
• Deletion: Remove userData directory (paths in preload API)

Sources: README.md393-407 packages/desktop/main.js589-594 packages/desktop/config/update-config.js1-70

API Proxy Deployment

For users requiring access to CORS-restricted APIs from web deployments, self-hosted API proxies provide a secure intermediary.

Proxy Architecture:

Recommended Proxy Solutions:

Proxy Tool	Features	Deployment
OneAPI	Multi-provider aggregation, key management, rate limiting	Docker, binary
NewAPI	OneAPI fork with additional providers	Docker, Vercel
litellm-proxy	Universal LLM gateway, load balancing	Docker, pip

Configuration in Prompt Optimizer:

1. Deploy proxy with CORS headers: Access-Control-Allow-Origin: *
2. Configure as Custom API in Model Manager:
   • API Key: Proxy's API key (not provider's)
   • Base URL: Proxy endpoint (e.g., https://proxy.example.com/v1)
   • Model: Provider-specific model name

Security Trade-offs:

• Trust: Proxy has access to API keys and request/response content
• Self-Hosted: User controls security and data retention
• Network: Additional hop increases latency, potential point of failure

Sources: README.md373-378

MCP Server Security Considerations

The Model Context Protocol server exposes prompt optimization capabilities via HTTP API, with deliberate authentication bypass for protocol compatibility.

MCP Server Architecture and Network Flow

Authentication Bypass Rationale:

The MCP endpoint explicitly disables Basic Authentication (while web UI remains protected):

Reason	Explanation
Protocol Incompatibility	MCP protocol specification does not support HTTP Basic Auth
Client Limitations	Claude Desktop cannot send Authorization headers to MCP servers
Local-Only Design	MCP intended for localhost usage, protected by network binding
Inspector Testing	MCP Inspector tool cannot authenticate, requires open endpoint

Nginx Configuration for /mcp Location:

Security Model:

Layer	Security Mechanism	Implementation
Network Isolation	Bind to localhost only	docker run -p 127.0.0.1:8081:80
API Key Protection	Keys in environment variables, never exposed	docker-compose.yml23-29
Direct API Calls	MCP server uses same core adapters as desktop	packages/mcp-server/src/config/models.ts1-69
No User Data Storage	MCP server is stateless	Uses in-memory core services

Configuration: docker-compose.yml31-36

Model Selection:

MCP server reuses @prompt-optimizer/core model system:

• Function: setupDefaultModel() at packages/mcp-server/src/config/models.ts12-66
• Reads defaultModels from core
• Selects based on MCP_DEFAULT_MODEL_PROVIDER or first enabled model
• Supports all custom model suffixes: custom_<suffix>

Exposure Recommendations:

Deployment	Recommended Configuration
Development	Expose 3000 directly, no authentication
Docker (Internal)	Bind to 127.0.0.1:8081, MCP via /mcp
Docker (Public)	Use VPN or SSH tunnel, do not expose 8081 publicly
Claude Desktop	Connect to http://localhost:8081/mcp

Known Issue (Fixed in v1.4.0+):

Earlier versions required MCP endpoint authentication workaround. Now properly configured with auth_basic off in nginx.

Sources: README.md183-245 docker-compose.yml31-36 packages/mcp-server/src/config/models.ts1-69 docs/user/mcp-server.md169-183 docs/user/mcp-server_en.md188-202

---

Summary: Prompt Optimizer's security architecture prioritizes client-side data processing and direct API communication. CORS challenges are addressed through platform-specific solutions, with the desktop application providing the most unrestricted access. Authentication is optional and deployment-dependent, using standard HTTP mechanisms.