security

package
v0.0.3 Latest Latest
Warning

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

 Go to latest Published: Jul 9, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// ContextKeyUserID is the gin context key for the authenticated user ID.
	ContextKeyUserID = "userID"
	// ContextKeyClientID is the gin context key for the agent client ID.
	ContextKeyClientID = "clientID"
	// ContextKeyRoles is the gin context key for resolved caller roles.
	ContextKeyRoles = "roles"
	// ContextKeyIsAdmin is the gin context key for admin authorization.
	ContextKeyIsAdmin = "isAdmin"
	// ContextKeyIdentity is the gin context key for the resolved caller identity.
	ContextKeyIdentity = "identity"
)
View Source 
const (
	RoleAdmin   = "admin"
	RoleAuditor = "auditor"
	RoleIndexer = "indexer"
)
View Source 
const EmbeddedMCPTransport = "embedded-mcp"

EmbeddedMCPTransport is the string value stored in the context by WithEmbeddedMCPContext. Exported only so internal/cmd/mcp can reference it as documentation; the actual trust gate is the unexported context key, not this string.

Variables

View Source 
var (

	// StoreLatency can be used by store implementations to record operation latency.
	StoreLatency *prometheus.HistogramVec

	CacheHitsTotal   prometheus.Counter
	CacheMissesTotal prometheus.Counter

	// DBPoolOpenConnections tracks the number of currently open database connections.
	DBPoolOpenConnections prometheus.Gauge

	// DBPoolMaxConnections tracks the configured maximum database connections.
	DBPoolMaxConnections prometheus.Gauge

	// SSEConnectionsActive tracks the number of currently active SSE connections.
	SSEConnectionsActive prometheus.Gauge

	// EventBusPublishedTotal counts total events published to the event bus.
	EventBusPublishedTotal prometheus.Counter

	// EventBusDeliveredTotal counts total events delivered to SSE clients.
	EventBusDeliveredTotal prometheus.Counter

	// EventBusDroppedTotal counts total events dropped (slow consumers or publish failures).
	EventBusDroppedTotal prometheus.Counter

	// EventBusSubscriberEvictionsTotal counts total slow subscribers evicted.
	EventBusSubscriberEvictionsTotal prometheus.Counter
)

Functions

func AccessLogMiddleware 

func AccessLogMiddleware(skipPaths ...string) gin.HandlerFunc

AccessLogMiddleware logs each HTTP request with method, path, status, and duration. Paths listed in skipPaths are silently passed through without logging.

func AdminAuditMiddleware 

func AdminAuditMiddleware(requireJustification bool) gin.HandlerFunc

AdminAuditMiddleware logs admin API calls with caller identity and target resource. When requireJustification is true, admin requests must include a justification via query param (?justification=...) or X-Justification header.

func AuthMiddleware 

func AuthMiddleware(resolver *TokenResolver) gin.HandlerFunc

AuthMiddleware returns a gin middleware that extracts user identity from the request headers using the provided TokenResolver. Allows X-API-Key-only requests (for admin service principals) when no Authorization header is present.

func CheckGRPCOIDCScope added in v0.0.3 

func CheckGRPCOIDCScope(ctx context.Context, permission Permission) error

CheckGRPCOIDCScope applies the same resource/API OIDC scope gate for gRPC handlers.

func EffectiveAdminRole 

func EffectiveAdminRole(c *gin.Context) string

EffectiveAdminRole returns the highest resolved admin role.

func GRPCStreamInterceptor 

func GRPCStreamInterceptor(resolver *TokenResolver) grpc.StreamServerInterceptor

GRPCStreamInterceptor returns a gRPC stream server interceptor that resolves caller identity.

func GRPCUnaryInterceptor 

func GRPCUnaryInterceptor(resolver *TokenResolver) grpc.UnaryServerInterceptor

GRPCUnaryInterceptor returns a gRPC unary server interceptor that resolves caller identity.

func GetClientID 

func GetClientID(c *gin.Context) string

GetClientID returns the agent client ID from the gin context.

func GetUserID 

func GetUserID(c *gin.Context) string

GetUserID returns the authenticated user ID from the gin context.

func HasRole 

func HasRole(c *gin.Context, role string) bool

HasRole returns true if the caller has the given role.

func InitMetrics 

func InitMetrics(constLabels prometheus.Labels)

InitMetrics registers all Prometheus metrics with the given constant labels. Must be called before starting the HTTP server or any store/cache initialization that records metrics. Safe to call multiple times; only the first call registers.

func IsAdmin 

func IsAdmin(c *gin.Context) bool

IsAdmin returns true if the request is from an admin.

func MetricsMiddleware 

func MetricsMiddleware() gin.HandlerFunc

MetricsMiddleware records HTTP request metrics for Prometheus.

func ParseMetricsLabels 

func ParseMetricsLabels(s string) (prometheus.Labels, error)

ParseMetricsLabels parses a comma-separated list of key=value pairs into Prometheus labels. Values support ${VAR} / $VAR environment variable expansion. Label values may not contain commas. Returns nil for an empty string.

func RequireAdminRole 

func RequireAdminRole() gin.HandlerFunc

RequireAdminRole requires the caller to have admin role.

func RequireAuditorRole 

func RequireAuditorRole() gin.HandlerFunc

RequireAuditorRole requires the caller to have auditor or admin role.

func RequireOIDCScope added in v0.0.3 

func RequireOIDCScope(permission Permission) gin.HandlerFunc

RequireOIDCScope requires the configured OIDC scope for a resource/API permission. It is a no-op for non-OIDC identities and for permissions with no configured scopes.

func RequireUser added in v0.0.3 

func RequireUser() gin.HandlerFunc

RequireUser requires a non-empty authenticated user principal. Client-only (API-key-only) identities are rejected with 401. This should be applied to all normal user/agent endpoints.

func WithEmbeddedMCPContext added in v0.0.3 

func WithEmbeddedMCPContext(ctx context.Context) context.Context

WithEmbeddedMCPContext stamps a request context as coming from the in-process embedded MCP transport. It must be called only by the in-process handlerTransport.RoundTrip. Remote callers cannot replicate this because embeddedMCPContextKey is unexported.

Types

type CredentialKind added in v0.0.3 

type CredentialKind string

CredentialKind describes the accepted credential combination for an identity. 

const (
	// CredentialOIDC — OIDC JWT bearer token only.
	CredentialOIDC CredentialKind = "oidc"
	// CredentialAPIKey — X-API-Key only (client-only service principal).
	CredentialAPIKey CredentialKind = "api-key"
	// CredentialOIDCAPIKey — OIDC JWT bearer token paired with X-API-Key.
	CredentialOIDCAPIKey CredentialKind = "oidc-api-key"
	// CredentialBearerAPIKey — bearer API key compatibility for no-OIDC deployments.
	CredentialBearerAPIKey CredentialKind = "bearer-api-key"
	// CredentialEmbeddedMCP — in-process embedded MCP synthetic identity.
	// Accepted only when RequestCredentials.Transport == "embedded-mcp"; never from network traffic.
	CredentialEmbeddedMCP CredentialKind = "embedded-mcp"
	// CredentialTesting — raw bearer user accepted only in testing mode with auth_testfixtures build tag.
	CredentialTesting CredentialKind = "testing-bearer-user"
)

type Identity 

type Identity struct {
	UserID         string
	ClientID       string
	Roles          map[string]bool
	IsAdmin        bool
	CredentialKind CredentialKind
	HasOIDCToken   bool
	OIDCScopes     map[string]bool
	OIDCScopeGates map[Permission]map[string]bool
}

Identity holds the resolved caller identity from a bearer token.

func GetIdentity added in v0.0.3 

func GetIdentity(c *gin.Context) *Identity

GetIdentity returns the resolved identity from the gin context.

func IdentityFromContext 

func IdentityFromContext(ctx context.Context) *Identity

IdentityFromContext retrieves the Identity stored in a context by the gRPC interceptor.

type Permission added in v0.0.3 

type Permission string

Permission is a fixed Memory Service API capability that can be additionally gated by configured OIDC token scopes. 

const (
	PermissionUser                    Permission = "user"
	PermissionUserRead                Permission = "user_read"
	PermissionUserWrite               Permission = "user_write"
	PermissionAdmin                   Permission = "admin"
	PermissionAdminRead               Permission = "admin_read"
	PermissionAdminWrite              Permission = "admin_write"
	PermissionSystemRead              Permission = "system_read"
	PermissionConversations           Permission = "conversations"
	PermissionConversationsRead       Permission = "conversations_read"
	PermissionConversationsWrite      Permission = "conversations_write"
	PermissionSharing                 Permission = "sharing"
	PermissionSharingRead             Permission = "sharing_read"
	PermissionSharingWrite            Permission = "sharing_write"
	PermissionSearch                  Permission = "search"
	PermissionSearchRead              Permission = "search_read"
	PermissionSearchWrite             Permission = "search_write"
	PermissionMemories                Permission = "memories"
	PermissionMemoriesRead            Permission = "memories_read"
	PermissionMemoriesWrite           Permission = "memories_write"
	PermissionAttachments             Permission = "attachments"
	PermissionAttachmentsRead         Permission = "attachments_read"
	PermissionAttachmentsWrite        Permission = "attachments_write"
	PermissionEventsRead              Permission = "events_read"
	PermissionRecordings              Permission = "recordings"
	PermissionRecordingsRead          Permission = "recordings_read"
	PermissionRecordingsWrite         Permission = "recordings_write"
	PermissionAdminConversations      Permission = "admin_conversations"
	PermissionAdminConversationsRead  Permission = "admin_conversations_read"
	PermissionAdminConversationsWrite Permission = "admin_conversations_write"
	PermissionAdminMemories           Permission = "admin_memories"
	PermissionAdminMemoriesRead       Permission = "admin_memories_read"
	PermissionAdminMemoriesWrite      Permission = "admin_memories_write"
	PermissionAdminAttachments        Permission = "admin_attachments"
	PermissionAdminAttachmentsRead    Permission = "admin_attachments_read"
	PermissionAdminAttachmentsWrite   Permission = "admin_attachments_write"
	PermissionAdminEventsRead         Permission = "admin_events_read"
	PermissionAdminCheckpoints        Permission = "admin_checkpoints"
	PermissionAdminCheckpointsRead    Permission = "admin_checkpoints_read"
	PermissionAdminCheckpointsWrite   Permission = "admin_checkpoints_write"
	PermissionAdminStatsRead          Permission = "admin_stats_read"
	PermissionAdminMaintenanceWrite   Permission = "admin_maintenance_write"
)

type PermissionDescriptor added in v0.0.3 

type PermissionDescriptor struct {
	Permission Permission
	FlagName   string
	EnvVar     string
	Usage      string
}

PermissionDescriptor describes the explicit flag/env mapping for one fixed permission key.

func PermissionDescriptors added in v0.0.3 

func PermissionDescriptors() []PermissionDescriptor

PermissionDescriptors returns the fixed OIDC scope permission vocabulary.

type RequestCredentials added in v0.0.3 

type RequestCredentials struct {
	// BearerToken is the value after stripping "Bearer " from Authorization header.
	BearerToken string
	// APIKey is the X-API-Key header value.
	APIKey string
	// ClientIDHeader is the X-Client-ID header value (testing/dev compatibility only).
	ClientIDHeader string
	// Transport, when set to EmbeddedMCPTransport, causes the resolver to produce a
	// CredentialEmbeddedMCP identity using the resolver's embedded user/client config.
	// Set only by AuthMiddleware after reading isEmbeddedMCPRequest; never from headers.
	Transport string
}

RequestCredentials is the transport-neutral credential shape extracted from HTTP or gRPC.

type TokenResolver 

type TokenResolver struct {
	// contains filtered or unexported fields
}

TokenResolver resolves bearer tokens to caller identities. It is initialized once at startup and shared by both the HTTP middleware and gRPC interceptors.

func NewTokenResolver 

func NewTokenResolver(cfg *config.Config) (*TokenResolver, error)

NewTokenResolver creates a TokenResolver from the application config. It performs one-time OIDC provider discovery if OIDCIssuer is configured. Returns an error if OIDC is configured but discovery fails.

func (*TokenResolver) ConfigureEmbeddedMCP added in v0.0.3 

func (r *TokenResolver) ConfigureEmbeddedMCP(userID, clientID string)

ConfigureEmbeddedMCP sets the synthetic user and client identity used by the in-process embedded MCP transport. Call this after NewTokenResolver when building an embedded MCP server. The resolver will return CredentialEmbeddedMCP for requests carrying Transport == EmbeddedMCPTransport.

func (*TokenResolver) Resolve 

func (r *TokenResolver) Resolve(ctx context.Context, creds RequestCredentials) (*Identity, error)

Resolve resolves a RequestCredentials into a caller Identity. It applies all configured credential policies based on the deployment configuration.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.