@synopackageland/cli 0.6.0 → 0.7.0

package/dist/standalone/inspect-spk.js

@@ -1,21 +1,25 @@
-import { inspectExecutor } from "../runtime/executor-inspect.js";
+import { inspectNativeLayout } from "./native-layout.js";
+import { inspectExecutor, inspectExecutorAnchor } from "../runtime/executor-inspect.js";
 import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import * as tar from "tar";
 import { familyOfArchToken, NATIVE_ARCH_FAMILIES } from "../build-spk/dsm-arch.js";
-import { CONTAINER_MIN_DSM, isDsmAtLeast } from "../build-spk/dsm-version.js";
+import { CONTAINER_MIN_DSM, isDsmAtLeast, PORTAL_MIN_DSM } from "../build-spk/dsm-version.js";
 import { ELF_MACHINE } from "./binary.js";
-import { CGI_PAYLOAD_PATH } from "./dsm-window.js";
+import { CGI_PAYLOAD_PATH, entryLauncherAccess } from "./dsm-window.js";
 import { daemonConfig, readDaemon } from "./daemon.js";
 import { BACKGROUND_UNIT_DIR, BACKGROUND_WORKER_PAYLOAD, backgroundUnitName, renderBackgroundUnit } from "./background.js";
 import { renderStandaloneResource } from "./resource.js";
 import { recoverSharedFolder, renderSharedFolderUpgradeWizardFiles, sharedFolderInstallSteps, SHARED_FOLDER_MARKER } from "./shared-folder.js";
 import { renderInstallWizardFiles, renderNativeInstallWizard } from "../build-spk/install-wizard.js";
+import { renderDelegateScopeSteps, renderDelegateInstallDraft } from "../build-spk/delegate-scope.js";
 import { renderUninstallWizardFiles } from "../build-spk/uninstall-wizard.js";
 import { renderStandaloneScript } from "./lifecycle.js";
 import { listPortExposures, loadCompose } from "../compose/analyze.js";
 import { uninstallCleanup } from "../runtime/uninstall-cleanup.js";
+import { PORTAL_JSON_RELPATH, PORTAL_MUSTACHE_RELPATH, portalResource, renderPortalJson, renderPortalLifecycle, renderPortalMustache, renderPortalWizardStep } from "../portal/package.js";
+import { isPortalAlias } from "../portal/alias.js";
 const ROOT_SCRIPT_HINTS = [/\bsudo\b/, /\bchown\s+(-\w+\s+)*root\b/, /chmod\s+[ugo]*\+s\b/, /chmod\s+[2467][0-7]{3}\b/];
 /** Reads an SPK without installing it and reports how it would run on DSM. */
 export async function inspectStandaloneSpk(spkPath) {
@@ -27,6 +31,19 @@ export async function inspectSpk(spkPath, expectedKind) {
     try {
         await tar.x({ file: spkPath, cwd: dir });
         const findings = [];
+        if (!expectedKind && existsSync(join(dir, "native-layout.json"))) {
+            const info = readInfo(join(dir, "INFO"), findings, "native-layout");
+            const payload = await listPayload(join(dir, "package.tgz"), findings);
+            const target = join(dir, "layout-inspection");
+            mkdirSync(target);
+            await tar.x({ file: join(dir, "package.tgz"), cwd: target });
+            findings.push(...inspectNativeLayout(dir, target, info));
+            for (const key of ["package", "version", "arch", "os_min_ver", "checksum"])
+                if (!info[key])
+                    findings.push(`Missing INFO ${key}`);
+            return { kind: "native-layout", package: info.package, version: info.version, arch: info.arch,
+                signed: existsSync(join(dir, "syno_signature.asc")), payload, findings, capabilities: [] };
+        }
         const payload = await listPayload(join(dir, "package.tgz"), findings);
         const paths = new Set(payload.map(entry => entry.path));
         let metadata = {};
@@ -34,7 +51,7 @@ export async function inspectSpk(spkPath, expectedKind) {
         if (metadataText !== undefined) {
             try {
                 const raw = JSON.parse(metadataText);
-                if (raw.schema !== 2 || !["go", "binary"].includes(raw.backend) || !Array.isArray(raw.capabilities) || raw.capabilities.some((name) => !["files", "jobs", "identity", "rootOps", "delegate"].includes(String(name))) || new Set(raw.capabilities).size !== raw.capabilities.length)
+                if (raw.schema !== 2 || !["go", "binary"].includes(raw.backend) || !Array.isArray(raw.capabilities) || raw.capabilities.some((name) => !["files", "jobs", "identity", "rootOps", "delegate"].includes(String(name))) || new Set(raw.capabilities).size !== raw.capabilities.length || (raw.entry !== undefined && !["admin-only", "app-privilege"].includes(raw.entry)))
                     throw new Error();
                 metadata = raw;
             }
@@ -49,18 +66,19 @@ export async function inspectSpk(spkPath, expectedKind) {
         await checkArch(dir, info, kind, paths.has(CGI_PAYLOAD_PATH), findings);
         const background = kind === "native-go" && paths.has(BACKGROUND_WORKER_PAYLOAD);
         const sharedFolder = standalone ? recoverSharedFolder(readOptional(join(dir, "scripts/postinst"))) : undefined;
-        checkConf(dir, findings, kind, background, sharedFolder, info.package);
+        const portal = await recoverPortal(dir, info, kind === "container" ? info.package ?? "" : `SYNO.SDS.${info.package}.Instance`, paths, payload, findings);
+        if (portal && info.os_min_ver && OS_MIN_VER.test(info.os_min_ver) && !isDsmAtLeast(info.os_min_ver, PORTAL_MIN_DSM)) {
+            findings.push(`INFO os_min_ver「${info.os_min_ver}」低於 portal 需要的 DSM ${PORTAL_MIN_DSM}；DSM 7.1.1 以錯誤 320 拒裝帶 web-config app-portal 的未簽章套件，7.2 未驗證`);
+        }
+        checkConf(dir, findings, kind, background, sharedFolder, info.package, portal);
         checkScripts(dir, findings);
-        if (standalone)
-            checkSharedFolder(dir, findings, info.package, sharedFolder);
         checkUninstall(dir, findings);
         if (kind === "container")
             await checkContainerExposure(dir, join(dir, "package.tgz"), findings);
         const hasExecutor = (metadata.capabilities ?? []).some(name => name === "rootOps" || name === "delegate") || paths.has("executor/executor");
+        const daemon = standalone ? await checkDaemon(dir, info, paths, payload, findings, hasExecutor, background) : undefined;
         if (background)
-            checkBackground(dir, info, payload, findings, hasExecutor);
-        if (standalone)
-            await checkDaemon(dir, info, paths, payload, findings, hasExecutor);
+            checkBackground(dir, info, payload, findings, hasExecutor, daemon);
         let executor;
         if ((metadata.capabilities ?? []).some(name => name === "rootOps" || name === "delegate") || paths.has("executor/executor")) {
             const executorDir = join(dir, "executor-inspection");
@@ -69,6 +87,8 @@ export async function inspectSpk(spkPath, expectedKind) {
             const inspected = inspectExecutor(executorDir, info.package, info.arch);
             findings.push(...inspected.findings);
             executor = inspected.executor;
+            if (executor)
+                findings.push(...inspectExecutorAnchor(readFileSync(join(dir, "INFO"), "utf8"), executor.executorDigest));
             if (payload.find(p => p.path === "executor/executor")?.mode !== "0755")
                 findings.push("Executor must be executable.");
             if (payload.find(p => p.path === "executor/lifecycle")?.mode !== "0755")
@@ -85,6 +105,13 @@ export async function inspectSpk(spkPath, expectedKind) {
                     findings.push(`Executor WIZARD_UIFILES/${name} is missing cleanup guidance.`);
             }
         }
+        if (background && daemon && (executor?.policy.lifetime !== 'until-revoked' || !metadata.capabilities?.includes('delegate'))) {
+            findings.push('daemon/background combination requires an explicitly pinned until-revoked delegate policy.');
+        }
+        if (metadata.entry)
+            await checkEntryLauncher(dir, info.package, metadata.entry, findings);
+        if (standalone)
+            checkSharedFolder(dir, findings, info.package, sharedFolder, executor?.policy.scope === 'install-selected', portal);
         const cgiEntry = payload.find((entry) => entry.path === CGI_PAYLOAD_PATH);
         if (standalone && !cgiEntry) {
             findings.push(`payload 沒有 ${CGI_PAYLOAD_PATH}`);
@@ -95,6 +122,8 @@ export async function inspectSpk(spkPath, expectedKind) {
         return {
             kind,
             ...(executor ? { executor } : {}),
+            ...(portal ? { portal: { appId: portal.appId, alias: portal.alias } } : {}),
+            ...(metadata.entry ? { entry: metadata.entry } : {}),
             ...(standalone ? { uninstallCleanup: uninstallCleanup(info.package, hasExecutor) } : {}),
             package: info.package,
             version: info.version,
@@ -110,6 +139,23 @@ export async function inspectSpk(spkPath, expectedKind) {
         rmSync(dir, { recursive: true, force: true });
     }
 }
+/** The launcher in ui/config must carry exactly the access the declared entry mode fixes. */
+async function checkEntryLauncher(dir, pkg, entry, findings) {
+    const target = join(dir, "entry-inspection");
+    mkdirSync(target);
+    await tar.x({ file: join(dir, "package.tgz"), cwd: target, filter: path => path.replace(/^\.\//, "") === "ui/config" });
+    let launcher;
+    try {
+        const config = JSON.parse(readFileSync(join(target, "ui/config"), "utf8"));
+        launcher = Object.values(config)[0]?.[`SYNO.SDS.${pkg}.Instance`];
+    }
+    catch { /* reported below */ }
+    const expected = entryLauncherAccess(entry);
+    const fields = ["allUsers", "grantPrivilege", "advanceGrantPrivilege"];
+    if (!launcher || fields.some(field => launcher[field] !== expected[field])) {
+        findings.push(`ENTRY_LAUNCHER_MISMATCH sdk-package.json 宣告 entry: ${entry}，但 ui/config 的 launcher 不是 ${JSON.stringify(expected)}；請用 synopkgland build 重新產生`);
+    }
+}
 const OS_MIN_VER = /^7\.\d+(\.\d+)?-\d+$/;
 /** INFO os_min_ver and arch must be values DSM accepts, and arch must match the shipped CGI. */
 async function checkArch(dir, info, kind, hasCgi, findings) {
@@ -143,7 +189,7 @@ async function checkArch(dir, info, kind, hasCgi, findings) {
         findings.push(`INFO arch 宣告 ${declared}，但 ${CGI_PAYLOAD_PATH} 是 ${actual} 的執行檔`);
     }
 }
-async function checkDaemon(dir, info, paths, payload, findings, executor) {
+async function checkDaemon(dir, info, paths, payload, findings, executor, background) {
     if (![...paths].some(path => path.startsWith("daemon/")))
         return;
     if (info.precheckstartstop !== "yes")
@@ -164,13 +210,14 @@ async function checkDaemon(dir, info, paths, payload, findings, executor) {
             throw new Error("invalid config");
         if (payload.find(p => p.path === `daemon/payload/${daemon.exec}`)?.mode !== "0755")
             throw new Error("missing executable");
-        const manifest = { package: info.package, daemon, capabilities: executor ? { rootOps: true } : {} };
+        const manifest = { package: info.package, daemon, capabilities: { ...(executor ? { rootOps: true } : {}), ...(background ? { jobs: { worker: 'sha256-v1' } } : {}) } };
         if (readFileSync(join(unpacked, "daemon/config.json"), "utf8") !== daemonConfig(manifest))
             throw new Error("non-canonical daemon config");
         for (const hook of ["start-stop-status", "preupgrade", "preuninst"]) {
             if (readFileSync(join(dir, "scripts", hook), "utf8") !== renderStandaloneScript(hook, manifest))
                 findings.push(`daemon scripts/${hook} 與固定 lifecycle 不符`);
         }
+        return daemon;
     }
     catch {
         findings.push("daemon/config.json 或 payload 不符合固定 daemon 契約");
@@ -220,12 +267,12 @@ async function checkContainerExposure(dir, packageTgz, findings) {
 function readOptional(path) {
     return existsSync(path) ? readFileSync(path, "utf8") : undefined;
 }
-function checkConf(dir, findings, kind, background, sharedFolder, pkg) {
+function checkConf(dir, findings, kind, background, sharedFolder, pkg, portal) {
     const confDir = join(dir, "conf");
     const entries = existsSync(confDir) ? readdirSync(confDir) : [];
-    const nativeResource = kind !== "container" ? renderStandaloneResource({ package: pkg ?? "", capabilities: background ? { jobs: { worker: "sha256-v1" } } : {}, ...(sharedFolder ? { sharedFolder } : {}) }) : undefined;
+    const nativeResource = kind !== "container" ? renderStandaloneResource({ package: pkg ?? "", capabilities: background ? { jobs: { worker: "sha256-v1" } } : {}, ...(sharedFolder ? { sharedFolder } : {}) }, portal) : undefined;
     if (nativeResource !== undefined && readOptional(join(confDir, "resource")) !== nativeResource) {
-        findings.push(`conf/resource 必須是 ${nativeResource}（只有官方 data-share 與 systemd-user-unit，且與 install.sharedFolder 宣告一致）`);
+        findings.push(`conf/resource 必須是 ${nativeResource}（只有官方 data-share、systemd-user-unit 與 web-config，且與 install.sharedFolder、portal 宣告一致）`);
     }
     for (const name of entries) {
         if (name !== "privilege" && !(kind === "container" && name === "resource") && !(nativeResource !== undefined && name === "resource") && !(background && name === "systemd")) {
@@ -238,9 +285,11 @@ function checkConf(dir, findings, kind, background, sharedFolder, pkg) {
             if (!resource["docker-project"])
                 findings.push("container 缺少 docker-project resource");
             for (const key of Object.keys(resource)) {
-                if (!["docker-project", "webservice"].includes(key))
+                if (!["docker-project", "webservice", ...(portal ? ["web-config"] : [])].includes(key))
                     findings.push(`未知 container resource: ${key}`);
             }
+            if (portal && JSON.stringify(resource["web-config"]) !== JSON.stringify(portalResource()["web-config"]))
+                findings.push("container web-config 必須只有固定的 app-portal 註冊");
         }
         catch {
             findings.push("container 缺少有效的 conf/resource");
@@ -269,19 +318,21 @@ function checkConf(dir, findings, kind, background, sharedFolder, pkg) {
     }
 }
 /** The opt-in package user unit must be exactly what the generator writes. */
-function checkBackground(dir, info, payload, findings, executor) {
+function checkBackground(dir, info, payload, findings, executor, daemon) {
     const pkg = info.package;
     if (!pkg)
         return;
     const read = (path) => existsSync(join(dir, path)) ? readFileSync(join(dir, path), "utf8") : undefined;
     if (payload.find(p => p.path === BACKGROUND_WORKER_PAYLOAD)?.mode !== "0755")
         findings.push(`${BACKGROUND_WORKER_PAYLOAD} 缺少或非 executable`);
+    if (info.precheckstartstop !== "yes")
+        findings.push('background INFO 必須明確設定 precheckstartstop="yes"（prestart 復原失去 socket 的套件使用者 manager）');
     const units = existsSync(join(dir, BACKGROUND_UNIT_DIR)) ? readdirSync(join(dir, BACKGROUND_UNIT_DIR)) : [];
     const unit = backgroundUnitName(pkg);
     if (units.length !== 1 || units[0] !== unit || read(`${BACKGROUND_UNIT_DIR}/${unit}`) !== renderBackgroundUnit(pkg)) {
         findings.push(`${BACKGROUND_UNIT_DIR} 必須只有固定的 ${unit}（套件帳號執行，無 User=、無 root）`);
     }
-    if (read("scripts/start-stop-status") !== renderStandaloneScript("start-stop-status", { package: pkg, capabilities: { jobs: { worker: "sha256-v1" }, ...(executor ? { rootOps: true } : {}) } }))
+    if (read("scripts/start-stop-status") !== renderStandaloneScript("start-stop-status", { package: pkg, ...(daemon ? { daemon } : {}), capabilities: { jobs: { worker: "sha256-v1" }, ...(executor ? { rootOps: true } : {}) } }))
         findings.push("background scripts/start-stop-status 與固定 synosystemctl lifecycle 不符");
 }
 /**
@@ -290,7 +341,7 @@ function checkBackground(dir, info, payload, findings, executor) {
  * declaration (without one, any present file must be the default native
  * install wizard), and no other install/upgrade wizard file may exist.
  */
-function checkSharedFolder(dir, findings, pkg, folder) {
+function checkSharedFolder(dir, findings, pkg, folder, selected = false, portal) {
     const wizardDir = join(dir, "WIZARD_UIFILES");
     const present = (existsSync(wizardDir) ? readdirSync(wizardDir) : []).filter(name => /^(install|upgrade)_uifile(_|\.|$)/.test(name)).sort();
     const postinst = readOptional(join(dir, "scripts/postinst"));
@@ -298,27 +349,69 @@ function checkSharedFolder(dir, findings, pkg, folder) {
         findings.push("scripts/postinst 的 install.sharedFolder 宣告無效");
     if (!pkg)
         return;
-    const wizards = expectedWizardFiles(pkg, folder);
-    const source = folder ? "install.sharedFolder 宣告" : "native-go 預設安裝精靈";
-    // The default native wizard is optional; a declared shared folder needs all of its files.
-    for (const name of folder ? Object.keys(wizards) : present.filter(n => n in wizards)) {
+    const wizards = expectedWizardFiles(pkg, folder, selected, portal);
+    const source = selected ? "install-selected policy" : folder ? "install.sharedFolder 宣告" : portal ? "portal 宣告" : "native-go 預設安裝精靈";
+    // The default native wizard is optional; a declared shared folder or portal needs all of its files.
+    for (const name of folder || selected || portal ? Object.keys(wizards) : present.filter(n => n in wizards)) {
         if (readOptional(join(wizardDir, name)) !== wizards[name])
             findings.push(`WIZARD_UIFILES/${name} 與${source}不符`);
     }
     for (const name of present.filter(n => !(n in wizards)))
         findings.push(`WIZARD_UIFILES/${name} 不是${source}產生的精靈檔`);
+    if (selected) {
+        for (const hook of ['preinst', 'postinst']) {
+            if (!readOptional(join(dir, 'scripts', hook))?.includes(renderDelegateInstallDraft(pkg, hook === 'preinst')))
+                findings.push(`scripts/${hook} missing install-selected draft handling`);
+        }
+    }
     if (!folder)
         return;
     for (const hook of ["postinst", "postupgrade"]) {
-        if (readOptional(join(dir, "scripts", hook)) !== renderStandaloneScript(hook, { package: pkg, sharedFolder: folder })) {
+        if (readOptional(join(dir, "scripts", hook)) !== renderStandaloneScript(hook, { package: pkg, sharedFolder: folder, ...(selected ? { capabilities: { delegate: { scope: "install-selected" } } } : {}), ...portalManifest(portal) })) {
             findings.push(`scripts/${hook} 與 install.sharedFolder 宣告的固定腳本不符`);
         }
     }
 }
-function expectedWizardFiles(pkg, folder) {
-    const install = renderInstallWizardFiles(pkg, folder ? sharedFolderInstallSteps(pkg, folder) : renderNativeInstallWizard);
+function expectedWizardFiles(pkg, folder, selected = false, portal) {
+    const steps = selected ? (t) => [...renderDelegateScopeSteps(t), ...(folder ? sharedFolderInstallSteps(pkg, folder)(t) : [])] : folder ? sharedFolderInstallSteps(pkg, folder) : renderNativeInstallWizard;
+    const install = renderInstallWizardFiles(pkg, portal ? (t) => [...steps(t), renderPortalWizardStep(t, portal.alias)] : steps);
     return { ...install.static, ...install.dynamic, ...(folder ? renderSharedFolderUpgradeWizardFiles(pkg, folder) : {}) };
 }
+function portalManifest(portal) {
+    return portal ? { displayname: portal.application, portal: { alias: portal.alias } } : {};
+}
+/**
+ * The portal declaration is recovered from the payload's etc/portal.json. Its
+ * files and alias lifecycle must be exactly what the generator writes for the
+ * package's own DSM window (native AppInstance or Compose `.url` entry); activation is never part of the package.
+ */
+async function recoverPortal(dir, info, appId, paths, payload, findings) {
+    const files = [PORTAL_JSON_RELPATH, PORTAL_MUSTACHE_RELPATH];
+    if (!files.some(path => paths.has(path)))
+        return;
+    const unpacked = join(dir, "portal-inspection");
+    mkdirSync(unpacked);
+    await tar.x({ file: join(dir, "package.tgz"), cwd: unpacked, filter: path => files.includes(path.replace(/^\.\//, "")) });
+    try {
+        if (files.some(path => payload.find(p => p.path === path)?.mode !== "0644"))
+            throw new Error("mode");
+        const json = readFileSync(join(unpacked, PORTAL_JSON_RELPATH), "utf8");
+        const alias = JSON.parse(json).alias;
+        if (!isPortalAlias(alias))
+            throw new Error("alias");
+        const portal = { appId, application: info.displayname ?? "", alias };
+        if (json !== renderPortalJson(portal) || readFileSync(join(unpacked, PORTAL_MUSTACHE_RELPATH), "utf8") !== renderPortalMustache())
+            throw new Error("content");
+        for (const hook of ["preinst", "postinst", "postupgrade"]) {
+            if (!readOptional(join(dir, "scripts", hook))?.startsWith(`#!/bin/sh\n${renderPortalLifecycle(hook, portal)}`))
+                throw new Error(hook);
+        }
+        return portal;
+    }
+    catch {
+        findings.push("PORTAL_INVALID etc/portal.json、etc/portal.mustache 或 lifecycle 不符合固定 Application Portal 契約（應開啟套件自己的 DSM 視窗）");
+    }
+}
 function checkScripts(dir, findings) {
     const scriptsDir = join(dir, "scripts");
     if (!existsSync(join(scriptsDir, "start-stop-status"))) {

package/dist/standalone/lifecycle.js

@@ -1,27 +1,56 @@
-import { renderBackgroundControl, backgroundUnitName } from "./background.js";
+import { renderBackgroundControl, renderBackgroundWorkerStart, renderBackgroundWorkerStop, renderUserManagerRecovery, backgroundUnitName } from "./background.js";
 import { renderPackagePostuninst } from "../build-spk/native-lifecycle.js";
 import { renderSharedFolderScript } from "./shared-folder.js";
+import { renderDelegateInstallDraft } from '../build-spk/delegate-scope.js';
+import { renderPortalLifecycle } from "../portal/package.js";
+import { nativePortal } from "./portal.js";
 /** Package-account lifecycle hooks for CGI, daemon and background packages. */
 export function renderStandaloneScript(name, manifest) {
+    const portal = nativePortal(manifest);
+    const script = renderCapabilityScript(name, manifest);
+    return portal ? script.replace("#!/bin/sh\n", () => `#!/bin/sh\n${renderPortalLifecycle(name, portal)}`) : script;
+}
+function renderCapabilityScript(name, manifest) {
+    if (name === 'preupgrade' && (manifest.capabilities.rootOps || manifest.capabilities.delegate)) {
+        const installed = `\${SYNOPKG_PKGDEST:-/var/packages/${manifest.package}/target}`;
+        // Incoming preupgrade sees the OLD payload. Only complete absence is first
+        // introduction; a partial or symlinked executor must still fail closed.
+        const legacy = manifest.daemon
+            ? `  if [ -e "${installed}/daemon" ] || [ -L "${installed}/daemon" ]; then\n    "${installed}/daemon/control" stop "${installed}" "\${SYNOPKG_PKGVAR:-/var/packages/${manifest.package}/var}" || exit $?\n  fi\n`
+            : '';
+        return renderStandaloneScriptBody(name, manifest).replace('#!/bin/sh\n', `#!/bin/sh\nif [ ! -e "${installed}/executor" ] && [ ! -L "${installed}/executor" ]; then\n${legacy}  exit 0\nfi\n`);
+    }
+    return renderStandaloneScriptBody(name, manifest);
+}
+function renderStandaloneScriptBody(name, manifest) {
+    if (manifest.capabilities?.delegate?.scope === 'install-selected' && ['preinst', 'postinst'].includes(name)) {
+        const normal = renderCapabilityScript(name, { ...manifest, capabilities: { ...manifest.capabilities, delegate: { ...manifest.capabilities.delegate, scope: 'home' } } });
+        return normal.replace('#!/bin/sh\n', () => '#!/bin/sh\n' + renderDelegateInstallDraft(manifest.package, name === 'preinst'));
+    }
+    if (manifest.daemon && manifest.capabilities?.jobs && (manifest.capabilities.delegate || manifest.capabilities.rootOps)
+        && ['start-stop-status', 'preupgrade', 'preuninst'].includes(name))
+        return renderDelegatedDaemonScript(name, manifest);
     if ((manifest.capabilities?.rootOps || manifest.capabilities?.delegate) && ["preuninst", "preupgrade", "start-stop-status"].includes(name)) {
         const helper = `"\${SYNOPKG_PKGDEST:-/var/packages/${manifest.package}/target}/executor/lifecycle"`;
-        const stopWorker = manifest.capabilities.jobs ? `/usr/syno/bin/synosystemctl stop ${backgroundUnitName(manifest.package)} || echo "worker stop unconfirmed; continuing executor cleanup" >&2\n` : "";
+        // Attempt worker stop first, but let executor shutdown drain requests and
+        // close ingress even when it fails; a still-running worker fails the hook.
+        const workerStop = manifest.capabilities.jobs ? renderBackgroundWorkerStop(manifest.package) : "";
+        const stopWorker = manifest.capabilities.jobs ? "worker_result=0\nstop_background_worker || worker_result=1\n" : "";
+        const workerResult = manifest.capabilities.jobs ? 'exit "$worker_result"\n' : "exit 0\n";
         const request = (action) => `${helper} ${action} --package ${manifest.package} || exit $?\n`;
         if (name === "start-stop-status") {
-            const normal = renderStandaloneScript(name, { ...manifest, capabilities: { ...manifest.capabilities, rootOps: undefined, delegate: undefined } });
-            // Attempt worker stop first. DSM may have already stopped it or deny this
-            // lifecycle context; executor shutdown drains requests and closes ingress.
+            const normal = renderCapabilityScript(name, { ...manifest, capabilities: { ...manifest.capabilities, rootOps: undefined, delegate: undefined } });
             const stopDaemon = manifest.daemon ? `"/var/packages/${manifest.package}/target/daemon/control" stop "\${SYNOPKG_PKGDEST:-/var/packages/${manifest.package}/target}" "\${SYNOPKG_PKGVAR:-/var/packages/${manifest.package}/var}" || exit $?\n` : "";
-            return normal.replace("#!/bin/sh\n", `#!/bin/sh\nif [ "$1" = start ]; then\n${request("start")}fi\nif [ "$1" = stop ]; then\n${stopWorker}${stopDaemon}${request("stop")}exit 0\nfi\n`);
+            return normal.replace("#!/bin/sh\n", `#!/bin/sh\n${workerStop}if [ "$1" = start ]; then\n${request("start")}fi\nif [ "$1" = stop ]; then\n${stopWorker}${stopDaemon}${request("stop")}${workerResult}fi\n`);
         }
         const action = name === "preuninst" ? '"$action"' : "stop";
         const choose = name === "preuninst" ? 'action=purge\n[ "${SYNOPKG_PKG_STATUS:-}" != UPGRADE ] || action=stop\n' : "";
-        return `#!/bin/sh\n${stopWorker}${choose}${request(action)}${manifest.daemon ? renderDaemonScript(name, manifest).replace("#!/bin/sh\n", "") : "exit 0\n"}`;
+        return `#!/bin/sh\n${workerStop}${stopWorker}${choose}${request(action)}${manifest.daemon ? renderDaemonScript(name, manifest).replace("#!/bin/sh\n", "") : workerResult}`;
     }
     if (name === "postuninst")
         return renderPackagePostuninst(manifest.package);
     if ((manifest.capabilities?.rootOps || manifest.capabilities?.delegate) && ["postinst", "postupgrade"].includes(name)) {
-        const normal = renderStandaloneScript(name, { ...manifest, capabilities: { ...manifest.capabilities, rootOps: undefined, delegate: undefined } });
+        const normal = renderCapabilityScript(name, { ...manifest, capabilities: { ...manifest.capabilities, rootOps: undefined, delegate: undefined } });
         return normal.replace("#!/bin/sh\n", `#!/bin/sh\n"\${SYNOPKG_PKGDEST:-/var/packages/${manifest.package}/target}/executor/lifecycle" start --package ${manifest.package} || exit $?\n`);
     }
     if (manifest.sharedFolder && (name === "postinst" || name === "postupgrade"))
@@ -40,6 +69,55 @@ esac
     }
     return "#!/bin/sh\nexit 0\n";
 }
+/** DSM owns the single user unit; the daemon controller owns only its producer. */
+function renderDelegatedDaemonScript(name, manifest) {
+    const pkg = manifest.package;
+    const daemon = `"/var/packages/${pkg}/target/daemon/control"`;
+    const paths = `"\${SYNOPKG_PKGDEST:-/var/packages/${pkg}/target}" "\${SYNOPKG_PKGVAR:-/var/packages/${pkg}/var}"`;
+    const helper = `"\${SYNOPKG_PKGDEST:-/var/packages/${pkg}/target}/executor/lifecycle"`;
+    const executor = (action) => `${helper} ${action} --package ${pkg}`;
+    const worker = (action) => `/usr/syno/bin/synosystemctl ${action} ${backgroundUnitName(pkg)}`;
+    // Try every owner even on failure; never leave protected ingress open merely
+    // because a producer could not stop. A partial teardown remains a failure.
+    const stop = (daemonAction, executorAction) => `result=0\nstop_background_worker || result=1\n${daemon} ${daemonAction} ${paths} || result=1\n${executor(executorAction)} || result=1\nexit "$result"\n`;
+    const workerStop = renderBackgroundWorkerStop(pkg);
+    if (name !== 'start-stop-status') {
+        if (name === 'preupgrade')
+            return `#!/bin/sh\n${workerStop}${stop('stop', 'stop')}`;
+        return `#!/bin/sh\n${workerStop}if [ "\${SYNOPKG_PKG_STATUS:-}" = UPGRADE ]; then\n${stop('stop', 'stop')}fi\n${stop(manifest.daemon?.uninstall_args ? 'uninstall' : 'stop', 'purge')}`;
+    }
+    return `#!/bin/sh
+${workerStop}${renderUserManagerRecovery()}${renderBackgroundWorkerStart(pkg)}case "$1" in
+  prestart) recover_user_manager ;;
+  prestop) exit 0 ;;
+  start)
+    ${executor('start')} || exit $?
+    if ! ${daemon} start ${paths}; then
+      ${daemon} stop ${paths}
+      ${executor('stop')}
+      exit 1
+    fi
+    if ! start_background_worker; then
+      ${worker('stop')}
+      ${daemon} stop ${paths}
+      ${executor('stop')}
+      exit 1
+    fi
+    exit 0 ;;
+  status)
+    ${daemon} status ${paths} || exit $?
+    worker_state="$(${worker('get-active-status')})" || exit 3
+    [ "$worker_state" = active ] && exit 0
+    exit 3 ;;
+  stop)
+${stop('stop', 'stop')}    ;;
+  restart)
+    "$0" stop || exit $?
+    exec "$0" start ;;
+  *) exit 1 ;;
+esac
+`;
+}
 function renderDaemonScript(name, manifest) {
     const pkg = manifest.package;
     const control = `"/var/packages/${pkg}/target/daemon/control"`;

package/dist/standalone/manifest.d.ts

@@ -1,3 +1,4 @@
+import { type PackageMetadata } from "../package-metadata.js";
 import { type DelegateCapability } from "../runtime/executor-policy.js";
 import type { ExecutorPins } from "../runtime/executor-tasks.js";
 import { type NativeArchFamily } from "../build-spk/dsm-arch.js";
@@ -7,6 +8,7 @@ import { type Daemon } from "./daemon.js";
 import { type Background } from "./background.js";
 import { type SharedFolder } from "./shared-folder.js";
 import { type ApiPermissions } from "./api-permissions.js";
+import { type PortalDeclaration } from "../portal/alias.js";
 /**
  * `dsm-package.yaml`: a Standalone Package, i.e. an unsigned native SPK that
  * runs as its own DSM package account with a CGI backend and a DSM window UI.
@@ -31,6 +33,7 @@ export interface StandaloneI18n {
     info: Partial<Record<Locale, InfoText>>;
 }
 export interface StandaloneManifest {
+    metadata?: PackageMetadata;
     root: string;
     package: string;
     version: string;
@@ -62,7 +65,16 @@ export interface StandaloneManifest {
     daemon?: Daemon;
     /** `install.sharedFolder`: the Shared Folder the install wizard selects or `data-share` creates. */
     sharedFolder?: SharedFolder;
+    /** Who may use the app at all; absent keeps the route policy alone. */
+    entry?: EntryMode;
+    /** `portal`: registers the DSM Application Portal entry; an administrator activates it. */
+    portal?: PortalDeclaration;
 }
+/**
+ * `admin-only`: DSM administrators only. `app-privilege`: administrators and
+ * accounts DSM's Control Panel > Application Privileges allows for the app.
+ */
+export type EntryMode = "admin-only" | "app-privilege";
 export interface Capabilities {
     files?: "session";
     identity?: "standalone";
@@ -81,6 +93,7 @@ export type ManifestResult = {
     ok: false;
     errors: StandaloneError[];
 };
+export declare const KNOWN_FIELDS: Set<string>;
 export declare function loadStandaloneManifest(root: string): ManifestResult;
 /**
  * The nearest directory at or above `start` that holds dsm-package.yaml,

package/dist/standalone/manifest.js

@@ -1,3 +1,4 @@
+import { validateMetadata } from "../package-metadata.js";
 import { validDelegate } from "../runtime/executor-policy.js";
 import { existsSync, readFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
@@ -7,17 +8,18 @@ import { checkGlossary, isLocale, loadCatalogs } from "./i18n.js";
 import { loadRootOps, ROOT_OPS_DIR } from "./root-ops.js";
 import { readDaemon } from "./daemon.js";
 import { readBackground } from "./background.js";
-import { DEFAULT_MIN_DSM, isDsmAtLeast } from "../build-spk/dsm-version.js";
+import { DEFAULT_MIN_DSM, isDsmAtLeast, PORTAL_MIN_DSM, portalMinDsmMessage } from "../build-spk/dsm-version.js";
 import { readSharedFolder } from "./shared-folder.js";
-import { readApiPermissions } from "./api-permissions.js";
+import { floorAtAdministrators, permitsOrdinaryUsers, readApiPermissions } from "./api-permissions.js";
+import { readPortalDeclaration } from "../portal/alias.js";
 /**
  * `dsm-package.yaml`: a Standalone Package, i.e. an unsigned native SPK that
  * runs as its own DSM package account with a CGI backend and a DSM window UI.
  */
 export const STANDALONE_MANIFEST = "dsm-package.yaml";
-const KNOWN_FIELDS = new Set([
+export const KNOWN_FIELDS = new Set([
     "schema", "package", "version", "build", "displayname", "description",
-    "maintainer", "os_min_ver", "arches", "backend", "ui", "capabilities", "i18n", "daemon", "install",
+    "metadata", "maintainer", "os_min_ver", "arches", "backend", "ui", "capabilities", "i18n", "daemon", "install", "entry", "portal",
 ]);
 const I18N_FIELDS = new Set(["messages", "glossary", "info"]);
 const INFO_TEXT_FIELDS = new Set(["displayname", "description"]);
@@ -108,6 +110,14 @@ function readManifest(raw, c) {
     const displayname = c.text(raw.displayname, "displayname");
     const description = c.text(raw.description, "description");
     const maintainer = c.text(raw.maintainer, "maintainer");
+    let metadata;
+    if (raw.metadata !== undefined)
+        try {
+            metadata = validateMetadata(raw.metadata);
+        }
+        catch {
+            c.fail("STANDALONE_TEXT_INVALID", "metadata 欄位格式不正確；請檢查文字、email、URLs 與 screenshots。");
+        }
     const arches = readArches(raw.arches, c);
     const backend = arches && readBackend(raw.backend, arches, c);
     let permissions;
@@ -120,8 +130,8 @@ function readManifest(raw, c) {
         }
     }
     const daemon = arches && readDaemon(raw.daemon, c.root, arches, e => c.fail(e.code, e.message));
-    if (capabilities.jobs && raw.daemon !== undefined) {
-        c.fail("CAPABILITY_COMBINATION_INVALID", "daemon 與 capabilities.jobs 互斥。");
+    if (capabilities.jobs && raw.daemon !== undefined && capabilities.delegate?.lifetime !== 'until-revoked') {
+        c.fail("CAPABILITY_COMBINATION_INVALID", "daemon 僅可與明確 until-revoked delegate 的固定 worker 共存；一般 capabilities.jobs 仍互斥。");
     }
     if (backend?.kind === "binary") {
         for (const name of ["files", "jobs", "identity", "delegate"]) {
@@ -130,10 +140,25 @@ function readManifest(raw, c) {
         }
     }
     const sharedFolder = raw.install === undefined ? undefined : readSharedFolder(raw.install, e => c.fail(e.code, e.message));
+    const entry = raw.entry === undefined ? undefined : readEntry(raw.entry, backend, permissions?.policy, c);
+    if (entry === "admin-only" && permissions) {
+        const floored = floorAtAdministrators(permissions.policy);
+        if (floored.widened.length) {
+            c.fail("STANDALONE_ENTRY_WIDENED", `entry: admin-only 以管理員為所有 route 的下限；permissions.json 的 ${floored.widened.join("、")} 會開放給其他人。請改為 administrators，或改用 entry: app-privilege／省略 entry。`);
+        }
+        permissions.policy = floored.policy;
+    }
     const ui = readUi(raw.ui, c);
     if (capabilities.identity && ui && !ui.build)
         c.fail("CAPABILITY_COMBINATION_INVALID", "capabilities.identity 需要獨立登入頁；plain UI 不支援，請改用 vue UI（init --ui vue）。");
+    if (capabilities.delegate?.scope === "install-selected" && ui && !ui.build)
+        c.fail("CAPABILITY_COMBINATION_INVALID", "delegate scope install-selected 只能在 Vue 面板確認；plain UI 不支援，請改用 vue UI（init --ui vue）。");
     const i18n = raw.i18n === undefined ? undefined : readI18n(raw.i18n, c);
+    const portal = raw.portal === undefined || !packageId ? undefined : readPortalDeclaration(raw.portal, packageId)
+        ?? c.fail("STANDALONE_PORTAL_INVALID", "portal 必須是 {} 或 { alias: <小寫英數與 -，1–64 字，不可為 DSM 保留路徑> }。");
+    if (portal && osMinVer && !isDsmAtLeast(osMinVer, PORTAL_MIN_DSM)) {
+        c.fail("STANDALONE_PORTAL_MIN_DSM", portalMinDsmMessage(osMinVer, "portal"));
+    }
     if (!packageId || !version || !build || !osMinVer || !displayname || !description || !maintainer
         || !arches || !backend || !ui || (capabilities.rootOps === true && !rootOps)) {
         return undefined;
@@ -147,6 +172,7 @@ function readManifest(raw, c) {
         displayname,
         description,
         maintainer,
+        ...(metadata ? { metadata } : {}),
         os_min_ver: osMinVer,
         arches,
         backend,
@@ -157,8 +183,31 @@ function readManifest(raw, c) {
         ...(rootOps ? { rootOps } : {}),
         ...(daemon ? { daemon } : {}),
         ...(sharedFolder ? { sharedFolder } : {}),
+        ...(entry ? { entry } : {}),
+        ...(portal ? { portal } : {}),
     };
 }
+/**
+ * The CGI enforces the entry mode only when the project's backend carries the
+ * SDK gate and main wires it; `-X main.entry` on an older main would be
+ * silently dropped and leave a registered app ungated.
+ */
+function readEntry(value, backend, policy, c) {
+    if (value !== "admin-only" && value !== "app-privilege") {
+        return c.fail("STANDALONE_ENTRY_INVALID", "entry 必須是 admin-only 或 app-privilege；省略則維持既有 permissions.json 行為。");
+    }
+    if (!backend)
+        return undefined;
+    const main = backend.kind === "go" ? join(backend.dir, backend.main, "main.go") : "";
+    if (backend.kind !== "go" || !existsSync(join(backend.dir, "internal/dsm/entry.go"))
+        || !existsSync(main) || !readFileSync(main, "utf8").includes("dsm.NewEntryGate(")) {
+        return c.fail("STANDALONE_ENTRY_UNSUPPORTED", "entry 需要 Go backend 內的 SDK entry gate：請從 SDK 範本複製 internal/dsm/entry.go、apppriv.go 與 native bridge，並在 cmd/app/main.go 以 dsm.NewEntryGate 包住 authenticator。");
+    }
+    if (value === "app-privilege" && !permitsOrdinaryUsers(policy)) {
+        return c.fail("STANDALONE_ENTRY_INVALID", "entry: app-privilege 需要至少一個 permissions.json 標為 authenticated 的 route，一般使用者才有功能可用。");
+    }
+    return value;
+}
 function readRootOps(enabled, c) {
     const dir = join(c.root, ROOT_OPS_DIR);
     if (!enabled) {
@@ -180,7 +229,7 @@ function readArches(value, c) {
         && new Set(value).size === value.length;
     return ok
         ? value
-        : c.fail("STANDALONE_ARCHES_INVALID", "arches 必須是不重複的 x86_64／aarch64 清單，至少一個。");
+        : c.fail("STANDALONE_ARCHES_INVALID", "arches 必須是不重複的 x86_64／aarch64／armv7 清單，至少一個。");
 }
 function readBackend(value, arches, c) {
     if (!isRecord(value) || !["go", "binary"].includes(String(value.kind))) {
@@ -314,7 +363,7 @@ function readCapabilities(value, c) {
             if (validDelegate(setting))
                 result.delegate = setting;
             else
-                c.fail("CAPABILITY_INVALID", "delegate requires nonempty unique §2.4 files operations and scope home or shared:<name>.");
+                c.fail("CAPABILITY_INVALID", "delegate requires scope home or shared:<name> and legacy files operations, or scope home/shared:<name>/install-selected with exactly files.moveFromStaging, nonempty unique destinations and lifetime: until-revoked.");
         }
         else if (name === "files" && setting === "session")
             result.files = "session";

package/dist/standalone/native-authorization-window.d.ts

@@ -0,0 +1,2 @@
+/** Shared host flow. CGI plans are never accepted as completed authorization. */
+export declare const AUTHORIZATION_RUNTIME = "function createAuthorizationAccess(options) {\n  var busy = null;\n  function fail(code) { var error = new Error(code); error.code = code; return error; }\n  function status() { return options.call(\"authorization.status\").then(function (d) {\n    if (!d || d.command !== \"authorization\" || d.schema_version !== 1 || [\"ready\",\"authorization_required\",\"not_admin\",\"session_expired\",\"unavailable\"].indexOf(d.state) < 0) throw fail(\"authorization_bad_response\");\n    // upgrade_reapproval is a reason-only tombstone: it can only explain a pending request.\n    if (d.reason === \"upgrade_reapproval\" && d.state !== \"authorization_required\") throw fail(\"authorization_bad_response\");\n    return d;\n  }); }\n  function plan(method) { return options.call(method).then(function (p) {\n    if (!p || p.command !== \"authorization\" || p.schema_version !== 1 || p.phase !== \"plan\" || !Array.isArray(p.operations) || p.operations.length === 0 || p.operations.length > options.tasks.length) throw fail(\"authorization_bad_response\");\n    var seen = {};\n    p.operations.forEach(function (op) { if (seen[op] || !options.tasks.some(function (t) { return t.op === op; })) throw fail(\"authorization_bad_response\"); seen[op] = true; });\n    return p;\n  }); }\n  function exclusive(fn) { if (busy) return busy; busy = Promise.resolve().then(fn).then(function (s) { busy = null; return s; },function (e) { busy = null; throw e; });return busy; }\n  function authorize(ops,run) { return ops.reduce(function (previous,op) { return previous.then(function () {\n    return options.root.authorize(op).then(function (state) { if (state !== \"ready\") throw fail(\"root_cancelled\"); return run ? options.root.run(op) : null; });\n  }); },Promise.resolve()); }\n  return {canManage:function () {return !!options.user && options.user().admin === true;},status:status,request:function () { return exclusive(function () {\n    return plan(\"authorization.request\").then(function (p) { return authorize(p.operations,p.run === true); }).then(status,function (e) { if (e.code === \"root_cancelled\") return status();throw e; });\n  }); },revoke:function () { return exclusive(function () {\n    return plan(\"authorization.revoke\").then(function (p) {\n      if (p.withdraw === true && typeof options.withdraw !== \"function\") throw fail(\"authorization_bad_response\");\n      var disabled = p.withdraw === true ? options.withdraw() : p.disable === true ? authorize([\"helper_disable\"],true) : Promise.resolve();\n      return disabled.then(function () { return p.purge === true ? authorize([\"helper_purge\"],true) : null; }).then(function () { return p.operations.reduce(function (previous,op) {return previous.then(function () {return options.root.remove(op);});},Promise.resolve()); });\n    }).then(status,function (e) { if (e.code === \"root_cancelled\") return status();throw e; });\n  }); }};\n}";