@synopackageland/cli 0.14.1 → 0.15.0

package/skills/reference/identity-gateway.md

@@ -17,8 +17,8 @@ or expected behavior. An unknown answer is not a pass.
 | 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. |
+| Can every container run at an arbitrary non-root UID/GID? | Use package UID/GID by default, cap_drop ALL and no-new-privileges. Only verified OIDC consumers need host networking. Explicit container-root is bounded to bridge and named volumes; test image compatibility. See compose.md. |
+| Where is data kept, and when does it exist? | Declare private storage differences; the nonroot SDK prepare checks DSM-owned pkgvar and creates bounded private subdirectories. Ownership/timing is a device blocker. Named volumes and local multiple files are supported; external Shares and file secret/config delivery remain unsupported. |
 | 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. |
@@ -31,150 +31,14 @@ 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
+## Compose declaration
 
-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.14.1, which contains the gateway/account APIs.
+Read [compose.md](compose.md) for the current schema-2 route, examples and support boundary. No dummy backend or helper directory is required. Upstream files stay unchanged; the SDK planner compiles an override and one worker model. Mode none retains native login, while header/token/OIDC use upstream-supported identity integration. There is no SSO Server.
 
-```yaml
-compose:
-  file: compose.yaml
-  targets: {x86_64: helpers}
-  services:
-    openlist: {address_env: ADDR, port: 25244}
-identity_gateway:
-  sdk: 0.14.1
-  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}
-```
+Default networking is bridge with one loopback ingress. OIDC consumers of the native loopback issuer require explicit verified host networking and address_env; this does not force unrelated services onto host networking. Named volumes and multiple local files are supported by the planner. Existing Shared Folders remain blocked until official protected mount authority and project control are verified.
 
-`compose.yaml` (replace `IMAGE_DIGEST` with the verified official image digest):
+Containers use a fixed package identity and do not inherit the signed-in user's File Station ACL. App account mapping is separate from filesystem authority. Per-user file access requires a session/Broker Adapter, outside the mount feature.
 
-```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"]
-```
+For native Apps, retain the existing daemon, identity_gateway and account.on_delete declarations. Use fixed native argv adapters and package-private paths for deletion; the gateway never writes an upstream database. Test rename, demotion, two-user visibility, stale credentials and account deletion against the actual upstream image.
 
-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.14.1.
-
-```yaml
-daemon:
-  exec: bin/absglue
-  targets: {x86_64: payload}
-  args: [run]
-identity_gateway:
-  sdk: 0.14.1
-  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.
-
-Schema 2 的 `dsm-package.yaml` + `identity_gateway` + `compose` 同樣視為
-web service：省略 `ui.launch` 時預設 `new-page`，使用 standalone launcher，
-不帶 Application Portal。兩條 Compose 路線共用 `contract/app-launch.ts`
-解析開啟方式與選擇 launcher 型別；明確的 `ui.launch` 可覆寫預設。
-只有沒有 web service 的 SDK 原生 App 省略時才預設 `dsm-window`。
+Bridge readiness is availability only: declared App health + loopback TCP + the current-version SDK lifecycle acquire generation. It cannot attest actual image/project/generation: another process already executing on the NAS can occupy the port. This local-code-execution threat is accepted; restore official full readback when available. Never use root, Docker socket access or borrowed admin credentials. See compose.md.

package/skills/reference/wrap.md

@@ -1,45 +1,16 @@
-# 封裝（Wrap）
+# 封裝上游 Compose
 
-已有 Compose 或要補齊 App Contract 時使用。權威仍是 schema + `check`。
+只使用 schema-2 `dsm-package.yaml`。先讀 [compose.md](compose.md) 的宣告、支援表及 DSM 阻擋條件，再讀 [identity-gateway.md](identity-gateway.md) 決定 none／header／token／OIDC。不架 SSO Server，也不需要假 backend 或 wrapper container。
 
-## 命令
-
-```bash
-synopkgland check      # 契約、Compose 意圖與 Web entry 提示
+```sh
+synopkgland init -t compose --from ./compose.yaml my-app
+synopkgland check --json
+synopkgland build --arch x86_64
+synopkgland inspect dist/MyApp-x86_64.spk --json
 ```
 
-## 契約允許什麼（v1 schema 1）
-
-必填：`schema`、`package`、`version`、`displayname`、`description`、`maintainer`、`os_min_ver`。
-
-
-
-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。
-- `adminport` 必須對應到某 service 的 published TCP port。
-- `install` 參數須在 `compose.yaml` 以 `${NAME}` 引用。
-
-## 包現成 Compose 的掛載
-
-容器路徑跟映像／upstream 的 container target 走，原樣保留；只把 host source 換成 `${NAME}` 這類 install parameter。原有的 upstream named volume mount 與頂層 `volumes:` 宣告也保留，不要為了套模板改成 `/data`。需要既有 Share 時，管理員在安裝時選這台 NAS 的 Share。
-
-修復方式：看 `check` 輸出的 `[錯誤碼]` 與 `Suggestion:` 行，對照 `diagnose.md`。**不要**為了過驗證而亂改 runtime 語意。
-
-## 下一步
-
-- 要身分／檔案整合 → `identity.md`／`files.md`
-- 要上 NAS → `deploy.md`
+上游 bytes 不改；CLI 只做工具，SDK reference planner 產生 override 與 worker 單檔。修正錯誤時看 code／原因／建議，不為通過驗證改掉上游語義。共用 launch resolver 解析 ui.launch，預設 new-page；classless gateway 使用 type url。
 
-## 開啟方式
+容器使用固定套件身分，不繼承登入者 File Station ACL。Shared Folder 需 composeMounts 明確 opt-in，安裝後由 admin 確認；官方 protected ACL／project control 未驗證前只啟動 SDK 設定頁，不 acquire 上游，不用 host root 繞過。每使用者檔案權限需 session／Broker Adapter，本次不做。
 
-Docker／web service App 的 `integration.web.launch` 內建預設為 `new-page`。
-主選單與套件中心開啟既有 gateway，不產生 Application Portal。
-schema 1 新分頁 launcher 使用 `type: "url"` 與明確 `url`；DSM 的 standalone
-會改寫成需要 AppWindow JS class 的 launchApp 頁面。schema 2 SDK wrapper
-有此 class，因此使用 standalone。只有 `access: public` 需要 Web Station alias。
-SDK 原生 App 的 `ui.launch` 內建預設是 `dsm-window`；非 UI SDK 前端明寫 `new-page`。
+交付 inspect 的 upstream／effective hashes、image digests、run-as、mount、egress 與 acceptance blockers。Linux 通過不代表 DSM 已驗收。部署請讀 [deploy.md](deploy.md)，保留資料並由專用 thread 驗 final SPK digest。

package/assets/go/daemon/fixture_linux_test.go

@@ -1,15 +0,0 @@
-//go:build linux
-
-package main
-
-import (
-	"os"
-	"os/exec"
-	"syscall"
-)
-
-func dropFixtureUser(cmd *exec.Cmd) {
-	if os.Geteuid() == 0 {
-		cmd.SysProcAttr = &syscall.SysProcAttr{Credential: &syscall.Credential{Uid: 65534, Gid: 65534, Groups: []uint32{65534}}}
-	}
-}

package/assets/go/daemon/fixture_other_test.go

@@ -1,7 +0,0 @@
-//go:build !linux
-
-package main
-
-import "os/exec"
-
-func dropFixtureUser(cmd *exec.Cmd) {}

package/assets/go/daemon/go.mod

@@ -1,5 +0,0 @@
-module synopkgland-daemon
-
-go 1.24
-
-toolchain go1.26.9