@synopackageland/cli 0.33.2 → 0.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.33.2",
+  "version": "0.35.0",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@napi-rs/keyring": "^2.1.1",
-    "@synopackageland/templates": "~0.31.0",
+    "@synopackageland/templates": "~0.32.0",
     "ajv": "^8.17.1",
     "commander": "^13.1.0",
     "json-canonicalize": "^3.0.1",

package/skills/SKILL.md

@@ -5,7 +5,7 @@ description: Initialize, extend, check, build, inspect, and deploy Synology appl
 
 # Independent Synology SPKs
 
-CLI 0.33.1 installs templates through `~0.31.0`. A templates patch needs only a
+CLI 0.35.0 installs templates through `~0.32.0`. A templates patch needs only a
 templates release; npm install/update selects a patch in that minor line. The CLI
 uses the locally installed templates and reads their SDK pin for defaults; it
 never downloads templates at runtime. Preserve the lockfile and use `npm ci` for
@@ -24,6 +24,23 @@ Use this guide to initialize, build and inspect own applications or upstream OSS
 
 For an existing open-source App, first read [reference/upstream-fork.md](reference/upstream-fork.md): upstream fork/history + untouched upstream files + all packaging in `synology/`, official container images pinned by tag/index digest, native official release binaries pinned by SHA-256 or a source build hook, and a single tag-merge upgrade command. Use `init --upstream-fork`; never rewrite the App as a component. Integrated upstream Apps require direct DSM administrator entry without a separate App password or an OIDC/SSO server: supported trusted headers first, disabling native login second; the shipped OpenList pattern uses the existing SDK 0.17.3 token adapter (`mode: token`, `access: dsm-admins`, `entry: admin-only`) with server-side Authorization injection. All DSM admins share one upstream admin; token reset requires package restart; WebDAV retains its native credentials.
 
+Use SDK 0.33.0 and CLI 0.35.0 for App entry enforcement. Declare every App method
+in the permissions table; dynamic names and unregistered HTTP dispatchers are rejected.
+Use fixed SDK routes and `identity_gateway.upstream_auth_paths` for client API
+paths that rely on upstream authentication. Read
+[reference/identity.md](reference/identity.md) and
+[reference/identity-gateway.md](reference/identity-gateway.md) before migration.
+For private worker HTTP, use `ipc.ServeUnix(ctx, path, handler)` and
+`ipc.DialUnix`, never a custom listener. The helper requires an owned mode-0600
+socket under the package's private `var/run`. For browser proxies, streams or
+initial upgrades, register `api.HandleHTTP("/proxy/", "app.proxy", handler)`
+in the same API registry and declare the method as authenticated or
+administrators. Prefixes are literal, disjoint full segments outside reserved
+SDK paths. Origin, entry, identity and permission checks still apply. CGI
+cannot upgrade a connection; use an existing upgrade-capable deployment
+transport. The audit follows each configured Go binary's Linux import graph,
+including declared workers; unshipped dev commands are excluded.
+
 **If you package someone else's open-source project, set `maintainer` to the
 original project/owner (prefer the project's own team/org name, else the owner's
 display name, else login), `metadata.maintainer_url` to the upstream repository,

package/skills/reference/create.md

@@ -56,7 +56,7 @@ backend: {runtime: rust, dir: app, entry: hello, methods: [hello.greet]}
 - Python：DSM 的 `/usr/bin/python3`；SDK 放進 `app/vendor/synopkgland_app/`，`PYTHONPATH=vendor`。
 - Node：Package Center 的 Node.js_v18／v20／v22 成為 INFO `install_dep_packages`；SDK 的 `package.json` 與 `dist/` 放進 `node_modules/@synopackageland/app`，其他 dependencies 先在 App 目錄 `npm ci --omit=dev`。
 - Rust：Cargo.toml 以 git＋tag 相依 `syno-pkg-land-app`；`cargo zigbuild` 交叉編譯（x86_64／aarch64 musl、armv7 glibc），`panic = "unwind"`；binary 在 `app/bin/<entry>`。需要 rustup 的 cargo、三個 target、cargo-zigbuild 與 zig。
-- methods：沒寫時 build 在建置機執行 `<entry> --describe`；Rust 必須寫。`permissions.json` 只能設定 methods 內的 method。
+- methods：沒寫時 build 在建置機執行 `<entry> --describe`；Rust 必須寫。每個 App method 都必須明列於 `permissions.json`，且表內只能設定 methods 內的 method。動態名稱與自訂 HTTP dispatcher 會被拒絕；請使用固定 SDK routes。
 - capabilities：`files`、`identity`、`jobs`、`rootOps`、`delegate`（僅 `until-revoked`＋`files.moveFromStaging`＋destinations）與 `portal`；daemon 需要 Go。jobs 或 delegate 時，同一個 runtime 另裝為 `target/background/worker`，DSM 以套件帳號執行 `worker --worker`；rootOps、delegate 附 executor，`bridge.json` 的 delegate digest 必須等於 SPK 的 executor。
 - transfers：`backend.transfers: {<method>: upload|download}`（method 必須在 methods 內），`backend.max_upload_bytes` 上限 16 GiB。
 

package/skills/reference/files.md

@@ -2,6 +2,11 @@
 
 Native-go 的 B 能力使用 `init --with files` 或 `add files`，對應 schema 2 `capabilities.files: session`。File tree 與共用 NasPicker 以 TreeView／DataGrid 顯示本人可見內容；一般選取不建立授權；delegate destination 選取例外，確認即授權。FilePicker 選瀏覽器本機檔案。上傳／下載使用 streaming transport，不把內容放進 JSON。每次以呼叫者有效 DSM session 由 File Station 判權，不需管理員進行能力設定。
 
+SDK 0.32.0 的 delegated `files.write` 逐檔上限為 100 MiB；`files.read` 與
+URL 下載另維持 64 MiB 上限。`webapi.call` 的 request params 只接受 JSON，
+不提供 request upload；檔案上傳使用串流 `files.write`。更新後重建套件，
+並重新核准變更的 executor payload。
+
 只有 App session 沒有有效 DSM cookie 時回 `dsm_session_required`，須在同 hostname 登入 DSM。不能以套件帳號或 root 作後備存取。
 
 A 能力 `--with jobs` 使用套件帳號處理已匯入的私有副本，依可信 username／UID 綁定；一般使用者不需 admin 設定即可提交、查詢與取消自己的工作。關閉瀏覽器後繼續，不保存 cookie／SID／密碼。匯入需要本人在線 session；私有副本不是離線讀取原檔案的權限。Jobs 與 daemon 互斥。

package/skills/reference/identity-gateway.md

@@ -1,5 +1,25 @@
 # Wrap an OSS app with DSM accounts
 
+## Upstream-authenticated paths
+
+Build with SDK 0.32.0 and CLI 0.34.0. Use `upstream_auth_paths` for client API
+paths that use upstream authentication.
+
+Keep browser routes behind `entry: admin-only` or `entry: app-privilege`; list
+only upstream API/share prefixes in `identity_gateway.upstream_auth_paths`, for
+example `[/rest, /share]`. Prefixes are case-sensitive and segment-bounded;
+`/rest` does not match `/restore`. Use 1-16 nonoverlapping absolute prefixes with
+URL unreserved characters and `/`, no root, dot segments, repeated slashes,
+percent escapes, wildcards or reserved `/_sso` / `/_spl` paths.
+
+Permanent/optional passthrough must be contained in those prefixes. Requests
+preserve upstream credentials but lose DSM/SDK cookies and trusted identity
+headers. Upstream auth owns authentication, CSRF, authorization and WebSockets;
+public upstream share links remain public. Other paths keep the DSM entry gate.
+SDK RPC methods cannot use this exception. The CLI checks matching SDK capability
+and links the gateway policy digest; editing the static paths requires rebuilding.
+See `docs/app-entry.md` for the complete contract.
+
 ## External access
 
 Use SDK 0.30.0 or later with matching gateway sources. Add this to the existing

package/skills/reference/identity.md

@@ -2,6 +2,14 @@
 
 Native-go validates the caller's DSM session per package. Business route permissions come from backend/internal/api/permissions.json; SDK-owned route policy is protected separately. Capabilities describe execution/resources and do not grant business route access. Never trust a request username as owner.
 
+With SDK 0.32.0 and CLI 0.34.0, every App method must appear in the permissions
+table, including administrator-default methods. Dynamic names and custom HTTP
+dispatchers are rejected. Use fixed SDK route constructors and declare
+`identity_gateway.upstream_auth_paths` for client API paths authenticated by the
+upstream. These paths never exempt SDK RPC methods from their own permissions.
+Read [App entry and registration](https://github.com/synopackageland/syno-pkg-land-cli/blob/main/docs/app-entry.md)
+for migration and build binding.
+
 Entry: omit `entry` for legacy access; `entry: admin-only` admits administrators only and is the floor of every route: SDK routes a capability adds (files, jobs, portal, delegate, rootOps) refuse ordinary users with `admin_required`, the launcher is hidden, and an app route marked `authenticated` or `public` in permissions.json fails validate/build with `STANDALONE_ENTRY_WIDENED` (only the public `identity: standalone` login routes stay public; they admit no one by themselves). The SPK records the mode in `sdk-package.json`; `inspect` prints it and flags `ENTRY_LAUNCHER_MISMATCH`; `entry: app-privilege` also admits accounts DSM Application Privileges allows for `SYNO.SDS.<package>.Instance` (native-go only, needs an `authenticated` route). DSM evaluates user/group/everyone rules, allow/deny precedence and IP ranges; one CGI check covers every route, failures refuse with `app_privilege_denied`, and decisions are cached at most 30 seconds. DSM's install default allows administrators only, so declaring or upgrading never opens the app to everyone. DSM keeps those rules after uninstall and applies them again to a later install under the same name: an App with the executor (rootOps or delegate) removes them automatically at uninstall (failures go to the system log entry `synopkgland-executor`); a no-privilege App never uses root, so an administrator removes them in Control Panel > Application Privileges. The delegate executor applies the same entry rule to every protected and producer move: once DSM no longer allows a user, new moves under that user's still-valid grant are refused (`APP_DENIED`, grant invalidated); files already saved stay. Guard global settings in shared routes with Go `api.RequireAdmin(caller)` (`admin_required`); the frontend `ctx.user?.isAdmin` only hides controls.
 
 I capability: init --with login or add login enables Go-native standalone identity and Vue login. Same-host DSM cookies can be reused across ports after backend verification. Missing cookies use an HTTPS DSM account/password/OTP fallback; passwords and DSM credentials are not persisted. Plain UI is unsupported. App sessions last at most 15 minutes; sensitive operations revalidate live DSM cookies and local UID. Password-only sessions permit only basic app.status/greeting.get reads. Missing revalidation returns session_revalidation_required; files return dsm_session_required. Sign in to DSM on the same hostname. Web Station portal/proxy acceptance remains pending.