@homeflare/alchemy 0.19.1 → 0.21.0

package/src/release/tar.ts

@@ -0,0 +1,195 @@
+/**
+ * A tar reader with one job: hand back the NAMED regular files of a vendor archive, and refuse the
+ * whole archive if any entry could make a name mean something other than what it says.
+ *
+ * ★ IN PROCESS, NOT `tar` ON THE HOST. An exec'd tar writes through its own path — past the
+ *   HostRunner seam, past sudoRunner's allowlist, and past the member digest check, which has to
+ *   see the bytes BEFORE they exist on any disk. Nothing this file reads is ever written by it.
+ * ★ STREAMING. It is fed the gunzip output chunk by chunk; an entry nobody asked for is counted
+ *   past, never held. vmutils unpacks to 264 MB across seven binaries (measured 2026-09-22) and a
+ *   stack wants two, so the unpacked archive never exists whole in memory.
+ * ⛔ REFUSED, WHOLE ARCHIVE, whichever entry it is and whether or not it was asked for:
+ *   an absolute name; a `..` segment; a hard link, symlink, directory, device, FIFO or contiguous
+ *   file (only a regular file is accepted); a name given twice; a header whose checksum fails; a
+ *   size in GNU base-256; a header that is neither ustar nor GNU; a lone zero block between entries;
+ *   non-zero bytes after the end marker; an archive that stops before it.
+ * ★ GNU LONG NAMES ('L', 'K') AND PAX HEADERS ('x', 'g') ARE REFUSED, NOT INTERPRETED. Each renames
+ *   the entry after it: a reader that honours them must get them exactly right to match exactly,
+ *   and one that skips them matches under the wrong name. The four pinned archives use neither
+ *   (measured 2026-09-22 with `tar -tvzf` on each: every entry a root-level regular file with a
+ *   short name), so refusing costs nothing today, and a vendor format change becomes a refusal that
+ *   says what changed instead of a silent mis-read.
+ */
+import { ArchiveRefused } from './refused.ts';
+
+const BLOCK = 512;
+
+const KINDS: Readonly<Record<string, string>> = {
+  '1': 'a hard link',
+  '2': 'a symlink',
+  '3': 'a character device',
+  '4': 'a block device',
+  '5': 'a directory',
+  '6': 'a FIFO',
+  '7': 'a contiguous file',
+  K: 'a GNU long-link header',
+  L: 'a GNU long-name header',
+  g: 'a PAX global header',
+  x: 'a PAX extended header',
+};
+
+const refuse = (message: string): ArchiveRefused => new ArchiveRefused({ message });
+const strict = new TextDecoder('utf-8', { fatal: true });
+const ascii = new TextDecoder('latin1');
+
+/** One NUL-terminated header field. */
+const field = (block: Uint8Array, start: number, length: number): Uint8Array => {
+  const slice = block.subarray(start, start + length);
+  const end = slice.indexOf(0);
+  return end === -1 ? slice : slice.subarray(0, end);
+};
+
+const text = (block: Uint8Array, start: number, length: number): string => {
+  try {
+    return strict.decode(field(block, start, length));
+  } catch {
+    throw refuse('an entry name is not UTF-8');
+  }
+};
+
+const octal = (block: Uint8Array, start: number, length: number, what: string): number => {
+  const raw = block.subarray(start, start + length);
+  if (((raw[0] ?? 0) & 0x80) !== 0) throw refuse(`${what} is base-256 encoded`);
+  const digits = ascii
+    .decode(raw)
+    .replace(/[\0 ]+$/, '')
+    .replace(/^ +/, '');
+  if (!/^[0-7]+$/.test(digits)) throw refuse(`${what} is not octal: ${JSON.stringify(digits)}`);
+  return Number.parseInt(digits, 8);
+};
+
+const checksumHolds = (block: Uint8Array): boolean => {
+  let sum = 0;
+  // The checksum field itself counts as eight spaces (POSIX ustar).
+  for (let at = 0; at < BLOCK; at += 1) sum += at >= 148 && at < 156 ? 0x20 : (block[at] ?? 0);
+  return sum === octal(block, 148, 8, 'a header checksum');
+};
+
+/** Why an entry name is unsafe to trust, or undefined. */
+const nameProblem = (name: string): string | undefined => {
+  if (name === '') return 'has an empty name';
+  if (name.startsWith('/')) return 'is absolute';
+  if (name.split('/').includes('..')) return 'climbs out of the archive with ".."';
+  return undefined;
+};
+
+/** Concatenate chunks into one buffer. */
+export const concatBytes = (parts: readonly Uint8Array[]): Uint8Array => {
+  const out = new Uint8Array(parts.reduce((total, part) => total + part.length, 0));
+  let at = 0;
+  for (const part of parts) {
+    out.set(part, at);
+    at += part.length;
+  }
+  return out;
+};
+
+export type TarContents = {
+  /** The asked-for regular files, by exact name. An asked-for name that is absent is absent here. */
+  readonly members: ReadonlyMap<string, Uint8Array>;
+  /** Every entry name, in archive order — so a refusal can say what the archive did hold. */
+  readonly names: readonly string[];
+};
+
+/** A push parser: `push` each chunk of the unzipped stream, then `finish`. Either may throw. */
+export const tarReader = (wanted: ReadonlySet<string>) => {
+  const header = new Uint8Array(BLOCK);
+  const members = new Map<string, Uint8Array>();
+  const names: string[] = [];
+  const seen = new Set<string>();
+  let phase: 'header' | 'data' | 'pad' | 'end' = 'header';
+  let filled = 0;
+  let remaining = 0;
+  let padding = 0;
+  let zeros = 0;
+  let name = '';
+  let parts: Uint8Array[] | undefined;
+
+  const endEntry = () => {
+    if (parts !== undefined) members.set(name, concatBytes(parts));
+    parts = undefined;
+    phase = padding > 0 ? 'pad' : 'header';
+  };
+
+  const startEntry = () => {
+    if (header.every((byte) => byte === 0)) {
+      zeros += 1;
+      if (zeros === 2) phase = 'end';
+      return;
+    }
+    if (zeros > 0) throw refuse('a zero block sits between entries (truncated or spliced)');
+    if (!checksumHolds(header)) throw refuse('an entry header fails its checksum');
+    const magic = ascii.decode(header.subarray(257, 265));
+    const posix = magic === 'ustar\u000000';
+    if (!posix && magic !== 'ustar  \u0000')
+      throw refuse('an entry header is neither ustar nor GNU');
+    const prefix = posix ? text(header, 345, 155) : '';
+    name = prefix === '' ? text(header, 0, 100) : `${prefix}/${text(header, 0, 100)}`;
+    const problem = nameProblem(name);
+    if (problem !== undefined) throw refuse(`entry ${JSON.stringify(name)} ${problem}`);
+    const type = String.fromCharCode(header[156] ?? 0);
+    if (type !== '0' && type !== '\0') {
+      const kind = KINDS[type] ?? `of unknown type ${JSON.stringify(type)}`;
+      throw refuse(`entry "${name}" is ${kind}; only regular files are accepted`);
+    }
+    if (seen.has(name)) throw refuse(`entry "${name}" appears twice`);
+    seen.add(name);
+    names.push(name);
+    remaining = octal(header, 124, 12, `entry "${name}"'s size`);
+    padding = (BLOCK - (remaining % BLOCK)) % BLOCK;
+    parts = wanted.has(name) ? [] : undefined;
+    phase = 'data';
+    if (remaining === 0) endEntry();
+  };
+
+  const push = (chunk: Uint8Array): void => {
+    let at = 0;
+    while (at < chunk.length) {
+      if (phase === 'end') {
+        if (chunk.subarray(at).some((byte) => byte !== 0)) {
+          throw refuse('data follows the end-of-archive marker');
+        }
+        return;
+      }
+      if (phase === 'header') {
+        const take = Math.min(BLOCK - filled, chunk.length - at);
+        header.set(chunk.subarray(at, at + take), filled);
+        filled += take;
+        at += take;
+        if (filled === BLOCK) {
+          filled = 0;
+          startEntry();
+        }
+      } else if (phase === 'data') {
+        const take = Math.min(remaining, chunk.length - at);
+        // ⚠️ slice, not subarray: a chunk's buffer may be reused by the stream after this returns.
+        parts?.push(chunk.slice(at, at + take));
+        remaining -= take;
+        at += take;
+        if (remaining === 0) endEntry();
+      } else {
+        const take = Math.min(padding, chunk.length - at);
+        padding -= take;
+        at += take;
+        if (padding === 0) phase = 'header';
+      }
+    }
+  };
+
+  const finish = (): TarContents => {
+    if (phase !== 'end') throw refuse('the archive stops before its end-of-archive marker');
+    return { members, names };
+  };
+
+  return { finish, push };
+};

package/src/release/victoria.test.ts

@@ -0,0 +1,108 @@
+/**
+ * The REAL Victoria data set against the vendor's own files — no network: fixtures/victoria/ holds
+ * the four checksum files byte-for-byte as fetched on 2026-09-22 (each one's SHA-256 equalled
+ * GitHub's asset digest for it that day; the data set records it), and the darwin-arm64 asset
+ * names the release API listed.
+ *
+ * ★ THE CHAIN THIS PROVES: fixture bytes = the recorded digest of the vendor file → the parser
+ *   reads exactly its lines → the data set equals those lines. A pin typed by hand, a member missed
+ *   or a line the vendor added fails here, not on a host.
+ * ⚠️ CONSISTENCY, NOT PROVENANCE. No network here: that the recorded digest is GITHUB'S was measured
+ *   once, on the recorded date. A change that edits a fixture and its pins together passes; review
+ *   is the gate for that.
+ */
+import { describe, expect, test } from 'bun:test';
+import { sha256Hex } from '../launchd/job-form.ts';
+import { releaseUrl } from './binary-form.ts';
+import { catalogBinary } from './catalog.ts';
+import { parseChecksums } from './checksums.ts';
+import { VICTORIA_RELEASES } from './victoria.ts';
+
+const fixture = (name: string) => Bun.file(new URL(`fixtures/victoria/${name}`, import.meta.url));
+const assets = (await fixture('darwin-arm64-assets.txt').text()).trim().split('\n');
+const REPOS: Readonly<Record<string, string>> = {
+  'victoria-logs': 'VictoriaMetrics/VictoriaLogs',
+  'victoria-metrics': 'VictoriaMetrics/VictoriaMetrics',
+  'victoria-traces': 'VictoriaMetrics/VictoriaTraces',
+  vmutils: 'VictoriaMetrics/VictoriaMetrics',
+};
+
+const archives = Object.entries(VICTORIA_RELEASES.packages).flatMap(([pkg, entry]) =>
+  Object.entries(entry.versions).flatMap(([version, platforms]) =>
+    Object.entries(platforms).map(([platform, archive]) => ({
+      archive,
+      entry,
+      pkg,
+      platform,
+      version,
+    })),
+  ),
+);
+
+describe('the Victoria data set is the vendor checksum files', () => {
+  test('it pins the four archives the Mac host runs, and nothing else', () => {
+    expect(archives.map((a) => `${a.pkg} ${a.version} ${a.platform}`).sort()).toEqual([
+      'victoria-logs 1.52.0 darwin-arm64',
+      'victoria-metrics 1.151.0 darwin-arm64',
+      'victoria-traces 0.10.0 darwin-arm64',
+      'vmutils 1.151.0 darwin-arm64',
+    ]);
+  });
+
+  test.each(archives.map((a) => [`${a.pkg} ${a.version}`, a] as const))('%s', async (_, a) => {
+    const asset = `${a.pkg}-${a.platform}-v${a.version}.tar.gz`;
+    const sums = `${a.pkg}-${a.platform}-v${a.version}_checksums.txt`;
+    // ⛔ Exact, whole names — and the names the release API actually lists.
+    expect([a.archive.repo, a.archive.tag, a.archive.asset]).toEqual([
+      REPOS[a.pkg] ?? '',
+      `v${a.version}`,
+      asset,
+    ]);
+    const base = `https://github.com/${REPOS[a.pkg] ?? ''}/releases/download/v${a.version}`;
+    expect(releaseUrl(a.archive.repo, a.archive.tag, a.archive.asset)).toBe(`${base}/${asset}`);
+    expect(a.archive.checksums.url).toBe(`${base}/${sums}`);
+    expect(a.archive.checksums.recorded).toBe('2026-09-22');
+    expect(assets).toContain(asset);
+    const bytes = new Uint8Array(await fixture(sums).arrayBuffer());
+    expect(sha256Hex(bytes)).toBe(a.archive.checksums.sha256);
+    const lines = parseChecksums(new TextDecoder().decode(bytes));
+    const [first, ...members] = [...lines.entries()];
+    expect(first).toEqual([asset, a.archive.sha256]);
+    expect(Object.fromEntries(members)).toEqual(a.archive.members);
+    // ★ Every installed name maps to `<name>-prod`, deliberately, and every one is pinned.
+    for (const [binary, member] of Object.entries(a.entry.binaries)) {
+      expect(member).toBe(`${binary}-prod`);
+      expect(a.archive.members[member]).toMatch(/^[0-9a-f]{64}$/);
+    }
+    expect(Object.keys(a.entry.binaries).length).toBe(members.length);
+  });
+
+  test('no pinned asset is an enterprise, cluster or other sibling, though each one is listed', () => {
+    const siblings = assets.filter((name) => /-(enterprise|cluster)[._]/.test(name));
+    expect(siblings.length).toBe(12);
+    const names = archives.flatMap((a) => [a.archive.asset, a.archive.checksums.url]);
+    for (const name of names) expect(name).not.toMatch(/enterprise|cluster|vlutils/);
+    for (const sibling of siblings) expect(names.some((n) => n.endsWith(sibling))).toBe(false);
+  });
+
+  test('vmalert out of the data set: the member vmalert-prod of the plain vmutils archive', () => {
+    const request = {
+      binary: 'vmalert',
+      package: 'vmutils',
+      platform: 'darwin-arm64',
+      version: '1.151.0',
+    };
+    expect(catalogBinary(VICTORIA_RELEASES, request)).toEqual({
+      archive: {
+        asset: 'vmutils-darwin-arm64-v1.151.0.tar.gz',
+        repo: 'VictoriaMetrics/VictoriaMetrics',
+        sha256: '27d68bac90e28929214091ed9d27f2e9fef25a080407e2c8661ea9b52dd6b183',
+        size: 123_584_800,
+        tag: 'v1.151.0',
+      },
+      member: 'vmalert-prod',
+      name: 'vmalert',
+      sha256: '62845795167e9ff47890e83ac4ac5934693c105767db88591c95a08f3c4fb354',
+    });
+  });
+});

package/src/release/victoria.ts

@@ -0,0 +1,154 @@
+/**
+ * VictoriaMetrics' release archives, pinned — the first data set for Release.Binary, and vendor
+ * facts only: every digest copied from the vendor's own checksum file for that archive and
+ * cross-checked against GitHub's asset digest ON THE RECORDED DATE. Nothing here names a host, a
+ * path, a user or an estate. victoria.test.ts holds every pin to the committed checksum files
+ * (fixtures/victoria/) — ⚠️ consistency, not provenance: it cannot re-read GitHub, so a fixture
+ * edited together with its pins passes, and review is the gate for that.
+ *
+ * ★ PINNED IN CODE, NOT FETCHED AT APPLY. The checksum file is published by the same account, on
+ *   the same release, over the same channel as the archive it describes — and these releases are
+ *   MUTABLE (`"immutable": false` on v1.151.0, v1.52.0 and v0.10.0, measured 2026-09-22; the
+ *   vendor's own release Makefile says to delete an asset in the UI to re-upload it). Whoever can
+ *   swap an archive can swap its checksum file in the same minute, and a provider that trusts
+ *   whatever checksum file it finds would install the new bytes and call them verified. A pin
+ *   committed here changes only through a reviewed kit release, so a swapped asset is a REFUSAL
+ *   that names the digest it expected. It also means an apply makes one request, not two, and a
+ *   plan knows exactly which bytes it will install without touching the network.
+ * ⚠️ TRUST ROOT. At apply, these pins alone: the transport (TLS, the redirect, the CDN) can fail
+ *   a download, never pass other bytes. The pins' own root is the GitHub release over TLS as read
+ *   on RECORDED (trust on first use), uploaded from a maintainer's personal account.
+ *   VictoriaMetrics publishes no signature, cosign bundle, SLSA provenance or GitHub artifact
+ *   attestation for these archives (measured 2026-09-22: no .sig/.asc/.pem/.bundle assets; the
+ *   attestations API answers 404 for all four digests, next to a positive control that answers
+ *   200). A checksum file proves the download is not corrupt — integrity — not who built it.
+ * ⛔ A NEW VERSION IS A NEW ENTRY, WALKED DOWN THE SAME WAY — docs/release-binary-catalogs.md.
+ *   Never `latest`, never sorted by publish date: VictoriaLogs v1.51.1 was published AFTER v1.52.0.
+ * ⛔ EXACT NAMES. `-enterprise`, `-cluster` and `-enterprise-cluster` archives sit beside each of
+ *   these with every prefix in common, so each asset name below is written out whole — never
+ *   composed from a package and a version, which is how a template drifts onto a sibling.
+ * ★ THE VENDOR'S `-prod` SUFFIX IS DROPPED ON PURPOSE: every member is `<binary>-prod`, and
+ *   installing it as `<binary>` keeps a job's argv[0], `ps` and `pgrep` names identical to the
+ *   builds it replaces. The map is written out per package, never derived.
+ */
+import type { ReleaseCatalog } from './catalog.ts';
+
+const RECORDED = '2026-09-22';
+const DOWNLOAD = 'https://github.com/VictoriaMetrics';
+
+export const VICTORIA_RELEASES: ReleaseCatalog = {
+  packages: {
+    'victoria-logs': {
+      binaries: { 'victoria-logs': 'victoria-logs-prod' },
+      versions: {
+        '1.52.0': {
+          'darwin-arm64': {
+            asset: 'victoria-logs-darwin-arm64-v1.52.0.tar.gz',
+            checksums: {
+              recorded: RECORDED,
+              sha256: 'd4ca686c3cceec78a0f4e733ef9ab3f857549131ea48cd6f89f701cda406ac4b',
+              url: `${DOWNLOAD}/VictoriaLogs/releases/download/v1.52.0/victoria-logs-darwin-arm64-v1.52.0_checksums.txt`,
+            },
+            members: {
+              'victoria-logs-prod':
+                '9e48809e314902782959b3a4e683a3087476759d0293791a0564921c676ca7be',
+            },
+            repo: 'VictoriaMetrics/VictoriaLogs',
+            sha256: '3157d4b6181d8a7e3e30918e2cbfcd4cc4cb66263e3ef21ea91e4f20f8980883',
+            size: 10_943_697,
+            tag: 'v1.52.0',
+          },
+        },
+      },
+    },
+    'victoria-metrics': {
+      // ⛔ The SINGLE-NODE archive. `…-cluster.tar.gz` holds vminsert/vmselect/vmstorage instead.
+      binaries: { 'victoria-metrics': 'victoria-metrics-prod' },
+      versions: {
+        '1.151.0': {
+          'darwin-arm64': {
+            asset: 'victoria-metrics-darwin-arm64-v1.151.0.tar.gz',
+            checksums: {
+              recorded: RECORDED,
+              sha256: '735745ee0e7b2d5b8118883f2d0ed124c2a12d70261c16380128f5e362566d1e',
+              url: `${DOWNLOAD}/VictoriaMetrics/releases/download/v1.151.0/victoria-metrics-darwin-arm64-v1.151.0_checksums.txt`,
+            },
+            members: {
+              'victoria-metrics-prod':
+                '3c493a95ac1e9034a3261b230c4d62f3b186a04aafcdbacc99bfc110dc5de6a1',
+            },
+            repo: 'VictoriaMetrics/VictoriaMetrics',
+            sha256: '8792437c4c0b63719fed7b44ad18d4b4167bbe6861ab3e84c7bb010c922e7582',
+            size: 12_739_105,
+            tag: 'v1.151.0',
+          },
+        },
+      },
+    },
+    'victoria-traces': {
+      binaries: { 'victoria-traces': 'victoria-traces-prod' },
+      versions: {
+        '0.10.0': {
+          'darwin-arm64': {
+            asset: 'victoria-traces-darwin-arm64-v0.10.0.tar.gz',
+            checksums: {
+              recorded: RECORDED,
+              sha256: 'cd32bfc21900b48ba543124e43827a1d13d735e45d50dbfd742c0ca6640e1aae',
+              url: `${DOWNLOAD}/VictoriaTraces/releases/download/v0.10.0/victoria-traces-darwin-arm64-v0.10.0_checksums.txt`,
+            },
+            members: {
+              'victoria-traces-prod':
+                '4759ec89a466129b9eefc22244a111e1f489739340747805fd93b58fd0f7b2dd',
+            },
+            repo: 'VictoriaMetrics/VictoriaTraces',
+            sha256: 'cbe83f1d409cbb85fbf1c890c4a9b7fd34c1d74acec4dce2e0ebe46fcb260e38',
+            size: 11_126_077,
+            tag: 'v0.10.0',
+          },
+        },
+      },
+    },
+    vmutils: {
+      // ★ ONE ARCHIVE, SEVEN TOOLS (measured: 264 MB unpacked). Only a declared member is extracted.
+      //   vmalert-logs is not a tool of its own: it is vmalert run with `--rule.defaultRuleType=vlogs`.
+      binaries: {
+        vmagent: 'vmagent-prod',
+        vmalert: 'vmalert-prod',
+        'vmalert-tool': 'vmalert-tool-prod',
+        vmauth: 'vmauth-prod',
+        vmbackup: 'vmbackup-prod',
+        vmctl: 'vmctl-prod',
+        vmrestore: 'vmrestore-prod',
+      },
+      versions: {
+        '1.151.0': {
+          'darwin-arm64': {
+            asset: 'vmutils-darwin-arm64-v1.151.0.tar.gz',
+            checksums: {
+              recorded: RECORDED,
+              sha256: 'fda5a64fce9022bee7614c3fda27271c0826f1d7b90f8b162e1f48c77c0df04b',
+              url: `${DOWNLOAD}/VictoriaMetrics/releases/download/v1.151.0/vmutils-darwin-arm64-v1.151.0_checksums.txt`,
+            },
+            members: {
+              'vmagent-prod': 'd3b6fa1f71ef48beac619f15f8adfa7610e76605caf37db1ebfbb379b6692329',
+              'vmalert-prod': '62845795167e9ff47890e83ac4ac5934693c105767db88591c95a08f3c4fb354',
+              'vmalert-tool-prod':
+                'cbffb9495e4bb1457c9d45e0a7064b3a3a29b2cfd1ae24bfe8f00ec327c26998',
+              // ⚠️ gitleaks' generic-api-key rule reads this one public digest as a key (its
+              //   entropy; measured 2026-09-22). It is the vendor's published SHA-256 of vmauth-prod.
+              'vmauth-prod': '398df9e0f5b7035d037e39ee9ff66a10ddde5333d832602463aa4d2865fdb508', // gitleaks:allow
+              'vmbackup-prod': '1974a2ee211b49bf581287808e010846f6c47ff135276214c6da628567777b9e',
+              'vmctl-prod': '998b111eee206b98e6d25fdf2fbaa455ecc17c7f9e7c3b2373e127cef762459f',
+              'vmrestore-prod': 'fc824df7215b01b57921ed46afde7fea6b6698adf13d9ea8e3fe36e194ef8190',
+            },
+            repo: 'VictoriaMetrics/VictoriaMetrics',
+            sha256: '27d68bac90e28929214091ed9d27f2e9fef25a080407e2c8661ea9b52dd6b183',
+            size: 123_584_800,
+            tag: 'v1.151.0',
+          },
+        },
+      },
+    },
+  },
+  vendor: 'VictoriaMetrics',
+};

package/src/{proxmox → secrets}/write-only.ts

@@ -2,6 +2,12 @@
  * Values a declaration may SEND and must never STORE — a webhook secret, a header carrying a
  * credential, an smtp password — and the one form in which a plan may still remember them.
  *
+ * ★ FAMILY-NEUTRAL ON PURPOSE, MOVED HERE FROM `proxmox/` 2026-09-22. The rule it encodes is not
+ *   about Proxmox: Alchemy's state store is the same unencrypted store for every provider, so the
+ *   Cloudflare MCP server entry's `auth_credentials` needs exactly this shape. A second copy under
+ *   `cloudflare/` would be two seal formats for one rule; a cross-family import would make
+ *   Cloudflare depend on Proxmox. Neither; it lives on its own.
+ *
  * ⛔ A SECRET PROP IS A SECRET IN THE STATE STORE, WHATEVER TYPE IT HAS. Alchemy persists props as
  *   well as attributes — `delete` is handed `olds`, which can only have come from the store — and
  *   it does not encrypt either: `StateEncoding.ts` TAGS a `Redacted` value and writes the inner