@homeflare/alchemy 0.43.0 → 0.45.0

package/src/litellm/key-secret.test.ts

@@ -0,0 +1,248 @@
+/**
+ * `LiteLLM.Key`'s secret: where it may go and where it must not. Every value here is FAKE-*, so a
+ * test can search for it — a secret nobody can find in a place proves nothing about that place.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as Redacted from 'effect/Redacted';
+import { keyHandlers } from './key.ts';
+import { generateKey } from './key-operations.ts';
+import {
+  FAKE_KEY,
+  OTHER_FAKE_KEY,
+  VAR,
+  declare,
+  failureOf,
+  keyStack,
+  liveRow,
+  newFake,
+  runAgainst,
+  tokenFor,
+  withEnv,
+} from './key-harness.ts';
+
+const seat = { key: { fromEnv: VAR }, keyAlias: 'seat-a' } as const;
+const reconcile = (news: Parameters<typeof keyHandlers.reconcile>[0]['news']) =>
+  keyHandlers.reconcile({ fqn: 'Seat', instanceId: 'i-1', news, output: undefined });
+
+describe('create returns the key Redacted, and it goes nowhere else', () => {
+  test("the SDK hands /key/generate's key back Redacted: it prints as <redacted>", async () => {
+    const fake = newFake();
+    const response = await runAgainst(fake, generateKey({ key: FAKE_KEY, key_alias: 'seat-a' }));
+    expect(Redacted.isRedacted(response.key)).toBe(true);
+    expect(String(response.key)).toBe('<redacted>');
+    expect(JSON.stringify(response)).not.toContain(FAKE_KEY);
+    expect(Redacted.value(response.key as Redacted.Redacted<string>)).toBe(FAKE_KEY);
+  });
+
+  test('the value reaches the proxy once and is in no state Alchemy persists', async () => {
+    const fake = newFake();
+    const stack = keyStack(fake);
+    await withEnv({ [VAR]: FAKE_KEY }, () => stack.deploy(declare({ ...seat, models: ['m'] })));
+    expect(fake.keys.received()).toEqual([FAKE_KEY]);
+    expect(
+      fake.keys.writes().filter((w) => JSON.stringify(w.body).includes(FAKE_KEY)),
+    ).toHaveLength(1);
+    const state = stack.snapshot();
+    expect(state).not.toContain(FAKE_KEY);
+    expect(state).toContain(VAR); // the NAME is what state keeps
+    expect(state).not.toContain('FAKE-TOKEN'); // and neither is the row's hash
+  });
+
+  test('the attributes a create returns carry no key material at all', async () => {
+    const fake = newFake();
+    const attributes = await withEnv({ [VAR]: FAKE_KEY }, () => runAgainst(fake, reconcile(seat)));
+    expect(Object.keys(attributes).sort()).toEqual([
+      'allowedRoutes',
+      'budgetId',
+      'duration',
+      'expires',
+      'keyAlias',
+      'metadata',
+      'models',
+      'teamId',
+      'withheld',
+    ]);
+    expect(JSON.stringify(attributes)).not.toContain(FAKE_KEY);
+  });
+});
+
+describe('a read-only plan never reveals or needs the key', () => {
+  test('diff with an unset variable makes no verification request', async () => {
+    const fake = newFake();
+    const attributes = await withEnv({ [VAR]: FAKE_KEY }, () => runAgainst(fake, reconcile(seat)));
+    const before = fake.requests().length;
+    const result = await withEnv({ NEVER_SET_FAKE_VAR: undefined }, () =>
+      runAgainst(
+        fake,
+        keyHandlers.diff({
+          news: { key: { fromEnv: 'NEVER_SET_FAKE_VAR' }, keyAlias: 'seat-a', models: ['x'] },
+          output: attributes,
+        }),
+      ),
+    );
+    expect(result).toEqual({ action: 'update' });
+    expect(fake.requests()).toHaveLength(before);
+  });
+
+  test('read surfaces no token hash, for an adopted row or a managed one', async () => {
+    const fake = newFake({ keySeed: [liveRow({ models: ['m'] })] });
+    const olds = { keyAlias: 'seat-a' };
+    const adopted = await runAgainst(fake, keyHandlers.read({ olds, output: undefined }));
+    expect(JSON.stringify(adopted)).not.toContain('FAKE-TOKEN');
+    expect(JSON.stringify(adopted)).toContain('"models":["m"]');
+  });
+});
+
+describe('a value that cannot be used is refused before any write', () => {
+  const refused = async (env: string | undefined, props = seat) => {
+    const fake = newFake();
+    const failure = await failureOf(
+      withEnv({ [VAR]: env }, () => keyStack(fake).deploy(declare(props))),
+    );
+    expect(fake.keys.writes()).toEqual([]);
+    return failure;
+  };
+
+  test('an unset variable names the variable and the alias', async () => {
+    const message = await refused(undefined);
+    expect(message).toContain(VAR);
+    expect(message).toContain('seat-a');
+  });
+
+  test('an EMPTY variable is a missing one, not an empty key', async () => {
+    expect(await refused('')).toContain(VAR);
+  });
+
+  test('a value that breaks the /key/generate rule is refused, and the value is not repeated', async () => {
+    for (const bad of ['sk-FAKE-short', 'FAKE-no-sk-prefix-0000000000']) {
+      const message = await refused(bad);
+      expect(message).toContain("must start with 'sk-'");
+      expect(message).not.toContain(bad);
+    }
+  });
+
+  test('the typed errors carry the variable and rule, never the value', async () => {
+    const fake = newFake();
+    const error = await withEnv({ [VAR]: 'sk-FAKE-short' }, () =>
+      runAgainst(fake, Effect.flip(reconcile(seat))),
+    );
+    expect(error).toMatchObject({ _tag: 'LitellmKeyValueMalformedError', variable: VAR });
+    expect(JSON.stringify(error)).not.toContain('sk-FAKE-short');
+  });
+
+  test('a create with no `key` declared is refused, not left to mint a value nobody holds', async () => {
+    const fake = newFake();
+    const error = await runAgainst(fake, Effect.flip(reconcile({ keyAlias: 'seat-a' })));
+    expect(error).toMatchObject({ _tag: 'LitellmKeyValueRequiredError', keyAlias: 'seat-a' });
+    expect(fake.keys.writes()).toEqual([]);
+  });
+});
+
+describe('the value is only ever for a create', () => {
+  test("an existing key's value is read only to compare, never sent", async () => {
+    // The row's token matches OTHER_FAKE_KEY, so the in-memory compare passes — proving the value
+    // was read for the check but never put on the wire.
+    const fake = newFake({
+      keySeed: [liveRow({ models: ['old'], token: tokenFor(OTHER_FAKE_KEY) })],
+    });
+    await withEnv({ [VAR]: OTHER_FAKE_KEY }, () =>
+      keyStack(fake).deploy(declare({ ...seat, models: ['new'] }), { adopt: true }),
+    );
+    expect(fake.keys.received()).toEqual([]);
+    expect(JSON.stringify(fake.keys.writes())).not.toContain(OTHER_FAKE_KEY);
+  });
+
+  test('an existing key whose declared value is not the key it holds is refused', async () => {
+    // The row's token is some OTHER key's hash; the declared value cannot be the row's, so nothing
+    // is written and the refusal names the variable, never the value.
+    const fake = newFake({ keySeed: [liveRow({ models: ['old'] })] });
+    const message = await failureOf(
+      withEnv({ [VAR]: OTHER_FAKE_KEY }, () =>
+        keyStack(fake).deploy(declare({ ...seat, models: ['new'] }), { adopt: true }),
+      ),
+    );
+    expect(message).toContain(VAR);
+    expect(message).toContain('is not the key');
+    expect(message).not.toContain(OTHER_FAKE_KEY);
+    expect(fake.keys.writes()).toEqual([]);
+  });
+
+  test('a proxy that mints its own value instead is caught, and its row removed again', async () => {
+    const fake = newFake({ keyIgnoresUserValue: true });
+    const message = await failureOf(
+      withEnv({ [VAR]: FAKE_KEY }, () => keyStack(fake).deploy(declare(seat))),
+    );
+    expect(message).toContain('different value');
+    expect(message).toContain('deleted again');
+    expect(message).not.toContain(FAKE_KEY);
+    expect(fake.keys.rows()).toEqual([]);
+    expect(fake.keys.writes().map((w) => w.path)).toEqual(['/key/generate', '/key/delete']);
+  });
+});
+
+/**
+ * Runs `body` with `console.error` captured. The SDK really does print bodies under
+ * `DISTILLED_DEBUG_HTTP`; capturing keeps the suite quiet and lets a test say what was printed.
+ */
+const printedBy = async (body: () => Promise<unknown>): Promise<string> => {
+  const printed: string[] = [];
+  const original = console.error;
+  console.error = (...args: unknown[]) => void printed.push(args.join(' '));
+  try {
+    await body();
+  } catch {
+    // the deploy's own failure is asserted by the caller, from what it left behind
+  } finally {
+    console.error = original;
+  }
+  return printed.join('\n');
+};
+
+describe('what could still leak the value, or lose the key', () => {
+  test('DISTILLED_DEBUG_HTTP refuses a create: the SDK would print the key to stderr', async () => {
+    const fake = newFake();
+    let message = '';
+    const printed = await printedBy(async () => {
+      message = await failureOf(
+        withEnv({ [VAR]: FAKE_KEY, DISTILLED_DEBUG_HTTP: '1' }, () =>
+          keyStack(fake).deploy(declare(seat)),
+        ),
+      );
+    });
+    expect(message).toContain('DISTILLED_DEBUG_HTTP');
+    expect(message).not.toContain(FAKE_KEY);
+    expect(fake.keys.writes()).toEqual([]);
+    expect(printed).not.toContain(FAKE_KEY);
+  });
+
+  test('DISTILLED_DEBUG_HTTP does not stop an update, which never carries the value', async () => {
+    const fake = newFake({
+      keySeed: [liveRow({ models: ['old'], token: tokenFor(FAKE_KEY) })],
+    });
+    const printed = await printedBy(() =>
+      withEnv({ DISTILLED_DEBUG_HTTP: '1', [VAR]: FAKE_KEY }, () =>
+        keyStack(fake).deploy(declare({ ...seat, models: ['new'] }), { adopt: true }),
+      ),
+    );
+    expect(fake.keys.writes().map((w) => w.path)).toEqual(['/key/update']);
+    expect(printed).toContain('/key/update'); // the printing path ran…
+    expect(printed).not.toContain(FAKE_KEY); // …with no value in it
+  });
+
+  test('a value with a trailing newline is refused, not sent', async () => {
+    const fake = newFake();
+    const message = await failureOf(
+      withEnv({ [VAR]: `${FAKE_KEY}\n` }, () => keyStack(fake).deploy(declare(seat))),
+    );
+    expect(message).toContain('no whitespace');
+    expect(fake.keys.writes()).toEqual([]);
+  });
+
+  test('an empty alias is refused before any request', async () => {
+    const fake = newFake();
+    const message = await failureOf(keyStack(fake).deploy(declare({ keyAlias: ' ' })));
+    expect(message).toContain('keyAlias is empty');
+    expect(fake.requests()).toEqual([]);
+  });
+});

package/src/litellm/key-secret.ts

@@ -0,0 +1,137 @@
+/**
+ * Where `LiteLLM.Key`'s secret comes from, and the only place it is unwrapped.
+ *
+ * ⛔ THE KEY VALUE IS WRITE-ONLY, THE SAME MECHANISM EVERY OTHER KIT SECRET USES
+ *   (`../secrets/write-only.ts`: PBS webhook secrets, the Cloudflare MCP entry, Forgejo org secrets).
+ *   The prop holds the NAME of an environment variable, `{ fromEnv: 'SEAT_KEY' }`; the deploying
+ *   process reads it at call time; the value goes over the wire once, in `/key/generate`'s body.
+ *   Alchemy persists props AND attributes unencrypted — a `Redacted` is TAGGED, not encrypted
+ *   (`State/StateEncoding.ts` writes the inner value beside the tag) — so neither may hold it.
+ *   S25 of the provider standard says the same; `MeshNode` (docs/mesh-node.md) is the other family
+ *   that keeps a generated secret out of state.
+ * ★ WHY NOT LET LITELLM MINT IT AND RETURN IT. `/key/generate` does return the new key, and the SDK
+ *   decodes it `Redacted` (`T.SensitiveValue`). But a resource has exactly two places to put it, an
+ *   attribute (state, in the clear) or nowhere; and LiteLLM never shows the plaintext again, only a
+ *   hash. A key minted and dropped is a row nobody can use. So the value is minted OUTSIDE — a random
+ *   `sk-…` in the vault, the same one the seat reads — and handed to LiteLLM, which the docstring
+ *   for `key` supports: "User defined key value. Must start with 'sk-' and be at least 16
+ *   characters long."
+ * ⚠️ AN ADOPTED KEY'S VALUE IS COMPARED WITH THE LIVE ROW, IN MEMORY ONLY. LiteLLM keeps the sha256
+ *   hex of the key (`hash_token`, measured in the 1.103.0 wheel's `proxy/utils.py`), and `/key/list`
+ *   with `return_full_object` returns it as the row's `token`. When a declaration names `key:
+ *   { fromEnv }` for a key that already exists, the resolved value is sha256'd and compared with that
+ *   hash (never with the value, and the hash is never persisted — key-form.ts's `toAttributes` still
+ *   drops `token`). A mismatch is refused (`LitellmKeyValueMismatchError`): a seat reading the same
+ *   variable would hold a key that authenticates nothing while the plan reported success. There is
+ *   nothing to WRITE about a mismatch — `/key/update` drops `key` from its body
+ *   (`prepare_key_update_data` pops it, `key_management_endpoints.py:2469`), so it cannot change a
+ *   key's value, and `/key/regenerate` is an Enterprise feature (its docstring, :5673) — so the
+ *   operator fixes the variable or drops the `key`. A changed variable changes nothing on an
+ *   existing key: rotate by declaring a new alias. Plan and reconcile both check a set variable;
+ *   an unset or empty variable skips verification so a deployer need not hold the seat key.
+ * ⚠️ A PROXY MAY REFUSE THE WHOLE APPROACH: with the dashboard's `disable_custom_api_keys` setting
+ *   on, `/key/generate` answers 403 to ANY user-defined key ("Keys must be auto-generated",
+ *   `_check_custom_key_allowed`, :485-496). That surfaces as the SDK's typed `Forbidden`. UNVERIFIED
+ *   whether the estate's proxy has it on; adopting existing keys is unaffected.
+ */
+import { createHash } from 'node:crypto';
+import * as Effect from 'effect/Effect';
+import * as Redacted from 'effect/Redacted';
+import { type FromEnv, resolveAll } from '../secrets/write-only.ts';
+import {
+  LitellmKeyDebugLoggingError,
+  LitellmKeyValueMalformedError,
+  LitellmKeyValueMismatchError,
+  LitellmKeyValueMissingError,
+  LitellmKeyValueRequiredError,
+} from './key-errors.ts';
+
+/** From `/key/generate`'s own docstring for the `key` field (distilled-litellm, LiteLLM 1.103.0). */
+const PREFIX = 'sk-';
+const MIN_LENGTH = 16;
+/**
+ * ⚠️ NO WHITESPACE is the house's own addition, not LiteLLM's: a secret renderer's trailing newline
+ *   would be sent as part of the value, and a seat that trims what it reads would then hold a
+ *   different key from the one LiteLLM stored (`resolveAll` deliberately does not trim).
+ */
+const RULE = `a user-defined key must start with '${PREFIX}', be at least ${MIN_LENGTH} characters and contain no whitespace`;
+
+/**
+ * The declared value, `Redacted`, or a typed refusal naming the alias, the variable and the rule.
+ * Called only when a create is actually about to happen, never by `diff` or `read`, so a plan
+ * (which needs no secret) runs without the variable.
+ * ⚠️ AN EMPTY VARIABLE IS A MISSING ONE (`resolveAll`): a secret renderer that failed writes
+ *   `NAME=` and sending `''` would create a key that authenticates with nothing.
+ */
+export const resolveKeyValue = (
+  keyAlias: string,
+  ref: FromEnv | undefined,
+): Effect.Effect<
+  Redacted.Redacted<string>,
+  LitellmKeyValueRequiredError | LitellmKeyValueMissingError | LitellmKeyValueMalformedError
+> =>
+  Effect.gen(function* () {
+    if (ref === undefined) return yield* new LitellmKeyValueRequiredError({ keyAlias });
+    const variable = ref.fromEnv;
+    const value = resolveAll({ key: ref }).values['key'];
+    if (value === undefined) return yield* new LitellmKeyValueMissingError({ keyAlias, variable });
+    if (!value.startsWith(PREFIX) || value.length < MIN_LENGTH || /\s/.test(value)) {
+      return yield* new LitellmKeyValueMalformedError({ keyAlias, rule: RULE, variable });
+    }
+    return Redacted.make(value);
+  });
+
+/** Whether `/key/generate` echoed the value it was sent (the SDK hands it back `Redacted`). */
+export const echoes = (
+  returned: string | Redacted.Redacted<string>,
+  sent: Redacted.Redacted<string>,
+): boolean =>
+  (Redacted.isRedacted(returned) ? Redacted.value(returned) : returned) === Redacted.value(sent);
+
+/**
+ * The sha256 hex of a key value, the same digest LiteLLM stores as `hash_token` (`proxy/utils.py`).
+ * ★ MATCHES THE VENDOR'S HASH, not a house format: the row's `token` is the vendor's own store, so
+ *   the digest must be reproducible from the value with the vendor's algorithm, not a salt (a salt
+ *   would make every comparison fail). Nothing here is persisted — the value is in memory only.
+ */
+const sha256 = (value: string): string => createHash('sha256').update(value).digest('hex');
+
+/**
+ * Whether an ADOPTED key's declared `key: { fromEnv }` value is the key the live row holds.
+ *
+ * ⚠️ COMPARED AS A SHA256 AGAINST THE ROW'S `token`, never value-against-value, and the hash is
+ *   never written anywhere: a `Redacted` value unwrapped only long enough to digest it, then gone.
+ *   The row's `token` (`hash_token`) is the vendor's own sha256 hex of the key.
+ */
+export const verifyKeyValue = (
+  keyAlias: string,
+  ref: FromEnv | undefined,
+  token: string | null,
+): Effect.Effect<void, LitellmKeyValueMismatchError> =>
+  Effect.gen(function* () {
+    if (ref === undefined) return;
+    const variable = ref.fromEnv;
+    const value = resolveAll({ key: ref }).values['key'];
+    if (value === undefined) return;
+    if (token === null || sha256(value) !== token) {
+      return yield* new LitellmKeyValueMismatchError({ keyAlias, variable });
+    }
+  });
+
+/**
+ * ⛔ THE SDK PRINTS BODIES WHILE `DISTILLED_DEBUG_HTTP` IS SET (`@distilled.cloud/core`
+ *   `protocol-http.ts`: the first 400 characters of every request body; `protocol-rest.ts`: of every
+ *   response), and `/key/generate` carries the key in both. Measured by reading the pinned source
+ *   2026-09-29; `mesh-node-token.ts` refuses for the same reason. Only a create needs it: no other
+ *   call in this resource carries the value. Reads `process.env` because that is what distilled reads.
+ */
+export const refuseDebugLogging = (
+  keyAlias: string,
+): Effect.Effect<void, LitellmKeyDebugLoggingError> =>
+  (globalThis.process?.env?.['DISTILLED_DEBUG_HTTP'] ?? '') !== ''
+    ? Effect.fail(new LitellmKeyDebugLoggingError({ keyAlias }))
+    : Effect.void;
+
+/** Whether verification can run; unset/empty variables skip the check, never a create. */
+export const hasKeyValue = (ref: FromEnv | undefined): boolean =>
+  ref !== undefined && resolveAll({ key: ref }).values['key'] !== undefined;

package/src/litellm/key-transport.test.ts

@@ -0,0 +1,166 @@
+/**
+ * `LiteLLM.Key`'s create when the connection to the proxy fails: the key is IN the request body of
+ * `/key/generate`, and an `HttpClientError` carries its request, so a create that dies on the wire
+ * would hand the plaintext to whoever logs, inspects or serialises the failure. Every place a failed
+ * create can be read from is searched here for a value the tests can find (`FAKE_KEY`).
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import * as Logger from 'effect/Logger';
+import { keyHandlers } from './key.ts';
+import {
+  FAKE_KEY,
+  type Fake,
+  VAR,
+  declare,
+  keyStack,
+  newFake,
+  runAgainst,
+  withEnv,
+} from './key-harness.ts';
+
+const seat = { key: { fromEnv: VAR }, keyAlias: 'seat-a' } as const;
+const reconcile = () =>
+  keyHandlers.reconcile({ fqn: 'Seat', instanceId: 'i-1', news: seat, output: undefined });
+
+const pathOf = (input: string | URL | Request) =>
+  new URL(input instanceof Request ? input.url : String(input)).pathname;
+
+/** The fake, with `/key/generate` answered by `onGenerate` and every other route its own. */
+const generatingWith = (fake: Fake, onGenerate: () => Promise<Response>): Fake => ({
+  ...fake,
+  fetch: (async (input: string | URL | Request, init?: RequestInit) =>
+    pathOf(input) === '/key/generate'
+      ? onGenerate()
+      : fake.fetch(input, init)) as typeof globalThis.fetch,
+});
+
+/** The connection drops: `fetch` rejects before any answer. */
+const droppedConnection = (fake: Fake): Fake =>
+  generatingWith(fake, () => Promise.reject(new TypeError('fetch failed')));
+
+/** The answer starts (200, headers) and its body then fails mid-read: the SDK reads it with `orDie`. */
+const brokenAnswer = (fake: Fake): Fake =>
+  generatingWith(fake, () =>
+    Promise.resolve(
+      new Response(
+        new ReadableStream({
+          start: (controller) => controller.error(new Error('connection reset mid-body')),
+        }),
+        { headers: { 'content-type': 'application/json' }, status: 200 },
+      ),
+    ),
+  );
+
+/** What Effect's own JSON logger prints for `Effect.logError('create failed', value)`. */
+const jsonLogged = async (value: unknown): Promise<string> => {
+  const lines: string[] = [];
+  const capture = Logger.make((options) => void lines.push(Logger.formatJson.log(options)));
+  await Effect.runPromise(
+    Effect.logError('create failed', value).pipe(Effect.provide(Logger.layer([capture]))),
+  );
+  return lines.join('\n');
+};
+
+/** Every reading of `value` a caller could take: serialise, deep-inspect, print, log. */
+const everyReadingOf = async (value: unknown): Promise<string> => {
+  const readings = [Bun.inspect(value, { depth: 12 }), String(value), await jsonLogged(value)];
+  try {
+    readings.push(JSON.stringify(value));
+  } catch {
+    // a value JSON cannot serialise leaks nothing that way
+  }
+  if (value instanceof Error) readings.push(value.message, String(value.stack));
+  return readings.join('\n');
+};
+
+const rejectionOf = (attempt: Promise<unknown>): Promise<unknown> =>
+  attempt.then(
+    () => undefined,
+    (error: unknown) => error,
+  );
+
+describe('a create that dies on the wire', () => {
+  test('fails with a typed error that names the alias and holds no request', async () => {
+    const fake = droppedConnection(newFake());
+    const error = await withEnv({ [VAR]: FAKE_KEY }, () =>
+      runAgainst(fake, Effect.flip(reconcile())),
+    );
+    expect(error).toMatchObject({
+      _tag: 'LitellmKeyTransportError',
+      keyAlias: 'seat-a',
+      reason: 'TransportError',
+    });
+    expect(Object.keys(error)).not.toContain('request');
+    expect(Object.keys(error)).not.toContain('cause');
+    expect(await everyReadingOf(error)).not.toContain(FAKE_KEY);
+  });
+
+  test('a create whose ANSWER was lost leaves a live key, and the next deploy takes it with --adopt', async () => {
+    const fake = newFake();
+    let answerLost = true;
+    const flaky: Fake = {
+      ...fake,
+      fetch: (async (input: string | URL | Request, init?: RequestInit) => {
+        const answer = await fake.fetch(input, init);
+        if (answerLost && pathOf(input) === '/key/generate') throw new TypeError('fetch failed');
+        return answer;
+      }) as typeof globalThis.fetch,
+    };
+    const stack = keyStack(flaky, { noRetry: true });
+    const first = await rejectionOf(
+      withEnv({ [VAR]: FAKE_KEY }, () => stack.deploy(declare(seat))),
+    );
+    expect(String((first as Error).message ?? first)).toContain('/key/generate request failed');
+    expect(fake.keys.rows()).toHaveLength(1); // the key DID land: the message says "MAY", and it was right
+
+    answerLost = false;
+    const refused = await rejectionOf(
+      withEnv({ [VAR]: FAKE_KEY }, () => stack.deploy(declare(seat))),
+    );
+    expect(String(refused)).toContain('adopt'); // what the error message tells the operator to use
+    await withEnv({ [VAR]: FAKE_KEY }, () => stack.deploy(declare(seat), { adopt: true }));
+    expect(fake.keys.writes().map((write) => write.path)).toEqual(['/key/generate']);
+    expect(fake.keys.rows()).toHaveLength(1);
+  });
+
+  test('through the engine the deploy rejects with nothing of the key in it', async () => {
+    const fake = droppedConnection(newFake());
+    const rejection = await rejectionOf(
+      withEnv({ [VAR]: FAKE_KEY }, () => keyStack(fake, { noRetry: true }).deploy(declare(seat))),
+    );
+    expect(rejection).toBeDefined();
+    expect(await everyReadingOf(rejection)).not.toContain(FAKE_KEY);
+    expect(fake.keys.writes()).toEqual([]);
+  });
+
+  test('a body that fails mid-read (a defect in the SDK) leaks nothing either', async () => {
+    const fake = brokenAnswer(newFake());
+    const exit = await withEnv({ [VAR]: FAKE_KEY }, () =>
+      runAgainst(fake, Effect.exit(reconcile())),
+    );
+    expect(exit._tag).toBe('Failure');
+    expect(await everyReadingOf(exit)).not.toContain(FAKE_KEY);
+    const rejection = await rejectionOf(
+      withEnv({ [VAR]: FAKE_KEY }, () => keyStack(fake, { noRetry: true }).deploy(declare(seat))),
+    );
+    expect(rejection).toBeDefined();
+    expect(await everyReadingOf(rejection)).not.toContain(FAKE_KEY);
+  });
+});
+
+describe('a transport failure on a call that carries no value keeps the SDK error', () => {
+  test('/key/list dropping is still the SDK error, so a read failure keeps its detail', async () => {
+    const fake: Fake = {
+      ...newFake(),
+      fetch: (async (_input: string | URL | Request): Promise<Response> => {
+        throw new TypeError('fetch failed');
+      }) as typeof globalThis.fetch,
+    };
+    const error = await runAgainst(
+      fake,
+      Effect.flip(keyHandlers.read({ olds: { keyAlias: 'seat-a' }, output: undefined })),
+    );
+    expect(error).toMatchObject({ _tag: 'HttpClientError' });
+  });
+});