@synopackageland/cli 0.4.0 → 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/native-go/README.md

@@ -135,9 +135,65 @@ Known limits:
 `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:
+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):
 

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/dsm-readonly-probe/main_linux.go

@@ -0,0 +1,46 @@
+// A standalone evidence-only static probe. No helper activation or mutation.
+package main
+
+import (
+	"context"
+	"dsmapp/internal/dsmprobe"
+	"encoding/json"
+	"golang.org/x/sys/unix"
+	"io"
+	"os"
+	"runtime"
+	"time"
+)
+
+func main() {
+	if len(os.Args) != 2 || os.Args[1] != "--wire-v1" {
+		os.Exit(2)
+	}
+	// Watchdog owns this bounded observation; no children or services are created.
+	go func() { time.Sleep(8 * time.Second); os.Exit(124) }()
+	runtime.LockOSThread()
+	if unix.Prctl(unix.PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0) != nil || unix.Prctl(unix.PR_SET_DUMPABLE, 0, 0, 0, 0) != nil {
+		os.Exit(3)
+	}
+	data, e := io.ReadAll(io.LimitReader(os.Stdin, dsmprobe.MaxRequestBytes+1))
+	if e != nil {
+		os.Exit(2)
+	}
+	request, e := dsmprobe.DecodeRequest(data)
+	if e != nil {
+		os.Exit(2)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 7*time.Second)
+	defer cancel()
+	out, e := dsmprobe.Collect(ctx, request)
+	if e != nil {
+		out.Status = "unsupported"
+	}
+	data, e = json.Marshal(out)
+	if e != nil || len(data) > dsmprobe.MaxResponseBytes {
+		os.Exit(3)
+	}
+	if _, e = os.Stdout.Write(append(data, '\n')); e != nil {
+		os.Exit(3)
+	}
+}

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

@@ -1,3 +1,7 @@
 module dsmapp
 
 go 1.24
+
+require github.com/godbus/dbus/v5 v5.2.2
+
+require golang.org/x/sys v0.27.0 // indirect

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

@@ -0,0 +1,4 @@
+github.com/godbus/dbus/v5 v5.2.2 h1:TUR3TgtSVDmjiXOgAAyaZbYmIeP3DPkld3jgKGV8mXQ=
+github.com/godbus/dbus/v5 v5.2.2/go.mod h1:3AAv2+hPq5rdnr5txxxRwiGjPXamgoIHgz9FPBfOp3c=
+golang.org/x/sys v0.27.0 h1:wBqf8DvsY9Y/2P8gAfPDEYNuS30J4lPHJxXSb/nJZ+s=
+golang.org/x/sys v0.27.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=

package/dist/templates/native-go/backend/internal/api/binary.go

@@ -0,0 +1,154 @@
+package api
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"regexp"
+	"strconv"
+	"sync"
+	"time"
+)
+
+const MaxBinaryReadBytes = 1 << 20
+const BinaryReadTimeout = 10 * time.Second
+
+// Control IDs are not bearer authority. The trusted adapter must revalidate
+// the original caller/session, epoch, grant revision and every chunk ticket.
+// The fixed route accepts no path, offset, range, URL, filename or MIME type.
+type BinaryReadRequest struct {
+	OperationID string `json:"operationId"`
+	Epoch       string `json:"epoch"`
+	Token       string `json:"token"`
+}
+
+// Body must implement Close concurrently with Read and unblock it on Close.
+// Close releases/cancels the helper transfer; it is not itself a Q receipt.
+type BinaryRead struct {
+	Body        io.ReadCloser
+	Bytes       uint64
+	OperationID string
+}
+type BinaryReadHandler func(context.Context, Caller, *http.Request, json.RawMessage) (BinaryRead, error)
+
+func BoundedRead(h BinaryReadHandler) Route {
+	return Route{method: "nas.files.read.binary", policy: policyUser, binary: h}
+}
+
+var binaryReference = regexp.MustCompile(`^[a-f0-9]{64}$`)
+
+func serveBoundedRead(w http.ResponseWriter, r *http.Request, c Caller, params json.RawMessage, h BinaryReadHandler) {
+	if r.Context().Err() != nil {
+		writeError(w, &Error{"canceled", "read canceled"})
+		return
+	}
+	if r.Header.Get("Range") != "" {
+		writeError(w, BadRequest("ranges are unsupported"))
+		return
+	}
+	in, ok := decodeBinaryReadControl(params)
+	if !ok {
+		writeError(w, BadRequest("invalid binary read control"))
+		return
+	}
+	ctx, cancel := context.WithTimeout(r.Context(), BinaryReadTimeout)
+	defer cancel()
+	result, err := h(ctx, c, r, params)
+	if err != nil {
+		if result.Body != nil {
+			result.Body.Close()
+		}
+		writeError(w, asError(err))
+		return
+	}
+	if result.Body == nil {
+		writeError(w, internalError)
+		return
+	}
+	var once sync.Once
+	var closeErr error
+	closeBody := func() { once.Do(func() { closeErr = result.Body.Close() }) }
+	defer closeBody()
+	if result.Bytes > MaxBinaryReadBytes || result.OperationID != in.OperationID {
+		writeError(w, BadRequest("invalid bounded read result"))
+		return
+	}
+	stop := make(chan struct{})
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		select {
+		case <-ctx.Done():
+			closeBody()
+		case <-stop:
+		}
+	}()
+	// Materialize only the bounded response so short/error/overlong transfers
+	// cannot become successful binary responses. Helper relay still leases at
+	// most one 64KiB chunk. Long CGI streaming remains disabled pending DSM proof.
+	body, readErr := io.ReadAll(io.LimitReader(result.Body, int64(result.Bytes)+1))
+	closeBody()
+	close(stop)
+	<-done
+	if ctx.Err() != nil {
+		writeError(w, &Error{"canceled", "read expired or canceled"})
+		return
+	}
+	if readErr != nil || closeErr != nil || uint64(len(body)) != result.Bytes {
+		writeError(w, &Error{"read_failed", "binary read failed"})
+		return
+	}
+	headers := w.Header()
+	headers.Set("Content-Type", "application/octet-stream")
+	headers.Set("Content-Length", strconv.FormatUint(result.Bytes, 10))
+	headers.Set("Cache-Control", "no-store")
+	headers.Set("X-Content-Type-Options", "nosniff")
+	w.WriteHeader(http.StatusOK)
+	// Go CGI may buffer or block stdout. All helper resources have already been
+	// released; there is no long-stream readiness claim from this bounded write.
+	_, _ = w.Write(body)
+}
+
+// Fixed shape with duplicate-key rejection, so two parsers cannot bind a token
+// to different operations. Controls never grow the existing ctx.call envelope.
+func decodeBinaryReadControl(raw json.RawMessage) (BinaryReadRequest, bool) {
+	var in BinaryReadRequest
+	if len(raw) > 16*1024 {
+		return in, false
+	}
+	d := json.NewDecoder(bytes.NewReader(raw))
+	first, e := d.Token()
+	if e != nil || first != json.Delim('{') {
+		return in, false
+	}
+	seen := map[string]bool{}
+	for d.More() {
+		token, e := d.Token()
+		key, ok := token.(string)
+		if e != nil || !ok || seen[key] {
+			return in, false
+		}
+		seen[key] = true
+		var value string
+		if d.Decode(&value) != nil {
+			return in, false
+		}
+		switch key {
+		case "operationId":
+			in.OperationID = value
+		case "epoch":
+			in.Epoch = value
+		case "token":
+			in.Token = value
+		default:
+			return in, false
+		}
+	}
+	end, e := d.Token()
+	if e != nil || end != json.Delim('}') || d.Decode(new(any)) != io.EOF {
+		return in, false
+	}
+	return in, binaryReference.MatchString(in.OperationID) && binaryReference.MatchString(in.Epoch) && binaryReference.MatchString(in.Token)
+}

package/dist/templates/native-go/backend/internal/api/binary_test.go

@@ -0,0 +1,165 @@
+package api
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/cgi"
+	"net/http/httptest"
+	"os"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+type binarySource struct {
+	io.Reader
+	closed bool
+}
+
+func (s *binarySource) Close() error { s.closed = true; return nil }
+func TestBoundedReadBinaryGuardAndBody(t *testing.T) {
+	for _, kind := range []string{"valid", "anonymous", "cross-origin", "oversize", "short", "nil", "cancel"} {
+		t.Run(kind, func(t *testing.T) {
+			auth := &fakeAuth{user: "normal1"}
+			if kind == "anonymous" {
+				auth.err = ErrNoSession
+			}
+			src := &binarySource{Reader: bytes.NewReader([]byte{0, 1, 255, 10})}
+			called := false
+			srv, e := NewServer(auth, BoundedRead(func(ctx context.Context, c Caller, r *http.Request, params json.RawMessage) (BinaryRead, error) {
+				called = true
+				if !c.Authenticated() || c.User() != "normal1" {
+					t.Fatal(c)
+				}
+				n := uint64(4)
+				if kind == "oversize" {
+					n = MaxBinaryReadBytes + 1
+				}
+				if kind == "short" {
+					n = 5
+				}
+				if kind == "nil" {
+					return BinaryRead{}, nil
+				}
+				return BinaryRead{Body: src, Bytes: n, OperationID: strings.Repeat("a", 64)}, nil
+			}))
+			if e != nil {
+				t.Fatal(e)
+			}
+			r := httptest.NewRequest("POST", "http://nas.local/cgi/api.cgi", strings.NewReader(`{"method":"nas.files.read.binary","params":{"operationId":"`+strings.Repeat("a", 64)+`","epoch":"`+strings.Repeat("b", 64)+`","token":"`+strings.Repeat("c", 64)+`"}}`))
+			r.Header.Set("Content-Type", "application/json")
+			if kind == "cross-origin" {
+				r.Header.Set("Origin", "http://evil.local")
+			}
+			if kind == "cancel" {
+				ctx, cancel := context.WithCancel(r.Context())
+				cancel()
+				r = r.WithContext(ctx)
+			}
+			w := httptest.NewRecorder()
+			srv.ServeHTTP(w, r)
+			if kind == "valid" {
+				if w.Header().Get("Content-Type") != "application/octet-stream" || !bytes.Equal(w.Body.Bytes(), []byte{0, 1, 255, 10}) || w.Header().Get("Content-Length") != "4" || !src.closed {
+					t.Fatal(w.Body.String(), w.Header())
+				}
+			} else {
+				if w.Header().Get("Content-Type") != "application/json" {
+					t.Fatal("invalid binary escaped")
+				}
+				if (kind == "anonymous" || kind == "cross-origin" || kind == "cancel") && called {
+					t.Fatal("handler called before guards")
+				}
+				if called && kind != "nil" && !src.closed {
+					t.Fatal("source not closed")
+				}
+			}
+		})
+	}
+}
+
+type blockedBinarySource struct {
+	done chan struct{}
+	once sync.Once
+}
+
+func (s *blockedBinarySource) Read([]byte) (int, error) { <-s.done; return 0, io.ErrClosedPipe }
+func (s *blockedBinarySource) Close() error             { s.once.Do(func() { close(s.done) }); return nil }
+func TestBoundedBinaryDisconnectCancelsSource(t *testing.T) {
+	src := &blockedBinarySource{done: make(chan struct{})}
+	started := make(chan struct{})
+	srv, e := NewServer(&fakeAuth{user: "normal1"}, BoundedRead(func(context.Context, Caller, *http.Request, json.RawMessage) (BinaryRead, error) {
+		close(started)
+		return BinaryRead{Body: src, Bytes: 1, OperationID: strings.Repeat("a", 64)}, nil
+	}))
+	if e != nil {
+		t.Fatal(e)
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	r := httptest.NewRequest("POST", "http://nas.local/cgi/api.cgi", strings.NewReader(`{"method":"nas.files.read.binary","params":{"operationId":"`+strings.Repeat("a", 64)+`","epoch":"`+strings.Repeat("b", 64)+`","token":"`+strings.Repeat("c", 64)+`"}}`)).WithContext(ctx)
+	r.Header.Set("Content-Type", "application/json")
+	done := make(chan struct{})
+	go func() { defer close(done); srv.ServeHTTP(httptest.NewRecorder(), r) }()
+	<-started
+	cancel()
+	select {
+	case <-done:
+	case <-time.After(time.Second):
+		t.Fatal("disconnect did not release bounded source")
+	}
+}
+func TestBoundedBinaryRejectsCallerPathsAndTransferSubstitution(t *testing.T) {
+	calls := 0
+	srv, e := NewServer(&fakeAuth{user: "normal1"}, BoundedRead(func(context.Context, Caller, *http.Request, json.RawMessage) (BinaryRead, error) {
+		calls++
+		return BinaryRead{}, nil
+	}))
+	if e != nil {
+		t.Fatal(e)
+	}
+	for _, params := range []string{`{}`, `{"operationId":"x"}`, `{"operationId":"` + strings.Repeat("a", 64) + `","epoch":"` + strings.Repeat("b", 64) + `","token":"` + strings.Repeat("c", 64) + `","path":"/secret"}`} {
+		_, env := post(t, srv, `{"method":"nas.files.read.binary","params":`+params+`}`)
+		if env.Success || env.Error == nil || env.Error.Code != "bad_request" {
+			t.Fatal(env)
+		}
+	}
+	if calls != 0 {
+		t.Fatal("invalid control reached adapter")
+	}
+}
+
+func TestBoundedBinaryRealCGIWire(t *testing.T) {
+	requestBody := `{"method":"nas.files.read.binary","params":{"operationId":"` + strings.Repeat("a", 64) + `","epoch":"` + strings.Repeat("b", 64) + `","token":"` + strings.Repeat("c", 64) + `"}}`
+	h := &cgi.Handler{Path: os.Args[0], Args: []string{"-test.run=TestBoundedBinaryCGIProcessFixture"}, Env: []string{"S6_CGI_FIXTURE=1"}}
+	r := httptest.NewRequest("POST", "http://nas.local/cgi/api.cgi", strings.NewReader(requestBody))
+	r.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+	h.ServeHTTP(w, r)
+	if w.Code != http.StatusOK || w.Header().Get("Content-Type") != "application/octet-stream" || w.Header().Get("Content-Length") != "1048576" || !bytes.Equal(w.Body.Bytes(), bytes.Repeat([]byte{0, 255, 10, 13}, MaxBinaryReadBytes/4)) {
+		t.Fatal(w.Code, w.Header(), w.Body.Len())
+	}
+}
+func TestBoundedBinaryCGIProcessFixture(t *testing.T) {
+	if os.Getenv("S6_CGI_FIXTURE") != "1" {
+		t.Skip("spawned CGI-only process")
+	}
+	srv, e := NewServer(&fakeAuth{user: "normal1"}, BoundedRead(func(context.Context, Caller, *http.Request, json.RawMessage) (BinaryRead, error) {
+		return BinaryRead{Body: io.NopCloser(bytes.NewReader(bytes.Repeat([]byte{0, 255, 10, 13}, MaxBinaryReadBytes/4))), Bytes: MaxBinaryReadBytes, OperationID: strings.Repeat("a", 64)}, nil
+	}))
+	if e != nil {
+		os.Exit(1)
+	}
+	if cgi.Serve(srv) != nil {
+		os.Exit(1)
+	}
+	os.Exit(0)
+}
+func TestBinaryControlRejectsDuplicates(t *testing.T) {
+	raw := `{"operationId":"` + strings.Repeat("a", 64) + `","epoch":"` + strings.Repeat("b", 64) + `","token":"` + strings.Repeat("c", 64) + `","token":"` + strings.Repeat("d", 64) + `"}`
+	if _, ok := decodeBinaryReadControl(json.RawMessage(raw)); ok {
+		t.Fatal("duplicate transfer token")
+	}
+}

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

@@ -32,17 +32,24 @@ type Route struct {
 	method  string
 	policy  policy
 	handler Handler
+	binary  BinaryReadHandler
 }
 
 // User declares an operation any signed-in DSM user may call.
-func User(method string, h Handler) Route { return Route{method, policyUser, h} }
+func User(method string, h Handler) Route {
+	return Route{method: method, policy: policyUser, handler: 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} }
+func Admin(method string, h Handler) Route {
+	return Route{method: method, policy: policyAdmin, handler: 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} }
+func Public(method string, h Handler) Route {
+	return Route{method: method, policy: policyPublic, handler: h}
+}
 
 // Identity is what an Authenticator established about the requester.
 type Identity struct {
@@ -73,7 +80,10 @@ func buildRegistry(routes []Route) (map[string]Route, error) {
 		if !methodName.MatchString(r.method) {
 			return nil, fmt.Errorf("route %q: method must look like \"area.action\" (lowercase)", r.method)
 		}
-		if r.handler == nil {
+		if r.binary != nil && (r.method != "nas.files.read.binary" || r.policy != policyUser || r.handler != nil) {
+			return nil, errors.New("binary read must use the fixed authenticated route")
+		}
+		if r.handler == nil && r.binary == nil {
 			return nil, fmt.Errorf("route %q has no handler", r.method)
 		}
 		if _, dup := registry[r.method]; dup {

package/dist/templates/native-go/backend/internal/api/server.go

@@ -67,6 +67,10 @@ func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 		writeError(w, apiErr)
 		return
 	}
+	if route.binary != nil {
+		serveBoundedRead(w, r, caller, req.Params, route.binary)
+		return
+	}
 	data, err := route.handler(r.Context(), caller, req.Params)
 	if err != nil {
 		writeError(w, asError(err))