feat(mcp): step-up auth gate for destructive ops — Phase 1 (KLA-408)

[jklaassenjc]

Summary

Phase 1 of KLA-408. Adds an opt-in chokepoint that gates every destructive MCP tool invocation (any tool argument carrying Execute: true) behind a fresh proof of operator presence. Ships the framework and a TTY-based authenticator; Touch ID and out-of-band approval are slated for follow-up slices.

Why

Today the execute: true bit on the 30+ destructive MCP tools is agent-controlled: any connected MCP client can flip it without operator awareness. The audit log records "the credential called users_delete," not "the operator at the keyboard called it." This adds a real human-in-the-loop pause point for the operators who want one.

What's wired

• internal/mcp/stepup.go — stepUpAuthenticator interface, noopStepUp (zero-cost default), ttyStepUp (mutex-serialized prompt for last-6 of API key), newStepUp factory. Reflection helpers isExecutingDestructive and destructiveTarget so a single chokepoint covers all 30+ destructive tool input types without per-handler hooks.
• internal/mcp/tools.go — chokepoint in addTypedTool's wrappedHandler. On denial, returns an error result and records a step-up entry in the audit log.
• internal/mcp/server.go — Options.RequireStepUp + StepUpAPIKey wire config through. Unexported Options.stepUp lets tests inject a recording fake.
• internal/cmd/mcp.go — --require-step-up flag (defaults to mcp.require_step_up_for_destructive). When set with transport=stdio, prints a startup warning that TTY prompts can't reach the operator.
• internal/config/config.go — mcp.require_step_up_for_destructive config key (default false), MCPRequireStepUp() getter, ValidConfigKeys + coerceValue handling.

Trade-offs (called out so reviewers can push back)

• Last-6-of-API-key is a weak challenge — anyone holding the key answers it. Real value is in (a) catching agent-flipped Execute and (b) forcing in-the-loop pause on destructive calls. Stronger authenticators (Touch ID, push approval) plug into the same interface as Phase 2.
• Stdio transport can't host a TTY prompt — --require-step-up is only effective when stdin is a real terminal (e.g. operator-launched --transport http session). Documented via startup warning. For the Claude Desktop / stdio flow, an out-of-band authenticator (Slice 3) is the right answer.
• Default is off. Backwards-compat with all existing deployments.

Behavior matrix

Tool input	Execute: true?	RequireStepUp?	Authenticator says	Result
destructive	yes	true	allow	API call fires
destructive	yes	true	deny	error result; audit-logged
destructive	yes	true	unavailable (no TTY)	error result; audit-logged
destructive	yes	false	(skipped)	API call fires
destructive	no (plan)	true	(skipped)	plan returned
non-destructive (no Execute field)	n/a	true	(skipped)	normal call

Test plan

• go build ./... clean
• go test ./... — full suite passing
• 9 stepup unit tests — noopStepUp allows; factory dispatch; ttyStepUp accept / wrong-fragment-deny / explicit-no-deny / empty-key / too-short-key / target-clause-omitted-when-empty
• 2 reflection helper tests — isExecutingDestructive and destructiveTarget table-driven across multiple tool input types incl. pointers and nil
• 4 chokepoint integration tests — destructive Execute: true triggers step-up; denial blocks the underlying API call; plan mode (Execute: false) bypasses; non-destructive tools (no Execute field) bypass
• CLI flag-defaults test (--require-step-up defaults to false)

Follow-ups

• Phase 2 (Touch ID via LocalAuthentication.framework)
• Phase 2 (op-envelope Ed25519 signing into the audit log)
• Phase 3 (out-of-band Slack/webhook approval)
• docs/AUTH.md section once PR docs(auth): add docs/AUTH.md — single source of truth (KLA-410) #21 lands

🤖 Generated with Claude Code

---

Note

Medium Risk
Adds a new authorization chokepoint that can block destructive MCP tool executions based on an interactive prompt, affecting runtime behavior when enabled and introducing new failure modes (no TTY/no API key). Default is off, limiting impact to opt-in deployments.

Overview
Adds an opt-in step-up authentication gate for destructive MCP tool calls (any tool input with Execute: true), prompting the operator on a controlling TTY and failing closed when denied/unavailable.

Wires the feature end-to-end via new config mcp.require_step_up_for_destructive (default false), server options (RequireStepUp, StepUpAPIKey), and a new jc mcp serve --require-step-up flag (including startup warnings for stdio transport and fail-fast if no API key is available).

Implements the gate in addTypedTool so all destructive tools share a single chokepoint, and adds comprehensive unit/integration tests for the authenticator, reflection-based destructiveness detection, and enforcement behavior.

^{Reviewed by Cursor Bugbot for commit 3037565. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Reviewed by Cursor Bugbot for commit 66d37fb. Configure here.}