@app-vitals/agent-admin 0.0.0-stage → 0.1.0

package/src/anthropic-credential-guard.ts

@@ -0,0 +1,44 @@
+/**
+ * admin/src/anthropic-credential-guard.ts
+ * Shared guard for Anthropic workload identity federation (WIF-2.1).
+ *
+ * CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN each
+ * outrank federation in the Anthropic client — even set to an empty string —
+ * so with federation enabled none of them may reach a federated (non
+ * self-hosted) agent through its env bundle.
+ */
+
+import { BadRequestError } from "./errors.ts";
+
+export const ANTHROPIC_CREDENTIAL_KEYS = [
+  "CLAUDE_CODE_OAUTH_TOKEN",
+  "ANTHROPIC_API_KEY",
+  "ANTHROPIC_AUTH_TOKEN",
+] as const;
+
+/** Stable machine-readable code for API/UI callers. */
+export const ANTHROPIC_CREDENTIALS_BLOCKED_CODE =
+  "anthropic_credentials_blocked_federation";
+
+const BLOCKED_KEYS = new Set<string>(ANTHROPIC_CREDENTIAL_KEYS);
+
+export function isAnthropicCredentialKey(key: string): boolean {
+  return BLOCKED_KEYS.has(key);
+}
+
+/** The subset of `keys` that are blocked Anthropic credential keys. */
+export function anthropicCredentialKeysIn(keys: Iterable<string>): string[] {
+  return [...keys].filter(isAnthropicCredentialKey);
+}
+
+/** Thrown (HTTP 400) when a blocked key is written for a federated agent. */
+export class AnthropicCredentialsBlockedError extends BadRequestError {
+  readonly code = ANTHROPIC_CREDENTIALS_BLOCKED_CODE;
+
+  constructor(public readonly keys: string[]) {
+    super(
+      `${ANTHROPIC_CREDENTIALS_BLOCKED_CODE}: ${keys.join(", ")} cannot be set on an agent that uses Anthropic workload identity federation`,
+    );
+    this.name = "AnthropicCredentialsBlockedError";
+  }
+}

package/src/anthropic-credential-guard.unit.test.ts

@@ -0,0 +1,88 @@
+/**
+ * admin/src/anthropic-credential-guard.unit.test.ts
+ * Unit tests for the Anthropic credential guard (WIF-2.1).
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  ANTHROPIC_CREDENTIAL_KEYS,
+  ANTHROPIC_CREDENTIALS_BLOCKED_CODE,
+  AnthropicCredentialsBlockedError,
+  anthropicCredentialKeysIn,
+  isAnthropicCredentialKey,
+} from "./anthropic-credential-guard.ts";
+import { BadRequestError } from "./errors.ts";
+
+describe("isAnthropicCredentialKey", () => {
+  it.each([
+    "CLAUDE_CODE_OAUTH_TOKEN",
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_AUTH_TOKEN",
+  ])("returns true for %s", (key) => {
+    expect(isAnthropicCredentialKey(key)).toBe(true);
+  });
+
+  it.each(["OPENAI_API_KEY", "ANTHROPIC_BASE_URL", "anthropic_api_key", ""])(
+    "returns false for %p",
+    (key) => {
+      expect(isAnthropicCredentialKey(key)).toBe(false);
+    },
+  );
+
+  it("covers every exported credential key", () => {
+    for (const key of ANTHROPIC_CREDENTIAL_KEYS) {
+      expect(isAnthropicCredentialKey(key)).toBe(true);
+    }
+  });
+});
+
+describe("anthropicCredentialKeysIn", () => {
+  it("filters to blocked keys, preserving input order", () => {
+    expect(
+      anthropicCredentialKeysIn([
+        "ANTHROPIC_AUTH_TOKEN",
+        "FOO",
+        "CLAUDE_CODE_OAUTH_TOKEN",
+        "BAR",
+        "ANTHROPIC_API_KEY",
+      ]),
+    ).toEqual([
+      "ANTHROPIC_AUTH_TOKEN",
+      "CLAUDE_CODE_OAUTH_TOKEN",
+      "ANTHROPIC_API_KEY",
+    ]);
+  });
+
+  it("returns an empty array for empty input", () => {
+    expect(anthropicCredentialKeysIn([])).toEqual([]);
+  });
+
+  it("returns an empty array when no keys are blocked", () => {
+    expect(anthropicCredentialKeysIn(["FOO", "BAR"])).toEqual([]);
+  });
+
+  it("accepts any iterable (e.g. a Set)", () => {
+    expect(
+      anthropicCredentialKeysIn(new Set(["ANTHROPIC_API_KEY", "FOO"])),
+    ).toEqual(["ANTHROPIC_API_KEY"]);
+  });
+});
+
+describe("AnthropicCredentialsBlockedError", () => {
+  it("extends BadRequestError and carries the stable code", () => {
+    const err = new AnthropicCredentialsBlockedError(["ANTHROPIC_API_KEY"]);
+    expect(err).toBeInstanceOf(BadRequestError);
+    expect(err).toBeInstanceOf(Error);
+    expect(err.code).toBe("anthropic_credentials_blocked_federation");
+    expect(err.code).toBe(ANTHROPIC_CREDENTIALS_BLOCKED_CODE);
+    expect(err.name).toBe("AnthropicCredentialsBlockedError");
+  });
+
+  it("lists the keys in the message and exposes them", () => {
+    const keys = ["ANTHROPIC_API_KEY", "CLAUDE_CODE_OAUTH_TOKEN"];
+    const err = new AnthropicCredentialsBlockedError(keys);
+    expect(err.keys).toEqual(keys);
+    expect(err.message).toContain("ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN");
+    expect(err.message).toContain(ANTHROPIC_CREDENTIALS_BLOCKED_CODE);
+  });
+});

package/src/anthropic-federated-token-provider.integration.test.ts

@@ -0,0 +1,248 @@
+/**
+ * admin/src/anthropic-federated-token-provider.integration.test.ts
+ * FederatedTokenProvider against the FakeAnthropicTokenExchange test double
+ * (POST /v1/oauth/token is not in the Anthropic OpenAPI spec, so there is no
+ * spec-validated recorded fixture for it — see anthropic-identity-client.fixtures.ts).
+ * The projected token is a real temp file; time is an injected Clock.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  AnthropicTokenExchangeError,
+  FederatedTokenProvider,
+} from "./anthropic-federated-token-provider.ts";
+import {
+  asFetch,
+  FakeAnthropicTokenExchange,
+} from "./anthropic-identity-client.fixtures.ts";
+import type { Clock } from "./clock.ts";
+
+class MutableClock implements Clock {
+  constructor(private ms: number) {}
+  now(): Date {
+    return new Date(this.ms);
+  }
+  advanceSeconds(s: number): void {
+    this.ms += s * 1000;
+  }
+}
+
+let dir: string;
+let tokenFile: string;
+let clock: MutableClock;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "anthropic-token-"));
+  tokenFile = join(dir, "token");
+  writeFileSync(tokenFile, "projected-jwt-v1\n");
+  clock = new MutableClock(Date.parse("2026-10-01T12:00:00Z"));
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+function makeProvider(
+  exchange: FakeAnthropicTokenExchange,
+  extra: Partial<ConstructorParameters<typeof FederatedTokenProvider>[0]> = {},
+) {
+  return new FederatedTokenProvider({
+    fetchFn: exchange.asFetch(),
+    tokenFilePath: tokenFile,
+    federationRuleId: "fdrl_01Admin",
+    organizationId: "org-1234",
+    clock,
+    ...extra,
+  });
+}
+
+describe("FederatedTokenProvider", () => {
+  it("POSTs a jwt-bearer grant with the projected token and returns the access token", async () => {
+    const exchange = new FakeAnthropicTokenExchange();
+    const provider = makeProvider(exchange, {
+      serviceAccountId: "svac_01Admin",
+      workspaceId: "wrkspc_01Work",
+    });
+
+    expect(await provider.getAccessToken()).toBe("fake-access-token-1");
+
+    const req = exchange.requests[0];
+    expect(req.method).toBe("POST");
+    expect(req.url.toString()).toBe("https://api.anthropic.com/v1/oauth/token");
+    expect(req.headers.get("content-type")).toBe("application/json");
+    expect(req.headers.get("anthropic-beta")).toContain(
+      "oidc-federation-2026-04-01",
+    );
+    expect(req.body).toEqual({
+      grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+      assertion: "projected-jwt-v1",
+      federation_rule_id: "fdrl_01Admin",
+      organization_id: "org-1234",
+      service_account_id: "svac_01Admin",
+      workspace_id: "wrkspc_01Work",
+    });
+  });
+
+  it("omits optional ids when not configured", async () => {
+    const exchange = new FakeAnthropicTokenExchange();
+    await makeProvider(exchange).getAccessToken();
+    expect(Object.keys(exchange.requests[0].body as object).sort()).toEqual([
+      "assertion",
+      "federation_rule_id",
+      "grant_type",
+      "organization_id",
+    ]);
+  });
+
+  it("caches the access token until shortly before expires_in", async () => {
+    const exchange = new FakeAnthropicTokenExchange({ expiresIn: 3600 });
+    const provider = makeProvider(exchange);
+
+    await provider.getAccessToken();
+    clock.advanceSeconds(3600 - 61);
+    expect(await provider.getAccessToken()).toBe("fake-access-token-1");
+    expect(exchange.calls).toBe(1);
+
+    clock.advanceSeconds(2);
+    expect(await provider.getAccessToken()).toBe("fake-access-token-2");
+    expect(exchange.calls).toBe(2);
+  });
+
+  it("re-reads the projected token file on every exchange (kubelet rotation)", async () => {
+    const exchange = new FakeAnthropicTokenExchange({ expiresIn: 120 });
+    const provider = makeProvider(exchange);
+
+    await provider.getAccessToken();
+    writeFileSync(tokenFile, "projected-jwt-v2\n");
+    clock.advanceSeconds(200);
+    await provider.getAccessToken();
+
+    expect(exchange.assertions).toEqual([
+      "projected-jwt-v1",
+      "projected-jwt-v2",
+    ]);
+  });
+
+  it("invalidate() forces a fresh exchange", async () => {
+    const exchange = new FakeAnthropicTokenExchange();
+    const provider = makeProvider(exchange);
+    await provider.getAccessToken();
+    provider.invalidate();
+    expect(await provider.getAccessToken()).toBe("fake-access-token-2");
+  });
+
+  it("coalesces concurrent callers into one exchange", async () => {
+    const exchange = new FakeAnthropicTokenExchange();
+    const provider = makeProvider(exchange);
+    const tokens = await Promise.all([
+      provider.getAccessToken(),
+      provider.getAccessToken(),
+      provider.getAccessToken(),
+    ]);
+    expect(new Set(tokens).size).toBe(1);
+    expect(exchange.calls).toBe(1);
+  });
+
+  it("fails clearly, without file contents, when the token file is missing", async () => {
+    rmSync(tokenFile);
+    const provider = makeProvider(new FakeAnthropicTokenExchange());
+    const err = await provider.getAccessToken().catch((e) => e);
+    expect(err).toBeInstanceOf(AnthropicTokenExchangeError);
+    expect(err.message).toMatch(/projected token file/i);
+    expect(err.message).toContain(tokenFile);
+  });
+
+  it("fails when the token file is empty", async () => {
+    writeFileSync(tokenFile, "  \n");
+    const provider = makeProvider(new FakeAnthropicTokenExchange());
+    await expect(provider.getAccessToken()).rejects.toThrow(/empty/i);
+  });
+
+  it("surfaces status, error code and request-id on exchange failure but never echoed secrets", async () => {
+    const exchange = new FakeAnthropicTokenExchange({
+      failWith: {
+        status: 401,
+        body: {
+          error: "invalid_grant",
+          error_description: "no matching rule",
+          assertion: "projected-jwt-v1",
+          access_token: "echoed-access-token",
+        },
+      },
+    });
+    const err = await makeProvider(exchange)
+      .getAccessToken()
+      .catch((e) => e);
+    expect(err).toBeInstanceOf(AnthropicTokenExchangeError);
+    expect(err.status).toBe(401);
+    expect(err.code).toBe("invalid_grant");
+    expect(err.message).toContain("401");
+    expect(err.message).toContain("req_fake");
+    expect(err.message).not.toContain("projected-jwt-v1");
+    expect(err.message).not.toContain("echoed-access-token");
+  });
+
+  it("rejects a success body that fails schema validation without echoing it", async () => {
+    const exchange = new FakeAnthropicTokenExchange({
+      successBody: () => ({ access_token: "", leaked: "do-not-print" }),
+    });
+    const err = await makeProvider(exchange)
+      .getAccessToken()
+      .catch((e) => e);
+    expect(err).toBeInstanceOf(AnthropicTokenExchangeError);
+    expect(err.message).not.toContain("do-not-print");
+  });
+
+  it("rejects a non-bearer token_type", async () => {
+    const exchange = new FakeAnthropicTokenExchange({
+      successBody: () => ({
+        access_token: "fake-access-token",
+        token_type: "mac",
+        expires_in: 60,
+      }),
+    });
+    await expect(makeProvider(exchange).getAccessToken()).rejects.toThrow(
+      /token_type/,
+    );
+  });
+
+  it("rejects a non-JSON response", async () => {
+    const fetchFn = asFetch(
+      async () => new Response("<html>oops</html>", { status: 200 }),
+    );
+    const provider = new FederatedTokenProvider({
+      fetchFn,
+      tokenFilePath: tokenFile,
+      federationRuleId: "fdrl_01Admin",
+      organizationId: "org-1234",
+      clock,
+    });
+    await expect(provider.getAccessToken()).rejects.toThrow(/not valid JSON/);
+  });
+
+  it("wraps network failures without leaking the assertion", async () => {
+    const fetchFn = asFetch(async () => {
+      throw new Error("connect ECONNREFUSED projected-jwt-v1");
+    });
+    const provider = new FederatedTokenProvider({
+      fetchFn,
+      tokenFilePath: tokenFile,
+      federationRuleId: "fdrl_01Admin",
+      organizationId: "org-1234",
+      clock,
+    });
+    const err = await provider.getAccessToken().catch((e) => e);
+    expect(err).toBeInstanceOf(AnthropicTokenExchangeError);
+    expect(err.message).not.toContain("projected-jwt-v1");
+  });
+
+  it("refuses to send the assertion to a non-https, non-loopback base URL", async () => {
+    const exchange = new FakeAnthropicTokenExchange();
+    const provider = makeProvider(exchange, { baseUrl: "http://example.com" });
+    await expect(provider.getAccessToken()).rejects.toThrow(/https/);
+    expect(exchange.calls).toBe(0);
+  });
+});

package/src/anthropic-federated-token-provider.ts

@@ -0,0 +1,249 @@
+/**
+ * admin/src/anthropic-federated-token-provider.ts
+ * Signs the admin pod in to the Anthropic API by workload identity federation.
+ *
+ * The pod's Kubernetes projected ServiceAccount token (a JWT at a configurable
+ * file path, rotated by the kubelet) is exchanged for a short-lived Anthropic
+ * access token via POST /v1/oauth/token. The wire format mirrors what the
+ * Anthropic SDK itself sends for federation: an RFC 7523 jwt-bearer grant that
+ * names the federation rule and organization.
+ *
+ * KNOWN GAP: POST /v1/oauth/token is not in the Anthropic OpenAPI spec that the
+ * rest of this client's fixtures are validated against, so this exchange is
+ * covered only by the FakeAnthropicTokenExchange test double
+ * (anthropic-identity-client.fixtures.ts).
+ *
+ * Secrets: neither the projected token nor the access token is ever logged or
+ * placed in an error message. Error bodies from the token endpoint are reduced
+ * to the RFC 6749 section 5.2 `error` code; everything else (which may echo
+ * the assertion) is dropped.
+ */
+
+import { readFile } from "node:fs/promises";
+import { z } from "zod";
+import { type Clock, SystemClock } from "./clock.ts";
+
+export const DEFAULT_ANTHROPIC_BASE_URL = "https://api.anthropic.com";
+const TOKEN_PATH = "/v1/oauth/token";
+const GRANT_TYPE_JWT_BEARER = "urn:ietf:params:oauth:grant-type:jwt-bearer";
+export const OAUTH_API_BETA = "oauth-2025-04-20";
+const FEDERATION_BETA = "oidc-federation-2026-04-01";
+/** Token endpoint rejects assertions over 16 KiB. */
+const MAX_ASSERTION_BYTES = 16 * 1024;
+/** Refresh this long before the token actually expires. */
+const DEFAULT_REFRESH_SKEW_SECONDS = 60;
+
+export interface AnthropicAccessTokenProvider {
+  /** A currently valid access token (exchanged on demand, cached). */
+  getAccessToken(): Promise<string>;
+  /** Drop the cached token, e.g. after the API answered 401. */
+  invalidate(): void;
+}
+
+export class AnthropicTokenExchangeError extends Error {
+  constructor(
+    message: string,
+    readonly status?: number,
+    readonly code?: string,
+    readonly requestId?: string,
+  ) {
+    super(message);
+    this.name = "AnthropicTokenExchangeError";
+  }
+}
+
+export interface FederatedTokenProviderOptions {
+  fetchFn: typeof fetch;
+  /** Path of the projected ServiceAccount token file. */
+  tokenFilePath: string;
+  federationRuleId: string;
+  organizationId: string;
+  serviceAccountId?: string;
+  workspaceId?: string;
+  baseUrl?: string;
+  clock?: Clock;
+  refreshSkewSeconds?: number;
+}
+
+const TokenResponse = z.object({
+  access_token: z.string().min(1),
+  token_type: z.string().optional(),
+  expires_in: z.number().positive(),
+});
+
+const TokenErrorBody = z.object({ error: z.string() });
+
+function requireSecureBaseUrl(baseUrl: string): void {
+  let u: URL;
+  try {
+    u = new URL(baseUrl);
+  } catch {
+    throw new AnthropicTokenExchangeError(
+      "Anthropic base URL is not a valid URL",
+    );
+  }
+  const host = u.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  const loopback =
+    host === "localhost" || host === "127.0.0.1" || host === "::1";
+  if (u.protocol !== "https:" && !(u.protocol === "http:" && loopback)) {
+    throw new AnthropicTokenExchangeError(
+      "Refusing to send a credential to a non-https Anthropic token endpoint",
+    );
+  }
+}
+
+export class FederatedTokenProvider implements AnthropicAccessTokenProvider {
+  private readonly clock: Clock;
+  private readonly baseUrl: string;
+  private readonly skewMs: number;
+  private cached: { token: string; refreshAtMs: number } | null = null;
+  private inflight: Promise<string> | null = null;
+  private generation = 0;
+
+  constructor(private readonly opts: FederatedTokenProviderOptions) {
+    this.clock = opts.clock ?? SystemClock();
+    this.baseUrl = (opts.baseUrl ?? DEFAULT_ANTHROPIC_BASE_URL).replace(
+      /\/+$/,
+      "",
+    );
+    this.skewMs =
+      (opts.refreshSkewSeconds ?? DEFAULT_REFRESH_SKEW_SECONDS) * 1000;
+  }
+
+  async getAccessToken(): Promise<string> {
+    if (this.cached && this.clock.now().getTime() < this.cached.refreshAtMs) {
+      return this.cached.token;
+    }
+    if (!this.inflight) {
+      const generation = this.generation;
+      const pending = this.exchange(generation).finally(() => {
+        if (this.inflight === pending) this.inflight = null;
+      });
+      this.inflight = pending;
+    }
+    return this.inflight;
+  }
+
+  invalidate(): void {
+    this.cached = null;
+    this.generation++;
+  }
+
+  private async readProjectedToken(): Promise<string> {
+    let raw: string;
+    try {
+      raw = await readFile(this.opts.tokenFilePath, "utf-8");
+    } catch (err) {
+      const code = (err as { code?: string }).code ?? "unknown";
+      throw new AnthropicTokenExchangeError(
+        `Failed to read projected token file at ${this.opts.tokenFilePath} (${code})`,
+      );
+    }
+    const jwt = raw.trim();
+    if (!jwt) {
+      throw new AnthropicTokenExchangeError(
+        `Projected token file at ${this.opts.tokenFilePath} is empty`,
+      );
+    }
+    if (Buffer.byteLength(jwt) > MAX_ASSERTION_BYTES) {
+      throw new AnthropicTokenExchangeError(
+        "Projected token exceeds the 16 KiB assertion limit",
+      );
+    }
+    return jwt;
+  }
+
+  private async exchange(generation: number): Promise<string> {
+    requireSecureBaseUrl(this.baseUrl);
+    // Re-read on every exchange: the kubelet rotates the projected token.
+    const assertion = await this.readProjectedToken();
+
+    const body: Record<string, string> = {
+      grant_type: GRANT_TYPE_JWT_BEARER,
+      assertion,
+      federation_rule_id: this.opts.federationRuleId,
+      organization_id: this.opts.organizationId,
+    };
+    if (this.opts.serviceAccountId) {
+      body.service_account_id = this.opts.serviceAccountId;
+    }
+    if (this.opts.workspaceId) body.workspace_id = this.opts.workspaceId;
+
+    let resp: Response;
+    try {
+      resp = await this.opts.fetchFn(`${this.baseUrl}${TOKEN_PATH}`, {
+        method: "POST",
+        redirect: "manual",
+        headers: {
+          "Content-Type": "application/json",
+          "anthropic-beta": `${OAUTH_API_BETA},${FEDERATION_BETA}`,
+        },
+        body: JSON.stringify(body),
+      });
+    } catch {
+      // The underlying error text could echo request details; drop it.
+      throw new AnthropicTokenExchangeError(
+        "Anthropic token exchange request failed (network error)",
+      );
+    }
+
+    const requestId = resp.headers.get("Request-Id") ?? undefined;
+    const text = await resp.text().catch(() => "");
+    let json: unknown;
+    try {
+      json = JSON.parse(text);
+    } catch {
+      json = undefined;
+    }
+
+    if (!resp.ok) {
+      const parsed = TokenErrorBody.safeParse(json);
+      const code = parsed.success ? parsed.data.error : undefined;
+      throw new AnthropicTokenExchangeError(
+        `Anthropic token exchange failed with status ${resp.status}${
+          code ? ` (${code})` : ""
+        }${requestId ? ` (request-id ${requestId})` : ""}`,
+        resp.status,
+        code,
+        requestId,
+      );
+    }
+
+    if (json === undefined) {
+      throw new AnthropicTokenExchangeError(
+        "Anthropic token exchange response was not valid JSON",
+        resp.status,
+        undefined,
+        requestId,
+      );
+    }
+    const parsed = TokenResponse.safeParse(json);
+    if (!parsed.success) {
+      throw new AnthropicTokenExchangeError(
+        "Anthropic token exchange response failed schema validation",
+        resp.status,
+        undefined,
+        requestId,
+      );
+    }
+    const { access_token, token_type, expires_in } = parsed.data;
+    if (token_type && token_type.toLowerCase() !== "bearer") {
+      throw new AnthropicTokenExchangeError(
+        "Anthropic token exchange returned an unsupported token_type",
+        resp.status,
+        undefined,
+        requestId,
+      );
+    }
+
+    // A token minted before invalidate() was called is not cached.
+    if (generation === this.generation) {
+      this.cached = {
+        token: access_token,
+        refreshAtMs:
+          this.clock.now().getTime() + expires_in * 1000 - this.skewMs,
+      };
+    }
+    return access_token;
+  }
+}