@synopackageland/cli 0.4.1 → 0.5.0

package/dist/cli.js

@@ -1,3 +1,4 @@
+import { isNativeLayout, loadNativeLayout, buildNativeLayout } from "./standalone/native-layout.js";
 import { planDeployment, deployStandalone } from "./deploy/plan.js";
 import { Command } from "commander";
 import { readFileSync, renameSync } from "node:fs";
@@ -6,12 +7,14 @@ import { findProjectRoot } from "./discovery.js";
 import { loadContract } from "./contract/load.js";
 import { formatErrors } from "./errors.js";
 import { formatInspectReport, inspectProject } from "./inspect.js";
+import { formatPinReport, pinProjectImages } from "./images/pin.js";
 import { initFromTemplate, isTemplateName, listTemplates } from "./init.js";
 import { validateProject } from "./validate.js";
 import { runDev } from "./dev.js";
 import { testProject } from "./test-command.js";
 import { buildSpk } from "./build-spk/generator.js";
-import { isNativeArchFamily } from "./build-spk/dsm-arch.js";
+import { isNativeArchFamily, NATIVE_ARCH_FAMILIES, parseArchList } from "./build-spk/dsm-arch.js";
+import { DEFAULT_MIN_DSM, CONTAINER_MIN_DSM } from "./build-spk/dsm-version.js";
 import { deployProject } from "./deploy/deploy.js";
 import { createNasHost } from "./host/dsm-client.js";
 import { projectInfo, formatProjectInfo } from "./info.js";
@@ -75,8 +78,8 @@ function requireProject(cwd, project) {
     }
     return found;
 }
-async function buildStandaloneCommand(root, arch, options) {
-    if (options.output && !arch) {
+async function buildStandaloneCommand(root, arches, options) {
+    if (options.output && arches?.length !== 1) {
         console.error("-o 只能搭配 --arch 建置單一架構；多架構請用 --out-dir。");
         process.exit(1);
     }
@@ -84,7 +87,7 @@ async function buildStandaloneCommand(root, arch, options) {
         ? dirname(resolve(process.cwd(), options.output))
         : options.outDir ? resolve(process.cwd(), options.outDir) : undefined;
     try {
-        const { outputs } = await buildStandalone({ root, arches: arch ? [arch] : undefined, outDir });
+        const { outputs } = await buildStandalone({ root, arches, outDir, minDsm: options.minDsm });
         for (let output of outputs) {
             if (options.output) {
                 const target = resolve(process.cwd(), options.output);
@@ -99,6 +102,46 @@ async function buildStandaloneCommand(root, arch, options) {
         process.exit(1);
     }
 }
+const MIN_DSM_HELP = `最低 DSM 版本（INFO os_min_ver）：7.0、7.1、7.2、7.2.1 或完整的 7.x-build（例如 7.2.1-69057）；省略時用專案宣告的值（native-go／binary 預設 DSM ${DEFAULT_MIN_DSM}，容器模板 ${CONTAINER_MIN_DSM}）`;
+const ARCH_REQUIRED = ["NATIVE_ARCH_FAMILY_REQUIRED", "GATEWAY_ARCH_FAMILY_REQUIRED"];
+/**
+ * Container / binary App: an architecture-neutral App builds one SPK. One that
+ * needs an architecture (binary, DSM gateway) builds one SPK per --arch family,
+ * all of them when --arch is omitted.
+ */
+async function buildContainerCommand(project, arches, options) {
+    const outputPath = options.output ? resolve(process.cwd(), options.output) : undefined;
+    const build = (archFamily, output = outputPath) => buildSpk({ project, outputPath: output, archFamily, minDsm: options.minDsm });
+    const fail = (errors) => {
+        console.error(`建置失敗：${errors.join(", ")}`);
+        return process.exit(1);
+    };
+    let results = [];
+    if (arches?.length === 1) {
+        results = [await build(arches[0])];
+    }
+    else {
+        const first = await build();
+        if (first.ok || !first.errors.every((code) => ARCH_REQUIRED.includes(code))) {
+            results = [first];
+        }
+        else {
+            if (outputPath) {
+                console.error("-o 只能搭配 --arch 建置單一架構；多架構請不要加 -o。");
+                process.exit(1);
+            }
+            const packageId = String(loadContract(project.contractPath).contract.package);
+            for (const arch of arches ?? NATIVE_ARCH_FAMILIES) {
+                results.push(await build(arch, join(project.root, `${packageId}-${arch}.spk`)));
+            }
+        }
+    }
+    for (const result of results) {
+        if (!result.ok)
+            fail(result.errors);
+        console.log(`已產生 ${result.outputPath}`);
+    }
+}
 export async function runCli(argv) {
     const program = new Command();
     program
@@ -112,7 +155,7 @@ export async function runCli(argv) {
         const global = command.parent?.opts() ?? {};
         const standalone = standaloneRoot(process.cwd(), global.project);
         if (standalone) {
-            const loaded = loadStandaloneManifest(standalone);
+            const loaded = isNativeLayout(standalone) ? loadNativeLayout(standalone) : loadStandaloneManifest(standalone);
             if (!loaded.ok) {
                 console.error(loaded.errors.map((e) => `[${e.code}] ${e.message}`).join("\n"));
                 process.exit(1);
@@ -158,6 +201,29 @@ export async function runCli(argv) {
         const report = inspectProject(project);
         console.log(formatInspectReport(report));
     });
+    const images = program
+        .command("images")
+        .description("Container image 工具");
+    images
+        .command("pin")
+        .description("讀取 compose.yaml 的 image，向 registry 取得 manifest digest，改寫為 tag@sha256:...")
+        .option("--check", "只報告未 pin 或已過期的 image，不寫入；有問題時 exit 1")
+        .action(async (options, command) => {
+        const global = command.parent?.parent?.opts() ?? {};
+        const project = requireProject(process.cwd(), global.project);
+        const check = options.check === true;
+        try {
+            const result = await pinProjectImages({ project, check });
+            console.log(formatPinReport(result, { check }));
+            if (check && result.findings.length > 0) {
+                process.exit(1);
+            }
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    });
     program
         .command("init")
         .description("從模板建立 App 專案（不覆蓋既有檔案）")
@@ -165,11 +231,18 @@ export async function runCli(argv) {
         .option("--binary", "建立 Binary App：以套件自己的帳號執行預先建置的 binary（等同 -t binary）")
         .option("--package <id>", "native-go：INFO.package（預設由目錄名產生，例如 photo-tagger → PhotoTagger）")
         .option("--name <display>", "native-go：顯示名稱（預設由目錄名產生）")
-        .option("--privilege <none|root>", "native-go：root 另加由 DSM 管理員在套件視窗核准的 root 操作（預設 none）")
-        .option("--ui <plain|vue>", `native-go：沿用 UI ${JSON.parse(readFileSync(join(templatesRoot(), "native-go-vue/frontend/package.json"), "utf8")).dependencies["@synopackageland/ui"]} 的 Vue 介面（預設 plain）`)
-        .option("--integration <go|better-auth>", "native-go --ui vue：每包 helper 與私有範例；better-auth 才加入 Node")
-        .option("--integration-protocol <1|2>", "helper inventory protocol（預設 1）；2 可選 NAS data policy，缺已認證 adapters 仍拒絕")
-        .option("--data-access <unavailable|relaxed>", "protocol 2 build-time 身分模式（預設 unavailable）；relaxed 不繞過 DSM／App／lifecycle gates")
+        .option("--privilege <none|root>", "native-go：root 另加由 DSM 管理員在套件視窗核准的 root 操作；與 --integration 並用時才加入特權 helper（預設 none）")
+        .option("--ui <plain|vue>", `native-go：UI 實作；預設 vue（沿用 UI ${JSON.parse(readFileSync(join(templatesRoot(), "native-go-vue/frontend/package.json"), "utf8")).dependencies["@synopackageland/ui"]} 的 DSM 左右分欄版面）；plain 為舊的純 JS UI`)
+        .option("--background", "native-go（預設 --ui vue）：以套件帳號執行的背景工作（systemd user unit + 固定 sha256-v1 worker；僅管理員；可併用 --integration go、--file-station，不可併用 --privilege root）")
+        .option("--file-station", "native-go：以使用者自己的 DSM session 提供互動 File Station 路由，由套件帳號執行、不需 root（不保存 session，不支援離線 job）")
+        .option("--shared-folder <select|create>", "native-go：安裝精靈選擇既有共用資料夾（select），或由 DSM data-share 建立專屬共用資料夾（create，需 --shared-folder-name）；解除安裝不會刪除共用資料夾")
+        .option("--shared-folder-name <name>", "--shared-folder create：要建立的共用資料夾名稱")
+        .option("--shared-folder-key <key>", "--shared-folder：精靈變數與 var/config.json 的鍵（預設 shared）")
+        .option("--shared-folder-permission <ro|rw>", "--shared-folder：套件帳號需要的權限（預設 rw）")
+        .option("--integration <go|better-auth>", "native-go（預設 --ui vue）：以套件帳號執行的私有範例，不含 helper（加 --privilege root 才有每包 helper）；better-auth 才加入 Node")
+        .option("--integration-protocol <1|2>", "helper inventory protocol（需要 --privilege root；預設 1）；2 可選 NAS data policy，缺已認證 adapters 仍拒絕")
+        .option("--data-access <unavailable|relaxed>", "protocol 2 build-time 身分模式（需要 --privilege root；預設 unavailable）；relaxed 不繞過 DSM／App／lifecycle gates")
+        .option("--min-dsm <version>", `新專案的最低 DSM 版本（os_min_ver）：7.0、7.1、7.2、7.2.1 或完整的 7.x-build（native-go／binary 預設 ${DEFAULT_MIN_DSM}，容器模板 ${CONTAINER_MIN_DSM}）`)
         .argument("[dir]", "目標目錄", ".")
         .addHelpText("after", `
 模板分兩類：
@@ -183,9 +256,11 @@ export async function runCli(argv) {
 
 快速開始（native-go，需要 Go 1.24+）：
   synopkgland init -t native-go my-app
-  cd my-app && $EDITOR backend/internal/app/routes.go ui/app.js
+  cd my-app && $EDITOR backend/internal/app/routes.go frontend/src/App.vue
   synopkgland build-spk          # → dist/<Package>-<version>-<arch>.spk
-  synopkgland inspect --spk dist/<file>.spk`)
+  synopkgland inspect --spk dist/<file>.spk
+
+UI 預設為 --ui vue（DSM 左右分欄）；--ui plain 使用舊的 ui/app.js。`)
         .action(async (dir, options, command) => {
         const global = command.parent?.opts() ?? {};
         if (global.project) {
@@ -210,9 +285,13 @@ export async function runCli(argv) {
             initFromTemplate(template, targetDir, {
                 packageId: options.package,
                 displayName: options.name,
+                minDsm: options.minDsm,
                 privilege: options.privilege,
                 ui: options.ui,
                 integration: options.integration,
+                background: options.background === true,
+                fileStation: options.fileStation === true,
+                sharedFolder: options.sharedFolder === undefined ? undefined : { mode: options.sharedFolder, name: options.sharedFolderName, key: options.sharedFolderKey, permission: options.sharedFolderPermission },
                 integrationProtocol: options.integrationProtocol === undefined ? undefined : (["1", "2"].includes(options.integrationProtocol) ? Number(options.integrationProtocol) : NaN),
                 dataAccess: options.dataAccess,
             });
@@ -282,7 +361,7 @@ export async function runCli(argv) {
         .command("deploy")
         .description("建置獨立 SPK 並直接安裝到 DSM")
         .option("--host <name>", "synoagentcli profile 或 NAS 名稱")
-        .option("--arch <family>", "native App 的目標架構：x86_64 或 aarch64（省略時由 NAS 判定）")
+        .option("--arch <family>", `native App 的目標架構：${NATIVE_ARCH_FAMILIES.join(" 或 ")}（省略時由 NAS 判定）`)
         .option("--dev", "部署到 Development Package Identity（{package}.dev）")
         .option("--share <slot=name>", "此 NAS 上的 Shared Folder 邏輯名（契約 shared_folder 槽，可重複）", collectShareOption)
         .option("--run-as <slot=name>", "此 NAS 上的 DSM 使用者邏輯名（契約 dsm_user 槽）", collectRunAsOption)
@@ -291,7 +370,7 @@ export async function runCli(argv) {
         .action(async (options, command) => {
         const global = command.parent?.opts() ?? {};
         if (options.arch !== undefined && !isNativeArchFamily(String(options.arch))) {
-            throw new Error('--arch accepts x86_64 or aarch64');
+            throw new Error(`--arch accepts ${NATIVE_ARCH_FAMILIES.join(" or ")}`);
         }
         const plan = planDeployment(resolve(process.cwd(), global.project ?? '.'), {
             arch: options.arch, dev: options.dev,
@@ -330,7 +409,7 @@ export async function runCli(argv) {
         }
         try {
             if (options.arch !== undefined && !isNativeArchFamily(String(options.arch))) {
-                console.error(`--arch 只接受 x86_64 或 aarch64，收到 ${String(options.arch)}。`);
+                console.error(`--arch 只接受 ${NATIVE_ARCH_FAMILIES.join("、")}，收到 ${String(options.arch)}。`);
                 process.exit(1);
             }
             const result = await deployProject({
@@ -444,30 +523,51 @@ export async function runCli(argv) {
         .description("產生本機未簽署 SPK：容器 App（synology-app.yaml）或 Standalone Package（dsm-package.yaml，會先編譯 UI 與 Go）")
         .option("-o, --output <path>", "輸出 .spk 路徑（Standalone Package 只在建置單一架構時可用）")
         .option("--out-dir <dir>", "Standalone Package：輸出目錄（預設 dist/）")
-        .option("--arch <family>", "目標架構：x86_64 或 aarch64（native App 必填；Standalone Package 預設建置 arches 全部）")
+        .option("--arch <families>", `目標架構，可用逗號列出多個，例如 x86_64,aarch64（可填：${NATIVE_ARCH_FAMILIES.join("、")}；省略時兩者都建，每個架構各產一個 SPK）`)
+        .option("--min-dsm <version>", MIN_DSM_HELP)
+        .option("--build <number>", "Native layout: override DSM build number")
         .action(async (options, command) => {
         const global = command.parent?.opts() ?? {};
-        if (options.arch !== undefined && !isNativeArchFamily(String(options.arch))) {
-            console.error(`--arch 只接受 x86_64 或 aarch64，收到 ${String(options.arch)}。`);
+        const layoutRoot = standaloneRoot(process.cwd(), global.project);
+        if (layoutRoot && isNativeLayout(layoutRoot)) {
+            try {
+                if (options.minDsm)
+                    throw new Error("Native layout: set os_min_ver in dsm-package.yaml");
+                const arches = options.arch === undefined ? undefined : String(options.arch).split(",");
+                if (options.output && arches?.length !== 1)
+                    throw new Error("-o requires exactly one --arch");
+                const result = await buildNativeLayout({ root: layoutRoot, arches, build: options.build === undefined ? undefined : Number(options.build), outDir: options.outDir ? resolve(options.outDir) : undefined });
+                for (const output of result.outputs) {
+                    if (options.output)
+                        renameSync(output, resolve(options.output));
+                    console.log(`已產生 ${options.output ?? output}`);
+                }
+            }
+            catch (e) {
+                console.error(String(e));
+                process.exit(1);
+            }
+            return;
+        }
+        if (options.build !== undefined) {
+            console.error("--build requires native layout");
+            process.exit(1);
+        }
+        let arches;
+        try {
+            arches = options.arch === undefined ? undefined : parseArchList(String(options.arch));
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
             process.exit(1);
         }
-        const archFamily = options.arch ? String(options.arch) : undefined;
         const standalone = standaloneRoot(process.cwd(), global.project);
         if (standalone) {
-            await buildStandaloneCommand(standalone, archFamily, options);
+            await buildStandaloneCommand(standalone, arches, options);
             return;
         }
         const project = requireProject(process.cwd(), global.project);
-        const result = await buildSpk({
-            project,
-            outputPath: options.output ? resolve(process.cwd(), options.output) : undefined,
-            archFamily,
-        });
-        if (!result.ok) {
-            console.error(`建置失敗：${result.errors.join(", ")}`);
-            process.exit(1);
-        }
-        console.log(`已產生 ${result.outputPath}`);
+        await buildContainerCommand(project, arches, options);
     });
     await program.parseAsync(argv);
 }

package/dist/compose/analyze.d.ts

@@ -9,6 +9,18 @@ export interface ParsedCompose {
 export declare function loadCompose(composePath: string): ParsedCompose | null;
 export declare function listServiceNames(compose: ComposeDocument): string[];
 export declare function extractPublishedTcpPorts(service: ComposeService): number[];
+export interface PortExposure {
+    service: string;
+    /** The Compose entry, as written (long form entries as JSON). */
+    entry: string;
+    /** Published host port when it is a single number. */
+    hostPort?: number;
+    containerPort?: string;
+    /** Reachable only from the NAS itself (127.0.0.0/8 or ::1). */
+    loopbackOnly: boolean;
+}
+/** Every way a Compose service is reachable from outside its container network. */
+export declare function listPortExposures(compose: ComposeDocument): PortExposure[];
 export declare function collectPublishedTcpPorts(compose: ComposeDocument): Map<number, string[]>;
 export type ResourceWorkerIneligibleReason = "HAS_INSTALL_PARAMETERS" | "HAS_COMPOSE_INTERPOLATION" | "HAS_COMPOSE_SECRETS_OR_CONFIGS" | "HAS_BUILD_STANZA" | "HAS_PRIVILEGED_CAPABILITY" | "WEB_APP_MISSING_OR_AMBIGUOUS_ADMINPORT";
 export interface ResourceWorkerEligibility {
@@ -28,6 +40,12 @@ export interface ResourceWorkerEligibility {
  * - any non-headless App without a unique literal published adminport status probe
  */
 export declare function resourceWorkerEligibility(contract: AppContract, compose: ComposeDocument): ResourceWorkerEligibility;
+export interface UnpinnedImage {
+    service: string;
+    image: string;
+}
+/** Service images a registry can move: anything without a trailing `@sha256:<64 hex>` digest. */
+export declare function collectUnpinnedImages(compose: ComposeDocument): UnpinnedImage[];
 export type ComposeRoute = "static-zero-config" | "dynamic" | "reject";
 export interface ComposeRouteClassification {
     route: ComposeRoute;
@@ -65,4 +83,6 @@ export declare function validateComposeRunAs(compose: ComposeDocument, composeFi
     hasSharedFolder: boolean;
     hasDsmUser?: boolean;
 }): ValidationError[];
+/** The gateway is the only door: the container's web port must not be reachable except through it. */
+export declare function validateGatewayPortLoopback(adminport: number, compose: ComposeDocument, composeFile: string): ValidationError[];
 export declare function validateAdminPortMapping(adminport: number, compose: ComposeDocument, composeFile: string): ValidationError[];

package/dist/compose/analyze.js

@@ -66,30 +66,76 @@ export function extractPublishedTcpPorts(service) {
     }
     return published;
 }
-function parsePortEntry(entry) {
+/** Splits `[ip:]host:container[/proto]`, `[ip:]container` and the long form. */
+function splitPortEntry(entry) {
     if (typeof entry === "number") {
-        return entry;
+        return { hostPort: String(entry) };
     }
     if (typeof entry === "string") {
         const trimmed = entry.trim();
         if (!trimmed || trimmed.startsWith("/")) {
             return null;
         }
-        const hostPart = trimmed.split(":")[0]?.replace(/^\[/, "").replace(/\]$/, "");
-        const parsed = Number(hostPart);
-        return Number.isInteger(parsed) ? parsed : null;
+        let rest = trimmed;
+        let hostIp;
+        if (rest.startsWith("[")) {
+            const close = rest.indexOf("]");
+            if (close < 0) {
+                return null;
+            }
+            hostIp = rest.slice(1, close);
+            rest = rest.slice(close + 1).replace(/^:/, "");
+        }
+        const parts = rest.split("/")[0].split(":");
+        if (hostIp === undefined && parts.length === 3) {
+            hostIp = parts.shift();
+        }
+        return { ...(hostIp ? { hostIp } : {}), hostPort: parts[0], containerPort: parts[parts.length - 1] };
     }
     if (entry && typeof entry === "object") {
         const record = entry;
-        if (typeof record.published === "number") {
-            return record.published;
-        }
-        if (typeof record.target === "number" && record.published === undefined) {
-            return record.target;
-        }
+        const hostIp = typeof record.host_ip === "string" && record.host_ip ? record.host_ip : undefined;
+        const published = record.published ?? record.target;
+        return {
+            ...(hostIp ? { hostIp } : {}),
+            ...(typeof published === "number" || typeof published === "string" ? { hostPort: String(published) } : {}),
+            ...(typeof record.target === "number" ? { containerPort: String(record.target) } : {}),
+        };
     }
     return null;
 }
+function parsePortEntry(entry) {
+    if (entry && typeof entry === "object" && typeof entry.published === "string") {
+        return null;
+    }
+    const hostPort = Number(splitPortEntry(entry)?.hostPort);
+    return Number.isInteger(hostPort) ? hostPort : null;
+}
+function isLoopbackAddress(address) {
+    return address !== undefined && (address === "::1" || /^127(\.\d{1,3}){3}$/.test(address));
+}
+/** Every way a Compose service is reachable from outside its container network. */
+export function listPortExposures(compose) {
+    const exposures = [];
+    for (const [service, definition] of Object.entries(compose.services ?? {})) {
+        if (definition.network_mode === "host") {
+            exposures.push({ service, entry: "network_mode: host", loopbackOnly: false });
+        }
+        const ports = definition.ports;
+        for (const entry of ports ? (Array.isArray(ports) ? ports : [ports]) : []) {
+            const parsed = splitPortEntry(entry);
+            const hostPort = parsePortEntry(entry);
+            exposures.push({
+                service,
+                entry: typeof entry === "string" ? entry : JSON.stringify(entry),
+                ...(hostPort === null ? {} : { hostPort }),
+                ...(parsed?.containerPort ? { containerPort: parsed.containerPort } : {}),
+                loopbackOnly: isLoopbackAddress(parsed?.hostIp),
+            });
+        }
+    }
+    return exposures;
+}
 export function collectPublishedTcpPorts(compose) {
     const result = new Map();
     if (!compose.services) {
@@ -180,6 +226,18 @@ function hasBuildStanza(compose) {
     }
     return Object.values(compose.services).some((service) => "build" in service && service.build !== undefined);
 }
+const DIGEST_PINNED_IMAGE = /@sha256:[0-9a-f]{64}$/i;
+/** Service images a registry can move: anything without a trailing `@sha256:<64 hex>` digest. */
+export function collectUnpinnedImages(compose) {
+    const unpinned = [];
+    for (const [service, definition] of Object.entries(compose.services ?? {})) {
+        const image = definition.image;
+        if (typeof image === "string" && !DIGEST_PINNED_IMAGE.test(image)) {
+            unpinned.push({ service, image });
+        }
+    }
+    return unpinned;
+}
 const HEADLESS_UNSUPPORTED_REASONS = new Set([
     "HAS_COMPOSE_SECRETS_OR_CONFIGS",
     "HAS_BUILD_STANZA",
@@ -811,6 +869,12 @@ export function validateComposeRunAs(compose, composeFile, context) {
     }
     return errors;
 }
+/** The gateway is the only door: the container's web port must not be reachable except through it. */
+export function validateGatewayPortLoopback(adminport, compose, composeFile) {
+    return listPortExposures(compose)
+        .filter((exposure) => exposure.hostPort === adminport && !exposure.loopbackOnly)
+        .map((exposure) => makeError("COMPOSE_GATEWAY_PORT_EXPOSED", composeSpanForPath(compose, composeFile, `services.${exposure.service}.ports`), `${exposure.service} 的 port ${exposure.entry} 綁在所有網路介面上，不經 DSM 驗證就能直接連到容器。`, `請改成只綁 loopback：\"127.0.0.1:${adminport}:${exposure.containerPort ?? adminport}\"，或在 synology-app.yaml 的 integration.web.access 明確選 public。`));
+}
 export function validateAdminPortMapping(adminport, compose, composeFile) {
     const published = collectPublishedTcpPorts(compose);
     const services = published.get(adminport) ?? [];

package/dist/contract/validate.js

@@ -3,7 +3,7 @@ import { dirname, join } from "node:path";
 import { contractSpan, makeError } from "../errors.js";
 import { collectInstallParameters, getValuePosition, stringViolations, } from "./load.js";
 import { validateContractSchema } from "./schema-validate.js";
-import { isWebLaunchMode, readWebIntegration } from "./web-launch.js";
+import { DSM_GROUP_NAME, isWebAccessMode, isWebLaunchMode, readWebIntegration } from "./web-launch.js";
 import { loadCompose } from "../compose/analyze.js";
 import { collectPosixAllSharesParameters, isPosixAllSharesType, validatePosixAllSharesSources, } from "./posix-all-shares.js";
 import { getErrorCode } from "../error-registry.js";
@@ -52,6 +52,7 @@ export function validateContract(parsed, contractFile) {
     errors.push(...validateInstallParameters(parsed, contractFile));
     errors.push(...validatePosixAllShares(parsed, contractFile));
     errors.push(...validateWebLaunch(parsed, contractFile));
+    errors.push(...validateWebAccess(parsed, contractFile));
     return errors;
 }
 function validatePosixAllShares(parsed, contractFile) {
@@ -87,6 +88,37 @@ function validateWebLaunch(parsed, contractFile) {
     }
     return errors;
 }
+function validateWebAccess(parsed, contractFile) {
+    const { contract, doc } = parsed;
+    const web = readWebIntegration(contract);
+    if (!web || (web.access === undefined && web.groups === undefined)) {
+        return [];
+    }
+    const at = (key) => {
+        const pos = getValuePosition(doc, ["integration", "web", key]) ?? { line: 1, column: 1 };
+        return contractSpan(contractFile, pos.line, pos.column, `integration.web.${key}`);
+    };
+    if (contract.adminport === undefined) {
+        return [
+            makeError("CONTRACT_ACCESS_REQUIRES_WEB", at(web.access !== undefined ? "access" : "groups"), "Headless App 沒有網頁入口，不需要 access 或 groups。", "請省略 integration.web.access／groups，或補上對應 Compose published port 的 adminport。"),
+        ];
+    }
+    if (web.access !== undefined && !isWebAccessMode(web.access)) {
+        return [
+            makeError("CONTRACT_ACCESS_INVALID", at("access"), "integration.web.access 只能是 dsm-users、dsm-admins、dsm-groups 或 public。", "請改為 dsm-users（已登入的 DSM 使用者，預設）、dsm-admins、dsm-groups（需搭配 groups），或明確選 public 以保留匿名 Web Station 入口。"),
+        ];
+    }
+    const groups = web.groups;
+    const groupsValid = Array.isArray(groups) &&
+        groups.length > 0 &&
+        groups.every((g) => typeof g === "string" && DSM_GROUP_NAME.test(g));
+    if (web.access === "dsm-groups" ? !groupsValid : groups !== undefined) {
+        return [
+            makeError("CONTRACT_ACCESS_GROUPS_INVALID", at("groups"), "integration.web.groups 必須搭配 access: dsm-groups，且是 DSM 本機群組或完整 DOMAIN\\group／group@domain 名稱（網域最長 64、群組最長 128 字元）的非空清單。", "請改用 access: dsm-groups 並列出群組名稱，或移除 groups。"),
+        ];
+    }
+    return [];
+}
 function validateDeveloperString(value, contractFile, path, pos) {
     const errors = [];
     const violations = stringViolations(value);

package/dist/contract/web-launch.d.ts

@@ -7,11 +7,33 @@ export declare const DEFAULT_WEB_LAUNCH_MODE: WebLaunchMode;
 export interface WebIntegration {
     launch?: unknown;
     cookies?: unknown;
+    access?: unknown;
+    groups?: unknown;
 }
 export declare function readWebIntegration(contract: AppContract): WebIntegration | undefined;
 export declare function isWebLaunchMode(value: unknown): value is WebLaunchMode;
 export declare function resolvedWebLaunch(contract: AppContract): WebLaunchMode | undefined;
+export declare const WEB_ACCESS_MODES: readonly ["dsm-users", "dsm-admins", "dsm-groups", "public"];
+export type WebAccessMode = (typeof WEB_ACCESS_MODES)[number];
+export declare const DEFAULT_WEB_ACCESS_MODE: WebAccessMode;
+/** Local or qualified directory group names (exact case and domain); also what the gateway accepts at startup. */
+export declare const DSM_GROUP_NAME: RegExp;
+export declare function isWebAccessMode(value: unknown): value is WebAccessMode;
+export interface WebAccess {
+    mode: WebAccessMode;
+    groups: string[];
+}
+/**
+ * Who may open a web App. Defaults to every signed-in DSM user; `public` is the
+ * explicit opt-out that keeps the anonymous Web Station portal. Undefined for a
+ * headless App or an access rule validation already rejects.
+ */
+export declare function resolvedWebAccess(contract: AppContract): WebAccess | undefined;
+/** True when the App's container is reached only through the DSM-authenticated gateway CGI. */
+export declare function usesAuthGateway(contract: AppContract): boolean;
 export declare function webStationAlias(packageId: string): string;
+/** DSM serves a package's `ui` directory under this root; the gateway CGI lives in it. */
+export declare function gatewayEntryPath(packageId: string, adminurl: unknown): string;
 export declare function trustedAppEntryPath(contract: AppContract): string;
 export declare const DSM_RESERVED_COOKIES: readonly ["id", "did"];
 export declare function extractContractCookieNames(contract: AppContract): string[];

package/dist/contract/web-launch.js

@@ -27,6 +27,35 @@ export function resolvedWebLaunch(contract) {
     }
     return isWebLaunchMode(launch) ? launch : undefined;
 }
+export const WEB_ACCESS_MODES = ["dsm-users", "dsm-admins", "dsm-groups", "public"];
+export const DEFAULT_WEB_ACCESS_MODE = "dsm-users";
+/** Local or qualified directory group names (exact case and domain); also what the gateway accepts at startup. */
+export const DSM_GROUP_NAME = /^(?:[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])/;
+export function isWebAccessMode(value) {
+    return WEB_ACCESS_MODES.includes(value);
+}
+/**
+ * Who may open a web App. Defaults to every signed-in DSM user; `public` is the
+ * explicit opt-out that keeps the anonymous Web Station portal. Undefined for a
+ * headless App or an access rule validation already rejects.
+ */
+export function resolvedWebAccess(contract) {
+    if (contract.adminport === undefined) {
+        return undefined;
+    }
+    const web = readWebIntegration(contract);
+    const mode = web?.access ?? DEFAULT_WEB_ACCESS_MODE;
+    if (!isWebAccessMode(mode)) {
+        return undefined;
+    }
+    const groups = Array.isArray(web?.groups) ? web.groups.filter((g) => typeof g === "string") : [];
+    return { mode, groups };
+}
+/** True when the App's container is reached only through the DSM-authenticated gateway CGI. */
+export function usesAuthGateway(contract) {
+    const access = resolvedWebAccess(contract);
+    return access !== undefined && access.mode !== "public";
+}
 export function webStationAlias(packageId) {
     const slug = packageId
         .toLowerCase()
@@ -37,7 +66,15 @@ export function webStationAlias(packageId) {
     }
     return `p${createHash("sha256").update(packageId).digest("hex").slice(0, 16)}`;
 }
+/** DSM serves a package's `ui` directory under this root; the gateway CGI lives in it. */
+export function gatewayEntryPath(packageId, adminurl) {
+    const path = typeof adminurl === "string" ? adminurl.trim().replace(/^\/+/, "") : "";
+    return `/webman/3rdparty/${packageId}/cgi/gateway.cgi/${path}`;
+}
 export function trustedAppEntryPath(contract) {
+    if (usesAuthGateway(contract)) {
+        return gatewayEntryPath(String(contract.package ?? ""), contract.adminurl);
+    }
     const alias = webStationAlias(String(contract.package ?? ""));
     const adminurl = String(contract.adminurl ?? "/").trim() || "/";
     const extra = adminurl.startsWith("/") ? adminurl : `/${adminurl}`;

package/dist/deploy/deploy.d.ts

@@ -1,3 +1,4 @@
+import type { CommandRunner } from "../standalone/build.js";
 import type { NativeArchFamily } from "../build-spk/dsm-arch.js";
 import type { ProjectRoot } from "../discovery.js";
 import type { NasHost } from "../host/types.js";
@@ -12,6 +13,8 @@ export interface DeployProjectOptions {
     shareValues?: Record<string, string>;
     runAsValues?: Record<string, string>;
     paramValues?: Record<string, string>;
+    /** Command runner for the DSM gateway's `go build` (tests inject a fake). */
+    gatewayRun?: CommandRunner;
 }
 export interface DeployProjectResult {
     ok: boolean;

package/dist/deploy/deploy.js

@@ -1,6 +1,7 @@
 import { buildSpk } from "../build-spk/generator.js";
 import { existsSync } from "node:fs";
 import { loadContract } from "../contract/load.js";
+import { usesAuthGateway } from "../contract/web-launch.js";
 import { findUnsupportedInstallTypes } from "../contract/unsupported-types.js";
 import { appOriginFromContract } from "../host/open-url.js";
 import { validateProject } from "../validate.js";
@@ -133,7 +134,7 @@ export async function deployProject(options) {
         ...shareResolved.extraValues,
         ...runAsResolved.extraValues,
     };
-    // The upgrade wizard deliberately ignores auto-filled Share controls unless
+    // The upgrade wizard deliberately ignores auto-filled Share and Run-as controls unless
     // the administrator opted into a change. Keep the CLI's explicit upgrade
     // flags equivalent to checking those controls.
     if (packageInstalled) {
@@ -142,6 +143,11 @@ export async function deployProject(options) {
                 extraValues[`CHANGE_${name}`] = "true";
             }
         }
+        for (const name of dsmUserParameterNames(contract)) {
+            if ((options.runAsValues?.[name] ?? "").trim() !== "") {
+                extraValues[`CHANGE_${name}`] = "true";
+            }
+        }
         for (const name of posixAllSharesNames) {
             if (explicitParamNames.has(name) && (paramValues[name] ?? "").trim() !== "") {
                 extraValues[`CHANGE_${name}`] = "true";
@@ -158,7 +164,9 @@ export async function deployProject(options) {
             message: error instanceof Error ? error.message : String(error) };
     }
     let archFamily = options.archFamily;
-    if (archFamily === undefined && options.project.nativePath && existsSync(options.project.nativePath)) {
+    const isNative = options.project.nativePath !== undefined && existsSync(options.project.nativePath);
+    // A DSM-authenticated web App ships a native gateway CGI, so it is built per architecture too.
+    if (archFamily === undefined && (isNative || usesAuthGateway(contract))) {
         archFamily = await options.host.getArchFamily?.();
         if (archFamily === undefined) {
             return {
@@ -174,6 +182,7 @@ export async function deployProject(options) {
         displayname: identity.displayname,
         spkVersion,
         archFamily,
+        gatewayRun: options.gatewayRun,
     });
     if (!build.ok || !build.outputPath) {
         return { ok: false, code: "BUILD_SPK_FAILED", message: build.errors.join(", ") };