@synopackageland/cli 0.6.1 → 0.7.0

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"] = `{}`

package/templates/native-go-delegate/backend/internal/background/delegated_moves.go

@@ -0,0 +1,270 @@
+package background
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"os"
+	"strings"
+	"time"
+
+	"golang.org/x/sys/unix"
+)
+
+// StagingIdentity identifies a package-owned source for cleanup only. It is
+// never a grant, a UID selector for destination writes, or protected authority.
+type StagingIdentity struct {
+	Device, Inode, ParentDevice, ParentInode, RootDevice, RootInode uint64
+	UID                                                             uint32
+	Size, ModifiedNS                                                int64
+}
+
+type MoveBinding struct {
+	JobID        string          `json:"job_id"`
+	DelegationID string          `json:"delegation_id"`
+	Params       json.RawMessage `json:"params"`
+	Source       StagingIdentity `json:"source"`
+	Settled      bool            `json:"settled,omitempty"`
+	CleanupDone  bool            `json:"cleanup_done,omitempty"`
+	Refusal      string          `json:"refusal,omitempty"`
+	// Phase records how far admission got. Older mirrors have none and are
+	// treated as possibly sent. Attempts counts sends that may have arrived.
+	Phase       string `json:"phase,omitempty"`
+	Attempts    int    `json:"attempts,omitempty"`
+	NextAttempt int64  `json:"next_attempt,omitempty"`
+	// CancelRequested is the producer's durable cancel: it is forwarded until
+	// the executor answers, and admission is never sent again.
+	CancelRequested bool `json:"cancel_requested,omitempty"`
+}
+
+const (
+	MoveReserved = "reserved" // durable before transport; no request sent
+	MoveSent     = "sent"     // a request may have reached the executor
+	MoveAccepted = "accepted" // the executor returned the operation
+)
+
+const maxMoveMirrorBytes = 10 << 20
+
+func moveBindingName(id string) string { return "move-" + sha256hex([]byte(id)) + ".json" }
+
+func readMoveBinding(root *os.Root, id string) (MoveBinding, error) {
+	var out MoveBinding
+	f, err := root.OpenFile(moveBindingName(id), os.O_RDONLY|unix.O_NOFOLLOW, 0)
+	if err != nil {
+		return out, err
+	}
+	defer f.Close()
+	if err = checkPrivate(f); err != nil {
+		return out, err
+	}
+	data, err := io.ReadAll(io.LimitReader(f, 16385))
+	if err != nil || len(data) > 16384 || json.Unmarshal(data, &out) != nil || out.JobID != id || out.DelegationID == "" || !json.Valid(out.Params) {
+		return MoveBinding{}, ErrInvalid
+	}
+	return out, nil
+}
+
+func (s *Store) MoveBinding(ctx context.Context, id string) (MoveBinding, error) {
+	var out MoveBinding
+	err := s.withJournal(ctx, func(root *os.Root, _ *journal) (bool, error) {
+		var err error
+		out, err = readMoveBinding(root, id)
+		return false, err
+	})
+	return out, err
+}
+
+// ReserveMove fsyncs a mirror before admission. A process crash or ambiguous
+// response leaves this reference for a status query first; only an operation
+// the executor does not know is admitted again, through ClaimAdmission.
+// A short spool lock covers metadata only, not a socket call or file copy.
+func (s *Store) ReserveMove(ctx context.Context, in MoveBinding) (MoveBinding, bool, error) {
+	out := in
+	fresh := false
+	err := s.withJournal(ctx, func(root *os.Root, _ *journal) (bool, error) {
+		existing, err := readMoveBinding(root, in.JobID)
+		if err == nil {
+			if existing.DelegationID != in.DelegationID || !bytes.Equal(existing.Params, in.Params) {
+				return false, ErrKeyConflict
+			}
+			out = existing
+			return false, nil
+		}
+		if !errors.Is(err, os.ErrNotExist) {
+			return false, err
+		}
+		dir, err := root.Open(".")
+		if err != nil {
+			return false, err
+		}
+		defer dir.Close()
+		entries, err := dir.ReadDir(-1)
+		if err != nil {
+			return false, err
+		}
+		var used int64
+		for _, e := range entries {
+			if strings.HasPrefix(e.Name(), "move-") && strings.HasSuffix(e.Name(), ".json") {
+				info, err := e.Info()
+				if err != nil {
+					return false, err
+				}
+				used += info.Size()
+			}
+		}
+		// Completed/uncertain mirrors are retained for local replay prevention.
+		// The protected executor owns the authoritative operation/history quota.
+		encoded, err := json.Marshal(in)
+		if err != nil || len(encoded) > 16384 {
+			return false, ErrInvalid
+		}
+		if used+int64(len(encoded)) > maxMoveMirrorBytes {
+			return false, ErrQuota
+		}
+		if err = writeAtomic(root, moveBindingName(in.JobID), in); err != nil {
+			return false, err
+		}
+		fresh = true
+		return false, nil
+	})
+	return out, fresh, err
+}
+
+// updateMoveBinding rewrites one existing mirror under the spool lock when
+// change reports a modification.
+func (s *Store) updateMoveBinding(ctx context.Context, id string, change func(*MoveBinding) bool) error {
+	return s.withJournal(ctx, func(root *os.Root, _ *journal) (bool, error) {
+		in, err := readMoveBinding(root, id)
+		if err != nil || !change(&in) {
+			return false, err
+		}
+		return false, writeAtomic(root, moveBindingName(id), in)
+	})
+}
+
+// ClaimAdmission durably records one send before it happens. Concurrent
+// callers serialize here: a claim is refused for accepted, settled, refused
+// or exhausted mirrors, and before the backoff of the previous send ends.
+func (s *Store) ClaimAdmission(ctx context.Context, id string, now time.Time, limit int, backoff func(int) time.Duration) (MoveBinding, bool, error) {
+	var out MoveBinding
+	claimed := false
+	err := s.updateMoveBinding(ctx, id, func(in *MoveBinding) bool {
+		out = *in
+		if in.Phase == MoveAccepted || in.Settled || in.CleanupDone || in.Refusal != "" || in.CancelRequested || in.Attempts >= limit || now.UnixNano() < in.NextAttempt {
+			return false
+		}
+		in.Phase, in.Attempts = MoveSent, in.Attempts+1
+		in.NextAttempt = now.Add(backoff(in.Attempts)).UnixNano()
+		out, claimed = *in, true
+		return true
+	})
+	return out, claimed, err
+}
+
+// ReleaseAdmission returns a claim the executor proved it did not admit, so
+// the bound counts only sends that might have created an operation.
+func (s *Store) ReleaseAdmission(ctx context.Context, id string) error {
+	return s.updateMoveBinding(ctx, id, func(in *MoveBinding) bool {
+		if in.Phase != MoveSent {
+			return false
+		}
+		in.Phase, in.Attempts, in.NextAttempt = MoveReserved, in.Attempts-1, 0
+		return true
+	})
+}
+
+// RequestMoveCancel durably records a cancel of the mirror bound to the grant.
+func (s *Store) RequestMoveCancel(ctx context.Context, id, delegationID string) error {
+	return s.updateMoveBinding(ctx, id, func(in *MoveBinding) bool {
+		changed := in.DelegationID == delegationID && !in.CancelRequested
+		in.CancelRequested = in.CancelRequested || changed
+		return changed
+	})
+}
+
+func (s *Store) AcceptMove(ctx context.Context, id string) error {
+	return s.updateMoveBinding(ctx, id, func(in *MoveBinding) bool {
+		changed := in.Phase != MoveAccepted
+		in.Phase = MoveAccepted
+		return changed
+	})
+}
+
+func (s *Store) FinishMoveMirror(ctx context.Context, id string, cleaned bool, refusal string) error {
+	return s.updateMoveBinding(ctx, id, func(in *MoveBinding) bool {
+		in.CleanupDone = in.CleanupDone || cleaned
+		in.Settled = in.Settled || cleaned
+		if refusal != "" {
+			in.Refusal = refusal
+		}
+		return true
+	})
+}
+
+func (s *Store) moveBindings(ctx context.Context) ([]MoveBinding, error) {
+	out := []MoveBinding{}
+	err := s.withJournal(ctx, func(root *os.Root, _ *journal) (bool, error) {
+		dir, err := root.Open(".")
+		if err != nil {
+			return false, err
+		}
+		defer dir.Close()
+		entries, err := dir.ReadDir(-1)
+		if err != nil {
+			return false, err
+		}
+		for _, entry := range entries {
+			if !strings.HasPrefix(entry.Name(), "move-") || !strings.HasSuffix(entry.Name(), ".json") {
+				continue
+			}
+			// Decode the bounded record to recover its non-path job key; verify it
+			// again through readMoveBinding before trusting even this local mirror.
+			f, err := root.OpenFile(entry.Name(), os.O_RDONLY|unix.O_NOFOLLOW, 0)
+			if err != nil {
+				return false, err
+			}
+			err = checkPrivate(f)
+			data, readErr := io.ReadAll(io.LimitReader(f, 16385))
+			f.Close()
+			var key struct {
+				JobID string `json:"job_id"`
+			}
+			if err != nil || readErr != nil || len(data) > 16384 || json.Unmarshal(data, &key) != nil || entry.Name() != moveBindingName(key.JobID) {
+				return false, ErrInvalid
+			}
+			binding, err := readMoveBinding(root, key.JobID)
+			if err != nil {
+				return false, err
+			}
+			out = append(out, binding)
+		}
+		return false, nil
+	})
+	return out, err
+}
+
+func (s *Store) PendingMoves(ctx context.Context) ([]MoveBinding, error) {
+	bindings, err := s.moveBindings(ctx)
+	out := []MoveBinding{}
+	for _, binding := range bindings {
+		if !binding.Settled && !binding.CleanupDone && binding.Refusal == "" {
+			out = append(out, binding)
+		}
+	}
+	return out, err
+}
+
+// MoveBindings includes settled/refused history. Callers must apply fresh
+// owner authorization; package mirrors never confer destination authority.
+func (s *Store) MoveBindings(ctx context.Context) ([]MoveBinding, error) { return s.moveBindings(ctx) }
+
+// Settled mirrors remain available to explicit status calls and idempotency,
+// but terminal operations do not make the worker poll history indefinitely.
+func (s *Store) SettleMoveMirror(ctx context.Context, id string) error {
+	return s.updateMoveBinding(ctx, id, func(in *MoveBinding) bool {
+		in.Settled = true
+		return true
+	})
+}