SSL & certificates
Providers, wor's own certificate copy, the HTTP to HTTPS redirect, and renewal.
certbot --webroot has issued a real certificate. The renewal hook firing on a real renewal, and wor ssl sync running as root from that hook, have not been exercised. Run certbot renew --dry-run before trusting renewal in production.Providers
| Provider | How it works | Needs |
|---|---|---|
letsencrypt | certbot with the webroot authenticator, challenge files served from $WOR_HOME/ssl/acme. Port 80 must be reachable from the internet (HTTP-01). | certbot, a public DNS name |
self-signed | Generated with openssl when available. | openssl |
custom | You supply the certificate and key: wor ssl install <host> --cert=... --key=.... | nothing |
none | No certificate for the host. | nothing |
The default provider is chosen in wor setup and overridden per host with --provider=. Let's Encrypt works on every platform wor runs on now that Windows is gone. DNS-01 and wildcard certificates are not supported (they need a provider plugin and credentials per DNS host, a feature of their own), and neither is HSTS: a redirect is reversible, an HSTS header cached by browsers is not.
wor keeps its own copy of every certificate
Whatever the provider, the generated vhost points at:
$WOR_HOME/ssl/hosts/<host>/fullchain.pem
$WOR_HOME/ssl/hosts/<host>/privkey.pem mode 0600, owned by whoever owns WOR_HOME
Self-signed and custom certificates always worked this way. Let's Encrypt used to be the exception: the vhost referenced /etc/letsencrypt/live/<host>/ directly. That exception broke a real machine.
Why
- certbot's real key lives in root-only
/etc/letsencrypt/archive/. - It is the web server's master process that opens a certificate at config load. On Linux, systemd runs the master as root, so it can read it. On macOS, Homebrew starts it as the login user, so it cannot.
- An unreadable certificate makes the configuration invalid, and one invalid vhost fails
nginx -tfor the whole machine. The reload took every site down, not just one. (Same structural problem as macOS php-fpm pools.)
Copying removes the asymmetry. Mode 0600 owned by the operator is enough on both platforms with no ACL, no group and no chown of anything else: the master reads certificates, and the master is root on Linux and the operator on macOS. privkey.pem is never made group- or world-readable. If your web server runs its master as a third user, give it a dedicated group; do not widen the mode.
Granting the web server user an ACL on /etc/letsencrypt was the alternative, and was rejected: it cannot work on macOS at all and reaches into a directory another tool owns.
HTTP to HTTPS redirect
An explicit per-host setting stored as forceHttps in $WOR_HOME/ssl/hosts/<host>/ssl.json. wor ssl issue asks and records the answer.
| Certificate | Default offered |
|---|---|
letsencrypt | on |
custom | on |
self-signed | off |
| any local hostname | off, overriding the above |
A local hostname has no dot, or ends in .local, .localhost, .test, .example or .invalid. Forcing HTTPS there sends visitors to a certificate no browser trusts, making the site unreachable without clicking through a warning every time.
--redirect/--no-redirectanswer without prompting.wor ssl redirect <host> on|offchanges it later without touching the certificate.wor ssl statusshows it.- Stored, not recomputed. Changing the provider or hostname later never silently changes the redirect.
WOR_ENVwas considered as an input and rejected: it is machine-wide while this is per host, and wor currently infers it, so a production host left looking like development would quietly stop redirecting. - Cannot outlive the certificate.
ssl removedeletes the state with it, so a host can never redirect to a certificate it no longer has (a guaranteed outage). - Behaviour on upgrade. The field is a
*bool, so "never recorded" differs from "recorded as off". A host whosessl.jsonpredates it keeps the active provider's old behaviour: Apache hosts still redirect, nginx hosts still do not, until you set it.wor ssl statusmarks the value as inherited. Reading absent as a flat "off" would have silently switched every upgraded Apache site back to plaintext on port 80; an upgrade quietly removing a redirect is the direction that weakens a site.
The nginx template is split into separate :80 and :443 server blocks, matching Apache. The redirect sits inside location / so it cannot swallow the ACME challenge. With the redirect on, the :80 block carries only the ACME location, the host check and the redirect, and the service config plus your .wor/nginx snippets move to :443.
Issuance
Why --webroot
certbot's --nginx and --apache plugins work by editing the vhost, which wor regenerates from templates on every write: two tools owning one generated file. With the two-block nginx split it is worse, because both blocks share one server_name and it is not something to depend on which one the plugin patches. With --webroot, certbot writes a file into a directory and touches nothing else. The web server provider stops mattering for issuance, so nginx and Apache share one code path, and wor performs the reload itself, through the validate-then-reload pipeline.
- Every
:80block serves/.well-known/acme-challenge/from$WOR_HOME/ssl/acmeunconditionally, andwor ssl issueregenerates the vhost before invoking certbot, so a host created by an older version has the location before the challenge arrives. - wor pre-creates the
acme/.well-known/acme-challengetree as the operator duringwor setup, so certbot (running as root) only writes files inside a directory wor owns. - Existing certificates that record
authenticator = nginxorapachekeep that until reissued:ssl syncmigrates the certificate copy but cannot change the authenticator, and certbot only rewrites a renewal config when it actually obtains a certificate.wor ssl issuewarns when the renewal hook did not end up registered, andwor ssl hook <host>registers it without reissuing.
Every SSL write is validated
Every SSL change follows one sequence: snapshot the current vhost, write, enable, run the server's config test, reload only if it passes, otherwise restore. Ordering matters too: ssl remove used to regenerate the vhost before clearing the certificate state, so the regenerated file still pointed at files the same command was about to delete. Now the state is cleared first and the files are deleted last, after the SSL-free vhost has been validated and reloaded.
Enabling now happens for every caller, not just host add, because on Linux the config test only sees files in sites-enabled. The snapshot records whether the enabled entry was a symlink or a plain copy, because a copy holds its own content and must be written back too.
Removing a host or service: certbot keeps its certificate
wor host remove, wor service remove --cascade and wor ssl remove delete wor's own copy of a Let's Encrypt certificate, not certbot's. certbot's lineage lives in root-owned /etc/letsencrypt, so wor does not reach into it. Left alone, certbot's timer keeps trying to renew it and fails once the name no longer points at this machine. After the removal wor prints the command to stop that, to copy and run yourself:
certbot still holds a certificate for app.example.com and will keep trying to renew it. To stop that:
sudo certbot delete --cert-name app.example.com
It is only printed for hosts that had a Let's Encrypt certificate. Revoking is not suggested. A revocation cannot be undone and tells the certificate authority the certificate is untrustworthy, which is for a leaked private key; removing a service is not that.
Renewal and wor ssl sync
wor ssl issue registers a certbot renewal hook, so each renewal refreshes wor's copy automatically. wor ssl sync <host> is that same refresh, runnable by hand. It does three jobs: the hook certbot calls, the way to migrate a host issued before wor kept its own copy, and the manual repair when copy and source have drifted. It is idempotent: an unchanged certificate produces no write and no reload.
| Property | Detail |
|---|---|
| Who owns the copied files | Derived from WOR_HOME's own ownership at the moment of use, never stored. The hook runs from certbot as plain root with no SUDO_USER, and baking a uid into the hook at issue time would go stale and hand a private key to whatever unrelated account later held that number. A root-owned WOR_HOME is refused unless the caller is also root (the supported "server with no account but root" case). |
| Hook command | Carries WOR_HOME explicitly and an absolute binary path. It runs as root months later, where ~/.wor/config is root's and the per-OS default WOR_HOME ($HOME/wor on macOS) would resolve to root's home: the wrong workspace. |
| Sudo | The one command allowed under sudo, because certbot runs hooks as root. It writes exactly two files and hands them back to the operator, so it upholds the no-root-artifacts rule rather than escaping it. It never prompts: a prompt would hang the renewal. |
| Registered flag | The hook is registered with --renew-hook and carries --skip-if-busy. |
Checking that renewal really works: wor ssl status
For a Let's Encrypt host, wor ssl status does not print a remembered value. It checks the two things that decide whether renewal works:
- Does certbot's renewal config for the host register a hook? The hook is what copies a renewed certificate into wor. A host issued by an older version may have none: certbot then renews on schedule while wor keeps serving the old copy, and the site only keeps working until the old certificate expires.
- Does wor's copy expire when certbot's certificate does? If certbot's certificate outlives the one wor serves, a renewal happened and wor was not told, or was told and failed.
Both need certbot's root-only files, so wor ssl status asks for elevated access (once, like every other privileged step). Where that is declined or impossible, for example under --non-interactive, the answer is unchecked, never "fine". A stale copy does not change the exit code; wor health owns that.
A host in the state this exists to catch (an illustrative example; the dates are made up):
$ wor ssl status app.example.com
SSL Enabled : true
Current Provider : letsencrypt
Certificate File : ~/wor/ssl/hosts/app.example.com/fullchain.pem
Private Key File : ~/wor/ssl/hosts/app.example.com/privkey.pem
Certificate Expiration: Oct 25 14:00:00 2026 GMT
Auto Renew Status : NOT WORKING -- certbot's renewal config for this host has no hook, so a renewal will not refresh wor's copy
Fix: wor ssl hook app.example.com (registers the hook without reissuing; needs certbot 2.3+ and port 80 reachable)
Certificate Copy : STALE -- certbot holds a certificate valid until Dec 24 18:00:00 2026 GMT, but wor is serving one valid until Oct 25 14:00:00 2026 GMT
Fix: wor ssl sync app.example.com
Last Sync : ok at 2026-09-25T03:00:12+07:00
HTTP -> HTTPS Redirect: on
Run wor ssl sync first: it refreshes the copy now. Then run wor ssl hook <host> so the hook is registered and the next renewal looks after itself. It changes only the hook line in certbot's renewal config, through certbot reconfigure (certbot 2.3 or newer, and port 80 reachable, because certbot checks the new configuration with a dry-run renewal), and then reads the config back to confirm. Reissuing with wor ssl issue does not do this while the certificate is still valid: certbot keeps the certificate and leaves its renewal config as it was. A healthy host prints Auto Renew Status : enabled (certbot's renewal hook is registered) and Certificate Copy : current (matches certbot's). With --json, a renewal object carries the same facts (hook, copy, both expirations, the last sync); auto_renew remains the remembered value.
If the hook fails: three layers of detection
Copying creates one risk the old design did not have: if the hook ever fails, the copy goes stale and the site serves an expired certificate silently, which is worse than failing loudly.
| Layer | What |
|---|---|
| Prevention | The renewal hook. |
| Detection of the outcome | wor health reports certificate expiry as its yellow Warning tier (exit code stays 0, so cron does not alarm on something days away). Each service card shows days left, or why the last sync failed. |
| Detection of the cause | Every ssl sync records {at, ok, source, error} in ssl/hosts/<host>/sync.json, read back by ssl status, health and diagnose. wor has no log of its own, so a hook failing at 03:00 would otherwise leave a trace only in a job output nobody reads. A general wor log file was considered and deferred as a feature in its own right. |
wor doctor adds two warnings that never affect the exit code: WOR_HOME owned by root when you are not (this blocks sync), and Let's Encrypt certificates with no renewal schedule anywhere on the machine. The second is not hypothetical: the Mac this work came from had no systemd timer, no launchd job and no root crontab, so nothing was going to renew anything and the hook would never have fired. Debian's certbot package installs a timer; Homebrew's does not. wor reports the gap and shows the command, and never installs a schedule silently (the precedent set for pm2 startup in wor run).
Example: issue, then change the redirect
Example outputs on this page come from real runs of wor on macOS. Machine-specific values (tool versions, disk sizes, dates, file names) have been replaced with typical ones and long paths shortened, so your numbers will differ. On Linux, paths and a few platform-specific checks differ.
$ wor ssl issue myapp.example.com --provider=self-signed --no-redirect
[OK] Self-signed SSL installed: myapp.example.com
[INFO] HTTP -> HTTPS redirect: off (change it with `wor ssl redirect myapp.example.com on|off`)
$ wor ssl redirect myapp.example.com on
[OK] HTTPS redirect for myapp.example.com is now on.
$ wor ssl status myapp.example.com
SSL Enabled : true
Current Provider : self-signed
Certificate File : ~/wor/ssl/hosts/myapp.example.com/fullchain.pem
Private Key File : ~/wor/ssl/hosts/myapp.example.com/privkey.pem
Certificate Expiration: Jan 1 00:00:00 2029 GMT
Auto Renew Status : unsupported
HTTP -> HTTPS Redirect: on
The Auto Renew Status: unsupported line is expected for a self-signed certificate: only Let's Encrypt certificates renew themselves.
State files
| File | Holds |
|---|---|
ssl/hosts/<host>/ssl.json | enabled, provider, certFile, keyFile, autoRenew, forceHttps (nullable) |
ssl/hosts/<host>/sync.json | Result of the last ssl sync |
ssl/hosts/<host>/fullchain.pem, privkey.pem | wor's copy; what the vhost serves |
ssl/acme/.well-known/acme-challenge/ | certbot webroot, shared by every host (the challenge filename identifies the request, so there is nothing to separate per host) |
The removed SSLCertificateChainFile directive (deprecated since Apache 2.4.8, unnecessary when serving fullchain.pem) is no longer emitted.