@synopackageland/templates 0.0.0-stage → 0.9.1

package/templates/native-go/README.md

@@ -0,0 +1,372 @@
+# __DISPLAY_NAME__
+
+A native DSM package (`__PACKAGE__`): a Go backend that DSM runs as a CGI,
+and a UI that opens in its own DSM window. It installs as an **unsigned** SPK,
+runs as its own DSM package account, needs no containers, and has no root by default.
+
+```text
+DSM main menu → DSM window (ui/app.js)
+                   │  ctx.call("greeting.get")  same-origin POST + DSM session
+                   ▼
+   /webman/3rdparty/__PACKAGE__/cgi/api.cgi   (backend/, runs as package user)
+      1. transport guards: POST, JSON, same origin, ≤ 1 MiB, bounded JSON complexity
+      2. one DSM authentication (unless the route is Public)
+      3. route policy: User or Admin  → refusal before any handler
+      4. your handler (backend/internal/app)
+```
+
+## Quick start
+
+Needs Node.js with `synopkgland` installed, and Go 1.25+.
+
+```bash
+(cd backend && go test ./...)   # auth policy + route tests
+synopkgland build           # → dist/__PACKAGE__-0.1.0-0001-{x86_64,aarch64}.spk
+synopkgland inspect dist/__PACKAGE__-0.1.0-0001-x86_64.spk
+```
+
+Install: Package Center → Settings → General → Trust Level "Any publisher",
+then Manual Install with the SPK for your NAS's CPU. Open
+**__DISPLAY_NAME__** from the DSM main menu: it shows who you are signed in
+as, what the backend reports, and (for administrators) a form that stores a
+greeting in the package's data folder.
+
+## Capabilities and schema 2
+
+`dsm-package.yaml` requires `schema: 2` and `backend: {kind: go, dir: backend}`.
+Declare `capabilities.files: session` for interactive File Station access,
+`capabilities.jobs: true` for persistent package-account jobs,
+`capabilities.identity: standalone` for independent DSM login, and
+`capabilities.rootOps: true` for administrator-approved fixed executor operations.
+`init --with files,jobs,root-ops` supports plain and Vue UI; `login` and
+`delegate` need the Vue UI. `daemon` cannot be combined with `jobs`, but it can
+be combined with an until-revoked `delegate`.
+
+```sh
+synopkgland add files jobs login
+synopkgland check --json
+synopkgland status --host my-nas --json
+```
+
+`add` writes SDK overlay files and updates capabilities. Your handlers/pages and
+application entry files remain app-owned. Differing existing overlay files and
+modified SDK placeholders cause `ADD_FILE_CONFLICT` with the conflicting paths;
+resolve them before retrying. Already-declared capabilities are a no-op.
+`check`, `build`, `inspect`, `deploy`, `status` emit one stdout object with
+`--json`; failures include `code`, `message`, `hint`.
+
+## Project layout
+
+| Path | What it is | Edit it? |
+| --- | --- | --- |
+| `dsm-package.yaml` | Package identity, version/build, arches, where backend and UI come from | Yes |
+| `ui/app.js`, `ui/app.css` | The app inside the DSM window | Yes — your UI |
+| `ui/…` | Any other assets; served from `/webman/3rdparty/__PACKAGE__/app/` | Yes |
+| `i18n/messages/<locale>.json` | UI text in nine languages | Yes |
+| `i18n/glossary.json` | DSM's own UI terms, and which messages must use them | Add terms |
+| `backend/internal/app/` | Your API: routes and handlers | Yes — your backend |
+| `backend/internal/api/permissions.json` | Who may call each of your methods | Yes |
+| `backend/cmd/app/` | Wires your routes to the SDK server | Rarely |
+| `backend/go.mod` | Your module; `require github.com/synopackageland/syno-pkg-land-sdk` pins the SDK | SDK upgrades |
+| `dist/` | Built SPKs (ignored by git) | No |
+
+`build` generates everything else: `INFO`, `conf/privilege`
+(`run-as: package`), no-op lifecycle scripts, icons, the DSM window wrapper
+(`ui/config`, `ui/window-<build>.js`) and the CGI at `ui/cgi/api.cgi`.
+
+## Add an API operation
+
+Add a handler in `backend/internal/app/routes.go`. Every method defaults to
+DSM administrator membership, resolved by its native SDK. All access rules live in
+`backend/internal/api/permissions.json`, including launcher access:
+
+```go
+func Routes(cfg Config) []api.Route {
+	return []api.Route{
+		api.Handle("app.status", cfg.status),
+		api.Handle("greeting.get", cfg.getGreeting),
+		api.Handle("greeting.set", cfg.setGreeting),
+		api.Handle("notes.list", cfg.listNotes),   // new: administrators by default
+		api.Handle("notes.purge", cfg.purgeNotes), // new: administrators by default
+	}
+}
+
+func (cfg Config) listNotes(ctx context.Context, caller api.Caller, params json.RawMessage) (any, error) {
+	var in struct{ Limit int `json:"limit"` }
+	if err := decodeParams(params, &in); err != nil {
+		return nil, err
+	}
+	return map[string]any{"owner": caller.User(), "notes": []string{}}, nil
+}
+```
+
+Then add the method's valid params to `sampleParams` in `routes_test.go`; the
+test fails until you do, and once you do it proves the new route refuses
+callers without a session and ordinary users without touching
+the data folder.
+
+Call it from the UI with `ctx.call("notes.list", { limit: 20 })`. Errors
+reject with `{ code, message }`, for example `session_required`,
+`admin_required`, `bad_request` or `internal`.
+
+### Who can call what
+
+The shipped policy is:
+
+```json
+{"schema": 1, "default": "administrators", "methods": {}}
+```
+
+The default must remain `administrators`. An intentional exception belongs in
+`methods`, for example `"notes.list": "authenticated"`; `"public"` explicitly
+allows anonymous calls. Such exceptions also enable ordinary-user launcher
+access. The template ships no exceptions and sets DSM `allUsers` to `false`.
+
+| JSON rule | No session | Ordinary user | Administrators group member |
+| --- | --- | --- | --- |
+| absent or `administrators` | `session_required` | `admin_required` | runs |
+| explicit `authenticated` | `session_required` | runs | runs |
+| explicit `public` | runs | runs | runs |
+| unregistered method | `session_required` | `unknown_method` | `unknown_method` |
+
+Missing or invalid JSON, duplicate keys, unknown permissions and rules for
+unregistered methods fail closed. The CLI validates the file and binds its
+SHA-256 digest to the compiled CGI, which checks it at startup before migration.
+Changing policy requires rebuilding the SPK; request parameters cannot alter it.
+Register routes with `api.Handle`. Binary reads cannot be configured as anonymous.
+
+## The SDK
+
+Everything outside `backend/internal/app`, `backend/internal/api/permissions.json`
+and your UI comes from the SDK: the Go module `github.com/synopackageland/syno-pkg-land-sdk`
+(pinned in `backend/go.mod`, the single source of the SDK version) and, for the
+Vue UI, the npm package `@synopackageland/sdk` at the same version. Transport
+guards, DSM authentication, the administrator check, File Station, jobs,
+identity, portal, migrations and the executor protocol are documented in the SDK
+repository: <https://github.com/synopackageland/syno-pkg-land-sdk>.
+
+Upgrade the SDK by changing the `require` line (and `frontend/package.json`) to
+the new version; `synopkgland check` refuses mismatched versions.
+
+## Customize the UI
+
+`ui/app.js` must register `window.DsmPackageApps[<package>].mount(root, ctx)`
+(the template shows how, using `document.currentScript.dataset.package`).
+`ctx.call(method, params)` is the only transport. `ctx.reopen(fn)` runs `fn`
+whenever DSM shows the window again and returns an idempotent unsubscribe function. Scope your CSS under your own root class:
+every DSM app shares one page.
+
+Plain JS and Vue receive the same `ctx.host` adapter. `ctx.host.platform()`
+returns a fresh frozen snapshot: `web`, `host` (`dsm`, `standalone-web` or
+`unavailable`), `dsmStandalone`, `dsmLanguage`, `appLocale`, `systemVersion`,
+`fullVersion`, and `theme`. Unknown fields are `null`; `theme` stays unknown.
+DSM launch mode is separate from plain-web fallback, and `appLocale` is the
+app's catalog locale, which may differ from DSM's UI language code.
+
+```js
+const platform = ctx.host.platform();
+const result = ctx.host.setTitle('My notes');
+if (result.status !== 'ok') showTitleStatus(result.status);
+```
+
+`setTitle` enables DSM HTML encoding or assigns standalone `document.title`.
+It returns `{status: 'ok', target: 'dsm-window' | 'document'}` on synchronous
+completion, or `unsupported`, `unavailable`, `invalid-input`, `failed` statuses.
+A missing DSM method is unsupported; it never changes the DSM desktop's title.
+Destroy disposes the adapter and clears reopen handlers; retained adapters
+return unavailable. Navigation exposes activateWindow/requestClose/openApp/openURL;
+requests do not acknowledge completion. `ctx.host.subscribe('window-resize', fn)`
+returns `{status: 'subscribed', dispose}` only for a verified DSM window with on/un.
+The callback receives no native arguments. Remove your subscriptions on unmount;
+wrapper destroy also cleans them. `host-theme-change` and `host-language-change`
+return unsupported: no third-party host event is proven. These observations do
+not authorize work.
+
+`ctx.host.openFileManager('/example-share/docs')` requests File Station folder
+navigation; `revealFile('/home/report.txt')` requests a file highlight. Both require
+a registered, enabled and launchable File Station and report requested plus action,
+not location completion or ACL success. Use canonical virtual share paths only;
+OS `/volumeN/...`, traversal, repeated/trailing slash, controls and backslash are
+invalid. No path conversion or grant is performed. `openFile`, `showFileDetails`
+and `openAppSetting` return unsupported; private preview/details/settings flows
+have no proven generic contract.
+
+File reveal adds a best-effort correction using File Station 1.4.x private
+structures. Required APIs are feature-detected; absent/throwing APIs silently
+cancel and release timers/listeners. One AppLaunch callback binds one receiver;
+only its model may be selected once. Interaction, navigation away from the reached
+parent, close/destroy, disposal and new requests cancel the correction. The named
+5000 ms total budget, 100 ms checks and 300 ms quiet interval have no device latency
+proof. `requested` still does not mean `selected`; actual effectiveness on DSM 7.4 /
+File Station 1.4.4 awaits a rebuilt-SPK device matrix. No second launch or broadcast
+setter is used, and later reloads may still clear selection.
+
+For an independent browser shell, use the SPK's generated `ui/host-0001.js`
+(the number follows the manifest build). It has no Ext or npm runtime dependency:
+
+```html
+<script src="./host-0001.js"></script>
+```
+
+```js
+// shellContext supplies your app's own auth/transport and other context members.
+const ctx = {...shellContext, host: window.DsmPackageHosts.__PACKAGE__({locale: 'en'})};
+const app = window.DsmPackageApps.__PACKAGE__.mount(root, ctx);
+// When your shell unmounts:
+ctx.host.dispose();
+app.unmount();
+```
+
+Serve the generated script with your shell (or reference its same-origin DSM
+static path). `ctx.host` does not create a standalone backend, DSM session,
+cross-origin iframe bridge, or implementations of `ctx.call/t/root/reopen`.
+Standalone title affects the document shared by that shell's mounts.
+
+To build the UI with Vite, Vue or React, point `ui` at the build output and
+give the build command as an argv list (no shell):
+
+```yaml
+ui:
+  dir: web/dist
+  build:
+    cwd: web
+    command: [npm, run, build]
+```
+
+The build must emit `app.js` (one script that registers `mount`) and
+`app.css`. The installed `@synopackageland/ui` package gives Vue components with DSM 7 styling;
+import its `themes/dsm7-embedded.css` for use inside a DSM window.
+
+## Languages
+
+The UI ships in nine of DSM's languages: `en`, `zh-TW`,
+`zh-CN`, `ja`, `ko`, `de`, `fr`, `es` and `it`. DSM's other languages show
+English. The window follows DSM's own language setting (`_S("lang")`).
+
+- **Messages**: `i18n/messages/<locale>.json`, flat `"key": "text"`. Use
+  `ctx.t("greeting.setBy", { text, user })` in the UI; `{name}` is a
+  placeholder, and `ctx.t("files", { count: 3 })` picks `files.one` or
+  `files.other`. Missing keys fall back to English, then to the key itself.
+  `build` embeds the catalogs in the DSM window script, so there is no
+  extra request.
+- **Errors**: the backend returns a `code`; the UI shows
+  `error.<code>` from the catalogs and uses the backend's English text only for
+  codes it has no message for. Add `error.<code>` for every code you return.
+- **Glossary**: `i18n/glossary.json` records DSM's own words in all nine
+  languages, each with its source (`section/key` in DSM 7.4's
+  `/usr/syno/synoman/webman/texts/<lang>/strings`). A term's `keys` lists the
+  messages that must contain it; that is how "Save" uses DSM's own word in
+  every language, the same as the rest of DSM. Product names in `untranslated`
+  stay in English everywhere.
+- **Package Center text**: `i18n.info` in `dsm-package.yaml` writes INFO
+  `displayname_<lang>` / `description_<lang>` (for example `description_cht`).
+
+`synopkgland check` and `build` refuse a language file with missing or
+extra keys, a translation that drops a `{placeholder}`, an unsupported
+language, or a listed message that drifts from the glossary.
+
+To add a message: add the key to `en.json` and to the other eight files. To
+use a DSM term, copy its `text` from the glossary and add your key to the
+term's `keys`. A Vue or React UI can keep its own i18n library; `ctx.t` and
+`ctx.locale` are there if you want them.
+
+The Vue shell (`--ui vue`) keeps the app's own text in `frontend/src/i18n/<locale>.json`,
+in the same nine languages; SDK components (sign-in, files, background jobs) ship
+their own catalogs. Add new text to all nine files rather than writing it into a
+`.vue` file.
+
+## Package an existing binary
+
+Keep the Go backend and call your tool from a handler (recommended: auth
+stays central), or replace the CGI with your own executable:
+
+```yaml
+arches: [x86_64]
+backend:
+  kind: binary
+  files:
+    x86_64: prebuilt/api-x86_64
+```
+
+The file must be a regular file in the project, a 64-bit Linux ELF for that
+arch, and statically linked (DSM models ship different libc versions). It is
+installed as `ui/cgi/api.cgi` (mode 0755) and runs as the package account.
+It then owns everything the SDK server does for you: bounded reads,
+POST-only JSON, same-origin checks, authentication before any work, and a
+refusal for unknown methods.
+
+## DSM Application Portal link
+
+Only an App with the root executor (`rootOps` or `delegate`) can declare a
+portal; `synopkgland add root-ops portal` declares both. Uninstall then
+removes the App's Application Privileges rules and reloads nginx once DSM has
+removed the alias, so it stops answering. `synopkgland add portal` adds
+`portal: {}` to dsm-package.yaml so
+`https://<nas>/<alias>/` opens this app right after DSM sign-in. The install
+wizard proposes the alias (the package name in lowercase by default); an
+administrator turns it on from the app's portal panel or Control Panel >
+Login Portal > Applications. Ordinary users then see the link; until then
+they see "ask an administrator". DSM owns the setting: the backend's
+`portal.status` only reads it, and nothing in the package may write it. See
+`synopkgland skill show portal`.
+
+A portal needs DSM 7.3.2-86009 or later, so `add portal` raises a lower
+`os_min_ver` and build refuses one below it. DSM 7.1.1 rejects an unsigned
+package that registers a portal (Package Center error 320); 7.3.2 and 7.4
+install it; 7.2 is untested. To keep supporting older DSM, remove `portal:`.
+
+## Data, upgrades, uninstall
+
+The backend stores data in `/var/packages/__PACKAGE__/var` (the package's
+own folder, kept across upgrades). Bump `build` for every SPK you hand out;
+bump `version` for feature releases. There are no lifecycle scripts to write:
+the CGI starts per request, so start/stop do nothing.
+
+### What an upgrade keeps
+
+An upgrade replaces the program files and keeps the data. DSM preserves `var`
+(`@appdata`), `home` (`@apphome`) and `etc` (`@appconf`) across an upgrade and
+removes `tmp` (`@apptemp`) and `target` (`@appstore`). Keep everything you need
+to keep under `var`, `home` or `etc`.
+
+### Schema migrations
+
+The SDK's `datamigrate` package applies ordered, idempotent schema migrations and
+records the result in `<var>/data-version`. `backend/cmd/app` runs `app.Migrate`
+on every start; the recorded version makes that a cheap no-op.
+
+- Versions start at 1 and never change meaning. The template ships one empty
+example in `backend/internal/app/migrations.go`; replace it with your steps.
+- Every step must be idempotent: a crash between `Apply` and the version record,
+or two CGI requests racing on the first start after an upgrade, can run one step
+twice.
+- A step that fails stops the run with the previous version still recorded, and
+the next start resumes from there. The helper never deletes or rewrites data
+itself, so a failed migration leaves your old data in place.
+- `datamigrate.Context.OldPkgVer` is the version being upgraded from:
+`SYNOPKG_OLD_PKGVER` when your environment sets it, otherwise the version the last
+successful run recorded. `NewPkgVer` is the version running now.
+
+Uninstalling keeps your data: DSM leaves `@appdata` and `@apphome` on the volume,
+and reinstalling the same package ID picks them up again. The install wizard is a
+dynamic `WIZARD_UIFILES/install_uifile.sh` that checks — read-only — whether
+`@appdata/<package>` already exists and, if it does, tells the administrator the
+install reuses the old data and how to start clean.
+
+The generated SPK ships
+an uninstall wizard (English, plus eight other languages) with one box, **Also
+delete the app data listed above** (`pkgwizard_remove_additional`), unchecked by
+default. Ticked, `postuninst` empties `@appdata/<package>`, `@apphome/<package>`
+and `@appconf/<package>` and nothing else: not Shared Folders, the package
+account or other packages. An upgrade never deletes anything. Do not write your own `postuninst`;
+`synopkgland inspect` flags a deleting script that lacks the upgrade guard
+or deletes outside the package's own folders.
+
+## Support matrix
+
+| | Status |
+| --- | --- |
+| Build hosts | macOS, Linux (any OS with Go and Node) |
+| Target CPUs | x86_64 and aarch64 DSM models (one SPK each). armv7 (DSM 7.2+ platforms `alpine`, `alpine4k`, `armada38x`, `monaco`) is opt-in: add it to `arches`; it covers the Go CGI (plain or Vue UI), jobs, daemon, root-ops and delegate. armv7 jobs, daemon and executor (root-ops, delegate) are built and checked locally but have not been verified on a NAS |
+| DSM | 7.1 or later declared (`os_min_ver`, change it with `init --min-dsm` or `build --min-dsm`). Installed and tested on DSM 7.4 and 7.3.2 (x86_64). armv7 was installed and tested on DSM 7.1.1 (`alpine4k`, Linux 3.10, where the bridge runs from the package tmp fallback) with administrator, AppPriv and unauthenticated requests; `armada38x` and `monaco` have not been run on a NAS. No x86_64 Linux 3.10 model has been tested. aarch64 SPKs are built the same way but have not been run on a NAS. |
+| Not supported | armv7 platforms only DSM 7.0/7.1 ship (`armada370`, `armada375`, `armadaxp`, `comcerto2k`); DSM 6, running anything as root without an administrator's approval |

package/templates/native-go/backend/THIRD_PARTY_NOTICES.txt

@@ -0,0 +1,53 @@
+Native Go package build dependencies
+
+github.com/synopackageland/syno-pkg-land-sdk v0.9.1 (MIT)
+
+Copyright (c) 2026 synopkgland
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+golang.org/x/sys v0.44.0 (BSD-3-Clause)
+
+Copyright 2009 The Go Authors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of Google LLC nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

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

@@ -0,0 +1,101 @@
+// 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.
+//
+//line __PACKAGE__/cmd/app/main.go:1
+package main
+
+import (
+	"fmt"
+	"log"
+	"net/http"
+	"net/http/cgi"
+	"os"
+
+	"github.com/synopackageland/syno-pkg-land-sdk/api"
+	"github.com/synopackageland/syno-pkg-land-sdk/dsm"
+	"github.com/synopackageland/syno-pkg-land-sdk/filestation"
+	standaloneidentity "github.com/synopackageland/syno-pkg-land-sdk/identity"
+
+	appapi "__PACKAGE__/internal/api"
+	"__PACKAGE__/internal/app"
+)
+
+// Set by `synopkgland build-spk` through -ldflags -X; never read from a request.
+var (
+	delegateScope            = ""
+	delegateOperationsJSON   = ""
+	delegateDestinationsJSON = ""
+	delegateLifetime         = ""
+	executorDigest           = ""
+	policyDigest             = ""
+	packageID                = "dev"
+	version                  = "0.0.0"
+	// "session" when the project opted into the interactive File Station adapter.
+	fileStation = ""
+	// "standalone" enables the SDK identity adapter; the runtime owns authentication.
+	identity = ""
+	// dsm-package.yaml entry: "admin-only" or "app-privilege"; empty keeps the route policy alone.
+	entry = ""
+	// "on" when dsm-package.yaml declares portal: serves portal.status.
+	portal = ""
+)
+
+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{
+		DelegateScope:            delegateScope,
+		DelegateOperationsJSON:   delegateOperationsJSON,
+		DelegateDestinationsJSON: delegateDestinationsJSON,
+		DelegateLifetime:         delegateLifetime,
+		ExecutorDigest:           executorDigest, PolicyDigest: policyDigest,
+		PackageID: packageID,
+		Version:   version,
+		DataDir:   "/var/packages/" + packageID + "/var",
+		Portal:    portal == "on",
+	}
+	if _, err := app.ParseDelegateConfig(cfg); err != nil {
+		log.Fatal(err)
+	}
+	if app.SessionFilesEnabled(fileStation) {
+		cfg.SessionFiles = filestation.Local(cfg.DataDir)
+	}
+	// Kernels without memfd_create stage DSM's bridges in the package's own temp.
+	dsm.SetBridgeFallbackDir("/var/packages/" + packageID + "/tmp")
+	var auth api.Authenticator = dsm.NewAuthenticator()
+	var standalone *standaloneidentity.Service
+	if identity == "standalone" {
+		var err error
+		standalone, err = app.StandaloneIdentity(cfg, os.Getenv("SCRIPT_NAME"))
+		if err != nil {
+			log.Fatal("identity configuration unavailable")
+		}
+		auth = standalone
+	}
+	auth, err := dsm.NewEntryGate(auth, entry, packageID, cfg.DataDir)
+	if err != nil {
+		log.Fatal(err)
+	}
+	permissions, err := appapi.Permissions()
+	if err != nil {
+		log.Fatal(err)
+	}
+	srv, err := api.NewServerWithPermissions(auth, permissions, app.Routes(cfg)...)
+	if err != nil {
+		log.Fatal(err)
+	}
+	if err := app.Migrate(cfg); err != nil {
+		log.Fatalf("schema migration failed: %v", err)
+	}
+	var handler http.Handler = srv
+	if standalone != nil {
+		handler = standalone.Wrap(handler)
+	}
+	if err := cgi.Serve(api.WithRequestDeadline(handler)); err != nil {
+		log.Fatal(err)
+	}
+}

package/templates/native-go/backend/cmd/background-worker/main.go

@@ -0,0 +1,38 @@
+// Command background-worker is the package's fixed background worker. DSM runs
+// it as the package's systemd user unit under the package account; it never
+// runs as root and takes no input except the jobs in its private spool.
+package main
+
+import (
+	"context"
+	"log"
+	"os"
+	"os/signal"
+	"os/user"
+	"strconv"
+	"syscall"
+
+	"github.com/synopackageland/syno-pkg-land-sdk/background"
+)
+
+// Set by `synopkgland build-spk` through -ldflags -X.
+var packageID = "dev"
+
+func main() {
+	log.SetFlags(0)
+	log.SetPrefix(packageID + " background: ")
+	if err := background.RefuseRoot(os.Geteuid()); err != nil {
+		log.Fatal(err)
+	}
+	name := ""
+	if u, err := user.Current(); err == nil {
+		name = u.Username
+	}
+	info := background.WorkerInfo{PID: os.Getpid(), UID: os.Getuid(), Username: name}
+	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, syscall.SIGINT)
+	defer stop()
+	log.Printf("started as uid %s", strconv.Itoa(info.UID))
+	if err := background.NewRunner("/var/packages/"+packageID+"/var/background", info).Run(ctx); err != nil {
+		log.Fatal(err)
+	}
+}

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

@@ -0,0 +1,9 @@
+module __PACKAGE__
+
+go 1.25.0
+
+toolchain go1.26.9
+
+require github.com/synopackageland/syno-pkg-land-sdk v0.9.1
+
+require golang.org/x/sys v0.44.0 // indirect

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

@@ -0,0 +1,4 @@
+github.com/synopackageland/syno-pkg-land-sdk v0.9.1 h1:Mni+769M/fldZTlv0IOZKeaK3xGu6hTSkTeWIALPqBg=
+github.com/synopackageland/syno-pkg-land-sdk v0.9.1/go.mod h1:JNoqISvR4biA9IuLi0CFe4c272tsKzCN9Nyj71nrXsQ=
+golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
+golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=

package/templates/native-go/backend/internal/api/permissions.go

@@ -0,0 +1,26 @@
+// Package api holds this App's method policy. The SDK's own capability
+// methods keep the SDK policy; this file only configures App methods.
+package api
+
+import (
+	"crypto/sha256"
+	_ "embed"
+	"errors"
+	"fmt"
+)
+
+//go:embed permissions.json
+var permissionsJSON []byte
+
+// Set by `synopkgland build` through -ldflags -X to bind the policy it
+// validated to the compiled CGI. Empty only in direct Go development builds.
+var expectedPermissionsDigest string
+
+// Permissions returns permissions.json, refusing a file that differs from the
+// one the package build validated.
+func Permissions() ([]byte, error) {
+	if expectedPermissionsDigest != "" && fmt.Sprintf("%x", sha256.Sum256(permissionsJSON)) != expectedPermissionsDigest {
+		return nil, errors.New("API permissions do not match package build policy")
+	}
+	return permissionsJSON, nil
+}

package/templates/native-go/backend/internal/api/permissions.json

@@ -0,0 +1,5 @@
+{
+  "schema": 1,
+  "default": "administrators",
+  "methods": {}
+}

package/templates/native-go/backend/internal/api/permissions_test.go

@@ -0,0 +1,30 @@
+package api
+
+import (
+	"crypto/sha256"
+	"fmt"
+	"testing"
+)
+
+func TestPermissionsWithoutABuildDigestAreTheEmbeddedFile(t *testing.T) {
+	got, err := Permissions()
+	if err != nil || string(got) != string(permissionsJSON) {
+		t.Fatalf("Permissions() = %q, %v", got, err)
+	}
+}
+
+func TestPermissionsMatchingTheBuildDigestAreAccepted(t *testing.T) {
+	t.Cleanup(func() { expectedPermissionsDigest = "" })
+	expectedPermissionsDigest = fmt.Sprintf("%x", sha256.Sum256(permissionsJSON))
+	if _, err := Permissions(); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestPermissionsDifferingFromTheBuildDigestAreRefused(t *testing.T) {
+	t.Cleanup(func() { expectedPermissionsDigest = "" })
+	expectedPermissionsDigest = fmt.Sprintf("%x", sha256.Sum256([]byte("other")))
+	if got, err := Permissions(); err == nil || got != nil {
+		t.Fatalf("Permissions() = %q, %v; want refusal", got, err)
+	}
+}