@homeflare/alchemy 0.6.0 → 0.8.0

package/src/caddy/guards.test.ts

@@ -0,0 +1,156 @@
+/**
+ * The pure checks: the digest's canonical form, the Caddyfile secret tripwire, and the admin-block
+ * guard. Each refusal here is one a deploy would otherwise learn about from a stranded Caddy or a
+ * token in the state store.
+ */
+import { describe, expect, test } from 'bun:test';
+import { adminProblems } from './admin-guard.ts';
+import type { CaddyAdminListener } from './admin.ts';
+import { caddyfileSecretProblems, tokensOf } from './caddyfile-tripwire.ts';
+import { canonicalConfig, configDigest, parseConfig } from './digest.ts';
+
+describe('digest', () => {
+  test('struct order (/adapt) and sorted, escaped, newline-terminated (/config/) hash the same', () => {
+    const adapted = {
+      apps: { http: { servers: { srv0: { routes: ['<a> & b'], listen: [':443'] } } } },
+    };
+    const reported =
+      '{"apps":{"http":{"servers":{"srv0":{"listen":[":443"],"routes":["\\u003ca\\u003e \\u0026 b"]}}}}}\n';
+    expect(configDigest(parseConfig(reported))).toBe(configDigest(adapted));
+  });
+
+  test('an empty config is null, and hashes as null', () => {
+    expect(parseConfig('null\n')).toBeNull();
+    expect(canonicalConfig(undefined)).toBe('null');
+  });
+
+  test('a real difference is a different digest', () => {
+    expect(configDigest({ a: [1, 2] })).not.toBe(configDigest({ a: [2, 1] }));
+  });
+});
+
+describe('tokensOf', () => {
+  test('quotes kept whole, comments dropped only at a token start', () => {
+    expect(tokensOf('header Authorization "Bearer {env.T}" # note')).toEqual([
+      'header',
+      'Authorization',
+      'Bearer {env.T}',
+    ]);
+    expect(tokensOf('respond a#b')).toEqual(['respond', 'a#b']);
+  });
+});
+
+/**
+ * ⚠️ ASSEMBLED AT RUN TIME. A literal token-shaped fixture trips the pre-commit gitleaks scan
+ *   (MEASURED 2026-09-21: its `jwt` rule flagged the first draft of this file). Joined parts keep
+ *   the shape the tripwire must catch out of the source text gitleaks reads.
+ */
+const GITHUB_TOKEN = ['ghp', 'a1B2'.repeat(9)].join('_');
+const JWT = ['eyJhbGciOiJub25lIn0', 'eyJzdWIiOiJ4In0x', 'c2lnbmF0dXJl'].join('.');
+const BCRYPT = ['', '2a', '14', 'x'.repeat(53)].join('$');
+
+describe('caddyfileSecretProblems', () => {
+  test.each([
+    ['dns provider token', 'tls {\n  dns cloudflare abcdef0123456789\n}'],
+    ['acme_dns token', 'acme_dns cloudflare abcdef0123456789'],
+    ['a secret-named subdirective', 'oauth {\n  client_secret s3cr3t\n}'],
+    [
+      'a literal Authorization header',
+      'reverse_proxy up:80 {\n  header_up Authorization "Bearer abc123"\n}',
+    ],
+    ['a GitHub token anywhere', `respond ${GITHUB_TOKEN}`],
+    ['a JWT', `header X-Id ${JWT}`],
+    ['a bcrypt hash in basic_auth', `basic_auth {\n  admin ${BCRYPT}\n}`],
+    ['a PEM private key', 'x {\n-----BEGIN EC PRIVATE KEY-----\n}'],
+    // ⛔ An adapt-time default is spliced in whenever the variable is unset: it is a literal.
+    ['a literal default for a dns token', 'dns cloudflare {$CF_API_TOKEN:abcdef0123456789}'],
+    ['a token-shaped default anywhere', `respond "{$GREETING:${GITHUB_TOKEN}}"`],
+  ])('refuses %s', (_, caddyfile) => {
+    const found = caddyfileSecretProblems(caddyfile);
+    expect(found.length).toBeGreaterThan(0);
+    expect(found.join(' ')).toContain('{env.NAME}');
+  });
+
+  test('never echoes the secret it found', () => {
+    const found = caddyfileSecretProblems('dns cloudflare abcdef0123456789').join(' ');
+    expect(found).not.toContain('abcdef0123456789');
+    expect(found).toContain('line 1');
+  });
+
+  test.each([
+    ['env placeholder', 'tls {\n  dns cloudflare {env.CF_API_TOKEN}\n}'],
+    ['file placeholder', 'client_secret {file./run/secrets/oidc}'],
+    ['adapt-time env (the name only)', 'dns cloudflare {$CF_API_TOKEN}'],
+    ['an adapt-time default that is not a secret', 'reverse_proxy {$UPSTREAM:127.0.0.1:8080}'],
+    ['a placeholder bearer', 'header_up Authorization "Bearer {env.UPSTREAM_TOKEN}"'],
+    ['a forwarded header', 'header_up Authorization {http.request.header.Authorization}'],
+    ['a block opener', 'dns cloudflare {\n  api_token {env.CF}\n}'],
+    ['a deleted header', 'header -Authorization'],
+    ['a *_file path', 'api_key_file /run/secrets/key'],
+    ['a hash from the env', 'basic_auth {\n  admin {env.ADMIN_HASH}\n}'],
+    ['an ordinary site', 'app.example.com {\n  reverse_proxy 127.0.0.1:8080\n}'],
+  ])('allows %s', (_, caddyfile) => {
+    expect(caddyfileSecretProblems(caddyfile)).toEqual([]);
+  });
+});
+
+describe('adminProblems', () => {
+  const tcp: CaddyAdminListener = { hostHeader: '127.0.0.1:2019', kind: 'tcp', port: 2019 };
+  const unix: CaddyAdminListener = { kind: 'unix', path: '/run/caddy/admin.sock' };
+  const admin = (block: object) => ({ admin: block, apps: {} });
+
+  const v6: CaddyAdminListener = { hostHeader: '[::1]:2019', kind: 'tcp', port: 2019 };
+  const named: CaddyAdminListener = { hostHeader: 'localhost:2019', kind: 'tcp', port: 2019 };
+
+  test.each([
+    [{}, tcp],
+    [{ listen: 'localhost:2019' }, tcp],
+    [{ listen: '127.0.0.1:2019', origins: ['127.0.0.1:2019'] }, tcp],
+    [{ listen: 'tcp/[::1]:2019' }, v6],
+    [{ listen: '127.0.0.1:2019' }, named],
+    [{ listen: 'unix//run/caddy/admin.sock|0660' }, unix],
+    [{ origins: ['http://127.0.0.1:2019'] }, tcp],
+  ])('allows %j', (block, transport) => {
+    expect(adminProblems(admin(block), transport)).toEqual([]);
+  });
+
+  test('no admin block at all, and an empty config, pass at Caddy’s default listener', () => {
+    expect(adminProblems({ apps: {} }, tcp)).toEqual([]);
+    expect(adminProblems(null, tcp)).toEqual([]);
+  });
+
+  /**
+   * ⛔ No `admin` address means DefaultAdminListen (localhost:2019) after the load — so a Caddy
+   *   reached anywhere else would move away from the provider (admin.go replaceLocalAdminServer).
+   */
+  test.each([
+    ['a unix socket', unix],
+    ['another port', { hostHeader: '127.0.0.1:2999', kind: 'tcp', port: 2999 } as const],
+    ['[::1] (localhost binds IPv4)', v6],
+  ])('no admin address is refused for a Caddy reached on %s', (_, transport) => {
+    expect(adminProblems({ apps: {} }, transport).join(' ')).toMatch(/declare `admin <address>`/);
+  });
+
+  test.each([
+    [{ disabled: true }, tcp, /admin off/],
+    [{ listen: ':2019' }, tcp, /not loopback/],
+    [{ listen: '0.0.0.0:2019' }, tcp, /not loopback/],
+    [{ listen: '192.0.2.5:2019' }, tcp, /not loopback/],
+    [{ listen: 'localhost:2020' }, tcp, /moves the admin API/],
+    [{ listen: 'tcp/[::1]:2019' }, tcp, /moves the admin API/],
+    [{ listen: '127.0.0.2:2019' }, tcp, /moves the admin API/],
+    [{ listen: 'localhost:2019' }, v6, /moves the admin API/],
+    [{ listen: 'unix//run/caddy/admin.sock', enforce_origin: true }, unix, /sends no Origin/],
+    [{ listen: 'unix//run/caddy/admin.sock' }, tcp, /moves the admin API/],
+    [{ listen: 'unix//run/other.sock' }, unix, /moves the admin API/],
+    [{ listen: '{env.CADDY_ADMIN}' }, tcp, /placeholder/],
+    [{ origins: ['caddy.example:2019'] }, tcp, /do not allow Host 127\.0\.0\.1:2019/],
+    [{ origins: ['https://127.0.0.1:2019'] }, tcp, /do not allow Host/],
+    [{ origins: [] }, tcp, /do not allow Host/],
+    [{}, { hostHeader: 'caddy.example:2019', kind: 'tcp', port: 2019 } as const, /default origins/],
+    [{ remote: { listen: ':2021' } }, tcp, /network-facing/],
+    [{ config: { load: { module: 'http' } } }, tcp, /pull its config/],
+  ])('refuses %j', (block, transport, reason) => {
+    expect(adminProblems(admin(block), transport).join(' ')).toMatch(reason);
+  });
+});

package/src/caddy/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Caddy for Alchemy — a running Caddy's config, declared as Caddyfile text and applied through
+ * Caddy's own admin API (`POST /load`, `GET /config/`).
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API, AND IT IS DELIBERATELY SMALLER THAN THE DIRECTORY. The lifecycle,
+ *   the digest, the guards and the admin calls are internals; an `export *` would publish them.
+ * ⛔ THE ADMIN API STAYS ON LOOPBACK OR A UNIX SOCKET. It has no authentication; localCaddyAdmin()
+ *   refuses any other address, and a Caddyfile that would move or expose it is refused before load.
+ * ⛔ NOTHING IS ADOPTED SILENTLY: a running config that is not the declared one needs `--adopt`.
+ * Guide, order of file and load, adoption, `--resume` and secrets: docs/caddy.md.
+ */
+export type {
+  CaddyAdmin,
+  CaddyAdminListener,
+  CaddyAdminRequest,
+  CaddyAdminResponse,
+} from './admin.ts';
+export { CaddyAdminService, CaddyUnreachableError, caddyAdminLayer } from './admin.ts';
+export { CaddyAdminError } from './admin-calls.ts';
+export type { CaddyConfigAttributes, CaddyConfigProps } from './config.ts';
+export { CaddyConfig, CaddyConfigProvider } from './config.ts';
+export type { LocalCaddyAdminOptions } from './local-admin.ts';
+export { DEFAULT_ADMIN_ADDRESS, localCaddyAdmin } from './local-admin.ts';
+export { caddyProviders } from './providers.ts';
+export type { CaddyWithFileProps } from './with-file.ts';
+export { caddyWithFile } from './with-file.ts';

package/src/caddy/local-admin.test.ts

@@ -0,0 +1,160 @@
+/**
+ * localCaddyAdmin: which addresses it accepts, the Host and Origin it sends (Caddy checks both),
+ * the unix-socket path, and retrying only a connection nothing accepted.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import { rmSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { CaddyUnreachableError } from './admin.ts';
+import { readRunningConfig } from './admin-calls.ts';
+import { type FakeCaddy, fakeCaddy } from './fake-caddy.ts';
+import { DEFAULT_ADMIN_ADDRESS, localCaddyAdmin, parseAdminAddress } from './local-admin.ts';
+
+let fake: FakeCaddy | undefined;
+afterEach(() => {
+  fake?.stop();
+  fake = undefined;
+});
+
+/** ⚠️ Short on purpose: macOS caps a socket path at 104 bytes, and node then fails EINVAL. */
+const socketPath = (label: string) => {
+  const path = join(tmpdir(), `fc-${label}-${String(process.pid)}.sock`);
+  rmSync(path, { force: true });
+  return path;
+};
+
+describe('parseAdminAddress', () => {
+  test("the default is Caddy's own default listener, over loopback TCP", () => {
+    expect(DEFAULT_ADMIN_ADDRESS).toBe('http://127.0.0.1:2019');
+    expect(parseAdminAddress(DEFAULT_ADMIN_ADDRESS).listener).toEqual({
+      hostHeader: '127.0.0.1:2019',
+      kind: 'tcp',
+      port: 2019,
+    });
+  });
+
+  test.each(['http://localhost:2019', 'http://[::1]:2019', 'http://127.0.0.2:2020'])(
+    'accepts loopback %s',
+    (address) => {
+      expect(parseAdminAddress(address).listener.kind).toBe('tcp');
+    },
+  );
+
+  test('a unix socket, which Caddy exempts from the Host check', () => {
+    expect(parseAdminAddress('unix:///run/caddy/admin.sock').listener).toEqual({
+      kind: 'unix',
+      path: '/run/caddy/admin.sock',
+    });
+  });
+
+  test.each([
+    ['http://192.0.2.10:2019', /not loopback/],
+    ['http://caddy.example.com:2019', /not loopback/],
+    ['https://127.0.0.1:2019', /only http/],
+    ['http://127.0.0.1:2019/config', /no path/],
+    ['http://user:pw@127.0.0.1:2019', /credentials/],
+    ['unix://relative.sock', /absolute/],
+    ['127.0.0.1:2019', /not a URL|only http/],
+  ])('refuses %s', (address, reason) => {
+    expect(() => parseAdminAddress(address)).toThrow(reason);
+  });
+
+  test('the Host always carries the port, as Caddy compares host:port (a default port too)', () => {
+    expect(parseAdminAddress('http://127.0.0.1').listener).toEqual({
+      hostHeader: '127.0.0.1:80',
+      kind: 'tcp',
+      port: 80,
+    });
+    expect(parseAdminAddress('http://[::1]:2019').listener).toMatchObject({
+      hostHeader: '[::1]:2019',
+    });
+  });
+
+  test('hostHeader is what Caddy checks: its port is the listener port, not the dialled one', () => {
+    const parsed = parseAdminAddress('http://127.0.0.1:12019', '127.0.0.1:2019');
+    expect(parsed.listener).toEqual({ hostHeader: '127.0.0.1:2019', kind: 'tcp', port: 2019 });
+    expect(() => parseAdminAddress('http://127.0.0.1:2019', 'no port')).toThrow(/host:port/);
+  });
+});
+
+describe('requests', () => {
+  test('over TCP: Host and Origin as the Caddy CLI sends them, so the checks pass', async () => {
+    fake = fakeCaddy();
+    const admin = localCaddyAdmin({ address: fake.address, retries: 0 });
+    expect(await readRunningConfig(admin)).toBeNull();
+    const host = `127.0.0.1:${String(fake.port)}`;
+    expect(fake.seen[0]?.headers.get('host')).toBe(host);
+    expect(fake.seen[0]?.headers.get('origin')).toBe(`http://${host}`);
+  });
+
+  test('a narrowed `origins` needs hostHeader — without it Caddy answers 403', async () => {
+    fake = fakeCaddy({ origins: ['caddy-admin.example:2019'] });
+    const plain = localCaddyAdmin({ address: fake.address, retries: 0 });
+    await expect(readRunningConfig(plain)).rejects.toThrow(/403: host not allowed/);
+    const named = localCaddyAdmin({
+      address: fake.address,
+      hostHeader: 'caddy-admin.example:2019',
+      retries: 0,
+    });
+    expect(await readRunningConfig(named)).toBeNull();
+  });
+
+  test('a caller cannot override the Host and Origin the checks depend on', async () => {
+    fake = fakeCaddy();
+    const admin = localCaddyAdmin({ address: fake.address, retries: 0 });
+    const headers = { Host: 'evil.example:2019', Origin: 'http://evil.example:2019' };
+    expect((await admin.request({ headers, method: 'GET', path: '/config/' })).status).toBe(200);
+    expect(fake.seen[0]?.headers.get('host')).toBe(`127.0.0.1:${String(fake.port)}`);
+  });
+
+  test('over a unix socket, with no Origin', async () => {
+    const path = socketPath('req');
+    fake = fakeCaddy({ running: { apps: {} }, unix: path });
+    const admin = localCaddyAdmin({ address: fake.address, retries: 0 });
+    expect(await readRunningConfig(admin)).toEqual({ apps: {} });
+    expect(fake.seen[0]?.headers.has('origin')).toBe(false);
+    rmSync(path, { force: true });
+  });
+
+  test('retries a socket nobody listens on yet, then reaches the Caddy that came up', async () => {
+    const path = socketPath('late');
+    const admin = localCaddyAdmin({ address: `unix://${path}`, retries: 5, retryDelayMs: 40 });
+    const late = setTimeout(() => {
+      fake = fakeCaddy({ unix: path });
+    }, 60);
+    expect(await readRunningConfig(admin)).toBeNull();
+    clearTimeout(late);
+    rmSync(path, { force: true });
+  });
+
+  test('a connection that was ACCEPTED is never re-sent, however many retries remain', async () => {
+    // ⛔ It may have reached Caddy: re-sending a `POST /load` could apply it twice.
+    let accepted = 0;
+    const server = createServer((socket) => {
+      accepted += 1;
+      socket.on('data', () => socket.destroy());
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const { port } = server.address() as { port: number };
+    const admin = localCaddyAdmin({
+      address: `http://127.0.0.1:${String(port)}`,
+      retries: 3,
+      retryDelayMs: 1,
+    });
+    const failure = admin.request({ body: 'x', method: 'POST', path: '/load' });
+    await expect(failure).rejects.toThrow(/Caddy admin POST \/load/);
+    await expect(failure).rejects.not.toBeInstanceOf(CaddyUnreachableError);
+    expect(accepted).toBe(1);
+    server.close();
+  });
+
+  test('gives up after the retries with CaddyUnreachableError, naming the address', async () => {
+    const path = socketPath('never');
+    const admin = localCaddyAdmin({ address: `unix://${path}`, retries: 1, retryDelayMs: 1 });
+    const failure = readRunningConfig(admin);
+    await expect(failure).rejects.toBeInstanceOf(CaddyUnreachableError);
+    await expect(failure).rejects.toThrow(/Caddy admin GET \/config\/ at unix:\/\//);
+  });
+});

package/src/caddy/local-admin.ts

@@ -0,0 +1,189 @@
+/**
+ * The real CaddyAdmin: this machine's Caddy, over loopback TCP or a unix socket.
+ *
+ * ★ node:http, NOT fetch. MEASURED 2026-09-21 on bun 1.4.0 and node 26.7.0: node:http sends a Host
+ *   override and dials a unix socket on BOTH runtimes, while node's fetch silently drops a `Host`
+ *   header (it sent the URL's host) and only Bun's fetch has a `unix` option. The published dist
+ *   loads under node too (launchd's local-runner.ts makes the same call for the same reason).
+ * ⛔ LOOPBACK OR A UNIX SOCKET, NOTHING ELSE. The admin API is unauthenticated plaintext; an
+ *   address off this machine means it is reachable from the network, which decision 23 forbids.
+ *   Reaching another host's Caddy means forwarding its socket or port to here (SSH), never
+ *   exposing :2019.
+ * ★ HOST AND ORIGIN, AS CADDY's OWN CLI SENDS THEM (cmd/commandfuncs.go AdminAPIRequest): over
+ *   TCP, `Host` and `Origin: http://<host>`; over a socket, `Host: 127.0.0.1` and no Origin, because
+ *   Caddy skips the Host check on unix listeners (admin.go allowedOrigins). MEASURED against the
+ *   mini's Caddy 2.11.4: any other Host gets 403 `host not allowed`, a forwarded port included —
+ *   hence `hostHeader`.
+ */
+import { request as httpRequest } from 'node:http';
+import {
+  type CaddyAdmin,
+  type CaddyAdminListener,
+  type CaddyAdminResponse,
+  CaddyUnreachableError,
+} from './admin.ts';
+
+export type LocalCaddyAdminOptions = {
+  /**
+   * `http://<loopback>:<port>` or `unix:///absolute/path.sock`.
+   * @default 'http://127.0.0.1:2019' — Caddy's default admin listener (`localhost:2019`).
+   */
+  readonly address?: string;
+  /**
+   * The Host (and Origin) to send over TCP, when it is not the address's own: the Caddyfile
+   * narrowed `admin { origins … }`, or the port is an SSH forward of the real one (Caddy checks
+   * the Host against ITS port, not yours). Form `host:port`.
+   */
+  readonly hostHeader?: string;
+  /**
+   * Abort an exchange after this long. @default 60_000
+   * ⚠️ A `shutdown_delay` in the Caddyfile makes `/load` block that long (caddyhttp app.go Stop);
+   *   a timeout then fails the deploy while Caddy goes on to apply — the next plan converges.
+   */
+  readonly timeoutMs?: number;
+  /**
+   * Retries when the connection is REFUSED (nothing listening yet — a Caddy launchd job that was
+   * bootstrapped a moment ago). Only refusals: those never reached Caddy, so re-sending a
+   * `POST /load` cannot apply it twice. @default 2
+   */
+  readonly retries?: number;
+  /** @default 500 */
+  readonly retryDelayMs?: number;
+};
+
+export const DEFAULT_ADMIN_ADDRESS = 'http://127.0.0.1:2019';
+
+type Target =
+  | { readonly kind: 'tcp'; readonly host: string; readonly port: number }
+  | { readonly kind: 'unix'; readonly socketPath: string };
+
+const UNIX = 'unix://';
+const HOST_PORT = /^(?:[A-Za-z0-9.-]+|\[[0-9A-Fa-f:.]+\]):\d{1,5}$/;
+
+const refuse = (address: string, why: string): Error =>
+  new Error(`Caddy admin address ${JSON.stringify(address)}: ${why}`);
+
+const isLoopback = (hostname: string): boolean =>
+  hostname === 'localhost' || hostname === '[::1]' || /^127(?:\.\d{1,3}){3}$/.test(hostname);
+
+/** The dial target and listener for an address, or a refusal naming what is wrong with it. */
+export const parseAdminAddress = (
+  address: string,
+  hostHeader?: string,
+): { target: Target; listener: CaddyAdminListener } => {
+  if (hostHeader !== undefined && !HOST_PORT.test(hostHeader)) {
+    throw refuse(address, `hostHeader ${JSON.stringify(hostHeader)} must be host:port`);
+  }
+  if (address.startsWith(UNIX)) {
+    const socketPath = address.slice(UNIX.length);
+    if (!socketPath.startsWith('/')) throw refuse(address, 'the socket path must be absolute');
+    return { listener: { kind: 'unix', path: socketPath }, target: { kind: 'unix', socketPath } };
+  }
+  let url: URL;
+  try {
+    url = new URL(address);
+  } catch {
+    throw refuse(address, 'not a URL (http://127.0.0.1:2019 or unix:///path)');
+  }
+  // ⛔ Caddy's local admin endpoint is plaintext by design; its TLS one (`admin.remote`, mTLS on
+  //   :2021) is a different, network-facing API this transport deliberately does not speak.
+  if (url.protocol !== 'http:') throw refuse(address, 'only http:// (loopback) or unix://');
+  if (!isLoopback(url.hostname)) {
+    throw refuse(address, 'not loopback — the admin API is unauthenticated; forward it to here');
+  }
+  if (url.pathname !== '/' || url.search !== '' || url.username !== '') {
+    throw refuse(address, 'no path, query or credentials — the API lives at the root');
+  }
+  const port = url.port === '' ? 80 : Number(url.port);
+  // ⚠️ NOT `url.host`: WHATWG URL drops a default port (`http://127.0.0.1:80` has host
+  //   `127.0.0.1`), and Caddy compares the Host against `host:port` (admin.go allowedOrigins), so
+  //   a portless Host is a 403 on every call. The Caddy CLI always sends the port (JoinHostPort).
+  const host = hostHeader ?? `${url.hostname}:${String(port)}`;
+  return {
+    listener: {
+      hostHeader: host,
+      kind: 'tcp',
+      port: Number(host.slice(host.lastIndexOf(':') + 1)),
+    },
+    // ★ `hostname` keeps IPv6 brackets; node:http wants them off.
+    target: { host: url.hostname.replace(/^\[(.*)\]$/, '$1'), kind: 'tcp', port },
+  };
+};
+
+const code = (cause: unknown): string | undefined =>
+  typeof cause === 'object' && cause !== null && 'code' in cause
+    ? String((cause as { code: unknown }).code)
+    : undefined;
+
+/** Nothing accepted the connection: refused TCP, or no socket file yet. The request never left. */
+const neverConnected = (cause: unknown): boolean =>
+  code(cause) === 'ECONNREFUSED' || code(cause) === 'ENOENT';
+
+const exchange = (
+  target: Target,
+  method: string,
+  path: string,
+  headers: Record<string, string>,
+  body: string | undefined,
+  timeoutMs: number,
+): Promise<CaddyAdminResponse> =>
+  new Promise((resolve, reject) => {
+    const bytes = body === undefined ? undefined : Buffer.from(body, 'utf8');
+    const request = httpRequest(
+      {
+        ...(target.kind === 'tcp'
+          ? { host: target.host, port: target.port }
+          : { socketPath: target.socketPath }),
+        headers: bytes === undefined ? headers : { ...headers, 'Content-Length': bytes.length },
+        method,
+        path,
+        timeout: timeoutMs,
+      },
+      (response) => {
+        const chunks: Buffer[] = [];
+        response.on('data', (chunk: Buffer) => chunks.push(chunk));
+        response.on('error', reject);
+        response.on('end', () =>
+          resolve({
+            body: Buffer.concat(chunks).toString('utf8'),
+            status: response.statusCode ?? 0,
+          }),
+        );
+      },
+    );
+    request.on('timeout', () => request.destroy(new Error(`no answer in ${String(timeoutMs)} ms`)));
+    request.on('error', reject);
+    request.end(bytes);
+  });
+
+export const localCaddyAdmin = (options: LocalCaddyAdminOptions = {}): CaddyAdmin => {
+  const address = options.address ?? DEFAULT_ADMIN_ADDRESS;
+  const { listener, target } = parseAdminAddress(address, options.hostHeader);
+  const timeoutMs = options.timeoutMs ?? 60_000;
+  const retries = options.retries ?? 2;
+  const delay = options.retryDelayMs ?? 500;
+  const fixed: Record<string, string> =
+    listener.kind === 'tcp'
+      ? { Host: listener.hostHeader, Origin: `http://${listener.hostHeader}` }
+      : { Host: '127.0.0.1' };
+  return {
+    endpoint: address,
+    listener,
+    request: async ({ body, headers, method, path }) => {
+      for (let attempt = 0; ; attempt += 1) {
+        try {
+          // oxlint-disable-next-line no-await-in-loop -- sequential by design: retry after a wait
+          return await exchange(target, method, path, { ...headers, ...fixed }, body, timeoutMs);
+        } catch (cause) {
+          if (!neverConnected(cause) || attempt >= retries) {
+            const reason = cause instanceof Error ? cause.message : String(cause);
+            const message = `Caddy admin ${method} ${path} at ${address}: ${reason}`;
+            throw neverConnected(cause) ? new CaddyUnreachableError(message) : new Error(message);
+          }
+          // oxlint-disable-next-line no-await-in-loop -- the wait between attempts
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+      }
+    },
+  };
+};