@synopackageland/templates 0.0.0-stage → 0.9.0

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

@@ -0,0 +1,320 @@
+package app
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/synopackageland/syno-pkg-land-sdk/api"
+	"github.com/synopackageland/syno-pkg-land-sdk/background"
+	"github.com/synopackageland/syno-pkg-land-sdk/filestation"
+)
+
+type fakeFiles struct {
+	data   []byte
+	err    error
+	calls  int
+	folder string
+	rel    string
+	offset int
+	page   filestation.Page
+}
+
+func (f *fakeFiles) Browse(_ context.Context, _ api.Caller, _ *http.Request, folder string, offset int) (filestation.Page, error) {
+	f.calls++
+	f.folder, f.offset = folder, offset
+	return f.page, f.err
+}
+
+func (f *fakeFiles) ReadFile(_ context.Context, _ api.Caller, _ *http.Request, folder, rel string) ([]byte, error) {
+	f.calls++
+	f.folder, f.rel = folder, rel
+	return f.data, f.err
+}
+
+type bgEnv struct {
+	t     *testing.T
+	store *background.Store
+	files *fakeFiles
+	srv   map[string]*api.Server
+}
+
+func newBgEnv(t *testing.T) *bgEnv {
+	lookupSubmitterUID = func(string) string { return "1024" }
+	t.Cleanup(func() { lookupSubmitterUID = osLookupUID })
+	store := background.NewStore(filepath.Join(t.TempDir(), "background"))
+	files := &fakeFiles{data: []byte("hello")}
+	return &bgEnv{t: t, store: store, files: files, srv: map[string]*api.Server{}}
+}
+
+func (e *bgEnv) call(auth api.Authenticator, method, params string) (string, map[string]any) {
+	e.t.Helper()
+	// SDK policy provides owner routes immediately.
+	routes := newBackgroundRoutes(e.store, e.files)
+	srv, err := api.NewServerWithPermissions(auth, []byte(`{"schema":1,"default":"administrators","methods":{}}`), routes...)
+	if err != nil {
+		e.t.Fatal(err)
+	}
+	req := httptest.NewRequest(http.MethodPost, "/api.cgi", strings.NewReader(`{"method":"`+method+`","params":`+params+`}`))
+	req.Header.Set("Content-Type", "application/json")
+	rec := httptest.NewRecorder()
+	srv.ServeHTTP(rec, req)
+	var out map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &out); err != nil {
+		e.t.Fatalf("not JSON: %s", rec.Body.String())
+	}
+	code := ""
+	if er, ok := out["error"].(map[string]any); ok {
+		code, _ = er["code"].(string)
+	}
+	return code, out
+}
+
+func data(out map[string]any) map[string]any { return out["data"].(map[string]any) }
+
+var bgSample = map[string]string{
+	"bg.schedules.list":    `{}`,
+	"bg.schedules.create":  `{"key":"schedule","jobId":"missing","intervalSeconds":3600,"consent":true}`,
+	"bg.schedules.disable": `{"id":"missing"}`,
+	"bg.schedules.delete":  `{"id":"missing"}`,
+	"bg.schedules.enable":  `{"id":"missing","consent":true}`,
+	"bg.status":            `{}`,
+	"bg.jobs.purge":        `{"owner":{"user":"bob","uid":"1025"}}`,
+	"bg.browse":            `{"folder":"/share","offset":0}`,
+	"bg.jobs.submit":       `{"key":"k1","folder":"/share","relative":"a.txt"}`,
+	"bg.jobs.list":         `{}`,
+	"bg.jobs.get":          `{"id":"` + strings.Repeat("a", 32) + `"}`,
+	"bg.jobs.cancel":       `{"id":"` + strings.Repeat("a", 32) + `"}`,
+	"bg.jobs.result":       `{"id":"` + strings.Repeat("a", 32) + `"}`,
+}
+
+func TestBackgroundSDKPoliciesAuthenticateEveryRoute(t *testing.T) {
+	e := newBgEnv(t)
+	routes := newBackgroundRoutes(e.store, e.files)
+	if len(routes) != len(bgSample) {
+		t.Fatalf("%d routes, %d samples", len(routes), len(bgSample))
+	}
+	for _, r := range routes {
+		if rule(t, r) == "public" {
+			t.Errorf("%s must not be public", r.Method())
+		}
+		params, ok := bgSample[r.Method()]
+		if !ok {
+			t.Fatalf("no sample for %s", r.Method())
+		}
+		code, _ := e.call(bob, r.Method(), params)
+		if r.Method() == "bg.jobs.purge" || r.Method() == "bg.schedules.enable" {
+			if code != "admin_required" {
+				t.Errorf("%s as ordinary user: %q", r.Method(), code)
+			}
+		} else if code == "admin_required" || code == "unsupported" || code == "disabled" {
+			t.Errorf("%s unexpectedly blocked: %q", r.Method(), code)
+		}
+		if code, _ := e.call(nobody, r.Method(), params); code != "session_required" {
+			t.Errorf("%s without a session: %q", r.Method(), code)
+		}
+	}
+}
+
+func TestBackgroundStatusReportsLimitsAndWorker(t *testing.T) {
+	e := newBgEnv(t)
+	code, out := e.call(alice, "bg.status", `{}`)
+	d := data(out)
+	if code != "" || d["algorithm"] != "sha256-v1" || d["worker"] != nil {
+		t.Fatalf("%s %v", code, out)
+	}
+	limits := d["limits"].(map[string]any)
+	if limits["maxInputBytes"].(float64) != 512*1024 || limits["maxQueued"].(float64) != 16 || limits["maxTotalBytes"].(float64) != 16<<20 || limits["jobTimeoutSeconds"].(float64) != 60 {
+		t.Fatalf("limits: %v", limits)
+	}
+	if err := e.store.Heartbeat(context.Background(), background.WorkerInfo{PID: 9, UID: 255853, Username: "pkg"}); err != nil {
+		t.Fatal(err)
+	}
+	_, out = e.call(alice, "bg.status", `{}`)
+	w := data(out)["worker"].(map[string]any)
+	if w["alive"] != true || w["uid"].(float64) != 255853 {
+		t.Fatalf("worker: %v", w)
+	}
+}
+
+func TestBackgroundSubmitAvailableOnFreshStore(t *testing.T) {
+	e := newBgEnv(t)
+	code, _ := e.call(alice, "bg.jobs.submit", bgSample["bg.jobs.submit"])
+	if code != "" || e.files.calls != 1 {
+		t.Fatalf("%q, NAS reads %d", code, e.files.calls)
+	}
+}
+
+func TestBackgroundSubmitImportsSelectedFileAndIsIdempotent(t *testing.T) {
+	e := newBgEnv(t)
+	params := `{"key":"k1","folder":"/share","relative":"docs/a.txt"}`
+	code, out := e.call(alice, "bg.jobs.submit", params)
+	job := data(out)["job"].(map[string]any)
+	if code != "" || job["state"] != "queued" || job["name"] != "a.txt" || data(out)["duplicate"] != false {
+		t.Fatalf("%s %v", code, out)
+	}
+	if e.files.folder != "/share" || e.files.rel != "docs/a.txt" {
+		t.Fatalf("adapter saw %q %q", e.files.folder, e.files.rel)
+	}
+	submitter := job["submitter"].(map[string]any)
+	if submitter["user"] != "alice" || submitter["uid"] != "1024" {
+		t.Fatalf("submitter: %v", submitter)
+	}
+	_, again := e.call(alice, "bg.jobs.submit", params)
+	if data(again)["duplicate"] != true || data(again)["job"].(map[string]any)["id"] != job["id"] {
+		t.Fatalf("duplicate: %v", again)
+	}
+	e.files.data = []byte("other")
+	if code, _ := e.call(alice, "bg.jobs.submit", params); code != "conflict" {
+		t.Fatalf("same key with different bytes: %q", code)
+	}
+}
+
+func TestBackgroundSubmitPassesAdapterRefusalsThrough(t *testing.T) {
+	e := newBgEnv(t)
+	e.files.err = &api.Error{Code: "limit-exceeded", Message: "x"}
+	if code, _ := e.call(alice, "bg.jobs.submit", bgSample["bg.jobs.submit"]); code != "limit-exceeded" {
+		t.Fatalf("%q", code)
+	}
+	if jobs, _ := e.store.List(context.Background()); len(jobs) != 0 {
+		t.Fatal("a failed import must never enter the queue")
+	}
+}
+
+func TestBackgroundSubmitValidatesParams(t *testing.T) {
+	e := newBgEnv(t)
+	for _, p := range []string{
+		`{}`, `{"key":"k","folder":"/share","relative":"a","extra":1}`, `{"key":"bad key","folder":"/share","relative":"a"}`,
+		`{"key":"k","folder":"/share","relative":""}`,
+	} {
+		if code, _ := e.call(alice, "bg.jobs.submit", p); code != "bad_request" {
+			t.Errorf("%s: %q", p, code)
+		}
+	}
+}
+
+func TestBackgroundQueueFullAndQuotaErrorsHaveStableCodes(t *testing.T) {
+	e := newBgEnv(t)
+	for i := 0; i < background.MaxQueued; i++ {
+		lookupSubmitterUID = func(string) string { return fmt.Sprint(1024 + i/2) }
+		key := "k" + string(rune('a'+i))
+		if code, _ := e.call(alice, "bg.jobs.submit", `{"key":"`+key+`","folder":"/share","relative":"a.txt"}`); code != "" {
+			t.Fatalf("%d: %q", i, code)
+		}
+	}
+	lookupSubmitterUID = func(string) string { return "9999" }
+	if code, _ := e.call(alice, "bg.jobs.submit", `{"key":"more","folder":"/share","relative":"a.txt"}`); code != "queue-full" {
+		t.Fatalf("%q", code)
+	}
+}
+
+func TestBackgroundListGetCancelAndResult(t *testing.T) {
+	e := newBgEnv(t)
+	_, out := e.call(alice, "bg.jobs.submit", `{"key":"k1","folder":"/share","relative":"a.txt"}`)
+	id := data(out)["job"].(map[string]any)["id"].(string)
+	idp := `{"id":"` + id + `"}`
+
+	if _, out = e.call(alice, "bg.jobs.list", `{}`); len(data(out)["jobs"].([]any)) != 1 {
+		t.Fatalf("%v", out)
+	}
+	if code, out := e.call(alice, "bg.jobs.get", idp); code != "" || data(out)["job"].(map[string]any)["id"] != id {
+		t.Fatalf("%s %v", code, out)
+	}
+	if code, _ := e.call(alice, "bg.jobs.result", idp); code != "not_ready" {
+		t.Fatalf("result of a queued job: %q", code)
+	}
+	ctx := context.Background()
+	if _, err := e.store.Claim(ctx); err != nil {
+		t.Fatal(err)
+	}
+	sum := "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
+	if err := e.store.Finish(ctx, id, background.Outcome{State: background.StateSucceeded, Result: &background.Result{SHA256: sum, Bytes: 5}}); err != nil {
+		t.Fatal(err)
+	}
+	code, out := e.call(alice, "bg.jobs.result", idp)
+	res := data(out)["result"].(map[string]any)
+	if code != "" || res["sha256"] != sum || res["bytes"].(float64) != 5 || res["worker"] != "sha256-v1" || res["jobId"] != id {
+		t.Fatalf("%s %v", code, out)
+	}
+	if code, _ := e.call(alice, "bg.jobs.cancel", idp); code != "conflict" {
+		t.Fatalf("cancel after completion: %q", code)
+	}
+	for _, m := range []string{"bg.jobs.get", "bg.jobs.cancel", "bg.jobs.result"} {
+		if code, _ := e.call(alice, m, `{"id":"`+strings.Repeat("0", 32)+`"}`); code != "not_found" {
+			t.Fatalf("%s unknown id: %q", m, code)
+		}
+	}
+}
+
+func TestBackgroundCancelQueuedJob(t *testing.T) {
+	e := newBgEnv(t)
+	_, out := e.call(alice, "bg.jobs.submit", `{"key":"k1","folder":"/share","relative":"a.txt"}`)
+	id := data(out)["job"].(map[string]any)["id"].(string)
+	code, out := e.call(alice, "bg.jobs.cancel", `{"id":"`+id+`"}`)
+	if code != "" || data(out)["job"].(map[string]any)["state"] != "canceled" {
+		t.Fatalf("%s %v", code, out)
+	}
+}
+
+func TestBackgroundWorkerAliveExpires(t *testing.T) {
+	if workerAlive(background.WorkerInfo{At: time.Now().Add(-time.Minute)}, time.Now()) || !workerAlive(background.WorkerInfo{At: time.Now()}, time.Now()) {
+		t.Fatal("a stale heartbeat is not alive")
+	}
+}
+
+func TestBackgroundBrowseListsThroughTheCallersSession(t *testing.T) {
+	e := newBgEnv(t)
+	e.files.page = filestation.Page{Files: []filestation.Entry{{Name: "a.txt", Path: "/share/a.txt"}}, Total: 1}
+	code, out := e.call(alice, "bg.browse", `{"folder":"/share","offset":100}`)
+	if code != "" {
+		t.Fatalf("%s %v", code, out)
+	}
+	if e.files.folder != "/share" || e.files.offset != 100 {
+		t.Fatalf("browsed %q at %d", e.files.folder, e.files.offset)
+	}
+	files := data(out)["files"].([]any)
+	if len(files) != 1 || files[0].(map[string]any)["path"] != "/share/a.txt" {
+		t.Fatalf("page %v", out)
+	}
+}
+
+func TestBackgroundBrowseWithoutFolderListsTheShares(t *testing.T) {
+	e := newBgEnv(t)
+	if code, out := e.call(alice, "bg.browse", `{}`); code != "" {
+		t.Fatalf("%s %v", code, out)
+	}
+	if e.files.folder != "" || e.files.offset != 0 {
+		t.Fatalf("browsed %q at %d", e.files.folder, e.files.offset)
+	}
+}
+
+func TestBackgroundBrowseValidatesParamsAndPassesRefusalsThrough(t *testing.T) {
+	e := newBgEnv(t)
+	for _, params := range []string{`{"offset":-1}`, `{"folder":"/share","extra":1}`, `{"offset":"1"}`} {
+		if code, _ := e.call(alice, "bg.browse", params); code != "bad_request" {
+			t.Errorf("%s: %q", params, code)
+		}
+	}
+	if e.files.calls != 0 {
+		t.Fatal("invalid params must not reach the NAS")
+	}
+	e.files.err = &api.Error{Code: "denied", Message: "no"}
+	if code, _ := e.call(alice, "bg.browse", `{"folder":"/share"}`); code != "denied" {
+		t.Fatalf("got %q", code)
+	}
+}
+
+func TestBackgroundListWithoutJobsIsAnEmptyArray(t *testing.T) {
+	e := newBgEnv(t)
+	_, out := e.call(alice, "bg.jobs.list", `{}`)
+	jobs, ok := data(out)["jobs"].([]any)
+	if !ok || len(jobs) != 0 {
+		t.Fatalf("jobs must be [] not null: %v", out)
+	}
+}

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

@@ -0,0 +1,57 @@
+package app
+
+import (
+	"encoding/json"
+	"errors"
+	"regexp"
+)
+
+type DelegateSettings struct {
+	Scope                    string
+	Operations, Destinations []string
+	Lifetime                 string
+}
+
+var destinationKey = regexp.MustCompile(`^[a-z][a-z0-9_-]{0,63}$`)
+
+// ParseDelegateConfig consumes only build/startup settings. Legacy declarations
+// retain their TTL/job branch; absent extension fields never imply permanence.
+func ParseDelegateConfig(cfg Config) (DelegateSettings, error) {
+	out := DelegateSettings{Scope: cfg.DelegateScope, Lifetime: cfg.DelegateLifetime}
+	invalid := errors.New("invalid delegate build configuration")
+	if cfg.DelegateOperationsJSON != "" && json.Unmarshal([]byte(cfg.DelegateOperationsJSON), &out.Operations) != nil {
+		return DelegateSettings{}, invalid
+	}
+	if cfg.DelegateDestinationsJSON != "" && json.Unmarshal([]byte(cfg.DelegateDestinationsJSON), &out.Destinations) != nil {
+		return DelegateSettings{}, invalid
+	}
+	if out.Lifetime == "" {
+		if len(out.Destinations) != 0 {
+			return DelegateSettings{}, invalid
+		}
+		seen := map[string]bool{}
+		for _, op := range out.Operations {
+			switch op {
+			case "files.list", "files.info", "files.createFolder", "files.checkPermission", "files.write":
+			default:
+				return DelegateSettings{}, invalid
+			}
+			if seen[op] {
+				return DelegateSettings{}, invalid
+			}
+			seen[op] = true
+		}
+		return out, nil
+	}
+	if out.Lifetime != "until-revoked" || out.Scope == "" || len(out.Operations) != 1 || out.Operations[0] != "files.moveFromStaging" || len(out.Destinations) == 0 || len(out.Destinations) > 64 {
+		return DelegateSettings{}, invalid
+	}
+	seen := map[string]bool{}
+	for _, key := range out.Destinations {
+		if !destinationKey.MatchString(key) || seen[key] {
+			return DelegateSettings{}, invalid
+		}
+		seen[key] = true
+	}
+	return out, nil
+}

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

@@ -0,0 +1,28 @@
+package app
+
+import "testing"
+
+func TestDelegateBuildConfigStrictlySeparatesLegacyAndPermanent(t *testing.T) {
+	valid := Config{DelegateScope: "home", DelegateOperationsJSON: `["files.moveFromStaging"]`, DelegateDestinationsJSON: `["save"]`, DelegateLifetime: "until-revoked"}
+	settings, err := ParseDelegateConfig(valid)
+	if err != nil || settings.Lifetime != "until-revoked" || len(settings.Destinations) != 1 {
+		t.Fatal(settings, err)
+	}
+	for _, cfg := range []Config{{}, {DelegateScope: "home"}, {DelegateScope: "home", DelegateOperationsJSON: `["files.write"]`}} {
+		settings, err = ParseDelegateConfig(cfg)
+		if err != nil || settings.Lifetime != "" || len(settings.Destinations) != 0 {
+			t.Fatal("legacy changed", settings, err)
+		}
+	}
+	for _, mutate := range []func(*Config){
+		func(c *Config) { c.DelegateLifetime = "" }, func(c *Config) { c.DelegateScope = "" }, func(c *Config) { c.DelegateOperationsJSON = `["files.write"]` },
+		func(c *Config) { c.DelegateDestinationsJSON = `["save","save"]` }, func(c *Config) { c.DelegateDestinationsJSON = `["Save"]` }, func(c *Config) { c.DelegateDestinationsJSON = `[]` }, func(c *Config) { c.DelegateDestinationsJSON = `null` },
+		func(c *Config) { c.DelegateDestinationsJSON = `["save"] {}` },
+	} {
+		cfg := valid
+		mutate(&cfg)
+		if _, err = ParseDelegateConfig(cfg); err == nil {
+			t.Fatal("invalid trusted config accepted", cfg)
+		}
+	}
+}

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

@@ -0,0 +1,5 @@
+package app
+
+import "github.com/synopackageland/syno-pkg-land-sdk/api"
+
+func (Config) delegateRoutes() []api.Route { return nil }

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

@@ -0,0 +1,20 @@
+package app
+
+import (
+	"errors"
+	"path"
+	"strings"
+
+	"github.com/synopackageland/syno-pkg-land-sdk/identity"
+)
+
+// StandaloneIdentity registers identity.status/session/login/logout through
+// Service.Wrap. Business routes keep their permissions.json policies. Call only
+// for capabilities.identity=standalone; the path comes from the CGI environment.
+func StandaloneIdentity(cfg Config, scriptName string) (*identity.Service, error) {
+	if !strings.HasPrefix(scriptName, "/") || strings.HasPrefix(scriptName, "//") || path.Clean(scriptName) != scriptName || !strings.HasSuffix(scriptName, "/cgi/api.cgi") {
+		return nil, errors.New("identity requires an absolute CGI script path")
+	}
+	cookiePath := strings.TrimSuffix(path.Dir(path.Dir(scriptName)), "/") + "/"
+	return identity.New(identity.Config{DataDir: cfg.DataDir, CookiePath: cookiePath})
+}

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

@@ -0,0 +1,15 @@
+package app
+
+import "testing"
+
+func TestIdentityApplicationPath(t *testing.T) {
+	for _, tc := range []struct {
+		script string
+		valid  bool
+	}{{"/webman/3rdparty/test/cgi/api.cgi", true}, {"/cgi/api.cgi", true}, {"", false}, {"cgi/api.cgi", false}, {"//evil/cgi/api.cgi", false}} {
+		_, err := StandaloneIdentity(Config{DataDir: t.TempDir()}, tc.script)
+		if (err == nil) != tc.valid {
+			t.Errorf("script %q: %v", tc.script, err)
+		}
+	}
+}

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

@@ -0,0 +1,41 @@
+package app
+
+import (
+	"os"
+
+	"github.com/synopackageland/syno-pkg-land-sdk/datamigrate"
+)
+
+// Migrations returns this app's schema migrations. The template ships one
+// empty example; replace it with your own steps. Versions start at 1 and never
+// change meaning. Every step must be idempotent: a crash between Apply and the
+// recorded version, or two CGI requests racing on the first run after an
+// upgrade, can run one step twice. A failed step stops the run with the
+// previous version still recorded, and the next run resumes from there; the
+// utility itself never deletes or rewrites data.
+func Migrations() []datamigrate.Migration {
+	return []datamigrate.Migration{
+		{
+			Version: 1,
+			Name:    "example",
+			Apply: func(datamigrate.Context) error {
+				// Nothing to do yet. Read ctx.DataDir, rewrite files with a
+				// temporary file + rename, and keep the step idempotent.
+				return nil
+			},
+		},
+	}
+}
+
+// Migrate applies Migrations to the package's persistent var directory. The
+// CGI calls it once per request; the recorded data-version makes that a cheap
+// no-op. SYNOPKG_OLD_PKGVER is set when DSM starts the app from a lifecycle
+// script; in a plain CGI request the version of the last successful run is
+// used instead.
+func Migrate(cfg Config) error {
+	_, err := datamigrate.Run(cfg.DataDir, datamigrate.Info{
+		OldPkgVer: os.Getenv("SYNOPKG_OLD_PKGVER"),
+		NewPkgVer: cfg.Version,
+	}, Migrations())
+	return err
+}

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

@@ -0,0 +1,41 @@
+package app
+
+import (
+	"testing"
+
+	"github.com/synopackageland/syno-pkg-land-sdk/datamigrate"
+)
+
+func TestMigrationsAreOrderedUniqueAndValid(t *testing.T) {
+	migrations := Migrations()
+	if len(migrations) == 0 {
+		t.Fatal("the template must ship one example migration")
+	}
+	for i, migration := range migrations {
+		if migration.Version < 1 || migration.Apply == nil || migration.Name == "" {
+			t.Fatalf("migration %d is invalid: %+v", i, migration)
+		}
+		if i > 0 && migrations[i-1].Version >= migration.Version {
+			t.Fatalf("migrations are not strictly version-ascending: %+v", migrations)
+		}
+	}
+}
+
+func TestMigrateRecordsTheSchemaAndPackageVersion(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("SYNOPKG_OLD_PKGVER", "0.1.0-0001")
+	cfg := Config{DataDir: dir, Version: "0.2.0-0002"}
+	if err := Migrate(cfg); err != nil {
+		t.Fatalf("Migrate: %v", err)
+	}
+	state, err := datamigrate.Load(dir)
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	if state.Schema != 1 || state.PackageVersion != "0.2.0-0002" {
+		t.Fatalf("recorded state = %+v", state)
+	}
+	if err := Migrate(cfg); err != nil {
+		t.Fatalf("second Migrate must be a no-op: %v", err)
+	}
+}

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

@@ -0,0 +1,30 @@
+package app
+
+import (
+	"context"
+	"encoding/json"
+
+	"github.com/synopackageland/syno-pkg-land-sdk/api"
+	"github.com/synopackageland/syno-pkg-land-sdk/portal"
+)
+
+// portalRoutes serves portal.status when dsm-package.yaml declares `portal`.
+// An administrator sets the alias with DSM's own AppPortal API from the UI;
+// the package only reads DSM's saved setting.
+func (cfg Config) portalRoutes() []api.Route {
+	if !cfg.Portal {
+		return nil
+	}
+	return []api.Route{api.Handle("portal.status", cfg.portalStatus)}
+}
+
+func (cfg Config) portalStatus(_ context.Context, _ api.Caller, params json.RawMessage) (any, error) {
+	if err := decodeParams(params, &struct{}{}); err != nil {
+		return nil, err
+	}
+	path := cfg.PortalConfig
+	if path == "" {
+		path = portal.ConfigPath(cfg.PackageID)
+	}
+	return portal.Read(path, "SYNO.SDS."+cfg.PackageID+".Instance"), nil
+}

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

@@ -0,0 +1,55 @@
+package app
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func portalConfig(t *testing.T, saved string) Config {
+	cfg := testConfig(t)
+	cfg.Portal = true
+	cfg.PortalConfig = filepath.Join(t.TempDir(), "AppPortal.json")
+	if saved != "" {
+		if err := os.WriteFile(cfg.PortalConfig, []byte(saved), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return cfg
+}
+
+func TestPortalStatusTellsEverySignedInUserTheAlias(t *testing.T) {
+	cfg := portalConfig(t, `{"alias":"hello-go","id":"SYNO.SDS.HelloGo.Instance","version":3}`)
+	code, out := call(t, cfg, bob, "portal.status", `{}`)
+	if code != "" {
+		t.Fatalf("%q %v", code, out)
+	}
+	data := out["data"].(map[string]any)
+	if data["state"] != "active" || data["alias"] != "hello-go" {
+		t.Fatalf("%v", data)
+	}
+	if code, _ := call(t, cfg, nobody, "portal.status", `{}`); code != "session_required" {
+		t.Fatalf("anonymous: %q", code)
+	}
+	if code, _ := call(t, cfg, bob, "portal.status", `{"alias":"x"}`); code != "bad_request" {
+		t.Fatalf("params: %q", code)
+	}
+}
+
+func TestPortalStatusFailsClosedOnAnotherAppsSetting(t *testing.T) {
+	cfg := portalConfig(t, `{"alias":"hello-go","id":"SYNO.SDS.Other.Instance"}`)
+	_, out := call(t, cfg, bob, "portal.status", `{}`)
+	if data := out["data"].(map[string]any); data["state"] != "unavailable" || data["alias"] != nil {
+		t.Fatalf("%v", data)
+	}
+	_, out = call(t, portalConfig(t, ""), bob, "portal.status", `{}`)
+	if data := out["data"].(map[string]any); data["state"] != "inactive" {
+		t.Fatalf("%v", data)
+	}
+}
+
+func TestPortalStatusExistsOnlyForAPortalBuild(t *testing.T) {
+	if code, _ := call(t, testConfig(t), alice, "portal.status", `{}`); code != "unknown_method" {
+		t.Fatalf("%q", code)
+	}
+}

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

@@ -0,0 +1,9 @@
+package app
+
+import "github.com/synopackageland/syno-pkg-land-sdk/api"
+
+// rootRoutes is empty: this package declares privilege: none and never runs
+// anything as root. `synopkgland init -t native-go --privilege root` creates
+// root.go instead, which reads the results of administrator-approved root
+// operations.
+func (Config) rootRoutes() []api.Route { return nil }