@homeflare/alchemy 0.20.0 → 0.21.0

package/docs/release-binary.md

@@ -0,0 +1,154 @@
+# Release binaries — `@homeflare/alchemy/release`
+
+Status: active
+Verified: 2026-09-22
+
+`Release.Binary` (`ReleaseBinary`) installs one binary out of a pinned release
+archive, verified twice: the archive against its pinned SHA-256 before anything
+is unpacked, then the binary against its own before it is written. The pinned
+archive is **props**. Each vendor's pinned versions are **data** kept beside
+the resource, and `VICTORIA_RELEASES` is the first data set. It exists to
+replace the Nix-built Victoria binaries on the Mac host: all five Nix builds
+link a `/nix/store` `libresolv`, and the vendor builds link none.
+
+⛔ **It installs; it never starts.** No `launchctl`, no `systemctl`, no restart.
+The daemon is the stack's own `LaunchdJob` (or systemd unit), and it puts the
+binary's `path` in its argv.
+
+## Declaring one
+
+```ts
+import { HostDirectory, linuxProviders } from '@homeflare/alchemy/linux';
+import { LaunchdJob, launchdProviders, localRunner } from '@homeflare/alchemy/launchd';
+import {
+  ReleaseBinary, VICTORIA_RELEASES, catalogBinary, catalogDirectory, releaseProviders,
+} from '@homeflare/alchemy/release';
+
+const runner = localRunner();
+// providers: Layer.mergeAll(launchdProviders(runner), linuxProviders(runner), releaseProviders(runner))
+
+const vmalertOf = { package: 'vmutils', version: '1.151.0', platform: 'darwin-arm64', binary: 'vmalert' };
+const dir = yield* HostDirectory('vmutils-1.151.0', {
+  path: catalogDirectory('/opt/example/bin', vmalertOf), // …/vmutils-1.151.0
+  mode: 0o755, owner: 0, group: 0,
+});
+const vmalert = yield* ReleaseBinary('vmalert', {
+  ...catalogBinary(VICTORIA_RELEASES, vmalertOf), // archive, member, sha256, name
+  directory: dir.path, // ★ an Output: the engine creates the directory first
+  owner: 0, group: 0, mode: 0o555,
+});
+yield* LaunchdJob('vmalert', { programArguments: [vmalert.path, '--httpListenAddr=127.0.0.1:8880'], … });
+```
+
+- **`catalogBinary()` runs in your stack program.** A version, package,
+  platform or binary the data set does not pin throws `BinaryRefused` there,
+  so `alchemy plan` fails before any resource is asked anything
+  (`plan.test.ts`: zero requests, zero host calls).
+- **The directory is yours, one per version.** It must exist.
+  `catalogDirectory(root, …)` names it `<root>/<package>-<version>`. A version
+  bump is then a new path. Measured through the engine (`plan.test.ts`):
+  mkdir new, download, write new, remove old, rmdir old, in that order.
+- ⛔ **A new pin at the same path is refused**, at plan when the path is
+  resolved and at apply otherwise, rather than overwriting a binary under the
+  daemon that runs it. 🔴 While the directory is still an Output, a re-pin of
+  the same bytes is planned as an `update`, never a `replace`: measured through
+  the engine, a `replace` onto an unmoved path took the identical file as the
+  new generation's, then deleted it with the old one, and reported success.
+- **The job references `vmalert.path`**, not a string it built. That Output
+  orders the job after the binary. A version bump moves the path, so the plist
+  changes and the job restarts on the new binary before the old one is deleted.
+- **Declare each path once.** vmalert-logs is vmalert with other flags: one
+  `ReleaseBinary`, referenced by both jobs.
+- **One logical id per binary, one per versioned directory.** `plan.test.ts`
+  declares `ReleaseBinary('vmalert')` and `HostDirectory('vmutils-<version>')`:
+  a bump plans the binary as a `replace`, the new directory as a `create` and
+  the old one as a `delete`, and the engine removes the old binary before its
+  directory.
+- **Nothing estate-specific is in the kit.** Root, owner, group and mode are
+  your props. The data sets hold vendor facts only.
+- **One runner for all of it.** Pass the same `HostRunner` to
+  `releaseProviders()` as to the jobs. There is no default: a binary goes
+  wherever the runner reaches. It provides its own `FetchHttpClient.layer`.
+- **Your own pins work too.** The props are plain data, so a stack may write
+  them itself. ⛔ They must be plain values in the stack program: a pin wired
+  from another resource's Output (a checksum file read at apply) is refused,
+  on a first deploy too (`apply-pins.test.ts`). ⚠️ A stack program that
+  fetches the file itself and passes plain strings cannot be told apart from
+  a reviewed pin; `catalogBinary()` over a reviewed data set is the path
+  that keeps them reviewed.
+
+## What reconcile does, in order
+
+1. **Validate every prop**, before any host or network call. Every pin must be a
+   plain, well-formed value, as the stack program DECLARED it: by now an Output
+   has resolved to a plausible string (`declared-pins.ts`).
+2. **Check the directory exists**, is not a symlink, and is not writable by
+   group or other (they could rename a file over the binary), before any download.
+3. **Observe the path.** A symlink or directory there is refused. A file this
+   resource does not own is refused without `--adopt`, even one holding the
+   pinned bytes: at plan the probe calls it `Unowned`, and at apply, when a
+   prop was an Output and the probe never ran, reconcile refuses it the same
+   way (`binary-claim.ts`). ⛔ A file with other bytes is refused under
+   `--adopt` too, at plan and at apply: adopting it would overwrite it in
+   place, and the plan would print that as `adopted`. Under `--adopt`, the
+   pinned bytes are kept: no download, and a write only to fix mode or owner.
+   ⚠️ A rename is not an adoption: declare it with `renamedFrom()`. Under
+   `--adopt` the new name takes the file, and the old name's delete leaves a
+   path another declaration installed in the same deploy (`adopt-parity.test.ts`).
+4. **Download** `https://github.com/<repo>/releases/download/<tag>/<asset>`,
+   into memory, never past the pinned size. Two binaries from one archive at
+   once share one download.
+5. **Verify the archive** against its pinned SHA-256, before unpacking a byte.
+6. **Unpack only the declared member**, streaming. The tar reader refuses the
+   whole archive for any unsafe entry, declared or not.
+7. **Verify the member** against its own pinned SHA-256.
+8. **Write** through `HostRunner.writeFileAtomic`, the one writer every file
+   resource uses: a temp file in the same directory, mode and owner set, then
+   rename. Under `sudoRunner`, one staged `install -S`, ⚠️ which sets the mode
+   just after its rename (measured: `0600` for under half a millisecond).
+9. **Read back** and compare. A create that does not read back, or whose
+   read-back fails, is removed.
+
+A binary with the right bytes but the wrong mode or owner is re-written from
+the bytes already on disk, re-hashed, without a download.
+
+⛔ A directory respelled to the same place (a symlinked parent, or case on
+APFS) is an `update` that keeps the file, never a `replace`: the replace's
+Phase 2 would delete the old path, which is the file (`launchd/file-identity.ts`).
+
+## Trust: why the digests are pinned in code
+
+★ **Pinned, not fetched at apply.** A checksum file comes from the same
+account, release and channel as the archive, and every release checked so far
+is mutable (`"immutable": false`). Whoever can swap an archive can swap its
+checksum file, and a provider that trusts what it fetches would call the swap
+verified. A pin moves only through a reviewed change, so a swapped asset is a
+refusal. And a plan knows exactly which bytes it will install without the
+network. Each data-set entry records the checksum file's URL, its own SHA-256
+and the date the pins were copied.
+
+⚠️ **The trust root.** At apply it is the pins alone: TLS, GitHub's redirect,
+its CDN or a proxy can make a download fail, never make other bytes pass. The
+pins rest on one read of the GitHub release over TLS on the `recorded` date
+(trust on first use), checked against GitHub's own asset `digest`, then on
+review of that commit and the kit release the stack's lockfile resolves.
+VictoriaMetrics publishes no signature, cosign bundle, SLSA provenance or
+GitHub attestation for these archives: a checksum proves integrity, not
+authorship.
+
+★ **What CI proves without a network** (`victoria.test.ts`) is consistency,
+not provenance: each committed checksum file in `src/release/fixtures/victoria/`
+hashes to the digest the data set records for it; the strict parser reads
+them; the data set equals what it reads; every asset is in the committed
+listing, and none is an `-enterprise`, `-cluster` or `vlutils` sibling.
+⚠️ That those recorded digests are GitHub's was measured once, not by CI. A
+change that edits a fixture and its pins together passes; review is the gate.
+
+## Refusals
+
+Every refusal, by where it is refused (the stack program, the plan, the apply,
+the vendor's bytes, the read-back): [release-binary-refusals.md](./release-binary-refusals.md).
+
+Data sets and adding a vendor: [release-binary-catalogs.md](./release-binary-catalogs.md).
+Measurements and limits: [release-binary-measured.md](./release-binary-measured.md).
+What alchemy-run/alchemy would need: [release-binary-upstream.md](./release-binary-upstream.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
@@ -64,6 +64,10 @@
       "types": "./dist/linux/index.d.ts",
       "default": "./dist/linux/index.js"
     },
+    "./release": {
+      "types": "./dist/release/index.d.ts",
+      "default": "./dist/release/index.js"
+    },
     "./caddy": {
       "types": "./dist/caddy/index.d.ts",
       "default": "./dist/caddy/index.js"

package/src/caddy/access-forward-auth.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from 'bun:test';
+import { accessForwardAuth, verifierProblems } from './access-forward-auth.ts';
+
+describe('accessForwardAuth', () => {
+  test('emits a forward_auth block with the identity headers copied', () => {
+    const block = accessForwardAuth({
+      verifier: '127.0.0.1:9101',
+      body: ['reverse_proxy 127.0.0.1:6080'],
+    });
+
+    expect(block).toBe(
+      [
+        '\treverse_proxy 127.0.0.1:6080',
+        '\tforward_auth 127.0.0.1:9101 {',
+        '\t\turi /access/verify',
+        '\t\tcopy_headers {',
+        '\t\t\tX-Access-Email',
+        '\t\t\tX-Access-Sub',
+        '\t\t}',
+        '\t}',
+      ].join('\n'),
+    );
+  });
+
+  test('copies exactly the headers the verifier sets, by default', () => {
+    // ⛔ A header the verifier emits but Caddy does not copy never reaches the upstream;
+    //    a header Caddy copies but the verifier never sets is the SPOOFING case — the
+    //    client's own value survives. These two lists must agree, which is why the default
+    //    is not configurable-by-accident.
+    const block = accessForwardAuth({ verifier: '127.0.0.1:9101' });
+    expect(block).toContain('X-Access-Email');
+    expect(block).toContain('X-Access-Sub');
+  });
+
+  test('refuses a verifier on a routable address', () => {
+    // 🔴 A verifier reachable from off-box can be answered around, and the upstream with it.
+    expect(() => accessForwardAuth({ verifier: '10.20.10.250:9101' })).toThrow(/loopback/);
+    expect(() => accessForwardAuth({ verifier: '0.0.0.0:9101' })).toThrow(/loopback/);
+  });
+
+  test('accepts loopback in its usual spellings, and a unix socket', () => {
+    for (const verifier of ['127.0.0.1:9101', 'localhost:9101', '[::1]:9101', 'unix//run/v.sock']) {
+      expect(verifierProblems(verifier)).toEqual([]);
+    }
+  });
+
+  test('a custom uri and header names flow through', () => {
+    const block = accessForwardAuth({
+      verifier: 'unix//run/access.sock',
+      uri: '/verify/vnc',
+      copyHeaders: ['Remote-Email'],
+    });
+
+    expect(block).toContain('forward_auth unix//run/access.sock {');
+    expect(block).toContain('uri /verify/vnc');
+    expect(block).toContain('Remote-Email');
+    expect(block).not.toContain('X-Access-Sub');
+  });
+
+  test('refuses an empty verifier rather than emitting a block that adapts to nothing', () => {
+    expect(() => accessForwardAuth({ verifier: '   ' })).toThrow(/empty/);
+  });
+});

package/src/caddy/access-forward-auth.ts

@@ -0,0 +1,120 @@
+/**
+ * The Caddyfile half of "protect this route with Cloudflare Access": a `forward_auth` block
+ * pointing at a verifier that speaks the contract in `@homeflare/cloudflare/access-auth`.
+ *
+ * ★ A BUILDER, NOT A RESOURCE. Nothing here is created, adopted or destroyed — it is Caddyfile
+ *   TEXT that a caller drops into the `caddyfile` prop of a `CaddyConfig` / `caddyWithFile()`.
+ *   A resource would own a fragment of a config that `CaddyConfig` already owns whole, and two
+ *   owners of one file is the drift this package exists to prevent.
+ *
+ * ⛔ WHY IT IS GENERATED RATHER THAN COPY-PASTED. Every field below is load-bearing, and the
+ *   failure mode of getting one wrong is a route that looks protected and is not:
+ *   · a missing `copy_headers` — the upstream gets no identity and either breaks or, worse,
+ *     falls back to trusting a header the CLIENT set;
+ *   · the verifier on anything but loopback — the JWT check becomes advisory, because the
+ *     verifier itself can be reached and answered around;
+ *   · `uri` pointing at a path the verifier does not route — every request 404s, which is
+ *     non-2xx, which Caddy correctly treats as a denial, so the symptom is "Access is broken".
+ */
+
+/** ⚠️ Kept in step with `granted()` in @homeflare/cloudflare/access-auth. */
+const DEFAULT_COPY_HEADERS = ['X-Access-Email', 'X-Access-Sub'] as const;
+
+export interface AccessForwardAuthProps {
+  /**
+   * Where the verifier listens, e.g. `127.0.0.1:9101`.
+   * ⛔ LOOPBACK OR A UNIX SOCKET. See `verifierProblems` — a routable verifier is not a check.
+   */
+  readonly verifier: string;
+  /** The path the verifier answers on. @default '/access/verify' */
+  readonly uri?: string;
+  /**
+   * Response headers copied from the verifier onto the upstream request.
+   * @default ['X-Access-Email', 'X-Access-Sub']
+   */
+  readonly copyHeaders?: readonly string[];
+  /** Lines placed inside the route BEFORE `forward_auth` — typically the upstream. */
+  readonly body?: readonly string[];
+  /** Indent applied to every emitted line. @default '\t' */
+  readonly indent?: string;
+}
+
+/**
+ * Problems that make a `forward_auth` block unsafe rather than merely wrong.
+ *
+ * ⛔ THE LOOPBACK RULE IS THE IMPORTANT ONE. If the verifier answers on a routable address, an
+ *   attacker reaches the UPSTREAM directly and never involves Caddy at all — or reaches the
+ *   verifier and reads identities out of it. The whole design assumes both the verifier and the
+ *   upstream are bound to loopback and that Caddy is the only way in.
+ */
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '::1', '[::1]']);
+
+/**
+ * The host part of a Caddy upstream address.
+ *
+ * ⚠️ NOT `split(':')[0]`. That returns `'['` for `[::1]:9101`, so an IPv6 loopback verifier
+ *   was rejected as routable — caught by the test below, not by reading the code.
+ */
+const hostOf = (verifier: string): string => {
+  const address = verifier.replace(/^https?:\/\//, '');
+  if (address.startsWith('unix/')) return 'unix';
+
+  // Bracketed IPv6 keeps its brackets; the port is whatever follows the closing one.
+  if (address.startsWith('[')) return address.slice(0, address.indexOf(']') + 1);
+
+  const colon = address.indexOf(':');
+  return colon === -1 ? address : address.slice(0, colon);
+};
+
+export const verifierProblems = (verifier: string): string[] => {
+  const found: string[] = [];
+  const host = hostOf(verifier.trim());
+
+  if (verifier.trim() === '') found.push('verifier is empty');
+  else if (host !== 'unix' && !LOOPBACK.has(host)) {
+    found.push(
+      `verifier must be loopback or a unix socket, got ${verifier} — a routable verifier can be bypassed`,
+    );
+  }
+  return found;
+};
+
+/**
+ * Render the `forward_auth` block for one protected route.
+ *
+ * ```ts
+ * const caddyfile = `vnc.example.com {
+ * ${accessForwardAuth({ verifier: '127.0.0.1:9101', body: ['reverse_proxy 127.0.0.1:6080'] })}
+ * }
+ * `;
+ * ```
+ *
+ * ⛔ ONE VERIFIER ENDPOINT PER ACCESS APPLICATION. The AUD is fixed in the verifier's own config,
+ *   never carried in this request — so two applications mean two `uri`s (or two verifiers), not
+ *   one endpoint told which app to check. An AUD the request can influence is the vulnerability.
+ *
+ * ⚠️ `forward_auth` COPIES THE VERIFIER'S RESPONSE BACK TO THE CLIENT on any non-2xx, which is why
+ *   the verifier answers a bare 401 with no body: whatever it returns is what the browser sees.
+ */
+export const accessForwardAuth = (props: AccessForwardAuthProps): string => {
+  const problems = verifierProblems(props.verifier);
+  if (problems.length > 0) throw new Error(`accessForwardAuth: ${problems.join('; ')}`);
+
+  const indent = props.indent ?? '\t';
+  const uri = props.uri ?? '/access/verify';
+  const headers = props.copyHeaders ?? DEFAULT_COPY_HEADERS;
+
+  const lines = [
+    ...(props.body ?? []),
+    `forward_auth ${props.verifier} {`,
+    `${indent}uri ${uri}`,
+    // ⚠️ `copy_headers` with a block, one field per line: the single-line form is also valid but
+    //   diffs badly, and this list is exactly where a security review needs to read a change.
+    `${indent}copy_headers {`,
+    ...headers.map((header) => `${indent}${indent}${header}`),
+    `${indent}}`,
+    '}',
+  ];
+
+  return lines.map((line) => `${indent}${line}`).join('\n');
+};

package/src/caddy/index.ts

@@ -9,6 +9,16 @@
  * ⛔ NOTHING IS ADOPTED SILENTLY: a running config that is not the declared one needs `--adopt`.
  * Guide, order of file and load, adoption, `--resume` and secrets: docs/caddy.md.
  */
+/**
+ * ★ `accessForwardAuth` is Caddyfile TEXT, not a resource: it renders the `forward_auth` block
+ *   that puts a Cloudflare Access check in front of a route, paired with the verifier in
+ *   `@homeflare/cloudflare/access-auth`. Guide: docs/access-auth.md.
+ */
+export {
+  accessForwardAuth,
+  verifierProblems,
+  type AccessForwardAuthProps,
+} from './access-forward-auth.ts';
 export type {
   CaddyAdmin,
   CaddyAdminListener,

package/src/caddy/providers.test.ts

@@ -220,10 +220,14 @@ describe('the barrel', () => {
       'CaddyConfigProvider',
       'CaddyUnreachableError',
       'DEFAULT_ADMIN_ADDRESS',
+      // Caddyfile TEXT for an Access-protected route, not a resource — see
+      // access-forward-auth.ts. It pairs with @homeflare/cloudflare/access-auth.
+      'accessForwardAuth',
       'caddyAdminLayer',
       'caddyProviders',
       'caddyWithFile',
       'localCaddyAdmin',
+      'verifierProblems',
     ]);
   });
 });