@homeflare/alchemy 0.42.0 → 0.44.0

package/src/litellm/credential-form.ts

@@ -0,0 +1,211 @@
+/**
+ * Refusals, wire bodies, the read shape and the comparison for `LiteLLM.Credential`, testable
+ * without a server. Value handling is credential-values.ts's.
+ *
+ * ⛔ WHAT IS COMPARED, WITH THE VENDOR'S MASKING IN MIND. Both reads answer `credential_values`
+ *   with SENSITIVE-keyed values masked (2 + `****` + 2, `*****` for a short string —
+ *   `litellm_logging.py::_get_masked_values`, measured in the live 1.103.0 container) and
+ *   `credential_info` in full:
+ *   - `credential_info` is the complete intended map, including on adoption. Nonempty PATCH
+ *     normally replaces DB info (`credential_endpoints/endpoints.py:314-319`, 1.103.0), while
+ *     memory merges (:385-387). Empty info leaves DB unchanged. Dropping a live info key therefore
+ *     requires a rewrite to converge both stores (`removedInfoKeys`). Every PATCH sends full info.
+ *   - the values are compared only through the seal of the values this process RESOLVED
+ *     (`valuesSeal`, credential-values.ts) — never against the masked fragments, which are
+ *     partial secrets and are never copied into state.
+ * ★ A CHANGED ROW IS PATCHED, NOT REWRITTEN. The vendor's PATCH merges VALUES by key
+ *   (`update_db_credential`:312), so updating a value or an `info` entry is a PATCH carrying the
+ *   declared `credential_info` and (only when the values are stale) the resolved
+ *   `credential_values`. A PATCH that fails on the wire leaves the row it was merging into — the
+ *   fix for the review's finding 3, where a DELETE + POST rewrite left NO row when the POST failed
+ *   after the DELETE. PATCH cannot REMOVE a value key or an in-memory info key, so dropping either
+ *   is still a whole-row rewrite (credential.ts decides). Names from the read prove removal. The
+ *   PATCH body carries `credential_name` IN THE BODY as a second member (`credential_name_body`,
+ *   wire-named `credential_name`) because the vendor's `UpdateCredentialItem` requires it and a
+ *   Smithy member has one binding — the path label can't also be the body field; the distilled
+ *   patch for it is `patches/credential_management/update_credential_credentials__credential_name__patch.json`.
+ */
+import type * as credentials from '@distilled.cloud/litellm/credential_management';
+import * as Redacted from 'effect/Redacted';
+import {
+  type CredentialAttributes,
+  type CredentialProps,
+  isBlank,
+  isSensitiveKey,
+} from './credential-types.ts';
+import type { ResolvedValues } from './credential-values.ts';
+
+/** The first reason a declaration is refused, or `undefined`. Pure: no environment, no server. */
+export const firstProblem = (props: CredentialProps): string | undefined => {
+  if (isBlank(props.credentialName) || props.credentialName !== props.credentialName.trim()) {
+    return '`credentialName` must be a non-empty string without leading or trailing whitespace';
+  }
+  if (
+    props.credentialInfo !== undefined &&
+    (typeof props.credentialInfo !== 'object' || props.credentialInfo === null)
+  ) {
+    return '`credentialInfo` must be an object of metadata';
+  }
+  if (props.credentialInfo !== undefined) {
+    for (const key of Object.keys(props.credentialInfo)) {
+      if (isSensitiveKey(key)) {
+        return (
+          `\`credentialInfo\` must not declare "${key}": LiteLLM returns \`credential_info\` ` +
+          'unmasked, so declare it in `credentialValues`, which LiteLLM stores encrypted'
+        );
+      }
+    }
+  }
+  if (Object.keys(props.credentialValues).length === 0) {
+    return (
+      '`credentialValues` needs at least one entry: LiteLLM refuses a credential with neither ' +
+      '`credential_values` nor a model_id, and `model_id` is not modelled here'
+    );
+  }
+  for (const key of Object.keys(props.credentialValues)) {
+    if (isBlank(key) || key !== key.trim()) {
+      return '`credentialValues` keys must be non-empty strings without padding';
+    }
+    const entry = props.credentialValues[key];
+    if (typeof entry !== 'object' || entry === null || isBlank(entry.fromEnv)) {
+      return `\`credentialValues["${key}"]\` takes \`{ fromEnv: 'NAME' }\`, never a value: the value would land in Alchemy's unencrypted state`;
+    }
+  }
+  return undefined;
+};
+
+/**
+ * Wire names of the fields where the live row and the declaration disagree, for a
+ * `NotConvergedError` and for the drift decision. The NAME is identity — a changed name plans a
+ * REPLACE in credential.ts and is never compared here. Values are never compared against the
+ * live row at all: the seal decides (credential-values.ts).
+ */
+export const differing = (
+  live: CredentialAttributes,
+  props: CredentialProps,
+): readonly string[] => {
+  const out: string[] = [];
+  if (props.credentialInfo !== undefined) {
+    for (const [key, declared] of Object.entries(props.credentialInfo)) {
+      if (!isSensitiveKey(key) && !jsonEquals(live.credentialInfo[key], declared)) {
+        out.push(`credential_info.${key}`);
+      }
+    }
+  }
+  return out;
+};
+
+/** Canonical-JSON deep equality, order-insensitive for objects. */
+const jsonEquals = (left: unknown, right: unknown): boolean =>
+  JSON.stringify(canonicalise(left)) === JSON.stringify(canonicalise(right));
+
+const canonicalise = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(canonicalise);
+  if (typeof value === 'object' && value !== null) {
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      out[key] = canonicalise((value as Record<string, unknown>)[key]);
+    }
+    return out;
+  }
+  return value;
+};
+
+/**
+ * One row of a credentials read, as attributes. ⛔ COPIES NO `credential_values` ENTRY: a masked
+ * fragment (`sk****45`) is a partial secret, and a sensitive key the read masks would land half a
+ * secret in Alchemy's state. The `credential_info` mirror drops SENSITIVE-KEYED entries (they are
+ * returned unmasked and would mirror a clear secret into state). The digest is the caller's
+ * (credential.ts fills `valuesSeal` from state; a row cannot supply one).
+ */
+export const toAttributes = (row: Record<string, unknown>): CredentialAttributes => {
+  const info = (row['credential_info'] ?? {}) as Record<string, unknown>;
+  const mirrored: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(info)) {
+    if (!isSensitiveKey(key)) mirrored[key] = value;
+  }
+  return {
+    credentialInfo: mirrored,
+    credentialName: String(row['credential_name'] ?? ''),
+    valueKeys: Object.keys((row['credential_values'] ?? {}) as Record<string, unknown>).sort(),
+    infoKeys: Object.keys(info).sort(),
+    valuesSeal: '',
+  };
+};
+
+/** The rows a credentials read carries, `CredentialItem`-shaped. */
+export const isCredentialRow = (row: unknown): row is Record<string, unknown> =>
+  typeof row === 'object' &&
+  row !== null &&
+  typeof (row as Record<string, unknown>)['credential_name'] === 'string';
+
+/**
+ * The literal values a create or a values-stale PATCH sends, unwrapped from their `Redacted`
+ * exactly once. ⛔ EVERY DECLARED ENTRY IS SENT: the whole-row create and the values-stale PATCH
+ * both demand every declared value (`requireValues`), so there is no partial send that could
+ * leave a stale value behind under a declared key.
+ */
+export const literalValues = (resolved: ResolvedValues): Readonly<Record<string, unknown>> =>
+  Object.fromEntries(
+    Object.entries(resolved.values).map(([key, value]) => [key, Redacted.value(value)]),
+  );
+
+/** The body `POST /credentials` carries — the name IN THE BODY (measured with a stub fetch). */
+export const createBody = (
+  props: CredentialProps,
+  resolved: ResolvedValues,
+): credentials.CreateCredentialCredentialsPostRequest => {
+  const body: Record<string, unknown> = {
+    credential_info: { ...props.credentialInfo },
+    credential_name: props.credentialName,
+    credential_values: { ...literalValues(resolved) },
+  };
+  return body as unknown as credentials.CreateCredentialCredentialsPostRequest;
+};
+
+/**
+ * The body `PATCH /credentials/{name}` carries — the declared `credential_info` always (the
+ * vendor's `UpdateCredentialItem` REQUIRES it, and the DB normally replaces the info map), the
+ * resolved `credential_values` only when the caller passes them (a values-stale write; an
+ * info-only drift sends none, so it never demands a value the environment does not hold).
+ *
+ * ⛔ `credential_name` APPEARS TWICE, ON PURPOSE: `credential_name` is the path label (its URI
+ *   placeholder is the row's address), and `credential_name_body` is the SAME value as a body
+ *   field wire-named `credential_name` — the vendor's `UpdateCredentialItem` requires the name in
+ *   the body, a Smithy member can carry only ONE binding, and the kit never renames in place (a
+ *   changed name is a REPLACE, credential.ts), so the two are always equal here.
+ */
+export const patchBody = (
+  props: CredentialProps,
+  values: Readonly<Record<string, unknown>> | undefined,
+): credentials.UpdateCredentialCredentialsCredentialNamePatchRequest => {
+  const body: Record<string, unknown> = {
+    credential_info: { ...props.credentialInfo },
+    credential_name: props.credentialName,
+    credential_name_body: props.credentialName,
+  };
+  if (values !== undefined) body.credential_values = { ...values };
+  return body as unknown as credentials.UpdateCredentialCredentialsCredentialNamePatchRequest;
+};
+
+/**
+ * All live info keys absent from the intended map, including on adoption. DB replacement alone
+ * cannot clear memory, so these require a rewrite. Only names of sensitive info are remembered.
+ */
+export const removedInfoKeys = (
+  prior: CredentialAttributes | undefined,
+  props: CredentialProps,
+): readonly string[] => {
+  if (prior === undefined) return [];
+  const declared = props.credentialInfo ?? {};
+  return (prior.infoKeys ?? Object.keys(prior.credentialInfo)).filter(
+    (key) => !Object.hasOwn(declared, key),
+  );
+};
+
+/** Values merge in BOTH stores, so dropped names from the masked read require a rewrite. */
+export const removedValueKeys = (
+  live: CredentialAttributes | undefined,
+  props: CredentialProps,
+): readonly string[] =>
+  (live?.valueKeys ?? []).filter((key) => !Object.hasOwn(props.credentialValues, key));

package/src/litellm/credential-guards.test.ts

@@ -0,0 +1,241 @@
+/**
+ * The guards `LiteLLM.Credential` adds on top of the typed SDK calls, tested at the handler level
+ * (a value is in the request body of `POST /credentials`, so a create that dies on the wire, or one
+ * made while the SDK's debug printing is on, would put it where nobody should see it) and through
+ * Alchemy's real Plan and Apply (a rename onto a row another owner holds must be refused, not
+ * overwritten).
+ *
+ * ★ EVERY VALUE IS `FAKE-*`, and a test that asserts a value is absent needs a value it can search
+ *   for: `FAKE-key-one` is the credential value the declaration resolves from `process.env`.
+ */
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { credentials } from '@distilled.cloud/litellm/Credentials';
+import { Retry } from '@distilled.cloud/litellm/Retry';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Logger from 'effect/Logger';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { credentialHandlers } from './credential.ts';
+import type { CredentialProps } from './credential-types.ts';
+import { resolveValues, sealValues } from './credential-values.ts';
+import { credentialRow, startFakeCredentialLitellm } from './fake-credential-litellm.ts';
+import { FAKE_BASE } from './fake-litellm.ts';
+import { fakeStack, writesOf } from './fake-stack.ts';
+import { LiteLLMCredential } from './credential.ts';
+
+const KEY = 'sk-test-master';
+const VARIABLE = 'FAKE_CREDENTIAL_GUARD_KEY';
+const VALUE = 'FAKE-key-one';
+
+const props: CredentialProps = {
+  credentialInfo: { note: 'docs search' },
+  credentialName: 'FAKE_api',
+  credentialValues: { api_key: { fromEnv: VARIABLE } },
+};
+
+beforeEach(() => {
+  process.env[VARIABLE] = VALUE;
+});
+afterEach(() => {
+  delete process.env[VARIABLE];
+  delete process.env.DISTILLED_DEBUG_HTTP;
+});
+
+type Fake = ReturnType<typeof startFakeCredentialLitellm>;
+
+/** One reconcile effect at the handler level, against the fake, with the SDK's retry OFF. */
+const reconcileEffect = (
+  fake: Fake,
+  news: CredentialProps,
+  output: Parameters<typeof credentialHandlers.reconcile>[0]['output'] = undefined,
+) =>
+  credentialHandlers
+    .reconcile({ fqn: 'Cred', instanceId: 'i-1', news, output })
+    .pipe(
+      Effect.provideService(Retry, { while: () => false }),
+      Effect.provide(FetchHttpClient.layer),
+      Effect.provide(Layer.succeed(FetchHttpClient.Fetch, fake.fetch)),
+      Effect.provide(credentials({ apiKey: KEY, baseUrl: FAKE_BASE })),
+    ) as Effect.Effect<unknown, unknown, never>;
+
+/** Runs the reconcile to a value, or the failure it raised. */
+const runReconcile = (fake: Fake, news: CredentialProps): Promise<unknown> =>
+  Effect.runPromise(Effect.flip(reconcileEffect(fake, news)));
+
+/** A fake whose `POST /credentials` drops the connection before any answer. */
+const droppedCreate = (fake: Fake): Fake => ({
+  ...fake,
+  fetch: (async (input: string | URL | Request, init?: RequestInit) => {
+    const request = input instanceof Request ? input : new Request(String(input), init);
+    if (new URL(request.url).pathname === '/credentials' && request.method === 'POST') {
+      throw new TypeError('fetch failed');
+    }
+    return fake.fetch(input, init);
+  }) as typeof globalThis.fetch,
+});
+
+/** A fake whose `PATCH /credentials/{name}` drops the connection before any answer. */
+const droppedPatch = (fake: Fake): Fake => ({
+  ...fake,
+  fetch: (async (input: string | URL | Request, init?: RequestInit) => {
+    const request = input instanceof Request ? input : new Request(String(input), init);
+    if (request.method === 'PATCH' && new URL(request.url).pathname.startsWith('/credentials/')) {
+      const body = (await request.json()) as Record<string, unknown>;
+      expect(Object.keys((body.credential_values ?? {}) as object)).toEqual(['api_key']);
+      throw new TypeError('fetch failed');
+    }
+    return fake.fetch(input, init);
+  }) as typeof globalThis.fetch,
+});
+
+/** What Effect's JSON logger prints for the 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, 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 (typeof value === 'object' && value !== null && 'message' in value) {
+    readings.push(String(value.message), 'stack' in value ? String(value.stack) : '');
+  }
+  return readings.join('\n');
+};
+
+describe('a rename onto a row another owner holds', () => {
+  test('is refused at apply, the foreign row untouched, nothing written', async () => {
+    const fake = startFakeCredentialLitellm({
+      masterKey: KEY,
+      seed: [
+        credentialRow({
+          credential_info: { note: 'another owner' },
+          credential_name: 'FAKE_api2',
+          credential_values: { api_key: 'FAKE-elsewhere' },
+        }),
+      ],
+    });
+    const engine = fakeStack({ apiKey: KEY, baseUrl: FAKE_BASE }, fake.fetch);
+    const declare = (p: CredentialProps) =>
+      Effect.gen(function* () {
+        yield* LiteLLMCredential('Cred', p);
+      });
+    // Own `FAKE_api` first, then rename onto the seeded `FAKE_api2`.
+    await engine.deploy(declare(props));
+    const before = fake.requests().length;
+    await expect(engine.deploy(declare({ ...props, credentialName: 'FAKE_api2' }))).rejects.toThrow(
+      /already exists/,
+    );
+    expect(writesOf(fake.requests().slice(before))).toEqual([]);
+    expect(fake.rows().find((row) => row['credential_name'] === 'FAKE_api2')).toMatchObject({
+      credential_info: { note: 'another owner' },
+      credential_values: { api_key: 'FAKE-elsewhere' },
+    });
+  });
+
+  test('is refused even under --adopt (a replace is never probed for adoption)', async () => {
+    const fake = startFakeCredentialLitellm({
+      masterKey: KEY,
+      seed: [credentialRow({ credential_name: 'FAKE_api2', credential_values: { api_key: 'x' } })],
+    });
+    const engine = fakeStack({ apiKey: KEY, baseUrl: FAKE_BASE }, fake.fetch);
+    const declare = (p: CredentialProps) =>
+      Effect.gen(function* () {
+        yield* LiteLLMCredential('Cred', p);
+      });
+    await engine.deploy(declare(props));
+    const before = fake.requests().length;
+    await expect(
+      engine.deploy(declare({ ...props, credentialName: 'FAKE_api2' }), { adopt: true }),
+    ).rejects.toThrow(/--adopt does not cover/);
+    expect(writesOf(fake.requests().slice(before))).toEqual([]);
+  });
+});
+
+describe('a create that dies on the wire', () => {
+  test('fails typed, names the credential, and holds no request and no value', async () => {
+    const fake = droppedCreate(startFakeCredentialLitellm({ masterKey: KEY }));
+    const error = await runReconcile(fake, props);
+    expect(error).toMatchObject({
+      _tag: 'LitellmCredentialTransportError',
+      credentialName: 'FAKE_api',
+      reason: 'TransportError',
+    });
+    expect(Object.keys(error as object)).not.toContain('request');
+    expect(Object.keys(error as object)).not.toContain('cause');
+    expect(await everyReadingOf(error)).not.toContain(VALUE);
+  });
+});
+
+describe('an update that dies on the wire', () => {
+  test('leaves the row in place, fails typed, holds no value', async () => {
+    // The owned row has a stale seal: this failing PATCH MUST carry credential values.
+    const fake = droppedPatch(
+      startFakeCredentialLitellm({
+        masterKey: KEY,
+        seed: [
+          credentialRow({
+            credential_info: { note: 'docs search' },
+            credential_name: 'FAKE_api',
+            credential_values: { api_key: VALUE },
+          }),
+        ],
+      }),
+    );
+    const sealed = sealValues(resolveValues(props).values);
+    process.env[VARIABLE] = 'FAKE-key-rotated';
+    const error = await Effect.runPromise(
+      Effect.flip(
+        reconcileEffect(fake, props, {
+          credentialInfo: { note: 'docs search' },
+          credentialName: 'FAKE_api',
+          valuesSeal: sealed,
+        }),
+      ),
+    );
+    expect(error).toMatchObject({
+      _tag: 'LitellmCredentialTransportError',
+      credentialName: 'FAKE_api',
+      reason: 'TransportError',
+    });
+    expect(Object.keys(error as object)).not.toContain('request');
+    expect(await everyReadingOf(error)).not.toContain('FAKE-key-rotated');
+    // ★ finding 3: a PATCH that dies leaves the row it was merging into — the old DELETE + POST
+    //   rewrite left NO row when the POST failed after the DELETE.
+    expect(fake.rows()).toHaveLength(1);
+    expect(fake.rows()[0]?.['credential_info']).toEqual({ note: 'docs search' });
+    expect(fake.rows()[0]?.['credential_values']).toEqual({ api_key: VALUE });
+  });
+});
+
+describe('a create while the SDK prints bodies', () => {
+  test('is refused before any request, naming the credential', async () => {
+    process.env.DISTILLED_DEBUG_HTTP = '1';
+    const fake = startFakeCredentialLitellm({ masterKey: KEY });
+    const error = await runReconcile(fake, props);
+    expect(error).toMatchObject({
+      _tag: 'LitellmCredentialDebugLoggingError',
+      credentialName: 'FAKE_api',
+    });
+    // Refuse at the top of reconcile: even a read can expose unmasked non-sensitive values.
+    expect(writesOf(fake.requests())).toEqual([]);
+  });
+});
+
+describe('an absent credential is caught as absence, never a failure', () => {
+  test('reconcile of a create with no live row converges (the read 404 is CredentialNotFound)', async () => {
+    const fake = startFakeCredentialLitellm({ masterKey: KEY });
+    const result = await Effect.runPromise(reconcileEffect(fake, props));
+    expect(result).toMatchObject({ credentialName: 'FAKE_api' });
+    expect(writesOf(fake.requests())).toEqual(['POST /credentials']);
+  });
+});

package/src/litellm/credential-operations.ts

@@ -0,0 +1,208 @@
+/**
+ * The `@distilled.cloud/litellm/credential_management` calls `LiteLLM.Credential` uses
+ * (LiteLLM 1.103.0; names verified in the generated source, never guessed):
+ *
+ *   read    `getCredentialByNameCredentialsByNameCredentialNameGet`  GET     /credentials/by_name/{name}
+ *   create  `createCredentialCredentialsPost`                        POST    /credentials
+ *   update  `updateCredentialCredentialsCredentialNamePatch`        PATCH   /credentials/{name}
+ *   delete  `deleteCredentialCredentialsCredentialNameDelete`        DELETE  /credentials/{name}
+ *
+ * ★ THE UPDATE IS A PATCH, NOT A REWRITE. The vendor's PATCH merges value keys; nonempty info
+ *   normally replaces the DB map but merges in memory (`endpoints.py:312-319,384-387`, 1.103.0).
+ *   The body carries `credential_name` as a second member
+ *   (`credential_name_body`, wire-named `credential_name`) because the vendor's
+ *   `UpdateCredentialItem` requires it in the body and a Smithy member has one binding — the
+ *   distilled patch `patches/credential_management/update_credential_credentials__credential_name__patch.json`.
+ *   A PATCH that fails on the wire leaves the row it was merging into, where the old DELETE + POST
+ *   rewrite left NO row when the POST failed after the DELETE (review finding 3). credential.ts
+ *   still rewrites to drop value or info keys, since PATCH cannot remove them from both stores.
+ * ⛔ NO MESSAGE SNIFFING (S21). The read's and delete's `404` is typed as the SDK's
+ *   `CredentialNotFound` (a distilled patch matched on the vendor's "Credential not found" message,
+ *   `endpoints.py`), so absence is that TAG, `catchTag`ed — never `instanceof`, never error text. A
+ *   404 from a front proxy, Access, or a wrong base path decodes as core's `NotFound` and stays an
+ *   error, never absence. A create on a name the DB already has answers `409` (`endpoints.py`'s
+ *   unique-violation handling), decoded as core `Conflict`, and is PROPAGATED: a row another writer
+ *   raced in is not this declaration's row. The PATCH's own 404 (message `Credential not found in
+ *   DB.`) is NOT `CredentialNotFound`: it stays core `NotFound`, an error — a row deleted between
+ *   the read and the PATCH must not silently read as absence.
+ * ⚠️ THE READ AND THE DELETE ASK DIFFERENT STORES (measured, `endpoints.py`): the by-name read
+ *   walks the proxy's IN-MEMORY `credential_list` (a row the proxy has not loaded answers 404),
+ *   while the delete consults the DATABASE (`delete_by_name`) and removes the in-memory entry
+ *   after. A row present in the DB but not loaded in memory reads as ABSENT, and a create for it
+ *   answers `409` — the resource reports that failure loudly instead of pretending to converge.
+ * ⚠️ Unlike pass-through endpoints, each credential is its own DB row: no semaphore.
+ */
+import * as credentials from '@distilled.cloud/litellm/credential_management';
+import * as Effect from 'effect/Effect';
+import * as Predicate from 'effect/Predicate';
+import { isHttpClientError } from 'effect/unstable/http/HttpClientError';
+import { isCredentialRow, toAttributes } from './credential-form.ts';
+import type { CredentialAttributes } from './credential-types.ts';
+import {
+  LitellmCredentialDebugLoggingError,
+  LitellmCredentialTransportError,
+  LitellmCredentialUnreadableError,
+} from './credential-errors.ts';
+import { type LitellmOpContext, throughFetch } from './operations.ts';
+
+/**
+ * One credential by name, or `undefined` when the proxy does not hold it in memory. ⛔ ANY FAILURE
+ * OTHER THAN `CredentialNotFound` PROPAGATES: a 401, a 422 or a dead network says nothing about
+ * whether the row exists, and must never be read as absence.
+ */
+export const readCredential = (
+  credentialName: string,
+): Effect.Effect<
+  CredentialAttributes | undefined,
+  | credentials.GetCredentialByNameCredentialsByNameCredentialNameGetError
+  | LitellmCredentialUnreadableError,
+  LitellmOpContext
+> =>
+  throughFetch(
+    credentials.getCredentialByNameCredentialsByNameCredentialNameGet({
+      credential_name: credentialName,
+    }),
+  ).pipe(
+    Effect.catchTag('CredentialNotFound', () => Effect.succeed(undefined)),
+    Effect.flatMap((response) => {
+      if (response === undefined) return Effect.succeed(undefined);
+      if (!isCredentialRow(response)) {
+        return Effect.fail(
+          new LitellmCredentialUnreadableError({
+            reason: 'the by-name read did not answer a credential row',
+          }),
+        );
+      }
+      const answer = String(response['credential_name']);
+      // The name is re-checked on the answer: a proxy that answered some other row must never be
+      // adopted as this one's.
+      return answer === credentialName
+        ? Effect.succeed(toAttributes(response))
+        : Effect.fail(
+            new LitellmCredentialUnreadableError({
+              reason: 'the by-name read answered a different credential name',
+            }),
+          );
+    }),
+  );
+
+/**
+ * POST /credentials. The answer carries no row (`{"success": true, ...}`), so the read back is the
+ * proof.
+ *
+ * ⛔ THE REQUEST BODY CARRIES THE VALUES, AND A FAILED CALL CAN CARRY ITS REQUEST — exactly the
+ *   `{"key":"sk-…"}` leak `generateKey` (key-operations.ts) closes, and it is closed the same way:
+ *   a transport failure is an `HttpClientError` in the error channel, a body that fails mid-read is
+ *   the SAME error as a DEFECT (`Effect.orDie` in core's `protocol-rest.ts`). Both become
+ *   `LitellmCredentialTransportError`, which keeps the NAME and the reason's tag and nothing else.
+ * ⛔ RECONCILE REFUSES WHILE `DISTILLED_DEBUG_HTTP` IS SET, before any request: the SDK prints
+ *   the first 400 characters of every request body (core `protocol-http.ts`), which would put the values on
+ *   stderr — the same refusal `key-secret.ts` makes for `/key/generate`.
+ */
+export const createCredential = (
+  body: credentials.CreateCredentialCredentialsPostRequest,
+): Effect.Effect<
+  void,
+  credentials.CreateCredentialCredentialsPostError | LitellmCredentialTransportError,
+  LitellmOpContext
+> => {
+  const credentialName = body.credential_name ?? '';
+  return Effect.gen(function* () {
+    yield* throughFetch(credentials.createCredentialCredentialsPost(body)).pipe(
+      Effect.asVoid,
+      Effect.catchTag('HttpClientError', (error) =>
+        Effect.fail(
+          new LitellmCredentialTransportError({ credentialName, reason: error.reason._tag }),
+        ),
+      ),
+      Effect.catchDefect((defect) =>
+        carriesRequest(defect)
+          ? Effect.fail(
+              new LitellmCredentialTransportError({
+                credentialName,
+                reason: isHttpClientError(defect) ? defect.reason._tag : 'Defect',
+              }),
+            )
+          : Effect.die(defect),
+      ),
+    );
+  });
+};
+
+/**
+ * PATCH /credentials/{name}. Sends the full intended `credential_info` (DB replacement, memory
+ * merge) and merges resolved `credential_values` when present. The answer carries no row
+ * (`{"success": true, ...}`), so the read back is the proof.
+ *
+ * ⛔ THE SAME TWO GUARDS AS `createCredential`: the body carries the values, so a transport failure
+ *   becomes a `LitellmCredentialTransportError` that keeps the NAME and the reason's tag and
+ *   nothing else, and reconcile refuses while `DISTILLED_DEBUG_HTTP` is set (the SDK would print
+ *   the values). A PATCH that fails on the wire leaves the row in place — the point of using it
+ *   over a DELETE + POST rewrite.
+ */
+export const updateCredential = (
+  body: credentials.UpdateCredentialCredentialsCredentialNamePatchRequest,
+): Effect.Effect<
+  void,
+  credentials.UpdateCredentialCredentialsCredentialNamePatchError | LitellmCredentialTransportError,
+  LitellmOpContext
+> => {
+  const credentialName = body.credential_name ?? '';
+  return Effect.gen(function* () {
+    yield* throughFetch(credentials.updateCredentialCredentialsCredentialNamePatch(body)).pipe(
+      Effect.asVoid,
+      Effect.catchTag('HttpClientError', (error) =>
+        Effect.fail(
+          new LitellmCredentialTransportError({ credentialName, reason: error.reason._tag }),
+        ),
+      ),
+      Effect.catchDefect((defect) =>
+        carriesRequest(defect)
+          ? Effect.fail(
+              new LitellmCredentialTransportError({
+                credentialName,
+                reason: isHttpClientError(defect) ? defect.reason._tag : 'Defect',
+              }),
+            )
+          : Effect.die(defect),
+      ),
+    );
+  });
+};
+
+/**
+ * DELETE /credentials/{name}, idempotent BY THIS FUNCTION: the vendor answers 404 for a name its
+ * database does not have, which this treats as already-absent — the DB is the authoritative store
+ * the delete consults (the read consults memory, see the header). Any other failure propagates.
+ */
+export const deleteCredential = (
+  credentialName: string,
+): Effect.Effect<
+  void,
+  credentials.DeleteCredentialCredentialsCredentialNameDeleteError,
+  LitellmOpContext
+> =>
+  throughFetch(
+    credentials.deleteCredentialCredentialsCredentialNameDelete({
+      credential_name: credentialName,
+    }),
+  ).pipe(
+    Effect.asVoid,
+    Effect.catchTag('CredentialNotFound', () => Effect.void),
+  );
+
+/**
+ * Whether `DISTILLED_DEBUG_HTTP` is set, refused once at the top of reconcile, before even a
+ * DELETE can run (the following POST would carry values). Reads `process.env` because that is
+ * what the SDK's `protocol-http.ts` reads.
+ */
+export const refuseDebugLogging = (
+  credentialName: string,
+): Effect.Effect<void, LitellmCredentialDebugLoggingError> =>
+  (globalThis.process?.env?.['DISTILLED_DEBUG_HTTP'] ?? '') !== ''
+    ? Effect.fail(new LitellmCredentialDebugLoggingError({ credentialName }))
+    : Effect.void;
+
+/** An `HttpClientError` (or a defect that is one) carries its request — and thus the values. */
+const carriesRequest = (value: unknown): boolean =>
+  isHttpClientError(value) || Predicate.hasProperty(value, 'request');