@homeflare/alchemy 0.43.0 → 0.45.0

package/src/valkey/acl-form.ts

@@ -0,0 +1,239 @@
+/**
+ * Pure helpers for `Valkey.AclFile`: building `ACL SETUSER` argument lists, parsing `ACL LIST`
+ * lines, computing the create/update/remove plan, and the refusals that run before any write.
+ *
+ * ⛔ THE COMMAND ALLOW-LIST IS A FIXED PROFILE, NOT PROP (see `acl-profiles.ts`). Widening in the
+ *   declaration would let a seat request `FLUSHALL` or `ACL SETUSER` and defeat the isolation the
+ *   resource exists to enforce.
+ * ★ `reset` IS LOAD-BEARING, MEASURED ON VALKEY 9.1.1 (2026-09-29). `ACL SETUSER` ADDS rules; a
+ *   second `>pw` without `reset` left TWO valid password hashes and two key patterns — a rotated
+ *   password kept authenticating forever. `reset` first, rebuild, makes the command idempotent:
+ *   after it the user holds exactly one password, one key pattern and one channel pattern.
+ * ★ THE PASSWORD GOES ON THE WIRE AS `#<sha256>`, NOT `>plaintext` (round-3). Valkey accepts the
+ *   hash form (ct100#117's templates render `#{{ . | sha256Hex }}` and the 9.1.1 scratch
+ *   authenticated against it, measured 2026-09-30): the plaintext never leaves the deploying
+ *   process's memory at all, and a command echo or audit log holds only an unreversible hash.
+ * ★ THE SERVER'S ECHO IS NORMALISED, ALSO MEASURED. `ACL LIST` answers the stored rule list, and:
+ *   the `reset` baseline appears as an explicit `-@all` token (which survives until `+@all`
+ *   cancels it — a fresh user written WITHOUT `reset` echoed `-@all` too); `allchannels` echoes
+ *   as the `&*` pattern; an empty channel list echoes the bare `resetchannels` marker (which
+ *   means NO channel access — PUBLISH as such a user answered `NOPERM`); `reset` itself is
+ *   dropped from the echo. Every comparison normalises that: drop `-@all` before comparing
+ *   `SEAT_RULES` (the seat set never grants it back), compare the other sets directly, ignore
+ *   the bare `resetchannels` marker when parsing.
+ */
+import { sha256 } from 'alchemy/Util/sha256';
+import * as Effect from 'effect/Effect';
+import type { ValkeyAclUser } from './acl-attrs.ts';
+import { declaredChannels, declaredKeyPatterns, profileRules } from './acl-profiles.ts';
+import {
+  ValkeyAclChannelPatterns,
+  ValkeyAclMonitorKeyPrefix,
+  ValkeyAclNameGlob,
+  ValkeyAclParseError,
+  ValkeyAclReservedUser,
+  ValkeyAclSeatKeyPrefix,
+  ValkeyAclUserNameMismatch,
+} from './errors.ts';
+import { type Environment, type FromEnv, resolveAll, sealMatches } from '../secrets/write-only.ts';
+import { matchesDeclared } from './acl-compare.ts';
+
+/** Glob characters a username must not carry: the name is interpolated into patterns. */
+const NAME_GLOB = /[*?[\]\\]/;
+
+/** The `#<sha256>` token `ACL SETUSER` accepts in place of `>plaintext`. */
+export const passwordToken = (password: string): Effect.Effect<string> =>
+  Effect.map(sha256(password), (hash) => `#${hash}`);
+
+/**
+ * The exact `ACL SETUSER` argument list the family issues for one user: reset the blank user,
+ * enable it, one password hash, channels reset to the profile's scope, the declared key pattern,
+ * then the profile's rules. `password` is the RESOLVED value (already checked present by the
+ * caller), never stored, never returned; only its sha256 crosses the wire.
+ */
+export const buildSetUserArgs = (
+  user: ValkeyAclUser,
+  password: string,
+): Effect.Effect<ReadonlyArray<string>> =>
+  Effect.map(passwordToken(password), (token) => [
+    'ACL',
+    'SETUSER',
+    user.name,
+    'reset',
+    'on',
+    token,
+    'resetchannels',
+    ...declaredChannels(user),
+    ...declaredKeyPatterns(user),
+    ...profileRules(user.profile),
+  ]);
+
+/** One `ACL LIST` line, parsed. `rules` holds the `+`/`-` tokens the server echoes (normalised,
+ * see the header); `keyPatterns`/`channelPatterns` keep their `~`/`&`; flags are booleans. */
+export interface ParsedAclUser {
+  readonly name: string;
+  readonly on: boolean;
+  readonly nopass: boolean;
+  /** Any password token (`#<hash>`, `>pw`, `<pw`) present. */
+  readonly hasPassword: boolean;
+  readonly keyPatterns: ReadonlyArray<string>;
+  readonly channelPatterns: ReadonlyArray<string>;
+  readonly rules: ReadonlyArray<string>;
+}
+
+/** Tokens the server echoes as state markers, never as rules or patterns. */
+const MARKER_TOKENS = new Set(['resetchannels', 'resetkeys', 'resetpass', 'reseton', 'resetoff']);
+
+/** Parse one `ACL LIST` line into `ParsedAclUser`. Throws `ValkeyAclParseError` on a malformed
+ * line. */
+export const parseAclLine = (line: string): ParsedAclUser => {
+  const parts = line.split(' ');
+  if (parts[0] !== 'user' || parts[1] === undefined || parts[1] === '') {
+    throw new ValkeyAclParseError();
+  }
+  const on = parts[2] === 'on';
+  const nopass = parts.includes('nopass');
+  const keyPatterns: string[] = [];
+  const channelPatterns: string[] = [];
+  const rules: string[] = [];
+  let hasPassword = false;
+  for (const part of parts.slice(2)) {
+    if (part.startsWith('~')) keyPatterns.push(part);
+    else if (part.startsWith('&')) channelPatterns.push(part);
+    else if (part.startsWith('>') || part.startsWith('<') || part.startsWith('#'))
+      hasPassword = true;
+    else if (part.startsWith('+') || part.startsWith('-')) rules.push(part);
+    else if (MARKER_TOKENS.has(part)) continue;
+    // Anything else (a flag a future Valkey adds) is neither a rule nor a pattern nor a
+    // credential; ignored.
+  }
+  return { name: parts[1], on, nopass, hasPassword, keyPatterns, channelPatterns, rules };
+};
+
+/** Whether a seat-profile user's key prefix escapes its own keyspace. `keyPrefix` goes on the
+ * wire as `~<keyPrefix>`, so read-back compares the declaration to itself: `*`, `grok:*` or
+ * `claude:grok:*` would converge and grant keys the seat does not own. CT100's template renders
+ * exactly `~${user}:*`. A service user is exempt: owning the whole instance is what that
+ * profile is for (LiteLLM's cache user, `*`). A monitor user is keyless and may not carry a
+ * prefix at all. */
+export const seatKeyPrefixEscapes = (user: ValkeyAclUser): boolean =>
+  user.profile === 'seat' && (user.keyPrefix ?? `${user.name}:*`) !== `${user.name}:*`;
+
+/** Refusals must run before any `ACL SETUSER`. A mismatched record key would split one user into
+ * two records; a reserved name would reset the credential this kit authenticates with; a glob in
+ * a name would widen the patterns the profile fixes; a seat prefix or monitor key prefix
+ * contradicts the profile's fixed shape. */
+export const refusalBeforeWrite = (
+  instance: string,
+  users: Readonly<Record<string, ValkeyAclUser>>,
+  self?: string,
+):
+  | ValkeyAclUserNameMismatch
+  | ValkeyAclReservedUser
+  | ValkeyAclSeatKeyPrefix
+  | ValkeyAclMonitorKeyPrefix
+  | ValkeyAclNameGlob
+  | ValkeyAclChannelPatterns
+  | undefined => {
+  for (const [key, user] of Object.entries(users)) {
+    if (user.name !== key) {
+      return new ValkeyAclUserNameMismatch({ instance, recordKey: key, user: user.name });
+    }
+    if (user.name === 'default' || user.name === self) {
+      return new ValkeyAclReservedUser({ instance, user: user.name });
+    }
+    const glob = NAME_GLOB.exec(user.name);
+    if (glob !== null) {
+      return new ValkeyAclNameGlob({ instance, user: user.name, chars: glob[0] });
+    }
+    if (seatKeyPrefixEscapes(user)) {
+      return new ValkeyAclSeatKeyPrefix({
+        instance,
+        user: user.name,
+        keyPrefix: user.keyPrefix ?? `${user.name}:*`,
+      });
+    }
+    if (
+      user.channelPatterns !== undefined &&
+      ((user.profile === 'monitor' && user.channelPatterns.length > 0) ||
+        (user.profile === 'seat' &&
+          (user.channelPatterns.length !== 1 || user.channelPatterns[0] !== `${user.name}:*`)))
+    )
+      return new ValkeyAclChannelPatterns({ instance, user: user.name });
+    if (user.profile === 'monitor' && user.keyPrefix !== undefined) {
+      return new ValkeyAclMonitorKeyPrefix({
+        instance,
+        user: user.name,
+        keyPrefix: user.keyPrefix,
+      });
+    }
+  }
+  return undefined;
+};
+
+/** How the environment compares to what the family last wrote for one user, by seal.
+ * `unknown` — the variable is unset here, so the plan cannot tell (never drift: a plan-only
+ * environment must not report every user as rotated). `stale` — no seal yet (an adopted user) or
+ * the seal disagrees with the current value. `match` — the seal was made from this value. */
+export type PasswordState = 'unknown' | 'stale' | 'match';
+
+export const passwordState = (sealed: string, value: string | undefined): PasswordState => {
+  if (value === undefined) return 'unknown';
+  if (sealed === '') return 'stale';
+  return sealMatches(sealed, { password: value }) ? 'match' : 'stale';
+};
+
+/** The password value of one user in `env`, or undefined when the reference is missing. */
+export const resolvedPassword = (user: ValkeyAclUser, env: Environment): string | undefined => {
+  const ref: Record<string, FromEnv> = { [user.name]: user.password };
+  const { values, missing } = resolveAll(ref, env);
+  if (missing.length > 0) return undefined;
+  return values[user.name];
+};
+
+/** The plan reconcile walks: `create` (absent live), `update` (present but not exactly as
+ * declared — see `matchesDeclared`), `remove` (previously managed users removed from the
+ * declaration, plus all undeclared users under `exclusive: true`) and `undeclared` (all live
+ * names outside the current declaration, reported with their deletion/preservation decision). */
+export interface AclUserPlan {
+  readonly create: ReadonlyArray<ValkeyAclUser>;
+  readonly update: ReadonlyArray<ValkeyAclUser>;
+  readonly remove: ReadonlyArray<string>;
+  readonly undeclared: ReadonlyArray<string>;
+}
+
+export const planAclUsers = (
+  declared: Readonly<Record<string, ValkeyAclUser>>,
+  live: Readonly<Record<string, ParsedAclUser>>,
+  exclusive = false,
+  managed: ReadonlyArray<string> = [],
+): AclUserPlan => {
+  const create: ValkeyAclUser[] = [];
+  const update: ValkeyAclUser[] = [];
+  const undeclared: string[] = [];
+  for (const [name, user] of Object.entries(declared)) {
+    const liveUser = live[name];
+    // ⛔ UPDATE MUST CATCH EVERY VISIBLE DISAGREEMENT, NOT JUST A CHANGED PREFIX. A user whose
+    // rules were widened outside the stack (or disabled, or stripped of its password) is exactly
+    // what this family exists to restore; a prefix-only criterion would leave it failing
+    // read-back forever instead of converging on the next plan.
+    if (liveUser === undefined) create.push(user);
+    else if (!matchesDeclared(liveUser, user)) update.push(user);
+  }
+  for (const name of Object.keys(live)) {
+    if (declared[name] === undefined) undeclared.push(name);
+  }
+  return {
+    create,
+    update,
+    remove: exclusive ? undeclared : undeclared.filter((name) => managed.includes(name)),
+    undeclared,
+  };
+};
+
+/** The exact `ACL DELUSER` argument list. */
+export const buildDelUserArgs = (users: ReadonlyArray<string>): ReadonlyArray<string> => [
+  'ACL',
+  'DELUSER',
+  ...users,
+];

package/src/valkey/acl-managed.ts

@@ -0,0 +1,13 @@
+/** Observed users are not ownership: remember the declaration independently of ACL LIST. */
+import type { ValkeyAclFileAttributes, ValkeyAclFileProps } from './acl-attrs.ts';
+
+export const managedUserNames = (
+  stored: ValkeyAclFileAttributes | undefined,
+  previous?: ValkeyAclFileProps,
+): ReadonlyArray<string> =>
+  stored?.managedUsers ??
+  // Compatibility with state written before managedUsers existed: the prior declaration is
+  // authoritative. Executor-only callers can identify users we wrote by their stored seals.
+  (previous === undefined
+    ? Object.keys(stored?.users ?? {}).filter((name) => stored?.users[name]?.passwordSeal !== '')
+    : Object.keys(previous.users));

package/src/valkey/acl-ops.ts

@@ -0,0 +1,122 @@
+/**
+ * `Valkey.AclFile` READ operations, engine-independent: reading the live ACL into attributes,
+ * and the aclfile probe the write path gates on. Extracted from `acl.ts` (the Resource and its
+ * handlers) to keep files under the cap; `acl.test.ts` drives these against `fake-valkey.ts`.
+ *
+ * ⛔ PASSWORD BY REFERENCE. Each `user.password` is a `{ fromEnv }` reference; state stores a
+ *   scrypt seal so the next plan can tell whether the value changed without holding the value.
+ *   See `secrets/write-only.ts` and `acl-attrs.ts`.
+ * ★ NO OWNERSHIP MARK (H1). `read` answers `Unowned` for a match (the same rule as
+ *   `Postgres.Database`), so an adopted instance's ACL needs `adopt(true)`.
+ * ★ THE SEALS THREAD THROUGH `output` THE WAY `LiteLLM.MCPServer`'s `credentialSeal` DOES
+ *   (`mcp-server.ts`): `read` never re-seals — it keeps the seal the store already holds. The
+ *   write path (`acl-reconcile.ts`) mints a fresh one only for a user it actually wrote.
+ */
+import * as Effect from 'effect/Effect';
+import { inferProfile } from './acl-compare.ts';
+import type { ValkeyAclFileAttributes, ValkeyAclUserAttributes } from './acl-attrs.ts';
+import { type ParsedAclUser, parseAclLine } from './acl-form.ts';
+import { ValkeyAclParseError } from './errors.ts';
+import {
+  type ValkeyExecutor,
+  ValkeyServerError,
+  type ValkeyTransportError,
+  arrayPairs,
+} from './transport.ts';
+
+/** Parse the live `ACL LIST` into its user lines, keyed by username. `self` is the username the
+ * stack's own connection authenticates as (the instance's admin user) — never this family's to
+ * manage: removing it would lock the kit out of the instance, and a `service` user cannot carry
+ * ACL commands anyway, so it is skipped exactly like `default`. A line that does not parse fails
+ * the whole read: a user this family cannot see is a user it cannot converge. */
+export const readParsedUsers = (
+  executor: ValkeyExecutor,
+  self?: string,
+): Effect.Effect<
+  Readonly<Record<string, ParsedAclUser>>,
+  ValkeyAclParseError | ValkeyTransportError
+> =>
+  Effect.gen(function* () {
+    const reply = yield* executor.send(['ACL', 'LIST']);
+    if (reply.kind === 'error') {
+      return yield* Effect.fail(new ValkeyServerError({ detail: reply.message }));
+    }
+    if (reply.kind !== 'array') {
+      return yield* Effect.fail(
+        new ValkeyServerError({ detail: 'ACL LIST did not answer an array' }),
+      );
+    }
+    const users: Record<string, ParsedAclUser> = {};
+    for (const line of reply.values) {
+      if (line === null) continue;
+      const parsed = yield* Effect.try({
+        try: () => parseAclLine(line),
+        catch: () => new ValkeyAclParseError(),
+      });
+      if (parsed.name === 'default' || parsed.name === self) continue;
+      users[parsed.name] = parsed;
+    }
+    return users;
+  });
+
+/** One user's live attributes from its parsed line. Passwords are never read (Valkey returns only
+ * hashes, and this family stores seals, not values), so the seal starts empty and `read` threads
+ * the stored one through `output`. */
+export const toUserAttributes = (line: ParsedAclUser): ValkeyAclUserAttributes => ({
+  name: line.name,
+  keyPrefix: line.keyPatterns[0]?.slice(1) ?? '',
+  extraKeyPatterns: line.keyPatterns.slice(1).map((pattern) => pattern.slice(1)),
+  channelPatterns: [...line.channelPatterns],
+  profile: inferProfile(line.rules),
+  on: line.on,
+  nopass: line.nopass,
+  hasPassword: line.hasPassword,
+  passwordSeal: '',
+});
+
+/** Live attributes from parsed lines. Passwords are never read (Valkey returns only hashes, and
+ * this family stores seals, not values), so the seal starts empty and `read` threads the stored
+ * one through `output`. */
+const toAttributes = (
+  instance: string,
+  parsed: Readonly<Record<string, ParsedAclUser>>,
+): ValkeyAclFileAttributes => {
+  const users: Record<string, ValkeyAclUserAttributes> = {};
+  for (const [name, line] of Object.entries(parsed)) {
+    users[name] = toUserAttributes(line);
+  }
+  return { instance, users };
+};
+
+/** Read the live ACL users into attributes, against any executor. `self` (the connection's own
+ * username) is skipped along with `default` — see `readParsedUsers`. */
+export const readWithExecutor = (
+  executor: ValkeyExecutor,
+  instance: string,
+  self?: string,
+): Effect.Effect<ValkeyAclFileAttributes, ValkeyAclParseError | ValkeyTransportError> =>
+  Effect.map(readParsedUsers(executor, self), (parsed) => toAttributes(instance, parsed));
+
+/** Probe `CONFIG GET aclfile`: empty means the kit owns ACL state (runtime SETUSER/DELUSER only —
+ * never `ACL SAVE`, which errors without a configured aclfile); non-empty means a rendered file
+ * is the source of truth and the write path refuses (see `ValkeyAclFileRendered`). */
+export const readAclFileConfig = (
+  executor: ValkeyExecutor,
+): Effect.Effect<string, ValkeyTransportError> =>
+  Effect.gen(function* () {
+    const reply = yield* executor.send(['CONFIG', 'GET', 'aclfile']);
+    if (reply.kind === 'error') {
+      return yield* Effect.fail(new ValkeyServerError({ detail: reply.message }));
+    }
+    if (reply.kind !== 'array') {
+      return yield* Effect.fail(
+        new ValkeyServerError({ detail: 'CONFIG GET aclfile did not answer an array' }),
+      );
+    }
+    const path = arrayPairs(reply.values).get('aclfile');
+    if (path === undefined || path === null)
+      return yield* Effect.fail(
+        new ValkeyServerError({ detail: 'CONFIG GET aclfile omitted aclfile' }),
+      );
+    return path;
+  });

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

@@ -0,0 +1,118 @@
+/** Round-3 regressions: shared ACL ownership, observability and namespace boundaries. */
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { buildSetUserArgs, parseAclLine } from './acl-form.ts';
+import { reconcileWithExecutor } from './acl-reconcile.ts';
+import type { ValkeyAclUser } from './acl-attrs.ts';
+import { makeFakeValkey } from './fake-valkey.ts';
+import { required } from './handler-test-fixture.ts';
+import { MONITOR_COMMANDS } from './acl-profiles.ts';
+
+const env = { TEST_VALKEY_USER_PW: 'FAKE-test-password' };
+const monitor: ValkeyAclUser = {
+  name: 'monitor',
+  profile: 'monitor',
+  password: { fromEnv: 'TEST_VALKEY_USER_PW' },
+};
+const monitorLine = `user monitor on #${'a'.repeat(64)} resetchannels ${MONITOR_COMMANDS}`;
+const run = Effect.runPromise;
+
+test('undeclared monitor survives default reconcile, with its ACL unchanged', async () => {
+  const fake = makeFakeValkey({ acl: { monitor: monitorLine } });
+  const before = fake.acl.get('monitor');
+  const output = await run(
+    reconcileWithExecutor(fake, { instance: 'scratch', users: {} }, undefined, {}),
+  );
+  expect(output.users.monitor?.profile).toBe('monitor');
+  expect(fake.acl.get('monitor')).toBe(before);
+  expect(fake.commands.some(({ args }) => args[1] === 'DELUSER')).toBe(false);
+});
+
+test('exclusive ownership deletes undeclared users, preserving default and admin', async () => {
+  const fake = makeFakeValkey({
+    acl: {
+      monitor: monitorLine,
+      default: 'user default off -@all',
+      admin: 'user admin on >FAKE-admin ~* &* +@all',
+    },
+  });
+  await run(
+    reconcileWithExecutor(
+      fake,
+      { instance: 'scratch', users: {}, exclusive: true },
+      undefined,
+      {},
+      'admin',
+    ),
+  );
+  expect([...fake.acl.keys()].sort()).toEqual(['admin', 'default']);
+});
+
+test('monitor converges with exactly ct100#117 observability rules and no keys/channels', async () => {
+  const fake = makeFakeValkey();
+  const props = { instance: 'scratch', users: { monitor } };
+  const first = await run(reconcileWithExecutor(fake, props, undefined, env));
+  expect(first.users.monitor?.profile).toBe('monitor');
+  const parsed = parseAclLine(required(fake.acl.get('monitor')));
+  expect(parsed.rules).toEqual(MONITOR_COMMANDS.split(' '));
+  expect(parsed.keyPatterns).toEqual([]);
+  expect(parsed.channelPatterns).toEqual([]);
+  const count = fake.commands.filter(({ args }) => args[1] === 'SETUSER').length;
+  await run(reconcileWithExecutor(fake, props, first, env));
+  expect(fake.commands.filter(({ args }) => args[1] === 'SETUSER')).toHaveLength(count);
+});
+
+test('service channel scope defaults to keyPrefix; foreign PUBLISH is NOPERM', async () => {
+  const fake = makeFakeValkey();
+  const service: ValkeyAclUser = {
+    ...monitor,
+    name: 'cache',
+    profile: 'service',
+    keyPrefix: 'cache:*',
+  };
+  await run(
+    reconcileWithExecutor(fake, { instance: 'scratch', users: { cache: service } }, undefined, env),
+  );
+  expect(await run(fake.send(['AUTH', 'cache', env.TEST_VALKEY_USER_PW]))).toEqual({
+    kind: 'bulk',
+    value: 'OK',
+  });
+  expect(await run(fake.send(['PUBLISH', 'cache:events', 'x']))).toEqual({
+    kind: 'bulk',
+    value: '0',
+  });
+  expect(await run(fake.send(['PUBLISH', 'foreign:events', 'x']))).toMatchObject({
+    kind: 'error',
+    message: 'NOPERM No permissions to access a channel',
+  });
+});
+
+test('service may declare separate channel patterns, including no channels', async () => {
+  const service: ValkeyAclUser = {
+    ...monitor,
+    name: 'cache',
+    profile: 'service',
+    keyPrefix: 'cache:*',
+    channelPatterns: ['events:*'],
+  };
+  const args = await run(buildSetUserArgs(service, env.TEST_VALKEY_USER_PW));
+  expect(args).toContain('&events:*');
+  expect(args).not.toContain('&cache:*');
+  expect(
+    (
+      await run(buildSetUserArgs({ ...service, channelPatterns: [] }, env.TEST_VALKEY_USER_PW))
+    ).some((arg) => arg.startsWith('&')),
+  ).toBe(false);
+});
+
+test('fake echoes hashes and baseline, adds passwords, and reset revokes the old password', async () => {
+  const fake = makeFakeValkey();
+  await run(fake.send(['ACL', 'SETUSER', 'seat', 'on', '>FAKE-first', '+ping']));
+  await run(fake.send(['ACL', 'SETUSER', 'seat', '>FAKE-second']));
+  expect(fake.acl.get('seat')).toContain('-@all +ping');
+  expect(fake.acl.get('seat')).not.toContain('FAKE-');
+  expect(await run(fake.send(['AUTH', 'seat', 'FAKE-first']))).toMatchObject({ value: 'OK' });
+  await run(fake.send(['ACL', 'SETUSER', 'seat', 'reset', 'on', '>FAKE-second', '+ping']));
+  expect(await run(fake.send(['AUTH', 'seat', 'FAKE-first']))).toMatchObject({ kind: 'error' });
+  expect(await run(fake.send(['AUTH', 'seat', 'FAKE-second']))).toMatchObject({ value: 'OK' });
+});

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

@@ -0,0 +1,38 @@
+/**
+ * The published seat example must emit the key pattern CT100 already renders.
+ * `homeflare-ct100/src/valkey-acl.ts` `seatLine` is `~${user}:*` (`~claude:*`).
+ * A kit example of `seat:claude:*` would `reset` that user onto `~seat:claude:*`
+ * and the next template render would put `~claude:*` back.
+ */
+import { readFileSync } from 'node:fs';
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { buildSetUserArgs } from './acl-form.ts';
+import type { ValkeyAclUser } from './acl-attrs.ts';
+
+const templatePattern = (user: string): string => `~${user}:*`;
+
+describe('published key prefix', () => {
+  test("example declaration's ~ pattern equals the CT100 seat template", async () => {
+    const doc = readFileSync(new URL('../../docs/valkey.md', import.meta.url), 'utf8');
+    const examples = [...doc.matchAll(/name: '(\w+)',\s*\n\s*keyPrefix: '([^']+)'/g)].map(
+      (match) => ({ name: match[1] ?? '', keyPrefix: match[2] ?? '' }),
+    );
+    expect(examples).toEqual([
+      { name: 'claude', keyPrefix: 'claude:*' },
+      { name: 'grok', keyPrefix: 'grok:*' },
+    ]);
+    for (const example of examples) {
+      const user: ValkeyAclUser = {
+        name: example.name,
+        keyPrefix: example.keyPrefix,
+        profile: 'seat',
+        password: { fromEnv: 'X' },
+      };
+      expect(await Effect.runPromise(buildSetUserArgs(user, 'FAKE-password'))).toContain(
+        templatePattern(example.name),
+      );
+      expect(`~${example.keyPrefix}`).toBe(templatePattern(example.name));
+    }
+  });
+});

package/src/valkey/acl-profiles.ts

@@ -0,0 +1,81 @@
+/**
+ * The fixed ACL profiles this family can express, as the exact rule tokens the wire carries.
+ *
+ * ⛔ THE COMMAND ALLOW-LIST IS A FIXED PROFILE, NOT A PROP (see `acl-attrs.ts`). Every rule set
+ *   here mirrors `homeflare-ct100/src/valkey-acl.ts` (ct100#117) token for token, measured on the
+ *   9.1.1 scratch; a free-form rules prop would let a declaration widen itself and request
+ *   `FLUSHALL` or `ACL SETUSER`, defeating the isolation the resource exists to enforce.
+ *
+ * ★ THE `monitor` PROFILE EXISTS BECAUSE CT100 CARRIES A KEY-LESS `monitor` USER FOR
+ *   `redis_exporter` (ct100#117). Before it existed, `seat` and `service` were the only profiles,
+ *   so `monitor` was undeclared on every CT100-style instance and reconcile DELETED it —
+ *   exporter's connection closed (measured 2026-09-30). `MONITOR_COMMANDS` is exactly what
+ *   `redis_exporter` v1.92.1 issues, measured: `client|setname`, `info`, `command|info`,
+ *   `commandlog|len` (Valkey 8.1+), `config|get`, `latency|latest`, `latency|histogram`,
+ *   `slowlog|get`, `slowlog|len`, plus `ping`. No keys (`resetkeys`), no channels
+ *   (`resetchannels`), no `client|list` (this exporter version never sends it, so it is not
+ *   granted).
+ */
+import type { ValkeyAclProfile, ValkeyAclUser } from './acl-attrs.ts';
+
+/** The seat command allow-list — fixed, mirrored from `homeflare-ct100/src/valkey-acl.ts`. */
+export const SEAT_COMMANDS =
+  '+@read +@write +@string +@hash +@list +@set +@sortedset +@stream +@pubsub +@connection ' +
+  '+@transaction -@dangerous -@admin -keys -flushall -flushdb -monitor -acl -config ' +
+  '-shutdown -debug';
+
+/** Commands that close keyspace/channel enumeration, measured as a leak without them
+ * (seat-wiring-spec §5). */
+const DENY = '-scan -randomkey -dbsize -pubsub';
+
+/** What `redis_exporter` v1.92.1 needs and nothing else (ct100#117's `monitor` note). */
+export const MONITOR_COMMANDS =
+  '-@all +ping +client|setname +info +command|info +commandlog|len +config|get ' +
+  '+latency|latest +latency|histogram +slowlog|get +slowlog|len';
+
+/** The fixed rule sets, as the exact tokens sent after `reset`. */
+export const SEAT_RULES: ReadonlyArray<string> = [...SEAT_COMMANDS.split(' '), ...DENY.split(' ')];
+export const SERVICE_RULES: ReadonlyArray<string> = ['+@all', '-@dangerous', ...DENY.split(' ')];
+export const MONITOR_RULES: ReadonlyArray<string> = MONITOR_COMMANDS.split(' ');
+
+/** The rule set one profile carries. */
+export const profileRules = (profile: ValkeyAclProfile): ReadonlyArray<string> =>
+  profile === 'seat' ? SEAT_RULES : profile === 'service' ? SERVICE_RULES : MONITOR_RULES;
+
+/**
+ * The effective key prefix of one declared user.
+ *
+ * - `monitor` is key-less (ct100#117's `resetkeys`): it has no prefix, and a declaration that
+ *   gives it one is refused (`ValkeyAclMonitorKeyPrefix`).
+ * - `seat` is pinned to `<name>:*` — the CT100 template's `~${user}:*`; anything else is refused
+ *   (`ValkeyAclSeatKeyPrefix`). The optional prop defaults to the pin.
+ * - `service` owns the instance's declared prefix, `*` by default (LiteLLM's cache user on CT100
+ *   declares `hf-litellm:*`).
+ */
+export const effectiveKeyPrefix = (user: ValkeyAclUser): string =>
+  user.profile === 'monitor'
+    ? ''
+    : user.profile === 'seat'
+      ? (user.keyPrefix ?? `${user.name}:*`)
+      : (user.keyPrefix ?? '*');
+
+/** The key patterns the declaration expects for one user, in the server's own echo form. */
+export const declaredKeyPatterns = (user: ValkeyAclUser): ReadonlyArray<string> => {
+  const prefix = effectiveKeyPrefix(user);
+  return prefix === '' ? [] : [`~${prefix}`];
+};
+
+/**
+ * The channel patterns the declaration expects for one user, in the server's own echo form.
+ *
+ * ★ CHANNELS COME FROM THE DECLARATION, NEVER `allchannels` (round-3 finding 2). `seat` gets
+ *   `&<name>:*`, `service` gets `&<keyPrefix>` (ct100#117's litellm line: `&${namespace}:*`),
+ *   `monitor` gets none. The old unconditional `allchannels` on `service` widened LiteLLM from
+ *   `&hf-litellm:*` to every channel; the "mirrors the CT100 template" comment next to it was
+ *   never true. A server normalises `&*` back to `allchannels` internally and echoes `&*`.
+ */
+export const declaredChannels = (user: ValkeyAclUser): ReadonlyArray<string> => {
+  if (user.profile === 'monitor') return [];
+  const prefix = effectiveKeyPrefix(user);
+  return (user.channelPatterns ?? [prefix]).map((pattern) => `&${pattern}`);
+};