@homeflare/alchemy 0.6.0 → 0.7.0

package/src/caddy/admin-calls.ts

@@ -0,0 +1,128 @@
+/**
+ * The three admin API calls the provider makes, each classified into a value or a readable Error
+ * that carries Caddy's own message.
+ *
+ * Read in caddyserver/caddy v2.11.4 (and the API docs, caddyserver.com/docs/api):
+ *   · `POST /adapt` — adapts without running (load.go handleAdapt): 200 `{warnings?, result}`,
+ *     or 400 `{"error": …}`. Side-effect free, so it is what plan-time validation uses.
+ *   · `POST /load` — Content-Type `text/caddyfile` picks the adapter (load.go adaptByContentType);
+ *     "if the new config fails for any reason, the old config is rolled back into place without
+ *     downtime" (docs; caddy.go changeConfig restores the previous raw config). An identical
+ *     config is a no-op without `Cache-Control: must-revalidate`.
+ *   · `GET /config/` — the running config as JSON, `null` when empty (admin.go handleConfig).
+ * ⛔ A FAILED LOAD CAN ANSWER 200. load.go writes the adapter's WARNINGS to the body before it
+ *   runs the config; if the run then fails, the error JSON is appended to a response whose status
+ *   is already 200 (Go's first Write sends 200; the later WriteHeader(400) is ignored). The
+ *   Caddyfile adapter warns on every unformatted input (adapter.go FormattingDifference), so this
+ *   is the COMMON failure shape, not an edge. Hence: look for the error in the body whatever the
+ *   status — and the lifecycle reads the config back after every load anyway.
+ *   MEASURED 2026-09-21 on a throwaway Caddy 2.11.4 (loopback ports, isolated XDG dirs): an
+ *   unformatted Caddyfile whose port was taken answered `200` with body
+ *   `[{"file":"Caddyfile","line":8,"message":"Caddyfile input is not formatted; …"}]{"error":"loading
+ *   config: … bind: address already in use"}`, and Caddy kept serving the previous config.
+ */
+import type { CaddyAdmin, CaddyAdminResponse } from './admin.ts';
+import { parseConfig } from './digest.ts';
+
+export class CaddyAdminError extends Error {
+  constructor(
+    readonly status: number,
+    readonly method: string,
+    readonly path: string,
+    reason: string,
+  ) {
+    super(`Caddy ${method} ${path} → ${String(status)}: ${reason}`);
+    this.name = 'CaddyAdminError';
+  }
+}
+
+const CADDYFILE = 'text/caddyfile';
+/** APIError marshals as exactly this key (admin.go APIError, `json:"error"`). */
+const ERROR_OPEN = '{"error":';
+
+type Warning = { file?: string; line?: number; message?: string };
+
+const describe = (warning: Warning): string =>
+  `${warning.file ?? 'Caddyfile'}:${String(warning.line ?? 0)}: ${warning.message ?? '(no message)'}`;
+
+/** Caddy's `error` string from a body that holds one, or `undefined`. */
+const errorIn = (body: string): string | undefined => {
+  const at = body.lastIndexOf(ERROR_OPEN);
+  if (at === -1) return undefined;
+  try {
+    const parsed = JSON.parse(body.slice(at)) as { error?: unknown };
+    return typeof parsed.error === 'string' ? parsed.error : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+const warningsIn = (text: string): string[] => {
+  if (text.trim() === '') return [];
+  try {
+    const parsed = JSON.parse(text) as unknown;
+    return Array.isArray(parsed) ? (parsed as Warning[]).map(describe) : [];
+  } catch {
+    return [];
+  }
+};
+
+const fail = (response: CaddyAdminResponse, method: string, path: string): never => {
+  const reason = errorIn(response.body) ?? (response.body.trim().slice(0, 500) || '(empty body)');
+  // ⚠️ Say so when the status lied (the ⛔ above), or "→ 200" reads like success.
+  const shown = response.status === 200 ? `${reason} (error in a 200 body)` : reason;
+  throw new CaddyAdminError(response.status, method, path, shown);
+};
+
+export type Adapted = { readonly config: unknown; readonly warnings: readonly string[] };
+
+/** Adapt a Caddyfile to JSON on the running Caddy, without loading it. */
+export const adaptCaddyfile = async (admin: CaddyAdmin, caddyfile: string): Promise<Adapted> => {
+  const response = await admin.request({
+    body: caddyfile,
+    headers: { 'Content-Type': CADDYFILE },
+    method: 'POST',
+    path: '/adapt',
+  });
+  // ★ Status alone here: /adapt writes its body once, and a successful result is config JSON in
+  //   which an `error` handler's key could look like an error object to a substring search.
+  if (response.status !== 200) fail(response, 'POST', '/adapt');
+  const parsed = JSON.parse(response.body) as { result?: unknown; warnings?: Warning[] };
+  return { config: parsed.result ?? null, warnings: (parsed.warnings ?? []).map(describe) };
+};
+
+/** The running config, parsed; `null` when Caddy runs with none. */
+export const readRunningConfig = async (admin: CaddyAdmin): Promise<unknown> => {
+  const response = await admin.request({ method: 'GET', path: '/config/' });
+  if (response.status !== 200) fail(response, 'GET', '/config/');
+  return parseConfig(response.body);
+};
+
+/**
+ * Apply a Caddyfile with `POST /load`; resolves with the adapter's warnings.
+ *
+ * ★ `sourceFile` RIDES AS `Caddy-Config-Source-File` (+ `-Adapter: caddyfile`), the headers
+ *   `caddy reload` sends (cmd/commandfuncs.go). A load WITHOUT them makes Caddy forget the file it
+ *   was started with (caddy.go ClearLastConfigIfDifferent), and SIGUSR1 then no longer reloads
+ *   from that file. With them, and the same path, it keeps it.
+ */
+export const loadCaddyfile = async (
+  admin: CaddyAdmin,
+  caddyfile: string,
+  sourceFile?: string,
+): Promise<readonly string[]> => {
+  const response = await admin.request({
+    body: caddyfile,
+    headers: {
+      'Content-Type': CADDYFILE,
+      ...(sourceFile === undefined
+        ? {}
+        : { 'Caddy-Config-Source-Adapter': 'caddyfile', 'Caddy-Config-Source-File': sourceFile }),
+    },
+    method: 'POST',
+    path: '/load',
+  });
+  const refused = errorIn(response.body);
+  if (response.status !== 200 || refused !== undefined) fail(response, 'POST', '/load');
+  return warningsIn(response.body);
+};

package/src/caddy/admin-guard.ts

@@ -0,0 +1,170 @@
+/**
+ * Refuse a config whose `admin` block would cut the provider off from Caddy, or expose the admin
+ * API — checked on the ADAPTED JSON (`POST /adapt`), before anything is loaded.
+ *
+ * ⛔ A Caddyfile can move its own admin endpoint. After `POST /load`, Caddy swaps the admin server
+ *   to the new config's (admin.go replaceLocalAdminServer), so each of these would succeed ONCE and
+ *   then strand the resource — no read-back, no drift check, no next deploy — or worse:
+ *   · `admin off` (`disabled`): nothing can manage this Caddy through its API again.
+ *   · a `listen` off loopback (`:2019`, `0.0.0.0:2019`, a LAN address): the unauthenticated API is
+ *     on the network. Decision 23: never expose :2019.
+ *   · a `listen` on another port, socket or loopback ADDRESS than the transport's: the provider
+ *     loses Caddy. Go binds exactly the literal address given (`[::1]:2019` is not reachable at
+ *     `127.0.0.1:2019`), and a hostname binds its first IPv4 address (net ListenConfig.Listen,
+ *     `addrs.first(isIPv4)`), so `localhost:2019` is `127.0.0.1:2019`. MEASURED 2026-09-21 on a
+ *     throwaway Caddy 2.11.4: after loading `admin [::1]:<p>`, `127.0.0.1:<p>` refused the
+ *     connection; after `admin localhost:<p>`, `[::1]:<p>` did.
+ *   · NO `admin` address at all: Caddy falls back to DefaultAdminListen — `localhost:2019`, or
+ *     `$CADDY_ADMIN` in ITS environment (admin.go replaceLocalAdminServer), which this side cannot
+ *     see. A Caddy reached any other way (a socket, another port) moves there on the first load.
+ *     Refused unless the transport is at that default; declaring `admin <address>` is the fix.
+ *   · a Host the new config does not allow: `origins` without it, or — with no `origins` — a Host
+ *     outside Caddy's loopback defaults (`localhost`, `[::1]`, `127.0.0.1` at the listen port).
+ *     Every later call answers 403 (admin.go allowedOrigins / checkHost; MEASURED on the mini's
+ *     Caddy 2.11.4 — `host not allowed`). The transport also sends `Origin: http://<Host>`, which
+ *     Caddy checks against the same list (originAllowed), so one check covers both.
+ *   · `enforce_origin` over a unix socket: this transport, like Caddy's CLI (cmd/commandfuncs.go
+ *     AdminAPIRequest), sends no Origin there, and a unix listener has no default origins — so
+ *     checkOrigin answers 403 to every call. MEASURED 2026-09-21 on a throwaway Caddy 2.11.4:
+ *     `client is not allowed to access from origin ''`, and that Caddy could not be managed again.
+ *   · `remote`: a second, network-facing admin listener (mTLS on :2021) — declare that deliberately,
+ *     not through this resource.
+ *   · `config.load`: Caddy pulls its config from elsewhere, replacing this one on a timer.
+ * ★ Read in caddyserver/caddy v2.11.4: admin.go AdminConfig / allowedOrigins / originAllowed, and
+ *   httpcaddyfile/options.go parseOptAdmin (an `admin { … }` block with no address still emits
+ *   `listen` as the default, so a present `listen` is the norm, not a change).
+ */
+import type { CaddyAdminListener } from './admin.ts';
+
+type AdminBlock = {
+  disabled?: boolean;
+  listen?: string;
+  origins?: string[];
+  enforce_origin?: boolean;
+  remote?: unknown;
+  config?: { load?: unknown };
+};
+
+/** Caddy's compiled-in admin port (admin.go DefaultAdminListen `localhost:2019`). */
+const DEFAULT_ADMIN_PORT = 2019;
+
+const LOOPBACK_HOST = /^(?:localhost|127(?:\.\d{1,3}){3}|\[?::1\]?)$/;
+
+type Listen = { kind: 'tcp'; host: string; port: number } | { kind: 'unix'; path: string };
+
+/** Caddy network address → a listener, or a description of why it is not one we can check. */
+const parseListen = (listen: string): Listen | string => {
+  if (listen.includes('{')) return 'a placeholder, which cannot be checked before it runs';
+  const unix = /^unix(?:gram|packet)?\/(.+?)(?:\|[0-7]{3,4})?$/.exec(listen);
+  if (unix !== null) return { kind: 'unix', path: unix[1] ?? '' };
+  if (/^[a-z0-9]+\//.test(listen) && !/^tcp[46]?\//.test(listen)) {
+    return `network ${JSON.stringify(listen.split('/')[0])}, not tcp or unix`;
+  }
+  const address = listen.replace(/^tcp[46]?\//, '');
+  const colon = address.lastIndexOf(':');
+  const port = Number(address.slice(colon + 1));
+  if (colon === -1 || !Number.isInteger(port) || port <= 0) return 'no single port';
+  return { host: address.slice(0, colon), kind: 'tcp', port };
+};
+
+const unbracket = (host: string): string => host.replace(/^\[(.*)\]$/, '$1');
+
+/**
+ * Whether a transport sending `hostHeader` reaches a listener bound to `listenHost`.
+ * ★ The Host stands in for the dial address: they are the same unless `hostHeader` was set for a
+ *   forward, where it should name the far side's address anyway. `localhost` on the transport's
+ *   side may resolve to either family (node tries both), so it reaches any loopback listener; a
+ *   literal address reaches only itself.
+ */
+const reaches = (hostHeader: string, listenHost: string): boolean => {
+  const dialled = unbracket(hostHeader.slice(0, hostHeader.lastIndexOf(':')));
+  const listening = unbracket(listenHost);
+  return (
+    dialled === 'localhost' || dialled === (listening === 'localhost' ? '127.0.0.1' : listening)
+  );
+};
+
+const sameListener = (listen: Listen, transport: CaddyAdminListener): boolean =>
+  listen.kind === 'tcp'
+    ? transport.kind === 'tcp' &&
+      listen.port === transport.port &&
+      reaches(transport.hostHeader, listen.host)
+    : transport.kind === 'unix' && listen.path === transport.path;
+
+/** Caddy's allowed Hosts for a loopback listener with no `origins` (admin.go allowedOrigins). */
+const defaultOrigins = (port: number): string[] =>
+  ['localhost', '[::1]', '127.0.0.1'].map((host) => `${host}:${String(port)}`);
+
+const originHost = (origin: string): string | undefined => {
+  if (!origin.includes('://')) return origin;
+  try {
+    const url = new URL(origin);
+    // ⚠️ originAllowed compares schemes when an entry has one; the transport sends `http://`.
+    return url.protocol === 'http:' ? url.host : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+const listenProblem = (admin: AdminBlock, transport: CaddyAdminListener): string | undefined => {
+  if (admin.listen === undefined) {
+    const atDefault =
+      transport.kind === 'tcp' &&
+      transport.port === DEFAULT_ADMIN_PORT &&
+      reaches(transport.hostHeader, 'localhost');
+    return atDefault
+      ? undefined
+      : 'no `admin` address: Caddy would fall back to its default listener (localhost:2019, or ' +
+          '$CADDY_ADMIN), away from where this provider reaches it — declare `admin <address>`';
+  }
+  const listen = parseListen(admin.listen);
+  const shown = JSON.stringify(admin.listen);
+  if (typeof listen === 'string') {
+    return `admin listen ${shown} is ${listen}; declare a literal loopback address`;
+  }
+  if (listen.kind === 'tcp' && !LOOPBACK_HOST.test(listen.host)) {
+    return `admin listen ${shown} is not loopback — it would put the admin API on the network`;
+  }
+  return sameListener(listen, transport)
+    ? undefined
+    : `admin listen ${shown} moves the admin API away from where this provider reaches it`;
+};
+
+/** Refusals for the adapted config's `admin` block, given where the transport reaches Caddy. */
+export const adminProblems = (adapted: unknown, transport: CaddyAdminListener): string[] => {
+  const admin =
+    typeof adapted === 'object' && adapted !== null
+      ? ((adapted as { admin?: AdminBlock }).admin ?? {})
+      : {};
+  const found: string[] = [];
+  if (admin.disabled === true) {
+    return ['`admin off` would disable the admin API this resource manages Caddy through'];
+  }
+  if (admin.remote !== undefined) found.push('`admin.remote` opens a network-facing admin API');
+  if (admin.config?.load !== undefined) {
+    found.push(
+      '`admin.config.load` makes Caddy pull its config from elsewhere, replacing this one',
+    );
+  }
+  const moved = listenProblem(admin, transport);
+  if (moved !== undefined) found.push(moved);
+  if (transport.kind === 'tcp') {
+    const allowed = admin.origins?.map(originHost) ?? defaultOrigins(transport.port);
+    if (!allowed.includes(transport.hostHeader)) {
+      const which =
+        admin.origins === undefined
+          ? `Caddy's default origins (no \`origins\` declared) ${JSON.stringify(allowed)}`
+          : `admin origins ${JSON.stringify(admin.origins)}`;
+      found.push(
+        `${which} do not allow Host ${transport.hostHeader}, which this provider sends — ` +
+          'Caddy would refuse it every call after this one',
+      );
+    }
+  } else if (admin.enforce_origin === true) {
+    found.push(
+      '`enforce_origin` over a unix socket: this transport (like the Caddy CLI) sends no Origin ' +
+        'there, so Caddy would answer 403 to every call',
+    );
+  }
+  return found;
+};

package/src/caddy/admin.ts

@@ -0,0 +1,74 @@
+/**
+ * The one seam between the Caddy provider and a running Caddy: every call to Caddy's admin API goes
+ * through a CaddyAdmin, and nothing in this directory reaches Caddy any other way.
+ *
+ * ★ CADDY's OWN MANAGEMENT API, NOT A FILE AND A SIGNAL. Decision 23 (vault consolidation plan,
+ *   2026-09-21): `POST /load` applies a Caddyfile with a graceful reload and rolls back a config
+ *   Caddy refuses; `GET /config/` reports what is running. Read in caddyserver/caddy v2.11.4,
+ *   caddyconfig/load.go and admin.go, and in the API docs (caddyserver.com/docs/api).
+ * ★ A SEAM, THE SAME SHAPE AS launchd's HostRunner, so the lifecycle runs against a fake admin
+ *   server in tests and a consumer can plug in another route to the API (an SSH-forwarded socket
+ *   today; a remote runner later) without touching the provider. PROMISES, NOT EFFECTS, for the
+ *   same reason as HostRunner: a consumer writing their own implements plain async functions.
+ * ⛔ THE ADMIN API HAS NO AUTHENTICATION. Anyone who reaches it can replace every site. It stays on
+ *   loopback or a unix socket; localCaddyAdmin() refuses anything else (local-admin.ts).
+ */
+import * as Context from 'effect/Context';
+import * as Layer from 'effect/Layer';
+
+/** One admin API exchange. ⛔ `body` may hold the running config — never log it whole. */
+export type CaddyAdminResponse = {
+  readonly status: number;
+  readonly body: string;
+};
+
+export type CaddyAdminRequest = {
+  readonly method: 'GET' | 'POST';
+  /** Absolute API path: `/load`, `/adapt`, `/config/`. */
+  readonly path: string;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly body?: string;
+};
+
+/**
+ * Where the admin listener is, in the terms Caddy's own `admin` option uses — so a Caddyfile that
+ * would move the listener away from where the provider talks to it can be refused (admin-guard.ts).
+ */
+export type CaddyAdminListener =
+  | { readonly kind: 'tcp'; readonly hostHeader: string; readonly port: number }
+  | { readonly kind: 'unix'; readonly path: string };
+
+export interface CaddyAdmin {
+  /** Where requests go, for error messages and the resource's attributes. Never a credential. */
+  readonly endpoint: string;
+  /**
+   * The listener as Caddy sees it. `hostHeader` is the Host every request carries: Caddy checks it
+   * against `admin.origins` (admin.go checkHost) on any loopback TCP listener.
+   */
+  readonly listener: CaddyAdminListener;
+  /**
+   * Send one request. Resolves with ANY status — classifying it is the caller's job
+   * (admin-calls.ts). Rejects only when there was no HTTP exchange at all: with a
+   * CaddyUnreachableError when nothing accepted the connection, any other Error otherwise.
+   */
+  request(request: CaddyAdminRequest): Promise<CaddyAdminResponse>;
+}
+
+/**
+ * Nothing accepted the connection — Caddy is not running, or not listening yet. A transport rejects
+ * with THIS only when the request provably never reached Caddy (refused, no socket file), because
+ * the provider treats it differently from every other failure: a stopped Caddy must not fail the
+ * PLAN that would bring it back (its launchd job in the same stack) — see config.ts.
+ */
+export class CaddyUnreachableError extends Error {
+  override readonly name = 'CaddyUnreachableError';
+}
+
+/** The Effect service the Caddy provider reads its admin transport from. */
+export class CaddyAdminService extends Context.Service<CaddyAdminService, CaddyAdmin>()(
+  'homeflare/caddy/CaddyAdmin',
+) {}
+
+/** Provide a transport to the provider: `Layer.provide(caddyAdminLayer(localCaddyAdmin()))`. */
+export const caddyAdminLayer = (admin: CaddyAdmin): Layer.Layer<CaddyAdminService> =>
+  Layer.succeed(CaddyAdminService, admin);

package/src/caddy/caddyfile-tripwire.ts

@@ -0,0 +1,133 @@
+/**
+ * A tripwire for the obvious ways a secret ends up in a CaddyConfig's `caddyfile` prop.
+ *
+ * ⛔ WHY IT EXISTS. Alchemy stores every prop UNENCRYPTED in its state store and prints it in plan
+ *   diffs (the reason launchd's secret-tripwire.ts and the metadata-only OpenBao families exist).
+ *   The whole Caddyfile is one prop, so a token typed into it is a token in state.
+ * ★ THE ALTERNATIVE, NAMED IN EVERY REFUSAL: a RUNTIME placeholder, which Caddy resolves in its own
+ *   process and which therefore never enters the Caddyfile, the state, the adapted JSON or
+ *   `autosave.json` (caddyserver/caddy v2.11.4 replacer.go):
+ *   · `{env.NAME}` — the Caddy process's environment; start Caddy with `--envfile <path>` where a
+ *     secret renderer (openbao-agent) writes that file. A rotated value needs a Caddy restart.
+ *   · `{file./path}` — the file's contents, trailing newline trimmed, read when the placeholder is
+ *     evaluated; the renderer writes the file.
+ * ⚠️ `{$NAME}` IS NOT ONE OF THEM. It is substituted at ADAPT time (caddyfile/parse.go
+ *   replaceEnvVars), so the value lands in the adapted JSON — readable at `GET /config/` and
+ *   written to `autosave.json`. It is not refused (the prop holds only the name), but it is worse.
+ *   `{$NAME:default}` is different: the default IS in the prop, and is checked as a literal.
+ * ⚠️ A TRIPWIRE, NOT A SCANNER. It catches the names and shapes people actually type; a secret in
+ *   an innocent-looking argument passes. Nothing here makes a secret safe to declare.
+ */
+import { PRIVATE_KEY } from '../launchd/secret-tripwire.ts';
+
+const ALTERNATIVE =
+  'props are stored unencrypted in Alchemy state. Use a runtime placeholder instead: {env.NAME} ' +
+  '(Caddy started with --envfile <file a secret renderer writes>) or {file./path/to/secret}.';
+
+/** A subdirective whose whole name says "my argument is the secret". `*_file` never matches. */
+const SECRET_WORD =
+  /^(?:token|api_token|auth_token|access_token|secret|client_secret|shared_secret|secret_key|password|passwd|passphrase|api_key|apikey|private_key|mac_key|hmac_key)$/i;
+
+/** Directives whose second argument is a DNS provider's credential: `dns cloudflare <token>`. */
+const DNS_DIRECTIVE = /^(?:dns|acme_dns)$/;
+
+const HEADER_DIRECTIVE = /^(?:header|header_up|header_down|request_header)$/;
+const CREDENTIAL_HEADER =
+  /^[+-]?(?:authorization|proxy-authorization|cookie|x-api-key|api-key|x-auth-token|x-vault-token)$/i;
+
+/** Shapes that are a credential wherever they appear. The label is what the refusal says. */
+const SHAPES: readonly (readonly [RegExp, string])[] = [
+  [/^(?:gh[pousr]_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{20,})$/, 'a GitHub token'],
+  [/^(?:AKIA|ASIA)[0-9A-Z]{16}$/, 'an AWS access key id'],
+  [/^xox[abposr]-[A-Za-z0-9-]{10,}$/, 'a Slack token'],
+  [/^sk-(?:ant-|proj-)?[A-Za-z0-9_-]{20,}$/, 'an API secret key'],
+  [/^eyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}$/, 'a JWT'],
+  // ★ basic_auth replaces placeholders in the hash at provision time (caddyauth/basicauth.go
+  //   Provision), so `{env.ADMIN_HASH}` works and a literal hash never needs to be declared.
+  [/^\$2[abxy]?\$\d{2}\$[./A-Za-z0-9]{53}$/, 'a bcrypt password hash'],
+  [/^\$argon2(?:id|i|d)\$/, 'an argon2 password hash'],
+];
+
+const PLACEHOLDER = /\{[^{}\s]+\}/g;
+const AUTH_SCHEME = /^(?:bearer|basic|token|digest)$/i;
+
+/**
+ * ⛔ `{$NAME:default}` IS A LITERAL. Caddy splices the default in at ADAPT time whenever NAME is
+ *   unset (caddyfile/parse.go replaceEnvVars: SplitN on `:`), so a secret typed as the default is
+ *   in the prop, the state and the adapted JSON. MEASURED 2026-09-21 on a throwaway Caddy 2.11.4:
+ *   `respond "{$UNSET:literal-default}"` adapted to the body `literal-default`. So each line is
+ *   checked as Caddy sees it with every such variable unset. The RUNTIME replacer has no default
+ *   syntax (replacer.go looks the whole key up), so `{env.X}` stays the safe form.
+ */
+const ENV_DEFAULT = /\{\$[^{}\s:]*:([^}]*)\}/g;
+const withDefaults = (line: string): string => line.replace(ENV_DEFAULT, '$1');
+
+/** One line's tokens: whitespace-separated, "double-quoted" and `backquoted` kept whole, # comments dropped. */
+export const tokensOf = (line: string): string[] => {
+  const tokens: string[] = [];
+  let current = '';
+  let quote: string | undefined;
+  for (let index = 0; index < line.length; index += 1) {
+    const char = line[index] ?? '';
+    if (quote !== undefined) {
+      if (char === '\\' && quote === '"' && index + 1 < line.length) {
+        index += 1;
+        current += line[index] ?? '';
+      } else if (char === quote) quote = undefined;
+      else current += char;
+    } else if (char === '"' || char === '`') {
+      quote = char;
+    } else if (/\s/.test(char)) {
+      if (current !== '') tokens.push(current);
+      current = '';
+    } else if (char === '#' && current === '') {
+      break; // a comment starts only at the beginning of a token (caddyfile lexer)
+    } else current += char;
+  }
+  if (current !== '') tokens.push(current);
+  return tokens;
+};
+
+/**
+ * True when nothing but placeholders (and an auth scheme word) is left of these tokens.
+ * ⚠️ A bare `{` / `}` is a block brace, not a value: `dns cloudflare {` opens a block whose
+ *   `api_token` line is checked on its own.
+ */
+const placeholderOnly = (tokens: readonly string[]): boolean =>
+  tokens
+    .flatMap((token) => token.replace(PLACEHOLDER, ' ').split(/\s+/))
+    .filter((part) => part !== '' && part !== '{' && part !== '}' && !AUTH_SCHEME.test(part))
+    .length === 0;
+
+const lineProblems = (tokens: readonly string[], where: string): string[] => {
+  const [first = '', second] = tokens;
+  const found: string[] = [];
+  if (SECRET_WORD.test(first) && tokens.length > 1 && !placeholderOnly(tokens.slice(1))) {
+    found.push(`${where}: \`${first}\` has a literal value`);
+  }
+  if (DNS_DIRECTIVE.test(first) && tokens.length > 2 && !placeholderOnly(tokens.slice(2))) {
+    found.push(`${where}: \`${first} ${second ?? ''}\` has a literal credential`);
+  }
+  if (HEADER_DIRECTIVE.test(first)) {
+    const at = tokens.findIndex((token, index) => index > 0 && CREDENTIAL_HEADER.test(token));
+    if (at !== -1 && tokens.length > at + 1 && !placeholderOnly(tokens.slice(at + 1))) {
+      found.push(`${where}: \`${first} ${tokens[at] ?? ''}\` sets a literal credential`);
+    }
+  }
+  for (const token of tokens) {
+    const shape = SHAPES.find(([pattern]) => pattern.test(token));
+    // ⛔ Never echo the token: if it IS a secret, the refusal would print it.
+    if (shape !== undefined) found.push(`${where}: holds what looks like ${shape[1]}`);
+  }
+  return found;
+};
+
+/** Refusals for a Caddyfile's text. Empty means nothing tripped. */
+export const caddyfileSecretProblems = (caddyfile: string): string[] => {
+  const found: string[] = [];
+  if (PRIVATE_KEY.test(caddyfile)) found.push('the Caddyfile holds a PEM private key');
+  for (const [index, line] of caddyfile.split('\n').entries()) {
+    found.push(...lineProblems(tokensOf(withDefaults(line)), `line ${String(index + 1)}`));
+  }
+  return found.map((problem) => `${problem}: ${ALTERNATIVE}`);
+};

package/src/caddy/config-form.ts

@@ -0,0 +1,64 @@
+/**
+ * CaddyConfig's props, attributes and validation — the pure half of the provider.
+ *
+ * ⛔ `caddyfile` IS NEVER A SECRET. Alchemy stores props unencrypted, so the whole Caddyfile sits in
+ *   the state store and in every plan diff. Secrets reach Caddy as runtime placeholders
+ *   (`{env.NAME}`, `{file./path}`) resolved from files a secret renderer writes — see
+ *   caddyfile-tripwire.ts, which refuses the obvious literals.
+ */
+import { caddyfileSecretProblems } from './caddyfile-tripwire.ts';
+
+export interface CaddyConfigProps {
+  /**
+   * The whole Caddyfile. Applied with `POST /load` (Content-Type `text/caddyfile`); it REPLACES the
+   * running config. ⛔ Never a secret. ⚠️ `import` paths resolve against Caddy's working directory
+   * (the API adapts with no file name), so keep them absolute.
+   */
+  caddyfile: string;
+  /**
+   * The file Caddy was started with (`caddy run --config <this>`), when the same Caddyfile is also
+   * written there — `caddyWithFile()` sets it from its HostFile. Sent as
+   * `Caddy-Config-Source-File` so a load keeps Caddy's SIGUSR1 reload-from-file working.
+   */
+  sourceFile?: string;
+}
+
+export interface CaddyConfigAttributes {
+  /**
+   * SHA-256 of the ADAPTED JSON Caddy reported after the last apply (digest.ts canonical form) —
+   * never the config itself. Drift is the live config hashing to anything else.
+   */
+  configSha256: string;
+  /** The admin endpoint the config was applied through (no credential; the API has none). */
+  endpoint: string;
+  /** The `sourceFile` prop as applied. */
+  sourceFile?: string;
+}
+
+const absoluteNormalised = (path: string): boolean =>
+  path.startsWith('/') &&
+  !path.endsWith('/') &&
+  !path.includes('\x00') &&
+  !path
+    .split('/')
+    .slice(1)
+    .some((part) => part === '' || part === '.' || part === '..');
+
+export const configProblems = (props: CaddyConfigProps): string[] => {
+  const found: string[] = [];
+  /**
+   * ⛔ AN EMPTY CADDYFILE IS NOT "NOTHING TO DO". It adapts to a config with no apps, and loading
+   *   it stops every server Caddy runs — every site down, on a templating bug that rendered ''.
+   *   Emptying Caddy is a deliberate act for a person at the admin API, not a declaration.
+   *   Text that is not empty but serves nothing (only comments, only global options) is caught
+   *   after `/adapt`, where it shows as no apps (config-lifecycle.ts servesNothing).
+   */
+  if (props.caddyfile.trim() === '') {
+    found.push('caddyfile is empty — loading it would stop every site Caddy serves');
+  }
+  if (props.sourceFile !== undefined && !absoluteNormalised(props.sourceFile)) {
+    found.push('sourceFile must be an absolute, normalised path');
+  }
+  found.push(...caddyfileSecretProblems(props.caddyfile));
+  return found;
+};