@homeflare/alchemy 0.51.0 → 0.52.0

package/src/linux/container-env-oracle.ts

@@ -0,0 +1,109 @@
+/**
+ * The `Environment=` oracle — a PORT of the three parsers a declared env value crosses, from
+ * `Environment=` line to what the container actually receives. The quadlet half (read, re-emit)
+ * is container-env-quadlet-oracle.ts; this file holds the SYSTEMD half — the `%` and `$` folds —
+ * and the composed chain. Every rule was MEASURED, not inferred (live podman 5.4.2
+ * `podman-system-generator --dryrun`, and a live systemd 257 unit start, 2026-10-11/12):
+ *
+ *   3. systemd parses the generated `ExecStart=` with the same splitter, then folds BOTH
+ *      expansion syntaxes: `%%` → one literal `%`, every other `%x` consumed as a specifier (an
+ *      unknown one invalidates the unit — systemd.unit(5) §Specifiers); and the `$` rules of
+ *      systemd.service(5) §Command lines (v257), measured against a live unit: `$$` → one literal
+ *      `$`; `${NAME}` "erased and replaced by the exact value of the environment variable" —
+ *      modelled here as UNSET, so recorded in `consumed` and replaced with the empty string — and
+ *      any other `$` mid-word stays literal, because unbraced expansion applies only to a word
+ *      that is EXACTLY `$FOO`, which a `KEY=value` word never is. An unterminated `${` stays
+ *      literal too (measured: `x${UNCLOSED` arrived intact). The generated ExecStart has no `:`
+ *      prefix, so variable substitution always applies. Measured end to end: the UNQUOTED
+ *      renderer's `pa$$word` arrives as `pa$word` (halved) and its `a${HOME}b` as `ab` (erased),
+ *      while the quoted-and-escaped forms of the same values arrive intact.
+ *
+ * ★ `consumed` IS THE FAILURE SIGNAL — a non-empty list means a `%x` or `${NAME}` the renderer let
+ *   through as data was eaten downstream, so the declared value did not survive (expanded away, or
+ *   the unit invalidated). The live unit also logged
+ *   `Referenced but unset environment variable evaluates to an empty string` for every `${NAME}`
+ *   — the host-side tell, in `journalctl`, if one ever escapes the renderer at deploy time.
+ * ⚠️ WHY A PORT, NOT THE REAL PARSERS: the real generator runs root-side per host, and starting a
+ *   unit IS a deploy — neither can be a unit test's dependency. The port lets every renderer
+ *   change replay the measured bytes in CI; container-env-live.test.ts re-validates the port
+ *   against the REAL generator wherever podman is installed, so port and pins stay honest.
+ */
+import { quadletEnvArgs, splitWords } from './container-env-quadlet-oracle.ts';
+
+/**
+ * Parser 3's `%` rules: `%%` folds to one literal `%`; every other `%x` is a specifier systemd
+ * consumes, so it is recorded — a non-empty record means the declared value did not survive
+ * (expanded away, or the unit invalidated).
+ */
+const foldSpecifiers = (text: string): { text: string; consumed: string[] } => {
+  const consumed: string[] = [];
+  const folded = text.replace(/%(.)/g, (_all, c: string) => {
+    if (c === '%') return '%';
+    consumed.push(`%${c}`);
+    return '';
+  });
+  return { text: folded, consumed };
+};
+
+/**
+ * Parser 3's `$` rules, left-to-right in ONE scan — a fold that ran two passes could not tell
+ * `pa$$$$word` (the escaped `pa$$word`) from anything else. systemd.service(5) §Command lines
+ * (v257), measured against a live unit: `$$` → one literal `$`; `${NAME}` → its value (unset →
+ * empty, recorded); any other `$` mid-word stays literal — unbraced expansion applies only to a
+ * word that is EXACTLY `$FOO`, and this oracle only ever folds `KEY=value` words.
+ */
+const foldDollars = (text: string): { text: string; consumed: string[] } => {
+  const consumed: string[] = [];
+  let out = '';
+  let i = 0;
+  while (i < text.length) {
+    const c = text.charAt(i);
+    if (c !== '$') {
+      out += c;
+      i++;
+      continue;
+    }
+    const next = text.charAt(i + 1);
+    if (next === '$') {
+      out += '$';
+      i += 2;
+      continue;
+    }
+    if (next === '{') {
+      const end = text.indexOf('}', i + 2);
+      if (end === -1) {
+        out += text.slice(i);
+        break;
+      }
+      consumed.push(text.slice(i, end + 1));
+      i = end + 1;
+      continue;
+    }
+    out += '$';
+    i++;
+  }
+  return { text: out, consumed };
+};
+
+/** Parser 3: what a `--env`-shaped ExecStart word becomes at the container — both folds applied. */
+const deployArgs = (
+  args: readonly string[],
+): { env: Record<string, string>; consumed: string[] } => {
+  const env: Record<string, string> = {};
+  const consumed: string[] = [];
+  for (const arg of args) {
+    const word = splitWords(arg)?.[0];
+    if (word === undefined) continue;
+    const specifiers = foldSpecifiers(word);
+    const dollars = foldDollars(specifiers.text);
+    consumed.push(...specifiers.consumed, ...dollars.consumed);
+    const eq = dollars.text.indexOf('=');
+    if (eq > 0) env[dollars.text.slice(0, eq)] = dollars.text.slice(eq + 1);
+  }
+  return { env, consumed };
+};
+
+/** The whole chain over rendered `Environment=` lines → what the container actually receives. */
+export const deployed = (
+  lines: readonly string[],
+): { env: Record<string, string>; consumed: string[] } => deployArgs(quadletEnvArgs(lines));

package/src/linux/container-env-quadlet-oracle.ts

@@ -0,0 +1,174 @@
+/**
+ * The QUADLET half of the `Environment=` oracle — how podman reads an `Environment=` line and
+ * re-emits it as `--env` arguments of the generated unit's `ExecStart=`. The systemd half (the
+ * `$`/`%` folds) and the composed chain live in container-env-oracle.ts, whose header carries
+ * the three-parser overview; every rule below was MEASURED against the live podman 5.4.2
+ * generator (2026-10-11/12), not inferred.
+ *
+ *   1. quadlet reads the line's value with systemd's own splitter (pkg/systemd/parser/unitfile.go
+ *      `LookupAllKeyVal` → `splitString(value, " \t\n\r", SplitRelax | SplitUnquote |
+ *      SplitCUnescape)`, podman v5.4.0). Measured: an unquoted space ends the assignment there
+ *      (`ROLE_ATTRIBUTE_PATH` was truncated at its first space); quoted fragments are unquoted
+ *      and re-parsed (`'cn=admins,ou=people')` became the bogus variable `cn`); words without
+ *      `=` are silently skipped; an unknown C escape (`\d`) drops EVERY assignment of that line,
+ *      silently.
+ *   2. quadlet re-emits each assignment as one `--env` argument (podman `addEnv` → `AddCmdline` →
+ *      `escapeWords`, pkg/systemd/parser/split.go v5.4.2): re-escaped, and wrapped in double quotes
+ *      iff ANY character needs escape — `wordNeedEscape`'s set: whitespace, control characters,
+ *      `"`, `'` and `\` — never touching `%` or `$`, which pass through verbatim. Measured:
+ *      `Environment="D=pa$$$$word"` → `--env D=pa$$$$word`, and the single quotes in Grafana's
+ *      role path stayed literal inside the double-quoted `--env "…'Admin'…"`.
+ */
+
+/**
+ * Parsers 1+2 composed: the assignments quadlet reads out of rendered `Environment=` lines, then
+ * the `--env` arguments it emits for them. Exported for container-env-live.test.ts, which replays
+ * this against the REAL generator wherever one is installed.
+ */
+export const quadletEnvArgs = (lines: readonly string[]): string[] => {
+  const told: Record<string, string> = {};
+  for (const line of lines) {
+    const words = splitWords(line.slice('Environment='.length));
+    if (words !== undefined) Object.assign(told, parseAssignments(words));
+  }
+  return emitPodmanArgs(told);
+};
+
+/** Podman's own separator set — `WhitespaceSeparators = " \t\n\r"` (split.go v5.4.2), NOT the
+ *  fuller C-locale whitespace: a raw `\f` or `\v` is a word character to quadlet, not a break. */
+const WHITESPACE = ' \t\n\r';
+
+const C_UNESCAPES: Record<string, string> = {
+  a: '\x07',
+  b: '\b',
+  f: '\f',
+  n: '\n',
+  r: '\r',
+  t: '\t',
+  v: '\v',
+  '\\': '\\',
+  '"': '"',
+  "'": "'",
+  0: '\0',
+};
+
+/**
+ * Parser 1: systemd's `splitString(value, WhitespaceSeparators, SplitRelax | SplitUnquote |
+ * SplitCUnescape)`. Returns the words, or `undefined` when the split FAILS — which is what turns
+ * into "every assignment on this line silently dropped" (measured, see header). Quotes are
+ * stripped and their content kept; `\xNN` is unescaped like the simple table.
+ */
+export const splitWords = (value: string): string[] | undefined => {
+  const words: string[] = [];
+  let word = '';
+  let quote: '"' | "'" | undefined;
+  let i = 0;
+  let started = false;
+  while (i < value.length) {
+    const c = value.charAt(i);
+    if (quote === undefined && WHITESPACE.includes(c)) {
+      if (started) words.push(word);
+      word = '';
+      started = false;
+      i++;
+      continue;
+    }
+    if (c === '\\') {
+      // CUNESCAPE applies inside and outside quotes; an unknown escape fails the whole split.
+      const next = value[i + 1];
+      if (next === undefined) return undefined;
+      if (next === 'x' && /^[0-9a-fA-F]{2}/.test(value.slice(i + 2, i + 4))) {
+        word += String.fromCharCode(parseInt(value.slice(i + 2, i + 4), 16));
+        i += 4;
+        started = true;
+        continue;
+      }
+      const unescaped = C_UNESCAPES[next];
+      if (unescaped === undefined) return undefined;
+      word += unescaped;
+      started = true;
+      i += 2;
+      continue;
+    }
+    if (c === '"' || c === "'") {
+      if (quote === c) quote = undefined;
+      else if (quote === undefined) {
+        quote = c;
+        started = true;
+      } else word += c;
+      i++;
+      continue;
+    }
+    word += c;
+    started = true;
+    i++;
+  }
+  if (started) words.push(word);
+  return words;
+};
+
+/** A word without `=` is not an assignment — measured: silently skipped, never an error. */
+export const parseAssignments = (words: readonly string[]): Record<string, string> => {
+  const env: Record<string, string> = {};
+  for (const word of words) {
+    const eq = word.indexOf('=');
+    if (eq <= 0) continue;
+    env[word.slice(0, eq)] = word.slice(eq + 1);
+  }
+  return env;
+};
+
+/**
+ * `wordNeedEscape`'s set, ported from podman pkg/systemd/parser/split.go (v5.4.2): a character
+ * forces quoting iff it is ASCII whitespace or control (`<= 0x20` or `0x7f`), a double or single
+ * quote, or a backslash — "unicode is ok" is the source's own comment, so anything above `0x80`
+ * passes. ⚠️ Note the SINGLE quote: podman quotes a word containing one even though escaping
+ * leaves it literal — a port that only quotes what escaping CHANGES would drift from the real
+ * `--env` bytes for values like `it's`.
+ */
+const needEscape = (word: string): boolean => {
+  for (const c of word) {
+    const code = c.charCodeAt(0);
+    if (code > 128) continue;
+    if (code <= 0x20 || code === 0x7f || c === '"' || c === "'" || c === '\\') return true;
+  }
+  return false;
+};
+
+/** `escapeString`'s table (same source): podman re-escapes the C control codes and `"`/`\`
+ *  inside the double quotes it adds, and writes a literal space and `'` — safe inside `"`. */
+const REESCAPES: Record<string, string> = {
+  '\x07': '\\a',
+  '\b': '\\b',
+  '\f': '\\f',
+  '\n': '\\n',
+  '\r': '\\r',
+  '\t': '\\t',
+  '\v': '\\v',
+  '\\': '\\\\',
+  '"': '\\"',
+  "'": "'",
+  ' ': ' ',
+};
+
+/** Parser 2: re-emit as one `--env` argument — escaped, and quoted iff any character needs it.
+ *  ⚠️ KEYS SORTED, NOT INSERTION-ORDERED: podman's `addEnv` → `addKeys` collects the map's keys
+ *  and `sort.Strings`s them before emitting (pkg/systemd/quadlet/podmancmdline.go, v5.4.2), so
+ *  the generated ExecStart holds the assignments sorted by key whatever order the file declared
+ *  them in — measured: a file declaring DOLLAR2, TRUNC, DOLLARBRACE emitted DOLLAR2, DOLLARBRACE,
+ *  TRUNC. The sort here compares UTF-16 code units like the renderer's own; for the ASCII env
+ *  key names in play it is Go's byte order exactly. */
+export const emitPodmanArgs = (env: Readonly<Record<string, string>>): string[] =>
+  Object.entries(env)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([key, value]) => {
+      const word = `${key}=${value}`;
+      if (!needEscape(word)) return word;
+      let escaped = '"';
+      for (const c of word) {
+        const known = c.charCodeAt(0) <= 128 ? REESCAPES[c] : undefined;
+        escaped +=
+          known ?? (needEscape(c) ? `\\x${c.charCodeAt(0).toString(16).padStart(2, '0')}` : c);
+      }
+      return `${escaped}"`;
+    });

package/src/linux/container-env-quote.test.ts

@@ -0,0 +1,131 @@
+/**
+ * The TEXT-level contract of the `Environment=` renderer: what `quoteEnvironmentValue` /
+ * `environmentLines` emit, that newlines are refused rather than encoded, and that
+ * `renderContainerFile` places the quoted block where the unquoted renderer had it.
+ *
+ * ⛔ Every expected string below was accepted by the LIVE podman 5.4.2 system generator (measured
+ *   2026-10-11/12, artifacts in /tmp/opencode/quadlet-quote/): the generator read each quoted line
+ *   as exactly ONE assignment. What those bytes BECOME through quadlet's splitter, podman's
+ *   re-emission and systemd's ExecStart parsing is the parser-level proof —
+ *   container-env-chain.test.ts, which also shows the old unquoted renderer corrupting the same
+ *   values through the same chain.
+ */
+import { describe, expect, test } from 'bun:test';
+import {
+  QuadletEnvironmentValueError,
+  environmentLines,
+  environmentValueProblems,
+  quoteEnvironmentValue,
+} from './container-env-quote.ts';
+import { containerProblems, renderContainerFile } from './container-form.ts';
+
+// The real values this row exists for (homeflare-ct100 commit 53b84c1, grafana.container).
+const VAR = 'GF_AUTH_GENERIC_OAUTH_ROLE_ATTRIBUTE_PATH';
+const ROLE_PATH =
+  "(contains(groups[*], 'Admin') || contains(email, 'tim@schenanigans.com')) && 'GrafanaAdmin'";
+
+describe('the rendered text', () => {
+  test('the deployed Grafana expression, quoted whole', () => {
+    expect(environmentLines({ [VAR]: ROLE_PATH })).toEqual([
+      [
+        'Environment',
+        `"${VAR}=(contains(groups[*], 'Admin') || contains(email, ` +
+          `'tim@schenanigans.com')) && 'GrafanaAdmin'"`,
+      ],
+    ]);
+  });
+
+  test('escapes, quotes and percent signs, exactly as the generator accepted them', () => {
+    expect(
+      environmentLines({ BACKSLASH: 'C:\\path', PCT: '50%off', QUOTED: 'say "hi"' }).map(
+        ([key, value]) => `${key}=${value}`,
+      ),
+    ).toEqual([
+      String.raw`Environment="BACKSLASH=C:\\path"`,
+      String.raw`Environment="PCT=50%%off"`,
+      String.raw`Environment="QUOTED=say \"hi\""`,
+    ]);
+  });
+
+  test('dollar signs are doubled for systemd, exactly as the generator accepted them', () => {
+    // ⛔ THE PIN THE 2026-10-12 FIX ROUND ADDS: systemd.service(5) §Command lines (v257, measured
+    //   against a live unit) folds `$$` to one literal `$` and erases `${FOO}`, so a `$` left bare
+    //   is data the container never receives: `pa$$word` arrived as `pa$word`, `a${HOME}b` as `ab`.
+    expect(
+      // oxlint-disable-next-line no-template-curly-in-string -- the declared value under test, not a placeholder
+      environmentLines({ B: 'a${HOME}b', D: 'pa$$word' }).map(([key, value]) => `${key}=${value}`),
+    ).toEqual(
+      // oxlint-disable-next-line no-template-curly-in-string -- the measured bytes the renderer must emit
+      ['Environment="B=a$${HOME}b"', 'Environment="D=pa$$$$word"'],
+    );
+  });
+
+  test('keys are sorted, so the render is stable for an unordered plain object', () => {
+    expect(environmentLines({ B: '2', A: '1' })).toEqual([
+      ['Environment', '"A=1"'],
+      ['Environment', '"B=2"'],
+    ]);
+    expect(environmentLines({})).toEqual([]);
+  });
+});
+
+describe('newlines are refused, not encoded', () => {
+  test('a newline in a value is a typed error naming the key, never the value', () => {
+    expect(() => quoteEnvironmentValue('WEBHOOK_URL', 'https://x\nSECRET-TAIL')).toThrow(
+      QuadletEnvironmentValueError,
+    );
+    try {
+      quoteEnvironmentValue('WEBHOOK_URL', 'https://x\nSECRET-TAIL');
+    } catch (error) {
+      expect((error as QuadletEnvironmentValueError)._tag).toBe('QuadletEnvironmentValueError');
+      expect((error as QuadletEnvironmentValueError).key).toBe('WEBHOOK_URL');
+      const message = (error as QuadletEnvironmentValueError).message;
+      expect(message).toContain('WEBHOOK_URL');
+      expect(message).not.toContain('SECRET-TAIL');
+    }
+    expect(() => quoteEnvironmentValue('BAD\nKEY', 'value')).toThrow(QuadletEnvironmentValueError);
+  });
+
+  test('environmentValueProblems reports every refusal at once, as problem strings', () => {
+    expect(environmentValueProblems({ OK: 'fine', BAD: 'a\nb', WORSE: 'c\nd' })).toEqual([
+      expect.stringContaining('BAD'),
+      expect.stringContaining('WORSE'),
+    ]);
+    expect(environmentValueProblems({ OK: 'fine' })).toEqual([]);
+  });
+
+  test('containerProblems reports the refusal, never throwing past the plan', () => {
+    // The plan-time surface: a newline value must not abort `containerProblems` (a caller
+    // building a plan needs every refusal at once), and the string it gets back is the rule
+    // text — enough to locate the prop, never the value.
+    const problems = containerProblems({
+      name: 'grafana-primary',
+      container: { image: 'docker.io/library/alpine:3', environment: { BAD: 'a\nb' } },
+    });
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).toContain('environment key "BAD" contains a newline');
+  });
+});
+
+describe('renderContainerFile wires the quoting in — the whole file', () => {
+  const props = {
+    name: 'grafana-primary',
+    container: {
+      environmentFile: ['/etc/grafana-primary/env'],
+      environment: { [VAR]: ROLE_PATH, GF_AUTH_GENERIC_OAUTH_ROLE_ATTRIBUTE_STRICT: 'true' },
+      image: 'docker.io/grafana/grafana:12.2.1',
+      network: 'host',
+    },
+  };
+
+  test('the Environment= block is quoted, still sorted, still after EnvironmentFile=', () => {
+    const lines = renderContainerFile(props).split('\n');
+    const envBlock = lines.filter((line) => line.startsWith('Environment='));
+    expect(envBlock).toEqual(
+      environmentLines(props.container.environment).map(([key, value]) => `${key}=${value}`),
+    );
+    expect(lines.indexOf(envBlock[0] ?? '')).toBeGreaterThan(
+      lines.indexOf('EnvironmentFile=/etc/grafana-primary/env'),
+    );
+  });
+});

package/src/linux/container-env-quote.ts

@@ -0,0 +1,126 @@
+/**
+ * The `[Container]` `Environment=` value renderer — the one place a declared env var crosses THREE
+ * parsers between `container.environment` and the container's own environment, each able to mangle
+ * a value the props held intact:
+ *
+ *   1. Quadlet's generator reads the raw line value with systemd's exec-like splitter:
+ *      `pkg/systemd/parser/unitfile.go` `LookupAllKeyVal` calls `splitString(value,
+ *      WhitespaceSeparators, SplitRelax | SplitUnquote | SplitCUnescape)` (podman v5.4.0). An
+ *      unquoted space ENDS the assignment there; a quote starts/ends a quoted region wherever it
+ *      sits; C-escapes are processed; and an unsupported escape (`\d` in a regex, say) fails the
+ *      split — `LookupAllKeyVal` then drops EVERY assignment of that line, silently.
+ *   2. Quadlet re-emits each assignment as `--env KEY=value` arguments of the generated unit's
+ *      `ExecStart=` (`podman.addEnv` → `AddCmdline` → `escapeWords`, same source), re-quoting for
+ *      the next parser but never touching `%` or `$` — both pass through verbatim.
+ *   3. systemd parses that `ExecStart=` and expands BOTH syntaxes there. `%`: `%%` folds to one
+ *      literal `%` and an unknown `%x` makes the setting invalid ("Specifiers must be known and
+ *      resolvable for the setting to be valid", systemd.unit(5) §Specifiers). `$`
+ *      (systemd.service(5) §Command lines, v257): the generated ExecStart has no `:` prefix, so
+ *      variables are always substituted — `${FOO}` is "erased and replaced by the exact value of
+ *      the environment variable", "to pass a literal dollar sign, use "$$"", and a bare `$` in
+ *      the middle of a word stays literal (unbraced expansion applies only to a whole `$FOO`
+ *      word, which a `KEY=value` word never is). So `pa$$word` arrives halved as `pa$word` and
+ *      `a${HOME}b` arrives as `ab` — the variable is resolved from the UNIT's environment, not
+ *      the one this file declares.
+ *
+ * ⛔ MEASURED 2026-10-11 (ice2/grafana-oidc.md; reproduced locally with the real podman 5.4.2
+ *   generator): the previous renderer emitted `Environment=KEY=value` UNQUOTED, so Grafana's
+ *   `ROLE_ATTRIBUTE_PATH=contains(groups[*], '…')` reached the container as
+ *   `ROLE_ATTRIBUTE_PATH=contains(groups[*],` — split at the first space — plus a bogus `--env
+ *   cn=…` variable, and every login failed `role_attribute_strict_violation`.
+ * ⛔ MEASURED 2026-10-12 (same generator dry run, plus a live systemd 257 unit): escaping `\`, `"`,
+ *   `%` and `$` is what survives all three parsers. `Environment="KEY=a b"` generates `--env
+ *   "KEY=a b"`; `Environment="D=pa$$$$word"` generates `--env D=pa$$$$word` and
+ *   `Environment="B=a$${HOME}b"` generates `--env B=a$${HOME}b` — podman passes `$` through
+ *   untouched — and the live unit folded them back to `pa$$word` and `a${HOME}b`, exactly the
+ *   declared values, while the same values UNQUOTED arrived as `pa$word` and `ab`.
+ * ⛔ NEWLINES ARE REFUSED, NOT ENCODED — a raw newline in a key or value breaks the LINE the whole
+ *   format is built on: quadlet reads the file line by line, so the assignment ends mid-value and
+ *   anything after the newline is parsed as a NEW directive (attacker-controllable key injection
+ *   when a value comes from external config). The refusal is a typed error so a caller can catch
+ *   it by tag; `containerProblems` (container-form.ts) turns it into a problem string so one plan
+ *   still shows every refusal at once.
+ */
+import * as Data from 'effect/Data';
+
+/** Same shape as container-form.ts's `UnitLine` — structural, so this module imports nothing back. */
+export type EnvironmentLine = readonly [key: string, value: string];
+
+/** The shared rule text — the typed error's message and the problem string are the same sentence. */
+const environmentValueProblem = (key: string): string =>
+  `environment key ${JSON.stringify(key)} contains a newline; a .container file is line-based, ` +
+  'so quadlet would end the assignment mid-value and parse whatever follows as a new directive. ' +
+  'Nothing was written.';
+
+/**
+ * ⛔ CARRIES THE KEY AND THE RULE, NEVER THE VALUE — an error is logged, retried and pasted into a
+ * PR, and a newline-containing value may be arbitrarily large or semi-secret; the key name (which
+ * `secretLikeEnvironment` already names in its own messages) is enough to locate the prop.
+ */
+export class QuadletEnvironmentValueError extends Data.TaggedError('QuadletEnvironmentValueError')<{
+  readonly key: string;
+}> {
+  override get message(): string {
+    return environmentValueProblem(this.key);
+  }
+}
+
+/**
+ * `Environment="KEY=value"` — the whole assignment double-quoted, with `\`, `"`, `%` and `$`
+ * escaped (in that order, over the joined `KEY=value`), so the wrapping quotes this function adds
+ * can never be confused with quotes the value contained, every `%` reaches systemd's specifier
+ * expansion as the documented `%%` literal instead of an unknown `%x` that invalidates the unit,
+ * and every `$` reaches it as `$$` — the documented literal-dollar escape (systemd.service(5)
+ * §Command lines) — instead of a `${FOO}` systemd would erase and replace with a variable of ITS
+ * choosing, or a `$$` it would fold and halve.
+ */
+export const quoteEnvironmentValue = (key: string, value: string): string => {
+  if (key.includes('\n') || value.includes('\n')) throw new QuadletEnvironmentValueError({ key });
+  // ⛔ THE `$` REPLACEMENT MUST BE A FUNCTION — measured 2026-10-12: `replaceAll`'s replacement
+  //   STRING runs its own `$`-pattern mini-language (same fold as systemd: `$$` in it IS one
+  //   literal `$`, and `$&` is the match), so a plain `'$$'` replacement silently no-ops and the
+  //   value ships bare. A function's return value is inserted verbatim, no patterns read.
+  //   The earlier `\`, `"` and `%` replacements keep string form: only `$` starts a pattern.
+  return `"${`${key}=${value}`
+    .replaceAll('\\', '\\\\')
+    .replaceAll('"', '\\"')
+    .replaceAll('%', '%%')
+    .replaceAll('$', () => '$$')}"`;
+};
+
+/**
+ * The sorted, quoted `Environment=` lines of a `[Container]` section — spliced by container-form.ts
+ * between `EnvironmentFile=` and `Volume=`, exactly where the unquoted renderer emitted them, so
+ * the render ORDER does not change (only the bytes of the Environment lines themselves do).
+ */
+export const environmentLines = (
+  environment: Readonly<Record<string, string>>,
+): readonly EnvironmentLine[] =>
+  // ★ Object.entries, not keys+index: under noUncheckedIndexedAccess an indexed read is
+  //   `string | undefined`, and the sort below reproduces the old `keys().sort()` order exactly
+  //   (both compare UTF-16 code units), so the render order does not change.
+  Object.entries(environment)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([key, value]): EnvironmentLine => ['Environment', quoteEnvironmentValue(key, value)]);
+
+/**
+ * The newline refusal as problem STRINGS (containerProblems' currency), so one plan still shows the
+ * whole list instead of aborting on the first newline — the typed error above stays the contract
+ * for anyone rendering directly.
+ */
+export const environmentValueProblems = (
+  environment: Readonly<Record<string, string>>,
+): string[] => {
+  const found: string[] = [];
+  for (const [key, value] of Object.entries(environment).sort(([a], [b]) =>
+    a < b ? -1 : a > b ? 1 : 0,
+  )) {
+    try {
+      quoteEnvironmentValue(key, value);
+    } catch (error) {
+      if (!(error instanceof QuadletEnvironmentValueError)) throw error;
+      found.push(environmentValueProblem(key));
+    }
+  }
+  return found;
+};

package/src/linux/container-fixture.test.ts

@@ -66,7 +66,9 @@ test('renders every directive CT100’s live caddy.container carries', () => {
     'ContainerName=caddy',
     'Network=host',
     'EnvironmentFile=/etc/caddy/cf-token.env',
-    'Environment=CADDY_CONFIG=/etc/caddy/Caddyfile',
+    // ⛔ Quoted, like every Environment= value now (container-env-quote.ts) — the caddy value has
+    //   no spaces, but uniform quoting is the rule; container-env-quote.test.ts has the story.
+    'Environment="CADDY_CONFIG=/etc/caddy/Caddyfile"',
     'Volume=/etc/caddy/Caddyfile:/etc/caddy/Caddyfile:ro,Z',
     'Volume=/etc/caddy/rendered:/etc/caddy/rendered:ro,Z',
     'Volume=/etc/caddy/cf-token.env:/run/cf/token.env:ro',