@homeflare/alchemy 0.43.0 → 0.45.0

package/src/release/binary-alias.test.ts

@@ -7,19 +7,19 @@
  *   `replace`, reported success, and left no binary on disk; the next deploy put it back.
  */
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
-import { mkdir, mkdtemp, rm, stat, symlink } from 'node:fs/promises';
+import { mkdtemp, rm, stat, symlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { type HostRunner } from '../launchd/runner.ts';
 import { localRunner } from '../launchd/local-runner.ts';
 import { reconcileBinary } from './binary-lifecycle.ts';
-import { VMALERT_TEXT, realEngine } from './fake-engine.ts';
+import { VMALERT_TEXT, makeBinaryDirectory, realEngine } from './fake-engine.ts';
 import { VMUTILS_URL, fakeTransport, syntheticRelease, vmalertProps } from './fake-release.ts';
 
 let tmp = '';
 beforeEach(async () => {
   tmp = await mkdtemp(join(tmpdir(), 'hf-alias-'));
-  await mkdir(join(tmp, 'real', 'vmutils-1.151.0'), { recursive: true });
+  await makeBinaryDirectory(join(tmp, 'real', 'vmutils-1.151.0'));
   await symlink(join(tmp, 'real'), join(tmp, 'link'));
 });
 afterEach(async () => {

package/src/release/binary-claims.test.ts

@@ -7,16 +7,16 @@
  *   `vmalert: noop, vmalert-logs: delete` — and the file `vmalert` still declared was gone.
  */
 import { afterEach, beforeEach, expect, test } from 'bun:test';
-import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { VMALERT_TEXT, realEngine } from './fake-engine.ts';
+import { VMALERT_TEXT, makeBinaryDirectory, realEngine } from './fake-engine.ts';
 import { VMUTILS_URL } from './fake-release.ts';
 
 let dir = '';
 beforeEach(async () => {
   dir = join(await mkdtemp(join(tmpdir(), 'hf-claims-')), 'vmutils-1.151.0');
-  await mkdir(dir);
+  await makeBinaryDirectory(dir);
 });
 afterEach(async () => {
   await rm(join(dir, '..'), { force: true, recursive: true });

package/src/release/binary-directory-umask.test.ts

@@ -0,0 +1,65 @@
+/**
+ * THE FIXTURE DIRECTORIES DO NOT DEPEND ON THE UMASK (fake-engine.ts `makeBinaryDirectory`).
+ *
+ * 🔴 MEASURED 2026-10-01: under CT100's login umask 0002 six tests in binary-alias and
+ *   binary-claims failed with "directory ... is writable by group or other (mode 0775)", because
+ *   their fixtures made the directory with a bare `mkdir`; under 022 they passed. Only the
+ *   fixtures were wrong — Release.Binary is right to refuse a directory its group may write, and
+ *   the last test here pins that it still does, on the real filesystem.
+ *
+ * Each test sets the umask for itself and puts the process's own back in a `finally`; bun runs the
+ * tests of a file one after another, so nothing else sees the changed mask. Every directory is
+ * under a fresh `mkdtemp`, removed in `afterEach`.
+ */
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdir, mkdtemp, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { VMALERT_TEXT, makeBinaryDirectory, realEngine } from './fake-engine.ts';
+
+let tmp = '';
+beforeEach(async () => {
+  tmp = await mkdtemp(join(tmpdir(), 'hf-umask-'));
+});
+afterEach(async () => {
+  await rm(tmp, { force: true, recursive: true });
+});
+
+/** Run `body` under `mask`, and give the process its own umask back whatever happens. */
+const underUmask = async <T>(mask: number, body: () => Promise<T>): Promise<T> => {
+  const before = process.umask(mask);
+  try {
+    return await body();
+  } finally {
+    process.umask(before);
+  }
+};
+const modeOf = async (path: string): Promise<number> => (await stat(path)).mode & 0o777;
+const octal = (mode: number): string => mode.toString(8).padStart(4, '0');
+
+describe('makeBinaryDirectory', () => {
+  for (const mask of [0o000, 0o002, 0o022]) {
+    test(`makes 0755 directories under umask ${octal(mask)}, the leaf and the ones on the way`, async () => {
+      const leaf = join(tmp, 'real', 'vmutils-1.151.0');
+      await underUmask(mask, () => makeBinaryDirectory(leaf));
+      expect(octal(await modeOf(leaf))).toBe('0755');
+      expect(octal(await modeOf(join(tmp, 'real')))).toBe('0755');
+    });
+  }
+
+  test('⛔ the control: a bare mkdir under 0002 is the 0775 the resource refuses, and still is', async () => {
+    const dir = join(tmp, 'vmutils-1.151.0');
+    await underUmask(0o002, () => mkdir(dir));
+    expect(octal(await modeOf(dir))).toBe('0775');
+    await expect(realEngine().deploy({ vmalert: dir })).rejects.toThrow(
+      `directory ${dir} is writable by group or other (mode 0775)`,
+    );
+  });
+
+  test('the real engine installs into one made under a group-writable umask', async () => {
+    const dir = join(tmp, 'vmutils-1.151.0');
+    await underUmask(0o002, () => makeBinaryDirectory(dir));
+    expect(await realEngine().deploy({ vmalert: dir })).toEqual({ vmalert: 'create' });
+    expect(await Bun.file(join(dir, 'vmalert')).text()).toBe(VMALERT_TEXT);
+  });
+});

package/src/release/fake-engine.ts

@@ -6,6 +6,7 @@
  * ⛔ TEST-ONLY, like fake-release.ts: no provider imports it and it is not on the barrel. Every
  *   directory a test passes must be under its own `mkdtemp`; nothing here chooses a path.
  */
+import { mkdir } from 'node:fs/promises';
 import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
 import * as HttpClient from 'effect/unstable/http/HttpClient';
@@ -20,6 +21,20 @@ import { BINARY, VMALERT_REQUEST, VMUTILS_URL, syntheticRelease } from './fake-r
 /** vmalert's bytes as text, to compare with what a test reads off the disk. */
 export const VMALERT_TEXT = new TextDecoder().decode(BINARY.vmalert);
 
+/**
+ * A directory Release.Binary accepts, whatever the process umask. The resource refuses a directory
+ * its group or others may write (binary-lifecycle.ts `directoryReady`), and a bare `mkdir` asks for
+ * 0777 and loses the umask's bits: 0775 under the 0002 a CT100 login shell has, so the suite
+ * passed under 022 and failed six tests under 0002 (measured 2026-10-01). A umask only ever takes
+ * bits away, so asking for 0755 outright can come out no wider than 0755 under any mask; the
+ * directories made on the way (`recursive`) get the same mode. Every test directory goes through
+ * here; the resource's refusal is right and stays as it is.
+ */
+export const makeBinaryDirectory = async (path: string): Promise<string> => {
+  await mkdir(path, { mode: 0o755, recursive: true });
+  return path;
+};
+
 /** One stack over localRunner; `deploy` takes logical id → directory; `gets` counts downloads. */
 export const realEngine = () => {
   const { catalog, vmutils } = syntheticRelease();

package/src/valkey/acl-attrs.ts

@@ -0,0 +1,98 @@
+/**
+ * `Valkey.AclFile` props attributes.
+ *
+ * ⛔ PASSWORDS BY REFERENCE, NEVER IN STATE. Each ACL user's password is a `{ fromEnv }` reference
+ *   (see `secrets/write-only.ts`); the value exists only in the deploying process's memory and on
+ *   the wire to the server. State stores an scrypt SEAL, so a later plan can check "is the value
+ *   in my environment the one I wrote" without holding anything a reader could send to Valkey.
+ * ★ THE KEY PREFIX IS THE ISOLATION. `~<name>:*` limits a seat to its own keyspace; a seat
+ *   gets `WRITE` only where its job writes. The deny list (`-scan -randomkey -dbsize -pubsub`)
+ *   closes keyspace/channel enumeration, matching `homeflare-ct100/src/valkey-acl.ts`.
+ * ★ THE COMMAND ALLOW-LIST IS A FIXED PROFILE, NOT A PROP. `profile: 'seat'` carries the seat
+ *   allow-list with pub/sub restricted to the user's own channel; `profile: 'service'` carries
+ *   `+@all -@dangerous` with channels from the declaration, for one consumer that owns the whole
+ *   instance (LiteLLM's cache user on `:6380`); `profile: 'monitor'` carries the key-less,
+ *   channel-less `redis_exporter` rule set (ct100#117). It is deliberately no free-form rules
+ *   prop: a declaration could widen itself, which would let a seat request `FLUSHALL` or
+ *   `ACL SETUSER` and defeat the isolation the resource enforces.
+ */
+import type { FromEnv } from '../secrets/write-only.ts';
+
+/** The fixed rule set a user carries. */
+export type ValkeyAclProfile = 'seat' | 'service' | 'monitor';
+
+/** One ACL user, limited to a key prefix and a fixed command allow-list. */
+export interface ValkeyAclUser {
+  /** The username (matches the seat name). */
+  readonly name: string;
+  /**
+   * The key pattern the user may touch, sent as `~<keyPrefix>`. Optional: a `seat` defaults to
+   * exactly `<name>:*` — CT100's template (`homeflare-ct100/src/valkey-acl.ts`) — and a
+   * `service` defaults to `*` (the whole instance; LiteLLM's cache user declares `hf-litellm:*`).
+   * A `monitor` must not carry one — it is key-less (`resetkeys`), so a declared prefix is
+   * refused (`ValkeyAclMonitorKeyPrefix`).
+   */
+  readonly keyPrefix?: string;
+  /** Channel globs without `&`. Defaults to the key prefix. Seats must keep `<name>:*`;
+   * monitors must have none. Services may declare a separate channel namespace. */
+  readonly channelPatterns?: ReadonlyArray<string>;
+  /** The fixed allow-list this user carries. */
+  readonly profile: ValkeyAclProfile;
+  /** The password, by reference. */
+  readonly password: FromEnv;
+}
+
+/** The ACL users of one instance. */
+export interface ValkeyAclFileProps {
+  /** The instance the ACL file belongs to — matches the `Valkey.Instance` name. */
+  readonly instance: string;
+  /** The ACL users, keyed by username. */
+  readonly users: Readonly<Record<string, ValkeyAclUser>>;
+  /**
+   * ★ EXCLUSIVE OWNERSHIP IS OPT-IN, OFF BY DEFAULT (round-3 finding 1). `true` means this
+   *   declaration is the ONLY writer of the instance's ACL: reconcile `ACL DELUSER`s every user
+   *   it did not declare. `false` — the default — leaves never-managed users (CT100's key-less
+   *   `monitor` for `redis_exporter`, an operator's debugging user) untouched and reports them
+   *   with a warning, because reconcile cannot know what a template renderer or a human still
+   *   needs. The measured incident: reconcile deleted CT100's `monitor` and closed the
+   *   exporter's connection.
+   *   Removing a previously managed user from the declaration always revokes it.
+   */
+  readonly exclusive?: boolean;
+}
+
+/** One user's live ACL fields, parsed from `ACL LIST`. Every field except `passwordSeal`
+ * comes from the server's own echo (measured semantics in `acl-form.ts`'s header), so `diff`
+ * can see exactly what `reconcile`'s read-back asserts — a user widened or disabled outside the
+ * stack must show up as an update, never as a silent no-op. */
+export interface ValkeyAclUserAttributes {
+  readonly name: string;
+  /** The first live key pattern without its `~`, or `''` when the user has none. */
+  readonly keyPrefix: string;
+  /** Any live key pattern beyond the first, `~`-stripped. This family declares exactly one
+   * pattern per user, so a non-empty list means the ACL was widened outside the stack. */
+  readonly extraKeyPatterns: ReadonlyArray<string>;
+  /** The live channel patterns as the server echoes them (`&claude:*`; `&*` is all channels;
+   * an empty list — the bare `resetchannels` marker — means no channel access at all). */
+  readonly channelPatterns: ReadonlyArray<string>;
+  /** The profile the live rule set was recognised as — `unrecognized` when the rules match
+   * neither fixed profile (something outside the stack edited them). */
+  readonly profile: ValkeyAclProfile | 'unrecognized';
+  /** The live `on` flag: a user this family declared but the host disabled is drift. */
+  readonly on: boolean;
+  /** The live `nopass` flag: a passwordless user authenticates as nobody, which bypasses the
+   * per-seat password boundary, so it always drifts for a user this family manages. */
+  readonly nopass: boolean;
+  /** Any password token (`#<hash>`, `>pw`, `<pw`) present. Never the value. */
+  readonly hasPassword: boolean;
+  /** The scrypt seal of the password the family last wrote, threaded from state. */
+  readonly passwordSeal: string;
+}
+
+/** The live ACL attributes of one instance. */
+export interface ValkeyAclFileAttributes {
+  readonly instance: string;
+  readonly users: Readonly<Record<string, ValkeyAclUserAttributes>>;
+  /** Last managed declaration, separate from observed users. Optional for earlier state. */
+  readonly managedUsers?: ReadonlyArray<string>;
+}

package/src/valkey/acl-compare.ts

@@ -0,0 +1,57 @@
+/**
+ * Comparison logic between a live `ACL LIST` line and the declaration: whether a user matches,
+ * what profile its rules were recognised as, and set equality over the token lists.
+ *
+ * Extracted from `acl-form.ts` (which owns building and parsing) to keep both files under the cap;
+ * tests import these comparisons directly.
+ */
+import type { ValkeyAclProfile, ValkeyAclUser } from './acl-attrs.ts';
+import type { ParsedAclUser } from './acl-form.ts';
+import {
+  MONITOR_RULES,
+  SEAT_RULES,
+  SERVICE_RULES,
+  declaredChannels,
+  declaredKeyPatterns,
+} from './acl-profiles.ts';
+
+/** Whether two string lists carry the same members — order ignored, duplicates and extras caught
+ * by the length guard (the echo's order is the server's business; a wider or duplicated list is
+ * not). */
+export const sameSet = (a: ReadonlyArray<string>, b: ReadonlyArray<string>): boolean => {
+  if (a.length !== b.length) return false;
+  const sa = new Set(a);
+  const sb = new Set(b);
+  if (sa.size !== sb.size) return false;
+  for (const x of sa) if (!sb.has(x)) return false;
+  return true;
+};
+
+/**
+ * Recognise a live rule set as one of the three fixed profiles. The echo is normalised first
+ * (`acl-form.ts`'s header): drop the `-@all` baseline the server echoes for a reset user, since
+ * the seat set never grants it back and a `+@all` cancels it. `unrecognized` means something
+ * outside the stack edited the rules — that user drifts.
+ */
+export const inferProfile = (rules: ReadonlyArray<string>): ValkeyAclProfile | 'unrecognized' => {
+  const normalised = rules.filter((rule) => rule !== '-@all');
+  if (sameSet(normalised, SEAT_RULES)) return 'seat';
+  if (sameSet(normalised, SERVICE_RULES)) return 'service';
+  if (sameSet(rules, MONITOR_RULES)) return 'monitor';
+  return 'unrecognized';
+};
+
+/**
+ * Whether a live user line is exactly as declared — every visible disagreement is a match failure,
+ * not just a changed prefix (a widened rule set, a disabled flag, or a stripped password is exactly
+ * what reconcile exists to restore). Passwords are never compared here: the live line holds only a
+ * hash, and the stored seal is what `diff`/`reconcile` check for rotation.
+ */
+export const matchesDeclared = (live: ParsedAclUser, user: ValkeyAclUser): boolean =>
+  live.name === user.name &&
+  live.on &&
+  !live.nopass &&
+  live.hasPassword &&
+  sameSet(live.keyPatterns, declaredKeyPatterns(user)) &&
+  sameSet(live.channelPatterns, declaredChannels(user)) &&
+  inferProfile(live.rules) === user.profile;

package/src/valkey/acl-connection.ts

@@ -0,0 +1,13 @@
+/** Map the whole connection operation, including socket acquisition and AUTH transport errors. */
+import * as Effect from 'effect/Effect';
+import { resolveValkeyConnection } from './connection-service.ts';
+import { ValkeyInstanceUnreachable } from './errors.ts';
+import type { ValkeySocketError } from './transport.ts';
+
+export const aclUnreachable = (instance: string) => (_error: ValkeySocketError) =>
+  Effect.gen(function* () {
+    const config = yield* resolveValkeyConnection(instance);
+    return yield* Effect.fail(
+      new ValkeyInstanceUnreachable({ instance, host: config.host, port: config.port }),
+    );
+  });

package/src/valkey/acl-delete.test.ts

@@ -0,0 +1,127 @@
+/** Delete removes only the users the declaration managed, never what the instance merely holds. */
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { makeValkeyAclFileHandlers } from './acl.ts';
+import type { ValkeyAclFileAttributes, ValkeyAclFileProps } from './acl-attrs.ts';
+import { managedUserNames } from './acl-managed.ts';
+import { readWithExecutor } from './acl-ops.ts';
+import { reconcileWithExecutor } from './acl-reconcile.ts';
+import { type FakeValkey, makeFakeValkey } from './fake-valkey.ts';
+import { connection, context, run } from './handler-test-fixture.ts';
+
+const seat = {
+  name: 'seat',
+  profile: 'seat',
+  password: { fromEnv: 'TEST_VALKEY_SEAT_PW' },
+} as const;
+const draft = {
+  name: 'draft',
+  profile: 'seat',
+  password: { fromEnv: 'TEST_VALKEY_DRAFT_PW' },
+} as const;
+const foreign = {
+  name: 'operator',
+  profile: 'seat',
+  password: { fromEnv: 'TEST_VALKEY_OPERATOR_PW' },
+} as const;
+const props: ValkeyAclFileProps = { instance: 'scratch', users: { seat } };
+const env = { TEST_VALKEY_SEAT_PW: 'FAKE-seat' };
+const admin = 'user admin on >FAKE-admin ~* &* +@all';
+const operator = 'user operator on >FAKE-operator ~* &* +@all';
+const monitor = 'user monitor on >FAKE-monitor -@all';
+const draftAcl = 'user draft on >FAKE-draft ~draft:* &draft:* +@all';
+const survivors = ['admin', 'monitor', 'operator'];
+
+const instance = (): FakeValkey =>
+  makeFakeValkey({ acl: { admin, operator, monitor }, passwords: { admin: 'FAKE-admin' } });
+// The state the engine would hold after a real reconcile: every observed user in `users`,
+// ownership recorded separately in `managedUsers`.
+const stored = (fake: FakeValkey): Promise<ValkeyAclFileAttributes> =>
+  Effect.runPromise(reconcileWithExecutor(fake, props, undefined, env, 'admin'));
+const remove = (
+  fake: FakeValkey,
+  olds: ValkeyAclFileProps,
+  output: ValkeyAclFileAttributes,
+): Promise<void> =>
+  run(makeValkeyAclFileHandlers(connection(fake)).delete({ ...context, olds, output }));
+const delusers = (fake: FakeValkey) =>
+  fake.commands.filter(({ args }) => args[1] === 'DELUSER').map(({ args }) => args);
+
+test('delete removes only the managed user, not an operator, monitor or admin user', async () => {
+  const fake = instance();
+  const output = await stored(fake);
+  expect(Object.keys(output.users).sort()).toEqual(['monitor', 'operator', 'seat']);
+  expect(output.managedUsers).toEqual(['seat']);
+  await remove(fake, props, output);
+  expect(delusers(fake)).toEqual([['ACL', 'DELUSER', 'seat']]);
+  expect([...fake.acl.keys()].sort()).toEqual(survivors);
+});
+
+test('delete on state written before managedUsers existed falls back as managedUserNames does', async () => {
+  const fake = instance();
+  const { managedUsers: _dropped, ...legacy } = await stored(fake);
+  expect(legacy).not.toHaveProperty('managedUsers');
+  expect(managedUserNames(legacy, props)).toEqual(['seat']);
+  await remove(fake, props, legacy);
+  expect(delusers(fake)).toEqual([['ACL', 'DELUSER', ...managedUserNames(legacy, props)]]);
+  expect([...fake.acl.keys()].sort()).toEqual(survivors);
+});
+
+test('read-without-output seals empty, so legacy state with no managedUsers and no previous answers []', async () => {
+  // ★ Apply.ts calls reconcile with `olds: undefined` and `output: attr` on both create (:924)
+  //   and replacement (:1321), never a bare read. The empty-seal fallback in `managedUserNames`
+  //   (`previous === undefined`) therefore only ever fires on state that predates `managedUsers`
+  //   AND was last read without an output — where `[]` is the safe default, not a Valkey adoption
+  //   bug. A read with no output mints an empty seal (acl-ops.ts `toUserAttributes`), and with no
+  //   `previous` to lean on, that is indistinguishable from "nothing we ever managed".
+  const fake = makeFakeValkey({ acl: { seat: 'user seat on >FAKE-seed ~seat:* +@read' } });
+  const bare = await Effect.runPromise(readWithExecutor(fake, 'scratch'));
+  expect(bare.users.seat?.passwordSeal).toBe('');
+  expect(managedUserNames({ instance: 'scratch', users: bare.users }, undefined)).toEqual([]);
+});
+
+test('delete after a failed update spares users the last good reconcile never managed', async () => {
+  // The engine commits the NEW declaration as `olds` before reconcile runs. If reconcile then
+  // fails, `olds` names `draft` and a foreign live user (`operator`) while `output.managedUsers`
+  // still holds the last successful ownership record.
+  const fake = instance();
+  const output = await stored(fake);
+  const failedUpdate: ValkeyAclFileProps = {
+    instance: 'scratch',
+    users: { seat, draft, operator: foreign },
+  };
+  await remove(fake, failedUpdate, output);
+  expect(delusers(fake)).toEqual([['ACL', 'DELUSER', 'seat']]);
+  expect([...fake.acl.keys()].sort()).toEqual(survivors);
+});
+
+test('delete removes only output.managedUsers, never users listed in olds', async () => {
+  const fake = instance();
+  const output = await stored(fake);
+  // `olds` claims live users (`operator`) and reserved names (`admin`, `default`) that the
+  // declaration no longer manages. Only `output.managedUsers` may be targets.
+  const corruptedOlds: ValkeyAclFileProps = {
+    instance: 'scratch',
+    users: { seat, operator: foreign, admin: foreign, default: foreign },
+  } as unknown as ValkeyAclFileProps;
+  await remove(fake, corruptedOlds, { ...output, managedUsers: ['seat'] });
+  expect(delusers(fake)).toEqual([['ACL', 'DELUSER', 'seat']]);
+  expect([...fake.acl.keys()].sort()).toEqual(['admin', 'monitor', 'operator']);
+});
+
+test('delete after a partially-applied failed update spares users it never managed', async () => {
+  // The engine committed the new declaration as `olds` before reconcile ran. Reconcile then
+  // partially applied `draft` before failing; `output` still carries the last successful
+  // ownership record (`managedUsers: ['seat']`) but `draft` is already live.
+  const partial = makeFakeValkey({
+    acl: { admin, operator, monitor, draft: draftAcl },
+    passwords: { admin: 'FAKE-admin' },
+  });
+  const output = await stored(partial);
+  expect(Object.keys(output.users).sort()).toEqual(['draft', 'monitor', 'operator', 'seat']);
+  expect(output.managedUsers).toEqual(['seat']);
+  const failedUpdate: ValkeyAclFileProps = { instance: 'scratch', users: { seat, draft } };
+  await remove(partial, failedUpdate, output);
+  expect(delusers(partial)).toEqual([['ACL', 'DELUSER', 'seat']]);
+  expect([...partial.acl.keys()].sort()).toEqual(['admin', 'draft', 'monitor', 'operator']);
+});