@synopackageland/cli 0.4.1 → 0.5.3

package/dist/validate.js

@@ -4,12 +4,12 @@ import { contractSpan, makeError } from "./errors.js";
 import { collectInstallParameters, getValuePosition, loadContract } from "./contract/load.js";
 import { validateContract } from "./contract/validate.js";
 import { findListingUnsupportedInstallTypes } from "./contract/unsupported-types.js";
-import { collectComposeInterpolations, collectVolumeSourceInterpolations, loadCompose, validateAdminPortMapping, validateComposeHostBinds, validateComposeNumericCommandArgs, validateComposeRunAs, validateComposeSecurity, } from "./compose/analyze.js";
+import { classifyComposeRoute, collectComposeInterpolations, collectVolumeSourceInterpolations, loadCompose, validateAdminPortMapping, validateComposeHostBinds, validateComposeNumericCommandArgs, validateComposeRunAs, validateComposeSecurity, validateGatewayPortLoopback, } from "./compose/analyze.js";
+import { usesAuthGateway } from "./contract/web-launch.js";
 import { loadNative } from "./native/load.js";
 import { validateNative } from "./native/validate.js";
 import { COMPOSE_FILENAME, CONTRACT_FILENAME, NATIVE_FILENAME, } from "./discovery.js";
 import { declaredPrivilegeFlags } from "./compose/privilege.js";
-import { resourceWorkerEligibility } from "./build-spk/resource-worker.js";
 export function validateProject(project, options = {}) {
     const profile = options.profile ?? "personal";
     const errors = [];
@@ -72,7 +72,7 @@ export function validateProject(project, options = {}) {
         profile,
         declaredPrivilege: declaredPrivilegeFlags(parsed.contract),
     }));
-    if (resourceWorkerEligibility(parsed.contract, parsedCompose.compose).eligible) {
+    if (classifyComposeRoute(parsed.contract, parsedCompose, composeFile).route !== "reject") {
         errors.push(...validateComposeNumericCommandArgs(parsedCompose.compose, composeFile));
     }
     const installParams = collectInstallParameters(parsed.contract);
@@ -91,6 +91,9 @@ export function validateProject(project, options = {}) {
     if (typeof parsed.contract.adminport === "number") {
         errors.push(...validateAdminPortMapping(parsed.contract.adminport, parsedCompose.compose, composeFile));
     }
+    if (typeof parsed.contract.adminport === "number" && usesAuthGateway(parsed.contract)) {
+        errors.push(...validateGatewayPortLoopback(parsed.contract.adminport, parsedCompose.compose, composeFile));
+    }
     const interpolations = collectComposeInterpolations(parsedCompose.compose);
     const volumeSourceVars = collectVolumeSourceInterpolations(parsedCompose.compose);
     const dsmUserParams = installParams.filter(({ param }) => param.type === "dsm_user");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.4.1",
+  "version": "0.5.3",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {
@@ -32,5 +32,8 @@
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "exports": {
+    "./authorization-sdk": "./dist/authorization-sdk.js"
+  }
 }

package/schema/synology-app.schema.json

@@ -99,6 +99,25 @@
                 "type": "string"
               },
               "description": "Optional App cookie name allowlist forwarded by the generated Web Station ingress. Omit to forward no browser cookies."
+            },
+            "access": {
+              "type": "string",
+              "enum": [
+                "dsm-users",
+                "dsm-admins",
+                "dsm-groups",
+                "public"
+              ],
+              "description": "Who may open the web App. dsm-users (default) lets any signed-in DSM user in through a DSM-authenticated gateway; dsm-admins limits it to administrators; dsm-groups to the DSM groups listed in groups; public keeps the anonymous Web Station portal for Apps that authenticate users themselves. Headless apps omit this field."
+            },
+            "groups": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "string",
+                "pattern": "^(?:[A-Za-z0-9._-]{1,64}|[A-Za-z0-9._-]{1,64}\\\\[A-Za-z0-9._-](?:[A-Za-z0-9._ -]{0,126}[A-Za-z0-9._-])?|[A-Za-z0-9._-](?:[A-Za-z0-9._ -]{0,126}[A-Za-z0-9._-])?@[A-Za-z0-9._-]{1,64})$(?![\\s\\S])"
+              },
+              "description": "DSM group names allowed in; only with access: dsm-groups."
             }
           },
           "additionalProperties": true

package/skills/reference/create.md

@@ -1,6 +1,6 @@
 # 建立（Create）
 
-先選擇 `native-go`（Go CGI + DSM 視窗）、`binary`（預建服務程式）或 `compose-import`（上游容器）。`hello-web` 與 `hello-web-page` 分別示範 DSM 視窗及新分頁入口；`hello-files` 示範 Share 與固定 run-as 使用者。
+先選擇 `native-go`（Go CGI + DSM 視窗）、`binary`（預建服務程式）或 `compose-import`（上游容器）。`hello-files` 示範 Share 與固定 run-as 使用者。
 
 ```sh
 synopkgland init -t native-go --package MyApp my-app
@@ -12,7 +12,11 @@ synopkgland init -t compose-import upstream-app
 
 ## Published port
 
-hello-web 預設 published port 是 18333。每個 package／instance 都要分配獨立的 port；同一台 NAS 上不要重用。可挑選未使用的 19xxx 高位 port，例如 19160；同時修改 contract adminport 與 Compose published port，保留容器內 target。
+有 Web 入口的 Compose 專案需要 published port。每個 package／instance 都要分配獨立的 port；同一台 NAS 上不要重用。可挑選未使用的 19xxx 高位 port，例如 19160；同時修改 contract adminport 與 Compose published port，保留容器內 target。
+
+## 容器存取控制
+
+有 adminport 的容器 App 預設經 DSM 驗證 gateway（`integration.web.access`：dsm-users 預設、dsm-admins、dsm-groups＋groups、public）。Compose published port 必須綁 loopback：`127.0.0.1:<adminport>:<port>`，否則 validate 失敗（`COMPOSE_GATEWAY_PORT_EXPOSED`）。gateway 是編譯的 Go，建置需要 Go 與 `--arch`。`public` 才保留匿名 Web Station portal，inspect 會以 `CONTAINER_ANONYMOUS_PORTAL` 提醒。
 
 ## 建置與檢查
 

package/templates/_authorization/main.go

@@ -0,0 +1,104 @@
+// CLI-owned root bootstrap: accepts only compiled fixed operations. The native
+// task copies and pins this executable before it can run with root authority.
+package main
+
+import (
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+)
+
+var inventoryBase64 string
+
+type inventory struct {
+	Schema     int    `json:"schema"`
+	Package    string `json:"package"`
+	Version    string `json:"version"`
+	Operations []struct {
+		Name string `json:"name"`
+		Body string `json:"body"`
+	} `json:"operations"`
+	Files []struct {
+		Path string `json:"path"`
+		Size int64  `json:"size"`
+		Hash string `json:"sha256"`
+	} `json:"files"`
+}
+
+func run(args []string) error {
+	if os.Geteuid() != 0 || len(args) != 1 {
+		return errors.New("root and one fixed operation required")
+	}
+	var i inventory
+	raw, decode := base64.StdEncoding.DecodeString(inventoryBase64)
+	if decode != nil || json.Unmarshal(raw, &i) != nil || i.Schema != 2 || len(i.Operations) == 0 {
+		return errors.New("invalid compiled inventory")
+	}
+	var body string
+	for _, op := range i.Operations {
+		if op.Name == args[0] {
+			body = op.Body
+		}
+	}
+	if body == "" {
+		return errors.New("unknown operation")
+	}
+	// Disable/teardown/repair retain an escape path when UI payload is corrupt;
+	// they still execute only compiled, hash-pinned cleanup code.
+	cleanup := args[0] == "helper_disable" || args[0] == "helper_teardown" || args[0] == "helper_repair" || args[0] == "helper_purge"
+	if !cleanup {
+		if e := verifyFiles("/var/packages/"+i.Package+"/target", raw); e != nil {
+			return e
+		}
+	}
+	cmd := exec.Command("/bin/sh", "-eu", "-c", body)
+	cmd.Env = []string{"PATH=/usr/sbin:/usr/bin:/sbin:/bin"}
+	cmd.Stdout = os.Stdout
+	cmd.Stderr = os.Stderr
+	return cmd.Run()
+}
+func verifyFiles(dir string, raw []byte) error {
+	var i inventory
+	if json.Unmarshal(raw, &i) != nil || i.Schema != 2 {
+		return errors.New("invalid inventory")
+	}
+	root, e := os.OpenRoot(dir)
+	if e != nil {
+		return e
+	}
+	defer root.Close()
+	for _, p := range i.Files {
+		if p.Size < 0 || p.Size > 64<<20 {
+			return errors.New("invalid size")
+		}
+		f, e := root.Open(p.Path)
+		if e != nil {
+			return e
+		}
+		st, e := f.Stat()
+		if e != nil || !st.Mode().IsRegular() || st.Size() != p.Size {
+			f.Close()
+			return errors.New("untrusted payload")
+		}
+		h := sha256.New()
+		_, e = io.Copy(h, io.LimitReader(f, p.Size+1))
+		f.Close()
+		if e != nil || hex.EncodeToString(h.Sum(nil)) != p.Hash {
+			return errors.New("untrusted payload")
+		}
+	}
+	return nil
+}
+
+func main() {
+	if e := run(os.Args[1:]); e != nil {
+		fmt.Fprintln(os.Stderr, "authorization bootstrap refused:", e)
+		os.Exit(1)
+	}
+}

package/templates/_authorization/main_test.go

@@ -0,0 +1,35 @@
+package main
+
+import (
+	"crypto/sha256"
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestInventoryRejectsReplacementAndSymlinkEscape(t *testing.T) {
+	dir := t.TempDir()
+	body := []byte("approved bytes")
+	os.WriteFile(filepath.Join(dir, "file"), body, 0600)
+	raw := fmt.Sprintf(`{"schema":2,"files":[{"path":"file","size":%d,"sha256":"%x"}]}`, len(body), sha256.Sum256(body))
+	if e := verifyFiles(dir, []byte(raw)); e != nil {
+		t.Fatal(e)
+	}
+	os.WriteFile(filepath.Join(dir, "file"), []byte("altered bytes!"), 0600)
+	if e := verifyFiles(dir, []byte(raw)); e == nil {
+		t.Fatal("accepted replacement")
+	}
+	os.Remove(filepath.Join(dir, "file"))
+	outside := filepath.Join(t.TempDir(), "file")
+	os.WriteFile(outside, body, 0600)
+	os.Symlink(outside, filepath.Join(dir, "file"))
+	if e := verifyFiles(dir, []byte(raw)); e == nil {
+		t.Fatal("accepted external symlink")
+	}
+}
+func TestUnknownOperationNeverRuns(t *testing.T) {
+	if e := run([]string{"arbitrary"}); e == nil {
+		t.Fatal("accepted unknown operation")
+	}
+}

package/templates/_daemon/go.mod

@@ -1,3 +1,5 @@
 module synopkgland-daemon
 
 go 1.24
+
+toolchain go1.26.8

package/templates/_gateway/auth.go

@@ -0,0 +1,101 @@
+package main
+
+// DSM runs a package's CGI as the package account and forwards the browser's
+// cookies. The authenticator hands only the session carriers (cookie,
+// SynoToken, client address) to DSM's own authenticate.cgi, which prints the
+// signed-in user name, then resolves local groups or directory groups through DSM NSS.
+// It never parses the session cookie or trusts a user name from the request.
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net"
+	"net/http"
+	"net/url"
+	"os/exec"
+	"regexp"
+	"strings"
+	"time"
+)
+
+// authenticateCGI is DSM's session check for third-party CGIs.
+const authenticateCGI = "/usr/syno/synoman/webman/modules/authenticate.cgi"
+
+var errNoSession = errors.New("no valid DSM session")
+
+type identity struct {
+	User   string
+	Groups []string
+}
+
+type authenticator interface {
+	Authenticate(r *http.Request) (identity, error)
+}
+
+type dsmAuthenticator struct {
+	groupFile       string
+	passwdFile      string
+	directoryGroups func(context.Context, string) ([]string, error)
+	timeout         time.Duration
+	run             func(ctx context.Context, path string, env []string) ([]byte, error)
+}
+
+func newDSMAuthenticator() *dsmAuthenticator {
+	return &dsmAuthenticator{groupFile: "/etc/group", passwdFile: "/etc/passwd", timeout: 10 * time.Second, run: runCGI, directoryGroups: (directoryLookup{timeout: 2 * time.Second, run: runDirectoryCommand}).groups}
+}
+
+var userName = regexp.MustCompile(`^[A-Za-z0-9._@\\-]{1,193}$`)
+
+func (a *dsmAuthenticator) Authenticate(r *http.Request) (identity, error) {
+	cookie := r.Header.Get("Cookie")
+	if cookie == "" {
+		return identity{}, errNoSession
+	}
+	ctx, cancel := context.WithTimeout(r.Context(), a.timeout)
+	defer cancel()
+	out, err := a.run(ctx, authenticateCGI, sessionEnv(r, cookie))
+	var exit interface{ ExitCode() int }
+	if errors.As(err, &exit) {
+		return identity{}, errNoSession
+	}
+	if err != nil {
+		return identity{}, fmt.Errorf("run %s: %w", authenticateCGI, err)
+	}
+	user := strings.TrimSpace(string(out))
+	if !userName.MatchString(user) {
+		return identity{}, errNoSession
+	}
+	groups, err := a.groupsOf(ctx, user)
+	if err != nil {
+		return identity{}, err
+	}
+	return identity{User: user, Groups: groups}, nil
+}
+
+// sessionEnv is the complete environment authenticate.cgi sees: nothing from
+// this process and no request header besides the session carriers.
+func sessionEnv(r *http.Request, cookie string) []string {
+	token := r.Header.Get("X-SYNO-TOKEN")
+	if token == "" {
+		// A navigation or iframe cannot send the header; DSM's front end appends ?SynoToken= instead.
+		token = r.URL.Query().Get("SynoToken")
+	}
+	host, _, err := net.SplitHostPort(r.RemoteAddr)
+	if err != nil {
+		host = r.RemoteAddr
+	}
+	return []string{
+		"REQUEST_METHOD=GET",
+		"HTTP_COOKIE=" + cookie,
+		"HTTP_X_SYNO_TOKEN=" + token,
+		"QUERY_STRING=SynoToken=" + url.QueryEscape(token),
+		"REMOTE_ADDR=" + host,
+	}
+}
+
+func runCGI(ctx context.Context, path string, env []string) ([]byte, error) {
+	cmd := exec.CommandContext(ctx, path)
+	cmd.Env = env
+	return cmd.Output()
+}

package/templates/_gateway/auth_test.go

@@ -0,0 +1,216 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+	"testing"
+)
+
+const groupFile = `root:x:0:
+users:x:100:
+administrators:x:101:admin,alice
+staff:x:1030:alice,carol
+http:x:1023:
+`
+
+// DSM keeps no member list for users: the group is every local account's primary group.
+const passwdFile = `root:x:0:0::/root:/bin/sh
+alice:x:1001:100::/var/services/homes/alice:/sbin/nologin
+bob:x:1002:100::/var/services/homes/bob:/sbin/nologin
+carol:x:1003:100::/var/services/homes/carol:/sbin/nologin
+dave:x:1004:1030::/var/services/homes/dave:/sbin/nologin
+`
+
+type fakeRunner struct {
+	out  string
+	err  error
+	env  []string
+	path string
+}
+
+func (f *fakeRunner) run(_ context.Context, path string, env []string) ([]byte, error) {
+	f.path, f.env = path, env
+	return []byte(f.out), f.err
+}
+
+type exitError struct{}
+
+func (*exitError) Error() string { return "exit status 1" }
+func (*exitError) ExitCode() int { return 1 }
+
+func newTestAuth(t *testing.T, runner *fakeRunner) *dsmAuthenticator {
+	t.Helper()
+	dir := t.TempDir()
+	groups, passwd := filepath.Join(dir, "group"), filepath.Join(dir, "passwd")
+	for path, content := range map[string]string{groups: groupFile, passwd: passwdFile} {
+		if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	a := newDSMAuthenticator()
+	a.groupFile, a.passwdFile = groups, passwd
+	a.run = runner.run
+	return a
+}
+
+func sessionRequest() *http.Request {
+	r := httptest.NewRequest(http.MethodGet, "/webman/3rdparty/App/cgi/gateway.cgi/", nil)
+	r.RemoteAddr = "192.0.2.7:51234"
+	r.Header.Set("Cookie", "id=abc; did=xyz")
+	r.Header.Set("X-SYNO-TOKEN", "tok+en/=")
+	r.Header.Set("User-Agent", "should-not-pass")
+	return r
+}
+
+func TestUserAndGroupsComeFromAuthenticateCGIAndGroupFile(t *testing.T) {
+	runner := &fakeRunner{out: "alice\n"}
+	id, err := newTestAuth(t, runner).Authenticate(sessionRequest())
+	if err != nil || id.User != "alice" {
+		t.Fatalf("got %+v, %v", id, err)
+	}
+	if want := []string{"users", "administrators", "staff"}; !slices.Equal(id.Groups, want) {
+		t.Errorf("groups = %v, want %v", id.Groups, want)
+	}
+	if runner.path != authenticateCGI {
+		t.Errorf("ran %q", runner.path)
+	}
+}
+
+func TestOrdinaryUserHasNoAdministratorsGroup(t *testing.T) {
+	id, err := newTestAuth(t, &fakeRunner{out: "bob\n"}).Authenticate(sessionRequest())
+	if err != nil || id.User != "bob" || slices.Contains(id.Groups, "administrators") {
+		t.Fatalf("got %+v, %v", id, err)
+	}
+}
+
+func TestPrimaryGroupCountsAsMembershipEvenWithoutAMemberListEntry(t *testing.T) {
+	id, err := newTestAuth(t, &fakeRunner{out: "bob\n"}).Authenticate(sessionRequest())
+	if err != nil || !slices.Equal(id.Groups, []string{"users"}) {
+		t.Fatalf("got %+v, %v", id, err)
+	}
+}
+
+func TestPrimaryGroupIsNotDuplicatedWhenAlsoListedAsMember(t *testing.T) {
+	a := newTestAuth(t, &fakeRunner{out: "dave"})
+	if err := os.WriteFile(a.groupFile, []byte("staff:x:1030:dave\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	id, _ := a.Authenticate(sessionRequest())
+	if !slices.Equal(id.Groups, []string{"staff"}) {
+		t.Fatalf("groups = %v", id.Groups)
+	}
+}
+
+func TestMissingPasswdFileFailsClosedWithoutBeingNoSession(t *testing.T) {
+	a := newTestAuth(t, &fakeRunner{out: "bob"})
+	a.passwdFile = filepath.Join(t.TempDir(), "absent")
+	if _, err := a.Authenticate(sessionRequest()); err == nil || errors.Is(err, errNoSession) {
+		t.Fatalf("err = %v", err)
+	}
+}
+
+func TestOnlySessionCarriersReachAuthenticateCGI(t *testing.T) {
+	runner := &fakeRunner{out: "alice"}
+	if _, err := newTestAuth(t, runner).Authenticate(sessionRequest()); err != nil {
+		t.Fatal(err)
+	}
+	want := []string{
+		"HTTP_COOKIE=id=abc; did=xyz",
+		"HTTP_X_SYNO_TOKEN=tok+en/=",
+		"QUERY_STRING=SynoToken=tok%2Ben%2F%3D",
+		"REMOTE_ADDR=192.0.2.7",
+		"REQUEST_METHOD=GET",
+	}
+	got := slices.Clone(runner.env)
+	slices.Sort(got)
+	if !slices.Equal(got, want) {
+		t.Fatalf("env = %q\nwant  %q", got, want)
+	}
+}
+
+func TestMissingCookieNeverRunsAuthenticateCGI(t *testing.T) {
+	runner := &fakeRunner{out: "alice"}
+	r := sessionRequest()
+	r.Header.Del("Cookie")
+	_, err := newTestAuth(t, runner).Authenticate(r)
+	if !errors.Is(err, errNoSession) || runner.path != "" {
+		t.Fatalf("err=%v ran=%q", err, runner.path)
+	}
+}
+
+func TestExpiredOrMalformedSessionsAreNoSession(t *testing.T) {
+	for name, runner := range map[string]*fakeRunner{
+		"expired session (exit status)": {err: &exitError{}},
+		"empty output":                  {out: "\n"},
+		"two lines":                     {out: "alice\nadmin\n"},
+		"html output":                   {out: "<html>login</html>"},
+		"overlong name":                 {out: strings.Repeat("a", 200)},
+		"space in name":                 {out: "alice admin"},
+	} {
+		t.Run(name, func(t *testing.T) {
+			_, err := newTestAuth(t, runner).Authenticate(sessionRequest())
+			if !errors.Is(err, errNoSession) {
+				t.Fatalf("err = %v", err)
+			}
+		})
+	}
+}
+
+func TestAuthenticateCGIThatCannotRunFailsClosedWithoutBeingNoSession(t *testing.T) {
+	_, err := newTestAuth(t, &fakeRunner{err: errors.New("fork/exec: no such file")}).Authenticate(sessionRequest())
+	if err == nil || errors.Is(err, errNoSession) {
+		t.Fatalf("err = %v", err)
+	}
+}
+
+func TestGroupMembershipIsReadFreshOnEveryRequest(t *testing.T) {
+	runner := &fakeRunner{out: "carol"}
+	a := newTestAuth(t, runner)
+	id, _ := a.Authenticate(sessionRequest())
+	if !slices.Equal(id.Groups, []string{"users", "staff"}) {
+		t.Fatalf("groups = %v", id.Groups)
+	}
+	if err := os.WriteFile(a.groupFile, []byte("users:x:100:\nstaff:x:1030:alice\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	id, _ = a.Authenticate(sessionRequest())
+	if !slices.Equal(id.Groups, []string{"users"}) {
+		t.Fatalf("groups after removal = %v", id.Groups)
+	}
+}
+
+func tokenEnv(t *testing.T, r *http.Request) []string {
+	t.Helper()
+	runner := &fakeRunner{out: "alice"}
+	if _, err := newTestAuth(t, runner).Authenticate(r); err != nil {
+		t.Fatal(err)
+	}
+	return runner.env
+}
+
+func TestQueryTokenIsUsedWhenHeaderIsEmpty(t *testing.T) {
+	r := sessionRequest()
+	r.Header.Del("X-SYNO-TOKEN")
+	r.URL.RawQuery = "a=b&SynoToken=q%2Btok"
+	env := tokenEnv(t, r)
+	for _, want := range []string{"HTTP_X_SYNO_TOKEN=q+tok", "QUERY_STRING=SynoToken=q%2Btok"} {
+		if !slices.Contains(env, want) {
+			t.Fatalf("env = %q, missing %q", env, want)
+		}
+	}
+}
+
+func TestHeaderTokenWinsOverQueryToken(t *testing.T) {
+	r := sessionRequest()
+	r.URL.RawQuery = "SynoToken=from-query"
+	env := tokenEnv(t, r)
+	if !slices.Contains(env, "HTTP_X_SYNO_TOKEN=tok+en/=") || slices.Contains(env, "QUERY_STRING=SynoToken=from-query") {
+		t.Fatalf("env = %q", env)
+	}
+}