test(19.3-05): phase gate with bouncer cookie and Turnstile unit suites

- scripts/check-phase19.3.sh: fail-closed gate (go stage, self-test, --all with NOT RUN docker); a required name that fails, skips or is missing fails its stage - cookie_test.go: LoadCookieConfig defaults and errors, TokenCookie attributes and refresh-window Max-Age, forget cookie, refresh and logout handlers with a real Refresh and MemoryBlacklist - turnstile_test.go: open/closed verdict matrix, timeout, form fields, token sources, body restore, statuses and secret-free logs
2026-10-15 19:24:32 +02:00
parent 6035ccc194
commit 619916b5d2
3 changed files with 1223 additions and 0 deletions
--- a/modules/bouncer/cookie_test.go
+++ b/modules/bouncer/cookie_test.go
@@ -0,0 +1,430 @@
+package bouncer
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+)
+
+// cookieSource is a CookieConfigSource over a flat map of dotted keys.
+type cookieSource struct {
+	values map[string]any
+	env    string
+}
+
+func (s cookieSource) Lookup(path string) (any, bool) {
+	v, ok := s.values[path]
+	return v, ok
+}
+
+func (s cookieSource) String(path string) string {
+	if v, ok := s.values[path].(string); ok {
+		return v
+	}
+	return ""
+}
+
+func (s cookieSource) Environment() string { return s.env }
+
+func TestLoadCookieConfigDefaults(t *testing.T) {
+	cfg, err := LoadCookieConfig(nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if cfg.Name != DefaultCookieName || cfg.Path != "/" || cfg.Domain != "" || cfg.SameSite != http.SameSiteLaxMode || cfg.Secure {
+		t.Fatalf("nil source = %+v", cfg)
+	}
+
+	for _, tc := range []struct {
+		url    string
+		secure bool
+	}{
+		{"https://app.example.com", true},
+		{"HTTPS://app.example.com", true},
+		{"http://localhost:8000", false},
+		{"", false},
+	} {
+		cfg, err := LoadCookieConfig(cookieSource{values: map[string]any{"app.url": tc.url}, env: "production"})
+		if err != nil {
+			t.Fatalf("app.url %q: %v", tc.url, err)
+		}
+		if cfg.Name != "token" || cfg.Path != "/" || cfg.Domain != "" || cfg.SameSite != http.SameSiteLaxMode {
+			t.Fatalf("app.url %q: defaults = %+v", tc.url, cfg)
+		}
+		if cfg.Secure != tc.secure {
+			t.Fatalf("app.url %q: Secure = %t, want %t", tc.url, cfg.Secure, tc.secure)
+		}
+	}
+
+	cfg, err = LoadCookieConfig(cookieSource{values: map[string]any{
+		"auth.cookie.name":      "sid",
+		"auth.cookie.path":      "/api",
+		"auth.cookie.domain":    "example.com",
+		"auth.cookie.same_site": "Strict",
+		"auth.cookie.secure":    "true",
+	}, env: "production"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if cfg.Name != "sid" || cfg.Path != "/api" || cfg.Domain != "example.com" || cfg.SameSite != http.SameSiteStrictMode || !cfg.Secure {
+		t.Fatalf("explicit = %+v", cfg)
+	}
+
+	cfg, err = LoadCookieConfig(cookieSource{values: map[string]any{
+		"auth.cookie.same_site": "none",
+		"auth.cookie.secure":    true,
+	}})
+	if err != nil || cfg.SameSite != http.SameSiteNoneMode || !cfg.Secure {
+		t.Fatalf("none with secure = %+v, %v", cfg, err)
+	}
+
+	// secure false outside production is allowed.
+	cfg, err = LoadCookieConfig(cookieSource{values: map[string]any{
+		"app.url":            "https://app.example.com",
+		"auth.cookie.secure": false,
+	}, env: "development"})
+	if err != nil || cfg.Secure {
+		t.Fatalf("secure false in development = %+v, %v", cfg, err)
+	}
+}
+
+func TestLoadCookieConfigErrors(t *testing.T) {
+	for _, tc := range []struct {
+		name   string
+		values map[string]any
+		env    string
+		key    string
+	}{
+		{"invalid domain", map[string]any{"auth.cookie.domain": "exa mple.com"}, "", "auth.cookie.domain"},
+		{"same_site none without secure", map[string]any{"auth.cookie.same_site": "none", "auth.cookie.secure": false}, "development", "auth.cookie.same_site"},
+		{"same_site none on http app", map[string]any{"auth.cookie.same_site": "none", "app.url": "http://localhost"}, "", "auth.cookie.same_site"},
+		{"secure false in production", map[string]any{"auth.cookie.secure": false}, "production", "auth.cookie.secure"},
+		{"secure string false in production", map[string]any{"auth.cookie.secure": "false"}, "Production", "auth.cookie.secure"},
+		{"secure not a bool", map[string]any{"auth.cookie.secure": "maybe"}, "", "auth.cookie.secure"},
+		{"secure wrong type", map[string]any{"auth.cookie.secure": 1}, "", "auth.cookie.secure"},
+		{"unknown same_site", map[string]any{"auth.cookie.same_site": "relaxed"}, "", "auth.cookie.same_site"},
+		{"path without leading slash", map[string]any{"auth.cookie.path": "api"}, "", "auth.cookie.path"},
+		{"invalid name", map[string]any{"auth.cookie.name": "to ken"}, "", "auth.cookie.name"},
+		{"empty name", map[string]any{"auth.cookie.name": " "}, "", "auth.cookie.name"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			_, err := LoadCookieConfig(cookieSource{values: tc.values, env: tc.env})
+			if err == nil {
+				t.Fatal("want an error")
+			}
+			if !strings.Contains(err.Error(), tc.key) {
+				t.Fatalf("error %q does not name %s", err, tc.key)
+			}
+		})
+	}
+}
+
+func TestTokenCookieAttributes(t *testing.T) {
+	cfg := CookieConfig{Name: "sid", Domain: "example.com", Path: "/api", Secure: true, SameSite: http.SameSiteLaxMode}
+	c := cfg.TokenCookie("tok", time.Hour)
+	if c.Name != "sid" || c.Value != "tok" || c.Domain != "example.com" || c.Path != "/api" {
+		t.Fatalf("cookie = %+v", c)
+	}
+	if !c.HttpOnly || !c.Secure || c.SameSite != http.SameSiteLaxMode {
+		t.Fatalf("flags = %+v", c)
+	}
+	if c.Valid() != nil {
+		t.Fatalf("cookie invalid: %v", c.Valid())
+	}
+	header := c.String()
+	for _, part := range []string{"sid=tok", "Path=/api", "Domain=example.com", "Max-Age=3600", "HttpOnly", "Secure", "SameSite=Lax"} {
+		if !strings.Contains(header, part) {
+			t.Fatalf("Set-Cookie %q lacks %q", header, part)
+		}
+	}
+
+	// A zero config writes the default cookie on "/" and host-only.
+	z := CookieConfig{}.TokenCookie("v", time.Minute)
+	if z.Name != DefaultCookieName || z.Path != "/" || z.Domain != "" || !z.HttpOnly {
+		t.Fatalf("zero config cookie = %+v", z)
+	}
+	if strings.Contains(z.String(), "Domain=") {
+		t.Fatalf("host-only cookie carries a domain: %s", z.String())
+	}
+}
+
+func TestTokenCookieMaxAgeIsRefreshWindow(t *testing.T) {
+	const (
+		accessTTL  = 60 * time.Minute
+		refreshTTL = 20160 * time.Minute
+	)
+	c := CookieConfig{}.TokenCookie("tok", refreshTTL)
+	if c.MaxAge != 1209600 {
+		t.Fatalf("MaxAge = %d, want 1209600 (refresh_ttl*60)", c.MaxAge)
+	}
+	if c.MaxAge == int(accessTTL/time.Second) {
+		t.Fatal("MaxAge equals the access ttl")
+	}
+	if d := time.Until(c.Expires); d < refreshTTL-time.Minute || d > refreshTTL+time.Minute {
+		t.Fatalf("Expires in %s, want about %s", d, refreshTTL)
+	}
+}
+
+func TestForgetTokenCookie(t *testing.T) {
+	cfg := CookieConfig{Name: "sid", Domain: "example.com", Path: "/api", Secure: true, SameSite: http.SameSiteNoneMode}
+	set := cfg.TokenCookie("tok", time.Hour)
+	f := cfg.ForgetTokenCookie()
+	if f.Name != set.Name || f.Domain != set.Domain || f.Path != set.Path || f.Secure != set.Secure || f.SameSite != set.SameSite || f.HttpOnly != set.HttpOnly {
+		t.Fatalf("forget %+v does not match set %+v", f, set)
+	}
+	if f.Value != "" || f.MaxAge != -1 || !f.Expires.Before(time.Now()) {
+		t.Fatalf("forget cookie = %+v", f)
+	}
+	if !strings.Contains(f.String(), "Max-Age=0") {
+		t.Fatalf("forget header %q does not expire the cookie", f.String())
+	}
+}
+
+// recordWriter captures what a cookie handler passes to the app's writer.
+type recordWriter struct {
+	calls int
+	res   CookieResult
+}
+
+func (rw *recordWriter) write(w http.ResponseWriter, _ *http.Request, res CookieResult) {
+	rw.calls++
+	rw.res = res
+	w.WriteHeader(res.Status)
+	_, _ = w.Write([]byte(res.Token))
+}
+
+func refreshRequest(name, value string) *http.Request {
+	r := httptest.NewRequest(http.MethodPost, "https://api.example.com/auth/refresh", nil)
+	if name != "" {
+		r.AddCookie(&http.Cookie{Name: name, Value: value})
+	}
+	return r
+}
+
+func TestCookieRefreshHandlerRotatesAndBlacklists(t *testing.T) {
+	const (
+		issuer     = "https://api.example.com/auth/login"
+		refreshTTL = 20160 * time.Minute
+	)
+	old, oldJTI, err := Mint(secret, "42", issuer, time.Hour)
+	if err != nil {
+		t.Fatal(err)
+	}
+	bl := NewMemoryBlacklist()
+	cfg := CookieConfig{Name: "token", Domain: "example.com", Path: "/", Secure: true, SameSite: http.SameSiteLaxMode}
+	rw := &recordWriter{}
+	h, err := CookieRefreshHandler(CookieRefreshOptions{
+		Cookie:     cfg,
+		RefreshTTL: refreshTTL,
+		Refresh: func(_ context.Context, token string) (string, error) {
+			return Refresh(secret, token, refreshTTL, bl, 0, "https://api.example.com/auth/refresh")
+		},
+		Write: rw.write,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, refreshRequest("token", old))
+
+	if rec.Code != http.StatusOK || rw.calls != 1 || rw.res.Status != http.StatusOK || rw.res.Err != nil {
+		t.Fatalf("status %d, writer %d calls, res %+v", rec.Code, rw.calls, rw.res)
+	}
+	if rw.res.Token == "" || rw.res.Token == old || rec.Body.String() != rw.res.Token {
+		t.Fatalf("writer token %q", rw.res.Token)
+	}
+	cookies := rec.Result().Cookies()
+	if len(cookies) != 1 {
+		t.Fatalf("Set-Cookie count = %d", len(cookies))
+	}
+	c := cookies[0]
+	if c.Name != "token" || c.Value != rw.res.Token || c.Domain != "example.com" || !c.HttpOnly || !c.Secure || c.MaxAge != 1209600 {
+		t.Fatalf("rotated cookie = %+v", c)
+	}
+	claims := decodeClaims(t, c.Value, secret)
+	if claims["jti"] == oldJTI || claims["sub"] != "42" {
+		t.Fatalf("new claims = %#v", claims)
+	}
+	blocked, err := bl.IsBlacklisted(t.Context(), oldJTI)
+	if err != nil || !blocked {
+		t.Fatalf("old jti blacklisted=%t err=%v", blocked, err)
+	}
+
+	// The old token no longer refreshes.
+	rw2 := &recordWriter{}
+	h2, _ := CookieRefreshHandler(CookieRefreshOptions{
+		Cookie: cfg, RefreshTTL: refreshTTL,
+		Refresh: func(_ context.Context, token string) (string, error) {
+			return Refresh(secret, token, refreshTTL, bl, 0, "https://api.example.com/auth/refresh")
+		},
+		Write: rw2.write,
+	})
+	rec2 := httptest.NewRecorder()
+	h2.ServeHTTP(rec2, refreshRequest("token", old))
+	if rec2.Code != http.StatusUnauthorized || len(rec2.Result().Cookies()) != 0 {
+		t.Fatalf("replayed refresh: %d, cookies %v", rec2.Code, rec2.Result().Cookies())
+	}
+}
+
+func TestCookieRefreshHandlerMissingCookie(t *testing.T) {
+	for _, tc := range []struct{ name, cookie, value string }{
+		{"no cookie", "", ""},
+		{"other cookie", "session", "abc"},
+		{"empty cookie", "token", ""},
+		{"blank cookie", "token", "   "},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			called := false
+			rw := &recordWriter{}
+			h, err := CookieRefreshHandler(CookieRefreshOptions{
+				RefreshTTL: time.Hour,
+				Refresh: func(context.Context, string) (string, error) {
+					called = true
+					return "x", nil
+				},
+				Write: rw.write,
+			})
+			if err != nil {
+				t.Fatal(err)
+			}
+			rec := httptest.NewRecorder()
+			h.ServeHTTP(rec, refreshRequest(tc.cookie, tc.value))
+			if called {
+				t.Fatal("Refresh called without a token cookie")
+			}
+			if rec.Code != http.StatusUnauthorized || !errors.Is(rw.res.Err, ErrNoTokenCookie) {
+				t.Fatalf("status %d err %v", rec.Code, rw.res.Err)
+			}
+			if rec.Header().Get("Set-Cookie") != "" {
+				t.Fatalf("Set-Cookie sent: %q", rec.Header().Get("Set-Cookie"))
+			}
+		})
+	}
+}
+
+func TestCookieRefreshHandlerRefreshError(t *testing.T) {
+	refusal := errors.New("token expired past refresh window")
+	rw := &recordWriter{}
+	h, err := CookieRefreshHandler(CookieRefreshOptions{
+		Cookie:     CookieConfig{Name: "sid"},
+		RefreshTTL: time.Hour,
+		Refresh: func(_ context.Context, token string) (string, error) {
+			if token != "stale" {
+				t.Fatalf("Refresh got %q", token)
+			}
+			return "", refusal
+		},
+		Write: rw.write,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, refreshRequest("sid", "stale"))
+	if rec.Code != http.StatusUnauthorized || !errors.Is(rw.res.Err, refusal) || rw.res.Token != "" {
+		t.Fatalf("status %d res %+v", rec.Code, rw.res)
+	}
+	if rec.Header().Get("Set-Cookie") != "" {
+		t.Fatalf("cookie touched on a refused refresh: %q", rec.Header().Get("Set-Cookie"))
+	}
+}
+
+func TestCookieLogoutHandler(t *testing.T) {
+	cfg := CookieConfig{Name: "token", Domain: "example.com", Path: "/", Secure: true, SameSite: http.SameSiteLaxMode}
+	revokeErr := errors.New("blacklist down")
+	for _, tc := range []struct {
+		name      string
+		cookie    string
+		revokeErr error
+		wantCall  bool
+	}{
+		{"revokes the cookie token", "tok-1", nil, true},
+		{"revoke failure still forgets", "tok-2", revokeErr, true},
+		{"no cookie still forgets", "", nil, false},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			var got []string
+			rw := &recordWriter{}
+			h, err := CookieLogoutHandler(CookieLogoutOptions{
+				Cookie: cfg,
+				Revoke: func(_ context.Context, token string) error {
+					got = append(got, token)
+					return tc.revokeErr
+				},
+				Write: rw.write,
+			})
+			if err != nil {
+				t.Fatal(err)
+			}
+			name := ""
+			if tc.cookie != "" {
+				name = "token"
+			}
+			rec := httptest.NewRecorder()
+			h.ServeHTTP(rec, refreshRequest(name, tc.cookie))
+			if tc.wantCall && (len(got) != 1 || got[0] != tc.cookie) {
+				t.Fatalf("Revoke calls = %v", got)
+			}
+			if !tc.wantCall && len(got) != 0 {
+				t.Fatalf("Revoke called without a cookie: %v", got)
+			}
+			if rec.Code != http.StatusOK || rw.res.Status != http.StatusOK || !errors.Is(rw.res.Err, tc.revokeErr) {
+				t.Fatalf("status %d res %+v", rec.Code, rw.res)
+			}
+			cookies := rec.Result().Cookies()
+			if len(cookies) != 1 {
+				t.Fatalf("Set-Cookie count = %d", len(cookies))
+			}
+			f := cookies[0]
+			if f.Name != "token" || f.Value != "" || f.MaxAge != -1 || f.Domain != "example.com" || f.Path != "/" || !f.Secure || !f.HttpOnly {
+				t.Fatalf("forget cookie = %+v", f)
+			}
+		})
+	}
+}
+
+func TestCookieHandlerOptionsValidated(t *testing.T) {
+	refresh := func(context.Context, string) (string, error) { return "", nil }
+	revoke := func(context.Context, string) error { return nil }
+	write := func(http.ResponseWriter, *http.Request, CookieResult) {}
+
+	for _, tc := range []struct {
+		name string
+		opts CookieRefreshOptions
+		want string
+	}{
+		{"nil refresh", CookieRefreshOptions{RefreshTTL: time.Hour, Write: write}, "Refresh"},
+		{"nil write", CookieRefreshOptions{RefreshTTL: time.Hour, Refresh: refresh}, "Write"},
+		{"zero ttl", CookieRefreshOptions{Refresh: refresh, Write: write}, "RefreshTTL"},
+		{"negative ttl", CookieRefreshOptions{RefreshTTL: -time.Second, Refresh: refresh, Write: write}, "RefreshTTL"},
+	} {
+		h, err := CookieRefreshHandler(tc.opts)
+		if err == nil || h != nil || !strings.Contains(err.Error(), tc.want) {
+			t.Fatalf("refresh %s: handler %v err %v", tc.name, h, err)
+		}
+	}
+	if h, err := CookieRefreshHandler(CookieRefreshOptions{RefreshTTL: time.Hour, Refresh: refresh, Write: write}); err != nil || h == nil {
+		t.Fatalf("valid refresh options: %v", err)
+	}
+
+	for _, tc := range []struct {
+		name string
+		opts CookieLogoutOptions
+		want string
+	}{
+		{"nil revoke", CookieLogoutOptions{Write: write}, "Revoke"},
+		{"nil write", CookieLogoutOptions{Revoke: revoke}, "Write"},
+	} {
+		h, err := CookieLogoutHandler(tc.opts)
+		if err == nil || h != nil || !strings.Contains(err.Error(), tc.want) {
+			t.Fatalf("logout %s: handler %v err %v", tc.name, h, err)
+		}
+	}
+	if h, err := CookieLogoutHandler(CookieLogoutOptions{Revoke: revoke, Write: write}); err != nil || h == nil {
+		t.Fatalf("valid logout options: %v", err)
+	}
+}
--- a/modules/bouncer/turnstile_test.go
+++ b/modules/bouncer/turnstile_test.go
@@ -0,0 +1,391 @@
+package bouncer
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+const turnstileTestSecret = "0x4AAAAAAA-test-secret-value"
+
+// siteverify is an httptest fake of Cloudflare's siteverify endpoint. It
+// records every form it receives and answers with the configured status and
+// body.
+type siteverify struct {
+	srv    *httptest.Server
+	calls  atomic.Int32
+	mu     sync.Mutex
+	forms  []url.Values
+	status int
+	body   string
+	delay  time.Duration
+}
+
+func newSiteverify(t *testing.T, status int, body string) *siteverify {
+	t.Helper()
+	f := &siteverify{status: status, body: body}
+	f.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		f.calls.Add(1)
+		_ = r.ParseForm()
+		f.mu.Lock()
+		f.forms = append(f.forms, r.PostForm)
+		f.mu.Unlock()
+		if f.delay > 0 {
+			select {
+			case <-time.After(f.delay):
+			case <-r.Context().Done():
+				return
+			}
+		}
+		w.WriteHeader(f.status)
+		_, _ = io.WriteString(w, f.body)
+	}))
+	t.Cleanup(f.srv.Close)
+	return f
+}
+
+func (f *siteverify) verifier(secret string, production bool) *Turnstile {
+	return &Turnstile{Secret: secret, Production: production, Endpoint: f.srv.URL, Client: f.srv.Client()}
+}
+
+func (f *siteverify) lastForm(t *testing.T) url.Values {
+	t.Helper()
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if len(f.forms) == 0 {
+		t.Fatal("siteverify was not called")
+	}
+	return f.forms[len(f.forms)-1]
+}
+
+func TestTurnstileVerifyMatrix(t *testing.T) {
+	const ok = `{"success":true}`
+	for _, tc := range []struct {
+		name       string
+		secret     string
+		production bool
+		failClosed bool
+		token      string
+		status     int
+		body       string
+		want       TurnstileVerdict
+		wantCall   bool
+		wantErr    bool
+	}{
+		{"open, no secret, development", "", false, false, "tok", 200, ok, TurnstilePassed, false, false},
+		{"open, no secret, production", "", true, false, "tok", 200, ok, TurnstilePassed, false, false},
+		{"closed, no secret, development", "", false, true, "tok", 200, ok, TurnstilePassed, false, false},
+		{"closed, no secret, production", "", true, true, "tok", 200, ok, TurnstileUnavailable, false, false},
+		{"closed, blank secret, production", "  ", true, true, "tok", 200, ok, TurnstileUnavailable, false, false},
+		{"open, empty token", turnstileTestSecret, true, false, "", 200, ok, TurnstileFailed, false, false},
+		{"closed, empty token", turnstileTestSecret, true, true, "", 200, ok, TurnstileFailed, false, false},
+		{"open, token over the limit", turnstileTestSecret, false, false, strings.Repeat("a", TurnstileMaxTokenLength+1), 200, ok, TurnstileFailed, false, false},
+		{"closed, token at the limit", turnstileTestSecret, false, true, strings.Repeat("a", TurnstileMaxTokenLength), 200, ok, TurnstilePassed, true, false},
+		{"open, success true", turnstileTestSecret, false, false, "tok", 200, ok, TurnstilePassed, true, false},
+		{"closed, success true", turnstileTestSecret, true, true, "tok", 200, ok, TurnstilePassed, true, false},
+		{"open, success false", turnstileTestSecret, false, false, "tok", 200, `{"success":false,"error-codes":["invalid-input-response"]}`, TurnstileFailed, true, true},
+		{"closed, success false", turnstileTestSecret, true, true, "tok", 200, `{"success":false}`, TurnstileFailed, true, true},
+		{"open, non-2xx", turnstileTestSecret, false, false, "tok", 500, ok, TurnstileFailed, true, true},
+		{"closed, non-2xx", turnstileTestSecret, true, true, "tok", 403, ok, TurnstileFailed, true, true},
+		{"open, invalid JSON", turnstileTestSecret, false, false, "tok", 200, `<html>`, TurnstileFailed, true, true},
+		{"closed, JSON without success", turnstileTestSecret, true, true, "tok", 200, `{"hostname":"x"}`, TurnstileFailed, true, true},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			f := newSiteverify(t, tc.status, tc.body)
+			got, err := f.verifier(tc.secret, tc.production).Verify(t.Context(), tc.token, "203.0.113.7", tc.failClosed)
+			if got != tc.want {
+				t.Fatalf("verdict = %s, want %s (err %v)", got, tc.want, err)
+			}
+			if called := f.calls.Load() > 0; called != tc.wantCall {
+				t.Fatalf("siteverify called = %t, want %t", called, tc.wantCall)
+			}
+			if (err != nil) != tc.wantErr {
+				t.Fatalf("err = %v, want error %t", err, tc.wantErr)
+			}
+		})
+	}
+
+	// A nil verifier behaves like an unconfigured one in production.
+	var nilT *Turnstile
+	if v, _ := nilT.Verify(t.Context(), "tok", "", true); v != TurnstileUnavailable {
+		t.Fatalf("nil closed = %s", v)
+	}
+	if v, _ := nilT.Verify(t.Context(), "tok", "", false); v != TurnstilePassed {
+		t.Fatalf("nil open = %s", v)
+	}
+	if TurnstilePassed.String() != "passed" || TurnstileFailed.String() != "failed" || TurnstileUnavailable.String() != "unavailable" {
+		t.Fatal("verdict names changed")
+	}
+}
+
+func TestTurnstileVerifyTimeout(t *testing.T) {
+	f := newSiteverify(t, 200, `{"success":true}`)
+	f.delay = 2 * time.Second
+	ctx, cancel := context.WithTimeout(t.Context(), 50*time.Millisecond)
+	defer cancel()
+	start := time.Now()
+	got, err := f.verifier(turnstileTestSecret, true).Verify(ctx, "tok", "", false)
+	if got != TurnstileFailed {
+		t.Fatalf("verdict = %s", got)
+	}
+	if err == nil || !strings.Contains(err.Error(), "timeout") {
+		t.Fatalf("err = %v, want a timeout", err)
+	}
+	if elapsed := time.Since(start); elapsed > time.Second {
+		t.Fatalf("Verify took %s past a 50 ms deadline", elapsed)
+	}
+}
+
+func TestTurnstileFormFields(t *testing.T) {
+	f := newSiteverify(t, 200, `{"success":true}`)
+	v := f.verifier(turnstileTestSecret, false)
+	if got, err := v.Verify(t.Context(), "the-token", "198.51.100.4", false); got != TurnstilePassed || err != nil {
+		t.Fatalf("verdict %s err %v", got, err)
+	}
+	form := f.lastForm(t)
+	if form.Get("secret") != turnstileTestSecret || form.Get("response") != "the-token" || form.Get("remoteip") != "198.51.100.4" {
+		t.Fatalf("form = %v", form)
+	}
+
+	if _, err := v.Verify(t.Context(), "the-token", "", false); err != nil {
+		t.Fatal(err)
+	}
+	form = f.lastForm(t)
+	if _, ok := form["remoteip"]; ok {
+		t.Fatalf("remoteip sent for an empty ip: %v", form)
+	}
+	if form.Get("response") != "the-token" {
+		t.Fatalf("form = %v", form)
+	}
+}
+
+func passHandler(called *bool) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		*called = true
+		w.WriteHeader(http.StatusNoContent)
+	})
+}
+
+func TestTurnstileMiddlewareTokenSources(t *testing.T) {
+	for _, tc := range []struct {
+		name  string
+		build func() *http.Request
+	}{
+		{"query", func() *http.Request {
+			return httptest.NewRequest(http.MethodPost, "/register?turnstile_token=src-token", strings.NewReader(`{"turnstile_token":"other"}`))
+		}},
+		{"json body", func() *http.Request {
+			r := httptest.NewRequest(http.MethodPost, "/register", strings.NewReader(`{"email":"a@b.c","turnstile_token":"src-token"}`))
+			r.Header.Set("Content-Type", "application/json; charset=utf-8")
+			return r
+		}},
+		{"json body without content type", func() *http.Request {
+			return httptest.NewRequest(http.MethodPost, "/register", strings.NewReader(` {"turnstile_token":"src-token"}`))
+		}},
+		{"vendor json body", func() *http.Request {
+			r := httptest.NewRequest(http.MethodPost, "/register", strings.NewReader(`{"turnstile_token":"src-token"}`))
+			r.Header.Set("Content-Type", "application/vnd.api+json")
+			return r
+		}},
+		{"urlencoded form", func() *http.Request {
+			r := httptest.NewRequest(http.MethodPost, "/register", strings.NewReader(`email=a%40b.c&turnstile_token=src-token`))
+			r.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+			return r
+		}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			f := newSiteverify(t, 200, `{"success":true}`)
+			called := false
+			h := f.verifier(turnstileTestSecret, true).Middleware(true, "", nil, nil)(passHandler(&called))
+			rec := httptest.NewRecorder()
+			h.ServeHTTP(rec, tc.build())
+			if rec.Code != http.StatusNoContent || !called {
+				t.Fatalf("status %d called %t body %s", rec.Code, called, rec.Body)
+			}
+			if got := f.lastForm(t).Get("response"); got != "src-token" {
+				t.Fatalf("token sent = %q", got)
+			}
+		})
+	}
+
+	// A custom field name is honoured; the default field is then ignored.
+	f := newSiteverify(t, 200, `{"success":true}`)
+	called := false
+	h := f.verifier(turnstileTestSecret, true).Middleware(true, "cf_token", nil, nil)(passHandler(&called))
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, httptest.NewRequest(http.MethodPost, "/x?turnstile_token=wrong&cf_token=right", nil))
+	if !called || f.lastForm(t).Get("response") != "right" {
+		t.Fatalf("custom field: called %t form %v", called, f.lastForm(t))
+	}
+}
+
+func TestTurnstileMiddlewareRestoresBody(t *testing.T) {
+	for _, tc := range []struct {
+		name, contentType, body string
+	}{
+		{"json", "application/json", `{"turnstile_token":"tok","name":"Ann"}`},
+		{"form", "application/x-www-form-urlencoded", `turnstile_token=tok&name=Ann`},
+		{"other media type", "text/plain", `turnstile_token=tok`},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			f := newSiteverify(t, 200, `{"success":true}`)
+			var seen []byte
+			next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				seen, _ = io.ReadAll(r.Body)
+				w.WriteHeader(http.StatusOK)
+			})
+			// Open mode without a secret passes even when no token is found,
+			// so the restored body is checked for every media type.
+			v := f.verifier(turnstileTestSecret, false)
+			if tc.contentType == "text/plain" {
+				v = f.verifier("", false)
+			}
+			r := httptest.NewRequest(http.MethodPost, "/submit", strings.NewReader(tc.body))
+			r.Header.Set("Content-Type", tc.contentType)
+			rec := httptest.NewRecorder()
+			v.Middleware(false, "", nil, nil)(next).ServeHTTP(rec, r)
+			if rec.Code != http.StatusOK {
+				t.Fatalf("status %d", rec.Code)
+			}
+			if string(seen) != tc.body {
+				t.Fatalf("handler read %q, want %q", seen, tc.body)
+			}
+		})
+	}
+}
+
+// turnstileCall records what a TurnstileWriter received.
+type turnstileCall struct {
+	status  int
+	verdict TurnstileVerdict
+}
+
+func TestTurnstileMiddlewareStatuses(t *testing.T) {
+	f := newSiteverify(t, 200, `{"success":true}`)
+	for _, tc := range []struct {
+		name       string
+		v          *Turnstile
+		failClosed bool
+		target     string
+		want       int
+		verdict    TurnstileVerdict
+		code       string
+	}{
+		{"unavailable", f.verifier("", true), true, "/x?turnstile_token=t", 503, TurnstileUnavailable, "turnstile_unavailable"},
+		{"failed without token", f.verifier(turnstileTestSecret, true), true, "/x", 422, TurnstileFailed, "turnstile_failed"},
+		{"passed", f.verifier(turnstileTestSecret, true), false, "/x?turnstile_token=t", 204, TurnstilePassed, ""},
+	} {
+		t.Run(tc.name+" default writer", func(t *testing.T) {
+			called := false
+			rec := httptest.NewRecorder()
+			tc.v.Middleware(tc.failClosed, "", nil, nil)(passHandler(&called)).ServeHTTP(rec, httptest.NewRequest(http.MethodPost, tc.target, nil))
+			if rec.Code != tc.want || called != (tc.want == 204) {
+				t.Fatalf("status %d called %t", rec.Code, called)
+			}
+			if tc.code != "" {
+				if rec.Header().Get("Content-Type") != "application/json" {
+					t.Fatalf("content type %q", rec.Header().Get("Content-Type"))
+				}
+				var body map[string]string
+				if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil || body["error"] != tc.code || len(body) != 1 {
+					t.Fatalf("body %s", rec.Body)
+				}
+			}
+		})
+		t.Run(tc.name+" app writer", func(t *testing.T) {
+			var calls []turnstileCall
+			write := func(w http.ResponseWriter, _ *http.Request, status int, verdict TurnstileVerdict) {
+				calls = append(calls, turnstileCall{status, verdict})
+				w.WriteHeader(status)
+			}
+			called := false
+			rec := httptest.NewRecorder()
+			tc.v.Middleware(tc.failClosed, "", nil, write)(passHandler(&called)).ServeHTTP(rec, httptest.NewRequest(http.MethodPost, tc.target, nil))
+			if tc.want == 204 {
+				if len(calls) != 0 || !called {
+					t.Fatalf("writer calls %v called %t", calls, called)
+				}
+				return
+			}
+			if len(calls) != 1 || calls[0].status != tc.want || calls[0].verdict != tc.verdict || called {
+				t.Fatalf("writer calls %v called %t", calls, called)
+			}
+		})
+	}
+
+	// A body over the router's limit answers 413 without calling siteverify.
+	before := f.calls.Load()
+	called := false
+	h := f.verifier(turnstileTestSecret, true).Middleware(true, "", nil, nil)(passHandler(&called))
+	rec := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodPost, "/x", strings.NewReader(strings.Repeat("a", 64)))
+	r.Header.Set("Content-Type", "application/json")
+	r.Body = http.MaxBytesReader(rec, r.Body, 8)
+	h.ServeHTTP(rec, r)
+	if rec.Code != http.StatusRequestEntityTooLarge || called || f.calls.Load() != before {
+		t.Fatalf("over-limit body: status %d called %t", rec.Code, called)
+	}
+
+	// The client IP func supplies remoteip.
+	h = f.verifier(turnstileTestSecret, true).Middleware(true, "", func(*http.Request) string { return "192.0.2.9" }, nil)(passHandler(&called))
+	h.ServeHTTP(httptest.NewRecorder(), httptest.NewRequest(http.MethodPost, "/x?turnstile_token=t", nil))
+	if got := f.lastForm(t).Get("remoteip"); got != "192.0.2.9" {
+		t.Fatalf("remoteip = %q", got)
+	}
+}
+
+func TestTurnstileNeverLogsSecret(t *testing.T) {
+	var logs bytes.Buffer
+	prev := slog.Default()
+	slog.SetDefault(slog.New(slog.NewTextHandler(&logs, &slog.HandlerOptions{Level: slog.LevelDebug})))
+	defer slog.SetDefault(prev)
+
+	const token = "client-token-must-not-be-logged"
+	// A transport error: the endpoint refuses connections.
+	dead := httptest.NewServer(http.NotFoundHandler())
+	endpoint := dead.URL + "/siteverify?secret=" + turnstileTestSecret
+	dead.Close()
+	v := &Turnstile{Secret: turnstileTestSecret, Endpoint: endpoint, Client: &http.Client{Timeout: time.Second}}
+	called := false
+	rec := httptest.NewRecorder()
+	v.Middleware(false, "", nil, nil)(passHandler(&called)).ServeHTTP(rec, httptest.NewRequest(http.MethodPost, "/x?turnstile_token="+token, nil))
+	if rec.Code != http.StatusUnprocessableEntity || called {
+		t.Fatalf("transport error: status %d called %t", rec.Code, called)
+	}
+
+	// A refusal (success false) is logged at debug with the codes only.
+	f := newSiteverify(t, 200, `{"success":false,"error-codes":["invalid-input-response","`+turnstileTestSecret+`"]}`)
+	rec = httptest.NewRecorder()
+	f.verifier(turnstileTestSecret, false).Middleware(false, "", nil, nil)(passHandler(&called)).ServeHTTP(rec, httptest.NewRequest(http.MethodPost, "/x?turnstile_token="+token, nil))
+	if rec.Code != http.StatusUnprocessableEntity {
+		t.Fatalf("refusal: status %d", rec.Code)
+	}
+
+	out := logs.String()
+	if !strings.Contains(out, "turnstile verification failed") || !strings.Contains(out, "turnstile token refused") {
+		t.Fatalf("expected both log lines, got:\n%s", out)
+	}
+	if strings.Contains(out, turnstileTestSecret) || strings.Contains(out, token) {
+		t.Fatalf("log leaks the secret or the token:\n%s", out)
+	}
+
+	// The returned error never carries them either.
+	_, err := v.Verify(t.Context(), token, "", false)
+	if err == nil || strings.Contains(err.Error(), turnstileTestSecret) || strings.Contains(err.Error(), token) || strings.Contains(err.Error(), "siteverify?") {
+		t.Fatalf("err = %v", err)
+	}
+	if errors.Is(err, errTurnstileRefused) {
+		t.Fatal("a transport error is not a refusal")
+	}
+}
--- a/scripts/check-phase19.3.sh
+++ b/scripts/check-phase19.3.sh
@@ -0,0 +1,402 @@
+#!/usr/bin/env bash
+# check-phase19.3: fail-closed gate for Phase 19.3, framework transport and
+# infrastructure. The framework pieces in this repository (bouncer token
+# cookies and Turnstile, surf CORS hardening, CORS profiles, the api-docs page
+# and the rate-limit store lookup, cabana's reorder hook, summer.yaml build
+# tags, the attach S3 build tag, DiskExtension and public_url, and the cooler
+# module: caches, the Redis rate-limit store, Install and the site-cache
+# purge), the purge wiring in the FAQ, menu and Journal plugins, and the
+# shared purge route of the FAQ, menu and Journal Nuxt layers.
+#
+# Stages:
+#   go        go vet ./... and go vet -tags summercms_s3 ./modules/lagoon/...;
+#             go test -short ./...; then the Docker-free framework suites by
+#             required name, the attach ones in both build-tag modes.
+#   docker    Docker host only: the testcontainers suites by required name
+#             (Postgres and Redis) in the framework and the plugins.
+#   plugins   go vet ./... and go test -short ./... in the three plugins, then
+#             their Docker-free suites by required name.
+#   layers    pnpm test (node --test, TAP) in the three layers with required
+#             test files and names, and cmp equality of the shared purge files
+#             and spec across the layers.
+#   docs      TestDocsTree, summer docs:build --check and a check that no file
+#             this phase added to the framework names a consuming application.
+#
+# A stage exits non-zero on a failing command, or on a go test -json run that
+# fails, skips a test, matches zero tests, prints "no tests to run" or misses a
+# required name; or a TAP run with a "not ok", a fail, cancelled, skipped or
+# todo count, no passing test or a missing required name.
+# --self-test proves the detectors fail on planted output.
+#
+# --all runs self-test, go, plugins, layers and docs, then docker when a
+# Docker daemon answers. When none does, --all prints NOT RUN docker and the
+# Docker suites stay a manual step for a Docker host:
+#   bash scripts/check-phase19.3.sh docker
+# Set PHASE193_REQUIRE_DOCKER=1 to make --all fail instead.
+#
+# Environment overrides (default: the sibling checkouts next to this
+# repository): PHASE193_ROOT (this repository), FAQ_PLUGIN, MENU_PLUGIN,
+# JOURNAL_PLUGIN, FAQ_LAYER, MENU_LAYER, JOURNAL_LAYER.
+set -euo pipefail
+
+unset FORCE_COLOR
+export NO_COLOR=1
+
+ROOT="${PHASE193_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+FAQ_PLUGIN="${FAQ_PLUGIN:-$ROOT/../sm-faq-plugin}"
+MENU_PLUGIN="${MENU_PLUGIN:-$ROOT/../sm-menu-plugin}"
+JOURNAL_PLUGIN="${JOURNAL_PLUGIN:-$ROOT/../sm-journal-plugin}"
+FAQ_LAYER="${FAQ_LAYER:-$ROOT/../vue-faq-layer}"
+MENU_LAYER="${MENU_LAYER:-$ROOT/../vue-menu-layer}"
+JOURNAL_LAYER="${JOURNAL_LAYER:-$ROOT/../vue-journal-layer}"
+
+# ---------------------------------------------------------------------------
+# Required test names. Each list runs with -run '^(a|b|...)$' and every name
+# must pass; a name that skips or does not run fails the stage.
+
+# go stage: Docker-free framework suites (-short).
+BOUNCER_TESTS=(
+	TestLoadCookieConfigDefaults TestLoadCookieConfigErrors
+	TestTokenCookieAttributes TestTokenCookieMaxAgeIsRefreshWindow TestForgetTokenCookie
+	TestCookieRefreshHandlerRotatesAndBlacklists TestCookieRefreshHandlerMissingCookie
+	TestCookieRefreshHandlerRefreshError TestCookieLogoutHandler TestCookieHandlerOptionsValidated
+	TestTurnstileVerifyMatrix TestTurnstileVerifyTimeout TestTurnstileFormFields
+	TestTurnstileMiddlewareTokenSources TestTurnstileMiddlewareRestoresBody
+	TestTurnstileMiddlewareStatuses TestTurnstileNeverLogsSecret
+)
+
+# docker stage: testcontainers suites.
+
+usage() {
+	cat >&2 <<'EOF'
+usage:
+  check-phase19.3.sh --self-test
+  check-phase19.3.sh go | docker | plugins | layers | docs
+  check-phase19.3.sh --go | --docker | --plugins | --layers | --docs
+  check-phase19.3.sh --all
+EOF
+	exit 2
+}
+
+# detect_go reads go test -json. Exit 1 fail/build, 2 skip, 3 zero/no-tests,
+# 4 non-JSON, 5 missing required name.
+detect_go() {
+	python3 - "$1" <<'PY'
+import json, os, sys
+path = sys.argv[1]
+require = [n for n in os.environ.get("REQUIRE_TESTS", "").split() if n]
+passed = set()
+failed = []
+with open(path, encoding="utf-8", errors="replace") as fh:
+    for raw in fh:
+        line = raw.strip()
+        if not line.startswith("{"):
+            continue
+        try:
+            ev = json.loads(line)
+        except json.JSONDecodeError:
+            print("refuse: non-json test output", file=sys.stderr)
+            sys.exit(4)
+        action = ev.get("Action")
+        test = ev.get("Test") or ""
+        pkg = ev.get("Package") or ev.get("ImportPath") or ""
+        if action == "build-fail" or (action == "fail" and ev.get("FailedBuild")):
+            print(f"refuse: build failed {pkg}", file=sys.stderr)
+            sys.exit(1)
+        text = ev.get("Output") or ""
+        if action == "output" and "no tests to run" in text:
+            print(f"refuse: no tests to run in {pkg}", file=sys.stderr)
+            sys.exit(3)
+        if action == "skip" and test:
+            print(f"refuse: skipped {pkg} {test}", file=sys.stderr)
+            sys.exit(2)
+        if action == "fail":
+            failed.append(f"{pkg} {test}".strip())
+        if action == "pass" and test:
+            passed.add(test)
+if failed:
+    print("refuse: failed " + ", ".join(failed), file=sys.stderr)
+    sys.exit(1)
+if not passed:
+    print("refuse: zero tests", file=sys.stderr)
+    sys.exit(3)
+missing = [n for n in require if n not in passed]
+if missing:
+    print("refuse: required tests did not pass: " + ", ".join(missing), file=sys.stderr)
+    sys.exit(5)
+PY
+}
+
+# detect_tap reads node --test --test-reporter=tap output. Exit 1 "not ok" or
+# a fail/cancelled count, 2 a skip/todo directive or count, 3 no passing test,
+# 5 a missing required name. REQUIRE_NAMES holds one test name per line.
+detect_tap() {
+	python3 - "$1" <<'PY'
+import os, re, sys
+path = sys.argv[1]
+require = [n for n in os.environ.get("REQUIRE_NAMES", "").split("\n") if n.strip()]
+passed = set()
+counts = {}
+with open(path, encoding="utf-8", errors="replace") as fh:
+    for raw in fh:
+        line = raw.rstrip("\n")
+        body = line.lstrip()
+        if body.startswith("not ok"):
+            print(f"refuse: {body}", file=sys.stderr)
+            sys.exit(1)
+        m = re.match(r"ok \d+ - (.*?)(\s+#\s*(SKIP|TODO)\b.*)?$", body, re.I)
+        if m:
+            if m.group(2):
+                print(f"refuse: {body}", file=sys.stderr)
+                sys.exit(2)
+            passed.add(m.group(1).replace("\\#", "#"))
+            continue
+        m = re.match(r"# (tests|suites|pass|fail|cancelled|skipped|todo) (\d+)$", line)
+        if m:
+            counts[m.group(1)] = int(m.group(2))
+for key in ("fail", "cancelled"):
+    if counts.get(key, 0) > 0:
+        print(f"refuse: {counts[key]} {key}", file=sys.stderr)
+        sys.exit(1)
+for key in ("skipped", "todo"):
+    if counts.get(key, 0) > 0:
+        print(f"refuse: {counts[key]} {key}", file=sys.stderr)
+        sys.exit(2)
+if counts.get("pass", 0) < 1 or not passed:
+    print("refuse: no passing tests", file=sys.stderr)
+    sys.exit(3)
+missing = [n for n in require if n not in passed]
+if missing:
+    print("refuse: required tests did not pass: " + "; ".join(missing), file=sys.stderr)
+    sys.exit(5)
+PY
+}
+
+go_json() {
+	local dir="$1"
+	shift
+	local log err rc=0 dc=0
+	log="$(mktemp)"
+	err="$(mktemp)"
+	(cd "$dir" && go test -json "$@") >"$log" 2>"$err" || rc=$?
+	detect_go "$log" || dc=$?
+	if [[ "$rc" -ne 0 || "$dc" -ne 0 ]]; then
+		cat "$err" >&2 || true
+		grep -v '^{' "$log" | tail -n 40 >&2 || true
+		python3 -c 'import json,sys
+for raw in open(sys.argv[1], errors="replace"):
+    try: ev = json.loads(raw)
+    except ValueError: continue
+    if ev.get("Action") == "output" and ("FAIL" in ev.get("Output", "") or "_test.go:" in ev.get("Output", "")):
+        sys.stderr.write(ev["Output"])' "$log" 2>&1 | tail -n 40 >&2 || true
+		rm -f "$log" "$err"
+		echo "refuse: go test $* in $dir (test=$rc detect=$dc)" >&2
+		return 1
+	fi
+	echo "go: $(grep -c '"Action":"pass","Package":"[^"]*","Test":"[^"/]*","Elapsed"' "$log") top-level tests passed in $dir ($*)"
+	rm -f "$log" "$err"
+}
+
+# go_named DIR PACKAGES FLAGS NAME... runs exactly the named top-level tests
+# and requires every one of them to pass. PACKAGES and FLAGS are word-split.
+go_named() {
+	local dir="$1" pkgs="$2" flags="$3"
+	shift 3
+	if [[ "$#" -eq 0 ]]; then
+		echo "refuse: go_named $pkgs in $dir without required names" >&2
+		return 1
+	fi
+	local names=("$@") regex
+	regex="^($(IFS='|'; echo "${names[*]}"))\$"
+	# shellcheck disable=SC2086
+	REQUIRE_TESTS="${names[*]}" go_json "$dir" $flags -count=1 -run "$regex" $pkgs
+}
+
+# go_short DIR runs go test -short ./... in DIR; on failure it prints the tail
+# of the output and fails.
+go_short() {
+	local out
+	if ! out="$(cd "$1" && go test -count=1 -short ./... 2>&1)"; then
+		printf '%s\n' "$out" | grep -v '^ok ' | tail -n 60 >&2
+		echo "refuse: go test -short ./... in $1" >&2
+		return 1
+	fi
+	echo "short: $1"
+}
+
+expect_detector() {
+	local detector="$1" name="$2" want="$3" payload="$4" log dc=0
+	log="$(mktemp)"
+	printf '%s\n' "$payload" >"$log"
+	"$detector" "$log" >/dev/null 2>&1 || dc=$?
+	rm -f "$log"
+	if [[ "$dc" -ne "$want" ]]; then
+		echo "refuse: self-test $detector $name: exit $dc, want $want" >&2
+		return 1
+	fi
+}
+
+run_self_test() {
+	bash -n "${BASH_SOURCE[0]}"
+
+	expect_detector detect_go pass 0 '{"Action":"pass","Package":"p","Test":"TestTokenCookieAttributes"}'
+	expect_detector detect_go fail 1 '{"Action":"pass","Package":"p","Test":"TestA"}
+{"Action":"fail","Package":"p","Test":"TestTurnstileVerifyMatrix"}'
+	expect_detector detect_go package-fail 1 '{"Action":"pass","Package":"p","Test":"TestA"}
+{"Action":"fail","Package":"p"}'
+	expect_detector detect_go build 1 '{"Action":"build-fail","ImportPath":"p"}'
+	expect_detector detect_go skip 2 '{"Action":"pass","Package":"p","Test":"TestA"}
+{"Action":"skip","Package":"p","Test":"TestCookieLogoutHandler"}'
+	expect_detector detect_go zero 3 '{"Action":"pass","Package":"p"}'
+	expect_detector detect_go no-tests 3 '{"Action":"output","Package":"p","Output":"testing: warning: no tests to run\n"}
+{"Action":"pass","Package":"p"}'
+	expect_detector detect_go nonjson 4 '{"Action":"pass",'
+	REQUIRE_TESTS="TestTokenCookieAttributes TestTurnstileFormFields" expect_detector detect_go missing-named 5 \
+		'{"Action":"pass","Package":"p","Test":"TestTokenCookieAttributes"}'
+	REQUIRE_TESTS="TestTokenCookie" expect_detector detect_go prefix-is-not-the-test 5 \
+		'{"Action":"pass","Package":"p","Test":"TestTokenCookieAttributes"}'
+	REQUIRE_TESTS="TestRegistry" expect_detector detect_go subtest-is-not-the-test 5 \
+		'{"Action":"pass","Package":"p","Test":"TestOuter/TestRegistry"}
+{"Action":"pass","Package":"p","Test":"TestOther"}'
+
+	local tok='TAP version 13
+ok 1 - sitePurge: a plain test
+ok 2 - sitePurge: escaped \# hash
+1..2
+# tests 2
+# pass 2
+# fail 0
+# cancelled 0
+# skipped 0
+# todo 0'
+	expect_detector detect_tap pass 0 "$tok"
+	REQUIRE_NAMES=$'sitePurge: a plain test\nsitePurge: escaped # hash' expect_detector detect_tap named 0 "$tok"
+	expect_detector detect_tap not-ok 1 'ok 1 - a
+not ok 2 - b
+# pass 1
+# fail 1'
+	expect_detector detect_tap nested-not-ok 1 '    not ok 1 - sub
+ok 1 - a
+# pass 1
+# fail 0'
+	expect_detector detect_tap fail-count 1 'ok 1 - a
+# pass 1
+# fail 1'
+	expect_detector detect_tap cancelled 1 'ok 1 - a
+# pass 1
+# cancelled 1'
+	expect_detector detect_tap skip 2 'ok 1 - a # SKIP later
+# pass 1'
+	expect_detector detect_tap todo-count 2 'ok 1 - a
+# pass 1
+# todo 1'
+	expect_detector detect_tap zero 3 '# tests 0
+# pass 0
+# fail 0'
+	expect_detector detect_tap no-output 3 ''
+	REQUIRE_NAMES=$'sitePurge: a plain test\nmissing' expect_detector detect_tap missing-named 5 "$tok"
+
+	grep -qF '"${PHASE193_REQUIRE_DOCKER:-0}" == "1"' "${BASH_SOURCE[0]}" || {
+		echo "refuse: --all does not honour PHASE193_REQUIRE_DOCKER" >&2
+		return 1
+	}
+	local mode
+	for mode in self-test go docker plugins layers docs all; do
+		grep -q -- "^	--$mode" "${BASH_SOURCE[0]}" || {
+			echo "refuse: missing mode --$mode" >&2
+			return 1
+		}
+	done
+	echo "phase19.3 self-test passed"
+}
+
+require_dir() {
+	[[ -d "$1" ]] || {
+		echo "refuse: $2 $1 not found" >&2
+		return 1
+	}
+}
+
+not_wired() {
+	echo "refuse: stage $1 is not wired yet" >&2
+	return 1
+}
+
+run_go() {
+	(cd "$ROOT" && go vet ./...)
+	echo "vet: $ROOT"
+	(cd "$ROOT" && go vet -tags summercms_s3 ./modules/lagoon/...)
+	echo "vet -tags summercms_s3: $ROOT/modules/lagoon/..."
+	go_short "$ROOT"
+	go_named "$ROOT" ./modules/bouncer -short "${BOUNCER_TESTS[@]}"
+	echo "phase19.3 go passed"
+}
+
+docker_up() {
+	command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1
+}
+
+run_docker() {
+	if ! docker_up; then
+		echo "refuse: the docker stage needs a reachable Docker daemon (testcontainers); run it on a Docker host" >&2
+		return 1
+	fi
+	not_wired docker
+}
+
+run_plugins() {
+	not_wired plugins
+}
+
+run_layers() {
+	not_wired layers
+}
+
+run_docs() {
+	not_wired docs
+}
+
+run_all() {
+	local stage
+	for stage in self-test go plugins layers docs; do
+		if bash "${BASH_SOURCE[0]}" "--$stage"; then
+			echo "PASS $stage"
+		else
+			echo "FAIL $stage"
+			exit 1
+		fi
+	done
+	if docker_up; then
+		if bash "${BASH_SOURCE[0]}" --docker; then
+			echo "PASS docker"
+		else
+			echo "FAIL docker"
+			exit 1
+		fi
+	elif [[ "${PHASE193_REQUIRE_DOCKER:-0}" == "1" ]]; then
+		echo "FAIL docker: no reachable Docker daemon and PHASE193_REQUIRE_DOCKER=1"
+		exit 1
+	else
+		cat >&2 <<'EOF'
+************************************************************************
+NOT RUN docker: no reachable Docker daemon on this host.
+The testcontainers suites (Postgres and Redis) of the framework and the
+plugins did NOT run. Run on a Docker host before /msd-verify-work:
+  bash scripts/check-phase19.3.sh docker
+************************************************************************
+EOF
+		echo "NOT RUN docker (Docker-host only; see the notice above)"
+	fi
+	echo "Phase 19.3 gate passed"
+}
+
+case "${1:---all}" in
+	--self-test | self-test) run_self_test ;;
+	--go | go) run_go ;;
+	--docker | docker) run_docker ;;
+	--plugins | plugins) run_plugins ;;
+	--layers | layers) run_layers ;;
+	--docs | docs) run_docs ;;
+	--all | all) run_all ;;
+	*) usage ;;
+esac