refactor(webhook): authenticate /v1/invoke with bearer token

Swap the bespoke X-Mithras-Token header for a standard
"Authorization: Bearer <token>" challenge. The scheme match is
case-insensitive per RFC 7235 and the token comparison stays
constant-time. 401 responses now include
WWW-Authenticate: Bearer realm="mithras" so clients can react
correctly. Tests cover the new parser's edge cases (missing
header, wrong scheme, empty token, mixed-case scheme).

Assisted-by: Claude Opus 4.7 via Claude Code
Signed-off-by: Xe Iaso <xe@tigrisdata.com>

Author: Xe

docs/architecture.md

@@ -143,8 +143,9 @@ HTTP-facing pieces of `webhookd`:
 
 - `Router` wires `POST /v1/invoke` (auth-required) and `GET /healthz`,
   with `recover500` and `requestLog` middleware on top.
-- `requireToken` does constant-time comparison of the `X-Mithras-Token`
-  header against the shared secret.
+- `requireToken` extracts the token from an `Authorization: Bearer …`
+  header and constant-time compares it against the shared secret. Failed
+  requests get a `WWW-Authenticate: Bearer realm="mithras"` response.
 - `AgentRunner` builds a fresh `agentloop.Impl` per request so conversation
   histories do not bleed between webhooks.
 - `BackgroundLauncher` spawns each runner call on a `sync.WaitGroup` so

internal/webhook/handler.go

@@ -26,8 +26,8 @@ type InvokeResponse struct {
 
 // Router returns an http.Handler wired up for the webhookd service.
 //
-// secret is the shared value required in the X-Mithras-Token header on
-// /v1/invoke. maxBody caps request bodies (in bytes).
+// secret is the shared value required in the Authorization: Bearer header
+// on /v1/invoke. maxBody caps request bodies (in bytes).
 func Router(launcher Launcher, secret string, maxBody int64, lg *slog.Logger) http.Handler {
 	mux := http.NewServeMux()
 

internal/webhook/handler_test.go

@@ -165,7 +165,7 @@ func TestInvokeHandler(t *testing.T) {
 				req.Header.Set("Content-Type", tt.contentType)
 			}
 			if tt.token != "" {
-				req.Header.Set("X-Mithras-Token", tt.token)
+				req.Header.Set("Authorization", "Bearer "+tt.token)
 			}
 			rec := httptest.NewRecorder()
 			h.ServeHTTP(rec, req)
@@ -200,6 +200,68 @@ func TestInvokeHandler(t *testing.T) {
 	}
 }
 
+func TestInvokeHandler_authorizationHeader(t *testing.T) {
+	t.Parallel()
+
+	const secret = "s3kret"
+
+	for _, tt := range []struct {
+		name       string
+		header     string
+		wantStatus int
+	}{
+		{
+			name:       "missing header is 401",
+			header:     "",
+			wantStatus: http.StatusUnauthorized,
+		},
+		{
+			name:       "wrong scheme is 401",
+			header:     "Basic " + secret,
+			wantStatus: http.StatusUnauthorized,
+		},
+		{
+			name:       "bearer without token is 401",
+			header:     "Bearer ",
+			wantStatus: http.StatusUnauthorized,
+		},
+		{
+			name:       "case-insensitive scheme accepted",
+			header:     "bearer " + secret,
+			wantStatus: http.StatusAccepted,
+		},
+		{
+			name:       "valid bearer accepted",
+			header:     "Bearer " + secret,
+			wantStatus: http.StatusAccepted,
+		},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			_, h := newTestRouter(t, secret, 1<<20)
+			req := httptest.NewRequest(http.MethodPost, "/v1/invoke", bytes.NewBufferString(`{}`))
+			req.Header.Set("Content-Type", "application/json")
+			if tt.header != "" {
+				req.Header.Set("Authorization", tt.header)
+			}
+
+			rec := httptest.NewRecorder()
+			h.ServeHTTP(rec, req)
+
+			if rec.Code != tt.wantStatus {
+				t.Fatalf("status = %d, want %d (body=%s)", rec.Code, tt.wantStatus, rec.Body.String())
+			}
+
+			if rec.Code == http.StatusUnauthorized {
+				if got := rec.Header().Get("WWW-Authenticate"); got == "" {
+					t.Error("missing WWW-Authenticate header on 401")
+				}
+			}
+		})
+	}
+}
+
 func TestInvokeHandler_bodyTooLarge(t *testing.T) {
 	t.Parallel()
 
@@ -209,7 +271,7 @@ func TestInvokeHandler_bodyTooLarge(t *testing.T) {
 	req := httptest.NewRequest(http.MethodPost, "/v1/invoke",
 		bytes.NewBufferString(`{"pad":"`+big+`"}`))
 	req.Header.Set("Content-Type", "application/json")
-	req.Header.Set("X-Mithras-Token", "x")
+	req.Header.Set("Authorization", "Bearer x")
 
 	rec := httptest.NewRecorder()
 	h.ServeHTTP(rec, req)

internal/webhook/middleware.go

@@ -8,26 +8,48 @@ import (
 	"net"
 	"net/http"
 	"runtime/debug"
+	"strings"
 )
 
 // ErrHijackNotSupported is returned by [statusRecorder.Hijack] when the wrapped
 // [http.ResponseWriter] does not implement [http.Hijacker].
 var ErrHijackNotSupported = errors.New("webhook: underlying ResponseWriter does not support hijacking")
 
-// requireToken returns middleware that 401s any request whose X-Mithras-Token
-// header does not equal secret. Comparison is constant time.
+// requireToken returns middleware that 401s any request whose
+// "Authorization: Bearer <token>" header does not equal secret. The scheme
+// match is case-insensitive per RFC 7235; the token comparison is constant
+// time.
 func requireToken(secret string, lg *slog.Logger, next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		got := r.Header.Get("X-Mithras-Token")
-		if subtle.ConstantTimeCompare([]byte(got), []byte(secret)) != 1 {
+		token, ok := bearerToken(r.Header.Get("Authorization"))
+		if !ok || subtle.ConstantTimeCompare([]byte(token), []byte(secret)) != 1 {
 			lg.Warn("rejected unauthenticated request", "path", r.URL.Path, "remote", r.RemoteAddr)
+			w.Header().Set("WWW-Authenticate", `Bearer realm="mithras"`)
 			http.Error(w, "Unauthorized", http.StatusUnauthorized)
 			return
 		}
 		next.ServeHTTP(w, r)
 	})
 }
 
+// bearerToken parses the value of the Authorization header and returns the
+// token portion when the scheme is Bearer. The second return is false when
+// the header is missing, malformed, or uses a different scheme.
+func bearerToken(authHeader string) (string, bool) {
+	const prefix = "Bearer "
+	if len(authHeader) < len(prefix) {
+		return "", false
+	}
+	if !strings.EqualFold(authHeader[:len(prefix)], prefix) {
+		return "", false
+	}
+	token := strings.TrimSpace(authHeader[len(prefix):])
+	if token == "" {
+		return "", false
+	}
+	return token, true
+}
+
 // recover500 converts panics in downstream handlers into a 500 response and
 // logs the panic value with its stack trace.
 func recover500(lg *slog.Logger, next http.Handler) http.Handler {