@synopackageland/cli 0.12.1 → 0.13.0

package/dist/standalone/spk.js

@@ -22,7 +22,9 @@ import { copyStandaloneNotices } from "../build-spk/notices.js";
 import { copyAppTree } from "./bridge-app.js";
 import { isBridgeBackend } from "./bridge-backend.js";
 import { hostScriptName, renderHostAdapterScript } from "./host-adapter.js";
+import { composeSource } from "./compose.js";
 import { copyDaemonPayload } from "./daemon.js";
+import { GATEWAY_CGI_PATH, GATEWAY_CONFIG_PATH, GATEWAY_EXEC, identityGatewayConfig } from "./identity-gateway.js";
 import { BACKGROUND_UNIT_DIR, BACKGROUND_WORKER_PAYLOAD, backgroundUnitName, renderBackgroundUnit, BRIDGE_WORKER_ARGS } from "./background.js";
 import { renderStandaloneResource } from "./resource.js";
 import { nativePortal } from "./portal.js";
@@ -79,11 +81,22 @@ export async function assembleStandaloneSpk(options) {
         mkdirSync(dirname(cgiTarget), { recursive: true });
         copyFileSync(options.cgiPath, cgiTarget);
         chmodSync(cgiTarget, EXEC_MODE);
-        if (manifest.daemon) {
+        if (manifest.daemon || manifest.compose) {
             if (!options.daemonControl)
                 throw new StandaloneBuildError("STANDALONE_DAEMON_ARTIFACT_REQUIRED", "daemon controller artifact required.");
             copyDaemonPayload(manifest, options.arch, join(staging, "package", "daemon"), options.daemonControl);
         }
+        if (manifest.identityGateway) {
+            if (!options.identityGateway)
+                throw new StandaloneBuildError("STANDALONE_IDENTITY_GATEWAY_ARTIFACT_REQUIRED", "identity gateway artifact required.");
+            for (const path of [GATEWAY_CGI_PATH, `daemon/payload/${GATEWAY_EXEC}`]) {
+                const target = join(staging, "package", path);
+                mkdirSync(dirname(target), { recursive: true });
+                copyFileSync(options.identityGateway, target);
+                chmodSync(target, EXEC_MODE);
+            }
+            writeFile(join(staging, "package", GATEWAY_CONFIG_PATH), identityGatewayConfig(manifest));
+        }
         if (manifest.capabilities.jobs) {
             if (!options.backgroundWorker)
                 throw new StandaloneBuildError("STANDALONE_BACKGROUND_ARTIFACT_REQUIRED", "background worker artifact required.");
@@ -127,11 +140,13 @@ export async function assembleStandaloneSpk(options) {
         const hook = manifest.uninstall && uninstallExecProblem(join(staging, "package"), manifest.uninstall.purge);
         if (hook)
             throw new StandaloneBuildError(hook.code, hook.message);
+        if (manifest.compose)
+            writeFile(join(staging, "package/compose/docker-compose.yml"), composeSource(manifest.compose));
         const packageTgz = join(staging, "package.tgz");
         await createReproducibleTar(join(staging, "package"), packageTgz, { gzip: true });
         rmSync(join(staging, "package"), { recursive: true, force: true });
         const checksum = createHash("md5").update(readFileSync(packageTgz)).digest("hex");
-        writeFile(join(staging, "sdk-package.json"), JSON.stringify({ schema: 2, backend: manifest.backend.kind, capabilities: Object.keys(manifest.capabilities).sort(), ...(manifest.entry ? { entry: manifest.entry } : {}), ...(manifest.uninstall ? { uninstall: uninstallRecord(manifest.uninstall, manifest.i18n?.catalogs) } : {}) }));
+        writeFile(join(staging, "sdk-package.json"), JSON.stringify({ schema: 2, backend: manifest.backend.kind, capabilities: Object.keys(manifest.capabilities).sort(), ...(manifest.compose ? { compose: { services: manifest.compose.services } } : {}), ...(manifest.entry ? { entry: manifest.entry } : {}), ...(manifest.uninstall ? { uninstall: uninstallRecord(manifest.uninstall, manifest.i18n?.catalogs) } : {}) }));
         writeFile(join(staging, "INFO"), renderInfo(manifest, options.arch, checksum, options.executor?.executorDigest));
         mkdirSync(join(staging, "conf"));
         writeFile(join(staging, "conf", "privilege"), renderNativePrivilege());
@@ -203,12 +218,14 @@ function renderInfo(manifest, arch, checksum, executorDigest) {
     // Package Center writes INFO as root; root tasks accept only this executor.
     if (executorDigest)
         fields.push([EXECUTOR_ANCHOR, executorDigest]);
+    if (manifest.compose)
+        fields.push(["install_dep_packages", "ContainerManager"]);
     const backend = manifest.backend;
     if (isBridgeBackend(backend) && backend.node)
         fields.push(["install_dep_packages", backend.node.package]);
     fields.push(...metadataInfoFields(manifest.metadata));
     // Background packages need prestart: it runs before DSM's systemd-user-unit acquire.
-    if (manifest.daemon || manifest.capabilities.jobs)
+    if (manifest.daemon || manifest.compose || manifest.capabilities.jobs)
         fields.push(["precheckstartstop", "yes"]);
     for (const locale of LOCALES) {
         const text = manifest.i18n?.info[locale];

package/dist/validate.js

@@ -21,7 +21,7 @@ export function validateProject(project, options = {}) {
     const standalonePath = join(project.root, DSM_PACKAGE_FILENAME);
     const hasCompose = existsSync(project.composePath);
     const hasStandalone = existsSync(standalonePath);
-    if (hasCompose && hasStandalone) {
+    if (hasCompose && hasStandalone && isNativeLayout(project.root)) {
         return { ok: false, errors: [{
                     code: "PROJECT_RUNTIME_EXCLUSIVE",
                     span: { file: DSM_PACKAGE_FILENAME, line: 1, column: 1 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {
@@ -25,7 +25,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@synopackageland/templates": "0.12.0",
+    "@synopackageland/templates": "0.13.0",
     "ajv": "^8.17.1",
     "commander": "^13.1.0",
     "tar": "^7.4.3",

package/skills/SKILL.md

@@ -7,7 +7,7 @@ description: Initialize, extend, check, build, inspect, and deploy Synology appl
 
 Use this guide to initialize, build and inspect own applications or upstream OSS as independent packages. 依已實作能力區分 DSM session 檔案、私有 jobs 與 App 登入；delegate 已實作並隨 CLI 提供固定操作的離線委託（預設 `files.moveFromStaging`）；共用 delegate／rootOps executor 的完整裝置生命週期驗收仍待完成，不得宣稱已通過；支援邊界依 delegate guide／support matrix，禁止發明新的身分平台。
 
-Start with `synopkgland init -t native-go`, `synopkgland init -t binary`, or `synopkgland init -t compose`. Read reference/create.md or reference/wrap.md, then reference/deploy.md. Native CGI session checks belong to the package. Container authentication belongs to upstream; fixed service credentials govern mounted data access.
+Start with `synopkgland init -t native-go`, `synopkgland init -t binary`, or `synopkgland init -t compose`. Read reference/create.md or reference/wrap.md, then reference/deploy.md. Native CGI session checks belong to the package. For wrapping upstream OSS with DSM accounts, read [reference/identity-gateway.md](reference/identity-gateway.md) first. It covers native and host-network Compose upstreams, mode selection, isolation, account deletion and verification. Fixed package credentials govern container data access.
 
 Never install, uninstall, publish or modify NAS data without task authorization. Prefer check, inspect and deploy --dry-run for reviewable artifacts.
 

package/skills/reference/create.md

@@ -39,8 +39,8 @@ rootOps 與 delegate 已共用管理員 PasswordConfirm 核准的 protected exec
 backend 寫 `runtime: python|node|rust`（`runtime: go` 等同 `kind: go`）。CGI 是 SDK 的 Go runtime（`bridge/cmd/runtime`），它驗證 DSM session、entry 與 `permissions.json` 後，以套件帳號（不是 root）每個請求啟動一次 App。App 放在 ui 以外的目錄，打包成 `target/app/`，build 寫入 `bridge.json`（spec/bridge/v1）並把它與 `permissions.json` 的 sha256 編進 runtime。
 
 ```yaml
-backend: {runtime: python, dir: app, entry: main.py, sdk: X.Y.Z}
-backend: {runtime: node, dir: app, entry: main.mjs, sdk: X.Y.Z, node: {package: Node.js_v20}}
+backend: {runtime: python, dir: app, entry: main.py, sdk: 0.13.0}
+backend: {runtime: node, dir: app, entry: main.mjs, sdk: 0.13.0, node: {package: Node.js_v20}}
 backend: {runtime: rust, dir: app, entry: hello, methods: [hello.greet]}
 ```
 

package/skills/reference/identity-gateway.md

@@ -0,0 +1,174 @@
+# Wrap an OSS app with DSM accounts
+
+Use this checklist before selecting an image or writing glue. Discover the
+installed CLI (`--help`, `skill show`, `check --json`) and SDK contracts. Use the
+app's supported API/configuration; do not patch upstream or write its database.
+Record the tested app revision, image digest, DSM, architecture and limitations.
+Ask the owner when evidence cannot establish a decision that affects their data
+or expected behavior. An unknown answer is not a pass.
+
+## Decide before building
+
+| Question to answer with upstream source/docs and a probe | Decision |
+| --- | --- |
+| OIDC, trusted reverse-proxy headers, or only its own login? | Prefer `mode: oidc`; use `header` only with upstream trusted-header support. `token` runs a bounded native argv adapter that returns headers; establish how it obtains a per-user app credential. Do not invent an admin impersonation API. |
+| Does OIDC JIT-create an account? Is registration interactive? Which username claim is used? | Enable supported auto-registration and silent entry. The gateway emits `sub` as DSM UID; verify the app stores/matches that stable subject, rather than only name/email. Test existing-account collisions and rename behavior. Never silently link unrelated accounts by email. |
+| Does each sign-in apply a role/group claim, including demotion? | Configure `roles` and the app's claim mapping. If unsupported, accept and document the limitation by default. OpenList's JIT accounts can all be ordinary users; do not patch it or describe a manually linked bootstrap admin as automatic mapping. Ask only if the owner requires a different product behavior. |
+| Is data private to each app user? | Test two ordinary users in both directions, including search, shares, downloads and APIs. OpenList needs distinct `base_path` and permissions; JIT alone does not create private storage. Jellyfin library visibility is not proof of object-level isolation. Paperless owner-NULL objects can become visible to everyone: deleting a user before their documents can expose them. Ask whether shared data is intended; do not promise isolation the app lacks. |
+| What starts login, and which base/callback paths does the app use? | Verify redirects, trailing slash, query and HTTP/HTTPS behavior. `redirects` accepts local paths without a query. OIDC callbacks require exact allowlists; `rewrite_json` handles supported JSON login redirects. Test the actual desktop/bare-root entry separately from a direct SSO URL. |
+| What really controls the listen address and port? | Verify the exact upstream environment/config key and actual kernel listener. OpenList uses `ADDR`, not `ADDRESS`. Set `127.0.0.1`; turn off every auxiliary public listener (FTP/SFTP/S3/debug/metrics as applicable). |
+| Can every container run at an arbitrary non-root UID/GID? | Require package UID/GID materialization, `cap_drop: [ALL]`, `no-new-privileges:true`, and `network_mode: host` for every service. Bridge cannot reach the native loopback issuer. Host networking shares the NAS network namespace; it is not network isolation. An image that needs root or extra privileges is unsupported by this policy. |
+| Where is data kept, and when does it exist? | Bind DSM's persistent `${SYNOPKG_PKGVAR}` root. DSM creates and owns it before resource acquisition; preinst only writes incoming `compose/.env`, never mkdir/chown `@appdata`. Do not mount upgrade-replaced `target/compose/data`. Test an actual package upgrade. Current support has no external share mounts, named volumes, extra Compose files or container secrets/config resources. |
+| What deletes the app account, sessions and owned data? | Use the supported CLI/REST interface through native `account.on_delete.exec`, then explicitly scoped `remove`. Keep secrets in package-owned 0600 files and directories in 0700. OpenList REST user deletion does not remove physical `base_path` files. Shared files need an explicit retention decision. Make deletion idempotent; inspect pending failures and verify readback. |
+| What happens when DSM disables the user or logs out? | New DSM sign-ins must fail. Existing app sessions, API tokens, download links or gateway sessions may remain until expiry; document the measured gap. Do not claim immediate revocation or add a root account watcher. |
+| Must native/mobile clients work? | Verify their actual flow: app passwords/API tokens, Jellyfin Quick Connect, or OIDC in the system browser. Use exact `native_redirects` custom schemes where supported. Passthrough grants no DSM session protection; document app authentication and revocation for each allowed prefix. Browser success is not mobile success. |
+| HTTP, HTTPS or both? | Test both requested schemes. HTTP can transmit the DSM `id` cookie without `Secure`; recommend HTTPS without claiming HTTP is unsupported. Local self-signed TLS and mobile trust are separate issues. Never disable NAS security settings to obtain a pass. |
+| Does the NAS meet deployment/resource requirements? | `docker-project` needs DSM >= 7.2.1 and installed/running Container Manager. Keep package code unprivileged; Container Manager owns containers. Measure app RSS/cgroup usage separately from gateway and shared infrastructure. Check image architecture, CPU features, helper tools and Docker-only dependencies. Do not infer a native build exists. |
+
+Account deletion uses a zero-root `/etc` inotify watcher and startup comparison
+of previously seen local UIDs. It does not install DSM plugins, hooks, poll DSM
+or use `account.snapshot`. Failed local delete actions remain pending and retry
+with backoff. Domain/LDAP disappearances require explicit `gateway account
+status` / `gateway account purge`; never infer deletion from an NSS outage.
+
+## OpenList container example
+
+Start with a schema-2 native-go or binary project for the native CGI and package
+UI. Add `compose` to **dsm-package.yaml**; do not combine the legacy
+`synology-app.yaml` Compose contract with it. Omit `daemon`. Set `os_min_ver` to
+at least `7.2.1-69057`, `capabilities: {}`, and supply one helper payload directory
+per architecture. The examples below pin released SDK 0.13.0, which contains the gateway/account APIs.
+
+```yaml
+compose:
+  file: compose.yaml
+  targets: {x86_64: helpers}
+  services:
+    openlist: {address_env: ADDR, port: 25244}
+identity_gateway:
+  sdk: 0.13.0
+  mode: oidc
+  upstream: 25244
+  listen: {http: 25240, https: 25241}
+  oidc:
+    issuer_port: 25249
+    clients:
+      - id: openlist
+        redirect_paths: [/api/auth/sso_callback, /api/auth/sso_get_token]
+  account:
+    on_delete:
+      - exec: [bin/openlist-glue, delete-user, "{uid}"]
+      - remove: users/{uid}
+```
+
+`compose.yaml` (replace `IMAGE_DIGEST` with the verified official image digest):
+
+```yaml
+services:
+  openlist:
+    image: openlistteam/openlist@sha256:IMAGE_DIGEST
+    network_mode: host
+    user: "${SYNOPKGLAND_UID}:${SYNOPKGLAND_GID}"
+    cap_drop: [ALL]
+    security_opt: [no-new-privileges:true]
+    restart: "no"
+    environment:
+      ADDR: 127.0.0.1
+      HTTP_PORT: "25244"
+      HTTPS_PORT: "-1"
+      LOG_ENABLE: "false"
+    volumes: ["${SYNOPKG_PKGVAR}:/opt/openlist/data"]
+```
+
+Verify the current OpenList settings API, then have package-account app glue
+configure `sso_login_enabled=true`, `sso_login_platform=OIDC`,
+`sso_client_id=openlist`, `sso_client_secret` from
+`var/sso/client-openlist.secret`, `sso_oidc_username_key=sub`,
+`sso_endpoint_name=http://127.0.0.1:25249`, `sso_auto_register=true` and the
+required compatibility setting. Keep bootstrap/admin credentials in a private
+file, never argv/logs. The helper `helpers/bin/openlist-glue` is a project-owned
+native executable: `delete-user UID` lists users, selects the exact ordinary
+account by SSO subject, deletes through REST, and reads back absence. It returns
+success if already absent and never deletes the bootstrap admin.
+
+Configure a tested upstream JIT path policy before promising private files.
+`remove: users/{uid}` deletes only that directory **under package var**; it is
+not automatic cleanup of an arbitrary OpenList storage provider. The app's
+SSO entry can be `/api/auth/sso?method=sso_get_token`; that query URL is not a
+valid `identity_gateway.redirects` value. Test and document the entry you ship.
+
+Startup order is DSM resource acquisition -> Container Manager starts the
+project -> the native controller waits up to its bounded start deadline for
+**all declared service ports**, owned by the package UID, at 127.0.0.1 ->
+`gateway run` without a child. The controller checks IPv4/IPv6 TCP and UDP
+bindings every second and closes the gateway on missing/unsafe upstreams.
+Public TCP listener exceptions are only the declared gateway ports. Package
+stop/preupgrade/preuninst stop the gateway before DSM releases the project;
+no package code calls Docker or uses its socket. Startup/monitor failure closes
+gateway ingress and fails package health; resource rollback/release belongs to
+DSM/Container Manager. The guard cannot stop a misconfigured container or act
+as a firewall: correct bindings must be established before deployment.
+
+## Audiobookshelf native example
+
+Use the existing native `daemon` route. A project-owned `absglue run` launches
+the unmodified ABS binary, binds it to loopback with the supported host/base
+path settings, configures OIDC through its API, and supervises it. The same
+helper implements idempotent deletion. The example pins released SDK 0.13.0.
+
+```yaml
+daemon:
+  exec: bin/absglue
+  targets: {x86_64: payload}
+  args: [run]
+identity_gateway:
+  sdk: 0.13.0
+  mode: oidc
+  upstream: 13378
+  listen: {http: 13380, https: 13443}
+  redirects: {"/": /audiobookshelf/}
+  oidc:
+    issuer_port: 13390
+    clients:
+      - id: abs
+        redirect_paths: [/audiobookshelf/auth/openid/callback]
+        pkce: true
+        roles: {claim: groups, admin: admin, user: user}
+  account:
+    on_delete:
+      - exec: [bin/absglue, delete-user, "{name}"]
+      - remove: users/{uid}
+```
+
+Verify ABS's current `openidAutoLaunch`, auto-registration, username/sub
+matching and `groups` mapping through its API. Test promotion and demotion at
+sign-in. `delete-user` must handle sessions, feeds/shares and retention in the
+correct order when those features are used; deleting a library does not imply
+deleting audio files. A minimal fixture directory is not proof of full purge.
+
+## Before calling it done
+
+- Run `check --json`, `build --json`, and `inspect <final-spk> --json` with the
+  installed CLI. Run the affected CLI/SDK gates, not only a patched PoC.
+- Use fresh ordinary/admin DSM browser sessions over each requested scheme;
+  prove zero-click sign-in, record the exact entry URL, stable subject and app
+  identity. Test signed-out/fake-identity requests. Do not log tokens, cookies,
+  assertions, URL queries or `/proc/*/cmdline`.
+- Read back admin/user roles and a demotion after another sign-in. Mark the
+  accepted OpenList role limitation explicitly; never manufacture a pass.
+- Prove two ordinary users cannot read each other's intended private objects,
+  including NULL-owner/shared-link behavior. Record what was actually tested.
+- Create only task-owned test users/data. Delete a DSM user and observe the
+  automatic native REST/CLI delete **and** owned file removal; read gateway
+  pending status and app absence. Restart with a pending deletion to exercise
+  readiness/retry. Preserve shared data unless its removal is authorized.
+- Disable a test user; show new SSO is blocked over both schemes. Probe the old
+  app token separately and report its actual lifetime/revocation behavior.
+- Inspect actual upstream/issuer listeners, UID and `CapEff: 0`, including CGI
+  and every container. From a second LAN host, prove upstream/issuer cannot be
+  reached, with the gateway as a positive reachability control.
+- Write package-owned data, upgrade the SPK, and read back the same data,
+  ownership and sign-in/deletion state. Test stop/start and failure health.
+- Clean up only task-owned users, package/project/containers/images, private
+  fixtures and test resources. Read back absence. Keep DSM-retained package
+  identities unless their deletion was authorized, and report their names.

package/skills/reference/wrap.md

@@ -14,6 +14,10 @@ synopkgland check      # 契約、Compose 意圖與 Web entry 提示
 
 
 
+For DSM-account SSO around OSS, first read [identity-gateway.md](identity-gateway.md).
+It defines the separate schema-2 `compose` + `identity_gateway` host-network policy;
+the legacy Compose route below retains its restrictions.
+
 ## Compose 規則（analyzer 會擋）
 
 - 禁止：`privileged`、`network_mode: host`、裝置節點、`cap_add`、掛載 Docker socket。