@homeflare/alchemy 0.37.7 → 0.37.8

package/src/linux/sudo-exec.ts

@@ -23,13 +23,44 @@
  *   is a valid type in `unit-form.ts`'s `TYPES` set) would also have elevated. Grepped: no code
  *   in this package ever calls `enable`/`start`/`restart` on a unit it has not itself just
  *   written a file for, so narrowing the exemption to `stop`/`disable` costs nothing legitimate.
+ * 🔴 MEASURED, CT100 deploy 2026-09-26 00:11Z: a THIRD gap, this one refusing a call that should
+ *   have been allowed. `Podman.Container caddy`'s generated `caddy.service` has
+ *   `FragmentPath=/run/systemd/generator/caddy.service` — Quadlet's generator output, never a
+ *   path this runner would ever declare as a prefix (nothing writes there directly) — so `restart`
+ *   was refused outright, even though the `.container` FILE THAT GENERATED IT lives at
+ *   `/etc/containers/systemd/caddy.container`, squarely under this runner's own
+ *   `/etc/containers/systemd` prefix, and this SAME runner had just written it. `SourcePath` is
+ *   the generator's own record of that file (systemctl.ts's header, MEASURED on CT100). So a
+ *   generated unit is now also reachable when its `FragmentPath` is the generator's OWN output
+ *   directory (`GENERATOR_DIRECTORIES` below) AND its `SourcePath` is under a declared prefix —
+ *   the thing this runner actually owns is the `.container` file, and the generated unit is
+ *   systemd's own derivative of it, not a foreign unit. Everything the check refused before still
+ *   refuses: a vendor unit's `FragmentPath` (`/usr/lib/systemd/system/...`) is not under a
+ *   generator directory at all; a generated unit with no `SourcePath`, or one outside every
+ *   prefix (a `.container` file elsewhere in Quadlet's OWN search path —
+ *   `podman-systemd.unit(5)` — that this runner was never told to own), still refuses.
  */
 import type { ExecResult, HostRunner } from '../launchd/runner.ts';
+import { GENERATED_UNIT_DIRECTORY } from './container-generator.ts';
 import { SYSTEMCTL_ABS, SudoRefusedError, canonicalize, prefixOf } from './sudo-allowlist.ts';
 import { type ChainExpect, assertGuardedChain } from './sudo-guard.ts';
 import type { Elevate } from './sudo-write.ts';
 import { parseShow } from './systemctl.ts';
 
+/**
+ * ★ ONLY THE `.late` VARIANT ADDED — `container-generator.ts`'s own header names it as part of
+ *   systemd's real Unit File Load Path; `.early` is not named anywhere in this repo and no
+ *   generator this family drives (Quadlet writes only the base directory) uses it, so it stays
+ *   out rather than widen the check on an unmeasured guess.
+ */
+const GENERATOR_DIRECTORIES: readonly string[] = [
+  GENERATED_UNIT_DIRECTORY,
+  `${GENERATED_UNIT_DIRECTORY}.late`,
+];
+
+const isUnderGeneratorDirectory = (fragmentPath: string): boolean =>
+  GENERATOR_DIRECTORIES.some((dir) => fragmentPath.startsWith(`${dir}/`));
+
 const DIR_EXPECT: Readonly<Record<string, ChainExpect>> = {
   chmod: 'directory',
   chown: 'directory',
@@ -43,26 +74,33 @@ const EMPTY_FRAGMENT_OK: ReadonlySet<string> = new Set(['stop', 'disable']);
 const unitStatusOf = async (
   base: HostRunner,
   unit: string,
-): Promise<{ readonly fragmentPath: string; readonly loadState: string }> => {
+): Promise<{
+  readonly fragmentPath: string;
+  readonly loadState: string;
+  readonly sourcePath: string;
+}> => {
   const result = await base.exec([
     SYSTEMCTL_ABS,
     'show',
     '--no-pager',
     '-p',
-    'FragmentPath,LoadState',
+    // ★ SourcePath added for the Quadlet-generated-unit exception below — same property
+    //   systemctl.ts's own `showUnit` already reads for `Podman.Container`.
+    'FragmentPath,LoadState,SourcePath',
     '--',
     unit,
   ]);
   if (result.exitCode !== 0) {
     throw new SudoRefusedError(
-      `sshSudoRunner ${unit}: could not read FragmentPath/LoadState (systemctl show exit ` +
-        `${String(result.exitCode)}). Nothing ran as root.`,
+      `sshSudoRunner ${unit}: could not read FragmentPath/LoadState/SourcePath (systemctl show ` +
+        `exit ${String(result.exitCode)}). Nothing ran as root.`,
     );
   }
   const fields = parseShow(result.stdout);
   return {
     fragmentPath: fields.get('FragmentPath') ?? '',
     loadState: fields.get('LoadState') ?? '',
+    sourcePath: fields.get('SourcePath') ?? '',
   };
 };
 
@@ -93,7 +131,7 @@ export const elevatedExec = (
   const verb = canonical[1] ?? '';
   const unit = canonical[3] ?? '';
   return elevate(canonical, {}, async () => {
-    const { fragmentPath, loadState } = await unitStatusOf(base, unit);
+    const { fragmentPath, loadState, sourcePath } = await unitStatusOf(base, unit);
     if (loadState === 'masked') {
       throw new SudoRefusedError(
         `sshSudoRunner ${unit}: is masked. Masking is someone's decision, not drift; unmask it ` +
@@ -108,11 +146,23 @@ export const elevatedExec = (
           `${unit} is (a kernel-generated unit, say). Nothing ran as root.`,
       );
     }
-    if (prefixOf(fragmentPath, prefixes) === undefined) {
-      throw new SudoRefusedError(
-        `sshSudoRunner ${unit}: FragmentPath ${fragmentPath} is outside every declared prefix ` +
-          `(${prefixes.join(', ')}); refusing to touch a unit this runner does not own. Nothing ran as root.`,
-      );
+    if (prefixOf(fragmentPath, prefixes) !== undefined) return;
+    // ⛔ THE QUADLET CASE — see this file's header. A generator's OWN output directory is never a
+    //   prefix, so this is not "found it under a prefix, done" — it is "found it under the
+    //   generator, so check what GENERATED it instead."
+    if (
+      isUnderGeneratorDirectory(fragmentPath) &&
+      sourcePath !== '' &&
+      prefixOf(sourcePath, prefixes) !== undefined
+    ) {
+      return;
     }
+    const sourceNote =
+      sourcePath === '' ? '' : `, and its SourcePath ${sourcePath} is not under one either`;
+    throw new SudoRefusedError(
+      `sshSudoRunner ${unit}: FragmentPath ${fragmentPath} is outside every declared prefix ` +
+        `(${prefixes.join(', ')})${sourceNote}; refusing to touch a unit this runner does not ` +
+        'own. Nothing ran as root.',
+    );
   });
 };

package/src/linux/sudo-lifecycle.test.ts

@@ -1,15 +1,19 @@
 /**
- * `Systemd.Unit` and `Remote.File`'s own lifecycle functions, driven through sshSudoRunner over
- * the fake Linux host — proving the two families this runner exists for actually work end to end,
- * not just that the runner's own primitives do. No sudo runs anywhere but through the fake.
+ * `Systemd.Unit`, `Remote.File` and `Podman.Container`'s own lifecycle functions, driven through
+ * sshSudoRunner over the fake Linux host — proving the families this runner exists for actually
+ * work end to end, not just that the runner's own primitives do. No sudo runs anywhere but through
+ * the fake.
  */
 import { describe, expect, test } from 'bun:test';
+import { fakeQuadletHost } from './fake-quadlet.ts';
 import { fakeSudoHost } from './fake-sudo.ts';
 import { SudoRefusedError } from './sudo-runner.ts';
 import { deleteFile, reconcileFile } from './remote-file-lifecycle.ts';
 import type { RemoteFileProps } from './remote-file-form.ts';
 import { deleteUnit, diffUnit, reconcileUnit } from './unit-lifecycle.ts';
 import type { SystemdUnitProps } from './unit-form.ts';
+import { reconcileContainer } from './container-lifecycle.ts';
+import type { ContainerProps } from './container-form.ts';
 
 const UNIT: SystemdUnitProps = {
   name: 'hf-thing.service',
@@ -124,6 +128,63 @@ describe('Systemd.Unit through sshSudoRunner', () => {
   });
 });
 
+// 🔴 REGRESSION, CT100 deploy 2026-09-26 00:11Z: `Podman.Container caddy`'s generated unit's
+//   FragmentPath (`/run/systemd/generator/…`) was refused outright by the ownership check above,
+//   even though its SourcePath (`/etc/containers/systemd/caddy.container`) was this runner's own
+//   `.container` file, under a declared prefix. `fakeQuadletHost` in place of the plain
+//   `fakeLinuxHost` (via `fakeSudoHost`'s `hostFactory`) reproduces the exact CT100 shape: a
+//   generated unit whose FragmentPath is the generator's own output directory.
+const CADDY_PREFIXES = ['/etc/containers/systemd', '/etc/systemd/system'];
+const CADDY: ContainerProps = {
+  container: { image: 'docker.io/library/caddy:2', network: 'host' },
+  install: { wantedBy: ['multi-user.target'] },
+  name: 'caddy',
+  service: { restart: 'always' },
+};
+
+describe('Podman.Container through sshSudoRunner', () => {
+  test(
+    'a full reconcile writes, reloads and starts — the generated unit’s FragmentPath under ' +
+      'the generator is reachable because its SourcePath is under a declared prefix',
+    async () => {
+      const { privileged, runner } = fakeSudoHost({}, undefined, {
+        hostFactory: fakeQuadletHost,
+        prefixes: CADDY_PREFIXES,
+      });
+      const attrs = await reconcileContainer(runner, CADDY, undefined);
+      expect(attrs.active).toBe(true);
+      expect(attrs.sourcePath).toBe('/etc/containers/systemd/caddy.container');
+      const verbs = privileged()
+        .filter((c) => c[0] === '/usr/bin/systemctl')
+        .map((c) => c[1]);
+      expect(verbs).toContain('daemon-reload');
+      expect(verbs).toContain('start');
+    },
+  );
+
+  test('a generated unit whose SourcePath is outside every declared prefix still refuses', async () => {
+    const { fake, privileged, runner } = fakeSudoHost({}, undefined, {
+      hostFactory: fakeQuadletHost,
+      prefixes: CADDY_PREFIXES,
+    });
+    // A `.container` file Quadlet's OWN search path would also read (podman-systemd.unit(5)), but
+    // not under any prefix THIS runner declared — a foreign Quadlet source, same idea as the
+    // vendor `pveproxy.service` test above for a plain unit.
+    fake.files.set('/run/containers/systemd/other.container', {
+      bytes: new TextEncoder().encode('[Container]\nImage=example/other:1\n'),
+      gid: 0,
+      kind: 'file',
+      mode: 0o644,
+      uid: 0,
+    });
+    await runner.exec(['systemctl', 'daemon-reload']);
+    await expect(runner.exec(['systemctl', 'restart', '--', 'other.service'])).rejects.toThrow(
+      /SourcePath .* is not under one either/,
+    );
+    expect(privileged().some((c) => c[1] === 'restart')).toBe(false);
+  });
+});
+
 const SCRIPT: RemoteFileProps = {
   content: '#!/bin/sh\necho hi\n',
   mode: 0o755,

package/src/linux/unit-form.ts

@@ -12,8 +12,11 @@
  * ⛔ `content` IS NEVER A SECRET. Props sit unencrypted in Alchemy state and the unit file is
  *   world-readable at 0644; a unit that needs a secret takes `EnvironmentFile=` pointing at a file
  *   a secret renderer maintains.
+ * ★ THE TEXT-SHAPE CHECKS (comments/blank lines before [Section], [Install] key lookup) live in
+ *   `unit-text.ts`, split out to keep this file under the house line cap.
  */
 import { sha256Hex } from '../launchd/job-form.ts';
+import { hasInstallSection, textProblems } from './unit-text.ts';
 
 export type UnitSection = {
   /** `Unit`, `Service`, `Timer`, `Install`, … — verbatim, including its capitalisation. */
@@ -172,8 +175,6 @@ const TYPES = new Set([
   'timer',
 ]);
 
-const INSTALL_KEYS = new Set(['WantedBy', 'RequiredBy', 'UpsertedBy', 'Also', 'Alias']);
-
 /**
  * Every refusal at once, so one plan shows the whole list.
  * ⛔ THE TWO STRUCTURAL RULES, both proven by systemd's own output rather than assumed:
@@ -206,7 +207,7 @@ export const unitProblems = (props: SystemdUnitProps, expect?: string): string[]
         `${directory} is not one of them. Move it, or declare enabled: false.`,
     );
   }
-  if (props.enabled !== false && !hasInstall(props)) {
+  if (props.enabled !== false && !hasInstallSection(unitText(props))) {
     found.push(
       'enabled units need an [Install] section with WantedBy/RequiredBy/Also/Alias; without one ' +
         'systemd calls the unit "static" and `systemctl enable` has nothing to link. Add one, or ' +
@@ -218,18 +219,3 @@ export const unitProblems = (props: SystemdUnitProps, expect?: string): string[]
   }
   return found;
 };
-
-const hasInstall = (props: SystemdUnitProps): boolean => {
-  const text = unitText(props);
-  if (!text.includes('[Install]')) return false;
-  const after = text.slice(text.indexOf('[Install]'));
-  return [...INSTALL_KEYS].some((key) => new RegExp(`^${key}=`, 'm').test(after));
-};
-
-const textProblems = (text: string): string[] => {
-  const found: string[] = [];
-  if (text.trim() === '') found.push('the unit file is empty');
-  if (text.includes('\u0000')) found.push('the unit file contains NUL');
-  if (!/^\s*\[[A-Za-z]+]/.test(text)) found.push('a unit file must begin with a [Section]');
-  return found;
-};

package/src/linux/unit-text.test.ts

@@ -0,0 +1,67 @@
+/**
+ * `unit-text.ts`'s own tests — the INI text-shape checks, on their own, separate from
+ * `unit-lifecycle.test.ts`'s end-to-end fake-host behaviour.
+ */
+import { describe, expect, test } from 'bun:test';
+import { hasInstallSection, textProblems } from './unit-text.ts';
+
+// 🔴 REGRESSION, CT100 deploy 2026-09-26 00:11Z: `assertValid` refused this EXACT content — "a
+//   unit file must begin with a [Section]" — even though it is byte-identical to what systemd
+//   already loads on CT100 (sha256 verified against the live host). Leading lines copied
+//   verbatim from homeflare-ct100's src/openbao-agent/files/openbao-agent.service.
+const CT100_OPENBAO_AGENT = [
+  "# CT100's openbao-agent.",
+  '#',
+  "# THIS FILE WAS RECOVERED FROM THE RUNNING BOX, NOT PUSHED TO IT. The repo's copy was STALE",
+  '#   and would have REMOVED `Environment=BAO_NAMESPACE=homeflare` -- without which the agent',
+  '#   authenticates into the root namespace, every template 403s, and the failure reads as a',
+  '#   missing grant rather than a missing variable. That is the exact shape the vault policies',
+  '#   README warns about: a deploy converging a stale copy over a working live one.',
+  '# So the FIRST run of deploy-ct100.sh was a --dry-run, and this is what it was for.',
+  '[Unit]',
+  'Description=OpenBao agent',
+  'After=network-online.target',
+  'Wants=network-online.target',
+  '[Service]',
+  'Environment=BAO_NAMESPACE=homeflare',
+  'ExecStart=/usr/bin/bao agent -config=/etc/openbao/agent.hcl',
+  'RuntimeDirectory=openbao',
+  'Restart=on-failure',
+  'RestartSec=10',
+  '[Install]',
+  'WantedBy=multi-user.target',
+  '',
+].join('\n');
+
+describe('textProblems', () => {
+  test('the CT100 openbao-agent.service fixture validates — comments may precede [Unit]', () => {
+    expect(textProblems(CT100_OPENBAO_AGENT)).toEqual([]);
+  });
+
+  test('blank lines alone may also precede the first section', () => {
+    expect(textProblems('\n\n[Unit]\nDescription=x\n')).toEqual([]);
+  });
+
+  test('a ; comment is accepted the same as a #  comment', () => {
+    expect(textProblems('; a semicolon comment\n[Unit]\nDescription=x\n')).toEqual([]);
+  });
+
+  test('a genuine key=value before any section still refuses — comments are not a blanket exemption', () => {
+    expect(textProblems('Description=no section at all\n[Unit]\n').join(' ')).toMatch(
+      /must begin with a \[Section\]/,
+    );
+  });
+
+  test('an empty file and one with NUL are still refused', () => {
+    expect(textProblems('   \n').join(' ')).toMatch(/is empty/);
+    expect(textProblems('[Unit]\nDescription=a\u0000b\n').join(' ')).toMatch(/contains NUL/);
+  });
+});
+
+describe('hasInstallSection', () => {
+  test('true only once an [Install] key actually appears after the header', () => {
+    expect(hasInstallSection('[Unit]\n[Install]\nWantedBy=multi-user.target\n')).toBe(true);
+    expect(hasInstallSection('[Unit]\nDescription=x\n')).toBe(false);
+    expect(hasInstallSection('[Unit]\n[Install]\n')).toBe(false);
+  });
+});

package/src/linux/unit-text.ts

@@ -0,0 +1,58 @@
+/**
+ * The parts of `unit-form.ts`'s validation that inspect the unit file's TEXT rather than its
+ * props struct — split out so unit-form.ts stays under the file cap, and because these are one
+ * coherent concern: is this INI shape something systemd would actually load. Takes plain strings,
+ * never `SystemdUnitProps`, so it never needs to import back from unit-form.ts.
+ *
+ * ⛔ `[Install]` KEYS ARE `unit-form.ts`'s OWN LIST, NOT SYSTEMD'S FULL VOCABULARY — WantedBy,
+ *   RequiredBy, UpsertedBy, Also, Alias, per `systemd.unit(5)` §[Install]. `container-form.ts`'s
+ *   own header notes it deliberately does NOT reuse this set: a `.container` file's `[Install]`
+ *   supports only Alias/WantedBy/RequiredBy (`podman-systemd.unit(5)`), narrower than this.
+ */
+
+export const INSTALL_KEYS = new Set(['WantedBy', 'RequiredBy', 'UpsertedBy', 'Also', 'Alias']);
+
+/** Whether `text` has an `[Install]` section carrying at least one key systemd actually links on. */
+export const hasInstallSection = (text: string): boolean => {
+  if (!text.includes('[Install]')) return false;
+  const after = text.slice(text.indexOf('[Install]'));
+  return [...INSTALL_KEYS].some((key) => new RegExp(`^${key}=`, 'm').test(after));
+};
+
+/**
+ * The first line that is neither blank nor a comment — the line whose shape actually decides
+ * whether the file "begins with a [Section]", per `textProblems` below.
+ * ★ systemd.syntax(7): "Empty lines and lines starting with '#' or ';' are ignored", with no
+ *   carve-out for the position before the first section — a comment header is ordinary content
+ *   there, same as anywhere else in the file.
+ */
+export const firstSubstantiveLine = (text: string): string | undefined =>
+  text
+    .split('\n')
+    .find((line) => !(line.trim() === '' || line.startsWith('#') || line.startsWith(';')));
+
+/**
+ * 🔴 MEASURED FALSE, CT100 deploy 2026-09-26 00:11Z: the openbao-agent.service asset's first eight
+ *   lines are `#`-comments recording where the file was recovered from (verbatim from the live
+ *   host — homeflare-ct100's `src/openbao-agent/files/openbao-agent.service`), and the file is
+ *   byte-identical to what systemd already loads there. The old check tested the WHOLE text
+ *   against `/^\s*\[[A-Za-z]+]/` — `\s*` skips blank lines and indentation, never a `#`/`;`
+ *   comment — so a leading comment line failed it outright. This checks only the first
+ *   SUBSTANTIVE line, so any number of leading blank lines and comments are fine and a genuine
+ *   `key=value` before any section — the one real error this exists to catch — still fails, since
+ *   that line is neither blank nor a comment either.
+ */
+export const textProblems = (text: string): string[] => {
+  const found: string[] = [];
+  if (text.trim() === '') found.push('the unit file is empty');
+  if (text.includes('\u0000')) found.push('the unit file contains NUL');
+  const first = firstSubstantiveLine(text);
+  // ★ `\s*` kept from the original regex — leading indentation on the SECTION line itself was
+  //   already tolerated before this fix and stays that way; only the leading-comment shape changes.
+  if (first === undefined || !/^\s*\[[A-Za-z]+]/.test(first)) {
+    found.push(
+      'a unit file must begin with a [Section] (blank lines and #/; comments before it are fine)',
+    );
+  }
+  return found;
+};