Documentation
¶
Overview ¶
Package session provides JWT-based session ID generation and validation
Index ¶
- Constants
- Variables
- func DeriveEncryptionKey(signingKey []byte) ([]byte, error)
- func WithEncryptionKey(key []byte) func(c *Cache)
- func WithRedisClient(client *redis.Client) func(c *Cache)
- type BackendInitClaims
- type Cache
- func (c *Cache) AddSession(ctx context.Context, key, mcpServerID, mcpSession string, ttl time.Duration) (bool, error)
- func (c *Cache) DeleteSessions(ctx context.Context, key ...string) error
- func (c *Cache) DeleteUserToken(ctx context.Context, sessionID, serverName string) error
- func (c *Cache) GetClientElicitation(ctx context.Context, gatewaySessionID string) (bool, error)
- func (c *Cache) GetSession(ctx context.Context, key string) (map[string]string, error)
- func (c *Cache) GetUserToken(ctx context.Context, sessionID, serverName string) (string, bool, error)
- func (c *Cache) KeyExists(ctx context.Context, key string) (bool, error)
- func (c *Cache) RemoveServerSession(ctx context.Context, key, mcpServerID string) error
- func (c *Cache) SetClientElicitation(ctx context.Context, gatewaySessionID string, ttl time.Duration) error
- func (c *Cache) SetUserToken(ctx context.Context, sessionID, serverName, token string) error
- type Claims
- type Deleter
- type JWTManager
- func (m *JWTManager) Generate() string
- func (m *JWTManager) GenerateBackendInitToken(host string) (string, error)
- func (m *JWTManager) GetExpiresIn(tokenValue string) (time.Time, error)
- func (m *JWTManager) Terminate(sessionID string) (isNotAllowed bool, err error)
- func (m *JWTManager) Validate(tokenValue string) (bool, error)
- func (m *JWTManager) ValidateBackendInitToken(tokenValue, expectedHost string) error
Constants ¶
const ( // DefaultSessionDuration is the default duration for session JWTs DefaultSessionDuration = 24 * time.Hour )
Variables ¶
var ErrInvalidBackendInitToken = errors.New("invalid backend-init token")
ErrInvalidBackendInitToken is returned when a backend-init JWT cannot be validated
Functions ¶
func DeriveEncryptionKey ¶ added in v0.7.0
DeriveEncryptionKey derives a 32-byte AES-256 key from the session signing key using HKDF.
func WithEncryptionKey ¶ added in v0.7.0
WithEncryptionKey sets the AES-256 key for encrypting user tokens in Redis.
func WithRedisClient ¶ added in v0.6.0
WithRedisClient configures the cache to use an existing redis client
Types ¶
type BackendInitClaims ¶ added in v0.7.0
type BackendInitClaims struct {
jwt.RegisteredClaims
Purpose string `json:"purpose"`
Host string `json:"host"`
}
BackendInitClaims represents the claims in a short-lived JWT used to authenticate the hairpin backend-init request the router makes when lazily initializing a session with an upstream MCP server.
type Cache ¶
type Cache struct {
// contains filtered or unexported fields
}
Cache implements a cache
func NewCache ¶
NewCache returns a new cache. Pass WithRedisClient to use an external redis store; otherwise an in-memory cache is returned.
func (*Cache) AddSession ¶
func (c *Cache) AddSession(ctx context.Context, key, mcpServerID, mcpSession string, ttl time.Duration) (bool, error)
AddSession will add a session under the key. If the key exists it will append that session. ttl sets the expiry on the Redis hash key; pass 0 for no expiry (in-memory mode ignores ttl).
func (*Cache) DeleteSessions ¶
DeleteSessions deletes sessions and associated metadata from the cache
func (*Cache) DeleteUserToken ¶ added in v0.7.0
DeleteUserToken removes a cached upstream token for the given session and server.
func (*Cache) GetClientElicitation ¶ added in v0.6.0
GetClientElicitation returns whether the client for this gateway session supports elicitation
func (*Cache) GetSession ¶
GetSession returns a session from the cache
func (*Cache) GetUserToken ¶ added in v0.7.0
func (c *Cache) GetUserToken(ctx context.Context, sessionID, serverName string) (string, bool, error)
GetUserToken retrieves a cached upstream token. Returns ("", false, nil) on miss. JWT tokens are checked for expiry; expired tokens are deleted and treated as a miss.
func (*Cache) RemoveServerSession ¶
RemoveServerSession remove specific server session form cache
func (*Cache) SetClientElicitation ¶ added in v0.6.0
func (c *Cache) SetClientElicitation(ctx context.Context, gatewaySessionID string, ttl time.Duration) error
SetClientElicitation records that the client for this gateway session supports elicitation. ttl sets the key expiry in Redis; pass 0 for no expiry (in-memory mode ignores ttl).
type Claims ¶
type Claims struct {
jwt.RegisteredClaims
}
Claims represents the claims in a session JWT
type JWTManager ¶
type JWTManager struct {
// contains filtered or unexported fields
}
JWTManager handles JWT generation and validation for session IDs
func NewJWTManager ¶
func NewJWTManager(signingKey string, sessionLength int64, logger *slog.Logger, sessionHandler Deleter) (*JWTManager, error)
NewJWTManager creates a new JWT manager with the provided signing key
func (*JWTManager) Generate ¶
func (m *JWTManager) Generate() string
Generate returns a session id JWT to fullfil SessionIdManager interface
func (*JWTManager) GenerateBackendInitToken ¶ added in v0.7.0
func (m *JWTManager) GenerateBackendInitToken(host string) (string, error)
GenerateBackendInitToken creates a short-lived JWT bound to a specific upstream host, used to authenticate the router's hairpin backend-init request. The token is signed with the same HMAC key used for client session JWTs but uses a distinct audience and purpose claim so it cannot be confused with a client session token.
func (*JWTManager) GetExpiresIn ¶
func (m *JWTManager) GetExpiresIn(tokenValue string) (time.Time, error)
GetExpiresIn returns the time a token will expire
func (*JWTManager) Terminate ¶
func (m *JWTManager) Terminate(sessionID string) (isNotAllowed bool, err error)
Terminate part of the SessionIDManager interface. Will remove the associated sessions from cache
func (*JWTManager) Validate ¶
func (m *JWTManager) Validate(tokenValue string) (bool, error)
Validate validates a JWT token and fulfils SessionIdManager interface. returns IsInValid as a bool
func (*JWTManager) ValidateBackendInitToken ¶ added in v0.7.0
func (m *JWTManager) ValidateBackendInitToken(tokenValue, expectedHost string) error
ValidateBackendInitToken verifies a short-lived backend-init JWT. The token must be signed with the manager's HMAC key, have issuer=mcp-gateway, audience=mcp-router, purpose=backend-init and a host claim equal to the expected target host. Any mismatch or expiry returns ErrInvalidBackendInitToken.
Source Files