@synopackageland/cli 0.21.1 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.23.0 (2026-10-21)
+
+- Validate the explicit OIDC `browser_redirect` contract before packaging and pin templates/SDK 0.23.0.
+- Reuse executor/v0.20.0 with unchanged executor and lifecycle payloads.
+
+## 0.22.0 (2026-10-21)
+
+- Support SDK/App 0.22.x and pin templates 0.22.0 with published UI 0.12.5.
+- Register actionable diagnostics for invalid, unsupported or unbuildable native installation settings.
+- Validate provider-only public upstream access, host UDP listeners, fixed launch paths and native installation settings.
+- Reuse immutable executor/v0.20.0 with exact SDK-version digest checks.
+
 ## 0.21.1 (2026-10-21)
 
 - Resolve SDK/App 0.21.1 to the verified immutable executor/v0.20.0 release while keeping exact SDK-version digest checks.

package/dist/cli.js

@@ -8,6 +8,7 @@ import { contractIconPath } from "./contract/icon.js";
 import { codedMessage, formatErrors } from "./errors.js";
 import { getErrorCode } from "./error-registry.js";
 import { formatInspectReport, inspectProject } from "./inspect.js";
+import { gatewayAdmissionReport } from "./standalone/identity-gateway.js";
 import { formatPinReport, pinProjectImages } from "./images/pin.js";
 import { initFromTemplate, initNextSteps, isTemplateName, listTemplates, } from "./init.js";
 import { templatesRoot } from "./template-paths.js";
@@ -116,9 +117,14 @@ function formatRootSteps(report) {
     ];
     return steps.length ? [`Root steps: ${steps.join(", ")}`] : [];
 }
+function formatInstallSettings(settings) {
+    return settings ? Object.entries(settings).map(([key, s]) => `Installation setting ${key}: ${s.type}, ${s.required ? 'required' : 'optional'} (${s.label}); values are private`) : [];
+}
 function formatSpkReport(spk, report) {
     return [
         `SPK: ${spk}`,
+        ...formatInstallSettings(report.installSettings),
+        ...(report.identityGateway ? [report.identityGateway.notice, `OIDC issuer access: ${report.identityGateway.issuerAccess}`] : []),
         `package: ${report.package ?? "?"}  version: ${report.version ?? "?"}`,
         report.synopkgland
             ? `arch: ${report.arch ?? "?"}  runtime: ${report.kind ?? "?"}`
@@ -126,6 +132,9 @@ function formatSpkReport(spk, report) {
         ...(report.compose
             ? [
                 `Compose readiness: ${report.compose.readiness.profile}`,
+                ...(report.compose.hostUdp?.length
+                    ? [`Host UDP listeners: ${report.compose.hostUdp.map(l => `${l.port} (${l.purpose})`).join(", ")}`]
+                    : []),
                 report.compose.readiness.limitation,
             ]
             : []),
@@ -338,6 +347,8 @@ export async function runCli(argv) {
                 : undefined;
             emit("check", {
                 package: loaded.manifest.package,
+                ...("installSettings" in loaded.manifest && loaded.manifest.installSettings ? { installSettings: loaded.manifest.installSettings } : {}),
+                ...("identityGateway" in loaded.manifest && gatewayAdmissionReport(loaded.manifest.identityGateway, loaded.manifest.entry) ? { identityGateway: gatewayAdmissionReport(loaded.manifest.identityGateway, loaded.manifest.entry) } : {}),
                 capabilities: "capabilities" in loaded.manifest
                     ? loaded.manifest.capabilities
                     : {},
@@ -348,6 +359,8 @@ export async function runCli(argv) {
                             images: loaded.manifest.compose.plan.images,
                             services: loaded.manifest.compose.plan.services,
                             mountsBlocked: loaded.manifest.compose.plan.mounts_blocked,
+                            ...(loaded.manifest.compose.plan.host_udp?.length
+                                ? { hostUdp: loaded.manifest.compose.plan.host_udp } : {}),
                             acceptanceBlockers: loaded.manifest.compose.plan.acceptance_blockers,
                         },
                     }
@@ -356,6 +369,8 @@ export async function runCli(argv) {
                 ...(loginStyle ? { loginStyle } : {}),
             }, [
                 "Validation passed.",
+                ...formatInstallSettings("installSettings" in loaded.manifest ? loaded.manifest.installSettings : undefined),
+                ...("identityGateway" in loaded.manifest && gatewayAdmissionReport(loaded.manifest.identityGateway) ? [gatewayAdmissionReport(loaded.manifest.identityGateway).notice] : []),
                 ...("compose" in loaded.manifest && loaded.manifest.compose
                     ? [
                         "Containers use the fixed package identity; signed-in File Station ACLs are not inherited.",
@@ -690,9 +705,13 @@ export async function runCli(argv) {
                     }),
             });
         const builtManifest = standalone && !isNativeLayout(standalone) ? loadStandaloneManifest(standalone) : undefined;
+        const installSettings = builtManifest && builtManifest.ok ? builtManifest.manifest.installSettings : undefined;
         const devices = builtManifest && builtManifest.ok ? builtManifest.manifest.compose?.plan.devices : undefined;
+        const identityGateway = builtManifest && builtManifest.ok ? gatewayAdmissionReport(builtManifest.manifest.identityGateway, builtManifest.manifest.entry) : undefined;
         const approval = await Promise.all(outputs.map(async (output) => ({ output, ...await spkApprovalDiff(output, options.baseline && resolve(options.baseline)) })));
         const lines = [
+            ...formatInstallSettings(installSettings),
+            ...(identityGateway ? [identityGateway.notice] : []),
             ...approval.map(item => item.output + "\n" + formatApprovalDiff(item)),
             ...outputs.map((output) => `Built ${output}`),
             ...(devices?.gpu ? [`GPU: ${devices.gpu.paths}; GID source: ${devices.gpu.gid_source}; fallback: ${devices.gpu.fallback}`] : []),
@@ -700,7 +719,7 @@ export async function runCli(argv) {
         ];
         if (reproducible && !reproducible.identical)
             throw Object.assign(failure("BUILD_NOT_REPRODUCIBLE", lines.join("\n"), "Find the payload files that differ between builds (timestamps, random paths, unpinned dependencies) and retry after fixing them."), { report: { outputs, reproducible } });
-        emit("build", { outputs, approval, ...(devices ? { compose: { devices } } : {}), ...(reproducible ? { reproducible } : {}) }, lines.join("\n"));
+        emit("build", { outputs, approval, ...(installSettings ? { installSettings } : {}), ...(identityGateway ? { identityGateway } : {}), ...(devices ? { compose: { devices } } : {}), ...(reproducible ? { reproducible } : {}) }, lines.join("\n"));
     });
     if (json)
         console.log = (...args) => console.error(...args);

package/dist/deploy/native-install-values.js

@@ -16,10 +16,11 @@ export function resolveNativeInstallValues(manifest, provided, state) {
     const folder = manifest.sharedFolder?.mode === "select" ? manifest.sharedFolder : undefined;
     const key = folder?.key;
     const changeKey = key ? `CHANGE_${key}` : undefined;
+    const settingNames = Object.keys(manifest.installSettings ?? {}).map(key => `pkgwizard_setting_${key}`);
     const names = Object.keys(provided);
-    if (!selected && !folder && names.length)
+    if (!selected && !folder && !settingNames.length && names.length)
         return fail("DEPLOY_PARAM_UNDECLARED", `${manifest.package} has no install wizard values; remove --param ${names[0]}.`);
-    const unknown = names.find((name) => !(selected && (name === "delegate_share" || name === "delegate_home")) && name !== key && name !== changeKey);
+    const unknown = names.find((name) => !(selected && (name === "delegate_share" || name === "delegate_home")) && name !== key && name !== changeKey && !settingNames.includes(name));
     if (unknown)
         return fail("DEPLOY_PARAM_UNDECLARED", `--param ${unknown} is not an install wizard value. Use: ${folder ? `--param ${folder.key}=<shared folder>` : USAGE}.`);
     if (key && changeKey) {
@@ -42,5 +43,12 @@ export function resolveNativeInstallValues(manifest, provided, state) {
         return fail("DEPLOY_PARAM_TYPE_INVALID", "Choose either --param delegate_share or --param delegate_home=true, not both.");
     if (selected && !state.installed && share === undefined && home !== "true")
         return fail("DEPLOY_PARAM_REQUIRED", `The first install of ${manifest.package} must select the delegate scope: ${USAGE}.`);
+    for (const [key, setting] of Object.entries(manifest.installSettings ?? {})) {
+        const name = `pkgwizard_setting_${key}`, value = provided[name];
+        if (value !== undefined && (value.length > 2048 || /[\x00-\x1f\x7f]/.test(value)))
+            return fail('DEPLOY_PARAM_TYPE_INVALID', `--param ${name} must be a bounded literal HTTPS origin.`);
+        if (setting.required && !state.installed && !value)
+            return fail('DEPLOY_PARAM_REQUIRED', `Supply --param ${name}=<HTTPS origin>. SDK hooks validate it on the NAS.`);
+    }
     return { ok: true, extraValues: { ...provided } };
 }

package/dist/error-registry.js

@@ -1,6 +1,9 @@
 import { COMPOSE_ERRORS } from "./standalone/compose-errors.js";
 export const ERROR_REGISTRY = {
     ...COMPOSE_ERRORS,
+    INSTALL_SETTINGS_INVALID: { "code": "INSTALL_SETTINGS_INVALID", "description": "The installation setting declaration is invalid.", "suggestion": "Declare 1–32 lowercase identifier keys in install.settings, each with type https-origin, a plain label and an explicit boolean required; omit defaults and values." },
+    SDK_INSTALL_SETTINGS_UNSUPPORTED: { "code": "SDK_INSTALL_SETTINGS_UNSUPPORTED", "description": "The selected SDK does not provide native installation settings.", "suggestion": "Pin SDK 0.23.0 or a matching supported release with installsettings/cmd/control, then rebuild with the matching CLI." },
+    SDK_INSTALL_SETTINGS_BUILD_FAILED: { "code": "SDK_INSTALL_SETTINGS_BUILD_FAILED", "description": "The SDK installation settings controller could not be built.", "suggestion": "Install the pinned Go toolchain, inspect the compiler diagnostics and rebuild with a complete matching SDK release." },
     INIT_HEALTH_INVALID: { code: "INIT_HEALTH_INVALID", description: "The Compose readiness selection is invalid.", suggestion: "Supply both --health-path and --health-status with the actual endpoint and expected 2xx response; redirects are not followed." },
     INIT_UPSTREAM_IMAGE_REQUIRED: { code: "INIT_UPSTREAM_IMAGE_REQUIRED", description: "The official upstream image repository was not selected.", suggestion: "Use init --upstream-fork --upstream-image <official-repository> for Compose." },
     INIT_UPSTREAM_IMAGE_INVALID: { code: "INIT_UPSTREAM_IMAGE_INVALID", description: "The upstream image repository is invalid.", suggestion: "Supply the official repository without a tag or digest; upgrade.sh selects the matching release and resolves its digest." },

package/dist/runtime/executor-digests.json

@@ -1,16 +1,5 @@
 {
-    "0.21.0": {
-        "x86_64": "e27cfeb85fed221b06f9c58166f02c0f701a724308cd17c96a43a843a0b5c4aa",
-        "aarch64": "908db00cbd37d072f6ffc339e7bca24da5efb8cddd4befcbad02c7398beb7191",
-        "armv7": "a0f35d62ec80a1bf3fb49f5e2d1a5f7576eda569a6fd0695084cec6cb8e100bc",
-        "lifecycle": {
-            "x86_64": "9bb53301670b43cdcd6e21cebac99ab7abd82962d874f32423a81e6cb49d4972",
-            "aarch64": "38fe873c86eb102c850baa1f304114a83a31d1df72defd22792bc37610fec9bb",
-            "armv7": "256fb348b275da7ac5728a3cb7cb7c65660de0d5c2c59430ab4f5ade1b0a3681"
-        },
-        "goToolchain": "go1.26.9"
-    },
-    "0.21.1": {
+    "0.23.0": {
         "x86_64": "e27cfeb85fed221b06f9c58166f02c0f701a724308cd17c96a43a843a0b5c4aa",
         "aarch64": "908db00cbd37d072f6ffc339e7bca24da5efb8cddd4befcbad02c7398beb7191",
         "armv7": "a0f35d62ec80a1bf3fb49f5e2d1a5f7576eda569a6fd0695084cec6cb8e100bc",

package/dist/runtime/sdk-source.js

@@ -76,7 +76,7 @@ function goMod(backendDir) {
     }
 }
 /** SDK releases that reuse an immutable executor release with identical payload bytes. */
-const EXECUTOR_RELEASES = { '0.21.0': '0.20.0', '0.21.1': '0.20.0' };
+const EXECUTOR_RELEASES = { '0.21.0': '0.20.0', '0.21.1': '0.20.0', '0.22.0': '0.20.0', '0.23.0': '0.20.0' };
 /**
  * The module directories of one SDK version. SYNOPKGLAND_SDK_DIR names a
  * local sdk checkout (development and gates only); otherwise modules come from

package/dist/standalone/build.js

@@ -1,3 +1,4 @@
+import { buildInstallSettings } from './install-settings.js';
 import { PORTAL_REQUIRES_EXECUTOR } from "../portal/alias.js";
 import { buildApiDescription } from "./api-description.js";
 import { goChildEnv } from "../runtime/go-env.js";
@@ -153,6 +154,7 @@ export async function buildStandalone(options) {
             const daemonControl = await buildDaemonControl(manifest, arch, archWork, run);
             const identityGateway = await buildIdentityGateway(manifest, arch, archWork, run);
             const composeControl = await buildComposeControl(manifest, arch, archWork, run);
+            const installSettingsControl = await buildInstallSettings(manifest, arch, archWork, run);
             const composeStorageInit = await buildComposeStorageInit(manifest, arch, archWork, run);
             // A portal needs the executor, so the executor's SDK carries the panel text.
             const portalText = manifest.portal && executor
@@ -167,6 +169,7 @@ export async function buildStandalone(options) {
                 identityGateway,
                 composeControl,
                 composeStorageInit,
+                installSettingsControl,
                 backgroundWorker,
                 executor,
                 app,

package/dist/standalone/compose-errors.js

@@ -1,5 +1,10 @@
 /** SDK planner errors accepted at this versioned tool boundary. */
 export const COMPOSE_ERRORS = {
+    COMPOSE_HOST_UDP_INVALID: {
+        code: "COMPOSE_HOST_UDP_INVALID",
+        description: "The host UDP listener declaration is invalid.",
+        suggestion: "Declare at most 32 distinct compose.host_udp ports from 1024 to 65535, each with a lowercase purpose label. Use the verified nonroot host Web topology; no added capabilities are required.",
+    },
     COMPOSE_GPU_INVALID: {
         code: "COMPOSE_GPU_INVALID",
         description: "The GPU declaration requires bounded package-UID services.",

package/dist/standalone/compose.d.ts

@@ -1,9 +1,14 @@
+import type { InstallSettings } from './install-settings.js';
 import { type ComposeAppData } from "../runtime/compose-data.js";
 import type { NativeArchFamily } from "../build-spk/dsm-arch.js";
 import { type Daemon } from "./daemon.js";
 import type { SharedFolder } from "./shared-folder.js";
 import type { StandaloneError, StandaloneManifest } from "./manifest.js";
 export interface ComposePlan {
+    host_udp?: Array<{
+        port: number;
+        purpose: string;
+    }>;
     devices?: {
         gpu?: {
             services: string[];
@@ -81,13 +86,14 @@ export interface ComposeApp {
     document: Record<string, any>;
     plan: ComposePlan;
 }
-export declare const COMPOSE_FIELDS: readonly ["devices", "startup_timeout_seconds", "resource_prefix", "files", "env_files", "profiles", "web", "data", "shares", "network", "services", "helpers", "sdk"];
+export declare const COMPOSE_FIELDS: readonly ["host_udp", "devices", "startup_timeout_seconds", "resource_prefix", "files", "env_files", "profiles", "web", "data", "shares", "network", "services", "helpers", "sdk"];
 export declare function readComposeApp(value: unknown, root: string, arches: NativeArchFamily[], fail: (e: StandaloneError) => void, context?: {
     package?: string;
     sdk?: string;
     mode?: string;
     composeMounts?: boolean;
     sharedFolder?: SharedFolder;
+    installSettings?: InstallSettings;
     resolveImages?: boolean;
     architecture?: NativeArchFamily;
     imageProofs?: unknown;
@@ -106,8 +112,12 @@ export declare function composeNetwork(m: Pick<StandaloneManifest, "compose" | "
     ingress?: {
         candidate: number;
     } | undefined;
-    mode: string;
     ports: number[];
+    host_udp?: {
+        port: number;
+        purpose: string;
+    }[] | undefined;
+    mode: string;
 };
 export declare function composeSource(c: ComposeApp): string;
 /** Retain upstream bytes, the true override and a lock without secret values. */

package/dist/standalone/compose.js

@@ -12,6 +12,7 @@ import { goChildEnv } from "../runtime/go-env.js";
 import { sdkSource } from "../runtime/sdk-source.js";
 import { readDaemon } from "./daemon.js";
 export const COMPOSE_FIELDS = [
+    "host_udp",
     "devices",
     "startup_timeout_seconds",
     "resource_prefix",
@@ -69,7 +70,7 @@ export function readComposeApp(value, root, arches, fail, context = {}) {
     if (!record(value) ||
         Object.keys(value).some((k) => !COMPOSE_FIELDS.includes(k)) ||
         !Array.isArray(value.files))
-        return invalid("compose requires files, with optional env_files, profiles, web, data, shares, devices, network, services, helpers and sdk; old file/targets syntax is removed.");
+        return invalid("compose requires files, with optional env_files, profiles, web, data, shares, devices, host_udp, network, services, helpers and sdk; old file/targets syntax is removed.");
     if (value.sdk !== undefined &&
         (typeof value.sdk !== "string" || !/^\d+\.\d+\.\d+$/.test(value.sdk)))
         return invalid("compose.sdk must name the matching SDK release.", "SDK_COMPOSE_UNSUPPORTED");
@@ -77,6 +78,20 @@ export function readComposeApp(value, root, arches, fail, context = {}) {
         (!Number.isInteger(value.startup_timeout_seconds) ||
             value.startup_timeout_seconds < 2 || value.startup_timeout_seconds > 900))
         return invalid("compose.startup_timeout_seconds must be an integer from 2 to 900 seconds (default 120).", "COMPOSE_STARTUP_INVALID");
+    let hostUdp;
+    if (value.host_udp !== undefined) {
+        const ports = new Set();
+        if (!Array.isArray(value.host_udp) || value.host_udp.length > 32 || value.host_udp.some((listener) => {
+            if (!record(listener) || Object.keys(listener).some(k => k !== "port" && k !== "purpose") ||
+                !Number.isInteger(listener.port) || listener.port < 1024 || listener.port > 65535 ||
+                typeof listener.purpose !== "string" || !/^[a-z][a-z0-9-]{0,63}$/.test(listener.purpose) || ports.has(listener.port))
+                return true;
+            ports.add(listener.port);
+            return false;
+        }))
+            return invalid("compose.host_udp allows at most 32 distinct ports 1024-65535 with lowercase purpose labels of 1-64 characters.", "COMPOSE_HOST_UDP_INVALID");
+        hostUdp = [...value.host_udp].map(l => ({ port: l.port, purpose: l.purpose })).sort((a, b) => a.port - b.port);
+    }
     const sdk = typeof value.sdk === "string" ? value.sdk : (context.sdk ?? templateSdkVersion());
     let targets = {};
     if (value.helpers !== undefined) {
@@ -95,6 +110,7 @@ export function readComposeApp(value, root, arches, fail, context = {}) {
                 identity_mode: context.mode ?? "none",
                 compose_mounts: context.composeMounts === true,
                 ...(context.sharedFolder?.mode === "select" ? { install_shared_folder: context.sharedFolder } : {}),
+                install_settings: context.installSettings,
                 resolve_images: context.resolveImages === true,
                 registry_mirrors: context.resolveImages &&
                     process.env.SYNOPKGLAND_COMPOSE_REGISTRY_MIRRORS
@@ -119,6 +135,9 @@ export function readComposeApp(value, root, arches, fail, context = {}) {
         if (value.startup_timeout_seconds !== undefined &&
             plan.startup_timeout_seconds !== value.startup_timeout_seconds)
             throw new Error("[SDK_COMPOSE_UNSUPPORTED] This SDK does not implement the declared startup budget; use the matching SDK/CLI release.");
+        if (JSON.stringify(plan.host_udp ?? []) !== JSON.stringify(hostUdp ?? []) ||
+            JSON.stringify(plan.lock?.host_udp ?? []) !== JSON.stringify(hostUdp ?? []))
+            throw new Error("[SDK_COMPOSE_UNSUPPORTED] The SDK planner and lock must preserve the exact host_udp declaration; use the matching SDK/CLI release.");
         const document = parse(plan.effective);
         const volumes = Object.entries(document?.volumes ?? {});
         if ((!validComposeAppData(plan.app_data, context.package ?? "ComposeApp")
@@ -169,6 +188,7 @@ export function composeNetwork(m) {
             "host";
     return {
         mode: c.plan.mounts_blocked ? "settings" : host ? "host" : "bridge",
+        ...(c.plan.host_udp?.length ? { host_udp: c.plan.host_udp } : {}),
         ports: c.web ? [c.plan.ingress?.port ?? c.web.host_port ?? c.web.port] : [],
         ...(c.plan.ingress
             ? { ingress: { candidate: c.plan.ingress.candidate } }
@@ -271,6 +291,7 @@ export function lockComposeImages(m, arch, resolveImages, imageProofs) {
         mode: m.identityGateway?.mode ?? "none",
         composeMounts: m.capabilities.composeMounts,
         sharedFolder: m.sharedFolder,
+        installSettings: m.installSettings,
         resolveImages,
         architecture: arch,
         imageProofs,

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

@@ -35,7 +35,11 @@ export interface IdentityGateway {
     /** The SDK release the gateway is built from. */
     sdk: string;
     mode: GatewayMode;
+    /** Fixed same-origin menu target, including optional query and fragment. */
+    launch_path?: string;
     access?: WebAccessMode;
+    /** Public App routes keep upstream authentication; access still protects OIDC issuance. */
+    upstream_access?: "protected" | "public";
     groups?: string[];
     max_upload_bytes?: number;
     response_header_timeout_seconds?: number;
@@ -55,6 +59,10 @@ export interface IdentityGateway {
     roles?: GatewayRoles;
     headers?: Partial<Record<"user" | "email" | "name" | "groups" | "uid", string>>;
     oidc?: {
+        browser_redirect?: {
+            html_paths?: string[];
+            same_origin_referrer?: boolean;
+        };
         native_login?: boolean;
         issuer_port: number;
         browser?: GatewayBrowser;
@@ -81,6 +89,18 @@ export type DeleteAction = {
     exec: string[];
 };
 export declare function readIdentityGateway(value: unknown, daemon: Pick<Daemon, "targets"> | undefined, fail: (error: StandaloneError) => void, packagedPayload?: boolean, composeBridge?: boolean): IdentityGateway | undefined;
+export interface GatewayAdmissionReport {
+    mode: "oidc";
+    issuerAccess: WebAccessMode;
+    issuerEntry: "admin-only" | "app-privilege";
+    issuerGroups?: string[];
+    upstreamAccess: "public";
+    upstreamProtected: false;
+    notice: string;
+}
+export declare function gatewayAdmissionReport(g?: IdentityGateway, entry?: string): GatewayAdmissionReport | undefined;
+/** Stable build contract; human-facing wording is not part of the policy digest. */
+export declare function gatewayAdmissionPolicy(g?: IdentityGateway, entry?: string): Omit<GatewayAdmissionReport, "notice"> | undefined;
 /** target/sso/gateway.json, the SDK gateway's configuration (idgateway.Config). */
 export declare function identityGatewayConfig(m: StandaloneManifest): string;
 /** The daemon as the controller runs it: the gateway, with the App as its child. */

package/dist/standalone/identity-gateway.js

@@ -1,6 +1,6 @@
 import { nativeGatewaySupported } from './native-gateway.js';
 import { operationBudgetSeconds, runtimeBudgetSdkSupported } from "../runtime/runtime-budgets.js";
-import { existsSync, lstatSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { PINNED_GO_HINT, pinnedGoBuildEnv, pinnedGoProblem, } from "../build-spk/go-toolchain.js";
 import { goChildEnv } from "../runtime/go-env.js";
@@ -127,6 +127,8 @@ export function readIdentityGateway(value, daemon, fail, packagedPayload = false
             "sdk",
             "mode",
             "access",
+            "upstream_access",
+            "launch_path",
             "groups",
             "max_upload_bytes",
             "response_header_timeout_seconds",
@@ -143,10 +145,27 @@ export function readIdentityGateway(value, daemon, fail, packagedPayload = false
             "token",
             "account",
         ])) {
-        return invalid("accepts only sdk, mode, upstream, listen, passthrough, redirects, email_domain, session_ttl, roles, headers, oidc, token and account.");
+        return invalid("accepts only sdk, mode, access, upstream_access, groups, upstream, listen, passthrough, optional_passthrough, redirects, email_domain, session_ttl, roles, headers, oidc, token and account.");
     }
     const v = value;
+    if (v.launch_path !== undefined) {
+        try {
+            const raw = v.launch_path;
+            if (typeof raw !== "string" || raw.length > 2048 || !raw.startsWith("/") || raw.startsWith("//") || /[\\\x00-\x1f\x7f]/.test(decodeURIComponent(raw)))
+                throw new Error();
+            const path = decodeURIComponent(raw.split(/[?#]/, 1)[0]);
+            if (path.startsWith("//") || path.split("/").some(p => p === "." || p === "..") || path === "/_sso" || path.startsWith("/_sso/"))
+                throw new Error();
+        }
+        catch {
+            return invalid("launch_path must be a bounded local App URL outside /_sso.");
+        }
+    }
     const access = v.access ?? "dsm-users";
+    if (v.upstream_access !== undefined && v.upstream_access !== "protected" && v.upstream_access !== "public")
+        return invalid("upstream_access must be protected or public.");
+    if (v.upstream_access === "public" && (v.mode !== "oidc" || access === "public" || v.optional_passthrough !== undefined))
+        return invalid("public upstream_access requires oidc with DSM issuer access and cannot combine with optional_passthrough.");
     if (!isWebAccessMode(access) || (access === "public" && v.mode !== "none"))
         return invalid("access must be dsm-users, dsm-admins, dsm-groups or public (none mode only).");
     if (access === "dsm-groups" &&
@@ -244,7 +263,9 @@ export function readIdentityGateway(value, daemon, fail, packagedPayload = false
     const gateway = {
         sdk: v.sdk,
         mode: v.mode,
+        ...(v.launch_path !== undefined ? { launch_path: v.launch_path } : {}),
         access,
+        ...(v.upstream_access !== undefined ? { upstream_access: v.upstream_access } : {}),
         ...(Array.isArray(v.groups) ? { groups: v.groups } : {}),
         ...(v.max_upload_bytes !== undefined
             ? { max_upload_bytes: v.max_upload_bytes }
@@ -270,7 +291,7 @@ export function readIdentityGateway(value, daemon, fail, packagedPayload = false
     if (v.mode === "oidc") {
         const o = v.oidc;
         if (!record(o) ||
-            !only(o, ["issuer_port", "clients", "rewrite_json", "browser", "native_login"]) ||
+            !only(o, ["issuer_port", "clients", "rewrite_json", "browser", "native_login", "browser_redirect"]) ||
             (o.native_login !== undefined && typeof o.native_login !== "boolean") ||
             !port(o.issuer_port) ||
             !Array.isArray(o.clients) ||
@@ -291,6 +312,14 @@ export function readIdentityGateway(value, daemon, fail, packagedPayload = false
                 name(r.field))) {
             return invalid("oidc.rewrite_json entries are { method, path, field }.");
         }
+        const br = o.browser_redirect;
+        if (br !== undefined) {
+            const path = (p) => localPath(p) && p.length <= 512 && !/[%\s]/.test(p) && !p.startsWith("/_sso");
+            if (!record(br) || !only(br, ["html_paths", "same_origin_referrer"]) ||
+                (br.same_origin_referrer !== undefined && typeof br.same_origin_referrer !== "boolean") ||
+                (br.html_paths !== undefined && (!strings(br.html_paths, path, 16) || new Set(br.html_paths).size !== br.html_paths.length)))
+                return invalid("oidc.browser_redirect accepts only optional exact html_paths outside /_sso and same_origin_referrer.");
+        }
         const b = o.browser;
         if (b !== undefined) {
             const [major, minor] = v.sdk.split(".").map(Number);
@@ -313,6 +342,7 @@ export function readIdentityGateway(value, daemon, fail, packagedPayload = false
                 return invalid("oidc.browser needs fixed local start, login_paths and callback_paths outside /_sso.");
         }
         gateway.oidc = {
+            ...(br !== undefined ? { browser_redirect: br } : {}),
             ...(o.native_login !== undefined ? { native_login: o.native_login } : {}),
             issuer_port: o.issuer_port,
             ...(b !== undefined ? { browser: b } : {}),
@@ -354,6 +384,22 @@ export function readIdentityGateway(value, daemon, fail, packagedPayload = false
     return gateway;
 }
 const packageDest = (m) => `/var/packages/${m.package}/target`;
+export function gatewayAdmissionReport(g, entry) {
+    return g?.upstream_access === "public" ? {
+        mode: "oidc", issuerAccess: g.access ?? "dsm-users", upstreamAccess: "public", upstreamProtected: false,
+        issuerEntry: entry === "admin-only" ? "admin-only" : "app-privilege",
+        ...(g.access === "dsm-groups" ? { issuerGroups: g.groups } : {}),
+        notice: "Upstream routes are not protected by the gateway; the App owns authentication, CSRF, native clients and WebSockets. OIDC issuance still requires DSM sign-in and App privileges.",
+    } : undefined;
+}
+/** Stable build contract; human-facing wording is not part of the policy digest. */
+export function gatewayAdmissionPolicy(g, entry) {
+    const report = gatewayAdmissionReport(g, entry);
+    if (!report)
+        return;
+    const { notice: _, ...policy } = report;
+    return policy;
+}
 /** target/sso/gateway.json, the SDK gateway's configuration (idgateway.Config). */
 export function identityGatewayConfig(m) {
     const g = m.identityGateway;
@@ -365,9 +411,11 @@ export function identityGatewayConfig(m) {
             stop_seconds: m.daemon?.timeouts.stop ?? m.lifecycleTimeouts?.stop ?? 30,
         } : {}),
         mode: g.mode,
+        ...(g.launch_path ? { launch_path: g.launch_path } : {}),
         access: g.access ?? "dsm-users",
+        ...(g.upstream_access ? { upstream_access: g.upstream_access } : {}),
         ...(g.groups ? { groups: g.groups } : {}),
-        ...(m.entry ? { entry: m.entry } : {}),
+        ...(m.entry || g.upstream_access === "public" ? { entry: m.entry ?? "app-privilege" } : {}),
         ...(m.compose ? { container_app: true } : {}),
         ...(m.compose?.plan.mounts_blocked ? { compose_blocked: true } : {}),
         ...(g.max_upload_bytes ? { max_upload_bytes: g.max_upload_bytes } : {}),
@@ -442,6 +490,21 @@ export async function buildIdentityGateway(m, arch, work, run) {
         throw new StandaloneBuildError("SDK_DOWNLOAD_FAILED", error.message.replace(/^\[[A-Z_]+\] /, ""));
     }
     runtimeBudgetSource(sdk.goDir, m);
+    if (m.identityGateway.oidc?.browser_redirect) {
+        const capability = join(sdk.goDir, "idgateway/browser_redirect.go");
+        if (!existsSync(capability) || !/const BrowserRedirectVersion = 2\b/.test(readFileSync(capability, "utf8")))
+            throw new StandaloneBuildError("STANDALONE_IDENTITY_GATEWAY_INVALID", "The selected SDK lacks per-request OIDC browser redirect support; use a matching SDK release or an explicit development source override.");
+    }
+    if (m.identityGateway.upstream_access === "public") {
+        const capability = join(sdk.goDir, "idgateway/provider_only.go");
+        if (!existsSync(capability) || !/const ProviderOnlyOIDCVersion = 1\b/.test(readFileSync(capability, "utf8")))
+            throw new StandaloneBuildError("STANDALONE_IDENTITY_GATEWAY_INVALID", "The selected SDK lacks provider-only OIDC support; use a matching SDK release or an explicit development source override.");
+    }
+    if (m.identityGateway.launch_path) {
+        const capability = join(sdk.goDir, "idgateway/launch_path.go");
+        if (!existsSync(capability) || !/const LauncherPathVersion = 1\b/.test(readFileSync(capability, "utf8")))
+            throw new StandaloneBuildError("STANDALONE_IDENTITY_GATEWAY_INVALID", "The selected SDK lacks fixed launch_path support; use a matching SDK release or an explicit development source override.");
+    }
     const out = join(work, `identity-gateway-${arch}`);
     const ldflags = `-s -w -buildid= -X main.configPath=${packageDest(m)}/${GATEWAY_CONFIG_PATH}`;
     const result = await run("go", [

package/dist/standalone/inspect-spk.d.ts

@@ -1,11 +1,15 @@
+import { type InstallSettings } from './install-settings.js';
 import { type WebLaunchMode } from "../contract/web-launch.js";
 import { type ComposeApp } from "./compose.js";
 import { type ExecutorInspection } from "../runtime/executor-inspect.js";
 import { type AppScriptName } from "./app-scripts.js";
+import { type GatewayAdmissionReport } from "./identity-gateway.js";
 import type { EntryMode } from "./manifest.js";
 import { type UninstallCleanupItem } from "../runtime/uninstall-cleanup.js";
 export type SpkKind = "native-go" | "native-python" | "native-node" | "native-rust" | "binary" | "container" | "native-layout";
 export interface SpkInspection {
+    installSettings?: InstallSettings;
+    identityGateway?: GatewayAdmissionReport;
     kind?: SpkKind;
     package?: string;
     version?: string;
@@ -25,6 +29,7 @@ export interface SpkInspection {
         requiresAdminApproval: boolean;
     }>;
     compose?: {
+        hostUdp?: ComposeApp["plan"]["host_udp"];
         devices?: ComposeApp["plan"]["devices"];
         ingress?: ComposeApp["plan"]["ingress"];
         images: unknown[];

package/dist/standalone/inspect-spk.js

@@ -1,3 +1,4 @@
+import { readInstallSettings, settingsInstallSteps, settingsConfig, renderSettingsHook } from './install-settings.js';
 import { nativePortal } from "./portal.js";
 import { nativeGatewaySupported, renderNativeGatewayConfig, renderNativeGatewayPrepare, NATIVE_GATEWAY_CONFIG, gatewayEntryPath } from './native-gateway.js';
 import { inspectPortalInfo } from "../portal/info.js";
@@ -11,8 +12,8 @@ import { createHash } from "node:crypto";
 import { inspectNativeLayout } from "./native-layout.js";
 import { checkBridgeApp, checkBridgeExecutor } from "./inspect-bridge.js";
 import { inspectExecutor, inspectExecutorAnchor, } from "../runtime/executor-inspect.js";
-import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, } from "node:fs";
-import { unwrapAppScripts } from "./app-scripts.js";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { sdkScriptOf, unwrapAppScripts } from "./app-scripts.js";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import * as tar from "tar";
@@ -33,7 +34,7 @@ import { renderDelegateScopeSteps, } from "../build-spk/delegate-scope.js";
 import { renderUninstallWizardFiles } from "../build-spk/uninstall-wizard.js";
 import { renderNativePrivilege } from "../build-spk/native-lifecycle.js";
 import { renderUiConfig } from "./dsm-window.js";
-import { identityGatewayConfig, readIdentityGateway, } from "./identity-gateway.js";
+import { identityGatewayConfig, gatewayAdmissionReport, gatewayAdmissionPolicy, readIdentityGateway, } from "./identity-gateway.js";
 import { checkCgiBinary } from "./binary.js";
 import { renderStandaloneScript } from "./lifecycle.js";
 import { listPortExposures, loadCompose } from "../compose/analyze.js";
@@ -123,8 +124,14 @@ export async function inspectSpk(spkPath, expectedKind) {
                 findings.push("sdk-package.json does not match the schema 2 capability inventory.");
             }
         }
+        const identityGateway = await inspectProviderOnlyAdmission(dir, paths, metadata.provider_only_oidc, findings);
+        const installSettings = await inspectInstallSettings(dir, payload, metadata, findings);
         if (metadata.compose !== undefined) {
-            const result = await inspectUnifiedCompose(dir, payload, metadata, findings);
+            const result = await inspectUnifiedCompose(dir, payload, { ...metadata, installSettings }, findings);
+            if (installSettings)
+                result.installSettings = installSettings;
+            if (identityGateway)
+                result.identityGateway = identityGateway;
             result.icon = inspectPackageIcons(dir, findings);
             return result;
         }
@@ -270,7 +277,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);
+            checkSharedFolder(dir, findings, info.package, sharedFolder, executor?.policy.scope === "install-selected", portal, hasExecutor, nativeGateway, info.os_min_ver, installSettings);
         const icon = inspectPackageIcons(dir, findings);
         const cgiEntry = payload.find((entry) => entry.path === CGI_PAYLOAD_PATH);
         if (standalone && !cgiEntry) {
@@ -281,6 +288,8 @@ export async function inspectSpk(spkPath, expectedKind) {
         }
         return {
             kind,
+            ...(identityGateway ? { identityGateway } : {}),
+            ...(installSettings ? { installSettings } : {}),
             ...(launch ? { launch } : {}),
             icon,
             ...(executor ? { executor } : {}),
@@ -598,6 +607,7 @@ async function inspectUnifiedCompose(dir, payload, metadata, findings) {
             mode: cfg?.mode ?? "none",
             composeMounts: metadata.capabilities?.includes("composeMounts"),
             sharedFolder: recoverSharedFolder(readOptional(join(dir, "scripts/postinst"))),
+            installSettings: metadata.installSettings,
             architecture: arch,
             imageProofs: JSON.parse(readFileSync(join(root, "compose/images.json"), "utf8")),
         });
@@ -655,8 +665,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) {
-            for (const [name, text] of Object.entries(expectedWizardFiles(info.package, manifest.sharedFolder)))
+        if (manifest.sharedFolder || metadata.installSettings) {
+            for (const [name, text] of Object.entries(expectedWizardFiles(info.package, manifest.sharedFolder, false, undefined, metadata.installSettings)))
                 if (readOptional(join(dir, "WIZARD_UIFILES", name)) !== text)
                     throw new Error(`unexpected WIZARD_UIFILES/${name}; native share selection must match the declaration`);
         }
@@ -734,6 +744,7 @@ async function inspectUnifiedCompose(dir, payload, metadata, findings) {
         if (storageProblem)
             throw new Error(`[${storageProblem.code}] ${storageProblem.message}`);
         base.compose = {
+            ...(c.plan.host_udp?.length ? { hostUdp: c.plan.host_udp } : {}),
             ...(c.plan.devices ? { devices: c.plan.devices } : {}),
             ...(c.plan.ingress ? { ingress: c.plan.ingress } : {}),
             images: c.plan.images,
@@ -975,6 +986,40 @@ async function checkContainerExposure(dir, packageTgz, findings) {
 function readOptional(path) {
     return existsSync(path) ? readFileSync(path, "utf8") : undefined;
 }
+async function inspectProviderOnlyAdmission(dir, paths, saved, findings) {
+    try {
+        if (!paths.has("sso/gateway.json")) {
+            if (saved !== undefined)
+                throw new Error("OIDC admission policy has no gateway configuration");
+            return;
+        }
+        const root = join(dir, "gateway-admission-inspection");
+        mkdirSync(root);
+        await tar.x({ file: join(dir, "package.tgz"), cwd: root, filter: p => p.replace(/^\.\//, "") === "sso/gateway.json" });
+        const cfg = JSON.parse(readFileSync(join(root, "sso/gateway.json"), "utf8"));
+        if (cfg.upstream_access !== undefined && !["public", "protected"].includes(cfg.upstream_access))
+            throw new Error("invalid OIDC upstream admission policy");
+        if (cfg.upstream_access !== "public") {
+            if (saved !== undefined)
+                throw new Error("OIDC admission policy differs from its build declaration");
+            return;
+        }
+        if (cfg.mode !== "oidc" || !["dsm-users", "dsm-admins", "dsm-groups"].includes(cfg.access)
+            || !["app-privilege", "admin-only"].includes(cfg.entry) || cfg.compose_blocked
+            || Object.keys(cfg.optional_passthrough ?? {}).length)
+            throw new Error("OIDC admission policy weakens issuer or Share protection");
+        if (cfg.access === "dsm-groups" && (!Array.isArray(cfg.groups) || !cfg.groups.length || !cfg.groups.every((g) => typeof g === "string" && g.length > 0)))
+            throw new Error("OIDC admission policy has no valid issuer groups");
+        const report = gatewayAdmissionReport(cfg, cfg.entry);
+        if (!isDeepStrictEqual(gatewayAdmissionPolicy(cfg, cfg.entry), saved))
+            throw new Error("OIDC admission policy differs from its build declaration");
+        return report;
+    }
+    catch (e) {
+        findings.push(e.message);
+        return;
+    }
+}
 async function recoverNativeGateway(dir, value, info, findings) {
     if (value === undefined)
         return undefined;
@@ -1114,7 +1159,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) {
+function checkSharedFolder(dir, findings, pkg, folder, selected = false, portal, executor = false, nativeGateway, osMinVer, installSettings) {
     const wizardDir = join(dir, "WIZARD_UIFILES");
     const present = (existsSync(wizardDir) ? readdirSync(wizardDir) : [])
         .filter((name) => /^(install|upgrade)_uifile(_|\.|$)/.test(name))
@@ -1140,7 +1185,7 @@ function checkSharedFolder(dir, findings, pkg, folder, selected = false, portal,
             : {}),
         ...portalManifest(portal),
     };
-    const wizards = expectedWizardFiles(pkg, folder, selected, portal);
+    const wizards = expectedWizardFiles(pkg, folder, selected, portal, installSettings);
     const source = selected
         ? "the install-selected policy"
         : folder
@@ -1149,7 +1194,7 @@ function checkSharedFolder(dir, findings, pkg, folder, selected = false, portal,
                 ? "the portal 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
+    for (const name of folder || selected || portal || installSettings
         ? Object.keys(wizards)
         : present.filter((n) => n in wizards)) {
         if (readOptional(join(wizardDir, name)) !== wizards[name])
@@ -1173,7 +1218,45 @@ function checkSharedFolder(dir, findings, pkg, folder, selected = false, portal,
         }
     }
 }
-function expectedWizardFiles(pkg, folder, selected = false, portal) {
+/** Validate SDK settings inventory and hook prefix before existing backend inspectors.
+ * All reads and temporary rewrites are in the extracted inspection directory. */
+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) {
+        if (present.length)
+            findings.push('INSTALL_SETTINGS_INVALID unexpected installation settings payload');
+        return;
+    }
+    const root = join(dir, 'install-settings-inspection');
+    mkdirSync(root);
+    await tar.x({ file: join(dir, 'package.tgz'), cwd: root });
+    const info = readInfo(join(dir, 'INFO'), findings, 'binary', Boolean(metadata.compose));
+    const gateway = metadata.compose?.gateway ?? (metadata.native_gateway ? { listen: metadata.native_gateway.listen } : undefined);
+    const m = { package: info.package, installSettings: settings, identityGateway: gateway };
+    try {
+        if (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)))
+            throw new Error('only SDK control and declarations may be packaged; values must never ship');
+        const arch = info.arch.split(/\s+/).map(familyOfArchToken).find(Boolean) ?? 'x86_64';
+        const error = checkCgiBinary(root, join(root, 'install/control'), arch);
+        if (error)
+            throw new Error(error.message);
+        // App wrappers remain intact here; remove exactly the SDK prefix within them.
+        for (const name of ['preinst', 'postinst', 'postupgrade', 'preuninst']) {
+            const file = join(dir, 'scripts', name), text = readOptional(file), prefix = renderSettingsHook(name, m);
+            if (!text || !sdkScriptOf(name, text)?.sdk.startsWith('#!/bin/sh\n' + prefix) || text.split(prefix).length !== 2)
+                throw new Error(`scripts/${name} lacks the exact SDK settings hook`);
+            writeFileSync(file, text.replace(prefix, ''));
+        }
+    }
+    catch (error) {
+        findings.push('INSTALL_SETTINGS_INVALID ' + error.message);
+    }
+    return settings;
+}
+function expectedWizardFiles(pkg, folder, selected = false, portal, installSettings) {
     const steps = selected
         ? (t) => [
             ...renderDelegateScopeSteps(t),
@@ -1182,9 +1265,7 @@ function expectedWizardFiles(pkg, folder, selected = false, portal) {
         : folder
             ? sharedFolderInstallSteps(pkg, folder)
             : renderNativeInstallWizard;
-    const install = renderInstallWizardFiles(pkg, portal
-        ? (t) => [...steps(t), renderPortalWizardStep(t, portal.alias)]
-        : steps);
+    const install = renderInstallWizardFiles(pkg, t => [...steps(t), ...settingsInstallSteps(installSettings)(t), ...(portal ? [renderPortalWizardStep(t, portal.alias)] : [])]);
     return {
         ...install.static,
         ...install.dynamic,

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

@@ -0,0 +1,34 @@
+import type { StandaloneError, StandaloneManifest } from './manifest.js';
+import type { Translate } from '../build-spk/wizard-i18n.js';
+import type { NativeArchFamily } from '../build-spk/dsm-arch.js';
+import type { CommandRunner } from './build.js';
+export interface InstallSetting {
+    type: 'https-origin';
+    label: string;
+    required: boolean;
+}
+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) => {
+    step_title: string;
+    items: {
+        type: string;
+        desc: string;
+        subitems: {
+            key: string;
+            desc: string;
+            defaultValue: string;
+            validator: {
+                allowBlank: boolean;
+            };
+        }[];
+    }[];
+}[];
+export declare function settingsConfig(m: Pick<StandaloneManifest, 'package' | 'installSettings' | 'identityGateway'>): {
+    settings: InstallSettings | undefined;
+    https_port?: number | undefined;
+    schema: number;
+    package: string;
+};
+export declare function renderSettingsHook(name: string, m: StandaloneManifest): string;
+export declare function buildInstallSettings(m: StandaloneManifest, arch: NativeArchFamily, work: string, run: CommandRunner): Promise<string | undefined>;

package/dist/standalone/install-settings.js

@@ -0,0 +1,57 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { sdkSource } from '../runtime/sdk-source.js';
+import { templateSdkVersion } from '../template-paths.js';
+import { goChildEnv } from '../runtime/go-env.js';
+import { pinnedGoBuildEnv, pinnedGoProblem } from '../build-spk/go-toolchain.js';
+import { checkCgiBinary } from './binary.js';
+import { StandaloneBuildError } from './spk.js';
+export function readInstallSettings(value, fail) {
+    if (value === undefined)
+        return;
+    const bad = () => { fail({ code: 'INSTALL_SETTINGS_INVALID', message: 'install.settings requires 1-32 lowercase identifier keys, each with type: https-origin, a plain label (1-160 characters) and boolean required; no defaults or values.' }); return undefined; };
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return bad();
+    const entries = Object.entries(value);
+    if (entries.length === 0 || entries.length > 32)
+        return bad();
+    for (const [key, s] of entries) {
+        if (!/^[a-z][a-z0-9_]{0,31}$/.test(key) || !s || typeof s !== 'object' || Array.isArray(s) ||
+            Object.keys(s).some(k => !['type', 'label', 'required'].includes(k)) || s.type !== 'https-origin' ||
+            typeof s.label !== 'string' || !s.label.trim() || s.label.length > 160 || /[\x00-\x1f\x7f]/.test(s.label) || typeof s.required !== 'boolean')
+            return bad();
+    }
+    return Object.fromEntries(entries.sort(([a], [b]) => a.localeCompare(b)));
+}
+export function settingsInstallSteps(settings) {
+    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 } }],
+            })) }] : [];
+}
+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)
+        return '';
+    const action = name === 'preinst' ? 'prepare' : ['postinst', 'postupgrade'].includes(name) ? 'remember' : name === 'preuninst' ? 'purge' : undefined;
+    if (!action)
+        return '';
+    const root = name === 'preinst' ? '${SYNOPKG_PKGINST_TEMP_DIR:?}' : `\${SYNOPKG_PKGDEST:-/var/packages/${m.package}/target}`;
+    return `"${root}/install/control" ${action} --root "${root}" --package '${m.package}' || exit $?\n`;
+}
+export async function buildInstallSettings(m, arch, work, run) {
+    if (!m.installSettings)
+        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.');
+    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)
+        throw new StandaloneBuildError('SDK_INSTALL_SETTINGS_BUILD_FAILED', `Cannot build SDK installation settings: ${result.stderr}`);
+    const error = checkCgiBinary(work, out, arch), toolchain = pinnedGoProblem(out);
+    if (error || toolchain)
+        throw new StandaloneBuildError('SDK_INSTALL_SETTINGS_BUILD_FAILED', error?.message ?? toolchain);
+    return out;
+}

package/dist/standalone/lifecycle.js

@@ -1,3 +1,4 @@
+import { renderSettingsHook } from './install-settings.js';
 import { renderComposeRetainedData } from "../build-spk/compose-retained-data.js";
 import { renderNativeGatewayPrepare } from './native-gateway.js';
 import { renderComposeDiagnosis } from "../build-spk/compose-diagnosis.js";
@@ -15,7 +16,8 @@ const UNINSTALL_ONLY = '[ "${SYNOPKG_PKG_STATUS:-}" = UPGRADE ] || synopkgland_u
 export function renderStandaloneScript(name, manifest) {
     const script = renderStandaloneScriptInternal(name, manifest);
     const prepared = ['postinst', 'postupgrade'].includes(name) ? renderNativeGatewayPrepare(manifest) : '';
-    const sdk = prepared ? script.replace('#!/bin/sh\n', '#!/bin/sh\n' + prepared) : script;
+    const prefix = renderSettingsHook(name, manifest) + prepared;
+    const sdk = prefix ? script.replace('#!/bin/sh\n', () => '#!/bin/sh\n' + prefix) : script;
     return manifest.appScripts?.some((app) => app === name)
         ? composeAppScript(name, sdk)
         : sdk;

package/dist/standalone/manifest.d.ts

@@ -1,3 +1,4 @@
+import { type InstallSettings } from './install-settings.js';
 import { type WebLaunchMode } from "../contract/web-launch.js";
 import { type WebAPIProfiles } from "../runtime/webapi-profile.js";
 import { type PackageMetadata } from "../package-metadata.js";
@@ -94,6 +95,7 @@ export interface StandaloneManifest {
     uninstall?: Uninstall;
     /** `install.sharedFolder`: the Shared Folder the install wizard selects or `data-share` creates. */
     sharedFolder?: SharedFolder;
+    installSettings?: InstallSettings;
     /** 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. */

package/dist/standalone/manifest.js

@@ -1,3 +1,4 @@
+import { readInstallSettings } from './install-settings.js';
 import { isWebLaunchMode } from "../contract/web-launch.js";
 import { validWebAPIProfiles, } from "../runtime/webapi-profile.js";
 import { validateMetadata } from "../package-metadata.js";
@@ -243,6 +244,7 @@ function readManifest(raw, c) {
     const sharedFolder = raw.install === undefined
         ? undefined
         : readSharedFolder(raw.install, (e) => c.fail(e.code, e.message));
+    const installSettings = readInstallSettings(isRecord(raw.install) ? raw.install.settings : undefined, e => c.fail(e.code, e.message));
     const compose = arches &&
         readComposeApp(raw.compose, c.root, arches, (e) => c.fail(e.code, e.message), {
             package: packageId,
@@ -250,6 +252,7 @@ function readManifest(raw, c) {
             mode: typeof gatewayRaw.mode === "string" ? gatewayRaw.mode : "none",
             composeMounts: capabilities.composeMounts,
             sharedFolder,
+            installSettings,
         });
     if (raw.compose !== undefined &&
         ((raw.daemon !== undefined && !timeoutOnly) ||
@@ -278,6 +281,8 @@ function readManifest(raw, c) {
         identityGateway?.access === "public" &&
         (raw.entry !== undefined || compose.plan.mounts_blocked))
         c.fail("STANDALONE_IDENTITY_GATEWAY_INVALID", "public ingress cannot bypass entry controls or expose blocked Shared Folder settings.");
+    if (compose?.plan.mounts_blocked && identityGateway?.upstream_access === "public")
+        c.fail("STANDALONE_IDENTITY_GATEWAY_INVALID", "public upstream access cannot expose blocked Shared Folder settings.");
     if (compose &&
         identityGateway &&
         (!Object.values(compose.services).some((s) => s.port === identityGateway.upstream) ||
@@ -446,6 +451,7 @@ function readManifest(raw, c) {
         ...(compose ? { compose } : {}),
         ...(uninstall ? { uninstall } : {}),
         ...(sharedFolder ? { sharedFolder } : {}),
+        ...(installSettings ? { installSettings } : {}),
         ...(entry ? { entry } : {}),
         ...(portal ? { portal } : {}),
         ...(icon ? { icon } : {}),

package/dist/standalone/shared-folder.js

@@ -13,9 +13,11 @@ export function readSharedFolder(value, fail) {
         fail({ code: "STANDALONE_SHARED_FOLDER_INVALID", message: `install.sharedFolder ${why}` });
         return undefined;
     };
-    if (!isRecord(value) || Object.keys(value).some((key) => key !== "sharedFolder")) {
+    if (!isRecord(value) || Object.keys(value).some((key) => key !== "sharedFolder" && key !== "settings")) {
         return refuse(": only sharedFolder is allowed.");
     }
+    if (value.sharedFolder === undefined && value.settings !== undefined)
+        return undefined;
     const folder = value.sharedFolder;
     if (!isRecord(folder) || Object.keys(folder).some((key) => !FIELDS.has(key))) {
         return refuse(" accepts only mode, key, name and permission.");

package/dist/standalone/spk.d.ts

@@ -17,6 +17,7 @@ export interface AssembleOptions {
     daemonControl?: string;
     composeControl?: string;
     composeStorageInit?: string;
+    installSettingsControl?: string;
     /** The SDK identity gateway, required exactly when the manifest declares identity_gateway. */
     identityGateway?: string;
     /** The compiled background worker, required exactly when capabilities.jobs is enabled. */

package/dist/standalone/spk.js

@@ -1,7 +1,9 @@
+import { settingsInstallSteps, settingsConfig } from './install-settings.js';
 import { nativeGatewaySupported, nativeGatewaySdk, renderNativeGatewayConfig, NATIVE_GATEWAY_CONFIG, legacyGatewayNotice, gatewayEntryPath } from './native-gateway.js';
 import { portalInfoFields } from "../portal/info.js";
 import { sdkSource } from "../runtime/sdk-source.js";
 import { resolvedSdkLaunch } from "../contract/app-launch.js";
+import { gatewayAdmissionPolicy } from "./identity-gateway.js";
 import { metadataInfoFields } from "../package-metadata.js";
 import { createHash } from "node:crypto";
 import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
@@ -203,6 +205,14 @@ export async function assembleStandaloneSpk(options) {
                 chmodSync(join(target, "storage-init"), EXEC_MODE);
             }
         }
+        if (manifest.installSettings) {
+            if (!options.installSettingsControl)
+                throw new StandaloneBuildError('SDK_INSTALL_SETTINGS_BUILD_FAILED', 'SDK settings controller required.');
+            const target = join(staging, 'package/install');
+            mkdirSync(target, { recursive: true });
+            copyExecutable(options.installSettingsControl, join(target, 'control'));
+            writeFile(join(target, 'settings.json'), JSON.stringify(settingsConfig(manifest), null, 2) + '\n');
+        }
         const packageTgz = join(staging, "package.tgz");
         await createReproducibleTar(join(staging, "package"), packageTgz, {
             gzip: true,
@@ -213,10 +223,12 @@ export async function assembleStandaloneSpk(options) {
             .digest("hex");
         writeFile(join(staging, "sdk-package.json"), JSON.stringify({
             schema: 2,
+            ...(manifest.installSettings ? { installSettings: manifest.installSettings } : {}),
             ...(manifest.lifecycleTimeouts ? { lifecycleTimeouts: manifest.lifecycleTimeouts } : {}),
             ...("timeoutSeconds" in manifest.backend && manifest.backend.timeoutSeconds ? { operationSeconds: manifest.backend.timeoutSeconds } : {}),
             ...(options.apiDescription ? { ctl: { hash: options.apiDescription.sha256, registry: options.apiRegistry } } : {}),
             backend: manifest.backend.kind,
+            ...(gatewayAdmissionPolicy(manifest.identityGateway, manifest.entry) ? { provider_only_oidc: gatewayAdmissionPolicy(manifest.identityGateway, manifest.entry) } : {}),
             ...(nativeGatewaySupported(manifest) ? { native_gateway: { sdk: manifest.identityGateway.sdk, listen: manifest.identityGateway.listen } } : {}),
             launch: resolvedSdkLaunch(manifest),
             capabilities: Object.keys(manifest.capabilities).sort(),
@@ -263,9 +275,7 @@ export async function assembleStandaloneSpk(options) {
             : folder
                 ? sharedFolderInstallSteps(manifest.package, folder)
                 : renderNativeInstallWizard;
-        const install = renderInstallWizardFiles(manifest.package, portal
-            ? (t) => [...steps(t), renderPortalWizardStep(t, portal.alias)]
-            : steps);
+        const install = renderInstallWizardFiles(manifest.package, (t) => [...steps(t), ...settingsInstallSteps(manifest.installSettings)(t), ...(portal ? [renderPortalWizardStep(t, portal.alias)] : [])]);
         writeWizardUiFiles(staging, {
             ...install.static,
             ...install.dynamic,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.21.1",
+  "version": "0.23.0",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@napi-rs/keyring": "^2.1.1",
-    "@synopackageland/templates": "0.21.1",
+    "@synopackageland/templates": "0.23.0",
     "ajv": "^8.17.1",
     "commander": "^13.1.0",
     "json-canonicalize": "^3.0.1",

package/skills/reference/compose.md

@@ -470,3 +470,16 @@ Administrator cleanup procedures, executor-tier Apps and storage redesign are
 out of scope. Final DSM native UI acceptance remains required.
 
 See the SDK's [Compose App data contract](https://github.com/synopackageland/syno-pkg-land-sdk/blob/main/docs/compose-app-data.md).
+# Explicit host UDP listeners
+
+For a verified nonroot host Web service, declare optional non-loopback UDP
+listeners with `compose.host_udp: [{port: 5353, purpose: mdns}, {port: 1900,
+purpose: ssdp}]`. Use up to 32 distinct integer ports, 1024–65535, with lowercase
+purpose labels of 1–64 characters beginning with a letter (letters, digits and
+hyphens only). This applies to the package UID across IPv4/IPv6, not one service.
+It never permits TCP, changes Web loopback/health requirements, or adds root or
+capabilities. Undeclared non-loopback listeners still fail readiness. The CLI
+verifies planner/lock agreement and `inspect --json` reports `compose.hostUdp`.
+Rebuild with a CLI and SDK that support the declaration; older planners reject
+it. Discovery and multicast coexistence need real LAN verification; this guard
+is not a firewall and does not reserve ports or configure reuse.

package/skills/reference/identity-gateway.md

@@ -1,5 +1,59 @@
 # Wrap an OSS app with DSM accounts
 
+## Per-request OIDC browser origins (development)
+
+`oidc.browser_redirect: {}` opts into per-request browser origins for SDK/CLI
+0.23. Optional `html_paths` and `same_origin_referrer` configure HTML behavior.
+No host list is accepted or stored in the SPK: users can open the same install
+by IP, hostname, DDNS or a new DNS alias. Each request must use a syntactically
+valid IP/DNS authority and the declared gateway scheme/port; forwarding headers
+cannot select the destination. DSM native ingress uses its HTTPS port.
+Host selects only this browser response's navigation URL, never an upstream
+dial target or an authorization decision. DSM admission, transaction origin
+and browser binding, exact redirect registration and PKCE remain required.
+Gateway cookies are host-only. This does not make public upstream routes a
+network security boundary; upstream retains its authentication/CSRF duties.
+Use trusted DNS and TLS, as a user signing in on an attacker-controlled origin
+exposes that origin's session to its owner. Rewritten responses use no-store
+and remove validators/digests; issuer/discovery never depend on Host.
+
+Location and existing `rewrite_json` rules already map the loopback authorization
+endpoint. For clients returning it in HTML, add `html_paths: ["/auth/redirect"]`:
+only those exact GET/200 HTML responses are rewritten, up to 1 MiB using identity
+encoding, with raw/escaped/percent-encoded URL support. Query bytes and upstream
+CSP stay intact; inline CSP hashes over modified scripts are incompatible.
+If an upstream native form uses `no-referrer` and browsers send `Origin: null`,
+explicit `same_origin_referrer: true` restores same-origin metadata only on
+the declared HTML paths. Include the form's page in that list. Referrers never
+go to other origins; null/foreign Origin checks are not relaxed.
+Issuer/ID token `iss`, discovery, token, userinfo and JWKS remain on loopback.
+Redirect registration, PKCE and DSM browser binding are unchanged. This needs
+matching SDK/CLI support; builds reject an SDK without the capability, including
+old releases selected without a development source override.
+
+## Provider-only OIDC
+
+For an upstream with native authentication for browsers and native clients,
+declare `mode: oidc`, `upstream_access: public`, and retain `access: dsm-users`,
+`dsm-admins` or `dsm-groups` for the issuer. This capability requires
+SDK/CLI 0.23.0 or later. A build with an old SDK
+without that capability fails rather than claiming support.
+
+The gateway does not require DSM cookies or browser Origin on upstream requests.
+The upstream owns authentication, authorization, CSRF, CORS and WebSocket policy;
+no DSM identity is injected. Reserved `/_sso/*` paths retain gateway protection.
+The issuer still verifies DSM sign-in, App Privileges and its role/group access
+before issuing a browser-bound grant. Client authentication, exact redirect,
+PKCE, code expiry and single use remain required at token exchange. App sessions
+and offline data do not become instantly revoked when DSM access changes.
+
+An omitted entry acquires `app-privilege` for issuer verification; explicit
+`admin-only` stays stricter. This cannot combine with optional passthrough rules
+or unapproved Share activation. Omission preserves protected behavior. Use
+`check`, `build` and `inspect`: the admission summary explicitly states
+**Upstream routes are not protected by the gateway**. Inspect compares that
+summary with the packaged policy and rejects inconsistent declarations.
+
 Use this checklist before selecting an image or writing glue. Discover the
 installed CLI (`--help`, `skill show`, `check --json`) and SDK contracts. Use the
 app's supported API/configuration; do not patch upstream or write its database.
@@ -122,7 +176,7 @@ URL is accepted as the return destination. The transaction expires in five minut
 This declares navigation only; upstream account provisioning/role mapping must
 use that upstream's supported configuration APIs and be tested independently.
 
-## Server-managed OIDC navigation (development)
+## Server-managed OIDC navigation
 
 For an upstream that automatically starts OIDC (for example a native web-server
 authentication module), leave `oidc.browser` unset and declare
@@ -132,3 +186,15 @@ capability; released SDK 0.18.0 does not yet implement this field. Native Compos
 URL entries resume only a bounded transaction and declared public gateway port.
 Normal menu entry remains the classless SDK CGI. Existing browser consumers keep
 their previous behavior. Never invent fake login paths just to enable DSM login.
+
+## Fixed DSM menu target
+
+`identity_gateway.launch_path` is a fixed local App URL, including a query or SPA
+fragment, for example `/#/sso?identifier=fixed-organization`. It requires matching
+SDK support; build rejects sources without that capability. Omission opens `/`.
+The setting does not change issuer redirects or sign-in transaction resume.
+External/network URLs, reserved `/_sso` paths, dot segments, backslashes and
+control characters are rejected. Caller query values cannot override it.
+Use the upstream's supported entry route; this does not modify upstream UI,
+produce an App session, or unlock encrypted data. HTTPS and App-specific
+fragment/query semantics still require deployment acceptance.