auth

package
v0.65.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 5, 2026 License: MIT Imports: 9 Imported by: 0

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

View Source
const (
	PermRead        = "read"
	PermWrite       = "write"
	PermDestructive = "destructive"
)

Permission constants define the allowed permission tiers.

View Source
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.

View Source
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.

View Source
const MaxTokens = 100

MaxTokens is the maximum number of agent tokens allowed.

View Source
const TokenPrefixStr = "mcp_agt_"

Token prefix used for all agent tokens.

Variables

This section is empty.

Functions

func AgentDeniedServerOp added in v0.52.0

func AgentDeniedServerOp(op string) bool

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

func CanEnumerateServer(ctx context.Context, name string) bool

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

func GenerateToken() (string, error)

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

func GetOrCreateHMACKey(dataDir string) ([]byte, error)

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

func HashToken(token string, key []byte) string

HashToken computes HMAC-SHA256 of the token using the given key and returns the hex-encoded digest.

func IsScopedCaller added in v0.64.0

func IsScopedCaller(ctx context.Context) bool

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

func RevealSecretsAllowed(ctx context.Context, flagEnabled bool) bool

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

func TokenPrefix(token string) string

TokenPrefix returns the first 12 characters of the token for display purposes.

func ValidatePermissions

func ValidatePermissions(perms []string) error

ValidatePermissions checks that the given permissions list is valid. It must contain "read" and only contain valid permission values.

func ValidateTokenFormat

func ValidateTokenFormat(token string) bool

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL