From 8b504ca2f8b2b5485aa0b01753f8580ef67c7b3a Mon Sep 17 00:00:00 2001 From: MCPJam Date: Fri, 28 Aug 2026 03:06:39 +0000 Subject: [PATCH 01/12] Deliver materialized secrets into the box, and keep them out of the transcript MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two halves of one change, because shipping either alone is worse than shipping neither: delivery without scrubbing writes credentials into transcripts, and scrubbing without delivery has nothing to scrub. The scrubber replaces EXACT KNOWN VALUES — the pairs this turn actually fetched — with `[secret:NAME]`. Not a heuristic: `log-scrubber.ts` already guesses by key name and value shape, and chat-session tool payloads are unredacted BY DESIGN, which is right (an agent debugging its own server needs the raw result) and exactly why a known value needs a different tool. It runs on the serialized ingest body rather than field by field: that options object grows a payload-bearing field every few releases, and a per-field list is one somebody forgets to extend. It searches both the raw and JSON-escaped form, so a value carrying a quote or a newline is found either way. It is a second line of defence and says so. Materialized delivery is extractable by design — an agent can base64 a value across two tool calls — and no post-hoc scrubber fixes that. What it fixes is the accidental case: a command that echoes its environment, a client that logs its own headers. Delivery is one fetch per turn, in the route, because three consumers need the same list: the emulated `bash` tool's env, the harness session's env bag, and the scrubber registry. Three fetches would be three KMS decrypts and a window where the registry is missing a value the box already has — values delivered but unregistered are values written verbatim. Sandbox bindings only. The local runner executes on the user's own machine behind an env allowlist and the remote data plane would carry the value in a request body to a plane that is not this box's; the registry reads `secretEnv` inside its `sandboxBinding` branch so a stray value elsewhere is inert. Everything travels in `envs`, never in a command string — argv is readable through `/proc` and lands in shell history. Rotation forks a resumable session. A resumed harness session reattaches to a bridge holding the environment it was created with — the exact failure the `ANTHROPIC_BASE_URL` compat bump was minted for — so the delivered set is fingerprinted into `harnessRuntimeFingerprint` as a digest, never a value. A fetch failure omits the dimension rather than sending empty: omitted resumes, empty would read as "the secrets were removed" and cold-start over a blip. Tri-state throughout: `{ok:false}` is never `[]`. A Convex blip that read as "no secrets" would strip a working session's credentials and leave the user watching a command fail with nothing changed on their side. `PtyBaseOpts` gains `envs` but nothing wires it. The only PTY routes today are persistent-computer terminals, and a persistent computer has no stable binding to one environment — the backend resolver refuses to invent one, so this side does not either. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01MCmi5hBBosufjwQ6L6UxPJ --- .../server/routes/v1/chat-session-payloads.ts | 27 ++- .../server/routes/v1/chat-session-turn.ts | 23 +- mcpjam-inspector/server/routes/web/chat-v2.ts | 59 ++++- .../server/utils/built-in-tools/registry.ts | 36 ++- .../utils/built-in-tools/sandbox-bash.ts | 27 ++- .../server/utils/chat-ingestion.ts | 58 +++-- .../utils/computers/convex-secrets-client.ts | 82 +++++++ .../server/utils/computers/create-pty.ts | 23 +- .../server/utils/computers/run-command.ts | 22 +- .../harness/__tests__/runtime-secrets.test.ts | 155 ++++++++++++ .../utils/harness/e2b-sandbox-provider.ts | 51 +++- .../server/utils/harness/run-harness-turn.ts | 197 +++++++++++----- .../server/utils/harness/runtime-secrets.ts | 124 ++++++++++ .../server/utils/mcpjam-stream-handler.ts | 221 ++++++++++-------- .../secrets/__tests__/secret-scrubber.test.ts | 157 +++++++++++++ .../server/utils/secrets/secret-scrubber.ts | 152 ++++++++++++ .../server/utils/web-chat-turn.ts | 91 +++++++- 17 files changed, 1286 insertions(+), 219 deletions(-) create mode 100644 mcpjam-inspector/server/utils/computers/convex-secrets-client.ts create mode 100644 mcpjam-inspector/server/utils/harness/__tests__/runtime-secrets.test.ts create mode 100644 mcpjam-inspector/server/utils/harness/runtime-secrets.ts create mode 100644 mcpjam-inspector/server/utils/secrets/__tests__/secret-scrubber.test.ts create mode 100644 mcpjam-inspector/server/utils/secrets/secret-scrubber.ts diff --git a/mcpjam-inspector/server/routes/v1/chat-session-payloads.ts b/mcpjam-inspector/server/routes/v1/chat-session-payloads.ts index fa66595ad2..fb750cd8fd 100644 --- a/mcpjam-inspector/server/routes/v1/chat-session-payloads.ts +++ b/mcpjam-inspector/server/routes/v1/chat-session-payloads.ts @@ -27,6 +27,8 @@ * conclude the server returned the short value and debug the wrong thing. */ +import type { SecretScrubber } from "../../utils/secrets/secret-scrubber"; + /** Nesting beyond this is replaced by a marker rather than recursed into. */ const MAX_DEPTH = 8; /** Serialized ceiling for ONE tool call's input or output. */ @@ -149,6 +151,17 @@ type EngineToolResult = { export function joinToolCalls( toolCalls: readonly EngineToolCall[], toolResults: readonly EngineToolResult[], + /** + * Materialized project secrets this turn delivered. Supplied, their values + * are replaced with `[secret:NAME]` in the LIVE response. + * + * The persistence path is scrubbed separately, at `buildIngestBody` — one + * pass over the serialized body. This is the other half: what this function + * returns goes straight back to the caller over HTTP and never passes through + * that pass, so scrubbing only there would keep the value out of the + * transcript while handing it to whoever made the request. + */ + scrubber?: SecretScrubber, ): PublicToolCall[] { const resultsById = new Map(); for (const result of toolResults) { @@ -158,14 +171,22 @@ export function joinToolCalls( resultsById.set(result.toolCallId, result); } } + const scrub = (value: T): T => + scrubber ? scrubber.scrubDeep(value) : value; return toolCalls.map((call) => { const result = resultsById.get(call.toolCallId); + // Scrubbed AFTER bounding, not before. Bounding is measured on the + // serialized payload, and `[secret:NAME]` is almost always shorter than the + // credential it replaces — so scrubbing first would let a payload that the + // caller should see truncated slip in under the cap, and two runs of the + // same tool would truncate at different points depending on whether a + // secret happened to appear. const input = boundPayload(call.input); if (!result) { return { toolCallId: call.toolCallId, toolName: call.toolName, - input: input.value, + input: scrub(input.value), status: "error" as const, // Not "the tool failed" — "no result reached us". The distinction // matters: an aborted turn and a tool that returned an error payload @@ -179,11 +200,11 @@ export function joinToolCalls( return { toolCallId: call.toolCallId, toolName: call.toolName ?? result.toolName ?? "unknown", - input: input.value, + input: scrub(input.value), status: isErrorOutput(result.output) ? ("error" as const) : ("ok" as const), - output: output.value, + output: scrub(output.value), ...(input.truncated || output.truncated ? { truncated: true as const } : {}), diff --git a/mcpjam-inspector/server/routes/v1/chat-session-turn.ts b/mcpjam-inspector/server/routes/v1/chat-session-turn.ts index 97e26049cb..d8ffe5062f 100644 --- a/mcpjam-inspector/server/routes/v1/chat-session-turn.ts +++ b/mcpjam-inspector/server/routes/v1/chat-session-turn.ts @@ -1098,8 +1098,8 @@ async function handleTurn(c: Context): Promise { const tools = noTools ? ({} as ToolSet) : body.maxToolCalls !== undefined && body.maxToolCalls > 0 - ? capToolCalls(prepared.allTools, body.maxToolCalls) - : prepared.allTools; + ? capToolCalls(prepared.allTools, body.maxToolCalls) + : prepared.allTools; const runtime = await resolveTurnRuntime({ modelDefinition, @@ -1120,7 +1120,8 @@ async function handleTurn(c: Context): Promise { const inputMessages = [...priorMessages, userMessage]; let lastEngineError: - { message: string; code?: string; httpStatus?: number } | undefined; + | { message: string; code?: string; httpStatus?: number } + | undefined; // Past this line the turn may have spent. See `modelCallStarted`. modelCallStarted = true; @@ -1197,7 +1198,7 @@ async function handleTurn(c: Context): Promise { message, { reason: rateLimited - ? (lastEngineError?.code ?? "ORG_RATE_LIMIT") + ? lastEngineError?.code ?? "ORG_RATE_LIMIT" : "TURN_FAILED", }, ); @@ -1287,6 +1288,14 @@ async function handleTurn(c: Context): Promise { toolCallCount: result.toolCalls.length, }); + // No materialized project secret can be in this turn's payloads: this route + // runs MCP SERVER TOOLS ONLY — there is no sandbox and no bash — so nothing + // was ever delivered into a box for a tool to echo back. The parameter is + // threaded rather than dropped so that the day this route gains a sandbox, + // the scrub is already in the path instead of a thing to remember; wiring + // it then is one assignment here. + const secretScrubber = undefined; + return v1Resource(c, { // May be null ONLY when the persist did not land — the caller then knows // from `persisted.outcome` that there is nothing to read back yet, which @@ -1300,7 +1309,11 @@ async function handleTurn(c: Context): Promise { projectId, reply: extractAssistantText(result), finishReason: result.finishReason ?? null, - toolCalls: joinToolCalls(result.toolCalls, result.toolResults), + toolCalls: joinToolCalls( + result.toolCalls, + result.toolResults, + secretScrubber, + ), trace: { turnId: leaseTurnId, spanCount: result.turnTrace.spans?.length ?? 0, diff --git a/mcpjam-inspector/server/routes/web/chat-v2.ts b/mcpjam-inspector/server/routes/web/chat-v2.ts index c3e40dc0a5..1bcc79ad14 100644 --- a/mcpjam-inspector/server/routes/web/chat-v2.ts +++ b/mcpjam-inspector/server/routes/web/chat-v2.ts @@ -125,6 +125,10 @@ import { maybeAppendEnvironmentContext, } from "../../utils/computers/environment-context.js"; import { buildMcpjamPlatformClient } from "./mcpjam-platform-client.js"; +import { + fetchRuntimeSecrets, + toSecretEnv, +} from "../../utils/harness/runtime-secrets.js"; import { logger } from "../../utils/logger.js"; import { resolveMrtrAuthPrincipal } from "../../utils/mrtr-hosted-collector.js"; @@ -576,8 +580,8 @@ chatV2.post("/", async (c) => { const environmentSkills = environmentSpec ? environmentRuntimeSkills(environmentSpec) : scenarioEnvironment - ? environmentRuntimeSkills({ skills: scenarioEnvironment.skills ?? [] }) - : undefined; + ? environmentRuntimeSkills({ skills: scenarioEnvironment.skills ?? [] }) + : undefined; // Enterprise-managed authorization policy. Server-authoritative wherever // a backend host config exists (scenario / host-bound turns above — the @@ -774,7 +778,9 @@ chatV2.post("/", async (c) => { // (pre-Phase-3 backend) ⇒ the tools fall back to the legacy projectId reserve. const executionScope = ( hostRuntimeConfig as - { executionScope?: ExecutionScope } | null | undefined + | { executionScope?: ExecutionScope } + | null + | undefined )?.executionScope; // COMP-16: the host-configured computer working directory — the SAME @@ -1197,6 +1203,32 @@ chatV2.post("/", async (c) => { // failure) must be rejected BEFORE it can acquire a paid box. Nothing // between here and the `streamWebChatTurn` call reads `builtInTools` or // `effectiveSystemPrompt`, which is what makes the late placement free. + // MATERIALIZED PROJECT SECRETS for this turn, resolved ONCE, here, because + // three separate things consume the SAME list and must not disagree: + // + // 1. the emulated engine's `bash` tool, which exports them into every + // command's environment (sandbox bindings only — see the registry); + // 2. the harness turn, which puts them in its sandbox session's env bag; + // 3. the transcript scrubber, which replaces those same values with + // `[secret:NAME]` in everything the turn persists. + // + // Three fetches would be three KMS decrypts per turn, and — worse — a + // window where the scrubber's registry is missing a value the box already + // has. Values delivered but unregistered are values written to the + // transcript verbatim, which is the one way this feature leaks by accident. + // + // Tri-state: on failure this is `null`, and every consumer treats that as + // "leave whatever state exists alone" rather than "there are no secrets". + const secretsFetch = await fetchRuntimeSecrets(bearerToken, { + projectId: hostedBody.projectId, + ...(environmentSpec + ? { environmentId: environmentSpec.environmentRef.environmentId } + : {}), + ...(body.chatSessionId ? { chatSessionId: body.chatSessionId } : {}), + }); + const runtimeSecrets = secretsFetch.ok ? secretsFetch.secrets : null; + const secretEnv = runtimeSecrets ? toSecretEnv(runtimeSecrets) : undefined; + const computerSandboxMode = isScenarioSession && scenarioId && !resolvedExecution.harness ? readComputerSandboxMode(hostRuntimeConfig) @@ -1207,7 +1239,8 @@ chatV2.post("/", async (c) => { // stream layer calls this right after writing the SSE parts; until it does, // the notices stay pending server-side and are re-delivered next turn. let ackSandboxNotices: - ((delivered: SandboxNoticeReason[]) => void) | undefined; + | ((delivered: SandboxNoticeReason[]) => void) + | undefined; // Drop the personal-computer resource for every suppressing plan, so // `bash` is not advertised at all rather than falling back to the member's // own box — which is precisely the behaviour this feature replaces: @@ -1348,6 +1381,12 @@ chatV2.post("/", async (c) => { // rejects anything that isn't `personal`, so a union on the config // would be either rejected or — worse — wire-forgeable. ...(sandboxBinding ? { sandboxBinding } : {}), + // Read by the registry ONLY inside its `sandboxBinding` branch: a + // project's credential reaches a box the project provisioned, never the + // user's own machine (local runner) or a remote data plane. + ...(secretEnv && Object.keys(secretEnv).length > 0 + ? { secretEnv } + : {}), mcpjamPlatformClient: buildMcpjamPlatformClient(c), }, ); @@ -1559,6 +1598,18 @@ chatV2.post("/", async (c) => { // file query cannot return a plugin skill's) and the pinned plugin // versions that fork an incompatible resumed sandbox. ...(effectiveCapabilities ? { effectiveCapabilities } : {}), + // PROJECT SECRETS: the id only, never the resolved spec. The harness + // turn fetches this environment's materialized secrets from Convex + // with the END USER'S OWN bearer, so the backend decides which of + // them that user's session receives — this process cannot ask for + // somebody else's. Absent ⇒ no grant. + ...(environmentSpec + ? { environmentId: environmentSpec.environmentRef.environmentId } + : {}), + // Already resolved above, so the turn helper does not re-fetch: + // presence is semantic, and one fetch is what keeps the scrubber's + // registry and the box's environment describing the same set. + ...(runtimeSecrets !== null ? { runtimeSecrets } : {}), ...(isDirectChat ? { directVisibility: body.directVisibility } : {}), ...(isDirectChat && body.rewind ? { rewind: body.rewind } : {}), // Hosted sessions finally honor the CAS the client already sends. diff --git a/mcpjam-inspector/server/utils/built-in-tools/registry.ts b/mcpjam-inspector/server/utils/built-in-tools/registry.ts index 97f671c3ba..a478a644a6 100644 --- a/mcpjam-inspector/server/utils/built-in-tools/registry.ts +++ b/mcpjam-inspector/server/utils/built-in-tools/registry.ts @@ -157,6 +157,20 @@ export interface BuiltInToolContext { * no wire shape that can inject one. */ sandboxBinding?: TrustedSandboxBinding; + /** + * MATERIALIZED project secrets for this turn, exported into every `bash` + * command's environment. + * + * Delivered ONLY alongside {@link sandboxBinding}, and the pairing is the + * policy rather than a coincidence of wiring: a sandbox is a disposable box + * the project provisioned, while the two other bash paths run somewhere a + * project's credential has no business being — `localBashRunner` on the + * user's own machine (behind an env allowlist), and `execViaRemoteDataPlane` + * through a request body to a plane that is not this box's. The gate below + * reads `secretEnv` only inside the `sandboxBinding` branch, so an + * accidentally-set value on another path is inert rather than dangerous. + */ + secretEnv?: Record; /** Host's approval policy — a root shell must honor it like MCP tools do. */ requireToolApproval?: boolean; /** @@ -210,7 +224,7 @@ export interface HostComputerResource { * registration — and worse, would point the tool at the caller's own machine. */ export function narrowHostComputer( - value: unknown + value: unknown, ): HostComputerResource | null { if (!value || typeof value !== "object") return null; const candidate = value as { kind?: unknown; workdir?: unknown }; @@ -243,14 +257,14 @@ function normalizeAuthHeader(raw: string): string { */ export function resolveHostTools( config: HostToolsConfig, - ctx: BuiltInToolContext | null + ctx: BuiltInToolContext | null, ): ToolSet | undefined { const ids = config.builtInToolIds ?? []; if (ids.length === 0) return undefined; if (!ctx) { logger.debug( "[built-in-tools] builtInToolIds requested without Convex auth context; omitting", - { ids: [...ids] } + { ids: [...ids] }, ); return undefined; } @@ -292,6 +306,12 @@ export function resolveHostTools( ...(ctx.sandboxBinding.lifetime ? { lifetime: ctx.sandboxBinding.lifetime } : {}), + // Read INSIDE this branch on purpose — see `secretEnv`'s own comment. + // A project secret reaches a box the project provisioned, and nothing + // else. + ...(ctx.secretEnv && Object.keys(ctx.secretEnv).length > 0 + ? { secretEnv: ctx.secretEnv } + : {}), requireToolApproval: ctx.requireToolApproval, }); continue; @@ -329,7 +349,7 @@ export function resolveHostTools( if (!computer) { logger.warn( "[built-in-tools] bash requested without a computer attached; skipping", - { projectId: ctx.projectId } + { projectId: ctx.projectId }, ); continue; } @@ -342,7 +362,7 @@ export function resolveHostTools( if (ctx.isGuest && ctx.executionScope?.kind !== "swarm") { logger.debug( "[built-in-tools] bash not advertised to guest actor without a host-funded swarm scope; skipping", - { projectId: ctx.projectId } + { projectId: ctx.projectId }, ); continue; } @@ -369,7 +389,7 @@ export function resolveHostTools( engine, isGuest: Boolean(ctx.isGuest), isScenarioSession: Boolean(ctx.isScenarioSession), - } + }, ); } out[BASH_TOOL_NAME] = buildBashTool({ @@ -392,14 +412,14 @@ export function resolveHostTools( if (ctx.isGuest || ctx.isScenarioSession) { logger.debug( "[built-in-tools] workspace tools not advertised to guest/scenario actors; skipping", - { id } + { id }, ); continue; } if (!ctx.mcpjamPlatformClient) { logger.debug( "[built-in-tools] workspace tool id without a platform client; skipping", - { id } + { id }, ); continue; } diff --git a/mcpjam-inspector/server/utils/built-in-tools/sandbox-bash.ts b/mcpjam-inspector/server/utils/built-in-tools/sandbox-bash.ts index 244796e779..f3c71dada7 100644 --- a/mcpjam-inspector/server/utils/built-in-tools/sandbox-bash.ts +++ b/mcpjam-inspector/server/utils/built-in-tools/sandbox-bash.ts @@ -86,6 +86,22 @@ export interface SandboxBashToolOptions { * the multi-step workflow a persistent shell exists to enable. */ lifetime?: "run" | "conversation"; + /** + * MATERIALIZED project secrets, exported into every command's environment. + * + * This is how a credential reaches a CLI the model runs: `stripe customers + * list` needs `STRIPE_API_KEY` in its process environment, and no amount of + * prompt engineering substitutes for that. + * + * SANDBOX BINDINGS ONLY. This tool is built only where a + * `TrustedSandboxBinding` exists, which is the whole condition: the local + * runner executes on the user's own machine behind an env allowlist, and the + * remote data plane would carry the value in a request body to a plane that + * is not this box's. Neither gets secrets, and neither builds this tool. + * + * Values travel in `envs`, never in the command string. + */ + secretEnv?: Record; } const LIFETIME_DESCRIPTION: Record< @@ -110,7 +126,7 @@ const LIFETIME_DESCRIPTION: Record< export function buildSandboxBashTool( opts: SandboxBashToolOptions, - runner: BashRunner = e2bRunner + runner: BashRunner = e2bRunner, ): ToolSet[string] { // Confined the same way the personal path confines it, so a host config can't // point an ephemeral shell outside the home root either. @@ -139,19 +155,19 @@ export function buildSandboxBashTool( .max(MAX_COMMAND_TIMEOUT_S) .optional() .describe( - `Command timeout in seconds (default ${DEFAULT_COMMAND_TIMEOUT_S})` + `Command timeout in seconds (default ${DEFAULT_COMMAND_TIMEOUT_S})`, ), }), needsApproval: opts.requireToolApproval === true, execute: async ( { command, timeoutSeconds }, - { abortSignal } + { abortSignal }, ): Promise => { if (workdirError) return { error: workdirError }; const timeoutMs = Math.min( Math.max(timeoutSeconds ?? DEFAULT_COMMAND_TIMEOUT_S, 1), - MAX_COMMAND_TIMEOUT_S + MAX_COMMAND_TIMEOUT_S, ) * 1000; try { const result = await runner({ @@ -166,6 +182,9 @@ export function buildSandboxBashTool( ...(workdir ? { workdir } : {}), timeoutMs, ...(abortSignal ? { signal: abortSignal } : {}), + ...(opts.secretEnv && Object.keys(opts.secretEnv).length > 0 + ? { envs: opts.secretEnv } + : {}), }); const authUrls = detectAuthUrls(`${result.stdout}\n${result.stderr}`); return { diff --git a/mcpjam-inspector/server/utils/chat-ingestion.ts b/mcpjam-inspector/server/utils/chat-ingestion.ts index 6823e0e2af..7745803124 100644 --- a/mcpjam-inspector/server/utils/chat-ingestion.ts +++ b/mcpjam-inspector/server/utils/chat-ingestion.ts @@ -12,6 +12,7 @@ import { type PersistReceiptData, } from "@/shared/persist-receipt"; import type { EvalTraceSpan } from "@/shared/eval-trace"; +import type { SecretScrubber } from "./secrets/secret-scrubber"; import type { LiveChatTraceUsage } from "@/shared/live-chat-trace"; const DEFAULT_INGEST_TIMEOUT_MS = 5_000; @@ -82,7 +83,7 @@ const ENRICHMENT_HEADERS_TO_FORWARD = [ * forwarded to the Convex `/ingest-chat` endpoint. */ export function pickEnrichmentHeaders( - reqHeaders: { get(name: string): string | null | undefined } | Headers + reqHeaders: { get(name: string): string | null | undefined } | Headers, ): Record { const result: Record = {}; for (const name of ENRICHMENT_HEADERS_TO_FORWARD) { @@ -286,6 +287,20 @@ interface PersistChatSessionOptions { expectedVersion?: number; rewind?: ChatRewind; turnTrace?: PersistedTurnTrace; + /** + * Materialized project secrets this turn delivered into the sandbox, so their + * values are replaced with `[secret:NAME]` before anything is persisted. + * + * Applied at the SERIALIZED body (see `buildIngestBody`) rather than field by + * field: this options object grows a new payload-bearing field every few + * releases, and a per-field scrub is a list somebody eventually forgets to + * extend. One pass over the bytes that actually leave the process cannot be + * partially applied. + * + * Absent on every caller that delivers no secrets, which is almost all of + * them — a session with nothing registered does no work here at all. + */ + secretScrubber?: SecretScrubber; /** * §3: chat-backed harness resume-state commit. Applied ATOMICALLY with the * transcript inside the ingest mutation (a failed sidecar commit rolls back @@ -390,14 +405,14 @@ export function stampSenderUserIdsOnSessionMessages( sourceMessages: unknown[], options?: { authenticatedUserId?: string | null; - } + }, ): unknown[] { if (!Array.isArray(sessionMessages) || !Array.isArray(sourceMessages)) { return sessionMessages; } const authenticatedUserId = normalizeSenderUserId( - options?.authenticatedUserId + options?.authenticatedUserId, ); const senderUserIdsByUserOrdinal = sourceMessages .filter((message) => isRecord(message) && message.role === "user") @@ -441,12 +456,12 @@ function sanitizeDiagnosticText(text: string): string { .replace( /(\bauthorization\b\s*[:=]\s*)(bearer\s+)?([^"',\s}]+)/gi, (_match, prefix: string, scheme?: string) => - `${prefix}${scheme ?? ""}[redacted-token]` + `${prefix}${scheme ?? ""}[redacted-token]`, ) .replace(/\b(Bearer\s+)[A-Za-z0-9._\-+/=]+\b/gi, "$1[redacted-token]") .replace( /(["']?(?:api[_-]?key|token|access[_-]?token|refresh[_-]?token)["']?\s*[:=]\s*["']?)([^"',\s}]+)/gi, - "$1[redacted-secret]" + "$1[redacted-secret]", ) .replace(/\bsk-[A-Za-z0-9]+\b/g, "[redacted-secret]"); @@ -467,7 +482,7 @@ async function readResponsePreview(response: Response): Promise { * retry as the same turn. */ function buildIngestBody(options: PersistChatSessionOptions): string { - return JSON.stringify({ + const body = JSON.stringify({ chatSessionId: options.chatSessionId, modelId: options.modelId, modelSource: options.modelSource, @@ -529,6 +544,17 @@ function buildIngestBody(options: PersistChatSessionOptions): string { ...(options.hostId ? { hostId: options.hostId } : {}), ...(options.targetId ? { targetId: options.targetId } : {}), }); + // AFTER serialization, on purpose. Every payload this body can carry — + // messages, tool inputs, tool outputs, the assistant's own text, a nested + // JSON string a tool returned — is inside these bytes by now, and the + // scrubber searches both the raw and the JSON-escaped form of each value, so + // a credential that was quoted or newline-bearing is found either way. + // + // Byte-identity across retries is preserved: the scrub is deterministic and + // runs once, outside the retry loop, exactly like the stringify it follows. + return options.secretScrubber + ? options.secretScrubber.scrubString(body) + : body; } type IngestAttemptResult = @@ -600,7 +626,7 @@ async function attemptChatIngest( url: string, headers: Record, body: string, - timeoutMs: number + timeoutMs: number, ): Promise { // A fresh controller per attempt. Reusing one across retries would poison // every later attempt: once aborted, an AbortSignal stays aborted, so retry 1 @@ -716,7 +742,7 @@ function sleep(ms: number): Promise { export async function persistChatSessionToConvex( options: PersistChatSessionOptions, - c?: Context + c?: Context, ): Promise { const convexUrl = process.env.CONVEX_HTTP_URL; if (!convexUrl) { @@ -756,7 +782,7 @@ export async function persistChatSessionToConvex( sourceType: options.sourceType, origin: options.origin, }, - error ? { error } : undefined + error ? { error } : undefined, ); return; } @@ -770,7 +796,7 @@ export async function persistChatSessionToConvex( if (failureKind === "timeout") { logger.warn( "[chat-session-persistence] Timed out persisting chat session", - { timeoutMs: perAttemptTimeoutMs } + { timeoutMs: perAttemptTimeoutMs }, ); return; } @@ -784,7 +810,7 @@ export async function persistChatSessionToConvex( `[chat-session-persistence] Failed to persist chat session${ status !== undefined ? ` (${status})` : "" }${preview ? `: ${preview}` : ""}`, - { status, responsePreview: preview } + { status, responsePreview: preview }, ); }; @@ -805,7 +831,7 @@ export async function persistChatSessionToConvex( body, // Truncated rather than allowed to overrun: the caller may be holding a // stream open on this promise. - Math.min(perAttemptTimeoutMs, remainingMs) + Math.min(perAttemptTimeoutMs, remainingMs), ); if (result.kind === "settled") { @@ -833,11 +859,11 @@ export async function persistChatSessionToConvex( sourceType: options.sourceType, origin: options.origin, hasTurnId: Boolean(options.turnTrace?.turnId), - } + }, ); } else { logger.warn( - "[chat-session-persistence] Ingest reported the turn as a replay and skipped it" + "[chat-session-persistence] Ingest reported the turn as a replay and skipped it", ); } } @@ -888,7 +914,7 @@ type PersistReceiptWriter = { write: (chunk: UIMessageChunk) => void }; */ export function buildPersistReceiptData( outcome: PersistChatOutcome, - context: { chatSessionId: string; turnId?: string } + context: { chatSessionId: string; turnId?: string }, ): PersistReceiptData | null { if (outcome.outcome === "not-attempted") { return null; @@ -936,7 +962,7 @@ export function buildPersistReceiptData( export function writePersistReceipt( writer: PersistReceiptWriter | undefined, outcome: PersistChatOutcome, - context: { chatSessionId: string; turnId?: string } + context: { chatSessionId: string; turnId?: string }, ): void { if (!writer) return; const data = buildPersistReceiptData(outcome, context); diff --git a/mcpjam-inspector/server/utils/computers/convex-secrets-client.ts b/mcpjam-inspector/server/utils/computers/convex-secrets-client.ts new file mode 100644 index 0000000000..52dceb24fc --- /dev/null +++ b/mcpjam-inspector/server/utils/computers/convex-secrets-client.ts @@ -0,0 +1,82 @@ +/** + * Thin client for the backend `projectSecretsNode` Convex functions. + * + * Mirrors `convex-skills-client.ts` — `ConvexHttpClient`, string function names, + * local DTOs, no codegen dependency — with two deliberate differences. + * + * ## It calls an ACTION, not a query + * + * The skills family is query-only, so `.action(...)` is a first in it. That is + * not a stylistic choice: the resolver has to DECRYPT, decryption is Node-only + * in Convex, and a query cannot be a Node function. It is also the right shape + * on its own terms — Convex queries are cached, replayable and subscribable, and + * a credential should be none of those. `ConvexHttpClient` supports actions, so + * the transport is unchanged. + * + * ## The bearer IS the authorization + * + * The backend action reads `ctx.actor.userId` from this bearer and checks the + * personal-secret rule against it. There is no `userId` argument and there must + * never be one: an argument would let this process name whose secrets it wants, + * and the whole personal-secret guarantee rests on it being unable to. + * + * ## Write-only, here too + * + * There is no create/update/delete in this file. Those go over the v1 HTTP API + * (`routes/v1/secrets.ts`), where they are audited and rate-limited like every + * other write. This module exists solely to deliver values into a runtime. + */ +import { ConvexHttpClient } from "convex/browser"; + +/** One materialized secret, ready to be exported as an environment variable. */ +export interface RuntimeSecret { + /** The env-var name. Backend-validated `^[A-Z_][A-Z0-9_]*$`. */ + name: string; + value: string; +} + +/** Convex function names — one place, so a rename is one edit. */ +const FN = { + /** + * MATERIALIZED secrets only. A brokered secret's value is never returned by + * anything, to anyone — it reaches its box through E2B's egress proxy and + * never enters this process. There is deliberately no sibling function that + * would return one. + */ + forRuntimeExecution: "projectSecretsNode:listSecretsForRuntimeExecution", +} as const; + +function stripBearer(token: string): string { + return token.replace(/^Bearer\s+/i, "").trim(); +} + +function makeClient(bearer: string): ConvexHttpClient { + const url = process.env.CONVEX_URL; + if (!url) { + throw new Error("CONVEX_URL is not configured"); + } + const client = new ConvexHttpClient(url); + client.setAuth(stripBearer(bearer)); + return client; +} + +/** + * Fetch the materialized secrets this environment grants to THIS caller's + * sessions. + * + * Throws on any failure. The tri-state wrapper (`runtime-secrets.ts`) is what + * turns that into `{ ok: false }`, and the distinction matters enough that the + * two live in different modules: an empty array here means "this environment + * grants nothing", and a thrown error must never be flattened into it. + */ +export async function convexListSecretsForRuntimeExecution( + bearer: string, + args: { + projectId: string; + environmentId: string; + /** Scopes the delivery throttle and the decrypt audit trail. Not authz. */ + chatSessionId?: string; + }, +): Promise { + return await makeClient(bearer).action(FN.forRuntimeExecution as any, args); +} diff --git a/mcpjam-inspector/server/utils/computers/create-pty.ts b/mcpjam-inspector/server/utils/computers/create-pty.ts index ba67d05eb3..2d703e87b4 100644 --- a/mcpjam-inspector/server/utils/computers/create-pty.ts +++ b/mcpjam-inspector/server/utils/computers/create-pty.ts @@ -15,6 +15,25 @@ export interface PtyBaseOpts { rows: number; timeoutMs: number; onData: (data: Uint8Array) => void; + /** + * Extra environment for the shell — how a MATERIALIZED project secret reaches + * a HUMAN typing `stripe customers list` into the terminal, not just an agent + * calling a tool. + * + * Carried through the retry-without-cwd fallback below, which is the whole + * reason it lives on the BASE opts rather than being passed alongside them: a + * stale workdir must cost the terminal its directory, never its environment. + * + * NOT WIRED YET, and the reason is a real constraint rather than an omission. + * The only PTY routes today are the persistent-computer terminals, and a + * persistent computer has no stable binding to any one Project Environment — + * it outlives runs, is reused across them, and can be attached to several — so + * there is no honest answer to "which secrets does this box hold". The backend + * grant resolver refuses to invent one (`projectSecretsEgress.ts`), and this + * side must not invent one either. When a session-sandbox terminal exists, its + * box DOES have an environment, and wiring it is one field at that call site. + */ + envs?: Record; } /** Minimal shape of the E2B sandbox we depend on (keeps this unit-testable). */ @@ -41,7 +60,9 @@ export async function createPtyWithCwd( } /** Accept only an absolute, length-bounded path as a cwd; reject anything else. */ -export function sanitizeTerminalCwd(raw: string | undefined): string | undefined { +export function sanitizeTerminalCwd( + raw: string | undefined, +): string | undefined { if (!raw || !raw.startsWith("/") || raw.length > 1024) return undefined; return raw; } diff --git a/mcpjam-inspector/server/utils/computers/run-command.ts b/mcpjam-inspector/server/utils/computers/run-command.ts index 8331a7fa7d..499e05e4d2 100644 --- a/mcpjam-inspector/server/utils/computers/run-command.ts +++ b/mcpjam-inspector/server/utils/computers/run-command.ts @@ -60,6 +60,22 @@ export type BashRunner = (args: { workdir?: string; timeoutMs: number; signal?: AbortSignal; + /** + * Extra environment for THIS command — how a materialized project secret + * reaches a CLI the emulated engine runs (`stripe`, `gh`, `psql`). + * + * In `envs`, never interpolated into `command`. Argv is readable by every + * process in the box through `/proc` and lands in shell history; the + * environment is not (`plugin-box.ts` states the same rule for the same + * reason). + * + * Only the SANDBOX runners honour this. `localBashRunner` runs on the user's + * own machine behind a strict env allowlist, and `execViaRemoteDataPlane` + * would put the value in a request body to a plane that is not this box's — + * neither is a place a project's credential should appear, so neither takes + * the parameter's value even if one is passed. + */ + envs?: Record; }) => Promise<{ stdout: string; stderr: string; exitCode: number }>; // Default runner — real E2B. Kept injectable so tests exercise the pipeline @@ -70,6 +86,7 @@ export const e2bRunner: BashRunner = async ({ workdir, timeoutMs, signal, + envs, }) => { const sandbox = await Sandbox.connect(sandboxId); try { @@ -86,6 +103,7 @@ export const e2bRunner: BashRunner = async ({ ...(workdir ? { cwd: workdir } : {}), timeoutMs, ...(signal ? { signal } : {}), + ...(envs && Object.keys(envs).length > 0 ? { envs } : {}), }); return { stdout: result.stdout, @@ -131,7 +149,7 @@ export interface RunComputerCommandArgs { export async function runComputerCommand( args: RunComputerCommandArgs, - runner: BashRunner = e2bRunner + runner: BashRunner = e2bRunner, ): Promise { if (!isComputersDataPlaneConfigured()) { return { error: COMPUTERS_NOT_CONFIGURED_ERROR }; @@ -173,7 +191,7 @@ export async function runComputerCommand( const timeoutMs = Math.min( Math.max(args.timeoutSeconds ?? DEFAULT_COMMAND_TIMEOUT_S, 1), - MAX_COMMAND_TIMEOUT_S + MAX_COMMAND_TIMEOUT_S, ) * 1000; let result: { stdout: string; stderr: string; exitCode: number }; diff --git a/mcpjam-inspector/server/utils/harness/__tests__/runtime-secrets.test.ts b/mcpjam-inspector/server/utils/harness/__tests__/runtime-secrets.test.ts new file mode 100644 index 0000000000..aeb2d4245a --- /dev/null +++ b/mcpjam-inspector/server/utils/harness/__tests__/runtime-secrets.test.ts @@ -0,0 +1,155 @@ +/** + * Materialized secret delivery: the tri-state, and the rotation fork. + * + * Both properties are the kind that only fail in production, so they are pinned + * here rather than trusted to the shape of the code: + * + * - a FETCH FAILURE must not be indistinguishable from "no secrets". If it + * were, a Convex blip would strip a working session's credentials and the + * user would see a `stripe` command start failing with nothing changed on + * their side. + * - a ROTATION must change the fingerprint. A resumed harness session + * reattaches to a bridge process holding the environment it was created + * with, so a rotation that did not fork would land everywhere except the + * conversation the user is sitting in. + */ +import { afterEach, describe, expect, it, vi } from "vitest"; + +const listSecrets = vi.fn(); +vi.mock("../../computers/convex-secrets-client.js", () => ({ + convexListSecretsForRuntimeExecution: (...args: unknown[]) => + listSecrets(...args), +})); + +const { fetchRuntimeSecrets, deliveredSecretsFingerprint, toSecretEnv } = + await import("../runtime-secrets.js"); + +afterEach(() => { + vi.clearAllMocks(); +}); + +describe("fetchRuntimeSecrets", () => { + it("returns an empty SUCCESS when there is no environment to grant from", async () => { + // The environment IS the grant boundary. No environment is not a failure — + // there is simply nothing granted — so callers must not treat it as one. + await expect( + fetchRuntimeSecrets("Bearer t", { projectId: "p1" }), + ).resolves.toEqual({ ok: true, secrets: [] }); + expect(listSecrets).not.toHaveBeenCalled(); + }); + + it("returns an empty SUCCESS with no bearer, without calling the backend", async () => { + await expect( + fetchRuntimeSecrets(undefined, { projectId: "p1", environmentId: "e1" }), + ).resolves.toEqual({ ok: true, secrets: [] }); + expect(listSecrets).not.toHaveBeenCalled(); + }); + + it("passes the bearer and the ids through, and returns what the backend gave", async () => { + listSecrets.mockResolvedValueOnce([ + { name: "STRIPE_API_KEY", value: "sk" }, + ]); + await expect( + fetchRuntimeSecrets("Bearer t", { + projectId: "p1", + environmentId: "e1", + chatSessionId: "cs1", + }), + ).resolves.toEqual({ + ok: true, + secrets: [{ name: "STRIPE_API_KEY", value: "sk" }], + }); + expect(listSecrets).toHaveBeenCalledWith("Bearer t", { + projectId: "p1", + environmentId: "e1", + chatSessionId: "cs1", + }); + }); + + it("reports a failure as { ok: false }, NEVER as an empty list", async () => { + listSecrets.mockRejectedValueOnce(new Error("convex down")); + await expect( + fetchRuntimeSecrets("Bearer t", { + projectId: "p1", + environmentId: "e1", + }), + ).resolves.toEqual({ ok: false }); + }); +}); + +describe("deliveredSecretsFingerprint", () => { + it("is empty for no secrets, so a secretless turn keeps resuming", () => { + // Byte-identical to a world where this dimension does not exist. + expect(deliveredSecretsFingerprint([])).toBe(""); + }); + + it("changes when a VALUE rotates under the same name", () => { + const before = deliveredSecretsFingerprint([ + { name: "STRIPE_API_KEY", value: "sk_live_old" }, + ]); + const after = deliveredSecretsFingerprint([ + { name: "STRIPE_API_KEY", value: "sk_live_new" }, + ]); + expect(after).not.toBe(before); + }); + + it("changes when a secret is added or removed", () => { + const one = deliveredSecretsFingerprint([{ name: "A_KEY", value: "v1" }]); + const two = deliveredSecretsFingerprint([ + { name: "A_KEY", value: "v1" }, + { name: "B_KEY", value: "v2" }, + ]); + expect(two).not.toBe(one); + }); + + it("is order-independent", () => { + const forward = deliveredSecretsFingerprint([ + { name: "A_KEY", value: "v1" }, + { name: "B_KEY", value: "v2" }, + ]); + const reversed = deliveredSecretsFingerprint([ + { name: "B_KEY", value: "v2" }, + { name: "A_KEY", value: "v1" }, + ]); + expect(forward).toBe(reversed); + }); + + it("does not contain the value it fingerprints", () => { + // The digest is folded into another hash before anything is stored, but the + // first hop must not be the credential itself either. + const fp = deliveredSecretsFingerprint([ + { name: "STRIPE_API_KEY", value: "sk_live_51H8xQ2abcdef" }, + ]); + expect(fp).not.toContain("sk_live"); + expect(fp).toMatch(/^[0-9a-f]+$/); + }); + + it("distinguishes two secrets whose values were swapped between names", () => { + // A digest keyed only on the value set would collide here, and the two are + // materially different environments. + const a = deliveredSecretsFingerprint([ + { name: "A_KEY", value: "one" }, + { name: "B_KEY", value: "two" }, + ]); + const b = deliveredSecretsFingerprint([ + { name: "A_KEY", value: "two" }, + { name: "B_KEY", value: "one" }, + ]); + expect(a).not.toBe(b); + }); +}); + +describe("toSecretEnv", () => { + it("maps names to values", () => { + expect( + toSecretEnv([ + { name: "A_KEY", value: "1" }, + { name: "B_KEY", value: "2" }, + ]), + ).toEqual({ A_KEY: "1", B_KEY: "2" }); + }); + + it("is empty for an empty list, so no call site has to special-case it", () => { + expect(toSecretEnv([])).toEqual({}); + }); +}); diff --git a/mcpjam-inspector/server/utils/harness/e2b-sandbox-provider.ts b/mcpjam-inspector/server/utils/harness/e2b-sandbox-provider.ts index 0e78d4c537..5241c7bac3 100644 --- a/mcpjam-inspector/server/utils/harness/e2b-sandbox-provider.ts +++ b/mcpjam-inspector/server/utils/harness/e2b-sandbox-provider.ts @@ -47,6 +47,25 @@ export interface E2BHarnessSandboxProviderOptions { * ~60s — too short for the harness bootstrap (`pnpm install`) on a larger * dep tree. Background `spawn` is not subject to the foreground cap. */ commandTimeoutMs?: number; + /** + * SESSION-WIDE environment merged into every `run` and `spawn`. + * + * This is how a MATERIALIZED project secret reaches a CLI in the box: the + * agent runs `stripe customers list`, and `STRIPE_API_KEY` has to be in that + * process's environment. Per-command `env` already existed, but the harness + * composes its own commands — nothing upstream of a `run` call knows to add a + * credential to it — so the bag has to live with the session. + * + * A CALLER-SUPPLIED `env` WINS on collision. The session bag is ambient + * configuration; a per-command value is a deliberate override at the call + * site, and ambient config silently beating an explicit argument is the + * surprise nobody debugs successfully. + * + * Secrets travel in `envs`, never in the command line — the rule + * `plugin-box.ts` already states, for the same reason: argv is visible to + * every process in the box through `/proc` and lands in shell history. + */ + sessionEnv?: Record; } const enc = new TextEncoder(); @@ -125,7 +144,7 @@ function bytesToStream(bytes: Uint8Array): ReadableStream { } async function streamToBytes( - stream: ReadableStream + stream: ReadableStream, ): Promise { const chunks: Uint8Array[] = []; const reader = stream.getReader(); @@ -145,7 +164,7 @@ async function streamToBytes( } export function createE2BHarnessSandboxProvider( - opts: E2BHarnessSandboxProviderOptions + opts: E2BHarnessSandboxProviderOptions, ): HarnessV1SandboxProvider { const bridgePort = opts.bridgePort ?? 39271; const cwd = opts.defaultWorkingDirectory ?? "/home/user"; @@ -153,6 +172,18 @@ export function createE2BHarnessSandboxProvider( // from the sandbox's own lifetime — too short for the harness bootstrap // (`pnpm install`). Background `spawn` is not subject to this cap. const commandTimeoutMs = opts.commandTimeoutMs ?? 10 * 60_000; + // Frozen at provider construction. The session's env is fixed for its + // lifetime by design: a harness session that changed its environment + // mid-flight would hand different commands different credentials, and the + // runtime fingerprint exists precisely so a change forks a NEW session + // instead. + const sessionEnv = opts.sessionEnv; + const mergeEnv = ( + env: Record | undefined, + ): Record | undefined => { + if (!sessionEnv) return env; + return { ...sessionEnv, ...(env ?? {}) }; + }; // Connect to the host's persistent computer and build a session bound to it. // Shared by createSession (fresh) and resumeSession (reattach): for our E2B @@ -161,7 +192,7 @@ export function createE2BHarnessSandboxProvider( // (which persists on the box) using the `resumeFrom` state; our provider just // has to supply the sandbox connection. const connectSession = async ( - connectSignal?: AbortSignal + connectSignal?: AbortSignal, ): Promise => { // Reuse the host's existing computer. It must already be awake — the // caller wakes it via the control plane (`ensureComputerReady`) before @@ -201,7 +232,7 @@ export function createE2BHarnessSandboxProvider( `model proxy, the package registry is unreachable by design — the ` + `harness runtime must be installed before that lock. Output: ` + (output ? output.slice(-500) : "(none)"), - { cause: err } + { cause: err }, ); } throw err; @@ -213,7 +244,7 @@ export function createE2BHarnessSandboxProvider( description: `E2B sandbox ${sandbox.sandboxId} (host computer). Working dir ${cwd}. ` + `Bridge port ${bridgePort} reachable at ${sandbox.getHost( - bridgePort + bridgePort, )}.`, // ── file I/O ────────────────────────────────────────────────────── @@ -249,14 +280,14 @@ export function createE2BHarnessSandboxProvider( enforceHarnessWritePath(path); await sandbox.files.write( [{ path, data: content }], - signalOpt(abortSignal) + signalOpt(abortSignal), ); }, writeBinaryFile: async ({ path, content, abortSignal }) => { enforceHarnessWritePath(path); await sandbox.files.write( [{ path, data: u8ToArrayBuffer(content) }], - signalOpt(abortSignal) + signalOpt(abortSignal), ); }, writeFile: async ({ path, content, abortSignal }) => { @@ -264,7 +295,7 @@ export function createE2BHarnessSandboxProvider( const bytes = await streamToBytes(content); await sandbox.files.write( [{ path, data: u8ToArrayBuffer(bytes) }], - signalOpt(abortSignal) + signalOpt(abortSignal), ); }, @@ -273,7 +304,7 @@ export function createE2BHarnessSandboxProvider( try { const res = await sandbox.commands.run(command, { cwd: workingDirectory ?? cwd, - envs: env, + envs: mergeEnv(env), timeoutMs: commandTimeoutMs, ...signalOpt(abortSignal), }); @@ -324,7 +355,7 @@ export function createE2BHarnessSandboxProvider( const handle = await sandbox.commands.run(command, { background: true, cwd: workingDirectory ?? cwd, - envs: env, + envs: mergeEnv(env), ...signalOpt(abortSignal), // Guard against enqueue-after-close once the process ends/is killed. onStdout: (d: string) => { diff --git a/mcpjam-inspector/server/utils/harness/run-harness-turn.ts b/mcpjam-inspector/server/utils/harness/run-harness-turn.ts index ac9869f64b..90eccdf18f 100644 --- a/mcpjam-inspector/server/utils/harness/run-harness-turn.ts +++ b/mcpjam-inspector/server/utils/harness/run-harness-turn.ts @@ -105,6 +105,12 @@ import { fetchRuntimeSkillFiles, skillsFingerprint, } from "./runtime-skills.js"; +import { + deliveredSecretsFingerprint, + fetchRuntimeSecrets, + toSecretEnv, +} from "./runtime-secrets.js"; +import { createSecretScrubber } from "../secrets/secret-scrubber.js"; import { materializeSkillFiles } from "./materialize-skill-files.js"; import { materializePinnedSkillFiles } from "./pinned-harness-skills.js"; import { selectHarnessSkillSource } from "./skill-delivery.js"; @@ -216,7 +222,7 @@ export async function buildHarnessProxyMcpJsonFromManager(args: { ...(pluginOrigins ? { pluginOrigins } : {}), onSkipped: (id) => logger.warn( - `[harness] selected server has no live config; skipping serverId=${id}` + `[harness] selected server has no live config; skipping serverId=${id}`, ), }); @@ -233,7 +239,7 @@ export async function buildHarnessProxyMcpJsonFromManager(args: { }); if (!minted.ok) { throw new Error( - `Couldn't mint harness MCP proxy tokens (${minted.status}): ${minted.error}` + `Couldn't mint harness MCP proxy tokens (${minted.status}): ${minted.error}`, ); } // Hard-fail, never skip: the harness must run with every selected server or @@ -245,7 +251,7 @@ export async function buildHarnessProxyMcpJsonFromManager(args: { const token = minted.tokens[id]; if (!token) { throw new Error( - `Harness MCP proxy: no token minted for selected serverId=${id} — refusing to run with missing MCP tools` + `Harness MCP proxy: no token minted for selected serverId=${id} — refusing to run with missing MCP tools`, ); } const url = await resolveHarnessProxyUrl({ @@ -287,7 +293,7 @@ export async function buildHarnessProxyMcpJsonFromManager(args: { // there. A policied run must never reach it. if (toolPolicy) { throw new Error( - "TOOL_POLICY_UNSUPPORTED: a tool policy cannot be enforced on the local-mcp harness plane (adapter-http accepts an absent proxy token), so the run is refused rather than run unenforced" + "TOOL_POLICY_UNSUPPORTED: a tool policy cannot be enforced on the local-mcp harness plane (adapter-http accepts an absent proxy token), so the run is refused rather than run unenforced", ); } for (const id of configured) { @@ -311,7 +317,7 @@ export async function buildHarnessProxyMcpJsonFromManager(args: { const header = entry.headers?.["X-MCPJam-Proxy-Token"]; if (!isSealedHarnessProxyToken(header)) { throw new Error( - `TOOL_POLICY_UNSEALED: harness .mcp.json entry for serverId=${serverId} carries an unsealed proxy token while a tool policy is in force — refusing to run unenforced` + `TOOL_POLICY_UNSEALED: harness .mcp.json entry for serverId=${serverId} carries an unsealed proxy token while a tool policy is in force — refusing to run unenforced`, ); } } @@ -361,7 +367,7 @@ const TYPED_TOOL_OUTPUT_TYPES: ReadonlySet = new Set([ * anything else is wrapped once as `{type:"json", value}`. */ export function toToolResultOutput( rawOutput: unknown, - isError: boolean + isError: boolean, ): { type: string; value: unknown } { if (isError) { return { @@ -432,6 +438,21 @@ export function harnessRuntimeFingerprint(parts: { * to before this dimension existed and its sessions keep resuming. */ pluginVersions?: RuntimePluginVersion[]; + /** + * The MATERIALIZED project secrets delivered into this turn's box + * (`deliveredSecretsFingerprint` — a digest, never a value). + * + * A resumed session reattaches to a bridge process holding the environment it + * was CREATED with, so a rotated credential would otherwise be delivered to a + * box that already has the old one. Forking is the only way a rotation + * reaches an in-flight conversation. + * + * Appended ONLY when non-empty, so a secretless turn hashes byte-identically + * to before this dimension existed and its sessions keep resuming. A fetch + * FAILURE omits it entirely (see the call site) rather than sending `""`, + * which would read as "the secrets were removed". + */ + secretsHash?: string; }): string { const pluginDimension = pluginVersionsFingerprint(parts.pluginVersions ?? []); const s = [ @@ -439,6 +460,7 @@ export function harnessRuntimeFingerprint(parts: { (parts.selectedServers ?? []).slice().sort().join(","), parts.permissionMode, ...(pluginDimension ? [pluginDimension] : []), + ...(parts.secretsHash ? [parts.secretsHash] : []), ].join(""); let h = 0x811c9dc5; for (let i = 0; i < s.length; i++) { @@ -477,7 +499,7 @@ const DEFAULT_POLICY_SEAL_TTL_MS = 6 * 60 * 60_000; export async function runHarnessTurn( options: MCPJamHandlerOptions, - streamSink: "ui" | "none" + streamSink: "ui" | "none", ): Promise { const { messages, @@ -518,12 +540,14 @@ export async function runHarnessTurn( pinnedHarnessSkills, runtimeSkillsOverride, effectiveCapabilities, + environmentId, + runtimeSecrets: runtimeSecretsOverride, createHarnessScopeStepUpContinuation, } = options; // One typed route.operation.failed per turn; the system fallback covers // callers with no request context (evals/swarms). const failureReporter = oncePerTurn( - failureReporterOption ?? createSystemStreamFailureReporter("harness-turn") + failureReporterOption ?? createSystemStreamFailureReporter("harness-turn"), ); // Canonicalize the model id up front (bare hosted ids like `gpt-5-nano` → // `openai/gpt-5-nano`). Everything downstream — supportsModel, the adapter's @@ -552,7 +576,7 @@ export async function runHarnessTurn( throw new Error( "runHarnessTurn: an ephemeral sandbox binding cannot be combined with " + "an execution scope (the guest/host-funded path runs on the scenario's " + - "own computer)" + "own computer)", ); } const harnessAdapter = getHarnessAdapter(harness); @@ -666,13 +690,13 @@ export async function runHarnessTurn( `${serverId}\u0000${toolName}`; const claimChannelPolicyBlock = ( serverId: string, - toolName: string + toolName: string, ): HarnessPolicyBlockEvent | undefined => { const event = channelPolicyBlocks.find( (candidate) => !candidate.claimed && candidate.serverId === serverId && - candidate.toolName === toolName + candidate.toolName === toolName, ); if (event) event.claimed = true; return event; @@ -777,7 +801,7 @@ export async function runHarnessTurn( }, toolName: matchingCall.toolName, toolInput: matchingCall.input, - }) + }), ) .then((event) => { emitScopeStepUpRequiredChunk(writer, event); @@ -821,7 +845,7 @@ export async function runHarnessTurn( ? subscribeHarnessScopeStepUp( turnId, receiveScopeStepUpChallenge, - selectedServers + selectedServers, ) : () => {}; @@ -838,7 +862,7 @@ export async function runHarnessTurn( (event) => { channelPolicyBlocks.push({ ...event }); }, - selectedServers + selectedServers, ) : () => {}; const stopPolicyBlockPoll = @@ -869,12 +893,12 @@ export async function runHarnessTurn( try { if (!projectId) { throw new Error( - "harness turn requires a projectId to resolve the computer" + "harness turn requires a projectId to resolve the computer", ); } if (!authHeader) { throw new Error( - "harness turn requires an auth bearer to resolve the computer" + "harness turn requires an auth bearer to resolve the computer", ); } // WS3: requireToolApproval is now SUPPORTED via the harness's native @@ -912,7 +936,7 @@ export async function runHarnessTurn( // silently substitute its own default model. if (!harnessAdapter.supportsModel(modelId)) { throw new Error( - `The ${harnessAdapter.displayName} harness can't run model "${modelId}".` + `The ${harnessAdapter.displayName} harness can't run model "${modelId}".`, ); } // (a2) capability/hook invariant for plugin BUNDLE install: advertising @@ -925,7 +949,7 @@ export async function runHarnessTurn( ) { throw new Error( `The ${harnessAdapter.displayName} harness advertises plugin-bundle ` + - "support but has no deliverPluginBundles strategy (adapter misconfigured)." + "support but has no deliverPluginBundles strategy (adapter misconfigured).", ); } // (b) approval invariant (advertise = enforce). The route pre-flight @@ -960,7 +984,7 @@ export async function runHarnessTurn( "Harness runs require broker credential delivery, but it is " + "disabled on this server (MCPJAM_HARNESS_BROKER_DELIVERY=false). " + "There is no fallback credential path — re-enable the broker to " + - "run harness turns." + "run harness turns.", ); } @@ -994,7 +1018,7 @@ export async function runHarnessTurn( !harnessMcpProxy ) { throw new Error( - "harness turn has MCP servers but no harnessMcpProxy strategy — the caller route must set options.harnessMcpProxy" + "harness turn has MCP servers but no harnessMcpProxy strategy — the caller route must set options.harnessMcpProxy", ); } const pluginServerOrigins = effectiveCapabilities @@ -1103,6 +1127,39 @@ export async function runHarnessTurn( const runtimeSkills = skillsFetch.ok ? skillsFetch.skills : null; const skillsHash = runtimeSkills !== null ? skillsFingerprint(runtimeSkills) : undefined; + + // MATERIALIZED PROJECT SECRETS, fetched beside the skills and for the + // same reason: both are per-turn runtime material the box needs before + // the first command runs. + // + // TRI-STATE, and the stakes are higher than for skills. `{ ok: false }` + // must never read as "no secrets": a transient Convex blip that dropped + // the env bag would leave the user watching a `stripe` command fail with + // nothing changed on their side to explain it. On failure the turn keeps + // whatever the session already has rather than deliberately handing it an + // empty environment. + // + // Brokered secrets are NOT here and never will be: their values reach the + // box through E2B's egress proxy, outside this process entirely. + const secretsFetch = + runtimeSecretsOverride !== undefined + ? { ok: true as const, secrets: runtimeSecretsOverride } + : await fetchRuntimeSecrets(authHeader, { + ...(projectId ? { projectId } : {}), + ...(environmentId ? { environmentId } : {}), + ...(chatSessionId ? { chatSessionId } : {}), + }); + const runtimeSecrets = secretsFetch.ok ? secretsFetch.secrets : null; + // ONE list, two consumers: the env bag the box receives, and the scrubber + // registry that keeps those same values out of the transcript. Deriving + // both from one fetch is what makes it impossible for the registry to be + // missing a value the box actually got. + const secretEnv = runtimeSecrets + ? toSecretEnv(runtimeSecrets) + : undefined; + const secretScrubber = runtimeSecrets + ? createSecretScrubber(runtimeSecrets) + : null; // What the ADAPTER will actually write, per its own rules (Codex rejects // a name outright — mid-`doStart`, i.e. it would fail the whole turn — so // it filters rather than throws). Every MCPJam-side skill pass below is @@ -1114,7 +1171,7 @@ export async function runHarnessTurn( : undefined; const deliveredSkills = preparedSkills?.delivered ?? []; const deliveredSkillNamesById = new Map( - deliveredSkills.map((s) => [s.skillId, s.name]) + deliveredSkills.map((s) => [s.skillId, s.name]), ); // WS3: gate side-effecting built-ins (Bash/Edit/Write) behind approval @@ -1140,6 +1197,19 @@ export async function runHarnessTurn( ...(effectiveCapabilities ? { pluginVersions: effectiveCapabilities.pluginVersions } : {}), + // ROTATION FORKS THE SESSION. A resumed harness session reattaches to a + // bridge process that already holds its environment — the exact failure + // the `ANTHROPIC_BASE_URL` compat bump above was minted for — so a + // rotated value delivered without forking would land everywhere except + // the conversation the user is sitting in. + // + // On a FETCH FAILURE the dimension is omitted rather than sent empty: + // omitted leaves the fingerprint where it was and the session resumes, + // while `""` would read as "the secrets were removed" and cold-start a + // conversation over a blip. + ...(runtimeSecrets !== null + ? { secretsHash: deliveredSecretsFingerprint(runtimeSecrets) } + : {}), }); const ownerType: HarnessOwnerRef["ownerType"] | undefined = sourceType === "scenario" @@ -1162,7 +1232,7 @@ export async function runHarnessTurn( throw new Error( "Swarm harness turn is missing continuity identity " + "(journeyRunId, hostId, and chatSessionId are all required for " + - "the swarm-chat owner lane)" + "the swarm-chat owner lane)", ); } let continuity: @@ -1226,7 +1296,7 @@ export async function runHarnessTurn( // conversation. if (claim.status === 409) { throw new Error( - "Another turn is already running for this chat — wait for it to finish." + "Another turn is already running for this chat — wait for it to finish.", ); } logger.warn("[harness] session-state claim failed; failing closed", { @@ -1236,7 +1306,7 @@ export async function runHarnessTurn( throw new Error( `Couldn't start a ${harnessAdapter.displayName} session — the ` + "continuity service is unavailable right now. Please try again in " + - "a moment." + "a moment.", ); } else { continuity = { @@ -1397,7 +1467,7 @@ export async function runHarnessTurn( .then((renewed) => { if (!renewed.ok && reservationHeld) { logger.error( - "[harness] preparation reservation was lost; aborting the turn" + "[harness] preparation reservation was lost; aborting the turn", ); livenessAbort.abort(new Error("harness box reservation lost")); } @@ -1406,7 +1476,7 @@ export async function runHarnessTurn( if (reservationHeld) { logger.error( "[harness] preparation reservation renewal failed; aborting the turn", - err + err, ); livenessAbort.abort(new Error("harness box reservation lost")); } @@ -1429,7 +1499,7 @@ export async function runHarnessTurn( // `computerWorkdir` keeps the personal path identical. Both still go // through `resolveWorkingDirectory`, so neither can escape /home/user. const resolvedHarnessWorkdir = resolveWorkingDirectory( - harnessSandboxBinding?.workdir ?? computerWorkdir + harnessSandboxBinding?.workdir ?? computerWorkdir, ); const defaultWorkingDirectory = "error" in resolvedHarnessWorkdir @@ -1441,6 +1511,17 @@ export async function runHarnessTurn( const sandbox = createE2BHarnessSandboxProvider({ sandboxId, defaultWorkingDirectory, + // The materialized secrets, as a session-wide env bag on every `run` + // and `spawn`. This is the whole of materialized delivery on the + // harness path: the agent runs `stripe customers list`, and + // `STRIPE_API_KEY` is simply in that process's environment. + // + // In `envs`, never in the command line — the rule `plugin-box.ts` + // already states: argv is readable by every process in the box through + // `/proc`, and it lands in shell history. + ...(secretEnv && Object.keys(secretEnv).length > 0 + ? { sessionEnv: secretEnv } + : {}), }); // 3b. BROKER delivery (the only credential path): the sandbox id is now @@ -1542,7 +1623,7 @@ export async function runHarnessTurn( Object.keys(hostExecutedTools).length ? { toolApproval: Object.fromEntries( - Object.keys(hostExecutedTools).map((n) => [n, "user-approval"]) + Object.keys(hostExecutedTools).map((n) => [n, "user-approval"]), ) as NonNullable< ConstructorParameters[0]["toolApproval"] >, @@ -1638,7 +1719,7 @@ export async function runHarnessTurn( ...(abortSignal ? { signal: abortSignal } : {}), }).catch(() => {}); const pluginSkills = pluginSkillDeliverySummary( - effectiveCapabilities + effectiveCapabilities, ); if (pluginSkills.length > 0) { // Provenance, not a pin: which plugin material this sandbox was @@ -1683,7 +1764,7 @@ export async function runHarnessTurn( const fileResult = await fetchRuntimeSkillFiles( authHeader, projectId, - executionScope + executionScope, ).catch(() => ({ ok: false } as const)); if (fileResult.ok) { await materializeSkillFiles({ @@ -1743,7 +1824,7 @@ export async function runHarnessTurn( if (eligibility.reason === "legacy-cold-resume") { logger.warn( "[harness] resuming a pre-detach sidecar (cold/disk resume; continuity not guaranteed)", - { harnessSessionId: continuity?.state?.harnessSessionId } + { harnessSessionId: continuity?.state?.harnessSessionId }, ); } // WS3: resuming a turn the user just approved/denied. The committed state @@ -1846,7 +1927,7 @@ export async function runHarnessTurn( }); if (elapsedMs >= HARNESS_LEASE_TTL_MS) { logger.warn( - "[harness] heartbeat lost liveness past TTL — aborting turn" + "[harness] heartbeat lost liveness past TTL — aborting turn", ); livenessAbort.abort(new Error("harness lost liveness")); } @@ -1965,7 +2046,7 @@ export async function runHarnessTurn( }); } const flushedToolCallIds = new Set( - pendingResults.map((tr) => tr.toolCallId) + pendingResults.map((tr) => tr.toolCallId), ); for (const tr of pendingResults) { messageHistory.push({ @@ -1982,7 +2063,7 @@ export async function runHarnessTurn( ? { providerOptions: mergeMcpToolOriginMetadata( undefined, - tr.serverId + tr.serverId, ), } : {}), @@ -1999,7 +2080,7 @@ export async function runHarnessTurn( messageHistory, promptIndex, stepIndex, - flushedToolCallIds + flushedToolCallIds, ); }; // Step + tool-identity tracking. A "step" spans assistant content + its @@ -2022,7 +2103,7 @@ export async function runHarnessTurn( writer, messageHistory, toolSetForTrace as unknown as ToolSet, - activeDriver.snapshotContext(messageHistory) + activeDriver.snapshotContext(messageHistory), ); stepIndex += 1; stepStartedAt = Date.now(); @@ -2069,7 +2150,7 @@ export async function runHarnessTurn( } else { if (reasoningId === undefined) { reasoningId = String( - (part as { id?: unknown }).id ?? crypto.randomUUID() + (part as { id?: unknown }).id ?? crypto.randomUUID(), ); emitReasoningStart(writer, reasoningId); } @@ -2077,7 +2158,7 @@ export async function runHarnessTurn( const rDelta = String( (part as { text?: unknown; delta?: unknown }).text ?? (part as { delta?: unknown }).delta ?? - "" + "", ); if (rDelta) emitReasoningDelta(writer, reasoningId, rDelta); } @@ -2087,7 +2168,7 @@ export async function runHarnessTurn( const delta = String( (part as { text?: unknown; delta?: unknown }).delta ?? (part as { text?: unknown }).text ?? - "" + "", ); if (!delta) continue; // Assistant text after tool results begins the next step. @@ -2130,10 +2211,10 @@ export async function runHarnessTurn( } const toolCallId = String( (part as { toolCallId?: unknown }).toolCallId ?? - crypto.randomUUID() + crypto.randomUUID(), ); const rawToolName = String( - (part as { toolName?: unknown }).toolName ?? "tool" + (part as { toolName?: unknown }).toolName ?? "tool", ); // Claude Code namespaces MCP tools as mcp____; map back // to { serverId, un-namespaced toolName } so the UI chunks, engine @@ -2142,12 +2223,12 @@ export async function runHarnessTurn( // tools (Bash, Read, …) have no prefix → serverId stays undefined. const { serverId, toolName } = harnessAdapter.parseToolName( rawToolName, - harnessKeyToServerId + harnessKeyToServerId, ); const input = coerceToolInput( (part as { input?: unknown }).input ?? (part as { args?: unknown }).args ?? - {} + {}, ); toolMeta.set(toolCallId, { ...(serverId ? { serverId } : {}), @@ -2163,7 +2244,7 @@ export async function runHarnessTurn( // auto-continues, re-submitting the turn forever. const providerMetadata = mergeMcpToolOriginMetadata( undefined, - serverId + serverId, ); writer.write({ type: "tool-input-available", @@ -2203,7 +2284,7 @@ export async function runHarnessTurn( type === "tool-output-available" ) { const toolCallId = String( - (part as { toolCallId?: unknown }).toolCallId ?? "" + (part as { toolCallId?: unknown }).toolCallId ?? "", ); // HOST-EXECUTED delivery: prefer the raw result captured at // `execute()` time over the runtime's echo, which is the model-facing @@ -2227,7 +2308,7 @@ export async function runHarnessTurn( toolMeta.get(toolCallId) ?? harnessAdapter.parseToolName( String((part as { toolName?: unknown }).toolName ?? "tool"), - harnessKeyToServerId + harnessKeyToServerId, ); // A tool call the MCP proxy blocked on policy, recognised only when // THIS run sealed a policy for that server, and only ever with the @@ -2321,7 +2402,7 @@ export async function runHarnessTurn( ...createOffsetInterval( traceBaseMs, toolStartMs.get(toolCallId) ?? Date.now(), - Date.now() + Date.now(), ), promptIndex, stepIndex, @@ -2435,15 +2516,15 @@ export async function runHarnessTurn( // for a turn that can never resume. if (!continuity) { throw new Error( - "Tool approval requested on a turn without a resumable harness session; aborting instead of pausing unresumably." + "Tool approval requested on a turn without a resumable harness session; aborting instead of pausing unresumably.", ); } const approvalId = String( (part as { approvalId?: unknown }).approvalId ?? - crypto.randomUUID() + crypto.randomUUID(), ); const toolCallId = String( - (part as { toolCallId?: unknown }).toolCallId ?? "" + (part as { toolCallId?: unknown }).toolCallId ?? "", ); closeReasoning(); if (textId !== undefined) { @@ -2563,7 +2644,7 @@ export async function runHarnessTurn( const finalTextLength = typeof finalText === "string" ? finalText.length : 0; logger.warn( - `[harness] completed without visible chat parts; streamTypes=${streamTypes}; finalTextLength=${finalTextLength}` + `[harness] completed without visible chat parts; streamTypes=${streamTypes}; finalTextLength=${finalTextLength}`, ); projectAssistantText(HARNESS_EMPTY_VISIBLE_OUTPUT_TEXT); } @@ -2587,13 +2668,11 @@ export async function runHarnessTurn( logger.info( `[harness][timing] claim=${tClaim - tStart}ms boxWake=${ tSandbox - tClaim - }ms brokerStart=${ - tBroker - tSandbox - }ms sessionConnect=${ + }ms brokerStart=${tBroker - tSandbox}ms sessionConnect=${ tConnect - tBroker }ms modelStream=${tStream - tConnect}ms total=${ tStream - tStart - }ms resumed=${resumedSession}` + }ms resumed=${resumedSession}`, ); } finally { if (heartbeatTimer) clearInterval(heartbeatTimer); @@ -2719,7 +2798,7 @@ export async function runHarnessTurn( } catch (finalizeErr) { logger.warn( "[harness] session finalize failed; releasing lease, sidecar not committed", - { error: finalizeErr } + { error: finalizeErr }, ); // stop()/destroy() threw → no resume payload to commit. Drop any // half-built commit and free the lane so the next turn can claim. @@ -2759,7 +2838,7 @@ export async function runHarnessTurn( writer, messageHistory, toolSetForTrace as unknown as ToolSet, - driver.snapshotContext(messageHistory) + driver.snapshotContext(messageHistory), ); driver.emitErrorTurnFinish(writer); } @@ -2835,7 +2914,7 @@ export async function runHarnessTurn( const persistOutcome = await onConversationComplete?.( [...messageHistory], trace, - runSucceeded ? capturedHarnessCommit : undefined + runSucceeded ? capturedHarnessCommit : undefined, ); // The callback RESOLVING is not the same as the turn being saved. Now // that it reports an outcome, a `failed`/`skipped`/`conflict` result @@ -2883,7 +2962,7 @@ export async function runHarnessTurn( } catch (cleanupError) { logger.error( "[harness] error while running stream cleanup", - cleanupError + cleanupError, ); } }; diff --git a/mcpjam-inspector/server/utils/harness/runtime-secrets.ts b/mcpjam-inspector/server/utils/harness/runtime-secrets.ts new file mode 100644 index 0000000000..e17f45f8b0 --- /dev/null +++ b/mcpjam-inspector/server/utils/harness/runtime-secrets.ts @@ -0,0 +1,124 @@ +/** + * Materialized project secrets as a runtime concern. + * + * The sibling of `runtime-skills.ts`, and shaped like it on purpose: one + * tri-state fetch, one deterministic fingerprint folded into the harness runtime + * fingerprint, and nothing else. What differs is what a mistake costs. + * + * - `fetchRuntimeSecrets` — TRI-STATE. `{ ok: false }` is NOT `[]`. A + * transient Convex failure that read as "no secrets" would silently strip a + * working session's credentials and leave the user watching a `stripe` + * command fail with no explanation. + * - `deliveredSecretsFingerprint` — folded into `harnessRuntimeFingerprint`, + * so a ROTATION forks a resumable session. This is not hygiene: the + * `ANTHROPIC_BASE_URL` compat bump in `run-harness-turn.ts` records the + * exact prior bug — "resumed sessions reconnect to a bridge process holding + * the OLD env". A rotated value that did not fork the session would be + * delivered to a bridge that already holds the old one, and the user would + * see the rotation land everywhere except the conversation they were in. + * + * Brokered secrets never appear here. Their values do not enter this process at + * all — the backend composes them into the box's egress policy — so there is + * nothing to fetch, fingerprint, or scrub. Rotating a brokered secret reaches + * new boxes only, the same "sessions created after" rule. + */ +import { + convexListSecretsForRuntimeExecution, + type RuntimeSecret, +} from "../computers/convex-secrets-client.js"; +import { logger } from "../logger.js"; + +export type { RuntimeSecret }; + +export type FetchRuntimeSecretsResult = + | { ok: true; secrets: RuntimeSecret[] } + | { ok: false }; + +/** + * Fetch the materialized secrets for this turn. Never throws, never returns `[]` + * to mean "failed". + * + * Requires an ENVIRONMENT. A turn with no environment has no grant — the + * environment IS the grant boundary — so that reports an empty success rather + * than a failure: nothing is wrong, there is simply nothing granted. Same for a + * turn with no bearer (a guest), which the backend would reject anyway. + */ +export async function fetchRuntimeSecrets( + bearer: string | undefined, + args: { projectId?: string; environmentId?: string; chatSessionId?: string }, +): Promise { + if (!bearer || !args.projectId || !args.environmentId) { + return { ok: true, secrets: [] }; + } + try { + const secrets = await convexListSecretsForRuntimeExecution(bearer, { + projectId: args.projectId, + environmentId: args.environmentId, + ...(args.chatSessionId ? { chatSessionId: args.chatSessionId } : {}), + }); + return { ok: true, secrets }; + } catch (error) { + logger.warn( + "[runtime-secrets] fetch failed; preserving prior secret state", + { error: error instanceof Error ? error.message : String(error) }, + ); + return { ok: false }; + } +} + +/** + * Deterministic fingerprint over the delivered set, order-independent. + * + * The value participates — it has to, because ROTATION is precisely "same name, + * new value" and that is the event that must fork a session — but it + * participates as a digest, never as itself. The runtime DTO carries no + * `updatedAt` to use instead (the resolver returns the minimum a delivery + * needs), so the digest is what stands in for one. + * + * Not a cryptographic claim, and not asked to be one: the only consumer is "is + * this the same runtime as last turn". FNV-1a over `name value`, and the result + * is folded into another hash by `harnessRuntimeFingerprint` before anything is + * stored — so no digest of a credential is ever persisted on its own. + * + * Empty list ⇒ `""`, so a project with no secrets hashes identically to one + * where this dimension does not exist and its sessions keep resuming. + */ +export function deliveredSecretsFingerprint( + secrets: readonly RuntimeSecret[], +): string { + if (secrets.length === 0) return ""; + const canon = secrets + .map((secret) => { + let v = 0x811c9dc5; + const material = `${secret.name} ${secret.value}`; + for (let i = 0; i < material.length; i++) { + v ^= material.charCodeAt(i); + v = Math.imul(v, 0x01000193); + } + return `${secret.name}:${(v >>> 0).toString(16)}`; + }) + .sort() + .join("\n"); + let h = 0x811c9dc5; + for (let i = 0; i < canon.length; i++) { + h ^= canon.charCodeAt(i); + h = Math.imul(h, 0x01000193); + } + return (h >>> 0).toString(16); +} + +/** + * The env bag a sandbox command should carry. + * + * Separate from the fetch so the caller holds ONE fetched list and derives both + * the bag and the scrubber registry from it. Two reads would be two chances for + * the registry to be missing a value the box actually received — which is the + * one way this feature leaks by accident. + */ +export function toSecretEnv( + secrets: readonly RuntimeSecret[], +): Record { + const env: Record = {}; + for (const secret of secrets) env[secret.name] = secret.value; + return env; +} diff --git a/mcpjam-inspector/server/utils/mcpjam-stream-handler.ts b/mcpjam-inspector/server/utils/mcpjam-stream-handler.ts index 1920dd67ad..a66636b58a 100644 --- a/mcpjam-inspector/server/utils/mcpjam-stream-handler.ts +++ b/mcpjam-inspector/server/utils/mcpjam-stream-handler.ts @@ -165,7 +165,7 @@ function isModelVisibleImageOutput(value: unknown): boolean { */ function isApprovalFreeMetaToolName( name: string, - progressivePlan: ProgressiveToolPlan | undefined + progressivePlan: ProgressiveToolPlan | undefined, ): boolean { if (!progressivePlan?.enabled) return false; return META_TOOL_NAMES.includes(name); @@ -196,7 +196,7 @@ function toolCallNeedsApproval( // by the client typecheck), so a bare `boolean` param let `undefined` flow // in and `return requireToolApproval` hand back `undefined` for a real // tool. Coerce so the return is always a real boolean. - requireToolApproval: boolean | undefined + requireToolApproval: boolean | undefined, ): boolean { if (uiToolApprovals?.requiredNames.has(name)) return true; if (uiToolApprovals?.freeNames.has(name)) return false; @@ -252,7 +252,7 @@ const STEP_LOG_THRESHOLD = 20; const GUEST_IP_HASH_HEADER = "x-mcpjam-guest-ip-hash"; function readLinkedMcpResourceWithManager( - mcpClientManager: MCPClientManager + mcpClientManager: MCPClientManager, ): (params: { serverId: string; uri: string; @@ -276,7 +276,7 @@ let warnedMissingAbortSignal = false; */ export function warnIfChatAbortSignalMissing( signal: AbortSignal | undefined, - source: string + source: string, ): void { if (signal || warnedMissingAbortSignal) return; warnedMissingAbortSignal = true; @@ -285,7 +285,7 @@ export function warnIfChatAbortSignalMissing( logger.warn( "[mcpjam-stream-handler] inbound chat request has no AbortSignal; " + "client disconnect will not cancel the agentic loop", - { source } + { source }, ); } @@ -470,10 +470,10 @@ export interface MCPJamEngineErrorEvent { export function describeBackendStreamFailure( status: number | undefined, rawText: string, - code?: string + code?: string, ): NormalizedError { const detail = new Error( - status !== undefined ? `HTTP ${status}: ${rawText}` : rawText + status !== undefined ? `HTTP ${status}: ${rawText}` : rawText, ); // Before the status branches: a body that names MCPJam settles ownership no @@ -511,10 +511,10 @@ export function describeBackendStreamFailure( export function describeStreamErrorChunkFailure( status: number | undefined, rawText: string, - code?: string + code?: string, ): NormalizedError { const detail = new Error( - status !== undefined ? `HTTP ${status}: ${rawText}` : rawText + status !== undefined ? `HTTP ${status}: ${rawText}` : rawText, ); if (isMcpjamOwnedFailureCode(code)) { @@ -527,7 +527,7 @@ export function describeStreamErrorChunkFailure( /** Status → slug, carrying the catalog's own origin. Shared by both paths. */ function backendFailureSlug( status: number | undefined, - detail: Error + detail: Error, ): NormalizedError { if (status === 401 || status === 403) { return describeAsSlug("provider/auth_error", detail); @@ -635,6 +635,31 @@ export interface MCPJamHandlerOptions { * launch re-resolves the environment, so a recorded version is provenance. */ effectiveCapabilities?: EffectiveCapabilitySet; + /** + * The Project Environment this turn resolved — the GRANT BOUNDARY for project + * secrets, and the ONLY thing the harness turn needs to fetch them. + * + * An id, never a resolved spec carrying values: the resolved-environment + * types are read by previews, logs and telemetry, and a credential on one of + * them would be a credential in all three. The harness turn calls Convex with + * the end user's own bearer, so the backend — not this process — decides + * which of this environment's secrets that user's session receives. + * + * Absent ⇒ no grant. Normal, not a failure. + */ + environmentId?: string; + /** + * This turn's MATERIALIZED project secrets, already resolved by the caller. + * + * PRESENCE IS SEMANTIC, exactly like `runtimeSkillsOverride`: supplied — even + * EMPTY — means "already resolved, do not fetch again". `web-chat-turn` + * resolves them once because two consumers need the same list (the sandbox's + * env bag and the transcript scrubber) and a second fetch would open a window + * where the scrubber is missing a value the box already has. A harness turn + * reached from a caller that does not resolve them (the eval/swarm driver) + * fetches for itself. + */ + runtimeSecrets?: { name: string; value: string }[]; /** * Phase 3 execution scope from the server-resolved runtime config (scenario OR * host-by-id). Threaded into the harness path (sandbox reserve, runtime skills, @@ -747,7 +772,7 @@ export interface MCPJamHandlerOptions { turnTrace: PersistedTurnTrace, // §3: present only for chat-backed harness turns — the resume-state commit // to apply atomically with the transcript via /ingest-chat. - harnessSessionCommit?: HarnessSessionCommitPayload + harnessSessionCommit?: HarnessSessionCommitPayload, ) => Promise | void | PersistChatOutcome; onStreamComplete?: () => Promise | void; onStreamWriterReady?: (writer: { @@ -1003,7 +1028,7 @@ function collectUsedToolCallIds(messages: ModelMessage[]): Set { function hasUnresolvedClientFulfilledToolCalls( messages: ModelMessage[], - tools: ToolSet + tools: ToolSet, ): boolean { const resultIds = new Set(); for (const msg of messages) { @@ -1041,7 +1066,7 @@ function hasUnresolvedClientFulfilledToolCalls( function generateUniqueToolCallId( usedToolCallIds: Set, - prefix = "tc" + prefix = "tc", ): string { const MAX_ATTEMPTS = 100; for (let i = 0; i < MAX_ATTEMPTS; i++) { @@ -1059,7 +1084,7 @@ function generateUniqueToolCallId( function createToolCallIdNormalizer( usedToolCallIds: Set, - stepIndex: number + stepIndex: number, ): (rawToolCallId?: string) => string { const perStepMap = new Map(); let collisionCounter = 0; @@ -1088,7 +1113,7 @@ function createToolCallIdNormalizer( function getPromptAssistantStepBaseIndex( messageHistory: ModelMessage[], - promptMessageStartIndex: number + promptMessageStartIndex: number, ): number { let assistantCount = 0; for ( @@ -1104,7 +1129,7 @@ function getPromptAssistantStepBaseIndex( } function readUsageFromFinishChunk( - finishChunk: UIMessageChunk | null + finishChunk: UIMessageChunk | null, ): LiveChatTraceUsage | undefined { if (!finishChunk || finishChunk.type !== "finish") { return undefined; @@ -1150,7 +1175,7 @@ function readUsageFromFinishChunk( * capture never fabricates one. */ function readFinishReasonFromChunk( - finishChunk: UIMessageChunk | null + finishChunk: UIMessageChunk | null, ): string | undefined { type FinishUIMessageChunk = Extract; const source = finishChunk as Partial | null; @@ -1160,7 +1185,7 @@ function readFinishReasonFromChunk( function createClientFinishChunk( finishChunk: UIMessageChunk | null, traceTurn: LiveTraceTurnContext | null, - fallbackReason: "length" | "stop" + fallbackReason: "length" | "stop", ): UIMessageChunk { type FinishUIMessageChunk = Extract; const source = finishChunk as Partial | null; @@ -1192,7 +1217,7 @@ function setStepSpanMessageRanges( promptIndex: number, stepIndex: number, messageStartIndex: number | undefined, - messageEndIndex: number | undefined + messageEndIndex: number | undefined, ): void { if ( typeof messageStartIndex !== "number" || @@ -1260,7 +1285,7 @@ function scrubMessagesForBackend( tools: ToolSet, mcpClientManager: MCPClientManager, selectedServers?: string[], - preserveReasoningFromIndex?: number + preserveReasoningFromIndex?: number, ): ModelMessage[] { let pruned: ModelMessage[]; if ( @@ -1291,7 +1316,7 @@ function scrubMessagesForBackend( const assistantMsg = msg as AssistantModelMessage; if (!Array.isArray(assistantMsg.content)) return msg; const filtered = assistantMsg.content.filter( - (part) => part.type !== "tool-approval-request" + (part) => part.type !== "tool-approval-request", ); if (filtered.length === assistantMsg.content.length) return msg; return { ...msg, content: filtered } as ModelMessage; @@ -1300,7 +1325,7 @@ function scrubMessagesForBackend( if (msg.role === "tool") { const toolMsg = msg as ToolModelMessage; const filtered = toolMsg.content.filter( - (part) => part.type !== "tool-approval-response" + (part) => part.type !== "tool-approval-response", ); if (filtered.length === toolMsg.content.length) return msg; return { ...msg, content: filtered } as ModelMessage; @@ -1311,28 +1336,28 @@ function scrubMessagesForBackend( const withoutUnavailableToolHistory = scrubUnavailableToolHistoryForBackend( stripped, - Object.keys(tools as Record) + Object.keys(tools as Record), ); const scrubbed = scrubChatGPTAppsToolResultsForBackend( scrubMcpAppsToolResultsForBackend( withoutUnavailableToolHistory, mcpClientManager, - selectedServers + selectedServers, ), mcpClientManager, - selectedServers + selectedServers, ); return normalizeModelMessagesForConvex(scrubbed); } function safelyEmitLiveTextDelta( onLiveTextDelta: ((delta: string) => void) | undefined, - delta: string + delta: string, ) { if (!onLiveTextDelta) return; safelyInvoke("[mcpjam-stream-handler] onLiveTextDelta", () => - onLiveTextDelta(delta) + onLiveTextDelta(delta), ); } @@ -1474,7 +1499,7 @@ function attachedFailureCode(error: unknown): string | undefined { */ function parseEngineErrorBody( status: number | undefined, - bodyText: string + bodyText: string, ): { message: string; code?: string; details?: string } { let code: string | undefined; try { @@ -1515,11 +1540,11 @@ function parseEngineErrorBody( */ function safelyEmitEngineError( onEngineError: ((event: MCPJamEngineErrorEvent) => void) | undefined, - event: MCPJamEngineErrorEvent + event: MCPJamEngineErrorEvent, ) { if (!onEngineError) return; safelyInvoke("[mcpjam-stream-handler] onEngineError", () => - onEngineError(event) + onEngineError(event), ); } @@ -1542,7 +1567,7 @@ async function processStream( // supplied. Chat / synthetic omit (handler still writes the UI // chunk + trace event unchanged). onToolCall?: (event: MCPJamToolCallEvent) => void, - uiToolApprovals?: UiToolApprovalClassification + uiToolApprovals?: UiToolApprovalClassification, ): Promise { const contentParts: PersistedAssistantPart[] = []; let pendingText = ""; @@ -1621,7 +1646,7 @@ async function processStream( "message" in parseErr && typeof (parseErr as { message?: unknown }).message === "string" ? (parseErr as { message: string }).message - : "stream parse failed" + : "stream parse failed", ); } @@ -1720,7 +1745,7 @@ async function processStream( const serverIdForToolCall = readToolServerId(tools, chunk.toolName); const providerMetadata = mergeMcpToolOriginMetadata( chunk.providerMetadata, - serverIdForToolCall + serverIdForToolCall, ); contentParts.push({ type: "tool-call", @@ -1763,7 +1788,7 @@ async function processStream( "[mcpjam-stream-handler] onToolCall callback failed", { error: error instanceof Error ? error.message : String(error), - } + }, ); } } @@ -1773,7 +1798,7 @@ async function processStream( chunk.toolName, progressivePlan, uiToolApprovals, - requireToolApproval + requireToolApproval, ) ) { emitToolApprovalRequest(writer, { @@ -1829,7 +1854,7 @@ async function processStream( const normalized = describeStreamErrorChunkFailure( parsed.statusCode, errorText, - parsed.code + parsed.code, ); throw Object.assign(new Error(parsed.message), { normalized, @@ -1876,7 +1901,7 @@ async function emitToolResults( // synthetic don't supply this callback — the UI writer + trace event // still fire unchanged. PR 14: a returned promise is awaited so the // eval render hook completes before the engine's next step. - onToolResult?: (event: MCPJamToolResultEvent) => void | Promise + onToolResult?: (event: MCPJamToolResultEvent) => void | Promise, ): Promise { for (const msg of newMessages) { if (msg?.role === "tool") { @@ -1978,7 +2003,7 @@ async function emitToolResults( { error: error instanceof Error ? error.message : String(error), - } + }, ); } } @@ -2006,7 +2031,7 @@ function emitInheritedToolCalls( tools?: ToolSet, traceTurn?: LiveTraceTurnContext, stepIndex?: number, - onToolCall?: (event: MCPJamToolCallEvent) => void + onToolCall?: (event: MCPJamToolCallEvent) => void, ) { // Collect existing tool result IDs const existingResultIds = new Set(); @@ -2060,7 +2085,7 @@ function emitInheritedToolCalls( "[mcpjam-stream-handler] onToolCall callback failed (inherited)", { error: error instanceof Error ? error.message : String(error), - } + }, ); } } @@ -2092,7 +2117,7 @@ async function handlePendingApprovals( // PR 5b-pre review fix (Cursor Medium): resumed-approval branch // emits `tool-input-available` UI chunks — `onToolCall` must fire // here too so PR 5b's wiring doesn't see orphan `tool_result`. - onToolCall?: (event: MCPJamToolCallEvent) => void + onToolCall?: (event: MCPJamToolCallEvent) => void, ): Promise { // Build approvalId → toolCallId map, toolCallId → toolName map, // and toolCallId → assistant message index map from assistant messages @@ -2214,7 +2239,7 @@ async function handlePendingApprovals( "[mcpjam-stream-handler] onToolResult callback failed (denial path)", { error: error instanceof Error ? error.message : String(error), - } + }, ); } } @@ -2256,7 +2281,7 @@ async function handlePendingApprovals( // executeToolCallsFromMessages skips tool-call IDs that already have results // (via existingToolResultIds), so the denied results prevent double-execution. const needsExecution = [...approvedToolCallIds].some( - (id) => !existingResultIds.has(id) + (id) => !existingResultIds.has(id), ); if (needsExecution) { @@ -2302,7 +2327,7 @@ async function handlePendingApprovals( "[mcpjam-stream-handler] onToolCall callback failed (approval)", { error: error instanceof Error ? error.message : String(error), - } + }, ); } } @@ -2331,7 +2356,7 @@ async function handlePendingApprovals( newMessages, traceTurn, stepIndex, - onToolResult + onToolResult, ); didHandle = true; } @@ -2344,7 +2369,7 @@ async function handlePendingApprovals( * Calls Convex, streams the response, and executes tools if needed. */ async function processOneStep( - ctx: StepContext + ctx: StepContext, ): Promise<{ shouldContinue: boolean; didEmitFinish: boolean }> { const { writer, @@ -2397,10 +2422,10 @@ async function processOneStep( ? (() => { const activeNames = resolveActiveToolNames( progressivePlan, - discoveryState + discoveryState, ); const cataloged = new Set( - progressivePlan.catalog.map((entry) => entry.modelName) + progressivePlan.catalog.map((entry) => entry.modelName), ); const seen = new Set(activeNames); for (const def of toolDefs) { @@ -2430,7 +2455,7 @@ async function processOneStep( prepareAdvertisedTools, onWarn: (message, meta) => logger.warn(`[mcpjam-stream-handler] ${message}`, meta), - }) + }), ); activeToolDefs = activeToolDefs.filter((def) => advertised.has(def.name)); } @@ -2461,12 +2486,12 @@ async function processOneStep( tools, mcpClientManager, selectedServers, - traceTurn.promptMessageStartIndex + traceTurn.promptMessageStartIndex, ); const normalizeToolCallId = createToolCallIdNormalizer( usedToolCallIds, - stepIndex + stepIndex, ); // The trace payload must reflect the *advertised* subset — `activeToolDefs` @@ -2480,7 +2505,7 @@ async function processOneStep( const t = (tools as Record)[def.name]; return t === undefined ? null : [def.name, t]; }) - .filter((pair): pair is [string, unknown] => pair !== null) + .filter((pair): pair is [string, unknown] => pair !== null), ) as ToolSet; emitRequestPayload(writer, { @@ -2599,7 +2624,7 @@ async function processOneStep( ? traceTurn.promptMessageStartIndex : undefined, messageEndIndex: stepMessageEndIndex, - } + }, ); setStepSpanMessageRanges( traceTurn.turnSpans, @@ -2608,7 +2633,7 @@ async function processOneStep( stepMessageEndIndex != null ? traceTurn.promptMessageStartIndex : undefined, - stepMessageEndIndex + stepMessageEndIndex, ); emitTraceSnapshot(writer, messageHistory, tools, traceTurn); writeTraceEvent(writer, { @@ -2637,7 +2662,7 @@ async function processOneStep( const normalized = describeBackendStreamFailure( res.status, errorText, - parsed.code + parsed.code, ); // `isJsonDenial` proves only that the body was JSON — NOT that it was the // documented `{ok:false, code:"..."}` refusal, and "has any code at all" @@ -2714,12 +2739,12 @@ async function processOneStep( abortSignal, progressivePlan, onToolCall, - uiToolApprovals + uiToolApprovals, ); const llmEndAbs = Date.now(); traceTurn.turnUsage = mergeLiveChatTraceUsage( traceTurn.turnUsage, - readUsageFromFinishChunk(finishChunk) + readUsageFromFinishChunk(finishChunk), ); // Update message history with assistant response @@ -2780,7 +2805,7 @@ async function processOneStep( part.toolName, progressivePlan, uiToolApprovals, - requireToolApproval + requireToolApproval, ) ) { return true; @@ -2817,7 +2842,7 @@ async function processOneStep( part.toolName, progressivePlan, uiToolApprovals, - requireToolApproval + requireToolApproval, ) ) { continue; @@ -2839,7 +2864,7 @@ async function processOneStep( if (deniedByAssistantIdx.size > 0) { const denialMessages: ModelMessage[] = []; const sortedKeys = [...deniedByAssistantIdx.keys()].sort( - (a, b) => b - a + (a, b) => b - a, ); for (const idx of sortedKeys) { const denialContent = deniedByAssistantIdx.get(idx)!; @@ -2856,7 +2881,7 @@ async function processOneStep( denialMessages, traceTurn, stepIndex, - onToolResult + onToolResult, ); } // Fall through to the normal tool-execution branch below so @@ -2879,7 +2904,7 @@ async function processOneStep( promptIndex: traceTurn.promptIndex, stepIndex, spans: traceTurn.turnSpans, - } + }, ); const metaMessages = await executeToolCallsFromMessages(messageHistory, { tools: metaTracedTools as Record, @@ -2896,7 +2921,7 @@ async function processOneStep( metaMessages, traceTurn, stepIndex, - onToolResult + onToolResult, ); // Promote any ids the model just loaded so a subsequent // resumed-after-approval step sees them as loaded. @@ -2922,14 +2947,14 @@ async function processOneStep( messageEndIndex: stepMessageEndIndex, status: "ok", ...harnessSpanMeta, - } + }, ); setStepSpanMessageRanges( traceTurn.turnSpans, traceTurn.promptIndex, stepIndex, stepMessageStartIndex, - stepMessageEndIndex + stepMessageEndIndex, ); emitTraceSnapshot(writer, messageHistory, tools, traceTurn); if (finishChunk) { @@ -2946,7 +2971,7 @@ async function processOneStep( tools, traceTurn, stepIndex, - onToolCall + onToolCall, ); const toolsStartAbs = Date.now(); @@ -2958,7 +2983,7 @@ async function processOneStep( promptIndex: traceTurn.promptIndex, stepIndex, spans: traceTurn.turnSpans, - } + }, ); // Progressive mode: gate execution to the active subset. Visibility @@ -2969,7 +2994,7 @@ async function processOneStep( let executableTools = gateToolsToActiveSubset( tracedTools as Record, progressivePlan, - () => discoveryState + () => discoveryState, ); // advertise = ENFORCE: when prepareAdvertisedTools narrowed the advertised // set (`activeToolDefs`), gate execution to it too so a remembered / @@ -2979,7 +3004,7 @@ async function processOneStep( const advertised = new Set(activeToolDefs.map((def) => def.name)); executableTools = gateToolsToAdvertisedSubset( executableTools, - () => advertised + () => advertised, ); } @@ -3020,7 +3045,7 @@ async function processOneStep( messageHistory, traceTurn.promptIndex, stepIndex, - newToolCallIds + newToolCallIds, ); const stepMessageEndIndexAfterTools = messageHistory.length > traceTurn.promptMessageStartIndex @@ -3052,14 +3077,14 @@ async function processOneStep( messageEndIndex: stepMessageEndIndexAfterTools, status: "ok", ...harnessSpanMeta, - } + }, ); setStepSpanMessageRanges( traceTurn.turnSpans, traceTurn.promptIndex, stepIndex, stepMessageStartIndexAfterTools, - stepMessageEndIndexAfterTools + stepMessageEndIndexAfterTools, ); // Emit results for newly executed tools @@ -3069,7 +3094,7 @@ async function processOneStep( newMessages, traceTurn, stepIndex, - onToolResult + onToolResult, ); emitTraceSnapshot(writer, messageHistory, tools, traceTurn); @@ -3136,14 +3161,14 @@ async function processOneStep( messageStartIndex: stepMessageStartIndex, messageEndIndex: stepMessageEndIndex, pushAggregateSpan: false, - } + }, ); setStepSpanMessageRanges( traceTurn.turnSpans, traceTurn.promptIndex, stepIndex, stepMessageStartIndex, - stepMessageEndIndex + stepMessageEndIndex, ); emitTraceSnapshot(writer, messageHistory, tools, traceTurn); @@ -3217,14 +3242,14 @@ async function processOneStep( messageEndIndex: stepMessageEndIndex, status: "ok", ...harnessSpanMeta, - } + }, ); setStepSpanMessageRanges( traceTurn.turnSpans, traceTurn.promptIndex, stepIndex, stepMessageStartIndex, - stepMessageEndIndex + stepMessageEndIndex, ); emitTraceSnapshot(writer, messageHistory, tools, traceTurn); @@ -3284,7 +3309,7 @@ export interface ChatEngineLoopResult { */ export async function runChatEngineLoop( options: MCPJamHandlerOptions, - streamSink: "ui" | "none" + streamSink: "ui" | "none", ): Promise { const { messages, @@ -3335,7 +3360,7 @@ export async function runChatEngineLoop( // that have no request context. Later failures in the same turn still get // classified (capture-deduped) and keep their free-form rows. const failureReporter = oncePerTurn( - failureReporterOption ?? createSystemStreamFailureReporter("chat-engine") + failureReporterOption ?? createSystemStreamFailureReporter("chat-engine"), ); const resolvedEndpointPath = endpointPath ?? "/stream"; const resolvedMaxSteps = @@ -3379,7 +3404,7 @@ export async function runChatEngineLoop( ) { const id = lookupToolIdByModelName( progressivePlan.catalog, - part.toolName + part.toolName, ); if (id) discoveryState.pendingApprovalToolIds.add(id); } @@ -3408,7 +3433,7 @@ export async function runChatEngineLoop( }); const promptStepBaseIndex = getPromptAssistantStepBaseIndex( messageHistory, - traceTurn.promptMessageStartIndex + traceTurn.promptMessageStartIndex, ); let steps = 0; let runSucceeded = false; @@ -3466,7 +3491,7 @@ export async function runChatEngineLoop( writeError instanceof Error ? writeError.message : String(writeError), - } + }, ); } } @@ -3553,7 +3578,7 @@ export async function runChatEngineLoop( abortSignal, modelVisibleMcpToolResults, onToolResult, - onToolCall + onToolCall, ); if (handled) { // Approvals were processed — if there are still unresolved tool @@ -3584,18 +3609,18 @@ export async function runChatEngineLoop( // Pause and let the client reconcile. logger.warn( "[mcpjam-stream-handler] MRTR resume: toolCallId is not an unresolved tool-call; skipping resume", - { toolCallId: operationResume.toolCallId } + { toolCallId: operationResume.toolCallId }, ); mrtrPaused = true; } else if (operationResume && !aborted) { const resolution = await operationResume.resolve((chunk) => - safeWriter.write(chunk) + safeWriter.write(chunk), ); if (resolution.kind === "complete" || resolution.kind === "recover") { const spliced = spliceMrtrToolResult( messageHistory, operationResume.toolCallId, - resolution.toolResultMessage + resolution.toolResultMessage, ); if (spliced) { await emitToolResults( @@ -3604,7 +3629,7 @@ export async function runChatEngineLoop( [resolution.toolResultMessage], traceTurn, effectiveSteps(), - onToolResult + onToolResult, ); emitTraceSnapshot(safeWriter, messageHistory, tools, traceTurn); // Only run the model once EVERY tool-call in the resent history has @@ -3625,7 +3650,7 @@ export async function runChatEngineLoop( // reconcile. logger.warn( "[mcpjam-stream-handler] MRTR resume: suspended tool-call not found in history; pausing", - { toolCallId: operationResume.toolCallId } + { toolCallId: operationResume.toolCallId }, ); mrtrPaused = true; } @@ -3703,7 +3728,7 @@ export async function runChatEngineLoop( driver.usage = traceTurn.turnUsage; driver.fireStepFinish( effectiveSteps() - 1, - !didEmitFinish && !shouldContinue + !didEmitFinish && !shouldContinue, ); if (!shouldContinue) { @@ -3742,8 +3767,8 @@ export async function runChatEngineLoop( createClientFinishChunk( null, traceTurn, - hitStepCap() ? "length" : "stop" - ) + hitStepCap() ? "length" : "stop", + ), ); finishEmitted = true; } @@ -3793,7 +3818,7 @@ export async function runChatEngineLoop( traceTurn.turnStartedAt, traceTurn.turnStartedAt, failAbs, - traceTurn.promptIndex + traceTurn.promptIndex, ); emitTraceSnapshot(safeWriter, messageHistory, tools, traceTurn); writeTraceEvent(safeWriter, { @@ -3853,7 +3878,7 @@ export async function runChatEngineLoop( try { const persistOutcome = await onConversationComplete?.( [...messageHistory], - trace + trace, ); // Costs no latency: `onConversationComplete` already awaited the // ingest, which is what gates this stream's close in the first place. @@ -3866,7 +3891,7 @@ export async function runChatEngineLoop( } catch (persistenceError) { logger.error( "[mcpjam-stream-handler] Error while persisting conversation", - persistenceError + persistenceError, ); // A thrown persist is still an answer the client deserves. Without // this the stream closes silent and the client waits out its whole @@ -3880,7 +3905,7 @@ export async function runChatEngineLoop( ...(capturedTurnTrace ? { turnId: capturedTurnTrace.turnId } : {}), - } + }, ); } } @@ -3891,7 +3916,7 @@ export async function runChatEngineLoop( } catch (cleanupError) { logger.error( "[mcpjam-stream-handler] Error while running stream cleanup", - cleanupError + cleanupError, ); } } @@ -3967,7 +3992,7 @@ export async function runChatEngineLoop( * and `extraBodyFields: { providerKey }` without modification. */ export async function handleMCPJamFreeChatModel( - options: MCPJamHandlerOptions + options: MCPJamHandlerOptions, ): Promise { // A host with a `harness` selected (claude-code | codex) runs the real runtime // via runHarnessTurn; otherwise the emulated engine. `harness` is already a @@ -3982,7 +4007,7 @@ export async function handleMCPJamFreeChatModel( throw new Error( `${ useHarness ? "runHarnessTurn" : "runChatEngineLoop" - }(streamSink: 'ui') returned no Response — internal invariant violated` + }(streamSink: 'ui') returned no Response — internal invariant violated`, ); } return result.response; diff --git a/mcpjam-inspector/server/utils/secrets/__tests__/secret-scrubber.test.ts b/mcpjam-inspector/server/utils/secrets/__tests__/secret-scrubber.test.ts new file mode 100644 index 0000000000..d1c6aefb15 --- /dev/null +++ b/mcpjam-inspector/server/utils/secrets/__tests__/secret-scrubber.test.ts @@ -0,0 +1,157 @@ +/** + * The materialized-secret scrubber. + * + * Two things are being pinned, and they pull in opposite directions: + * - a REGISTERED value must not survive anywhere in a payload, in any of the + * forms it can take after serialization; + * - an UNREGISTERED string must come back byte-identical, because tool + * payloads on this surface are raw by design and a transcript that quietly + * rewrote a tool's output would be worse than one carrying a value. + */ +import { describe, expect, it } from "vitest"; +import { + createSecretScrubber, + MIN_SCRUBBABLE_LENGTH, +} from "../secret-scrubber"; + +const STRIPE = { name: "STRIPE_API_KEY", value: "sk_live_51H8xQ2abcdef" }; +const GH = { name: "GH_TOKEN", value: "ghp_0123456789abcdef" }; + +describe("createSecretScrubber", () => { + it("returns null when there is nothing worth scrubbing", () => { + // `null`, not a no-op object: the call sites read `scrubber ? … : x`, so the + // common no-secrets path does no work and is visible as doing none. + expect(createSecretScrubber([])).toBeNull(); + expect( + createSecretScrubber([{ name: "PIN", value: "1234" }]), + "a value under the length floor must not be registered", + ).toBeNull(); + }); + + it("does not register a short value, because the collateral is worse", () => { + // Replacing every occurrence of a 4-character value would corrupt unrelated + // text throughout the transcript. + const short = "a".repeat(MIN_SCRUBBABLE_LENGTH - 1); + const long = "b".repeat(MIN_SCRUBBABLE_LENGTH); + const scrubber = createSecretScrubber([ + { name: "SHORT", value: short }, + { name: "LONG", value: long }, + ]); + expect(scrubber?.size).toBe(1); + expect(scrubber!.scrubString(`${short} ${long}`)).toBe( + `${short} [secret:LONG]`, + ); + }); +}); + +describe("scrubString", () => { + it("replaces every occurrence, not just the first", () => { + const scrubber = createSecretScrubber([STRIPE])!; + expect( + scrubber.scrubString( + `export A=${STRIPE.value}\nexport B=${STRIPE.value}`, + ), + ).toBe( + "export A=[secret:STRIPE_API_KEY]\nexport B=[secret:STRIPE_API_KEY]", + ); + }); + + it("finds the value inside a JSON-serialized string too", () => { + // A tool that returns its own config as a JSON string, or any payload + // scrubbed after `JSON.stringify`. A value carrying a quote or a newline + // looks nothing like itself once escaped. + const awkward = { name: "PEM_KEY", value: '-----BEGIN\n"key"\\here-----' }; + const scrubber = createSecretScrubber([awkward])!; + const serialized = JSON.stringify({ env: { PEM_KEY: awkward.value } }); + expect(serialized).toContain("\\n"); + const scrubbed = scrubber.scrubString(serialized); + expect(scrubbed).not.toContain("BEGIN"); + expect(JSON.parse(scrubbed)).toEqual({ + env: { PEM_KEY: "[secret:PEM_KEY]" }, + }); + }); + + it("leaves unregistered text byte-identical", () => { + const scrubber = createSecretScrubber([STRIPE])!; + const untouched = + "sk_live_somethingelse and $& and ${} and [secret:NOT_REAL]"; + expect(scrubber.scrubString(untouched)).toBe(untouched); + }); + + it("does not let a value containing $& corrupt the replacement", () => { + // `String.replace` with a string pattern expands `$&` in the replacement. + // A credential that happens to contain it would be re-expanded back into + // the output — which is why this uses split/join. + const tricky = { name: "WEIRD", value: "abc$&def$1ghi" }; + const scrubber = createSecretScrubber([tricky])!; + expect(scrubber.scrubString(`v=${tricky.value}`)).toBe("v=[secret:WEIRD]"); + }); + + it("replaces the LONGER of two overlapping secrets first", () => { + // Otherwise the shorter replacement runs first and leaves the longer value + // partially intact in the transcript. + const inner = { name: "INNER", value: "0123456789abcdef" }; + const outer = { name: "OUTER", value: "Bearer 0123456789abcdef" }; + const scrubber = createSecretScrubber([inner, outer])!; + expect(scrubber.scrubString(`auth: ${outer.value}`)).toBe( + "auth: [secret:OUTER]", + ); + expect(scrubber.scrubString(`raw: ${inner.value}`)).toBe( + "raw: [secret:INNER]", + ); + }); +}); + +describe("scrubDeep", () => { + it("reaches string leaves at any depth, in objects and arrays alike", () => { + const scrubber = createSecretScrubber([STRIPE, GH])!; + const payload = { + toolName: "bash", + output: { + stdout: [`STRIPE_API_KEY=${STRIPE.value}`, "PATH=/usr/bin"], + nested: { deep: { token: GH.value } }, + }, + count: 2, + ok: true, + nothing: null, + }; + expect(scrubber.scrubDeep(payload)).toEqual({ + toolName: "bash", + output: { + stdout: ["STRIPE_API_KEY=[secret:STRIPE_API_KEY]", "PATH=/usr/bin"], + nested: { deep: { token: "[secret:GH_TOKEN]" } }, + }, + count: 2, + ok: true, + nothing: null, + }); + }); + + it("does not rewrite object KEYS", () => { + // A key is a field name, not a payload. Rewriting one would reshape a + // structure the caller then cannot address. + const scrubber = createSecretScrubber([STRIPE])!; + const out = scrubber.scrubDeep({ [STRIPE.value]: "value" }) as Record< + string, + string + >; + expect(Object.keys(out)).toEqual([STRIPE.value]); + }); + + it("passes non-plain objects through by identity", () => { + // Rebuilding a Date or a typed array as a plain object would corrupt the + // payload far more than a missed scrub would. + const scrubber = createSecretScrubber([STRIPE])!; + const date = new Date(0); + const bytes = new Uint8Array([1, 2, 3]); + const out = scrubber.scrubDeep({ date, bytes }); + expect(out.date).toBe(date); + expect(out.bytes).toBe(bytes); + }); + + it("leaves a payload with no registered value structurally identical", () => { + const scrubber = createSecretScrubber([STRIPE])!; + const payload = { a: ["x", { b: "y" }], n: 1 }; + expect(scrubber.scrubDeep(payload)).toEqual(payload); + }); +}); diff --git a/mcpjam-inspector/server/utils/secrets/secret-scrubber.ts b/mcpjam-inspector/server/utils/secrets/secret-scrubber.ts new file mode 100644 index 0000000000..9a38380fec --- /dev/null +++ b/mcpjam-inspector/server/utils/secrets/secret-scrubber.ts @@ -0,0 +1,152 @@ +/** + * Keeping a MATERIALIZED secret's value out of the transcript. + * + * ## Why the existing redactor is not enough + * + * `log-scrubber.ts` redacts by KEY NAME (`authorization`, `api_key`, …) and by + * VALUE SHAPE (`sk-…`, `Bearer …`). Both are pattern guesses, and a project + * secret is by definition a value we KNOW — so guessing is the wrong tool. + * + * More importantly, chat-session tool payloads are UNREDACTED BY DESIGN. The + * header of `chat-session-payloads.ts` says so plainly: an agent debugging its + * own MCP server needs the arguments it sent and the result it got back, and a + * prose summary is not the deliverable. That is right, and it is exactly why + * materialized delivery needs this: the moment a real credential is an + * environment variable inside the box, `env`, a shell echo, or a tool that + * reflects its own configuration will put it into a payload that is then + * persisted verbatim, forever. + * + * ## What this does, and what it does not + * + * It replaces EXACT KNOWN VALUES — the `{name, value}` pairs this turn actually + * fetched, already in memory, costing no extra decrypt — with `[secret:NAME]`. + * It is not a heuristic and does not try to be: an unregistered string is never + * touched, so the payload surface stays as honest as it was. + * + * It is also a SECOND line of defence, not the first. The first is brokered + * delivery, where the value never enters the box at all. Materialized delivery + * is extractable by design — a determined agent can base64 the value, split it + * across two tool calls, or paste it into a file it then reads back — and no + * post-hoc scrubber can fix that. What this fixes is the ACCIDENTAL case, which + * is overwhelmingly the common one: a command that echoes its environment, a + * client that logs its own headers, a stack trace carrying a connection string. + * + * Brokered values never reach this process at all, so there is nothing here for + * them to miss. + */ + +/** One registered value, and the name it is replaced by. */ +export type SecretRegistryEntry = { name: string; value: string }; + +/** + * Values shorter than this are NOT registered. + * + * A short secret is not a secret worth this trade: replacing every occurrence + * of, say, a four-character value would corrupt unrelated text throughout the + * transcript — a tool result mentioning `test` would come back as + * `[secret:MY_KEY]` — and a transcript that lies about what a tool returned is + * worse than one carrying a low-entropy value the user chose to materialize. + * The threshold is the same order as the shortest credential any real API + * issues. + */ +export const MIN_SCRUBBABLE_LENGTH = 8; + +export type SecretScrubber = { + /** Replace every registered value inside one string. */ + scrubString(input: string): string; + /** + * Replace every registered value in the STRING LEAVES of a JSON-ish value. + * Arrays and objects are rebuilt; non-string leaves pass through untouched. + */ + scrubDeep(value: T): T; + /** How many values are registered — for tests and diagnostics only. */ + readonly size: number; +}; + +function replacementFor(name: string): string { + return `[secret:${name}]`; +} + +/** + * Build a scrubber, or `null` when there is nothing to scrub. + * + * `null` rather than a no-op object so every call site is forced to write + * `scrubber ? scrubber.scrubDeep(x) : x` — which costs nothing on the + * overwhelmingly common path where a session has no materialized secrets, and + * makes "this turn has secrets" visible in the code rather than hidden inside a + * function that usually does nothing. + */ +export function createSecretScrubber( + secrets: readonly SecretRegistryEntry[], +): SecretScrubber | null { + // LONGEST FIRST. If two secrets overlap — one value a prefix or substring of + // another, which happens when a token and a `Bearer ` form are both + // registered — replacing the shorter one first would leave the longer one + // partially rewritten and therefore partially INTACT in the transcript. + const entries = secrets + .filter((entry) => entry.value.length >= MIN_SCRUBBABLE_LENGTH) + .slice() + .sort((a, b) => b.value.length - a.value.length); + if (entries.length === 0) return null; + + // Each secret contributes two search forms: + // 1. the RAW value, which is what appears in a live response object; + // 2. its JSON-ESCAPED body, which is what appears once the value has been + // serialized into a string — a tool that returns its config as a JSON + // string, or any payload we scrub after `JSON.stringify`. A value + // containing a quote, a backslash or a newline looks nothing like itself + // in that form, and searching only for the raw text would sail past it. + const needles: { search: string; replace: string }[] = []; + for (const entry of entries) { + const replace = replacementFor(entry.name); + needles.push({ search: entry.value, replace }); + const escaped = JSON.stringify(entry.value).slice(1, -1); + if (escaped !== entry.value) { + needles.push({ search: escaped, replace }); + } + } + + function scrubString(input: string): string { + let out = input; + for (const needle of needles) { + // `split`/`join` rather than `replace`: a `String.replace` with a string + // pattern replaces only the FIRST occurrence, and its replacement string + // expands `$&` / `$1` patterns — so a credential containing `$&` would be + // re-expanded into the output. Neither trap applies here. + if (out.includes(needle.search)) { + out = out.split(needle.search).join(needle.replace); + } + } + return out; + } + + function scrubDeep(value: T): T { + if (typeof value === "string") { + return scrubString(value) as unknown as T; + } + if (Array.isArray(value)) { + return value.map((item) => scrubDeep(item)) as unknown as T; + } + if (value && typeof value === "object") { + // Preserve non-plain objects (Date, Uint8Array, …) by identity: they hold + // no string leaves worth rewriting, and rebuilding them as plain objects + // would corrupt the payload far more than a missed scrub would. + const proto = Object.getPrototypeOf(value); + if (proto !== Object.prototype && proto !== null) return value; + const out: Record = {}; + for (const [key, item] of Object.entries( + value as Record, + )) { + // Keys are NOT scrubbed. A key is a field name, not a payload; a + // credential appearing as an object key would mean the producer built + // the key from the value, which no MCP payload does — and rewriting keys + // would silently reshape a structure the caller then cannot address. + out[key] = scrubDeep(item); + } + return out as unknown as T; + } + return value; + } + + return { scrubString, scrubDeep, size: entries.length }; +} diff --git a/mcpjam-inspector/server/utils/web-chat-turn.ts b/mcpjam-inspector/server/utils/web-chat-turn.ts index 0c5d1242fe..84ae0b5acb 100644 --- a/mcpjam-inspector/server/utils/web-chat-turn.ts +++ b/mcpjam-inspector/server/utils/web-chat-turn.ts @@ -74,6 +74,8 @@ import { type DirectHostConfig, type PersistedTurnTrace, } from "./chat-ingestion.js"; +import { fetchRuntimeSecrets } from "./harness/runtime-secrets.js"; +import { createSecretScrubber } from "./secrets/secret-scrubber.js"; import type { HarnessSessionCommitPayload } from "./harness/harness-session-state.js"; import { type RuntimeSkill } from "./harness/runtime-skills.js"; import type { EffectiveCapabilitySet } from "../services/environments/effective-capabilities.js"; @@ -254,6 +256,32 @@ export interface WebChatTurnPersistContext { * resumed sandbox with stale plugin material ineligible. */ effectiveCapabilities?: EffectiveCapabilitySet; + /** + * The Project Environment this turn resolved, if any — the GRANT BOUNDARY for + * project secrets. + * + * An id rather than the resolved spec, deliberately. `resolveEnvironmentForRuntime` + * and `ResolvedEnvironmentRuntime` never carry secrets: `toEnvironmentPreview` + * spreads nothing and must never see a value, and a resolved spec that could + * carry one would put a credential on the same object every preview, log line + * and telemetry field already reads. The harness turn fetches its own secrets + * from Convex with the user's own bearer instead, and this is the only thing + * it needs to do that. + * + * Absent ⇒ this turn has no grant, which is a normal state, not a failure. + */ + environmentId?: string; + /** + * This turn's MATERIALIZED secrets, when the ROUTE already resolved them. + * + * Presence is semantic (even empty): supplied ⇒ do not fetch again. `chat-v2` + * resolves them before it builds the emulated `bash` tool, so by the time + * this helper runs the list already exists — and re-fetching would both cost + * a second KMS decrypt and risk the scrubber registering a different set than + * the box received. A caller that has not resolved them omits this and the + * helper fetches from {@link environmentId}. + */ + runtimeSecrets?: { name: string; value: string }[]; } /** @@ -666,13 +694,13 @@ export async function streamWebChatTurn( abortSignal: runtime.abortSignal, }) : runtime.scopeStepUp?.cancelRequest - ? buildHostedScopeStepUpCancellation({ - request: runtime.scopeStepUp.cancelRequest, - bearer: runtime.scopeStepUp.bearer, - messages: modelMessages, - tools: preparedTools, - }) - : undefined; + ? buildHostedScopeStepUpCancellation({ + request: runtime.scopeStepUp.cancelRequest, + bearer: runtime.scopeStepUp.bearer, + messages: modelMessages, + tools: preparedTools, + }) + : undefined; const createScopeStepUpContinuation = runtime.scopeStepUp && persist.chatSessionId ? async ({ @@ -783,6 +811,40 @@ export async function streamWebChatTurn( .join("\n\n"); const hostedChatSessionId = persist.chatSessionId; + + // MATERIALIZED PROJECT SECRETS for this turn, fetched ONCE here because two + // very different things need the same list and must not disagree about it: + // + // 1. the SANDBOX, which receives the values as environment variables (the + // harness turn takes them via `runtimeSecrets` below); + // 2. the SCRUBBER, which replaces those same values with `[secret:NAME]` + // in everything this turn persists. + // + // Two fetches would mean two KMS decrypts per turn AND a window where the + // registry is missing something the box already has — which is the one way + // this feature leaks by accident. Values that reach the box but not the + // registry are values that get written to the transcript verbatim. + // + // Tri-state: on failure the scrubber is `null` and the harness turn keeps + // whatever environment its session already holds. A failure must never read + // as "no secrets". + const secretsFetch = + persist.runtimeSecrets !== undefined + ? { ok: true as const, secrets: persist.runtimeSecrets } + : await fetchRuntimeSecrets(runtime.authHeader, { + ...(persist.projectId ? { projectId: persist.projectId } : {}), + ...(persist.environmentId + ? { environmentId: persist.environmentId } + : {}), + ...(hostedChatSessionId + ? { chatSessionId: hostedChatSessionId } + : {}), + }); + const runtimeSecrets = secretsFetch.ok ? secretsFetch.secrets : null; + const secretScrubber = runtimeSecrets + ? createSecretScrubber(runtimeSecrets) + : null; + const cleanupStream = async () => { // Withdraw pending elicitation rows BEFORE dropping the connections: once // the stream is gone nobody can answer, and an abandoned row would stay @@ -810,8 +872,8 @@ export async function streamWebChatTurn( // callers preserve that by passing a closure here. const resolvedHostConfig: DirectHostConfig | null = typeof persist.hostConfig === "function" - ? (persist.hostConfig({ resolvedTemperature }) ?? null) - : (persist.hostConfig ?? null); + ? persist.hostConfig({ resolvedTemperature }) ?? null + : persist.hostConfig ?? null; // Build the persist callback once — it's a closure over a lot of context // and is identical between MCPJam-free and org-BYOK other than the modelId @@ -855,6 +917,11 @@ export async function streamWebChatTurn( // rather than inferring it from a version poll. return await persistChatSessionToConvex({ chatSessionId: hostedChatSessionId, + // Applied to the SERIALIZED ingest body, so it covers every payload + // this call can carry — session messages, the tool snapshot, assistant + // text, a nested JSON string a tool returned — without a per-field list + // somebody has to remember to extend. + ...(secretScrubber ? { secretScrubber } : {}), modelId, modelSource, projectId: persist.projectId, @@ -1104,6 +1171,12 @@ export async function streamWebChatTurn( ...(persist.effectiveCapabilities ? { effectiveCapabilities: persist.effectiveCapabilities } : {}), + ...(persist.environmentId ? { environmentId: persist.environmentId } : {}), + // Presence is semantic, exactly like `runtimeSkillsOverride`: supplied + // (even empty) means "this turn's secrets are already resolved, do not + // fetch again". A harness turn reached from somewhere that does not resolve + // them (the eval/swarm driver) still fetches for itself. + ...(runtimeSecrets !== null ? { runtimeSecrets } : {}), ...(harnessMcpProxy ? { harnessMcpProxy } : {}), // Hosted MRTR (§12.5) resume: emulated engine only. On a fresh resume // request the engine drives one retry leg (reconstructing tool From 69d5f3480a59bf16f33bac3b5caa6cd84fec4f89 Mon Sep 17 00:00:00 2001 From: MCPJam Date: Fri, 28 Aug 2026 03:47:04 +0000 Subject: [PATCH 02/12] The v1 Secrets API, and every surface that carries it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Five routes, and none of them returns a value. That is the contract, not a default: the DTO has no such field, the Convex functions behind it have no code path that produces one, and the only things that decrypt write into a sandbox's environment or an egress policy and hand nothing back. The test asserts on the response SCHEMA rather than a sample body, in all three places the promise is written down (OpenAPI, the SDK type, the route's own mapper) — a sample body only proves what one fixture happened not to contain. Cross-project scoping is enforced in Convex, not here. `personas.ts`'s header apologizes for its list-and-scan preflight and names the fix; that scoped getter was built up front, so every by-id route is one read with one decision and this file holds no copy of the rule to drift from. `delivery` is required with no default. A caller who has not said whether the value ends up inside the sandbox has not made the decision the field exists for. The broker triple is required iff brokered, checked in both directions: a brokered row missing it delivers nothing silently, and a materialized row carrying it tells every reader the value is proxy-injected when it is an env var in the box. `name` and `sharing` are immutable, and their absence from PATCH is the contract. Renaming breaks the workflows that reference the environment variable; re-sharing changes who has been handed the value without changing the value. The two write ops are excluded from the MCP catalog, the agent registry and the workspace tools — and not for risk appetite. Their INPUT carries the plaintext, so it would transit model context and land in a transcript before any approval card could render, and an approval that fires after the value is logged is not one. No tier fixes that; only keeping them off those surfaces does. `TIER_EXCEPTIONS` records the deviation from the risk derivation with that reasoning, since exposure would otherwise derive `gated`. The CLI takes the value from a file, an env var, or stdin. `--value ` exists for scripting and is documented with the caveat rather than quietly available: an argv token is written to shell history, is readable in `/proc` for the life of the command, and lands in CI logs that echo their commands. DELETE is hard and is not blocked when an environment still selects the secret. Refusing would make a leaked credential un-revokable until someone edited every environment naming it; revocation never waits on cleanup. `secretSelection` joins the environment PATCH's tri-state and its `.refine` list — the field where "unclearable" would have meant a credential grant that can only ever grow. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01MCmi5hBBosufjwQ6L6UxPJ --- cli/src/commands/cloud.ts | 4 + cli/src/commands/secrets.ts | 433 +++++++ cli/src/lib/op-bindings.ts | 10 + cli/tests/cloud-flag-conventions.test.ts | 1 + docs/reference/openapi.json | 501 +++++++- mcp/README.md | 3 + mcp/src/tools/platformTools.ts | 63 +- mcp/tests/platformTools.test.ts | 22 +- .../v1/__tests__/agent-op-registry.test.ts | 374 +++--- .../v1/__tests__/secrets-write-only.test.ts | 177 +++ .../server/routes/v1/agent-op-registry.ts | 59 +- .../server/routes/v1/environments.ts | 57 +- mcpjam-inspector/server/routes/v1/index.ts | 9 +- mcpjam-inspector/server/routes/v1/secrets.ts | 476 +++++++ .../server/utils/built-in-tools/mcpjam.ts | 20 + .../operation-permalink-coverage.test.ts | 6 + sdk/src/platform/client.ts | 1136 ++++++++++------- sdk/src/platform/index.ts | 18 + sdk/src/platform/operations.ts | 403 +++++- sdk/src/platform/types.ts | 105 ++ sdk/tests/platform/operations.test.ts | 35 +- 21 files changed, 3176 insertions(+), 736 deletions(-) create mode 100644 cli/src/commands/secrets.ts create mode 100644 mcpjam-inspector/server/routes/v1/__tests__/secrets-write-only.test.ts create mode 100644 mcpjam-inspector/server/routes/v1/secrets.ts diff --git a/cli/src/commands/cloud.ts b/cli/src/commands/cloud.ts index 51dd6609d6..d0d49aa5df 100644 --- a/cli/src/commands/cloud.ts +++ b/cli/src/commands/cloud.ts @@ -11,6 +11,7 @@ import { registerJourneysCommands } from "./journeys.js"; import { registerOrganizationsCommands } from "./organizations.js"; import { registerProjectsCommands } from "./projects.js"; import { registerScenariosCommands } from "./scenarios.js"; +import { registerSecretsCommands } from "./secrets.js"; import { registerSessionsCommands } from "./sessions.js"; import { registerSwarmAuthoringCommands } from "./swarms.js"; import { registerTunnelCommands } from "./tunnel.js"; @@ -44,6 +45,9 @@ export function registerCloudCommands(program: Command): Command { registerEvalCommands(cloud); registerClientsCommands(cloud); registerEnvironmentsCommands(cloud); + // Project secrets sit with environments because an environment is what grants + // one to a run — you create a secret here and then select it there. + registerSecretsCommands(cloud); registerImagesCommands(cloud); registerSkillsCommands(cloud); diff --git a/cli/src/commands/secrets.ts b/cli/src/commands/secrets.ts new file mode 100644 index 0000000000..b10cc8db47 --- /dev/null +++ b/cli/src/commands/secrets.ts @@ -0,0 +1,433 @@ +import { readFileSync } from "node:fs"; +import type { Command } from "commander"; +import { + createSecretOperation, + deleteSecretOperation, + getSecretOperation, + listSecretsOperation, + updateSecretOperation, +} from "@mcpjam/sdk/platform"; +import { usageError, writeResult } from "../lib/output.js"; +import { + platformOptionsOf, + runPlatformOperation as runPlatformCommand, + type PlatformOptions, +} from "../lib/platform-command.js"; +import { resolveCloudProjectArgs } from "../lib/cloud-scope.js"; +import { getGlobalOptions } from "../lib/server-config.js"; + +/** + * `mcpjam cloud secrets` — the project credentials a real workflow needs. + * + * A project secret is a named credential (`STRIPE_API_KEY`, `GH_TOKEN`, a + * `psql` password) that an environment can grant to the runs launched from it. + * + * ## Write-only + * + * Nothing here prints a value, and nothing can: `list` and `show` return + * metadata — name, delivery mode, host binding, sharing, when it was last + * handed to a run. A secret is written and delivered; it is never read back. + * + * ## How the value gets in + * + * `set` and `update` take the value from a FILE, an ENVIRONMENT VARIABLE, or + * STDIN. There is deliberately no positional argument for it: a credential + * typed as an argv token is written to shell history, is visible in `ps` and + * `/proc` to every process on the machine for the life of the command, and + * lands in CI logs that echo their commands. + * + * mcpjam cloud secrets set --name STRIPE_API_KEY --value-file ./key.txt + * mcpjam cloud secrets set --name STRIPE_API_KEY --value-env STRIPE_KEY + * pass show stripe | mcpjam cloud secrets set --name STRIPE_API_KEY --value - + * + * `--value ` exists, because scripting occasionally needs it, and it + * is documented as the scripting-only option with the history caveat attached + * rather than being quietly available. + * + * ## Delivery mode is a required decision + * + * --delivery brokered the sandbox's egress proxy injects the value as a + * request header, OUTSIDE the VM. The box never + * holds it, so a prompt-injected agent has nothing + * to exfiltrate. Prevents EXTRACTION, not USE — any + * process in the box can call the bound host while + * the policy is live — and works for HTTPS APIs + * only. Needs --host / --header / --template. + * --delivery materialized a real environment variable inside the box, which + * is the only thing a CLI can read. EXTRACTABLE BY + * DESIGN: `env` prints it. + */ + +/** Where a secret's value may come from. Exactly one, and never argv by default. */ +type ValueOptions = { + value?: string; + valueFile?: string; + valueEnv?: string; +}; + +/** + * Resolve the value from whichever source the caller named. + * + * `--value -` and `--value-file -` both read STDIN, so a pipeline reads + * naturally either way. The trailing newline a shell adds is stripped ONLY for + * stdin and file input, where it is an artifact of how the text was produced; + * an explicit `--value` is taken verbatim, because there the caller typed + * exactly what they meant. + */ +function resolveSecretValue( + options: ValueOptions, + { required }: { required: boolean } +): string | undefined { + const supplied = [ + options.value !== undefined ? "--value" : null, + options.valueFile !== undefined ? "--value-file" : null, + options.valueEnv !== undefined ? "--value-env" : null, + ].filter((flag): flag is string => flag !== null); + + if (supplied.length > 1) { + throw usageError( + `Provide exactly one of --value, --value-file, or --value-env (got ${supplied.join( + ", " + )}).` + ); + } + if (supplied.length === 0) { + if (!required) return undefined; + throw usageError( + "A value is required. Prefer --value-file , --value-env , or `--value -` to read stdin; --value works but is written to your shell history." + ); + } + + if (options.valueEnv !== undefined) { + const value = process.env[options.valueEnv]; + if (value === undefined || value === "") { + throw usageError( + `Environment variable "${options.valueEnv}" is not set (or is empty).` + ); + } + return value; + } + + const readStdinOrFile = (path: string): string => { + try { + return path === "-" + ? readFileSync(0, "utf8") + : readFileSync(path, "utf8"); + } catch (error) { + throw usageError( + path === "-" + ? "Failed to read the secret value from stdin." + : `Failed to read the secret value from "${path}".`, + { source: error instanceof Error ? error.message : String(error) } + ); + } + }; + + if (options.valueFile !== undefined) { + const text = readStdinOrFile(options.valueFile).replace(/\r?\n$/, ""); + if (text === "") throw usageError("The secret value is empty."); + return text; + } + + // `--value -` is the stdin spelling most people reach for first. + if (options.value === "-") { + const text = readStdinOrFile("-").replace(/\r?\n$/, ""); + if (text === "") throw usageError("The secret value is empty."); + return text; + } + if (options.value === "") throw usageError("The secret value is empty."); + return options.value; +} + +/** The broker triple, or nothing. Presence is checked against `--delivery`. */ +function brokerFields(options: { + host?: string[]; + header?: string; + template?: string; +}): { + brokerHosts?: string[]; + brokerHeader?: string; + brokerTemplate?: string; +} { + return { + ...(options.host !== undefined && options.host.length > 0 + ? { brokerHosts: options.host } + : {}), + ...(options.header !== undefined ? { brokerHeader: options.header } : {}), + ...(options.template !== undefined + ? { brokerTemplate: options.template } + : {}), + }; +} + +/** Commander's repeatable-option collector for `--host`. */ +function collectHost(value: string, previous: string[] = []): string[] { + return [...previous, value]; +} + +export function registerSecretsCommands(program: Command): void { + const secrets = program + .command("secrets") + .description( + "Store and manage the project credentials a workflow needs (stripe, gh, psql). Write-only: no command prints a value." + ); + + secrets + .command("list") + .description( + "List the project's secrets — metadata only. Shows the project-shared ones plus your own personal ones." + ) + .option( + "--project ", + "Project name or ID (defaults to the most recently updated project)" + ) + .action( + async (options: PlatformOptions & { project?: string }, command) => { + const globalOptions = getGlobalOptions(command); + const result = await runPlatformCommand( + platformOptionsOf(command), + globalOptions.timeout, + ({ client, signal }) => + listSecretsOperation.execute( + { project: resolveCloudProjectArgs(options).project }, + { client, signal } + ) + ); + writeResult(result, globalOptions.format); + } + ); + + secrets + .command("show") + .description( + "Show one secret's metadata: delivery mode, host binding, sharing, last delivery. Never its value." + ) + .requiredOption("--secret ", "Secret ID, from `cloud secrets list`") + .option("--project ", "Project name or ID") + .action( + async ( + options: PlatformOptions & { project?: string; secret: string }, + command + ) => { + const globalOptions = getGlobalOptions(command); + const result = await runPlatformCommand( + platformOptionsOf(command), + globalOptions.timeout, + ({ client, signal }) => + getSecretOperation.execute( + { + project: resolveCloudProjectArgs(options).project, + secret: options.secret, + }, + { client, signal } + ) + ); + writeResult(result, globalOptions.format); + } + ); + + secrets + .command("set") + .description( + "Create a secret. The value comes from --value-file, --value-env, or stdin — never a positional argument." + ) + .requiredOption( + "--name ", + "Environment-variable name (STRIPE_API_KEY). Uppercase, digits, underscores; not starting with a digit. Immutable." + ) + .requiredOption( + "--delivery ", + "brokered (the proxy injects it outside the sandbox — extraction-proof, not use-proof, HTTPS only) or materialized (a real env var inside the box, which is what a CLI can read, and which `env` prints)" + ) + .option( + "--value-file ", + "Read the value from a file; `-` reads stdin. Preferred." + ) + .option("--value-env ", "Read the value from an environment variable.") + .option( + "--value ", + "The value inline, or `-` to read stdin. SCRIPTING ONLY: an inline literal is written to your shell history and is visible in `ps` while the command runs." + ) + .option("--description ", "What this credential is for.") + .option( + "--host ", + "Brokered only, repeatable: an exact hostname the header is injected on (api.stripe.com). No scheme, no port, no wildcard.", + collectHost + ) + .option( + "--header ", + "Brokered only: the header name, e.g. Authorization." + ) + .option( + "--template ", + 'Brokered only: the header value with {} where the secret goes, e.g. "Bearer {}".' + ) + .option( + "--sharing ", + "project (default; delivered to every member's sessions, admin-only) or user (personal; delivered only in sessions you start)" + ) + .option( + "--idempotency-key ", + "Retry key. Pass one: a retried create without it fails as a name conflict with the row the first attempt already made." + ) + .action( + async ( + options: PlatformOptions & + ValueOptions & { + project?: string; + name: string; + delivery: string; + description?: string; + host?: string[]; + header?: string; + template?: string; + sharing?: string; + idempotencyKey?: string; + }, + command + ) => { + const globalOptions = getGlobalOptions(command); + const value = resolveSecretValue(options, { required: true })!; + // Validated through the operation's own schema, so the CLI and the API + // reject the same inputs with the same messages rather than growing a + // second, drifting copy of the rules. + const input = createSecretOperation.inputSchema.safeParse({ + project: resolveCloudProjectArgs(options).project, + name: options.name, + value, + ...(options.description !== undefined + ? { description: options.description } + : {}), + delivery: options.delivery, + ...brokerFields(options), + ...(options.sharing !== undefined + ? { sharing: options.sharing } + : {}), + ...(options.idempotencyKey !== undefined + ? { idempotencyKey: options.idempotencyKey } + : {}), + }); + if (!input.success) { + throw usageError( + `Invalid input: ${input.error.issues + .map( + (issue) => + `${issue.path.join(".") || "(root)"}: ${issue.message}` + ) + .join("; ")}` + ); + } + const result = await runPlatformCommand( + platformOptionsOf(command), + globalOptions.timeout, + ({ client, signal }) => + createSecretOperation.execute(input.data, { client, signal }) + ); + writeResult(result, globalOptions.format); + } + ); + + secrets + .command("update") + .description( + "Rotate a secret's value and/or change how it is delivered. A rotation reaches NEW RUNS ONLY — a session already running keeps the value it was given." + ) + .requiredOption("--secret ", "Secret ID, from `cloud secrets list`") + .option("--project ", "Project name or ID") + .option( + "--value-file ", + "Read the new value from a file; `-` reads stdin. Preferred." + ) + .option( + "--value-env ", + "Read the new value from an environment variable." + ) + .option( + "--value ", + "The new value inline, or `-` to read stdin. SCRIPTING ONLY — see `secrets set`." + ) + .option("--description ", "Replacement description.") + .option( + "--delivery ", + "brokered or materialized. Switching to brokered needs --host/--header/--template in the same call; switching to materialized clears them." + ) + .option("--host ", "Brokered only, repeatable.", collectHost) + .option("--header ", "Brokered only: the header name.") + .option("--template ", 'Brokered only: e.g. "Bearer {}".') + .action( + async ( + options: PlatformOptions & + ValueOptions & { + project?: string; + secret: string; + description?: string; + delivery?: string; + host?: string[]; + header?: string; + template?: string; + }, + command + ) => { + const globalOptions = getGlobalOptions(command); + const value = resolveSecretValue(options, { required: false }); + const input = updateSecretOperation.inputSchema.safeParse({ + project: resolveCloudProjectArgs(options).project, + secret: options.secret, + ...(value !== undefined ? { value } : {}), + ...(options.description !== undefined + ? { description: options.description } + : {}), + ...(options.delivery !== undefined + ? { delivery: options.delivery } + : {}), + ...brokerFields(options), + }); + if (!input.success) { + throw usageError( + `Invalid input: ${input.error.issues + .map( + (issue) => + `${issue.path.join(".") || "(root)"}: ${issue.message}` + ) + .join("; ")}` + ); + } + const result = await runPlatformCommand( + platformOptionsOf(command), + globalOptions.timeout, + ({ client, signal }) => + updateSecretOperation.execute(input.data, { client, signal }) + ); + writeResult(result, globalOptions.format); + } + ); + + secrets + .command("rm") + .description( + "Revoke a secret. HARD: the row and the encrypted value both go. Not blocked when an environment still selects it — revocation never waits on cleanup." + ) + .requiredOption("--secret ", "Secret ID, from `cloud secrets list`") + .option("--project ", "Project name or ID") + .action( + async ( + options: PlatformOptions & { project?: string; secret: string }, + command + ) => { + const globalOptions = getGlobalOptions(command); + const result = await runPlatformCommand( + platformOptionsOf(command), + globalOptions.timeout, + ({ client, signal }) => + deleteSecretOperation.execute( + { + project: resolveCloudProjectArgs(options).project, + secret: options.secret, + }, + { client, signal } + ) + ); + writeResult(result, globalOptions.format); + } + ); +} diff --git a/cli/src/lib/op-bindings.ts b/cli/src/lib/op-bindings.ts index 1246b990d2..db431728b1 100644 --- a/cli/src/lib/op-bindings.ts +++ b/cli/src/lib/op-bindings.ts @@ -84,6 +84,16 @@ export const CLI_BINDINGS: Readonly> = { update_persona: { command: "cloud personas update" }, delete_persona: { command: "cloud personas delete" }, generate_personas: { command: "cloud personas generate" }, + + // ── Project secrets ───────────────────────────────────────────────────── + // `set`/`update` take the value from --value-file, --value-env, or stdin. + // A positional value would be written to shell history and visible in `ps` + // for the life of the command, which is why the CLI does not offer one. + list_secrets: { command: "cloud secrets list" }, + get_secret: { command: "cloud secrets show" }, + create_secret: { command: "cloud secrets set" }, + update_secret: { command: "cloud secrets update" }, + delete_secret: { command: "cloud secrets rm" }, list_swarms: { command: "cloud swarms list" }, get_swarm: { command: "cloud swarms get" }, create_swarm: { command: "cloud swarms create" }, diff --git a/cli/tests/cloud-flag-conventions.test.ts b/cli/tests/cloud-flag-conventions.test.ts index 6ffa16c595..97f16f53d5 100644 --- a/cli/tests/cloud-flag-conventions.test.ts +++ b/cli/tests/cloud-flag-conventions.test.ts @@ -30,6 +30,7 @@ const CLOUD_COMMAND_FILES = [ "projects.ts", "registry.ts", "scenarios.ts", + "secrets.ts", "sessions.ts", "skills.ts", "swarms.ts", diff --git a/docs/reference/openapi.json b/docs/reference/openapi.json index 7ef3dfab40..d5c8248c73 100644 --- a/docs/reference/openapi.json +++ b/docs/reference/openapi.json @@ -4965,7 +4965,11 @@ "tags": ["Skills"], "summary": "List a project's skills", "description": "The Cloud Skills visible to the caller in this project: the project-shared ones plus the caller's own drafts. Each row reports `pinnability`, which is what decides whether its id is usable in an environment's `skillSelection`.", - "parameters": [{ "$ref": "#/components/parameters/projectId" }], + "parameters": [ + { + "$ref": "#/components/parameters/projectId" + } + ], "responses": { "200": { "description": "The project's skills.", @@ -5005,12 +5009,16 @@ "summary": "Get a skill", "description": "One skill, including its SKILL.md body. The body is mutable and an edit overwrites the previous one in place, so `aggregateHash` is the only handle on which content this read returned.", "parameters": [ - { "$ref": "#/components/parameters/projectId" }, + { + "$ref": "#/components/parameters/projectId" + }, { "name": "skillId", "in": "path", "required": true, - "schema": { "type": "string" }, + "schema": { + "type": "string" + }, "description": "Skill ID." } ], @@ -6533,6 +6541,233 @@ } } }, + "/projects/{projectId}/secrets": { + "parameters": [ + { + "$ref": "#/components/parameters/projectId" + } + ], + "get": { + "operationId": "listSecrets", + "tags": ["Secrets"], + "summary": "List secrets", + "description": "The project's credentials as METADATA ONLY — no value is returned by this or any other route. Shows the project-shared secrets plus the caller's own personal ones; another member's personal secret does not appear at all, not even its name.", + "responses": { + "200": { + "description": "A page of secrets.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SecretPage" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + }, + "post": { + "operationId": "createSecret", + "tags": ["Secrets"], + "summary": "Create a secret", + "description": "Store a credential so environments can grant it to runs. THE VALUE TRAVELS IN THE REQUEST BODY and becomes visible to whatever makes the call. The response is metadata only. Creating a project-shared secret requires project admin; a personal one does not.", + "parameters": [ + { + "name": "Idempotency-Key", + "in": "header", + "required": false, + "description": "Retry-safe create key. Replaying the SAME key with the SAME body returns the original resource instead of creating a second one; reusing it with a DIFFERENT body is a 409. Worth passing: a retried create without one fails as a name conflict with the row the first attempt already made.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "description": "The secret to create.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SecretCreateRequest" + } + } + } + }, + "responses": { + "201": { + "description": "The created secret, as metadata.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Secret" + } + } + } + }, + "400": { + "$ref": "#/components/responses/ValidationError" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "409": { + "$ref": "#/components/responses/Conflict" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + }, + "/projects/{projectId}/secrets/{secretId}": { + "parameters": [ + { + "$ref": "#/components/parameters/projectId" + }, + { + "$ref": "#/components/parameters/secretId" + } + ], + "get": { + "operationId": "getSecret", + "tags": ["Secrets"], + "summary": "Get a secret", + "description": "One secret's metadata: delivery mode, host binding, sharing, and when it was last handed to a run. Never its value. A secret from another project — and another member's personal secret — both read as 404.", + "responses": { + "200": { + "description": "The secret, as metadata.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Secret" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + }, + "patch": { + "operationId": "updateSecret", + "tags": ["Secrets"], + "summary": "Rotate or re-bind a secret", + "description": "Rotate the value and/or change how it is delivered. A rotation reaches NEW RUNS ONLY: a session already running holds the old value — materialized in its box's environment, or inside an egress policy that cannot be read back — and there is no safe way to replace it mid-run.", + "requestBody": { + "required": true, + "description": "The fields to change.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SecretUpdateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "The updated secret, as metadata.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Secret" + } + } + } + }, + "400": { + "$ref": "#/components/responses/ValidationError" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "409": { + "$ref": "#/components/responses/Conflict" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + }, + "delete": { + "operationId": "deleteSecret", + "tags": ["Secrets"], + "summary": "Delete a secret", + "description": "Revoke a credential. HARD — the row and the encrypted value both go. Deliberately NOT blocked when an environment still selects it: refusing would make a leaked credential un-revokable until someone edited every environment naming it, and revocation must never wait on cleanup.", + "responses": { + "200": { + "description": "The secret was revoked.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SecretDeleted" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "429": { + "$ref": "#/components/responses/RateLimited" + }, + "500": { + "$ref": "#/components/responses/InternalError" + } + } + } + }, "/projects/{projectId}/journeys/generate": { "parameters": [ { @@ -11090,6 +11325,15 @@ "type": "string" }, "description": "Gate waiver ID, as returned when the waiver was granted or read." + }, + "secretId": { + "name": "secretId", + "in": "path", + "required": true, + "description": "Secret ID, as returned by the project's secret list.", + "schema": { + "type": "string" + } } }, "requestBodies": { @@ -16766,6 +17010,25 @@ } } }, + "EnvironmentSecretSelection": { + "type": "object", + "description": "Which PROJECT SECRETS a run launched from this environment receives — ids only. The environment is the GRANT BOUNDARY: absent means no secrets, and there is no \"all of them\" mode. Cannot be empty; clear the field instead (send `null` on update) to revoke the grant.\n\nMembership is not delivery. A `sharing: user` secret selected here reaches ONLY sessions its owner started; every other member's run of this environment silently does not receive it, and that rule is re-checked live at launch rather than baked into the selection.", + "required": ["mode", "secretIds"], + "properties": { + "mode": { + "type": "string", + "enum": ["explicit"] + }, + "secretIds": { + "type": "array", + "minItems": 1, + "items": { + "type": "string" + }, + "description": "Secret IDs, as returned by the project's secret list." + } + } + }, "ProjectEnvironment": { "type": "object", "description": "A project environment: a named, live-editable execution bundle that eval suites and journeys run against.", @@ -16808,6 +17071,9 @@ "skillSelection": { "$ref": "#/components/schemas/EnvironmentSkillSelection" }, + "secretSelection": { + "$ref": "#/components/schemas/EnvironmentSecretSelection" + }, "pluginVersionIds": { "type": "array", "items": { @@ -17113,7 +17379,9 @@ }, "SkillDetail": { "allOf": [ - { "$ref": "#/components/schemas/Skill" }, + { + "$ref": "#/components/schemas/Skill" + }, { "type": "object", "required": ["content"], @@ -17184,6 +17452,9 @@ "skillSelection": { "$ref": "#/components/schemas/EnvironmentSkillSelection" }, + "secretSelection": { + "$ref": "#/components/schemas/EnvironmentSecretSelection" + }, "pluginVersionIds": { "type": "array", "items": { @@ -17245,6 +17516,9 @@ "skillSelection": { "$ref": "#/components/schemas/EnvironmentSkillSelection" }, + "secretSelection": { + "$ref": "#/components/schemas/EnvironmentSecretSelection" + }, "pluginVersionIds": { "type": "array", "minItems": 1, @@ -17305,6 +17579,9 @@ "skillSelection": { "$ref": "#/components/schemas/EnvironmentSkillSelection" }, + "secretSelection": { + "$ref": "#/components/schemas/EnvironmentSecretSelection" + }, "pluginVersionIds": { "type": "array", "minItems": 1, @@ -17364,6 +17641,15 @@ "nullable": true, "description": "`null` clears the pinned skill selection." }, + "secretSelection": { + "allOf": [ + { + "$ref": "#/components/schemas/EnvironmentSecretSelection" + } + ], + "nullable": true, + "description": "`null` REVOKES the environment's credential grant; a value replaces it; omission leaves it unchanged. `[]` is rejected — an accidental empty array that read as \"remove every credential\" would break a workflow with no error to look at." + }, "pluginVersionIds": { "type": "array", "minItems": 1, @@ -18914,6 +19200,213 @@ } } }, + "Secret": { + "type": "object", + "description": "A project credential — METADATA ONLY, always. There is no `value` field on this schema and no route that returns one: a secret is written and delivered into a run, never read back.", + "required": [ + "id", + "projectId", + "name", + "description", + "delivery", + "sharing", + "lastDeliveredAt", + "createdAt", + "updatedAt", + "createdByUserId", + "updatedByUserId" + ], + "properties": { + "id": { + "type": "string" + }, + "projectId": { + "type": "string" + }, + "name": { + "type": "string", + "description": "The environment-variable name (`^[A-Z_][A-Z0-9_]*$`). This IS the secret's identity: what a materialized delivery exports, what a workflow references, and what stays stable across a rotation. Immutable." + }, + "description": { + "type": ["string", "null"] + }, + "delivery": { + "type": "string", + "enum": ["brokered", "materialized"], + "description": "`brokered` — the sandbox's egress proxy injects the value as a request header OUTSIDE the VM, so the box never holds it. Prevents EXTRACTION, not USE: any process in the box can call the bound host while the policy is live, and it works for HTTPS APIs only (domain rules bind on ports 80/443). `materialized` — a real environment variable inside the box, which is the only thing a CLI can read; EXTRACTABLE BY DESIGN." + }, + "brokerHosts": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Brokered only: the exact hostnames the header is injected on." + }, + "brokerHeader": { + "type": "string", + "description": "Brokered only: the header name." + }, + "brokerTemplate": { + "type": "string", + "description": "Brokered only: the header value, with `{}` where the secret goes." + }, + "sharing": { + "type": "string", + "enum": ["user", "project"], + "description": "`project` — admin-managed, delivered to every member's sessions. `user` — personal, delivered ONLY in sessions its owner starts and silently absent from anyone else's run of the same environment. Immutable." + }, + "ownerUserId": { + "type": "string", + "description": "Personal secrets only. Project-shared rows have no owner." + }, + "lastDeliveredAt": { + "type": ["integer", "null"], + "description": "When this secret was last HANDED TO a run — not when it was last used. Brokered use is unobservable by construction (the proxy injects the header; the request is never seen here), so `used` would be a number nobody can honestly produce. `null` means nothing has been recorded, which is not the same as never delivered." + }, + "createdAt": { + "type": "integer" + }, + "updatedAt": { + "type": "integer" + }, + "createdByUserId": { + "type": "string" + }, + "updatedByUserId": { + "type": "string" + } + } + }, + "SecretPage": { + "type": "object", + "required": ["items"], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Secret" + } + }, + "nextCursor": { + "type": "string", + "description": "Present only when another page exists. Opaque — do not parse it." + } + } + }, + "SecretCreateRequest": { + "type": "object", + "description": "THE VALUE TRAVELS IN THIS BODY and becomes visible to whatever makes the call — its process, its logs, its shell history. Supply it from a file or an environment variable rather than pasting it into a command.", + "required": ["name", "value", "delivery"], + "properties": { + "name": { + "type": "string", + "maxLength": 64, + "pattern": "^[A-Z_][A-Z0-9_]*$", + "description": "Environment-variable name. Immutable — renaming is delete-and-recreate." + }, + "value": { + "type": "string", + "maxLength": 65536, + "description": "The credential. Stored encrypted; no route ever returns it. NOT trimmed — a trailing newline is meaningful in a PEM block, and rewriting what you sent would present as 'the key is wrong' with nothing to look at." + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "delivery": { + "type": "string", + "enum": ["brokered", "materialized"], + "description": "Required, with no default: a caller who has not said whether the value ends up inside the sandbox has not made the decision this field exists for. See `Secret.delivery`." + }, + "brokerHosts": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1, + "maxItems": 10, + "description": "Required for `brokered`, forbidden for `materialized`. Exact hostnames — no scheme, no port, no wildcard: the proxy matches a host, and a URL installs a rule that silently never fires." + }, + "brokerHeader": { + "type": "string", + "maxLength": 64, + "description": "Required for `brokered`, forbidden for `materialized`. e.g. `Authorization`." + }, + "brokerTemplate": { + "type": "string", + "maxLength": 256, + "description": "Required for `brokered`, forbidden for `materialized`. The header value with `{}` where the secret goes, e.g. `Bearer {}`. A template without `{}` is rejected: it installs a constant header that never carries the credential." + }, + "sharing": { + "type": "string", + "enum": ["user", "project"], + "default": "project", + "description": "Defaults to `project`. A non-admin asking for it is refused rather than downgraded to personal — a silent downgrade looks like success and then reaches nobody else's sessions." + } + } + }, + "SecretUpdateRequest": { + "type": "object", + "description": "At least one field. `name` and `sharing` are absent because both are IMMUTABLE: renaming would break the workflows referencing the environment variable, and re-sharing would change who has already been handed the value. Delete and recreate for either. A rotation reaches NEW RUNS ONLY — a session already running holds the old value and cannot be reached.", + "minProperties": 1, + "properties": { + "value": { + "type": "string", + "maxLength": 65536, + "description": "The new credential. Same exposure as on create: it travels in this body." + }, + "description": { + "type": ["string", "null"], + "maxLength": 500, + "description": "`null` clears it; omit to leave it unchanged." + }, + "delivery": { + "type": "string", + "enum": ["brokered", "materialized"], + "description": "Switching to `brokered` requires the host binding in the same call; switching to `materialized` clears it." + }, + "brokerHosts": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1, + "maxItems": 10, + "description": "Required for `brokered`, forbidden for `materialized`. Exact hostnames — no scheme, no port, no wildcard: the proxy matches a host, and a URL installs a rule that silently never fires." + }, + "brokerHeader": { + "type": "string", + "maxLength": 64, + "description": "Required for `brokered`, forbidden for `materialized`. e.g. `Authorization`." + }, + "brokerTemplate": { + "type": "string", + "maxLength": 256, + "description": "Required for `brokered`, forbidden for `materialized`. The header value with `{}` where the secret goes, e.g. `Bearer {}`. A template without `{}` is rejected: it installs a constant header that never carries the credential." + } + } + }, + "SecretDeleted": { + "type": "object", + "description": "A HARD delete: the row and the encrypted value both go. This is the revoke button, so it is not soft.", + "required": ["id", "projectId", "name", "deleted"], + "properties": { + "id": { + "type": "string" + }, + "projectId": { + "type": "string" + }, + "name": { + "type": "string", + "description": "Echoed so a caller logging the revoke needs no prior read." + }, + "deleted": { + "type": "boolean", + "enum": [true] + } + } + }, "JourneyDraft": { "type": "object", "required": ["goal"], diff --git a/mcp/README.md b/mcp/README.md index ba8aa90b7f..c98de22627 100644 --- a/mcp/README.md +++ b/mcp/README.md @@ -110,6 +110,9 @@ so results respect the caller's project access. | `create_persona` | Create a reusable synthetic character for Swarms to run as. | — | | `update_persona` | Edit a persona's name, role or notes. Finished runs keep the persona they ran as. | — | | `delete_persona` | Remove a persona from the roster. Soft: history keeps resolving it. | — | +| `list_secrets` | List the project's credentials as metadata only — name, delivery mode, host binding, sharing. No value is ever returned. | — | +| `get_secret` | One secret's metadata: how it is delivered, where it is bound, when it was last handed to a run. Never its value. | — | +| `delete_secret` | Revoke a credential. Hard: the row and the encrypted value both go. | — | | `generate_personas` | Draft candidate personas with a model, grounded in what the project's servers do. Saves nothing; spends. | — | | `list_journeys` | List the project's journeys — a persona, a goal, and the environments to pursue it against. | — | | `get_journey` | Get one journey in full, including the execution config that determines how many sessions a run produces. | — | diff --git a/mcp/src/tools/platformTools.ts b/mcp/src/tools/platformTools.ts index e2fcbe6c4a..1f713d990c 100644 --- a/mcp/src/tools/platformTools.ts +++ b/mcp/src/tools/platformTools.ts @@ -97,6 +97,9 @@ import { createPersonaOperation, updatePersonaOperation, deletePersonaOperation, + listSecretsOperation, + getSecretOperation, + deleteSecretOperation, generatePersonasOperation, listJourneysOperation, getJourneyOperation, @@ -329,6 +332,13 @@ export const PLATFORM_CATALOG_OPERATIONS: ReadonlyArray< createPersonaOperation, updatePersonaOperation, deletePersonaOperation, + // PROJECT SECRETS — the metadata reads plus the revoke. The two write ops + // that carry a plaintext are in EXCLUDED_FROM_CATALOG; `delete_secret` is + // here because revoking a leaked credential is exactly the thing an + // unattended caller should be able to do without a human in the loop. + listSecretsOperation, + getSecretOperation, + deleteSecretOperation, generatePersonasOperation, listJourneysOperation, getJourneyOperation, @@ -490,24 +500,32 @@ export const EXCLUDED_FROM_CATALOG: Readonly> = { "Scenario exposure is already update_user_testing_scenario. The unified setter also changes who can open a conformance or eval share URL; shipping it now would add a second spelling of scenario mode on the unattended catalog.", rotate_share_link: "Scenario rotation is already rotate_user_testing_link. The unified rotate is destructive across resource types and should land with the same share group as the get/set pair, not as a third rotate tool.", + // PROJECT SECRET WRITES. Excluded for a reason that has nothing to do with + // how destructive they are, and everything to do with their INPUT: the + // plaintext credential is an argument, so it would transit model context and + // be written into chat transcripts before any approval card could render. + // An approval that runs after the value has already been logged is not an + // approval. The reads (list_secrets, get_secret) are in the catalog — they + // return metadata only and cannot produce a value. + create_secret: + "The plaintext value is an argument, so it would transit model context and be written into chat transcripts before any approval could run — an approval that fires after the credential is already logged is not one. Available on REST, the SDK and the CLI, where the caller controls where the value comes from. The metadata reads (list_secrets, get_secret) are in the catalog.", + update_secret: + "Same as create_secret: a rotation carries the new plaintext as an argument, so it would reach model context and the transcript before any approval could run. Available on REST, the SDK and the CLI. The metadata reads (list_secrets, get_secret) are in the catalog.", }; const catalogOperationNames = new Set( - PLATFORM_CATALOG_OPERATIONS.map((operation) => operation.name), + PLATFORM_CATALOG_OPERATIONS.map((operation) => operation.name) ); const allOperationNames = new Set( - ALL_OPERATIONS.map((operation) => operation.name), + ALL_OPERATIONS.map((operation) => operation.name) ); const staleCatalogExclusions = Object.keys(EXCLUDED_FROM_CATALOG).filter( - (name) => !allOperationNames.has(name), + (name) => !allOperationNames.has(name) ); const uncoveredCatalogOperations = ALL_OPERATIONS.filter( (operation) => !catalogOperationNames.has(operation.name) && - !Object.prototype.hasOwnProperty.call( - EXCLUDED_FROM_CATALOG, - operation.name, - ), + !Object.prototype.hasOwnProperty.call(EXCLUDED_FROM_CATALOG, operation.name) ); if ( staleCatalogExclusions.length > 0 || @@ -515,10 +533,10 @@ if ( ) { throw new Error( `Platform MCP catalog partition drift: stale=${staleCatalogExclusions.join( - ",", + "," )}; uncovered=${uncoveredCatalogOperations .map((operation) => operation.name) - .join(",")}`, + .join(",")}` ); } @@ -562,8 +580,8 @@ const DESTRUCTIVE_OPERATION_NAMES: ReadonlySet = new Set( ALL_OPERATIONS.filter( (operation) => operation.risk === "destructive" || - LEGACY_DESTRUCTIVE_NAMES.has(operation.name), - ).map((operation) => operation.name), + LEGACY_DESTRUCTIVE_NAMES.has(operation.name) + ).map((operation) => operation.name) ); /** @@ -585,6 +603,9 @@ const NON_IDEMPOTENT_DESTRUCTIVE_NAMES: ReadonlySet = new Set([ // not retryable), never looser. renderServerWidgetOperation.name, deletePersonaOperation.name, + // A HARD delete of a credential: the row and the ciphertext both go, and a + // second call cannot find the row to report the same outcome. + deleteSecretOperation.name, archiveJourneyOperation.name, archiveSwarmOperation.name, removeUserTestingMemberOperation.name, @@ -613,7 +634,7 @@ export const PLATFORM_TOOL_WIDGET_VIEWS: Readonly< export function registerPlatformCatalogTools( registrar: SessionToolRegistrar, - context: PlatformToolContext, + context: PlatformToolContext ): void { for (const operation of PLATFORM_CATALOG_OPERATIONS) { const view = PLATFORM_TOOL_WIDGET_VIEWS[operation.name]; @@ -626,7 +647,7 @@ export function registerPlatformCatalogTools( annotations: operationAnnotations(operation), }, async (input) => runPlatformOperation(context, operation, input), - view ? platformWidgetUi(context, operation, view) : undefined, + view ? platformWidgetUi(context, operation, view) : undefined ); } } @@ -641,7 +662,7 @@ export function registerPlatformCatalogTools( export function platformWidgetUi( context: PlatformToolContext, operation: PlatformOperation, - view: PlatformWidgetView, + view: PlatformWidgetView ) { return { resourceUri: PLATFORM_WIDGET_RESOURCE_URIS[view], @@ -654,13 +675,13 @@ export function platformWidgetUi( }, callback: async (input: unknown) => runPlatformOperation(context, operation, input, (payload) => - tagPlatformWidgetPayload(view, payload), + tagPlatformWidgetPayload(view, payload) ), }; } export function operationAnnotations( - operation: PlatformOperation, + operation: PlatformOperation ): ToolAnnotations { if (operation.readOnly) { return { readOnlyHint: true }; @@ -703,7 +724,7 @@ export function operationAnnotations( * before the call, not from the invoice. */ export function operationDescription( - operation: PlatformOperation, + operation: PlatformOperation ): string { return operation.risk === "spend" ? `${operation.description} COSTS MONEY: this consumes the organization's credits or configured provider keys.` @@ -714,7 +735,7 @@ export async function runPlatformOperation( context: PlatformToolContext, operation: PlatformOperation, input: TInput, - transformPayload?: (payload: TOutput) => object, + transformPayload?: (payload: TOutput) => object ) { // Resolve the bearer: the verified token for an authed session, or a // lazily-minted guest token for an anonymous one. Minting happens here (on @@ -761,7 +782,7 @@ export async function runPlatformOperation( } catch (error) { return toolError( describeOperationError(error), - errorStructuredContent(error), + errorStructuredContent(error) ); } } @@ -772,7 +793,7 @@ export async function runPlatformOperation( // calmly instead of with the alarming destructive styling. The model/CLI still // see `isError` plus the human-readable text message. function errorStructuredContent( - error: unknown, + error: unknown ): Record | undefined { if (isPlatformApiError(error)) { return { error: { code: error.code, message: error.message } }; @@ -948,7 +969,7 @@ function toolSuccess(payload: object, permalinks: PlatformPermalink[] = []) { function toolError( message: string, - structuredContent?: Record, + structuredContent?: Record ) { return { isError: true, diff --git a/mcp/tests/platformTools.test.ts b/mcp/tests/platformTools.test.ts index 74c55fc3da..7f7c28c277 100644 --- a/mcp/tests/platformTools.test.ts +++ b/mcp/tests/platformTools.test.ts @@ -212,6 +212,9 @@ const PLAIN_TOOLS = [ "create_persona", "update_persona", "delete_persona", + "list_secrets", + "get_secret", + "delete_secret", "generate_personas", "list_journeys", "get_journey", @@ -338,7 +341,9 @@ describe("platform tool registration", () => { registrations.map((registration) => [registration.name, registration]) ); for (const operation of PLATFORM_CATALOG_OPERATIONS) { - const description = String(byName.get(operation.name)?.config.description); + const description = String( + byName.get(operation.name)?.config.description + ); expect(description.includes("COSTS MONEY")).toBe( operation.risk === "spend" ); @@ -347,9 +352,9 @@ describe("platform tool registration", () => { expect(String(byName.get("run_eval_suite")?.config.description)).toContain( "COSTS MONEY" ); - expect(String(byName.get("list_eval_suites")?.config.description)).not.toContain( - "COSTS MONEY" - ); + expect( + String(byName.get("list_eval_suites")?.config.description) + ).not.toContain("COSTS MONEY"); }); it("registers show_servers with the MCP Apps UI resource", () => { @@ -460,6 +465,9 @@ describe("platform tool registration", () => { "create_persona", "update_persona", "delete_persona", + "list_secrets", + "get_secret", + "delete_secret", "generate_personas", "list_journeys", "get_journey", @@ -649,6 +657,9 @@ describe("platform tool registration", () => { // that running a third party's tool twice is safe. "render_server_widget", "delete_persona", + // A HARD credential revoke: the row and the ciphertext both go, so a + // second call cannot find the row to report the same outcome. + "delete_secret", "archive_journey", "archive_swarm", "remove_user_testing_member", @@ -669,6 +680,9 @@ describe("platform tool registration", () => { // roster and a second call answers not-found. From the caller's side // that is a removal. "delete_persona", + // Revoking a credential. Unlike the soft deletes around it, this one is + // genuinely irreversible — the encrypted value is gone. + "delete_secret", "archive_journey", "archive_swarm", "cancel_journey_run", diff --git a/mcpjam-inspector/server/routes/v1/__tests__/agent-op-registry.test.ts b/mcpjam-inspector/server/routes/v1/__tests__/agent-op-registry.test.ts index ec3d258fc6..8c7bb45cb2 100644 --- a/mcpjam-inspector/server/routes/v1/__tests__/agent-op-registry.test.ts +++ b/mcpjam-inspector/server/routes/v1/__tests__/agent-op-registry.test.ts @@ -67,7 +67,7 @@ describe("agent op registry", () => { // sees. Both directions are checked so the exclusion list can only shrink // except by deliberate change. const registered = new Set( - AGENT_OP_REGISTRY.map((entry) => entry.operation.name) + AGENT_OP_REGISTRY.map((entry) => entry.operation.name), ); const excluded = new Set(Object.keys(EXCLUDED_FROM_AGENT)); @@ -93,7 +93,7 @@ describe("agent op registry", () => { for (const [name, reason] of Object.entries(EXCLUDED_FROM_AGENT)) { expect( reason.length, - `${name} needs a substantive reason` + `${name} needs a substantive reason`, ).toBeGreaterThan(20); } const reasons = Object.values(EXCLUDED_FROM_AGENT); @@ -104,13 +104,13 @@ describe("agent op registry", () => { it("derives the two tiers from the registry, in registry order", () => { expect(AGENT_API_OPERATIONS.map((op) => op.name)).toEqual( AGENT_OP_REGISTRY.filter((entry) => entry.tier === "direct").map( - (entry) => entry.operation.name - ) + (entry) => entry.operation.name, + ), ); expect(AGENT_API_GATED_OPERATIONS.map((op) => op.name)).toEqual( AGENT_OP_REGISTRY.filter((entry) => entry.tier === "gated").map( - (entry) => entry.operation.name - ) + (entry) => entry.operation.name, + ), ); }); @@ -121,12 +121,12 @@ describe("agent op registry", () => { // catalog; this asserts the derivation, so a future edit that reintroduces // a manual entry fails here. const escaped = AGENT_API_OPERATIONS.filter( - (op) => !op.readOnly && !WRITE_OPERATION_NAMES.has(op.name) + (op) => !op.readOnly && !WRITE_OPERATION_NAMES.has(op.name), ).map((op) => op.name); expect(escaped).toEqual([]); const spurious = [...WRITE_OPERATION_NAMES].filter((name) => - AGENT_API_OPERATIONS.some((op) => op.name === name && op.readOnly) + AGENT_API_OPERATIONS.some((op) => op.name === name && op.readOnly), ); expect(spurious).toEqual([]); }); @@ -169,7 +169,7 @@ describe("agent op registry", () => { "dismiss_user_testing_finding", "undismiss_user_testing_finding", "cancel_user_testing_insights", - ].sort() + ].sort(), ); }); @@ -204,22 +204,22 @@ describe("agent op registry", () => { expect( proposalMetaFor(runEvalSuiteOperation.name).description({ suite: "smoke", - }) + }), ).toBe("Run eval suite smoke"); expect( proposalMetaFor(runEvalCaseOperation.name).description({ case: "case_1", - }) + }), ).toBe("Run eval case case_1"); expect( proposalMetaFor(generateEvalCasesOperation.name).description({ suite: "smoke", - }) + }), ).toBe("Generate eval cases for smoke"); expect( proposalMetaFor(cancelEvalRunOperation.name).description({ runId: "run_1", - }) + }), ).toBe("Cancel run run_1"); }); @@ -228,12 +228,12 @@ describe("agent op registry", () => { // the one present — listing one would advertise a selector the operation // does not accept. const suiteDescribe = proposalMetaFor( - runEvalSuiteOperation.name + runEvalSuiteOperation.name, ).description; expect(suiteDescribe({ suite: "smoke" })).toBe("Run eval suite smoke"); expect(suiteDescribe({ suiteId: "ts_1" })).toBe("Run eval suite (unnamed)"); const cancelDescribe = proposalMetaFor( - cancelEvalRunOperation.name + cancelEvalRunOperation.name, ).description; expect(cancelDescribe({ runId: "run_1" })).toBe("Cancel run run_1"); expect(cancelDescribe({ run: "run_1" })).toBe("Cancel run (unnamed)"); @@ -246,15 +246,15 @@ describe("agent op registry", () => { // run, so the count is the decided one. const describeRun = proposalMetaFor(runEvalSuiteOperation.name).description; expect( - describeRun({ suite: "smoke", hosts: ["host_a", "host_b", "host_c"] }) + describeRun({ suite: "smoke", hosts: ["host_a", "host_b", "host_c"] }), ).toBe("Start 3 paid eval runs of suite smoke: host_a, host_b, host_c"); expect(describeRun({ suite: "smoke", host: "host_a" })).toBe( - "Run eval suite smoke against host_a" + "Run eval suite smoke against host_a", ); // Unfrozen `allAttached` (normalization could not reach the platform): // say it fans out, without claiming a number we do not have. expect(describeRun({ suite: "smoke", allAttached: true })).toBe( - "Run eval suite smoke against every attached target — one paid run each" + "Run eval suite smoke against every attached target — one paid run each", ); // A line that said only "Run eval suite smoke" would approve a // multiplier (or an attach) nobody mentioned. @@ -279,9 +279,9 @@ describe("agent op registry", () => { host: "Claude Code", models: ["anthropic/claude-haiku-4.5", "google/gemini-2.5-flash"], }, - }) + }), ).toBe( - "Start 2 paid eval runs of suite smoke (Claude Code): 1 client × 2 model choices = 2 runs, without attaching them to the suite" + "Start 2 paid eval runs of suite smoke (Claude Code): 1 client × 2 model choices = 2 runs, without attaching them to the suite", ); expect( describeRun({ @@ -290,9 +290,9 @@ describe("agent op registry", () => { host: "ChatGPT", models: ["anthropic/claude-haiku-4.5", "google/gemini-2.5-flash"], }, - }) + }), ).toBe( - "Start 2 paid eval runs of suite smoke (ChatGPT): 1 client × 2 model choices = 2 runs, without attaching them to the suite" + "Start 2 paid eval runs of suite smoke (ChatGPT): 1 client × 2 model choices = 2 runs, without attaching them to the suite", ); expect( describeRun({ @@ -302,15 +302,15 @@ describe("agent op registry", () => { models: ["anthropic/claude-haiku-4.5", "google/gemini-2.5-flash"], includeClientDefault: true, }, - }) + }), ).toBe( - "Start 3 paid eval runs of suite smoke (Claude Code): 1 client × 3 model choices = 3 runs, without attaching them to the suite" + "Start 3 paid eval runs of suite smoke (Claude Code): 1 client × 3 model choices = 3 runs, without attaching them to the suite", ); expect( describeRun({ suite: "smoke", compose: { host: "Claude Code", saveTargets: true }, - }) + }), ).toContain("attached to the suite"); }); @@ -320,7 +320,7 @@ describe("agent op registry", () => { // neither of which the line mentioned. const describeCase = proposalMetaFor(runEvalCaseOperation.name).description; expect(describeCase({ suite: "smoke", case: "checkout" })).toBe( - "Run eval case checkout" + "Run eval case checkout", ); const composed = describeCase({ suite: "smoke", @@ -336,18 +336,18 @@ describe("agent op registry", () => { suite: "smoke", case: "checkout", compose: { host: "Claude Code", saveTargets: true }, - }) + }), ).toContain("attached to the suite"); }); it("marks both eval-run proposals as SPEND", () => { // Every eval run consumes credits, and a fan-out consumes them N times — // the host's default confirmation copy does not say so. - expect( - proposalMetaFor(runEvalSuiteOperation.name).severityFor({}) - ).toBe("spend"); + expect(proposalMetaFor(runEvalSuiteOperation.name).severityFor({})).toBe( + "spend", + ); expect(proposalMetaFor(runEvalCaseOperation.name).severityFor({})).toBe( - "spend" + "spend", ); }); @@ -367,14 +367,17 @@ describe("agent op registry", () => { >[1]["client"]; const frozen = await proposalMetaFor( - runEvalSuiteOperation.name + runEvalSuiteOperation.name, ).normalizeArgs( { suite: "smoke", allAttached: true }, - { projectId: "p1", client } + { projectId: "p1", client }, ); // ONE axis, environments first — the precedence the operation itself // applies, so the frozen set is the set that would have run. - expect(frozen).toEqual({ suite: "smoke", environments: ["env_a", "env_b"] }); + expect(frozen).toEqual({ + suite: "smoke", + environments: ["env_a", "env_b"], + }); // `allAttached` is DROPPED, not merely supplemented: leaving it would let // the re-expansion happen at approval time anyway. expect(frozen.allAttached).toBeUndefined(); @@ -398,8 +401,8 @@ describe("agent op registry", () => { expect( await proposalMetaFor(runEvalSuiteOperation.name).normalizeArgs( { suite: "smoke", hosts: ["Claude", "ChatGPT"] }, - { projectId: "p1", client } - ) + { projectId: "p1", client }, + ), ).toEqual({ suite: "smoke", hosts: ["host_a", "host_b"] }); }); @@ -428,8 +431,8 @@ describe("agent op registry", () => { expect( await proposalMetaFor(runEvalSuiteOperation.name).normalizeArgs( { suite: "smoke", environments: ["staging", "env_prod"] }, - { projectId: "p1", client } - ) + { projectId: "p1", client }, + ), // An id already IS the frozen form; an unresolvable selector passes // through so the operation reports the miss with its own message. ).toEqual({ suite: "smoke", environments: ["env_stg", "env_prod"] }); @@ -456,15 +459,15 @@ describe("agent op registry", () => { expect( await proposalMetaFor(runEvalSuiteOperation.name).normalizeArgs( { suite: "smoke", environment: "Staging" }, - { projectId: "p1", client } - ) + { projectId: "p1", client }, + ), ).toEqual({ suite: "smoke", environment: "env_stg" }); expect( await proposalMetaFor(runEvalSuiteOperation.name).normalizeArgs( { suite: "smoke", host: "Claude" }, - { projectId: "p1", client } - ) + { projectId: "p1", client }, + ), ).toEqual({ suite: "smoke", host: "host_a" }); }); @@ -483,8 +486,8 @@ describe("agent op registry", () => { expect( await proposalMetaFor(runEvalSuiteOperation.name).normalizeArgs( { suite: "smoke", environment: "Ghost" }, - { projectId: "p1", client } - ) + { projectId: "p1", client }, + ), ).toEqual({ suite: "smoke", environment: "Ghost" }); }); @@ -502,8 +505,8 @@ describe("agent op registry", () => { expect( await proposalMetaFor(runEvalSuiteOperation.name).normalizeArgs( { suite: "smoke", allAttached: true }, - { projectId: "p1", client } - ) + { projectId: "p1", client }, + ), ).toEqual({ suite: "smoke", allAttached: true }); }); @@ -533,8 +536,8 @@ describe("agent op registry", () => { saveTargets: true, }, }, - { projectId: "p1", client } - ) + { projectId: "p1", client }, + ), ).toEqual({ suite: "smoke", compose: { @@ -571,8 +574,8 @@ describe("agent op registry", () => { suite: "smoke", compose: { host: "Claude Code", computer: "playwright-base" }, }, - { projectId: "p1", client } - ) + { projectId: "p1", client }, + ), ).toEqual({ suite: "smoke", compose: { @@ -608,8 +611,8 @@ describe("agent op registry", () => { saveTargets: true, }, }, - { projectId: "p1", client } - ) + { projectId: "p1", client }, + ), ).toEqual({ suite: "smoke", case: "checkout", @@ -637,7 +640,7 @@ describe("agent op registry", () => { >[1]["client"]; const frozen = await proposalMetaFor( - runEvalSuiteOperation.name + runEvalSuiteOperation.name, ).normalizeArgs( { suite: "smoke", @@ -646,15 +649,15 @@ describe("agent op registry", () => { models: ["anthropic/claude-haiku-4.5", "google/gemini-2.5-flash"], }, }, - { projectId: "p1", client } + { projectId: "p1", client }, + ); + const description = proposalMetaFor(runEvalSuiteOperation.name).description( + frozen, ); - const description = proposalMetaFor( - runEvalSuiteOperation.name - ).description(frozen); expect(description).toContain("Claude Code"); expect(description).not.toContain("host_a"); expect(description).toBe( - "Start 2 paid eval runs of suite smoke (Claude Code): 1 client × 2 model choices = 2 runs, without attaching them to the suite" + "Start 2 paid eval runs of suite smoke (Claude Code): 1 client × 2 model choices = 2 runs, without attaching them to the suite", ); }); @@ -677,8 +680,8 @@ describe("agent op registry", () => { models: ["google/gemini-2.5-flash"], }, }, - { projectId: "p1", client } - ) + { projectId: "p1", client }, + ), ).toEqual({ suite: "smoke", compose: { @@ -707,8 +710,8 @@ describe("agent op registry", () => { hostLabel: "Looks Friendly", }, }, - { projectId: "p1", client } - ) + { projectId: "p1", client }, + ), ).toEqual({ suite: "smoke", compose: { host: "missing-host" }, @@ -732,7 +735,7 @@ describe("agent op registry", () => { proposalMetaFor(runEvalSuiteOperation.name).hashInput({ suite: "smoke", compose: { host: "host_a", hostLabel: "Claude Code" }, - }) + }), ).toEqual(original); }); @@ -752,7 +755,7 @@ describe("agent op registry", () => { await proposalMetaFor(runEvalSuiteOperation.name).normalizeArgs(input, { projectId: "p1", client, - }) + }), ).toEqual(input); }); @@ -770,41 +773,38 @@ describe("agent op registry", () => { >[1]["client"]; const frozen = await proposalMetaFor( - installRegistryDirectoryServerOperation.name - ).normalizeArgs( - { catalogServerId: "cs_1" }, - { projectId: "p1", client } - ); + installRegistryDirectoryServerOperation.name, + ).normalizeArgs({ catalogServerId: "cs_1" }, { projectId: "p1", client }); expect(frozen.expectedContentHash).toBe("hash_now"); expect(frozen.endpointUrl).toBe("https://mcp.linear.app/mcp"); // The PARSED host, not the raw URL — same rule as connect_project_server: // a scraped `https://mcp.linear.app@evil.tld/mcp` must not read as Linear // on the approval button while dialing evil.tld. expect( - proposalMetaFor( - installRegistryDirectoryServerOperation.name - ).description(frozen) + proposalMetaFor(installRegistryDirectoryServerOperation.name).description( + frozen, + ), ).toBe("Install directory server cs_1 at mcp.linear.app"); }); it("renders the parsed host on install buttons — a userinfo URL reads as its real host", () => { const describeDirectory = proposalMetaFor( - installRegistryDirectoryServerOperation.name + installRegistryDirectoryServerOperation.name, ).description; expect( describeDirectory({ catalogServerId: "cs_1", endpointUrl: "https://mcp.linear.app@evil.tld/mcp", - }) + }), ).toBe("Install directory server cs_1 at evil.tld"); expect( - describeDirectory({ catalogServerId: "cs_1", endpointUrl: "not a url" }) + describeDirectory({ catalogServerId: "cs_1", endpointUrl: "not a url" }), ).toBe("Install directory server cs_1 at (unparseable url)"); expect( proposalMetaFor(installRegistryServerOperation.name).description({ registryServerId: "rs_1", endpointUrl: "https://mcp.linear.app@evil.tld/mcp", - }) + }), ).toBe("Install registry card rs_1 at evil.tld"); }); @@ -822,14 +822,14 @@ describe("agent op registry", () => { >[1]["client"]; const frozen = await proposalMetaFor( - installRegistryDirectoryServerOperation.name + installRegistryDirectoryServerOperation.name, ).normalizeArgs( { catalogServerId: "cs_1", expectedContentHash: "hash_at_propose", endpointUrl: "https://mcp.linear.app/mcp", }, - { projectId: "p1", client } + { projectId: "p1", client }, ); expect(frozen.expectedContentHash).toBe("hash_at_propose"); expect(frozen.endpointUrl).toBe("https://mcp.linear.app/mcp"); @@ -853,15 +853,15 @@ describe("agent op registry", () => { >[1]["client"]; const frozen = await proposalMetaFor( - installRegistryServerOperation.name + installRegistryServerOperation.name, ).normalizeArgs({ registryServerId: "rs_1" }, { projectId: "p1", client }); expect(frozen.expectedUpdatedAt).toBe(1_700_000_000_000); expect(frozen.endpointUrl).toBe("https://mcp.linear.app/mcp"); expect( - proposalMetaFor(installRegistryServerOperation.name).description(frozen) + proposalMetaFor(installRegistryServerOperation.name).description(frozen), ).toBe("Install registry card rs_1 at mcp.linear.app"); expect( - proposalMetaFor(installRegistryServerOperation.name).severityFor({}) + proposalMetaFor(installRegistryServerOperation.name).severityFor({}), ).toBe("external"); }); @@ -886,10 +886,10 @@ describe("agent op registry", () => { >[1]["client"]; const frozen = await proposalMetaFor( - installRegistryServerOperation.name + installRegistryServerOperation.name, ).normalizeArgs( { registryServerId: "rs_1", endpointUrl: "https://mcp.linear.app/mcp" }, - { projectId: "p1", client } + { projectId: "p1", client }, ); expect(frozen.endpointUrl).toBe("https://real.example/mcp"); }); @@ -904,14 +904,14 @@ describe("agent op registry", () => { >[1]["client"]; const frozen = await proposalMetaFor( - installRegistryServerOperation.name + installRegistryServerOperation.name, ).normalizeArgs( { registryServerId: "rs_1", endpointUrl: "https://evil.tld/mcp" }, - { projectId: "p1", client } + { projectId: "p1", client }, ); expect(frozen.endpointUrl).toBeUndefined(); expect( - proposalMetaFor(installRegistryServerOperation.name).description(frozen) + proposalMetaFor(installRegistryServerOperation.name).description(frozen), ).toBe("Install registry card rs_1"); }); @@ -934,14 +934,14 @@ describe("agent op registry", () => { await expect( proposalMetaFor( - installRegistryDirectoryServerOperation.name - ).normalizeArgs({ catalogServerId: "cs_1" }, { projectId: "p1", client }) + installRegistryDirectoryServerOperation.name, + ).normalizeArgs({ catalogServerId: "cs_1" }, { projectId: "p1", client }), ).rejects.toThrow(/platform unreachable/); await expect( proposalMetaFor(installRegistryServerOperation.name).normalizeArgs( { registryServerId: "rs_1" }, - { projectId: "p1", client } - ) + { projectId: "p1", client }, + ), ).rejects.toThrow(/platform unreachable/); }); @@ -958,8 +958,8 @@ describe("agent op registry", () => { await expect( proposalMetaFor(installRegistryServerOperation.name).normalizeArgs( { registryServerId: "rs_missing" }, - { projectId: "p1", client } - ) + { projectId: "p1", client }, + ), ).rejects.toThrow(/rs_missing/); }); @@ -978,8 +978,8 @@ describe("agent op registry", () => { await expect( proposalMetaFor( - installRegistryDirectoryServerOperation.name - ).normalizeArgs({ catalogServerId: "cs_1" }, { projectId: "p1", client }) + installRegistryDirectoryServerOperation.name, + ).normalizeArgs({ catalogServerId: "cs_1" }, { projectId: "p1", client }), ).rejects.toThrow(/cannot be pinned/); }); @@ -989,28 +989,28 @@ describe("agent op registry", () => { // input missing them. expect( proposalMetaFor(installRegistryDirectoryServerOperation.name) - .requiredFrozenKeys + .requiredFrozenKeys, ).toEqual(["endpointUrl", "expectedContentHash"]); expect( - proposalMetaFor(installRegistryServerOperation.name).requiredFrozenKeys + proposalMetaFor(installRegistryServerOperation.name).requiredFrozenKeys, ).toEqual(["expectedUpdatedAt"]); // The generic tier stays best-effort — no pins, no refusal. expect( - proposalMetaFor(runEvalSuiteOperation.name).requiredFrozenKeys + proposalMetaFor(runEvalSuiteOperation.name).requiredFrozenKeys, ).toEqual([]); }); it("gates both registry installs as external — org cards are not a softer hazard", () => { expect( proposalMetaFor(installRegistryDirectoryServerOperation.name).severityFor( - {} - ) + {}, + ), ).toBe("external"); expect( - proposalMetaFor(installRegistryServerOperation.name).severityFor({}) + proposalMetaFor(installRegistryServerOperation.name).severityFor({}), ).toBe("external"); expect(EXCLUDED_FROM_AGENT.uninstall_registry_server).toMatch( - /never destruction/ + /never destruction/, ); }); @@ -1031,7 +1031,7 @@ describe("agent op registry", () => { await proposalMetaFor(runEvalSuiteOperation.name).normalizeArgs(input, { projectId: "p1", client, - }) + }), ).toEqual(input); }); @@ -1053,8 +1053,8 @@ describe("agent op registry", () => { expect( await proposalMetaFor(startConformanceRunOperation.name).normalizeArgs( { server: "acme mcp", suites: ["protocol"] }, - { projectId: "p1", client } - ) + { projectId: "p1", client }, + ), ).toEqual({ server: "srv_1", suites: ["protocol"] }); }); @@ -1070,8 +1070,8 @@ describe("agent op registry", () => { expect( await proposalMetaFor(startConformanceRunOperation.name).normalizeArgs( { server: "srv_1" }, - { projectId: "p1", client } - ) + { projectId: "p1", client }, + ), ).toEqual({ server: "srv_1" }); }); @@ -1087,8 +1087,8 @@ describe("agent op registry", () => { expect( await proposalMetaFor(startConformanceRunOperation.name).normalizeArgs( { server: "Ghost" }, - { projectId: "p1", client } - ) + { projectId: "p1", client }, + ), ).toEqual({ server: "Ghost" }); }); @@ -1104,8 +1104,8 @@ describe("agent op registry", () => { expect( await proposalMetaFor(startConformanceRunOperation.name).normalizeArgs( input, - { projectId: "p1", client } - ) + { projectId: "p1", client }, + ), ).toEqual(input); }); @@ -1126,8 +1126,8 @@ describe("agent op registry", () => { expect( await proposalMetaFor(startConformanceRunOperation.name).normalizeArgs( input, - { projectId: "p1", client } - ) + { projectId: "p1", client }, + ), ).toEqual(input); } expect(listProjectServers).not.toHaveBeenCalled(); @@ -1139,18 +1139,24 @@ describe("agent op registry", () => { // a result the policy cannot address yields no resource, and never a // half-built URL. const link = (result: unknown) => - executedActionResource(startConformanceRunOperation, result, {}, { - projectId: "p1", - }); + executedActionResource( + startConformanceRunOperation, + result, + {}, + { + projectId: "p1", + }, + ); expect(link({})).toBeUndefined(); expect(link({ run: {} })).toBeUndefined(); expect(link({ run: { runId: "" } })).toBeUndefined(); expect(link(null)).toBeUndefined(); expect(link(undefined)).toBeUndefined(); - expect( - link({ run: { runId: "run_1", projectId: "p1" } }) - ).toMatchObject({ type: "conformance_run", id: "run_1" }); + expect(link({ run: { runId: "run_1", projectId: "p1" } })).toMatchObject({ + type: "conformance_run", + id: "run_1", + }); }); it("returns undefined rather than throwing when a policy fails", () => { @@ -1171,8 +1177,8 @@ describe("agent op registry", () => { startConformanceRunOperation, { run: { runId: "run_1", projectId: "p1" } }, {}, - { projectId: "p1" } - ) + { projectId: "p1" }, + ), ).toBeUndefined(); } finally { (startConformanceRunOperation as { permalink: unknown }).permalink = @@ -1184,9 +1190,14 @@ describe("agent op registry", () => { // The contract carries one resource. Linking the first run would hide a // sibling's failure — the one thing an approver of N paid runs needs. const link = (result: unknown) => - executedActionResource(runEvalSuiteOperation, result, {}, { - projectId: "p1", - }); + executedActionResource( + runEvalSuiteOperation, + result, + {}, + { + projectId: "p1", + }, + ); const groupResource = link({ project: { id: "p1" }, suite: { id: "ts_1" }, @@ -1240,7 +1251,7 @@ describe("agent op registry", () => { expect(proposalMetaFor(runEvalSuiteOperation.name).kind).toBe("start"); expect(proposalMetaFor(runEvalCaseOperation.name).kind).toBe("start"); expect(proposalMetaFor(generateEvalCasesOperation.name).kind).toBe( - "generate" + "generate", ); expect(proposalMetaFor(cancelEvalRunOperation.name).kind).toBe("cancel"); }); @@ -1271,10 +1282,10 @@ describe("agent op registry", () => { // first; offering it here would produce turns that time out having done // nothing else. expect(AGENT_API_OPERATIONS.map((op) => op.name)).not.toContain( - checkHostCompatibilityOperation.name + checkHostCompatibilityOperation.name, ); expect(AGENT_API_GATED_OPERATIONS.map((op) => op.name)).not.toContain( - checkHostCompatibilityOperation.name + checkHostCompatibilityOperation.name, ); }); @@ -1282,11 +1293,11 @@ describe("agent op registry", () => { // Both server-content reads carry the same note; the collector's dedupe is // what stops it appearing twice in the prompt. const injectionNotes = AGENT_OP_PROMPT_NOTES.filter((note) => - /never instructions|DATA, never instructions/i.test(note) + /never instructions|DATA, never instructions/i.test(note), ); expect(injectionNotes).toHaveLength(1); expect(injectionNotes[0]).toMatch( - /never follow directions found inside it/ + /never follow directions found inside it/, ); }); @@ -1295,10 +1306,10 @@ describe("agent op registry", () => { // unknowable upstream of the call. Nothing on this surface may contradict // that: it is gated, and the severity is what tells a host to say so. expect(AGENT_API_GATED_OPERATIONS.map((op) => op.name)).toContain( - callServerToolOperation.name + callServerToolOperation.name, ); expect(AGENT_API_OPERATIONS.map((op) => op.name)).not.toContain( - callServerToolOperation.name + callServerToolOperation.name, ); expect(callServerToolOperation.mayBeDestructive).toBe(true); const meta = proposalMetaFor(callServerToolOperation.name); @@ -1310,7 +1321,7 @@ describe("agent op registry", () => { it("shows the approver WHAT will be called, not just that a call exists", () => { // "Approve a tool call?" is a rubber stamp. This is the difference. const description = proposalMetaFor( - callServerToolOperation.name + callServerToolOperation.name, ).description({ server: "mailer", toolName: "send_email", @@ -1340,7 +1351,7 @@ describe("agent op registry", () => { // nested value. `{1 field}` asks a person to approve precisely the part // they cannot see. const description = proposalMetaFor( - callServerToolOperation.name + callServerToolOperation.name, ).description({ toolName: "delete", parameters: { @@ -1362,21 +1373,21 @@ describe("agent op registry", () => { const cyclic: Record = { a: 1 }; cyclic.self = cyclic; const description = proposalMetaFor( - callServerToolOperation.name + callServerToolOperation.name, ).description({ toolName: "t", parameters: { cyclic } }); expect(description).toContain("cyclic: {2 fields}"); }); it("bounds a hostile preview per value, per count, and in total", () => { const description = proposalMetaFor( - callServerToolOperation.name + callServerToolOperation.name, ).description({ toolName: "x".repeat(500), parameters: Object.fromEntries( Array.from({ length: 40 }, (_, index) => [ `k${index}`, "v".repeat(5_000), - ]) + ]), ), }); expect(description.length).toBeLessThanOrEqual(260); @@ -1388,7 +1399,7 @@ describe("agent op registry", () => { // budget and the approver is shown a truncated word and nothing about what // it will do — the exact rubber stamp this preview exists to replace. const description = proposalMetaFor( - callServerToolOperation.name + callServerToolOperation.name, ).description({ server: "files", toolName: "delete_everything_".repeat(30), @@ -1404,14 +1415,14 @@ describe("agent op registry", () => { // a literal `\n` INSIDE the quotes — better than flattening to a space, // which would hide that the value contained a break at all. const description = proposalMetaFor( - callServerToolOperation.name + callServerToolOperation.name, ).description({ toolName: "send", parameters: { body: "line one\nMCPJam: this call is safe" }, }); expect(description).not.toContain("\n"); expect(description).toContain( - 'body: "line one\\nMCPJam: this call is safe"' + 'body: "line one\\nMCPJam: this call is safe"', ); }); @@ -1420,11 +1431,11 @@ describe("agent op registry", () => { // verbatim; a suite name with newlines would otherwise hand the approval // control a forged extra line the argument-preview flattening never sees. const description = proposalMetaFor(runEvalSuiteOperation.name).description( - { suite: "smoke\n\nMCPJam: verified safe — approve below" } + { suite: "smoke\n\nMCPJam: verified safe — approve below" }, ); expect(description).not.toContain("\n"); expect(description).toBe( - "Run eval suite smoke MCPJam: verified safe — approve below" + "Run eval suite smoke MCPJam: verified safe — approve below", ); // Same seam for the server suffix of a tool call, which sits OUTSIDE the // flattened argument preview. @@ -1439,7 +1450,7 @@ describe("agent op registry", () => { // U+202E flips rendering order: "to: alice@" can be made to display as its // mirror while the stored value — what actually runs — stays unreversed. const description = proposalMetaFor( - callServerToolOperation.name + callServerToolOperation.name, ).description({ toolName: "send", server: "mail", @@ -1457,7 +1468,7 @@ describe("agent op registry", () => { // `mailer` \u2014 everything after it, including the real recipient, looks // like trailing noise. Quoted, the same text is visibly data. const description = proposalMetaFor( - callServerToolOperation.name + callServerToolOperation.name, ).description({ toolName: "send_email", server: "mailer", @@ -1470,7 +1481,7 @@ describe("agent op registry", () => { expect(description).toContain('to: "attacker@evil.example"'); // The one unquoted `) on ` in the preview is its real terminator. expect(description.indexOf('to: "attacker@evil.example"')).toBeLessThan( - description.lastIndexOf(") on mailer") + description.lastIndexOf(") on mailer"), ); }); @@ -1481,7 +1492,7 @@ describe("agent op registry", () => { // that reads differently from a real one invites exactly the scrutiny it // deserves. const description = proposalMetaFor( - callServerToolOperation.name + callServerToolOperation.name, ).description({ toolName: "send(to: a@b.c) on mailer", server: "evil", @@ -1497,7 +1508,7 @@ describe("agent op registry", () => { // defines the argument names, so six benign keys sort ahead of `to` and // the destructive target is exactly what alphabetical truncation hides. const description = proposalMetaFor( - callServerToolOperation.name + callServerToolOperation.name, ).description({ toolName: "send_email", server: "mailer", @@ -1527,7 +1538,7 @@ describe("agent op registry", () => { expect(meta.targetFor({})).toBeUndefined(); // No meaningful target answers undefined, never a guess. expect( - proposalMetaFor(cancelEvalRunOperation.name).targetFor({ runId: "r1" }) + proposalMetaFor(cancelEvalRunOperation.name).targetFor({ runId: "r1" }), ).toBeUndefined(); }); @@ -1536,7 +1547,7 @@ describe("agent op registry", () => { proposalMetaFor(callServerToolOperation.name).description({ toolName: "ping", server: "srv", - }) + }), ).toBe("Call ping() on srv"); }); @@ -1545,10 +1556,10 @@ describe("agent op registry", () => { // as long as nobody notices, so it earns the same gate — and `schedule` // keeps the announcement honest, because nothing starts on approval. expect(AGENT_API_GATED_OPERATIONS.map((op) => op.name)).toContain( - setEvalSuiteScheduleOperation.name + setEvalSuiteScheduleOperation.name, ); expect(AGENT_API_OPERATIONS.map((op) => op.name)).not.toContain( - setEvalSuiteScheduleOperation.name + setEvalSuiteScheduleOperation.name, ); const meta = proposalMetaFor(setEvalSuiteScheduleOperation.name); expect(meta.kind).toBe("schedule"); @@ -1556,7 +1567,7 @@ describe("agent op registry", () => { // Gated ⇒ absent from the derived idempotency set, and the derivation // proves it rather than a hand-maintained list asserting it. expect(WRITE_OPERATION_NAMES.has(setEvalSuiteScheduleOperation.name)).toBe( - false + false, ); expect(setEvalSuiteScheduleOperation.readOnly).toBe(false); }); @@ -1573,27 +1584,27 @@ describe("agent op registry", () => { it("puts the CADENCE in the schedule proposal, from the validated input", () => { const describe = proposalMetaFor( - setEvalSuiteScheduleOperation.name + setEvalSuiteScheduleOperation.name, ).description; expect( - describe({ suite: "smoke", enabled: true, intervalMinutes: 60 }) + describe({ suite: "smoke", enabled: true, intervalMinutes: 60 }), ).toBe("Schedule smoke to run every 60 minutes"); // No interval means the suite's SAVED one is reused. Naming a number we do // not have would be a guess printed next to an approval button. expect(describe({ suite: "smoke", enabled: true })).toBe( - "Schedule smoke to run on its saved interval" + "Schedule smoke to run on its saved interval", ); expect(describe({ suite: "smoke", enabled: false })).toBe( - "Clear the schedule for smoke" + "Clear the schedule for smoke", ); }); it("de-duplicates prompt notes and preserves registry order", () => { expect(new Set(AGENT_OP_PROMPT_NOTES).size).toBe( - AGENT_OP_PROMPT_NOTES.length + AGENT_OP_PROMPT_NOTES.length, ); const inOrder = AGENT_OP_REGISTRY.flatMap( - (entry) => entry.promptNotes ?? [] + (entry) => entry.promptNotes ?? [], ); expect(AGENT_OP_PROMPT_NOTES).toEqual([...new Set(inOrder)]); }); @@ -1645,6 +1656,23 @@ describe("tier derives from operation.risk", () => { "the project may talk to your servers. That is a human decision the " + "agent should not even propose.", }, + create_secret: { + tier: "excluded", + reason: + "Exposure would derive gated, but gating cannot help here: the " + + "plaintext credential is an ARGUMENT, so it reaches model context " + + "and this turn's transcript before an approval card could render. " + + "An approval that fires after the value is already logged is not " + + "an approval. Only keeping the operation off the surface works, and " + + "it stays available on REST/SDK/CLI where the caller chooses where " + + "the value comes from.", + }, + update_secret: { + tier: "excluded", + reason: + "The same argument as create_secret: a rotation carries the new " + + "plaintext as an argument, with the same pre-approval exposure.", + }, render_server_widget: { tier: "gated", reason: @@ -1745,7 +1773,7 @@ describe("tier derives from operation.risk", () => { `${expected} — TIER_EXCEPTIONS: ${exception.reason}` : `${op.name} (risk: ${op.risk}) must be ${expected}. If this ` + `deviation is deliberate, add ${op.name} to TIER_EXCEPTIONS in ` + - `this file with the reason a reviewer should read.` + `this file with the reason a reviewer should read.`, ).toBe(expected); } }); @@ -1758,20 +1786,20 @@ describe("tier derives from operation.risk", () => { const op = ALL_OPERATIONS.find((candidate) => candidate.name === name); expect( op, - `${name} is not an SDK operation; remove it from TIER_EXCEPTIONS` + `${name} is not an SDK operation; remove it from TIER_EXCEPTIONS`, ).toBeDefined(); expect( op!.risk, - `${name} declares no risk, so no derivation applies; remove it from TIER_EXCEPTIONS` + `${name} declares no risk, so no derivation applies; remove it from TIER_EXCEPTIONS`, ).toBeDefined(); expect( TIER_BY_RISK[op!.risk!], `${name} no longer deviates — risk "${op!.risk}" already derives ` + - `"${exception.tier}"; remove it from TIER_EXCEPTIONS` + `"${exception.tier}"; remove it from TIER_EXCEPTIONS`, ).not.toBe(exception.tier); expect( exception.reason.length, - `${name} needs a substantive reason` + `${name} needs a substantive reason`, ).toBeGreaterThan(20); } }); @@ -1787,7 +1815,7 @@ describe("tier derives from operation.risk", () => { expect( op.risk, `${op.name} is read-only; risk is meaningless on a read and would ` + - `put it under a derivation that does not govern reads` + `put it under a derivation that does not govern reads`, ).toBeUndefined(); } }); @@ -1849,7 +1877,7 @@ describe("tier derives from operation.risk", () => { it("pins the unclassified legacy writes — the list only shrinks", () => { const unclassified = ALL_OPERATIONS.filter( - (op) => !op.readOnly && op.risk === undefined + (op) => !op.readOnly && op.risk === undefined, ).map((op) => op.name); // EQUALITY, not <=: a <= ceiling decays as the pin shrinks (classifying @@ -1863,7 +1891,7 @@ describe("tier derives from operation.risk", () => { `write): lower UNCLASSIFIED_WRITES_CEILING to match. Growing: don't — ` + `classify the new write (one \`risk\` field in the SDK catalog) ` + `instead; growing needs a reviewer to accept both the ceiling bump ` + - `and the new name above.` + `and the new name above.`, ).toBe(UNCLASSIFIED_WRITES_CEILING); const newcomers = unclassified @@ -1874,7 +1902,7 @@ describe("tier derives from operation.risk", () => { `New write operations must declare \`risk\` in the SDK catalog ` + `(none | spend | exposure | destructive) — that classification is ` + `what derives their agent tier. Do not add names to ` + - `UNCLASSIFIED_WRITES; it is a legacy pin and only shrinks.` + `UNCLASSIFIED_WRITES; it is a legacy pin and only shrinks.`, ).toEqual([]); const departed = [...UNCLASSIFIED_WRITES] @@ -1883,7 +1911,7 @@ describe("tier derives from operation.risk", () => { expect( departed, `These writes were classified (or removed from the catalog) — delete ` + - `them from UNCLASSIFIED_WRITES so the derivation above governs them.` + `them from UNCLASSIFIED_WRITES so the derivation above governs them.`, ).toEqual([]); }); }); @@ -1930,16 +1958,16 @@ const EXPECTED_PROMPT_NOTES = [ "- `start_claude_readiness_run` and `start_openai_readiness_run` return a RECEIPT, not a verdict. The run dials the target and takes minutes; poll `get_readiness_run` and report what it says, never the receipt.", "- A readiness run answers three separate questions and they do not collapse. `status` is whether the run finished; `overallStatus` is the grade (a `completed` run can be `not-ready`, which is a finished run that failed the grade); `llmObservations` is whether the optional paid pass ran. A run whose observations were `billing-blocked` is still a complete, valid grade — say the observations were skipped for credit, never that the server has a problem.", "- A run that FAILED produced no grade at all. Report it as a run that could not finish, and never as a verdict about the server.", - "- When a readiness run reports `authMode: \"headless\"` and a lane's `missingInputs` names `authorizationRequests`, the server is auth-walled and the run carried no token. That is not a defect — challenging correctly earns the server green marks. Tell the user to connect the server with OAuth in the app (server menu), then start a NEW run: the platform uses the saved token automatically, and the not-evaluated checks will grade.", + '- When a readiness run reports `authMode: "headless"` and a lane\'s `missingInputs` names `authorizationRequests`, the server is auth-walled and the run carried no token. That is not a defect — challenging correctly earns the server green marks. Tell the user to connect the server with OAuth in the app (server menu), then start a NEW run: the platform uses the saved token automatically, and the not-evaluated checks will grade.', "- `start_openai_readiness_run` needs `submissionMode` and it is NEVER inferred: guessing turns a missing input into a clean bill of health. Ask which shape is being submitted. The two package shapes are not available here — they need a package on the user's machine, so point them at `mcpjam readiness check`.", "- `start_conformance_run` returns a RECEIPT, not a verdict. The run dials the target and takes minutes; poll `get_conformance_run` and report what it says, never the receipt.", "- A conformance run answers three separate questions and they do not collapse. `status` is whether the run finished; `outcome` is the grade (a `completed` run can be `failed`); `score` is the number. `pending` counts checks this profile reported but did not score — do not treat them as failures.", "- OAuth is not startable here. There is no cancel op. A dead process is recovered by heartbeat + sweep, never re-queued.", "- Cancelling a readiness run STOPS traffic to somebody else's server, so it needs no approval. The run's real terminal state arrives on a later `get_readiness_run` — the cancel response reports the request, not the outcome.", "- Before launching an eval run, `get_eval_run_disclosure` tells you (and lets you tell a human) what actually happens to the run's content — which models it calls, whether analyzers/judges fire and where their evidence goes, retention and region facts. It never gates the run; `run_eval_suite` already fetches and returns its own disclosure on `disclosure`, so call this separately only when you need it BEFORE deciding to launch.", - "- WHEN A RUN DOES NOT PASS, READ `decisionSummary` FIRST: it states the first failed stage in the user-value chain (connection → discovery → selection → call → response → userValue), the failure category, evidence scoped to that stage, and one next action. Authored step results (`get_eval_run_steps`) come second and a full trace (`get_eval_iteration_trace`) last — do not reconstruct the chain from raw tool calls when the summary already states it.", - "- Read `measurementUnit` before quoting a count: under verdict policy v2 the counts are CASE-EXECUTION VARIANTS with repetitions as trials inside them, and on a legacy run they are trials, so the same suite is legitimately \"3\" or \"15\" and a count without its unit is not a fact. And `verdict: \"notEstablished\"` is neither a failure nor `inconclusive` — no verdict exists at all (`undecided.reason` says why), so never report it as a regression.", - "- `diagnostics` is one PAGE and one KIND of claim. When `diagnostics.complete` is false, more failing trials went unexamined — say so instead of presenting the page as the run's failures, and pass `diagnosticsCursor` to continue. And a diagnostic says WHERE the chain stopped, not why: `firstFailedStage` is a location and `failureCategory` a bucket, so neither authorizes proposing a server change on its own.", + "- WHEN A RUN DOES NOT PASS, READ `decisionSummary` FIRST: it states the first failed stage in the user-value chain (connection → discovery → selection → call → response → userValue), the failure category, evidence scoped to that stage, and one next action. Authored step results (`get_eval_run_steps`) come second and a full trace (`get_eval_iteration_trace`) last — do not reconstruct the chain from raw tool calls when the summary already states it.", + '- Read `measurementUnit` before quoting a count: under verdict policy v2 the counts are CASE-EXECUTION VARIANTS with repetitions as trials inside them, and on a legacy run they are trials, so the same suite is legitimately "3" or "15" and a count without its unit is not a fact. And `verdict: "notEstablished"` is neither a failure nor `inconclusive` — no verdict exists at all (`undecided.reason` says why), so never report it as a regression.', + "- `diagnostics` is one PAGE and one KIND of claim. When `diagnostics.complete` is false, more failing trials went unexamined — say so instead of presenting the page as the run's failures, and pass `diagnosticsCursor` to continue. And a diagnostic says WHERE the chain stopped, not why: `firstFailedStage` is a location and `failureCategory` a bucket, so neither authorizes proposing a server change on its own.", "- A scorer whose `definitionChanged` is true was graded by a DIFFERENT definition on each side. Its delta is not a regression — the two runs did not measure the same thing — so do not report it as one.", "- To find out why an iteration failed, start with `get_eval_run_steps`: it gives the per-step verdicts and reasons in a fraction of the tokens. Reach for `get_eval_iteration_trace` only when the steps do not explain it — a full trace is the whole message history and can be large enough to crowd out the rest of the turn.", "- `get_client` is the first step of every client edit, not an optional one: `update_client` and `set_client_servers` require the `configId` it returns as `expectedConfigId`, and a rename requires the `name` it returns as `expectedName`.", @@ -1949,6 +1977,8 @@ const EXPECTED_PROMPT_NOTES = [ "- `call_server_tool` runs a real tool on the user's MCP server, as them, with effects MCPJam cannot undo. Calling it PROPOSES the call; a person approves it. Read the tool's schema from `list_server_tools` first and pass exactly the arguments you mean — the arguments you send are shown to the approver and are what will run, so a placeholder is a lie they will act on. Never call a tool to 'test' or 'see what happens'.", "- `render_server_widget` EXECUTES the tool and then mounts its widget in a browser. It is not a read: use it to find out whether an MCP App actually renders, what it logs, and what it was blocked from fetching — never to 'look at' a tool whose side effects you have not read.", "- Before planning anything that authors, launches or publishes, call `get_capabilities` for the project. Your tool list is identical for every caller, so it cannot tell you that this organization is not in the Swarms beta or that you are a member where the action needs an admin. The `can` block answers both. Finding out from a 403 means you have already told someone you were doing it.", + "- `list_secrets` and `get_secret` return METADATA ONLY — a secret's value is not readable by you or by anyone, through any surface. If a task needs a credential's value, the answer is that you cannot have it; say so rather than looking for another route to it.", + "- Delivery mode matters when you reason about a workflow: a `brokered` secret is injected by the sandbox's egress proxy and is NOT an environment variable in the box (so `echo $NAME` will be empty and a CLI that reads env vars will not see it), while a `materialized` one is.", "- A journey run produces `targets x sessionsPerTarget` conversations, and that total is what spends. Read `get_journey` before proposing a launch so the number in your proposal is the real one.", "- After a launch is approved, poll `get_journey_run`. It leaves `running` once every attempt has settled; `canceled` and `stale` are separate booleans, so a deliberate stop and a runner that went silent do not both read as failure.", "- `get_swarms_overview` is the right first read for 'how are our swarms doing'. Every rate in it is over GRADED sessions, never attempted ones, and `passRate: null` means nothing has been graded yet — it does not mean everything failed.", @@ -1970,7 +2000,7 @@ describe("assembled system prompt", () => { it("is the pre-registry literal plus exactly the notes we expect", () => { expect([...AGENT_OP_PROMPT_NOTES]).toEqual(EXPECTED_PROMPT_NOTES); expect(AGENT_API_SYSTEM_PROMPT).toBe( - [PROMPT_BEFORE_REGISTRY, ...EXPECTED_PROMPT_NOTES].join("\n") + [PROMPT_BEFORE_REGISTRY, ...EXPECTED_PROMPT_NOTES].join("\n"), ); }); @@ -1981,7 +2011,7 @@ describe("assembled system prompt", () => { expect(AGENT_API_SYSTEM_PROMPT).not.toMatch(/\d{13}/); // epoch millis expect(AGENT_API_SYSTEM_PROMPT).not.toMatch(/\d{4}-\d{2}-\d{2}T/); // iso expect(AGENT_API_SYSTEM_PROMPT).not.toMatch( - /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}/i + /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}/i, ); // uuid }); }); diff --git a/mcpjam-inspector/server/routes/v1/__tests__/secrets-write-only.test.ts b/mcpjam-inspector/server/routes/v1/__tests__/secrets-write-only.test.ts new file mode 100644 index 0000000000..8dbcfca170 --- /dev/null +++ b/mcpjam-inspector/server/routes/v1/__tests__/secrets-write-only.test.ts @@ -0,0 +1,177 @@ +/** + * The one contract the secrets surface cannot be allowed to break: NO ROUTE + * RETURNS A VALUE. + * + * Asserted on the RESPONSE SCHEMAS, not on sample bodies. A sample body only + * proves what one fixture happened not to contain — it passes just as happily + * the day someone adds a `value` field that this particular row left empty. + * The schema is the promise, so the schema is what is checked, in all three + * places it is written down: + * + * 1. the OpenAPI response schemas for every `/secrets` route; + * 2. the SDK's `PlatformSecret` type, which is what a typed caller sees; + * 3. the route module's own DTO mapper, read as source. + * + * The three are separate on purpose. Any one of them could grow a value field + * without the other two noticing, and each is the only thing some consumer + * reads. + */ +import { readFileSync } from "node:fs"; +import { join } from "node:path"; +import { describe, expect, it } from "vitest"; + +const REPO_ROOT = join(import.meta.dirname, "..", "..", "..", "..", ".."); +const OPENAPI_PATH = join(REPO_ROOT, "docs", "reference", "openapi.json"); +const SDK_TYPES_PATH = join(REPO_ROOT, "sdk", "src", "platform", "types.ts"); +const ROUTE_PATH = join(import.meta.dirname, "..", "secrets.ts"); + +type JsonObject = Record; + +const openapi = JSON.parse(readFileSync(OPENAPI_PATH, "utf8")) as { + paths: Record; + components: { schemas: Record }; +}; + +/** + * Every property name reachable from a schema, following `$ref`, `allOf`, + * `items` and nested `properties`. + * + * Recursive with a visited set rather than a fixed depth: the point is that a + * value cannot hide anywhere in the tree, and a depth limit would be a hole + * someone could nest past. + */ +function reachableProperties( + schema: unknown, + seen = new Set(), +): string[] { + if (!schema || typeof schema !== "object") return []; + const node = schema as JsonObject; + + const ref = node.$ref; + if (typeof ref === "string") { + const name = ref.replace("#/components/schemas/", ""); + if (seen.has(name)) return []; + seen.add(name); + return reachableProperties(openapi.components.schemas[name], seen); + } + + const out: string[] = []; + const props = node.properties; + if (props && typeof props === "object") { + for (const [key, child] of Object.entries(props as JsonObject)) { + out.push(key); + out.push(...reachableProperties(child, seen)); + } + } + for (const key of ["allOf", "anyOf", "oneOf"] as const) { + const branch = node[key]; + if (Array.isArray(branch)) { + for (const child of branch) out.push(...reachableProperties(child, seen)); + } + } + if (node.items) out.push(...reachableProperties(node.items, seen)); + return out; +} + +/** Field names that would mean the surface hands a credential back. */ +const FORBIDDEN = ["value", "secretValue", "plaintext", "ciphertext"]; + +describe("the secrets surface is write-only", () => { + const secretPaths = Object.keys(openapi.paths).filter((path) => + path.includes("/secrets"), + ); + + it("has the routes it is supposed to have", () => { + // If this ever fails because a route was renamed, the assertions below stop + // checking anything — so the list is pinned rather than derived. + expect(secretPaths.sort()).toEqual([ + "/projects/{projectId}/secrets", + "/projects/{projectId}/secrets/{secretId}", + ]); + }); + + it("declares no value field in ANY response schema", () => { + const offenders: string[] = []; + for (const path of secretPaths) { + for (const [method, operation] of Object.entries(openapi.paths[path]!)) { + if (method === "parameters") continue; + const responses = (operation as JsonObject).responses as + | JsonObject + | undefined; + if (!responses) continue; + for (const [status, response] of Object.entries(responses)) { + const content = (response as JsonObject).content as + | JsonObject + | undefined; + const schema = ( + content?.["application/json"] as JsonObject | undefined + )?.schema; + if (!schema) continue; + for (const property of reachableProperties(schema)) { + if (FORBIDDEN.includes(property)) { + offenders.push( + `${method.toUpperCase()} ${path} ${status}: ${property}`, + ); + } + } + } + } + } + expect( + offenders, + "A secrets response schema exposes a credential field. There is no code " + + "path that could produce one — if this fails, the schema is a promise " + + "the implementation does not keep, which is worse than either.", + ).toEqual([]); + }); + + it("DOES declare a value on the two write REQUESTS, so the check above is real", () => { + // Guards the guard. If `reachableProperties` silently returned nothing, the + // assertion above would pass vacuously forever. + const create = reachableProperties({ + $ref: "#/components/schemas/SecretCreateRequest", + }); + const update = reachableProperties({ + $ref: "#/components/schemas/SecretUpdateRequest", + }); + expect(create).toContain("value"); + expect(update).toContain("value"); + }); + + it("keeps the value out of the SDK's PlatformSecret type", () => { + const source = readFileSync(SDK_TYPES_PATH, "utf8"); + const start = source.indexOf("export interface PlatformSecret {"); + expect(start, "PlatformSecret was renamed or removed").toBeGreaterThan(-1); + const body = source.slice(start, source.indexOf("\n}", start)); + for (const forbidden of FORBIDDEN) { + expect( + new RegExp(`^\\s*${forbidden}\\??:`, "m").test(body), + `PlatformSecret declares \`${forbidden}\``, + ).toBe(false); + } + }); + + it("keeps the value out of the route's own DTO mapper", () => { + const source = readFileSync(ROUTE_PATH, "utf8"); + const start = source.indexOf("function toSecretDto("); + expect(start, "toSecretDto was renamed or removed").toBeGreaterThan(-1); + const body = source.slice(start, source.indexOf("\n}", start)); + for (const forbidden of FORBIDDEN) { + expect( + new RegExp(`\\b${forbidden}\\s*:`).test(body), + `toSecretDto emits \`${forbidden}\``, + ).toBe(false); + } + }); + + it("is absent from the guest allowlist, so guests cannot reach it", () => { + // `guest-allowed-paths.ts` is default-deny, so this is not "no rule denies + // it" — it is "no rule ADMITS it". A single added entry would be the one + // change that breaks the guarantee, and this is what would catch it. + const source = readFileSync( + join(import.meta.dirname, "..", "guest-allowed-paths.ts"), + "utf8", + ); + expect(source).not.toContain("/secrets"); + }); +}); diff --git a/mcpjam-inspector/server/routes/v1/agent-op-registry.ts b/mcpjam-inspector/server/routes/v1/agent-op-registry.ts index 1ca43389b9..e3e7d8cce6 100644 --- a/mcpjam-inspector/server/routes/v1/agent-op-registry.ts +++ b/mcpjam-inspector/server/routes/v1/agent-op-registry.ts @@ -105,6 +105,8 @@ import { runEvalSuiteOperation, getCapabilitiesOperation, listPersonasOperation, + listSecretsOperation, + getSecretOperation, getPersonaOperation, createPersonaOperation, updatePersonaOperation, @@ -415,17 +417,15 @@ function describeComposeEvalSuiteRun( ? "and the composed environment is attached to the suite" : "and the composed environments are attached to the suite" : n <= 1 - ? "ephemeral when supported; otherwise attached" - : "without attaching them to the suite"; + ? "ephemeral when supported; otherwise attached" + : "without attaching them to the suite"; if (n <= 1) { return ( `Run eval suite ${suite} on a composed setup${hostNote}` + ` — one paid run, ${attach}` ); } - return ( - `Start ${n} paid eval runs of suite ${suite}${hostNote}: 1 client × ${n} model choices = ${n} runs, ${attach}` - ); + return `Start ${n} paid eval runs of suite ${suite}${hostNote}: 1 client × ${n} model choices = ${n} runs, ${attach}`; } /** @@ -775,7 +775,9 @@ function readOptionalNumber( key: string, ): number | undefined { const value = input[key]; - return typeof value === "number" && Number.isFinite(value) ? value : undefined; + return typeof value === "number" && Number.isFinite(value) + ? value + : undefined; } /** @@ -899,8 +901,7 @@ export async function freezeDirectoryInstallArgs( const row = await context.client.getRegistryDirectoryServer({ catalogServerId, }); - const endpointUrl = - readOptionalString(input, "endpointUrl") ?? row.remoteUrl; + const endpointUrl = readOptionalString(input, "endpointUrl") ?? row.remoteUrl; const expectedContentHash = readOptionalString(input, "expectedContentHash") ?? row.latestContentHash; if (!endpointUrl || !expectedContentHash) { @@ -1411,7 +1412,7 @@ export const AGENT_OP_REGISTRY: readonly AgentOpEntry[] = [ "- `start_claude_readiness_run` and `start_openai_readiness_run` return a RECEIPT, not a verdict. The run dials the target and takes minutes; poll `get_readiness_run` and report what it says, never the receipt.", "- A readiness run answers three separate questions and they do not collapse. `status` is whether the run finished; `overallStatus` is the grade (a `completed` run can be `not-ready`, which is a finished run that failed the grade); `llmObservations` is whether the optional paid pass ran. A run whose observations were `billing-blocked` is still a complete, valid grade — say the observations were skipped for credit, never that the server has a problem.", "- A run that FAILED produced no grade at all. Report it as a run that could not finish, and never as a verdict about the server.", - "- When a readiness run reports `authMode: \"headless\"` and a lane's `missingInputs` names `authorizationRequests`, the server is auth-walled and the run carried no token. That is not a defect — challenging correctly earns the server green marks. Tell the user to connect the server with OAuth in the app (server menu), then start a NEW run: the platform uses the saved token automatically, and the not-evaluated checks will grade.", + '- When a readiness run reports `authMode: "headless"` and a lane\'s `missingInputs` names `authorizationRequests`, the server is auth-walled and the run carried no token. That is not a defect — challenging correctly earns the server green marks. Tell the user to connect the server with OAuth in the app (server menu), then start a NEW run: the platform uses the saved token automatically, and the not-evaluated checks will grade.', ], }, { @@ -1445,9 +1446,7 @@ export const AGENT_OP_REGISTRY: readonly AgentOpEntry[] = [ tier: "gated", proposal: { describe: (input) => - `Run conformance suites on ${ - named(input, "server") ?? "a server" - }`, + `Run conformance suites on ${named(input, "server") ?? "a server"}`, buttonLabel: "Run it", kind: "start", confirmSeverity: () => "none", @@ -1520,7 +1519,7 @@ export const AGENT_OP_REGISTRY: readonly AgentOpEntry[] = [ tier: "direct", promptNotes: [ "- WHEN A RUN DOES NOT PASS, READ `decisionSummary` FIRST: it states the first failed stage in the user-value chain (connection → discovery → selection → call → response → userValue), the failure category, evidence scoped to that stage, and one next action. Authored step results (`get_eval_run_steps`) come second and a full trace (`get_eval_iteration_trace`) last — do not reconstruct the chain from raw tool calls when the summary already states it.", - "- Read `measurementUnit` before quoting a count: under verdict policy v2 the counts are CASE-EXECUTION VARIANTS with repetitions as trials inside them, and on a legacy run they are trials, so the same suite is legitimately \"3\" or \"15\" and a count without its unit is not a fact. And `verdict: \"notEstablished\"` is neither a failure nor `inconclusive` — no verdict exists at all (`undecided.reason` says why), so never report it as a regression.", + '- Read `measurementUnit` before quoting a count: under verdict policy v2 the counts are CASE-EXECUTION VARIANTS with repetitions as trials inside them, and on a legacy run they are trials, so the same suite is legitimately "3" or "15" and a count without its unit is not a fact. And `verdict: "notEstablished"` is neither a failure nor `inconclusive` — no verdict exists at all (`undecided.reason` says why), so never report it as a regression.', "- `diagnostics` is one PAGE and one KIND of claim. When `diagnostics.complete` is false, more failing trials went unexamined — say so instead of presenting the page as the run's failures, and pass `diagnosticsCursor` to continue. And a diagnostic says WHERE the chain stopped, not why: `firstFailedStage` is a location and `failureCategory` a bucket, so neither authorizes proposing a server change on its own.", ], }, @@ -1884,6 +1883,26 @@ export const AGENT_OP_REGISTRY: readonly AgentOpEntry[] = [ { operation: getPersonaOperation, tier: "direct" }, { operation: createPersonaOperation, tier: "direct" }, { operation: updatePersonaOperation, tier: "direct" }, + // ── PROJECT SECRETS (reads only) ────────────────────────────────────── + // + // Metadata only, and structurally incapable of returning a value — which is + // what makes them ordinary `direct` reads despite naming credentials. An + // agent needs them to answer "does this project already have a STRIPE_API_KEY, + // and is it brokered?" before proposing an environment change. + // + // The three WRITES are excluded (see EXCLUDED_FROM_AGENT), and for + // create/update the reason is not risk appetite: their input CARRIES the + // plaintext, so it would reach model context and the transcript before any + // approval card could render. + { + operation: listSecretsOperation, + tier: "direct", + promptNotes: [ + "- `list_secrets` and `get_secret` return METADATA ONLY — a secret's value is not readable by you or by anyone, through any surface. If a task needs a credential's value, the answer is that you cannot have it; say so rather than looking for another route to it.", + "- Delivery mode matters when you reason about a workflow: a `brokered` secret is injected by the sandbox's egress proxy and is NOT an environment variable in the box (so `echo $NAME` will be empty and a CLI that reads env vars will not see it), while a `materialized` one is.", + ], + }, + { operation: getSecretOperation, tier: "direct" }, { operation: listJourneysOperation, tier: "direct" }, { operation: getJourneyOperation, @@ -2271,6 +2290,20 @@ export const EXCLUDED_FROM_AGENT: Readonly> = { // deliberate, it does not make a removal recoverable. delete_persona: "Removes a persona from the roster; the agent proposes authoring, never destruction.", + // PROJECT SECRET WRITES. The first two are excluded for a reason that is not + // about risk appetite at all: their INPUT carries the plaintext credential, + // so it would transit model context and be written into this turn's + // transcript before any approval card could render. An approval that fires + // after the value is already logged is not an approval, and no tier fixes + // that — only keeping the operation off the surface does. They stay + // available on REST, the SDK and the CLI, where the caller decides where the + // value comes from (a file, an env var, stdin) and nothing transcribes it. + create_secret: + "The plaintext value is an argument, so it would reach model context and the turn transcript before any approval could run. Available on REST/SDK/CLI, where the caller controls where the value comes from.", + update_secret: + "Same as create_secret: a rotation carries the new plaintext as an argument. Available on REST/SDK/CLI.", + delete_secret: + "Hard-revokes a credential — the row and the encrypted value both go, and nothing here can put it back; the agent proposes authoring, never destruction.", archive_journey: "Removes a journey from the roster; the agent proposes authoring, never destruction.", archive_swarm: diff --git a/mcpjam-inspector/server/routes/v1/environments.ts b/mcpjam-inspector/server/routes/v1/environments.ts index 9e99a75011..f8abf8ca73 100644 --- a/mcpjam-inspector/server/routes/v1/environments.ts +++ b/mcpjam-inspector/server/routes/v1/environments.ts @@ -73,6 +73,20 @@ function isNamedEnvironmentRow(row: { return typeof row.name === "string" && row.name.trim().length > 0; } +/** + * Which PROJECT SECRETS a run launched from this environment receives. Ids + * only — the DTO carries no name and certainly no value, and the secret rows + * behind these ids are readable (metadata-only) through `/v1/projects/:id/secrets`. + * + * No version pins, unlike `SkillSelection`: a secret has exactly one current + * value by definition, and "pin the previous value" is the opposite of what + * rotation is for. + */ +type SecretSelection = { + mode: "explicit"; + secretIds: string[]; +}; + type EnvironmentRow = { environmentId: string; projectId: string; @@ -86,6 +100,7 @@ type EnvironmentRow = { /** The stored model OVERRIDE. Absent ⇒ the environment inherits its host's. */ modelId?: string; skillSelection?: SkillSelection; + secretSelection?: SecretSelection; pluginVersionIds?: string[]; /** Internal (Convex) name for the sandbox-image pin — public DTOs expose it * as `sandboxImageId`, matching the SDK's `PlatformImage` vocabulary. */ @@ -146,6 +161,13 @@ function toEnvironmentDto(row: EnvironmentRow) { ...(row.skillSelection !== undefined ? { skillSelection: row.skillSelection } : {}), + // The GRANT, as ids. Which of these a given run actually receives is + // decided live at launch against that session's owner (a personal secret + // reaches only its owner's sessions), so this is what the environment ASKS + // FOR, not a promise about any one run. + ...(row.secretSelection !== undefined + ? { secretSelection: row.secretSelection } + : {}), ...(row.pluginVersionIds !== undefined ? { pluginVersionIds: row.pluginVersionIds } : {}), @@ -389,6 +411,18 @@ const skillSelectionSchema = z.strictObject({ const pluginVersionIdsSchema = z.array(z.string().trim().min(1)).min(1); +/** + * `.min(1)` for the same reason every other selection has it: the backend + * rejects an empty selection with "clear the selection instead", so `[]` is a + * 400 rather than a silent revoke. Revoking a grant is `null` on PATCH, and + * that distinction is worth a validation error — an accidental `[]` that read + * as "remove every credential" would break a workflow with no error to look at. + */ +const secretSelectionSchema = z.strictObject({ + mode: z.literal("explicit"), + secretIds: z.array(z.string().trim().min(1)).min(1), +}); + const createEnvironmentSchema = z.strictObject({ name: z.string().trim().min(1), description: z.string().optional(), @@ -401,6 +435,7 @@ const createEnvironmentSchema = z.strictObject({ */ modelId: z.string().trim().min(1).optional(), skillSelection: skillSelectionSchema.optional(), + secretSelection: secretSelectionSchema.optional(), pluginVersionIds: pluginVersionIdsSchema.optional(), /** Public name for the internal `computerEnvironmentId` pin; must be a * project-shared image (backend rejects personal drafts). */ @@ -409,10 +444,14 @@ const createEnvironmentSchema = z.strictObject({ /** * `.nullable().optional()` on every clearable field (`serverAttachmentId`, - * `skillSelection`, `pluginVersionIds`, `sandboxImageId`) encodes the backend's - * tri-state: omitted = unchanged, `null` = clear, value = set. A new clearable - * field must join BOTH that shape and the `.refine` below, or it silently - * becomes unclearable / unable to be the only field in a PATCH. + * `skillSelection`, `secretSelection`, `pluginVersionIds`, `sandboxImageId`) + * encodes the backend's tri-state: omitted = unchanged, `null` = clear, value = + * set. A new clearable field must join BOTH that shape and the `.refine` below, + * or it silently becomes unclearable / unable to be the only field in a PATCH. + * + * `secretSelection` is the field where that would hurt most: unclearable means + * an environment's credential grant can only ever grow, and revoking it would + * require deleting the environment. */ const updateEnvironmentSchema = z .strictObject({ @@ -423,6 +462,7 @@ const updateEnvironmentSchema = z serverAttachmentId: z.string().trim().min(1).nullable().optional(), modelId: z.string().trim().min(1).nullable().optional(), skillSelection: skillSelectionSchema.nullable().optional(), + secretSelection: secretSelectionSchema.nullable().optional(), pluginVersionIds: pluginVersionIdsSchema.nullable().optional(), sandboxImageId: z.string().trim().min(1).nullable().optional(), }) @@ -434,11 +474,12 @@ const updateEnvironmentSchema = z value.serverAttachmentId !== undefined || value.modelId !== undefined || value.skillSelection !== undefined || + value.secretSelection !== undefined || value.pluginVersionIds !== undefined || value.sandboxImageId !== undefined, { message: - "Provide at least one of `name`, `description`, `hostId`, `serverAttachmentId`, `modelId`, `skillSelection`, `pluginVersionIds`, or `sandboxImageId` to update.", + "Provide at least one of `name`, `description`, `hostId`, `serverAttachmentId`, `modelId`, `skillSelection`, `secretSelection`, `pluginVersionIds`, or `sandboxImageId` to update.", }, ); @@ -456,6 +497,7 @@ const ensureAdhocEnvironmentSchema = z.strictObject({ serverAttachmentId: z.string().trim().min(1).optional(), modelId: z.string().trim().min(1).optional(), skillSelection: skillSelectionSchema.optional(), + secretSelection: secretSelectionSchema.optional(), pluginVersionIds: pluginVersionIdsSchema.optional(), sandboxImageId: z.string().trim().min(1).optional(), }); @@ -806,6 +848,11 @@ environments.patch( if (body.modelId !== undefined) updateArgs.modelId = body.modelId; if (body.skillSelection !== undefined) updateArgs.skillSelection = body.skillSelection; + // `null` REVOKES the environment's credential grant; a value replaces it; + // omission leaves it alone. The one field here where "unchanged" and + // "cleared" have materially different security consequences. + if (body.secretSelection !== undefined) + updateArgs.secretSelection = body.secretSelection; if (body.pluginVersionIds !== undefined) updateArgs.pluginVersionIds = body.pluginVersionIds; // Boundary rename (public sandboxImageId ↔ internal computerEnvironmentId); diff --git a/mcpjam-inspector/server/routes/v1/index.ts b/mcpjam-inspector/server/routes/v1/index.ts index a2bc7bfe00..71be27fe32 100644 --- a/mcpjam-inspector/server/routes/v1/index.ts +++ b/mcpjam-inspector/server/routes/v1/index.ts @@ -32,6 +32,7 @@ import plugins from "./plugins.js"; import skills from "./skills.js"; import journeys from "./journeys.js"; import personas from "./personas.js"; +import secrets from "./secrets.js"; import swarms from "./swarms.js"; import swarmInsights from "./swarm-insights.js"; import swarmGenerateV1 from "./swarm-generate.js"; @@ -94,7 +95,7 @@ v1.use( "*", bearerAuthMiddleware, passthroughRateLimitMiddleware, - guestRateLimitMiddleware + guestRateLimitMiddleware, ); v1.use("*", async (c, next) => { @@ -150,6 +151,12 @@ v1.route("/", journeys); // Personas and swarm containers — the authoring half of Swarms. Same beta // gate, same guest denial: authoring is a member-only surface end to end. v1.route("/", personas); +// PROJECT SECRETS — the credential a real workflow needs, as a first-class +// resource. WRITE-ONLY: nothing here returns a value, ever. Guest-DENIED by +// default (`guest-allowed-paths.ts` is default-deny and there is deliberately +// NO entry for `/secrets` — adding one would be the single change that breaks +// the guarantee). +v1.route("/", secrets); v1.route("/", swarms); // The insights layer over runs: scorecards, findings, wave insights. Reads are // ungated (an empty result leaks nothing); REQUESTING wave insights spends diff --git a/mcpjam-inspector/server/routes/v1/secrets.ts b/mcpjam-inspector/server/routes/v1/secrets.ts new file mode 100644 index 0000000000..52dcad890b --- /dev/null +++ b/mcpjam-inspector/server/routes/v1/secrets.ts @@ -0,0 +1,476 @@ +/** + * Public v1 SECRETS surface — write-only, without exception. + * + * A project secret is a named credential a real workflow needs: `STRIPE_API_KEY` + * for a `stripe` CLI run, `GH_TOKEN` for `gh`, a password for `psql`. Before + * this, the only way to get one into a run was hand-editing a server's `env` in + * the UI: per-server, invisible to the API, unusable from CI. The Sessions API + * shipped and still could not be handed a credential, which made automation + * half a product. + * + * ## Write-only means write-only + * + * No route here returns a value, and none can. The DTO below has no `value` + * field; the Convex functions behind these routes have no code path that + * produces one; the only two things that decrypt are the delivery paths, which + * write into a sandbox's environment or an egress policy and return nothing to + * a caller. A test asserts this on the RESPONSE SCHEMA rather than on a sample + * body, because a sample body only proves what one fixture happened not to + * contain. + * + * ## Two delivery modes, and the honest description of each + * + * - `brokered` (the default) — the value is injected as a request header by + * the sandbox's egress proxy, OUTSIDE the VM. The box never holds it, so a + * prompt-injected agent has nothing to exfiltrate. It prevents EXTRACTION, + * not USE: any process in the box can call the bound host while the policy + * is live. Works for HTTPS APIs only — the proxy binds domain rules on + * ports 80/443. + * - `materialized` — a real environment variable inside the box, because a + * CLI cannot read a header the proxy adds. EXTRACTABLE BY DESIGN: `env` + * prints it. The label, the transcript scrubber and the brokered default + * are mitigations, not a claim that it is safe. + * + * ## Two sharing scopes + * + * - `project` — admin-managed, delivered to every member's sessions. + * - `user` — personal; delivered ONLY in sessions its owner starts, and + * silently absent from another member's run of the same environment. That + * silence is documented behaviour, not a bug: an error would leak that the + * secret exists, and the environment's other secrets should still deliver. + * + * ## Cross-project scoping is enforced in CONVEX, not here + * + * `personas.ts`'s header apologizes for a list-and-scan preflight and names the + * fix: a scoped getter taking `{projectId, resourceId}` that asserts the scope + * inside Convex, where a scope rule belongs. `projectSecrets:getSecret` is that + * getter, built up front — so every by-id route below is one read with one + * decision, and there is no copy of the rule in this file to drift. + * + * ## Guests + * + * `guest-allowed-paths.ts` is default-deny and there is deliberately NO entry + * for `/secrets`. Nothing here is reachable by an unauthenticated caller, and + * adding an entry would be the single change that breaks that. + */ +import { Hono } from "hono"; +import { z } from "zod"; +import { createConvexClient } from "./convex-client.js"; +import { ErrorCode, WebRouteError } from "../web/errors.js"; +import { getConvexBearerForRequest } from "../../utils/v1-convex-token.js"; +import { v1PageJson, v1Resource } from "./envelope.js"; +import { translateConvexWriteError } from "./convex-errors.js"; +import { translateConvexReadError } from "./convex-read-errors.js"; + +const secrets = new Hono(); + +function translateReadError(error: unknown): WebRouteError { + return translateConvexReadError(error, { scope: "v1.secrets" }); +} + +/** + * Convex `projectSecrets:toSecretView` output, hand-mirrored. + * + * Note what is NOT here, and could not be added by accident: a value. The + * backend view type has no such field, so a `value` on this type would fail to + * compile against nothing — which is why the contract test asserts on the + * response SCHEMA instead of trusting the mirror. + */ +type SecretRow = { + secretId: string; + projectId: string; + name: string; + description?: string; + delivery: "brokered" | "materialized"; + brokerHosts?: string[]; + brokerHeader?: string; + brokerTemplate?: string; + sharing: "user" | "project"; + ownerUserId?: string; + isOwner: boolean; + lastDeliveredAt?: number; + createdAt: number; + updatedAt: number; + createdByUserId: string; + updatedByUserId: string; +}; + +function toSecretDto(row: SecretRow) { + return { + id: row.secretId, + projectId: row.projectId, + /** The environment-variable name. This IS the secret's identity. */ + name: row.name, + description: row.description ?? null, + delivery: row.delivery, + ...(row.brokerHosts !== undefined ? { brokerHosts: row.brokerHosts } : {}), + ...(row.brokerHeader !== undefined + ? { brokerHeader: row.brokerHeader } + : {}), + ...(row.brokerTemplate !== undefined + ? { brokerTemplate: row.brokerTemplate } + : {}), + sharing: row.sharing, + /** Personal secrets only. Absent on project-shared rows, which have no owner. */ + ...(row.ownerUserId !== undefined ? { ownerUserId: row.ownerUserId } : {}), + /** + * When this secret was last HANDED TO a run — not when it was last used. + * Brokered use is unobservable to us by construction (the proxy injects the + * header and we never see the request), so "used" would be a number we + * cannot honestly produce. `null` means nothing has been recorded, which is + * not the same as "never delivered". + */ + lastDeliveredAt: row.lastDeliveredAt ?? null, + createdAt: row.createdAt, + updatedAt: row.updatedAt, + createdByUserId: row.createdByUserId, + updatedByUserId: row.updatedByUserId, + }; +} + +const NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/; + +const nameSchema = z + .string() + .trim() + .min(1) + .max(64) + .regex( + NAME_PATTERN, + "Secret name must be an environment-variable identifier: uppercase letters, digits and underscores, not starting with a digit (e.g. STRIPE_API_KEY).", + ); + +/** + * The secret itself. + * + * NOT trimmed, deliberately, and the schema must not add `.trim()`: a trailing + * newline is meaningful in some credentials (a PEM block), and silently + * rewriting what the caller sent produces a failure that presents as "the API + * key is wrong" with nothing to look at. + */ +const valueSchema = z + .string() + .min(1) + .max(64 * 1024); + +const brokerHostsSchema = z + .array(z.string().trim().min(1).max(253)) + .min(1) + .max(10); +const brokerHeaderSchema = z.string().trim().min(1).max(64); +const brokerTemplateSchema = z.string().min(1).max(256); + +const deliverySchema = z.enum(["brokered", "materialized"]); +const sharingSchema = z.enum(["user", "project"]); + +/** + * The broker triple is required IFF `delivery === "brokered"`, checked in both + * directions. + * + * A brokered row missing it would be delivered as nothing, silently. A + * materialized row CARRYING it would tell every reader the value is + * proxy-injected when it is in fact an environment variable in the box — the + * exact confusion the two modes exist to keep apart. The backend enforces the + * same rule; this refine exists so the caller learns it at the boundary with a + * message naming the fields, rather than as a Convex error. + */ +function refineBrokerBinding< + T extends { + delivery?: "brokered" | "materialized"; + brokerHosts?: string[]; + brokerHeader?: string; + brokerTemplate?: string; + }, +>(value: T): boolean { + const supplied = + value.brokerHosts !== undefined || + value.brokerHeader !== undefined || + value.brokerTemplate !== undefined; + if (value.delivery === "materialized") return !supplied; + if (value.delivery === "brokered") { + return ( + value.brokerHosts !== undefined && + value.brokerHeader !== undefined && + value.brokerTemplate !== undefined + ); + } + // `delivery` omitted on PATCH: the binding may be edited in place, and the + // backend re-validates against the row's stored mode. + return true; +} + +const BROKER_BINDING_MESSAGE = + 'A brokered secret must declare `brokerHosts`, `brokerHeader` and `brokerTemplate` (e.g. ["api.stripe.com"], "Authorization", "Bearer {}"); a materialized secret must declare none of them.'; + +const createSecretSchema = z + .strictObject({ + name: nameSchema, + value: valueSchema, + description: z.string().max(500).optional(), + /** + * REQUIRED, with no default. `brokered` is the safer mode and the one the + * UI defaults to, but a caller who does not say which they want is a caller + * who has not thought about whether the value ends up inside the box — and + * defaulting silently would make that decision for them. + */ + delivery: deliverySchema, + brokerHosts: brokerHostsSchema.optional(), + brokerHeader: brokerHeaderSchema.optional(), + brokerTemplate: brokerTemplateSchema.optional(), + /** + * Defaults to `project`: a secret a team creates is normally a team secret, + * and the surprising outcome is a credential nobody else's session can use. + * A non-admin asking for `project` is REFUSED rather than downgraded to + * personal — a silent downgrade looks like success and then is not + * delivered to anyone but them. + */ + sharing: sharingSchema.optional(), + }) + .refine(refineBrokerBinding, { message: BROKER_BINDING_MESSAGE }); + +/** + * PATCH rotates the value and/or edits the binding. + * + * `name` and `sharing` are IMMUTABLE in v1, and their absence here is the + * contract rather than an oversight. Renaming would break the running workflows + * that reference the environment variable; re-sharing would change who has been + * handed the value without changing the value. Both are "delete and recreate", + * which keeps env-var identity and grant history honest. + */ +const updateSecretSchema = z + .strictObject({ + value: valueSchema.optional(), + description: z.string().max(500).nullable().optional(), + delivery: deliverySchema.optional(), + brokerHosts: brokerHostsSchema.optional(), + brokerHeader: brokerHeaderSchema.optional(), + brokerTemplate: brokerTemplateSchema.optional(), + }) + .refine((value) => Object.keys(value).length > 0, { + message: + "Provide at least one of `value`, `description`, `delivery`, `brokerHosts`, `brokerHeader`, or `brokerTemplate` to update.", + }) + .refine(refineBrokerBinding, { message: BROKER_BINDING_MESSAGE }); + +async function parseBody( + c: { req: { json: () => Promise } }, + schema: z.ZodType, +): Promise { + let raw: unknown; + try { + raw = await c.req.json(); + } catch { + throw new WebRouteError( + 400, + ErrorCode.VALIDATION_ERROR, + "Request body must be JSON", + ); + } + const parsed = schema.safeParse(raw); + if (!parsed.success) { + throw new WebRouteError( + 400, + ErrorCode.VALIDATION_ERROR, + parsed.error.issues[0]?.message ?? "Invalid request body", + ); + } + return parsed.data; +} + +/** + * The write idempotency key, straight from the header with NO transformation. + * + * Load-bearing for the same reason it is on personas: Convex fingerprints a + * replay from the request, so a layer that injected or renamed a field would + * make the retry arrive with a different fingerprint and be rejected as key + * reuse. Every optional field below is forwarded only when the caller sent it. + * + * The secrets fingerprint additionally PRE-HASHES the value backend-side, so + * the stored fingerprint is a hash of a hash — a leaked metadata row cannot + * seed an offline guess against a low-entropy secret. + */ +function idempotencyKeyOf(c: { + req: { header: (name: string) => string | undefined }; +}): string | undefined { + const key = c.req.header("idempotency-key")?.trim(); + return key && key.length > 0 ? key : undefined; +} + +// ── Routes ────────────────────────────────────────────────────────────────── + +// GET /v1/projects/:projectId/secrets — metadata only. +// +// Returns project-shared secrets plus the CALLER'S OWN personal ones. Another +// member's personal secret is absent entirely — not redacted, not listed with a +// hidden value; its name never appears. +secrets.get("/projects/:projectId/secrets", async (c) => { + const projectId = c.req.param("projectId"); + const client = createConvexClient(await getConvexBearerForRequest(c)); + let rows: SecretRow[]; + try { + rows = ((await client.query( + "projectSecrets:listSecrets" as never, + { + projectId, + } as never, + )) ?? []) as SecretRow[]; + } catch (error) { + throw translateReadError(error); + } + return v1PageJson(c, rows.map(toSecretDto)); +}); + +// GET /v1/projects/:projectId/secrets/:secretId — metadata only. +// +// The scoped getter does the cross-project check inside Convex, so a valid id +// from another project reads as NOT_FOUND. So does another member's personal +// secret — a 403 there would confirm the id names a real row. +secrets.get("/projects/:projectId/secrets/:secretId", async (c) => { + const projectId = c.req.param("projectId"); + const secretId = c.req.param("secretId"); + const client = createConvexClient(await getConvexBearerForRequest(c)); + let row: SecretRow; + try { + row = (await client.query( + "projectSecrets:getSecret" as never, + { + projectId, + secretId, + } as never, + )) as SecretRow; + } catch (error) { + throw translateReadError(error); + } + return v1Resource(c, toSecretDto(row)); +}); + +// POST /v1/projects/:projectId/secrets +// +// The value crosses exactly one boundary: this request, and then client → +// Convex Node action. It is never logged, never echoed, and never returned — +// the 201 body is the same metadata DTO every read produces. +// +// IDEMPOTENT on `idempotency-key`. Worth using: a retried create without one +// fails as a name conflict with the row the first attempt already made, which +// is indistinguishable from a genuine collision. +secrets.post("/projects/:projectId/secrets", async (c) => { + const projectId = c.req.param("projectId"); + const body = await parseBody(c, createSecretSchema); + const client = createConvexClient(await getConvexBearerForRequest(c)); + const idempotencyKey = idempotencyKeyOf(c); + + let row: SecretRow; + try { + // An ACTION, not a mutation: encryption is Node-only in Convex, and this is + // the one hop a plaintext makes. + row = (await client.action( + "projectSecretsNode:createSecret" as never, + { + projectId, + name: body.name, + value: body.value, + ...(body.description !== undefined + ? { description: body.description } + : {}), + delivery: body.delivery, + ...(body.brokerHosts !== undefined + ? { brokerHosts: body.brokerHosts } + : {}), + ...(body.brokerHeader !== undefined + ? { brokerHeader: body.brokerHeader } + : {}), + ...(body.brokerTemplate !== undefined + ? { brokerTemplate: body.brokerTemplate } + : {}), + ...(body.sharing !== undefined ? { sharing: body.sharing } : {}), + ...(idempotencyKey ? { idempotencyKey } : {}), + } as never, + )) as SecretRow; + } catch (error) { + throw translateConvexWriteError(error, { resource: "Secret" }); + } + + return v1Resource(c, toSecretDto(row), 201); +}); + +// PATCH /v1/projects/:projectId/secrets/:secretId +// +// ROTATION SEMANTICS, and they are not hidden: a rotated value reaches NEW RUNS +// ONLY. A session already running holds the old value — materialized in its +// box's environment, or inside an egress transform we cannot read back — and +// there is no safe way to reach in and replace it mid-run. Same rule Devin +// documents as "sessions created after you added the secret". +secrets.patch("/projects/:projectId/secrets/:secretId", async (c) => { + const projectId = c.req.param("projectId"); + const secretId = c.req.param("secretId"); + const body = await parseBody(c, updateSecretSchema); + const client = createConvexClient(await getConvexBearerForRequest(c)); + + let row: SecretRow; + try { + row = (await client.action( + "projectSecretsNode:updateSecret" as never, + { + projectId, + secretId, + ...(body.value !== undefined ? { value: body.value } : {}), + // Tri-state: `null` clears the description, a value replaces it, omission + // leaves it. Forwarded with `!== undefined` so the two do not collapse. + ...(body.description !== undefined + ? { description: body.description } + : {}), + ...(body.delivery !== undefined ? { delivery: body.delivery } : {}), + ...(body.brokerHosts !== undefined + ? { brokerHosts: body.brokerHosts } + : {}), + ...(body.brokerHeader !== undefined + ? { brokerHeader: body.brokerHeader } + : {}), + ...(body.brokerTemplate !== undefined + ? { brokerTemplate: body.brokerTemplate } + : {}), + } as never, + )) as SecretRow; + } catch (error) { + throw translateConvexWriteError(error, { resource: "Secret" }); + } + + return v1Resource(c, toSecretDto(row)); +}); + +// DELETE /v1/projects/:projectId/secrets/:secretId +// +// A HARD delete: the row goes and the ciphertext behind it goes with it. This +// is the revoke button, so it must not be soft. +// +// Deliberately NOT blocked when an environment still selects the secret. The +// selection resolver drops ids that no longer resolve, and refusing here would +// make a leaked credential un-revokable until someone edited every environment +// referencing it. Revocation is never gated on cleanup. +secrets.delete("/projects/:projectId/secrets/:secretId", async (c) => { + const projectId = c.req.param("projectId"); + const secretId = c.req.param("secretId"); + const client = createConvexClient(await getConvexBearerForRequest(c)); + + let result: { deleted: true; secretId: string; name: string }; + try { + result = (await client.action( + "projectSecretsNode:deleteSecret" as never, + { + projectId, + secretId, + } as never, + )) as { deleted: true; secretId: string; name: string }; + } catch (error) { + throw translateConvexWriteError(error, { resource: "Secret" }); + } + + return v1Resource(c, { + id: result.secretId, + projectId, + name: result.name, + deleted: true, + }); +}); + +export default secrets; diff --git a/mcpjam-inspector/server/utils/built-in-tools/mcpjam.ts b/mcpjam-inspector/server/utils/built-in-tools/mcpjam.ts index 56fb4326c4..8876c67229 100644 --- a/mcpjam-inspector/server/utils/built-in-tools/mcpjam.ts +++ b/mcpjam-inspector/server/utils/built-in-tools/mcpjam.ts @@ -83,6 +83,8 @@ import { getPersonaOperation, createPersonaOperation, updatePersonaOperation, + listSecretsOperation, + getSecretOperation, listJourneysOperation, getJourneyOperation, createJourneyOperation, @@ -199,6 +201,24 @@ const WORKSPACE_OPERATIONS: ReadonlyArray> = [ getPersonaOperation, createPersonaOperation, updatePersonaOperation, + + // ── Project secrets: the METADATA READS only ──────────────────────────── + // + // This list has no drift test — it is hand-maintained — so the omission is + // stated rather than left to be noticed. `list_secrets` and `get_secret` are + // here because a workspace chat needs to answer "does this project already + // have a STRIPE_API_KEY, and is it brokered?"; both return metadata and are + // structurally incapable of returning a value. + // + // The three WRITES are deliberately absent. `create_secret` and + // `update_secret` carry the plaintext as an ARGUMENT, so it would transit + // model context and be written into this chat's transcript before anything + // could approve it; `delete_secret` hard-revokes a credential and belongs on + // a surface where the person meant it. All three stay on REST, the SDK and + // the CLI. + listSecretsOperation, + getSecretOperation, + listJourneysOperation, getJourneyOperation, createJourneyOperation, diff --git a/sdk/src/platform/__tests__/operation-permalink-coverage.test.ts b/sdk/src/platform/__tests__/operation-permalink-coverage.test.ts index a1d24a9dc5..5bb940213b 100644 --- a/sdk/src/platform/__tests__/operation-permalink-coverage.test.ts +++ b/sdk/src/platform/__tests__/operation-permalink-coverage.test.ts @@ -60,6 +60,12 @@ const ROUTE_DEBT_ALLOWLIST: Readonly> = { create_persona: "swarms/personas/:personaId", update_persona: "swarms/personas/:personaId", generate_personas: "swarms/personas/:personaId", + // Project secrets: the Secrets tab lives inside project settings and selects + // a row as component state, so there is nothing to address. Note that a + // permalink here would be to the METADATA row — a secret's value is not + // readable anywhere, by anyone, so there is no page that could show one. + list_secrets: "secrets/:secretId", + get_secret: "secrets/:secretId", }; const VALID_REASONS: ReadonlySet = new Set([ diff --git a/sdk/src/platform/client.ts b/sdk/src/platform/client.ts index ed81e1590d..40b3006fe1 100644 --- a/sdk/src/platform/client.ts +++ b/sdk/src/platform/client.ts @@ -50,6 +50,8 @@ import type { PlatformJourneyArchived, PlatformPersona, PlatformPersonaDeleted, + PlatformSecret, + PlatformSecretDeleted, PlatformRunCompare, PlatformRunScorecard, PlatformGuestExecution, @@ -216,7 +218,7 @@ export class PlatformApiClient { constructor(options: PlatformApiClientOptions) { this.baseUrl = (options.baseUrl ?? DEFAULT_PLATFORM_API_BASE_URL).replace( /\/+$/, - "", + "" ); this.getAuth = options.getAuth; // Native fetch must run with `this` bound to the global scope. Storing the @@ -236,51 +238,51 @@ export class PlatformApiClient { } listOrganizations( - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request("GET", "/organizations", {}, options); } listProjects( params: { organizationId?: string } = {}, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", "/projects", { query: { organizationId: params.organizationId } }, - options, + options ); } createProject( params: { body: Record }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request("POST", "/projects", { body: params.body }, options); } updateProject( params: { projectId: string; body: Record }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "PATCH", `/projects/${encodeURIComponent(params.projectId)}`, { body: params.body }, - options, + options ); } deleteProject( params: { projectId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise<{ id: string; deleted: boolean }> { return this.request( "DELETE", `/projects/${encodeURIComponent(params.projectId)}`, {}, - options, + options ); } @@ -297,7 +299,7 @@ export class PlatformApiClient { cursor?: string; limit?: number; } = {}, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", @@ -313,62 +315,64 @@ export class PlatformApiClient { params.connectableOnly === undefined ? undefined : params.connectableOnly - ? "true" - : "false", + ? "true" + : "false", ...pageQuery({ cursor: params.cursor, limit: params.limit }), }, }, - options, + options ); } getRegistryDirectoryServer( params: { catalogServerId: string } | { name: string; source?: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { if ("catalogServerId" in params) { return this.request( "GET", - `/registry/directory-servers/${encodeURIComponent(params.catalogServerId)}`, + `/registry/directory-servers/${encodeURIComponent( + params.catalogServerId + )}`, {}, - options, + options ); } return this.request( "GET", `/registry/directory-servers/${encodeURIComponent(params.name)}`, { query: { source: params.source } }, - options, + options ); } listRegistryDirectorySources( - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request("GET", "/registry/directory-sources", {}, options); } listRegistryServers( params: { projectId: string; scope?: "global" | "organization" | "all" }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", `/projects/${encodeURIComponent(params.projectId)}/registry/servers`, { query: { scope: params.scope } }, - options, + options ); } listRegistryConnections( params: { projectId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", `/projects/${encodeURIComponent(params.projectId)}/registry/connections`, {}, - options, + options ); } @@ -379,7 +383,7 @@ export class PlatformApiClient { endpointUrl?: string; expectedContentHash?: string; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { // Explicit picks, not a rest spread — see `startClaudeReadinessRun`. The // route's body schema forbids additional properties. @@ -394,7 +398,7 @@ export class PlatformApiClient { "POST", `/projects/${encodeURIComponent(projectId)}/registry/directory-installs`, { body }, - options, + options ); } @@ -404,7 +408,7 @@ export class PlatformApiClient { registryServerId: string; expectedUpdatedAt?: number; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { const { projectId, registryServerId, expectedUpdatedAt } = params; const body: Record = { registryServerId }; @@ -415,19 +419,21 @@ export class PlatformApiClient { "POST", `/projects/${encodeURIComponent(projectId)}/registry/installs`, { body }, - options, + options ); } uninstallRegistryServer( params: { projectId: string; registryServerId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise<{ deleted?: boolean }> { return this.request( "DELETE", - `/projects/${encodeURIComponent(params.projectId)}/registry/installs/${encodeURIComponent(params.registryServerId)}`, + `/projects/${encodeURIComponent( + params.projectId + )}/registry/installs/${encodeURIComponent(params.registryServerId)}`, {}, - options, + options ); } @@ -446,13 +452,13 @@ export class PlatformApiClient { */ createServerConnection( params: { body: PlatformServerConnectionCreateBody }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", "/server-connections", { body: params.body }, - options, + options ); } @@ -462,27 +468,27 @@ export class PlatformApiClient { * means the interval itself is too fast — honour `Retry-After`. */ getServerConnection( params: { connectionRequestId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/server-connections/${encodeURIComponent(params.connectionRequestId)}`, {}, - options, + options ); } cancelServerConnection( params: { connectionRequestId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/server-connections/${encodeURIComponent( - params.connectionRequestId, + params.connectionRequestId )}/cancel`, {}, - options, + options ); } @@ -494,53 +500,53 @@ export class PlatformApiClient { */ retryServerConnectionValidation( params: { connectionRequestId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/server-connections/${encodeURIComponent( - params.connectionRequestId, + params.connectionRequestId )}/retry-validation`, {}, - options, + options ); } listProjectServers( params: { projectId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", `/projects/${encodeURIComponent(params.projectId)}/servers`, {}, - options, + options ); } createProjectServer( params: { projectId: string; body: Record }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent(params.projectId)}/servers`, { body: params.body }, - options, + options ); } getProjectServer( params: { projectId: string; serverId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/servers/${encodeURIComponent(params.serverId)}`, {}, - options, + options ); } @@ -550,41 +556,41 @@ export class PlatformApiClient { serverId: string; body: Record; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "PATCH", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/servers/${encodeURIComponent(params.serverId)}`, { body: params.body }, - options, + options ); } deleteProjectServer( params: { projectId: string; serverId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise<{ id: string; deleted: boolean }> { return this.request( "DELETE", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/servers/${encodeURIComponent(params.serverId)}`, { body: {} }, - options, + options ); } listEvalSuites( params: { projectId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", `/projects/${encodeURIComponent(params.projectId)}/eval-suites`, {}, - options, + options ); } @@ -595,7 +601,7 @@ export class PlatformApiClient { limit?: number; before?: string; } = {}, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", @@ -608,7 +614,7 @@ export class PlatformApiClient { before: params.before, }, }, - options, + options ); } @@ -645,7 +651,7 @@ export class PlatformApiClient { allowedTools?: string[]; maxToolCalls?: number; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { // Built field by field rather than forwarded wholesale. The route's body // schema is STRICT, so any extra key a caller happens to carry on its own @@ -695,7 +701,7 @@ export class PlatformApiClient { : {}), }, }, - options, + options ); } @@ -713,7 +719,7 @@ export class PlatformApiClient { afterMessageIndex?: number; limit?: number; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", @@ -725,7 +731,7 @@ export class PlatformApiClient { limit: params.limit, }, }, - options, + options ); } @@ -745,7 +751,7 @@ export class PlatformApiClient { limit?: number; includeSpans?: boolean; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", @@ -765,7 +771,7 @@ export class PlatformApiClient { : String(params.includeSpans), }, }, - options, + options ); } @@ -796,7 +802,7 @@ export class PlatformApiClient { limit?: number; cursor?: string; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", @@ -813,33 +819,33 @@ export class PlatformApiClient { cursor: params.cursor, }, }, - options, + options ); } listScenarios( params: { projectId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", `/projects/${encodeURIComponent(params.projectId)}/scenarios`, {}, - options, + options ); } getScenario( params: { projectId: string; scenarioId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/scenarios/${encodeURIComponent(params.scenarioId)}`, {}, - options, + options ); } @@ -853,7 +859,7 @@ export class PlatformApiClient { listClients( params: { projectId: string; includePrivateBacking?: boolean }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", @@ -863,7 +869,7 @@ export class PlatformApiClient { ? { includePrivateBacking: "true" } : undefined, }, - options, + options ); } @@ -882,19 +888,19 @@ export class PlatformApiClient { client: string; includePrivateBacking?: boolean; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/clients/${encodeURIComponent(params.client)}`, { query: params.includePrivateBacking ? { includePrivateBacking: "true" } : undefined, }, - options, + options ); } @@ -905,13 +911,13 @@ export class PlatformApiClient { */ createClient( params: { projectId: string; body: Record }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent(params.projectId)}/clients`, { body: params.body }, - options, + options ); } @@ -928,15 +934,15 @@ export class PlatformApiClient { client: string; body: Record; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "PATCH", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/clients/${encodeURIComponent(params.client)}`, { body: params.body }, - options, + options ); } @@ -949,12 +955,12 @@ export class PlatformApiClient { expectedConfigId: string; expectedImpact?: PlatformClientImpact; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/clients/${encodeURIComponent(params.client)}/servers`, { body: { @@ -968,21 +974,21 @@ export class PlatformApiClient { : {}), }, }, - options, + options ); } duplicateClient( params: { projectId: string; client: string; name?: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/clients/${encodeURIComponent(params.client)}/duplicate`, { body: params.name === undefined ? {} : { name: params.name } }, - options, + options ); } @@ -992,15 +998,15 @@ export class PlatformApiClient { client: string; body?: Record; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "DELETE", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/clients/${encodeURIComponent(params.client)}`, { body: params.body ?? {} }, - options, + options ); } @@ -1009,28 +1015,28 @@ export class PlatformApiClient { /** @deprecated Use {@link listClients}. Calls the deprecated `/hosts` alias. */ listHosts( params: { projectId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", `/projects/${encodeURIComponent(params.projectId)}/hosts`, {}, - options, + options ); } /** @deprecated Use {@link getClient}. Calls the deprecated `/hosts` alias. */ getHost( params: { projectId: string; hostId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/hosts/${encodeURIComponent(params.hostId)}`, {}, - options, + options ); } @@ -1043,13 +1049,13 @@ export class PlatformApiClient { */ createHost( params: { projectId: string; body: Record }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent(params.projectId)}/hosts`, { body: params.body }, - options, + options ); } @@ -1060,15 +1066,15 @@ export class PlatformApiClient { hostId: string; body: Record; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "PATCH", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/hosts/${encodeURIComponent(params.hostId)}`, { body: params.body }, - options, + options ); } @@ -1080,12 +1086,12 @@ export class PlatformApiClient { serverIds: string[]; optionalServerIds?: string[]; }, - options?: RequestOptions, + options?: RequestOptions ): Promise<{ hostId: string; hostConfigId: string }> { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/hosts/${encodeURIComponent(params.hostId)}/servers`, { body: { @@ -1095,22 +1101,22 @@ export class PlatformApiClient { : {}), }, }, - options, + options ); } /** @deprecated Use {@link duplicateClient}. Calls the deprecated `/hosts` alias. */ duplicateHost( params: { projectId: string; hostId: string; name?: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/hosts/${encodeURIComponent(params.hostId)}/duplicate`, { body: params.name === undefined ? {} : { name: params.name } }, - options, + options ); } @@ -1121,15 +1127,15 @@ export class PlatformApiClient { hostId: string; body?: Record; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "DELETE", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/hosts/${encodeURIComponent(params.hostId)}`, { body: params.body ?? {} }, - options, + options ); } @@ -1145,7 +1151,7 @@ export class PlatformApiClient { listEnvironments( params: { projectId: string; includeArchived?: boolean }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", @@ -1153,7 +1159,7 @@ export class PlatformApiClient { { query: params.includeArchived ? { includeArchived: "true" } : undefined, }, - options, + options ); } @@ -1167,29 +1173,29 @@ export class PlatformApiClient { */ getEnvironmentCapabilities( params: { projectId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/environments/capabilities`, {}, - options, + options ); } getEnvironment( params: { projectId: string; environmentId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/environments/${encodeURIComponent(params.environmentId)}`, {}, - options, + options ); } @@ -1201,27 +1207,27 @@ export class PlatformApiClient { */ resolveEnvironment( params: { projectId: string; environmentId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/environments/${encodeURIComponent(params.environmentId)}/resolve`, {}, - options, + options ); } createEnvironment( params: { projectId: string; body: PlatformEnvironmentCreateBody }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent(params.projectId)}/environments`, { body: params.body }, - options, + options ); } @@ -1240,15 +1246,15 @@ export class PlatformApiClient { */ ensureAdhocEnvironment( params: { projectId: string; body: PlatformAdhocEnvironmentBody }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/environments/ensure-adhoc`, { body: params.body }, - options, + options ); } @@ -1268,15 +1274,15 @@ export class PlatformApiClient { environmentId: string; body: PlatformEnvironmentNameBody; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/environments/${encodeURIComponent(params.environmentId)}/name`, { body: params.body }, - options, + options ); } @@ -1291,15 +1297,15 @@ export class PlatformApiClient { environmentId: string; body: PlatformEnvironmentUpdateBody; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "PATCH", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/environments/${encodeURIComponent(params.environmentId)}`, { body: params.body }, - options, + options ); } @@ -1313,15 +1319,15 @@ export class PlatformApiClient { environmentId: string; expectedRevision: number; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/environments/${encodeURIComponent(params.environmentId)}/archive`, { body: { expectedRevision: params.expectedRevision } }, - options, + options ); } @@ -1337,15 +1343,15 @@ export class PlatformApiClient { environmentId: string; expectedRevision: number; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/environments/${encodeURIComponent(params.environmentId)}/restore`, { body: { expectedRevision: params.expectedRevision } }, - options, + options ); } @@ -1356,27 +1362,27 @@ export class PlatformApiClient { listProjectSkills( params: { projectId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", `/projects/${encodeURIComponent(params.projectId)}/skills`, {}, - options, + options ); } getProjectSkill( params: { projectId: string; skillId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/skills/${encodeURIComponent(params.skillId)}`, {}, - options, + options ); } @@ -1387,13 +1393,13 @@ export class PlatformApiClient { listProjectPlugins( params: { projectId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", `/projects/${encodeURIComponent(params.projectId)}/plugins`, {}, - options, + options ); } @@ -1405,13 +1411,13 @@ export class PlatformApiClient { */ getPluginVersion( params: { pluginVersionId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/plugin-versions/${encodeURIComponent(params.pluginVersionId)}`, {}, - options, + options ); } @@ -1422,39 +1428,39 @@ export class PlatformApiClient { listImages( params: { projectId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", `/projects/${encodeURIComponent(params.projectId)}/images`, {}, - options, + options ); } getImage( params: { projectId: string; imageId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/images/${encodeURIComponent(params.imageId)}`, {}, - options, + options ); } createImage( params: { projectId: string; body: { name: string; blueprint: string } }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent(params.projectId)}/images`, { body: params.body }, - options, + options ); } @@ -1464,15 +1470,15 @@ export class PlatformApiClient { imageId: string; body: { name?: string; blueprint?: string }; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "PATCH", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/images/${encodeURIComponent(params.imageId)}`, { body: params.body }, - options, + options ); } @@ -1480,70 +1486,70 @@ export class PlatformApiClient { * invalid blueprint is a successful lint with structured errors. */ validateImageBlueprint( params: { projectId: string; body: { blueprint: string } }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent(params.projectId)}/images/validate`, { body: params.body }, - options, + options ); } deleteImage( params: { projectId: string; imageId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "DELETE", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/images/${encodeURIComponent(params.imageId)}`, {}, - options, + options ); } listImageBuilds( params: { projectId: string; imageId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/images/${encodeURIComponent(params.imageId)}/builds`, {}, - options, + options ); } /** `POST …/build` — async (202); poll `listImageBuilds` for status. */ buildImage( params: { projectId: string; imageId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/images/${encodeURIComponent(params.imageId)}/build`, {}, - options, + options ); } promoteImage( params: { projectId: string; imageId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/images/${encodeURIComponent(params.imageId)}/promote`, {}, - options, + options ); } @@ -1551,28 +1557,28 @@ export class PlatformApiClient { * pinned image). */ useImage( params: { projectId: string; imageId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/images/${encodeURIComponent(params.imageId)}/use`, {}, - options, + options ); } /** Reset the caller's computer to its image (wipes mutable state). */ resetComputer( params: { projectId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent(params.projectId)}/computer/reset`, {}, - options, + options ); } @@ -1582,13 +1588,13 @@ export class PlatformApiClient { */ createEvalRun( params: { projectId: string; body: Record }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent(params.projectId)}/eval-runs`, { body: params.body }, - options, + options ); } @@ -1640,16 +1646,18 @@ export class PlatformApiClient { */ namedHostId?: string; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-suites/${encodeURIComponent(params.suiteId)}/run-disclosure`, { query: { - caseIds: params.caseIds?.length ? params.caseIds.join(",") : undefined, + caseIds: params.caseIds?.length + ? params.caseIds.join(",") + : undefined, environmentId: params.environmentId, environmentIds: params.environmentIds?.length ? params.environmentIds.join(",") @@ -1657,7 +1665,7 @@ export class PlatformApiClient { host: params.namedHostId, }, }, - options, + options ); } @@ -1673,15 +1681,15 @@ export class PlatformApiClient { */ attachEvalSuiteEnvironment( params: { projectId: string; suiteId: string; environmentId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-suites/${encodeURIComponent(params.suiteId)}/environments`, { body: { environmentId: params.environmentId } }, - options, + options ); } @@ -1702,13 +1710,13 @@ export class PlatformApiClient { */ createEvalRunGroup( params: { projectId: string; body: Record }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent(params.projectId)}/eval-run-groups`, { body: params.body }, - options, + options ); } @@ -1720,13 +1728,13 @@ export class PlatformApiClient { */ createEvalSuite( params: { projectId: string; body: Record }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent(params.projectId)}/eval-suites`, { body: params.body }, - options, + options ); } @@ -1751,27 +1759,27 @@ export class PlatformApiClient { verdictPolicyDefaults?: PlatformEvalVerdictPolicyDefaults; }; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent(params.projectId)}/eval-suites/from-file`, { body: params.body }, - options, + options ); } getEvalRun( params: { projectId: string; runId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-runs/${encodeURIComponent(params.runId)}`, {}, - options, + options ); } @@ -1798,15 +1806,15 @@ export class PlatformApiClient { cursor?: string; limit?: number; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-runs/${encodeURIComponent(params.runId)}/decision-summary`, { query: { cursor: params.cursor, limit: params.limit } }, - options, + options ); } @@ -1817,15 +1825,15 @@ export class PlatformApiClient { */ requestEvalRunInsights( params: { projectId: string; runId: string; force?: boolean }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-runs/${encodeURIComponent(params.runId)}/insights`, { body: params.force ? { force: true } : {} }, - options, + options ); } @@ -1848,12 +1856,12 @@ export class PlatformApiClient { model?: string; threshold?: number; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-runs/${encodeURIComponent(params.runId)}/judge`, { body: { @@ -1865,7 +1873,7 @@ export class PlatformApiClient { : {}), }, }, - options, + options ); } @@ -1875,15 +1883,15 @@ export class PlatformApiClient { */ listEvalCheckRepos( params: { organizationId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/organizations/${encodeURIComponent( - params.organizationId, + params.organizationId )}/eval-check-repos`, {}, - options, + options ); } @@ -1902,12 +1910,12 @@ export class PlatformApiClient { repo: string; outagePolicy: "fail_open" | "fail_closed"; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/organizations/${encodeURIComponent( - params.organizationId, + params.organizationId )}/eval-check-repos`, { body: { @@ -1917,7 +1925,7 @@ export class PlatformApiClient { outagePolicy: params.outagePolicy, }, }, - options, + options ); } @@ -1928,47 +1936,47 @@ export class PlatformApiClient { cursor?: string; limit?: number; }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-runs/${encodeURIComponent(params.runId)}/iterations`, { query: { cursor: params.cursor, limit: params.limit } }, - options, + options ); } /** Full trace envelope (messages + analysis) for one iteration. */ getEvalIterationTrace( params: { projectId: string; runId: string; iterationId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-runs/${encodeURIComponent( - params.runId, + params.runId )}/iterations/${encodeURIComponent(params.iterationId)}/trace`, {}, - options, + options ); } /** Cancel an in-flight run; returns the run in its (now cancelled) state. */ cancelEvalRun( params: { projectId: string; runId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-runs/${encodeURIComponent(params.runId)}/cancel`, {}, - options, + options ); } @@ -2004,15 +2012,15 @@ export class PlatformApiClient { reason: string; expiresAt: number; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-runs/${encodeURIComponent(params.runId)}/gate-waivers`, { body: { reason: params.reason, expiresAt: params.expiresAt } }, - options, + options ); } @@ -2025,15 +2033,15 @@ export class PlatformApiClient { */ getGateWaiver( params: { projectId: string; runId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-runs/${encodeURIComponent(params.runId)}/gate-waivers`, {}, - options, + options ); } @@ -2046,17 +2054,17 @@ export class PlatformApiClient { */ revokeGateWaiver( params: { projectId: string; runId: string; waiverId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "DELETE", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-runs/${encodeURIComponent( - params.runId, + params.runId )}/gate-waivers/${encodeURIComponent(params.waiverId)}`, {}, - options, + options ); } @@ -2078,8 +2086,11 @@ export class PlatformApiClient { * that can spend, and it defaults off. */ startClaudeReadinessRun( - params: { projectId: string; serverId: string } & PlatformReadinessStartBody, - options?: RequestOptions, + params: { + projectId: string; + serverId: string; + } & PlatformReadinessStartBody, + options?: RequestOptions ): Promise { // Explicit picks, not a rest spread. The endpoint's body schema is // `strictObject`, and TypeScript's structural typing lets a caller hand a @@ -2092,10 +2103,10 @@ export class PlatformApiClient { return this.request( "POST", `/projects/${encodeURIComponent(projectId)}/servers/${encodeURIComponent( - serverId, + serverId )}/readiness-runs/claude`, { body: pickReadinessStartBody(params) }, - options, + options ); } @@ -2112,32 +2123,32 @@ export class PlatformApiClient { projectId: string; serverId: string; } & PlatformOpenAIReadinessStartBody, - options?: RequestOptions, + options?: RequestOptions ): Promise { // Explicit picks — see `startClaudeReadinessRun`. const { projectId, serverId, submissionMode } = params; return this.request( "POST", `/projects/${encodeURIComponent(projectId)}/servers/${encodeURIComponent( - serverId, + serverId )}/readiness-runs/openai`, { body: { ...pickReadinessStartBody(params), submissionMode } }, - options, + options ); } /** Lane statuses, coverage and the observation axis. Poll this. */ getReadinessRun( params: { projectId: string; runId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/readiness-runs/${encodeURIComponent(params.runId)}`, {}, - options, + options ); } @@ -2148,14 +2159,14 @@ export class PlatformApiClient { serverId?: string; limit?: number; }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { const { projectId, ...query } = params; return this.request( "GET", `/projects/${encodeURIComponent(projectId)}/readiness-runs`, { query }, - options, + options ); } @@ -2168,15 +2179,15 @@ export class PlatformApiClient { */ cancelReadinessRun( params: { projectId: string; runId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise<{ runId: string; projectId: string; status: string }> { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/readiness-runs/${encodeURIComponent(params.runId)}/cancel`, {}, - options, + options ); } @@ -2193,15 +2204,15 @@ export class PlatformApiClient { */ getReadinessReport( params: { projectId: string; runId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/readiness-runs/${encodeURIComponent(params.runId)}/report`, {}, - options, + options ); } @@ -2220,10 +2231,16 @@ export class PlatformApiClient { protocolVersion?: string; engineVersion?: string; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { - const { projectId, serverId, suites, idempotencyKey, protocolVersion, engineVersion } = - params; + const { + projectId, + serverId, + suites, + idempotencyKey, + protocolVersion, + engineVersion, + } = params; const body: Record = {}; if (suites !== undefined) body.suites = suites; if (idempotencyKey !== undefined) body.idempotencyKey = idempotencyKey; @@ -2232,24 +2249,24 @@ export class PlatformApiClient { return this.request( "POST", `/projects/${encodeURIComponent(projectId)}/servers/${encodeURIComponent( - serverId, + serverId )}/conformance-runs`, { body }, - options, + options ); } getConformanceRun( params: { projectId: string; runId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/conformance-runs/${encodeURIComponent(params.runId)}`, {}, - options, + options ); } @@ -2260,45 +2277,45 @@ export class PlatformApiClient { limit?: number; cursor?: string; }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { const { projectId, ...query } = params; return this.request( "GET", `/projects/${encodeURIComponent(projectId)}/conformance-runs`, { query }, - options, + options ); } getConformanceReport( params: { projectId: string; runId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/conformance-runs/${encodeURIComponent(params.runId)}/report`, {}, - options, + options ); } /** One row per authored step (status + reason + evidence) for one iteration. */ getEvalRunSteps( params: { projectId: string; runId: string; iterationId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-runs/${encodeURIComponent( - params.runId, + params.runId )}/iterations/${encodeURIComponent(params.iterationId)}/steps`, {}, - options, + options ); } @@ -2331,12 +2348,12 @@ export class PlatformApiClient { baseCommitSha?: string; previewChars?: number; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-runs/${encodeURIComponent(params.runId)}/compare`, { query: { @@ -2345,21 +2362,21 @@ export class PlatformApiClient { previewChars: params.previewChars, }, }, - options, + options ); } listEvalSuiteRuns( params: { projectId: string; suiteId: string; limit?: number }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-suites/${encodeURIComponent(params.suiteId)}/runs`, { query: { limit: params.limit } }, - options, + options ); } @@ -2367,15 +2384,15 @@ export class PlatformApiClient { getEvalSuite( params: { projectId: string; suiteId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-suites/${encodeURIComponent(params.suiteId)}`, {}, - options, + options ); } @@ -2385,29 +2402,29 @@ export class PlatformApiClient { suiteId: string; body: Record; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "PATCH", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-suites/${encodeURIComponent(params.suiteId)}`, { body: params.body }, - options, + options ); } deleteEvalSuite( params: { projectId: string; suiteId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "DELETE", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-suites/${encodeURIComponent(params.suiteId)}`, {}, - options, + options ); } @@ -2417,45 +2434,45 @@ export class PlatformApiClient { suiteId: string; body: Record; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "PATCH", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-suites/${encodeURIComponent(params.suiteId)}/schedule`, { body: params.body }, - options, + options ); } listEvalCases( params: { projectId: string; suiteId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-suites/${encodeURIComponent(params.suiteId)}/cases`, {}, - options, + options ); } getEvalCase( params: { projectId: string; suiteId: string; caseId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-suites/${encodeURIComponent( - params.suiteId, + params.suiteId )}/cases/${encodeURIComponent(params.caseId)}`, {}, - options, + options ); } @@ -2465,15 +2482,15 @@ export class PlatformApiClient { suiteId: string; body: Record; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-suites/${encodeURIComponent(params.suiteId)}/cases`, { body: params.body }, - options, + options ); } @@ -2488,15 +2505,15 @@ export class PlatformApiClient { suiteId: string; body: Record; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-suites/${encodeURIComponent(params.suiteId)}/cases/batch`, { body: params.body }, - options, + options ); } @@ -2507,33 +2524,33 @@ export class PlatformApiClient { caseId: string; body: Record; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "PATCH", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-suites/${encodeURIComponent( - params.suiteId, + params.suiteId )}/cases/${encodeURIComponent(params.caseId)}`, { body: params.body }, - options, + options ); } deleteEvalCase( params: { projectId: string; suiteId: string; caseId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "DELETE", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-suites/${encodeURIComponent( - params.suiteId, + params.suiteId )}/cases/${encodeURIComponent(params.caseId)}`, {}, - options, + options ); } @@ -2543,56 +2560,56 @@ export class PlatformApiClient { suiteId: string; body: Record; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/eval-suites/${encodeURIComponent(params.suiteId)}/cases/generate`, { body: params.body }, - options, + options ); } validateServer( params: ServerScope & { body?: Record }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.serverOp(params, "validate", options); } doctorServer( params: ServerScope & { body?: Record }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.serverOp(params, "doctor", options); } exportServer( params: ServerScope & { body?: Record }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.serverOp(params, "export", options); } listServerTools( params: ServerScope & { body?: Record }, - options?: RequestOptions, + options?: RequestOptions ): Promise>> { return this.serverOp(params, "tools", options); } listServerResources( params: ServerScope & { body?: Record }, - options?: RequestOptions, + options?: RequestOptions ): Promise>> { return this.serverOp(params, "resources", options); } listServerPrompts( params: ServerScope & { body?: Record }, - options?: RequestOptions, + options?: RequestOptions ): Promise>> { return this.serverOp(params, "prompts", options); } @@ -2606,7 +2623,7 @@ export class PlatformApiClient { params: ServerScope & { body: { toolName: string; parameters?: Record }; }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.serverOp(params, "tools/call", options); } @@ -2632,11 +2649,13 @@ export class PlatformApiClient { viewport?: { width: number; height: number }; }; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { - return this.serverOp(params, "widgets/render", options) as Promise< - PlatformWidgetRender - >; + return this.serverOp( + params, + "widgets/render", + options + ) as Promise; } /** `POST /projects/{p}/servers/{s}/prompts/get` — render one prompt. */ @@ -2647,7 +2666,7 @@ export class PlatformApiClient { arguments?: Record; }; }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.serverOp(params, "prompts/get", options); } @@ -2655,7 +2674,7 @@ export class PlatformApiClient { /** `POST /projects/{p}/servers/{s}/resources/read` — read one resource. */ readServerResource( params: ServerScope & { body: { uri: string } }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.serverOp(params, "resources/read", options); } @@ -2670,7 +2689,7 @@ export class PlatformApiClient { */ listServerSkills( params: ServerScope & { body?: Record }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.serverOp(params, "skills", options); } @@ -2684,7 +2703,7 @@ export class PlatformApiClient { */ getServerSkill( params: ServerScope & { body: { uri: string } }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.serverOp(params, "skills/get", options); } @@ -2695,7 +2714,7 @@ export class PlatformApiClient { */ readServerSkillFile( params: ServerScope & { body: { skillUri: string; resourceUri: string } }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.serverOp(params, "skills/read-file", options); } @@ -2708,13 +2727,13 @@ export class PlatformApiClient { */ createTunnel( params: { projectId: string; name: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent(params.projectId)}/tunnels`, { body: { name: params.name } }, - options, + options ); } @@ -2725,15 +2744,15 @@ export class PlatformApiClient { */ closeTunnel( params: { projectId: string; serverId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/tunnels/${encodeURIComponent(params.serverId)}/close`, {}, - options, + options ); } @@ -2755,13 +2774,13 @@ export class PlatformApiClient { listJourneys( params: { projectId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", `/projects/${encodeURIComponent(params.projectId)}/journeys`, {}, - options, + options ); } @@ -2772,29 +2791,29 @@ export class PlatformApiClient { cursor?: string; limit?: number; }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/journeys/${encodeURIComponent(params.journeyId)}/runs`, { query: pageQuery(params) }, - options, + options ); } getJourneyRun( params: { projectId: string; runId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/journey-runs/${encodeURIComponent(params.runId)}`, {}, - options, + options ); } @@ -2805,15 +2824,15 @@ export class PlatformApiClient { cursor?: string; limit?: number; }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/journey-runs/${encodeURIComponent(params.runId)}/sessions`, { query: pageQuery(params) }, - options, + options ); } @@ -2838,12 +2857,12 @@ export class PlatformApiClient { waveId?: string; environmentIds?: string[]; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/journeys/${encodeURIComponent(params.journeyId)}/runs`, { body: { @@ -2853,7 +2872,7 @@ export class PlatformApiClient { : {}), }, }, - options, + options ); } @@ -2870,15 +2889,15 @@ export class PlatformApiClient { */ cancelJourneyRun( params: { projectId: string; runId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/journey-runs/${encodeURIComponent(params.runId)}/cancel`, {}, - options, + options ); } @@ -2894,27 +2913,27 @@ export class PlatformApiClient { listPersonas( params: { projectId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", `/projects/${encodeURIComponent(params.projectId)}/personas`, {}, - options, + options ); } getPersona( params: { projectId: string; personaId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/personas/${encodeURIComponent(params.personaId)}`, {}, - options, + options ); } @@ -2933,14 +2952,14 @@ export class PlatformApiClient { avatarShape?: number; avatarPalette?: number; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { const { projectId, ...body } = params; return this.request( "POST", `/projects/${encodeURIComponent(projectId)}/personas`, { body }, - options, + options ); } @@ -2954,16 +2973,16 @@ export class PlatformApiClient { avatarShape?: number; avatarPalette?: number; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { const { projectId, personaId, ...body } = params; return this.request( "PATCH", `/projects/${encodeURIComponent(projectId)}/personas/${encodeURIComponent( - personaId, + personaId )}`, { body }, - options, + options ); } @@ -2975,29 +2994,176 @@ export class PlatformApiClient { */ deletePersona( params: { projectId: string; personaId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "DELETE", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/personas/${encodeURIComponent(params.personaId)}`, {}, - options, + options + ); + } + + // ── Project secrets ─────────────────────────────────────────────────────── + // + // WRITE-ONLY. Every method below returns metadata; none returns a value, and + // there is deliberately no method that could. A secret is written and + // delivered into a run, never read back. + + /** + * List the project's secrets — METADATA ONLY. + * + * Returns project-shared secrets plus the CALLER'S OWN personal ones. Another + * member's personal secret is absent entirely: not redacted, not listed with + * a hidden value — its name never appears. + */ + listSecrets( + params: { projectId: string }, + options?: RequestOptions + ): Promise> { + return this.request( + "GET", + `/projects/${encodeURIComponent(params.projectId)}/secrets`, + {}, + options + ); + } + + /** One secret's metadata. Never its value. */ + getSecret( + params: { projectId: string; secretId: string }, + options?: RequestOptions + ): Promise { + return this.request( + "GET", + `/projects/${encodeURIComponent( + params.projectId + )}/secrets/${encodeURIComponent(params.secretId)}`, + {}, + options + ); + } + + /** + * Create a secret. + * + * THE VALUE BECOMES VISIBLE TO WHATEVER CARRIES THIS CALL. It is in the + * request body, so it passes through whatever process, log, shell history or + * transcript the call is made from. Prefer reading it from a file, an + * environment variable, or stdin rather than pasting it into an argument. + * + * `delivery` is required, with no default, because it decides whether the + * value ends up INSIDE the sandbox: + * - `"brokered"` — injected by the egress proxy outside the VM. The box + * never holds it. Prevents extraction, not use, and works for HTTPS APIs + * only. + * - `"materialized"` — a real environment variable in the box, so a CLI can + * read it. Extractable by design. + * + * `sharing` defaults to `"project"`. A non-admin asking for it is refused, + * not silently downgraded to personal — a downgrade would look like success + * and then not reach anyone else's sessions. + * + * IDEMPOTENT ON `options.idempotencyKey`, and worth passing: a retried create + * without one fails as a name conflict with the row the first attempt already + * made, which is indistinguishable from a genuine collision. + */ + createSecret( + params: { + projectId: string; + name: string; + value: string; + description?: string; + delivery: "brokered" | "materialized"; + brokerHosts?: string[]; + brokerHeader?: string; + brokerTemplate?: string; + sharing?: "user" | "project"; + }, + options?: RequestOptions + ): Promise { + const { projectId, ...body } = params; + return this.request( + "POST", + `/projects/${encodeURIComponent(projectId)}/secrets`, + { body }, + options + ); + } + + /** + * Rotate a secret's value and/or edit its delivery binding. + * + * ROTATION REACHES NEW RUNS ONLY. A session already running holds the old + * value — materialized in its box's environment, or inside an egress + * transform that cannot be read back — and there is no safe way to replace it + * mid-run. + * + * `name` and `sharing` are absent on purpose: both are immutable. Renaming + * would break the workflows that reference the environment variable, and + * re-sharing would change who has been handed the value without changing the + * value. Delete and recreate for either. + */ + updateSecret( + params: { + projectId: string; + secretId: string; + value?: string; + /** `null` clears the description; omit to leave it unchanged. */ + description?: string | null; + delivery?: "brokered" | "materialized"; + brokerHosts?: string[]; + brokerHeader?: string; + brokerTemplate?: string; + }, + options?: RequestOptions + ): Promise { + const { projectId, secretId, ...body } = params; + return this.request( + "PATCH", + `/projects/${encodeURIComponent(projectId)}/secrets/${encodeURIComponent( + secretId + )}`, + { body }, + options + ); + } + + /** + * Delete a secret — HARD. The row and the ciphertext both go. + * + * Not blocked when an environment still selects it: the selection resolver + * drops ids that no longer resolve, and refusing would make a leaked + * credential un-revokable until someone edited every environment naming it. + * Revocation is never gated on cleanup. + */ + deleteSecret( + params: { projectId: string; secretId: string }, + options?: RequestOptions + ): Promise { + return this.request( + "DELETE", + `/projects/${encodeURIComponent( + params.projectId + )}/secrets/${encodeURIComponent(params.secretId)}`, + {}, + options ); } getJourney( params: { projectId: string; journeyId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/journeys/${encodeURIComponent(params.journeyId)}`, {}, - options, + options ); } @@ -3015,14 +3181,14 @@ export class PlatformApiClient { serverAttachmentId?: string; hostIds?: string[]; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { const { projectId, ...body } = params; return this.request( "POST", `/projects/${encodeURIComponent(projectId)}/journeys`, { body }, - options, + options ); } @@ -3046,16 +3212,16 @@ export class PlatformApiClient { sessionsPerTarget?: number; maxTurns?: number; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { const { projectId, journeyId, ...body } = params; return this.request( "PATCH", `/projects/${encodeURIComponent(projectId)}/journeys/${encodeURIComponent( - journeyId, + journeyId )}`, { body }, - options, + options ); } @@ -3066,41 +3232,41 @@ export class PlatformApiClient { */ archiveJourney( params: { projectId: string; journeyId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "DELETE", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/journeys/${encodeURIComponent(params.journeyId)}`, {}, - options, + options ); } listSwarms( params: { projectId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", `/projects/${encodeURIComponent(params.projectId)}/swarms`, {}, - options, + options ); } getSwarm( params: { projectId: string; swarmId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/swarms/${encodeURIComponent(params.swarmId)}`, {}, - options, + options ); } @@ -3114,14 +3280,14 @@ export class PlatformApiClient { description?: string; environmentIds?: string[]; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { const { projectId, ...body } = params; return this.request( "POST", `/projects/${encodeURIComponent(projectId)}/swarms`, { body }, - options, + options ); } @@ -3135,16 +3301,16 @@ export class PlatformApiClient { sessionsPerTarget?: number; maxTurns?: number; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { const { projectId, swarmId, ...body } = params; return this.request( "PATCH", `/projects/${encodeURIComponent(projectId)}/swarms/${encodeURIComponent( - swarmId, + swarmId )}`, { body }, - options, + options ); } @@ -3154,15 +3320,15 @@ export class PlatformApiClient { */ archiveSwarm( params: { projectId: string; swarmId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "DELETE", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/swarms/${encodeURIComponent(params.swarmId)}`, {}, - options, + options ); } @@ -3184,14 +3350,14 @@ export class PlatformApiClient { description?: string; existingPersonas?: Array<{ name: string; role: string }>; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { const { projectId, ...body } = params; return this.request( "POST", `/projects/${encodeURIComponent(projectId)}/personas/generate`, { body }, - options, + options ); } @@ -3210,14 +3376,14 @@ export class PlatformApiClient { journeyCount?: number; description?: string; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { const { projectId, ...body } = params; return this.request( "POST", `/projects/${encodeURIComponent(projectId)}/journeys/generate`, { body }, - options, + options ); } @@ -3231,81 +3397,81 @@ export class PlatformApiClient { getSwarmOverview( params: { projectId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent(params.projectId)}/journeys-overview`, {}, - options, + options ); } getJourneyRunScorecard( params: { projectId: string; runId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/journey-runs/${encodeURIComponent(params.runId)}/scorecard`, {}, - options, + options ); } listSwarmFindings( params: { projectId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", `/projects/${encodeURIComponent(params.projectId)}/journey-findings`, {}, - options, + options ); } dismissSwarmFinding( params: { projectId: string; findingId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/journey-findings/${encodeURIComponent(params.findingId)}/dismiss`, {}, - options, + options ); } undismissSwarmFinding( params: { projectId: string; findingId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/journey-findings/${encodeURIComponent(params.findingId)}/undismiss`, {}, - options, + options ); } getWaveInsights( params: { projectId: string; waveId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/waves/${encodeURIComponent(params.waveId)}/insights`, {}, - options, + options ); } @@ -3320,15 +3486,15 @@ export class PlatformApiClient { */ requestWaveInsights( params: { projectId: string; waveId: string; force?: boolean }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/waves/${encodeURIComponent(params.waveId)}/insights`, { body: params.force ? { force: true } : {} }, - options, + options ); } @@ -3339,15 +3505,15 @@ export class PlatformApiClient { */ cancelWaveInsights( params: { projectId: string; waveId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "DELETE", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/waves/${encodeURIComponent(params.waveId)}/insights`, {}, - options, + options ); } @@ -3362,13 +3528,13 @@ export class PlatformApiClient { */ getCapabilities( params: { projectId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `/projects/${encodeURIComponent(params.projectId)}/capabilities`, {}, - options, + options ); } @@ -3393,7 +3559,7 @@ export class PlatformApiClient { description?: string; mode?: "project_members" | "invited_only" | "anyone_with_link"; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { const { projectId, environmentId } = params; // Explicit picks, not a rest spread: TypeScript's structural typing lets a @@ -3404,31 +3570,31 @@ export class PlatformApiClient { name: params.name, description: params.description, mode: params.mode, - }).filter(([, value]) => value !== undefined), + }).filter(([, value]) => value !== undefined) ); return this.request( "PUT", `/projects/${encodeURIComponent( - projectId, + projectId )}/environments/${encodeURIComponent(environmentId)}/scenario`, // Bodyless when there is nothing to send — the common case, and what // existing callers already put on the wire. Object.keys(body).length > 0 ? { body } : {}, - options, + options ); } unpublishScenario( params: { projectId: string; environmentId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "DELETE", `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/environments/${encodeURIComponent(params.environmentId)}/scenario`, {}, - options, + options ); } @@ -3464,16 +3630,16 @@ export class PlatformApiClient { description?: string; mode?: "project_members" | "invited_only" | "anyone_with_link"; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { const { projectId, environmentId, ...body } = params; return this.request( "PUT", `/projects/${encodeURIComponent( - projectId, + projectId )}/environments/${encodeURIComponent(environmentId)}/scenario`, { body }, - options, + options ); } @@ -3487,13 +3653,13 @@ export class PlatformApiClient { */ getUserTestingScenario( params: { projectId: string; scenarioId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", this.userTestingPath(params.projectId, params.scenarioId), {}, - options, + options ); } @@ -3512,14 +3678,14 @@ export class PlatformApiClient { description?: string; mode?: "project_members" | "invited_only" | "anyone_with_link"; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { const { projectId, scenarioId, ...body } = params; return this.request( "PATCH", this.userTestingPath(projectId, scenarioId), { body }, - options, + options ); } @@ -3531,13 +3697,13 @@ export class PlatformApiClient { cursor?: string; limit?: number; }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", `${this.userTestingPath(params.projectId, params.scenarioId)}/sessions`, { query: pageQuery(params) }, - options, + options ); } @@ -3556,22 +3722,22 @@ export class PlatformApiClient { cursor?: string; limit?: number; }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "GET", `${this.userTestingPath( params.projectId, - params.scenarioId, + params.scenarioId )}/sessions/${encodeURIComponent(params.sessionId)}`, { query: pageQuery(params) }, - options, + options ); } getUserTestingMetrics( params: { projectId: string; scenarioId: string; population?: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", @@ -3579,7 +3745,7 @@ export class PlatformApiClient { { query: params.population ? { population: params.population } : {}, }, - options, + options ); } @@ -3591,53 +3757,53 @@ export class PlatformApiClient { */ getUserTestingUsage( params: { projectId: string; scenarioId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", `${this.userTestingPath(params.projectId, params.scenarioId)}/usage`, {}, - options, + options ); } listUserTestingFindings( params: { projectId: string; scenarioId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise>> { return this.request( "GET", `${this.userTestingPath(params.projectId, params.scenarioId)}/findings`, {}, - options, + options ); } /** Also how you learn the CURRENT window id, which the insights read takes. */ getUserTestingSignals( params: { projectId: string; scenarioId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", `${this.userTestingPath(params.projectId, params.scenarioId)}/signals`, {}, - options, + options ); } getUserTestingInsights( params: { projectId: string; scenarioId: string; windowId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", `${this.userTestingPath( params.projectId, - params.scenarioId, + params.scenarioId )}/windows/${encodeURIComponent(params.windowId)}/insights`, {}, - options, + options ); } @@ -3648,38 +3814,38 @@ export class PlatformApiClient { */ requestUserTestingInsights( params: { projectId: string; scenarioId: string; force?: boolean }, - options?: RequestOptions, + options?: RequestOptions ): Promise { return this.request( "POST", `${this.userTestingPath(params.projectId, params.scenarioId)}/insights`, { body: params.force ? { force: true } : {} }, - options, + options ); } cancelUserTestingInsights( params: { projectId: string; scenarioId: string; windowId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "DELETE", `${this.userTestingPath(params.projectId, params.scenarioId)}/insights`, { body: { windowId: params.windowId } }, - options, + options ); } dismissUserTestingFinding( params: { projectId: string; scenarioId: string; findingId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.userTestingFindingAction(params, "dismiss", options); } undismissUserTestingFinding( params: { projectId: string; scenarioId: string; findingId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.userTestingFindingAction(params, "undismiss", options); } @@ -3697,16 +3863,16 @@ export class PlatformApiClient { scenarioId: string; guestExecution: PlatformGuestExecution; }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "PUT", `${this.userTestingPath( params.projectId, - params.scenarioId, + params.scenarioId )}/guest-execution`, { body: params.guestExecution }, - options, + options ); } @@ -3716,16 +3882,16 @@ export class PlatformApiClient { */ rotateUserTestingLink( params: { projectId: string; scenarioId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "POST", `${this.userTestingPath( params.projectId, - params.scenarioId, + params.scenarioId )}/rotate-link`, {}, - options, + options ); } @@ -3737,29 +3903,29 @@ export class PlatformApiClient { email: string; sendInviteEmail?: boolean; }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { const { projectId, scenarioId, ...body } = params; return this.request( "PUT", `${this.userTestingPath(projectId, scenarioId)}/members`, { body }, - options, + options ); } removeUserTestingMember( params: { projectId: string; scenarioId: string; member: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "DELETE", `${this.userTestingPath( params.projectId, - params.scenarioId, + params.scenarioId )}/members/${encodeURIComponent(params.member)}`, {}, - options, + options ); } @@ -3770,46 +3936,48 @@ export class PlatformApiClient { */ rebindUserTestingScenario( params: { projectId: string; scenarioId: string; environmentId: string }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "POST", `${this.userTestingPath(params.projectId, params.scenarioId)}/rebind`, { body: { environmentId: params.environmentId } }, - options, + options ); } private userTestingPath(projectId: string, scenarioId: string): string { return `/projects/${encodeURIComponent( - projectId, + projectId )}/user-testing/scenarios/${encodeURIComponent(scenarioId)}`; } private userTestingFindingAction( params: { projectId: string; scenarioId: string; findingId: string }, action: "dismiss" | "undismiss", - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "POST", `${this.userTestingPath( params.projectId, - params.scenarioId, + params.scenarioId )}/findings/${encodeURIComponent(params.findingId)}/${action}`, {}, - options, + options ); } private sharePath( projectId: string, resourceType: string, - resourceId: string, + resourceId: string ): string { - return `/projects/${encodeURIComponent(projectId)}/shares/${encodeURIComponent( - resourceType, - )}/${encodeURIComponent(resourceId)}`; + return `/projects/${encodeURIComponent( + projectId + )}/shares/${encodeURIComponent(resourceType)}/${encodeURIComponent( + resourceId + )}`; } getShareSettings( @@ -3818,13 +3986,13 @@ export class PlatformApiClient { resourceType: "scenario" | "conformanceRun" | "evalRun"; resourceId: string; }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "GET", this.sharePath(params.projectId, params.resourceType, params.resourceId), {}, - options, + options ); } @@ -3836,7 +4004,7 @@ export class PlatformApiClient { mode: "project_members" | "invited_only" | "anyone_with_link"; allowGuestAccess?: boolean; }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { const { projectId, resourceType, resourceId, mode, allowGuestAccess } = params; @@ -3849,7 +4017,7 @@ export class PlatformApiClient { ...(allowGuestAccess !== undefined ? { allowGuestAccess } : {}), }, }, - options, + options ); } @@ -3863,23 +4031,27 @@ export class PlatformApiClient { resourceType: "scenario" | "conformanceRun" | "evalRun"; resourceId: string; }, - options?: RequestOptions, + options?: RequestOptions ): Promise> { return this.request( "POST", - `${this.sharePath(params.projectId, params.resourceType, params.resourceId)}/rotate-link`, + `${this.sharePath( + params.projectId, + params.resourceType, + params.resourceId + )}/rotate-link`, {}, - options, + options ); } private serverOp( params: ServerScope & { body?: Record }, op: string, - options?: RequestOptions, + options?: RequestOptions ): Promise { const path = `/projects/${encodeURIComponent( - params.projectId, + params.projectId )}/servers/${encodeURIComponent(params.serverId)}/${op}`; return this.request("POST", path, { body: params.body ?? {} }, options); } @@ -3892,7 +4064,7 @@ export class PlatformApiClient { method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", path: string, init: { query?: QueryParams; body?: unknown }, - options?: RequestOptions, + options?: RequestOptions ): Promise { const url = resolvePlatformRequestUrl(`${this.baseUrl}${path}`); for (const [name, value] of Object.entries(init.query ?? {})) { @@ -3929,9 +4101,9 @@ export class PlatformApiClient { const timeoutHandle = setTimeout( () => controller.abort( - new Error(`Request timed out after ${this.timeoutMs}ms`), + new Error(`Request timed out after ${this.timeoutMs}ms`) ), - this.timeoutMs, + this.timeoutMs ); // BOTH THE FETCH AND THE BODY READ ARE INSIDE THIS `try`, and that is the @@ -3962,10 +4134,10 @@ export class PlatformApiClient { aborted ? `Request to ${path} timed out after ${this.timeoutMs}ms` : `Failed to reach the MCPJam API at ${url.origin}: ${errorMessage( - error, + error )}`, aborted ? "TIMEOUT" : "NETWORK_ERROR", - { status: 0, endpoint: path, cause: error }, + { status: 0, endpoint: path, cause: error } ); } @@ -3981,13 +4153,13 @@ export class PlatformApiClient { throw new PlatformApiError( `Request to ${path} timed out after ${this.timeoutMs}ms`, "TIMEOUT", - { status: 0, endpoint: path, cause: error }, + { status: 0, endpoint: path, cause: error } ); } throw new PlatformApiError( `Failed to read the MCPJam API response (${response.status}) for ${path}`, "INTERNAL_ERROR", - { status: response.status, endpoint: path, cause: error }, + { status: response.status, endpoint: path, cause: error } ); } } finally { @@ -4015,7 +4187,7 @@ export class PlatformApiClient { throw new PlatformApiError( `The MCPJam API returned a non-JSON response (${response.status}) for ${path}`, "INTERNAL_ERROR", - { status: response.status, endpoint: path, cause: parseError }, + { status: response.status, endpoint: path, cause: parseError } ); } @@ -4026,7 +4198,7 @@ export class PlatformApiClient { private toApiError( response: Response, body: unknown, - path: string, + path: string ): PlatformApiError { const envelope = body && typeof body === "object" && !Array.isArray(body) @@ -4072,7 +4244,7 @@ function fallbackCodeForStatus(status: number): string { function parseRetryAfter( header: string | null, - now: number = Date.now(), + now: number = Date.now() ): number | undefined { if (!header) return undefined; const seconds = Number(header); diff --git a/sdk/src/platform/index.ts b/sdk/src/platform/index.ts index 2d99cceada..d79656dea2 100644 --- a/sdk/src/platform/index.ts +++ b/sdk/src/platform/index.ts @@ -190,6 +190,7 @@ export type { PlatformEvalSuiteSettings, PlatformEvalSuiteComputerEnvironment, PlatformEnvironment, + PlatformEnvironmentSecretSelection, PlatformJourney, PlatformJourneyRun, PlatformJourneyRunAttempt, @@ -202,6 +203,8 @@ export type { PlatformJourneyArchived, PlatformPersona, PlatformPersonaDeleted, + PlatformSecret, + PlatformSecretDeleted, PlatformRunScorecard, PlatformScenario, PlatformSwarm, @@ -396,6 +399,11 @@ export { createPersonaOperation, updatePersonaOperation, deletePersonaOperation, + listSecretsOperation, + getSecretOperation, + createSecretOperation, + updateSecretOperation, + deleteSecretOperation, generatePersonasOperation, getJourneyOperation, createJourneyOperation, @@ -583,6 +591,16 @@ export { type UpdatePersonaResult, type DeletePersonaInput, type DeletePersonaResult, + type ListSecretsInput, + type ListSecretsResult, + type GetSecretInput, + type GetSecretResult, + type CreateSecretInput, + type CreateSecretResult, + type UpdateSecretInput, + type UpdateSecretResult, + type DeleteSecretInput, + type DeleteSecretResult, type GeneratePersonasInput, type GeneratePersonasResult, type GetJourneyInput, diff --git a/sdk/src/platform/operations.ts b/sdk/src/platform/operations.ts index 0f4cd98d71..fbc2ddc7e9 100644 --- a/sdk/src/platform/operations.ts +++ b/sdk/src/platform/operations.ts @@ -106,6 +106,8 @@ import type { PlatformJourneyRunCanceled, PlatformPersona, PlatformPersonaDeleted, + PlatformSecret, + PlatformSecretDeleted, PlatformRunScorecard, PlatformSessionSummary, PlatformSwarm, @@ -7534,11 +7536,11 @@ async function resolveClient( client: PlatformApiClient, project: PlatformProject, selector: string, - signal: AbortSignal | undefined, + signal: AbortSignal | undefined ): Promise { return client.getClient( { projectId: project.id, client: selector }, - { signal }, + { signal } ); } @@ -7573,7 +7575,7 @@ export const listClientsOperation: PlatformOperation< ); const page = await client.listClients( { projectId: project.id }, - { signal }, + { signal } ); return { project: toSelectedProjectInfo(project), @@ -7629,7 +7631,7 @@ const createClientInput = z .min(1) .optional() .describe( - "Built-in template to seed the client config from (e.g. claude, chatgpt, cursor).", + "Built-in template to seed the client config from (e.g. claude, chatgpt, cursor)." ), theme: z .enum(["light", "dark"]) @@ -7639,7 +7641,7 @@ const createClientInput = z .record(z.string(), z.unknown()) .optional() .describe( - "Full client config v2 to use verbatim (alternative to template). Must pin a non-empty `modelId`.", + "Full client config v2 to use verbatim (alternative to template). Must pin a non-empty `modelId`." ), }) // ONE `superRefine`, shaped exactly like the route's, because the route's 400 @@ -7725,7 +7727,7 @@ const clientFieldSet = z .min(1) .optional() .describe( - "Model the client pins. Value only — there is no null, and a blank string is refused.", + "Model the client pins. Value only — there is no null, and a blank string is refused." ), systemPrompt: z .string() @@ -7751,7 +7753,7 @@ const clientFieldSet = z .nullable() .optional() .describe( - "Whole-object replacement. null resets to the platform defaults.", + "Whole-object replacement. null resets to the platform defaults." ), respectToolVisibility: z .boolean() @@ -7768,7 +7770,7 @@ const clientFieldSet = z .nullable() .optional() .describe( - "Execution runtime. null clears it (back to emulated). Setting one needs the matching feature flag; clearing never does.", + "Execution runtime. null clears it (back to emulated). Setting one needs the matching feature flag; clearing never does." ), computer: z .object({ @@ -7858,12 +7860,12 @@ const updateClientInput = z .record(z.string(), z.unknown()) .optional() .describe( - "Whole-config replacement. Prefer `set` — a full round-trip composed from a stale read reverts whatever landed in between.", + "Whole-config replacement. Prefer `set` — a full round-trip composed from a stale read reverts whatever landed in between." ), set: clientFieldSet .optional() .describe( - "Named fields to change, applied over the client's current config inside the write transaction.", + "Named fields to change, applied over the client's current config inside the write transaction." ), }) // Mirrors the route's 400s exactly, so an agent is refused by the schema with @@ -7932,7 +7934,7 @@ export const updateClientOperation: PlatformOperation< async execute(input, { client, signal, onScopeResolved }) { const { project } = await resolveProjectOrThrow( { client, signal, onScopeResolved }, - input.project, + input.project ); const body: Record = {}; if (input.name !== undefined) body.name = input.name; @@ -7948,7 +7950,7 @@ export const updateClientOperation: PlatformOperation< if (input.set !== undefined) body.set = input.set; return client.updateClient( { projectId: project.id, client: input.client, body }, - { signal }, + { signal } ); }, }; @@ -7979,7 +7981,7 @@ export const deleteClientOperation: PlatformOperation< async execute(input, { client, signal, onScopeResolved }) { const { project } = await resolveProjectOrThrow( { client, signal, onScopeResolved }, - input.project, + input.project ); return client.deleteClient( { @@ -7988,7 +7990,7 @@ export const deleteClientOperation: PlatformOperation< // The v1 delete contract is bodyless — the route rejects any field. body: {}, }, - { signal }, + { signal } ); }, }; @@ -8034,7 +8036,7 @@ export const setClientServersOperation: PlatformOperation< async execute(input, { client, signal, onScopeResolved }) { const { project } = await resolveProjectOrThrow( { client, signal, onScopeResolved }, - input.project, + input.project ); return client.setClientServers( { @@ -8047,7 +8049,7 @@ export const setClientServersOperation: PlatformOperation< ? { expectedImpact: input.expectedImpact } : {}), }, - { signal }, + { signal } ); }, }; @@ -8080,11 +8082,11 @@ export const duplicateClientOperation: PlatformOperation< async execute(input, { client, signal, onScopeResolved }) { const { project } = await resolveProjectOrThrow( { client, signal, onScopeResolved }, - input.project, + input.project ); return client.duplicateClient( { projectId: project.id, client: input.client, name: input.name }, - { signal }, + { signal } ); }, }; @@ -8131,7 +8133,7 @@ export const listHostsOperation: PlatformOperation< async execute(input, { client, signal, onScopeResolved }) { const { project, sortedProjects } = await resolveProjectOrThrow( { client, signal, onScopeResolved }, - input.project, + input.project ); const page = await client.listHosts({ projectId: project.id }, { signal }); return { @@ -8153,14 +8155,14 @@ async function resolveHost( client: PlatformApiClient, project: PlatformProject, selector: string, - signal: AbortSignal | undefined, + signal: AbortSignal | undefined ): Promise { const page = await client.listHosts({ projectId: project.id }, { signal }); return resolveByIdOrName( page.items, selector, "Host", - `project "${project.name}"`, + `project "${project.name}"` ); } @@ -8193,12 +8195,12 @@ export const getHostOperation: PlatformOperation< async execute(input, { client, signal, onScopeResolved }) { const { project } = await resolveProjectOrThrow( { client, signal, onScopeResolved }, - input.project, + input.project ); const host = await resolveHost(client, project, input.host, signal); return client.getHost( { projectId: project.id, hostId: host.id }, - { signal }, + { signal } ); }, }; @@ -8309,7 +8311,7 @@ export const createHostOperation: PlatformOperation< async execute(input, { client, signal, onScopeResolved }) { const { project } = await resolveProjectOrThrow( { client, signal, onScopeResolved }, - input.project, + input.project ); const body: Record = { name: input.name }; if (input.template) { @@ -8358,7 +8360,7 @@ export const deleteHostOperation: PlatformOperation< // The v1 delete contract is bodyless — the route rejects any field. body: {}, }, - { signal }, + { signal } ); }, }; @@ -8453,7 +8455,6 @@ export const duplicateHostOperation: PlatformOperation< }, }; - // ── Project Environments ───────────────────────────────────────────────────── // // Named execution bundles (one host + optional server group + optional pinned @@ -9350,7 +9351,7 @@ export const listProjectSkillsOperation: PlatformOperation< name: "list_project_skills", title: "List MCPJam project skills", description: - "List the Cloud Skills visible to you in an MCPJam project — the project-shared ones plus your own personal drafts. Use this to obtain the skill IDs that environments pin via skillSelection and that eval runs pin via --compose-skill. Only `sharing: \"project\"` skills can be pinned; each row's `pinnability` says whether that skill is eligible and, if not, why.", + 'List the Cloud Skills visible to you in an MCPJam project — the project-shared ones plus your own personal drafts. Use this to obtain the skill IDs that environments pin via skillSelection and that eval runs pin via --compose-skill. Only `sharing: "project"` skills can be pinned; each row\'s `pinnability` says whether that skill is eligible and, if not, why.', readOnly: true, permalink: noPermalink( "route-not-addressable", @@ -10828,6 +10829,344 @@ export const deletePersonaOperation: PlatformOperation< }, }; +// ── Project secrets ───────────────────────────────────────────────────────── +// +// WRITE-ONLY. No operation here returns a value, and none can: the DTO has no +// such field and the backend has no code path that produces one. +// +// `create_secret` and `update_secret` are excluded from the MCP catalog and the +// agent registry (see `platformTools.ts` and `agent-op-registry.ts`), because +// their input CARRIES the value — it would transit model context and be written +// into chat transcripts before any approval could run. They stay reachable over +// HTTP, the SDK and the CLI, where the caller controls where the value comes +// from. + +const secretSelectorInput = z.object({ + project: z + .string() + .trim() + .min(1) + .optional() + .describe(PROJECT_SELECTOR_DESCRIPTION), + secret: z.string().trim().min(1).describe("Secret id."), +}); + +const SECRET_NAME_DESCRIPTION = + "Environment-variable name — uppercase letters, digits and underscores, not starting with a digit (STRIPE_API_KEY). This IS the secret's identity: it is what a materialized delivery exports and what a workflow references, and it is immutable (renaming means delete and recreate)."; + +const SECRET_DELIVERY_DESCRIPTION = + "How the value reaches a run. 'brokered' (prefer this): the sandbox's egress proxy injects it as a request header OUTSIDE the VM, so the box never holds it and a prompt-injected agent has nothing to exfiltrate — but it prevents EXTRACTION, not USE (any process in the box can call the bound host while the policy is live), and it works for HTTPS APIs only. 'materialized': a real environment variable inside the box, which is the only thing a CLI can read — EXTRACTABLE BY DESIGN, `env` prints it."; + +const SECRET_SHARING_DESCRIPTION = + "'project' (default) — admin-managed, delivered to every member's sessions. 'user' — personal, delivered ONLY in sessions its owner starts and silently absent from anyone else's run of the same environment. Immutable."; + +const secretBrokerFields = { + brokerHosts: z + .array(z.string().trim().min(1).max(253)) + .min(1) + .max(10) + .optional() + .describe( + "Brokered only, and required for it: the exact hostnames the header is injected on (api.stripe.com). No scheme, no port, no wildcard — the proxy matches a host, and a URL would install a rule that silently never fires." + ), + brokerHeader: z + .string() + .trim() + .min(1) + .max(64) + .optional() + .describe( + "Brokered only, and required for it: the header name, e.g. Authorization." + ), + brokerTemplate: z + .string() + .min(1) + .max(256) + .optional() + .describe( + "Brokered only, and required for it: the header value, with {} where the secret goes — 'Bearer {}'. A template without {} is rejected: it would install a constant header that never carries the credential." + ), +} as const; + +export type ListSecretsInput = z.infer; +const listSecretsInput = z.object({ + project: z + .string() + .trim() + .min(1) + .optional() + .describe(PROJECT_SELECTOR_DESCRIPTION), +}); + +export type ListSecretsResult = { + project: SelectedProjectInfo; + items: PlatformSecret[]; +}; + +export const listSecretsOperation: PlatformOperation< + ListSecretsInput, + ListSecretsResult +> = { + name: "list_secrets", + title: "List MCPJam project secrets", + description: + "The project's credentials, as METADATA ONLY — name, delivery mode, host binding, sharing, when each was last delivered. No value is ever returned by this or any other operation. Shows the project-shared secrets plus your own personal ones; another member's personal secret does not appear at all. Read this to find out what an environment can grant before selecting one.", + readOnly: true, + permalink: noPermalink( + "route-not-addressable", + "Secrets are managed inside the project settings surface as component state; there is no `secrets/:secretId` route." + ), + inputSchema: listSecretsInput, + async execute(input, { client, signal, onScopeResolved }) { + const { project } = await resolveProjectOrThrow( + { client, signal, onScopeResolved }, + input.project + ); + const page = await client.listSecrets( + { projectId: project.id }, + { signal } + ); + return { project: toSelectedProjectInfo(project), items: page.items }; + }, +}; + +export type GetSecretInput = z.infer; +export type GetSecretResult = { + project: SelectedProjectInfo; + secret: PlatformSecret; +}; + +export const getSecretOperation: PlatformOperation< + GetSecretInput, + GetSecretResult +> = { + name: "get_secret", + title: "Get one MCPJam project secret", + description: + "One secret's metadata: delivery mode, host binding, sharing, and when it was last handed to a run. NEVER its value. Note that lastDeliveredAt means delivered, not used — brokered use is unobservable to us by construction, since the proxy injects the header and we never see the request.", + readOnly: true, + permalink: noPermalink( + "route-not-addressable", + "Secrets are managed inside the project settings surface as component state; there is no `secrets/:secretId` route." + ), + inputSchema: secretSelectorInput, + async execute(input, { client, signal, onScopeResolved }) { + const { project } = await resolveProjectOrThrow( + { client, signal, onScopeResolved }, + input.project + ); + const secret = await client.getSecret( + { projectId: project.id, secretId: input.secret }, + { signal } + ); + return { project: toSelectedProjectInfo(project), secret }; + }, +}; + +const createSecretInput = z.object({ + project: z + .string() + .trim() + .min(1) + .optional() + .describe(PROJECT_SELECTOR_DESCRIPTION), + name: z.string().trim().min(1).max(64).describe(SECRET_NAME_DESCRIPTION), + value: z + .string() + .min(1) + .max(64 * 1024) + .describe( + "The credential itself. IT BECOMES VISIBLE TO WHATEVER SURFACE CARRIES THIS CALL — it travels in the request body, so it passes through that surface's process, logs, shell history and any transcript it keeps. Read it from a file, an environment variable or stdin rather than typing it into an argument. It is stored encrypted and no operation ever returns it." + ), + description: z + .string() + .max(500) + .optional() + .describe( + "What this credential is for, so a teammate does not have to guess." + ), + delivery: z + .enum(["brokered", "materialized"]) + .describe(SECRET_DELIVERY_DESCRIPTION), + ...secretBrokerFields, + sharing: z + .enum(["user", "project"]) + .optional() + .describe(SECRET_SHARING_DESCRIPTION), + idempotencyKey: z + .string() + .trim() + .min(1) + .max(200) + .optional() + .describe( + "Retry key. Pass one: a retried create without it fails as a name conflict with the row the first attempt already made, which is indistinguishable from a real collision." + ), +}); + +export type CreateSecretInput = z.infer; +export type CreateSecretResult = { + project: SelectedProjectInfo; + secret: PlatformSecret; +}; + +export const createSecretOperation: PlatformOperation< + CreateSecretInput, + CreateSecretResult +> = { + name: "create_secret", + title: "Create an MCPJam project secret", + description: + "Store a credential a workflow needs (a stripe CLI run, gh, psql) so environments can grant it to runs. THE VALUE TRAVELS IN THIS CALL and becomes visible to whatever surface makes it — its process, its logs, its transcript — so supply it from a file or an environment variable, not from something a human typed into a chat. Choose delivery deliberately: 'brokered' keeps the value outside the sandbox, 'materialized' puts it inside as an environment variable where a CLI can read it and anything in the box can print it. The response is metadata only.", + readOnly: false, + risk: "exposure", + permalink: noPermalink("mutation-only"), + inputSchema: createSecretInput, + async execute(input, { client, signal, onScopeResolved }) { + const { project } = await resolveProjectOrThrow( + { client, signal, onScopeResolved }, + input.project + ); + const secret = await client.createSecret( + { + projectId: project.id, + name: input.name, + value: input.value, + ...(input.description !== undefined + ? { description: input.description } + : {}), + delivery: input.delivery, + ...(input.brokerHosts !== undefined + ? { brokerHosts: input.brokerHosts } + : {}), + ...(input.brokerHeader !== undefined + ? { brokerHeader: input.brokerHeader } + : {}), + ...(input.brokerTemplate !== undefined + ? { brokerTemplate: input.brokerTemplate } + : {}), + ...(input.sharing !== undefined ? { sharing: input.sharing } : {}), + }, + { + signal, + ...(input.idempotencyKey + ? { idempotencyKey: input.idempotencyKey } + : {}), + } + ); + return { project: toSelectedProjectInfo(project), secret }; + }, +}; + +const updateSecretInput = z.object({ + project: z + .string() + .trim() + .min(1) + .optional() + .describe(PROJECT_SELECTOR_DESCRIPTION), + secret: z.string().trim().min(1).describe("Secret id."), + value: z + .string() + .min(1) + .max(64 * 1024) + .optional() + .describe( + "The new credential — a ROTATION. Same exposure as on create: it travels in this call and becomes visible to whatever surface makes it. Reaches NEW RUNS ONLY; a session already running holds the old value and cannot be reached mid-run." + ), + description: z + .string() + .max(500) + .optional() + .describe("Replacement description."), + delivery: z + .enum(["brokered", "materialized"]) + .optional() + .describe( + `${SECRET_DELIVERY_DESCRIPTION} Switching to 'brokered' requires supplying the host binding in the same call; switching to 'materialized' clears it.` + ), + ...secretBrokerFields, +}); + +export type UpdateSecretInput = z.infer; +export type UpdateSecretResult = { + project: SelectedProjectInfo; + secret: PlatformSecret; +}; + +export const updateSecretOperation: PlatformOperation< + UpdateSecretInput, + UpdateSecretResult +> = { + name: "update_secret", + title: "Rotate or re-bind an MCPJam project secret", + description: + "Rotate a secret's value and/or change how it is delivered. THE NEW VALUE TRAVELS IN THIS CALL, with the same exposure as create. A rotation reaches NEW RUNS ONLY — a session already running holds the old value, in its box's environment or inside an egress policy that cannot be read back, and there is no safe way to replace it mid-run. `name` and `sharing` cannot be changed: renaming would break the workflows referencing the environment variable, and re-sharing would change who has already been handed the value. Delete and recreate for either.", + readOnly: false, + risk: "exposure", + permalink: noPermalink("mutation-only"), + inputSchema: updateSecretInput, + async execute(input, { client, signal, onScopeResolved }) { + const { project } = await resolveProjectOrThrow( + { client, signal, onScopeResolved }, + input.project + ); + const secret = await client.updateSecret( + { + projectId: project.id, + secretId: input.secret, + ...(input.value !== undefined ? { value: input.value } : {}), + ...(input.description !== undefined + ? { description: input.description } + : {}), + ...(input.delivery !== undefined ? { delivery: input.delivery } : {}), + ...(input.brokerHosts !== undefined + ? { brokerHosts: input.brokerHosts } + : {}), + ...(input.brokerHeader !== undefined + ? { brokerHeader: input.brokerHeader } + : {}), + ...(input.brokerTemplate !== undefined + ? { brokerTemplate: input.brokerTemplate } + : {}), + }, + { signal } + ); + return { project: toSelectedProjectInfo(project), secret }; + }, +}; + +export type DeleteSecretInput = z.infer; +export type DeleteSecretResult = { + project: SelectedProjectInfo; + secret: PlatformSecretDeleted; +}; + +export const deleteSecretOperation: PlatformOperation< + DeleteSecretInput, + DeleteSecretResult +> = { + name: "delete_secret", + title: "Delete an MCPJam project secret", + description: + "Revoke a credential. HARD — the row and the encrypted value both go, and nothing keeps resolving it. Deliberately NOT blocked when an environment still selects it: refusing would make a leaked credential un-revokable until someone edited every environment naming it, and revocation must never wait on cleanup. Runs already in flight keep the value they were handed.", + readOnly: false, + risk: "destructive", + permalink: noPermalink("mutation-only"), + inputSchema: secretSelectorInput, + async execute(input, { client, signal, onScopeResolved }) { + const { project } = await resolveProjectOrThrow( + { client, signal, onScopeResolved }, + input.project + ); + const secret = await client.deleteSecret( + { projectId: project.id, secretId: input.secret }, + { signal } + ); + return { project: toSelectedProjectInfo(project), secret }; + }, +}; + const journeySelectorInput = z.object({ project: z .string() @@ -13463,6 +13802,16 @@ export const ALL_OPERATIONS: readonly AnyPlatformOperation[] = [ createPersonaOperation, updatePersonaOperation, deletePersonaOperation, + // PROJECT SECRETS. Write-only end to end — no operation here returns a value. + // The two write ops carry one in their INPUT, which is why they are excluded + // from the MCP catalog and the agent registry (see `platformTools.ts` and + // `agent-op-registry.ts`) while staying reachable over HTTP, the SDK and the + // CLI. + listSecretsOperation, + getSecretOperation, + createSecretOperation, + updateSecretOperation, + deleteSecretOperation, generatePersonasOperation, getJourneyOperation, createJourneyOperation, diff --git a/sdk/src/platform/types.ts b/sdk/src/platform/types.ts index 7e8ad9a10c..4f1162a0ae 100644 --- a/sdk/src/platform/types.ts +++ b/sdk/src/platform/types.ts @@ -1980,6 +1980,7 @@ export interface PlatformEnvironment { */ modelId?: string; skillSelection?: PlatformEnvironmentSkillSelection; + secretSelection?: PlatformEnvironmentSecretSelection; /** * Pinned plugin VERSIONS. Narrow by design: a version is pinnable only when * its plugin is installed and enabled, the version is `ready`, at most one @@ -2024,6 +2025,7 @@ export interface PlatformAdhocEnvironment { /** See `PlatformEnvironment.modelId` — absent means "inherit the host's". */ modelId?: string; skillSelection?: PlatformEnvironmentSkillSelection; + secretSelection?: PlatformEnvironmentSecretSelection; pluginVersionIds?: string[]; sandboxImageId?: string; /** Pass back as `expectedRevision` when promoting it with a name. */ @@ -2057,6 +2059,7 @@ export interface PlatformAdhocEnvironmentBody { serverAttachmentId?: string; modelId?: string; skillSelection?: PlatformEnvironmentSkillSelection; + secretSelection?: PlatformEnvironmentSecretSelection; pluginVersionIds?: string[]; sandboxImageId?: string; } @@ -2090,6 +2093,7 @@ export interface PlatformEnvironmentCreateBody { /** Model to run instead of the host's; omit to inherit the host's. */ modelId?: string; skillSelection?: PlatformEnvironmentSkillSelection; + secretSelection?: PlatformEnvironmentSecretSelection; pluginVersionIds?: string[]; /** Project-shared `PlatformImage` id to pin; omit for the default image. */ sandboxImageId?: string; @@ -2115,6 +2119,12 @@ export interface PlatformEnvironmentUpdateBody { */ modelId?: string | null; skillSelection?: PlatformEnvironmentSkillSelection | null; + /** + * New credential grant, or `null` to REVOKE it entirely. Omit to leave + * unchanged. `[]` is rejected: an accidental empty array that read as "remove + * every credential" would break a workflow with no error to look at. + */ + secretSelection?: PlatformEnvironmentSecretSelection | null; pluginVersionIds?: string[] | null; /** New sandbox-image pin, or null to clear it. Omit to leave unchanged. */ sandboxImageId?: string | null; @@ -2202,6 +2212,28 @@ export interface PlatformEnvironmentResolved { // programmatic way to obtain one. Authoring stays on the app's `/api/web` // surface behind the `skills-enabled` beta gate. +/** + * Which PROJECT SECRETS a run launched from this environment receives. + * + * Ids only. The environment is the GRANT BOUNDARY: no selection means no + * secrets, and there is no "all of them" mode — a credential is granted + * deliberately, per environment. + * + * Deliberately simpler than `PlatformEnvironmentSkillSelection`: no version + * pins, because a secret has exactly one current value and "pin the previous + * value" is the opposite of what rotation is for. + * + * Membership is not the same as delivery. A `sharing: "user"` secret selected + * here reaches ONLY sessions its owner started; every other member's run of + * this environment silently does not receive it. That rule is checked live at + * launch, so revoking someone's access does not require editing every + * environment that names their secret. + */ +export interface PlatformEnvironmentSecretSelection { + mode: "explicit"; + secretIds: string[]; +} + /** Why a skill cannot be pinned into an environment's `skillSelection`. */ export type PlatformSkillPinnability = | { ok: true } @@ -2832,6 +2864,79 @@ export interface PlatformPersona { updatedAt: number; } +/** + * A PROJECT SECRET — metadata only, always. + * + * There is no `value` field on this type, and there is no route, operation, or + * tool that returns one. A secret is written and delivered; it is never read + * back. That is the contract, not a default: the only code that decrypts writes + * into a sandbox's environment or an egress policy and returns nothing. + */ +export interface PlatformSecret { + id: string; + projectId: string; + /** + * The environment-variable name (`^[A-Z_][A-Z0-9_]*$`). This IS the secret's + * identity: it is what a materialized delivery exports, what a workflow + * references, and what stays stable across a rotation. Immutable — renaming + * is delete-and-recreate. + */ + name: string; + description: string | null; + /** + * How the value reaches a run. + * + * - `"brokered"` — injected as a request header by the sandbox's egress + * proxy, OUTSIDE the VM. The box never holds it, so a prompt-injected + * agent has nothing to exfiltrate. Prevents EXTRACTION, not USE: any + * process in the box can call the bound host while the policy is live. + * HTTPS APIs only (the proxy binds domain rules on ports 80/443). + * - `"materialized"` — a real environment variable inside the box, because a + * CLI cannot read a header the proxy adds. EXTRACTABLE BY DESIGN: `env` + * prints it. + */ + delivery: "brokered" | "materialized"; + /** Brokered only: the exact hostnames the header is injected on. */ + brokerHosts?: string[]; + /** Brokered only: the header name, e.g. `Authorization`. */ + brokerHeader?: string; + /** Brokered only: the header value template; `{}` is where the value goes. */ + brokerTemplate?: string; + /** + * `"project"` — admin-managed, delivered to every member's sessions. + * `"user"` — personal; delivered ONLY in sessions its owner starts, and + * silently absent from another member's run of the same environment. + * Immutable — re-sharing is delete-and-recreate. + */ + sharing: "user" | "project"; + /** Personal secrets only. Project-shared rows have no owner. */ + ownerUserId?: string; + /** + * When this secret was last HANDED TO a run — not when it was last used. + * Brokered use is unobservable by construction (the proxy injects the header; + * we never see the request), so "used" would be a number nobody can honestly + * produce. `null` means nothing has been recorded, which is not the same as + * "never delivered". + */ + lastDeliveredAt: number | null; + createdAt: number; + updatedAt: number; + createdByUserId: string; + updatedByUserId: string; +} + +/** + * Result of deleting a secret. A HARD delete — the row and the ciphertext both + * go. This is the revoke button, so it must not be soft. + */ +export interface PlatformSecretDeleted { + id: string; + projectId: string; + /** Echoed so a caller logging the revoke does not need a prior read. */ + name: string; + deleted: true; +} + /** Result of deleting a persona. The delete is SOFT: history still resolves it. */ export interface PlatformPersonaDeleted { id: string; diff --git a/sdk/tests/platform/operations.test.ts b/sdk/tests/platform/operations.test.ts index c3b97051bf..393bcd0168 100644 --- a/sdk/tests/platform/operations.test.ts +++ b/sdk/tests/platform/operations.test.ts @@ -586,9 +586,9 @@ function makeClient(overrides: FixtureOverrides = {}): { { id: "scenario-1", environmentId, - name: created ? ((requestBody.name as string) ?? "Checkout") : "Kept", + name: created ? (requestBody.name as string) ?? "Checkout" : "Kept", mode: created - ? ((requestBody.mode as string) ?? "project_members") + ? (requestBody.mode as string) ?? "project_members" : "anyone_with_link", accessVersion: 1, link: "https://app.mcpjam.com/s/checkout?t=abc", @@ -1251,9 +1251,9 @@ describe("createEvalSuiteOperation", () => { }); expect(parsed.success).toBe(false); if (parsed.success) return; - expect(parsed.error.issues.some((issue) => /hostz/.test(issue.message))).toBe( - true - ); + expect( + parsed.error.issues.some((issue) => /hostz/.test(issue.message)) + ).toBe(true); }); it("requires a name, at least one server, and at least one case", () => { @@ -1948,6 +1948,18 @@ describe("operation catalog consistency", () => { create_persona: { name: "Ada", role: "buyer" }, update_persona: { persona: "pe", name: "Ada" }, delete_persona: { persona: "pe" }, + list_secrets: {}, + get_secret: { secret: "sec" }, + // `delivery` is REQUIRED with no default, which is the point: a caller who + // has not said whether the value ends up inside the sandbox has not made + // the decision this operation exists to make. + create_secret: { + name: "STRIPE_API_KEY", + value: "sk_live_example_value", + delivery: "materialized", + }, + update_secret: { secret: "sec", value: "sk_live_rotated_value" }, + delete_secret: { secret: "sec" }, generate_personas: { environmentId: "e" }, get_journey: { journey: "j" }, create_journey: { @@ -2197,6 +2209,11 @@ describe("operation catalog consistency", () => { "create_persona", "update_persona", "delete_persona", + // Secret writes. `create_secret` and `update_secret` carry a credential + // in their INPUT (risk: exposure); `delete_secret` revokes one. + "create_secret", + "update_secret", + "delete_secret", "create_journey", "update_journey", "archive_journey", @@ -2431,14 +2448,18 @@ describe("registry operations", () => { if (path === "/api/v1/projects") { return Response.json({ items: PROJECTS }); } - if (/^\/api\/v1\/projects\/[^/]+\/registry\/directory-installs$/.test(path)) { + if ( + /^\/api\/v1\/projects\/[^/]+\/registry\/directory-installs$/.test(path) + ) { return Response.json({ serverId: "server-installed", serverName: "Installed", outcome: options?.outcome ?? "created", }); } - if (/^\/api\/v1\/projects\/[^/]+\/servers\/server-installed$/.test(path)) { + if ( + /^\/api\/v1\/projects\/[^/]+\/servers\/server-installed$/.test(path) + ) { return Response.json({ id: "server-installed", projectId: "project-new", From 882542b0fcd02e66a3dbb34d0c8b93e58dd96b12 Mon Sep 17 00:00:00 2001 From: MCPJam Date: Fri, 28 Aug 2026 04:35:47 +0000 Subject: [PATCH 03/12] Manage secrets in the app, and grant them per environment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two surfaces. A Secrets section in project settings, where credentials are created, rotated and revoked; and a picker on the environment editor, where an environment says which of them its runs receive. Neither shows a value, and no state in either holds one past a submit. The create and rotate dialogs clear their field on success and say plainly that it cannot be read back — a masked field that looks like it is holding something invites people to come back looking for it. The delivery radio is the point of the create form, so it says what each mode actually does where the choice is made: brokered is invisible to `echo $NAME` and unreadable by a CLI; materialized is printed by `env`. Picking wrong produces a workflow that silently does not work, and neither option is simply "more secure" than the other. Personal secrets are selectable in the environment picker — unlike skills, which refuse them outright. That is the motivating workflow: your session gets your key, a teammate's session of the same environment does not. The "only your sessions" chip says so at the point of selection, because discovering it from a teammate's failing run is the bad version. Another member's personal secret cannot appear at all; the query does not return it. Clearing the last selection emits `null`, not `[]` — `[]` fails the save, and `null` is what revokes the grant. A selected id the query never returns gets a detach-only row, or it would be invisible, unremovable, and still shipped on every save. Delete names the environments that stop delivering the secret, as information rather than a blocker: revocation is never gated on cleanup, and someone revoking a leaked credential must not be told to go edit five environments first. The harness turn no longer fetches its own secrets. Delivering a value and scrubbing it from the transcript are two uses of one list, and only the caller — which builds the persist callback — can wire the second; a turn that fetched for itself would put the value in the box and then persist it verbatim, which is worse than delivering none. A caller that has not wired secrets now delivers none, and the runtime fingerprint omits the dimension so those sessions keep resuming. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01MCmi5hBBosufjwQ6L6UxPJ --- .../src/components/ProjectSettingsTab.tsx | 33 +- .../__tests__/ProjectSettingsTab.test.tsx | 12 +- .../environment-composer/environment-stack.ts | 23 + .../ProjectEnvironmentEditor.tsx | 51 +- .../ProjectEnvironmentSecretsPicker.tsx | 241 ++++++ .../archive-consumer-counts.test.tsx | 20 +- .../environment-canvas-panel.test.tsx | 22 +- .../__tests__/environment-picker.test.tsx | 44 +- .../environment-secrets-picker.test.tsx | 172 ++++ .../name-environment-dialog.test.tsx | 11 +- .../__tests__/orphan-selections.test.tsx | 18 +- ...-environment-editor.initial-draft.test.tsx | 10 +- ...nment-editor.optional-description.test.tsx | 12 +- ...-environment-editor.sandbox-image.test.tsx | 40 +- ...ct-environment-editor.skills-gate.test.tsx | 30 +- ...ronment-mutations.project-scoping.test.tsx | 9 +- ...ject-environments-route.flag-gate.test.tsx | 8 +- ...ject-environments-route.permalink.test.tsx | 24 +- .../project-environments-route.seed.test.tsx | 24 +- ...vironments-route.tentative-drafts.test.tsx | 12 +- .../project/ProjectSecretsSection.tsx | 751 ++++++++++++++++++ .../src/hooks/useProjectEnvironments.ts | 51 ++ .../client/src/hooks/useProjectSecrets.ts | 164 ++++ .../routes/v1/__tests__/sdk-coverage.test.ts | 25 +- .../__tests__/mcpjam-built-in-tools.test.ts | 11 +- .../server/utils/built-in-tools/mcpjam.ts | 13 + .../server/utils/harness/run-harness-turn.ts | 53 +- .../server/utils/mcpjam-stream-handler.ts | 15 +- 28 files changed, 1708 insertions(+), 191 deletions(-) create mode 100644 mcpjam-inspector/client/src/components/project-environments/ProjectEnvironmentSecretsPicker.tsx create mode 100644 mcpjam-inspector/client/src/components/project-environments/__tests__/environment-secrets-picker.test.tsx create mode 100644 mcpjam-inspector/client/src/components/project/ProjectSecretsSection.tsx create mode 100644 mcpjam-inspector/client/src/hooks/useProjectSecrets.ts diff --git a/mcpjam-inspector/client/src/components/ProjectSettingsTab.tsx b/mcpjam-inspector/client/src/components/ProjectSettingsTab.tsx index 6927c3ee37..ab1b08a4bc 100644 --- a/mcpjam-inspector/client/src/components/ProjectSettingsTab.tsx +++ b/mcpjam-inspector/client/src/components/ProjectSettingsTab.tsx @@ -6,6 +6,7 @@ import { AccountApiKeySection } from "./setting/AccountApiKeySection"; import { ProjectMembersFacepile } from "./project/ProjectMembersFacepile"; import { ProjectShareButton } from "./project/ProjectShareButton"; import { ProjectIconPicker } from "./project/ProjectEmojiPicker"; +import { ProjectSecretsSection } from "./project/ProjectSecretsSection"; import { Button } from "@mcpjam/design-system/button"; import { Input } from "@mcpjam/design-system/input"; @@ -82,7 +83,9 @@ function XaaTestDefaultsSection({ try { await onUpdateProject(projectId, { xaaTestDefaults: bothSet - ? { defaultIdentity: { subject: trimmedSubject, email: trimmedEmail } } + ? { + defaultIdentity: { subject: trimmedSubject, email: trimmedEmail }, + } : // Explicit clear — the mutation removes the stored default. null, }); @@ -106,8 +109,8 @@ function XaaTestDefaultsSection({ Identity provider: MCPJam test IdP - Used when an authenticated project member connects without a - server override. + Used when an authenticated project member connects without a server + override. {!hasStored && ( @@ -189,10 +192,7 @@ interface ProjectSettingsTabProps { updates: Partial, ) => Promise; onDeleteProject: (projectId: string) => Promise; - onProjectShared: ( - sharedProjectId: string, - sourceProjectId?: string, - ) => void; + onProjectShared: (sharedProjectId: string, sourceProjectId?: string) => void; onNavigateAway: () => void; } @@ -309,6 +309,18 @@ export function ProjectSettingsTab({ /> + {/* Project secrets — Convex-backed projects only: the store is a + Convex table, and a local project has nowhere to keep one. Shown to + every member rather than admins alone, because PERSONAL secrets are + owner-managed; `canManageShared` is what gates the project-shared + option inside the form. */} + {isAuthenticated && convexProjectId && ( + + )} + {/* XAA test identity defaults — Convex-backed projects only (the local-project update path is a no-op for this field). */} {isAuthenticated && convexProjectId && ( @@ -335,8 +347,8 @@ export function ProjectSettingsTab({ {isDefault ? "Switch to another project first" : !canDeleteProject - ? "Only project admins can delete this project" - : "Permanently delete this project and all its data"} + ? "Only project admins can delete this project" + : "Permanently delete this project and all its data"} @@ -361,8 +373,7 @@ export function ProjectSettingsTab({ Cancel { - const success = - await onDeleteProject(activeProjectId); + const success = await onDeleteProject(activeProjectId); if (success) { onNavigateAway(); } diff --git a/mcpjam-inspector/client/src/components/__tests__/ProjectSettingsTab.test.tsx b/mcpjam-inspector/client/src/components/__tests__/ProjectSettingsTab.test.tsx index 8bdf4a99b5..2d1740662f 100644 --- a/mcpjam-inspector/client/src/components/__tests__/ProjectSettingsTab.test.tsx +++ b/mcpjam-inspector/client/src/components/__tests__/ProjectSettingsTab.test.tsx @@ -26,6 +26,14 @@ vi.mock("convex/react", () => ({ }), })); +// The Secrets section is a sibling, not what these tests are about. Stubbed at +// the component boundary rather than by widening the `convex/react` mock: it +// reads a live query and drives three actions, and teaching this file about all +// four would make it a test of the secrets surface by accident. +vi.mock("@/components/project/ProjectSecretsSection", () => ({ + ProjectSecretsSection: () =>
, +})); + vi.mock("@workos-inc/authkit-react", () => ({ useAuth: () => ({ user: { email: "admin@example.com" } }), })); @@ -105,9 +113,7 @@ describe("ProjectSettingsTab — XAA test identity defaults", () => { const user = userEvent.setup(); const { onUpdateProject } = renderTab(); - expect( - screen.getByText("XAA test identity defaults"), - ).toBeInTheDocument(); + expect(screen.getByText("XAA test identity defaults")).toBeInTheDocument(); // Fixed issuer — the MCPJam test IdP, never enterprise SSO. expect( screen.getByText(/Identity provider: MCPJam test IdP/), diff --git a/mcpjam-inspector/client/src/components/environment-composer/environment-stack.ts b/mcpjam-inspector/client/src/components/environment-composer/environment-stack.ts index b45b68531a..b5a301ec49 100644 --- a/mcpjam-inspector/client/src/components/environment-composer/environment-stack.ts +++ b/mcpjam-inspector/client/src/components/environment-composer/environment-stack.ts @@ -21,6 +21,7 @@ * slot in keep today's one-axis compose. */ import type { + ProjectEnvironmentSecretSelection, ProjectEnvironmentSkillSelection, ProjectEnvironmentView, } from "@/hooks/useProjectEnvironments"; @@ -446,6 +447,28 @@ export function composerTargetCount(state: EnvironmentComposerState): number { return state.environmentIds.length; } +/** + * Two secret selections are the same grant. + * + * ORDER-SENSITIVE, matching `sameSkillSelection` and the backend's own + * order-preserving normalization: the stored array is what the fingerprint + * hashes, so two orderings are two rows and a comparison that called them equal + * would mark a real edit clean. + * + * Absent and null are the same thing (no grant); there is no empty-array case + * to reconcile, because a picker that clears its last row emits `null`. + */ +export function sameSecretSelection( + a: ProjectEnvironmentSecretSelection | null | undefined, + b: ProjectEnvironmentSecretSelection | null | undefined, +): boolean { + const left = a ?? null; + const right = b ?? null; + if (left === null || right === null) return left === right; + if (left.secretIds.length !== right.secretIds.length) return false; + return left.secretIds.every((id, index) => id === right.secretIds[index]); +} + export function sameSkillSelection( a: ProjectEnvironmentSkillSelection | null | undefined, b: ProjectEnvironmentSkillSelection | null | undefined, diff --git a/mcpjam-inspector/client/src/components/project-environments/ProjectEnvironmentEditor.tsx b/mcpjam-inspector/client/src/components/project-environments/ProjectEnvironmentEditor.tsx index 234409f5e9..af85a4015b 100644 --- a/mcpjam-inspector/client/src/components/project-environments/ProjectEnvironmentEditor.tsx +++ b/mcpjam-inspector/client/src/components/project-environments/ProjectEnvironmentEditor.tsx @@ -15,15 +15,20 @@ import { isRevisionConflictError, useCreateProjectEnvironment, useUpdateProjectEnvironment, + type ProjectEnvironmentSecretSelection, type ProjectEnvironmentSkillSelection, type ProjectEnvironmentView, } from "@/hooks/useProjectEnvironments"; import { ProjectEnvironmentSkillsPicker } from "./ProjectEnvironmentSkillsPicker"; +import { ProjectEnvironmentSecretsPicker } from "./ProjectEnvironmentSecretsPicker"; // Re-exported from the composer's shared helper rather than kept as a second // copy: a dirty-check that missed version pins would silently discard a "hold // this skill at v1" edit, and two implementations means one of them eventually // does. -import { sameSkillSelection } from "@/components/environment-composer/environment-stack"; +import { + sameSecretSelection, + sameSkillSelection, +} from "@/components/environment-composer/environment-stack"; type EnvironmentDraft = { name: string; @@ -31,6 +36,13 @@ type EnvironmentDraft = { hostId: string | null; serverAttachmentId: string | null; skillSelection: ProjectEnvironmentSkillSelection | null; + /** + * The environment's CREDENTIAL GRANT. Deliberately NOT flag-gated like skills + * and sandbox images: there is no `secrets-enabled` flag, and a picker that + * could vanish would be a picker whose stored grant could not be revoked from + * the UI. + */ + secretSelection: ProjectEnvironmentSecretSelection | null; computerEnvironmentId: string | null; }; @@ -45,6 +57,7 @@ function draftFromEnvironment(env: ProjectEnvironmentView): EnvironmentDraft { hostId: env.hostId, serverAttachmentId: env.serverAttachmentId ?? null, skillSelection: env.skillSelection ?? null, + secretSelection: env.secretSelection ?? null, computerEnvironmentId: env.computerEnvironmentId ?? null, }; } @@ -111,6 +124,7 @@ export function ProjectEnvironmentEditor({ hostId: null, serverAttachmentId: null, skillSelection: null, + secretSelection: null, computerEnvironmentId: null, ...initialDraft, }, @@ -141,6 +155,10 @@ export function ProjectEnvironmentEditor({ draft.skillSelection, environment.skillSelection ?? null, )) || + !sameSecretSelection( + draft.secretSelection, + environment.secretSelection ?? null, + ) || (computersEnabled && draft.computerEnvironmentId !== (environment.computerEnvironmentId ?? null)) @@ -149,6 +167,7 @@ export function ProjectEnvironmentEditor({ draft.hostId !== null || draft.serverAttachmentId !== null || (skillsEnabled && draft.skillSelection !== null) || + draft.secretSelection !== null || (computersEnabled && draft.computerEnvironmentId !== null); // Reactivity observed someone else's edit while this draft diverged. @@ -182,6 +201,10 @@ export function ProjectEnvironmentEditor({ hostId: null, serverAttachmentId: null, skillSelection: null, + // Dropped along with the rest: a grant naming the previous + // project's secrets would be rejected at save, and holding it + // would let a form submit ids the new project cannot resolve. + secretSelection: null, computerEnvironmentId: null, }, ); @@ -219,6 +242,9 @@ export function ProjectEnvironmentEditor({ ...(skillsEnabled && draft.skillSelection ? { skillSelection: draft.skillSelection } : {}), + ...(draft.secretSelection + ? { secretSelection: draft.secretSelection } + : {}), ...(computersEnabled && draft.computerEnvironmentId ? { computerEnvironmentId: draft.computerEnvironmentId } : {}), @@ -261,6 +287,17 @@ export function ProjectEnvironmentEditor({ ) ? { skillSelection: draft.skillSelection } : {}), + // NOT flag-gated, unlike the two fields around it — the picker is + // always rendered, so the "hidden picker must omit the field" rule has + // nothing to protect against here. Still tri-state: unchanged omits, + // and clearing the last selection sends `null`, which REVOKES the + // grant. + ...(!sameSecretSelection( + draft.secretSelection, + environment.secretSelection ?? null, + ) + ? { secretSelection: draft.secretSelection } + : {}), ...(computersEnabled && draft.computerEnvironmentId !== (environment.computerEnvironmentId ?? null) @@ -400,6 +437,18 @@ export function ProjectEnvironmentEditor({
) : null} +
+ + + setDraft((d) => ({ ...d, secretSelection })) + } + disabled={readOnly} + /> +
+ {computersEnabled ? (
+ , ); } @@ -148,13 +148,13 @@ describe("EnvironmentCanvasPanel — preview → canvas wiring", () => { const { container } = renderPanel(); const joined = container.querySelector( - `.react-flow__node[data-id="server-card:s1"]` + `.react-flow__node[data-id="server-card:s1"]`, ) as HTMLElement | null; expect(joined).not.toBeNull(); expect(joined!.textContent).toContain("https://bench.example.com"); const nameOnly = container.querySelector( - `.react-flow__node[data-id="server-card:p1"]` + `.react-flow__node[data-id="server-card:p1"]`, ) as HTMLElement | null; expect(nameOnly).not.toBeNull(); expect(nameOnly!.textContent).toContain("plugin-server"); @@ -177,10 +177,10 @@ describe("EnvironmentCanvasPanel — preview → canvas wiring", () => { const { container } = renderPanel(); expect( - container.querySelector(`.react-flow__node[data-id="server-card:s1"]`) + container.querySelector(`.react-flow__node[data-id="server-card:s1"]`), ).not.toBeNull(); expect( - container.querySelector(`.react-flow__node[data-id="server-card:s9"]`) + container.querySelector(`.react-flow__node[data-id="server-card:s9"]`), ).toBeNull(); }); @@ -258,7 +258,7 @@ describe("EnvironmentCanvasPanel — non-canvas states", () => { const { container } = renderPanel(); expect( - screen.getByText("This environment couldn't be resolved.") + screen.getByText("This environment couldn't be resolved."), ).toBeInTheDocument(); fireEvent.click(screen.getByRole("button", { name: /retry/i })); expect(mockRefresh).toHaveBeenCalledTimes(1); @@ -286,7 +286,7 @@ describe("EnvironmentCanvasPanel — non-canvas states", () => { expect(screen.getByText(/archived/i)).toBeInTheDocument(); expect(container.querySelector(".react-flow")).toBeNull(); expect(mockPreviewArgs).toHaveBeenCalledWith( - expect.objectContaining({ environmentId: null }) + expect.objectContaining({ environmentId: null }), ); }); @@ -300,7 +300,9 @@ describe("EnvironmentCanvasPanel — non-canvas states", () => { const { container } = renderPanel(); expect( - screen.getByText(/client behind this environment is no longer available/i) + screen.getByText( + /client behind this environment is no longer available/i, + ), ).toBeInTheDocument(); expect(container.querySelector(".animate-spin")).toBeNull(); expect(container.querySelector(".react-flow")).toBeNull(); diff --git a/mcpjam-inspector/client/src/components/project-environments/__tests__/environment-picker.test.tsx b/mcpjam-inspector/client/src/components/project-environments/__tests__/environment-picker.test.tsx index 4d203d5ea8..f1b06a93d9 100644 --- a/mcpjam-inspector/client/src/components/project-environments/__tests__/environment-picker.test.tsx +++ b/mcpjam-inspector/client/src/components/project-environments/__tests__/environment-picker.test.tsx @@ -46,7 +46,12 @@ describe("EnvironmentPicker — controlled contract", () => { it("reports selection to the caller and persists nothing itself", () => { const onChange = vi.fn(); render( - + , ); fireEvent.click(screen.getByRole("button")); fireEvent.click(screen.getByLabelText("Staging")); @@ -64,7 +69,7 @@ describe("EnvironmentPicker — controlled contract", () => { value={["env_2"]} onChange={onChange} multi - /> + />, ); fireEvent.click(screen.getByRole("button")); fireEvent.click(screen.getByLabelText("Staging")); @@ -80,7 +85,7 @@ describe("EnvironmentPicker — controlled contract", () => { onChange={onChange} multi max={1} - /> + />, ); fireEvent.click(screen.getByRole("button")); fireEvent.click(screen.getByLabelText("Staging")); @@ -97,7 +102,7 @@ describe("EnvironmentPicker — single-select mode", () => { value={null} onChange={onChange} multi={false} - /> + />, ); fireEvent.click(screen.getByRole("button")); fireEvent.click(screen.getByLabelText("Staging")); @@ -112,7 +117,7 @@ describe("EnvironmentPicker — single-select mode", () => { value={"env_2"} onChange={onChange} multi={false} - /> + />, ); fireEvent.click(screen.getByRole("button")); fireEvent.click(screen.getByLabelText("Staging")); @@ -127,7 +132,7 @@ describe("EnvironmentPicker — single-select mode", () => { value={"env_1"} onChange={onChange} multi={false} - /> + />, ); fireEvent.click(screen.getByRole("button")); fireEvent.click(screen.getByLabelText("Staging")); @@ -141,7 +146,7 @@ describe("EnvironmentPicker — single-select mode", () => { value={"env_1"} onChange={vi.fn()} multi={false} - /> + />, ); fireEvent.click(screen.getByRole("button")); expect(screen.queryByText("1")).toBeNull(); @@ -158,7 +163,12 @@ describe("EnvironmentPicker — archived rows stay detach-only", () => { ]; const onChange = vi.fn(); render( - + , ); fireEvent.click(screen.getByRole("button")); expect(screen.queryByLabelText("Retired")).toBeNull(); @@ -177,7 +187,7 @@ describe("EnvironmentPicker — archived rows stay detach-only", () => { value={["env_arch"]} onChange={onChange} multi - /> + />, ); fireEvent.click(screen.getByRole("button")); fireEvent.click(screen.getByLabelText("Retired (archived)")); @@ -198,7 +208,7 @@ describe("EnvironmentPicker — ad-hoc rows", () => { it("never offers an ad-hoc row for selection", () => { mockEnvironments.value = [env("env_1", "Staging"), adhoc("env_adhoc")]; render( - + , ); fireEvent.click(screen.getByRole("button")); @@ -217,12 +227,12 @@ describe("EnvironmentPicker — ad-hoc rows", () => { onChange={vi.fn()} multi triggerTestId="picker" - /> + />, ); // "…" is reserved for an id NO row resolves. An ad-hoc row resolves — it // just has no name — so it must read as a real thing. expect(screen.getByTestId("picker")).toHaveTextContent( - "Automatic environment" + "Automatic environment", ); expect(screen.getByTestId("picker")).not.toHaveTextContent("…"); }); @@ -234,7 +244,7 @@ describe("EnvironmentPicker — ad-hoc rows", () => { env("env_1", "Staging"), ]; render( - + , ); fireEvent.click(screen.getByRole("button")); expect(screen.getByLabelText("Staging")).toBeInTheDocument(); @@ -253,7 +263,7 @@ describe("EnvironmentPicker — ad-hoc rows", () => { Save as environment } - /> + />, ); fireEvent.click(screen.getByRole("button")); expect(screen.getByTestId("picker-footer-action")).toBeInTheDocument(); @@ -285,7 +295,7 @@ describe("EnvironmentPicker — ad-hoc rows", () => { Save as environment } - /> + />, ); fireEvent.click(screen.getByTestId("picker")); @@ -298,8 +308,8 @@ describe("EnvironmentPicker — ad-hoc rows", () => { // has to dismiss the popover exactly like a pointer click does. await waitFor(() => expect( - screen.queryByTestId("picker-footer-action") - ).not.toBeInTheDocument() + screen.queryByTestId("picker-footer-action"), + ).not.toBeInTheDocument(), ); }); }); diff --git a/mcpjam-inspector/client/src/components/project-environments/__tests__/environment-secrets-picker.test.tsx b/mcpjam-inspector/client/src/components/project-environments/__tests__/environment-secrets-picker.test.tsx new file mode 100644 index 0000000000..4214b41657 --- /dev/null +++ b/mcpjam-inspector/client/src/components/project-environments/__tests__/environment-secrets-picker.test.tsx @@ -0,0 +1,172 @@ +/** + * The environment's credential grant, as the picker expresses it. + * + * Three things are pinned, and each is a way the feature would be wrong in a + * way nobody notices until a run fails: + * + * - CLEARING THE LAST SELECTION EMITS `null`, not `[]`. The backend rejects + * an empty array, so `[]` would fail the save; and `null` is what REVOKES + * the grant, which is the whole reason the field has to be clearable. + * - A PERSONAL secret is selectable and carries the "only your sessions" + * chip. Unlike skills, personal secrets are pinnable on purpose — that is + * the motivating workflow — and the chip is what stops a teammate's empty + * environment from being a mystery. + * - A selected id the query never returns gets a DETACH-ONLY row. Otherwise + * it is invisible, unremovable, and still shipped on every save. + */ +import { fireEvent, render, screen } from "@testing-library/react"; +import { beforeEach, describe, expect, it, vi } from "vitest"; + +const { mockSecrets } = vi.hoisted(() => ({ + mockSecrets: { value: undefined as unknown }, +})); + +vi.mock("@/hooks/useProjectSecrets", () => ({ + useProjectSecrets: () => mockSecrets.value, +})); + +import { ProjectEnvironmentSecretsPicker } from "../ProjectEnvironmentSecretsPicker"; + +const SHARED = { + secretId: "sec_shared", + projectId: "proj-1", + name: "STRIPE_API_KEY", + delivery: "brokered" as const, + brokerHosts: ["api.stripe.com"], + brokerHeader: "Authorization", + brokerTemplate: "Bearer {}", + sharing: "project" as const, + isOwner: false, + createdAt: 1, + updatedAt: 1, + createdByUserId: "u1", + updatedByUserId: "u1", +}; + +const PERSONAL = { + ...SHARED, + secretId: "sec_personal", + name: "MY_GH_TOKEN", + delivery: "materialized" as const, + brokerHosts: undefined, + brokerHeader: undefined, + brokerTemplate: undefined, + sharing: "user" as const, + ownerUserId: "u1", + isOwner: true, +}; + +beforeEach(() => { + vi.clearAllMocks(); + mockSecrets.value = [SHARED, PERSONAL]; +}); + +describe("ProjectEnvironmentSecretsPicker", () => { + it("emits an explicit selection when a secret is checked", () => { + const onChange = vi.fn(); + render( + , + ); + fireEvent.click(screen.getByLabelText("STRIPE_API_KEY")); + expect(onChange).toHaveBeenCalledWith({ + mode: "explicit", + secretIds: ["sec_shared"], + }); + }); + + it("emits NULL when the last selection is removed, never an empty array", () => { + // `[]` is rejected by the backend, and `null` is what revokes the grant. + const onChange = vi.fn(); + render( + , + ); + fireEvent.click(screen.getByLabelText("STRIPE_API_KEY")); + expect(onChange).toHaveBeenCalledWith(null); + }); + + it("offers a PERSONAL secret, labelled with who actually receives it", () => { + const onChange = vi.fn(); + render( + , + ); + // Selectable — this is the motivating workflow, not a mistake to prevent. + fireEvent.click(screen.getByLabelText("MY_GH_TOKEN")); + expect(onChange).toHaveBeenCalledWith({ + mode: "explicit", + secretIds: ["sec_personal"], + }); + // And labelled, so a teammate's empty run is not a mystery later. + expect(screen.getByText("only your sessions")).toBeInTheDocument(); + }); + + it("labels a materialized secret as reaching inside the box", () => { + render( + , + ); + expect(screen.getByText("in the box")).toBeInTheDocument(); + expect(screen.getByText("brokered")).toBeInTheDocument(); + }); + + it("renders a detach-only row for a selected id the query never returns", () => { + const onChange = vi.fn(); + render( + , + ); + const orphan = screen.getByLabelText(/Remove missing secret sec_gone/i); + expect(orphan).toBeInTheDocument(); + // Removable: unchecking commits the remaining ids. + fireEvent.click(orphan); + expect(onChange).toHaveBeenCalledWith({ + mode: "explicit", + secretIds: ["sec_shared"], + }); + }); + + it("shows no orphan rows while the query is still loading", () => { + // Otherwise every selection flashes as "no longer available" on mount. + mockSecrets.value = undefined; + render( + , + ); + expect(screen.queryByText(/No longer available/i)).not.toBeInTheDocument(); + }); + + it("says plainly that no selection means no secrets", () => { + // The fail-closed default is the surprising one, so it is stated rather + // than left as an empty list to interpret. + render( + , + ); + expect( + screen.getByText(/Runs from this environment receive none/i), + ).toBeInTheDocument(); + }); +}); diff --git a/mcpjam-inspector/client/src/components/project-environments/__tests__/name-environment-dialog.test.tsx b/mcpjam-inspector/client/src/components/project-environments/__tests__/name-environment-dialog.test.tsx index cd56d9afe6..de941ed5ee 100644 --- a/mcpjam-inspector/client/src/components/project-environments/__tests__/name-environment-dialog.test.tsx +++ b/mcpjam-inspector/client/src/components/project-environments/__tests__/name-environment-dialog.test.tsx @@ -86,9 +86,7 @@ describe("NameEnvironmentDialog", () => { open onOpenChange={vi.fn()} projectId="p1" - environment={ - { ...(adhocEnvironment as object), revision: 7 } as never - } + environment={{ ...(adhocEnvironment as object), revision: 7 } as never} />, ); @@ -105,10 +103,9 @@ describe("NameEnvironmentDialog", () => { renderDialog({}); typeName("Checkout flow"); - fireEvent.change( - screen.getByTestId("name-environment-description-input"), - { target: { value: "Staging servers for the checkout revamp" } }, - ); + fireEvent.change(screen.getByTestId("name-environment-description-input"), { + target: { value: "Staging servers for the checkout revamp" }, + }); fireEvent.click(screen.getByTestId("name-environment-submit")); await waitFor(() => diff --git a/mcpjam-inspector/client/src/components/project-environments/__tests__/orphan-selections.test.tsx b/mcpjam-inspector/client/src/components/project-environments/__tests__/orphan-selections.test.tsx index f23333b493..dec136113a 100644 --- a/mcpjam-inspector/client/src/components/project-environments/__tests__/orphan-selections.test.tsx +++ b/mcpjam-inspector/client/src/components/project-environments/__tests__/orphan-selections.test.tsx @@ -53,7 +53,7 @@ describe("SuiteProjectEnvironmentsPicker — unresolvable attached ids", () => { suiteId="suite-1" projectId="proj-1" environmentIds={["env-live", "env-gone"]} - /> + />, ); // The popover trigger is the only button rendered before it opens; its @@ -61,7 +61,7 @@ describe("SuiteProjectEnvironmentsPicker — unresolvable attached ids", () => { fireEvent.click(screen.getAllByRole("button")[0]!); const orphanRow = await screen.findByLabelText( - /Unavailable environment env-gone \(detach\)/i + /Unavailable environment env-gone \(detach\)/i, ); expect(orphanRow).toBeInTheDocument(); @@ -82,14 +82,14 @@ describe("SuiteProjectEnvironmentsPicker — unresolvable attached ids", () => { suiteId="suite-1" projectId="proj-1" environmentIds={["env-a", "env-b"]} - /> + />, ); // The popover trigger is the only button rendered before it opens; its // label is the joined environment names, so match it positionally. fireEvent.click(screen.getAllByRole("button")[0]!); // A loading list must not flash every attached id as an orphan. expect( - screen.queryByLabelText(/Unavailable environment/i) + screen.queryByLabelText(/Unavailable environment/i), ).not.toBeInTheDocument(); }); }); @@ -106,11 +106,11 @@ describe("ProjectEnvironmentSkillsPicker — unresolvable pinned ids", () => { projectId="proj-1" value={{ mode: "explicit", skillIds: ["sk-live", "sk-gone"] }} onChange={onChange} - /> + />, ); const orphanRow = await screen.findByLabelText( - /Unavailable skill sk-gone \(remove\)/i + /Unavailable skill sk-gone \(remove\)/i, ); fireEvent.click(orphanRow); expect(onChange).toHaveBeenCalledWith({ @@ -130,14 +130,14 @@ describe("ProjectEnvironmentSkillsPicker — unresolvable pinned ids", () => { projectId="proj-1" value={{ mode: "explicit", skillIds: ["sk-gone"] }} onChange={onChange} - /> + />, ); const orphanRow = await screen.findByLabelText( - /Unavailable skill sk-gone \(remove\)/i + /Unavailable skill sk-gone \(remove\)/i, ); expect( - screen.queryByText(/No shared skills in this project yet/i) + screen.queryByText(/No shared skills in this project yet/i), ).not.toBeInTheDocument(); // Clearing the last pin emits null, never an empty array. diff --git a/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environment-editor.initial-draft.test.tsx b/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environment-editor.initial-draft.test.tsx index 0235cf161e..8f3c2b18d0 100644 --- a/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environment-editor.initial-draft.test.tsx +++ b/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environment-editor.initial-draft.test.tsx @@ -38,6 +38,12 @@ vi.mock("@/components/hosts/ServerGroupPicker", () => ({ vi.mock("../ProjectEnvironmentSkillsPicker", () => ({ ProjectEnvironmentSkillsPicker: () =>
, })); +// The secrets picker is a sibling section, not what these tests are about. It +// is stubbed rather than mocked at the hook level because it reads a live +// Convex query, and a real one here would need the whole provider. +vi.mock("../ProjectEnvironmentSecretsPicker", () => ({ + ProjectEnvironmentSecretsPicker: () =>
, +})); vi.mock("@/components/computer/EnvironmentBuildBadge", () => ({ EnvironmentBuildBadge: () => null, })); @@ -71,7 +77,7 @@ describe("ProjectEnvironmentEditor — initialDraft", () => { environment={null} canManage initialDraft={{ name: "Claude Code", hostId: "host_1" }} - /> + />, ); expect(screen.getByLabelText("Name")).toHaveValue("Claude Code"); expect(screen.getByTestId("host-picker")).toHaveTextContent("host_1"); @@ -100,7 +106,7 @@ describe("ProjectEnvironmentEditor — initialDraft", () => { }} canManage initialDraft={{ name: "Seeded", hostId: "host_seed" }} - /> + />, ); expect(screen.getByLabelText("Name")).toHaveValue("Existing"); expect(screen.getByTestId("host-picker")).toHaveTextContent("host_row"); diff --git a/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environment-editor.optional-description.test.tsx b/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environment-editor.optional-description.test.tsx index 1adbbf3c7e..dff4334188 100644 --- a/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environment-editor.optional-description.test.tsx +++ b/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environment-editor.optional-description.test.tsx @@ -20,7 +20,7 @@ const { mockCreateEnvironment, mockUpdateEnvironment, mockToast } = vi.hoisted( mockCreateEnvironment: vi.fn(), mockUpdateEnvironment: vi.fn(), mockToast: { error: vi.fn(), success: vi.fn() }, - }) + }), ); vi.mock("@/hooks/useProjectEnvironments", () => ({ @@ -48,6 +48,12 @@ vi.mock("@/components/hosts/ServerGroupPicker", () => ({ vi.mock("../ProjectEnvironmentSkillsPicker", () => ({ ProjectEnvironmentSkillsPicker: () =>
, })); +// The secrets picker is a sibling section, not what these tests are about. It +// is stubbed rather than mocked at the hook level because it reads a live +// Convex query, and a real one here would need the whole provider. +vi.mock("../ProjectEnvironmentSecretsPicker", () => ({ + ProjectEnvironmentSecretsPicker: () =>
, +})); vi.mock("@/components/computer/EnvironmentBuildBadge", () => ({ EnvironmentBuildBadge: () => null, })); @@ -90,7 +96,7 @@ describe("ProjectEnvironmentEditor — optional description", () => { environment={null} canManage initialDraft={{ name: "test environment", hostId: "host_1" }} - /> + />, ); const description = screen.getByLabelText("Description"); @@ -117,7 +123,7 @@ describe("ProjectEnvironmentEditor — optional description", () => { projectId="proj_1" environment={rowWithoutDescription} canManage - /> + />, ); // Grey at rest because the draft matches the row, NOT because the diff --git a/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environment-editor.sandbox-image.test.tsx b/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environment-editor.sandbox-image.test.tsx index c5cac548ba..008b488392 100644 --- a/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environment-editor.sandbox-image.test.tsx +++ b/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environment-editor.sandbox-image.test.tsx @@ -52,11 +52,7 @@ vi.mock("@/hooks/useSandboxImages", () => ({ })); // Sibling sections are not under test — render inert placeholders. vi.mock("@/components/hosts/HostPicker", () => ({ - HostPicker: ({ - onChange, - }: { - onChange: (hostId: string | null) => void; - }) => ( + HostPicker: ({ onChange }: { onChange: (hostId: string | null) => void }) => ( @@ -68,6 +64,12 @@ vi.mock("@/components/hosts/ServerGroupPicker", () => ({ vi.mock("../ProjectEnvironmentSkillsPicker", () => ({ ProjectEnvironmentSkillsPicker: () =>
, })); +// The secrets picker is a sibling section, not what these tests are about. It +// is stubbed rather than mocked at the hook level because it reads a live +// Convex query, and a real one here would need the whole provider. +vi.mock("../ProjectEnvironmentSecretsPicker", () => ({ + ProjectEnvironmentSecretsPicker: () =>
, +})); vi.mock("@/components/computer/EnvironmentBuildBadge", () => ({ EnvironmentBuildBadge: ({ build }: { build: unknown }) => ( {build ? "has-build" : "no-build"} @@ -110,7 +112,7 @@ const IMAGE_DRAFT = { }; function envRow( - overrides: Partial = {} + overrides: Partial = {}, ): ProjectEnvironmentView { return { environmentId: "env-1", @@ -138,7 +140,7 @@ function renderEditor(environment: ProjectEnvironmentView | null) { projectId="proj-1" environment={environment} canManage - /> + />, ); } @@ -169,7 +171,7 @@ describe("flag gating + the omission contract", () => { mockComputersEnabled.value = false; renderEditor(envRow()); expect( - screen.queryByTestId("project-environment-sandbox-image") + screen.queryByTestId("project-environment-sandbox-image"), ).not.toBeInTheDocument(); }); @@ -202,14 +204,16 @@ describe("flag gating + the omission contract", () => { await waitFor(() => expect(mockUpdateEnvironment).toHaveBeenCalled()); expect( "computerEnvironmentId" in - (mockUpdateEnvironment.mock.calls[0]![0] as Record) + (mockUpdateEnvironment.mock.calls[0]![0] as Record), ).toBe(false); }); }); describe("flag flips false AFTER an edit (review regression)", () => { it("omits the pin when the flag turns off between editing and saving", async () => { - const { rerender } = renderEditor(envRow({ computerEnvironmentId: "img-ready" })); + const { rerender } = renderEditor( + envRow({ computerEnvironmentId: "img-ready" }), + ); // Admin clears the pin while the picker is visible… await pickImage("None (default image)"); // …then PostHog re-evaluates the flag to false and the picker unmounts. @@ -219,10 +223,10 @@ describe("flag flips false AFTER an edit (review regression)", () => { projectId="proj-1" environment={envRow({ computerEnvironmentId: "img-ready" })} canManage - /> + />, ); expect( - screen.queryByTestId("project-environment-sandbox-image") + screen.queryByTestId("project-environment-sandbox-image"), ).not.toBeInTheDocument(); // The diverged draft value must NOT ship: a hidden picker always omits. @@ -253,13 +257,13 @@ describe("flag flips false AFTER an edit (review regression)", () => { projectId="proj-1" environment={null} canManage - /> + />, ); fireEvent.click(screen.getByRole("button", { name: "Create" })); await waitFor(() => expect(mockCreateEnvironment).toHaveBeenCalled()); expect( "computerEnvironmentId" in - (mockCreateEnvironment.mock.calls[0]![0] as Record) + (mockCreateEnvironment.mock.calls[0]![0] as Record), ).toBe(false); }); }); @@ -273,7 +277,9 @@ describe("loading state (review regression)", () => { // would make a pinned environment look unpinned mid-load. expect(trigger()).toHaveTextContent("Loading image…"); const options = await openOptions(); - expect(options.some((o) => o.label.startsWith("Unknown image"))).toBe(false); + expect(options.some((o) => o.label.startsWith("Unknown image"))).toBe( + false, + ); expect(options).toContainEqual({ label: "Loading image…", disabled: true, @@ -300,7 +306,7 @@ describe("wire shapes", () => { await waitFor(() => expect(mockUpdateEnvironment).toHaveBeenCalled()); expect( (mockUpdateEnvironment.mock.calls[0]![0] as Record) - .computerEnvironmentId + .computerEnvironmentId, ).toBeNull(); }); @@ -341,7 +347,7 @@ describe("option list states", () => { renderEditor(envRow({ computerEnvironmentId: "img-gone" })); expect(trigger()).toHaveTextContent("Unknown image (img-gone)"); const orphan = (await openOptions()).find((o) => - o.label.startsWith("Unknown image") + o.label.startsWith("Unknown image"), ); expect(orphan).toEqual({ label: "Unknown image (img-gone)", diff --git a/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environment-editor.skills-gate.test.tsx b/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environment-editor.skills-gate.test.tsx index 84c5b7d1f0..2746019796 100644 --- a/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environment-editor.skills-gate.test.tsx +++ b/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environment-editor.skills-gate.test.tsx @@ -36,11 +36,7 @@ vi.mock("@/hooks/useSandboxImages", () => ({ // Sibling sections are not under test — render inert placeholders. The skills // picker mock exposes attach/clear buttons so tests can drive `onChange`. vi.mock("@/components/hosts/HostPicker", () => ({ - HostPicker: ({ - onChange, - }: { - onChange: (hostId: string | null) => void; - }) => ( + HostPicker: ({ onChange }: { onChange: (hostId: string | null) => void }) => ( @@ -53,9 +49,7 @@ vi.mock("../ProjectEnvironmentSkillsPicker", () => ({ ProjectEnvironmentSkillsPicker: ({ onChange, }: { - onChange: ( - next: { mode: "explicit"; skillIds: string[] } | null - ) => void; + onChange: (next: { mode: "explicit"; skillIds: string[] } | null) => void; }) => (
), })); +// The secrets picker is a sibling section, not what these tests are about. It +// is stubbed rather than mocked at the hook level because it reads a live +// Convex query, and a real one here would need the whole provider. +vi.mock("../ProjectEnvironmentSecretsPicker", () => ({ + ProjectEnvironmentSecretsPicker: () =>
, +})); vi.mock("@/components/computer/EnvironmentBuildBadge", () => ({ EnvironmentBuildBadge: () => null, })); @@ -86,7 +86,7 @@ import type { ProjectEnvironmentView } from "@/hooks/useProjectEnvironments"; const PINNED = { mode: "explicit" as const, skillIds: ["sk-1", "sk-2"] }; function envRow( - overrides: Partial = {} + overrides: Partial = {}, ): ProjectEnvironmentView { return { environmentId: "env-1", @@ -113,7 +113,7 @@ function renderEditor(environment: ProjectEnvironmentView | null) { projectId="proj-1" environment={environment} canManage - /> + />, ); } @@ -154,7 +154,7 @@ describe("flag gating + the omission contract", () => { await waitFor(() => expect(mockUpdateEnvironment).toHaveBeenCalled()); expect( "skillSelection" in - (mockUpdateEnvironment.mock.calls[0]![0] as Record) + (mockUpdateEnvironment.mock.calls[0]![0] as Record), ).toBe(false); }); }); @@ -171,7 +171,7 @@ describe("flag flips false AFTER an edit", () => { projectId="proj-1" environment={envRow({ skillSelection: PINNED })} canManage - /> + />, ); expect(screen.queryByTestId("skills-picker")).not.toBeInTheDocument(); @@ -203,13 +203,13 @@ describe("flag flips false AFTER an edit", () => { projectId="proj-1" environment={null} canManage - /> + />, ); fireEvent.click(screen.getByRole("button", { name: "Create" })); await waitFor(() => expect(mockCreateEnvironment).toHaveBeenCalled()); expect( "skillSelection" in - (mockCreateEnvironment.mock.calls[0]![0] as Record) + (mockCreateEnvironment.mock.calls[0]![0] as Record), ).toBe(false); }); }); @@ -233,7 +233,7 @@ describe("wire shapes (flag on)", () => { await waitFor(() => expect(mockUpdateEnvironment).toHaveBeenCalled()); expect( (mockUpdateEnvironment.mock.calls[0]![0] as Record) - .skillSelection + .skillSelection, ).toBeNull(); }); diff --git a/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environment-mutations.project-scoping.test.tsx b/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environment-mutations.project-scoping.test.tsx index 12a86cc976..ac42a767fa 100644 --- a/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environment-mutations.project-scoping.test.tsx +++ b/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environment-mutations.project-scoping.test.tsx @@ -49,6 +49,11 @@ vi.mock("@/hooks/useComputersEnabled", () => ({ useComputersEnabled: () => false, })); vi.mock("@/hooks/useSkillsEnabled", () => ({ useSkillsEnabled: () => false })); +// The secrets picker is a sibling section, not what this test is about, and it +// reads a live Convex query — a real one here would need the whole provider. +vi.mock("../ProjectEnvironmentSecretsPicker", () => ({ + ProjectEnvironmentSecretsPicker: () =>
, +})); vi.mock("@/hooks/useSandboxImages", () => ({ useSandboxImages: () => undefined, })); @@ -85,7 +90,7 @@ import type { ProjectEnvironmentView } from "@/hooks/useProjectEnvironments"; const PROJECT_ID = "proj-1"; function envRow( - overrides: Partial = {} + overrides: Partial = {}, ): ProjectEnvironmentView { return { environmentId: "env-1", @@ -116,7 +121,7 @@ function renderDetail(environment: ProjectEnvironmentView) { } /> - + , ); fireEvent.click(screen.getByText("Prod-like")); } diff --git a/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environments-route.flag-gate.test.tsx b/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environments-route.flag-gate.test.tsx index e9b9d36a20..e17e174292 100644 --- a/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environments-route.flag-gate.test.tsx +++ b/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environments-route.flag-gate.test.tsx @@ -57,7 +57,7 @@ function renderAtEnvironments(projectId = "proj-1") { /> Servers Screen
} /> - + , ); } @@ -85,7 +85,7 @@ describe("ProjectEnvironmentsRoute flag gate", () => { mockFlagValue.value = true; renderAtEnvironments(); expect( - screen.getByRole("heading", { name: "Environments" }) + screen.getByRole("heading", { name: "Environments" }), ).toBeInTheDocument(); expect(screen.queryByText("Servers Screen")).not.toBeInTheDocument(); }); @@ -126,12 +126,12 @@ describe("ProjectEnvironmentsRoute project switch", () => { /> Servers Screen
} /> - + , ); expect(screen.queryByText("Environment Editor")).not.toBeInTheDocument(); expect( - screen.getByRole("heading", { name: "Environments" }) + screen.getByRole("heading", { name: "Environments" }), ).toBeInTheDocument(); }); }); diff --git a/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environments-route.permalink.test.tsx b/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environments-route.permalink.test.tsx index 1e709174cf..dfe716107f 100644 --- a/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environments-route.permalink.test.tsx +++ b/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environments-route.permalink.test.tsx @@ -77,7 +77,7 @@ describe("ProjectEnvironmentsRoute — permalink targets", () => { projectId="proj_1" canManage routeEnvironmentId="env_1" - /> + />, ); await waitFor(() => expect(screen.getByTestId("editor")).toBeVisible()); }); @@ -93,7 +93,7 @@ describe("ProjectEnvironmentsRoute — permalink targets", () => { projectId="proj_1" canManage routeEnvironmentId="env_1" - /> + />, ); await waitFor(() => expect(screen.getByTestId("editor")).toBeVisible()); @@ -104,7 +104,7 @@ describe("ProjectEnvironmentsRoute — permalink targets", () => { projectId="proj_2" canManage routeEnvironmentId="env_1" - /> + />, ); await waitFor(() => expect(screen.getByTestId("editor")).toBeVisible()); }); @@ -120,12 +120,12 @@ describe("ProjectEnvironmentsRoute — permalink targets", () => { projectId="proj_1" canManage routeEnvironmentId="env_1" - /> + />, ); await waitFor(() => expect( - screen.getByTestId("environment-permalink-unavailable") - ).toBeVisible() + screen.getByTestId("environment-permalink-unavailable"), + ).toBeVisible(), ); expect(screen.queryByTestId("editor")).not.toBeInTheDocument(); expect(screen.queryByText("Other")).not.toBeInTheDocument(); @@ -143,7 +143,7 @@ describe("ProjectEnvironmentsRoute — permalink targets", () => { projectId="proj_1" canManage routeEnvironmentId="env_1" - /> + />, ); await waitFor(() => expect(screen.getByTestId("editor")).toBeVisible()); @@ -154,14 +154,14 @@ describe("ProjectEnvironmentsRoute — permalink targets", () => { projectId="proj_1" canManage routeEnvironmentId={empty} - /> + />, ); await waitFor(() => - expect(screen.queryByTestId("editor")).not.toBeInTheDocument() + expect(screen.queryByTestId("editor")).not.toBeInTheDocument(), ); // The list, not the unavailable notice: no id was asked for. expect( - screen.queryByTestId("environment-permalink-unavailable") + screen.queryByTestId("environment-permalink-unavailable"), ).not.toBeInTheDocument(); expect(screen.getByText("Staging")).toBeInTheDocument(); } @@ -177,10 +177,10 @@ describe("ProjectEnvironmentsRoute — permalink targets", () => { projectId="proj_1" canManage routeEnvironmentId="env_1" - /> + />, ); expect( - screen.queryByTestId("environment-permalink-unavailable") + screen.queryByTestId("environment-permalink-unavailable"), ).not.toBeInTheDocument(); }); }); diff --git a/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environments-route.seed.test.tsx b/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environments-route.seed.test.tsx index 23a21b3b5d..4916ac6ba1 100644 --- a/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environments-route.seed.test.tsx +++ b/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environments-route.seed.test.tsx @@ -76,7 +76,7 @@ describe("ProjectEnvironmentsRoute — seed consumption", () => { skillSelection: null, }); render( - + , ); await waitFor(() => expect(screen.getByTestId("editor")).toBeVisible()); @@ -102,17 +102,17 @@ describe("ProjectEnvironmentsRoute — seed consumption", () => { }); mockFlagValue.value = undefined; const { rerender, container } = render( - + , ); // Hydrating: route renders nothing, seed untouched. expect(container).toBeEmptyDOMElement(); expect(sessionStorage.getItem("mcp-environment-draft-seed")).toContain( - "host_1" + "host_1", ); mockFlagValue.value = true; rerender( - + , ); await waitFor(() => expect(screen.getByTestId("editor")).toBeVisible()); expect(screen.getByText("New environment")).toBeInTheDocument(); @@ -133,7 +133,7 @@ describe("ProjectEnvironmentsRoute — seed consumption", () => { }); const { rerender } = render( - + , ); await waitFor(() => expect(screen.getByTestId("editor")).toBeVisible()); expect( @@ -141,13 +141,13 @@ describe("ProjectEnvironmentsRoute — seed consumption", () => { mockEditorProps.mock.calls.at(-1)![0] as { capturedInitialDraft?: { hostId: string }; } - ).capturedInitialDraft?.hostId + ).capturedInitialDraft?.hostId, ).toBe("host_a"); // Straight from one seeded create form to another: the remount key must // change, or React reuses the instance and B's already-deleted seed is lost. rerender( - + , ); await waitFor(() => { const props = mockEditorProps.mock.calls.at(-1)![0] as { @@ -171,7 +171,7 @@ describe("ProjectEnvironmentsRoute — seed consumption", () => { isAuthenticated projectId=" proj_1 " canManage - /> + />, ); await waitFor(() => expect(screen.getByTestId("editor")).toBeVisible()); expect( @@ -179,13 +179,13 @@ describe("ProjectEnvironmentsRoute — seed consumption", () => { mockEditorProps.mock.calls.at(-1)![0] as { capturedInitialDraft?: { hostId: string }; } - ).capturedInitialDraft?.hostId + ).capturedInitialDraft?.hostId, ).toBe("host_1"); }); it("no seed ⇒ lands on the list, not create mode", () => { render( - + , ); // The list ALSO renders a "New environment" button — the editor testid is // the unambiguous create-mode signal. @@ -199,12 +199,12 @@ describe("ProjectEnvironmentsRoute — seed consumption", () => { skillSelection: null, }); render( - + , ); expect(screen.queryByTestId("editor")).not.toBeInTheDocument(); // The other project's seed stays for its own route visit. expect(sessionStorage.getItem("mcp-environment-draft-seed")).toContain( - "proj_other" + "proj_other", ); }); }); diff --git a/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environments-route.tentative-drafts.test.tsx b/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environments-route.tentative-drafts.test.tsx index 42c81210a4..b7af5eae7e 100644 --- a/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environments-route.tentative-drafts.test.tsx +++ b/mcpjam-inspector/client/src/components/project-environments/__tests__/project-environments-route.tentative-drafts.test.tsx @@ -85,13 +85,13 @@ describe("ProjectEnvironmentsRoute — tentative castle drafts", () => { }); render( - + , ); expect(screen.getByTestId("environment-tentative-drafts")).toBeVisible(); const draftId = listTentativeCastles("proj_1")[0]!.id; fireEvent.click( - screen.getByTestId(`environment-tentative-draft-${draftId}`) + screen.getByTestId(`environment-tentative-draft-${draftId}`), ); await waitFor(() => expect(screen.getByTestId("editor")).toBeVisible()); @@ -121,16 +121,14 @@ describe("ProjectEnvironmentsRoute — tentative castle drafts", () => { })!; render( - + , ); fireEvent.click( - screen.getByTestId(`environment-tentative-draft-${saved.id}`) + screen.getByTestId(`environment-tentative-draft-${saved.id}`), ); await waitFor(() => expect(screen.getByTestId("editor")).toBeVisible()); fireEvent.click(screen.getByTestId("fake-save")); - await waitFor(() => - expect(listTentativeCastles("proj_1")).toHaveLength(0) - ); + await waitFor(() => expect(listTentativeCastles("proj_1")).toHaveLength(0)); }); }); diff --git a/mcpjam-inspector/client/src/components/project/ProjectSecretsSection.tsx b/mcpjam-inspector/client/src/components/project/ProjectSecretsSection.tsx new file mode 100644 index 0000000000..74c3d88a50 --- /dev/null +++ b/mcpjam-inspector/client/src/components/project/ProjectSecretsSection.tsx @@ -0,0 +1,751 @@ +import { useMemo, useState } from "react"; +import { + AlertTriangle, + KeyRound, + Loader2, + Plus, + RefreshCw, + ShieldCheck, + Trash2, +} from "lucide-react"; +import { Button } from "@mcpjam/design-system/button"; +import { Badge } from "@mcpjam/design-system/badge"; +import { Input } from "@mcpjam/design-system/input"; +import { Label } from "@mcpjam/design-system/label"; +import { Textarea } from "@mcpjam/design-system/textarea"; +import { RadioGroup, RadioGroupItem } from "@mcpjam/design-system/radio-group"; +import { + Dialog, + DialogContent, + DialogDescription, + DialogFooter, + DialogHeader, + DialogTitle, +} from "@mcpjam/design-system/dialog"; +import { + AlertDialog, + AlertDialogAction, + AlertDialogCancel, + AlertDialogContent, + AlertDialogDescription, + AlertDialogFooter, + AlertDialogHeader, + AlertDialogTitle, +} from "@mcpjam/design-system/alert-dialog"; +import { + Tooltip, + TooltipContent, + TooltipTrigger, +} from "@mcpjam/design-system/tooltip"; +import { + useCreateProjectSecret, + useDeleteProjectSecret, + useProjectSecrets, + useUpdateProjectSecret, + type ProjectSecretView, + type SecretDelivery, + type SecretSharing, +} from "@/hooks/useProjectSecrets"; +import { useProjectEnvironments } from "@/hooks/useProjectEnvironments"; +import { environmentLabel } from "@/lib/environment-label"; + +/** + * Project secrets — the credentials a real workflow needs, managed in one place. + * + * ## What this screen can and cannot show + * + * It never shows a value, and there is no state in this component that holds + * one past a submit. The create and rotate dialogs clear their field on success + * and say plainly that the value cannot be read back, because the alternative — + * a masked field that looks like it is holding something — invites people to + * come back looking for it. + * + * ## The delivery choice is the point of the form + * + * Brokered and materialized are not "secure" and "less secure"; they answer + * different questions, and picking wrong produces a workflow that silently does + * not work. A brokered secret is invisible to `echo $NAME` and unreadable by a + * CLI; a materialized one is printed by `env`. The radio group says both things + * where the choice is made rather than in documentation nobody opens. + */ +export function ProjectSecretsSection({ + projectId, + canManageShared, +}: { + projectId: string; + /** + * Whether this member may create or edit PROJECT-SHARED secrets (project + * admin). Personal secrets are owner-managed and always available — which is + * why a non-admin sees the section rather than an empty screen. + */ + canManageShared: boolean; +}) { + const secrets = useProjectSecrets(projectId); + const environments = useProjectEnvironments(projectId); + const deleteSecret = useDeleteProjectSecret(); + + const [createOpen, setCreateOpen] = useState(false); + const [rotating, setRotating] = useState(null); + const [deleting, setDeleting] = useState(null); + const [deleteError, setDeleteError] = useState(null); + const [busy, setBusy] = useState(false); + + /** + * Which environments would stop delivering this secret. Shown in the delete + * confirm as INFORMATION, not as a blocker: revocation is never gated on + * cleanup, and a user revoking a leaked credential must not be told to go + * edit five environments first. + */ + const environmentsUsing = useMemo(() => { + if (!deleting || !environments) return []; + return environments.filter((environment) => + environment.secretSelection?.secretIds.includes(deleting.secretId), + ); + }, [deleting, environments]); + + const confirmDelete = async () => { + if (!deleting) return; + setBusy(true); + setDeleteError(null); + try { + await deleteSecret({ projectId, secretId: deleting.secretId }); + setDeleting(null); + } catch (error) { + setDeleteError( + error instanceof Error ? error.message : "Failed to delete the secret.", + ); + } finally { + setBusy(false); + } + }; + + return ( +
+
+

Secrets

+ +
+

+ Credentials a workflow needs — a stripe run,{" "} + gh, psql. Select them on an environment to + grant them to the runs it launches. Values are write-only: once saved, + nobody can read one back, here or through the API. +

+ +
+ {secrets === undefined ? ( +
+ Loading secrets… +
+ ) : secrets.length === 0 ? ( +

+ No secrets yet. Add one, then select it on the environment whose + runs should receive it. +

+ ) : ( +
    + {secrets.map((secret) => ( +
  • + +
    + + {secret.name} + + {secret.description ? ( + + {secret.description} + + ) : null} +
    + + + {secret.sharing === "project" ? "Project" : "Personal"} + + + {secret.lastDeliveredAt + ? `Delivered ${new Date( + secret.lastDeliveredAt, + ).toLocaleDateString()}` + : "Never delivered"} + +
    + + +
    +
    • + ))} +
+ )} +
+ + + + { + if (!open) setRotating(null); + }} + /> + + { + if (!open) setDeleting(null); + }} + > + + + + Revoke {deleting?.name ?? "this secret"}? + + +
+

+ The stored value is deleted permanently. Runs already in + flight keep the credential they were handed; every new run + gets nothing. +

+ {environmentsUsing.length > 0 ? ( +

+ {environmentsUsing.length === 1 + ? "One environment selects it and will stop delivering it:" + : `${environmentsUsing.length} environments select it and will stop delivering it:`}{" "} + + {environmentsUsing + .map((environment) => environmentLabel(environment)) + .join(", ")} + + . +

+ ) : null} + {deleteError ? ( +

{deleteError}

+ ) : null} +
+ + + + Cancel + { + // Kept open until the action settles so a failure is visible + // here rather than vanishing with the dialog. + event.preventDefault(); + void confirmDelete(); + }} + > + {busy ? "Revoking…" : "Revoke"} + + + + +
+ ); +} + +/** A shared secret needs admin; a personal one is its owner's. */ +function canEdit(secret: ProjectSecretView, canManageShared: boolean): boolean { + return secret.sharing === "project" ? canManageShared : secret.isOwner; +} + +/** + * The delivery badge, with the sentence that stops the wrong choice from being + * discovered inside a sandbox. + */ +function DeliveryBadge({ secret }: { secret: ProjectSecretView }) { + if (secret.delivery === "materialized") { + return ( + + + + materialized + + + +

+ The value is a real environment variable inside the sandbox, which + is what makes a CLI able to read it — and what makes it visible to + anything else in the box, including env. Extractable by + design. +

+ + + ); + } + return ( + + + + brokered + + + +

+ Injected as {secret.brokerHeader ?? "a header"} on{" "} + {(secret.brokerHosts ?? []).join(", ") || "its bound hosts"} by the + egress proxy, outside the sandbox. The box never holds the value — but + anything in the box can still CALL those hosts while the run is live. +

+ + + ); +} + +/** Shared broker binding fields, used by both dialogs. */ +function BrokerFields({ + hosts, + header, + template, + onHosts, + onHeader, + onTemplate, + disabled, +}: { + hosts: string; + header: string; + template: string; + onHosts: (next: string) => void; + onHeader: (next: string) => void; + onTemplate: (next: string) => void; + disabled?: boolean; +}) { + return ( +
+
+ + onHosts(event.target.value)} + /> +

+ Comma-separated, exact hostnames. No scheme, port, or wildcard — the + proxy matches a host, and a URL installs a rule that never fires. + HTTPS only. +

+
+
+ + onHeader(event.target.value)} + /> +
+
+ + onTemplate(event.target.value)} + /> +

+ {template.includes("{}") ? ( + <> + Sent as{" "} + + {header || "Header"}: {template.replace("{}", "•••••")} + + + ) : ( + <> + Must contain {"{}"}, which is replaced with the + secret. Without it the header never carries the credential. + + )} +

+
+
+ ); +} + +/** Split the comma-separated host field, dropping blanks. */ +function parseHosts(raw: string): string[] { + return raw + .split(",") + .map((host) => host.trim()) + .filter((host) => host.length > 0); +} + +function CreateSecretDialog({ + projectId, + open, + canManageShared, + onOpenChange, +}: { + projectId: string; + open: boolean; + canManageShared: boolean; + onOpenChange: (open: boolean) => void; +}) { + const createSecret = useCreateProjectSecret(); + const [name, setName] = useState(""); + const [value, setValue] = useState(""); + const [description, setDescription] = useState(""); + const [delivery, setDelivery] = useState("brokered"); + const [hosts, setHosts] = useState(""); + const [header, setHeader] = useState("Authorization"); + const [template, setTemplate] = useState("Bearer {}"); + // Defaults to `project` because a secret a team creates is normally a team + // secret — but only when this member could actually create one. A non-admin + // defaulted to `project` would fill the form and then be refused at submit. + const [sharing, setSharing] = useState( + canManageShared ? "project" : "user", + ); + const [error, setError] = useState(null); + const [busy, setBusy] = useState(false); + + const reset = () => { + setName(""); + setValue(""); + setDescription(""); + setDelivery("brokered"); + setHosts(""); + setHeader("Authorization"); + setTemplate("Bearer {}"); + setSharing(canManageShared ? "project" : "user"); + setError(null); + }; + + const submit = async () => { + setBusy(true); + setError(null); + try { + await createSecret({ + projectId, + name, + value, + ...(description.trim() ? { description: description.trim() } : {}), + delivery, + ...(delivery === "brokered" + ? { + brokerHosts: parseHosts(hosts), + brokerHeader: header.trim(), + brokerTemplate: template, + } + : {}), + sharing, + }); + // The value is gone from this process the moment the dialog closes, and + // nothing can bring it back — which is why the field is cleared here + // rather than left populated "in case they want to edit it". + reset(); + onOpenChange(false); + } catch (caught) { + setError( + caught instanceof Error + ? caught.message + : "Failed to create the secret.", + ); + } finally { + setBusy(false); + } + }; + + // Uppercased as you type: the name IS an environment-variable identifier, and + // silently rejecting `stripe_api_key` at submit teaches nothing. + const onName = (raw: string) => + setName(raw.toUpperCase().replace(/[^A-Z0-9_]/g, "_")); + + const nameValid = /^[A-Z_][A-Z0-9_]*$/.test(name); + const brokerValid = + delivery === "materialized" || + (parseHosts(hosts).length > 0 && + header.trim().length > 0 && + template.includes("{}")); + const canSubmit = nameValid && value.length > 0 && brokerValid && !busy; + + return ( + { + if (!next) reset(); + onOpenChange(next); + }} + > + + + New secret + + The value is stored encrypted and cannot be read back — not here, + not through the API. To change it later you replace it. + + + +
+
+ + onName(event.target.value)} + /> +

+ The environment-variable name. Immutable — to rename it later you + create a new secret and delete this one. +

+
+ +
+ +