RFC: Shared key authentication for local MCP servers

[JAORMX]

Summary

Port proposal from toolhive PR #2570.

This proposal introduces a lightweight authentication mechanism for localhost MCP server deployments that provides defense-in-depth security without requiring external identity providers.

Overview

The proposal adds shared key authentication as an opt-in feature for local ToolHive deployments. While localhost binding provides network-level security, this adds an additional authentication layer for defense-in-depth.

Key Features

• Cryptographically-secure shared key generation per workload (32-byte keys)
• OS keychain storage via existing encrypted secrets provider
• New middleware for constant-time key validation
• Transparent integration with thv proxy stdio bridge
• Zero-configuration UX: just add --shared-key-auth flag
• Backward compatible (opt-in feature)

Architecture

The solution leverages existing ToolHive infrastructure:

• Key storage: Uses existing encrypted secrets provider and OS keychain integration
• Middleware: Follows standard middleware pattern for clean integration
• Stdio bridge: Enhances existing proxy to inject authentication headers
• Workload manager: Handles key lifecycle automatically

Security Properties

• 256-bit cryptographic keys via crypto/rand
• AES-256-GCM encrypted storage in OS keychain
• Constant-time comparison to prevent timing attacks
• Defense-in-depth layer (complements network isolation)
• Unique key per workload with automatic cleanup

Usage Example

# Enable shared key auth
thv run my-server --shared-key-auth

# ToolHive automatically:
# 1. Generates secure key
# 2. Stores in OS keychain
# 3. Configures middleware
# 4. Updates client config

[eleftherias]

This approach makes sense, but I wonder if it could be simplified.
Did you also consider a single shared key across workloads?

The proposal states

Key injected via TOOLHIVE_SHARED_KEY environment variable to container and proxy

But does the container need to know the key?

I assume if the container doesn't know the key, then we can use a single key across all workloads without risk.