@synopackageland/cli 0.22.0 → 0.23.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.23.1 (2026-10-22)
+
+- Build SDK/App 0.23.1 with its verified immutable executor/v0.20.0 digests; retain support for SDK/App 0.23.0. This enables the SDK HTTP transfer error-status fix without changing executor or lifecycle payloads.
+- Include the native HTTPS shutdown/start port-release fix and recognize its exact diagnostic prefix when inspecting Portal and background-job lifecycle scripts. Keep templates 0.23.0 and the existing UI pin.
+
+## 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.

package/dist/error-registry.js

@@ -2,7 +2,7 @@ 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.22.0 or a matching supported release with installsettings/cmd/control, then rebuild with the matching CLI." },
+    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." },

package/dist/runtime/executor-digests.json

@@ -1,5 +1,16 @@
 {
-    "0.22.0": {
+    "0.23.0": {
+        "x86_64": "e27cfeb85fed221b06f9c58166f02c0f701a724308cd17c96a43a843a0b5c4aa",
+        "aarch64": "908db00cbd37d072f6ffc339e7bca24da5efb8cddd4befcbad02c7398beb7191",
+        "armv7": "a0f35d62ec80a1bf3fb49f5e2d1a5f7576eda569a6fd0695084cec6cb8e100bc",
+        "lifecycle": {
+            "x86_64": "9bb53301670b43cdcd6e21cebac99ab7abd82962d874f32423a81e6cb49d4972",
+            "aarch64": "38fe873c86eb102c850baa1f304114a83a31d1df72defd22792bc37610fec9bb",
+            "armv7": "256fb348b275da7ac5728a3cb7cb7c65660de0d5c2c59430ab4f5ade1b0a3681"
+        },
+        "goToolchain": "go1.26.9"
+    },
+    "0.23.1": {
         "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', '0.22.0': '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', '0.23.1': '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/identity-gateway.d.ts

@@ -59,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;

package/dist/standalone/identity-gateway.js

@@ -291,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) ||
@@ -312,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);
@@ -334,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 } : {}),
@@ -481,6 +490,11 @@ 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")))

package/dist/standalone/inspect-spk.js

@@ -1,6 +1,6 @@
 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 { nativeGatewaySupported, renderNativeGatewayConfig, renderNativeGatewayDiagnostic, renderNativeGatewayPrepare, NATIVE_GATEWAY_CONFIG, gatewayEntryPath } from './native-gateway.js';
 import { inspectPortalInfo } from "../portal/info.js";
 import { isDeepStrictEqual } from "node:util";
 import { inspectApiDescription } from "./api-description-inspect.js";
@@ -36,7 +36,7 @@ import { renderNativePrivilege } from "../build-spk/native-lifecycle.js";
 import { renderUiConfig } from "./dsm-window.js";
 import { identityGatewayConfig, gatewayAdmissionReport, gatewayAdmissionPolicy, readIdentityGateway, } from "./identity-gateway.js";
 import { checkCgiBinary } from "./binary.js";
-import { renderStandaloneScript } from "./lifecycle.js";
+import { matchesStandaloneScript, renderStandaloneScript } from "./lifecycle.js";
 import { listPortExposures, loadCompose } from "../compose/analyze.js";
 import { uninstallCleanup, } from "../runtime/uninstall-cleanup.js";
 import { PORTAL_JSON_RELPATH, PORTAL_MUSTACHE_RELPATH, renderPortalJson, renderPortalLifecycle, renderPortalMustache, renderPortalWizardStep, } from "../portal/package.js";
@@ -209,7 +209,7 @@ export async function inspectSpk(spkPath, expectedKind) {
             ? await checkDaemon(dir, info, paths, payload, findings, hasExecutor, background, combined, nativeGateway, uninstallHook?.uninstall)
             : undefined;
         if (background)
-            checkBackground(dir, info, payload, findings, hasExecutor, daemon, kind !== "native-go", metadata.lifecycleTimeouts);
+            checkBackground(dir, info, payload, findings, hasExecutor, daemon, kind !== "native-go", metadata.lifecycleTimeouts, nativeGateway);
         let executor;
         if ((metadata.capabilities ?? []).some((name) => name === "rootOps" || name === "delegate" || name === "webapi") ||
             paths.has("executor/executor")) {
@@ -701,8 +701,7 @@ async function inspectUnifiedCompose(dir, payload, metadata, findings) {
             "postupgrade",
             "start-stop-status",
         ])
-            if (readOptional(join(dir, "scripts", hook)) !==
-                renderStandaloneScript(hook, manifest))
+            if (!matchesStandaloneScript(hook, manifest, readOptional(join(dir, "scripts", hook))))
                 throw new Error(`unexpected scripts/${hook}`);
         if (appScripts.length)
             base.appScripts = appScripts;
@@ -897,8 +896,7 @@ async function checkDaemon(dir, info, paths, payload, findings, executor, backgr
         if (readFileSync(join(unpacked, "daemon/config.json"), "utf8") !== JSON.stringify(expectedConfig) + '\n')
             throw new Error("non-canonical daemon config");
         for (const hook of ["start-stop-status", "preupgrade", "preuninst"]) {
-            if (readFileSync(join(dir, "scripts", hook), "utf8") !==
-                renderStandaloneScript(hook, nativeGateway ? { ...manifest, os_min_ver: info.os_min_ver, identityGateway: nativeGateway } : manifest))
+            if (!matchesStandaloneScript(hook, nativeGateway ? { ...manifest, os_min_ver: info.os_min_ver, identityGateway: nativeGateway } : manifest, readFileSync(join(dir, "scripts", hook), "utf8")))
                 findings.push(`daemon scripts/${hook} does not match the fixed lifecycle`);
         }
         return daemon;
@@ -1120,7 +1118,7 @@ function checkConf(dir, findings, kind, background, sharedFolder, pkg, portal, c
     }
 }
 /** The opt-in package user unit must be exactly what the generator writes. */
-function checkBackground(dir, info, payload, findings, executor, daemon, bridge = false, lifecycleTimeouts) {
+function checkBackground(dir, info, payload, findings, executor, daemon, bridge = false, lifecycleTimeouts, nativeGateway) {
     const pkg = info.package;
     if (!pkg)
         return;
@@ -1141,16 +1139,17 @@ function checkBackground(dir, info, payload, findings, executor, daemon, bridge
             renderBackgroundUnit(pkg, bridge ? BRIDGE_WORKER_ARGS : [], daemon?.timeouts.stop ?? lifecycleTimeouts?.stop ?? 30)) {
         findings.push(`${BACKGROUND_UNIT_DIR} must contain only the fixed ${unit} (runs as the package account, no User=, no root)`);
     }
-    if (read("scripts/start-stop-status") !==
-        renderStandaloneScript("start-stop-status", {
-            package: pkg,
-            lifecycleTimeouts,
-            ...(daemon ? { daemon } : {}),
-            capabilities: {
-                jobs: { worker: "sha256-v1" },
-                ...(executor ? { rootOps: true } : {}),
-            },
-        }))
+    if (!matchesStandaloneScript("start-stop-status", {
+        package: pkg,
+        os_min_ver: info.os_min_ver,
+        ...(nativeGateway ? { identityGateway: nativeGateway } : {}),
+        lifecycleTimeouts,
+        ...(daemon ? { daemon } : {}),
+        capabilities: {
+            jobs: { worker: "sha256-v1" },
+            ...(executor ? { rootOps: true } : {}),
+        },
+    }, read("scripts/start-stop-status")))
         findings.push("background scripts/start-stop-status does not match the fixed synosystemctl lifecycle");
 }
 /**
@@ -1204,16 +1203,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 (readOptional(join(dir, "scripts", hook)) !==
-                renderStandaloneScript(hook, lifecycleManifest))
+            if (!matchesStandaloneScript(hook, lifecycleManifest, readOptional(join(dir, "scripts", hook))))
                 findings.push(`scripts/${hook} does not match the fixed install-selected draft handling`);
         }
     }
     if (!folder && !portal)
         return;
     for (const hook of ["postinst", "postupgrade"]) {
-        if (readOptional(join(dir, "scripts", hook)) !==
-            renderStandaloneScript(hook, lifecycleManifest)) {
+        if (!matchesStandaloneScript(hook, lifecycleManifest, readOptional(join(dir, "scripts", hook)))) {
             findings.push(`scripts/${hook} does not match the fixed script declared by ${folder ? "install.sharedFolder" : "portal"}`);
         }
     }
@@ -1313,7 +1310,15 @@ async function recoverPortal(dir, info, appId, paths, payload, findings, nativeG
                     identityGateway: nativeGateway,
                 })
                 : "";
-            if (!readOptional(join(dir, "scripts", hook))?.startsWith(`#!/bin/sh\n${prepare}${renderPortalLifecycle(hook, portal)}`))
+            const diagnostic = renderNativeGatewayDiagnostic({
+                package: info.package,
+                os_min_ver: info.os_min_ver,
+                identityGateway: nativeGateway,
+            }, hook);
+            const script = readOptional(join(dir, "scripts", hook));
+            // The fixed native diagnostics precede preparation in current scripts;
+            // released scripts can still start directly with preparation.
+            if (![diagnostic, ""].some(prefix => script?.startsWith(`#!/bin/sh\n${prefix}${prepare}${renderPortalLifecycle(hook, portal)}`)))
                 throw new Error(hook);
         }
         return portal;

package/dist/standalone/lifecycle.d.ts

@@ -1,3 +1,5 @@
 import type { StandaloneManifest } from "./manifest.js";
 /** Package-account lifecycle hooks for CGI, daemon and background packages. */
 export declare function renderStandaloneScript(name: string, manifest: StandaloneManifest): string;
+/** Accept the exact current, diagnostic-only, and released lifecycle variants. */
+export declare function matchesStandaloneScript(name: string, manifest: StandaloneManifest, actual: string | undefined): boolean;

package/dist/standalone/lifecycle.js

@@ -1,6 +1,6 @@
 import { renderSettingsHook } from './install-settings.js';
 import { renderComposeRetainedData } from "../build-spk/compose-retained-data.js";
-import { renderNativeGatewayPrepare } from './native-gateway.js';
+import { renderNativeGatewayDiagnostic, renderNativeGatewayPortWait, renderNativeGatewayPrepare } from './native-gateway.js';
 import { renderComposeDiagnosis } from "../build-spk/compose-diagnosis.js";
 import { composeDaemon, renderComposeInstall } from "./compose.js";
 import { renderBackgroundControl, renderBackgroundWorkerStart, renderBackgroundWorkerStop, renderUserManagerRecovery, backgroundUnitName, } from "./background.js";
@@ -16,12 +16,23 @@ 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 prefix = renderSettingsHook(name, manifest) + prepared;
+    const prefix = renderNativeGatewayDiagnostic(manifest, name) + renderNativeGatewayPortWait(manifest, name) + 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;
 }
+/** Accept the exact current, diagnostic-only, and released lifecycle variants. */
+export function matchesStandaloneScript(name, manifest, actual) {
+    const expected = renderStandaloneScript(name, manifest);
+    if (actual === expected)
+        return true;
+    const diagnostic = renderNativeGatewayDiagnostic(manifest, name);
+    const wait = renderNativeGatewayPortWait(manifest, name);
+    const diagnosticOnly = wait ? expected.replace(wait, '') : expected;
+    return (wait !== '' && actual === diagnosticOnly) ||
+        (diagnostic !== '' && actual === diagnosticOnly.replace(diagnostic, ''));
+}
 function renderStandaloneScriptInternal(name, manifest) {
     if (manifest.compose) {
         const native = {

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

@@ -8,6 +8,10 @@ type Target = {
 export declare const NATIVE_GATEWAY_CONFIG = "sso/native-nginx.conf";
 export declare function nativeGatewaySdk(sdk: string): boolean;
 export declare function nativeGatewaySupported(m: Target): boolean;
+/** Observe the boundary before DSM acquires web-config, without claiming port ownership. */
+export declare function renderNativeGatewayDiagnostic(m: Target, hook: string): string;
+/** Give a retiring nginx listener a bounded window before DSM acquires web-config. */
+export declare function renderNativeGatewayPortWait(m: Target, hook: string): string;
 export declare function gatewayEntryPath(m: Target): string;
 export declare function legacyGatewayNotice(): string;
 export declare function nativeGatewayResource(m: Target): Record<string, unknown> | undefined;

package/dist/standalone/native-gateway.js

@@ -10,6 +10,92 @@ export function nativeGatewaySupported(m) {
     return Boolean(m.identityGateway && nativeGatewaySdk(m.identityGateway.sdk)
         && m.os_min_ver && isDsmAtLeast(m.os_min_ver, PORTAL_MIN_DSM));
 }
+/** Observe the boundary before DSM acquires web-config, without claiming port ownership. */
+export function renderNativeGatewayDiagnostic(m, hook) {
+    if (!nativeGatewaySupported(m) || !['start-stop-status', 'postinst', 'postupgrade', 'preupgrade', 'preuninst'].includes(hook))
+        return '';
+    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`
+        : '  action=hook\n';
+    // Only fixed phase names and declared public ports reach syslog. In particular,
+    // never log argv, environment dumps, request/session data or a guessed owner.
+    return `synopkgland_native_diagnostic() (
+  command -v logger >/dev/null 2>&1 || exit 0
+${action}  case "\${SYNOPKG_PKG_STATUS:-}" in
+    INSTALL|UPGRADE|UNINSTALL|START|STOP) reason="$SYNOPKG_PKG_STATUS" ;;
+    '') reason=NONE ;;
+    *) reason=UNKNOWN ;;
+  esac
+  stamp=$(date -u '+%Y-%m-%dT%H:%M:%SZ') || stamp=unknown
+  socket_state() {
+    if [ ! -r "$1" ]; then echo unknown; return; fi
+    awk -v port="$2" '$4 == "0A" && toupper($2) ~ (":" port "$") { found=1 } END { print found ? "listening" : "clear" }' "$1" || echo unknown
+  }
+${ports.map(port => `  tcp4=$(socket_state /proc/net/tcp ${port.toString(16).toUpperCase().padStart(4, '0')})
+  tcp6=$(socket_state /proc/net/tcp6 ${port.toString(16).toUpperCase().padStart(4, '0')})
+  logger -p user.warning -t synopkgland "NATIVE_GATEWAY_LIFECYCLE at=$stamp package=${m.package} hook=${hook} action=$action reason=$reason port=${port} tcp4=$tcp4 tcp6=$tcp6" || :
+`).join('')})
+synopkgland_native_diagnostic "$@" >/dev/null 2>&1 || :
+`;
+}
+/** Give a retiring nginx listener a bounded window before DSM acquires web-config. */
+export function renderNativeGatewayPortWait(m, hook) {
+    if (hook !== 'start-stop-status' || !nativeGatewaySupported(m))
+        return '';
+    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
+  socket_state() {
+    if [ ! -r "$1" ]; then echo unknown; return; fi
+    awk -v port="$2" '$4 == "0A" && toupper($2) ~ (":" port "$") { found=1 } END { print found ? "listening" : "clear" }' "$1" || echo unknown
+  }
+  remaining=30
+  polls=0
+  monotonic_cs() {
+    read uptime unused < /proc/uptime || return 1
+    whole=\${uptime%.*}
+    fraction=\${uptime#*.}
+    case "$whole" in ''|*[!0-9]*) return 1 ;; esac
+    case "$fraction" in [0-9][0-9]) : ;; *) return 1 ;; esac
+    echo $((whole * 100 + 1$fraction - 100))
+  }
+  started=$(monotonic_cs) || started=
+  deadline=$((\${started:-0} + 1500))
+  while :; do
+    busy=0
+    unknown=0
+    for port in ${ports.map(port => port.toString(16).toUpperCase().padStart(4, '0')).join(' ')}; do
+      for table in /proc/net/tcp /proc/net/tcp6; do
+        case "$(socket_state "$table" "$port")" in
+          listening) busy=1 ;;
+          clear) : ;;
+          *) unknown=1 ;;
+        esac
+      done
+    done
+    if [ "$busy" -eq 0 ]; then
+      outcome=clear
+      [ "$unknown" -eq 0 ] || outcome=unknown
+      break
+    fi
+    if [ "$remaining" -eq 0 ]; then outcome=timeout; break; fi
+    now=$(monotonic_cs) || now=
+    if [ -z "$started" ] || [ -z "$now" ]; then outcome=unavailable; break; fi
+    left=$((deadline - now))
+    if [ "$left" -le 0 ]; then outcome=timeout; break; fi
+    delay=0.5
+    if [ "$left" -lt 50 ]; then delay=$(printf '0.%02d' "$left"); fi
+    sleep "$delay" || { outcome=unavailable; break; }
+    remaining=$((remaining - 1))
+    polls=$((polls + 1))
+  done
+  stamp=$(date -u '+%Y-%m-%dT%H:%M:%SZ') || stamp=unknown
+  logger -p user.warning -t synopkgland "NATIVE_GATEWAY_PORT_WAIT at=$stamp package=${m.package} action=prestart ports=${ports.join(',')} outcome=$outcome polls=$polls" || :
+)
+synopkgland_native_port_wait "$@" >/dev/null 2>&1 || :
+`;
+}
 export function gatewayEntryPath(m) {
     return `/webman/3rdparty/${m.package}/sso/open.${m.identityGateway && !nativeGatewaySdk(m.identityGateway.sdk) ? 'html' : 'cgi'}`;
 }

package/package.json

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

package/skills/reference/diagnose.md

@@ -5,3 +5,51 @@ Start with check; inspect the built SPK. For DSM broken / 150 inspect Package Ce
 The independent container path uses resource-worker lifecycle. Unsupported Compose settings fail before build; there is no alternate installer. COMPOSE_NUMERIC_COMMAND_ARG_FORBIDDEN means DSM may strip quoting from 純數字 command 元素. Use a single shell command when appropriate, for example `command: ["sh","-c","httpd -f -p 18333 -h /srv"]`.
 
 Never work around a failed permission check by running the package as root. Native CGI authentication and root-operation administrator approval are separate checks.
+
+## Native HTTPS fails before the App starts
+
+For a package using DSM-managed native gateway HTTPS (including Compose Apps),
+`start_failed` can occur after `start-stop-status prestart` succeeds but before
+DSM invokes `start`. Check `/var/log/packages/<package>.log`,
+`/var/log/synopkg.log`, `/var/log/synopkgmgr.log` and `/var/log/messages` at the
+same timestamp. `Failed to acquire startup worker` (272) plus
+`Runtime port <port> conflict for nginx` identifies the DSM `web-config` resource
+boundary. Increasing the daemon or Compose startup timeout cannot repair a
+failure that occurs before the daemon controller runs.
+
+New builds emit `NATIVE_GATEWAY_LIFECYCLE` records to local syslog at SDK hook entry
+for prestart, prestop, start, stop, restart and the install/upgrade/removal hooks.
+The record contains a UTC timestamp, package, fixed hook/action/reason, declared
+public port, and IPv4/IPv6 TCP listener presence from `/proc/net/tcp{,6}`:
+`listening`, `clear`, or `unknown`. It records no usernames, environment dumps,
+credentials or application arguments. Records use `user.warning` because DSM
+may filter notice-level messages; these records are observations, not error verdicts. Status polls are silent. Missing logger or
+unreadable proc data does not change the lifecycle result.
+
+Before the existing SDK and App prestart steps, native gateway builds also
+check all declared public ports for IPv4/IPv6 TCP listeners. While any is
+listening, one shared monotonic 15-second deadline includes probe time, with at
+most thirty sleeps of up to 0.5 seconds. The final sleep uses only the remaining
+budget; scheduling and the final local probe can add slight overhead. No listener
+means no sleep. Unknown
+probe results do not themselves trigger a wait. `NATIVE_GATEWAY_PORT_WAIT`
+records the outcome (`clear`, `timeout`, `unknown`, or `unavailable`) and the
+number of sleeps. Timeout, logger failure, or an unavailable sleep command
+continues to the original prestart steps and preserves their exit semantics;
+DSM remains responsible for acquiring the resource and reporting a conflict.
+This is an observation-only mitigation, without signalling processes or a root
+helper. Inspect accepts the exact current scripts, the prior diagnostic-only
+scripts, and the original released scripts; edited waits or SDK steps fail.
+
+These observations do not identify the listener's owner or reserve the port.
+They do not prove that a listener persisted until DSM's subsequent resource
+check, and a missing record may mean logging was unavailable. Correlate them
+with DSM's own hook begin/end records. During an authorized reproduction, also
+capture a timestamped `netstat -lntp` (administrator access may be required),
+nginx process/config state, package state and daemon logs before attempting
+recovery. Keep system logs private and redact them before sharing. A later
+native Start success proves recovery, not why the previous attempt failed.
+
+Do not restart nginx, change DSM port assignments, kill unrelated listeners,
+or add automatic package-start retries to hide an unproven conflict. Rebuild
+an App to obtain the diagnostic hooks; existing installed packages are unchanged.

package/skills/reference/identity-gateway.md

@@ -1,11 +1,42 @@
 # 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.22.0 or later. A build with an old SDK
+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.