Help us shape the future of Go! Take the 2026 Go Developer Survey

middleware

package
v2.17.1 Latest Latest
Warning

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

 Go to latest Published: Oct 25, 2026 License: BSD-3-Clause Imports: 43 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	HeaderAgentBootstrap             = "X-Arcane-Agent-Bootstrap"
	HeaderAgentToken                 = "X-Arcane-Agent-Token" // #nosec G101: header name, not a credential
	HeaderApiKey                     = "X-Api-Key"            // #nosec G101: header name, not a credential
	HeaderActivityBatchID            = "X-Arcane-Batch-Id"
	HeaderUpdateInitiatorID          = "X-Arcane-Update-Initiator-Id"
	HeaderUpdateInitiatorName        = "X-Arcane-Update-Initiator-Name"
	HeaderUpdateInitiatorDisplayName = "X-Arcane-Update-Initiator-Display-Name"
	// HeaderIconCatalog carries the requesting user's icon catalog preference to
	// remote environments. Agents authenticate proxied calls as a synthetic user
	// with no preferences, so without it every remote environment would resolve
	// container/project icons against the default catalog.
	HeaderIconCatalog  = "X-Arcane-Icon-Catalog"
	AgentPairingPrefix = "/api/environments/0/agent/pair"

	ContextKeyApiKeyID ContextKey = "apiKeyID"
	// ContextKeyUserID is the context key for the authenticated user's ID.
	ContextKeyUserID ContextKey = "userID"
	// ContextKeyCurrentSessionID is the context key for the authenticated session ID.
	ContextKeyCurrentSessionID ContextKey = "currentSessionID"
	// ContextKeyUserPermissions is the context key for the caller's resolved
	// PermissionSet, attached by the auth bridge.
	ContextKeyUserPermissions ContextKey = "userPermissions"
	// ContextKeyRemoteAddr is the context key for the request remote address.
	ContextKeyRemoteAddr ContextKey = "remoteAddr"
	// ContextKeyCurrentUser is the Echo context key for the authenticated user.
	ContextKeyCurrentUser ContextKey = "currentUser"
	// ContextKeyAuthMethod is the Echo context key for the authentication method.
	ContextKeyAuthMethod ContextKey = "authMethod"
)

Variables

This section is empty.

Functions

func GetCurrentSessionIDFromContext added in v2.8.0 

func GetCurrentSessionIDFromContext(ctx context.Context) (string, bool)

GetCurrentSessionIDFromContext retrieves the current session ID from the context.

func GetRemoteAddrFromContext added in v2.8.0 

func GetRemoteAddrFromContext(ctx context.Context) string

GetRemoteAddrFromContext retrieves the request remote address from context.

func GetUserIDFromContext added in v2.8.0 

func GetUserIDFromContext(ctx context.Context) (string, bool)

GetUserIDFromContext retrieves the user ID from the context.

func IsManagerLocalPath added in v2.16.0 

func IsManagerLocalPath(method, suffix string) bool

IsManagerLocalPath reports whether an environment-scoped path suffix is served by the manager instead of being proxied.

func NewActivityBatchID added in v2.8.0 

func NewActivityBatchID() func(ctx huma.Context, next func(huma.Context))

NewActivityBatchID lifts the client-supplied activity batch ID header into the request context so activities spawned by one logical bulk action can be grouped without threading the ID through every handler. Invalid values are ignored by utils.WithActivityBatchID.

func NewEnvProxyMiddlewareWithParamAndRegistry 

func NewEnvProxyMiddlewareWithParamAndRegistry(
	localID,
	paramName string,
	resolver EnvResolver,
	authValidator AuthValidator,
	matcher *authz.PermissionMatcher,
	registry *edge.TunnelRegistry,
	checkOrigin func(*http.Request) bool,
) echo.MiddlewareFunc

NewEnvProxyMiddlewareWithParamAndRegistry creates middleware with an injected tunnel registry.

func NewEnvironmentScopeMiddleware added in v2.16.1 

func NewEnvironmentScopeMiddleware(resolve httpx.EnvironmentResolver, matcher *authz.PermissionMatcher, limit func(context.Context) int) echo.MiddlewareFunc

func PerAgentTokenRateLimit 

func PerAgentTokenRateLimit(perMinute, burst int) echo.MiddlewareFunc

PerAgentTokenRateLimit returns an Echo middleware that limits requests per edge agent token to the given rate and burst.

func PerIPRateLimit 

func PerIPRateLimit(perMinute, burst int) echo.MiddlewareFunc

PerIPRateLimit returns an Echo middleware that limits requests per client IP to the given rate and burst. It responds with 429 when the limit is exceeded.

func PerIPRateLimitForPaths 

func PerIPRateLimitForPaths(paths []string, perMinute, burst int) echo.MiddlewareFunc

PerIPRateLimitForPaths returns an Echo middleware that applies a per-IP rate limit only when c.Path() (the registered route pattern) is in paths. Each path gets its own independent token bucket, so traffic on one path does not deplete the budget for another (e.g. a login burst will not block a concurrent token refresh).

func PerTokenRateLimitForPaths added in v2.10.2 

func PerTokenRateLimitForPaths(
	paths []string,
	perMinute int,
	burst int,
	tokenOf func(c *echo.Context) string,
	isKnown func(token string) bool,
) echo.MiddlewareFunc

PerTokenRateLimitForPaths gives known tokens independent budgets and limits others per IP. isKnown must be an in-memory lookup with bounded input, without request-driven cache fills. A nil lookup falls back to the shared IP limiter.

func PermissionsFromContext added in v2.8.0 

func PermissionsFromContext(ctx context.Context) (*authz.PermissionSet, bool)

PermissionsFromContext retrieves the caller's resolved PermissionSet. Returns nil, false on unauthenticated paths.

func RecordAuthenticatedRequest added in v2.16.0 

func RecordAuthenticatedRequest(ctx context.Context, header http.Header, user *usertypes.Actor)

RecordAuthenticatedRequest tags the request span with the acting user and counts the request by credential type.

func RegisterWithPermission added in v2.8.0 

func RegisterWithPermission[I, O any](api huma.API, op huma.Operation, perm string, handler func(context.Context, *I) (*O, error))

RegisterWithPermission registers a Huma operation that requires perm. It attaches the RequirePermission middleware AND records perm in the operation metadata (authz.MetaRequiredPermission) so the remote environment proxy can enforce the same permission for environment-scoped operations before forwarding a request to an agent.

Use this instead of huma.Register with an inline RequirePermission middleware for every operation served under /environments/{id}/..., so the required permission stays the single source of truth for both local enforcement and remote-proxy enforcement. It is safe to use for org-level operations too; the recorded metadata is simply unused by the proxy for non-environment paths.

func RequireEchoPermission added in v2.8.0 

func RequireEchoPermission(perm string) echo.MiddlewareFunc

RequireEchoPermission rejects Echo requests lacking perm for the environment in the request path, or globally for organization-level permissions. It must run after auth.AuthMiddleware has attached the caller's permission set.

func RequireGlobalAdmin added in v2.8.0 

func RequireGlobalAdmin(api huma.API) huma.Middlewares

RequireGlobalAdmin returns a per-operation Huma middleware that rejects any caller who is not a global admin (or sudo). Used for operations that are intentionally not exposed as delegated permissions — role creation/edits, user role assignment, and OIDC mapping management. Keeping these admin-only avoids the meta-escalation surface where a holder of `roles:assign` could promote themselves via a custom role.

func RequirePermission 

func RequirePermission(api huma.API, perm string) huma.Middlewares

RequirePermission returns per-operation Huma middleware that rejects callers lacking `perm`. For env-scoped permissions, the env ID is extracted from the request path (/environments/{id}/...). For org-level permissions, the env ID segment, if any, is ignored.

Attach via Operation.Middlewares: 

huma.Register(api, huma.Operation{..., Middlewares: middleware.RequirePermission(api, authz.PermContainersStart)}, h.Handler)

func RequireSudo added in v2.8.0 

func RequireSudo(api huma.API) huma.Middlewares

RequireSudo restricts infrastructure-only operations to callers authenticated through the agent-token path. Holding every user-facing permission is not sufficient because these operations may expose materialized secret values.

func SpanEnvironment added in v2.16.0 

func SpanEnvironment(environmentName func(ctx context.Context, id string) string) echo.MiddlewareFunc

SpanEnvironment tags the request span with the routed environment's ID, and with its name once the request succeeds, so unauthenticated or unknown-environment requests never trigger a lookup.

func WarnUntrustedForwardedFor added in v2.17.0 

func WarnUntrustedForwardedFor(trustedProxyNets []*net.IPNet) echo.MiddlewareFunc

Types

type AuthValidator 

type AuthValidator func(ctx context.Context, c *echo.Context) (*authz.PermissionSet, *usertypes.Actor, bool)

AuthValidator authenticates a request and returns the caller's permission set and user (nil for non-user callers). Sudo permission sets (internal agent proxies) bypass authorization.

type CORSMiddleware 

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

func NewCORSMiddleware 

func NewCORSMiddleware(cfg *config.Config) *CORSMiddleware

func (*CORSMiddleware) Add 

func (m *CORSMiddleware) Add() echo.MiddlewareFunc

type CSRFMiddleware 

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

CSRFMiddleware rejects cross-origin state-changing requests to the cookie-backed API. It complements the SameSite=Lax session cookie with server-side origin verification (Sec-Fetch-Site, with an Origin/Host fallback) via the standard library's net/http.CrossOriginProtection.

Header-credentialed requests (Bearer / X-API-Key / agent token) are not CSRF-able — a browser cannot attach those headers to a forged cross-origin request — so they are left untouched, as are non-browser clients that send no Origin header.

func NewCSRFMiddleware 

func NewCSRFMiddleware(cfg *config.Config) *CSRFMiddleware

func (*CSRFMiddleware) Add 

func (m *CSRFMiddleware) Add() echo.MiddlewareFunc

type ContextKey added in v2.8.0 

type ContextKey string

ContextKey is a type for context keys used by Huma handlers.

type EnvResolver 

type EnvResolver func(ctx context.Context, id string) (string, *string, bool, error)

EnvResolver resolves an environment ID to its connection details. Returns: apiURL, accessToken, enabled, error

type EnvironmentMiddleware 

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

EnvironmentMiddleware proxies requests for remote environments to their respective agents.

func (*EnvironmentMiddleware) Handle 

func (m *EnvironmentMiddleware) Handle(c *echo.Context, next echo.HandlerFunc) error

Handle is the main middleware handler.

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.