SSL & Security

SSL certificate management including Let's Encrypt integration, custom certificate upload, and security configuration for HTTPS deployments.

Capabilities

SSL Certificate Upload

Upload custom SSL certificates for domains (legacy method).

/**
 * Upload custom SSL certificate for domain
 * @param hooks - Optional lifecycle hooks
 * @returns Command function
 */
function ssl(hooks?: HookConfig): CommandFunction;

CLI Usage:

# Interactive certificate upload
surge ssl

# Upload certificate for specific domain
surge ssl example.com cert.pem

# With domain and certificate file
surge ssl --domain example.com --pem cert.pem

Certificate Requirements:

• PEM format certificate file
• Must include private key and certificate chain
• Domain must match certificate common name
• Valid certificate from trusted CA

Library Usage:

surge.ssl({})(process.argv.slice(2));

Let's Encrypt Integration

Provision SSL certificates automatically using Let's Encrypt.

/**
 * Provision SSL certificate via Let's Encrypt
 * @param hooks - Optional lifecycle hooks
 * @returns Command function
 */
function encrypt(hooks?: HookConfig): CommandFunction;

CLI Usage:

# Provision SSL for domain
surge encrypt example.com

# Interactive domain selection
surge encrypt

Let's Encrypt Process:

1. Domain ownership verification
2. Certificate provisioning
3. Automatic installation
4. Auto-renewal setup

Benefits:

• Free SSL certificates
• Automatic renewal
• Trusted by all browsers
• No manual certificate management

Library Usage:

surge.encrypt({})(process.argv.slice(2));

View Certificates

Display SSL certificate information for projects.

/**
 * View SSL certificate information for project
 * @param hooks - Optional lifecycle hooks
 * @returns Command function
 */
function certs(hooks?: HookConfig): CommandFunction;

CLI Usage:

# View certificates for domain
surge certs example.com

# List all certificates
surge certs

Certificate Information Displayed:

• Certificate status (active, expired, pending)
• Expiration date
• Certificate authority
• Subject and alternative names
• Renewal status

Library Usage:

surge.certs({})(process.argv.slice(2));

SSL Configuration

Automatic HTTPS

All Surge domains automatically receive SSL certificates:

• surge.sh subdomains: Wildcard certificate included
• Custom domains: Let's Encrypt certificates automatically provisioned
• HTTPS enforcement: Optional redirect from HTTP to HTTPS

Certificate Types

Wildcard Certificates:

• Covers all *.surge.sh subdomains
• Automatically applied
• No configuration required

Let's Encrypt Certificates:

• Free domain validation certificates
• 90-day validity with automatic renewal
• Supports multiple domains and wildcards

Custom Certificates:

• Upload your own certificates
• Supports EV and OV certificates
• Manual renewal required

HTTPS Redirection

Configure automatic HTTPS redirection:

1. Deploy with HTTPS URLs in your application
2. Surge automatically handles HTTP to HTTPS redirects
3. Use relative URLs to maintain protocol flexibility

Security Features

Security Headers

Surge automatically adds security headers:

Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block

Content Security Policy

Configure CSP headers in your HTML:

<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self' 'unsafe-inline';">

CORS Configuration

Configure CORS for API access:

// In your application
const corsHeaders = {
  'Access-Control-Allow-Origin': 'https://yourapp.surge.sh',
  'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE',
  'Access-Control-Allow-Headers': 'Content-Type, Authorization'
};

Domain Validation

DNS Validation

For Let's Encrypt certificates, domain validation occurs via:

1. HTTP Challenge: Temporary file served from domain
2. DNS Challenge: TXT record added to domain DNS
3. Automatic Validation: Surge handles validation process

Custom Domain Setup

For custom domains with SSL:

1. Point DNS: CNAME or A record to Surge
2. Deploy Project: Upload files to domain
3. Provision SSL: Use surge encrypt command
4. Verify: Check HTTPS access

# Example custom domain setup
surge ./build customdomain.com
surge encrypt customdomain.com

Certificate Management

Renewal Process

Automatic Renewal:

• Let's Encrypt certificates auto-renew before expiration
• No user intervention required
• Email notifications for renewal status

Manual Renewal:

• Custom certificates require manual renewal
• Upload new certificate before expiration
• Monitor expiration dates

Certificate Monitoring

Monitor certificate status:

# Check certificate status
surge certs example.com

# List expiring certificates
surge certs --expiring

Backup and Recovery

Certificate Backup:

• Store custom certificates securely
• Keep private keys encrypted
• Document certificate details

Recovery Process:

• Re-upload certificates if lost
• Use Let's Encrypt for quick recovery
• Verify certificate installation

Best Practices

SSL Implementation

1. Use Let's Encrypt: Free and automated certificate management
2. Enable HTTPS Everywhere: Redirect all HTTP traffic to HTTPS
3. Update Links: Use HTTPS URLs in your application
4. Test Certificate: Verify SSL installation with online tools

Security Hardening

1. Security Headers: Implement comprehensive security headers
2. Content Security Policy: Restrict resource loading
3. HTTPS Only: Never serve sensitive content over HTTP
4. Certificate Monitoring: Monitor expiration dates

Performance Optimization

1. HTTP/2: Automatic with HTTPS
2. Certificate Caching: Browsers cache certificates
3. OCSP Stapling: Improved certificate validation
4. Session Resumption: Faster SSL handshakes

Troubleshooting

Common SSL Issues

Certificate Not Trusted:

• Verify certificate chain completeness
• Check certificate authority
• Update browser/system certificates

Domain Mismatch:

• Ensure certificate matches domain exactly
• Check alternative names in certificate
• Verify DNS configuration

Expired Certificate:

• Check expiration date
• Renew or replace certificate
• Clear browser certificate cache

Let's Encrypt Failures:

• Verify domain ownership
• Check DNS propagation
• Ensure domain is accessible

Debugging Commands

# Check certificate details
openssl x509 -in cert.pem -text -noout

# Test SSL connection
openssl s_client -connect example.com:443

# Verify certificate online
# Use SSL Labs SSL Test or similar tools