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 GenerateToken() (string, error)
- func GetOrCreateHMACKey(dataDir string) ([]byte, error)
- func HashToken(token string, key []byte) string
- 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
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 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 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 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 (teams edition)
}
AgentToken represents a stored agent token record.
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)
// 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")
}
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 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) 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.
Source Files