Documentation
¶
Overview ¶
Package auth provides authentication header parsing and middleware for the MCP Gateway server.
This package implements MCP specification 7.1 for authentication, which requires Authorization headers to contain the API key directly without any scheme prefix (e.g., NOT "Bearer <key>").
The package provides both full parsing with error handling (ParseAuthHeader) and convenience methods for specific use cases (ExtractAgentID, ValidateAgentID).
Usage Guidelines:
Use ParseAuthHeader() for complete authentication with error handling: Returns both API key and agent ID, with errors for missing/invalid headers.
Use ExtractAgentID() when you only need the agent ID and want automatic fallback to "default" instead of error handling.
Use ValidateAgentID() to check if a provided identifier matches the expected value. Automatically handles the case where authentication is disabled (no expected key).
Example:
// Full authentication
apiKey, agentID, err := auth.ParseAuthHeader(r.Header.Get("Authorization"))
if err != nil {
return err
}
if !auth.ValidateAgentID(apiKey, expectedKey) {
return errors.New("invalid agent ID")
}
// Extract agent ID only (for context, not authentication)
agentID := auth.ExtractAgentID(r.Header.Get("Authorization"))
Index ¶
- Variables
- func ExtractAgentID(authHeader string) string
- func ExtractSessionID(authHeader string) string
- func ExtractSessionIDFromHeaders(xAgentID, authHeader string) string
- func GenerateRandomAgentID() (string, error)
- func IsMalformedHeader(header string) bool
- func ParseAuthHeader(authHeader string) (apiKey string, agentID string, error error)
- func ValidateAgentID(provided, expected string) bool
Constants ¶
This section is empty.
Variables ¶
var ( // ErrMissingAuthHeader is returned when the Authorization header is missing ErrMissingAuthHeader = errors.New("missing Authorization header") // ErrInvalidAuthHeader is returned when the Authorization header format is invalid ErrInvalidAuthHeader = errors.New("invalid Authorization header format") )
Functions ¶
func ExtractAgentID ¶
ExtractAgentID extracts the agent ID from an Authorization header. This is a convenience wrapper around ParseAuthHeader that only returns the agent ID. Returns "default" if the header is empty or cannot be parsed.
This function is intended for use cases where you only need the agent ID and don't need full error handling. For complete authentication handling, use ParseAuthHeader instead.
func ExtractSessionID ¶
ExtractSessionID extracts session ID from Authorization header. Per spec 7.1: When API key is configured, Authorization contains plain API key. When API key is not configured, supports Bearer token for backward compatibility.
This function is specifically designed for server connection handling where:
- Empty auth headers should return "" (to allow rejection of unauthenticated requests)
- Bearer tokens should have whitespace trimmed (for backward compatibility)
Returns:
- Empty string if authHeader is empty
- Trimmed token value if Bearer format
- Plain authHeader value otherwise
func ExtractSessionIDFromHeaders ¶ added in v0.3.24
ExtractSessionIDFromHeaders extracts session ID from X-Agent-ID and Authorization. X-Agent-ID takes precedence when present, otherwise Authorization is used.
func GenerateRandomAgentID ¶ added in v0.3.24
GenerateRandomAgentID generates a cryptographically random agent ID. Per spec §7.3, the gateway SHOULD generate a random agent ID on startup if none is provided. Returns a 32-byte hex-encoded string (64 chars).
func IsMalformedHeader ¶ added in v0.2.26
IsMalformedHeader returns true if the header value contains characters that are not valid in HTTP header values per RFC 7230: null bytes, control characters below 0x20 (except horizontal tab 0x09), or DEL (0x7F). Per spec 7.2 item 3, such headers must be rejected with HTTP 400.
func ParseAuthHeader ¶
ParseAuthHeader parses the Authorization header and extracts the API key and agent ID. Per MCP spec 7.1, the Authorization header should contain the API key directly without any Bearer prefix or other scheme.
For backward compatibility, this function also supports:
- "Bearer <token>" format (uses token as both API key and agent ID)
- "Agent <agent-id>" format (extracts agent ID)
Returns:
- apiKey: The extracted API key
- agentID: The extracted agent/session identifier
- error: ErrMissingAuthHeader if header is empty, nil otherwise
func ValidateAgentID ¶ added in v0.3.24
ValidateAgentID checks if the provided agent identifier matches the expected value. Returns true if they match, false otherwise.
Types ¶
This section is empty.
Source Files