@synopackageland/cli 0.5.3 → 0.6.0

package/templates/native-go/backend/internal/filestation/client.go

@@ -43,10 +43,8 @@ func wireError(code int) error {
 	switch code {
 	case 106, 107, 119:
 		return fail("session_required")
-	case 105, 403, 407:
+	case 105, 403, 407, 408:
 		return fail("denied")
-	case 408:
-		return fail("not_found")
 	case 414, 1805:
 		return fail("conflict")
 	case 400:
@@ -171,7 +169,27 @@ type Page struct {
 	Offset int     `json:"offset"`
 }
 
-func (c *Client) page(ctx context.Context, r *http.Request, p string, offset int) (Page, error) {
+type ListOptions struct {
+	Offset        int    `json:"offset"`
+	Limit         int    `json:"limit"`
+	SortBy        string `json:"sortBy"`
+	SortDirection string `json:"sortDirection"`
+}
+
+func (c *Client) page(ctx context.Context, r *http.Request, p string, opts ListOptions) (Page, error) {
+	offset := opts.Offset
+	if opts.Limit == 0 {
+		opts.Limit = PageSize
+	}
+	if opts.SortBy == "" {
+		opts.SortBy = "name"
+	}
+	if opts.SortDirection == "" {
+		opts.SortDirection = "ASC"
+	}
+	if opts.Limit < 1 || opts.Limit > PageSize || (opts.SortBy != "name" && opts.SortBy != "size" && opts.SortBy != "type" && opts.SortBy != "mtime") || (opts.SortDirection != "ASC" && opts.SortDirection != "DESC") {
+		return Page{}, fail("invalid-request")
+	}
 	var d Page
 	if offset < 0 || offset > 1000000 || (p != "" && !validPath(p)) {
 		return d, fail("invalid-request")
@@ -182,22 +200,30 @@ func (c *Client) page(ctx context.Context, r *http.Request, p string, offset int
 	}
 	v := fields("SYNO.FileStation.List", method, "2")
 	v.Set("offset", strconv.Itoa(offset))
-	v.Set("limit", strconv.Itoa(PageSize))
+	v.Set("limit", strconv.Itoa(opts.Limit))
+	v.Set("sort_by", opts.SortBy)
+	v.Set("sort_direction", opts.SortDirection)
 	v.Set("additional", `["size"]`)
 	if p != "" {
 		v.Set("folder_path", p)
 	}
 	e := c.call(ctx, r, v, &d)
-	if len(d.Files) > PageSize || len(d.Shares) > PageSize {
+	if d.Files == nil {
+		d.Files = []Entry{}
+	}
+	if len(d.Files) > opts.Limit || len(d.Shares) > opts.Limit {
 		return Page{}, fail("unavailable")
 	}
 	return d, e
 }
 func (c *Client) Discover(ctx context.Context, r *http.Request, offset int) (Page, error) {
-	return c.page(ctx, r, "", offset)
+	return c.page(ctx, r, "", ListOptions{Offset: offset})
 }
-func (c *Client) List(ctx context.Context, r *http.Request, p string, offset int) (Page, error) {
-	return c.page(ctx, r, p, offset)
+func (c *Client) List(ctx context.Context, r *http.Request, p string, opts ListOptions) (Page, error) {
+	if !validPath(p) {
+		return Page{}, fail("invalid-request")
+	}
+	return c.page(ctx, r, p, opts)
 }
 func (c *Client) Stat(ctx context.Context, r *http.Request, p string) (Entry, error) {
 	var d Page
@@ -215,36 +241,60 @@ func (c *Client) Stat(ctx context.Context, r *http.Request, p string) (Entry, er
 	}
 	return d.Files[0], nil
 }
-func (c *Client) Read(ctx context.Context, r *http.Request, p string) ([]byte, error) {
+
+// Download owns an open response body; the caller must close it. No file bytes
+// are buffered and JSON error envelopes never become successful content.
+type Download struct {
+	Body               io.ReadCloser
+	ContentType        string
+	ContentDisposition string
+	ContentLength      int64
+}
+
+func (c *Client) DownloadStream(ctx context.Context, r *http.Request, p string) (Download, error) {
 	if !validPath(p) {
-		return nil, fail("invalid-request")
+		return Download{}, fail("invalid-request")
 	}
 	v := fields("SYNO.FileStation.Download", "download", "2")
 	v.Set("path", array(p))
 	v.Set("mode", "download")
-	resp, e := c.send(ctx, r, strings.NewReader(v.Encode()), "")
+	if c == nil {
+		return Download{}, fail("unavailable")
+	}
+	transfer := *c
+	httpClient := *c.http
+	httpClient.Timeout = 20 * time.Minute
+	transfer.http = &httpClient
+	resp, e := transfer.send(ctx, r, strings.NewReader(v.Encode()), "")
 	if e != nil {
-		return nil, e
+		return Download{}, e
 	}
-	// DSM error envelopes must never be returned as successful file content.
-	// A real JSON file remains downloadable when attachment disposition is set.
 	disposition, _, _ := mime.ParseMediaType(resp.Header.Get("Content-Disposition"))
 	if disposition != "attachment" {
 		e = decode(resp, nil)
 		if e == nil {
 			e = fail("unavailable")
 		}
+		return Download{}, e
+	}
+	return Download{Body: resp.Body, ContentType: resp.Header.Get("Content-Type"), ContentDisposition: resp.Header.Get("Content-Disposition"), ContentLength: resp.ContentLength}, nil
+}
+
+// Read is the bounded package-private job import, using the same stream.
+func (c *Client) Read(ctx context.Context, r *http.Request, p string) ([]byte, error) {
+	stream, e := c.DownloadStream(ctx, r, p)
+	if e != nil {
 		return nil, e
 	}
-	defer resp.Body.Close()
-	b, e := io.ReadAll(io.LimitReader(resp.Body, MaxBytes+1))
+	defer stream.Body.Close()
+	b, e := io.ReadAll(io.LimitReader(stream.Body, MaxBytes+1))
 	if e != nil {
 		return nil, fail("read_failed")
 	}
 	if len(b) > MaxBytes {
 		return nil, fail("limit-exceeded")
 	}
-	if resp.ContentLength >= 0 && resp.ContentLength != int64(len(b)) {
+	if stream.ContentLength >= 0 && stream.ContentLength != int64(len(b)) {
 		return nil, fail("read_failed")
 	}
 	return bytes.Clone(b), nil

package/templates/native-go/backend/internal/filestation/client_test.go

@@ -67,7 +67,7 @@ func TestReadOperationsUseOnlyCurrentSession(t *testing.T) {
 	if _, err := c.Discover(context.Background(), r, 0); err != nil {
 		t.Fatal(err)
 	}
-	if _, err := c.List(context.Background(), r, "/home", 0); err != nil {
+	if _, err := c.List(context.Background(), r, "/home", ListOptions{}); err != nil {
 		t.Fatal(err)
 	}
 	if _, err := c.Stat(context.Background(), r, "/home/a"); err != nil {
@@ -85,14 +85,14 @@ func TestRefusalAndBoundedErrors(t *testing.T) {
 	for _, tt := range []struct{ body, want string }{
 		{`{"success":false,"error":{"code":119,"secret":"test-session"}}`, "session_required"},
 		{`{"success":false,"error":{"code":407}}`, "denied"},
-		{`{"success":false,"error":{"code":408}}`, "not_found"},
+		{`{"success":false,"error":{"code":408}}`, "denied"},
 		{`{"success":false,"error":{"code":1805}}`, "conflict"},
 		{`{"success":false,"error":{"code":9999}}`, "unavailable"},
 		{`{"data":{}}`, "unavailable"}, {`not json`, "unavailable"},
 	} {
 		t.Run(tt.want+tt.body, func(t *testing.T) {
 			c := fakeClient(t, func(w http.ResponseWriter, r *http.Request) { fmt.Fprint(w, tt.body) })
-			_, err := c.List(context.Background(), sessionRequest(), "/home", 0)
+			_, err := c.List(context.Background(), sessionRequest(), "/home", ListOptions{})
 			if err == nil || !strings.Contains(err.Error(), tt.want) || strings.Contains(err.Error(), "test-session") {
 				t.Fatal(err)
 			}
@@ -110,10 +110,10 @@ func TestNoSessionRedirectOrRemoteDestination(t *testing.T) {
 		calls++
 		http.Redirect(w, r, "http://127.0.0.1:1/leak", 302)
 	})
-	if _, err := c.List(context.Background(), httptest.NewRequest("POST", "/", nil), "/home", 0); err == nil || calls != 0 {
+	if _, err := c.List(context.Background(), httptest.NewRequest("POST", "/", nil), "/home", ListOptions{}); err == nil || calls != 0 {
 		t.Fatal("missing session sent")
 	}
-	if _, err := c.List(context.Background(), sessionRequest(), "/home", 0); err == nil || calls != 1 {
+	if _, err := c.List(context.Background(), sessionRequest(), "/home", ListOptions{}); err == nil || calls != 1 {
 		t.Fatal("redirect accepted")
 	}
 }
@@ -144,12 +144,12 @@ func TestBoundariesCancellationAndIdentityMismatch(t *testing.T) {
 	}
 	ctx, cancel := context.WithCancel(context.Background())
 	cancel()
-	if _, e := c.List(ctx, sessionRequest(), "/home", 0); e == nil {
+	if _, e := c.List(ctx, sessionRequest(), "/home", ListOptions{}); e == nil {
 		t.Fatal("canceled request succeeded")
 	}
 	r := sessionRequest()
 	r.AddCookie(&http.Cookie{Name: "id", Value: "other"})
-	if _, e := c.List(context.Background(), r, "/home", 0); e == nil {
+	if _, e := c.List(context.Background(), r, "/home", ListOptions{}); e == nil {
 		t.Fatal("ambiguous session accepted")
 	}
 }

package/templates/native-go/backend/internal/filestation/doc.go

@@ -1,4 +1,4 @@
 // Package filestation implements interactive NAS operations using the current
 // DSM user's session. It never opens NAS data paths or retains credentials.
-// Folder selections are not background grants or filesystem confinement.
+// Every typed operation uses a request-scoped session; DSM alone decides access.
 package filestation

package/templates/native-go/backend/internal/filestation/http.go

@@ -0,0 +1,70 @@
+package filestation
+
+import (
+	"context"
+	"dsmapp/internal/api"
+	"io"
+	"log"
+	"mime"
+	"net/http"
+	"path"
+	"strconv"
+)
+
+// Raw upload bodies are passed through as readers, with no multipart buffering.
+func (s *Service) uploadHTTP(ctx context.Context, c api.Caller, w http.ResponseWriter, r *http.Request) error {
+	if r.Method != http.MethodPost {
+		return &api.Error{Code: "method_not_allowed", Message: "use POST"}
+	}
+	media, _, err := mime.ParseMediaType(r.Header.Get("Content-Type"))
+	if err != nil || media != "application/octet-stream" {
+		return fail("invalid-request")
+	}
+	if r.ContentLength < 0 || r.ContentLength > MaxUploadBytes {
+		return fail("upload_size_required")
+	}
+	q := r.URL.Query()
+	if !validPath(q.Get("parent")) || !validName(q.Get("name")) {
+		return fail("invalid-request")
+	}
+	if err := s.Upload(ctx, c, r, q.Get("parent"), q.Get("name"), http.MaxBytesReader(w, r.Body, MaxUploadBytes), r.ContentLength); err != nil {
+		return err
+	}
+	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set("Cache-Control", "no-store")
+	w.Header().Set("X-Content-Type-Options", "nosniff")
+	payload := `{"success":true,"data":{"uploaded":true}}`
+	w.Header().Set("Content-Length", strconv.Itoa(len(payload)))
+	_, err = io.WriteString(w, payload)
+	return err
+}
+func (s *Service) downloadHTTP(ctx context.Context, c api.Caller, w http.ResponseWriter, r *http.Request) error {
+	if r.Method == http.MethodPost {
+		media, _, err := mime.ParseMediaType(r.Header.Get("Content-Type"))
+		if err != nil || media != "application/x-www-form-urlencoded" {
+			return fail("invalid-request")
+		}
+	} else if r.Method != http.MethodGet {
+		return &api.Error{Code: "method_not_allowed", Message: "use GET or POST"}
+	}
+	target := r.URL.Query().Get("path")
+	stream, err := s.Download(ctx, c, r, target)
+	if err != nil {
+		return err
+	}
+	defer stream.Body.Close()
+	h := w.Header()
+	h.Set("Content-Type", "application/octet-stream")
+	h.Set("Content-Disposition", mime.FormatMediaType("attachment", map[string]string{"filename": path.Base(target)}))
+	h.Set("Cache-Control", "no-store")
+	h.Set("X-Content-Type-Options", "nosniff")
+	if stream.ContentLength >= 0 {
+		h.Set("Content-Length", strconv.FormatInt(stream.ContentLength, 10))
+	}
+	w.WriteHeader(http.StatusOK)
+	// Once headers are sent a failed transfer must remain truncated, never receive a JSON trailer.
+	if _, err := io.Copy(w, stream.Body); err != nil {
+		log.Print("File Station download interrupted")
+	}
+	return nil
+}

package/templates/native-go/backend/internal/filestation/http_test.go

@@ -0,0 +1,188 @@
+package filestation
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"mime"
+	"net/http"
+	"net/http/httptest"
+	"runtime"
+	"strings"
+	"testing"
+
+	"dsmapp/internal/api"
+)
+
+type transferClient struct {
+	DSMClient
+	read          int64
+	maxChunk      int
+	verified      string
+	downloadToken string
+}
+
+func (c *transferClient) Verify(_ context.Context, r *http.Request, user string) error {
+	c.verified = user
+	if _, err := r.Cookie("id"); err != nil {
+		return fail("dsm_session_required")
+	}
+	return nil
+}
+func (c *transferClient) UploadStream(_ context.Context, r *http.Request, parent, name string, source io.Reader, size int64) error {
+	if parent != "/home" || name != "large.bin" {
+		return fail("invalid-request")
+	}
+	buf := make([]byte, 32<<10)
+	for {
+		n, err := source.Read(buf)
+		if n > c.maxChunk {
+			c.maxChunk = n
+		}
+		c.read += int64(n)
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			return err
+		}
+	}
+	if c.read != size {
+		return fail("invalid-request")
+	}
+	return nil
+}
+func (c *transferClient) DownloadStream(_ context.Context, r *http.Request, _ string) (Download, error) {
+	c.downloadToken = r.Header.Get("X-SYNO-TOKEN")
+	return Download{Body: io.NopCloser(bytes.NewBufferString("contents")), ContentLength: 8, ContentType: "text/plain"}, nil
+}
+
+type largeReader struct{ remaining int64 }
+
+func (r *largeReader) Read(p []byte) (int, error) {
+	if r.remaining == 0 {
+		return 0, io.EOF
+	}
+	n := int64(len(p))
+	if n > r.remaining {
+		n = r.remaining
+	}
+	clear(p[:n])
+	r.remaining -= n
+	return int(n), nil
+}
+func transferRequest(method, url string, body io.Reader) *http.Request {
+	r := httptest.NewRequest(method, url, body)
+	r.AddCookie(&http.Cookie{Name: "id", Value: "user-session"})
+	r.Header.Set("X-SYNO-TOKEN", "token")
+	r.Header.Set("Origin", "http://example.com")
+	return r
+}
+func transferServer(t *testing.T, c *transferClient) *api.Server {
+	t.Helper()
+	s, err := api.NewServerWithPermissions(testAuth{"normal1"}, []byte(`{"schema":1,"default":"administrators","methods":{}}`), NewService(c).Routes()...)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return s
+}
+func TestBrowserUploadStreams64MiB(t *testing.T) {
+	c := &transferClient{}
+	s := transferServer(t, c)
+	r := transferRequest("POST", "http://example.com/api.cgi?method=nas.files.upload&parent=/home&name=large.bin", &largeReader{64 << 20})
+	r.ContentLength = 64 << 20
+	r.Header.Set("Content-Type", "application/octet-stream")
+	w := httptest.NewRecorder()
+	var before, after runtime.MemStats
+	runtime.ReadMemStats(&before)
+	s.ServeHTTP(w, r)
+	runtime.ReadMemStats(&after)
+	if allocated := after.TotalAlloc - before.TotalAlloc; allocated > 8<<20 {
+		t.Fatalf("64 MiB upload allocated %d bytes (limit 8 MiB)", allocated)
+	}
+	if c.read != 64<<20 || c.maxChunk > 32<<10 || c.verified != "normal1" {
+		t.Fatalf("not streamed: %+v %s", c, w.Body.String())
+	}
+	if !bytes.Contains(w.Body.Bytes(), []byte(`"success":true`)) {
+		t.Fatal(w.Body.String())
+	}
+}
+func TestBrowserDownloadDispositionAndCentralGuards(t *testing.T) {
+	for _, tc := range []struct{ name, origin, user, code string }{{"normal", "http://example.com", "normal1", ""}, {"anonymous", "http://example.com", "", "session_required"}, {"csrf", "http://evil", "normal1", "cross_origin"}} {
+		t.Run(tc.name, func(t *testing.T) {
+			c := &transferClient{}
+			s, err := api.NewServerWithPermissions(testAuth{tc.user}, []byte(`{"schema":1,"default":"administrators","methods":{}}`), NewService(c).Routes()...)
+			if err != nil {
+				t.Fatal(err)
+			}
+			r := transferRequest("GET", "http://example.com/api.cgi?method=nas.files.download&path=/home/%E5%A0%B1%E5%91%8A.txt", nil)
+			r.Header.Set("Origin", tc.origin)
+			w := httptest.NewRecorder()
+			s.ServeHTTP(w, r)
+			if tc.code != "" {
+				if !bytes.Contains(w.Body.Bytes(), []byte(tc.code)) {
+					t.Fatal(w.Body.String())
+				}
+				return
+			}
+			_, p, err := mime.ParseMediaType(w.Header().Get("Content-Disposition"))
+			if err != nil || p["filename"] != "\u5831\u544a.txt" || w.Body.String() != "contents" || w.Header().Get("Content-Length") != "8" {
+				t.Fatalf("bad download: %v %v %v", p, w.Header(), w.Body.String())
+			}
+		})
+	}
+}
+func TestBrowserUploadLimits(t *testing.T) {
+	for _, size := range []int64{-1, MaxUploadBytes + 1} {
+		c := &transferClient{}
+		r := transferRequest("POST", "http://example.com/api.cgi?method=nas.files.upload&parent=/home&name=large.bin", &largeReader{1})
+		r.ContentLength = size
+		r.Header.Set("Content-Type", "application/octet-stream")
+		w := httptest.NewRecorder()
+		transferServer(t, c).ServeHTTP(w, r)
+		if c.read != 0 {
+			t.Fatal("read rejected payload")
+		}
+		var out map[string]any
+		if json.Unmarshal(w.Body.Bytes(), &out) != nil || out["success"] != false {
+			t.Fatal(w.Body.String())
+		}
+	}
+}
+
+func TestBrowserDownloadForwardsTokenFromPOSTBodyNotURL(t *testing.T) {
+	c := &transferClient{}
+	r := transferRequest("POST", "http://example.com/api.cgi?method=nas.files.download&path=/home/a.txt", strings.NewReader("SynoToken=caller-token"))
+	r.Header.Del("X-SYNO-TOKEN")
+	r.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	w := httptest.NewRecorder()
+	transferServer(t, c).ServeHTTP(w, r)
+	if w.Body.String() != "contents" || c.downloadToken != "caller-token" {
+		t.Fatalf("POST transfer: %s token=%s", w.Body.String(), c.downloadToken)
+	}
+}
+
+type transferTokenAuth struct{}
+
+func (transferTokenAuth) Authenticate(r *http.Request) (api.Identity, error) {
+	if r.Header.Get("X-SYNO-TOKEN") != "caller-token" {
+		return api.Identity{}, api.ErrNoSession
+	}
+	return api.Identity{User: "normal1"}, nil
+}
+func TestPOSTDownloadTokenReachesCentralAuthentication(t *testing.T) {
+	c := &transferClient{}
+	s, err := api.NewServerWithPermissions(transferTokenAuth{}, []byte(`{"schema":1,"default":"administrators","methods":{}}`), NewService(c).Routes()...)
+	if err != nil {
+		t.Fatal(err)
+	}
+	r := transferRequest("POST", "http://example.com/api.cgi?method=nas.files.download&path=/home/a.txt", strings.NewReader("SynoToken=caller-token"))
+	r.Header.Del("X-SYNO-TOKEN")
+	r.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	w := httptest.NewRecorder()
+	s.ServeHTTP(w, r)
+	if w.Body.String() != "contents" {
+		t.Fatal(w.Body.String())
+	}
+}

package/templates/native-go/backend/internal/filestation/operations_test.go

@@ -0,0 +1,206 @@
+package filestation
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+)
+
+func TestTypedOperationsAlwaysUseEachCallersSession(t *testing.T) {
+	calls := 0
+	client := fakeClient(t, func(w http.ResponseWriter, r *http.Request) {
+		calls++
+		cookie, err := r.Cookie("id")
+		if err != nil || (cookie.Value != "alice-session" && cookie.Value != "bob-session") || r.Header.Get("Cookie") != "id="+cookie.Value || r.Header.Get("Authorization") != "" {
+			t.Error("caller session was replaced or extra credentials forwarded")
+			return
+		}
+		if r.Header.Get("X-SYNO-TOKEN") != "test-token" {
+			t.Error("missing caller token")
+		}
+		if strings.HasPrefix(r.Header.Get("Content-Type"), "multipart/") {
+			if err := r.ParseMultipartForm(1024); err != nil {
+				t.Error(err)
+				return
+			}
+			defer r.MultipartForm.RemoveAll()
+		} else {
+			r.ParseForm()
+		}
+		if r.Form.Get("_sid") != "" {
+			t.Error("unexpected SID")
+		}
+		method := r.Form.Get("method")
+		switch method {
+		case "get":
+			fmt.Fprintf(w, `{"success":true,"data":{"username":%q}}`, strings.TrimSuffix(cookie.Value, "-session"))
+		case "list_share":
+			fmt.Fprint(w, `{"success":true,"data":{"shares":[{"path":"/anything","name":"anything","isdir":true}],"total":1}}`)
+		case "list":
+			if r.Form.Get("offset") != "100" || r.Form.Get("limit") != "25" || r.Form.Get("sort_by") != "size" || r.Form.Get("sort_direction") != "DESC" {
+				t.Error("pagination/sort not forwarded")
+			}
+			fmt.Fprint(w, `{"success":true,"data":{"files":[],"total":100,"offset":100}}`)
+		case "getinfo":
+			fmt.Fprint(w, `{"success":true,"data":{"files":[{"path":"/anything/a","name":"a","isdir":false}]}}`)
+		case "create", "upload":
+			fmt.Fprint(w, `{"success":true}`)
+		case "download":
+			w.Header().Set("Content-Disposition", `attachment; filename="a"`)
+			fmt.Fprint(w, strings.Repeat("x", MaxBytes+1))
+		default:
+			t.Errorf("unexpected DSM operation %q", method)
+		}
+	})
+	s := NewService(client)
+	for _, user := range []string{"alice", "bob"} {
+		r := sessionRequest()
+		r.Header.Set("Cookie", "id="+user+"-session")
+		r.Header.Set("Authorization", "package-account-credentials-must-not-travel")
+		caller := callerFor(t, user)
+		ctx := context.Background()
+		roots, err := s.ListShares(ctx, caller, r, 0)
+		if err != nil || roots.Shares[0].Path != "/anything" {
+			t.Fatalf("%+v %v", roots, err)
+		}
+		if _, err := s.List(ctx, caller, r, "/anything", ListOptions{Offset: 100, Limit: 25, SortBy: "size", SortDirection: "DESC"}); err != nil {
+			t.Fatal(err)
+		}
+		if _, err := s.Info(ctx, caller, r, "/anything/a"); err != nil {
+			t.Fatal(err)
+		}
+		if err := s.CreateFolder(ctx, caller, r, "/anything", "new"); err != nil {
+			t.Fatal(err)
+		}
+		if err := s.Upload(ctx, caller, r, "/anything", "a", strings.NewReader("abc"), 3); err != nil {
+			t.Fatal(err)
+		}
+		stream, err := s.Download(ctx, caller, r, "/anything/a")
+		if err != nil {
+			t.Fatal(err)
+		}
+		n, err := io.Copy(io.Discard, stream.Body)
+		stream.Body.Close()
+		if err != nil || n != MaxBytes+1 {
+			t.Fatalf("stream was buffered/bounded: %d %v", n, err)
+		}
+	}
+	if calls != 24 {
+		t.Fatalf("wanted verification plus operation for every request, got %d", calls)
+	}
+}
+
+func TestTypedOperationsRejectMissingOrMismatchedSession(t *testing.T) {
+	calls := 0
+	client := fakeClient(t, func(w http.ResponseWriter, r *http.Request) {
+		calls++
+		fmt.Fprint(w, `{"success":true,"data":{"username":"mallory"}}`)
+	})
+	s := NewService(client)
+	for _, r := range []*http.Request{sessionRequest(), {Header: make(http.Header)}} {
+		if _, err := s.ListShares(context.Background(), alice(t), r, 0); err == nil {
+			t.Fatal("unverified caller accepted")
+		}
+	}
+	if calls != 1 {
+		t.Fatal("missing session reached DSM")
+	}
+}
+
+func TestDownloadReturnsBeforeDSMFinishesSendingBytes(t *testing.T) {
+	release := make(chan struct{})
+	client := fakeClient(t, func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Disposition", `attachment; filename="a"`)
+		fmt.Fprint(w, "first")
+		w.(http.Flusher).Flush()
+		<-release
+		fmt.Fprint(w, "last")
+	})
+	stream, err := client.DownloadStream(context.Background(), sessionRequest(), "/share/a")
+	close(release)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer stream.Body.Close()
+	b, err := io.ReadAll(stream.Body)
+	if err != nil || string(b) != "firstlast" {
+		t.Fatalf("%q %v", b, err)
+	}
+}
+
+func TestListValidatesOptionsAndDownloadPropagatesPermissionRefusal(t *testing.T) {
+	calls := 0
+	client := fakeClient(t, func(w http.ResponseWriter, r *http.Request) {
+		calls++
+		fmt.Fprint(w, `{"success":false,"error":{"code":408,"secret":"test-token"}}`)
+	})
+	for _, opts := range []ListOptions{{Offset: -1}, {Limit: 101}, {SortBy: "arbitrary"}, {SortDirection: "bad"}} {
+		if _, err := client.List(context.Background(), sessionRequest(), "/share", opts); err == nil {
+			t.Fatal("invalid listing option accepted")
+		}
+	}
+	if calls != 0 {
+		t.Fatal("invalid options sent to DSM")
+	}
+	if _, err := client.DownloadStream(context.Background(), sessionRequest(), "/share/a"); err == nil || strings.Contains(err.Error(), "test-token") || !strings.Contains(err.Error(), "denied") {
+		t.Fatal(err)
+	}
+}
+
+func TestMetadataRoutesUsePathsWithoutPersistedGrants(t *testing.T) {
+	client := fakeClient(t, func(w http.ResponseWriter, r *http.Request) {
+		r.ParseForm()
+		if r.Form.Get("method") == "get" {
+			fmt.Fprint(w, `{"success":true,"data":{"username":"alice"}}`)
+			return
+		}
+		if r.Form.Get("method") == "list_share" {
+			fmt.Fprint(w, `{"success":true,"data":{"shares":[],"total":0,"offset":0}}`)
+			return
+		}
+		if r.Form.Get("method") == "list" {
+			fmt.Fprint(w, `{"success":false,"error":{"code":407}}`)
+			return
+		}
+		fmt.Fprint(w, `{"success":true}`)
+	})
+	s := NewService(client)
+	if out := invoke(t, s, "alice", "nas.files.shares", `{"offset":0}`); out["success"] != true {
+		t.Fatal(out)
+	}
+	if out := invoke(t, s, "alice", "nas.files.list", `{"path":"/team","sortBy":"name"}`); out["error"].(map[string]any)["code"] != "denied" {
+		t.Fatal(out)
+	}
+	if out := invoke(t, s, "alice", "nas.files.create_folder", `{"parent":"/team","name":"new"}`); out["success"] != true {
+		t.Fatal(out)
+	}
+	if out := invoke(t, s, "alice", "nas.files.list", `{"grantId":"legacy","relative":""}`); out["success"] != false {
+		t.Fatal("legacy request accepted")
+	}
+	for _, route := range s.Routes() {
+		if strings.Contains(route.Method(), "grants") || route.Method() == "nas.discovery" {
+			t.Fatal("retired grant route retained")
+		}
+	}
+}
+
+func TestEmptySharePageSerializesAsAnEmptyListing(t *testing.T) {
+	client := fakeClient(t, func(w http.ResponseWriter, r *http.Request) {
+		fmt.Fprint(w, `{"success":true,"data":{"shares":[],"total":0,"offset":0}}`)
+	})
+	page, err := client.Discover(context.Background(), sessionRequest(), 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	encoded, err := json.Marshal(page)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(encoded), `"files":[]`) && !strings.Contains(string(encoded), `"shares":[]`) {
+		t.Fatalf("empty share page is indistinguishable from a malformed response: %s", encoded)
+	}
+}