Documentation
¶
Overview ¶
Package errors defines shared sentinel errors used by go-service token implementations.
This package centralizes common token validation failures so callers can:
- Check classes of failures consistently across token kinds (JWT, PASETO, SSH, etc.), typically via errors.Is.
- Avoid importing implementation-specific packages just to compare error values.
- Map token failures to transport-appropriate responses (for example HTTP 401/403, gRPC status codes, audit events, or metrics dimensions).
Sentinel errors and matching ¶
The exported variables in this package are intended to be used as sentinel errors. Token implementations should wrap these errors (for example using fmt.Errorf with %w or a helper that preserves an error chain) so callers can detect the failure reason while still preserving additional context.
Example:
if errors.Is(err, tokenerrors.ErrInvalidAudience) {
// audience claim did not match expected audience
}
Meaning of common errors ¶
While concrete semantics are implementation-defined, the sentinels in this package generally correspond to:
- ErrInvalidMatch: cryptographic or structural mismatch (signature/MAC mismatch, invalid encoding, etc.).
- ErrInvalidIssuer: issuer ("iss") claim mismatch.
- ErrInvalidAudience: audience ("aud") claim mismatch.
- ErrInvalidAlgorithm: algorithm mismatch (token signed/encrypted with an unexpected algorithm).
- ErrInvalidKeyID: missing or unexpected key identifier (for example JWT "kid").
- ErrInvalidTime: time validity failure (expired, not-before in the future, etc.).
Notes ¶
This package does not provide error constructors or formatting helpers. If you need to attach more context (which claim failed, expected vs. actual, key name, etc.), wrap the sentinel error in the implementation package and preserve it in the error chain.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidMatch is a sentinel error indicating a token comparison failed to match. // // Implementations typically use this for cryptographic or structural mismatches // (for example signature/MAC mismatch, invalid encoding, etc.) and should wrap // this error so callers can detect it via errors.Is while still preserving context. ErrInvalidMatch = errors.New("token: invalid match") // ErrInvalidIssuer is a sentinel error indicating the issuer claim is invalid. // // For claim-based token formats, this commonly corresponds to an "iss" claim // mismatch. Implementations should wrap this error to preserve additional context. ErrInvalidIssuer = errors.New("token: invalid issuer") // ErrInvalidAudience is a sentinel error indicating the audience claim is invalid. // // For claim-based token formats, this commonly corresponds to an "aud" claim // mismatch. Implementations should wrap this error to preserve additional context. ErrInvalidAudience = errors.New("token: invalid audience") // ErrInvalidAlgorithm is a sentinel error indicating the token used an unexpected algorithm. // // Implementations may return or wrap this when a token is signed/encrypted with an // algorithm that does not match the expected configuration. ErrInvalidAlgorithm = errors.New("token: invalid algorithm") // ErrInvalidKeyID is a sentinel error indicating a key identifier is missing or unexpected. // // This is commonly used for JWT verification when the "kid" header is missing or // does not match the expected configured key ID. ErrInvalidKeyID = errors.New("token: invalid key id") // ErrInvalidTime is a sentinel error indicating a token is not valid for the current time. // // This commonly covers expiration and not-before failures (for example expired tokens // or tokens that are not yet valid). ErrInvalidTime = errors.New("token: invalid time") )
Functions ¶
This section is empty.
Types ¶
This section is empty.
Source Files