From 3fa786330e03e57f88e07110efbb244a31b20fa5 Mon Sep 17 00:00:00 2001 From: snowkide Date: Tue, 3 Nov 2026 11:21:39 +0100 Subject: [PATCH 1/3] fix(tracing): redact credential query parameters from http.url The Http.ReceivedRequest span recorded r.URL.String() verbatim, so a secret, token, JWT or SIWE signature passed as ?secret=, ?token=, ?jwt= or ?signature= was exported to the tracing backend. Replace those values with REDACTED; other query parameters and the path are kept as is. Co-Authored-By: Claude Opus 5.5 --- common/tracing_util.go | 37 +++++++++++++++++++++++++++++- common/tracing_util_redact_test.go | 29 +++++++++++++++++++++++ docs/pages/operation/tracing.mdx | 2 +- 3 files changed, 66 insertions(+), 2 deletions(-) create mode 100644 common/tracing_util_redact_test.go diff --git a/common/tracing_util.go b/common/tracing_util.go index 6054c21e0..458e4496d 100644 --- a/common/tracing_util.go +++ b/common/tracing_util.go @@ -4,6 +4,7 @@ import ( "context" "fmt" "net/http" + "net/url" "go.opentelemetry.io/otel/attribute" "go.opentelemetry.io/otel/codes" @@ -64,6 +65,40 @@ func InjectHTTPResponseTraceContext(ctx context.Context, w http.ResponseWriter) propagator.Inject(ctx, propagation.HeaderCarrier(w.Header())) } +// credentialQueryParams are the query parameters the HTTP auth payload +// extractor reads credentials from (see auth.NewPayloadFromHttp). A SIWE +// signature is replayable until its message expires, so it is redacted too; +// the SIWE message itself is kept. +var credentialQueryParams = []string{"token", "secret", "jwt", "signature"} + +// RedactedRequestURL renders u for telemetry with the values of +// credential-carrying query parameters replaced, so secrets passed in the +// URL do not end up in exported spans. +func RedactedRequestURL(u *url.URL) string { + if u == nil { + return "" + } + if u.RawQuery == "" { + return u.String() + } + q := u.Query() + redacted := false + for _, name := range credentialQueryParams { + if vals, ok := q[name]; ok { + for i := range vals { + vals[i] = "REDACTED" + } + redacted = true + } + } + if !redacted { + return u.String() + } + c := *u + c.RawQuery = q.Encode() + return c.String() +} + func StartHTTPServerSpan(ctx context.Context, r *http.Request) (context.Context, trace.Span) { if !IsTracingEnabled { return ctx, trace.SpanFromContext(ctx) @@ -80,7 +115,7 @@ func StartHTTPServerSpan(ctx context.Context, r *http.Request) (context.Context, trace.WithSpanKind(trace.SpanKindServer), trace.WithAttributes( semconv.HTTPMethodKey.String(r.Method), - semconv.HTTPURLKey.String(r.URL.String()), + semconv.HTTPURLKey.String(RedactedRequestURL(r.URL)), semconv.HTTPSchemeKey.String(r.URL.Scheme), semconv.HTTPUserAgentKey.String(r.UserAgent()), ), diff --git a/common/tracing_util_redact_test.go b/common/tracing_util_redact_test.go new file mode 100644 index 000000000..0a0fe54e1 --- /dev/null +++ b/common/tracing_util_redact_test.go @@ -0,0 +1,29 @@ +package common + +import ( + "net/url" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestRedactedRequestURL(t *testing.T) { + cases := map[string]string{ + "/main/evm/1": "/main/evm/1", + "/main/evm/1?foo=bar": "/main/evm/1?foo=bar", + "/main/evm/1?secret=s3cret": "/main/evm/1?secret=REDACTED", + "/main/evm/1?token=t0k&foo=bar": "/main/evm/1?foo=bar&token=REDACTED", + "/main/evm/1?jwt=a.b.c": "/main/evm/1?jwt=REDACTED", + "http://host:4000/main/evm/1?secret=x": "http://host:4000/main/evm/1?secret=REDACTED", + "/main/evm/1?secret=a&secret=b": "/main/evm/1?secret=REDACTED&secret=REDACTED", + "/main/evm/1?signature=0x1&message=abc": "/main/evm/1?message=abc&signature=REDACTED", + "/main/evm/1?foo=bar&baz=1": "/main/evm/1?foo=bar&baz=1", + } + for in, want := range cases { + u, err := url.Parse(in) + require.NoError(t, err) + assert.Equal(t, want, RedactedRequestURL(u), in) + } + assert.Equal(t, "", RedactedRequestURL(nil)) +} diff --git a/docs/pages/operation/tracing.mdx b/docs/pages/operation/tracing.mdx index 5499a3ab4..04e8bf215 100644 --- a/docs/pages/operation/tracing.mdx +++ b/docs/pages/operation/tracing.mdx @@ -423,7 +423,7 @@ are recorded. Use `sampleRate: 0.0000001` because `sampleRate: 0` is rewritten t | Attribute | Phase | Value | |---|---|---| | `http.method` | on request | HTTP method (semconv) | -| `http.url` | on request | Full request URL | +| `http.url` | on request | Full request URL; values of the credential query parameters the auth extractor reads (`secret`, `token`, `jwt`, SIWE `signature`) are replaced with `REDACTED` | | `http.scheme` | on request | URL scheme | | `http.user_agent` | on request | User-Agent header value | | `erpc.force_trace` | on request, when forced | `true` (if forced via header/query) | From d2914ccb549d5214c054129a27daab94f43d65e7 Mon Sep 17 00:00:00 2001 From: snowkide Date: Tue, 3 Nov 2026 12:15:28 +0100 Subject: [PATCH 2/3] feat(auth): add forwardedClientId strategy for gateway-authenticated callers When eRPC runs behind an API gateway or reverse proxy that already authenticates callers, the gateway typically forwards the authenticated client's id in a request header. The new forwardedClientId strategy trusts that header as the user id, so per-client rate-limit budgets, method scoping and the user metric label work without duplicating the gateway's key store in eRPC. The strategy is only active when configured and is offered every HTTP or WebSocket request that carries its header, in declaration order: - header: header name, default X-Client-Id - allowedProxies: only trust the header from these direct TCP peers (the socket address, not the X-Forwarded-For client IP); a startup warning is logged when it is empty - allowedIds: optional allowlist, also bounds user label cardinality - rateLimitBudget: budget attached to the authenticated user A header with several values (a proxy that appends instead of overwriting) is rejected, as are ids that are empty, longer than 256 bytes, or contain whitespace, commas or non-ASCII characters. AuthPayload now carries the request headers and remote address so that strategies can read their own transport inputs. Co-Authored-By: Claude Opus 5.5 --- auth/authorizer.go | 12 ++ auth/http.go | 4 +- auth/payload.go | 13 +- auth/strategy_forwarded_client_id.go | 146 +++++++++++++ auth/strategy_forwarded_client_id_test.go | 200 ++++++++++++++++++ common/config.go | 39 +++- common/defaults.go | 17 ++ common/validation.go | 45 ++++ ...alidation_auth_forwarded_client_id_test.go | 68 ++++++ docs/pages/config/auth.mdx | 69 +++++- erpc/http_server_forwarded_client_id_test.go | 109 ++++++++++ typescript/config/src/generated.ts | 38 ++++ typescript/config/src/index.ts | 1 + typescript/config/src/types/generic.ts | 14 +- 14 files changed, 764 insertions(+), 11 deletions(-) create mode 100644 auth/strategy_forwarded_client_id.go create mode 100644 auth/strategy_forwarded_client_id_test.go create mode 100644 common/validation_auth_forwarded_client_id_test.go create mode 100644 erpc/http_server_forwarded_client_id_test.go diff --git a/auth/authorizer.go b/auth/authorizer.go index 464d2b306..01eed87ba 100644 --- a/auth/authorizer.go +++ b/auth/authorizer.go @@ -63,6 +63,18 @@ func NewAuthorizer(appCtx context.Context, logger *zerolog.Logger, projectId str if err != nil { return nil, err } + case common.AuthTypeForwardedClientId: + if cfg.ForwardedClientId == nil { + return nil, common.NewErrInvalidConfig("forwardedClientId strategy config is nil") + } + strategy, err = NewForwardedClientIdStrategy(cfg.ForwardedClientId) + if err != nil { + return nil, err + } + if len(cfg.ForwardedClientId.AllowedProxies) == 0 { + logger.Warn().Str("projectId", projectId).Str("header", cfg.ForwardedClientId.Header). + Msg("forwardedClientId auth strategy accepts its header from any peer; set allowedProxies to the proxy that sets it") + } default: return nil, common.NewErrInvalidConfig(fmt.Sprintf("unknown auth strategy type: %s", cfg.Type)) } diff --git a/auth/http.go b/auth/http.go index 3b6698662..3f579f4eb 100644 --- a/auth/http.go +++ b/auth/http.go @@ -12,7 +12,9 @@ import ( func NewPayloadFromHttp(method string, remoteAddr string, headers http.Header, args url.Values) (*AuthPayload, error) { ap := &AuthPayload{ - Method: method, + Method: method, + Headers: headers, + RemoteAddr: remoteAddr, } if token := args.Get("token"); token != "" { // deprecated diff --git a/auth/payload.go b/auth/payload.go index 712003534..43bc556d3 100644 --- a/auth/payload.go +++ b/auth/payload.go @@ -1,6 +1,10 @@ package auth -import "github.com/erpc/erpc/common" +import ( + "net/http" + + "github.com/erpc/erpc/common" +) type AuthPayload struct { Method string @@ -8,6 +12,13 @@ type AuthPayload struct { Secret *SecretPayload Jwt *JwtPayload Siwe *SiwePayload + + // Headers and RemoteAddr carry the raw transport context for strategies + // that need it rather than a credential extracted up front (e.g. + // forwardedClientId reads its configured header and checks the direct + // peer). They are only populated for HTTP and WebSocket requests. + Headers http.Header + RemoteAddr string } // This payload is used by both "secret" and "database" strategies diff --git a/auth/strategy_forwarded_client_id.go b/auth/strategy_forwarded_client_id.go new file mode 100644 index 000000000..408358fce --- /dev/null +++ b/auth/strategy_forwarded_client_id.go @@ -0,0 +1,146 @@ +package auth + +import ( + "context" + "fmt" + "net" + "net/http" + "strings" + + "github.com/erpc/erpc/common" +) + +// maxForwardedClientIdLength caps the accepted id length. The id becomes the +// request's user id, which is used in logs, metric labels and rate-limit keys. +const maxForwardedClientIdLength = 256 + +// ForwardedClientIdStrategy authenticates a caller by a client id that a +// trusted reverse proxy / API gateway placed in a request header after +// authenticating the caller itself. eRPC performs no credential check of its +// own, so this strategy must only be enabled behind a proxy that strips or +// overwrites the header on incoming requests (see +// common.ForwardedClientIdStrategyConfig). +type ForwardedClientIdStrategy struct { + cfg *common.ForwardedClientIdStrategyConfig + header string + allowedIds map[string]struct{} + allowedIPs []net.IP + allowedCIDRs []*net.IPNet + restrictToPeer bool +} + +var _ AuthStrategy = &ForwardedClientIdStrategy{} + +func NewForwardedClientIdStrategy(cfg *common.ForwardedClientIdStrategyConfig) (*ForwardedClientIdStrategy, error) { + s := &ForwardedClientIdStrategy{ + cfg: cfg, + header: http.CanonicalHeaderKey(cfg.Header), + } + if s.header == "" { + s.header = common.DefaultForwardedClientIdHeader + } + + if len(cfg.AllowedIds) > 0 { + s.allowedIds = make(map[string]struct{}, len(cfg.AllowedIds)) + for _, id := range cfg.AllowedIds { + s.allowedIds[strings.TrimSpace(id)] = struct{}{} + } + } + + for _, entry := range cfg.AllowedProxies { + if ip := net.ParseIP(entry); ip != nil { + s.allowedIPs = append(s.allowedIPs, ip) + continue + } + _, cidr, err := net.ParseCIDR(entry) + if err != nil { + return nil, fmt.Errorf("invalid allowedProxies entry (must be an IP or CIDR): %s", entry) + } + s.allowedCIDRs = append(s.allowedCIDRs, cidr) + } + s.restrictToPeer = len(s.allowedIPs) > 0 || len(s.allowedCIDRs) > 0 + + return s, nil +} + +// Supports reports whether the configured header is present. It does not +// depend on ap.Type, so a request that also carries another credential (for +// example an API key the proxy already consumed) is still offered to this +// strategy; strategies are tried in configuration order. +func (s *ForwardedClientIdStrategy) Supports(ap *AuthPayload) bool { + if ap == nil || ap.Headers == nil { + return false + } + return len(ap.Headers.Values(s.header)) > 0 +} + +func (s *ForwardedClientIdStrategy) Authenticate(ctx context.Context, req *common.NormalizedRequest, ap *AuthPayload) (*common.User, error) { + if ap == nil || ap.Headers == nil { + return nil, common.NewErrAuthUnauthorized("forwardedClientId", "missing_client_id", "missing client id header") + } + + if s.restrictToPeer && !s.isAllowedPeer(ap.RemoteAddr) { + return nil, common.NewErrAuthUnauthorized("forwardedClientId", "ip_not_allowed", "client id header not accepted from this peer") + } + + // More than one value means the header was appended to rather than + // overwritten somewhere on the way, so a client-supplied copy may be + // first. Refuse instead of guessing which one the proxy set. + values := ap.Headers.Values(s.header) + if len(values) != 1 { + return nil, common.NewErrAuthUnauthorized("forwardedClientId", "multiple_client_ids", "client id header must have exactly one value") + } + id := strings.TrimSpace(values[0]) + if !isValidForwardedClientId(id) { + return nil, common.NewErrAuthUnauthorized("forwardedClientId", "invalid_client_id", "invalid client id") + } + + if s.allowedIds != nil { + if _, ok := s.allowedIds[id]; !ok { + return nil, common.NewErrAuthUnauthorized("forwardedClientId", "client_id_not_allowed", "client id is not allowed") + } + } + + user := &common.User{Id: id} + if s.cfg.RateLimitBudget != "" { + user.RateLimitBudget = s.cfg.RateLimitBudget + } + return user, nil +} + +func (s *ForwardedClientIdStrategy) isAllowedPeer(remoteAddr string) bool { + host := remoteAddr + if h, _, err := net.SplitHostPort(remoteAddr); err == nil { + host = h + } + ip := net.ParseIP(host) + if ip == nil { + return false + } + for _, allowed := range s.allowedIPs { + if allowed.Equal(ip) { + return true + } + } + for _, cidr := range s.allowedCIDRs { + if cidr.Contains(ip) { + return true + } + } + return false +} + +// isValidForwardedClientId accepts non-empty, bounded, visible-ASCII ids +// without commas (a comma suggests several values were joined into one). +func isValidForwardedClientId(id string) bool { + if id == "" || len(id) > maxForwardedClientIdLength { + return false + } + for i := 0; i < len(id); i++ { + c := id[i] + if c < 0x21 || c > 0x7e || c == ',' { + return false + } + } + return true +} diff --git a/auth/strategy_forwarded_client_id_test.go b/auth/strategy_forwarded_client_id_test.go new file mode 100644 index 000000000..566022ee8 --- /dev/null +++ b/auth/strategy_forwarded_client_id_test.go @@ -0,0 +1,200 @@ +package auth + +import ( + "context" + "net/http" + "net/url" + "strings" + "testing" + + "github.com/erpc/erpc/common" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func forwardedPayload(t *testing.T, remoteAddr string, headers http.Header) *AuthPayload { + t.Helper() + ap, err := NewPayloadFromHttp("eth_blockNumber", remoteAddr, headers, url.Values{}) + require.NoError(t, err) + return ap +} + +func newForwardedStrategy(t *testing.T, cfg *common.ForwardedClientIdStrategyConfig) *ForwardedClientIdStrategy { + t.Helper() + require.NoError(t, cfg.SetDefaults()) + require.NoError(t, cfg.Validate()) + s, err := NewForwardedClientIdStrategy(cfg) + require.NoError(t, err) + return s +} + +func TestForwardedClientIdStrategy_DefaultHeader(t *testing.T) { + s := newForwardedStrategy(t, &common.ForwardedClientIdStrategyConfig{RateLimitBudget: "gateway-tier"}) + + h := http.Header{} + h.Set("x-client-id", " client-a ") + ap := forwardedPayload(t, "10.0.0.1:1234", h) + + // No credential was extracted, so the payload keeps the network type, but + // the strategy still supports it because its header is present. + assert.Equal(t, common.AuthTypeNetwork, ap.Type) + require.True(t, s.Supports(ap)) + + user, err := s.Authenticate(context.Background(), nil, ap) + require.NoError(t, err) + assert.Equal(t, "client-a", user.Id) + assert.Equal(t, "gateway-tier", user.RateLimitBudget) +} + +func TestForwardedClientIdStrategy_CustomHeader(t *testing.T) { + s := newForwardedStrategy(t, &common.ForwardedClientIdStrategyConfig{Header: "X-Gateway-Consumer"}) + + h := http.Header{} + h.Set("X-Client-Id", "client-a") + assert.False(t, s.Supports(forwardedPayload(t, "10.0.0.1:1234", h)), "default header must be ignored when another header is configured") + + h = http.Header{} + h.Set("x-gateway-consumer", "client-b") + ap := forwardedPayload(t, "10.0.0.1:1234", h) + require.True(t, s.Supports(ap)) + user, err := s.Authenticate(context.Background(), nil, ap) + require.NoError(t, err) + assert.Equal(t, "client-b", user.Id) +} + +func TestForwardedClientIdStrategy_NotSupportedWithoutHeader(t *testing.T) { + s := newForwardedStrategy(t, &common.ForwardedClientIdStrategyConfig{}) + assert.False(t, s.Supports(forwardedPayload(t, "10.0.0.1:1234", http.Header{}))) + assert.False(t, s.Supports(nil)) + assert.False(t, s.Supports(&AuthPayload{Type: common.AuthTypeNetwork}), "payloads without headers (e.g. gRPC) are not supported") +} + +func TestForwardedClientIdStrategy_RejectsInvalidValues(t *testing.T) { + s := newForwardedStrategy(t, &common.ForwardedClientIdStrategyConfig{}) + + cases := map[string]struct { + values []string + msg string + }{ + "empty": {[]string{""}, "invalid client id"}, + "whitespace only": {[]string{" "}, "invalid client id"}, + "inner space": {[]string{"client a"}, "invalid client id"}, + "comma joined": {[]string{"client-a,client-b"}, "invalid client id"}, + "non ascii": {[]string{"client-é"}, "invalid client id"}, + "too long": {[]string{strings.Repeat("a", maxForwardedClientIdLength+1)}, "invalid client id"}, + "multiple values": {[]string{"client-a", "client-b"}, "exactly one value"}, + } + for name, tc := range cases { + t.Run(name, func(t *testing.T) { + h := http.Header{} + for _, v := range tc.values { + h.Add("X-Client-Id", v) + } + ap := forwardedPayload(t, "10.0.0.1:1234", h) + require.True(t, s.Supports(ap)) + user, err := s.Authenticate(context.Background(), nil, ap) + assert.Nil(t, user) + assertForwardedDenied(t, err, tc.msg) + }) + } +} + +func assertForwardedDenied(t *testing.T, err error, msg string) { + t.Helper() + require.Error(t, err) + var authErr *common.ErrAuthUnauthorized + require.ErrorAs(t, err, &authErr) + assert.Equal(t, "forwardedClientId", authErr.Details["strategy"]) + assert.Contains(t, authErr.Message, msg) +} + +func TestForwardedClientIdStrategy_AllowedIds(t *testing.T) { + s := newForwardedStrategy(t, &common.ForwardedClientIdStrategyConfig{AllowedIds: []string{"client-a"}}) + + h := http.Header{} + h.Set("X-Client-Id", "client-a") + user, err := s.Authenticate(context.Background(), nil, forwardedPayload(t, "10.0.0.1:1234", h)) + require.NoError(t, err) + assert.Equal(t, "client-a", user.Id) + + h.Set("X-Client-Id", "client-b") + _, err = s.Authenticate(context.Background(), nil, forwardedPayload(t, "10.0.0.1:1234", h)) + assertForwardedDenied(t, err, "client id is not allowed") +} + +func TestForwardedClientIdStrategy_AllowedProxies(t *testing.T) { + s := newForwardedStrategy(t, &common.ForwardedClientIdStrategyConfig{ + AllowedProxies: []string{"10.0.0.0/8", "192.168.1.10", "fd00::/8"}, + }) + + h := http.Header{} + h.Set("X-Client-Id", "client-a") + + for _, peer := range []string{"10.1.2.3:4567", "192.168.1.10:80", "[fd00::1]:443"} { + user, err := s.Authenticate(context.Background(), nil, forwardedPayload(t, peer, h)) + require.NoError(t, err, "peer %s", peer) + assert.Equal(t, "client-a", user.Id) + } + for _, peer := range []string{"203.0.113.7:4567", "192.168.1.11:80", "", "not-an-ip"} { + _, err := s.Authenticate(context.Background(), nil, forwardedPayload(t, peer, h)) + assertForwardedDenied(t, err, "not accepted from this peer") + } +} + +func TestNewForwardedClientIdStrategy_InvalidProxy(t *testing.T) { + _, err := NewForwardedClientIdStrategy(&common.ForwardedClientIdStrategyConfig{AllowedProxies: []string{"10.0.0.0/33"}}) + require.Error(t, err) +} + +func TestAuthRegistry_ForwardedClientId(t *testing.T) { + registry := newSecretAuthRegistry(t, &common.AuthConfig{ + Strategies: []*common.AuthStrategyConfig{ + { + Type: common.AuthTypeForwardedClientId, + ForwardedClientId: &common.ForwardedClientIdStrategyConfig{Header: common.DefaultForwardedClientIdHeader}, + }, + { + Type: common.AuthTypeSecret, + Secret: &common.SecretStrategyConfig{Id: "backend", Value: "backend-token"}, + }, + }, + }) + + t.Run("header authenticates and is attached to the request", func(t *testing.T) { + h := http.Header{} + h.Set("X-Client-Id", "client-a") + req := common.NewNormalizedRequest(nil) + user, err := registry.Authenticate(context.Background(), req, "eth_blockNumber", forwardedPayload(t, "10.0.0.1:1234", h)) + require.NoError(t, err) + assert.Equal(t, "client-a", user.Id) + assert.Equal(t, "client-a", req.UserId()) + }) + + t.Run("other strategies still work without the header", func(t *testing.T) { + h := http.Header{} + h.Set("X-ERPC-Secret-Token", "backend-token") + user, err := registry.Authenticate(context.Background(), nil, "eth_blockNumber", forwardedPayload(t, "10.0.0.1:1234", h)) + require.NoError(t, err) + assert.Equal(t, "backend", user.Id) + }) + + t.Run("no header and no credential is rejected", func(t *testing.T) { + _, err := registry.Authenticate(context.Background(), nil, "eth_blockNumber", forwardedPayload(t, "10.0.0.1:1234", http.Header{})) + require.Error(t, err) + }) +} + +func TestAuthRegistry_ForwardedClientIdNotTrustedUnlessConfigured(t *testing.T) { + registry := newSecretAuthRegistry(t, &common.AuthConfig{ + Strategies: []*common.AuthStrategyConfig{ + { + Type: common.AuthTypeSecret, + Secret: &common.SecretStrategyConfig{Id: "backend", Value: "backend-token"}, + }, + }, + }) + h := http.Header{} + h.Set("X-Client-Id", "client-a") + _, err := registry.Authenticate(context.Background(), nil, "eth_blockNumber", forwardedPayload(t, "10.0.0.1:1234", h)) + require.Error(t, err) +} diff --git a/common/config.go b/common/config.go index a8e9ea7f9..cebc54e18 100644 --- a/common/config.go +++ b/common/config.go @@ -3341,11 +3341,12 @@ func (s *SelectionPolicyConfig) UnmarshalYAML(unmarshal func(interface{}) error) type AuthType string const ( - AuthTypeSecret AuthType = "secret" - AuthTypeDatabase AuthType = "database" - AuthTypeJwt AuthType = "jwt" - AuthTypeSiwe AuthType = "siwe" - AuthTypeNetwork AuthType = "network" + AuthTypeSecret AuthType = "secret" + AuthTypeDatabase AuthType = "database" + AuthTypeJwt AuthType = "jwt" + AuthTypeSiwe AuthType = "siwe" + AuthTypeNetwork AuthType = "network" + AuthTypeForwardedClientId AuthType = "forwardedClientId" ) type AuthConfig struct { @@ -3389,6 +3390,8 @@ type AuthStrategyConfig struct { Database *DatabaseStrategyConfig `yaml:"database,omitempty" json:"database,omitempty"` Jwt *JwtStrategyConfig `yaml:"jwt,omitempty" json:"jwt,omitempty"` Siwe *SiweStrategyConfig `yaml:"siwe,omitempty" json:"siwe,omitempty"` + + ForwardedClientId *ForwardedClientIdStrategyConfig `yaml:"forwardedClientId,omitempty" json:"forwardedClientId,omitempty"` } type SecretStrategyConfig struct { @@ -3458,6 +3461,32 @@ type JwtStrategyConfig struct { RateLimitBudgetClaimName string `yaml:"rateLimitBudgetClaimName,omitempty" json:"rateLimitBudgetClaimName,omitempty"` } +// DefaultForwardedClientIdHeader is the request header the forwardedClientId +// auth strategy reads when no header is configured. +const DefaultForwardedClientIdHeader = "X-Client-Id" + +// ForwardedClientIdStrategyConfig authenticates callers by a client id that a +// trusted reverse proxy / API gateway has already authenticated and forwarded +// in a request header. eRPC does not verify any credential itself: anyone who +// can reach eRPC directly and set this header can claim any id. Only enable it +// when every request reaches eRPC through a proxy that strips or overwrites +// the header on incoming client requests, and prefer pinning that proxy with +// AllowedProxies. +type ForwardedClientIdStrategyConfig struct { + // Header is the request header carrying the client id. + // Defaults to "X-Client-Id". + Header string `yaml:"header,omitempty" json:"header,omitempty"` + // AllowedIds, if set, restricts accepted client ids to this list. Any + // other id is rejected. Also bounds the cardinality of the `user` label. + AllowedIds []string `yaml:"allowedIds,omitempty" json:"allowedIds,omitempty"` + // AllowedProxies, if set, only trusts the header when the direct TCP peer + // (not the X-Forwarded-For resolved client IP) matches one of these IPs or + // CIDRs, so callers that bypass the proxy cannot set the header. + AllowedProxies []string `yaml:"allowedProxies,omitempty" json:"allowedProxies,omitempty"` + // RateLimitBudget, if set, is applied to the authenticated user. + RateLimitBudget string `yaml:"rateLimitBudget,omitempty" json:"rateLimitBudget,omitempty"` +} + type SiweStrategyConfig struct { AllowedDomains []string `yaml:"allowedDomains" json:"allowedDomains"` // RateLimitBudget, if set, is applied to the authenticated user diff --git a/common/defaults.go b/common/defaults.go index 35b7334be..b09fe5845 100644 --- a/common/defaults.go +++ b/common/defaults.go @@ -3470,6 +3470,23 @@ func (s *AuthStrategyConfig) SetDefaults() error { } } + if s.Type == AuthTypeForwardedClientId && s.ForwardedClientId == nil { + s.ForwardedClientId = &ForwardedClientIdStrategyConfig{} + } + if s.ForwardedClientId != nil { + s.Type = AuthTypeForwardedClientId + if err := s.ForwardedClientId.SetDefaults(); err != nil { + return fmt.Errorf("failed to set defaults for forwardedClientId strategy: %w", err) + } + } + + return nil +} + +func (s *ForwardedClientIdStrategyConfig) SetDefaults() error { + if s.Header == "" { + s.Header = DefaultForwardedClientIdHeader + } return nil } diff --git a/common/validation.go b/common/validation.go index 84dcf2848..691de2447 100644 --- a/common/validation.go +++ b/common/validation.go @@ -981,6 +981,13 @@ func (s *AuthStrategyConfig) Validate() error { if err := s.Database.Validate(); err != nil { return err } + case AuthTypeForwardedClientId: + if s.ForwardedClientId == nil { + return fmt.Errorf("auth.*.forwardedClientId is required for forwardedClientId strategy") + } + if err := s.ForwardedClientId.Validate(); err != nil { + return err + } default: return fmt.Errorf("auth.*.type '%s' is invalid must be one of: %v", s.Type, []AuthType{ AuthTypeNetwork, @@ -988,6 +995,7 @@ func (s *AuthStrategyConfig) Validate() error { AuthTypeJwt, AuthTypeSiwe, AuthTypeDatabase, + AuthTypeForwardedClientId, }) } return nil @@ -1057,6 +1065,43 @@ func (s *SiweStrategyConfig) Validate() error { return nil } +func (s *ForwardedClientIdStrategyConfig) Validate() error { + if !isValidHeaderName(s.Header) { + return fmt.Errorf("auth.*.forwardedClientId.header '%s' is not a valid HTTP header name", s.Header) + } + for _, id := range s.AllowedIds { + if strings.TrimSpace(id) == "" { + return fmt.Errorf("auth.*.forwardedClientId.allowedIds must not contain empty values") + } + } + for _, entry := range s.AllowedProxies { + if net.ParseIP(entry) != nil { + continue + } + if _, _, err := net.ParseCIDR(entry); err != nil { + return fmt.Errorf("auth.*.forwardedClientId.allowedProxies entry '%s' is not a valid IP or CIDR", entry) + } + } + return nil +} + +// isValidHeaderName reports whether name is a non-empty RFC 7230 token. +func isValidHeaderName(name string) bool { + if name == "" { + return false + } + for i := 0; i < len(name); i++ { + c := name[i] + switch { + case c >= 'a' && c <= 'z', c >= 'A' && c <= 'Z', c >= '0' && c <= '9': + case strings.IndexByte("!#$%&'*+-.^_`|~", c) >= 0: + default: + return false + } + } + return true +} + func (c *CORSConfig) Validate() error { if len(c.AllowedOrigins) == 0 { return fmt.Errorf("*.cors.allowedOrigins is required, add at least one allowed origin") diff --git a/common/validation_auth_forwarded_client_id_test.go b/common/validation_auth_forwarded_client_id_test.go new file mode 100644 index 000000000..ef5aea583 --- /dev/null +++ b/common/validation_auth_forwarded_client_id_test.go @@ -0,0 +1,68 @@ +package common + +import ( + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "gopkg.in/yaml.v3" +) + +func TestForwardedClientIdStrategyConfig_DefaultsFromYaml(t *testing.T) { + var cfg AuthConfig + require.NoError(t, yaml.Unmarshal([]byte(` +strategies: + - type: forwardedClientId + - forwardedClientId: + header: X-Gateway-Consumer + allowedIds: [client-a, client-b] + allowedProxies: [10.0.0.0/8, 192.168.1.10] + rateLimitBudget: gateway-tier +`), &cfg)) + require.Len(t, cfg.Strategies, 2) + + for _, s := range cfg.Strategies { + require.NoError(t, s.SetDefaults()) + require.NoError(t, s.Validate()) + assert.Equal(t, AuthTypeForwardedClientId, s.Type, "type is inferred from the strategy block") + require.NotNil(t, s.ForwardedClientId) + } + + assert.Equal(t, DefaultForwardedClientIdHeader, cfg.Strategies[0].ForwardedClientId.Header) + assert.Equal(t, "X-Gateway-Consumer", cfg.Strategies[1].ForwardedClientId.Header) + assert.Equal(t, []string{"client-a", "client-b"}, cfg.Strategies[1].ForwardedClientId.AllowedIds) + assert.Equal(t, "gateway-tier", cfg.Strategies[1].ForwardedClientId.RateLimitBudget) +} + +func TestForwardedClientIdStrategyConfig_Validate(t *testing.T) { + cases := map[string]struct { + cfg ForwardedClientIdStrategyConfig + wantErr string + }{ + "empty header": {cfg: ForwardedClientIdStrategyConfig{}, wantErr: "forwardedClientId.header"}, + "header with space": {cfg: ForwardedClientIdStrategyConfig{Header: "X Client"}, wantErr: "forwardedClientId.header"}, + "header with colon": {cfg: ForwardedClientIdStrategyConfig{Header: "X-Client:"}, wantErr: "forwardedClientId.header"}, + "empty allowed id": {cfg: ForwardedClientIdStrategyConfig{Header: "X-Client-Id", AllowedIds: []string{"client-a", " "}}, wantErr: "allowedIds"}, + "invalid proxy": {cfg: ForwardedClientIdStrategyConfig{Header: "X-Client-Id", AllowedProxies: []string{"10.0.0.0/33"}}, wantErr: "allowedProxies"}, + "hostname as proxy": {cfg: ForwardedClientIdStrategyConfig{Header: "X-Client-Id", AllowedProxies: []string{"proxy.local"}}, wantErr: "allowedProxies"}, + "valid ip and cidr": {cfg: ForwardedClientIdStrategyConfig{Header: "X-Client-Id", AllowedProxies: []string{"10.0.0.1", "fd00::/8"}}}, + "valid default style": {cfg: ForwardedClientIdStrategyConfig{Header: "x-client-id"}}, + } + for name, tc := range cases { + t.Run(name, func(t *testing.T) { + err := tc.cfg.Validate() + if tc.wantErr == "" { + require.NoError(t, err) + return + } + require.Error(t, err) + assert.Contains(t, err.Error(), tc.wantErr) + }) + } +} + +func TestAuthStrategyConfig_Validate_ForwardedClientIdRequiresBlock(t *testing.T) { + err := (&AuthStrategyConfig{Type: AuthTypeForwardedClientId}).Validate() + require.Error(t, err) + assert.Contains(t, err.Error(), "auth.*.forwardedClientId is required") +} diff --git a/docs/pages/config/auth.mdx b/docs/pages/config/auth.mdx index 4cca37fa8..9a731db9c 100644 --- a/docs/pages/config/auth.mdx +++ b/docs/pages/config/auth.mdx @@ -119,6 +119,8 @@ For each HTTP request, eRPC extracts credential signals from query params and he 8. `X-Siwe-Message` + `X-Siwe-Signature` headers → `AuthTypeSiwe` 9. No credential present → `AuthTypeNetwork` (fallback) +The `forwardedClientId` strategy does not take part in this order: it is offered every request that carries its configured header (whatever credential type was extracted), in declaration order like any other strategy. + gRPC metadata uses a parallel order without query-param equivalents: `x-erpc-secret-token`, then `authorization: Basic`, `authorization: Bearer`, then `x-siwe-message`+`x-siwe-signature`, then network fallback. gRPC has no `?token=` / `?secret=` / `?jwt=` equivalents — query params are not available in gRPC metadata. **Method filtering.** Every strategy accepts `ignoreMethods` and `allowMethods` wildcard lists. `ignoreMethods` is evaluated first; `allowMethods` overrides it. The canonical pattern for restricting a strategy to one method is `ignoreMethods: ["*"]` plus `allowMethods: ["eth_getLogs"]`. @@ -153,6 +155,19 @@ Authorizes requests by client IP address against an allowlist of exact IPs and C Authenticate: reads `req.ClientIP()` (proxy-resolved by HTTP ingress). Checks localhost → exact IP list → CIDR list. First match wins. `ipAsUser=false` (default): all IPs in a CIDR range share one identity (`cidr.String()`). `ipAsUser=true`: each IP gets its own identity (`clientIP.String()`). +#### forwardedClientId strategy + +For deployments where eRPC sits behind an API gateway or reverse proxy that already authenticates callers (API keys, OAuth, mTLS, …) and forwards the authenticated client's id in a request header. eRPC trusts that header as the `User.Id` without verifying any credential itself, so per-client rate-limit budgets, `allowMethods`/`ignoreMethods` scoping and the `user` metric label all work without duplicating the gateway's key store in eRPC. + +**Security model.** Anyone who can reach eRPC directly and set the header can claim any id. Only enable this strategy when every request reaches eRPC through a proxy that **strips or overwrites** the header on incoming client requests, and keep eRPC itself off the public network. Defense in depth: +- `allowedProxies` — only trust the header when the direct TCP peer (the socket's remote address, not the `X-Forwarded-For`-resolved client IP) is one of these IPs/CIDRs. It is independent of `server.trustedIPForwarders`, which only decides how the client IP is resolved. +- `allowedIds` — reject any id not in the list; also bounds the cardinality of the `user` label. +- A header with more than one value is rejected (the proxy appended instead of overwriting, so a client-supplied copy might come first). Ids must be 1–256 visible ASCII characters without commas. + +Supports: any HTTP or WebSocket request carrying the configured header (WebSocket uses the upgrade request's headers). gRPC is not supported. The strategy is never active unless it is configured — a request carrying the header against a project without this strategy is unaffected. + +Compared to the project-level `trustUserIdHeader` (identity for metrics/logs only, never authenticates), `forwardedClientId` **authenticates**: the request is admitted because the header is present, and the strategy's `rateLimitBudget`/`allowClientDirectives` apply. + #### database strategy Looks up an API key against a connector-backed store (PostgreSQL, DynamoDB, Redis, memory, or gRPC). Includes an in-process Ristretto positive cache (default 1h TTL), a hardcoded 5-second negative cache for invalid/disabled keys, singleflight deduplication for concurrent misses, configurable retry/backoff, and a connector-down circuit-breaker with optional fail-open. @@ -195,7 +210,7 @@ Authenticate fast paths (in evaluation order): | Field | Type | Default | Notes | |---|---|---|---| -| `strategies[*].type` | `string` | Inferred from sub-config block | `"secret"`, `"jwt"`, `"siwe"`, `"network"`, `"database"`. Block presence force-overwrites `type` for secret/database/jwt/siwe. For network, only `type: "network"` triggers auto-creation; the network block does not overwrite type. | +| `strategies[*].type` | `string` | Inferred from sub-config block | `"secret"`, `"jwt"`, `"siwe"`, `"network"`, `"database"`, `"forwardedClientId"`. Block presence force-overwrites `type` for secret/database/jwt/siwe/forwardedClientId. For network, only `type: "network"` triggers auto-creation; the network block does not overwrite type. | | `strategies[*].ignoreMethods` | `[]string` | `nil` | Wildcard patterns (supports `*`, `\|`, `&`, `!`). Applied before `allowMethods`. | | `strategies[*].allowMethods` | `[]string` | `nil` | Overrides `ignoreMethods`; any matching allow re-enables the strategy for that method. | | `strategies[*].rateLimitBudget` | `string` | `""` | Strategy-level budget ID. Overridden by per-user budget when non-empty. | @@ -242,6 +257,19 @@ YAML prefix: `auth.strategies[*].siwe` Supports: `AuthTypeSiwe` only. `SetDefaults`: no-op. +**`forwardedClientId` strategy — `ForwardedClientIdStrategyConfig`** + +YAML prefix: `auth.strategies[*].forwardedClientId` + +| Field | Type | Default | Notes | +|---|---|---|---| +| `forwardedClientId.header` | `string` | `"X-Client-Id"` | Request header carrying the client id (case-insensitive). Must be a valid header name. Its trimmed value becomes `User.Id`. | +| `forwardedClientId.allowedIds` | `[]string` | `nil` (any id) | If set, ids outside the list are rejected with `ErrAuthUnauthorized`. | +| `forwardedClientId.allowedProxies` | `[]string` | `nil` (any peer) | IPs/CIDRs of the proxy allowed to set the header, matched against the direct TCP peer address. Invalid entries fail startup validation. | +| `forwardedClientId.rateLimitBudget` | `string` | `""` | Attached to `User.RateLimitBudget` if non-empty. Combine with a `perUser` rule to give every forwarded client its own quota. | + +Supports: any payload carrying the configured header (independent of the extracted credential type). `SetDefaults`: sets `header = "X-Client-Id"` if empty; `type: forwardedClientId` auto-creates the block and the block forces `type`. + **`network` strategy — `NetworkStrategyConfig`** YAML prefix: `auth.strategies[*].network` @@ -579,6 +607,40 @@ they naturally expire. Always set `allowedAlgorithms` to prevent algorithm-confu }`} /> +**6. Behind an API gateway that authenticates callers and forwards their id.** The gateway +validates the caller's API key, strips any client-supplied `X-Client-Id`, and sets it to the +authenticated consumer's name. eRPC trusts it only from the gateway's address range and gives +each forwarded client its own quota via a `perUser` budget rule: + + + ### Request/response behavior - A successful auth attaches `User{Id, RateLimitBudget}` to the request; `User.Id` flows into log context and Prometheus labels on every downstream metric. [] @@ -598,6 +660,7 @@ they naturally expire. Always set `allowedAlgorithms` to prevent algorithm-confu - **Never set `rateLimitBudget` on a `healthCheck.auth` strategy** — the healthcheck auth registry is created with a nil rate-limiter registry; reaching the budget-acquisition path causes a nil pointer panic. - **Enable `failOpen` with a capped emergency budget on `database`** — a DB outage should not make your RPC endpoint unreachable; the circuit-breaker bounds probe load to ~1 query/second per replica. - **DynamoDB `lockRetryInterval` defaults to `0`** — zero means busy-spin retries during lock contention; set to `100ms` or higher in production to avoid rapid API calls and unexpected cost. +- **Pin `forwardedClientId` to the proxy with `allowedProxies`** — the header is a claim, not a credential; make sure only the proxy that strips/overwrites it can deliver it, and consider `allowedIds` to bound the `user` label cardinality. - **Use `secret` only for private, server-side callers** — the plain string comparison is not timing-safe; for browser-reachable endpoints, prefer `jwt` or `database`. ### Edge cases & gotchas @@ -612,7 +675,7 @@ they naturally expire. Always set `allowedAlgorithms` to prevent algorithm-confu 8. **secret uses non-constant-time comparison.** Plain `!=` is timing-side-channel vulnerable for public internet exposures. 9. **Database negative cache TTL is hardcoded at 5 seconds.** Not configurable. Re-enabled keys are rejected for up to 5 seconds. 10. **Connector-down probe is per-process.** One probe/second per replica, no cross-replica coordination. -11. **type inference conflict.** Setting multiple sub-config blocks (e.g. both `secret:` and `jwt:`) in one strategy entry causes the last-evaluated block to silently overwrite `type`. Evaluation order: `secret → database → jwt → siwe`. Never set multiple sub-config blocks in one strategy entry. +11. **type inference conflict.** Setting multiple sub-config blocks (e.g. both `secret:` and `jwt:`) in one strategy entry causes the last-evaluated block to silently overwrite `type`. Evaluation order: `secret → database → jwt → siwe → forwardedClientId`. Never set multiple sub-config blocks in one strategy entry. 12. **`Authorization: Basic` username is silently discarded.** Only the password field is used as the secret value. `alice:mysecret` and `bob:mysecret` are treated identically. 13. **JWT requires keys.** Configure `verificationKeys` and/or `verificationJwksUrl`. With neither, startup validation fails. An empty resolved key map rejects every JWT (deny-all, not allow-all). 14. **SIWE requires both signature and message together.** Missing either one causes silent fallthrough to network-strategy payload extraction. @@ -631,6 +694,7 @@ they naturally expire. Always set `allowedAlgorithms` to prevent algorithm-confu 27. **JWT `jwt.Parse` failures are classified into closed reasons.** Bad signatures → `invalid_signature`; expired → `token_expired`. If both bits are set, signature wins. Other `ValidationError` flags use `invalid_token` and keep jwt library text as the message. [] 28. **`erpc_auth_failed_total` increments when an `ErrAuthUnauthorized` is returned to the client** (`processErrorBody` / gRPC status mapping via `RecordAuthFailed`). Strategies stamp a closed `Details.reason` via `NewErrAuthUnauthorized`; intermediate strategy rejects on a request that later succeeds are not counted. When multiple strategies reject the same payload, the registry join keeps `strategy`/`reason` if every attempt agrees; if any attempt is `token_expired`, that wins (multi-JWT setups often pair matching-key expiry with other-key `invalid_signature`); other divergent attempts fall back to `n/a`/`unauthorized` while the joined message still lists each failure. `agent_name` is always `"unknown"`; `project`/`network` are `"n/a"` unless a resolved network is already on the request. [, ] +29. **`forwardedClientId` trusts a header.** It authenticates whoever can set the header. A proxy that *appends* to the header rather than overwriting it yields two values, which the strategy rejects; a proxy that passes a client-supplied header through untouched is a full auth bypass. The id is used verbatim in logs, metric labels and `perUser` rate-limit keys. A strategy without `allowedProxies` logs a `warn` at startup (`forwardedClientId auth strategy accepts its header from any peer; ...`). [] ### Observability @@ -666,6 +730,7 @@ No dedicated auth trace spans — auth runs inline inside the HTTP handler gorou - [`auth/strategy_database.go:L271-L357`](https://github.com/erpc/erpc/blob/main/auth/strategy_database.go#L271-L357) — connector-down circuit-breaker, probe election, fail-open - [`auth/strategy_jwt.go:L100-L116`](https://github.com/erpc/erpc/blob/main/auth/strategy_jwt.go#L100-L116) — JWT key selection (kid lookup + type-compatibility scan) - [`auth/strategy_siwe.go:L22-L67`](https://github.com/erpc/erpc/blob/main/auth/strategy_siwe.go#L22-L67) — SIWE signature verification + domain allowlist +- [`auth/strategy_forwarded_client_id.go`](https://github.com/erpc/erpc/blob/main/auth/strategy_forwarded_client_id.go) — ForwardedClientIdStrategy: header lookup, proxy pinning, id validation, `allowedIds` - [`auth/strategy_network.go:L47-L93`](https://github.com/erpc/erpc/blob/main/auth/strategy_network.go#L47-L93) — NetworkStrategy: localhost/IP/CIDR checks, `ipAsUser` mode - [`common/config.go:L2433-L2534`](https://github.com/erpc/erpc/blob/main/common/config.go#L2433-L2534) — all auth config type declarations - [`common/defaults.go:L2611-L2761`](https://github.com/erpc/erpc/blob/main/common/defaults.go#L2611-L2761) — SetDefaults for all auth types diff --git a/erpc/http_server_forwarded_client_id_test.go b/erpc/http_server_forwarded_client_id_test.go new file mode 100644 index 000000000..65617f3e2 --- /dev/null +++ b/erpc/http_server_forwarded_client_id_test.go @@ -0,0 +1,109 @@ +package erpc + +import ( + "encoding/json" + "fmt" + "io" + "net/http" + "strings" + "testing" + + "github.com/erpc/erpc/common" + "github.com/erpc/erpc/util" + "github.com/gorilla/websocket" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +const forwardedGetBalance = `{"jsonrpc":"2.0","id":1,"method":"eth_getBalance","params":["0x0000000000000000000000000000000000000001","latest"]}` + +func forwardedClientIdConfig(fc *common.ForwardedClientIdStrategyConfig) *common.Config { + cfg := httpOnlyConfig() + cfg.Projects[0].Auth = &common.AuthConfig{Strategies: []*common.AuthStrategyConfig{{ + Type: common.AuthTypeForwardedClientId, + ForwardedClientId: fc, + }}} + return cfg +} + +func postForwarded(t *testing.T, addr string, headers map[string]string) (int, map[string]interface{}) { + t.Helper() + req, err := http.NewRequest(http.MethodPost, fmt.Sprintf("http://%s/test_ws/evm/123", addr), strings.NewReader(forwardedGetBalance)) + require.NoError(t, err) + req.Header.Set("Content-Type", "application/json") + for k, v := range headers { + req.Header.Set(k, v) + } + resp, err := http.DefaultClient.Do(req) + require.NoError(t, err) + defer resp.Body.Close() + body, err := io.ReadAll(resp.Body) + require.NoError(t, err) + var out map[string]interface{} + require.NoError(t, json.Unmarshal(body, &out), "body: %s", body) + return resp.StatusCode, out +} + +func TestForwardedClientIdAuth_Http(t *testing.T) { + setupGock() + defer util.ResetGock() + + addr, cleanup := setupTestERPCServer(t, forwardedClientIdConfig(&common.ForwardedClientIdStrategyConfig{ + AllowedProxies: []string{"127.0.0.0/8", "::1"}, + AllowedIds: []string{"client-a"}, + })) + defer cleanup() + + status, out := postForwarded(t, addr, map[string]string{"X-Client-Id": "client-a"}) + assert.Equal(t, http.StatusOK, status) + assert.Equal(t, "0xabc123", out["result"]) + + status, out = postForwarded(t, addr, nil) + assert.Equal(t, http.StatusUnauthorized, status, "a request without the header must be rejected: %v", out) + + status, out = postForwarded(t, addr, map[string]string{"X-Client-Id": "client-b"}) + assert.Equal(t, http.StatusUnauthorized, status, "an id outside allowedIds must be rejected: %v", out) +} + +func TestForwardedClientIdAuth_UntrustedPeerRejected(t *testing.T) { + setupGock() + defer util.ResetGock() + + // The test client connects over loopback, which is not an allowed proxy. + addr, cleanup := setupTestERPCServer(t, forwardedClientIdConfig(&common.ForwardedClientIdStrategyConfig{ + AllowedProxies: []string{"10.0.0.0/8"}, + })) + defer cleanup() + + status, out := postForwarded(t, addr, map[string]string{"X-Client-Id": "client-a"}) + assert.Equal(t, http.StatusUnauthorized, status, "%v", out) + + // X-Forwarded-For must not be able to impersonate the proxy: the check + // uses the direct TCP peer. + status, out = postForwarded(t, addr, map[string]string{"X-Client-Id": "client-a", "X-Forwarded-For": "10.1.2.3"}) + assert.Equal(t, http.StatusUnauthorized, status, "%v", out) +} + +func TestForwardedClientIdAuth_WebSocket(t *testing.T) { + setupGock() + defer util.ResetGock() + + addr, cleanup := setupTestERPCServer(t, forwardedClientIdConfig(&common.ForwardedClientIdStrategyConfig{ + Header: "X-Gateway-Consumer", + })) + defer cleanup() + + wsURL := fmt.Sprintf("ws://%s/test_ws/evm/123", addr) + + _, resp, err := websocket.DefaultDialer.Dial(wsURL, nil) + require.Error(t, err, "an upgrade without the header must be refused") + require.NotNil(t, resp) + assert.Equal(t, http.StatusUnauthorized, resp.StatusCode) + + conn, _, err := websocket.DefaultDialer.Dial(wsURL, http.Header{"X-Gateway-Consumer": []string{"client-a"}}) + require.NoError(t, err) + defer conn.Close() + + out := sendAndReceive(t, conn, forwardedGetBalance) + assert.Equal(t, "0xabc123", out["result"]) +} diff --git a/typescript/config/src/generated.ts b/typescript/config/src/generated.ts index 35b6f05c9..31cabbc63 100644 --- a/typescript/config/src/generated.ts +++ b/typescript/config/src/generated.ts @@ -2124,6 +2124,7 @@ export const AuthTypeDatabase: AuthType = "database"; export const AuthTypeJwt: AuthType = "jwt"; export const AuthTypeSiwe: AuthType = "siwe"; export const AuthTypeNetwork: AuthType = "network"; +export const AuthTypeForwardedClientId: AuthType = "forwardedClientId"; export interface AuthConfig { strategies: TsAuthStrategyConfig[]; } @@ -2163,6 +2164,7 @@ export interface AuthStrategyConfig { database?: DatabaseStrategyConfig; jwt?: JwtStrategyConfig; siwe?: SiweStrategyConfig; + forwardedClientId?: ForwardedClientIdStrategyConfig; } export interface SecretStrategyConfig { id: string; @@ -2215,6 +2217,42 @@ export interface JwtStrategyConfig { */ rateLimitBudgetClaimName?: string; } +/** + * DefaultForwardedClientIdHeader is the request header the forwardedClientId + * auth strategy reads when no header is configured. + */ +export const DefaultForwardedClientIdHeader = "X-Client-Id"; +/** + * ForwardedClientIdStrategyConfig authenticates callers by a client id that a + * trusted reverse proxy / API gateway has already authenticated and forwarded + * in a request header. eRPC does not verify any credential itself: anyone who + * can reach eRPC directly and set this header can claim any id. Only enable it + * when every request reaches eRPC through a proxy that strips or overwrites + * the header on incoming client requests, and prefer pinning that proxy with + * AllowedProxies. + */ +export interface ForwardedClientIdStrategyConfig { + /** + * Header is the request header carrying the client id. + * Defaults to "X-Client-Id". + */ + header?: string; + /** + * AllowedIds, if set, restricts accepted client ids to this list. Any + * other id is rejected. Also bounds the cardinality of the `user` label. + */ + allowedIds?: string[]; + /** + * AllowedProxies, if set, only trusts the header when the direct TCP peer + * (not the X-Forwarded-For resolved client IP) matches one of these IPs or + * CIDRs, so callers that bypass the proxy cannot set the header. + */ + allowedProxies?: string[]; + /** + * RateLimitBudget, if set, is applied to the authenticated user. + */ + rateLimitBudget?: string; +} export interface SiweStrategyConfig { allowedDomains: string[]; /** diff --git a/typescript/config/src/index.ts b/typescript/config/src/index.ts index 0c7da1a48..7497cd36a 100644 --- a/typescript/config/src/index.ts +++ b/typescript/config/src/index.ts @@ -71,6 +71,7 @@ export { AuthTypeJwt, AuthTypeSiwe, AuthTypeNetwork, + AuthTypeForwardedClientId, // Consensus related ConsensusLowParticipantsBehaviorReturnError, ConsensusLowParticipantsBehaviorAcceptMostCommonValidResult, diff --git a/typescript/config/src/types/generic.ts b/typescript/config/src/types/generic.ts index 6d2cb4c9a..dec665cdb 100644 --- a/typescript/config/src/types/generic.ts +++ b/typescript/config/src/types/generic.ts @@ -1,6 +1,7 @@ import type { DynamoDBConnectorConfig, EvmNetworkConfig, + ForwardedClientIdStrategyConfig, SvmNetworkConfig, AuthStrategyConfig as GenAuthStrategyConfig, JwtStrategyConfig, @@ -115,14 +116,19 @@ import type { /** * Supported auth type */ - export type AuthType = "secret" | "jwt" | "siwe" | "network"; + export type AuthType = + | "secret" + | "jwt" + | "siwe" + | "network" + | "forwardedClientId"; /** * Connector config depending on the upstream type */ export type AuthStrategyConfig = Omit< GenAuthStrategyConfig, - "type" | "network" | "secret" | "jwt" | "siwe" + "type" | "network" | "secret" | "jwt" | "siwe" | "forwardedClientId" > & ( | { @@ -141,6 +147,10 @@ import type { type: "siwe"; secret: SiweStrategyConfig; } + | { + type: "forwardedClientId"; + forwardedClientId?: ForwardedClientIdStrategyConfig; + } ); /** From 52914954486e5521ba87b58b0fa15ad099a446f4 Mon Sep 17 00:00:00 2001 From: snowkide Date: Tue, 3 Nov 2026 12:16:58 +0100 Subject: [PATCH 3/3] feat(auth): opt-in apikey query/header and URL path secret locations Many clients and gateways send an API key as ?apikey=, an X-Api-Key or apikey header, or (wallets and SDKs that only accept a single RPC URL) as the URL path itself. The secret and database strategies gain additionalLocations, empty by default, to also accept the secret from: - apikeyQuery: the ?apikey= query parameter - apikeyHeader: the X-Api-Key or apikey header - path: the URL path as a single segment (https://host/), only on a domain alias that preselects project, architecture and chain so the path is not used for routing; /admin, /healthcheck and /metrics are never treated as secrets These locations are consulted only when none of the standard ones supplied a secret, and never change the extracted credential type, so a request carrying only one of them still reaches a network strategy as before. A strategy ignores a secret from a location it does not list; unknown location names fail validation. A path is only read as a secret when the auth config serving the request (the project's, or healthCheck.auth for GET healthchecks) lists path. Such a path is replaced with /REDACTED in the http.url span attribute and the CORS metrics' path label, and ?apikey= values are redacted from http.url like ?secret=. Co-Authored-By: Claude Opus 5.5 --- auth/http.go | 58 ++++- auth/http_payload_test.go | 4 +- auth/http_secret_locations_test.go | 200 ++++++++++++++++++ auth/payload.go | 20 ++ auth/strategy_database.go | 2 +- auth/strategy_forwarded_client_id_test.go | 2 +- auth/strategy_secret.go | 5 +- common/config.go | 53 ++++- common/tracing_util.go | 18 +- common/tracing_util_redact_test.go | 1 + common/validation.go | 17 +- .../validation_auth_secret_locations_test.go | 33 +++ docs/pages/config/auth.mdx | 62 +++++- docs/pages/operation/tracing.mdx | 2 +- erpc/healthcheck.go | 3 +- erpc/healthcheck_test.go | 2 +- erpc/http_server.go | 56 ++++- erpc/http_server_path_secret_test.go | 159 ++++++++++++++ erpc/http_server_test.go | 2 +- erpc/ws_server.go | 35 +-- typescript/config/src/generated.ts | 29 +++ 21 files changed, 719 insertions(+), 44 deletions(-) create mode 100644 auth/http_secret_locations_test.go create mode 100644 common/validation_auth_secret_locations_test.go create mode 100644 erpc/http_server_path_secret_test.go diff --git a/auth/http.go b/auth/http.go index 3f579f4eb..791f737c3 100644 --- a/auth/http.go +++ b/auth/http.go @@ -5,12 +5,17 @@ import ( "errors" "net/http" "net/url" + "path" "strings" "github.com/erpc/erpc/common" ) -func NewPayloadFromHttp(method string, remoteAddr string, headers http.Header, args url.Values) (*AuthPayload, error) { +// NewPayloadFromHttp extracts auth signals from an HTTP (or WebSocket +// upgrade) request. credentialPath is the request path when the server does +// not use it for routing (a domain alias preselects project, architecture and +// chain), and "" otherwise; see PathSegmentSecret. +func NewPayloadFromHttp(method string, remoteAddr string, headers http.Header, args url.Values, credentialPath string) (*AuthPayload, error) { ap := &AuthPayload{ Method: method, Headers: headers, @@ -81,6 +86,23 @@ func NewPayloadFromHttp(method string, remoteAddr string, headers http.Header, a } } + // Secondary secret locations, for clients and gateways that use the + // common "API key" conventions. They fill ap.Secret only when no other + // secret was found and never change ap.Type, so they do not alter which + // strategies a request without one of the credentials above reaches: + // a request that only carries an X-Api-Key header still reaches a + // network strategy, and only secret/database strategies that list the + // location in additionalLocations pick the key up. + if ap.Secret == nil { + if apikey := args.Get("apikey"); apikey != "" { + ap.Secret = &SecretPayload{Value: apikey, Location: common.SecretLocationApikeyQuery} + } else if apikey := firstNonEmptyHeader(headers, "X-Api-Key", "Apikey"); apikey != "" { + ap.Secret = &SecretPayload{Value: apikey, Location: common.SecretLocationApikeyHeader} + } else if pathSecret := PathSegmentSecret(credentialPath); pathSecret != "" { + ap.Secret = &SecretPayload{Value: pathSecret, Location: common.SecretLocationPath} + } + } + // Default to network strategy when no other auth signals are present. if ap.Type == "" { ap.Type = common.AuthTypeNetwork @@ -89,6 +111,40 @@ func NewPayloadFromHttp(method string, remoteAddr string, headers http.Header, a return ap, nil } +// reservedPathSegments are single-segment paths eRPC serves itself; they are +// never treated as a secret. +var reservedPathSegments = map[string]struct{}{ + "admin": {}, + "healthcheck": {}, + "metrics": {}, +} + +// PathSegmentSecret returns the secret carried as the only path segment of +// requestPath ("/" or "//"), or "" when the path is empty, +// "/", has several segments, or is a reserved endpoint. +func PathSegmentSecret(requestPath string) string { + if requestPath == "" { + return "" + } + seg := strings.TrimPrefix(path.Clean("/"+requestPath), "/") + if seg == "" || strings.Contains(seg, "/") { + return "" + } + if _, reserved := reservedPathSegments[seg]; reserved { + return "" + } + return seg +} + +func firstNonEmptyHeader(headers http.Header, names ...string) string { + for _, name := range names { + if v := strings.TrimSpace(headers.Get(name)); v != "" { + return v + } + } + return "" +} + func normalizeSiweMessage(msg string) string { decoded, err := base64.StdEncoding.DecodeString(msg) if err != nil { diff --git a/auth/http_payload_test.go b/auth/http_payload_test.go index 04864f52b..9dd7a9a62 100644 --- a/auth/http_payload_test.go +++ b/auth/http_payload_test.go @@ -131,7 +131,7 @@ func TestNewPayloadFromHttp_SignalPrecedence(t *testing.T) { if args == nil { args = url.Values{} } - ap, err := NewPayloadFromHttp("eth_call", "10.0.0.1:1234", headers, args) + ap, err := NewPayloadFromHttp("eth_call", "10.0.0.1:1234", headers, args, "") require.NoError(t, err) assert.Equal(t, "eth_call", ap.Method) assert.Equal(t, tc.wantType, ap.Type) @@ -169,7 +169,7 @@ func TestNewPayloadFromHttp_MalformedBasicAuth(t *testing.T) { } for _, tc := range tests { t.Run(tc.name, func(t *testing.T) { - ap, err := NewPayloadFromHttp("eth_call", "", http.Header{"Authorization": {tc.value}}, url.Values{}) + ap, err := NewPayloadFromHttp("eth_call", "", http.Header{"Authorization": {tc.value}}, url.Values{}, "") require.Error(t, err) assert.Nil(t, ap) }) diff --git a/auth/http_secret_locations_test.go b/auth/http_secret_locations_test.go new file mode 100644 index 000000000..dd41c9f58 --- /dev/null +++ b/auth/http_secret_locations_test.go @@ -0,0 +1,200 @@ +package auth + +import ( + "context" + "net/http" + "net/url" + "testing" + + "github.com/erpc/erpc/common" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestPathSegmentSecret(t *testing.T) { + cases := map[string]string{ + "": "", + "/": "", + "/my-secret-key": "my-secret-key", + "/my-secret-key/": "my-secret-key", + "my-secret-key": "my-secret-key", + "/main/evm/1": "", + "/main/evm": "", + "/a/../b": "b", + "/a/..": "", + "/admin": "", + "/healthcheck": "", + "/metrics": "", + "/admin/": "", + } + for in, want := range cases { + assert.Equal(t, want, PathSegmentSecret(in), "path %q", in) + } +} + +func TestNewPayloadFromHttp_SecondarySecretLocations(t *testing.T) { + t.Run("apikey query", func(t *testing.T) { + ap, err := NewPayloadFromHttp("eth_blockNumber", "", http.Header{}, url.Values{"apikey": {"q-key"}}, "") + require.NoError(t, err) + require.NotNil(t, ap.Secret) + assert.Equal(t, "q-key", ap.Secret.Value) + assert.Equal(t, common.AuthTypeNetwork, ap.Type, "secondary locations must not change the payload type") + }) + + for _, name := range []string{"X-Api-Key", "x-api-key", "apikey"} { + t.Run("header "+name, func(t *testing.T) { + h := http.Header{} + h.Set(name, "h-key") + ap, err := NewPayloadFromHttp("eth_blockNumber", "", h, url.Values{}, "") + require.NoError(t, err) + require.NotNil(t, ap.Secret) + assert.Equal(t, "h-key", ap.Secret.Value) + assert.Equal(t, common.AuthTypeNetwork, ap.Type) + }) + } + + t.Run("path segment", func(t *testing.T) { + ap, err := NewPayloadFromHttp("eth_blockNumber", "", http.Header{}, url.Values{}, "/my-secret-key") + require.NoError(t, err) + require.NotNil(t, ap.Secret) + assert.Equal(t, "my-secret-key", ap.Secret.Value) + assert.Equal(t, common.AuthTypeNetwork, ap.Type) + }) + + t.Run("multi-segment and reserved paths are ignored", func(t *testing.T) { + for _, p := range []string{"/main/evm/1", "/admin", "/healthcheck", "/metrics", "/"} { + ap, err := NewPayloadFromHttp("eth_blockNumber", "", http.Header{}, url.Values{}, p) + require.NoError(t, err) + assert.Nil(t, ap.Secret, "path %s", p) + assert.Equal(t, common.AuthTypeNetwork, ap.Type, "path %s", p) + } + }) + + t.Run("precedence: primary locations win, then query, header, path", func(t *testing.T) { + h := http.Header{} + h.Set("X-Api-Key", "h-key") + h.Set("X-ERPC-Secret-Token", "primary") + ap, err := NewPayloadFromHttp("eth_blockNumber", "", h, url.Values{"apikey": {"q-key"}}, "/path-key") + require.NoError(t, err) + assert.Equal(t, "primary", ap.Secret.Value) + assert.Equal(t, common.AuthTypeSecret, ap.Type) + + h.Del("X-ERPC-Secret-Token") + ap, err = NewPayloadFromHttp("eth_blockNumber", "", h, url.Values{"apikey": {"q-key"}}, "/path-key") + require.NoError(t, err) + assert.Equal(t, "q-key", ap.Secret.Value) + + ap, err = NewPayloadFromHttp("eth_blockNumber", "", h, url.Values{}, "/path-key") + require.NoError(t, err) + assert.Equal(t, "h-key", ap.Secret.Value) + }) + + t.Run("a bearer token keeps the jwt type and the api key is still available", func(t *testing.T) { + h := http.Header{} + h.Set("Authorization", "Bearer a.b.c") + h.Set("X-Api-Key", "h-key") + ap, err := NewPayloadFromHttp("eth_blockNumber", "", h, url.Values{}, "") + require.NoError(t, err) + assert.Equal(t, common.AuthTypeJwt, ap.Type) + require.NotNil(t, ap.Jwt) + require.NotNil(t, ap.Secret) + assert.Equal(t, "h-key", ap.Secret.Value) + }) +} + +func TestAuthRegistry_SecondarySecretLocations(t *testing.T) { + secretOnly := newSecretAuthRegistry(t, &common.AuthConfig{Strategies: []*common.AuthStrategyConfig{{ + Type: common.AuthTypeSecret, + Secret: &common.SecretStrategyConfig{Id: "backend", Value: "backend-token", AdditionalLocations: []common.SecretLocation{ + common.SecretLocationApikeyQuery, common.SecretLocationApikeyHeader, common.SecretLocationPath, + }}, + }}}) + + h := http.Header{} + h.Set("X-Api-Key", "backend-token") + for name, ap := range map[string]func() (*AuthPayload, error){ + "query": func() (*AuthPayload, error) { + return NewPayloadFromHttp("m", "", http.Header{}, url.Values{"apikey": {"backend-token"}}, "") + }, + "header": func() (*AuthPayload, error) { return NewPayloadFromHttp("m", "", h, url.Values{}, "") }, + "path": func() (*AuthPayload, error) { + return NewPayloadFromHttp("m", "", http.Header{}, url.Values{}, "/backend-token") + }, + } { + t.Run(name, func(t *testing.T) { + p, err := ap() + require.NoError(t, err) + user, err := secretOnly.Authenticate(context.Background(), nil, "m", p) + require.NoError(t, err) + assert.Equal(t, "backend", user.Id) + }) + } + + t.Run("locations are off unless listed", func(t *testing.T) { + standardOnly := newSecretAuthRegistry(t, &common.AuthConfig{Strategies: []*common.AuthStrategyConfig{{ + Type: common.AuthTypeSecret, + Secret: &common.SecretStrategyConfig{Id: "backend", Value: "backend-token"}, + }}}) + headerOnly := newSecretAuthRegistry(t, &common.AuthConfig{Strategies: []*common.AuthStrategyConfig{{ + Type: common.AuthTypeSecret, + Secret: &common.SecretStrategyConfig{Id: "backend", Value: "backend-token", AdditionalLocations: []common.SecretLocation{ + common.SecretLocationApikeyHeader, + }}, + }}}) + + p, err := NewPayloadFromHttp("m", "", h, url.Values{}, "") + require.NoError(t, err) + _, err = standardOnly.Authenticate(context.Background(), nil, "m", p) + require.Error(t, err) + user, err := headerOnly.Authenticate(context.Background(), nil, "m", p) + require.NoError(t, err) + assert.Equal(t, "backend", user.Id) + + p, err = NewPayloadFromHttp("m", "", http.Header{}, url.Values{}, "/backend-token") + require.NoError(t, err) + _, err = headerOnly.Authenticate(context.Background(), nil, "m", p) + require.Error(t, err) + + // The standard locations keep working without additionalLocations. + p, err = NewPayloadFromHttp("m", "", http.Header{}, url.Values{"secret": {"backend-token"}}, "") + require.NoError(t, err) + user, err = standardOnly.Authenticate(context.Background(), nil, "m", p) + require.NoError(t, err) + assert.Equal(t, "backend", user.Id) + }) + + t.Run("wrong path secret is rejected", func(t *testing.T) { + p, err := NewPayloadFromHttp("m", "", http.Header{}, url.Values{}, "/wrong") + require.NoError(t, err) + _, err = secretOnly.Authenticate(context.Background(), nil, "m", p) + require.Error(t, err) + }) + + t.Run("network strategy still serves requests that only carry a secondary secret", func(t *testing.T) { + networkOnly := newSecretAuthRegistry(t, &common.AuthConfig{Strategies: []*common.AuthStrategyConfig{{ + Type: common.AuthTypeNetwork, + Network: &common.NetworkStrategyConfig{AllowLocalhost: true}, + }}}) + p, err := NewPayloadFromHttp("m", "", h, url.Values{}, "") + require.NoError(t, err) + req := common.NewNormalizedRequest(nil) + req.SetClientIP("127.0.0.1") + user, err := networkOnly.Authenticate(context.Background(), req, "m", p) + require.NoError(t, err) + assert.Equal(t, "127.0.0.1", user.Id) + }) +} + +func TestStrategySupports_AdditionalLocations(t *testing.T) { + headerKey := &AuthPayload{Type: common.AuthTypeNetwork, Secret: &SecretPayload{Value: "k", Location: common.SecretLocationApikeyHeader}} + standard := &AuthPayload{Type: common.AuthTypeSecret, Secret: &SecretPayload{Value: "k"}} + headerOnly := []common.SecretLocation{common.SecretLocationApikeyHeader} + + assert.False(t, NewSecretStrategy(&common.SecretStrategyConfig{Value: "k"}).Supports(headerKey)) + assert.True(t, NewSecretStrategy(&common.SecretStrategyConfig{Value: "k", AdditionalLocations: headerOnly}).Supports(headerKey)) + assert.True(t, NewSecretStrategy(&common.SecretStrategyConfig{Value: "k"}).Supports(standard)) + + assert.False(t, (&DatabaseStrategy{cfg: &common.DatabaseStrategyConfig{}}).Supports(headerKey)) + assert.True(t, (&DatabaseStrategy{cfg: &common.DatabaseStrategyConfig{AdditionalLocations: headerOnly}}).Supports(headerKey)) + assert.True(t, (&DatabaseStrategy{cfg: &common.DatabaseStrategyConfig{}}).Supports(standard)) +} diff --git a/auth/payload.go b/auth/payload.go index 43bc556d3..78e3ae963 100644 --- a/auth/payload.go +++ b/auth/payload.go @@ -24,6 +24,26 @@ type AuthPayload struct { // This payload is used by both "secret" and "database" strategies type SecretPayload struct { Value string + // Location is where an additional-location secret was found (see + // common.SecretLocation); "" for the standard locations. + Location common.SecretLocation +} + +// secretAccepted reports whether ap carries a secret from a location a +// strategy accepts: a standard one, or one of its additional locations. +func secretAccepted(ap *AuthPayload, additional []common.SecretLocation) bool { + if ap.Secret == nil { + return false + } + if ap.Secret.Location == "" { + return true + } + for _, l := range additional { + if l == ap.Secret.Location { + return true + } + } + return false } type JwtPayload struct { diff --git a/auth/strategy_database.go b/auth/strategy_database.go index 3b34e63fa..f6cac473b 100644 --- a/auth/strategy_database.go +++ b/auth/strategy_database.go @@ -115,7 +115,7 @@ func NewDatabaseStrategy(appCtx context.Context, logger *zerolog.Logger, cfg *co } func (s *DatabaseStrategy) Supports(ap *AuthPayload) bool { - return ap.Type == common.AuthTypeSecret || ap.Type == common.AuthTypeDatabase + return ap.Type == common.AuthTypeSecret || ap.Type == common.AuthTypeDatabase || secretAccepted(ap, s.cfg.AdditionalLocations) } func (s *DatabaseStrategy) Authenticate(ctx context.Context, req *common.NormalizedRequest, ap *AuthPayload) (*common.User, error) { diff --git a/auth/strategy_forwarded_client_id_test.go b/auth/strategy_forwarded_client_id_test.go index 566022ee8..2e22791c2 100644 --- a/auth/strategy_forwarded_client_id_test.go +++ b/auth/strategy_forwarded_client_id_test.go @@ -14,7 +14,7 @@ import ( func forwardedPayload(t *testing.T, remoteAddr string, headers http.Header) *AuthPayload { t.Helper() - ap, err := NewPayloadFromHttp("eth_blockNumber", remoteAddr, headers, url.Values{}) + ap, err := NewPayloadFromHttp("eth_blockNumber", remoteAddr, headers, url.Values{}, "") require.NoError(t, err) return ap } diff --git a/auth/strategy_secret.go b/auth/strategy_secret.go index d0e10fc67..fe81d25e5 100644 --- a/auth/strategy_secret.go +++ b/auth/strategy_secret.go @@ -16,8 +16,11 @@ func NewSecretStrategy(cfg *common.SecretStrategyConfig) *SecretStrategy { return &SecretStrategy{cfg: cfg} } +// Supports accepts a payload carrying a secret from a standard location +// (which also sets ap.Type to secret) or from one of the strategy's +// additionalLocations (which leave ap.Type unchanged). func (s *SecretStrategy) Supports(ap *AuthPayload) bool { - return ap.Type == common.AuthTypeSecret + return ap.Type == common.AuthTypeSecret || secretAccepted(ap, s.cfg.AdditionalLocations) } func (s *SecretStrategy) Authenticate(ctx context.Context, req *common.NormalizedRequest, ap *AuthPayload) (*common.User, error) { diff --git a/common/config.go b/common/config.go index cebc54e18..aa146cd70 100644 --- a/common/config.go +++ b/common/config.go @@ -3394,11 +3394,53 @@ type AuthStrategyConfig struct { ForwardedClientId *ForwardedClientIdStrategyConfig `yaml:"forwardedClientId,omitempty" json:"forwardedClientId,omitempty"` } +// SecretLocation is a request location a secret can be read from besides the +// standard ones (?secret=, ?token=, X-ERPC-Secret-Token, Authorization: Basic). +type SecretLocation string + +const ( + // SecretLocationApikeyQuery is the ?apikey= query parameter. + SecretLocationApikeyQuery SecretLocation = "apikeyQuery" + // SecretLocationApikeyHeader is the X-Api-Key or apikey header. + SecretLocationApikeyHeader SecretLocation = "apikeyHeader" + // SecretLocationPath is the URL path as a single segment + // (https://host/), only when a domain alias preselects project, + // architecture and chain so the path is not used for routing. + SecretLocationPath SecretLocation = "path" +) + +// AcceptsSecretLocation reports whether any secret or database strategy of c +// lists l in its additionalLocations. +func (c *AuthConfig) AcceptsSecretLocation(l SecretLocation) bool { + if c == nil { + return false + } + for _, st := range c.Strategies { + if st == nil { + continue + } + var locations []SecretLocation + switch { + case st.Type == AuthTypeSecret && st.Secret != nil: + locations = st.Secret.AdditionalLocations + case st.Type == AuthTypeDatabase && st.Database != nil: + locations = st.Database.AdditionalLocations + } + if slices.Contains(locations, l) { + return true + } + } + return false +} + type SecretStrategyConfig struct { Id string `yaml:"id" json:"id"` Value string `yaml:"value" json:"value"` // RateLimitBudget, if set, is applied to the authenticated user from this strategy RateLimitBudget string `yaml:"rateLimitBudget,omitempty" json:"rateLimitBudget,omitempty"` + // AdditionalLocations also accepts the secret from these locations. Empty + // (the default) accepts only the standard ones. + AdditionalLocations []SecretLocation `yaml:"additionalLocations,omitempty" json:"additionalLocations,omitempty" tstype:"SecretLocation[]"` } // custom json marshaller to redact the secret value @@ -3409,11 +3451,15 @@ func (s *SecretStrategyConfig) MarshalJSON() ([]byte, error) { } func (s *SecretStrategyConfig) MarshalYAML() (interface{}, error) { - return map[string]string{ + out := map[string]interface{}{ "id": s.Id, "value": "REDACTED", "rateLimitBudget": s.RateLimitBudget, - }, nil + } + if len(s.AdditionalLocations) > 0 { + out["additionalLocations"] = s.AdditionalLocations + } + return out, nil } type DatabaseStrategyConfig struct { @@ -3422,6 +3468,9 @@ type DatabaseStrategyConfig struct { Retry *DatabaseRetryConfig `yaml:"retry,omitempty" json:"retry,omitempty"` FailOpen *DatabaseFailOpenConfig `yaml:"failOpen,omitempty" json:"failOpen,omitempty"` MaxWait Duration `yaml:"maxWait,omitempty" json:"maxWait" tstype:"Duration"` + // AdditionalLocations also accepts the secret from these locations. Empty + // (the default) accepts only the standard ones. + AdditionalLocations []SecretLocation `yaml:"additionalLocations,omitempty" json:"additionalLocations,omitempty" tstype:"SecretLocation[]"` } type DatabaseStrategyCacheConfig struct { diff --git a/common/tracing_util.go b/common/tracing_util.go index 458e4496d..f0b05ec89 100644 --- a/common/tracing_util.go +++ b/common/tracing_util.go @@ -69,7 +69,10 @@ func InjectHTTPResponseTraceContext(ctx context.Context, w http.ResponseWriter) // extractor reads credentials from (see auth.NewPayloadFromHttp). A SIWE // signature is replayable until its message expires, so it is redacted too; // the SIWE message itself is kept. -var credentialQueryParams = []string{"token", "secret", "jwt", "signature"} +var credentialQueryParams = []string{"token", "secret", "jwt", "signature", "apikey"} + +// RedactedPath replaces a request path that carries a credential in telemetry. +const RedactedPath = "/REDACTED" // RedactedRequestURL renders u for telemetry with the values of // credential-carrying query parameters replaced, so secrets passed in the @@ -99,6 +102,19 @@ func RedactedRequestURL(u *url.URL) string { return c.String() } +// RedactHTTPServerSpanPath overwrites the http.url attribute of the server +// span in ctx with u's path replaced by RedactedPath, for requests whose path +// carries a credential. +func RedactHTTPServerSpanPath(ctx context.Context, u *url.URL) { + if !IsTracingEnabled || u == nil { + return + } + c := *u + c.Path = RedactedPath + c.RawPath = "" + trace.SpanFromContext(ctx).SetAttributes(semconv.HTTPURLKey.String(RedactedRequestURL(&c))) +} + func StartHTTPServerSpan(ctx context.Context, r *http.Request) (context.Context, trace.Span) { if !IsTracingEnabled { return ctx, trace.SpanFromContext(ctx) diff --git a/common/tracing_util_redact_test.go b/common/tracing_util_redact_test.go index 0a0fe54e1..757a8950e 100644 --- a/common/tracing_util_redact_test.go +++ b/common/tracing_util_redact_test.go @@ -15,6 +15,7 @@ func TestRedactedRequestURL(t *testing.T) { "/main/evm/1?secret=s3cret": "/main/evm/1?secret=REDACTED", "/main/evm/1?token=t0k&foo=bar": "/main/evm/1?foo=bar&token=REDACTED", "/main/evm/1?jwt=a.b.c": "/main/evm/1?jwt=REDACTED", + "/main/evm/1?apikey=k": "/main/evm/1?apikey=REDACTED", "http://host:4000/main/evm/1?secret=x": "http://host:4000/main/evm/1?secret=REDACTED", "/main/evm/1?secret=a&secret=b": "/main/evm/1?secret=REDACTED&secret=REDACTED", "/main/evm/1?signature=0x1&message=abc": "/main/evm/1?message=abc&signature=REDACTED", diff --git a/common/validation.go b/common/validation.go index 691de2447..aaf11d738 100644 --- a/common/validation.go +++ b/common/validation.go @@ -1001,10 +1001,25 @@ func (s *AuthStrategyConfig) Validate() error { return nil } +func validateSecretLocations(field string, locations []SecretLocation) error { + for _, l := range locations { + switch l { + case SecretLocationApikeyQuery, SecretLocationApikeyHeader, SecretLocationPath: + default: + return fmt.Errorf("%s: unknown location %q (supported: %s, %s, %s)", + field, l, SecretLocationApikeyQuery, SecretLocationApikeyHeader, SecretLocationPath) + } + } + return nil +} + func (s *DatabaseStrategyConfig) Validate() error { if s.Connector == nil { return fmt.Errorf("auth.*.database.connector is required") } + if err := validateSecretLocations("auth.*.database.additionalLocations", s.AdditionalLocations); err != nil { + return err + } if s.Cache != nil { if s.Cache.TTL != nil && *s.Cache.TTL < 0 { @@ -1032,7 +1047,7 @@ func (s *SecretStrategyConfig) Validate() error { if s.Value == "" { return fmt.Errorf("auth.*.secret.value is required") } - return nil + return validateSecretLocations("auth.*.secret.additionalLocations", s.AdditionalLocations) } func (j *JwtStrategyConfig) Validate() error { diff --git a/common/validation_auth_secret_locations_test.go b/common/validation_auth_secret_locations_test.go new file mode 100644 index 000000000..ba58c0b52 --- /dev/null +++ b/common/validation_auth_secret_locations_test.go @@ -0,0 +1,33 @@ +package common + +import ( + "testing" + + "github.com/stretchr/testify/assert" +) + +func TestSecretStrategyConfig_ValidateAdditionalLocations(t *testing.T) { + ok := &SecretStrategyConfig{Value: "s", AdditionalLocations: []SecretLocation{SecretLocationApikeyQuery, SecretLocationApikeyHeader, SecretLocationPath}} + assert.NoError(t, ok.Validate()) + + bad := &SecretStrategyConfig{Value: "s", AdditionalLocations: []SecretLocation{"cookie"}} + assert.ErrorContains(t, bad.Validate(), `unknown location "cookie"`) + + db := &DatabaseStrategyConfig{Connector: &ConnectorConfig{Id: "c", Driver: DriverMemory, Memory: &MemoryConnectorConfig{MaxItems: 10}}, AdditionalLocations: []SecretLocation{"cookie"}} + assert.ErrorContains(t, db.Validate(), `unknown location "cookie"`) +} + +func TestAuthConfig_AcceptsSecretLocation(t *testing.T) { + var nilCfg *AuthConfig + assert.False(t, nilCfg.AcceptsSecretLocation(SecretLocationPath)) + + cfg := &AuthConfig{Strategies: []*AuthStrategyConfig{ + {Type: AuthTypeNetwork, Network: &NetworkStrategyConfig{}}, + {Type: AuthTypeSecret, Secret: &SecretStrategyConfig{Value: "s", AdditionalLocations: []SecretLocation{SecretLocationApikeyHeader}}}, + }} + assert.True(t, cfg.AcceptsSecretLocation(SecretLocationApikeyHeader)) + assert.False(t, cfg.AcceptsSecretLocation(SecretLocationPath)) + + cfg.Strategies = append(cfg.Strategies, &AuthStrategyConfig{Type: AuthTypeDatabase, Database: &DatabaseStrategyConfig{AdditionalLocations: []SecretLocation{SecretLocationPath}}}) + assert.True(t, cfg.AcceptsSecretLocation(SecretLocationPath)) +} diff --git a/docs/pages/config/auth.mdx b/docs/pages/config/auth.mdx index 9a731db9c..e5e3342f5 100644 --- a/docs/pages/config/auth.mdx +++ b/docs/pages/config/auth.mdx @@ -119,6 +119,8 @@ For each HTTP request, eRPC extracts credential signals from query params and he 8. `X-Siwe-Message` + `X-Siwe-Signature` headers → `AuthTypeSiwe` 9. No credential present → `AuthTypeNetwork` (fallback) +**Additional secret locations (opt-in).** When none of 1–4 supplied a secret, eRPC also looks, in this order, at `?apikey=` (`apikeyQuery`), the `X-Api-Key` / `apikey` header (`apikeyHeader`), and — only when a [domain alias](/config/server) preselects project, architecture **and** chain so the path is not used for routing, and a strategy of the auth config that serves the request (the project's, or `healthCheck.auth` for `GET` healthchecks) lists `path` — a single path segment (`path`: `https://rpc.example.com/`; `/admin`, `/healthcheck` and `/metrics` are never treated as secrets). A `secret` or `database` strategy only accepts a secret found there when it lists the location in its `additionalLocations`; without it (the default) such a secret is ignored. These locations do **not** change the credential type either: a request that only carries one of them still reaches a `network` strategy, so existing setups behave as before. + The `forwardedClientId` strategy does not take part in this order: it is offered every request that carries its configured header (whatever credential type was extracted), in declaration order like any other strategy. gRPC metadata uses a parallel order without query-param equivalents: `x-erpc-secret-token`, then `authorization: Basic`, `authorization: Bearer`, then `x-siwe-message`+`x-siwe-signature`, then network fallback. gRPC has no `?token=` / `?secret=` / `?jwt=` equivalents — query params are not available in gRPC metadata. @@ -129,7 +131,9 @@ gRPC metadata uses a parallel order without query-param equivalents: `x-erpc-sec #### secret strategy -The simplest backend-to-backend gate. The client sends the token as `?secret=VALUE` or the `X-ERPC-Secret-Token` header. `Authorization: Basic` is also accepted; only the password field is used — the username is silently discarded. +The simplest backend-to-backend gate. The client sends the token as `?secret=VALUE` or the `X-ERPC-Secret-Token` header. `Authorization: Basic` is also accepted; only the password field is used — the username is silently discarded. `?apikey=`, `X-Api-Key` / `apikey` headers and, on a fully aliased domain, the path (`/`) are accepted too when listed in `additionalLocations` (`apikeyQuery`, `apikeyHeader`, `path`; see above). + +A secret in the URL (query or path) ends up in the access logs of every proxy and load balancer on the way and in browser history; prefer headers where clients support them. eRPC replaces it with `REDACTED` / `/REDACTED` in the `http.url` span attribute and the CORS metrics' path label. Authenticate: exact equality match (`ap.Secret.Value != s.cfg.Value`). Returns `ErrAuthUnauthorized` on mismatch. No timing-safe compare — plain Go string inequality. For public internet deployments, prefer `database` or `jwt`. @@ -224,8 +228,9 @@ YAML prefix: `auth.strategies[*].secret` | `secret.id` | `string` | `""` | Returned as `User.Id` on success. May be empty. | | `secret.value` | `string` | required | Exact token to match. Plain string equality (not timing-safe). Redacted in JSON/YAML marshal. | | `secret.rateLimitBudget` | `string` | `""` | Attached to returned `User.RateLimitBudget` if non-empty. | +| `secret.additionalLocations` | `SecretLocation[]` | `[]` | Also accept the secret from `apikeyQuery` (`?apikey=`), `apikeyHeader` (`X-Api-Key` / `apikey`) and/or `path` (`/` on a fully aliased domain). Unknown values fail validation. | -Supports: `AuthTypeSecret` only. `SetDefaults`: no-op. +Supports: `AuthTypeSecret`, or a payload carrying a secret from one of its `additionalLocations`. `SetDefaults`: no-op. **`jwt` strategy — `JwtStrategyConfig`** @@ -293,6 +298,7 @@ YAML prefix: `auth.strategies[*].database` |---|---|---|---| | `database.connector` | `*ConnectorConfig` | auto-created | Drivers: `postgresql`, `dynamodb`, `redis`, `memory`, `grpc`. Connector id defaults to `"auth-"`. | | `database.maxWait` | `Duration` | `1s` | Per-request context timeout for the full DB lookup (singleflight + retries). | +| `database.additionalLocations` | `SecretLocation[]` | `[]` | Also accept the secret from `apikeyQuery` (`?apikey=`), `apikeyHeader` (`X-Api-Key` / `apikey`) and/or `path` (`/` on a fully aliased domain). Unknown values fail validation. | | `database.cache.ttl` | `*time.Duration` | `1h` | Positive-cache TTL in Ristretto. | | `database.cache.maxSize` | `*int64` | `10000` | Max positive-cache entries. | | `database.cache.maxCost` | `*int64` | `1073741824` (1 GiB) | Ristretto MaxCost for positive cache. | @@ -305,7 +311,7 @@ YAML prefix: `auth.strategies[*].database` Negative cache: hardcoded 5-second TTL, 1 MiB MaxCost. Not configurable. Disabled/invalid keys stay rejected up to 5 seconds after change. -**`database` strategy `Supports`**: accepts both `AuthTypeSecret` (token delivered via header/query) and `AuthTypeDatabase`. The `AuthTypeDatabase` enum value is never set by any current HTTP or gRPC payload extractor — it is reserved for future or programmatic use. +**`database` strategy `Supports`**: accepts `AuthTypeSecret` (token delivered via header/query), `AuthTypeDatabase`, and a payload carrying a secret from one of its `additionalLocations` (`apikeyQuery`, `apikeyHeader`, `path`). The `AuthTypeDatabase` enum value is never set by any current HTTP or gRPC payload extractor — it is reserved for future or programmatic use. **database connector error classification** — determines whether `connectorDown` latch is set ([`auth/strategy_database.go:L487-L517`](https://github.com/erpc/erpc/blob/main/auth/strategy_database.go#L487-L517)): @@ -641,6 +647,52 @@ each forwarded client its own quota via a `perUser` budget rule: },`} /> +**7. API key in the URL path for clients that only accept a URL.** Some wallets and SDKs +take a single RPC URL and cannot set headers. On a domain alias that pins project, +architecture and chain, `https://eth.rpc.example.com/` authenticates with the +`secret` (or `database`) strategy that lists `path` in `additionalLocations`: + + + ### Request/response behavior - A successful auth attaches `User{Id, RateLimitBudget}` to the request; `User.Id` flows into log context and Prometheus labels on every downstream metric. [] @@ -695,6 +747,8 @@ each forwarded client its own quota via a `perUser` budget rule: 27. **JWT `jwt.Parse` failures are classified into closed reasons.** Bad signatures → `invalid_signature`; expired → `token_expired`. If both bits are set, signature wins. Other `ValidationError` flags use `invalid_token` and keep jwt library text as the message. [] 28. **`erpc_auth_failed_total` increments when an `ErrAuthUnauthorized` is returned to the client** (`processErrorBody` / gRPC status mapping via `RecordAuthFailed`). Strategies stamp a closed `Details.reason` via `NewErrAuthUnauthorized`; intermediate strategy rejects on a request that later succeeds are not counted. When multiple strategies reject the same payload, the registry join keeps `strategy`/`reason` if every attempt agrees; if any attempt is `token_expired`, that wins (multi-JWT setups often pair matching-key expiry with other-key `invalid_signature`); other divergent attempts fall back to `n/a`/`unauthorized` while the joined message still lists each failure. `agent_name` is always `"unknown"`; `project`/`network` are `"n/a"` unless a resolved network is already on the request. [, ] 29. **`forwardedClientId` trusts a header.** It authenticates whoever can set the header. A proxy that *appends* to the header rather than overwriting it yields two values, which the strategy rejects; a proxy that passes a client-supplied header through untouched is a full auth bypass. The id is used verbatim in logs, metric labels and `perUser` rate-limit keys. A strategy without `allowedProxies` logs a `warn` at startup (`forwardedClientId auth strategy accepts its header from any peer; ...`). [] +30. **Additional secret locations never shadow `network`.** `?apikey=`, `X-Api-Key`/`apikey` and the `/` path leave the credential type as `network` when nothing else was supplied. With `[network, secret]` and a caller from an allowed IP, `network` wins (declaration order) and the key is not used for identity; put `secret`/`database` first if the key should decide the identity. +31. **Path secrets need a fully aliased domain and an opt-in.** The single path segment is only read as a secret when the domain alias preselects project, architecture and chain, and at least one `secret`/`database` strategy of that project lists `path` in `additionalLocations`. Otherwise the path is handled exactly as before: if the alias leaves any of project/architecture/chain to the path, the segment is routing (`/main`, `/1`, a network alias). [] ### Observability @@ -726,7 +780,7 @@ No dedicated auth trace spans — auth runs inline inside the HTTP handler gorou - [`auth/registry.go:L46-L96`](https://github.com/erpc/erpc/blob/main/auth/registry.go#L46-L96) — `AuthRegistry.Authenticate`: first-win loop, error accumulation - [`auth/authorizer.go:L83-L157`](https://github.com/erpc/erpc/blob/main/auth/authorizer.go#L83-L157) — `shouldApplyToMethod`, `acquireRateLimitPermit`, budget cascade -- [`auth/http.go:L13-L88`](https://github.com/erpc/erpc/blob/main/auth/http.go#L13-L88) — `NewPayloadFromHttp`: credential extraction priority order +- [`auth/http.go`](https://github.com/erpc/erpc/blob/main/auth/http.go) — `NewPayloadFromHttp`: credential extraction priority order, additional secret locations, `PathSegmentSecret` - [`auth/strategy_database.go:L271-L357`](https://github.com/erpc/erpc/blob/main/auth/strategy_database.go#L271-L357) — connector-down circuit-breaker, probe election, fail-open - [`auth/strategy_jwt.go:L100-L116`](https://github.com/erpc/erpc/blob/main/auth/strategy_jwt.go#L100-L116) — JWT key selection (kid lookup + type-compatibility scan) - [`auth/strategy_siwe.go:L22-L67`](https://github.com/erpc/erpc/blob/main/auth/strategy_siwe.go#L22-L67) — SIWE signature verification + domain allowlist diff --git a/docs/pages/operation/tracing.mdx b/docs/pages/operation/tracing.mdx index 04e8bf215..7bc857b8b 100644 --- a/docs/pages/operation/tracing.mdx +++ b/docs/pages/operation/tracing.mdx @@ -423,7 +423,7 @@ are recorded. Use `sampleRate: 0.0000001` because `sampleRate: 0` is rewritten t | Attribute | Phase | Value | |---|---|---| | `http.method` | on request | HTTP method (semconv) | -| `http.url` | on request | Full request URL; values of the credential query parameters the auth extractor reads (`secret`, `token`, `jwt`, SIWE `signature`) are replaced with `REDACTED` | +| `http.url` | on request | Full request URL; values of the credential query parameters the auth extractor reads (`secret`, `token`, `jwt`, SIWE `signature`, `apikey`) are replaced with `REDACTED`, and on a fully aliased domain where a strategy accepts path secrets, a single-segment path is replaced with `/REDACTED` | | `http.scheme` | on request | URL scheme | | `http.user_agent` | on request | User-Agent header value | | `erpc.force_trace` | on request, when forced | `true` (if forced via header/query) | diff --git a/erpc/healthcheck.go b/erpc/healthcheck.go index d3e79b137..f83740143 100644 --- a/erpc/healthcheck.go +++ b/erpc/healthcheck.go @@ -74,6 +74,7 @@ func (s *HttpServer) handleHealthCheck( projectId string, architecture string, chainId string, + credentialPath string, encoder sonic.Encoder, writeFatalError func(ctx context.Context, statusCode int, body error), ) { @@ -87,7 +88,7 @@ func (s *HttpServer) handleHealthCheck( headers := r.Header queryArgs := r.URL.Query() - ap, err := auth.NewPayloadFromHttp("healthcheck", r.RemoteAddr, headers, queryArgs) + ap, err := auth.NewPayloadFromHttp("healthcheck", r.RemoteAddr, headers, queryArgs, credentialPath) if err != nil { handleErrorResponse(ctx, &logger, startedAt, nil, err, w, encoder, writeFatalError, &common.TRUE, s.executionHeadersMode()) return diff --git a/erpc/healthcheck_test.go b/erpc/healthcheck_test.go index 25b9abdfe..415d3ae13 100644 --- a/erpc/healthcheck_test.go +++ b/erpc/healthcheck_test.go @@ -160,7 +160,7 @@ func TestHealthCheckSvmNetworkScope(t *testing.T) { ctx, w, &http.Request{Method: "GET", URL: &url.URL{Path: "/"}}, &startTime, - "solana-mainnet-beta", "svm", "mainnet-beta", + "solana-mainnet-beta", "svm", "mainnet-beta", "", encoder, func(ctx context.Context, statusCode int, body error) { w.WriteHeader(statusCode) diff --git a/erpc/http_server.go b/erpc/http_server.go index 5e9672ddb..dade7efd7 100644 --- a/erpc/http_server.go +++ b/erpc/http_server.go @@ -346,6 +346,10 @@ func (s *HttpServer) createRequestHandler() http.Handler { } } + // Only a domain alias that preselects project, architecture and chain + // leaves the path free of routing, so only then can it carry a secret. + fullyAliased := projectId != "" && architecture != "" && chainId != "" + w.Header().Set("Content-Type", "application/json") // executionHeaders:"off" suppresses all X-ERPC-* headers, including these. if s.executionHeadersMode() != common.ExecutionHeadersOff { @@ -382,13 +386,18 @@ func (s *HttpServer) createRequestHandler() http.Handler { } if isHealthCheck { - s.handleHealthCheck(httpCtx, w, r, &startedAt, projectId, architecture, chainId, encoder, writeFatalError) + var healthCheckAuth *common.AuthConfig + if s.healthCheckCfg != nil { + healthCheckAuth = s.healthCheckCfg.Auth + } + credentialPath := credentialPathFor(httpCtx, r, fullyAliased, healthCheckAuth) + s.handleHealthCheck(httpCtx, w, r, &startedAt, projectId, architecture, chainId, credentialPath, encoder, writeFatalError) return } if isAdmin { if s.adminCfg != nil && s.adminCfg.CORS != nil { - if !s.handleCORS(httpCtx, w, r, s.adminCfg.CORS) || r.Method == http.MethodOptions { + if !s.handleCORS(httpCtx, w, r, s.adminCfg.CORS, r.URL.Path) || r.Method == http.MethodOptions { return } } @@ -436,8 +445,17 @@ func (s *HttpServer) createRequestHandler() http.Handler { return } + var credentialPath string + if project != nil { + credentialPath = credentialPathFor(httpCtx, r, fullyAliased, project.Config.Auth) + } + corsPath := r.URL.Path + if credentialPath != "" { + corsPath = common.RedactedPath + } + if project != nil && project.Config.CORS != nil { - if !s.handleCORS(httpCtx, w, r, project.Config.CORS) || r.Method == http.MethodOptions { + if !s.handleCORS(httpCtx, w, r, project.Config.CORS, corsPath) || r.Method == http.MethodOptions { return } } @@ -466,7 +484,7 @@ func (s *HttpServer) createRequestHandler() http.Handler { // served. Method scoping and rate limits still apply per message. nq := common.NewNormalizedRequest(nil) nq.SetClientIP(s.resolveRealClientIP(r)) - ap, err := auth.NewPayloadFromHttp("", r.RemoteAddr, r.Header, r.URL.Query()) + ap, err := auth.NewPayloadFromHttp("", r.RemoteAddr, r.Header, r.URL.Query(), credentialPath) if err == nil { err = project.AcceptsConsumerPayload(httpCtx, nq, ap) } @@ -486,7 +504,7 @@ func (s *HttpServer) createRequestHandler() http.Handler { ) return } - s.handleWebSocket(w, r, &lg, project, architecture, chainId) + s.handleWebSocket(w, r, &lg, project, architecture, chainId, credentialPath) return } @@ -682,9 +700,9 @@ func (s *HttpServer) createRequestHandler() http.Handler { var ap *auth.AuthPayload if project != nil { - ap, err = auth.NewPayloadFromHttp(method, r.RemoteAddr, headers, queryArgs) + ap, err = auth.NewPayloadFromHttp(method, r.RemoteAddr, headers, queryArgs, credentialPath) } else if isAdmin { - ap, err = auth.NewPayloadFromHttp(method, r.RemoteAddr, headers, queryArgs) + ap, err = auth.NewPayloadFromHttp(method, r.RemoteAddr, headers, queryArgs, credentialPath) } if err != nil { responses[index] = processErrorBody(&rlg, &startedAt, nq, err, &common.TRUE) @@ -1186,7 +1204,23 @@ func (s *HttpServer) parseUrlPath( return projectId, architecture, chainId, isAdmin, isHealthCheck, nil } -func (s *HttpServer) handleCORS(httpCtx context.Context, w http.ResponseWriter, r *http.Request, corsConfig *common.CORSConfig) bool { +// credentialPathFor returns r's path when it carries a secret (see +// auth.PathSegmentSecret), and "" otherwise. Only a domain alias that +// preselects project, architecture and chain leaves the path free of routing, +// and only an auth config with a strategy that lists the path location reads +// it. A returned path is also redacted from the request span. +func credentialPathFor(ctx context.Context, r *http.Request, fullyAliased bool, authCfg *common.AuthConfig) string { + if !fullyAliased || !authCfg.AcceptsSecretLocation(common.SecretLocationPath) || auth.PathSegmentSecret(r.URL.Path) == "" { + return "" + } + common.RedactHTTPServerSpanPath(ctx, r.URL) + return r.URL.Path +} + +// handleCORS applies corsConfig to r. metricPath is the path label for the +// CORS metrics (the request path, or common.RedactedPath when it carries a +// secret). +func (s *HttpServer) handleCORS(httpCtx context.Context, w http.ResponseWriter, r *http.Request, corsConfig *common.CORSConfig, metricPath string) bool { origin := r.Header.Get("Origin") if origin == "" { // When no Origin is provided, we allow the request as there's no point in enforcing CORS. @@ -1198,7 +1232,7 @@ func (s *HttpServer) handleCORS(httpCtx context.Context, w http.ResponseWriter, return true } - telemetry.MetricCORSRequestsTotal.WithLabelValues(r.URL.Path, origin).Inc() + telemetry.MetricCORSRequestsTotal.WithLabelValues(metricPath, origin).Inc() allowed := false for _, allowedOrigin := range corsConfig.AllowedOrigins { @@ -1216,7 +1250,7 @@ func (s *HttpServer) handleCORS(httpCtx context.Context, w http.ResponseWriter, // If disallowed origin, we can continue without CORS headers if !allowed { s.logger.Debug().Str("origin", origin).Msg("CORS request from disallowed origin, continuing without CORS headers") - telemetry.MetricCORSDisallowedOriginTotal.WithLabelValues(r.URL.Path, origin).Inc() + telemetry.MetricCORSDisallowedOriginTotal.WithLabelValues(metricPath, origin).Inc() // If it's a preflight OPTIONS request, we can send a basic 204 with no CORS. if r.Method == http.MethodOptions { @@ -1247,7 +1281,7 @@ func (s *HttpServer) handleCORS(httpCtx context.Context, w http.ResponseWriter, // If it's a preflight request, return a 204 and don't continue to main handler. if r.Method == http.MethodOptions { - telemetry.MetricCORSPreflightRequestsTotal.WithLabelValues(r.URL.Path, origin).Inc() + telemetry.MetricCORSPreflightRequestsTotal.WithLabelValues(metricPath, origin).Inc() w.WriteHeader(http.StatusNoContent) common.EnrichHTTPServerSpan(httpCtx, http.StatusNoContent, nil) return false diff --git a/erpc/http_server_path_secret_test.go b/erpc/http_server_path_secret_test.go new file mode 100644 index 000000000..9c5bc283b --- /dev/null +++ b/erpc/http_server_path_secret_test.go @@ -0,0 +1,159 @@ +package erpc + +import ( + "fmt" + "io" + "net/http" + "strings" + "testing" + + "github.com/erpc/erpc/common" + "github.com/erpc/erpc/telemetry" + "github.com/erpc/erpc/util" + "github.com/gorilla/websocket" + promUtil "github.com/prometheus/client_golang/prometheus/testutil" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +const ( + pathSecretValue = "path-secret-value" + pathSecretGetBalance = `{"jsonrpc":"2.0","id":1,"method":"eth_getBalance","params":["0x0000000000000000000000000000000000000001","latest"]}` +) + +func pathSecretConfig(rule *common.AliasingRuleConfig) *common.Config { + cfg := httpOnlyConfig() + cfg.Server.Aliasing = &common.AliasingConfig{Rules: []*common.AliasingRuleConfig{rule}} + strategies := func() *common.AuthConfig { + return &common.AuthConfig{Strategies: []*common.AuthStrategyConfig{{ + Type: common.AuthTypeSecret, + Secret: &common.SecretStrategyConfig{Id: "client-a", Value: pathSecretValue, AdditionalLocations: []common.SecretLocation{common.SecretLocationPath}}, + }}} + } + cfg.Projects[0].Auth = strategies() + // A GET request is a healthcheck, authenticated by healthCheck.auth. + cfg.HealthCheck = &common.HealthCheckConfig{Auth: strategies()} + return cfg +} + +func doPathSecretRequest(t *testing.T, method, url string, headers map[string]string) (int, string) { + t.Helper() + var body io.Reader + if method == http.MethodPost { + body = strings.NewReader(pathSecretGetBalance) + } + req, err := http.NewRequest(method, url, body) + require.NoError(t, err) + req.Header.Set("Content-Type", "application/json") + for k, v := range headers { + req.Header.Set(k, v) + } + resp, err := http.DefaultClient.Do(req) + require.NoError(t, err) + defer resp.Body.Close() + b, err := io.ReadAll(resp.Body) + require.NoError(t, err) + return resp.StatusCode, string(b) +} + +// With a domain alias that preselects project, architecture and chain, the +// URL path is not used for routing and can carry the secret: https://host/. +func TestPathSecretAuth_FullyAliasedDomain(t *testing.T) { + setupGock() + defer util.ResetGock() + + cfg := pathSecretConfig(&common.AliasingRuleConfig{ + MatchDomain: "*", ServeProject: "test_ws", ServeArchitecture: "evm", ServeChain: "123", + }) + cfg.Projects[0].CORS = &common.CORSConfig{AllowedOrigins: []string{"*"}} + addr, cleanup := setupTestERPCServer(t, cfg) + defer cleanup() + + t.Run("http", func(t *testing.T) { + status, body := doPathSecretRequest(t, http.MethodPost, fmt.Sprintf("http://%s/%s", addr, pathSecretValue), nil) + assert.Equal(t, http.StatusOK, status, body) + assert.Contains(t, body, "0xabc123") + + status, body = doPathSecretRequest(t, http.MethodPost, fmt.Sprintf("http://%s/wrong-secret", addr), nil) + assert.Equal(t, http.StatusUnauthorized, status, body) + assert.NotContains(t, body, pathSecretValue) + + status, body = doPathSecretRequest(t, http.MethodPost, fmt.Sprintf("http://%s/", addr), nil) + assert.Equal(t, http.StatusUnauthorized, status, body) + }) + + t.Run("websocket", func(t *testing.T) { + _, resp, err := websocket.DefaultDialer.Dial(fmt.Sprintf("ws://%s/wrong-secret", addr), nil) + require.Error(t, err) + require.NotNil(t, resp) + assert.Equal(t, http.StatusUnauthorized, resp.StatusCode) + + conn, _, err := websocket.DefaultDialer.Dial(fmt.Sprintf("ws://%s/%s", addr, pathSecretValue), nil) + require.NoError(t, err) + defer conn.Close() + out := sendAndReceive(t, conn, pathSecretGetBalance) + assert.Equal(t, "0xabc123", out["result"]) + }) + + t.Run("healthcheck", func(t *testing.T) { + status, body := doPathSecretRequest(t, http.MethodGet, fmt.Sprintf("http://%s/wrong-secret", addr), nil) + assert.Equal(t, http.StatusUnauthorized, status, body) + + status, body = doPathSecretRequest(t, http.MethodGet, fmt.Sprintf("http://%s/%s", addr, pathSecretValue), nil) + assert.NotEqual(t, http.StatusUnauthorized, status, body) + }) + + t.Run("cors metric does not record the secret", func(t *testing.T) { + const origin = "https://path-secret-test.example" + status, body := doPathSecretRequest(t, http.MethodPost, fmt.Sprintf("http://%s/%s", addr, pathSecretValue), map[string]string{"Origin": origin}) + assert.Equal(t, http.StatusOK, status, body) + assert.Equal(t, float64(0), promUtil.ToFloat64(telemetry.MetricCORSRequestsTotal.WithLabelValues("/"+pathSecretValue, origin))) + assert.Equal(t, float64(1), promUtil.ToFloat64(telemetry.MetricCORSRequestsTotal.WithLabelValues(common.RedactedPath, origin))) + }) +} + +// When routing consumes the path (here the chain id), a single segment must +// never be read as a secret, even if it happens to equal one. +func TestPathSecretAuth_IgnoredWhenPathIsRouted(t *testing.T) { + setupGock() + defer util.ResetGock() + + cfg := pathSecretConfig(&common.AliasingRuleConfig{ + MatchDomain: "*", ServeProject: "test_ws", ServeArchitecture: "evm", + }) + cfg.Projects[0].Auth.Strategies[0].Secret.Value = "123" + addr, cleanup := setupTestERPCServer(t, cfg) + defer cleanup() + + status, body := doPathSecretRequest(t, http.MethodPost, fmt.Sprintf("http://%s/123", addr), nil) + assert.Equal(t, http.StatusUnauthorized, status, body) + + status, body = doPathSecretRequest(t, http.MethodPost, fmt.Sprintf("http://%s/123?secret=123", addr), nil) + assert.Equal(t, http.StatusOK, status, body) +} + +// Without a strategy that lists path in additionalLocations, a fully aliased +// domain treats the path exactly as before: it is not a credential and is +// recorded as is. +func TestPathSecretAuth_NotOptedIn(t *testing.T) { + setupGock() + defer util.ResetGock() + + cfg := pathSecretConfig(&common.AliasingRuleConfig{ + MatchDomain: "*", ServeProject: "test_ws", ServeArchitecture: "evm", ServeChain: "123", + }) + cfg.Projects[0].Auth.Strategies[0].Secret.AdditionalLocations = nil + cfg.HealthCheck = nil + cfg.Projects[0].CORS = &common.CORSConfig{AllowedOrigins: []string{"*"}} + addr, cleanup := setupTestERPCServer(t, cfg) + defer cleanup() + + const origin = "https://path-secret-not-opted-in.example" + status, body := doPathSecretRequest(t, http.MethodPost, fmt.Sprintf("http://%s/%s", addr, pathSecretValue), map[string]string{"Origin": origin}) + assert.Equal(t, http.StatusUnauthorized, status, body) + assert.Equal(t, float64(1), promUtil.ToFloat64(telemetry.MetricCORSRequestsTotal.WithLabelValues("/"+pathSecretValue, origin))) + assert.Equal(t, float64(0), promUtil.ToFloat64(telemetry.MetricCORSRequestsTotal.WithLabelValues(common.RedactedPath, origin))) + + status, body = doPathSecretRequest(t, http.MethodPost, fmt.Sprintf("http://%s/?secret=%s", addr, pathSecretValue), nil) + assert.Equal(t, http.StatusOK, status, body) +} diff --git a/erpc/http_server_test.go b/erpc/http_server_test.go index a580b7552..b112f97ff 100644 --- a/erpc/http_server_test.go +++ b/erpc/http_server_test.go @@ -4506,7 +4506,7 @@ func TestHttpServer_HandleHealthCheck(t *testing.T) { startTime := time.Now() encoder := common.SonicCfg.NewEncoder(w) - s.handleHealthCheck(ctx, w, tt.request, &startTime, tt.projectId, tt.architecture, tt.chainId, encoder, func(ctx context.Context, statusCode int, body error) { + s.handleHealthCheck(ctx, w, tt.request, &startTime, tt.projectId, tt.architecture, tt.chainId, "", encoder, func(ctx context.Context, statusCode int, body error) { w.WriteHeader(statusCode) encoder.Encode(map[string]string{"error": body.Error()}) }) diff --git a/erpc/ws_server.go b/erpc/ws_server.go index 64df98389..3ec824512 100644 --- a/erpc/ws_server.go +++ b/erpc/ws_server.go @@ -47,6 +47,9 @@ type WsConnection struct { costFrames bool // notifyCostBlocks caches each subscription kind's notification block. notifyCostBlocks [indexer.KindPendingTx + 1]atomic.Pointer[[]byte] + // credentialPath is the upgrade request's path when it may carry a + // secret (see auth.NewPayloadFromHttp), "" otherwise. + credentialPath string // Write synchronization (gorilla/websocket requires synchronized writes) writeMu sync.Mutex @@ -82,6 +85,7 @@ func (s *HttpServer) handleWebSocket( project *PreparedProject, architecture string, chainId string, + credentialPath string, ) { wsCfg := s.serverCfg.WebSocket @@ -122,20 +126,21 @@ func (s *HttpServer) handleWebSocket( // so in-flight requests still get their response. connCtx, connCancel := context.WithCancel(context.Background()) wsc := &WsConnection{ - id: fmt.Sprintf("ws-%d", atomic.AddInt64(&wsConnCounter, 1)), - conn: wsConn, - ctx: connCtx, - cancel: connCancel, - logger: lg, - server: s, - project: project, - networkId: fmt.Sprintf("%s:%s", architecture, chainId), - architecture: common.NetworkArchitecture(architecture), - httpReq: r, - costFrames: s.costHeadersEnabled() && r.Header.Get(headerCostFrames) == "1", - sem: make(chan struct{}, wsCfg.MaxConcurrentRequestsPerConnection), - stopped: make(chan struct{}), - done: make(chan struct{}), + id: fmt.Sprintf("ws-%d", atomic.AddInt64(&wsConnCounter, 1)), + conn: wsConn, + ctx: connCtx, + cancel: connCancel, + logger: lg, + server: s, + project: project, + networkId: fmt.Sprintf("%s:%s", architecture, chainId), + architecture: common.NetworkArchitecture(architecture), + httpReq: r, + credentialPath: credentialPath, + costFrames: s.costHeadersEnabled() && r.Header.Get(headerCostFrames) == "1", + sem: make(chan struct{}, wsCfg.MaxConcurrentRequestsPerConnection), + stopped: make(chan struct{}), + done: make(chan struct{}), } lg.Info().Str("connId", wsc.id).Str("remoteAddr", r.RemoteAddr).Msg("websocket connection established") @@ -379,7 +384,7 @@ func (wsc *WsConnection) handleRequest(ctx context.Context, raw []byte, startedA return unsupported("subscription methods (eth_subscribe, eth_unsubscribe) are not supported in batch requests"), notification } - ap, err := auth.NewPayloadFromHttp(method, wsc.httpReq.RemoteAddr, headers, queryArgs) + ap, err := auth.NewPayloadFromHttp(method, wsc.httpReq.RemoteAddr, headers, queryArgs, wsc.credentialPath) if err != nil { return fail(err, &common.TRUE), notification } diff --git a/typescript/config/src/generated.ts b/typescript/config/src/generated.ts index 31cabbc63..4122b040f 100644 --- a/typescript/config/src/generated.ts +++ b/typescript/config/src/generated.ts @@ -2166,6 +2166,25 @@ export interface AuthStrategyConfig { siwe?: SiweStrategyConfig; forwardedClientId?: ForwardedClientIdStrategyConfig; } +/** + * SecretLocation is a request location a secret can be read from besides the + * standard ones (?secret=, ?token=, X-ERPC-Secret-Token, Authorization: Basic). + */ +export type SecretLocation = string; +/** + * SecretLocationApikeyQuery is the ?apikey= query parameter. + */ +export const SecretLocationApikeyQuery: SecretLocation = "apikeyQuery"; +/** + * SecretLocationApikeyHeader is the X-Api-Key or apikey header. + */ +export const SecretLocationApikeyHeader: SecretLocation = "apikeyHeader"; +/** + * SecretLocationPath is the URL path as a single segment + * (https://host/), only when a domain alias preselects project, + * architecture and chain so the path is not used for routing. + */ +export const SecretLocationPath: SecretLocation = "path"; export interface SecretStrategyConfig { id: string; value: string; @@ -2173,6 +2192,11 @@ export interface SecretStrategyConfig { * RateLimitBudget, if set, is applied to the authenticated user from this strategy */ rateLimitBudget?: string; + /** + * AdditionalLocations also accepts the secret from these locations. Empty + * (the default) accepts only the standard ones. + */ + additionalLocations?: SecretLocation[]; } export interface DatabaseStrategyConfig { connector?: ConnectorConfig; @@ -2180,6 +2204,11 @@ export interface DatabaseStrategyConfig { retry?: DatabaseRetryConfig; failOpen?: DatabaseFailOpenConfig; maxWait?: Duration; + /** + * AdditionalLocations also accepts the secret from these locations. Empty + * (the default) accepts only the standard ones. + */ + additionalLocations?: SecretLocation[]; } export interface DatabaseStrategyCacheConfig { ttl?: number /* time in nanoseconds (time.Duration) */;