@synopackageland/cli 0.3.9 → 0.4.0

package/templates/native-go/README.md

@@ -0,0 +1,268 @@
+# __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. Scope your CSS under your own root class:
+every DSM app shares one page.
+
+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/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)
+	}
+}

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

@@ -0,0 +1,38 @@
+// Built only when dsm-package.yaml explicitly opts into integration.
+package main
+
+import (
+	"context"
+	"dsmapp/internal/helper"
+	"encoding/json"
+	"fmt"
+	"os"
+)
+
+var helperInventory string
+
+func main() {
+	var i helper.Inventory
+	if len(os.Args) != 2 || json.Unmarshal([]byte(helperInventory), &i) != nil {
+		os.Exit(2)
+	}
+	if os.Args[1] == "check-stopped" || os.Args[1] == "diagnose" {
+		c, err := helper.LocalClient(i)
+		if err != nil {
+			os.Exit(1)
+		}
+		if os.Args[1] == "diagnose" {
+			json.NewEncoder(os.Stdout).Encode(c.Status(context.Background()))
+			return
+		}
+		if c.CheckStopped(context.Background()) != nil {
+			os.Exit(1)
+		}
+		return
+	}
+	if err := helper.RunLinux(i, os.Args[1]); err != nil {
+		fmt.Fprintln(os.Stderr, "helper lifecycle refused")
+		os.Exit(1)
+	}
+	fmt.Println(`{"success":true}`)
+}

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

@@ -0,0 +1,3 @@
+module dsmapp
+
+go 1.24

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

@@ -0,0 +1,33 @@
+package api
+
+import (
+	"errors"
+	"log"
+)
+
+// Error is an API error the browser may see. Any other error a handler
+// returns is logged and reported only as "internal". Errors travel in the
+// JSON envelope with HTTP 200, as DSM's own WebAPI does: DSM's web server
+// replaces the body of a CGI's 403, 404 and 5xx replies with its own page.
+type Error struct {
+	Code    string
+	Message string
+}
+
+func (e *Error) Error() string { return e.Code + ": " + e.Message }
+
+// BadRequest reports invalid params.
+func BadRequest(message string) *Error {
+	return &Error{"bad_request", message}
+}
+
+var internalError = &Error{"internal", "internal error"}
+
+func asError(err error) *Error {
+	var apiErr *Error
+	if errors.As(err, &apiErr) {
+		return apiErr
+	}
+	log.Printf("handler error: %v", err)
+	return internalError
+}

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

@@ -0,0 +1,94 @@
+// Package api is the package's one HTTP entry point. Every request passes the
+// same transport guards and, unless its route was explicitly declared Public,
+// one DSM authentication before any handler runs. The policy is part of the
+// route itself: a Route can only be made through User, Admin or Public, so a
+// handler cannot be registered without saying who may call it.
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"regexp"
+)
+
+type policy int
+
+const (
+	policyUnset policy = iota
+	policyUser
+	policyAdmin
+	policyPublic
+)
+
+// Handler runs one business operation. It receives the caller the server
+// verified and the raw `params` object; it decodes params itself.
+type Handler func(ctx context.Context, caller Caller, params json.RawMessage) (any, error)
+
+// Route binds a method name to its handler and access policy. Its fields are
+// private: build routes with User, Admin or Public.
+type Route struct {
+	method  string
+	policy  policy
+	handler Handler
+}
+
+// User declares an operation any signed-in DSM user may call.
+func User(method string, h Handler) Route { return Route{method, policyUser, h} }
+
+// Admin declares an operation only members of DSM's administrators group may call.
+func Admin(method string, h Handler) Route { return Route{method, policyAdmin, h} }
+
+// Public declares an operation that runs WITHOUT a DSM session. Use it only for
+// data that is safe to show anyone who can reach the NAS's DSM port.
+func Public(method string, h Handler) Route { return Route{method, policyPublic, h} }
+
+// Identity is what an Authenticator established about the requester.
+type Identity struct {
+	User  string
+	Admin bool
+}
+
+// Caller is the verified requester handed to handlers. Only the server sets
+// its fields, so a handler cannot fabricate an authenticated caller; the zero
+// value carries no authority.
+type Caller struct {
+	identity      Identity
+	authenticated bool
+}
+
+func (c Caller) Authenticated() bool { return c.authenticated }
+func (c Caller) User() string        { return c.identity.User }
+func (c Caller) Admin() bool         { return c.authenticated && c.identity.Admin }
+
+var methodName = regexp.MustCompile(`^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$`)
+
+func buildRegistry(routes []Route) (map[string]Route, error) {
+	registry := make(map[string]Route, len(routes))
+	for _, r := range routes {
+		if r.policy == policyUnset {
+			return nil, errors.New("route without access policy: build it with api.User, api.Admin or api.Public")
+		}
+		if !methodName.MatchString(r.method) {
+			return nil, fmt.Errorf("route %q: method must look like \"area.action\" (lowercase)", r.method)
+		}
+		if r.handler == nil {
+			return nil, fmt.Errorf("route %q has no handler", r.method)
+		}
+		if _, dup := registry[r.method]; dup {
+			return nil, fmt.Errorf("route %q is registered twice", r.method)
+		}
+		registry[r.method] = r
+	}
+	return registry, nil
+}
+
+// Method is the route's method name, e.g. "greeting.set".
+func (r Route) Method() string { return r.method }
+
+// Public reports whether the route was declared with Public.
+func (r Route) Public() bool { return r.policy == policyPublic }
+
+// AdminOnly reports whether the route was declared with Admin.
+func (r Route) AdminOnly() bool { return r.policy == policyAdmin }