@homeflare/alchemy 0.43.0 → 0.45.0

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');

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

@@ -0,0 +1,93 @@
+/** A failed rewrite must describe the completed DELETE and recover on the next real deploy. */
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { type CredentialProps, LiteLLMCredential, credentialHandlers } from './credential.ts';
+import { startFakeCredentialLitellm } from './fake-credential-litellm.ts';
+import { fakeStack, writesOf } from './fake-stack.ts';
+import { FAKE_BASE } from './fake-litellm.ts';
+import { FAKE_KEY, MASTER_KEY, failureOf, newFake, runAgainst, withEnv } from './key-harness.ts';
+
+const variable = 'FAKE_RECOVERY_KEY';
+const props: CredentialProps = {
+  credentialName: 'recovery',
+  credentialInfo: { note: 'search' },
+  credentialValues: { api_key: { fromEnv: variable } },
+};
+const original = { ...props, credentialInfo: { ...props.credentialInfo, extra: 'remove' } };
+const declare = (news: CredentialProps) =>
+  Effect.gen(function* () {
+    yield* LiteLLMCredential('Cred', news);
+  });
+
+for (const mode of ['transport', 'forbidden', 'validation'] as const) {
+  test(`a rewrite POST ${mode} failure reports DELETE and the next deploy recreates`, async () => {
+    const fake = startFakeCredentialLitellm({ masterKey: MASTER_KEY });
+    let failPost = false;
+    let postsFailed = 0;
+    const fetch = (async (input, init) => {
+      const request =
+        input instanceof Request ? new Request(input, init) : new Request(String(input), init);
+      if (
+        failPost &&
+        request.method === 'POST' &&
+        new URL(request.url).pathname === '/credentials'
+      ) {
+        postsFailed += 1;
+        if (mode === 'transport') throw new TypeError('connection dropped');
+        return new Response(JSON.stringify({ detail: 'replacement rejected' }), {
+          status: mode === 'forbidden' ? 403 : 422,
+          headers: { 'content-type': 'application/json' },
+        });
+      }
+      return fake.fetch(request);
+    }) as typeof globalThis.fetch;
+    const engine = fakeStack({ apiKey: MASTER_KEY, baseUrl: FAKE_BASE }, fetch, 'Recovery', {
+      noRetry: true,
+    });
+    await withEnv({ [variable]: FAKE_KEY }, async () => {
+      await engine.deploy(declare(original));
+      failPost = true;
+      const message = await failureOf(engine.deploy(declare(props)));
+      expect(message).toContain('DELETE already ran');
+      expect(message).toContain('next deploy recreates');
+      expect(message.includes(FAKE_KEY)).toBe(false);
+      expect(postsFailed).toBe(1);
+      expect(fake.rows()).toHaveLength(0);
+      expect(writesOf(fake.requests())).toEqual([
+        'POST /credentials',
+        'DELETE /credentials/recovery',
+      ]);
+      failPost = false;
+      await engine.deploy(declare(props));
+      expect(fake.rows()).toHaveLength(1);
+      expect(fake.rows()[0]?.credential_info).toEqual(props.credentialInfo);
+      expect(await engine.deploy(declare(props))).toEqual({ Cred: 'noop' });
+      expect(engine.snapshot().includes(FAKE_KEY)).toBe(false);
+
+      // The same failure is catchable in the error channel, with no request or cause retained.
+      await engine.deploy(declare(original));
+      failPost = true;
+      const error = await runAgainst(
+        { ...newFake(), fetch },
+        credentialHandlers
+          .reconcile({
+            fqn: 'Cred',
+            instanceId: 'i-1',
+            news: props,
+            output: {
+              credentialName: props.credentialName,
+              credentialInfo: original.credentialInfo,
+              valuesSeal: '',
+            },
+          })
+          .pipe(
+            Effect.catchTag('LitellmCredentialRewriteError', (failure) => Effect.succeed(failure)),
+          ),
+      );
+      expect('_tag' in error && error._tag).toBe('LitellmCredentialRewriteError');
+      expect(JSON.stringify(error).includes(FAKE_KEY)).toBe(false);
+      expect('cause' in error).toBe(false);
+      expect('request' in error).toBe(false);
+    });
+  });
+}

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

@@ -0,0 +1,164 @@
+/** Removal needs both LiteLLM stores to converge; preflight must finish before DELETE. */
+import { afterEach, beforeEach, expect, test } from 'bun:test';
+import { credentials } from '@distilled.cloud/litellm/Credentials';
+import * as Effect from 'effect/Effect';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { type CredentialProps, LiteLLMCredential, credentialHandlers } from './credential.ts';
+import { credentialRow, startFakeCredentialLitellm } from './fake-credential-litellm.ts';
+import { FAKE_BASE } from './fake-litellm.ts';
+import { fakeStack, writesOf } from './fake-stack.ts';
+
+const variable = 'FAKE_REWRITE_KEY';
+const creds = { apiKey: 'FAKE-master', baseUrl: FAKE_BASE };
+const props: CredentialProps = {
+  credentialName: 'FAKE_api',
+  credentialInfo: { note: 'search' },
+  credentialValues: { api_key: { fromEnv: variable } },
+};
+const declare = (news: CredentialProps) =>
+  Effect.gen(function* () {
+    yield* LiteLLMCredential('Cred', news);
+  });
+const extraValues = {
+  ...props,
+  credentialValues: {
+    ...props.credentialValues,
+    api_base: { fromEnv: variable },
+  },
+};
+const extraInfo = { ...props, credentialInfo: { ...props.credentialInfo, team: 'a' } };
+const setup = () => {
+  const fake = startFakeCredentialLitellm({ masterKey: creds.apiKey });
+  return { fake, engine: fakeStack(creds, fake.fetch) };
+};
+beforeEach(() => {
+  process.env[variable] = 'FAKE-rewrite-value';
+});
+afterEach(() => {
+  delete process.env[variable];
+  delete process.env.DISTILLED_DEBUG_HTTP;
+});
+
+test('dropping a value key rewrites the row, removes it from DB and memory, then noops', async () => {
+  const { fake, engine } = setup();
+  await engine.deploy(declare(extraValues));
+  const before = fake.requests().length;
+  expect(await engine.deploy(declare(props))).toEqual({ Cred: 'update' });
+  expect(writesOf(fake.requests().slice(before))).toEqual([
+    'DELETE /credentials/FAKE_api',
+    'POST /credentials',
+  ]);
+  expect(Object.keys(fake.rows()[0]?.credential_values as object)).toEqual(['api_key']);
+  expect(await engine.deploy(declare(props))).toEqual({ Cred: 'noop' });
+  expect(engine.snapshot().includes('FAKE-rewrite-value')).toBe(false);
+});
+
+for (const [kind, original] of [
+  ['value', extraValues],
+  ['info', extraInfo],
+] as const) {
+  test(`dropping a ${kind} key with a missing value refuses before DELETE`, async () => {
+    const { fake, engine } = setup();
+    await engine.deploy(declare(original));
+    const before = fake.requests().length;
+    delete process.env[variable];
+    await expect(engine.deploy(declare(props))).rejects.toThrow(variable);
+    expect(writesOf(fake.requests().slice(before))).toEqual([]);
+    expect(fake.rows()).toHaveLength(1);
+  });
+
+  test(`dropping a ${kind} key under debug logging refuses before any reconcile request`, async () => {
+    const { fake, engine } = setup();
+    await engine.deploy(declare(original));
+    // The refusal is before any observation or write, so even stale state cannot bypass it.
+    const before = fake.requests().length;
+    process.env.DISTILLED_DEBUG_HTTP = '1';
+    const error = await Effect.runPromise(
+      credentialHandlers
+        .reconcile({
+          fqn: 'Cred',
+          instanceId: 'i-1',
+          news: props,
+          output: {
+            credentialName: props.credentialName,
+            credentialInfo: original.credentialInfo ?? {},
+            valuesSeal: '',
+          },
+        })
+        .pipe(
+          Effect.catchTag('LitellmCredentialDebugLoggingError', (failure) =>
+            Effect.succeed(failure._tag),
+          ),
+          Effect.provide(FetchHttpClient.layer),
+          Effect.provideService(FetchHttpClient.Fetch, fake.fetch),
+          Effect.provide(credentials(creds)),
+        ),
+    );
+    expect(error).toBe('LitellmCredentialDebugLoggingError');
+    expect(fake.requests()).toHaveLength(before);
+    expect(fake.rows()).toHaveLength(1);
+  });
+}
+
+test('adoption deliberately removes undeclared info keys, including withheld sensitive names', async () => {
+  const fake = startFakeCredentialLitellm({
+    masterKey: creds.apiKey,
+    seed: [
+      credentialRow({
+        credential_name: props.credentialName,
+        credential_info: { note: 'search', foreign: 'a', secret: 'FAKE-withheld' },
+        credential_values: { api_key: 'FAKE-existing' },
+      }),
+    ],
+  });
+  const engine = fakeStack(creds, fake.fetch);
+  await engine.deploy(declare(props), { adopt: true });
+  expect(writesOf(fake.requests())).toEqual(['DELETE /credentials/FAKE_api', 'POST /credentials']);
+  expect(Object.keys(fake.rows()[0]?.credential_info as object)).toEqual(['note']);
+  expect(engine.snapshot().includes('FAKE-withheld')).toBe(false);
+  expect(await engine.deploy(declare(props))).toEqual({ Cred: 'noop' });
+});
+
+test('PATCH records a complete intended info map and the required body name', async () => {
+  const { fake, engine } = setup();
+  await engine.deploy(declare(extraInfo));
+  const news = { ...extraInfo, credentialInfo: { note: 'changed', team: 'a' } };
+  await engine.deploy(declare(news));
+  expect(fake.bodies()[1]?.credential_name).toBe(props.credentialName);
+  expect(fake.bodies()[1]?.credential_info).toEqual(news.credentialInfo);
+  expect(fake.rows()[0]?.credential_info).toEqual(news.credentialInfo);
+  expect(await engine.deploy(declare(news))).toEqual({ Cred: 'noop' });
+});
+
+test('the fake rejects a PATCH with no body credential_name, matching UpdateCredentialItem', async () => {
+  const { fake, engine } = setup();
+  await engine.deploy(declare(props));
+  const response = await fake.fetch(`${FAKE_BASE}/credentials/FAKE_api`, {
+    method: 'PATCH',
+    headers: { authorization: `Bearer ${creds.apiKey}`, 'content-type': 'application/json' },
+    body: JSON.stringify({ credential_info: { note: 'changed' } }),
+  });
+  expect(response.status).toBe(422);
+  expect(fake.bodies()).toHaveLength(2);
+  expect(fake.rows()[0]?.credential_info).toEqual(props.credentialInfo);
+});
+
+test('a debug-enabled plan refuses before the read response can print unmasked values', async () => {
+  const { fake, engine } = setup();
+  await engine.deploy(declare(extraValues));
+  const before = fake.requests().length;
+  const printed: string[] = [];
+  const original = console.error;
+  console.error = (...args: unknown[]) => {
+    printed.push(args.join(' '));
+  };
+  try {
+    process.env.DISTILLED_DEBUG_HTTP = '1';
+    await expect(engine.deploy(declare(props))).rejects.toThrow('DISTILLED_DEBUG_HTTP');
+  } finally {
+    console.error = original;
+  }
+  expect(printed.join('\n').includes('FAKE-rewrite-value')).toBe(false);
+  expect(fake.requests()).toHaveLength(before);
+  expect(fake.rows()).toHaveLength(1);
+});

package/src/litellm/credential-rewrite.ts

@@ -0,0 +1,50 @@
+/** Whole-row removal needs a diagnostic that remembers DELETE succeeded before POST failed. */
+import type { API_ERRORS } from '@distilled.cloud/litellm/Errors';
+import type * as credentials from '@distilled.cloud/litellm/credential_management';
+import * as Effect from 'effect/Effect';
+import {
+  LitellmCredentialRewriteError,
+  type LitellmCredentialTransportError,
+} from './credential-errors.ts';
+import { createCredential, deleteCredential } from './credential-operations.ts';
+import type { LitellmOpContext } from './operations.ts';
+
+export const rewriteCredential = (body: credentials.CreateCredentialCredentialsPostRequest) =>
+  Effect.gen(function* () {
+    const credentialName = body.credential_name;
+    yield* deleteCredential(credentialName);
+    // The SDK's status fallback can emit every API_ERRORS member, including statuses absent
+    // from this operation's generated union. Keep only its tag, never a body/message/cause.
+    const post: Effect.Effect<
+      void,
+      | credentials.CreateCredentialCredentialsPostError
+      | LitellmCredentialTransportError
+      | InstanceType<(typeof API_ERRORS)[number]>,
+      LitellmOpContext
+    > = createCredential(body);
+    yield* post.pipe(
+      Effect.catchTag(
+        [
+          'BadGateway',
+          'BadRequest',
+          'ConfigError',
+          'Conflict',
+          'Forbidden',
+          'GatewayTimeout',
+          'HttpClientError',
+          'InternalServerError',
+          'LitellmCredentialTransportError',
+          'LitellmParseError',
+          'Locked',
+          'NotFound',
+          'ServiceUnavailable',
+          'TooManyRequests',
+          'Unauthorized',
+          'UnknownLitellmError',
+          'UnprocessableEntity',
+        ],
+        (error) =>
+          Effect.fail(new LitellmCredentialRewriteError({ credentialName, reason: error._tag })),
+      ),
+    );
+  });

package/src/litellm/credential-types.ts

@@ -0,0 +1,117 @@
+/**
+ * What `LiteLLM.Credential` declares (props) and what is remembered about it (attributes).
+ *
+ * ⛔ NO CREDENTIAL VALUE IS EVER A PROP OR AN ATTRIBUTE (S25). Alchemy persists props AND
+ *   attributes unencrypted (`StateEncoding.ts` writes a `Redacted` value's inner string beside
+ *   the tag — `secrets/write-only.ts`, measured on alchemy 2.0.0-beta.79), and LiteLLM stores a
+ *   credential's values ENCRYPTED in its database while the reads answer them MASKED, so a value
+ *   the declaration holds is `{ fromEnv: 'NAME' }` — NAME lands in state, and the value is read
+ *   from the DEPLOYING process's environment only when a write is being made
+ *   (`credential-values.ts`, the same shape `McpServerProps.authValue` uses). Unlike a model
+ *   deployment's `os.environ/NAME` reference (the PROXY resolves that in its own environment),
+ *   the credential table stores LITERAL values — measured in the live 1.103.0 container
+ *   (`credential_endpoints/endpoints.py`: `create_credential` encrypts the body's
+ *   `credential_values` before the insert, `CredentialsRepository.create`) — so the proxy could
+ *   not resolve a reference here even if one were sent.
+ * ⛔ THE LIVE ROW'S MASKED VALUES ARE NEVER MIRRORED INTO ATTRIBUTES. Both reads answer
+ *   `credential_values` with every SENSITIVE-keyed value masked (the vendor's own rule,
+ *   `_get_masked_values` in `litellm_logging.py`: a key matching `authorization`, `token`, `key`,
+ *   `secret`, `vertex_credentials`, `credentials`, `password` or `passwd` — substring,
+ *   case-insensitive — answers `v[:2] + "****" + v[-2:]` for a string longer than four
+ *   characters, `*****` otherwise; non-string values and non-sensitive keys answer in full).
+ *   A masked fragment (`sk****45`) is a PARTIAL SECRET, so `toAttributes` copies no
+ *   `credential_values` entry at all (`credential-form.ts`); what was last written is remembered
+ *   as the digest of the values this process RESOLVED, `valuesSeal` — never the values.
+ * ⚠️ `credential_info` IS THE COMPLETE INTENDED MAP, INCLUDING ON ADOPTION. Measured in
+ *   LiteLLM 1.103.0 `credential_endpoints/endpoints.py:314-319`: a nonempty PATCH normally resets
+ *   the DB info map (except when it contains a literal `credential_info` key); an empty patch
+ *   leaves it alone. Memory only merges (:385-387), retaining removed keys until restart.
+ *   Therefore removing any live info key requires a rewrite; every PATCH sends the full map.
+ *   Sensitive info keys are refused at plan time because the vendor returns info UNMASKED.
+ *   Reads retain their NAMES only, so removal can converge without persisting their values.
+ */
+import type { FromEnv } from '../secrets/write-only.ts';
+
+/**
+ * The credential's name — its identity in the vendor's table (a unique column, enforced by the
+ * database, `schema.prisma`'s `Credentials` model). ADOPTED: the live row whose `credential_name`
+ * equals it. ⛔ A RENAMED ROW IS A DIFFERENT CREDENTIAL: the name is the only address the vendor's
+ * routes have, so a changed `credentialName` plans a REPLACE — the old row survives under the
+ * resource's default `retain` policy, never renamed in place.
+ */
+export interface CredentialProps {
+  readonly credentialName: string;
+
+  /**
+   * Free-form metadata stored beside the values (`credential_info` in the vendor's row), compared
+   * as the complete intended map with canonical-JSON deep equality (omitted means empty). ⛔ Refused for a key matching the vendor's
+   * own sensitive-key list: those belong in `credentialValues`, where LiteLLM stores them
+   * encrypted and answers them masked — in `credential_info` they would be stored in clear.
+   */
+  readonly credentialInfo?: Readonly<Record<string, unknown>>;
+
+  /**
+   * The credential's values, each declared as `{ fromEnv: 'NAME' }` naming the environment
+   * variable the DEPLOYING process reads at call time. AT LEAST ONE is required: LiteLLM's create
+   * model refuses a body whose `credential_values` and `model_id` are both empty
+   * (`models/credentials.py`'s `CreateCredentialItem` validator → 422), and `model_id` — which
+   * would copy a deployment's values — is not modelled here, so a value-less declaration has
+   * nothing to write. A value that never resolves in a plan-only environment never drifts
+   * (credential-values.ts); one that resolves is SENT as the literal the proxy stores encrypted.
+   */
+  readonly credentialValues: Readonly<Record<string, FromEnv>>;
+}
+
+export interface CredentialAttributes {
+  readonly credentialName: string;
+
+  /**
+   * The row's `credential_info` as the read answers it, minus any SENSITIVE-KEYED entry — those
+   * would mirror a clear secret into Alchemy's state and are skipped (`toAttributes`). The digest
+   * comparison removes undeclared live keys, including on adoption (credential-form.ts).
+   */
+  readonly credentialInfo: Readonly<Record<string, unknown>>;
+
+  /**
+   * `scrypt:<salt>:<digest>` of the values the LAST WRITE resolved — the only way a plan notices
+   * a rotated credential, because the live row answers masked fragments that can never be
+   * compared (`secrets/write-only.ts`). An ADOPTED row starts `''`, which reads as `stale`.
+   */
+  readonly valuesSeal: string;
+
+  /** Names only, never masked fragments. Optional for states written by older providers. */
+  readonly valueKeys?: readonly string[];
+
+  /** All info key names, including withheld sensitive entries; optional for older states. */
+  readonly infoKeys?: readonly string[];
+}
+
+/**
+ * Whether a value is not a string with something in it. Takes `unknown`: a declaration can say
+ * anything. (Same rule as model-types.ts and registry-support.ts.)
+ */
+export const isBlank = (value: unknown): boolean =>
+  typeof value !== 'string' || value.trim() === '';
+
+/**
+ * The vendor's OWN sensitive-key list, read from the live 1.103.0 container
+ * (`litellm_logging.py::_get_masked_values`): a key containing any of these substrings
+ * (case-insensitive) is masked in every `credential_values` read. Credential-form.ts refuses
+ * them in `credentialInfo` for the same reason the vendor masks them in values.
+ */
+const SENSITIVE_KEY_FRAGMENTS: readonly string[] = [
+  'authorization',
+  'token',
+  'key',
+  'secret',
+  'vertex_credentials',
+  'credentials',
+  'password',
+  'passwd',
+];
+
+/** Whether a key is one the vendor itself treats as sensitive. */
+export const isSensitiveKey = (key: string): boolean => {
+  const lower = key.toLowerCase();
+  return SENSITIVE_KEY_FRAGMENTS.some((fragment) => lower.includes(fragment));
+};