Documentation
¶
Overview ¶
Package webhookauth holds the webhook authentication schemes several sending providers share, so each adapter verifies them the same way: Standard Webhooks (the Svix scheme Resend uses), HMAC signatures over the body, and shared secrets sent as basic auth or in a header. Every check is constant-time and fails with providers.ErrBadSignature.
Index ¶
- Constants
- Variables
- func Basic(r *http.Request, user, password string) error
- func Decode(sig, encoding string) ([]byte, error)
- func Equal(got, want string) bool
- func Fresh(ts string, now time.Time) error
- func HMAC(h func() hash.Hash, key []byte, parts ...[]byte) []byte
- func Hash(alg string) (func() hash.Hash, error)
- func Key(parts ...string) string
- func SignStandard(secret, id, ts string, body []byte) (string, error)
- func Standard(secret string, h http.Header, body []byte, now time.Time) error
- func StandardKey(secret string) ([]byte, error)
- func Within(ts string, now time.Time, window time.Duration) error
- type Material
- type Replay
Constants ¶
const MaxAge = time.Hour
MaxAge is how long material read from a provider is trusted before it is read again, so a secret or key the provider rotated out (after a leak, say) stops verifying requests.
const Refetch = time.Minute
Refetch is the least time between two reads of one entry: a flood of badly signed requests causes at most one provider API call a minute.
const Tolerance = 5 * time.Minute
Tolerance is how far a signed timestamp may be from now before the request is treated as a replay.
Variables ¶
var ErrReplayed = fmt.Errorf("%w: the signature was already used with another payload", providers.ErrBadSignature)
ErrReplayed is a signed token used again with another payload: a captured signature carrying a forged event. It wraps providers.ErrBadSignature.
var ErrStale = fmt.Errorf("%w: the signed timestamp is outside the accepted window", providers.ErrBadSignature)
ErrStale is a signed timestamp outside the accepted window (a replay, or a clock that is off); it wraps providers.ErrBadSignature.
Functions ¶
func Decode ¶
Decode decodes a signature in hex (default) or base64 (standard or URL alphabet, padded or not).
func Equal ¶
Equal compares two secrets in constant time. An empty expected secret never matches, so a provider without a configured secret rejects everything instead of accepting everything.
func Hash ¶
Hash returns the hash for an HMAC algorithm name: sha256 (also the default for ""), sha1 or sha512.
func Key ¶
Key identifies an entry by what selects the material: the API's base URL, the API key, the webhook's path.
func SignStandard ¶
SignStandard returns the webhook-signature value for a Standard Webhooks payload, for tests and for webhook test events.
func Standard ¶
Standard verifies a Standard Webhooks request (standardwebhooks.com, the scheme Svix signs with): the headers webhook-id, webhook-timestamp and webhook-signature (or their svix- equivalents) and an HMAC-SHA256 over "id.timestamp.body" with the base64 secret that follows "whsec_". The signature header lists one or more "v1,<base64>" entries; any may match, so secrets can be rotated. A zero now skips the timestamp check.
func StandardKey ¶
StandardKey decodes a Standard Webhooks secret ("whsec_" + base64).
Types ¶
type Material ¶
type Material struct {
// Now is the clock, replaced in tests.
Now func() time.Time
// contains filtered or unexported fields
}
Material caches signing material adapters read from their provider's API (a webhook's signing secret or public key, an identity provider's key set), shared by every adapter instance: the factory builds one per request. Entries are keyed by a hash (see Key), so no credential is kept as a map key. The zero value is ready to use.
func (*Material) Set ¶
Set stores material the provider just returned (when the webhook is registered), saving a read on the first request.
func (*Material) Verify ¶
func (c *Material) Verify(ctx context.Context, key string, fetch func(context.Context) (string, error), check func(material string) error) error
Verify runs check with the material cached under key, read with fetch when needed. When check fails, the material is read again (at most once per Refetch) in case the provider rotated it, and checked once more. Every failure wraps providers.ErrBadSignature, a failed read included: a request that could not be verified is never trusted.
type Replay ¶
type Replay struct {
// Window is how old a signed timestamp may be (Within).
Window time.Duration
// contains filtered or unexported fields
}
Replay ties each signed one-time token to the payload it first came with, for schemes whose signature covers a token but not the payload (Mailgun's): a token is honored again with the same payload (a redelivery, which ingest's dedupe drops) but never with another, so a captured signature can't carry a forged event. Call Check only once the signature verified, so only the provider's own tokens are kept.
The ties are kept in a providers.TokenStore (ReputeCast's database), where every process and every restart sees them, for as long as a signature with the token can be accepted. Memory only remembers what this process saw, to answer again without asking the store. Without a store (unit tests) memory is all there is, and once it is full new tokens are refused rather than let through untied.
func (*Replay) Check ¶
func (r *Replay) Check(ctx context.Context, store providers.TokenStore, scope, token string, payload []byte, now time.Time) error
Check ties token to payload within scope (the adapter), or fails with ErrReplayed when the token is tied to another payload. The tie lasts as long as a signature with the token can be accepted: Within's window, signed up to Tolerance ahead. A store that can't be reached fails with an error wrapping providers.ErrUnavailable: the provider is asked to deliver again, rather than the event stored unchecked.