HTTPS Security Enforcement Implementation¶

Overview¶

This document describes the HTTPS security measures implemented across the PCB Stackup Generator application. HTTPS is enforced in production builds and opt-in for local development (via VITE_FORCE_HTTPS=true plus local certificates), with automatic redirects and comprehensive security headers.

🔒 Security Features Implemented¶

1. Backend HTTPS Enforcement (FastAPI)¶

File: backend/main.py

Changes Made: - Always Enabled HTTPS Redirect: Removed conditional logic, HTTPS redirect middleware is now always active - Default HTTPS: Changed FORCE_HTTPS default from false to true - Security Headers Always Active: All security headers (HSTS, CSP, X-Frame-Options, etc.) are now always applied - HTTPS-Preferred CORS: Development mode now prefers HTTPS URLs over HTTP

Security Headers Applied:

# HSTS (HTTP Strict Transport Security) - Force HTTPS for 1 year
response.headers["Strict-Transport-Security"] = "max-age=31536000; includeSubDomains; preload"

# Content Security Policy
response.headers["Content-Security-Policy"] = "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' https://www.googletagmanager.com; ..."

# Additional security headers
response.headers["X-Frame-Options"] = "DENY"
response.headers["X-Content-Type-Options"] = "nosniff"
response.headers["X-XSS-Protection"] = "1; mode=block"
response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"

2. Frontend HTTPS Enforcement (Vite)¶

File: frontend/vite.config.ts

How it works: - Conditional HTTPS: useHTTPS is true in production builds, and in development only when VITE_FORCE_HTTPS=true is set (in the repo-root .env) - Certificate-Gated: Dev HTTPS only activates if local certificates exist (certs/localhost-key.pem + certs/localhost.pem, resolved from the directory Vite runs in, i.e. frontend/) - Protocol-Matched Proxy Targets: Proxy targets use HTTPS when useHTTPS is on, HTTP otherwise - Conditional Security Headers: Dev-server security headers are applied when useHTTPS is on

Configuration (actual code from frontend/vite.config.ts):

// Check if HTTPS should be enabled
const useHTTPS = env.VITE_FORCE_HTTPS === 'true' || mode === 'production';

// SSL certificate paths (for development HTTPS)
const sslKeyPath = path.resolve('./certs/localhost-key.pem');
const sslCertPath = path.resolve('./certs/localhost.pem');

// Check if SSL certificates exist for development HTTPS
const hasSSLCerts = useHTTPS && fs.existsSync(sslKeyPath) && fs.existsSync(sslCertPath);

The /api proxy targets the FastAPI backend on port 8000, switching between https://localhost:8000 and http://localhost:8000 based on useHTTPS.

3. Browser-Side HTTPS Enforcement¶

File: frontend/src/components/HTTPSEnforcer.tsx

Features: - Automatic HTTPS Redirect: Redirects HTTP requests to HTTPS for non-localhost domains - Security Warnings: Provides console warnings for HTTP usage on localhost - BeforeUnload Protection: Prevents navigation away from HTTPS to HTTP - Development-Friendly: Allows HTTP on localhost for development while warning

Integration: Added to main App component for global enforcement.

4. Server Startup Script Updates¶

File: start-all-servers-windowed.ps1

Changes Made: - HTTPS URLs: All server URLs now use HTTPS protocol - Environment Variables: Frontend environment file updated with HTTPS URLs - Security Notices: Added security warnings in startup messages - HTTPS Flag: Added VITE_FORCE_HTTPS=true to frontend environment

5. Local Development Certificates¶

The repo does not ship a certificate-generation script. The Vite config expects these files (paths resolved from the directory Vite runs in, i.e. frontend/):

certs/localhost-key.pem - Private key
certs/localhost.pem - Certificate

If both files exist and useHTTPS is on, the dev server starts with HTTPS; otherwise it falls back to HTTP.

Generating them (using mkcert, an external tool — not part of this repo):

# From the frontend/ directory
mkdir certs
mkcert -key-file certs/localhost-key.pem -cert-file certs/localhost.pem localhost

Any equivalent tool (e.g. OpenSSL self-signed certs) works, as long as the two files land at the paths above.

🔧 Configuration Changes¶

Environment Variables¶

Backend (backend/.env):

FORCE_HTTPS=true
ENVIRONMENT=production

Frontend (repo-root .env — Vite loads VITE_* vars from the project root via envDir, not from frontend/.env, which is a generated cache):

VITE_FASTAPI_URL=https://localhost:8000
VITE_FORCE_HTTPS=true

🚀 Usage Instructions¶

1. Generate SSL Certificates¶

First-time setup — create the certificates the Vite config expects (see "Local Development Certificates" above), e.g. with the external mkcert tool:

# From the frontend/ directory
mkcert -key-file certs/localhost-key.pem -cert-file certs/localhost.pem localhost

2. Start Application¶

# Start all servers with HTTPS enforcement
.\start-all-servers-windowed.ps1

3. Access Application¶

Frontend: https://localhost:5180
Backend API: https://localhost:8000
AI Chat: served by the FastAPI backend on port 8000 (SSE at /api/chat/gemini/stream) — there is no separate chat server

4. Browser Security Warning¶

When accessing the application for the first time: 1. Browser will show "Not Secure" or certificate warning 2. Click "Advanced" or "Show Details" 3. Click "Proceed to localhost" or "Accept Risk" 4. Application will load with HTTPS security

🔒 Security Benefits¶

1. Data Protection¶

Encrypted Communication: All data transmitted between client and server is encrypted
Man-in-the-Middle Protection: Prevents eavesdropping on communications
Data Integrity: Ensures data hasn't been tampered with in transit

2. Authentication Security¶

Secure Sessions: Session cookies are only transmitted over HTTPS
API Security: All API calls are encrypted and secure
Credential Protection: Login credentials and sensitive data are protected

3. Compliance¶

Industry Standards: Meets modern web security standards
Regulatory Compliance: Helps meet security requirements for sensitive applications
Best Practices: Follows OWASP security guidelines

⚠️ Important Notes¶

Development Certificates¶

Self-Signed: Certificates are self-signed for development only
Browser Warnings: Browsers will show security warnings - this is normal
Not for Production: Never use development certificates in production
Expiration: Local certificates expire (validity depends on the tool used to generate them) — regenerate when they do

Production Deployment¶

Real Certificates: Use proper SSL certificates from a trusted CA
Domain Validation: Ensure certificates match your production domain
Certificate Renewal: Set up automatic certificate renewal
Security Headers: All security headers are automatically applied

Troubleshooting¶

Certificate Tooling: Certificate generation requires an external tool such as mkcert or OpenSSL
Port Conflicts: Ensure ports 5180 and 8000 are available
Firewall: Allow HTTPS traffic through firewall
Browser Cache: Clear browser cache if experiencing issues

📋 Testing Checklist¶

SSL certificates generated successfully
Application starts with HTTPS URLs
Browser shows HTTPS in address bar
HTTP requests redirect to HTTPS
Security headers are present
API calls work over HTTPS
No mixed content warnings
Development workflow functions normally

🔄 Maintenance¶

Certificate Renewal¶

When local certificates expire: 1. Delete the existing files in the certs/ directory 2. Regenerate them (e.g. re-run the mkcert command from the setup section) 3. Restart the application

Security Updates¶

Monitor security advisories for OpenSSL
Update security headers as needed
Review and update CORS policies
Test security configurations regularly

This implementation ensures that the PCB Stackup Generator application maintains the highest security standards with comprehensive HTTPS enforcement across all components.