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..791f737c3 100644 --- a/auth/http.go +++ b/auth/http.go @@ -5,14 +5,21 @@ 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, + Method: method, + Headers: headers, + RemoteAddr: remoteAddr, } if token := args.Get("token"); token != "" { // deprecated @@ -79,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 @@ -87,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 712003534..78e3ae963 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,11 +12,38 @@ 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 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.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..2e22791c2 --- /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/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 a8e9ea7f9..aa146cd70 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,47 @@ 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"` +} + +// 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 { @@ -3396,6 +3438,9 @@ type SecretStrategyConfig struct { 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 @@ -3406,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 { @@ -3419,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 { @@ -3458,6 +3510,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/tracing_util.go b/common/tracing_util.go index 6054c21e0..f0b05ec89 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,56 @@ 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", "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 +// 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() +} + +// 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) @@ -80,7 +131,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..757a8950e --- /dev/null +++ b/common/tracing_util_redact_test.go @@ -0,0 +1,30 @@ +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", + "/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", + "/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/common/validation.go b/common/validation.go index 84dcf2848..aaf11d738 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,15 +995,31 @@ func (s *AuthStrategyConfig) Validate() error { AuthTypeJwt, AuthTypeSiwe, AuthTypeDatabase, + AuthTypeForwardedClientId, }) } 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 { @@ -1024,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 { @@ -1057,6 +1080,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/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 4cca37fa8..e5e3342f5 100644 --- a/docs/pages/config/auth.mdx +++ b/docs/pages/config/auth.mdx @@ -119,6 +119,10 @@ 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. **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"]`. @@ -127,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`. @@ -153,6 +159,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 +214,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. | @@ -209,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`** @@ -242,6 +262,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` @@ -265,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. | @@ -277,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)): @@ -579,6 +613,86 @@ 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: + + + +**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. [] @@ -598,6 +712,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 +727,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 +746,9 @@ 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; ...`). [] +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 @@ -662,10 +780,11 @@ 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 +- [`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/docs/pages/operation/tracing.mdx b/docs/pages/operation/tracing.mdx index 5499a3ab4..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 | +| `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_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/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 35b6f05c9..4122b040f 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,7 +2164,27 @@ export interface AuthStrategyConfig { database?: DatabaseStrategyConfig; jwt?: JwtStrategyConfig; 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; @@ -2171,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; @@ -2178,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) */; @@ -2215,6 +2246,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; + } ); /**