feat: webhook + SSO secret helpers (HMAC verification)

The server side of talking to Discourse, all stdlib crypto:
VerifyWebhook checks X-Discourse-Event-Signature (sha256 HMAC hex,
constant-time, with or without the sha256= prefix) over the raw
body; ParseWebhook/WebhookHandler turn that into a drop-in
http.HandlerFunc that 403s mis-signed deliveries before dispatch.
VerifySSO decodes + verifies a Discourse Connect login redirect
(HMAC over the base64 string), BuildSSOResponse signs the identity
answer (nonce + email/external_id/username/...), and SSOLogin does
the whole dance in one call, returning the redirect URL. Secrets
load from DISCOURSE_WEBHOOK_SECRET / DISCOURSE_SSO_SECRET, are
trimmed, never logged and never echoed in errors.

Part of Redmine 507 (Discourse Go client): the webhook helper is
what the fleet receiver and 495 delivery loop verify pushes with.
This commit is contained in:
2026-08-29 16:43:59 -05:00
parent 6891f3febc
commit 5bbb307b12
2 changed files with 432 additions and 0 deletions
+204
View File
@@ -0,0 +1,204 @@
// Webhook + SSO helpers: the secret-handling side of talking to
// Discourse from a server.
//
// Webhooks: Discourse signs each delivery's raw body with the webhook
// secret as HMAC-SHA256 hex in X-Discourse-Event-Signature (with a
// "sha256=" prefix). Never trust an unsigned or mis-signed delivery —
// the endpoint is internet-facing by nature.
//
// SSO (Discourse Connect): Discourse redirects users to your site with
// ?sso=<base64 payload>&sig=<hex HMAC-SHA256 of that base64 string>
// signed with the shared SSO secret; you answer by redirecting back to
// return_sso_url with a payload signed the same way.
//
// Secrets arrive via environment (DISCOURSE_WEBHOOK_SECRET /
// DISCOURSE_SSO_SECRET, see WebhookSecretFromEnv / SSOSecretFromEnv) —
// never flags, never arguments, never logged, never echoed in errors.
package discourse
import (
"context"
"crypto/hmac"
"crypto/sha256"
"encoding/base64"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"io"
"net/http"
"net/url"
"os"
"strings"
)
// ErrBadSignature: HMAC verification failed (webhook or SSO). The
// payload must be treated as attacker-controlled and dropped.
var ErrBadSignature = errors.New("discourse: bad signature")
// WebhookSecretFromEnv reads DISCOURSE_WEBHOOK_SECRET (trimmed).
func WebhookSecretFromEnv() ([]byte, error) {
return secretFromEnv("DISCOURSE_WEBHOOK_SECRET")
}
// SSOSecretFromEnv reads DISCOURSE_SSO_SECRET (trimmed).
func SSOSecretFromEnv() ([]byte, error) {
return secretFromEnv("DISCOURSE_SSO_SECRET")
}
func secretFromEnv(name string) ([]byte, error) {
v := strings.TrimSpace(os.Getenv(name))
if v == "" {
return nil, fmt.Errorf("%w: %s is not set", ErrInvalidRequest, name)
}
return []byte(v), nil
}
// VerifyWebhook checks a Discourse webhook signature: HMAC-SHA256 hex
// digest of the raw request body under secret, constant-time compared.
// Discourse sends the digest with a "sha256=" prefix; both forms pass.
func VerifyWebhook(secret, body []byte, signature string) error {
sig := strings.TrimPrefix(strings.TrimSpace(signature), "sha256=")
want, err := hex.DecodeString(sig)
if err != nil || len(want) != sha256.Size {
return fmt.Errorf("%w: signature is not a sha256 hex digest", ErrBadSignature)
}
m := hmac.New(sha256.New, secret)
m.Write(body)
if !hmac.Equal(want, m.Sum(nil)) {
return ErrBadSignature
}
return nil
}
// WebhookEvent is one verified webhook delivery.
type WebhookEvent struct {
ID string // X-Discourse-Event-Id (delivery id)
Type string // X-Discourse-Event-Type ("post", "topic", "user", ...)
Event string // X-Discourse-Event ("post_created", ...)
Body json.RawMessage // raw JSON payload, unmodified
}
// ParseWebhook verifies and decodes an incoming webhook request. It
// consumes r.Body, so wrap with http.MaxBytesReader first if the
// endpoint is exposed. Signature failure returns ErrBadSignature.
func ParseWebhook(secret []byte, r *http.Request) (*WebhookEvent, error) {
body, err := io.ReadAll(io.LimitReader(r.Body, 8<<20))
if err != nil {
return nil, fmt.Errorf("%w: read body: %v", ErrUnreachable, err)
}
if err := VerifyWebhook(secret, body, r.Header.Get("X-Discourse-Event-Signature")); err != nil {
return nil, err
}
if !json.Valid(body) {
return nil, fmt.Errorf("%w: payload is not JSON", ErrMalformedResponse)
}
return &WebhookEvent{
ID: r.Header.Get("X-Discourse-Event-Id"),
Type: r.Header.Get("X-Discourse-Event-Type"),
Event: r.Header.Get("X-Discourse-Event"),
Body: json.RawMessage(body),
}, nil
}
// WebhookHandler adapts ParseWebhook to net/http: bad signatures get
// 403 and are never dispatched; verified deliveries go to next, which
// must not panic-write after the handler returns.
func WebhookHandler(secret []byte, next func(*WebhookEvent)) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
evt, err := ParseWebhook(secret, r)
if err != nil {
http.Error(w, "invalid signature", http.StatusForbidden)
return
}
next(evt)
w.WriteHeader(http.StatusOK)
}
}
// VerifySSO verifies a Discourse Connect (SSO) login redirect: sso is
// the base64 payload, sig the hex HMAC-SHA256 of the base64 string
// (not of the decoded payload). Returns the payload's fields — always
// nonce and return_sso_url.
func VerifySSO(secret []byte, sso, sig string) (url.Values, error) {
sigBytes, err := hex.DecodeString(strings.TrimSpace(sig))
if err != nil || len(sigBytes) != sha256.Size {
return nil, fmt.Errorf("%w: sso signature is not a sha256 hex digest", ErrBadSignature)
}
m := hmac.New(sha256.New, secret)
m.Write([]byte(sso))
if !hmac.Equal(sigBytes, m.Sum(nil)) {
return nil, ErrBadSignature
}
raw, err := base64.StdEncoding.DecodeString(sso)
if err != nil {
return nil, fmt.Errorf("%w: sso payload is not base64: %v", ErrBadSignature, err)
}
vals, err := url.ParseQuery(string(raw))
if err != nil {
return nil, fmt.Errorf("%w: sso payload is not a querystring: %v", ErrBadSignature, err)
}
return vals, nil
}
// BuildSSOResponse builds the signed response payload: nonce (copied
// from the incoming request) plus the identity fields Discourse accepts
// (email, external_id, username, name, avatar_url, admin, moderator,
// add_groups, remove_groups, ...). Returns the base64 payload and its
// hex signature, ready for SSORedirectURL.
func BuildSSOResponse(secret []byte, nonce string, params map[string]string) (string, string, error) {
if strings.TrimSpace(nonce) == "" {
return "", "", fmt.Errorf("%w: sso response requires the request's nonce", ErrInvalidRequest)
}
vals := url.Values{}
vals.Set("nonce", nonce)
for k, v := range params {
if v != "" {
vals.Set(k, v)
}
}
raw := vals.Encode()
b64 := base64.StdEncoding.EncodeToString([]byte(raw))
m := hmac.New(sha256.New, secret)
m.Write([]byte(b64))
return b64, hex.EncodeToString(m.Sum(nil)), nil
}
// SSORedirectURL assembles the return redirect: returnURL with sso and
// sig query parameters appended.
func SSORedirectURL(returnURL, sso, sig string) (string, error) {
u, err := url.Parse(returnURL)
if err != nil || u.Scheme == "" || u.Host == "" {
return "", fmt.Errorf("%w: return_sso_url %q is not absolute", ErrInvalidRequest, returnURL)
}
q := u.Query()
q.Set("sso", sso)
q.Set("sig", sig)
u.RawQuery = q.Encode()
return u.String(), nil
}
// SSOLogin is the full server-side SSO dance for one request: verify
// the incoming sso/sig pair, build the signed response with the user's
// identity, and return the URL to redirect the user's browser to.
// The context is unused today (pure crypto) but keeps the signature
// future-proof for lookups (e.g. fetching the external user's groups).
func SSOLogin(ctx context.Context, secret []byte, sso, sig string, params map[string]string) (string, error) {
vals, err := VerifySSO(secret, sso, sig)
if err != nil {
return "", err
}
nonce := vals.Get("nonce")
if nonce == "" {
return "", fmt.Errorf("%w: sso payload carries no nonce", ErrBadSignature)
}
returnURL := vals.Get("return_sso_url")
if returnURL == "" {
return "", fmt.Errorf("%w: sso payload carries no return_sso_url", ErrBadSignature)
}
b64, respSig, err := BuildSSOResponse(secret, nonce, params)
if err != nil {
return "", err
}
return SSORedirectURL(returnURL, b64, respSig)
}
+228
View File
@@ -0,0 +1,228 @@
package discourse
import (
"bytes"
"crypto/hmac"
"crypto/sha256"
"encoding/base64"
"encoding/hex"
"encoding/json"
"errors"
"net/http"
"net/http/httptest"
"net/url"
"strings"
"testing"
)
const testWebhookSecret = "whsec-test-0123456789"
const testSSOSecret = "ssosec-test-0123456789"
func hmacHex(secret string, data []byte) string {
m := hmac.New(sha256.New, []byte(secret))
m.Write(data)
return hex.EncodeToString(m.Sum(nil))
}
// --- webhook payload verification ---
func TestVerifyWebhookGoodSignature(t *testing.T) {
body := []byte(`{"post":{"id":55,"topic_id":12}}`)
sig := hmacHex(testWebhookSecret, body)
if err := VerifyWebhook([]byte(testWebhookSecret), body, sig); err != nil {
t.Fatalf("good sig rejected: %v", err)
}
if err := VerifyWebhook([]byte(testWebhookSecret), body, "sha256="+sig); err != nil {
t.Fatalf("sha256=-prefixed sig rejected: %v", err)
}
}
func TestVerifyWebhookBadSignature(t *testing.T) {
body := []byte(`{"post":{"id":55}}`)
err := VerifyWebhook([]byte(testWebhookSecret), body, "deadbeef")
if !errors.Is(err, ErrBadSignature) {
t.Fatalf("want ErrBadSignature, got %v", err)
}
err = VerifyWebhook([]byte("other-secret"), body, hmacHex(testWebhookSecret, body))
if !errors.Is(err, ErrBadSignature) {
t.Fatalf("wrong secret must fail, got %v", err)
}
if err := VerifyWebhook([]byte(testWebhookSecret), nil, ""); !errors.Is(err, ErrBadSignature) {
t.Fatalf("empty signature must fail, got %v", err)
}
}
func TestParseWebhookVerifiesAndExtracts(t *testing.T) {
body := []byte(`{"post":{"id":55,"post_number":2}}`)
req := httptest.NewRequest(http.MethodPost, "/hooks/discourse", bytes.NewReader(body))
req.Header.Set("X-Discourse-Event-Id", "0d8417a0-1c2b-4d7b")
req.Header.Set("X-Discourse-Event-Type", "post")
req.Header.Set("X-Discourse-Event", "post_created")
req.Header.Set("X-Discourse-Event-Signature", "sha256="+hmacHex(testWebhookSecret, body))
evt, err := ParseWebhook([]byte(testWebhookSecret), req)
if err != nil {
t.Fatalf("ParseWebhook: %v", err)
}
if evt.ID != "0d8417a0-1c2b-4d7b" || evt.Type != "post" || evt.Event != "post_created" {
t.Fatalf("headers not extracted: %+v", evt)
}
var payload struct {
Post struct {
ID int `json:"id"`
PostNumber int `json:"post_number"`
} `json:"post"`
}
if err := json.Unmarshal(evt.Body, &payload); err != nil {
t.Fatalf("body not preserved: %v", err)
}
if payload.Post.ID != 55 || payload.Post.PostNumber != 2 {
t.Fatalf("body mangled: %s", evt.Body)
}
}
func TestWebhookHandlerRejectsAndAccepts(t *testing.T) {
body := []byte(`{"topic":{"id":12}}`)
got := 0
h := WebhookHandler([]byte(testWebhookSecret), func(evt *WebhookEvent) { got++ })
r := httptest.NewRequest(http.MethodPost, "/", bytes.NewReader(body))
r.Header.Set("X-Discourse-Event-Signature", hmacHex("wrong", body))
w := httptest.NewRecorder()
h(w, r)
if w.Code != http.StatusForbidden || got != 0 {
t.Fatalf("bad sig: want 403 + no dispatch, got %d dispatch=%d", w.Code, got)
}
r = httptest.NewRequest(http.MethodPost, "/", bytes.NewReader(body))
r.Header.Set("X-Discourse-Event-Signature", "sha256="+hmacHex(testWebhookSecret, body))
r.Header.Set("X-Discourse-Event", "topic_created")
w = httptest.NewRecorder()
h(w, r)
if w.Code != http.StatusOK || got != 1 {
t.Fatalf("good sig: want 200 + dispatch, got %d dispatch=%d", w.Code, got)
}
}
// --- SSO (Discourse Connect) ---
func ssoPayload(t *testing.T, fields string) (string, string) {
t.Helper()
b64 := base64.StdEncoding.EncodeToString([]byte(fields))
return b64, hmacHex(testSSOSecret, []byte(b64))
}
func TestVerifySSO(t *testing.T) {
b64, sig := ssoPayload(t, "nonce=cb68251eefb35f7e&return_sso_url=https%3A%2F%2Fapp.example.test%2Fsso%2Fcallback")
vals, err := VerifySSO([]byte(testSSOSecret), b64, sig)
if err != nil {
t.Fatalf("VerifySSO: %v", err)
}
if vals.Get("nonce") != "cb68251eefb35f7e" {
t.Fatalf("nonce not decoded: %q", vals.Get("nonce"))
}
if vals.Get("return_sso_url") != "https://app.example.test/sso/callback" {
t.Fatalf("return url not decoded: %q", vals.Get("return_sso_url"))
}
}
func TestVerifySSORejectsTampering(t *testing.T) {
b64, sig := ssoPayload(t, "nonce=abc")
if _, err := VerifySSO([]byte(testSSOSecret), b64+"x", sig); !errors.Is(err, ErrBadSignature) {
t.Fatalf("tampered payload must fail, got %v", err)
}
if _, err := VerifySSO([]byte("other"), b64, sig); !errors.Is(err, ErrBadSignature) {
t.Fatalf("wrong secret must fail, got %v", err)
}
if _, err := VerifySSO([]byte(testSSOSecret), "!!not-base64!!", sig); err == nil {
t.Fatal("undecodable payload must fail")
}
if _, err := VerifySSO([]byte(testSSOSecret), "", ""); !errors.Is(err, ErrBadSignature) {
t.Fatalf("empty sso/sig must fail, got %v", err)
}
}
func TestBuildSSOResponseRoundTrip(t *testing.T) {
b64, sig, err := BuildSSOResponse([]byte(testSSOSecret), "cb68251eefb35f7e", map[string]string{
"email": "charles@turnsys.com",
"external_id": "7",
"username": "reachableceo",
"admin": "true",
})
if err != nil {
t.Fatalf("BuildSSOResponse: %v", err)
}
vals, err := VerifySSO([]byte(testSSOSecret), b64, sig)
if err != nil {
t.Fatalf("round-trip verify: %v", err)
}
for k, want := range map[string]string{
"nonce": "cb68251eefb35f7e", "email": "charles@turnsys.com",
"external_id": "7", "username": "reachableceo", "admin": "true",
} {
if got := vals.Get(k); got != want {
t.Fatalf("field %s: want %q got %q", k, want, got)
}
}
if _, err := base64.StdEncoding.DecodeString(b64); err != nil {
t.Fatalf("response not std base64: %v", err)
}
}
func TestBuildSSOResponseRequiresNonce(t *testing.T) {
if _, _, err := BuildSSOResponse([]byte(testSSOSecret), "", map[string]string{"email": "x@y.test"}); !errors.Is(err, ErrInvalidRequest) {
t.Fatalf("empty nonce: want ErrInvalidRequest, got %v", err)
}
}
func TestSSORedirectURL(t *testing.T) {
u, err := SSORedirectURL("https://app.example.test/sso/callback", "c29tZXBheWxvYWQ=", "aabbcc")
if err != nil {
t.Fatalf("SSORedirectURL: %v", err)
}
parsed, err := url.Parse(u)
if err != nil {
t.Fatalf("parse: %v", err)
}
if parsed.Scheme != "https" || parsed.Host != "app.example.test" {
t.Fatalf("host mangled: %s", u)
}
q := parsed.Query()
if q.Get("sso") != "c29tZXBheWxvYWQ=" || q.Get("sig") != "aabbcc" {
t.Fatalf("query mangled: %s", u)
}
}
// --- secret loading from env ---
func TestSecretsFromEnv(t *testing.T) {
t.Setenv("DISCOURSE_WEBHOOK_SECRET", " hook-secret ")
t.Setenv("DISCOURSE_SSO_SECRET", " sso-secret ")
wh, err := WebhookSecretFromEnv()
if err != nil || string(wh) != "hook-secret" {
t.Fatalf("webhook secret: %q %v", wh, err)
}
sso, err := SSOSecretFromEnv()
if err != nil || string(sso) != "sso-secret" {
t.Fatalf("sso secret: %q %v", sso, err)
}
}
func TestSecretsFromEnvMissing(t *testing.T) {
t.Setenv("DISCOURSE_WEBHOOK_SECRET", "")
t.Setenv("DISCOURSE_SSO_SECRET", "")
if _, err := WebhookSecretFromEnv(); !errors.Is(err, ErrInvalidRequest) {
t.Fatalf("missing webhook secret: want ErrInvalidRequest, got %v", err)
}
if _, err := SSOSecretFromEnv(); !errors.Is(err, ErrInvalidRequest) {
t.Fatalf("missing sso secret: want ErrInvalidRequest, got %v", err)
}
}
func TestWebhookSecretNeverLeaksInError(t *testing.T) {
body := []byte(`{}`)
err := VerifyWebhook([]byte(testWebhookSecret), body, "bad")
if strings.Contains(err.Error(), testWebhookSecret) {
t.Fatalf("secret leaked in error: %v", err)
}
}