@synopackageland/cli 0.3.10 → 0.4.1

package/dist/templates/native-go/backend/cmd/dsm-readonly-probe/main_linux.go

@@ -0,0 +1,46 @@
+// A standalone evidence-only static probe. No helper activation or mutation.
+package main
+
+import (
+	"context"
+	"dsmapp/internal/dsmprobe"
+	"encoding/json"
+	"golang.org/x/sys/unix"
+	"io"
+	"os"
+	"runtime"
+	"time"
+)
+
+func main() {
+	if len(os.Args) != 2 || os.Args[1] != "--wire-v1" {
+		os.Exit(2)
+	}
+	// Watchdog owns this bounded observation; no children or services are created.
+	go func() { time.Sleep(8 * time.Second); os.Exit(124) }()
+	runtime.LockOSThread()
+	if unix.Prctl(unix.PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0) != nil || unix.Prctl(unix.PR_SET_DUMPABLE, 0, 0, 0, 0) != nil {
+		os.Exit(3)
+	}
+	data, e := io.ReadAll(io.LimitReader(os.Stdin, dsmprobe.MaxRequestBytes+1))
+	if e != nil {
+		os.Exit(2)
+	}
+	request, e := dsmprobe.DecodeRequest(data)
+	if e != nil {
+		os.Exit(2)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 7*time.Second)
+	defer cancel()
+	out, e := dsmprobe.Collect(ctx, request)
+	if e != nil {
+		out.Status = "unsupported"
+	}
+	data, e = json.Marshal(out)
+	if e != nil || len(data) > dsmprobe.MaxResponseBytes {
+		os.Exit(3)
+	}
+	if _, e = os.Stdout.Write(append(data, '\n')); e != nil {
+		os.Exit(3)
+	}
+}

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,7 @@
+module dsmapp
+
+go 1.24
+
+require github.com/godbus/dbus/v5 v5.2.2
+
+require golang.org/x/sys v0.27.0 // indirect

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

@@ -0,0 +1,4 @@
+github.com/godbus/dbus/v5 v5.2.2 h1:TUR3TgtSVDmjiXOgAAyaZbYmIeP3DPkld3jgKGV8mXQ=
+github.com/godbus/dbus/v5 v5.2.2/go.mod h1:3AAv2+hPq5rdnr5txxxRwiGjPXamgoIHgz9FPBfOp3c=
+golang.org/x/sys v0.27.0 h1:wBqf8DvsY9Y/2P8gAfPDEYNuS30J4lPHJxXSb/nJZ+s=
+golang.org/x/sys v0.27.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=

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

@@ -0,0 +1,154 @@
+package api
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"regexp"
+	"strconv"
+	"sync"
+	"time"
+)
+
+const MaxBinaryReadBytes = 1 << 20
+const BinaryReadTimeout = 10 * time.Second
+
+// Control IDs are not bearer authority. The trusted adapter must revalidate
+// the original caller/session, epoch, grant revision and every chunk ticket.
+// The fixed route accepts no path, offset, range, URL, filename or MIME type.
+type BinaryReadRequest struct {
+	OperationID string `json:"operationId"`
+	Epoch       string `json:"epoch"`
+	Token       string `json:"token"`
+}
+
+// Body must implement Close concurrently with Read and unblock it on Close.
+// Close releases/cancels the helper transfer; it is not itself a Q receipt.
+type BinaryRead struct {
+	Body        io.ReadCloser
+	Bytes       uint64
+	OperationID string
+}
+type BinaryReadHandler func(context.Context, Caller, *http.Request, json.RawMessage) (BinaryRead, error)
+
+func BoundedRead(h BinaryReadHandler) Route {
+	return Route{method: "nas.files.read.binary", policy: policyUser, binary: h}
+}
+
+var binaryReference = regexp.MustCompile(`^[a-f0-9]{64}$`)
+
+func serveBoundedRead(w http.ResponseWriter, r *http.Request, c Caller, params json.RawMessage, h BinaryReadHandler) {
+	if r.Context().Err() != nil {
+		writeError(w, &Error{"canceled", "read canceled"})
+		return
+	}
+	if r.Header.Get("Range") != "" {
+		writeError(w, BadRequest("ranges are unsupported"))
+		return
+	}
+	in, ok := decodeBinaryReadControl(params)
+	if !ok {
+		writeError(w, BadRequest("invalid binary read control"))
+		return
+	}
+	ctx, cancel := context.WithTimeout(r.Context(), BinaryReadTimeout)
+	defer cancel()
+	result, err := h(ctx, c, r, params)
+	if err != nil {
+		if result.Body != nil {
+			result.Body.Close()
+		}
+		writeError(w, asError(err))
+		return
+	}
+	if result.Body == nil {
+		writeError(w, internalError)
+		return
+	}
+	var once sync.Once
+	var closeErr error
+	closeBody := func() { once.Do(func() { closeErr = result.Body.Close() }) }
+	defer closeBody()
+	if result.Bytes > MaxBinaryReadBytes || result.OperationID != in.OperationID {
+		writeError(w, BadRequest("invalid bounded read result"))
+		return
+	}
+	stop := make(chan struct{})
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		select {
+		case <-ctx.Done():
+			closeBody()
+		case <-stop:
+		}
+	}()
+	// Materialize only the bounded response so short/error/overlong transfers
+	// cannot become successful binary responses. Helper relay still leases at
+	// most one 64KiB chunk. Long CGI streaming remains disabled pending DSM proof.
+	body, readErr := io.ReadAll(io.LimitReader(result.Body, int64(result.Bytes)+1))
+	closeBody()
+	close(stop)
+	<-done
+	if ctx.Err() != nil {
+		writeError(w, &Error{"canceled", "read expired or canceled"})
+		return
+	}
+	if readErr != nil || closeErr != nil || uint64(len(body)) != result.Bytes {
+		writeError(w, &Error{"read_failed", "binary read failed"})
+		return
+	}
+	headers := w.Header()
+	headers.Set("Content-Type", "application/octet-stream")
+	headers.Set("Content-Length", strconv.FormatUint(result.Bytes, 10))
+	headers.Set("Cache-Control", "no-store")
+	headers.Set("X-Content-Type-Options", "nosniff")
+	w.WriteHeader(http.StatusOK)
+	// Go CGI may buffer or block stdout. All helper resources have already been
+	// released; there is no long-stream readiness claim from this bounded write.
+	_, _ = w.Write(body)
+}
+
+// Fixed shape with duplicate-key rejection, so two parsers cannot bind a token
+// to different operations. Controls never grow the existing ctx.call envelope.
+func decodeBinaryReadControl(raw json.RawMessage) (BinaryReadRequest, bool) {
+	var in BinaryReadRequest
+	if len(raw) > 16*1024 {
+		return in, false
+	}
+	d := json.NewDecoder(bytes.NewReader(raw))
+	first, e := d.Token()
+	if e != nil || first != json.Delim('{') {
+		return in, false
+	}
+	seen := map[string]bool{}
+	for d.More() {
+		token, e := d.Token()
+		key, ok := token.(string)
+		if e != nil || !ok || seen[key] {
+			return in, false
+		}
+		seen[key] = true
+		var value string
+		if d.Decode(&value) != nil {
+			return in, false
+		}
+		switch key {
+		case "operationId":
+			in.OperationID = value
+		case "epoch":
+			in.Epoch = value
+		case "token":
+			in.Token = value
+		default:
+			return in, false
+		}
+	}
+	end, e := d.Token()
+	if e != nil || end != json.Delim('}') || d.Decode(new(any)) != io.EOF {
+		return in, false
+	}
+	return in, binaryReference.MatchString(in.OperationID) && binaryReference.MatchString(in.Epoch) && binaryReference.MatchString(in.Token)
+}

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

@@ -0,0 +1,165 @@
+package api
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/cgi"
+	"net/http/httptest"
+	"os"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+type binarySource struct {
+	io.Reader
+	closed bool
+}
+
+func (s *binarySource) Close() error { s.closed = true; return nil }
+func TestBoundedReadBinaryGuardAndBody(t *testing.T) {
+	for _, kind := range []string{"valid", "anonymous", "cross-origin", "oversize", "short", "nil", "cancel"} {
+		t.Run(kind, func(t *testing.T) {
+			auth := &fakeAuth{user: "normal1"}
+			if kind == "anonymous" {
+				auth.err = ErrNoSession
+			}
+			src := &binarySource{Reader: bytes.NewReader([]byte{0, 1, 255, 10})}
+			called := false
+			srv, e := NewServer(auth, BoundedRead(func(ctx context.Context, c Caller, r *http.Request, params json.RawMessage) (BinaryRead, error) {
+				called = true
+				if !c.Authenticated() || c.User() != "normal1" {
+					t.Fatal(c)
+				}
+				n := uint64(4)
+				if kind == "oversize" {
+					n = MaxBinaryReadBytes + 1
+				}
+				if kind == "short" {
+					n = 5
+				}
+				if kind == "nil" {
+					return BinaryRead{}, nil
+				}
+				return BinaryRead{Body: src, Bytes: n, OperationID: strings.Repeat("a", 64)}, nil
+			}))
+			if e != nil {
+				t.Fatal(e)
+			}
+			r := httptest.NewRequest("POST", "http://nas.local/cgi/api.cgi", strings.NewReader(`{"method":"nas.files.read.binary","params":{"operationId":"`+strings.Repeat("a", 64)+`","epoch":"`+strings.Repeat("b", 64)+`","token":"`+strings.Repeat("c", 64)+`"}}`))
+			r.Header.Set("Content-Type", "application/json")
+			if kind == "cross-origin" {
+				r.Header.Set("Origin", "http://evil.local")
+			}
+			if kind == "cancel" {
+				ctx, cancel := context.WithCancel(r.Context())
+				cancel()
+				r = r.WithContext(ctx)
+			}
+			w := httptest.NewRecorder()
+			srv.ServeHTTP(w, r)
+			if kind == "valid" {
+				if w.Header().Get("Content-Type") != "application/octet-stream" || !bytes.Equal(w.Body.Bytes(), []byte{0, 1, 255, 10}) || w.Header().Get("Content-Length") != "4" || !src.closed {
+					t.Fatal(w.Body.String(), w.Header())
+				}
+			} else {
+				if w.Header().Get("Content-Type") != "application/json" {
+					t.Fatal("invalid binary escaped")
+				}
+				if (kind == "anonymous" || kind == "cross-origin" || kind == "cancel") && called {
+					t.Fatal("handler called before guards")
+				}
+				if called && kind != "nil" && !src.closed {
+					t.Fatal("source not closed")
+				}
+			}
+		})
+	}
+}
+
+type blockedBinarySource struct {
+	done chan struct{}
+	once sync.Once
+}
+
+func (s *blockedBinarySource) Read([]byte) (int, error) { <-s.done; return 0, io.ErrClosedPipe }
+func (s *blockedBinarySource) Close() error             { s.once.Do(func() { close(s.done) }); return nil }
+func TestBoundedBinaryDisconnectCancelsSource(t *testing.T) {
+	src := &blockedBinarySource{done: make(chan struct{})}
+	started := make(chan struct{})
+	srv, e := NewServer(&fakeAuth{user: "normal1"}, BoundedRead(func(context.Context, Caller, *http.Request, json.RawMessage) (BinaryRead, error) {
+		close(started)
+		return BinaryRead{Body: src, Bytes: 1, OperationID: strings.Repeat("a", 64)}, nil
+	}))
+	if e != nil {
+		t.Fatal(e)
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	r := httptest.NewRequest("POST", "http://nas.local/cgi/api.cgi", strings.NewReader(`{"method":"nas.files.read.binary","params":{"operationId":"`+strings.Repeat("a", 64)+`","epoch":"`+strings.Repeat("b", 64)+`","token":"`+strings.Repeat("c", 64)+`"}}`)).WithContext(ctx)
+	r.Header.Set("Content-Type", "application/json")
+	done := make(chan struct{})
+	go func() { defer close(done); srv.ServeHTTP(httptest.NewRecorder(), r) }()
+	<-started
+	cancel()
+	select {
+	case <-done:
+	case <-time.After(time.Second):
+		t.Fatal("disconnect did not release bounded source")
+	}
+}
+func TestBoundedBinaryRejectsCallerPathsAndTransferSubstitution(t *testing.T) {
+	calls := 0
+	srv, e := NewServer(&fakeAuth{user: "normal1"}, BoundedRead(func(context.Context, Caller, *http.Request, json.RawMessage) (BinaryRead, error) {
+		calls++
+		return BinaryRead{}, nil
+	}))
+	if e != nil {
+		t.Fatal(e)
+	}
+	for _, params := range []string{`{}`, `{"operationId":"x"}`, `{"operationId":"` + strings.Repeat("a", 64) + `","epoch":"` + strings.Repeat("b", 64) + `","token":"` + strings.Repeat("c", 64) + `","path":"/secret"}`} {
+		_, env := post(t, srv, `{"method":"nas.files.read.binary","params":`+params+`}`)
+		if env.Success || env.Error == nil || env.Error.Code != "bad_request" {
+			t.Fatal(env)
+		}
+	}
+	if calls != 0 {
+		t.Fatal("invalid control reached adapter")
+	}
+}
+
+func TestBoundedBinaryRealCGIWire(t *testing.T) {
+	requestBody := `{"method":"nas.files.read.binary","params":{"operationId":"` + strings.Repeat("a", 64) + `","epoch":"` + strings.Repeat("b", 64) + `","token":"` + strings.Repeat("c", 64) + `"}}`
+	h := &cgi.Handler{Path: os.Args[0], Args: []string{"-test.run=TestBoundedBinaryCGIProcessFixture"}, Env: []string{"S6_CGI_FIXTURE=1"}}
+	r := httptest.NewRequest("POST", "http://nas.local/cgi/api.cgi", strings.NewReader(requestBody))
+	r.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+	h.ServeHTTP(w, r)
+	if w.Code != http.StatusOK || w.Header().Get("Content-Type") != "application/octet-stream" || w.Header().Get("Content-Length") != "1048576" || !bytes.Equal(w.Body.Bytes(), bytes.Repeat([]byte{0, 255, 10, 13}, MaxBinaryReadBytes/4)) {
+		t.Fatal(w.Code, w.Header(), w.Body.Len())
+	}
+}
+func TestBoundedBinaryCGIProcessFixture(t *testing.T) {
+	if os.Getenv("S6_CGI_FIXTURE") != "1" {
+		t.Skip("spawned CGI-only process")
+	}
+	srv, e := NewServer(&fakeAuth{user: "normal1"}, BoundedRead(func(context.Context, Caller, *http.Request, json.RawMessage) (BinaryRead, error) {
+		return BinaryRead{Body: io.NopCloser(bytes.NewReader(bytes.Repeat([]byte{0, 255, 10, 13}, MaxBinaryReadBytes/4))), Bytes: MaxBinaryReadBytes, OperationID: strings.Repeat("a", 64)}, nil
+	}))
+	if e != nil {
+		os.Exit(1)
+	}
+	if cgi.Serve(srv) != nil {
+		os.Exit(1)
+	}
+	os.Exit(0)
+}
+func TestBinaryControlRejectsDuplicates(t *testing.T) {
+	raw := `{"operationId":"` + strings.Repeat("a", 64) + `","epoch":"` + strings.Repeat("b", 64) + `","token":"` + strings.Repeat("c", 64) + `","token":"` + strings.Repeat("d", 64) + `"}`
+	if _, ok := decodeBinaryReadControl(json.RawMessage(raw)); ok {
+		t.Fatal("duplicate transfer token")
+	}
+}

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,104 @@
+// 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
+	binary  BinaryReadHandler
+}
+
+// User declares an operation any signed-in DSM user may call.
+func User(method string, h Handler) Route {
+	return Route{method: method, policy: policyUser, handler: h}
+}
+
+// Admin declares an operation only members of DSM's administrators group may call.
+func Admin(method string, h Handler) Route {
+	return Route{method: method, policy: policyAdmin, handler: 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: method, policy: policyPublic, handler: 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.binary != nil && (r.method != "nas.files.read.binary" || r.policy != policyUser || r.handler != nil) {
+			return nil, errors.New("binary read must use the fixed authenticated route")
+		}
+		if r.handler == nil && r.binary == 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 }