@synopackageland/cli 0.41.3 → 0.41.5

package/dist/standalone/inspect-spk.js

@@ -1,3 +1,4 @@
+import { portDefaults, portInstallSteps } from "./install-ports.js";
 import { inspectPackageDependencies, dependencyInfo } from "./package-dependencies.js";
 import { readInstallSettings, settingsInstallSteps, settingsConfig, renderSettingsHook } from './install-settings.js';
 import { MODULE_UI_ENTRY, uiTreeDigest } from "./ui-assets.js";
@@ -217,7 +218,7 @@ export async function inspectSpk(spkPath, expectedKind) {
             !isDsmAtLeast(info.os_min_ver, PORTAL_MIN_DSM)) {
             findings.push(`INFO os_min_ver "${info.os_min_ver}" is below the DSM ${PORTAL_MIN_DSM} a portal needs; ${PORTAL_MIN_DSM_REASON}`);
         }
-        checkConf(dir, findings, kind, background, sharedFolder, info.package, portal, combined?.compose, nativeGateway, info.os_min_ver, daemonIngress);
+        checkConf(dir, findings, kind, background, sharedFolder, info.package, portal, combined?.compose, nativeGateway, info.os_min_ver, daemonIngress, Boolean(metadata.installPorts));
         checkScripts(dir, findings);
         checkUninstall(dir, findings);
         if (kind === "container")
@@ -318,7 +319,7 @@ export async function inspectSpk(spkPath, expectedKind) {
             ? await inspectLoginStyle(dir, info.package, Boolean(portal || executor?.policy.portal), findings)
             : undefined;
         if (standalone)
-            checkSharedFolder(dir, findings, info.package, sharedFolder, executor?.policy.scope === "install-selected", portal, hasExecutor, nativeGateway, info.os_min_ver, installSettings, integrations);
+            checkSharedFolder(dir, findings, info.package, sharedFolder, executor?.policy.scope === "install-selected", portal, hasExecutor, nativeGateway, info.os_min_ver, installSettings, integrations, metadata.installPorts);
         const icon = inspectPackageIcons(dir, findings);
         const cgiEntry = payload.find((entry) => entry.path === CGI_PAYLOAD_PATH);
         if (standalone && !cgiEntry) {
@@ -744,6 +745,7 @@ async function inspectUnifiedCompose(dir, payload, metadata, findings) {
             composeMounts: metadata.capabilities?.includes("composeMounts"),
             sharedFolder: recoverSharedFolder(readOptional(join(dir, "scripts/postinst"))),
             installSettings: metadata.installSettings,
+            installPorts: metadata.installPorts,
             architecture: arch,
             imageProofs: JSON.parse(readFileSync(join(root, "compose/images.json"), "utf8")),
         });
@@ -792,6 +794,7 @@ async function inspectUnifiedCompose(dir, payload, metadata, findings) {
             },
             compose: c,
             sharedFolder: recoverSharedFolder(readOptional(join(dir, "scripts/postinst"))),
+            ...(metadata.installPorts ? { installPorts: true } : {}),
             ...(g ? { identityGateway: g } : {}),
             ...(metadata.entry ? { entry: metadata.entry } : {}),
         };
@@ -801,8 +804,8 @@ async function inspectUnifiedCompose(dir, payload, metadata, findings) {
             throw new Error("gateway configuration differs from the declared package contract");
         if (readOptional(join(dir, "conf/privilege")) !== renderNativePrivilege())
             throw new Error("Compose hooks must run as the package account");
-        if (manifest.sharedFolder || metadata.installSettings) {
-            for (const [name, text] of Object.entries(expectedWizardFiles(info.package, manifest.sharedFolder, false, undefined, metadata.installSettings)))
+        if (manifest.sharedFolder || metadata.installSettings || metadata.installPorts) {
+            for (const [name, text] of Object.entries(expectedWizardFiles(info.package, manifest.sharedFolder, false, undefined, metadata.installSettings, [], manifest.identityGateway?.listen.https, metadata.installPorts)))
                 if (readOptional(join(dir, "WIZARD_UIFILES", name)) !== text)
                     throw new Error(`unexpected WIZARD_UIFILES/${name}; native share selection must match the declaration`);
         }
@@ -837,7 +840,7 @@ async function inspectUnifiedCompose(dir, payload, metadata, findings) {
             "postupgrade",
             "start-stop-status",
         ])
-            if (!matchesStandaloneScript(hook, manifest, readOptional(join(dir, "scripts", hook))))
+            if (!matchesStandaloneScript(hook, manifest, readOptional(join(dir, "scripts", hook)), Boolean(metadata.installPorts)))
                 throw new Error(`unexpected scripts/${hook}`);
         if (appScripts.length)
             base.appScripts = appScripts;
@@ -1310,12 +1313,13 @@ async function recoverDaemonIngress(dir, value, info, paths, findings) {
         return undefined;
     }
 }
-function checkConf(dir, findings, kind, background, sharedFolder, pkg, portal, compose, nativeGateway, osMinVer, daemonIngress) {
+function checkConf(dir, findings, kind, background, sharedFolder, pkg, portal, compose, nativeGateway, osMinVer, daemonIngress, installPorts = false) {
     const confDir = join(dir, "conf");
     const entries = existsSync(confDir) ? readdirSync(confDir) : [];
     const nativeResource = kind !== "container"
         ? renderStandaloneResource({
             package: pkg ?? "",
+            ...(installPorts ? { installPorts: true } : {}),
             os_min_ver: osMinVer,
             ...(nativeGateway ? { identityGateway: nativeGateway } : {}),
             ...(compose ? { compose } : {}),
@@ -1415,7 +1419,7 @@ function checkBackground(dir, info, payload, findings, executor, daemon, bridge
  * 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, selected = false, portal, executor = false, nativeGateway, osMinVer, installSettings, integrations = []) {
+function checkSharedFolder(dir, findings, pkg, folder, selected = false, portal, executor = false, nativeGateway, osMinVer, installSettings, integrations = [], installPortDefinitions = {}) {
     const wizardDir = join(dir, "WIZARD_UIFILES");
     const present = (existsSync(wizardDir) ? readdirSync(wizardDir) : [])
         .filter((name) => /^(install|upgrade)_uifile(_|\.|$)/.test(name))
@@ -1431,6 +1435,7 @@ function checkSharedFolder(dir, findings, pkg, folder, selected = false, portal,
         package: pkg,
         os_min_ver: osMinVer,
         sharedFolder: folder,
+        ...(Object.keys(installPortDefinitions).length ? { installPorts: true } : {}),
         capabilities: selected
             ? { delegate: { scope: "install-selected" } }
             : executor
@@ -1441,7 +1446,7 @@ function checkSharedFolder(dir, findings, pkg, folder, selected = false, portal,
             : {}),
         ...portalManifest(portal),
     };
-    const wizards = expectedWizardFiles(pkg, folder, selected, portal, installSettings, integrations);
+    const wizards = expectedWizardFiles(pkg, folder, selected, portal, installSettings, integrations, nativeGateway?.listen.https, installPortDefinitions);
     const source = selected
         ? "the install-selected policy"
         : folder
@@ -1452,7 +1457,7 @@ function checkSharedFolder(dir, findings, pkg, folder, selected = false, portal,
                     ? "the integrations declaration"
                     : "the native-go default install wizard";
     // The default native wizard is optional; a declared shared folder or portal needs all of its files.
-    for (const name of folder || selected || portal || installSettings || integrations.length
+    for (const name of folder || selected || portal || installSettings || Object.keys(installPortDefinitions).length || integrations.length
         ? Object.keys(wizards)
         : present.filter((n) => n in wizards)) {
         if (readOptional(join(wizardDir, name)) !== wizards[name])
@@ -1462,14 +1467,14 @@ function checkSharedFolder(dir, findings, pkg, folder, selected = false, portal,
         findings.push(`WIZARD_UIFILES/${name} is not a wizard file produced by ${source}`);
     if (selected) {
         for (const hook of ["preinst", "postinst"]) {
-            if (!matchesStandaloneScript(hook, lifecycleManifest, readOptional(join(dir, "scripts", hook))))
+            if (!matchesStandaloneScript(hook, lifecycleManifest, readOptional(join(dir, "scripts", hook)), Boolean(Object.keys(installPortDefinitions).length)))
                 findings.push(`scripts/${hook} does not match the fixed install-selected draft handling`);
         }
     }
     if (!folder && !portal)
         return;
     for (const hook of ["postinst", "postupgrade"]) {
-        if (!matchesStandaloneScript(hook, lifecycleManifest, readOptional(join(dir, "scripts", hook)))) {
+        if (!matchesStandaloneScript(hook, lifecycleManifest, readOptional(join(dir, "scripts", hook)), Boolean(Object.keys(installPortDefinitions).length))) {
             findings.push(`scripts/${hook} does not match the fixed script declared by ${folder ? "install.sharedFolder" : "portal"}`);
         }
     }
@@ -1479,7 +1484,8 @@ function checkSharedFolder(dir, findings, pkg, folder, selected = false, portal,
 async function inspectInstallSettings(dir, payload, metadata, findings) {
     const settings = readInstallSettings(metadata.installSettings, e => findings.push(e.message));
     const present = payload.filter(p => p.path.startsWith('install/'));
-    if (!settings) {
+    const ports = metadata.installPorts;
+    if (!settings && !ports) {
         if (present.length)
             findings.push('INSTALL_SETTINGS_INVALID unexpected installation settings payload');
         return;
@@ -1489,12 +1495,30 @@ async function inspectInstallSettings(dir, payload, metadata, findings) {
     await tar.x({ file: join(dir, 'package.tgz'), cwd: root });
     const info = readInfo(join(dir, 'INFO'), findings, 'binary', Boolean(metadata.compose), undefined, inspectPackageDependencies(metadata.dependencies, findings));
     const gateway = metadata.compose?.gateway ?? metadata.native_gateway;
-    const m = { package: info.package, os_min_ver: info.os_min_ver, capabilities: {}, installSettings: settings, identityGateway: gateway };
+    const m = { package: info.package, os_min_ver: info.os_min_ver, capabilities: {}, installSettings: settings, identityGateway: gateway, ...(ports ? { installPorts: true } : {}) };
     try {
-        if (readOptional(join(root, 'install/settings.json')) !== JSON.stringify(settingsConfig(m), null, 2) + '\n')
+        if (settings && readOptional(join(root, 'install/settings.json')) !== JSON.stringify(settingsConfig(m), null, 2) + '\n')
             throw new Error('settings inventory differs from its declaration or gateway port');
-        if (present.length !== 2 || !present.some(p => p.path === 'install/control' && p.mode === '0755') || present.some(p => !['install/control', 'install/settings.json'].includes(p.path)))
+        const allowed = ['install/control', ...(settings ? ['install/settings.json'] : []), ...(ports ? ['install/ports.json', `install/${info.package}.sc`] : [])];
+        if (present.length !== allowed.length || !present.some(p => p.path === 'install/control' && p.mode === '0755') || present.some(p => !allowed.includes(p.path)))
             throw new Error('only SDK control and declarations may be packaged; values must never ship');
+        if (ports) {
+            const config = JSON.parse(readFileSync(join(root, 'install/ports.json'), 'utf8'));
+            const actualGateway = JSON.parse(readFileSync(join(root, 'sso/gateway.json'), 'utf8'));
+            const expected = portDefaults({ ...m, identityGateway: { ...actualGateway, sdk: gateway.sdk } });
+            if (config.schema !== 1 || config.package !== info.package || !isDeepStrictEqual(config.ports, ports) || !isDeepStrictEqual(ports, expected))
+                throw new Error('port defaults differ from gateway listeners');
+            const required = ['sso/gateway.json', 'daemon/config.json', ...(actualGateway.native_ingress ? ['sso/native-nginx.conf'] : []), ...(settings ? ['install/settings.json'] : []), ...payload.filter(p => /^ui\/window-[0-9]+\.js$/.test(p.path)).map(p => p.path)].sort();
+            if (!isDeepStrictEqual(Object.keys(config.files).sort(), required))
+                throw new Error('port templates must cover every generated port consumer');
+            for (const [path, source] of Object.entries(config.files)) {
+                let text = String(source);
+                for (const [key, p] of Object.entries(ports))
+                    text = text.replaceAll('@@PORT_' + key + '@@', String(p.default));
+                if (text.includes('@@PORT_') || readOptional(join(root, path)) !== text)
+                    throw new Error('port template differs from generated default artifact');
+            }
+        }
         const arch = info.arch.split(/\s+/).map(familyOfArchToken).find(Boolean) ?? 'x86_64';
         const error = checkCgiBinary(root, join(root, 'install/control'), arch);
         if (error)
@@ -1513,7 +1537,7 @@ async function inspectInstallSettings(dir, payload, metadata, findings) {
     }
     return settings;
 }
-function expectedWizardFiles(pkg, folder, selected = false, portal, installSettings, integrations = []) {
+function expectedWizardFiles(pkg, folder, selected = false, portal, installSettings, integrations = [], settingsPort = 0, installPortDefinitions = {}) {
     const steps = selected
         ? (t) => [
             ...renderDelegateScopeSteps(t),
@@ -1522,7 +1546,7 @@ function expectedWizardFiles(pkg, folder, selected = false, portal, installSetti
         : folder
             ? sharedFolderInstallSteps(pkg, folder)
             : renderNativeInstallWizard;
-    const install = renderInstallWizardFiles(pkg, t => [...steps(t), ...settingsInstallSteps(installSettings)(t), ...(portal ? [renderPortalWizardStep(t, portal.alias)] : []), ...integrationWizardSteps(t, integrations)]);
+    const install = renderInstallWizardFiles(pkg, t => [...steps(t), ...portInstallSteps({ package: pkg, ...(Object.keys(installPortDefinitions).length ? { installPorts: true } : {}) }, installPortDefinitions)(t), ...settingsInstallSteps(installSettings, settingsPort, Object.keys(installPortDefinitions).length ? pkg : undefined)(t), ...(portal ? [renderPortalWizardStep(t, portal.alias)] : []), ...integrationWizardSteps(t, integrations)]);
     return {
         ...install.static,
         ...install.dynamic,

package/dist/standalone/install-ports.d.ts

@@ -0,0 +1,31 @@
+import type { StandaloneManifest } from './manifest.js';
+import type { Translate } from '../build-spk/wizard-i18n.js';
+export declare function portDefaults(m: Pick<StandaloneManifest, 'identityGateway' | 'installPorts'>): Record<string, {
+    default: number;
+    protocol: 'tcp';
+}>;
+export declare function withPort(m: StandaloneManifest, key: string, value: number): StandaloneManifest;
+export declare function portFieldValidator(pkg: string, key: string, reason: string): string;
+export declare function portInstallSteps(m: Pick<StandaloneManifest, 'package' | 'installPorts' | 'identityGateway'>, definitions?: Record<string, {
+    default: number;
+    protocol: "tcp";
+}>): (t: Translate) => {
+    step_title: string;
+    items: {
+        type: string;
+        desc: string;
+        subitems: {
+            key: string;
+            desc: string;
+            defaultValue: string;
+            validator: {
+                allowBlank: boolean;
+                fn: string;
+            };
+        }[];
+    }[];
+}[];
+/** Render each artifact with out-of-range marker ports. Only values derived
+ * from the selected listener change; an unrelated timer or numeric setting
+ * equal to a default port is preserved. Originals remain inspectable in SPK. */
+export declare function writePortPayload(m: StandaloneManifest, root: string, render: (variant: StandaloneManifest) => Record<string, string>): void;

package/dist/standalone/install-ports.js

@@ -0,0 +1,103 @@
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+export function portDefaults(m) {
+    if (!m.installPorts || !m.identityGateway)
+        return {};
+    const g = m.identityGateway;
+    return Object.fromEntries([
+        ...Object.entries(g.listen ?? {}).map(([key, value]) => ['gateway_' + key, { default: value, protocol: 'tcp' }]),
+        ...(g.oidc ? [['oidc_issuer', { default: g.oidc.issuer_port, protocol: 'tcp' }]] : []),
+    ]);
+}
+export function withPort(m, key, value) {
+    const g = m.identityGateway;
+    return { ...m, identityGateway: { ...g, listen: { ...g.listen, ...(key.startsWith('gateway_') ? { [key.slice(8)]: value } : {}) }, ...(g.oidc ? { oidc: { ...g.oidc, ...(key === 'oidc_issuer' ? { issuer_port: value } : {}) } } : {}) } };
+}
+function validatePortField(value, pkg, key, reason) {
+    const raw = String(value), n = Number(raw);
+    if (!/^[1-9][0-9]{3,4}$/.test(raw) || n < 1024 || n > 65535 || [1900, 5000, 5001, 5005, 5006, 5353, 6690].includes(n))
+        return reason;
+    try {
+        let request = new XMLHttpRequest();
+        request.open('GET', '/webman/login.cgi?enable_syno_token=yes', false);
+        request.send();
+        const token = JSON.parse(request.responseText).SynoToken;
+        if (!token)
+            throw new Error();
+        request = new XMLHttpRequest();
+        request.open('POST', '/webapi/entry.cgi', false);
+        request.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
+        request.setRequestHeader('X-SYNO-TOKEN', token);
+        request.send('api=SYNO.Core.Service.PortInfo&version=1&method=load');
+        const result = JSON.parse(request.responseText), rows = result.data?.port_info;
+        if (request.status !== 200 || result.success !== true || !Array.isArray(rows) || !rows.length)
+            throw new Error();
+        for (const row of rows) {
+            if (typeof row.protocol !== 'string' || typeof row.port_id !== 'string' || !Array.isArray(row.dst_port) || !row.dst_port.length)
+                throw new Error();
+            const protocol = row.protocol.toLowerCase().replace(/\s/g, '');
+            if (!/^(?:tcp|udp)(?:,(?:tcp|udp))*$/.test(protocol))
+                throw new Error();
+            if (!protocol.split(',').includes('tcp'))
+                continue;
+            for (const item of row.dst_port) {
+                if (typeof item !== 'string')
+                    throw new Error();
+                const range = /^([0-9]+)(?:[-:]([0-9]+))?$/.exec(item);
+                if (!range || Number(range[1]) < 1 || Number(range[2] || range[1]) > 65535 || Number(range[1]) > Number(range[2] || range[1]))
+                    throw new Error();
+                if (n >= Number(range[1]) && n <= Number(range[2] || range[1]) && row.port_id !== 'synopkgland.' + pkg.replaceAll('_', '-') + '.' + key.replaceAll('_', '-'))
+                    return reason;
+            }
+        }
+        const globals = globalThis;
+        const state = globals['synopkglandPorts_' + pkg] || (globals['synopkglandPorts_' + pkg] = {});
+        for (const other in state)
+            if (other !== key && state[other] === n)
+                return reason;
+        state[key] = n;
+        return true;
+    }
+    catch {
+        return reason;
+    }
+}
+export function portFieldValidator(pkg, key, reason) {
+    return `{return (${validatePortField.toString()})(arguments[0],${JSON.stringify(pkg)},${JSON.stringify(key)},${JSON.stringify(reason)})}`;
+}
+export function portInstallSteps(m, definitions = portDefaults(m)) {
+    return (t) => m.installPorts ? [{ step_title: t('ports.title'), items: Object.entries(definitions).map(([key, p]) => ({ type: 'textfield', desc: t(key === 'gateway_http' ? 'ports.http' : key === 'gateway_https' ? 'ports.https' : 'ports.signin'), subitems: [{ key: 'pkgwizard_port_' + key, desc: t(key === 'gateway_http' ? 'ports.http' : key === 'gateway_https' ? 'ports.https' : 'ports.signin'), defaultValue: String(p.default), validator: { allowBlank: false, fn: portFieldValidator(m.package, key, t('ports.invalid')) } }] })) }] : [];
+}
+/** Render each artifact with out-of-range marker ports. Only values derived
+ * from the selected listener change; an unrelated timer or numeric setting
+ * equal to a default port is preserved. Originals remain inspectable in SPK. */
+export function writePortPayload(m, root, render) {
+    if (!m.installPorts)
+        return;
+    const ports = portDefaults(m), base = render(m);
+    let marker = 900000000;
+    if (!Object.keys(ports).length)
+        throw new Error('INSTALL_PORT_INVALID: install.ports requires an identity gateway');
+    const marked = Object.entries(ports).reduce((variant, [key]) => {
+        while (Object.values(base).some(s => s.includes(String(marker))))
+            marker++;
+        const value = marker++;
+        return withPort(variant, key, value);
+    }, m);
+    const files = render(marked);
+    let index = 0;
+    for (const [key] of Object.entries(ports)) {
+        const g = marked.identityGateway;
+        const value = key === 'oidc_issuer' ? g.oidc.issuer_port : g.listen[key.slice(8)];
+        for (const path of Object.keys(files))
+            files[path] = files[path].replaceAll(String(value), '@@PORT_' + key + '@@');
+        index++;
+    }
+    for (const [path, content] of Object.entries(base)) {
+        if (!existsSync(join(root, path)) || readFileSync(join(root, path), 'utf8') !== content)
+            throw new Error('INSTALL_PORT_INVALID: port template must match the generated artifact ' + path);
+    }
+    mkdirSync(join(root, 'install'), { recursive: true });
+    writeFileSync(join(root, 'install/ports.json'), JSON.stringify({ schema: 1, package: m.package, ports, files }, null, 2) + '\n', { mode: 0o600 });
+    writeFileSync(join(root, `install/${m.package}.sc`), Object.entries(ports).map(([key, p]) => `[synopkgland.${m.package.replaceAll('_', '-')}.${key.replaceAll('_', '-')}]\ntitle="${m.package}"\ndesc="${m.package}"\nport_forward="no"\ndst.ports="${p.default}/${p.protocol}"\n`).join('\n'), { mode: 0o644 });
+}

package/dist/standalone/install-settings.d.ts

@@ -9,7 +9,8 @@ export interface InstallSetting {
 }
 export type InstallSettings = Record<string, InstallSetting>;
 export declare function readInstallSettings(value: unknown, fail: (e: StandaloneError) => void): InstallSettings | undefined;
-export declare function settingsInstallSteps(settings: InstallSettings | undefined): (t: Translate) => {
+export declare function originFieldValidator(required: boolean, port: number, reason: string, portPackage?: string): string;
+export declare function settingsInstallSteps(settings: InstallSettings | undefined, port?: number, portPackage?: string): (t: Translate) => {
     step_title: string;
     items: {
         type: string;
@@ -20,6 +21,7 @@ export declare function settingsInstallSteps(settings: InstallSettings | undefin
             defaultValue: string;
             validator: {
                 allowBlank: boolean;
+                fn: string;
             };
         }[];
     }[];

package/dist/standalone/install-settings.js

@@ -23,16 +23,22 @@ export function readInstallSettings(value, fail) {
     }
     return Object.fromEntries(entries.sort(([a], [b]) => a.localeCompare(b)));
 }
-export function settingsInstallSteps(settings) {
+// DSM invokes validator.fn with the field value as arguments[0]. Keep this
+// independent of App JavaScript: the package has not been installed yet.
+export function originFieldValidator(required, port, reason, portPackage) {
+    const expected = portPackage ? `(globalThis[${JSON.stringify('synopkglandPorts_' + portPackage)}]?.gateway_https??${port})` : String(port);
+    return `{var expected=${expected};var value=arguments[0];if(!value)return ${required ? JSON.stringify(reason) : 'true'};try{if(typeof value!=='string'||value.length>2048||/[\\x00-\\x20\\x7f]/.test(value)||!/^https:\\/\\//.test(value))return ${JSON.stringify(reason)};var u=new URL(value);var host=u.hostname;if(!host||host.length>253||host.indexOf(':')>=0||!host.split('.').every(function(label){return /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?$/.test(label)}))return ${JSON.stringify(reason)};var authority=value.slice(8);if(/[\\/\\?#@\\\\]/.test(authority))return ${JSON.stringify(reason)};var parts=authority.split(':');if(!parts[0].split('.').every(function(label){return /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?$/.test(label)}))return ${JSON.stringify(reason)};if(parts.length>2||(parts.length===2&&(!/^[1-9][0-9]{0,4}$/.test(parts[1])||Number(parts[1])>65535)))return ${JSON.stringify(reason)};if(expected&&parts[1]!==String(expected))return ${JSON.stringify(reason)};return true}catch(e){return ${JSON.stringify(reason)}}}`;
+}
+export function settingsInstallSteps(settings, port = 0, portPackage) {
     return (t) => settings ? [{ step_title: t('install.step'), items: Object.entries(settings).map(([key, s]) => ({
-                type: 'textfield', desc: `${s.label}${s.required ? ' (required on first install)' : ''}. Blank reuses retained settings.`, subitems: [{ key: `pkgwizard_setting_${key}`, desc: s.label, defaultValue: '', validator: { allowBlank: true } }],
+                type: 'textfield', desc: s.label, subitems: [{ key: `pkgwizard_setting_${key}`, desc: s.label, defaultValue: '', validator: { allowBlank: !s.required, fn: originFieldValidator(s.required, port, portPackage ? t('ports.originInvalid') : t('settings.originInvalid', { port: port ? `:${port}` : '' }), portPackage) } }],
             })) }] : [];
 }
 export function settingsConfig(m) {
     return { schema: 1, package: m.package, ...(m.identityGateway?.listen.https ? { https_port: m.identityGateway.listen.https } : {}), settings: m.installSettings };
 }
 export function renderSettingsHook(name, m) {
-    if (!m.installSettings)
+    if (!m.installSettings && !m.installPorts)
         return '';
     const action = name === 'preinst' ? 'prepare' : ['postinst', 'postupgrade'].includes(name) ? 'remember' : name === 'preuninst' ? 'purge' : undefined;
     if (!action)
@@ -41,11 +47,13 @@ export function renderSettingsHook(name, m) {
     return `"${root}/install/control" ${action} --root "${root}" --package '${m.package}' || exit $?\n`;
 }
 export async function buildInstallSettings(m, arch, work, run) {
-    if (!m.installSettings)
+    if (!m.installSettings && !m.installPorts)
         return;
     const sdk = m.compose?.sdk ?? m.identityGateway?.sdk ?? templateSdkVersion(), source = sdkSource(sdk);
     if (!existsSync(join(source.goDir, 'installsettings/cmd/control/main.go')))
         throw new StandaloneBuildError('SDK_INSTALL_SETTINGS_UNSUPPORTED', 'Use an SDK release with native install.settings support.');
+    if (m.installPorts && !existsSync(join(source.goDir, 'installsettings/ports.go')))
+        throw new StandaloneBuildError('SDK_PORT_SETTINGS_UNSUPPORTED', 'Use an SDK release with install.ports support');
     const out = join(work, `install-settings-${arch}`);
     const result = await run('go', ['build', '-trimpath', '-buildvcs=false', '-ldflags', '-s -w -buildid=', '-o', out, './installsettings/cmd/control'], { cwd: source.goDir, env: goChildEnv({ ...process.env, ...pinnedGoBuildEnv(arch) }) });
     if (result.status !== 0)

package/dist/standalone/lifecycle.d.ts

@@ -5,4 +5,4 @@ export declare function renderStandaloneScript(name: string, manifest: Standalon
  * The backend inspector then replays the entire remaining lifecycle script. */
 export declare function matchesStandaloneScriptPrefix(name: string, manifest: StandaloneManifest, actual: string): boolean;
 /** Accept the exact current, diagnostic-only, and released lifecycle variants. */
-export declare function matchesStandaloneScript(name: string, manifest: StandaloneManifest, actual: string | undefined): boolean;
+export declare function matchesStandaloneScript(name: string, manifest: StandaloneManifest, actual: string | undefined, settingsPeeled?: boolean): boolean;

package/dist/standalone/lifecycle.js

@@ -35,8 +35,9 @@ export function matchesStandaloneScriptPrefix(name, manifest, actual) {
         blocks.every(block => prefix.includes(block) || !actual.includes(block)));
 }
 /** Accept the exact current, diagnostic-only, and released lifecycle variants. */
-export function matchesStandaloneScript(name, manifest, actual) {
-    return actual !== undefined && standaloneScriptVariants(name, manifest, renderStandaloneScript(name, manifest)).includes(actual);
+export function matchesStandaloneScript(name, manifest, actual, settingsPeeled = false) {
+    const expected = renderStandaloneScript(name, manifest);
+    return actual !== undefined && standaloneScriptVariants(name, manifest, settingsPeeled ? expected.replace(renderSettingsHook(name, manifest), '') : expected).includes(actual);
 }
 function standaloneScriptVariants(name, manifest, expected) {
     const diagnostic = renderNativeGatewayDiagnostic(manifest, name);

package/dist/standalone/manifest.d.ts

@@ -102,6 +102,7 @@ export interface StandaloneManifest {
     /** `install.sharedFolder`: the Shared Folder the install wizard selects or `data-share` creates. */
     sharedFolder?: SharedFolder;
     installSettings?: InstallSettings;
+    installPorts?: true;
     /** `backup`: Hyper Backup application backup; on by default for native Apps, absent when opted out. */
     hyperBackup?: HyperBackup;
     /** Who may use the app at all; absent keeps the route policy alone. */

package/dist/standalone/manifest.js

@@ -1,3 +1,4 @@
+import { portDefaults } from "./install-ports.js";
 import { readPackageDependencies, packageDependencies, dependencyError } from "./package-dependencies.js";
 import { readInstallSettings } from './install-settings.js';
 import { auditGoRoutes } from './route-audit.js';
@@ -271,6 +272,9 @@ function readManifest(raw, c) {
     const sharedFolder = raw.install === undefined
         ? undefined
         : readSharedFolder(raw.install, (e) => c.fail(e.code, e.message));
+    const installPorts = isRecord(raw.install) && raw.install.ports === true ? true : undefined;
+    if (isRecord(raw.install) && raw.install.ports !== undefined && raw.install.ports !== true)
+        c.fail("INSTALL_PORT_INVALID", "install.ports must be true when present");
     const installSettings = readInstallSettings(isRecord(raw.install) ? raw.install.settings : undefined, e => c.fail(e.code, e.message));
     const hyperBackup = readHyperBackup(raw.backup, { compose: raw.compose !== undefined }, e => c.fail(e.code, e.message));
     const compose = arches &&
@@ -281,6 +285,7 @@ function readManifest(raw, c) {
             composeMounts: capabilities.composeMounts,
             sharedFolder,
             installSettings,
+            installPorts: installPorts ? portDefaults({ installPorts, identityGateway: gatewayRaw }) : undefined,
         });
     if (raw.compose !== undefined &&
         ((raw.daemon !== undefined && !timeoutOnly) ||
@@ -303,6 +308,16 @@ function readManifest(raw, c) {
         c.fail("COMPOSE_WEB_INVALID", "Compose upstream is derived from the SDK Compose ingress endpoint; remove identity_gateway.upstream.");
     // A failed Compose plan already explains the invalid upstream declaration.
     const identityGateway = raw.compose !== undefined && !compose ? undefined : readIdentityGateway(gatewayValue, daemon || (compose ? { targets: compose.targets } : undefined), (e) => c.fail(e.code, e.message), false, Boolean(compose?.plan.ingress));
+    if (installPorts && !identityGateway)
+        c.fail('INSTALL_PORT_INVALID', 'install.ports requires an identity gateway');
+    if (installPorts && identityGateway) {
+        const [major, minor, patch] = identityGateway.sdk.split('.').map(Number);
+        if (major === 0 && (minor < 38 || minor === 38 && patch < 2))
+            c.fail('SDK_PORT_SETTINGS_UNSUPPORTED', 'install.ports requires SDK 0.38.2 or newer');
+        for (const p of Object.values(portDefaults({ identityGateway, installPorts })))
+            if (!Number.isInteger(p.default) || p.default < 1024 || p.default > 65535 || [1900, 5000, 5001, 5005, 5006, 5353, 6690].includes(p.default))
+                c.fail('INSTALL_PORT_INVALID', 'Choose non-reserved manifest port defaults from 1024 to 65535');
+    }
     if (daemon?.ingress) {
         const problem = daemonIngressMinDsmProblem(osMinVer);
         if (problem)
@@ -550,6 +565,7 @@ function readManifest(raw, c) {
         ...(uninstall ? { uninstall } : {}),
         ...(sharedFolder ? { sharedFolder } : {}),
         ...(installSettings ? { installSettings } : {}),
+        ...(installPorts ? { installPorts } : {}),
         ...(hyperBackup ? { hyperBackup } : {}),
         ...(entry ? { entry } : {}),
         ...(integrations?.length ? { integrations } : {}),

package/dist/standalone/native-gateway.d.ts

@@ -4,6 +4,7 @@ type Target = {
     package: string;
     os_min_ver?: string;
     identityGateway?: NativeGatewayPlan;
+    installPorts?: true;
 };
 export declare const NATIVE_GATEWAY_CONFIG = "sso/native-nginx.conf";
 export declare function nativeGatewaySdk(sdk: string): boolean;

package/dist/standalone/native-gateway.js

@@ -14,6 +14,8 @@ export function nativeGatewaySupported(m) {
 export function renderNativeGatewayDiagnostic(m, hook) {
     if (!nativeGatewaySupported(m) || !['start-stop-status', 'postinst', 'postupgrade', 'preupgrade', 'preuninst'].includes(hook))
         return '';
+    if (m.installPorts)
+        return managedPortHook(m, hook, false);
     const ports = [...new Set([m.identityGateway.listen.https, m.identityGateway.listen.http].filter((port) => port !== undefined))];
     const action = hook === 'start-stop-status'
         ? `  case "\${1:-}" in prestart|prestop|start|stop|restart) action="$1" ;; *) exit 0 ;; esac\n`
@@ -43,6 +45,8 @@ synopkgland_native_diagnostic "$@" >/dev/null 2>&1 || :
 export function renderNativeGatewayPortWait(m, hook) {
     if (hook !== 'start-stop-status' || !nativeGatewaySupported(m))
         return '';
+    if (m.installPorts)
+        return managedPortHook(m, hook, true);
     const ports = [...new Set([m.identityGateway.listen.https, m.identityGateway.listen.http].filter((port) => port !== undefined))];
     return `synopkgland_native_port_wait() (
   [ "\${1:-}" = prestart ] || exit 0
@@ -108,7 +112,7 @@ export function nativeGatewayResource(m) {
     const g = m.identityGateway, https = g.listen.https ?? g.listen.http;
     const ports = [https, ...(g.listen.http && g.listen.http !== https ? [g.listen.http] : [])];
     return { 'nginx-static-config': { enable: [{ type: 'server', relpath: NATIVE_GATEWAY_CONFIG,
-                    ports: ports.map(port => ({ port, protocol: 'tcp', schema: port === https ? 'https' : 'http' })) }] } };
+                    ...(!m.installPorts ? { ports: ports.map(port => ({ port, protocol: 'tcp', schema: port === https ? 'https' : 'http' })) } : {}) }] } };
 }
 export function renderNativeGatewayConfig(m) {
     if (!nativeGatewaySupported(m))
@@ -199,3 +203,31 @@ NATIVE_TLS_CONFIG
 synopkgland_native_keys || exit $?
 `;
 }
+function managedPortHook(m, hook, wait) {
+    const keys = Object.keys(m.identityGateway.listen).map(key => 'gateway_' + key);
+    return `synopkgland_managed_port_${wait ? 'wait' : 'diagnostic'}() (
+  ${wait ? '[ "\${1:-}" = prestart ] || exit 0' : ''}
+  target="\${SYNOPKG_PKGDEST:-/var/packages/${m.package}/target}"
+  remaining=${wait ? 30 : 0}
+  while :; do
+    busy=0
+    for key in ${keys.join(' ')}; do
+      port=
+      IFS= read -r port < "$target/install/port-values/$key.value" || [ -n "\${port:-}" ] || exit 0
+      case "$port" in ''|*[!0-9]*) exit 0 ;; esac
+      [ "$port" -ge 1024 ] && [ "$port" -le 65535 ] || exit 0
+      hex=$(printf '%04X' "$port")
+      for table in /proc/net/tcp /proc/net/tcp6; do
+        [ -r "$table" ] || continue
+        if awk -v port="$hex" '$4 == "0A" && toupper($2) ~ (":" port "$") { found=1 } END { exit !found }' "$table"; then busy=1; fi
+      done
+      ${wait ? '' : `logger -p user.warning -t synopkgland "NATIVE_GATEWAY_LIFECYCLE package=${m.package} hook=${hook} port=$port busy=$busy" || :`}
+    done
+    [ "$busy" -eq 1 ] && [ "$remaining" -gt 0 ] || break
+    sleep 0.5 || break
+    remaining=$((remaining - 1))
+  done
+)
+synopkgland_managed_port_${wait ? 'wait' : 'diagnostic'} "$@" >/dev/null 2>&1 || :
+`;
+}

package/dist/standalone/resource.d.ts

@@ -16,6 +16,7 @@ export declare function renderStandaloneResource(m: {
     capabilities: Capabilities;
     compose?: ComposeApp;
     sharedFolder?: SharedFolder;
+    installPorts?: true;
     daemon?: {
         ingress?: DaemonIngress;
     };

package/dist/standalone/resource.js

@@ -20,6 +20,7 @@ export function renderStandaloneResource(m, portal) {
             ? renderDockerProjectResource(m.package, "compose", false, m.compose.plan.project_name)
             : {}),
         ...(dataShare ? { "data-share": dataShare } : {}),
+        ...(m.installPorts ? { "port-config": { "protocol-file": `install/${m.package}.sc` } } : {}),
         ...(m.capabilities.jobs ? { "systemd-user-unit": {} } : {}),
         ...(Object.keys(webConfig).length ? { 'web-config': webConfig } : {}),
     };

package/dist/standalone/shared-folder.d.ts

@@ -4,17 +4,17 @@ import { type InstallWizardStep } from "../build-spk/install-wizard.js";
 /**
  * `install.sharedFolder`: the Shared Folder a package keeps its files in.
  *
- * `select`: the install and upgrade wizard offer the NAS's existing Shared
- * Folders. DSM cannot grant a package account access to a folder chosen at
- * install time, so the administrator grants `permission` afterwards.
- * `create`: DSM's official `data-share` resource creates the fixed `name` and
- * gives the package account `permission`. Removing the package never deletes it.
+ * `dedicated`: DSM creates the declared name and grants exactly RO/RW. The
+ * wizard may select an existing folder only after checking package access.
+ * `select`: an explicit existing folder, with the same field validation.
+ * `create`: a fixed DSM resource without an existing-folder option.
+ * Removing the package never deletes shared data.
  */
 export interface SharedFolder {
-    mode: "select" | "create";
+    mode: "select" | "create" | "dedicated";
     /** The wizard variable and the `var/config.json` entry for this folder. */
     key: string;
-    /** `create` only: the Shared Folder `data-share` creates. */
+    /** Dedicated or fixed Shared Folder created by DSM data-share. */
     name?: string;
     permission: "ro" | "rw";
 }