@homeflare/alchemy 0.42.0 → 0.44.0

package/src/valkey/acl-reconcile.ts

@@ -0,0 +1,180 @@
+/**
+ * `Valkey.AclFile` reconcile core, against any executor. Extracted from the old single-file
+ * `acl.ts` and reworked for the round-3 findings:
+ *
+ * ★ GATE FIRST (F3). `CONFIG GET aclfile` non-empty → `ValkeyAclFileRendered`, BEFORE any write.
+ *   The rendered file is the source of truth (CT100: openbao-agent renders it and a runtime
+ *   write reverts — the measured WRONGPASS seat). `delete` runs the same gate (`acl.ts`).
+ * ★ RUNTIME-ONLY WRITES, NO `ACL SAVE` (F3). In kit-owned mode (empty aclfile) `ACL SAVE`
+ *   measurably errors on 8.1.10 — "This instance is not configured to use an ACL file" — so the
+ *   kit-owned family never calls it. ACL state is runtime state, not data: it does not survive
+ *   a restart even with appendonly (measured), so this family re-asserts on every reconcile.
+ * ★ NEVER-MANAGED USERS ARE PRESERVED BY DEFAULT (F1). `planAclUsers` only DELUSERs those
+ *   under `exclusive: true`; removing a previously declared user always revokes it.
+ */
+import * as Effect from 'effect/Effect';
+import { type Environment, type FromEnv, resolveAll, seal } from '../secrets/write-only.ts';
+import type {
+  ValkeyAclFileAttributes,
+  ValkeyAclFileProps,
+  ValkeyAclUser,
+  ValkeyAclUserAttributes,
+} from './acl-attrs.ts';
+import { managedUserNames } from './acl-managed.ts';
+import { matchesDeclared } from './acl-compare.ts';
+import {
+  buildDelUserArgs,
+  buildSetUserArgs,
+  passwordState,
+  planAclUsers,
+  refusalBeforeWrite,
+} from './acl-form.ts';
+import { readAclFileConfig, readParsedUsers, toUserAttributes } from './acl-ops.ts';
+import {
+  ValkeyAclFileRendered,
+  ValkeyAclPasswordMissing,
+  ValkeyAclReadbackFailed,
+  type ValkeyError,
+} from './errors.ts';
+import { type ValkeyExecutor, ValkeyServerError, type ValkeyTransportError } from './transport.ts';
+
+/** The reconcile core: gate on the rendered aclfile, refuse bad declarations, resolve every
+ * password ONCE, plan against the live ACL, write, then re-read and verify (S10: never trust
+ * the write). `stored` is the state this stack already holds (`output`); it is what adoption
+ * lacks, and its absence is what makes the first plan a write. `self` is the connection's own
+ * username — never managed, like `default`. */
+export const reconcileWithExecutor = (
+  executor: ValkeyExecutor,
+  props: ValkeyAclFileProps,
+  stored: ValkeyAclFileAttributes | undefined,
+  env: Environment = process.env,
+  self?: string,
+  previous?: ValkeyAclFileProps,
+): Effect.Effect<ValkeyAclFileAttributes, ValkeyError | ValkeyTransportError> =>
+  Effect.gen(function* () {
+    // ⛔ BEFORE ANY WRITE. The aclfile gate stands in front of the declaration refusals and the
+    //   writes: on a rendered instance this family writes nothing at all, good or bad.
+    const aclfile = yield* readAclFileConfig(executor);
+    if (aclfile !== '') {
+      return yield* Effect.fail(
+        new ValkeyAclFileRendered({ instance: props.instance, path: aclfile }),
+      );
+    }
+
+    // Declaration refusals (reserved names, split record key, seat prefix escapes, glob chars in
+    // names, monitor-with-keyPrefix). Read hides `default` and the connection username, so a
+    // declaration of either would otherwise look absent and `reset` the kit's own credential.
+    const refused = refusalBeforeWrite(props.instance, props.users, self);
+    if (refused !== undefined) return yield* Effect.fail(refused);
+
+    // Resolve every declared password ONCE, at call time. A user the plan does not need to write
+    // does not demand its variable — that is the `unknown` state, and it never drifts (diff).
+    const refs: Record<string, FromEnv> = {};
+    for (const [name, user] of Object.entries(props.users)) refs[name] = user.password;
+    const { values } = resolveAll(refs, env);
+
+    const live = yield* readParsedUsers(executor, self);
+    const { create, update, remove, undeclared } = planAclUsers(
+      props.users,
+      live,
+      props.exclusive,
+      managedUserNames(stored, previous),
+    );
+
+    // Preserve-by-default (F1): never-managed users need exclusive ownership to be removed.
+    // Previously managed users are revoked; `default`/`self` never appear in this live map.
+    for (const name of undeclared) {
+      yield* Effect.logWarning(
+        `Valkey.AclFile "${props.instance}": live ACL user "${name}" is not declared; ${
+          remove.includes(name)
+            ? 'it is scheduled for deletion (previously managed or exclusive: true).'
+            : 'it was left alone (exclusive: false).'
+        }`,
+      );
+    }
+
+    // Rotate: live and shaped exactly as declared, but the stored seal is absent (an adopted
+    // user) or disagrees with the value this process holds — the reset-first rewrite is what
+    // retires the old password, so the seal change must reach the server, not only the state.
+    const rotate = Object.entries(props.users)
+      .filter(([name, user]) => {
+        const liveUser = live[name];
+        const sealed = stored?.users[name]?.passwordSeal ?? '';
+        return (
+          liveUser !== undefined &&
+          matchesDeclared(liveUser, user) &&
+          passwordState(sealed, values[name]) === 'stale'
+        );
+      })
+      .map(([, user]) => user);
+
+    // Every write re-sends the password (`reset` clears it), so a write without the value would
+    // leave the user unable to authenticate — refused, naming the first user and variable. The
+    // refusal is checked for EVERY user before the first write, so a missing variable never
+    // leaves half of the plan applied.
+    const writes = [...create, ...update, ...rotate];
+    const writeList: Array<{ readonly user: ValkeyAclUser; readonly password: string }> = [];
+    for (const user of writes) {
+      const password = values[user.name];
+      if (password === undefined) {
+        return yield* Effect.fail(
+          new ValkeyAclPasswordMissing({
+            instance: props.instance,
+            user: user.name,
+            variable: user.password.fromEnv,
+          }),
+        );
+      }
+      writeList.push({ user, password });
+    }
+
+    // ⛔ RUNTIME-ONLY. `reset`-first SETUSER per write; DELUSER for removed managed users or `exclusive`. No
+    //   `ACL SAVE`: in the only mode this family writes (empty aclfile) it measurably errors on
+    //   8.1.10. See the header note for the restart semantics that follow.
+    for (const { user, password } of writeList) {
+      const reply = yield* executor.send(yield* buildSetUserArgs(user, password));
+      if (reply.kind === 'error') {
+        return yield* Effect.fail(new ValkeyServerError({ detail: reply.message }));
+      }
+    }
+    if (remove.length > 0) {
+      const reply = yield* executor.send(buildDelUserArgs(remove));
+      if (reply.kind === 'error') {
+        return yield* Effect.fail(new ValkeyServerError({ detail: reply.message }));
+      }
+    }
+
+    // Read back and verify: every declared user, exactly as declared (S10). Undeclared leftovers
+    // fail under `exclusive` or when a previously managed user was scheduled for revocation.
+    const after = yield* readParsedUsers(executor, self);
+    for (const [name, user] of Object.entries(props.users)) {
+      const parsed = after[name];
+      if (parsed === undefined || !matchesDeclared(parsed, user)) {
+        return yield* Effect.fail(
+          new ValkeyAclReadbackFailed({ instance: props.instance, user: name }),
+        );
+      }
+    }
+    if (props.exclusive || remove.length > 0) {
+      for (const name of Object.keys(after)) {
+        if (props.users[name] === undefined && (props.exclusive || remove.includes(name))) {
+          return yield* Effect.fail(
+            new ValkeyAclReadbackFailed({ instance: props.instance, user: name }),
+          );
+        }
+      }
+    }
+
+    // Seals: keep what the store held for users this run did not write, mint a fresh one for
+    // every user it did. A user absent from `stored` (adoption) gets its first seal here.
+    const seals: Record<string, string> = {};
+    for (const name of Object.keys(props.users)) {
+      seals[name] = stored?.users[name]?.passwordSeal ?? '';
+    }
+    for (const { user, password } of writeList) seals[user.name] = seal({ password });
+    const users: Record<string, ValkeyAclUserAttributes> = {};
+    for (const [name, parsed] of Object.entries(after)) {
+      users[name] = { ...toUserAttributes(parsed), passwordSeal: seals[name] ?? '' };
+    }
+    return { instance: props.instance, users, managedUsers: Object.keys(props.users).sort() };
+  });

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

@@ -0,0 +1,69 @@
+/**
+ * Declaring `default` or the connection username must fail before any `ACL SETUSER`.
+ * Read hides those names, so a plan would otherwise create them and `reset` the
+ * credential the kit authenticates with.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { reconcileWithExecutor } from './acl-reconcile.ts';
+import { ValkeyAclReservedUser } from './errors.ts';
+import { makeFakeValkey } from './fake-valkey.ts';
+import type { ValkeyAclUser } from './acl-attrs.ts';
+
+const fails = <A, E>(eff: Effect.Effect<A, E>): Promise<E> => Effect.runPromise(Effect.flip(eff));
+
+const env = { CLAUDE_PW: 'FAKE-seat-password' };
+const claude: ValkeyAclUser = {
+  name: 'claude',
+  keyPrefix: 'claude:*',
+  profile: 'seat',
+  password: { fromEnv: 'CLAUDE_PW' },
+};
+
+const setuser = (fake: ReturnType<typeof makeFakeValkey>): ReadonlyArray<unknown> =>
+  fake.commands.filter((command) => command.args[0] === 'ACL' && command.args[1] === 'SETUSER');
+
+describe('reserved ACL names', () => {
+  test('refuses to declare the connection username before any SETUSER', async () => {
+    const fake = makeFakeValkey({ acl: { admin: 'user admin on >FAKE-seed ~* +@all' } });
+    const admin: ValkeyAclUser = {
+      name: 'admin',
+      keyPrefix: 'admin:*',
+      profile: 'seat',
+      password: { fromEnv: 'CLAUDE_PW' },
+    };
+    const error = await fails(
+      reconcileWithExecutor(
+        fake,
+        { instance: 'valkey-seats', users: { admin, claude } },
+        undefined,
+        env,
+        'admin',
+      ),
+    );
+    expect(setuser(fake)).toEqual([]);
+    expect(error).toBeInstanceOf(ValkeyAclReservedUser);
+    expect(fake.acl.get('admin')).toContain('~* resetchannels +@all');
+  });
+
+  test('refuses to declare default before any SETUSER', async () => {
+    const fake = makeFakeValkey({ acl: { default: 'user default off' } });
+    const reserved: ValkeyAclUser = {
+      name: 'default',
+      keyPrefix: '*',
+      profile: 'service',
+      password: { fromEnv: 'CLAUDE_PW' },
+    };
+    const error = await fails(
+      reconcileWithExecutor(
+        fake,
+        { instance: 'valkey-seats', users: { default: reserved } },
+        undefined,
+        env,
+        'admin',
+      ),
+    );
+    expect(error).toBeInstanceOf(ValkeyAclReservedUser);
+    expect(setuser(fake)).toEqual([]);
+  });
+});

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

@@ -0,0 +1,94 @@
+/** A removed seat must lose access without claiming ownership of an operator's users. */
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { makeValkeyAclFileHandlers } from './acl.ts';
+import type { ValkeyAclFileProps } from './acl-attrs.ts';
+import { reconcileWithExecutor } from './acl-reconcile.ts';
+import { makeFakeValkey } from './fake-valkey.ts';
+import { config, connection, context, required, run } from './handler-test-fixture.ts';
+import { ValkeySocketError } from './transport.ts';
+import type { withValkey } from './connection.ts';
+
+const props: ValkeyAclFileProps = {
+  instance: 'scratch',
+  users: {
+    seat: { name: 'seat', profile: 'seat', password: { fromEnv: 'TEST_VALKEY_SEAT_PW' } },
+  },
+};
+const news: ValkeyAclFileProps = { instance: 'scratch', users: {} };
+const env = { TEST_VALKEY_SEAT_PW: 'FAKE-seat' };
+const operator = 'user operator on >FAKE-operator ~* &* +@all';
+
+for (const legacy of [false, true]) {
+  test(`removing a managed seat plans an update and revokes AUTH, preserving never-managed users (legacy=${legacy})`, async () => {
+    const fake = makeFakeValkey({ acl: { operator }, passwords: { admin: 'FAKE-admin' } });
+    const created = await Effect.runPromise(reconcileWithExecutor(fake, props, undefined, env));
+    const operatorBefore = fake.acl.get('operator');
+    const stored = legacy ? { instance: created.instance, users: created.users } : created;
+    expect(
+      await Effect.runPromise(fake.send(['AUTH', 'seat', env.TEST_VALKEY_SEAT_PW])),
+    ).toMatchObject({ value: 'OK' });
+    const handlers = makeValkeyAclFileHandlers(connection(fake));
+    expect(
+      await run(required(handlers.diff)({ ...context, olds: props, news, output: stored })),
+    ).toEqual({ action: 'update' });
+    // A drift read must preserve ownership independently of all the live users it observes.
+    const observed = required(
+      await run(required(handlers.read)({ ...context, olds: props, output: stored })),
+    );
+    expect(observed.managedUsers).toEqual(['seat']);
+    const output = await run(
+      handlers.reconcile({ ...context, olds: props, news, output: observed }),
+    );
+    expect(output.managedUsers).toEqual([]);
+    expect(Object.keys(output.users)).toEqual(['operator']);
+    expect(fake.acl.get('operator')).toBe(operatorBefore);
+    expect(
+      fake.commands.filter(({ args }) => args[1] === 'DELUSER').map(({ args }) => args),
+    ).toEqual([['ACL', 'DELUSER', 'seat']]);
+    expect(
+      await Effect.runPromise(fake.send(['AUTH', 'seat', env.TEST_VALKEY_SEAT_PW])),
+    ).toMatchObject({ kind: 'error' });
+    expect(await run(required(handlers.diff)({ ...context, olds: news, news, output }))).toEqual({
+      action: 'noop',
+    });
+    await run(handlers.reconcile({ ...context, olds: news, news, output }));
+    expect(fake.commands.filter(({ args }) => args[1] === 'DELUSER')).toHaveLength(1);
+  });
+}
+
+test('a removed seat re-added by another writer fails readback even without exclusive ownership', async () => {
+  const fake = makeFakeValkey({
+    reAddAfterWrite: { name: 'seat', line: 'user seat on nopass -@all' },
+  });
+  fake.acl.set('seat', 'user seat on nopass -@all');
+  const error = await Effect.runPromise(
+    Effect.flip(
+      reconcileWithExecutor(
+        fake,
+        news,
+        { instance: 'scratch', users: {}, managedUsers: ['seat'] },
+        {},
+      ),
+    ),
+  );
+  expect(error).toMatchObject({ _tag: 'ValkeyAclReadbackFailed', user: 'seat' });
+});
+
+test('ACL socket acquisition failure is mapped before the executor callback can run', async () => {
+  const connect: typeof withValkey = () =>
+    Effect.fail(new ValkeySocketError({ reason: 'ECONNREFUSED' }));
+  const handlers = makeValkeyAclFileHandlers(connect);
+  for (const operation of [
+    required(handlers.read)({ ...context, olds: props, output: undefined }),
+    handlers.reconcile({ ...context, olds: props, news: props, output: undefined }),
+    handlers.delete({ ...context, olds: props, output: { instance: 'scratch', users: {} } }),
+  ]) {
+    expect(await run(Effect.flip(operation))).toMatchObject({
+      _tag: 'ValkeyInstanceUnreachable',
+      instance: 'scratch',
+      host: config.host,
+      port: config.port,
+    });
+  }
+});

package/src/valkey/acl-seat-prefix.test.ts

@@ -0,0 +1,111 @@
+/**
+ * A seat profile must not grant another seat's keys. `keyPrefix` is interpolated as
+ * `~${keyPrefix}` and read-back compares the declaration to itself, so `*` or `grok:*`
+ * on user `claude` would converge and widen the keyspace. Refused before any `ACL SETUSER`.
+ * `*` stays legal on the service profile — that user owns the instance.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import type { ValkeyAclUser } from './acl-attrs.ts';
+import { reconcileWithExecutor } from './acl-reconcile.ts';
+import { ValkeyAclSeatKeyPrefix } from './errors.ts';
+import { makeFakeValkey } from './fake-valkey.ts';
+
+const fails = <A, E>(eff: Effect.Effect<A, E>): Promise<E> => Effect.runPromise(Effect.flip(eff));
+
+const env = { CLAUDE_PW: 'FAKE-seat-password', LITELLM_PW: 'FAKE-cache-password' };
+
+const setuser = (fake: ReturnType<typeof makeFakeValkey>): ReadonlyArray<unknown> =>
+  fake.commands.filter((command) => command.args[0] === 'ACL' && command.args[1] === 'SETUSER');
+
+describe('seat key prefix', () => {
+  test("a seat keyPrefix of '*' issues no SETUSER", async () => {
+    const fake = makeFakeValkey({ acl: { admin: 'user admin on >FAKE-seed ~* +@all' } });
+    const claude: ValkeyAclUser = {
+      name: 'claude',
+      keyPrefix: '*',
+      profile: 'seat',
+      password: { fromEnv: 'CLAUDE_PW' },
+    };
+    const error = await fails(
+      reconcileWithExecutor(
+        fake,
+        { instance: 'valkey-seats', users: { claude } },
+        undefined,
+        env,
+        'admin',
+      ),
+    );
+    expect(setuser(fake)).toEqual([]);
+    expect(error).toBeInstanceOf(ValkeyAclSeatKeyPrefix);
+    expect(fake.acl.has('claude')).toBe(false);
+  });
+
+  test('a seat keyPrefix that only shares the name prefix issues no SETUSER', async () => {
+    const fake = makeFakeValkey();
+    const claude: ValkeyAclUser = {
+      name: 'claude',
+      keyPrefix: 'claude:grok:*',
+      profile: 'seat',
+      password: { fromEnv: 'CLAUDE_PW' },
+    };
+    const error = await fails(
+      reconcileWithExecutor(
+        fake,
+        { instance: 'valkey-seats', users: { claude } },
+        undefined,
+        env,
+        'admin',
+      ),
+    );
+    expect(setuser(fake)).toEqual([]);
+    expect(error).toBeInstanceOf(ValkeyAclSeatKeyPrefix);
+  });
+
+  test("a seat keyPrefix of another user's pattern issues no SETUSER", async () => {
+    const fake = makeFakeValkey();
+    const claude: ValkeyAclUser = {
+      name: 'claude',
+      keyPrefix: 'grok:*',
+      profile: 'seat',
+      password: { fromEnv: 'CLAUDE_PW' },
+    };
+    const error = await fails(
+      reconcileWithExecutor(
+        fake,
+        { instance: 'valkey-seats', users: { claude } },
+        undefined,
+        env,
+        'admin',
+      ),
+    );
+    expect(setuser(fake)).toEqual([]);
+    expect(error).toBeInstanceOf(ValkeyAclSeatKeyPrefix);
+  });
+
+  test("a service keyPrefix of '*' is still written", async () => {
+    const fake = makeFakeValkey();
+    const litellm: ValkeyAclUser = {
+      name: 'litellm',
+      keyPrefix: '*',
+      profile: 'service',
+      password: { fromEnv: 'LITELLM_PW' },
+    };
+    const output = await Effect.runPromise(
+      reconcileWithExecutor(
+        fake,
+        { instance: 'valkey-litellm', users: { litellm } },
+        undefined,
+        env,
+        'admin',
+      ),
+    );
+    // The fake now echoes &*, matching the measured live echo; read-back must succeed.
+    expect(output.users.litellm?.profile).toBe('service');
+    const wrote = fake.commands.filter(
+      (command) => command.args[0] === 'ACL' && command.args[1] === 'SETUSER',
+    );
+    expect(wrote.length).toBe(1);
+    expect(wrote[0]?.args.includes('~*')).toBe(true);
+  });
+});

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

@@ -0,0 +1,54 @@
+/** Validate declarations before any write; a seat name becomes part of a glob. */
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import type { ValkeyError } from './errors.ts';
+import type { ValkeyAclUser } from './acl-attrs.ts';
+import { reconcileWithExecutor } from './acl-reconcile.ts';
+import { makeValkeyAclFileHandlers } from './acl.ts';
+import { makeFakeValkey } from './fake-valkey.ts';
+import { connection, context, required, run } from './handler-test-fixture.ts';
+
+const seat: ValkeyAclUser = {
+  name: 'seat',
+  profile: 'seat',
+  password: { fromEnv: 'TEST_VALKEY_USER_PW' },
+};
+const invalid: ReadonlyArray<readonly [ValkeyAclUser, ValkeyError['_tag']]> = [
+  ...['*', '?', '[ab]', '\\'].map(
+    (glob) => [{ ...seat, name: `seat${glob}` }, 'ValkeyAclNameGlob'] as const,
+  ),
+  [{ ...seat, channelPatterns: ['*'] }, 'ValkeyAclChannelPatterns'],
+  [{ ...seat, profile: 'monitor', keyPrefix: '*' }, 'ValkeyAclMonitorKeyPrefix'],
+  [{ ...seat, profile: 'monitor', channelPatterns: ['*'] }, 'ValkeyAclChannelPatterns'],
+];
+
+for (const [user, tag] of invalid) {
+  test(`refuse ${user.name} ${user.profile} with ${tag} in diff and reconcile`, async () => {
+    const fake = makeFakeValkey();
+    const props = { instance: 'scratch', users: { [user.name]: user } };
+    const error = await Effect.runPromise(
+      Effect.flip(
+        reconcileWithExecutor(fake, props, undefined, { TEST_VALKEY_USER_PW: 'FAKE-password' }),
+      ),
+    );
+    expect(error._tag).toBe(tag);
+    expect(fake.commands.some(({ args }) => args[1] === 'SETUSER')).toBe(false);
+    const handlers = makeValkeyAclFileHandlers(connection(fake));
+    const failure = await run(
+      Effect.flip(
+        required(handlers.diff)({ ...context, olds: props, news: props, output: undefined }),
+      ),
+    );
+    expect(failure._tag).toBe(tag);
+  });
+}
+
+test('aclfile probe failure is not treated as an empty file path', async () => {
+  const fake = makeFakeValkey();
+  fake.config.delete('aclfile');
+  const failure = await Effect.runPromise(
+    Effect.flip(reconcileWithExecutor(fake, { instance: 'scratch', users: {} }, undefined, {})),
+  );
+  expect(failure._tag).toBe('ValkeyServerError');
+  expect(fake.commands.some(({ args }) => args[1] === 'SETUSER')).toBe(false);
+});