security: validate client-supplied trace IDs (#26)

* security: validate client-supplied trace IDs to prevent log injection

Add validateTraceID helper that sanitizes trace IDs from gRPC metadata
and proto fields: max 128 chars, printable ASCII only (0x20-0x7E).
Non-printable/control/unicode bytes are stripped. If all characters are
invalid, falls back to generating a new UUID.

Called in SetTraceIdWithValue (after metadata extraction) and UpdateTraceId
(before storing). Protects logs, Sentry/Rollbar, and OTEL span attributes
from injection attacks and DoS via oversized trace IDs.

* feat: add SetTraceIDValidator for configurable trace ID validation

Add SetTraceIDValidator(func(string) string) to allow custom validation
or disable it entirely (set to nil). Follows the existing init-only
setter pattern. Default behavior unchanged (max 128 chars, printable
ASCII only).

* fix: add UTF-8 test case, use TrimSpace in UpdateTraceId

Address review feedback:
- Add non-ASCII UTF-8 test case (accented, CJK, emoji) to validateTraceID
- Use strings.TrimSpace in UpdateTraceId to match SetTraceIdWithValue
  behavior — whitespace-only trace IDs now fall back to generation

* docs: fix SetTraceIDValidator docstring — empty string triggers resolution flow, not direct generation

* docs: fix resolution order in SetTraceIDValidator docstring

Author: ankurs

README.md

@@ -134,7 +134,7 @@ const SupportPackageIsVersion1 = true
 ```
 
 <a name="SetBaseFilePath"></a>
-## func [SetBaseFilePath](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L281>)
+## func [SetBaseFilePath](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L285>)
 
 ```go
 func SetBaseFilePath(path string)
@@ -143,7 +143,7 @@ func SetBaseFilePath(path string)
 SetBaseFilePath sets the base file path for linking source code with reported stack information
 
 <a name="SetMaxStackDepth"></a>
-## func [SetMaxStackDepth](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L264>)
+## func [SetMaxStackDepth](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L268>)
 
 ```go
 func SetMaxStackDepth(n int)
@@ -172,7 +172,7 @@ type ErrorExt interface {
 ```
 
 <a name="New"></a>
-### func [New](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L180>)
+### func [New](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L181>)
 
 ```go
 func New(msg string) ErrorExt
@@ -210,7 +210,7 @@ something went wrong
 </details>
 
 <a name="NewWithSkip"></a>
-### func [NewWithSkip](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L190>)
+### func [NewWithSkip](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L191>)
 
 ```go
 func NewWithSkip(msg string, skip int) ErrorExt
@@ -219,7 +219,7 @@ func NewWithSkip(msg string, skip int) ErrorExt
 NewWithSkip creates a new error skipping the number of function on the stack
 
 <a name="NewWithSkipAndStatus"></a>
-### func [NewWithSkipAndStatus](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L195>)
+### func [NewWithSkipAndStatus](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L196>)
 
 ```go
 func NewWithSkipAndStatus(msg string, skip int, status *grpcstatus.Status) ErrorExt
@@ -228,7 +228,7 @@ func NewWithSkipAndStatus(msg string, skip int, status *grpcstatus.Status) Error
 NewWithSkipAndStatus creates a new error skipping the number of function on the stack and GRPC status
 
 <a name="NewWithStatus"></a>
-### func [NewWithStatus](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L185>)
+### func [NewWithStatus](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L186>)
 
 ```go
 func NewWithStatus(msg string, status *grpcstatus.Status) ErrorExt
@@ -237,7 +237,7 @@ func NewWithStatus(msg string, status *grpcstatus.Status) ErrorExt
 NewWithStatus creates a new error with statck information and GRPC status
 
 <a name="Newf"></a>
-### func [Newf](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L271>)
+### func [Newf](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L275>)
 
 ```go
 func Newf(format string, args ...any) ErrorExt
@@ -275,7 +275,7 @@ user alice not found
 </details>
 
 <a name="Wrap"></a>
-### func [Wrap](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L200>)
+### func [Wrap](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L201>)
 
 ```go
 func Wrap(err error, msg string) ErrorExt
@@ -349,7 +349,7 @@ true
 </details>
 
 <a name="WrapWithSkip"></a>
-### func [WrapWithSkip](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L210>)
+### func [WrapWithSkip](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L211>)
 
 ```go
 func WrapWithSkip(err error, msg string, skip int) ErrorExt
@@ -358,7 +358,7 @@ func WrapWithSkip(err error, msg string, skip int) ErrorExt
 WrapWithSkip wraps an existing error and appends stack information if it does not exists skipping the number of function on the stack
 
 <a name="WrapWithSkipAndStatus"></a>
-### func [WrapWithSkipAndStatus](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L215>)
+### func [WrapWithSkipAndStatus](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L216>)
 
 ```go
 func WrapWithSkipAndStatus(err error, msg string, skip int, status *grpcstatus.Status) ErrorExt
@@ -367,7 +367,7 @@ func WrapWithSkipAndStatus(err error, msg string, skip int, status *grpcstatus.S
 WrapWithSkip wraps an existing error and appends stack information if it does not exists skipping the number of function on the stack along with GRPC status
 
 <a name="WrapWithStatus"></a>
-### func [WrapWithStatus](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L205>)
+### func [WrapWithStatus](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L206>)
 
 ```go
 func WrapWithStatus(err error, msg string, status *grpcstatus.Status) ErrorExt
@@ -412,7 +412,7 @@ gRPC code: NotFound
 </details>
 
 <a name="Wrapf"></a>
-### func [Wrapf](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L276>)
+### func [Wrapf](<https://github.com/go-coldbrew/errors/blob/main/errors.go#L280>)
 
 ```go
 func Wrapf(err error, format string, args ...any) ErrorExt

notifier/README.md

@@ -33,13 +33,15 @@ import "github.com/go-coldbrew/errors/notifier"
 - [func SetRelease\(rel string\)](<#SetRelease>)
 - [func SetServerRoot\(path string\)](<#SetServerRoot>)
 - [func SetTraceHeaderName\(name string\)](<#SetTraceHeaderName>)
+- [func SetTraceIDValidator\(fn func\(string\) string\)](<#SetTraceIDValidator>)
 - [func SetTraceId\(ctx context.Context\) context.Context](<#SetTraceId>)
+- [func SetTraceIdWithValue\(ctx context.Context\) \(context.Context, string\)](<#SetTraceIdWithValue>)
 - [func UpdateTraceId\(ctx context.Context, traceID string\) context.Context](<#UpdateTraceId>)
 - [type Tags](<#Tags>)
 
 
 <a name="Close"></a>
-## func [Close](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L493>)
+## func [Close](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L503>)
 
 ```go
 func Close()
@@ -48,7 +50,7 @@ func Close()
 Close closes the airbrake notifier and flushes pending Sentry events. Sentry events are flushed with a 2 second timeout. You should call Close before app shutdown. Close doesn't call os.Exit.
 
 <a name="GetTraceHeaderName"></a>
-## func [GetTraceHeaderName](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L93>)
+## func [GetTraceHeaderName](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L104>)
 
 ```go
 func GetTraceHeaderName() string
@@ -57,7 +59,7 @@ func GetTraceHeaderName() string
 GetTraceHeaderName gets the header name for trace id default is x\-trace\-id
 
 <a name="GetTraceId"></a>
-## func [GetTraceId](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L553>)
+## func [GetTraceId](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L590>)
 
 ```go
 func GetTraceId(ctx context.Context) string
@@ -66,7 +68,7 @@ func GetTraceId(ctx context.Context) string
 GetTraceId fetches traceID from context if no trace id is found then it will return empty string
 
 <a name="InitAirbrake"></a>
-## func [InitAirbrake](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L113>)
+## func [InitAirbrake](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L124>)
 
 ```go
 func InitAirbrake(projectID int64, projectKey string)
@@ -75,7 +77,7 @@ func InitAirbrake(projectID int64, projectKey string)
 InitAirbrake inits airbrake configuration projectID: airbrake project id projectKey: airbrake project key
 
 <a name="InitRollbar"></a>
-## func [InitRollbar](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L124>)
+## func [InitRollbar](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L135>)
 
 ```go
 func InitRollbar(token, env string)
@@ -84,7 +86,7 @@ func InitRollbar(token, env string)
 InitRollbar inits rollbar configuration token: rollbar token env: rollbar environment
 
 <a name="InitSentry"></a>
-## func [InitSentry](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L156>)
+## func [InitSentry](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L167>)
 
 ```go
 func InitSentry(dsn string)
@@ -93,7 +95,7 @@ func InitSentry(dsn string)
 InitSentry inits sentry configuration dsn: sentry dsn
 
 <a name="Notify"></a>
-## func [Notify](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L254>)
+## func [Notify](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L265>)
 
 ```go
 func Notify(err error, rawData ...interface{}) error
@@ -102,7 +104,7 @@ func Notify(err error, rawData ...interface{}) error
 Notify notifies error to airbrake, rollbar and sentry if they are inited and error is not ignored err: error to notify rawData: extra data to notify with error \(can be context.Context, Tags, or any other data\) when rawData is context.Context, it will used to get extra data from loggers.FromContext\(ctx\) and tags from metadata
 
 <a name="NotifyAsync"></a>
-## func [NotifyAsync](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L66>)
+## func [NotifyAsync](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L77>)
 
 ```go
 func NotifyAsync(err error, rawData ...interface{}) error
@@ -111,7 +113,7 @@ func NotifyAsync(err error, rawData ...interface{}) error
 NotifyAsync sends an error notification asynchronously with bounded concurrency. If the async notification pool is full, the notification is dropped to prevent goroutine explosion under sustained error bursts. Returns the original error for convenience.
 
 <a name="NotifyOnPanic"></a>
-## func [NotifyOnPanic](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L455>)
+## func [NotifyOnPanic](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L465>)
 
 ```go
 func NotifyOnPanic(rawData ...interface{})
@@ -120,7 +122,7 @@ func NotifyOnPanic(rawData ...interface{})
 NotifyOnPanic notifies error to airbrake, rollbar and sentry if they are inited and error is not ignored rawData: extra data to notify with error \(can be context.Context, Tags, or any other data\) when rawData is context.Context, it will used to get extra data from loggers.FromContext\(ctx\) and tags from metadata this function should be called in defer example: defer NotifyOnPanic\(ctx, "some data"\) example: defer NotifyOnPanic\(ctx, "some data", Tags\{"tag1": "value1"\}\)
 
 <a name="NotifyWithExclude"></a>
-## func [NotifyWithExclude](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L424>)
+## func [NotifyWithExclude](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L434>)
 
 ```go
 func NotifyWithExclude(err error, rawData ...interface{}) error
@@ -129,7 +131,7 @@ func NotifyWithExclude(err error, rawData ...interface{}) error
 NotifyWithExclude notifies error to airbrake, rollbar and sentry if they are inited and error is not ignored err: error to notify rawData: extra data to notify with error \(can be context.Context, Tags, or any other data\) when rawData is context.Context, it will used to get extra data from loggers.FromContext\(ctx\) and tags from metadata
 
 <a name="NotifyWithLevel"></a>
-## func [NotifyWithLevel](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L263>)
+## func [NotifyWithLevel](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L274>)
 
 ```go
 func NotifyWithLevel(err error, level string, rawData ...interface{}) error
@@ -138,7 +140,7 @@ func NotifyWithLevel(err error, level string, rawData ...interface{}) error
 NotifyWithLevel notifies error to airbrake, rollbar and sentry if they are inited and error is not ignored err: error to notify level: error level rawData: extra data to notify with error \(can be context.Context, Tags, or any other data\) when rawData is context.Context, it will used to get extra data from loggers.FromContext\(ctx\) and tags from metadata
 
 <a name="NotifyWithLevelAndSkip"></a>
-## func [NotifyWithLevelAndSkip](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L314>)
+## func [NotifyWithLevelAndSkip](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L325>)
 
 ```go
 func NotifyWithLevelAndSkip(err error, skip int, level string, rawData ...interface{}) error
@@ -147,7 +149,7 @@ func NotifyWithLevelAndSkip(err error, skip int, level string, rawData ...interf
 NotifyWithLevelAndSkip notifies error to airbrake, rollbar and sentry if they are inited and error is not ignored err: error to notify skip: skip stack frames when notify error level: error level rawData: extra data to notify with error \(can be context.Context, Tags, or any other data\) when rawData is context.Context, it will used to get extra data from loggers.FromContext\(ctx\) and tags from metadata
 
 <a name="SetEnvironment"></a>
-## func [SetEnvironment](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L504>)
+## func [SetEnvironment](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L514>)
 
 ```go
 func SetEnvironment(env string)
@@ -156,7 +158,7 @@ func SetEnvironment(env string)
 SetEnvironment sets the environment. The environment is used to distinguish errors occurring in different
 
 <a name="SetHostname"></a>
-## func [SetHostname](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L589>)
+## func [SetHostname](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L670>)
 
 ```go
 func SetHostname(name string)
@@ -165,16 +167,16 @@ func SetHostname(name string)
 SetHostname sets the hostname of the server. The hostname is used to identify the server that logged an error.
 
 <a name="SetMaxAsyncNotifications"></a>
-## func [SetMaxAsyncNotifications](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L54>)
+## func [SetMaxAsyncNotifications](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L64>)
 
 ```go
 func SetMaxAsyncNotifications(n int)
 ```
 
-SetMaxAsyncNotifications sets the maximum number of concurrent async notification goroutines. When the limit is reached, new async notifications are dropped to prevent goroutine explosion under sustained error bursts. Default is 1000. Can only be called once; subsequent calls are no\-ops.
+SetMaxAsyncNotifications sets the maximum number of concurrent async notification goroutines. When the limit is reached, new async notifications are dropped to prevent goroutine explosion under sustained error bursts. Default is 20. The first successful call wins; subsequent calls are no\-ops. It is safe to call concurrently with NotifyAsync.
 
 <a name="SetRelease"></a>
-## func [SetRelease](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L517>)
+## func [SetRelease](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L527>)
 
 ```go
 func SetRelease(rel string)
@@ -183,7 +185,7 @@ func SetRelease(rel string)
 SetRelease sets the release tag. The release tag is used to group errors together by release.
 
 <a name="SetServerRoot"></a>
-## func [SetServerRoot](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L583>)
+## func [SetServerRoot](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L664>)
 
 ```go
 func SetServerRoot(path string)
@@ -192,25 +194,43 @@ func SetServerRoot(path string)
 SetServerRoot sets the root directory of the project. The root directory is used to trim prefixes from filenames in stack traces.
 
 <a name="SetTraceHeaderName"></a>
-## func [SetTraceHeaderName](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L87>)
+## func [SetTraceHeaderName](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L98>)
 
 ```go
 func SetTraceHeaderName(name string)
 ```
 
 SetTraceHeaderName sets the header name for trace id default is x\-trace\-id
 
+<a name="SetTraceIDValidator"></a>
+## func [SetTraceIDValidator](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L619>)
+
+```go
+func SetTraceIDValidator(fn func(string) string)
+```
+
+SetTraceIDValidator sets a custom trace ID validation function. The function receives a raw trace ID and must return the sanitized version. Returning an empty string triggers the standard trace ID resolution flow \(existing ctx → gRPC metadata → OTEL span trace ID → generate UUID\), not direct generation. Set to nil to disable validation entirely \(not recommended\). Must be called during init — not safe for concurrent use.
+
 <a name="SetTraceId"></a>
-## func [SetTraceId](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L524>)
+## func [SetTraceId](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L583>)
 
 ```go
 func SetTraceId(ctx context.Context) context.Context
 ```
 
 SetTraceId updates the traceID based on context values if no trace id is found then it will create one and update the context You should use the context returned by this function instead of the one passed
 
+<a name="SetTraceIdWithValue"></a>
+## func [SetTraceIdWithValue](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L535>)
+
+```go
+func SetTraceIdWithValue(ctx context.Context) (context.Context, string)
+```
+
+SetTraceIdWithValue is like SetTraceId but also returns the resolved trace ID, avoiding a separate GetTraceId call. Callers must use the returned context, not the original ctx, so the stored trace ID is preserved in options and log context.
+
 <a name="UpdateTraceId"></a>
-## func [UpdateTraceId](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L573>)
+## func [UpdateTraceId](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L651>)
 
 ```go
 func UpdateTraceId(ctx context.Context, traceID string) context.Context
@@ -219,7 +239,7 @@ func UpdateTraceId(ctx context.Context, traceID string) context.Context
 UpdateTraceId force updates the traced id to provided id if no trace id is found then it will create one and update the context You should use the context returned by this function instead of the one passed
 
 <a name="Tags"></a>
-## type [Tags](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L102>)
+## type [Tags](<https://github.com/go-coldbrew/errors/blob/main/notifier/notifier.go#L113>)