@topline-build/harness-mcp 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -4,11 +4,17 @@ All notable customer-visible Build MCP changes are recorded here. A source chang
 
 ## Unreleased
 
-- Generate a versioned runtime reference and machine-readable documentation manifest from the registry used by MCP `tools/list`.
-- Enforce documentation freshness in tests, continuous integration, and release validation.
-- Define documentation ownership, pull request impact review, release synchronization, and recurring maintenance.
-- Notify the website of an exact npm release immediately, with daily recovery and a review-only pull request boundary.
-- Add machine-readable Codex, Claude Code, and Cursor certification with distinct CLI, protocol, client-mediated read, structured failure, and reviewed apply evidence.
+## 0.5.2 - 2026-09-26
+
+- Report rejected bearer credentials as `authorization_required`, with scoped cache-clearing and browser reconnect guidance instead of input-correction advice.
+- Guide connection-specific cache cleanup and recovery of existing deployment progress before a write is retried.
+- Report native client certification timeouts as failures even when partial output mentions authentication; a timed-out process is not proof of a missing provider session.
+
+## 0.5.1 - 2026-09-18
+
+- Harden the bundled Claude certification script with strict tool isolation, effective-runtime proof, and noninteractive JSONL validation.
+- Update certification setup documentation and regression coverage.
+- Harden live certification CI and add an exact-version website documentation dispatch probe.
 
 ## 0.5.0
 

package/README.md

@@ -22,6 +22,8 @@ npx -y @topline-build/harness-mcp
 
 Run `npx -y @topline-build/harness-mcp --help` for every supported flag and environment variable. `TOPLINE_MCP_TOKEN` is an advanced manual-token fallback; browser-approved OAuth is preferred.
 
+If a tool returns `authorization_required`, clear only that connection's OAuth cache and reconnect through browser sign-in. Replace an expired or revoked manual token if using the fallback. Inspect existing artifact/deployment progress before retrying a write; the helper does not silently replay the rejected request.
+
 ## Typical workflow
 
 1. Use `platform_init_artifact_app` to create a starter, or point at an existing artifact app.
@@ -75,9 +77,11 @@ can consume provider model quota and runs only for clients whose CLI can reject
 user/global MCP configuration and disable every built-in tool. Claude Code is
 currently the supported mediated client; Codex and Cursor report
 `strict_client_tool_isolation_unavailable` instead of starting an agent with
-broader access. The Claude process uses strict MCP configuration, safe mode,
+broader access. The Claude process uses strict MCP configuration, bare mode,
 no built-in tools, an allowlisted environment, an isolated OAuth cache, and a
-server exposing only `platform_inspect_artifact_app`. The write credential is
+server exposing only `platform_inspect_artifact_app`. Its bare noninteractive
+permission bypass is accepted only when Claude's structured init event proves
+that this is the sole effective tool and MCP server. The write credential is
 available only to the direct exact-SHA apply path. Missing client CLIs, provider
 login, URL/app inputs, or credentials produce explicit `skipped` results and
 exit successfully by default; `--require-all` exits 2 for any skip. A failed

package/dist/index.d.ts

@@ -32,7 +32,7 @@ export interface PackedArtifactAppBundle {
 type ToolProgressReporter = (progress: number, message: string) => void | Promise<void>;
 export declare const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
 export declare const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
-export declare const HARNESS_MCP_VERSION = "0.5.0";
+export declare const HARNESS_MCP_VERSION = "0.5.2";
 export declare const DEFAULT_OAUTH_SCOPES: readonly string[];
 export interface BuildMcpSetupOption {
     readonly flag: string;

package/dist/index.js

@@ -13,7 +13,7 @@ import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError } fr
 export const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
 const DEFAULT_TIMEOUT_MS = 120_000;
 export const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
-export const HARNESS_MCP_VERSION = "0.5.0";
+export const HARNESS_MCP_VERSION = "0.5.2";
 export const DEFAULT_OAUTH_SCOPES = Object.freeze(["harness:artifact:read", "harness:artifact:write", "harness:artifact:deploy", "harness:artifact:delete"]);
 export const BUILD_MCP_SETUP_OPTIONS = Object.freeze([
     { flag: "--url", env: "TOPLINE_API_URL", aliases: ["PLATFORM_API_URL", "OVERSITE_API_URL"], required: true, description: "Topline tenant base URL. HTTPS is required except for loopback development." },
@@ -1063,6 +1063,7 @@ function toolError(message) {
     return structuredToolError(message);
 }
 const BUILD_MCP_RECOVERY_ERROR_VALUES = {
+    authorization_required: { retryable: false, recoveryAction: "Clear only this connection's cached OAuth credentials, then reconnect the Build MCP through browser sign-in. If using a manual bearer token, replace the expired or revoked token. Recover existing artifact/deployment progress before retrying a write." },
     platform_harness_timeout: { retryable: true, recoveryAction: "Retry the call. For a deployment, use platform_list_artifact_drafts to recover the artifact and platform_wait_artifact_deploy to resume progress." },
     platform_mcp_tool_error: { retryable: false, recoveryAction: "Read the returned error code, correct the request or OAuth scopes, then retry." },
     artifact_deploy_wait_timeout: { retryable: true, recoveryAction: "Call platform_wait_artifact_deploy again with the same artifactId and operationId." },
@@ -1087,6 +1088,8 @@ function structuredToolError(message) {
     };
 }
 function recoveryErrorCode(message) {
+    if (/^platform_harness_http_error:401(?::|$)/.test(message))
+        return "authorization_required";
     const known = [
         "artifact_delete_plan_stale",
         "artifact_deploy_wait_timeout",

package/docs/generated/build-mcp-manifest.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "package": {
     "name": "@topline-build/harness-mcp",
-    "version": "0.5.0",
+    "version": "0.5.2",
     "bin": {
       "topline-mcp": "dist/cli.js"
     }
@@ -12,7 +12,7 @@
     "defaultVersion": "2025-11-25",
     "server": {
       "name": "topline-build-stdio",
-      "version": "0.5.0"
+      "version": "0.5.2"
     }
   },
   "generatedFrom": {
@@ -171,6 +171,11 @@
       "recoveryAction": "Inspect the code and message, correct the input if needed, then retry the same tool."
     },
     "catalog": [
+      {
+        "code": "authorization_required",
+        "retryable": false,
+        "recoveryAction": "Clear only this connection's cached OAuth credentials, then reconnect the Build MCP through browser sign-in. If using a manual bearer token, replace the expired or revoked token. Recover existing artifact/deployment progress before retrying a write."
+      },
       {
         "code": "platform_harness_timeout",
         "retryable": true,

package/docs/generated/build-mcp-reference.md

@@ -2,7 +2,7 @@
 
 > Generated from `src/index.ts#BUILD_MCP_TOOLS`. Do not edit this file by hand.
 
-Package: `@topline-build/harness-mcp@0.5.0`
+Package: `@topline-build/harness-mcp@0.5.2`
 Transport: `stdio`
 Default protocol: `2025-11-25`
 Canonical guide: https://topline.build/docs/build-mcp-guide
@@ -32,6 +32,7 @@ The first authenticated tool call normally opens browser approval. Set `TOPLINE_
 
 Tool failures set `isError: true` and return `structuredContent.error` with `code`, `message`, `retryable`, and `recoveryAction`.
 
+- `authorization_required` (not automatically retryable): Clear only this connection's cached OAuth credentials, then reconnect the Build MCP through browser sign-in. If using a manual bearer token, replace the expired or revoked token. Recover existing artifact/deployment progress before retrying a write.
 - `platform_harness_timeout` (retryable): Retry the call. For a deployment, use platform_list_artifact_drafts to recover the artifact and platform_wait_artifact_deploy to resume progress.
 - `platform_mcp_tool_error` (not automatically retryable): Read the returned error code, correct the request or OAuth scopes, then retry.
 - `artifact_deploy_wait_timeout` (retryable): Call platform_wait_artifact_deploy again with the same artifactId and operationId.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topline-build/harness-mcp",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Topline Build MCP for creating and deploying artifact app drafts.",
   "type": "module",
   "main": "./dist/index.js",

package/scripts/certify-live.mjs

@@ -20,6 +20,23 @@ const EXPECTED_TOOLS = [
   "platform_validate_artifact",
   "platform_plan_artifact_draft_delete"
 ];
+const PROVIDER_ENV_KEYS = [
+  "ANTHROPIC_API_KEY",
+  "TOPLINE_CERTIFICATION_ALLOW_ANTHROPIC_API_KEY",
+  "TOPLINE_CERTIFICATION_ALLOW_BEDROCK",
+  "CLAUDE_CODE_USE_BEDROCK",
+  "ANTHROPIC_MODEL",
+  "ANTHROPIC_SMALL_FAST_MODEL",
+  "DISABLE_PROMPT_CACHING",
+  "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC",
+  "AWS_ACCESS_KEY_ID",
+  "AWS_SECRET_ACCESS_KEY",
+  "AWS_SESSION_TOKEN",
+  "AWS_REGION",
+  "AWS_DEFAULT_REGION",
+  "AWS_EC2_METADATA_DISABLED",
+  "AWS_STS_REGIONAL_ENDPOINTS"
+];
 const packageJson = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
 const manifest = JSON.parse(await readFile(new URL("../docs/generated/build-mcp-manifest.json", import.meta.url), "utf8"));
 let args;
@@ -38,8 +55,7 @@ if (process.argv[2] === "--certification-read-only-server") {
 }
 
 async function runCertificationReadOnlyServer(values) {
-  delete process.env.ANTHROPIC_API_KEY;
-  delete process.env.TOPLINE_CERTIFICATION_ALLOW_ANTHROPIC_API_KEY;
+  for (const key of PROVIDER_ENV_KEYS) delete process.env[key];
   const opts = parseHarnessOptions(values, withoutManualToken(process.env));
   const server = createHarnessMcpStdioServer(opts, ["platform_inspect_artifact_app"]);
   await server.connect(new StdioServerTransport());
@@ -179,10 +195,7 @@ async function agentMediatedRead(name, command, scratch, apiUrl, appDir, workspa
   if (!appDir) return skipped("certification_app_missing");
   const server = {
     command: process.execPath,
-    env: {
-      ANTHROPIC_API_KEY: "",
-      TOPLINE_CERTIFICATION_ALLOW_ANTHROPIC_API_KEY: ""
-    },
+    env: Object.fromEntries(PROVIDER_ENV_KEYS.map((key) => [key, ""])),
     args: [
       fileURLToPath(import.meta.url),
       "--certification-read-only-server",
@@ -198,21 +211,20 @@ async function agentMediatedRead(name, command, scratch, apiUrl, appDir, workspa
   const configPath = path.join(configDir, "mcp.json");
   await writeFile(configPath, JSON.stringify({ mcpServers: { "topline-build": server } }, null, 2), "utf8");
   const result = run(command, [
-    "--mcp-config", configPath, "--strict-mcp-config", "--safe-mode",
+    "--mcp-config", configPath, "--strict-mcp-config", "--bare",
     "--tools", "", "--allowedTools", "mcp__topline-build__platform_inspect_artifact_app",
-    "--permission-mode", "dontAsk", "--no-chrome", "--disable-slash-commands",
+    "--dangerously-skip-permissions", "--no-chrome", "--disable-slash-commands",
     "--no-session-persistence", "--max-budget-usd", "0.25",
-    "-p", "--output-format", "stream-json", prompt
+    "-p", "--verbose", "--output-format", "stream-json", prompt
   ], scratch, 180000, strictAgentEnvironment(process.env));
   if (!result.ok) {
-    return authUnavailable(result.output)
-      ? skipped("provider_credentials_or_client_session_unavailable")
-      : failed("client_mediated_read_failed", result.exitCode);
+    return clientMediatedFailure(result);
   }
   const usedTool = hasToolCallEvidence(result.output, "platform_inspect_artifact_app");
   const certified = hasAssistantCertificationEvidence(result.output);
-  return usedTool && certified
-    ? passed({ tool: "platform_inspect_artifact_app", providerModelUsed: true })
+  const isolated = hasStrictClaudeInitEvidence(result.output);
+  return usedTool && certified && isolated
+    ? passed({ tool: "platform_inspect_artifact_app", providerModelUsed: true, strictToolIsolation: true, provider: process.env.CLAUDE_CODE_USE_BEDROCK === "1" ? "bedrock" : "anthropic" })
     : failed("client_mediated_tool_evidence_missing", result.exitCode);
 }
 
@@ -330,6 +342,12 @@ async function certifyProtocol({ apiUrl, token, appDir, workspaceRoot }) {
 }
 
 function selfTestReport() {
+  const timedOutProbe = run({ executable: process.execPath, prefix: [] }, ["-e", "console.log('api key authentication required'); setInterval(() => {}, 1000)"], process.cwd(), 1000);
+  const timedOutFailure = clientMediatedFailure(timedOutProbe);
+  if (!timedOutProbe.timedOut || !authUnavailable(timedOutProbe.output) || timedOutFailure.status !== "failed" || timedOutFailure.reason !== "client_mediated_read_timed_out"
+    || clientMediatedFailure({ timedOut: false, output: "not logged in", exitCode: 1 }).status !== "skipped") {
+    throw new Error("client_timeout_classification_self_test_failed");
+  }
   const toolName = "platform_inspect_artifact_app";
   const promptOnly = JSON.stringify({ type: "user", content: `Call ${toolName} and print TOPLINE_CLIENT_READ_CERTIFIED.` });
   const toolEvent = JSON.stringify({ type: "item.completed", item: { type: "mcp_tool_call", tool: toolName } });
@@ -355,6 +373,18 @@ function selfTestReport() {
     ANTHROPIC_API_KEY: "anthropic-secret",
     TOPLINE_CERTIFICATION_ALLOW_ANTHROPIC_API_KEY: "1"
   });
+  const bedrockStrictEnvironment = strictAgentEnvironment({
+    PATH: "kept-path",
+    AWS_ACCESS_KEY_ID: "temporary-access-key",
+    AWS_SECRET_ACCESS_KEY: "temporary-secret-key",
+    AWS_SESSION_TOKEN: "temporary-session-token",
+    AWS_REGION: "us-west-2",
+    AWS_DEFAULT_REGION: "us-west-2",
+    CLAUDE_CODE_USE_BEDROCK: "1",
+    ANTHROPIC_MODEL: "global.anthropic.claude-sonnet-4-6",
+    ANTHROPIC_SMALL_FAST_MODEL: "global.anthropic.claude-sonnet-4-6",
+    TOPLINE_CERTIFICATION_ALLOW_BEDROCK: "1"
+  });
   if (hasToolCallEvidence(promptOnly, toolName)
     || !hasToolCallEvidence(toolEvent, toolName)
     || hasAssistantCertificationEvidence(promptOnly)
@@ -367,7 +397,12 @@ function selfTestReport() {
     || strictEnvironment.USERPROFILE !== "kept-profile"
     || ["AWS_ACCESS_KEY_ID", "DATABASE_URL", "OPENAI_API_KEY", "ANTHROPIC_API_KEY", "CURSOR_API_KEY", "TOPLINE_MCP_TOKEN"].some((key) => key in strictEnvironment)
     || optedInStrictEnvironment.ANTHROPIC_API_KEY !== "anthropic-secret"
-    || "TOPLINE_CERTIFICATION_ALLOW_ANTHROPIC_API_KEY" in optedInStrictEnvironment) {
+    || "TOPLINE_CERTIFICATION_ALLOW_ANTHROPIC_API_KEY" in optedInStrictEnvironment
+    || bedrockStrictEnvironment.CLAUDE_CODE_USE_BEDROCK !== "1"
+    || bedrockStrictEnvironment.AWS_ACCESS_KEY_ID !== "temporary-access-key"
+    || bedrockStrictEnvironment.AWS_SECRET_ACCESS_KEY !== "temporary-secret-key"
+    || bedrockStrictEnvironment.AWS_SESSION_TOKEN !== "temporary-session-token"
+    || "TOPLINE_CERTIFICATION_ALLOW_BEDROCK" in bedrockStrictEnvironment) {
     throw new Error("client_tool_evidence_self_test_failed");
   }
   return {
@@ -435,7 +470,7 @@ function clientCommand(name) {
   return { executable, prefix: [] };
 }
 
-function run(command, commandArgs, cwd, timeout = 30000, env = withoutManualToken(process.env)) {
+function run(command, commandArgs, cwd, timeout = 30000, env = clientProbeEnvironment(process.env)) {
   const result = spawnSync(command.executable, [...command.prefix, ...commandArgs], {
     cwd,
     encoding: "utf8",
@@ -446,14 +481,22 @@ function run(command, commandArgs, cwd, timeout = 30000, env = withoutManualToke
   return {
     ok: result.status === 0,
     missing: result.error?.code === "ENOENT",
+    timedOut: result.error?.code === "ETIMEDOUT",
     exitCode: result.status,
     stdout: result.stdout || "",
     output: `${result.stdout || ""}\n${result.stderr || ""}`
   };
 }
 
+function clientMediatedFailure(result) {
+  if (result.timedOut) return failed("client_mediated_read_timed_out", result.exitCode);
+  return authUnavailable(result.output)
+    ? skipped("provider_credentials_or_client_session_unavailable")
+    : failed("client_mediated_read_failed", result.exitCode);
+}
+
 function authUnavailable(output) {
-  return /not logged in|not authenticated|authentication required|api key|login required|please login|sign in/i.test(output);
+  return /not logged in|not authenticated|authentication required|api key|login required|please login|sign in|unable to locate credentials|security token|AccessDeniedException|UnrecognizedClientException/i.test(output);
 }
 
 function hasToolCallEvidence(output, toolName) {
@@ -468,6 +511,29 @@ function hasToolCallEvidence(output, toolName) {
   return false;
 }
 
+function hasStrictClaudeInitEvidence(output) {
+  for (const line of output.split(/\r?\n/)) {
+    if (!line.trim().startsWith("{")) continue;
+    try {
+      const value = JSON.parse(line);
+      if (value?.type !== "system" || value?.subtype !== "init") continue;
+      return Array.isArray(value.tools)
+        && value.tools.length === 1
+        && value.tools[0] === "mcp__topline-build__platform_inspect_artifact_app"
+        && Array.isArray(value.mcp_servers)
+        && value.mcp_servers.length === 1
+        && value.mcp_servers[0]?.name === "topline-build"
+        && value.mcp_servers[0]?.status === "connected"
+        && value.permissionMode === "bypassPermissions"
+        && Array.isArray(value.slash_commands)
+        && value.slash_commands.length === 0;
+    } catch {
+      // Only the structured Claude init event can prove the effective tool set.
+    }
+  }
+  return false;
+}
+
 function containsToolCall(value, toolName) {
   if (!value || typeof value !== "object") return false;
   const type = typeof value.type === "string" ? value.type : "";
@@ -510,17 +576,34 @@ function withoutManualToken(source) {
 }
 
 function strictAgentEnvironment(source) {
+  const env = clientProbeEnvironment(source);
+  if (source.TOPLINE_CERTIFICATION_ALLOW_ANTHROPIC_API_KEY === "1" && source.ANTHROPIC_API_KEY) {
+    env.ANTHROPIC_API_KEY = source.ANTHROPIC_API_KEY;
+  }
+  const bedrockCredentialKeys = ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN"];
+  if (source.TOPLINE_CERTIFICATION_ALLOW_BEDROCK === "1"
+    && source.CLAUDE_CODE_USE_BEDROCK === "1"
+    && bedrockCredentialKeys.every((key) => typeof source[key] === "string" && source[key].length > 0)) {
+    for (const key of [
+      ...bedrockCredentialKeys,
+      "AWS_REGION", "AWS_DEFAULT_REGION", "AWS_EC2_METADATA_DISABLED", "AWS_STS_REGIONAL_ENDPOINTS",
+      "CLAUDE_CODE_USE_BEDROCK", "ANTHROPIC_MODEL", "ANTHROPIC_SMALL_FAST_MODEL",
+      "DISABLE_PROMPT_CACHING", "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC"
+    ]) {
+      if (typeof source[key] === "string" && source[key].length > 0) env[key] = source[key];
+    }
+  }
+  return env;
+}
+
+function clientProbeEnvironment(source) {
   const allowed = new Set([
     "ALL_PROXY", "APPDATA", "CI", "COMSPEC", "FORCE_COLOR", "HTTP_PROXY", "HTTPS_PROXY",
     "LANG", "LC_ALL", "LOCALAPPDATA", "NODE_EXTRA_CA_CERTS", "NO_COLOR", "NO_PROXY", "PATH",
     "PATHEXT", "PROGRAMDATA", "SSL_CERT_DIR", "SSL_CERT_FILE", "SYSTEMROOT", "TEMP", "TMP",
     "USERPROFILE", "WINDIR"
   ]);
-  const env = Object.fromEntries(Object.entries(source).filter(([key]) => allowed.has(key.toUpperCase())));
-  if (source.TOPLINE_CERTIFICATION_ALLOW_ANTHROPIC_API_KEY === "1" && source.ANTHROPIC_API_KEY) {
-    env.ANTHROPIC_API_KEY = source.ANTHROPIC_API_KEY;
-  }
-  return env;
+  return Object.fromEntries(Object.entries(source).filter(([key]) => allowed.has(key.toUpperCase())));
 }
 
 function structured(result) {