@homeflare/alchemy 0.43.0 → 0.45.0

package/src/litellm/mcp-server-alias.test.ts

@@ -0,0 +1,184 @@
+/**
+ * `LiteLLM.MCPServer`: an update must not rewrite the alias, and the names LiteLLM refuses are
+ * refused first.
+ *
+ * ⛔ MEASURED 2026-09-29 by running the live 1.103.0 container's own `validate_and_normalize_mcp_server_payload`
+ *   and `_prepare_mcp_server_data` on edit bodies (no database, no network): a body with a `server_name`
+ *   and no `alias` comes out with `alias = normalize(server_name)` and the alias IS written; a body with
+ *   neither sends none. The alias is the tool prefix, so an update that sent the name alone renamed
+ *   every tool of a row with a custom alias, and the plan showed `adopted` or an update with no alias.
+ *   The fake models exactly that rule (`fake-mcp-litellm.ts`), and the first test pins the fake to it.
+ * ★ EVERY VALUE IS `FAKE-*` or an RFC 2606 host.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { FAKE_BASE } from './fake-litellm.ts';
+import { type FakeMcpLitellm, serverRow, startFakeMcpLitellm } from './fake-mcp-litellm.ts';
+import { fakeStack } from './fake-stack.ts';
+import { LiteLLMMCPServer } from './mcp-server.ts';
+import { createBody, firstProblem, updateBody } from './mcp-server-form.ts';
+import type { McpServerAttributes, McpServerProps } from './mcp-server-types.ts';
+
+const KEY = 'sk-test-master';
+
+const stack = (fake: FakeMcpLitellm) => fakeStack({ apiKey: KEY, baseUrl: FAKE_BASE }, fake.fetch);
+const declare = (props: McpServerProps) => Effect.asVoid(LiteLLMMCPServer('Web', props));
+
+const base: McpServerProps = {
+  authType: 'none',
+  serverName: 'FAKE_web',
+  transport: 'http',
+  url: 'https://web.example.com/mcp',
+};
+/** A row a person aliased: its tools are `search-*`, and it is open to every key. */
+const aliased = serverRow({
+  alias: 'search',
+  allow_all_keys: true,
+  server_id: 'FAKE-web-id',
+  server_name: 'FAKE_web',
+  transport: 'http',
+  url: 'https://web.example.com/mcp',
+});
+const live = (over: Partial<McpServerAttributes> = {}): McpServerAttributes => ({
+  alias: 'search',
+  allowAllKeys: false,
+  allowedTools: [],
+  authType: 'none',
+  credentialSeal: '',
+  description: null,
+  mcpAccessGroups: [],
+  serverId: 'FAKE-web-id',
+  serverName: 'FAKE_web',
+  transport: 'http',
+  url: 'https://web.example.com/mcp',
+  ...over,
+});
+
+const put = (fake: FakeMcpLitellm, body: Record<string, unknown>) =>
+  fake.fetch(`${FAKE_BASE}/v1/mcp/server`, {
+    body: JSON.stringify(body),
+    headers: { authorization: `Bearer ${KEY}`, 'content-type': 'application/json' },
+    method: 'PUT',
+  });
+
+test('the fake models the measured rule: a name with no alias rewrites the alias, neither leaves it', async () => {
+  const fake = startFakeMcpLitellm({ masterKey: KEY, seed: [aliased] });
+  await put(fake, { allow_all_keys: false, server_id: 'FAKE-web-id' });
+  expect(fake.servers()[0]).toMatchObject({ alias: 'search' });
+  await put(fake, { server_id: 'FAKE-web-id', server_name: 'FAKE_web' });
+  expect(fake.servers()[0]).toMatchObject({ alias: 'FAKE_web' });
+});
+
+describe('the update body', () => {
+  test('sends no server_name and no alias when the name is unchanged and no alias is declared', () => {
+    const body = updateBody(base, 'FAKE-web-id', undefined, false, live());
+    expect(body).not.toHaveProperty('server_name');
+    expect(body).not.toHaveProperty('alias');
+  });
+
+  test('a rename re-sends the live alias, so the tool prefix survives', () => {
+    const body = updateBody(
+      { ...base, serverName: 'FAKE_web2' },
+      'FAKE-web-id',
+      undefined,
+      false,
+      live(),
+    );
+    expect(body).toMatchObject({ alias: 'search', server_name: 'FAKE_web2' });
+  });
+
+  test('a rename of a row with no alias sends the name alone: LiteLLM then defaults the alias', () => {
+    const body = updateBody(
+      { ...base, serverName: 'FAKE_web2' },
+      'FAKE-web-id',
+      undefined,
+      false,
+      live({ alias: null }),
+    );
+    expect(body).toHaveProperty('server_name', 'FAKE_web2');
+    expect(body).not.toHaveProperty('alias');
+  });
+
+  test('a declared alias is sent, and wins over the live one', () => {
+    const body = updateBody({ ...base, alias: 'docs' }, 'FAKE-web-id', undefined, false, live());
+    expect(body).toHaveProperty('alias', 'docs');
+    expect(body).not.toHaveProperty('server_name');
+  });
+
+  test('a create sends the name, and an alias only when declared', () => {
+    expect(createBody(base, 'FAKE-web-id', undefined)).not.toHaveProperty('alias');
+    expect(createBody({ ...base, alias: 'docs' }, 'FAKE-web-id', undefined)).toHaveProperty(
+      'alias',
+      'docs',
+    );
+    expect(createBody(base, 'FAKE-web-id', undefined)).toHaveProperty('server_name', 'FAKE_web');
+  });
+});
+
+describe('through the engine', () => {
+  test('adopting an aliased row and correcting its grant leaves the alias alone', async () => {
+    const fake = startFakeMcpLitellm({ masterKey: KEY, seed: [aliased] });
+    // ⚠️ the plan says `adopted` even though reconcile writes (allow_all_keys true -> false)
+    expect(await stack(fake).deploy(declare(base), { adopt: true })).toEqual({ Web: 'adopted' });
+    const sent = fake.bodies();
+    expect(sent).toHaveLength(1);
+    expect(sent[0]).not.toHaveProperty('alias');
+    expect(sent[0]).not.toHaveProperty('server_name');
+    expect(fake.servers()[0]).toMatchObject({ alias: 'search', allow_all_keys: false });
+  });
+
+  test('a rename of an owned row keeps its custom alias, and the next deploy is a no-op', async () => {
+    const fake = startFakeMcpLitellm({ masterKey: KEY, seed: [aliased] });
+    const engine = stack(fake);
+    const pinned: McpServerProps = { ...base, serverId: 'FAKE-web-id' };
+    await engine.deploy(declare(pinned), { adopt: true });
+    expect(await engine.deploy(declare({ ...pinned, serverName: 'FAKE_web2' }))).toEqual({
+      Web: 'update',
+    });
+    expect(fake.servers()[0]).toMatchObject({ alias: 'search', server_name: 'FAKE_web2' });
+    expect(await engine.deploy(declare({ ...pinned, serverName: 'FAKE_web2' }))).toEqual({
+      Web: 'noop',
+    });
+  });
+});
+
+describe('the names LiteLLM would refuse or rewrite', () => {
+  test.each([
+    ['a hyphen in serverName', { ...base, serverName: 'FAKE-web' }, 'serverName'],
+    ['a hyphen in the alias', { ...base, alias: 'my-search' }, 'alias'],
+    ['a space in the alias', { ...base, alias: 'my search' }, 'space'],
+    ['a blank alias', { ...base, alias: ' ' }, 'alias'],
+    ['a slash in serverName', { ...base, serverName: 'FAKE/web' }, 'serverName'],
+    ['a colon in serverName', { ...base, serverName: 'FAKE:web' }, 'serverName'],
+    ['an at-sign in serverName', { ...base, serverName: 'FAKE@web' }, 'serverName'],
+    ['a slash in the alias', { ...base, alias: 'my/search' }, 'alias'],
+    ['a colon in the alias', { ...base, alias: 'my:search' }, 'alias'],
+    ['an at-sign in the alias', { ...base, alias: 'my@search' }, 'alias'],
+  ])('%s is refused before any request', (_label, props, mention) => {
+    expect(firstProblem(props)).toContain(mention);
+  });
+
+  test('a space in serverName is refused: LiteLLM 1.103 rejects it at apply, it is not stored as written', () => {
+    const problem = firstProblem({ ...base, serverName: 'FAKE web' });
+    expect(problem).toContain('serverName');
+    expect(problem).toContain('space');
+  });
+
+  test('a serverName or alias longer than 128 characters is refused', () => {
+    const over = 'A'.repeat(129);
+    expect(firstProblem({ ...base, serverName: over })).toContain('128');
+    expect(firstProblem({ ...base, alias: over })).toContain('128');
+  });
+
+  test('a name of letters, digits, "." and "_" up to 128 characters passes', () => {
+    expect(
+      firstProblem({ ...base, serverName: 'A'.repeat(128), alias: 'FAKE.web_1' }),
+    ).toBeUndefined();
+  });
+
+  test('a declared blank description is refused: LiteLLM never copies it into mcp_info', () => {
+    expect(firstProblem({ ...base, description: '' })).toContain('description');
+    expect(firstProblem({ ...base, description: ' ' })).toContain('description');
+    expect(firstProblem({ ...base, description: 'FAKE notes' })).toBeUndefined();
+  });
+});

package/src/litellm/mcp-server-credential.ts

@@ -0,0 +1,85 @@
+/**
+ * The credential of a `LiteLLM.MCPServer`: resolved from the deploying process's environment,
+ * held as `Redacted`, sealed, and compared by seal.
+ *
+ * ★ `Redacted` IS THE IN-MEMORY WRAPPER, NOT THE STORAGE FORMAT. Inside this process the value is a
+ *   `Redacted<string>`, so a stray `console.log`, `JSON.stringify` or error dump prints
+ *   `<redacted>`. It is unwrapped in exactly one place: the wire body (`mcp-server-form.ts`). It is
+ *   never a prop or an attribute — see mcp-server-types.ts for why `Redacted` cannot be either.
+ * ⚠️ LITELLM DOES NOT HAND A CREDENTIAL BACK TO COMPARE WITH (UNMEASURED at 1.103.0; the resource
+ *   never relies on it). So what was last written is remembered as a SEAL, and a plan asks "is the
+ *   value in my environment the one I wrote". Four answers:
+ *   - `none`    — no credential is declared, nothing to compare.
+ *   - `unknown` — the variable is unset here, so a plan cannot tell. Never drift: a plan-only
+ *                 environment must not report every credentialed server as changed. (A write that
+ *                 CHANGES `auth_type` is the exception: it demands the value, `requireCredential`.)
+ *   - `stale`   — the variable is set and there is no seal (an adopted row, or one written outside
+ *                 this stack) or the seal disagrees. The declaration is authoritative, so it is written.
+ *   - `match`   — the seal was made from this value.
+ * ⚠️ A SEAL OF A GUESSABLE SECRET IS STILL GUESSABLE (secrets/write-only.ts). Use a random token.
+ */
+import * as Effect from 'effect/Effect';
+import * as Redacted from 'effect/Redacted';
+import { type Environment, resolveAll, seal, sealMatches } from '../secrets/write-only.ts';
+import { LitellmMcpServerCredentialEnvUnsetError } from './mcp-server-errors.ts';
+import { type McpServerProps, isStaticAuthType } from './mcp-server-types.ts';
+
+/** What the environment holds for the declared credential. `value` is undefined when unset or empty. */
+export interface ResolvedCredential {
+  /** The variable's NAME, for a message. `undefined` when no credential is declared. */
+  readonly variable: string | undefined;
+  readonly value: Redacted.Redacted<string> | undefined;
+}
+
+export type CredentialState = 'none' | 'unknown' | 'stale' | 'match';
+
+/** ⛔ Reads the environment at CALL time, never at module load (docs/credentials.md). */
+export const resolveCredential = (
+  props: McpServerProps,
+  env: Environment = process.env,
+): ResolvedCredential => {
+  if (props.authValue === undefined) return { value: undefined, variable: undefined };
+  const { values } = resolveAll({ authValue: props.authValue }, env);
+  const raw = values['authValue'];
+  return {
+    value: raw === undefined ? undefined : Redacted.make(raw),
+    variable: props.authValue.fromEnv,
+  };
+};
+
+const sealable = (value: Redacted.Redacted<string>) => ({ authValue: Redacted.value(value) });
+
+/** `scrypt:<salt>:<digest>` of a credential, for `credentialSeal`. ⛔ Never the value. */
+export const sealCredential = (value: Redacted.Redacted<string>): string => seal(sealable(value));
+
+export const credentialState = (
+  props: McpServerProps,
+  sealed: string,
+  resolved: ResolvedCredential = resolveCredential(props),
+): CredentialState => {
+  if (props.authValue === undefined || !isStaticAuthType(props.authType)) return 'none';
+  if (resolved.value === undefined) return 'unknown';
+  if (sealed === '') return 'stale';
+  return sealMatches(sealed, sealable(resolved.value)) ? 'match' : 'stale';
+};
+
+/**
+ * Fails naming the variable when this write has to send a static credential and the deploying
+ * process does not hold it. Passes for a type that carries none.
+ *
+ * ⛔ A WRITE THAT CHANGES `auth_type` MUST SEND THE CREDENTIAL, exactly like a create. Measured on
+ *   the live 1.103.0 container (`mcp_server/db.py` lines 1013-1014, `_credential_auth_class`): an
+ *   edit whose auth class differs from the stored one and that sends no `credentials` key WIPES the
+ *   stored credential, and each static type is its own class. Sent without the credential, the row
+ *   would end with none while the seal still matched the old value, so a later deploy with the
+ *   variable set would be a no-op and the server would stay unauthenticated until the secret rotated.
+ */
+export const requireCredential = (props: McpServerProps, credential: ResolvedCredential) =>
+  isStaticAuthType(props.authType) && credential.value === undefined
+    ? Effect.fail(
+        new LitellmMcpServerCredentialEnvUnsetError({
+          serverName: props.serverName,
+          variable: credential.variable ?? '(undeclared)',
+        }),
+      )
+    : Effect.void;

package/src/litellm/mcp-server-errors.ts

@@ -0,0 +1,141 @@
+/**
+ * The typed refusals `LiteLLM.MCPServer` raises on top of `@distilled.cloud/litellm`'s own SDK errors.
+ *
+ * ⛔ NO MESSAGE HERE MAY CARRY A CREDENTIAL. The only things named are the server's name, ids the
+ *   proxy already lists, field names, and the NAME of an environment variable — never a value, and
+ *   never a URL (a URL can hold a token; `mcp-server-form.ts` refuses those and redacts the read).
+ */
+import type * as mcp from '@distilled.cloud/litellm/mcp_management';
+import * as Data from 'effect/Data';
+
+/** A declaration the resource refuses before any request: a combination nobody meant. */
+export class LitellmMcpServerInvalidError extends Data.TaggedError('LitellmMcpServerInvalidError')<{
+  readonly serverName: string;
+  readonly problem: string;
+}> {
+  override get message(): string {
+    return `LiteLLM.MCPServer "${this.serverName}": ${this.problem}.`;
+  }
+}
+
+/**
+ * A write must send the credential and the deploying process does not have it. An empty variable
+ * counts as unset (secrets/write-only.ts: a failed renderer writes `NAME=`, and sending `''` would
+ * store an empty credential and report a successful deploy).
+ */
+export class LitellmMcpServerCredentialEnvUnsetError extends Data.TaggedError(
+  'LitellmMcpServerCredentialEnvUnsetError',
+)<{
+  readonly serverName: string;
+  readonly variable: string;
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.MCPServer "${this.serverName}": this write must send its credential, and ` +
+      `${this.variable} is unset or empty in the deploying environment. Export it and deploy again.`
+    );
+  }
+}
+
+/**
+ * More than one live row carries the declared `server_name`, so adopt-by-name cannot say which one
+ * is meant. LiteLLM does not make the name unique (unmeasured on 1.103.0). Declare `serverId` to
+ * pick one — nothing is adopted, updated or deleted on a guess.
+ */
+export class LitellmMcpServerAmbiguousNameError extends Data.TaggedError(
+  'LitellmMcpServerAmbiguousNameError',
+)<{
+  readonly serverName: string;
+  readonly serverIds: readonly string[];
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.MCPServer "${this.serverName}": ${this.serverIds.length} live rows carry that ` +
+      `server_name (${this.serverIds.join(', ')}). Declare \`serverId\` to choose one.`
+    );
+  }
+}
+
+/** `GET /v1/mcp/server` answered something that is not a list of servers. */
+export class LitellmMcpServerUnreadableError extends Data.TaggedError(
+  'LitellmMcpServerUnreadableError',
+)<{
+  readonly reason: string;
+}> {
+  override get message(): string {
+    return `LiteLLM.MCPServer: the server list is unreadable (${this.reason}).`;
+  }
+}
+
+/**
+ * A create or edit returned no error, yet the row is absent on the read back: neither in the list
+ * NOR in a database-backed read by id (the list alone is the registry, which can lag a commit).
+ */
+export class LitellmMcpServerAbsentAfterWriteError extends Data.TaggedError(
+  'LitellmMcpServerAbsentAfterWriteError',
+)<{
+  readonly serverName: string;
+  readonly serverId: string;
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.MCPServer "${this.serverName}": the write of ${this.serverId} returned no error ` +
+      'but the row is absent from the list and from the database read.'
+    );
+  }
+}
+
+/**
+ * The write returned no error but the row still differs from the declaration. The edit route may
+ * merge with `exclude_none` or a truthiness check (an empty list or a `false` never lands); the
+ * read back says so instead of reporting a converged row. Unmeasured on 1.103.0.
+ */
+export class LitellmMcpServerNotConvergedError extends Data.TaggedError(
+  'LitellmMcpServerNotConvergedError',
+)<{
+  readonly serverName: string;
+  readonly serverId: string;
+  readonly fields: readonly string[];
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.MCPServer "${this.serverName}": after the write, ${this.serverId} still differs ` +
+      `from the declaration in ${this.fields.join(', ')}.`
+    );
+  }
+}
+
+/**
+ * The declared `description` cannot be applied: the live row's `mcp_info` has a `description` key
+ * (even a null one), and LiteLLM answers that in preference to the column, which is all this
+ * resource writes (`mcp_info` is not modelled). Raised BEFORE any write, so the row is untouched.
+ * Nothing here names the text itself: a description is free text a person wrote.
+ */
+export class LitellmMcpServerDescriptionShadowedError extends Data.TaggedError(
+  'LitellmMcpServerDescriptionShadowedError',
+)<{
+  readonly serverName: string;
+  readonly serverId: string;
+}> {
+  override get message(): string {
+    return (
+      `LiteLLM.MCPServer "${this.serverName}": ${this.serverId} has a \`description\` in \`mcp_info\`, ` +
+      'which LiteLLM shows instead of the column this resource writes, and it differs from the ' +
+      'declaration. Edit it in LiteLLM, or remove `description` from the declaration.'
+    );
+  }
+}
+
+export type McpServerError =
+  | mcp.AddMcpServerV1McpServerPostError
+  | mcp.EditMcpServerV1McpServerPutError
+  | mcp.FetchAllMcpServersV1McpServerGetError
+  | mcp.FetchMcpServerV1McpServerServerIdGetError
+  | mcp.RemoveMcpServerV1McpServerServerIdDeleteError
+  | LitellmMcpServerInvalidError
+  | LitellmMcpServerCredentialEnvUnsetError
+  | LitellmMcpServerAmbiguousNameError
+  | LitellmMcpServerUnreadableError
+  | LitellmMcpServerAbsentAfterWriteError
+  | LitellmMcpServerNotConvergedError
+  | LitellmMcpServerDescriptionShadowedError;

package/src/litellm/mcp-server-exports.test.ts

@@ -0,0 +1,15 @@
+/**
+ * The public barrel re-exports every typed refusal, including the one a shadowed description raises.
+ * A missing name here is a runtime import failure: the class exists in mcp-server-errors.ts either way.
+ */
+import { expect, test } from 'bun:test';
+import { LitellmMcpServerDescriptionShadowedError } from './index.ts';
+
+test('LitellmMcpServerDescriptionShadowedError is on the litellm barrel', () => {
+  const error = new LitellmMcpServerDescriptionShadowedError({
+    serverId: 'FAKE-id',
+    serverName: 'FAKE_web',
+  });
+  expect(error._tag).toBe('LitellmMcpServerDescriptionShadowedError');
+  expect(error.message).toContain('FAKE_web');
+});

package/src/litellm/mcp-server-form.test.ts

@@ -0,0 +1,241 @@
+/**
+ * The pure half of `LiteLLM.MCPServer`: what is refused, what a row is read as, what differs, and
+ * what each write body carries. No server, no engine.
+ *
+ * ★ EVERY VALUE IS `FAKE-*` or an RFC 2606 host.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Redacted from 'effect/Redacted';
+import {
+  createBody,
+  differing,
+  firstProblem,
+  toAttributes,
+  updateBody,
+} from './mcp-server-form.ts';
+import { redactUrl } from './mcp-server-url.ts';
+import type { McpServerAttributes, McpServerProps } from './mcp-server-types.ts';
+
+const base: McpServerProps = {
+  authType: 'none',
+  serverName: 'FAKE_docs',
+  transport: 'http',
+  url: 'https://mcp.example.com/mcp',
+};
+
+const attributes = (over: Partial<McpServerAttributes> = {}): McpServerAttributes => ({
+  alias: null,
+  allowAllKeys: false,
+  allowedTools: [],
+  authType: 'none',
+  credentialSeal: '',
+  description: null,
+  mcpAccessGroups: [],
+  serverId: 'FAKE-id',
+  serverName: 'FAKE_docs',
+  transport: 'http',
+  url: 'https://mcp.example.com/mcp',
+  ...over,
+});
+
+describe('what is refused before any request', () => {
+  test('an ordinary declaration passes', () => {
+    expect(firstProblem(base)).toBeUndefined();
+  });
+
+  test.each([
+    ['a blank name', { ...base, serverName: ' ' }, 'serverName'],
+    ['a padded name', { ...base, serverName: ' FAKE_docs' }, 'serverName'],
+    ['stdio', { ...base, transport: 'stdio' as never }, 'stdio'],
+    [
+      'an auth type that needs credential fields not modelled',
+      { ...base, authType: 'aws_sigv4' as never },
+      'authType',
+    ],
+    ['a static type without a credential', { ...base, authType: 'api_key' as const }, 'authValue'],
+    [
+      'a credential on oauth2',
+      { ...base, authType: 'oauth2' as const, authValue: { fromEnv: 'FAKE_VAR' } },
+      'authValue',
+    ],
+    ['a blank tool name', { ...base, allowedTools: ['FAKE_tool', ''] }, 'allowedTools'],
+    ['a scheme that is not http', { ...base, url: 'ftp://mcp.example.com/mcp' }, 'http'],
+    ['a bare host', { ...base, url: 'mcp.example.com' }, 'url'],
+    [
+      'userinfo in the url',
+      { ...base, url: 'https://FAKE-user:FAKE-pass@mcp.example.com/mcp' },
+      'userinfo',
+    ],
+    ['a fragment', { ...base, url: 'https://mcp.example.com/mcp#frag' }, 'fragment'],
+  ])('%s', (_label, props, mention) => {
+    expect(firstProblem(props)).toContain(mention);
+  });
+
+  test('a secret-looking query parameter is refused by NAME and the value is never quoted', () => {
+    const problem = firstProblem({
+      ...base,
+      url: 'https://mcp.example.com/mcp?api_key=FAKE-secret',
+    });
+    expect(problem).toContain('api_key');
+    expect(problem).not.toContain('FAKE-secret');
+  });
+
+  test('a harmless query parameter is allowed', () => {
+    expect(firstProblem({ ...base, url: 'https://mcp.example.com/mcp?region=eu' })).toBeUndefined();
+  });
+});
+
+describe('redactUrl', () => {
+  test('a url that needs nothing comes back byte for byte, bare origin included', () => {
+    expect(redactUrl('https://mcp.example.com')).toBe('https://mcp.example.com');
+    expect(redactUrl('https://mcp.example.com/mcp?region=eu')).toBe(
+      'https://mcp.example.com/mcp?region=eu',
+    );
+  });
+
+  test('userinfo and secret-looking query values are replaced', () => {
+    const out = redactUrl(
+      'https://FAKE-user:FAKE-pass@mcp.example.com/mcp?token=FAKE-t&keep=1&token=FAKE-u',
+    );
+    expect(out).not.toContain('FAKE-');
+    expect(out).toContain('keep=1');
+  });
+
+  test('a string that is not a url is returned as it is', () => {
+    expect(redactUrl('not a url')).toBe('not a url');
+  });
+});
+
+describe('the read shape', () => {
+  test('copies no credential and no header, whatever the row carries', () => {
+    const row = {
+      credentials: { auth_value: 'FAKE-live-secret', client_secret: 'FAKE-client-secret' },
+      env: { FAKE_ENV: 'FAKE-env-secret' },
+      env_vars: [{ name: 'FAKE_ENV', scope: 'global' as const }],
+      server_id: 'FAKE-id',
+      static_headers: { Authorization: 'FAKE-header-secret' },
+      transport: 'sse' as const,
+      url: 'https://mcp.example.com/sse?token=FAKE-url-secret',
+    };
+    const text = JSON.stringify(toAttributes(row));
+    for (const secret of [
+      'FAKE-live-secret',
+      'FAKE-client-secret',
+      'FAKE-env-secret',
+      'FAKE-header-secret',
+      'FAKE-url-secret',
+    ]) {
+      expect(text).not.toContain(secret);
+    }
+    expect(toAttributes(row).credentialSeal).toBe('');
+  });
+
+  test('a row with no auth type reads as none, and absent lists read as empty', () => {
+    const live = toAttributes({ server_id: 'FAKE-id', transport: 'http', auth_type: null });
+    expect(live).toMatchObject({
+      allowAllKeys: false,
+      allowedTools: [],
+      authType: 'none',
+      mcpAccessGroups: [],
+    });
+  });
+});
+
+describe('what differs', () => {
+  test('nothing, for a live row that matches', () => {
+    expect(differing(attributes(), base)).toEqual([]);
+  });
+
+  test('key and group grants are always compared, against a closed default', () => {
+    const open = attributes({ allowAllKeys: true, mcpAccessGroups: ['FAKE_g'] });
+    expect(differing(open, base)).toEqual(['allow_all_keys', 'mcp_access_groups']);
+  });
+
+  test('a tool list is compared only when declared: an undeclared one is never drift', () => {
+    const whitelisted = attributes({ allowedTools: ['FAKE_a'] });
+    expect(differing(whitelisted, base)).toEqual([]);
+    // ⚠️ a declared `[]` is a real difference from a whitelist: it asks for "no restriction"
+    expect(differing(whitelisted, { ...base, allowedTools: [] })).toEqual(['allowed_tools']);
+    expect(differing(attributes(), { ...base, allowedTools: ['FAKE_a'] })).toEqual([
+      'allowed_tools',
+    ]);
+  });
+
+  test('lists compare as sets: order and repeats do not matter', () => {
+    const live = attributes({ allowedTools: ['FAKE_b', 'FAKE_a'] });
+    expect(differing(live, { ...base, allowedTools: ['FAKE_a', 'FAKE_b'] })).toEqual([]);
+    expect(differing(live, { ...base, allowedTools: ['FAKE_a'] })).toEqual(['allowed_tools']);
+  });
+
+  test('alias and description are compared only when declared', () => {
+    const live = attributes({ alias: 'FAKE_alias', description: 'a person wrote this' });
+    expect(differing(live, base)).toEqual([]);
+    expect(differing(live, { ...base, alias: 'other', description: 'other' })).toEqual([
+      'alias',
+      'description',
+    ]);
+  });
+
+  test('a live url that carried a token differs from the clean declaration', () => {
+    const live = attributes({ url: redactUrl('https://mcp.example.com/mcp?token=FAKE-t') });
+    expect(differing(live, base)).toEqual(['url']);
+  });
+});
+
+describe('the write bodies', () => {
+  const token = Redacted.make('FAKE-token');
+
+  test('a create carries the id, the managed set and the credential, and no undeclared field', () => {
+    const body = createBody(
+      { ...base, authType: 'bearer_token', authValue: { fromEnv: 'FAKE_VAR' } },
+      'FAKE-id',
+      token,
+    );
+    expect(body).toEqual({
+      allow_all_keys: false,
+      auth_type: 'bearer_token',
+      credentials: { auth_value: 'FAKE-token' },
+      mcp_access_groups: [],
+      server_id: 'FAKE-id',
+      server_name: 'FAKE_docs',
+      transport: 'http',
+      url: 'https://mcp.example.com/mcp',
+    });
+  });
+
+  test('the declaration names the variable, never the value', () => {
+    expect(JSON.stringify({ ...base, authValue: { fromEnv: 'FAKE_VAR' } })).not.toContain(
+      'FAKE-token',
+    );
+    expect(JSON.stringify(token)).not.toContain('FAKE-token');
+  });
+
+  test('allowed_tools is sent only when declared, and a declared empty list is sent as it is', () => {
+    for (const body of [
+      createBody(base, 'FAKE-id', undefined),
+      updateBody(base, 'FAKE-id', undefined, false, attributes()),
+    ]) {
+      expect(body).not.toHaveProperty('allowed_tools');
+    }
+    expect(
+      updateBody({ ...base, allowedTools: [] }, 'FAKE-id', undefined, false, attributes()),
+    ).toHaveProperty('allowed_tools', []);
+    expect(createBody({ ...base, allowedTools: ['FAKE_a'] }, 'FAKE-id', undefined)).toHaveProperty(
+      'allowed_tools',
+      ['FAKE_a'],
+    );
+  });
+
+  test('an update with no credential sends no credentials key, so the stored one is left', () => {
+    expect(updateBody(base, 'FAKE-id', undefined, false, attributes())).not.toHaveProperty(
+      'credentials',
+    );
+  });
+
+  test('leaving a static type sends an explicit null', () => {
+    expect(updateBody(base, 'FAKE-id', undefined, true, attributes())).toHaveProperty(
+      'credentials',
+      null,
+    );
+  });
+});