Add proposal for shared key authentication for local deployments

[JAORMX]

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

This addresses security concerns around unauthenticated localhost ports while maintaining simplicity for single-user local deployments.

[codecov[bot]]

Codecov Report

:white_check_mark: All modified and coverable lines are covered by tests. :white_check_mark: Project coverage is 54.92%. Comparing base (89b161e) to head (4fb0176).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2570      +/-   ##
==========================================
+ Coverage   54.90%   54.92%   +0.02%     
==========================================
  Files         305      305              
  Lines       28712    28712              
==========================================
+ Hits        15765    15771       +6     
+ Misses      11544    11533      -11     
- Partials     1403     1408       +5     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

• :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.