@homeflare/alchemy 0.43.0 → 0.45.0

package/src/litellm/fake-credential-litellm.ts

@@ -0,0 +1,216 @@
+/**
+ * A fake of LiteLLM's `/credentials/*` routes for tests — TEST ONLY, never imported by `index.ts`.
+ * Like `fake-model-litellm.ts` it is a `fetch` function handed to Effect's real `FetchHttpClient`
+ * through its `Fetch` reference, so a test exercises distilled's REAL path assembly, JSON encoding
+ * and status-to-error matching; only the wire responses a scenario needs are written here.
+ *
+ * ★ THE MASKING RULE IS THE VENDOR'S, READ FROM THE LIVE 1.103.0 CONTAINER
+ *   (`litellm_logging.py::_get_masked_values`): a key whose lowercased form contains `token`,
+ *   `key`, `secret`, `password`, `passwd`, `credentials`, `vertex_credentials` or
+ *   `authorization` answers `v[:2] + "****" + v[-2:]` for a string longer than four characters,
+ *   `*****` for a shorter one, the value untouched for a non-string, and a non-sensitive key
+ *   answers its full value. Both the list and the by-name read apply it (the by-name read with
+ *   `unmasked_length=4, number_of_asterisks=4` — the same rule).
+ * ★ THE READ AND THE DELETE ASK DIFFERENT STORES, AS THE VENDOR DOES (measured): the by-name read
+ *   answers only rows loaded in memory, while the delete consults the table. `memoryOmits` models
+ *   a row committed to the table but not loaded in memory, so the read answers 404 while the
+ *   create for the same name answers 409 — the asymmetry credential-operations.ts documents.
+ * ★ A CREATE ON AN EXISTING NAME ANSWERS 409 (the vendor's unique-violation handling,
+ *   `_credential_exists_detail`), decoded by the real SDK path as core `Conflict`. The PATCH route
+ *   merges values in both stores; nonempty info normally replaces DB info but merges in memory
+ *   (`credential_endpoints/endpoints.py:312-319,384-387`, 1.103.0). Empty info leaves DB unchanged. With
+ *   the body's `credential_name` (the `credential_name_body` member) applied as the new name only
+ *   when it differs from the path's (the kit never renames in place, so it never does).
+ * ★ `FAKE-*` VALUES ONLY. Nothing here is, or looks like, a real credential.
+ */
+/** One request that reached the fake. Its own type, so this file depends on no other fake. */
+export interface FakeCredentialRequest {
+  readonly method: string;
+  readonly path: string;
+}
+
+type Row = Record<string, unknown>;
+
+export interface FakeCredentialLitellm {
+  readonly fetch: typeof globalThis.fetch;
+  /**
+   * Every stored row as the fake's table holds it — values in CLEAR, the fake's own choice: the
+   * real table encrypts them, but nothing reads the table directly, only the masked reads, so the
+   * encryption seam is invisible here and a test can assert what a write SENT.
+   */
+  readonly rows: () => readonly Row[];
+  readonly requests: () => readonly FakeCredentialRequest[];
+  /** The JSON bodies of every `POST` and `PATCH`, in order (including rejected PATCH requests). */
+  readonly bodies: () => readonly Row[];
+}
+
+export interface FakeCredentialOptions {
+  readonly masterKey?: string;
+  readonly seed?: readonly Row[];
+  /** Names committed to the table that the in-memory read omits (a row not loaded). */
+  readonly memoryOmits?: readonly string[];
+}
+
+const json = (status: number, body: unknown) =>
+  new Response(JSON.stringify(body), { headers: { 'content-type': 'application/json' }, status });
+
+/** A minimal 1.103.0-shaped row, as the table holds it. */
+export const credentialRow = (fields: Row): Row => ({
+  credential_info: {},
+  credential_name: '',
+  credential_values: {},
+  ...fields,
+});
+
+const SENSITIVE_FRAGMENTS: readonly string[] = [
+  'authorization',
+  'token',
+  'key',
+  'secret',
+  'vertex_credentials',
+  'credentials',
+  'password',
+  'passwd',
+];
+
+/** The vendor's own masking rule, applied to one keyed map (see the header). */
+const masked = (values: unknown): Record<string, unknown> => {
+  const out: Record<string, unknown> = {};
+  if (typeof values !== 'object' || values === null) return out;
+  for (const [key, value] of Object.entries(values as Record<string, unknown>)) {
+    const sensitive = SENSITIVE_FRAGMENTS.some((fragment) => key.toLowerCase().includes(fragment));
+    if (!sensitive) {
+      out[key] = value;
+      continue;
+    }
+    if (typeof value !== 'string') {
+      out[key] = value;
+      continue;
+    }
+    out[key] = value.length <= 4 ? '*****' : `${value.slice(0, 2)}****${value.slice(-2)}`;
+  }
+  return out;
+};
+
+export const startFakeCredentialLitellm = (
+  options: FakeCredentialOptions = {},
+): FakeCredentialLitellm => {
+  const masterKey = options.masterKey ?? 'sk-test-master';
+  let rows: Row[] = (options.seed ?? []).map((row) => ({ ...row }));
+  let memory = rows.map((row) => ({ ...row }));
+  const requests: FakeCredentialRequest[] = [];
+  const bodies: Row[] = [];
+  const memoryOmits = new Set<string>(options.memoryOmits ?? []);
+
+  const inMemory = (name: string): Row | undefined =>
+    memory.find((row) => String(row['credential_name']) === name && !memoryOmits.has(name));
+
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const request =
+      input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+    const url = new URL(request.url);
+    requests.push({ method: request.method, path: `${url.pathname}${url.search}` });
+    if (request.headers.get('authorization') !== `Bearer ${masterKey}`) {
+      return json(401, { detail: 'invalid api key' });
+    }
+    const path = url.pathname;
+
+    // GET /credentials/by_name/{name} — the read, in-memory only (see the header).
+    if (path.startsWith('/credentials/by_name/') && request.method === 'GET') {
+      const name = decodeURIComponent(path.slice('/credentials/by_name/'.length));
+      const found = inMemory(name);
+      return found === undefined
+        ? json(404, { error: { message: `Credential not found. Got credential name: ${name}` } })
+        : json(200, {
+            ...found,
+            credential_values: masked(found['credential_values']),
+          });
+    }
+
+    // POST /credentials — the create; 409 on a name the TABLE already has.
+    if (path === '/credentials' && request.method === 'POST') {
+      const body = (await request.json()) as Row;
+      bodies.push(body);
+      const name = String(body['credential_name']);
+      if (rows.some((row) => String(row['credential_name']) === name)) {
+        return json(409, { detail: `Credential '${name}' already exists.` });
+      }
+      rows = [...rows, credentialRow(body)];
+      memory = [...memory, credentialRow(body)];
+      memoryOmits.delete(name); // a create loads the row into memory; an omission is seeded-only
+      return json(200, { success: true, message: 'Credential created successfully' });
+    }
+
+    // PATCH /credentials/{name} — DB info replacement, memory merge (see the header); the body's
+    // `credential_name` (the `credential_name_body` member) renames only when it differs.
+    if (path.startsWith('/credentials/') && request.method === 'PATCH') {
+      const name = decodeURIComponent(path.slice('/credentials/'.length));
+      const body = (await request.json()) as Row;
+      bodies.push(body);
+      if (typeof body['credential_name'] !== 'string') {
+        return json(422, {
+          detail: [{ loc: ['body', 'credential_name'], msg: 'Field required', type: 'missing' }],
+        });
+      }
+      if (!rows.some((row) => String(row['credential_name']) === name)) {
+        return json(404, { error: { message: 'Credential not found in DB.' } });
+      }
+      const bodyName = body['credential_name'];
+      const target =
+        typeof bodyName === 'string' && bodyName !== '' && bodyName !== name ? bodyName : name;
+      const info = (body['credential_info'] ?? {}) as Row;
+      const values = (body['credential_values'] ?? {}) as Row;
+      rows = rows.map((row) =>
+        String(row['credential_name']) === name
+          ? {
+              ...row,
+              credential_name: target,
+              credential_info:
+                Object.keys(info).length === 0
+                  ? row['credential_info']
+                  : {
+                      ...('credential_info' in ((row['credential_info'] ?? {}) as Row)
+                        ? (row['credential_info'] as Row)
+                        : {}),
+                      ...info,
+                    },
+              credential_values: { ...((row['credential_values'] ?? {}) as Row), ...values },
+            }
+          : row,
+      );
+      memory = memory.map((row) =>
+        String(row['credential_name']) === name
+          ? {
+              ...row,
+              credential_name: target,
+              credential_info: { ...((row['credential_info'] ?? {}) as Row), ...info },
+              credential_values: { ...((row['credential_values'] ?? {}) as Row), ...values },
+            }
+          : row,
+      );
+      return json(200, { success: true, message: 'Credential updated successfully' });
+    }
+
+    // DELETE /credentials/{name} — DB-authoritative; 404 when the TABLE lacks the name.
+    if (path.startsWith('/credentials/') && request.method === 'DELETE') {
+      const name = decodeURIComponent(path.slice('/credentials/'.length));
+      if (!rows.some((row) => String(row['credential_name']) === name)) {
+        return json(404, {
+          error: { message: `Credential not found. Got credential name: ${name}` },
+        });
+      }
+      rows = rows.filter((row) => String(row['credential_name']) !== name);
+      memory = memory.filter((row) => String(row['credential_name']) !== name);
+      return json(200, { success: true, message: 'Credential deleted successfully' });
+    }
+
+    return json(404, { error: { message: 'not found' } });
+  }) as typeof globalThis.fetch;
+
+  return {
+    bodies: () => [...bodies],
+    fetch,
+    requests: () => [...requests],
+    rows: () => rows.map((row) => ({ ...row })),
+  };
+};

package/src/litellm/fake-keys.ts

@@ -0,0 +1,190 @@
+/**
+ * A fake of LiteLLM's `/key/*` routes for `LiteLLM.Key` tests — TEST ONLY, never imported by
+ * `index.ts`. `fake-litellm.ts` mounts it, so a test still goes through distilled's REAL path
+ * assembly, JSON encode/decode and status→typed-error matching over `FetchHttpClient.Fetch`.
+ *
+ * ★ MEASURED against the litellm 1.103.0 wheel's source (`key_management_endpoints.py`), not a live
+ *   proxy: a user-defined `key` must start with `sk-` and be 16+ characters, else 400 (:1477-1490); a
+ *   duplicate `key_alias` is 400 on generate and update (`_enforce_unique_key_alias`, :7639-7667);
+ *   `/key/update` applies `model_dump(exclude_unset=True)`, so an explicit `null` clears a column
+ *   (`duration: null` sets `expires` null, :2468-2500) and omitted fields are untouched; an update
+ *   that finds no alias is 404 (`_get_and_validate_existing_key`, per the distilled patch); a delete
+ *   of an alias it does not hold is 404 "No keys found" (:4914-4918) and of a key the caller may not
+ *   delete 403 (:4933-4936), BOTH answered as a `ProxyException` envelope, because `delete_key_fn`
+ *   re-raises through `handle_exception_on_proxy` (`proxy/utils.py:7815`), whose `message` is `str(detail)`
+ *   (`_types.py` `ProxyException`): `{"error": {"message": "{'error': 'No keys found'}", "code": "404", ...}}`;
+ *   `/key/list` filters `key_alias` exactly unless told otherwise, and
+ *   `return_full_object` answers full rows, `token` being the sha256 hex of the key (`hash_token`).
+ * ⚠️ NOT MODELLED, or only a stand-in: `disable_custom_api_keys` (a 403 for ANY user-defined key);
+ *   a `budget_id` that names no budget is a foreign-key violation whose status is UNMEASURED — 400
+ *   here, so a test can prove the Budget is written first.
+ * ⛔ THE PLAINTEXT KEY NEVER SITS IN A ROW. Rows carry only `token`, a sha256 of the value, the way
+ *   a LiteLLM row carries a hash. The values the proxy was SENT are kept apart in `received()`, so a
+ *   test can prove what reached the wire without the value ever being in the state a resource sees.
+ */
+type Row = Record<string, unknown>;
+
+export interface FakeKeysOptions {
+  /** Live rows, wire-shaped like `UserAPIKeyAuth` (`key_alias`, `budget_id`, `models`, `token`, …). */
+  readonly keySeed?: readonly Row[];
+  /** `GET /key/list` answers this status and nothing else — a transient read failure. */
+  readonly keyListStatus?: number;
+  /** `POST /key/delete` answers 403 and keeps the row — a caller that may not delete. */
+  readonly keyDeleteForbidden?: boolean;
+  /** `POST /key/delete` deletes the row and STILL answers 404 — another caller got there first. */
+  readonly keyDeleteRaces?: boolean;
+  /** `/key/generate` ignores the user-defined `key` and mints its own. */
+  readonly keyIgnoresUserValue?: boolean;
+  /** `/key/update` drops explicit `null`s instead of writing them (an `exclude_none` merge). */
+  readonly keyUpdateIgnoresNull?: boolean;
+}
+
+export interface FakeKeys {
+  readonly route: (request: Request, url: URL) => Promise<Response>;
+  readonly rows: () => readonly Row[];
+  /** Every JSON body a `/key/*` write carried, in order. FAKE-* material only. */
+  readonly writes: () => readonly { readonly path: string; readonly body: Row }[];
+  /** The raw key values `/key/generate` was sent — kept off the rows on purpose. */
+  readonly received: () => readonly string[];
+}
+
+const json = (status: number, body: unknown) =>
+  new Response(JSON.stringify(body), { headers: { 'content-type': 'application/json' }, status });
+
+/**
+ * What `/key/delete` answers a failure with: a `ProxyException`, whose `message` is Python's `str()` of
+ * the `HTTPException` detail dict (`{'error': '…'}`), and whose `code` is the status as a string.
+ */
+const proxyException = (status: number, error: string) =>
+  json(status, {
+    error: {
+      code: String(status),
+      message: `{'error': '${error}'}`,
+      param: null,
+      type: 'internal_server_error',
+    },
+  });
+
+const sha256 = (value: string): string =>
+  new Bun.CryptoHasher('sha256').update(value).digest('hex');
+
+const UNITS = { d: 86_400_000, h: 3_600_000, m: 60_000, s: 1_000 } as const;
+
+/** `'30d'` → an ISO timestamp that far ahead; `undefined` for anything else (a bad duration is refused; its status is UNMEASURED). */
+const expiryFor = (duration: string): string | undefined => {
+  const match = /^(\d+)([smhd])$/.exec(duration);
+  if (match === null) return undefined;
+  const unit = UNITS[match[2] as keyof typeof UNITS];
+  return new Date(Date.now() + Number(match[1]) * unit).toISOString();
+};
+
+/** The columns `/key/update` may write; each list column's `null` means "none". */
+const LIST_COLUMNS = new Set(['models', 'allowed_routes']);
+
+export const createFakeKeys = (
+  options: FakeKeysOptions | undefined,
+  budgetExists: (budgetId: string) => boolean,
+): FakeKeys => {
+  let rows: Row[] = [...(options?.keySeed ?? [])];
+  const writes: { path: string; body: Row }[] = [];
+  const received: string[] = [];
+  let minted = 0;
+
+  const byAlias = (alias: unknown) => rows.findIndex((row) => row['key_alias'] === alias);
+
+  const generate = (body: Row) => {
+    const alias = body['key_alias'];
+    const supplied = body['key'];
+    if (typeof supplied === 'string') received.push(supplied);
+    if (
+      typeof supplied === 'string' &&
+      (!supplied.startsWith('sk-') || supplied.length < 16) &&
+      options?.keyIgnoresUserValue !== true
+    ) {
+      return json(400, { detail: 'user-defined key must start with sk- and be 16+ characters' });
+    }
+    if (byAlias(alias) !== -1) return json(400, { detail: `key alias '${String(alias)}' exists` });
+    const budgetId = body['budget_id'];
+    if (typeof budgetId === 'string' && !budgetExists(budgetId)) {
+      return json(400, { detail: `budget ${budgetId} not found` });
+    }
+    minted += 1;
+    const value =
+      typeof supplied === 'string' && options?.keyIgnoresUserValue !== true
+        ? supplied
+        : `sk-FAKE-minted-${minted}-0000000000`;
+    const token = sha256(value);
+    // ⚠️ A key VALUE already held is a unique-token violation; its status is UNMEASURED.
+    if (rows.some((row) => row['token'] === token)) return json(400, { detail: 'key exists' });
+    const duration = body['duration'];
+    const expires = typeof duration === 'string' ? expiryFor(duration) : null;
+    if (expires === undefined) return json(400, { detail: 'invalid duration' });
+    const { key: _key, duration: _duration, ...rest } = body;
+    const row = { models: [], allowed_routes: [], metadata: {}, ...rest, expires, token };
+    rows = [...rows, row];
+    return json(200, { ...row, key: value });
+  };
+
+  const update = (body: Row) => {
+    const at = byAlias(body['key_alias']);
+    if (at === -1) return json(404, { detail: 'no key with that alias' });
+    const budgetId = body['budget_id'];
+    if (typeof budgetId === 'string' && !budgetExists(budgetId)) {
+      return json(400, { detail: `budget ${budgetId} not found` });
+    }
+    const ignoresNull = options?.keyUpdateIgnoresNull === true;
+    const patch: Row = {};
+    for (const [column, value] of Object.entries(body)) {
+      if (column === 'key' || column === 'duration') continue;
+      if (value === null && ignoresNull) continue;
+      patch[column] = value === null && LIST_COLUMNS.has(column) ? [] : value;
+    }
+    if ('duration' in body && !(body['duration'] === null && ignoresNull)) {
+      const duration = body['duration'];
+      const expires = typeof duration === 'string' ? expiryFor(duration) : null;
+      if (expires === undefined) return json(400, { detail: 'invalid duration' });
+      patch['expires'] = expires;
+    }
+    rows = rows.map((row, i) => (i === at ? { ...row, ...patch } : row));
+    return json(200, {});
+  };
+
+  const remove = (body: Row) => {
+    if (options?.keyDeleteForbidden === true) {
+      return proxyException(403, 'You are not authorized to delete this key');
+    }
+    const aliases = Array.isArray(body['key_aliases']) ? body['key_aliases'] : [];
+    const found = aliases.filter((alias) => byAlias(alias) !== -1);
+    if (found.length === 0) return proxyException(404, 'No keys found');
+    rows = rows.filter((row) => !found.includes(row['key_alias']));
+    if (options?.keyDeleteRaces === true) return proxyException(404, 'No keys found');
+    return json(200, { deleted_keys: found });
+  };
+
+  const route = async (request: Request, url: URL): Promise<Response> => {
+    if (request.method === 'GET' && url.pathname === '/key/list') {
+      if (options?.keyListStatus !== undefined) {
+        return json(options.keyListStatus, { detail: 'upstream unavailable' });
+      }
+      const alias = url.searchParams.get('key_alias');
+      const matching = rows.filter((row) => alias === null || row['key_alias'] === alias);
+      const full = url.searchParams.get('return_full_object') === 'true';
+      const keys = full ? matching : matching.map((row) => row['token']);
+      return json(200, { keys, total_count: keys.length, current_page: 1, total_pages: 1 });
+    }
+    if (request.method !== 'POST') return json(405, { detail: `unhandled ${request.method}` });
+    const body = (await request.json()) as Row;
+    writes.push({ body, path: url.pathname });
+    if (url.pathname === '/key/generate') return generate(body);
+    if (url.pathname === '/key/update') return update(body);
+    if (url.pathname === '/key/delete') return remove(body);
+    return json(404, { detail: 'not found' });
+  };
+
+  return {
+    received: () => [...received],
+    route,
+    rows: () => [...rows],
+    writes: () => [...writes],
+  };
+};

package/src/litellm/fake-litellm.ts

@@ -27,6 +27,7 @@
  *   fake now matches that measured vendor behaviour.
  */
 import type { PassThroughGenericEndpoint } from '@distilled.cloud/litellm/misc';
+import { type FakeKeys, type FakeKeysOptions, createFakeKeys } from './fake-keys.ts';
 
 /** RFC 2606 placeholder — never a real host. Shared across tests, like `../netbox/fake-netbox.ts`. */
 export const FAKE_BASE = 'https://litellm.example.com';
@@ -42,6 +43,8 @@ export interface FakeLitellm {
   readonly requests: () => readonly FakeRequest[];
   /** `/budget/*` rows, wire-shaped (`tpm_limit`/`rpm_limit` as decimal strings, like the real table). */
   readonly budgets: () => readonly Record<string, unknown>[];
+  /** `/key/*` rows and the writes they took — see fake-keys.ts. */
+  readonly keys: FakeKeys;
 }
 
 const RACE_WINDOW_MS = 15;
@@ -50,20 +53,25 @@ const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve,
 const json = (status: number, body: unknown) =>
   new Response(JSON.stringify(body), { headers: { 'content-type': 'application/json' }, status });
 
-export const startFakeLitellm = (options?: {
-  readonly masterKey?: string;
-  readonly seed?: readonly PassThroughGenericEndpoint[];
-  /** Every `DELETE` 400s `not_allowed_access`, whether or not the row exists — see the file header. */
-  readonly forbidDelete?: boolean;
-  readonly budgetSeed?: readonly Record<string, unknown>[];
-  /** `/budget/update` drops `null`s instead of writing them (an `exclude_none` merge). */
-  readonly budgetExcludeNone?: boolean;
-}): FakeLitellm => {
+export const startFakeLitellm = (
+  options?: {
+    readonly masterKey?: string;
+    readonly seed?: readonly PassThroughGenericEndpoint[];
+    /** Every `DELETE` 400s `not_allowed_access`, whether or not the row exists — see the file header. */
+    readonly forbidDelete?: boolean;
+    readonly budgetSeed?: readonly Record<string, unknown>[];
+    /** `/budget/update` drops `null`s instead of writing them (an `exclude_none` merge). */
+    readonly budgetExcludeNone?: boolean;
+  } & FakeKeysOptions,
+): FakeLitellm => {
   const masterKey = options?.masterKey ?? 'sk-test-master';
   const forbidDelete = options?.forbidDelete ?? false;
   let rows: PassThroughGenericEndpoint[] = [...(options?.seed ?? [])];
   const requests: FakeRequest[] = [];
   let budgets: Record<string, unknown>[] = [...(options?.budgetSeed ?? [])];
+  // ★ A KEY'S `budget_id` MUST NAME A LIVE BUDGET — the foreign key that makes `LiteLLM.Key` wait for
+  //   the `LiteLLM.Budget` it binds to. Read at call time: `budgets` is reassigned on every write.
+  const keys = createFakeKeys(options, (id) => budgets.some((row) => row['budget_id'] === id));
 
   /**
    * ⚠️ Shapes from the generated 1.100.0 schema (`budget_management.ts`), not a live 1.103.0 read.
@@ -110,6 +118,7 @@ export const startFakeLitellm = (options?: {
     const auth = request.headers.get('authorization');
     if (auth !== `Bearer ${masterKey}`) return json(401, { detail: 'invalid api key' });
     if (url.pathname.startsWith('/budget/')) return budgetRoute(request, url);
+    if (url.pathname.startsWith('/key/')) return keys.route(request, url);
     if (
       url.pathname !== '/config/pass_through_endpoint' &&
       !url.pathname.startsWith('/config/pass_through_endpoint/')
@@ -164,6 +173,7 @@ export const startFakeLitellm = (options?: {
   return {
     budgets: () => [...budgets],
     fetch,
+    keys,
     requests: () => [...requests],
     rows: () => [...rows],
   };