0
# SSL & Security
1

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

4
## Capabilities
5

6
### SSL Certificate Upload
7

8
Upload custom SSL certificates for domains (legacy method).
9

10
```javascript { .api }
11
/**
12
 * Upload custom SSL certificate for domain
13
 * @param hooks - Optional lifecycle hooks
14
 * @returns Command function
15
 */
16
function ssl(hooks?: HookConfig): CommandFunction;
17
```
18

19
**CLI Usage:**
20
```bash
21
# Interactive certificate upload
22
surge ssl
23

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

27
# With domain and certificate file
28
surge ssl --domain example.com --pem cert.pem
29
```
30

31
**Certificate Requirements:**
32
- PEM format certificate file
33
- Must include private key and certificate chain
34
- Domain must match certificate common name
35
- Valid certificate from trusted CA
36

37
**Library Usage:**
38
```javascript
39
surge.ssl({})(process.argv.slice(2));
40
```
41

42
### Let's Encrypt Integration
43

44
Provision SSL certificates automatically using Let's Encrypt.
45

46
```javascript { .api }
47
/**
48
 * Provision SSL certificate via Let's Encrypt
49
 * @param hooks - Optional lifecycle hooks
50
 * @returns Command function
51
 */
52
function encrypt(hooks?: HookConfig): CommandFunction;
53
```
54

55
**CLI Usage:**
56
```bash
57
# Provision SSL for domain
58
surge encrypt example.com
59

60
# Interactive domain selection
61
surge encrypt
62
```
63

64
**Let's Encrypt Process:**
65
1. Domain ownership verification
66
2. Certificate provisioning
67
3. Automatic installation
68
4. Auto-renewal setup
69

70
**Benefits:**
71
- Free SSL certificates
72
- Automatic renewal
73
- Trusted by all browsers
74
- No manual certificate management
75

76
**Library Usage:**
77
```javascript
78
surge.encrypt({})(process.argv.slice(2));
79
```
80

81
### View Certificates
82

83
Display SSL certificate information for projects.
84

85
```javascript { .api }
86
/**
87
 * View SSL certificate information for project
88
 * @param hooks - Optional lifecycle hooks
89
 * @returns Command function
90
 */
91
function certs(hooks?: HookConfig): CommandFunction;
92
```
93

94
**CLI Usage:**
95
```bash
96
# View certificates for domain
97
surge certs example.com
98

99
# List all certificates
100
surge certs
101
```
102

103
**Certificate Information Displayed:**
104
- Certificate status (active, expired, pending)
105
- Expiration date
106
- Certificate authority
107
- Subject and alternative names
108
- Renewal status
109

110
**Library Usage:**
111
```javascript
112
surge.certs({})(process.argv.slice(2));
113
```
114

115
## SSL Configuration
116

117
### Automatic HTTPS
118

119
All Surge domains automatically receive SSL certificates:
120

121
- **surge.sh subdomains**: Wildcard certificate included
122
- **Custom domains**: Let's Encrypt certificates automatically provisioned
123
- **HTTPS enforcement**: Optional redirect from HTTP to HTTPS
124

125
### Certificate Types
126

127
**Wildcard Certificates:**
128
- Covers all *.surge.sh subdomains
129
- Automatically applied
130
- No configuration required
131

132
**Let's Encrypt Certificates:**
133
- Free domain validation certificates
134
- 90-day validity with automatic renewal
135
- Supports multiple domains and wildcards
136

137
**Custom Certificates:**
138
- Upload your own certificates
139
- Supports EV and OV certificates
140
- Manual renewal required
141

142
### HTTPS Redirection
143

144
Configure automatic HTTPS redirection:
145

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

150
## Security Features
151

152
### Security Headers
153

154
Surge automatically adds security headers:
155

156
```http
157
Strict-Transport-Security: max-age=31536000; includeSubDomains
158
X-Content-Type-Options: nosniff
159
X-Frame-Options: DENY
160
X-XSS-Protection: 1; mode=block
161
```
162

163
### Content Security Policy
164

165
Configure CSP headers in your HTML:
166

167
```html
168
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self' 'unsafe-inline';">
169
```
170

171
### CORS Configuration
172

173
Configure CORS for API access:
174

175
```javascript
176
// In your application
177
const corsHeaders = {
178
  'Access-Control-Allow-Origin': 'https://yourapp.surge.sh',
179
  'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE',
180
  'Access-Control-Allow-Headers': 'Content-Type, Authorization'
181
};
182
```
183

184
## Domain Validation
185

186
### DNS Validation
187

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

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

194
### Custom Domain Setup
195

196
For custom domains with SSL:
197

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

203
```bash
204
# Example custom domain setup
205
surge ./build customdomain.com
206
surge encrypt customdomain.com
207
```
208

209
## Certificate Management
210

211
### Renewal Process
212

213
**Automatic Renewal:**
214
- Let's Encrypt certificates auto-renew before expiration
215
- No user intervention required
216
- Email notifications for renewal status
217

218
**Manual Renewal:**
219
- Custom certificates require manual renewal
220
- Upload new certificate before expiration
221
- Monitor expiration dates
222

223
### Certificate Monitoring
224

225
Monitor certificate status:
226

227
```bash
228
# Check certificate status
229
surge certs example.com
230

231
# List expiring certificates
232
surge certs --expiring
233
```
234

235
### Backup and Recovery
236

237
**Certificate Backup:**
238
- Store custom certificates securely
239
- Keep private keys encrypted
240
- Document certificate details
241

242
**Recovery Process:**
243
- Re-upload certificates if lost
244
- Use Let's Encrypt for quick recovery
245
- Verify certificate installation
246

247
## Best Practices
248

249
### SSL Implementation
250

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

256
### Security Hardening
257

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

263
### Performance Optimization
264

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

270
## Troubleshooting
271

272
### Common SSL Issues
273

274
**Certificate Not Trusted:**
275
- Verify certificate chain completeness
276
- Check certificate authority
277
- Update browser/system certificates
278

279
**Domain Mismatch:**
280
- Ensure certificate matches domain exactly
281
- Check alternative names in certificate
282
- Verify DNS configuration
283

284
**Expired Certificate:**
285
- Check expiration date
286
- Renew or replace certificate
287
- Clear browser certificate cache
288

289
**Let's Encrypt Failures:**
290
- Verify domain ownership
291
- Check DNS propagation
292
- Ensure domain is accessible
293

294
### Debugging Commands
295

296
```bash
297
# Check certificate details
298
openssl x509 -in cert.pem -text -noout
299

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

303
# Verify certificate online
304
# Use SSL Labs SSL Test or similar tools
305
```