@synopackageland/cli 0.3.10 → 0.4.0

package/dist/templates/native-go/backend/cmd/app/main.go

@@ -0,0 +1,49 @@
+// Command app is the package backend. DSM runs it as a CGI (ui/cgi/api.cgi in
+// the package) under the package account, once per request.
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"log"
+	"net/http/cgi"
+	"os"
+
+	"dsmapp/internal/api"
+	"dsmapp/internal/app"
+	"dsmapp/internal/dsm"
+	"dsmapp/internal/helper"
+)
+
+// Set by `synopkgland build-spk` through -ldflags -X; never read from a request.
+var (
+	packageID       = "dev"
+	version         = "0.0.0"
+	helperInventory = ""
+)
+
+func main() {
+	log.SetFlags(0)
+	log.SetPrefix(packageID + ": ")
+	if os.Getenv("GATEWAY_INTERFACE") == "" {
+		fmt.Fprintf(os.Stderr, "%s %s: this program runs as the package's DSM CGI; open the app from the DSM main menu.\n", packageID, version)
+		os.Exit(2)
+	}
+	cfg := app.Config{
+		PackageID: packageID,
+		Version:   version,
+		DataDir:   "/var/packages/" + packageID + "/var",
+	}
+	if helperInventory != "" {
+		if json.Unmarshal([]byte(helperInventory), &cfg.HelperInventory) != nil || cfg.HelperInventory.Package != packageID || cfg.HelperInventory.Version != version {
+			cfg.HelperInventory = helper.Inventory{Package: packageID}
+		}
+	}
+	srv, err := api.NewServer(dsm.NewAuthenticator(), app.Routes(cfg)...)
+	if err != nil {
+		log.Fatal(err)
+	}
+	if err := cgi.Serve(srv); err != nil {
+		log.Fatal(err)
+	}
+}

package/dist/templates/native-go/backend/cmd/helper/main.go

@@ -0,0 +1,38 @@
+// Built only when dsm-package.yaml explicitly opts into integration.
+package main
+
+import (
+	"context"
+	"dsmapp/internal/helper"
+	"encoding/json"
+	"fmt"
+	"os"
+)
+
+var helperInventory string
+
+func main() {
+	var i helper.Inventory
+	if len(os.Args) != 2 || json.Unmarshal([]byte(helperInventory), &i) != nil {
+		os.Exit(2)
+	}
+	if os.Args[1] == "check-stopped" || os.Args[1] == "diagnose" {
+		c, err := helper.LocalClient(i)
+		if err != nil {
+			os.Exit(1)
+		}
+		if os.Args[1] == "diagnose" {
+			json.NewEncoder(os.Stdout).Encode(c.Status(context.Background()))
+			return
+		}
+		if c.CheckStopped(context.Background()) != nil {
+			os.Exit(1)
+		}
+		return
+	}
+	if err := helper.RunLinux(i, os.Args[1]); err != nil {
+		fmt.Fprintln(os.Stderr, "helper lifecycle refused")
+		os.Exit(1)
+	}
+	fmt.Println(`{"success":true}`)
+}

package/dist/templates/native-go/backend/go.mod

@@ -0,0 +1,3 @@
+module dsmapp
+
+go 1.24

package/dist/templates/native-go/backend/internal/api/errors.go

@@ -0,0 +1,33 @@
+package api
+
+import (
+	"errors"
+	"log"
+)
+
+// Error is an API error the browser may see. Any other error a handler
+// returns is logged and reported only as "internal". Errors travel in the
+// JSON envelope with HTTP 200, as DSM's own WebAPI does: DSM's web server
+// replaces the body of a CGI's 403, 404 and 5xx replies with its own page.
+type Error struct {
+	Code    string
+	Message string
+}
+
+func (e *Error) Error() string { return e.Code + ": " + e.Message }
+
+// BadRequest reports invalid params.
+func BadRequest(message string) *Error {
+	return &Error{"bad_request", message}
+}
+
+var internalError = &Error{"internal", "internal error"}
+
+func asError(err error) *Error {
+	var apiErr *Error
+	if errors.As(err, &apiErr) {
+		return apiErr
+	}
+	log.Printf("handler error: %v", err)
+	return internalError
+}

package/dist/templates/native-go/backend/internal/api/registry.go

@@ -0,0 +1,94 @@
+// Package api is the package's one HTTP entry point. Every request passes the
+// same transport guards and, unless its route was explicitly declared Public,
+// one DSM authentication before any handler runs. The policy is part of the
+// route itself: a Route can only be made through User, Admin or Public, so a
+// handler cannot be registered without saying who may call it.
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"regexp"
+)
+
+type policy int
+
+const (
+	policyUnset policy = iota
+	policyUser
+	policyAdmin
+	policyPublic
+)
+
+// Handler runs one business operation. It receives the caller the server
+// verified and the raw `params` object; it decodes params itself.
+type Handler func(ctx context.Context, caller Caller, params json.RawMessage) (any, error)
+
+// Route binds a method name to its handler and access policy. Its fields are
+// private: build routes with User, Admin or Public.
+type Route struct {
+	method  string
+	policy  policy
+	handler Handler
+}
+
+// User declares an operation any signed-in DSM user may call.
+func User(method string, h Handler) Route { return Route{method, policyUser, h} }
+
+// Admin declares an operation only members of DSM's administrators group may call.
+func Admin(method string, h Handler) Route { return Route{method, policyAdmin, h} }
+
+// Public declares an operation that runs WITHOUT a DSM session. Use it only for
+// data that is safe to show anyone who can reach the NAS's DSM port.
+func Public(method string, h Handler) Route { return Route{method, policyPublic, h} }
+
+// Identity is what an Authenticator established about the requester.
+type Identity struct {
+	User  string
+	Admin bool
+}
+
+// Caller is the verified requester handed to handlers. Only the server sets
+// its fields, so a handler cannot fabricate an authenticated caller; the zero
+// value carries no authority.
+type Caller struct {
+	identity      Identity
+	authenticated bool
+}
+
+func (c Caller) Authenticated() bool { return c.authenticated }
+func (c Caller) User() string        { return c.identity.User }
+func (c Caller) Admin() bool         { return c.authenticated && c.identity.Admin }
+
+var methodName = regexp.MustCompile(`^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$`)
+
+func buildRegistry(routes []Route) (map[string]Route, error) {
+	registry := make(map[string]Route, len(routes))
+	for _, r := range routes {
+		if r.policy == policyUnset {
+			return nil, errors.New("route without access policy: build it with api.User, api.Admin or api.Public")
+		}
+		if !methodName.MatchString(r.method) {
+			return nil, fmt.Errorf("route %q: method must look like \"area.action\" (lowercase)", r.method)
+		}
+		if r.handler == nil {
+			return nil, fmt.Errorf("route %q has no handler", r.method)
+		}
+		if _, dup := registry[r.method]; dup {
+			return nil, fmt.Errorf("route %q is registered twice", r.method)
+		}
+		registry[r.method] = r
+	}
+	return registry, nil
+}
+
+// Method is the route's method name, e.g. "greeting.set".
+func (r Route) Method() string { return r.method }
+
+// Public reports whether the route was declared with Public.
+func (r Route) Public() bool { return r.policy == policyPublic }
+
+// AdminOnly reports whether the route was declared with Admin.
+func (r Route) AdminOnly() bool { return r.policy == policyAdmin }

package/dist/templates/native-go/backend/internal/api/registry_test.go

@@ -0,0 +1,329 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+// fakeAuth returns a fixed outcome and counts how often it was consulted, so
+// tests can prove each request authenticates at most once.
+type fakeAuth struct {
+	user  string
+	admin bool
+	err   error
+	calls int
+}
+
+func (f *fakeAuth) Authenticate(*http.Request) (Identity, error) {
+	f.calls++
+	if f.err != nil {
+		return Identity{}, f.err
+	}
+	return Identity{User: f.user, Admin: f.admin}, nil
+}
+
+func post(t *testing.T, srv http.Handler, body string, mutate ...func(*http.Request)) (*httptest.ResponseRecorder, envelope) {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodPost, "http://nas.local/webman/3rdparty/App/cgi/api.cgi", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	for _, m := range mutate {
+		m(req)
+	}
+	rec := httptest.NewRecorder()
+	srv.ServeHTTP(rec, req)
+	var env envelope
+	if err := json.Unmarshal(rec.Body.Bytes(), &env); err != nil {
+		t.Fatalf("response is not JSON: %q", rec.Body.String())
+	}
+	return rec, env
+}
+
+type envelope struct {
+	Success bool            `json:"success"`
+	Data    json.RawMessage `json:"data"`
+	Error   *struct {
+		Code string `json:"code"`
+	} `json:"error"`
+}
+
+func countingRoutes(counter *int) []Route {
+	h := func(_ context.Context, c Caller, _ json.RawMessage) (any, error) {
+		*counter++
+		return map[string]string{"user": c.User()}, nil
+	}
+	return []Route{
+		User("demo.user", h),
+		Admin("demo.admin", h),
+	}
+}
+
+func newTestServer(t *testing.T, auth Authenticator, routes ...Route) *Server {
+	t.Helper()
+	srv, err := NewServer(auth, routes...)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return srv
+}
+
+func TestUserRouteRunsForAuthenticatedUserWithVerifiedCaller(t *testing.T) {
+	var executed int
+	auth := &fakeAuth{user: "alice"}
+	srv := newTestServer(t, auth, countingRoutes(&executed)...)
+
+	rec, env := post(t, srv, `{"method":"demo.user"}`)
+
+	if rec.Code != http.StatusOK || !env.Success {
+		t.Fatalf("got %d %s", rec.Code, rec.Body.String())
+	}
+	if string(env.Data) != `{"user":"alice"}` {
+		t.Fatalf("data = %s", env.Data)
+	}
+	if executed != 1 || auth.calls != 1 {
+		t.Fatalf("executed=%d auth=%d, want 1/1", executed, auth.calls)
+	}
+}
+
+func TestEveryProtectedRouteRefusesMissingInvalidAndUnavailableAuth(t *testing.T) {
+	cases := []struct {
+		name string
+		err  error
+		code string
+	}{
+		{"missing session", ErrNoSession, "session_required"},
+		{"invalid session", ErrNoSession, "session_required"},
+		{"auth unavailable", errors.New("authenticate.cgi crashed"), "auth_unavailable"},
+	}
+	for _, method := range []string{"demo.user", "demo.admin"} {
+		for _, tc := range cases {
+			t.Run(method+"/"+tc.name, func(t *testing.T) {
+				var executed int
+				auth := &fakeAuth{err: tc.err}
+				srv := newTestServer(t, auth, countingRoutes(&executed)...)
+
+				rec, env := post(t, srv, `{"method":"`+method+`"}`)
+
+				if rec.Code != http.StatusOK || env.Success || env.Error.Code != tc.code {
+					t.Fatalf("got %d %s", rec.Code, rec.Body.String())
+				}
+				if executed != 0 || auth.calls != 1 {
+					t.Fatalf("executed=%d auth=%d, want 0/1", executed, auth.calls)
+				}
+			})
+		}
+	}
+}
+
+func TestAdminRouteRefusesNonAdminWithoutExecuting(t *testing.T) {
+	var executed int
+	srv := newTestServer(t, &fakeAuth{user: "bob"}, countingRoutes(&executed)...)
+
+	rec, env := post(t, srv, `{"method":"demo.admin"}`)
+
+	if rec.Code != http.StatusOK || env.Error.Code != "admin_required" || executed != 0 {
+		t.Fatalf("got %d %s executed=%d", rec.Code, rec.Body.String(), executed)
+	}
+}
+
+func TestAdminRouteRunsForAdmin(t *testing.T) {
+	var executed int
+	srv := newTestServer(t, &fakeAuth{user: "root-admin", admin: true}, countingRoutes(&executed)...)
+
+	rec, _ := post(t, srv, `{"method":"demo.admin"}`)
+
+	if rec.Code != http.StatusOK || executed != 1 {
+		t.Fatalf("got %d executed=%d", rec.Code, executed)
+	}
+}
+
+func TestUnknownMethodNeedsSessionThenIsNotFound(t *testing.T) {
+	var executed int
+	srv := newTestServer(t, &fakeAuth{err: ErrNoSession}, countingRoutes(&executed)...)
+	_, env := post(t, srv, `{"method":"demo.missing"}`)
+	if env.Error == nil || env.Error.Code != "session_required" {
+		t.Fatalf("anonymous unknown method: got %+v, want session_required (no route probing)", env.Error)
+	}
+
+	srv = newTestServer(t, &fakeAuth{user: "alice", admin: true}, countingRoutes(&executed)...)
+	rec, env := post(t, srv, `{"method":"demo.missing"}`)
+	if rec.Code != http.StatusOK || env.Error.Code != "unknown_method" || executed != 0 {
+		t.Fatalf("got %d %s executed=%d", rec.Code, rec.Body.String(), executed)
+	}
+}
+
+func TestPublicRouteIsExplicitAndSkipsAuthentication(t *testing.T) {
+	var executed int
+	auth := &fakeAuth{err: ErrNoSession}
+	srv := newTestServer(t, auth, Public("demo.ping", func(_ context.Context, c Caller, _ json.RawMessage) (any, error) {
+		executed++
+		if c.Authenticated() {
+			t.Error("public handler received an authenticated caller")
+		}
+		return "pong", nil
+	}))
+
+	rec, _ := post(t, srv, `{"method":"demo.ping"}`)
+
+	if rec.Code != http.StatusOK || executed != 1 || auth.calls != 0 {
+		t.Fatalf("got %d executed=%d auth=%d", rec.Code, executed, auth.calls)
+	}
+}
+
+func TestTransportGuardsRunBeforeAuthenticationAndDispatch(t *testing.T) {
+	cases := []struct {
+		name   string
+		body   string
+		mutate func(*http.Request)
+		code   string
+	}{
+		{"GET", `{"method":"demo.user"}`, func(r *http.Request) { r.Method = http.MethodGet }, "method_not_allowed"},
+		{"form post", `{"method":"demo.user"}`, func(r *http.Request) { r.Header.Set("Content-Type", "text/plain") }, "json_required"},
+		{"cross-site fetch", `{"method":"demo.user"}`, func(r *http.Request) { r.Header.Set("Sec-Fetch-Site", "cross-site") }, "cross_origin"},
+		{"foreign origin", `{"method":"demo.user"}`, func(r *http.Request) { r.Header.Set("Origin", "https://evil.example") }, "cross_origin"},
+		{"oversized body", `{"method":"demo.user","params":"` + strings.Repeat("x", MaxRequestBytes) + `"}`, nil, "request_too_large"},
+		{"malformed JSON", `{"method":`, nil, "bad_request"},
+		{"unknown field", `{"method":"demo.user","user":"admin"}`, nil, "bad_request"},
+		{"trailing data", `{"method":"demo.user"}{}`, nil, "bad_request"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			var executed int
+			auth := &fakeAuth{user: "alice", admin: true}
+			srv := newTestServer(t, auth, countingRoutes(&executed)...)
+			mutate := []func(*http.Request){}
+			if tc.mutate != nil {
+				mutate = append(mutate, tc.mutate)
+			}
+
+			rec, env := post(t, srv, tc.body, mutate...)
+
+			if rec.Code != http.StatusOK || env.Error == nil || env.Error.Code != tc.code {
+				t.Fatalf("got %d %s", rec.Code, rec.Body.String())
+			}
+			if executed != 0 || auth.calls != 0 {
+				t.Fatalf("executed=%d auth=%d, want 0/0", executed, auth.calls)
+			}
+		})
+	}
+}
+
+// countingReader records how much of the request body the server consumed.
+type countingReader struct {
+	r    io.Reader
+	read int
+}
+
+func (c *countingReader) Read(p []byte) (int, error) {
+	n, err := c.r.Read(p)
+	c.read += n
+	return n, err
+}
+
+// DSM's CGI gateway cuts the reply short when a CGI exits without reading
+// its stdin, so every refusal still consumes the request body.
+func TestRefusalsConsumeTheWholeRequestBody(t *testing.T) {
+	cases := map[string]func(*http.Request){
+		"form post":  func(r *http.Request) { r.Header.Set("Content-Type", "text/plain") },
+		"cross-site": func(r *http.Request) { r.Header.Set("Sec-Fetch-Site", "cross-site") },
+		"GET":        func(r *http.Request) { r.Method = http.MethodGet },
+		"oversized":  func(*http.Request) {},
+	}
+	for name, mutate := range cases {
+		t.Run(name, func(t *testing.T) {
+			var executed int
+			srv := newTestServer(t, &fakeAuth{user: "alice"}, countingRoutes(&executed)...)
+			body := `{"method":"demo.user"}`
+			if name == "oversized" {
+				body = `{"method":"demo.user","params":"` + strings.Repeat("x", 2*MaxRequestBytes) + `"}`
+			}
+			reader := &countingReader{r: strings.NewReader(body)}
+			req := httptest.NewRequest(http.MethodPost, "http://nas.local/api.cgi", reader)
+			req.Header.Set("Content-Type", "application/json")
+			mutate(req)
+			srv.ServeHTTP(httptest.NewRecorder(), req)
+			if reader.read != len(body) {
+				t.Fatalf("read %d of %d body bytes", reader.read, len(body))
+			}
+		})
+	}
+}
+
+func TestSameOriginRequestIsAccepted(t *testing.T) {
+	var executed int
+	srv := newTestServer(t, &fakeAuth{user: "alice"}, countingRoutes(&executed)...)
+	rec, _ := post(t, srv, `{"method":"demo.user"}`, func(r *http.Request) {
+		r.Header.Set("Origin", "http://nas.local")
+		r.Header.Set("Sec-Fetch-Site", "same-origin")
+	})
+	if rec.Code != http.StatusOK {
+		t.Fatalf("got %d %s", rec.Code, rec.Body.String())
+	}
+}
+
+func TestResponsesAreUncachedJSON(t *testing.T) {
+	var executed int
+	srv := newTestServer(t, &fakeAuth{err: ErrNoSession}, countingRoutes(&executed)...)
+	rec, _ := post(t, srv, `{"method":"demo.user"}`)
+	if got := rec.Header().Get("Cache-Control"); got != "no-store" {
+		t.Errorf("Cache-Control = %q", got)
+	}
+	if got := rec.Header().Get("Content-Type"); got != "application/json" {
+		t.Errorf("Content-Type = %q", got)
+	}
+}
+
+func TestHandlerErrorsKeepTheirCodeButInternalErrorsAreHidden(t *testing.T) {
+	srv := newTestServer(t, &fakeAuth{user: "alice"},
+		User("demo.invalid", func(context.Context, Caller, json.RawMessage) (any, error) {
+			return nil, BadRequest("text must not be empty")
+		}),
+		User("demo.crash", func(context.Context, Caller, json.RawMessage) (any, error) {
+			return nil, errors.New("disk path /secret/xyz failed")
+		}),
+		User("demo.panic", func(context.Context, Caller, json.RawMessage) (any, error) {
+			panic("boom")
+		}),
+	)
+
+	rec, env := post(t, srv, `{"method":"demo.invalid"}`)
+	if rec.Code != http.StatusOK || env.Error.Code != "bad_request" || !strings.Contains(rec.Body.String(), "text must not be empty") {
+		t.Fatalf("got %d %s", rec.Code, rec.Body.String())
+	}
+	for _, method := range []string{"demo.crash", "demo.panic"} {
+		rec, env = post(t, srv, `{"method":"`+method+`"}`)
+		if rec.Code != http.StatusOK || env.Error.Code != "internal" || strings.Contains(rec.Body.String(), "secret") || strings.Contains(rec.Body.String(), "boom") {
+			t.Fatalf("%s: got %d %s", method, rec.Code, rec.Body.String())
+		}
+	}
+}
+
+func TestRegistryRefusesUnusableRoutes(t *testing.T) {
+	h := func(context.Context, Caller, json.RawMessage) (any, error) { return nil, nil }
+	cases := map[string][]Route{
+		"zero route (no policy)": {{}},
+		"nil handler":            {User("demo.nil", nil)},
+		"bad method name":        {User("Demo Method", h)},
+		"duplicate method":       {User("demo.x", h), Admin("demo.x", h)},
+	}
+	for name, routes := range cases {
+		if _, err := NewServer(&fakeAuth{}, routes...); err == nil {
+			t.Errorf("%s: NewServer accepted it", name)
+		}
+	}
+	if _, err := NewServer(nil, User("demo.x", h)); err == nil {
+		t.Error("NewServer accepted a nil authenticator")
+	}
+}
+
+func TestZeroCallerIsNotAuthenticated(t *testing.T) {
+	var c Caller
+	if c.Authenticated() || c.Admin() || c.User() != "" {
+		t.Fatal("a Caller built outside the server must carry no authority")
+	}
+}