@synopackageland/cli 0.4.1 → 0.5.3

package/templates/_gateway/directory_test.go

@@ -0,0 +1,202 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"net/http/httptest"
+	"os"
+	"slices"
+	"strings"
+	"testing"
+	"time"
+)
+
+const directoryID = `uid=2969567732(VT-NAS\Administrator) gid=2969567745(VT-NAS\Domain Users) groups=2969567745(VT-NAS\Domain Users),2969567751(VT-NAS\Enterprise Admins)`
+
+func TestDirectoryIdentityUsesNSSIncludingPrimaryAndSupplementaryGroups(t *testing.T) {
+	a := newTestAuth(t, &fakeRunner{out: `VT-NAS\Administrator`})
+	var gotUser string
+	a.directoryGroups = func(ctx context.Context, user string) ([]string, error) {
+		gotUser = user
+		if _, ok := ctx.Deadline(); !ok {
+			t.Fatal("missing deadline")
+		}
+		return parseDirectoryGroups([]byte(directoryID))
+	}
+	id, err := a.Authenticate(sessionRequest())
+	if err != nil || gotUser != `VT-NAS\Administrator` || !slices.Equal(id.Groups, []string{`VT-NAS\Domain Users`, `VT-NAS\Enterprise Admins`}) {
+		t.Fatalf("id=%+v user=%q err=%v", id, gotUser, err)
+	}
+}
+
+func TestLocalIdentityNeverNeedsDirectoryLookup(t *testing.T) {
+	a := newTestAuth(t, &fakeRunner{out: "alice"})
+	a.directoryGroups = func(context.Context, string) ([]string, error) {
+		t.Fatal("directory lookup for local account")
+		return nil, nil
+	}
+	id, err := a.Authenticate(sessionRequest())
+	if err != nil || !slices.Contains(id.Groups, "staff") {
+		t.Fatalf("id=%+v err=%v", id, err)
+	}
+}
+
+func TestDirectoryFailureCannotFallBackToLocalMemberLists(t *testing.T) {
+	a := newTestAuth(t, &fakeRunner{out: `OTHER\alice`})
+	if err := os.WriteFile(a.groupFile, []byte("staff:x:1030:OTHER\\alice\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	a.directoryGroups = func(context.Context, string) ([]string, error) { return nil, errors.New("directory unavailable") }
+	if _, err := a.Authenticate(sessionRequest()); err == nil || errors.Is(err, errNoSession) {
+		t.Fatalf("err=%v", err)
+	}
+}
+
+func TestDirectoryMembershipAndSessionAreRecheckedEachRequest(t *testing.T) {
+	runner := &fakeRunner{out: `VT-NAS\Administrator`}
+	a := newTestAuth(t, runner)
+	calls := 0
+	a.directoryGroups = func(context.Context, string) ([]string, error) {
+		calls++
+		if calls == 1 {
+			return []string{`VT-NAS\Domain Users`}, nil
+		}
+		return []string{`VT-NAS\Other`}, nil
+	}
+	id, _ := a.Authenticate(sessionRequest())
+	if !slices.Contains(id.Groups, `VT-NAS\Domain Users`) {
+		t.Fatal(id)
+	}
+	id, _ = a.Authenticate(sessionRequest())
+	if slices.Contains(id.Groups, `VT-NAS\Domain Users`) || calls != 2 {
+		t.Fatal(id, calls)
+	}
+	runner.err = &exitError{}
+	if _, err := a.Authenticate(sessionRequest()); !errors.Is(err, errNoSession) || calls != 2 {
+		t.Fatal(err, calls)
+	}
+}
+
+func TestNSSParserPreservesQualifiedNamesAndFailsClosed(t *testing.T) {
+	for _, text := range []string{directoryID + "\n", `uid=123(alice@example.test) gid=200(staff@example.test) groups=200(staff@example.test),201(Domain Users@example.test)`} {
+		groups, err := parseDirectoryGroups([]byte(text))
+		if err != nil || len(groups) != 2 {
+			t.Fatalf("groups=%q err=%v", groups, err)
+		}
+	}
+	for _, text := range []string{"", "100 101", `uid=1(alice) gid=2(staff) groups=2`, `uid=1(alice) gid=2(staff) groups=3(ops)`, `uid=1(alice) gid=2(staff) groups=2(staff),3`, `uid=1(alice) gid=2(staff) groups=2(staff),3(bad(name))`, directoryID + "\n" + directoryID, `uid=1(alice) gid=2(staff) groups=2(staff),2(ops)`} {
+		if _, err := parseDirectoryGroups([]byte(text)); err == nil {
+			t.Fatalf("accepted %q", text)
+		}
+	}
+}
+
+func TestDirectoryCommandIsBoundedAndHasNoSessionEnvironment(t *testing.T) {
+	var gotPath string
+	var gotArgs, gotEnv []string
+	lookup := directoryLookup{timeout: 20 * time.Millisecond, run: func(ctx context.Context, path string, args, env []string) ([]byte, error) {
+		gotPath, gotArgs, gotEnv = path, args, env
+		if _, ok := ctx.Deadline(); !ok {
+			t.Fatal("missing deadline")
+		}
+		return []byte(directoryID), nil
+	}}
+	if _, err := lookup.groups(context.Background(), `VT-NAS\Administrator`); err != nil {
+		t.Fatal(err)
+	}
+	if gotPath != "/usr/bin/id" || !slices.Equal(gotArgs, []string{`VT-NAS\Administrator`}) || !slices.Equal(gotEnv, []string{"LC_ALL=C"}) {
+		t.Fatal(gotPath, gotArgs, gotEnv)
+	}
+	for _, user := range []string{"", "-G", "--help", "alice\nadmin", "alice;id"} {
+		gotPath = ""
+		if _, err := lookup.groups(context.Background(), user); err == nil || gotPath != "" {
+			t.Fatal(user, err, gotPath)
+		}
+	}
+	lookup.run = func(ctx context.Context, _ string, _, _ []string) ([]byte, error) {
+		<-ctx.Done()
+		return nil, ctx.Err()
+	}
+	if _, err := lookup.groups(context.Background(), "alice"); !errors.Is(err, context.DeadlineExceeded) {
+		t.Fatal(err)
+	}
+}
+
+func TestDirectoryRulesKeepTheDomainAndExactCase(t *testing.T) {
+	for _, name := range []string{`VT-NAS\Domain Users`, `Domain Users@example.test`, `DOMAIN\staff`, `staff@example.test`} {
+		cfg := config{Upstream: "127.0.0.1:1", Access: accessGroups, Groups: []string{name}}
+		g, err := newGateway(cfg, &fakeAuth{})
+		if err != nil {
+			t.Fatal(err)
+		}
+		if !g.permits(identity{Groups: []string{name}}) {
+			t.Fatal(name)
+		}
+		for _, other := range []string{"Domain Users", "staff", `OTHER\Domain Users`, `VT-NAS\domain users`} {
+			if other != name && g.permits(identity{Groups: []string{other}}) {
+				t.Fatal(name, other)
+			}
+		}
+	}
+	g := &gateway{cfg: config{Access: accessAdmins}}
+	if g.permits(identity{Groups: []string{`DOMAIN\administrators`}}) {
+		t.Fatal("domain group became a local administrator")
+	}
+}
+
+func TestDirectoryLookupFailureNeverReachesUpstream(t *testing.T) {
+	a := newTestAuth(t, &fakeRunner{out: `DOMAIN\alice`})
+	a.directoryGroups = func(context.Context, string) ([]string, error) { return nil, errors.New("offline") }
+	g, err := newGateway(config{Upstream: "127.0.0.1:1", Access: accessGroups, Groups: []string{`DOMAIN\staff`}}, a)
+	if err != nil {
+		t.Fatal(err)
+	}
+	w := httptest.NewRecorder()
+	g.ServeHTTP(w, sessionRequest())
+	if w.Header().Get("X-Synopkgland-Error") != "auth_unavailable" {
+		t.Fatal(w.Code, w.Body.String())
+	}
+}
+
+func TestDirectoryIdentitySupportsQualifiedAccountLength(t *testing.T) {
+	user := "DOMAIN\\" + strings.Repeat("a", 100)
+	a := newTestAuth(t, &fakeRunner{out: user})
+	a.directoryGroups = func(context.Context, string) ([]string, error) { return []string{`DOMAIN\staff`}, nil }
+	id, err := a.Authenticate(sessionRequest())
+	if err != nil || id.User != user {
+		t.Fatal(id, err)
+	}
+}
+
+func TestNSSParserBoundsIDsGroupsAndOutput(t *testing.T) {
+	base := `uid=1(alice) gid=2(staff) groups=2(staff)`
+	for _, text := range []string{strings.Replace(base, "uid=1", "uid=4294967295", 1), strings.Replace(base, "gid=2", "gid=4294967296", 1), base + strings.Repeat(",3(ops)", 256), base + strings.Repeat(" ", maxDirectoryOutput), strings.Replace(base, "2(staff)", "02(staff)", -1)} {
+		if _, err := parseDirectoryGroups([]byte(text)); err == nil {
+			t.Fatal("accepted out-of-bounds output")
+		}
+	}
+	var output directoryOutput
+	if _, err := output.Write(make([]byte, maxDirectoryOutput)); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := output.Write([]byte{1}); err == nil || len(output.data) != maxDirectoryOutput {
+		t.Fatal("output not bounded")
+	}
+}
+
+func TestNSSNonzeroExitAndCancellationDiscardEvenValidGroups(t *testing.T) {
+	for _, cancelled := range []bool{false, true} {
+		ctx, cancel := context.WithCancel(context.Background())
+		defer cancel()
+		d := directoryLookup{timeout: time.Second, run: func(context.Context, string, []string, []string) ([]byte, error) {
+			if cancelled {
+				cancel()
+				return []byte(directoryID), nil
+			}
+			return []byte(directoryID), errors.New("exit 1")
+		}}
+		if groups, err := d.groups(ctx, `VT-NAS\Administrator`); err == nil || len(groups) != 0 {
+			t.Fatal(groups, err)
+		}
+	}
+}

package/templates/_gateway/gateway.go

@@ -0,0 +1,412 @@
+package main
+
+// The gateway is the only door to a package's container. DSM runs it as the
+// package account's CGI behind the DSM web server, so a request reaches the
+// container only after DSM's own session check, the access rule of the
+// package, and (for state-changing methods) a SynoToken.
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"net/http/httputil"
+	"net/url"
+	"regexp"
+	"slices"
+	"strconv"
+	"strings"
+	"time"
+)
+
+const (
+	accessUsers  = "users"
+	accessAdmins = "admins"
+	accessGroups = "groups"
+
+	adminGroup = "administrators"
+
+	// gatewayScript is the CGI file name; what follows it in the URL path is the
+	// path inside the container.
+	gatewayScript = "/gateway.cgi"
+
+	// keepErrorBodyHeader is the request header with which an app asks that its own error replies reach it
+	// whole: see keepErrorBody.
+	keepErrorBodyHeader = "X-Synopkgland-Keep-Error-Body"
+
+	defaultMaxBodyBytes    = 64 << 20
+	defaultResponseTimeout = 60 * time.Second
+)
+
+type config struct {
+	// Upstream is the container's published loopback address, host:port.
+	Upstream string `json:"upstream"`
+	// Access is users (any signed-in DSM user), admins or groups.
+	Access string   `json:"access"`
+	Groups []string `json:"groups,omitempty"`
+
+	MaxBodyBytes          int64 `json:"maxBodyBytes,omitempty"`
+	ResponseTimeoutMillis int   `json:"responseTimeoutMillis,omitempty"`
+}
+
+var groupName = regexp.MustCompile(`^(?:[A-Za-z0-9._-]{1,64}|[A-Za-z0-9._-]{1,64}\\[A-Za-z0-9._-](?:[A-Za-z0-9._ -]{0,126}[A-Za-z0-9._-])?|[A-Za-z0-9._-](?:[A-Za-z0-9._ -]{0,126}[A-Za-z0-9._-])?@[A-Za-z0-9._-]{1,64})$`)
+
+func (c config) validate() error {
+	host, port, err := net.SplitHostPort(c.Upstream)
+	if err != nil || (host != "127.0.0.1" && host != "::1") {
+		return fmt.Errorf("upstream %q must be a loopback host:port", c.Upstream)
+	}
+	if n, err := strconv.Atoi(port); err != nil || n < 1 || n > 65535 {
+		return fmt.Errorf("upstream port %q is invalid", port)
+	}
+	switch c.Access {
+	case accessUsers, accessAdmins:
+	case accessGroups:
+		if len(c.Groups) == 0 {
+			return errors.New("access groups needs at least one group")
+		}
+		for _, g := range c.Groups {
+			if !groupName.MatchString(g) {
+				return fmt.Errorf("group %q is invalid", g)
+			}
+		}
+	default:
+		return fmt.Errorf("access %q must be users, admins or groups", c.Access)
+	}
+	return nil
+}
+
+type gateway struct {
+	cfg   config
+	auth  authenticator
+	proxy *httputil.ReverseProxy
+}
+
+// newGateway refuses an unusable configuration or a missing authenticator, so
+// a mistake fails at startup instead of opening the door.
+func newGateway(cfg config, auth authenticator) (*gateway, error) {
+	if auth == nil {
+		return nil, errors.New("newGateway needs an authenticator")
+	}
+	if err := cfg.validate(); err != nil {
+		return nil, err
+	}
+	if cfg.MaxBodyBytes <= 0 {
+		cfg.MaxBodyBytes = defaultMaxBodyBytes
+	}
+	timeout := defaultResponseTimeout
+	if cfg.ResponseTimeoutMillis > 0 {
+		timeout = time.Duration(cfg.ResponseTimeoutMillis) * time.Millisecond
+	}
+	g := &gateway{cfg: cfg, auth: auth}
+	g.proxy = &httputil.ReverseProxy{
+		Rewrite:        g.rewrite,
+		ModifyResponse: g.modifyResponse,
+		ErrorHandler:   g.proxyError,
+		Transport: &http.Transport{
+			Proxy:                 nil,
+			DialContext:           (&net.Dialer{Timeout: 3 * time.Second}).DialContext,
+			ResponseHeaderTimeout: timeout,
+			DisableKeepAlives:     true,
+		},
+	}
+	return g, nil
+}
+
+type ctxKey struct{}
+
+// gatewayRequest is what ServeHTTP worked out before handing over to the proxy.
+type gatewayRequest struct {
+	prefix string // escaped URL path up to and including the CGI file name
+	rest   string // escaped path inside the container, starting with "/"
+	id     identity
+	// keepErrorBody: the app asked for DSM-safe statuses on the container's own error replies.
+	keepErrorBody bool
+}
+
+func (g *gateway) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	// DSM's CGI gateway cuts the reply short if the CGI exits with request
+	// bytes unread, so drain whatever the handling below did not consume.
+	defer io.Copy(io.Discard, io.LimitReader(r.Body, g.cfg.MaxBodyBytes))
+
+	prefix, rest, ok := splitGatewayPath(r.URL.EscapedPath())
+	if !ok {
+		reply(w, http.StatusNotFound, "not_found", "Not a gateway path.")
+		return
+	}
+	id, err := g.auth.Authenticate(r)
+	switch {
+	case errors.Is(err, errNoSession):
+		reply(w, http.StatusUnauthorized, "session_required", "Sign in to DSM to open this app.")
+		return
+	case err != nil:
+		reply(w, http.StatusInternalServerError, "auth_unavailable", "DSM could not verify the session.")
+		return
+	}
+	if !g.permits(id) {
+		reply(w, http.StatusForbidden, "forbidden", "Your DSM account is not allowed to open this app.")
+		return
+	}
+	if !safeMethod(r.Method) {
+		if !wellFormedToken(r.Header.Get("X-SYNO-TOKEN")) {
+			reply(w, http.StatusForbidden, "token_required", "State-changing requests need the DSM SynoToken.")
+			return
+		}
+		if !sameOrigin(r) {
+			reply(w, http.StatusForbidden, "cross_site_blocked", "State-changing requests must come from this DSM's own pages.")
+			return
+		}
+	}
+	if isUpgrade(r) {
+		switch {
+		case !isWebSocket(r):
+			reply(w, http.StatusNotImplemented, "upgrade_unsupported", "Only WebSocket upgrades pass through the DSM gateway.")
+			return
+		case !sameOrigin(r):
+			// A browser cannot add the SynoToken header to a WebSocket handshake, so the same-origin evidence
+			// (the rule state-changing requests use) is what keeps another site from opening a socket with the user's DSM cookie.
+			reply(w, http.StatusForbidden, "cross_site_blocked", "The WebSocket must be opened from this DSM's own pages.")
+			return
+		}
+	}
+	if rest == "" {
+		// Relative links in the app only resolve under a trailing slash.
+		location := strings.TrimPrefix(gatewayScript, "/") + "/"
+		if r.URL.RawQuery != "" {
+			location += "?" + r.URL.RawQuery
+		}
+		w.Header().Set("Location", location)
+		reply(w, http.StatusPermanentRedirect, "redirect", "Open the app with a trailing slash.")
+		return
+	}
+	if !safeContainerPath(rest) {
+		reply(w, http.StatusBadRequest, "bad_path", "The path is not allowed.")
+		return
+	}
+	r.Body = http.MaxBytesReader(w, r.Body, g.cfg.MaxBodyBytes)
+	g.proxy.ServeHTTP(w, r.WithContext(context.WithValue(r.Context(), ctxKey{}, gatewayRequest{prefix: prefix, rest: rest, id: id, keepErrorBody: r.Header.Get(keepErrorBodyHeader) == "1"})))
+}
+
+func (g *gateway) permits(id identity) bool {
+	switch g.cfg.Access {
+	case accessUsers:
+		return true
+	case accessAdmins:
+		return slices.Contains(id.Groups, adminGroup)
+	default:
+		return slices.ContainsFunc(id.Groups, func(group string) bool { return slices.Contains(g.cfg.Groups, group) })
+	}
+}
+
+func splitGatewayPath(escaped string) (prefix, rest string, ok bool) {
+	i := strings.Index(escaped, gatewayScript)
+	if i < 0 {
+		return "", "", false
+	}
+	end := i + len(gatewayScript)
+	rest = escaped[end:]
+	if rest != "" && rest[0] != '/' {
+		return "", "", false
+	}
+	return escaped[:end], rest, true
+}
+
+// safeContainerPath keeps the request inside the container's own URL space:
+// no dot segments, no authority-looking "//", no NUL, no backslash.
+func safeContainerPath(escaped string) bool {
+	decoded, err := url.PathUnescape(escaped)
+	if err != nil || strings.HasPrefix(decoded, "//") || strings.ContainsAny(decoded, "\x00\\") {
+		return false
+	}
+	return !slices.Contains(strings.Split(decoded, "/"), "..") && !slices.Contains(strings.Split(decoded, "/"), ".")
+}
+
+func safeMethod(method string) bool {
+	return method == http.MethodGet || method == http.MethodHead || method == http.MethodOptions
+}
+
+func isUpgrade(r *http.Request) bool {
+	if r.Header.Get("Upgrade") != "" {
+		return true
+	}
+	for _, v := range r.Header.Values("Connection") {
+		for _, token := range strings.Split(v, ",") {
+			if strings.EqualFold(strings.TrimSpace(token), "upgrade") {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+func isWebSocket(r *http.Request) bool {
+	return strings.EqualFold(strings.TrimSpace(r.Header.Get("Upgrade")), "websocket")
+}
+
+// Inbound headers that carry or imitate identity, session or proxy state. The
+// container trusts only the X-Syno-User and X-Syno-Admin the gateway sets
+// after DSM verified the session, so the client's own copies never get through.
+var droppedExact = map[string]bool{"Cookie": true, "Remote-User": true, "Remote-Groups": true, "Remote-Email": true, "Remote-Name": true, "Forwarded": true}
+
+func dropsHeader(name string) bool {
+	canonical := http.CanonicalHeaderKey(name)
+	if droppedExact[canonical] {
+		return true
+	}
+	for _, prefix := range []string{"X-Syno-", "X-Forwarded-", "X-Remote-", "X-Auth", "X-Real-", "Remote-"} {
+		if strings.HasPrefix(canonical, prefix) {
+			return true
+		}
+	}
+	return false
+}
+
+func (g *gateway) rewrite(pr *httputil.ProxyRequest) {
+	gr := pr.In.Context().Value(ctxKey{}).(gatewayRequest)
+	decoded, _ := url.PathUnescape(gr.rest)
+	pr.Out.URL = &url.URL{Scheme: "http", Host: g.cfg.Upstream, Path: decoded, RawPath: gr.rest, RawQuery: withoutSynoToken(pr.In.URL.RawQuery)}
+	pr.Out.Host = g.cfg.Upstream
+	if isUpgrade(pr.In) {
+		// The Origin was checked against this host; the container's own same-origin check needs to see it too.
+		pr.Out.Host = pr.In.Host
+	}
+	for name := range pr.Out.Header {
+		if dropsHeader(name) {
+			pr.Out.Header.Del(name)
+		}
+	}
+	pr.Out.Header.Set("X-Syno-User", gr.id.User)
+	pr.Out.Header.Set("X-Syno-Admin", strconv.FormatBool(slices.Contains(gr.id.Groups, adminGroup)))
+}
+
+// withoutSynoToken keeps the CSRF token out of the container's logs.
+func withoutSynoToken(rawQuery string) string {
+	if rawQuery == "" {
+		return ""
+	}
+	var kept []string
+	for _, pair := range strings.Split(rawQuery, "&") {
+		key, _, _ := strings.Cut(pair, "=")
+		if k, err := url.QueryUnescape(key); err == nil && k == "SynoToken" {
+			continue
+		}
+		kept = append(kept, pair)
+	}
+	return strings.Join(kept, "&")
+}
+
+func (g *gateway) modifyResponse(resp *http.Response) error {
+	gr := resp.Request.Context().Value(ctxKey{}).(gatewayRequest)
+	// The container shares DSM's origin; it must not be able to set or clear
+	// DSM's own cookies.
+	resp.Header.Del("Set-Cookie")
+	if resp.StatusCode != http.StatusSwitchingProtocols {
+		resp.Header.Set("Cache-Control", privateCacheControl(resp.Header.Get("Cache-Control")))
+		resp.Header.Add("Vary", "Cookie")
+	}
+	if location := resp.Header.Get("Location"); location != "" {
+		resp.Header.Set("Location", g.rewriteLocation(location, gr.prefix))
+	}
+	if gr.keepErrorBody {
+		keepErrorBody(resp)
+	}
+	return nil
+}
+
+// keepErrorBody swaps a container status that DSM would replace for its stand-in, so the body and headers
+// the container sent reach the app. Opt-in per request: the app then reads X-Synopkgland-Status for the
+// status the container really sent. Without it the container's own status goes out untouched.
+func keepErrorBody(resp *http.Response) {
+	if safe := dsmSafeStatus(resp.StatusCode); safe != resp.StatusCode {
+		resp.Header.Set("X-Synopkgland-Status", strconv.Itoa(resp.StatusCode))
+		resp.StatusCode, resp.Status = safe, strconv.Itoa(safe)+" "+http.StatusText(safe)
+	}
+}
+
+func privateCacheControl(value string) string {
+	kept := []string{"private"}
+	for _, directive := range strings.Split(value, ",") {
+		directive = strings.TrimSpace(directive)
+		name, _, _ := strings.Cut(strings.ToLower(directive), "=")
+		if directive != "" && name != "public" && name != "private" && name != "s-maxage" {
+			kept = append(kept, directive)
+		}
+	}
+	return strings.Join(kept, ", ")
+}
+
+// rewriteLocation points root-relative and container-absolute redirects back
+// under the gateway path; relative and foreign locations pass through.
+func (g *gateway) rewriteLocation(location, prefix string) string {
+	u, err := url.Parse(location)
+	if err != nil {
+		return location
+	}
+	switch {
+	case u.Host == g.cfg.Upstream && (u.Scheme == "http" || u.Scheme == "https"):
+		u.Scheme, u.Host = "", ""
+	case u.Scheme != "" || u.Host != "":
+		return location
+	}
+	if !strings.HasPrefix(u.EscapedPath(), "/") {
+		return location
+	}
+	u.Path, u.RawPath = "", prefix+u.EscapedPath()
+	u.Path, _ = url.PathUnescape(u.RawPath)
+	return u.String()
+}
+
+func (g *gateway) proxyError(w http.ResponseWriter, r *http.Request, err error) {
+	var tooLarge *http.MaxBytesError
+	var netErr net.Error
+	var opErr *net.OpError
+	switch {
+	case errors.As(err, &tooLarge):
+		reply(w, http.StatusRequestEntityTooLarge, "body_too_large", "The request body is too large.")
+	case errors.Is(err, context.DeadlineExceeded) || (errors.As(err, &netErr) && netErr.Timeout()):
+		reply(w, http.StatusGatewayTimeout, "upstream_timeout", "The app did not answer in time.")
+	case errors.As(err, &opErr) && opErr.Op == "dial":
+		w.Header().Set("Retry-After", "5")
+		reply(w, http.StatusServiceUnavailable, "upstream_unavailable", "The app is not running. Start the package in Package Center and try again.")
+	default:
+		reply(w, http.StatusBadGateway, "bad_gateway", "The app returned an invalid response.")
+	}
+}
+
+// DSM's nginx runs `scgi_intercept_errors on` with `error_page 403 404 500 502 503 504`, so a CGI reply with
+// one of these statuses loses its body and headers to DSM's generic error page (measured on DSM 7.4-90069;
+// every other status, 4xx and 5xx alike, passes with body and headers intact). Each replaced status has a
+// stand-in the app can read; the status the reply would have had travels in X-Synopkgland-Status.
+var dsmReplacedStatus = map[int]int{
+	http.StatusForbidden:           http.StatusUnauthorized,
+	http.StatusNotFound:            http.StatusGone,
+	http.StatusInternalServerError: 520, // unregistered (Cloudflare "unknown error"); clients treat it as 500
+	http.StatusBadGateway:          520,
+	http.StatusServiceUnavailable:  521, // unregistered (Cloudflare "web server is down")
+	http.StatusGatewayTimeout:      524, // unregistered (Cloudflare "a timeout occurred")
+}
+
+func dsmSafeStatus(status int) int {
+	if safe, replaced := dsmReplacedStatus[status]; replaced {
+		return safe
+	}
+	return status
+}
+
+// reply answers with one of the gateway's own errors. `intended` is the status the error means; the status
+// sent is the one DSM lets through, and X-Synopkgland-Error carries the machine-readable code.
+func reply(w http.ResponseWriter, intended int, code, message string) {
+	status := dsmSafeStatus(intended)
+	h := w.Header()
+	h.Set("Content-Type", "text/plain; charset=utf-8")
+	h.Set("Cache-Control", "no-store")
+	h.Set("X-Content-Type-Options", "nosniff")
+	h.Set("X-Synopkgland-Error", code)
+	if status != intended {
+		h.Set("X-Synopkgland-Status", strconv.Itoa(intended))
+	}
+	w.WriteHeader(status)
+	fmt.Fprintf(w, "%s\n%s\n", code, message)
+}