@synopackageland/cli 0.3.10 → 0.4.1

package/dist/templates/_shared/third-party-notices.mjs

@@ -0,0 +1,51 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// Conservative inventory of every locked production dependency, including
+// dependencies tree-shaken from the bundle. Build tools marked dev are omitted.
+// Read actual upstream license/notice files, never synthesize license text from
+// SPDX metadata. npm ci must have installed the exact lock before this runs.
+export function writeThirdPartyNotices(root, output, { ui = false } = {}) {
+  const lock = JSON.parse(readFileSync(join(root, 'package-lock.json'), 'utf8'));
+  if (lock.lockfileVersion < 2 || !lock.packages) throw new Error('Notice generation requires a v2/v3 npm lockfile');
+  const inventory = [];
+  const sections = [];
+  let uiFiles;
+  for (const [path, entry] of Object.entries(lock.packages).sort(([a], [b]) => a.localeCompare(b, 'en'))) {
+    if (!path || entry.dev) continue;
+    if (!/^node_modules\//.test(path) || path.split('/').includes('..') || entry.link) throw new Error(`Unsupported notice package path: ${path}`);
+    const dir = join(root, path);
+    const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+    if (pkg.version !== entry.version) throw new Error(`Notice version mismatch: ${path}; run npm ci`);
+    const files = readdirSync(dir, { withFileTypes: true })
+      .filter(f => f.isFile() && /^(licen[sc]e|copying|notice|copyright)([.-]|$)/i.test(f.name))
+      .map(f => f.name).sort();
+    const texts = files.map(file => ({ file, text: readFileSync(join(dir, file), 'utf8') }));
+    let source, provenance;
+    if (!files.some(f => /^(licen[sc]e|copying)([.-]|$)/i.test(f))) {
+      const index = new URL('./notice-overrides/index.json', import.meta.url);
+      const overrides = existsSync(index) ? JSON.parse(readFileSync(index, 'utf8')) : {};
+      const override = overrides[`${pkg.name}@${pkg.version}`];
+      if (!override || !entry.integrity || override.integrity !== entry.integrity) throw new Error(`Missing upstream license text: ${pkg.name}@${pkg.version}`);
+      source = override.source;
+      provenance = override.provenance;
+      texts.push({file: 'LICENSE (pinned upstream source)', text: readFileSync(new URL(`./notice-overrides/${override.file}`, import.meta.url), 'utf8')});
+      files.push(override.file);
+    }
+    // UI ships its own aggregate for fonts, icons and dependencies/assets.
+    if (pkg.name === '@synopackageland/ui') {
+      uiFiles = {
+        'UI-LICENSE': readFileSync(join(dir, 'LICENSE'), 'utf8'),
+        'UI-THIRD_PARTY.md': readFileSync(join(dir, 'LICENSES/THIRD_PARTY.md'), 'utf8'),
+      };
+    }
+    inventory.push({ name: pkg.name, version: pkg.version, license: pkg.license ?? entry.license ?? 'unknown', integrity: entry.integrity, path, files, ...(source ? {source, provenance} : {}) });
+    sections.push(`\n===== ${pkg.name}@${pkg.version} (${pkg.license ?? entry.license ?? 'unknown'}) =====\n` + (source ? `Source: ${source}\n${provenance}\n` : '') + texts.map(({ file, text }) => `\n--- ${file} ---\n${text}\n`).join(''));
+  }
+  if (ui && !uiFiles) throw new Error('UI dependency is missing from the locked production inventory');
+  rmSync(output, { recursive: true, force: true });
+  mkdirSync(output, { recursive: true });
+  writeFileSync(join(output, 'THIRD_PARTY_NOTICES.txt'), 'Locked production dependency notices (conservative superset of bundled code).\n' + sections.join(''));
+  writeFileSync(join(output, 'inventory.json'), JSON.stringify(inventory, null, 2) + '\n');
+  for (const [name, text] of Object.entries(uiFiles ?? {})) writeFileSync(join(output, name), text);
+}

package/dist/templates/binary/synology-app.yaml

@@ -0,0 +1,7 @@
+schema: 1
+package: com.example.binary-app
+version: 0.1.0
+displayname: Binary App
+description: A minimal Syno Package Land app that runs one prebuilt binary.
+maintainer: Syno Package Land
+os_min_ver: "7.2-60000"

package/dist/templates/hello-files/compose.yaml

@@ -3,7 +3,6 @@ services:
     image: alpine:3.20
     command: ["sleep", "infinity"]
     volumes:
-      # Dynamic Shared Folder plus writable /state is Broker-managed and is
       # intentionally outside the zero-config docker-project resource-worker path.
       - "${MEDIA_SHARE}/data:/data:ro"
       - "${SYNOPKG_PKGVAR}/state:/state"

package/dist/templates/hello-web/compose.yaml

@@ -1,16 +1,19 @@
 services:
   web:
     image: busybox:1.36
-    # 兩個平台限制，改動前先看 docs/impl/STATUS.md 的 2026-08-24 段：
-    # 1) command／entrypoint 陣列不得有純數字元素（例如 "18333"）。DSM 的
-    #    docker-project worker 會在 YAML round-trip 時掉引號、把它變成整數，
-    #    postinst acquire 直接失敗（error 276 → 套件 broken/150，且 worker_msg
-    #    為空，開發者看不到原因）。所以 port 要包在單一字串裡。
-    #    `synopkgland validate` 已會擋這個寫法。
-    # 2) 預設不用 8080：那個 port 在真實 NAS 上很常被既有容器占用，而 port
-    #    衝突同樣以那個看不出原因的 broken/150 呈現。
-    # 官方 nginx image 也不能用：resource worker 注入任意 package UID/GID，
-    # nginx entrypoint 啟動階段需要 root，會在該身分下直接退出。
+    # DSM worker constraints to preserve when changing this service:
+    # 1) command/entrypoint arrays must not contain bare numeric elements
+    #    (such as "18333"). DSM's docker-project worker drops the quotes on a
+    #    YAML round-trip and turns them into integers, so postinst acquire
+    #    fails (error 276 -> package broken/150, with an empty worker_msg that
+    #    tells the developer nothing). Keep the port inside one string.
+    #    `synopkgland validate` already rejects the bare form.
+    # 2) The default is not 8080: that port is often taken by an existing
+    #    container on a real NAS, and the conflict shows up as the same
+    #    unexplained broken/150.
+    # The official nginx image cannot be used either: the resource worker
+    # injects an arbitrary package UID/GID, and the nginx entrypoint needs
+    # root during startup, so it exits immediately under that identity.
     command: ["sh","-c","httpd -f -p 18333 -h /usr/share/nginx/html"]
     ports:
       - "18333:18333"

package/dist/templates/hello-web/html/app.js

@@ -1,23 +1 @@
-import { createSynologyClient } from "./sdk.js";
-
-const status = document.getElementById("status");
-const userEl = document.getElementById("user");
-
-const client = createSynologyClient();
-
-try {
-  await client.auth.requireLogin();
-  const user = await client.auth.getCurrentUser();
-  if (status) {
-    status.textContent = "Signed in with DSM";
-  }
-  if (userEl) {
-    userEl.textContent = user.username;
-  }
-} catch (error) {
-  const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
-  const message = error instanceof Error ? error.message : String(error);
-  if (status) {
-    status.textContent = code === "UNAUTHENTICATED" ? "DSM login required" : message;
-  }
-}
+document.getElementById("status").textContent = "Your app is running.";

package/dist/templates/hello-web/html/index.html

@@ -7,9 +7,7 @@
   </head>
   <body>
     <h1>Hello Web</h1>
-    <p id="status">Opening with your DSM session…</p>
-    <p id="user"></p>
-    <script src="./bootstrap.js"></script>
+    <p id="status">Loading…</p>
     <script type="module" src="./app.js"></script>
   </body>
 </html>

package/dist/templates/hello-web-page/compose.yaml

@@ -1,16 +1,19 @@
 services:
   web:
     image: busybox:1.36
-    # 兩個平台限制，改動前先看 docs/impl/STATUS.md 的 2026-08-24 段：
-    # 1) command／entrypoint 陣列不得有純數字元素（例如 "18333"）。DSM 的
-    #    docker-project worker 會在 YAML round-trip 時掉引號、把它變成整數，
-    #    postinst acquire 直接失敗（error 276 → 套件 broken/150，且 worker_msg
-    #    為空，開發者看不到原因）。所以 port 要包在單一字串裡。
-    #    `synopkgland validate` 已會擋這個寫法。
-    # 2) 預設不用 8080：那個 port 在真實 NAS 上很常被既有容器占用，而 port
-    #    衝突同樣以那個看不出原因的 broken/150 呈現。
-    # 官方 nginx image 也不能用：resource worker 注入任意 package UID/GID，
-    # nginx entrypoint 啟動階段需要 root，會在該身分下直接退出。
+    # DSM worker constraints to preserve when changing this service:
+    # 1) command/entrypoint arrays must not contain bare numeric elements
+    #    (such as "18333"). DSM's docker-project worker drops the quotes on a
+    #    YAML round-trip and turns them into integers, so postinst acquire
+    #    fails (error 276 -> package broken/150, with an empty worker_msg that
+    #    tells the developer nothing). Keep the port inside one string.
+    #    `synopkgland validate` already rejects the bare form.
+    # 2) The default is not 8080: that port is often taken by an existing
+    #    container on a real NAS, and the conflict shows up as the same
+    #    unexplained broken/150.
+    # The official nginx image cannot be used either: the resource worker
+    # injects an arbitrary package UID/GID, and the nginx entrypoint needs
+    # root during startup, so it exits immediately under that identity.
     command: ["sh","-c","httpd -f -p 18333 -h /usr/share/nginx/html"]
     ports:
       - "18333:18333"

package/dist/templates/hello-web-page/html/app.js

@@ -1,23 +1 @@
-import { createSynologyClient } from "./sdk.js";
-
-const status = document.getElementById("status");
-const userEl = document.getElementById("user");
-
-const client = createSynologyClient();
-
-try {
-  await client.auth.requireLogin();
-  const user = await client.auth.getCurrentUser();
-  if (status) {
-    status.textContent = "Signed in with DSM";
-  }
-  if (userEl) {
-    userEl.textContent = user.username;
-  }
-} catch (error) {
-  const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
-  const message = error instanceof Error ? error.message : String(error);
-  if (status) {
-    status.textContent = code === "UNAUTHENTICATED" ? "DSM login required" : message;
-  }
-}
+document.getElementById("status").textContent = "Your app is running.";

package/dist/templates/hello-web-page/html/index.html

@@ -7,9 +7,7 @@
   </head>
   <body>
     <h1>Hello Web Page</h1>
-    <p id="status">Opening with your DSM session…</p>
-    <p id="user"></p>
-    <script src="./bootstrap.js"></script>
+    <p id="status">Loading…</p>
     <script type="module" src="./app.js"></script>
   </body>
 </html>

package/dist/templates/native-go/README.md

@@ -0,0 +1,324 @@
+# __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
+      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.24+.
+
+```bash
+(cd backend && go test ./...)   # auth policy + route tests
+synopkgland build-spk           # → dist/__PACKAGE__-0.1.0-0001-{x86_64,aarch64}.spk
+synopkgland inspect --spk 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.
+
+## 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` | Synology's official DSM terms, and which messages must use them | Add terms |
+| `backend/internal/app/` | Your API: routes and handlers | Yes — your backend |
+| `backend/internal/api/` | The CGI front door: guards, auth order, route policies | Rarely |
+| `backend/internal/dsm/` | DSM session check and administrators lookup | Rarely |
+| `backend/cmd/app/` | Wires the above together | Rarely |
+| `dist/` | Built SPKs (ignored by git) | No |
+
+`build-spk` 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 route in `backend/internal/app/routes.go`. The policy is part of the
+route, so you cannot register a handler without one:
+
+```go
+func Routes(cfg Config) []api.Route {
+	return []api.Route{
+		api.User("app.status", cfg.status),
+		api.User("greeting.get", cfg.getGreeting),
+		api.Admin("greeting.set", cfg.setGreeting),
+		api.User("notes.list", cfg.listNotes),   // new: any signed-in user
+		api.Admin("notes.purge", cfg.purgeNotes), // new: administrators only
+	}
+}
+
+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 non-admins, for `api.Admin`) 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
+
+| Declared with | No session | Signed-in user | Administrator |
+| --- | --- | --- | --- |
+| `api.User` | `session_required` | runs | runs |
+| `api.Admin` | `session_required` | `admin_required` | runs |
+| `api.Public` | runs | runs | runs |
+| not registered | `session_required` | `unknown_method` | `unknown_method` |
+
+Every reply, error or not, is HTTP 200 with `{"success": false, "error":
+{"code", "message"}}` on failure, the same convention as DSM's own WebAPI.
+DSM's web server replaces the body of any CGI reply with status 403, 404 or
+5xx by its own HTML error page, so a status-coded error would never reach your
+UI.
+
+- Handlers get an `api.Caller` the server built after authenticating; code
+  outside `internal/api` cannot construct an authenticated one.
+- `api.Public` runs with **no** DSM login. Use it only for data you would show
+  anyone who can reach DSM's port; the template ships none.
+- "Administrator" means a member of DSM's `administrators` group, read fresh
+  from `/etc/group` on every request.
+
+## How authentication works (and its limits)
+
+The CGI hands only the session carriers (`Cookie`, `X-SYNO-TOKEN`, client
+address) to DSM's own `/usr/syno/synoman/webman/modules/authenticate.cgi`,
+which prints the signed-in user name. The backend never parses the session
+cookie and never takes a user name or admin flag from the request.
+
+Cross-site requests are refused: the API accepts only `POST` with
+`Content-Type: application/json` (which forces a CORS preflight DSM never
+approves), and it rejects `Sec-Fetch-Site` other than `same-origin` and any
+foreign `Origin`. The DSM window wrapper sends DSM's `SynoToken`, but when DSM
+has `enable_syno_token=no` that token proves nothing, so the same-origin
+checks are what stop cross-site requests.
+
+Known limits:
+
+- Each request reuses the browser's DSM session; it does not carry DSM's
+  per-request `X-SYNO-HASH` proof. Verifying that proof needs private,
+  version-specific DSM libraries through a C bridge, so it is not part of this
+  template.
+- Users from a directory service (LDAP/AD) who are administrators only
+  through directory groups are not listed in `/etc/group`, so they count as
+  ordinary users. This errs towards refusal.
+
+## 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. DSM runtime remains unknown.
+
+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 public `@synopackageland/ui@0.4.0` package on
+`https://registry.npmjs.org` 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-spk` 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 validate` and `build-spk` 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.
+
+## 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:
+  binary:
+    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 `backend/internal/api` does for you: bounded reads,
+POST-only JSON, same-origin checks, authentication before any work, and a
+refusal for unknown methods.
+
+## 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.
+
+## Root access
+
+By default (`privilege: none`) nothing in this package ever runs as root, and
+that is the right choice for almost every app. Lifecycle scripts and the CGI
+run as the package account, and nothing the package account can write is ever
+run as root.
+
+If your app truly needs root for a few fixed actions, create the project with
+`synopkgland init -t native-go --privilege root`. That sets `privilege: root`
+and adds:
+
+- `root/whoami.sh`: one root operation. Each `root/<name>.sh` (lowercase name,
+  `#!/bin/sh`, at most 16 KiB) is one operation. The demo only reports the
+  user ID it runs as (`{"euid":0}`). Replace it with your own fixed actions.
+- `backend/internal/app/root.go`: the `root.output` route (administrators
+  only) that returns an operation's last result.
+
+How it works, with no keys or signing involved:
+
+1. `build-spk` embeds each operation's exact task text in the DSM window. The
+   SPK payload carries no root script, and the package still runs as its own
+   account.
+2. The window shows an authorization panel above your app, in the user's
+   DSM language. A DSM administrator clicks **Authorize** and confirms with
+   their DSM password in DSM's own dialog. DSM then creates one **disabled**
+   root task in Task Scheduler, named `<package> root: <name>`. The
+   confirmation is used for that one task and never stored.
+3. **Run** checks that the task is still exactly the approved text, runs it
+   with the administrator's session and shows its result. The task writes
+   only to `/run/synopkgland-<package>/<name>.out`, which root owns and your
+   backend can only read.
+4. The task text includes the package version, so after an upgrade the panel
+   shows "needs authorization again" and the old task never runs. A
+   same-named task that the panel did not create is never run, replaced or
+   deleted.
+5. **Remove** deletes the task, also an outdated one, without asking for the
+   password. Remove it before uninstalling the package, because DSM keeps
+   Task Scheduler tasks after an uninstall.
+
+Non-administrators see DSM's "Only administrator accounts can perform this
+operation." and nothing else. HTTP requests can never choose what runs as
+root: the only root code is the fixed text an administrator approved. Your app
+can also use `ctx.root` (`state`, `authorize`, `run`, `remove`, `output`) to
+drive the same flow from its own UI.
+
+## Support matrix
+
+| | Status |
+| --- | --- |
+| Build hosts | macOS, Linux (any OS with Go and Node) |
+| Target CPUs | x86_64 and aarch64 DSM models (one SPK each) |
+| DSM | 7.2 or later declared (`os_min_ver`). Installed and tested on DSM 7.4 (x86_64). aarch64 SPKs are built the same way but have not been run on a NAS. |
+| Not supported | 32-bit ARM, DSM 6, running anything as root without an administrator's approval |

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

@@ -0,0 +1,59 @@
+DSM integration helper build dependencies
+
+github.com/godbus/dbus/v5 v5.2.2 (BSD-2-Clause)
+
+Copyright (c) 2013, Georg Reinke (<guelfey at gmail dot com>), Google
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.
+
+2. 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.
+
+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
+HOLDER 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.
+
+golang.org/x/sys v0.27.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/dist/templates/native-go/backend/cmd/app/main.go

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