@synopackageland/cli 0.4.0 → 0.5.0

package/templates/native-go/backend/internal/app/routes.go

@@ -1,6 +1,10 @@
+//go:build !synopkgland_sdk_workers
+
 // Package app holds this package's business operations. Add a route here and
 // pick its policy: api.User (any signed-in DSM user), api.Admin (DSM
 // administrators only) or, rarely, api.Public (no sign-in at all).
+//
+//line dsmapp/internal/app/routes.go:1
 package app
 
 import (
@@ -9,6 +13,7 @@ import (
 	"encoding/json"
 	"errors"
 	"io/fs"
+	"net/http"
 	"os"
 	"path/filepath"
 	"runtime"
@@ -16,26 +21,39 @@ import (
 	"unicode/utf8"
 
 	"dsmapp/internal/api"
+	"dsmapp/internal/filestation"
 	"dsmapp/internal/helper"
 )
 
 // Config is fixed at build time and startup, never taken from a request.
 type Config struct {
+	// SessionFiles is the interactive File Station adapter; nil keeps legacy refusal.
+	SessionFiles    *filestation.Service
 	PackageID       string
 	Version         string
 	HelperInventory helper.Inventory
+	// PackageIntegration marks an integration built without a privileged
+	// helper: its features run as the package account and are ready by themselves.
+	PackageIntegration bool
+	// Staged trusted adapter. Nil refuses; no production data transport is installed.
+	NASBinaryRead api.BinaryReadHandler
 	// DataDir is the package's persistent, package-owned directory
 	// (/var/packages/<package>/var). It survives upgrades.
 	DataDir string
+	// VolumeRoot is where /volumeN lives; empty means "/". Tests set it.
+	VolumeRoot string
 }
 
 func Routes(cfg Config) []api.Route {
 	routes := []api.Route{
 		api.User("integration.status", cfg.integrationStatus),
+		api.BoundedRead(cfg.binaryRead),
 		api.User("app.status", cfg.status),
 		api.User("greeting.get", cfg.getGreeting),
 		api.Admin("greeting.set", cfg.setGreeting),
 	}
+	routes = append(routes, cfg.SessionFiles.Routes()...)
+	routes = append(routes, cfg.backgroundRoutes()...)
 	return append(routes, cfg.rootRoutes()...)
 }
 
@@ -43,11 +61,11 @@ func (cfg Config) integrationStatus(ctx context.Context, _ api.Caller, params js
 	if err := decodeParams(params, &struct{}{}); err != nil {
 		return nil, err
 	}
-	return helper.NewClient(cfg.HelperInventory).Status(ctx), nil
+	return cfg.integrationState(ctx), nil
 }
 
 func (cfg Config) status(_ context.Context, caller api.Caller, _ json.RawMessage) (any, error) {
-	return map[string]any{
+	return cfg.withSharedFolders(map[string]any{
 		"package":    cfg.PackageID,
 		"version":    cfg.Version,
 		"user":       caller.User(),
@@ -56,7 +74,7 @@ func (cfg Config) status(_ context.Context, caller api.Caller, _ json.RawMessage
 		"go_version": runtime.Version(),
 		"platform":   runtime.GOOS + "/" + runtime.GOARCH,
 		"time":       time.Now().UTC().Format(time.RFC3339),
-	}, nil
+	}), nil
 }
 
 type greeting struct {
@@ -125,3 +143,10 @@ func writeFileAtomic(path string, data []byte) error {
 	}
 	return os.Rename(tmp.Name(), path)
 }
+
+func (cfg Config) binaryRead(ctx context.Context, c api.Caller, r *http.Request, p json.RawMessage) (api.BinaryRead, error) {
+	if cfg.NASBinaryRead == nil {
+		return api.BinaryRead{}, &api.Error{Code: "unsupported", Message: "NAS binary read is unavailable"}
+	}
+	return cfg.NASBinaryRead(ctx, c, r, p)
+}

package/templates/native-go/backend/internal/app/routes_test.go

@@ -57,12 +57,17 @@ var (
 // sampleParams holds valid params for every route, so the denial test below
 // proves the refusal came from the policy and not from bad input.
 var sampleParams = map[string]string{
-	"integration.status": `{}`,
-	"app.status":         `{}`,
-	"greeting.get":       `{}`,
-	"greeting.set":       `{"text":"Hi"}`,
+	"integration.status":    `{}`,
+	"nas.files.read.binary": `{"operationId":"` + strings.Repeat("a", 64) + `","epoch":"` + strings.Repeat("b", 64) + `","token":"` + strings.Repeat("c", 64) + `"}`,
+	"app.status":            `{}`,
+	"greeting.get":          `{}`,
+	"greeting.set":          `{"text":"Hi"}`,
 }
 
+// sampleOutcome is the error code an administrator gets from a route's sample
+// params; routes that are not listed (and not jobs.*) succeed.
+var sampleOutcome = map[string]string{"nas.files.read.binary": "unsupported"}
+
 func TestIntegrationStatusIsReadableByOrdinaryUsers(t *testing.T) {
 	code, out := call(t, testConfig(t), bob, "integration.status", `{}`)
 	if code != "" || out["data"].(map[string]any)["state"] != "not-enabled" {
@@ -74,6 +79,19 @@ func TestIntegrationStatusIsReadableByOrdinaryUsers(t *testing.T) {
 	}
 }
 
+func TestPackageOnlyIntegrationIsReadyWithoutAHelper(t *testing.T) {
+	cfg := testConfig(t)
+	cfg.PackageIntegration = true
+	code, out := call(t, cfg, bob, "integration.status", `{}`)
+	data, _ := out["data"].(map[string]any)
+	if code != "" || data["state"] != "ready" || data["reason"] != "package-only" || data["scheduler"] != "not-required" || data["packageRunning"] != "running" {
+		t.Fatalf("%s: %v", code, out)
+	}
+	if _, cleanup := data["cleanup"]; cleanup {
+		t.Fatal("no helper means no cleanup state")
+	}
+}
+
 func TestEveryRouteHasSampleParamsAndNoneIsPublic(t *testing.T) {
 	routes := Routes(testConfig(t))
 	if len(routes) != len(sampleParams) {
@@ -117,7 +135,11 @@ func TestEveryAdminRouteRefusesOrdinaryUsersAndChangesNothing(t *testing.T) {
 func TestEveryRouteSucceedsForAnAdmin(t *testing.T) {
 	for _, r := range Routes(testConfig(t)) {
 		code, out := call(t, testConfig(t), alice, r.Method(), sampleParams[r.Method()])
-		if code != "" {
+		want := sampleOutcome[r.Method()]
+		if strings.HasPrefix(r.Method(), "jobs.") {
+			want = "unavailable"
+		}
+		if code != want {
 			t.Errorf("%s: %q %v", r.Method(), code, out)
 		}
 	}

package/templates/native-go/backend/internal/app/sdk_jobs.go

@@ -0,0 +1,70 @@
+//go:build synopkgland_sdk_workers
+
+package app
+
+import (
+	"bytes"
+	"context"
+	"dsmapp/internal/api"
+	"dsmapp/internal/helper"
+	"encoding/json"
+	"io"
+	"net"
+	"net/http"
+)
+
+type sdkCarrierKey struct{}
+
+// Only session carriers from the HTTP request are forwarded. The authenticated
+// Caller and root NativeActor remain independent trust decisions.
+func SDKHandler(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		raw, err := io.ReadAll(http.MaxBytesReader(w, r.Body, api.MaxRequestBytes))
+		if err != nil || helper.ValidateSDKEnvelope(raw) != "" {
+			w.Header().Set("Content-Type", "application/json")
+			w.Header().Set("Cache-Control", "no-store")
+			io.WriteString(w, `{"success":false,"error":{"code":"invalid-request","message":"Invalid request"}}`)
+			return
+		}
+		r.Body = io.NopCloser(bytes.NewReader(raw))
+		address, _, err := net.SplitHostPort(r.RemoteAddr)
+		if err != nil {
+			address = r.RemoteAddr
+		}
+		c := helper.SessionCarriers{Cookie: r.Header.Get("Cookie"), SynoToken: r.Header.Get("X-SYNO-TOKEN"), ClientAddress: address}
+		next.ServeHTTP(w, r.WithContext(context.WithValue(r.Context(), sdkCarrierKey{}, c)))
+	})
+}
+func (cfg Config) sdkJobRoutes() []api.Route {
+	routes := []api.Route{}
+	for _, method := range []string{"jobs.prepare", "jobs.submit", "jobs.status", "jobs.lookup", "jobs.result", "jobs.cancel", "jobs.revoke", "jobs.attach", "jobs.admin.status", "jobs.admin.cancel"} {
+		name := method
+		handler := func(ctx context.Context, caller api.Caller, args json.RawMessage) (any, error) {
+			if !caller.Authenticated() {
+				return nil, &api.Error{Code: "session_required", Message: "Sign in again"}
+			}
+			if code := helper.ValidateSDKArgs(name, args); code != "" {
+				return nil, &api.Error{Code: string(code), Message: "Job request refused"}
+			}
+			c, ok := ctx.Value(sdkCarrierKey{}).(helper.SessionCarriers)
+			if !ok {
+				return nil, &api.Error{Code: "unavailable", Message: "Native proof unavailable"}
+			}
+			invoke := cfg.SDKJobs
+			if invoke == nil {
+				invoke = helper.NewClient(cfg.HelperInventory).SDKJobs
+			}
+			data, code := invoke(ctx, name, c, args)
+			if code != "" {
+				return nil, &api.Error{Code: string(code), Message: "Job request refused"}
+			}
+			return data, nil
+		}
+		if name == "jobs.admin.status" || name == "jobs.admin.cancel" {
+			routes = append(routes, api.Admin(name, handler))
+		} else {
+			routes = append(routes, api.User(name, handler))
+		}
+	}
+	return routes
+}

package/templates/native-go/backend/internal/app/sdk_jobs_test.go

@@ -0,0 +1,116 @@
+//go:build synopkgland_sdk_workers
+
+package app
+
+import (
+	"context"
+	"dsmapp/internal/api"
+	"dsmapp/internal/helper"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+type sdkAppAuth struct{ calls int }
+
+func (a *sdkAppAuth) Authenticate(r *http.Request) (api.Identity, error) {
+	a.calls++
+	if r.Header.Get("Cookie") == "" {
+		return api.Identity{}, api.ErrNoSession
+	}
+	return api.Identity{User: "fixture"}, nil
+}
+func TestSDKCGIRoutesCarryOnlyNativeSessionAndFixedMethods(t *testing.T) {
+	auth := &sdkAppAuth{}
+	var got helper.SessionCarriers
+	calls := 0
+	cfg := Config{SDKJobs: func(ctx context.Context, method string, c helper.SessionCarriers, p json.RawMessage) (json.RawMessage, helper.Code) {
+		calls++
+		got = c
+		return json.RawMessage(`{"revision":1,"items":[]}`), ""
+	}}
+	s, e := api.NewServer(auth, Routes(cfg)...)
+	if e != nil {
+		t.Fatal(e)
+	}
+	h := SDKHandler(s)
+	for _, body := range []string{`{"method":"jobs.status","params":{}}`, `{"method":"jobs.status","params":{"actor":"root"}}`, `{"method":"jobs.status","method":"jobs.cancel","params":{}}`} {
+		req := httptest.NewRequest("POST", "http://nas.test/cgi/api.cgi", strings.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set("Cookie", "fixture-cookie")
+		req.Header.Set("X-SYNO-TOKEN", "fixture-csrf")
+		req.RemoteAddr = "192.0.2.1:1234"
+		w := httptest.NewRecorder()
+		h.ServeHTTP(w, req)
+	}
+	if calls != 1 || got.Cookie != "fixture-cookie" || got.SynoToken != "fixture-csrf" || got.ClientAddress != "192.0.2.1" {
+		t.Fatal(calls, got)
+	}
+	req := httptest.NewRequest("POST", "http://nas.test/cgi/api.cgi", strings.NewReader(`{"method":"jobs.status","params":{}}`))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+	h.ServeHTTP(w, req)
+	if calls != 1 || !strings.Contains(w.Body.String(), "session_required") {
+		t.Fatal(w.Body.String())
+	}
+	// No side-channel namespace registration of arbitrary dispatch or background.
+	for _, r := range Routes(cfg) {
+		if strings.HasPrefix(r.Method(), "jobs.") && r.Public() {
+			t.Fatal("public job route")
+		}
+	}
+}
+
+func TestSDKIntegrationSeparatesLifecycleAndJobReadiness(t *testing.T) {
+	cfg := Config{SDKJobs: func(_ context.Context, method string, c helper.SessionCarriers, _ json.RawMessage) (json.RawMessage, helper.Code) {
+		if method != "jobs.diagnose" || c.Cookie != "fixture" {
+			t.Fatal(method, c)
+		}
+		return nil, helper.ErrUnavailable
+	}}
+	ctx := context.WithValue(context.Background(), sdkCarrierKey{}, helper.SessionCarriers{Cookie: "fixture"})
+	result, err := cfg.integrationStatus(ctx, api.Caller{}, json.RawMessage(`{}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	raw, _ := json.Marshal(result)
+	if !strings.Contains(string(raw), `"interactive":"unavailable"`) || !strings.Contains(string(raw), `"background":"unavailable"`) || !strings.Contains(string(raw), `"attachTtlMs":6000`) {
+		t.Fatal(string(raw))
+	}
+}
+
+func init() {
+	ref := strings.Repeat("a", 64)
+	params := map[string]any{
+		"jobs.prepare":      map[string]any{"worker": map[string]any{"id": "scan", "revision": 1}, "parent": map[string]any{"id": ref, "revision": 1}, "input": map[string]any{"steps": []any{map[string]any{"action": "nas.files.stat", "segments": []string{"fixture"}}}}},
+		"jobs.submit":       map[string]any{"intentId": ref, "summaryDigest": ref},
+		"jobs.lookup":       map[string]any{"intentId": ref},
+		"jobs.result":       map[string]any{"jobId": ref},
+		"jobs.cancel":       map[string]any{"jobId": ref, "revision": 1},
+		"jobs.admin.cancel": map[string]any{"jobId": ref, "revision": 1},
+		"jobs.attach":       map[string]any{"jobId": ref, "attachId": ref},
+		"jobs.revoke":       map[string]any{"jobId": ref, "revision": 1, "delegationRevision": 1, "storeRevision": 1},
+		"jobs.status":       map[string]any{}, "jobs.admin.status": map[string]any{},
+	}
+	for method, param := range params {
+		raw, _ := json.Marshal(param)
+		sampleParams[method] = string(raw)
+	}
+}
+
+func TestSDKIntegrationReportsLiveSessionModeOnly(t *testing.T) {
+	cfg := Config{SDKJobs: func(context.Context, string, helper.SessionCarriers, json.RawMessage) (json.RawMessage, helper.Code) {
+		return json.RawMessage(`{"diagnosticSchema":1,"availability":"session-required","jobs":[],"total":0,"truncated":false}`), ""
+	}}
+	ctx := context.WithValue(context.Background(), sdkCarrierKey{}, helper.SessionCarriers{Cookie: "fixture"})
+	result, err := cfg.integrationStatus(ctx, api.Caller{}, json.RawMessage(`{}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	raw, _ := json.Marshal(result)
+	if !strings.Contains(string(raw), `"interactive":"session-required"`) || !strings.Contains(string(raw), `"background":"unavailable"`) || !strings.Contains(string(raw), `"validation":"local-only"`) {
+		t.Fatal("missing session mode readiness")
+	}
+}

package/templates/native-go/backend/internal/app/sdk_routes.go

@@ -0,0 +1,174 @@
+//go:build synopkgland_sdk_workers
+
+// Package app holds this package's business operations. Add a route here and
+// pick its policy: api.User (any signed-in DSM user), api.Admin (DSM
+// administrators only) or, rarely, api.Public (no sign-in at all).
+package app
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"io/fs"
+	"net/http"
+	"os"
+	"path/filepath"
+	"runtime"
+	"time"
+	"unicode/utf8"
+
+	"dsmapp/internal/api"
+	"dsmapp/internal/filestation"
+	"dsmapp/internal/helper"
+)
+
+// Config is fixed at build time and startup, never taken from a request.
+type Config struct {
+	// SessionFiles is the interactive File Station adapter; nil keeps legacy refusal.
+	SessionFiles    *filestation.Service
+	SDKJobs         func(context.Context, string, helper.SessionCarriers, json.RawMessage) (json.RawMessage, helper.Code)
+	PackageID       string
+	Version         string
+	HelperInventory helper.Inventory
+	// PackageIntegration marks an integration built without a privileged
+	// helper. SDK workers need the helper, so this build never sets it.
+	PackageIntegration bool
+	// Staged trusted adapter. Nil refuses; no production data transport is installed.
+	NASBinaryRead api.BinaryReadHandler
+	// DataDir is the package's persistent, package-owned directory
+	// (/var/packages/<package>/var). It survives upgrades.
+	DataDir string
+	// VolumeRoot is where /volumeN lives; empty means "/". Tests set it.
+	VolumeRoot string
+}
+
+func Routes(cfg Config) []api.Route {
+	routes := []api.Route{
+		api.User("integration.status", cfg.integrationStatus),
+		api.BoundedRead(cfg.binaryRead),
+		api.User("app.status", cfg.status),
+		api.User("greeting.get", cfg.getGreeting),
+		api.Admin("greeting.set", cfg.setGreeting),
+	}
+	routes = append(routes, cfg.sdkJobRoutes()...)
+	routes = append(routes, cfg.SessionFiles.Routes()...)
+	routes = append(routes, cfg.backgroundRoutes()...)
+	return append(routes, cfg.rootRoutes()...)
+}
+
+func (cfg Config) integrationStatus(ctx context.Context, _ api.Caller, params json.RawMessage) (any, error) {
+	if err := decodeParams(params, &struct{}{}); err != nil {
+		return nil, err
+	}
+	state := cfg.integrationState(ctx)
+	jobs := map[string]any{"interactive": "unavailable", "background": "unavailable", "reason": "native-proof-unavailable", "attachRenewMs": helper.SDKAttachRenewMS, "attachTtlMs": helper.SDKAttachTTLMS}
+	if carriers, ok := ctx.Value(sdkCarrierKey{}).(helper.SessionCarriers); ok {
+		invoke := cfg.SDKJobs
+		if invoke == nil {
+			invoke = helper.NewClient(cfg.HelperInventory).SDKJobs
+		}
+		if data, code := invoke(ctx, "jobs.diagnose", carriers, json.RawMessage(`{}`)); code == "" {
+			jobs["diagnostic"] = data
+			var diagnostic struct {
+				Availability string `json:"availability"`
+			}
+			if json.Unmarshal(data, &diagnostic) == nil && diagnostic.Availability == "session-required" {
+				jobs["interactive"] = "session-required"
+				jobs["reason"] = "filestation-session"
+				jobs["validation"] = "local-only"
+			}
+		}
+	}
+	return struct {
+		helper.State
+		Jobs map[string]any `json:"jobs"`
+	}{state, jobs}, nil
+}
+
+func (cfg Config) status(_ context.Context, caller api.Caller, _ json.RawMessage) (any, error) {
+	return cfg.withSharedFolders(map[string]any{
+		"package":    cfg.PackageID,
+		"version":    cfg.Version,
+		"user":       caller.User(),
+		"admin":      caller.Admin(),
+		"process":    map[string]int{"uid": os.Getuid(), "gid": os.Getgid()},
+		"go_version": runtime.Version(),
+		"platform":   runtime.GOOS + "/" + runtime.GOARCH,
+		"time":       time.Now().UTC().Format(time.RFC3339),
+	}), nil
+}
+
+type greeting struct {
+	Text      string `json:"text"`
+	UpdatedBy string `json:"updated_by,omitempty"`
+}
+
+func (cfg Config) greetingPath() string { return filepath.Join(cfg.DataDir, "greeting.json") }
+
+func (cfg Config) getGreeting(context.Context, api.Caller, json.RawMessage) (any, error) {
+	data, err := os.ReadFile(cfg.greetingPath())
+	if errors.Is(err, fs.ErrNotExist) {
+		return greeting{Text: "Hello"}, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	var g greeting
+	return g, json.Unmarshal(data, &g)
+}
+
+func (cfg Config) setGreeting(_ context.Context, caller api.Caller, params json.RawMessage) (any, error) {
+	var in struct {
+		Text string `json:"text"`
+	}
+	if err := decodeParams(params, &in); err != nil {
+		return nil, err
+	}
+	if n := utf8.RuneCountInString(in.Text); n < 1 || n > 200 {
+		return nil, api.BadRequest("text must be 1 to 200 characters")
+	}
+	g := greeting{Text: in.Text, UpdatedBy: caller.User()}
+	data, err := json.Marshal(g)
+	if err != nil {
+		return nil, err
+	}
+	return g, writeFileAtomic(cfg.greetingPath(), data)
+}
+
+// decodeParams decodes params strictly: unknown fields are an error.
+func decodeParams(params json.RawMessage, into any) error {
+	if len(params) == 0 {
+		params = json.RawMessage(`{}`)
+	}
+	dec := json.NewDecoder(bytes.NewReader(params))
+	dec.DisallowUnknownFields()
+	if err := dec.Decode(into); err != nil {
+		return api.BadRequest("invalid params: " + err.Error())
+	}
+	return nil
+}
+
+// writeFileAtomic replaces path in one rename, so readers never see half a file.
+func writeFileAtomic(path string, data []byte) error {
+	tmp, err := os.CreateTemp(filepath.Dir(path), ".tmp-*")
+	if err != nil {
+		return err
+	}
+	defer os.Remove(tmp.Name())
+	if _, err := tmp.Write(data); err != nil {
+		tmp.Close()
+		return err
+	}
+	if err := tmp.Close(); err != nil {
+		return err
+	}
+	return os.Rename(tmp.Name(), path)
+}
+
+func (cfg Config) binaryRead(ctx context.Context, c api.Caller, r *http.Request, p json.RawMessage) (api.BinaryRead, error) {
+	if cfg.NASBinaryRead == nil {
+		return api.BinaryRead{}, &api.Error{Code: "unsupported", Message: "NAS binary read is unavailable"}
+	}
+	return cfg.NASBinaryRead(ctx, c, r, p)
+}

package/templates/native-go/backend/internal/app/session_files.go

@@ -0,0 +1,15 @@
+package app
+
+import "dsmapp/internal/helper"
+
+// FileStationSession is the build-time value that selects the package-account
+// interactive File Station adapter without a helper.
+const FileStationSession = "session"
+
+// SessionFilesEnabled reports whether the build installs the interactive File
+// Station adapter: for a protocol 2 helper inventory, or when the project opted
+// in with fileStation: session. Both inputs are fixed at build time, never from
+// a request; any other fileStation value refuses.
+func SessionFilesEnabled(inventory helper.Inventory, fileStation string) bool {
+	return inventory.Protocol == 2 || fileStation == FileStationSession
+}

package/templates/native-go/backend/internal/app/session_files_test.go

@@ -0,0 +1,26 @@
+package app
+
+import (
+	"testing"
+
+	"dsmapp/internal/helper"
+)
+
+func TestSessionFilesEnabledByEitherTrustedBuildSetting(t *testing.T) {
+	for name, tc := range map[string]struct {
+		inventory   helper.Inventory
+		fileStation string
+		want        bool
+	}{
+		"nothing selected":             {helper.Inventory{}, "", false},
+		"helper protocol 1":            {helper.Inventory{Protocol: 1}, "", false},
+		"helper protocol 2":            {helper.Inventory{Protocol: 2}, "", true},
+		"package-only file station":    {helper.Inventory{}, "session", true},
+		"unknown build value refuses":  {helper.Inventory{}, "yes", false},
+		"protocol 1 plus file station": {helper.Inventory{Protocol: 1}, "session", true},
+	} {
+		if got := SessionFilesEnabled(tc.inventory, tc.fileStation); got != tc.want {
+			t.Errorf("%s: got %v, want %v", name, got, tc.want)
+		}
+	}
+}