webhookauth

package
v1.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: AGPL-3.0 Imports: 18 Imported by: 0

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

View Source
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.

View Source
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.

View Source
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

View Source
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.

View Source
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 Basic

func Basic(r *http.Request, user, password string) error

Basic checks HTTP basic auth against user and password.

func Decode

func Decode(sig, encoding string) ([]byte, error)

Decode decodes a signature in hex (default) or base64 (standard or URL alphabet, padded or not).

func Equal

func Equal(got, want string) bool

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 Fresh

func Fresh(ts string, now time.Time) error

Fresh checks a Unix timestamp in seconds (or milliseconds) is within Tolerance of now.

func HMAC

func HMAC(h func() hash.Hash, key []byte, parts ...[]byte) []byte

HMAC computes the HMAC of the parts with key.

func Hash

func Hash(alg string) (func() hash.Hash, error)

Hash returns the hash for an HMAC algorithm name: sha256 (also the default for ""), sha1 or sha512.

func Key

func Key(parts ...string) string

Key identifies an entry by what selects the material: the API's base URL, the API key, the webhook's path.

func SignStandard

func SignStandard(secret, id, ts string, body []byte) (string, error)

SignStandard returns the webhook-signature value for a Standard Webhooks payload, for tests and for webhook test events.

func Standard

func Standard(secret string, h http.Header, body []byte, now time.Time) error

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

func StandardKey(secret string) ([]byte, error)

StandardKey decodes a Standard Webhooks secret ("whsec_" + base64).

func Within

func Within(ts string, now time.Time, window time.Duration) error

Within checks a Unix timestamp in seconds (or milliseconds) is at most window old and at most Tolerance ahead of now, for providers that retry a delivery with its first signature for hours.

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

func (c *Material) Set(key, value string)

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL