Documentation
¶
Overview ¶
Package auth provides agent token authentication for MCPProxy.
It implements token generation, validation, HMAC-based hashing, and context propagation for distinguishing admin vs agent access. Agent tokens use the "mcp_agt_" prefix and are secured with HMAC-SHA256 hashing before storage.
Index ¶
- Constants
- func AgentDeniedServerOp(op string) bool
- func AuthorizeServerOp(ac *AuthContext, op string) bool
- func CanEnumerateServer(ctx context.Context, name string) bool
- func GenerateToken() (string, error)
- func GetOrCreateHMACKey(dataDir string) ([]byte, error)
- func HashToken(token string, key []byte) string
- func IsScopedCaller(ctx context.Context) bool
- func RevealSecretsAllowed(ctx context.Context, flagEnabled bool) bool
- func TokenPrefix(token string) string
- func ValidatePermissions(perms []string) error
- func ValidateTokenFormat(token string) bool
- func WithAuthContext(ctx context.Context, ac *AuthContext) context.Context
- type AgentToken
- type AuthContext
- func (ac *AuthContext) CanAccessServer(name string) bool
- func (ac *AuthContext) CanRevealSecrets() bool
- func (ac *AuthContext) GetUserID() string
- func (ac *AuthContext) HasPermission(perm string) bool
- func (ac *AuthContext) IsAdmin() bool
- func (ac *AuthContext) IsAuthenticated() bool
- func (ac *AuthContext) IsUser() bool
Constants ¶
const ( PermRead = "read" PermWrite = "write" PermDestructive = "destructive" )
Permission constants define the allowed permission tiers.
const ( AuthTypeAdmin = "admin" // API key admin (personal edition) AuthTypeAgent = "agent" // Agent token authentication AuthTypeUser = "user" // Regular OAuth-authenticated user (server edition) AuthTypeAdminUser = "admin_user" // OAuth-authenticated admin (server edition) )
Auth type constants.
const ( ServerOpAdd = "add" ServerOpRemove = "remove" ServerOpUpdate = "update" ServerOpPatch = "patch" ServerOpEnable = "enable" ServerOpDisable = "disable" ServerOpRestart = "restart" ServerOpRefresh = "refresh" ServerOpDiscoverTools = "discover_tools" ServerOpQuarantine = "quarantine" ServerOpUnquarantine = "unquarantine" ServerOpAddFromRegistry = "add_from_registry" ServerOpLogin = "login" ServerOpLogout = "logout" ServerOpConfigToSecret = "config_to_secret" ServerOpApproveTools = "approve_tools" ServerOpBlockTools = "block_tools" // REST-only mutating operations that reach server/security/config state // through routes OTHER than /api/v1/servers/{id}. They are denied to agents // so the /servers gate cannot be bypassed via a sibling endpoint // (config apply rewrites mcpServers; registry add creates a server; the // security scanner mutates a server's approval state). ServerOpConfigWrite = "config_write" ServerOpScan = "scan" ServerOpSecurityApprove = "security_approve" ServerOpSecurityReject = "security_reject" ServerOpSecretWrite = "secret_write" ServerOpDiagnosticsFix = "diagnostics_fix" )
Server-mutating operation identifiers.
These name the write operations on upstream MCP servers that are exposed on BOTH the MCP `upstream_servers` / `quarantine_security` tools and the REST `/api/v1/servers/...` surface. They are the single source of truth for which operations agent tokens (non-admin) may NOT perform, so the two surfaces can never drift apart again (issues #877/#878).
The string values for the operations that also exist on the MCP `upstream_servers` tool intentionally match that tool's operation names (see internal/server/mcp.go: operationAdd/operationRemove and the literal "update"/"patch"/"enable"/"disable"/"restart"/"refresh"/"add_from_registry" dispatch), so the MCP denylist can consume this policy without changing its observable behavior. REST-only operations (quarantine, login, …) use their own identifiers; the MCP surface never passes those strings here, so listing them is a no-op for MCP and closes the REST gap.
const MaxTokens = 100
MaxTokens is the maximum number of agent tokens allowed.
const TokenPrefixStr = "mcp_agt_"
Token prefix used for all agent tokens.
Variables ¶
This section is empty.
Functions ¶
func AgentDeniedServerOp ¶ added in v0.52.0
AgentDeniedServerOp reports whether the named operation is forbidden to agent tokens (non-admin auth contexts). It is case-sensitive: callers pass the canonical ServerOp* identifiers, never user-controlled free text.
func AuthorizeServerOp ¶ added in v0.52.0
func AuthorizeServerOp(ac *AuthContext, op string) bool
AuthorizeServerOp is the shared gate both surfaces use. It returns true when the caller is permitted to perform op. An admin context (API key or OS-authenticated socket) is always allowed. A nil context means the request arrived without an AuthContext — the auth middleware only leaves it nil in test/no-config passthrough scenarios that never occur once a real *config.Config is loaded, so it is treated as allowed here (the middleware, not this policy, is responsible for rejecting unauthenticated production requests). Any present non-admin context (agent token) is denied when op is on the denylist.
func CanEnumerateServer ¶ added in v0.64.0
CanEnumerateServer is THE shared predicate for "may this caller SEE that a server named `name` exists?" (issue #1166).
The MCP door has filtered upstream enumeration through AuthContext.CanAccessServer since Spec 028; the REST doors never did, so a token scoped to `allowed_servers: ["alpha"]` still enumerated every configured server on GET /api/v1/servers, /api/v1/config, /api/v1/tools, /api/v1/status and the /events stream. Reads on both surfaces now answer from one place.
Fails OPEN on absence, deliberately and in exact mirror of AuthorizeServerOp: apiKeyAuthMiddleware forwards a request with NO AuthContext whenever the controller has no usable config (the testing / bootstrap passthrough), and treating that as "sees nothing" would blank the server list for every such caller. Absence of a token must not be stricter than a scoped token — it must be treated exactly as today's unrestricted behaviour. The unauthenticated /mcp back-compat context (AnonymousContext) is admin-typed and likewise unrestricted here; hiding a server's NAME from it is not the boundary this predicate defends, revealing its CREDENTIALS is, and that is what RevealSecretsAllowed refuses it.
func GenerateToken ¶
GenerateToken creates a new agent token with the mcp_agt_ prefix followed by 64 hex characters (32 random bytes). Total length: 72 chars.
func GetOrCreateHMACKey ¶
GetOrCreateHMACKey reads the HMAC key from <dataDir>/.token_key. If the file does not exist, it generates a 32-byte random key, writes it with 0600 permissions, and returns it.
func HashToken ¶
HashToken computes HMAC-SHA256 of the token using the given key and returns the hex-encoded digest.
func IsScopedCaller ¶ added in v0.64.0
IsScopedCaller reports whether ctx carries a non-admin identity whose visibility is limited by AllowedServers. It is the cheap short-circuit for handlers that would otherwise copy a payload just to filter it: an admin (or an absent context, per CanEnumerateServer) sees everything, so the payload can be forwarded untouched.
func RevealSecretsAllowed ¶ added in v0.64.0
RevealSecretsAllowed is THE shared predicate for "may this caller be handed raw credential values?" (issues #1148 and #1167).
Both halves are required and neither is sufficient:
- flagEnabled — the operator's `reveal_secret_headers` opt-in, and
- CanRevealSecrets() — an authenticated, non-anonymous admin identity.
#1167: the MCP door already ANDed the two; the REST list, the whole-config read, both doctor doors and the per-server diagnostics door checked the flag ALONE, so a read-only agent token scoped to one server received every other server's Authorization header, URL query credential, argv secret and env secret in plaintext the moment an operator turned the flag on. Every request-scoped door now reads the answer from here so they cannot drift apart again.
Fails CLOSED on absence: a nil ctx (an in-process or future background caller) and a ctx with no AuthContext both yield false. A payload with no caller has no identity to check, so it gets masked values.
func TokenPrefix ¶
TokenPrefix returns the first 12 characters of the token for display purposes.
func ValidatePermissions ¶
ValidatePermissions checks that the given permissions list is valid. It must contain "read" and only contain valid permission values.
func ValidateTokenFormat ¶
ValidateTokenFormat checks that a token has the correct format: mcp_agt_ prefix followed by exactly 64 hex characters (72 chars total).
func WithAuthContext ¶
func WithAuthContext(ctx context.Context, ac *AuthContext) context.Context
WithAuthContext returns a new context with the given AuthContext attached.
Types ¶
type AgentToken ¶
type AgentToken struct {
Name string `json:"name"`
TokenHash string `json:"token_hash"`
TokenPrefix string `json:"token_prefix"` // first 12 chars of the raw token
AllowedServers []string `json:"allowed_servers"`
Permissions []string `json:"permissions"`
ExpiresAt time.Time `json:"expires_at"`
CreatedAt time.Time `json:"created_at"`
LastUsedAt *time.Time `json:"last_used_at,omitempty"`
Revoked bool `json:"revoked"`
UserID string `json:"user_id,omitempty"` // Owner user ID (server edition)
ProfilePin string `json:"profile_pin,omitempty"` // Profile this token is pinned to (Profiles v2 T3)
}
AgentToken represents a stored agent token record.
func (*AgentToken) AuthContext ¶ added in v0.58.0
func (t *AgentToken) AuthContext() *AuthContext
AuthContext builds the request AuthContext for a validated agent token. It is the single constructor for the agent tier so no auth path can silently drop a field: the REST path used to omit ProfilePin, which meant a profile-pinned token evaluated (and, with Spec 098, preflighted) against the unpinned server set. Returns nil for a nil token.
func (*AgentToken) IsExpired ¶
func (t *AgentToken) IsExpired() bool
IsExpired returns true if the token has passed its expiry time.
func (*AgentToken) IsRevoked ¶
func (t *AgentToken) IsRevoked() bool
IsRevoked returns true if the token has been revoked.
type AuthContext ¶
type AuthContext struct {
Type string // "admin", "agent", "user", or "admin_user"
AgentName string // Name of the agent token (empty for admin)
TokenPrefix string // First 12 chars of raw token (empty for admin)
AllowedServers []string // Servers this token can access (nil = all for admin)
Permissions []string // Permission tiers (nil = all for admin)
ProfilePin string // Profile this agent token is pinned to (Profiles v2 T3; empty if unpinned)
// Multi-user OAuth fields (server edition). Empty for non-user auth types.
UserID string // User's unique ULID identifier
Email string // User's email from OAuth provider
DisplayName string // User's display name
Role string // "admin" or "user" (empty for API key / agent token auth)
Provider string // OAuth provider used (e.g., "google", "github")
// Anonymous marks a context that was NOT authenticated and only carries
// admin type for backward compatibility (issue #1148).
//
// /mcp is deliberately unprotected by default (require_mcp_auth=false) so
// MCP clients that cannot send an API key keep working, and the middleware
// therefore hands an unauthenticated request an admin context. That is
// fine for the operations those clients need — and it is NOT an identity,
// so it must not satisfy a check that hands back raw credentials. See
// CanRevealSecrets.
Anonymous bool
}
AuthContext carries authentication identity through request context.
func AdminContext ¶
func AdminContext() *AuthContext
AdminContext returns an AuthContext representing full admin access (API key auth).
func AdminUserContext ¶ added in v0.21.0
func AdminUserContext(userID, email, displayName, provider string) *AuthContext
AdminUserContext returns an AuthContext for an OAuth-authenticated admin user.
func AnonymousContext ¶ added in v0.64.0
func AnonymousContext() *AuthContext
AnonymousContext returns the back-compat admin context for an UNAUTHENTICATED MCP request (issue #1148).
Type stays AuthTypeAdmin on purpose: every existing IsAdmin()-based allowance — ordinary tool calls, retrieve_tools, server add/update/patch, quarantine approvals — behaves exactly as it did, so no MCP client that works today stops working. The only thing the Anonymous bit changes is CanRevealSecrets.
func AuthContextFromContext ¶
func AuthContextFromContext(ctx context.Context) *AuthContext
AuthContextFromContext extracts the AuthContext from the context. Returns nil if no AuthContext is present.
func UserContext ¶ added in v0.21.0
func UserContext(userID, email, displayName, provider string) *AuthContext
UserContext returns an AuthContext for a regular OAuth-authenticated user.
func (*AuthContext) CanAccessServer ¶
func (ac *AuthContext) CanAccessServer(name string) bool
CanAccessServer checks whether this context is allowed to access the named server. Admin contexts have unrestricted access. Agent contexts check their AllowedServers list, where "*" is treated as a wildcard granting access to all servers.
func (*AuthContext) CanRevealSecrets ¶ added in v0.64.0
func (ac *AuthContext) CanRevealSecrets() bool
CanRevealSecrets reports whether this caller may be handed RAW credential values (issue #1148) — today, `upstream_servers list` under the opt-in `reveal_secret_headers` flag.
It is deliberately stricter than IsAdmin and deliberately nil-safe:
- an unauthenticated /mcp caller is admin for back-compat but has proved no identity, so it gets masked values like everyone else;
- a nil context (the stdio transport before it installs one, an in-process caller, a test) is unprivileged rather than admin-by-absence — the opposite of the `authCtx != nil && !authCtx.IsAdmin()` shape, which lets the ABSENCE of a token pass a gate that a scoped token fails.
Authenticated admins — the API key, a tray/socket connection, stdio, an OAuth admin user in the server edition — are unaffected.
func (*AuthContext) GetUserID ¶ added in v0.21.0
func (ac *AuthContext) GetUserID() string
GetUserID returns the user's unique identifier, or empty string for non-user auth.
func (*AuthContext) HasPermission ¶
func (ac *AuthContext) HasPermission(perm string) bool
HasPermission checks whether this context includes the given permission. Admin contexts have all permissions. Agent contexts check their Permissions list.
func (*AuthContext) IsAdmin ¶
func (ac *AuthContext) IsAdmin() bool
IsAdmin returns true if this is an admin authentication context. Both API key admins ("admin") and OAuth-authenticated admins ("admin_user") are considered admin.
func (*AuthContext) IsAuthenticated ¶ added in v0.21.0
func (ac *AuthContext) IsAuthenticated() bool
IsAuthenticated returns true if this context has any authentication type set.
func (*AuthContext) IsUser ¶ added in v0.21.0
func (ac *AuthContext) IsUser() bool
IsUser returns true if this is an OAuth-authenticated user context. Both regular users ("user") and admin users ("admin_user") are considered users.