@synopackageland/cli 0.6.0 → 0.7.0

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

@@ -0,0 +1,138 @@
+// Package portal reads the DSM Application Portal alias an administrator set
+// for this package. DSM owns the setting: the package never writes it, and
+// anything this reader does not fully understand reads as Unavailable.
+package portal
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"io"
+	"io/fs"
+	"os"
+	"regexp"
+	"syscall"
+	"unicode/utf8"
+
+	"dsmapp/internal/jsonlimits"
+)
+
+// MaxConfigBytes bounds DSM's saved setting; its real size is a few hundred bytes.
+const MaxConfigBytes = 64 << 10
+
+const (
+	// Active means users can open the app at /<alias>/ after DSM sign-in.
+	Active = "active"
+	// Inactive means no administrator has set an alias yet.
+	Inactive = "inactive"
+	// Unavailable means the setting could not be read safely.
+	Unavailable = "unavailable"
+)
+
+// Status is what portal.status returns; Alias is set only when Active.
+type Status struct {
+	State string `json:"state"`
+	Alias string `json:"alias,omitempty"`
+}
+
+// A single URL path segment; DSM's own validation is looser than this.
+var aliasPattern = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$`)
+
+// ConfigPath is where DSM saves the package's portal setting
+// (/var/packages/<package>/etc is the package's @appconf directory).
+func ConfigPath(packageID string) string {
+	return "/var/packages/" + packageID + "/etc/AppPortal.json"
+}
+
+// Read returns the saved alias when the setting belongs to appID.
+func Read(path, appID string) Status {
+	raw, err := readBounded(path)
+	if errors.Is(err, fs.ErrNotExist) {
+		return Status{State: Inactive}
+	}
+	if err != nil {
+		return Status{State: Unavailable}
+	}
+	id, alias, ok := parse(raw)
+	if !ok || id != appID {
+		return Status{State: Unavailable}
+	}
+	if alias == "" {
+		return Status{State: Inactive}
+	}
+	if !aliasPattern.MatchString(alias) {
+		return Status{State: Unavailable}
+	}
+	return Status{State: Active, Alias: alias}
+}
+
+func readBounded(path string) ([]byte, error) {
+	f, err := os.OpenFile(path, os.O_RDONLY|syscall.O_NOFOLLOW|syscall.O_NONBLOCK, 0)
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+	info, err := f.Stat()
+	if err != nil {
+		return nil, err
+	}
+	if !info.Mode().IsRegular() {
+		return nil, errors.New("not a regular file")
+	}
+	raw, err := io.ReadAll(io.LimitReader(f, MaxConfigBytes+1))
+	if err != nil {
+		return nil, err
+	}
+	if len(raw) > MaxConfigBytes {
+		return nil, errors.New("too large")
+	}
+	return raw, nil
+}
+
+// parse accepts exactly one JSON object with unique top-level keys, a string
+// id and a string or null alias; other DSM fields are skipped unread.
+func parse(raw []byte) (id, alias string, ok bool) {
+	if !utf8.Valid(raw) || !jsonlimits.WithinLimits(raw) {
+		return "", "", false
+	}
+	d := json.NewDecoder(bytes.NewReader(raw))
+	if token, err := d.Token(); err != nil || token != json.Delim('{') {
+		return "", "", false
+	}
+	seen := map[string]bool{}
+	hasID := false
+	for d.More() {
+		token, err := d.Token()
+		key, isKey := token.(string)
+		if err != nil || !isKey || seen[key] {
+			return "", "", false
+		}
+		seen[key] = true
+		var value json.RawMessage
+		if err := d.Decode(&value); err != nil {
+			return "", "", false
+		}
+		switch key {
+		case "id":
+			if json.Unmarshal(value, &id) != nil || id == "" {
+				return "", "", false
+			}
+			hasID = true
+		case "alias":
+			var text *string
+			if json.Unmarshal(value, &text) != nil {
+				return "", "", false
+			}
+			if text != nil {
+				alias = *text
+			}
+		}
+	}
+	if token, err := d.Token(); err != nil || token != json.Delim('}') {
+		return "", "", false
+	}
+	if _, err := d.Token(); err != io.EOF {
+		return "", "", false
+	}
+	return id, alias, hasID
+}

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

@@ -0,0 +1,89 @@
+package portal
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+const appID = "SYNO.SDS.HelloGo.Instance"
+
+// saved mirrors DSM 7.4's AppPortal.json after an administrator sets an alias.
+func saved(alias string) string {
+	return "{\n\t\"acl\" : \"\",\n\t\"alias\" : " + alias + ",\n\t\"alternatePort\" : null,\n\t\"application\" : \"Hello Go\",\n\t\"fqdn\" : null,\n\t\"https\" : \n\t{\n\t\t\"hsts\" : false\n\t},\n\t\"id\" : \"" + appID + "\",\n\t\"version\" : 3\n}\n"
+}
+
+func write(t *testing.T, content string) string {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "AppPortal.json")
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return path
+}
+
+func TestActiveAlias(t *testing.T) {
+	got := Read(write(t, saved(`"hello-go"`)), appID)
+	if got != (Status{State: Active, Alias: "hello-go"}) {
+		t.Fatalf("got %+v", got)
+	}
+}
+
+func TestNoSavedSettingIsInactive(t *testing.T) {
+	if got := Read(filepath.Join(t.TempDir(), "AppPortal.json"), appID); got != (Status{State: Inactive}) {
+		t.Fatalf("missing file: %+v", got)
+	}
+	for _, alias := range []string{`null`, `""`} {
+		if got := Read(write(t, saved(alias)), appID); got != (Status{State: Inactive}) {
+			t.Fatalf("alias %s: %+v", alias, got)
+		}
+	}
+}
+
+func TestAnythingElseFailsClosed(t *testing.T) {
+	other := strings.Replace(saved(`"hello-go"`), appID, "SYNO.SDS.Other.Instance", 1)
+	cases := map[string]string{
+		"another app":     other,
+		"no id":           `{"alias":"hello-go"}`,
+		"duplicate alias": `{"alias":"hello-go","alias":"evil","id":"` + appID + `"}`,
+		"duplicate id":    `{"id":"SYNO.SDS.Other.Instance","alias":"hello-go","id":"` + appID + `"}`,
+		"alias number":    saved(`1`),
+		"alias path":      saved(`"a/b"`),
+		"alias dots":      saved(`".."`),
+		"alias query":     saved(`"a?b"`),
+		"alias too long":  saved(`"` + strings.Repeat("a", 65) + `"`),
+		"array":           `[]`,
+		"trailing value":  saved(`"hello-go"`) + `{}`,
+		"not json":        `alias=hello-go`,
+		"not utf8":        "{\"alias\":\"\xff\",\"id\":\"" + appID + "\"}",
+		"too large":       saved(`"hello-go"`) + strings.Repeat(" ", MaxConfigBytes),
+		"too deep":        strings.Replace(saved(`"hello-go"`), `"acl" : ""`, `"acl" : `+strings.Repeat("[", 64)+strings.Repeat("]", 64), 1),
+	}
+	for name, content := range cases {
+		if got := Read(write(t, content), appID); got != (Status{State: Unavailable}) {
+			t.Errorf("%s: %+v", name, got)
+		}
+	}
+}
+
+func TestOnlyARegularFileIsRead(t *testing.T) {
+	dir := t.TempDir()
+	target := write(t, saved(`"hello-go"`))
+	link := filepath.Join(dir, "AppPortal.json")
+	if err := os.Symlink(target, link); err != nil {
+		t.Fatal(err)
+	}
+	if got := Read(link, appID); got != (Status{State: Unavailable}) {
+		t.Fatalf("symlink: %+v", got)
+	}
+	if got := Read(dir, appID); got != (Status{State: Unavailable}) {
+		t.Fatalf("directory: %+v", got)
+	}
+}
+
+func TestConfigPathIsThePackagesOwnSetting(t *testing.T) {
+	if got := ConfigPath("HelloGo"); got != "/var/packages/HelloGo/etc/AppPortal.json" {
+		t.Fatal(got)
+	}
+}

package/templates/native-go/dsm-package.yaml

@@ -11,9 +11,28 @@ build: 1
 displayname: __DISPLAY_NAME__
 description: A native DSM package with a Go backend and a DSM window UI.
 maintainer: Your Name
+# Optional INFO/website metadata. Omit fields you do not need.
+# metadata:
+#   contact_email: you@example.com
+#   support_email: support@example.com
+#   homepage: https://example.com
+#   source_url: https://github.com/you/your-app
+#   issues_url: https://github.com/you/your-app/issues
+#   license: MIT
+#   long_description:
+#     en: |-
+#       Explain what the app does and how to use it.
+#     zh-TW: Translated description.
+#   changelog:          # text, or per-language like long_description
+#     en: |-
+#       - Most important change first. Omit to use Release notes.
+#     zh-TW: |-
+#       - Translated changes.
+#   screenshots: [https://example.com/screenshot.png]
 os_min_ver: "7.1-42661"
 
-# One SPK per architecture. Supported: x86_64, aarch64.
+# One SPK per architecture. Supported: x86_64, aarch64, armv7 (add it here to
+# build it; armv7 jobs/delegate/root-ops/daemon are built but not NAS-verified).
 arches: [x86_64, aarch64]
 
 backend:

package/templates/native-go/i18n/glossary.json

@@ -580,7 +580,8 @@
         "it": "Siamo spiacenti, a questo account utente non sono stati assegnati privilegi appropriati per eseguire questa azione."
       },
       "keys": [
-        "error.admin_required"
+        "error.admin_required",
+        "error.app_privilege_denied"
       ]
     },
     {

package/templates/native-go/i18n/messages/de.json

@@ -3,6 +3,7 @@
   "app.refresh": "Aktualisieren",
   "app.title": "Es funktioniert",
   "error.admin_required": "Dieses Benutzerkonto verfügt nicht über die erforderlichen Berechtigungen, um diese Aktion durchzuführen.",
+  "error.app_privilege_denied": "Dieses Benutzerkonto verfügt nicht über die erforderlichen Berechtigungen, um diese Aktion durchzuführen.",
   "error.auth_unavailable": "Dieser Vorgang kann nicht ausgeführt werden. Bitte versuchen Sie es später erneut.",
   "error.bad_request": "Überprüfen Sie den eingegebenen Wert und versuchen Sie es erneut.",
   "error.bad_response": "Dieser Vorgang kann nicht ausgeführt werden. Bitte versuchen Sie es später erneut.",

package/templates/native-go/i18n/messages/en.json

@@ -3,6 +3,7 @@
   "app.refresh": "Refresh",
   "app.title": "It works",
   "error.admin_required": "Sorry, this user account has not been assigned proper privileges to perform this action.",
+  "error.app_privilege_denied": "Sorry, this user account has not been assigned proper privileges to perform this action.",
   "error.auth_unavailable": "Unable to perform this operation. Please try again later.",
   "error.bad_request": "Check the entered value and try again.",
   "error.bad_response": "Unable to perform this operation. Please try again later.",

package/templates/native-go/i18n/messages/es.json

@@ -3,6 +3,7 @@
   "app.refresh": "Actualizar",
   "app.title": "Funciona",
   "error.admin_required": "A esta cuenta de usuario no se le han asignado los privilegios adecuados para realizar esta acción.",
+  "error.app_privilege_denied": "A esta cuenta de usuario no se le han asignado los privilegios adecuados para realizar esta acción.",
   "error.auth_unavailable": "No se puede realizar esta operación. Vuelva a intentarlo más tarde.",
   "error.bad_request": "Compruebe el valor introducido y vuelva a intentarlo.",
   "error.bad_response": "No se puede realizar esta operación. Vuelva a intentarlo más tarde.",

package/templates/native-go/i18n/messages/fr.json

@@ -3,6 +3,7 @@
   "app.refresh": "Actualiser",
   "app.title": "Ça fonctionne",
   "error.admin_required": "Désolé, ce compte utilisateur ne dispose pas des droits nécessaires pour accomplir cette action.",
+  "error.app_privilege_denied": "Désolé, ce compte utilisateur ne dispose pas des droits nécessaires pour accomplir cette action.",
   "error.auth_unavailable": "Impossible d'effectuer cette opération. Veuillez réessayer ultérieurement.",
   "error.bad_request": "Vérifiez la valeur saisie et réessayez.",
   "error.bad_response": "Impossible d'effectuer cette opération. Veuillez réessayer ultérieurement.",

package/templates/native-go/i18n/messages/it.json

@@ -3,6 +3,7 @@
   "app.refresh": "Aggiorna",
   "app.title": "Funziona",
   "error.admin_required": "Siamo spiacenti, a questo account utente non sono stati assegnati privilegi appropriati per eseguire questa azione.",
+  "error.app_privilege_denied": "Siamo spiacenti, a questo account utente non sono stati assegnati privilegi appropriati per eseguire questa azione.",
   "error.auth_unavailable": "Impossibile eseguire questa operazione. Riprovare più tardi.",
   "error.bad_request": "Controllare il valore inserito e riprovare.",
   "error.bad_response": "Impossibile eseguire questa operazione. Riprovare più tardi.",

package/templates/native-go/i18n/messages/ja.json

@@ -3,6 +3,7 @@
   "app.refresh": "最新の情報に更新",
   "app.title": "動作しています",
   "error.admin_required": "申し訳ありませんが、このユーザー アカウントにはこの操作を行うための権限が与えられていません。",
+  "error.app_privilege_denied": "申し訳ありませんが、このユーザー アカウントにはこの操作を行うための権限が与えられていません。",
   "error.auth_unavailable": "この操作は実行できません。後でもう一度お試しください。",
   "error.bad_request": "入力した値を確認して、もう一度お試しください。",
   "error.bad_response": "この操作は実行できません。後でもう一度お試しください。",

package/templates/native-go/i18n/messages/ko.json

@@ -3,6 +3,7 @@
   "app.refresh": "새로 고침",
   "app.title": "정상적으로 작동합니다",
   "error.admin_required": "죄송합니다. 이 사용자 계정에는 이 작업을 수행하기에 적절한 권한이 할당되지 않았습니다.",
+  "error.app_privilege_denied": "죄송합니다. 이 사용자 계정에는 이 작업을 수행하기에 적절한 권한이 할당되지 않았습니다.",
   "error.auth_unavailable": "이 작업을 수행할 수 없습니다. 나중에 다시 시도하십시오.",
   "error.bad_request": "입력한 값을 확인한 후 다시 시도하십시오.",
   "error.bad_response": "이 작업을 수행할 수 없습니다. 나중에 다시 시도하십시오.",

package/templates/native-go/i18n/messages/zh-CN.json

@@ -3,6 +3,7 @@
   "app.refresh": "刷新",
   "app.title": "运行成功",
   "error.admin_required": "抱歉，此用户帐户权限不足，无法执行此操作。",
+  "error.app_privilege_denied": "抱歉，此用户帐户权限不足，无法执行此操作。",
   "error.auth_unavailable": "无法执行此操作。请稍后再试。",
   "error.bad_request": "请检查输入的值后重试。",
   "error.bad_response": "无法执行此操作。请稍后再试。",

package/templates/native-go/i18n/messages/zh-TW.json

@@ -3,6 +3,7 @@
   "app.refresh": "重新整理",
   "app.title": "成功運作了",
   "error.admin_required": "抱歉，此使用者帳號權限不足，無法執行此動作。",
+  "error.app_privilege_denied": "抱歉，此使用者帳號權限不足，無法執行此動作。",
   "error.auth_unavailable": "無法執行此操作。請稍後再試。",
   "error.bad_request": "請檢查輸入的值後再試一次。",
   "error.bad_response": "無法執行此操作。請稍後再試。",

package/templates/native-go/ui/app.css

@@ -33,3 +33,13 @@
 .dsmapp-facts { display: grid; grid-template-columns: max-content 1fr; gap: 4px 16px; margin: 0; }
 .dsmapp-facts dt { color: #5d6b7a; }
 .dsmapp-facts dd { margin: 0; }
+/* SDK portal panel (ctx.portal.mountPanel). */
+.dsmapp-portal-form { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; max-width: 560px; }
+.dsmapp-portal input { height: 28px; padding: 0 8px; border: 1px solid #c8d0da; border-radius: 3px; font: inherit; }
+.dsmapp-portal button {
+  height: 30px; padding: 0 12px; border: 1px solid #c8d0da; border-radius: 3px;
+  background: #fff; color: inherit; font: inherit; cursor: pointer; margin-top: 8px;
+}
+.dsmapp-portal-form button { margin-top: 0; }
+.dsmapp-portal-form button[type="submit"] { border-color: #0086e5; background: #0086e5; color: #fff; }
+.dsmapp-portal-error { color: #c0392b; }

package/templates/native-go/ui/app.js

@@ -15,6 +15,9 @@
 //                                   host-theme/language-change unsupported
 //   ctx.host.openFileManager(path) / revealFile(path) -> File Station virtual path
 //       request only; preview/details/settings return unsupported, never a grant
+//   ctx.portal               -> only with `portal:` in dsm-package.yaml;
+//                               mountPanel(element) shows the DSM Application
+//                               Portal link, or the alias form to administrators
 // Replace everything below with your own UI (plain JS, or a bundle you build
 // with Vite/Vue into this folder -- see README.md).
 (function () {
@@ -40,6 +43,7 @@
     var message = el("p", { class: "dsmapp-message", role: "status" });
     var form = el("form", { class: "dsmapp-form", hidden: "" }, [input, save]);
     var adminOnly = el("p", { class: "dsmapp-note", hidden: "", text: t("greeting.adminOnly") });
+    var portal = ctx.portal ? el("section", { class: "dsmapp-portal" }) : null;
 
     root.classList.add("dsmapp");
     root.replaceChildren(
@@ -51,6 +55,7 @@
       el("h2", { text: t("status.heading") }),
       status
     );
+    var portalPanel = portal && (root.appendChild(portal), ctx.portal.mountPanel(portal));
 
     // Errors arrive as { code }; the backend's English message is only a fallback.
     function showError(error) {
@@ -93,7 +98,12 @@
 
     ctx.reopen(refresh);
     refresh();
-    return { unmount: function () { root.replaceChildren(); } };
+    return {
+      unmount: function () {
+        if (portalPanel) portalPanel.dispose();
+        root.replaceChildren();
+      }
+    };
   }
 
   window.DsmPackageApps = window.DsmPackageApps || {};

package/templates/native-go-delegate/DELEGATE.md

@@ -8,10 +8,12 @@ A worker stores only a delegation ID and job ID, never session credentials.
 ## CLI assembly
 
 `init --with delegate` and `add delegate` apply base → jobs → delegate.
-The SDK registers `DelegateRoutes` using the trusted manifest scope and gives
-all seven methods below `authenticated` access through `sdk-permissions.json`.
-App-owned permissions remain in `permissions.json`; `app.status` is initialized
-as authenticated so ordinary users can mount their panels. The CLI binds both
+The SDK registers `DelegateRoutes` using the trusted manifest scope and lists
+all 17 delegate methods in `sdk-permissions.json`: `delegate.disable` and
+`delegate.enable` require administrators, the others `authenticated`.
+App-owned permissions remain in `permissions.json`. `init --with delegate` sets
+`app.status` to authenticated so ordinary users can mount their panels;
+`add delegate` leaves `permissions.json` unchanged. The CLI binds both
 policy files to the CGI build. SDK policy edits and overrides fail validation.
 
 `background.Job.DelegationID` is an optional field in the shared base store.
@@ -23,7 +25,7 @@ shared store before activating delegate.
 ```ts
 interface ExecutorSetup {
   status(): Promise<CapabilityStatus>
-  authorize(password: string): Promise<CapabilityStatus>
+  authorize(password: string, selectedScope?: string): Promise<CapabilityStatus>
   control(action: 'start' | 'stop' | 'purge'): Promise<CapabilityStatus>
 }
 ```
@@ -140,3 +142,122 @@ The fixtures are temporary and are removed after each run.
 These tests do not claim DSM kernel ACL, owner, reboot, real task or real executor
 validation. CLI activation and real executor/setup integration belong to the other
 P2 workstreams.
+
+## Choose the scope at install and confirm it once
+
+New `init` / `add delegate` projects default to `scope: install-selected`.
+The DSM install wizard's native `api_store` combobox dynamically lists local
+shares using the installer's administrator session (`SYNO.Core.Share list v1`).
+A checkbox offers each user's `/home` instead; choosing a share never creates it
+or grants its ACL to the package account. This wizard was measured on vt-nas
+DSM 7.4 through a session-only SSH tunnel. Other DSM versions remain unverified.
+
+Installation saves `{schema:1, scope}` in package-owned
+`var/delegate-install.json`. It is **only a pre-selection**. The existing
+administrator enable form displays it alongside the DSM password field. One
+PasswordConfirm authorizes the pinned boot/control tasks and a one-time exact
+selection task. Only the root executor writes
+`/usr/local/etc/synopkgland/<pkg>/delegations/selected-scope.record`
+(`schema`, `scope`, `generation`, root 0600). The package peer cannot call the
+internal selection operation, even with an administrator cookie. Shipped
+executor/policy pins lock the selection mode and operations; the chosen scope
+is protected runtime state, so changing it does not rewrite shipped pins.
+
+Settings uses this same form and `ctx.executor.authorize(password, scope)` to
+change the scope. There is no extra dialog or step. A new scope generation
+revokes existing grants and cancels pending saves under the publication fence.
+Changing away and back never revives old grants. Existing destination files
+remain. Selecting another directory for the same destination key replaces only
+that person's previous grant for the key. Every person must select again after
+scope changes. If the package draft differs, the UI shows both and follows the
+protected value. Existing `scope: home` and `shared:<name>` manifests retain their
+fixed-scope API and legacy TTL behavior. Dynamic selection requires the
+`until-revoked` / `files.moveFromStaging` declaration.
+
+A scope change on a running executor whose pins verify runs only the selection
+task. It never restarts the executor, so a copy in flight ends `canceled` with
+reason `scope-changed`, not `interrupted`. `authorize` waits about 20 seconds
+for the protected readback. A `blocked` reply that carries `requested: {scope,
+generation}` means the root task may still land: read `ctx.executor.status()`
+(or `delegate.status`) until `selection.scope` equals `requested.scope` with a
+`selection.generation` above `requested.generation` (applied); otherwise it was
+not applied. Submitting the same scope again is safe: the task is pinned to the
+current generation and an already selected scope is answered unchanged.
+
+## One typed destination lookup, online and offline
+
+The generated Vue template contains the complete administrator setup, confirmed
+scope, scope-limited NasPicker, personal destinations and operations, and admin
+kill switch. Use its existing facade:
+
+```ts
+import {createBackgroundSaveFacade} from './delegate/facade'
+const sdk = createBackgroundSaveFacade(ctx)
+const current = await sdk.destination('save')
+// current.selection: {scope, root, generation} | null — protected executor evidence
+// current.destination: {id, key, path, username, lifetime} | null — this caller only
+// current.status: active | missing | reselection-required | needs-scope-confirmation | disabled
+if (current.status === 'active') {
+  const ref = await sdk.exportExample({key: 'save', job_id: stableJobID})
+  // The generated My saves panel queries this reference; admission is not Saved.
+}
+```
+
+The authenticated CGI is `delegate.destination` with `{key}`; it verifies the
+fresh DSM session and username+UID, configured key, protected scope/generation
+and current grant. Neither browser storage nor the installation draft supplies
+a destination. Errors or missing protected evidence disable new selections.
+
+Go uses `service.Destination(ctx, caller, request, "save") (DestinationState,error)`.
+Capture `current.Destination.ID` in the App's own job only when status is active.
+After logout, a producer uses that ID with `service.MoveFromStaging(ctx, params)`.
+It does not use the package draft, pass a virtual destination path, or retain
+session credentials. The executor rechecks scope generation, account, grant,
+directory identity and DSM ACL before writing as the user's nonzero UID.
+
+The shipped **Save example file** button calls `delegate.example.export` with
+`{key, job_id}`. `backend/internal/delegate/example.go` is a working producer:
+it obtains this user's active destination, creates a small package-private JSON
+file (0600) under staging, and invokes `MoveFromStaging`. Repeated job IDs repeat
+the original request: they return the original operation, admit only one the
+executor does not know, and never overwrite staging. Adapt this producer for
+daemon/export jobs and keep its stable ID. An uncertain result has no automatic
+retry; only a protected committed receipt means Saved.
+
+If admission failed or its reply was lost, call `MoveFromStaging` again later
+with the same params. It queries the original first and re-sends only an
+operation the executor does not know, with the pinned source unchanged (at most
+10 possibly-delivered sends, 2 s backoff doubling to 5 min; the worker sweep
+does the same). Retry on `EXECUTOR_UNAVAILABLE`, `EXECUTOR_TIMEOUT`,
+`EXECUTOR_PROTOCOL`, `canceled`, `EXECUTOR_PAUSED`, `queue-full`,
+`STORAGE_ERROR`, `ADMISSION_PENDING`, and on the package journal codes
+`jobs_busy` (lock busy), `jobs_unavailable` (transient I/O) and `canceled` (the
+caller's deadline or cancel ended the wait). None of these admitted anything a
+retry could duplicate; while the journal is unavailable, a ref the executor
+already knows still answers its state, so a committed move stays committed.
+Terminal: executor refusals such as `APP_DENIED`, `DELEGATION_DENIED`,
+`operation-conflict`, `disabled`, plus `STAGING_CHANGED`, `ADMISSION_EXHAUSTED`,
+`spool_unsafe` and `journal_corrupt` (the package spool needs repair), and
+`operation-not-found` for an accepted operation. See the delegate guide's Admission recovery table.
+
+Cancel with the original reference (`CancelOperation`, or
+`delegate.operations.cancel` from the UI); it is idempotent, so repeat it with
+the same reference after a retryable error or a lost reply. `queued` becomes
+`canceled` at once. A copy in flight answers `copying` with code
+`CANCEL_REQUESTED`: accepted and durable, not finished. Poll `OperationStatus`
+on the same reference until `canceled` (writer stopped, part removed, nothing
+published, staging kept), `committed` (publication won; the file stays, drop only
+the app record) or `uncertain` (a publish attempt failed first; keep querying).
+The request survives executor crash, package stop/start and logout.
+Revoke, scope change and disable store their reason (`grant-revoked`,
+`scope-changed`, `integration-disabled`) the same way: a copy in flight answers
+`CANCEL_REQUESTED` with it and settles `canceled` with it across a restart. A
+copy the executor stops without a cancel ends `interrupted`/`EXECUTOR_PAUSED`
+(`interrupted`/`interrupted` after a crash), never `WRITE_FAILED`. A cancel of
+a reference not yet admitted leaves a `canceled` tombstone that a late or
+recovered admission returns instead of copying, and a producer cancel is written
+to the mirror first, so `MoveFromStaging` and the worker sweep forward it rather
+than admit. See the delegate guide's Cancellation table.
+
+
+The pinned scope-selection task also binds the protected generation observed before confirmation. The executor compares it under the publish lock and refuses stale tasks, so a retained task cannot replay an older selection after another confirmation.

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

@@ -12,12 +12,14 @@ import (
 	"strconv"
 	"syscall"
 
+	"dsmapp/internal/app"
 	"dsmapp/internal/background"
 	"dsmapp/internal/delegate"
 )
 
 // Set by `synopkgland build-spk` through -ldflags -X.
 var packageID = "dev"
+var delegateScope, delegateOperationsJSON, delegateDestinationsJSON, delegateLifetime string
 
 func main() {
 	log.SetFlags(0)
@@ -35,6 +37,11 @@ func main() {
 	log.Printf("started as uid %s", strconv.Itoa(info.UID))
 	dataDir := "/var/packages/" + packageID + "/var"
 	service := &delegate.Service{Client: delegate.Local(packageID), Store: background.NewStore(dataDir + "/background"), StagingDir: dataDir + "/executor-staging"}
+	settings, err := app.ParseDelegateConfig(app.Config{DelegateScope: delegateScope, DelegateOperationsJSON: delegateOperationsJSON, DelegateDestinationsJSON: delegateDestinationsJSON, DelegateLifetime: delegateLifetime})
+	if err != nil {
+		log.Fatal(err)
+	}
+	service.Scope, service.Operations, service.Destinations, service.Lifetime = settings.Scope, settings.Operations, settings.Destinations, settings.Lifetime
 	if err := service.Run(ctx, info); err != nil {
 		log.Fatal(err)
 	}

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

@@ -4,12 +4,22 @@ import (
 	"dsmapp/internal/api"
 	"dsmapp/internal/background"
 	"dsmapp/internal/delegate"
+	"dsmapp/internal/filestation"
 	"path/filepath"
 )
 
 // DelegateRoutes is appended by the CLI's delegate capability assembly.
 // scope comes from the trusted manifest, never an HTTP parameter.
 func DelegateRoutes(cfg Config, scope string) []api.Route {
-	service := &delegate.Service{ExecutorDigest: cfg.ExecutorDigest, PolicyDigest: cfg.PolicyDigest, Client: delegate.Local(cfg.PackageID), Store: background.NewRequestStore(filepath.Join(cfg.DataDir, "background")), Scope: scope, StagingDir: filepath.Join(cfg.DataDir, "executor-staging")}
+	service := &delegate.Service{ExecutorDigest: cfg.ExecutorDigest, PolicyDigest: cfg.PolicyDigest, Client: delegate.Local(cfg.PackageID), Store: background.NewRequestStore(filepath.Join(cfg.DataDir, "background")), Scope: scope, StagingDir: filepath.Join(cfg.DataDir, "executor-staging"), InstallDraftPath: filepath.Join(cfg.DataDir, "delegate-install.json")}
+	settings, err := ParseDelegateConfig(cfg)
+	if err == nil {
+		service.Destinations, service.Operations, service.Lifetime = settings.Destinations, settings.Operations, settings.Lifetime
+	}
+	if cfg.SessionFiles != nil {
+		service.SessionFiles = cfg.SessionFiles
+	} else {
+		service.SessionFiles = filestation.Local(cfg.DataDir)
+	}
 	return service.Routes()
 }

package/templates/native-go-delegate/backend/internal/app/delegate_routes_test.go

@@ -1,6 +1,20 @@
 package app
 
 func init() {
+	for method, params := range map[string]string{
+		"delegate.example.export":     `{"key":"save","job_id":"example-1"}`,
+		"delegate.destination":        `{"key":"save"}`,
+		"delegate.select_destination": `{"key":"save","path":"/home"}`,
+		"delegate.move_from_staging":  `{"delegation_id":"grant","job_id":"export-1","staging":"a","name":"a","size":3}`,
+		"delegate.operations.get":     `{"delegation_id":"grant","job_id":"export-1"}`,
+		"delegate.operations.list":    `{}`,
+		"delegate.operations.cancel":  `{"delegation_id":"grant","job_id":"export-1"}`,
+		"delegate.disable":            `{}`, "delegate.enable": `{}`, "delegate.audit": `{}`,
+	} {
+		sampleParams[method] = params
+		sampleOutcome[method] = "session_required"
+	}
+
 	sampleParams["delegate.status"] = `{}`
 	sampleParams["delegate.create"] = `{"job_id":"job1","ops":["files.write"],"path":"/home","ttl_seconds":60}`
 	sampleParams["delegate.list"] = `{}`