Radically Straightforward · Caddy

☁️ Install Caddy as an npm package

Installation

$ npm install @radically-straightforward/caddy

Note: For quick-and-easy testing you may run Caddy from the command line with npx instead of installing it explicitly:

$ npx @radically-straightforward/caddy

Note: By default the latest version of Caddy is installed. You may specify a version in package.json with a caddy property, for example:

package.json

{
  "caddy": "2.7.5"
}

Usage

$ npx caddy

Note: If the command above doesn’t work, which may happen in particular on Windows, use the path to the binary instead of npx:

> .\node_modules\.bin\caddy

Besides the Caddy binary, @radically-straightforward/caddy also comes with helpers to define a Caddyfile.

import childProcess from "node:child_process";
import caddyfile from "@radically-straightforward/caddy";
import * as caddy from "@radically-straightforward/caddy";

const caddyServer = childProcess.spawn(
  "./node_modules/.bin/caddy",
  ["run", "--adapter", "caddyfile", "--config", "-"],
  { stdio: [undefined, "inherit", "inherit"] },
);
caddyServer.stdin.end(caddy.application());

start()

export function start({
  extraCaddyfile = caddyfile``,
  ...applicationOptions
}: {
  extraCaddyfile?: Caddyfile;
} & Parameters<typeof application>[0] = {}): void;

Start a Caddy process with application() configuration. If the process crashes, a new one is spawned.

staticFiles

export const staticFiles: {
  [key: string]: string;
};

A mapping from static file names to their hashed names, as produced by @radically-straightforward/build and found in ./build/static.json.

application()

export function application({
  hostname = "localhost",
  systemAdministratorEmail = undefined,
  hstsPreload = false,
  ports = [18000],
  trustedStaticFilesRoots = [
    `* "${path.join(path.join(import.meta.dirname, "..").split("/node_modules/")[0], "build/static/")}"`,
  ],
  untrustedStaticFilesRoots = [],
  extraGlobalOptions = caddyfile``,
}: {
  hostname?: string;
  systemAdministratorEmail?: string;
  hstsPreload?: boolean;
  ports?: number[];
  trustedStaticFilesRoots?: string[];
  untrustedStaticFilesRoots?: string[];
  extraGlobalOptions?: Caddyfile;
} = {}): Caddyfile;

A Caddyfile template for an application.

Parameters

• hostname: The hostname part of the application’s URL, for example, example.com.

• systemAdministratorEmail: The email of the system administrator is used by certificate authorities to contact about certificates. If undefined, then the server is run in development mode with the hostname localhost and a local self-signed certificate.

• hstsPreload: Whether the Strict-Transport-Security header should include the preload directive. This is false by default, but we recommended that in production you opt into preloading by setting hstsPreload to true and then submit your domain to the preload list.

• ports: Ports for the dynamic part of the application to which Caddy reverse proxies—usually several processes of a Node.js server.

• trustedStaticFilesRoots: Caddy root directives for static files that are trusted by the application, for example, the application’s CSS and browser JavaScript.

• untrustedStaticFilesRoots: Similar to trustedStaticFilesRoots, but for static files that are untrusted by the application, for example, user-uploaded avatars, attachments to messages, and so forth.

  Note: Both trustedStaticFilesRoots and untrustedStaticFilesRoots must refer to immutable files. You may use @radically-straightforward/build to build CSS, browser JavaScript, and other static files with immutable and unique file names. Your application should create immutable and unique file names for user-uploaded avatars, attachments to messages, and so forth.

• extraGlobalOptions: Extra Caddyfile global options. Useful, for example, to set HTTP ports other than the default.

Features

• Turn off Caddy’s administrative API endpoint. This keeps things simple, at the cost of requiring an application restart to change Caddy’s configurations.

• Set the system administrator email, which is used by certificate authorities to contact about certificates.

• Set the following security headers:

  Note: These headers may be overwritten by the underlying application. This is useful if the application needs to tweak some security settings, for example, Content Security Policy (CSP).

  • Strict-Transport-Security: Tells the browser that moving forward it should only attempt to load this origin with HTTPS (not HTTP). The hstsPreload parameter controls whether to set the preload directive—by default it’s false, but it’s recommended that you opt into preloading by setting hstsPreload: true.

  • Cache-Control: Turns off HTTP caching. This is the best setting for the dynamic parts of the application: in the best case the cache may be stale, and in the worst case the cache may include private information that could leak even after signing out. For static files, we recommend that you overwrite this header to enable caching, for example, header Cache-Control "public, max-age=31536000, immutable".

  • X-Content-Type-Options: Turns off Content-Type sniffing, because: 1. The application may break if content sniffing goes wrong; and 2. Content sniffing needs access to the response body but the response body may take long to arrive in streaming responses. Make sure to set the Content-Type header appropriately.

  • X-XSS-Protection: Disables XSS filtering because, ironically, XSS filtering may make the application vulnerable.

  • Permissions-Policy: Opts out of FLoC.

  • Origin-Agent-Cluster: Tells the browser to try and isolate the process running the application.

  • Content-Security-Policy: Allows the application to retrieve content only from the same origin. Inline styles are allowed. Frames and objects are disabled. Forms may only be submitted to the same origin. If you need to serve images/videos/audios from third-party websites (for example, as part of content generated by users), setup a proxy (it also solves the potential issue of mixed content).

  • Cross-Origin-*-Policy: Allow only the same origin to load content from the application. This is the converse of the Content-Security-Policy header. For files that you wish to allow embedding in other origins, set header Cross-Origin-Resource-Policy cross-origin.

  • X-Frame-Options: Disallows the application from being embedded in a frame.

  • X-Permitted-Cross-Domain-Policies: Disallows the application from being embedded in a PDF, a Flash document, and so forth.

  • X-DNS-Prefetch-Control: Disables DNS prefetching, because DNS prefetching could leak information about the application to potentially untrusted DNS servers.

  • Referrer-Policy: Tells the browser to not send the Referer request header. This makes the application more secure because external links don’t leak information about the URL that the user was on.

• Configure a server for trusted and untrusted static files. Safe untrusted file types are allowed to be embedded in other origins, and unsafe untrusted file types are forced to be downloaded, which prevents user-generated JavaScript from running within the context of the application (XSS).

• Configure a reverse proxy with load balancing to the dynamic part of the application. The load balancing policy is set to cookie, which uses the lb cookie to setup sticky sessions and allows the server to hold state (for example, @radically-straightforward/server’s Live Connections).

References

• https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP and other articles under HTTP security.
• https://owasp.org/www-project-secure-headers/
• https://helmetjs.github.io/

Caddyfile

export type Caddyfile = string;

A type alias to make your type annotations more specific.

caddyfile()

export default function caddyfile(
  templateStrings: TemplateStringsArray,
  ...substitutions: Caddyfile[]
): Caddyfile;

A tagged template for Caddyfile.

dataDirectory()

export function dataDirectory(): string;

A best-effort to get the path to the data directory in which Caddy stores TLS certificates.

Related Work

caddy-npm

Only supports specific versions of Caddy and requires an update to the package itself when a new version of Caddy is released. At the time of this writing (2023-11-14) the latest supported version is Caddy 2.1.1 from 2020-06-20 (more than three years old).

@radically-straightforward/caddy, on the other hand, supports new versions of Caddy as soon as they’re released.