@synopackageland/cli 0.27.1 → 0.29.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.29.0 (2026-10-24)
+
+- Depend on templates `~0.29.0` with SDK/App 0.29.0 and UI 0.14.10. SDK 0.29.0 reuses executor/v0.27.0 through executor manifest format 1; no executor digests change.
+- Package `identity_gateway.external_access` (`connect: optional | none`, `origin_change: none | confirm`) for SDK 0.29.0 or later gateways; check refuses it for older SDKs and inspect verifies the packaged external declaration and `settings.cgi` gateway entry.
+
+## 0.28.0 (2026-10-24)
+
+- Depend on templates `~0.28.0` with SDK/App 0.28.0 and UI 0.14.10. SDK 0.28.0 reuses executor/v0.27.0 through executor manifest format 1; no executor digests change.
+- Default the Compose startup budget to 900 seconds and document slow-NAS readiness; the SDK owns health timing and the Starting status. No per-App option is added.
+- Keep UI CGI scripts executable in built SPKs, and let external OIDC resume tokens reach only the fixed DSM CGI.
+- The release gate checks SDK 0.27.1+ executor builds against the SDK executor manifest instead of requiring a frozen legacy table entry.
+
 ## 0.27.1 (2026-10-23)
 
 - Read executor release mappings, toolchain and six payload pins from SDK executor manifest format 1. Accept compatible SDK minors independently of CLI versions; keep the frozen 0.26.0/0.27.0 fallback. Remove the CLI digest-recording script.

package/README.md

@@ -66,8 +66,8 @@ CLI-only patch releases can differ from the SDK patch. Compose import and SDK de
 read the SDK pin from the installed templates; explicit App SDK declarations take precedence.
 
 `init` and `add` read their templates from the locally installed
-`@synopackageland/templates`. CLI 0.27.1 depends on `~0.27.0`: npm installation or
-update can select the latest templates patch in the 0.27 minor line. Templates
+`@synopackageland/templates`. CLI 0.29.0 depends on `~0.29.0`: npm installation or
+update can select the latest templates patch in the 0.29 minor line. Templates
 patches need only a templates release; update the npm installation to receive them.
 The CLI never fetches templates at runtime, so offline use works after installation;
 commit a lockfile and use `npm ci` to reproduce a chosen dependency tree.
@@ -303,6 +303,16 @@ or `portal`, or with `capabilities.rootOps`, `delegate`, `webapi` or
 `identity`, whose approval or sign-in is shown in the SDK window
 (`STANDALONE_UI_NO_WINDOW_INVALID`). A missing `ui` is still an error.
 
+Gateway Apps built with SDK 0.29.0 or later include DSM-origin `sso/settings.cgi`
+and default to `external_access: {connect: optional, origin_change: none}`.
+Declare `identity_gateway.external_access.connect: none` to ignore Connect's
+public URL projection; manual URLs remain available without Connect. Use
+`origin_change: confirm` for Apps that need confirmation when their public
+origin changes. `connect: required` is rejected, and declaring `external_access`
+with SDK older than 0.29.0 is rejected. Compose and gateway SDK pins must match.
+See [external access configuration](skills/reference/identity-gateway.md#external-access)
+for the manifest, settings entry, URL rules and cold-login handoff.
+
 Compose uses schema-2 `dsm-package.yaml` and `ui.launch`; the default is new-page.
 Classless gateways use type url via the shared contract/app-launch resolver;
 AppWindow wrappers use standalone. Headless projects have no launcher.

package/dist/error-registry.js

@@ -362,6 +362,16 @@ export const ERROR_REGISTRY = {
             description: "The identity_gateway declaration does not match the gateway contract.",
             suggestion: "Declare a daemon; set sdk, mode (oidc, header or token), the App's loopback upstream port and distinct listen ports other than 5000/5001; keep passthrough and redirects local paths outside /_sso; oidc needs issuer_port and clients, header needs headers.user, token needs token.exec in the daemon payload.",
         },
+        STANDALONE_IDENTITY_GATEWAY_EXTERNAL_INVALID: {
+            code: "STANDALONE_IDENTITY_GATEWAY_EXTERNAL_INVALID",
+            description: "The external access declaration does not match the gateway contract.",
+            suggestion: "Set identity_gateway.external_access.connect to optional or none, and origin_change to none or confirm; required is not supported.",
+        },
+        STANDALONE_IDENTITY_GATEWAY_EXTERNAL_SDK_REQUIRED: {
+            code: "STANDALONE_IDENTITY_GATEWAY_EXTERNAL_SDK_REQUIRED",
+            description: "External access requires SDK 0.29.0 or later and matching gateway sources.",
+            suggestion: "Update identity_gateway.sdk and compose.sdk together to SDK 0.29.0 or later; ensure any development SDK override includes external access and settings.cgi support.",
+        },
         STANDALONE_IDENTITY_GATEWAY_BUILD_FAILED: {
             code: "STANDALONE_IDENTITY_GATEWAY_BUILD_FAILED",
             description: "The SDK identity gateway could not be built from identity_gateway.sdk.",

package/dist/standalone/compose-errors.js

@@ -13,7 +13,7 @@ export const COMPOSE_ERRORS = {
     COMPOSE_STARTUP_INVALID: {
         code: "COMPOSE_STARTUP_INVALID",
         description: "The container startup budget is invalid.",
-        suggestion: "Set compose.startup_timeout_seconds to an integer from 2 to 900 seconds; the default is 120. Read the same SYNOPKGLAND_STARTUP_BUDGET_SECONDS in the App bootstrap adapter.",
+        suggestion: "Set compose.startup_timeout_seconds to an integer from 2 to 900 seconds; the default is 900, which a loaded HDD NAS may need. Read the same SYNOPKGLAND_STARTUP_BUDGET_SECONDS in the App bootstrap adapter.",
     },
     COMPOSE_STARTUP_TIMEOUT: {
         code: "COMPOSE_STARTUP_TIMEOUT",
@@ -82,8 +82,8 @@ export const COMPOSE_ERRORS = {
     },
     COMPOSE_HEALTH_NOT_READY: {
         code: "COMPOSE_HEALTH_NOT_READY",
-        description: "The App health endpoint did not return the expected status.",
-        suggestion: "Check the declared App health path/status and upstream health; redirects are not followed.",
+        description: "The App health endpoint did not return the expected status within the startup budget.",
+        suggestion: "Check the declared App health path/status and upstream health; redirects are not followed. daemon/daemon.log records how long the App stayed unavailable. Keep the default startup budget on slow NAS devices.",
     },
     COMPOSE_REQUEST_INVALID: {
         code: "COMPOSE_REQUEST_INVALID",

package/dist/standalone/compose.js

@@ -77,7 +77,7 @@ export function readComposeApp(value, root, arches, fail, context = {}) {
     if (value.startup_timeout_seconds !== undefined &&
         (!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");
+        return invalid("compose.startup_timeout_seconds must be an integer from 2 to 900 seconds (default 900).", "COMPOSE_STARTUP_INVALID");
     let hostUdp;
     if (value.host_udp !== undefined) {
         const ports = new Set();
@@ -178,7 +178,7 @@ export function composeDaemon(m) {
         args: ["run"],
         targets: m.compose.targets,
         env: {},
-        timeouts: { stop: 30, status: 5, uninstall: 60, ...m.lifecycleTimeouts, start: m.compose.plan.startup_timeout_seconds ?? m.lifecycleTimeouts?.start ?? 120 },
+        timeouts: { stop: 30, status: 5, uninstall: 60, ...m.lifecycleTimeouts, start: m.compose.plan.startup_timeout_seconds ?? m.lifecycleTimeouts?.start ?? 900 },
     };
 }
 export function composeNetwork(m) {

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

@@ -7,11 +7,22 @@ import type { StandaloneError, StandaloneManifest } from "./manifest.js";
 export declare const GATEWAY_MAIN = "./idgateway/cmd/gateway";
 /** Served by DSM at /webman/3rdparty/<package>/sso/authorize.cgi. */
 export declare const GATEWAY_CGI_PATH = "ui/sso/authorize.cgi";
+export declare const GATEWAY_SETTINGS_CGI_PATH = "ui/sso/settings.cgi";
 /** The gateway inside the daemon payload; the App's payload must leave _sso/ free. */
 export declare const GATEWAY_PAYLOAD_DIR = "_sso";
 export declare const GATEWAY_EXEC = "_sso/gateway";
 export declare const GATEWAY_CONFIG_PATH = "sso/gateway.json";
 export type GatewayMode = "none" | "oidc" | "header" | "token";
+export interface GatewayExternalAccess {
+    connect: "optional" | "none";
+    origin_change: "none" | "confirm";
+}
+export declare const EXTERNAL_ACCESS_MIN_SDK = "0.29.0";
+/** SDK 0.28 has the diagnostic ping only; older gateways reject external JSON. */
+export declare function externalAccessSdkSupported(sdk: string): boolean;
+export declare function gatewayExternalAccess(gateway: IdentityGateway): GatewayExternalAccess | undefined;
+/** The SDK executable dispatches these entry points by SCRIPT_NAME. */
+export declare function gatewayCgiPaths(gateway: IdentityGateway): string[];
 export interface GatewayRoles {
     claim: string;
     admin: string;
@@ -34,6 +45,7 @@ export interface GatewayBrowser {
 export interface IdentityGateway {
     /** The SDK release the gateway is built from. */
     sdk: string;
+    external_access?: GatewayExternalAccess;
     mode: GatewayMode;
     /** Fixed same-origin menu target, including optional query and fragment. */
     launch_path?: string;

package/dist/standalone/identity-gateway.js

@@ -13,10 +13,25 @@ import { StandaloneBuildError } from "./spk.js";
 export const GATEWAY_MAIN = "./idgateway/cmd/gateway";
 /** Served by DSM at /webman/3rdparty/<package>/sso/authorize.cgi. */
 export const GATEWAY_CGI_PATH = "ui/sso/authorize.cgi";
+export const GATEWAY_SETTINGS_CGI_PATH = "ui/sso/settings.cgi";
 /** The gateway inside the daemon payload; the App's payload must leave _sso/ free. */
 export const GATEWAY_PAYLOAD_DIR = "_sso";
 export const GATEWAY_EXEC = `${GATEWAY_PAYLOAD_DIR}/gateway`;
 export const GATEWAY_CONFIG_PATH = "sso/gateway.json";
+export const EXTERNAL_ACCESS_MIN_SDK = "0.29.0";
+/** SDK 0.28 has the diagnostic ping only; older gateways reject external JSON. */
+export function externalAccessSdkSupported(sdk) {
+    const [major, minor] = sdk.split(".").map(Number);
+    return major > 0 || minor >= 29;
+}
+export function gatewayExternalAccess(gateway) {
+    return gateway.external_access ?? (externalAccessSdkSupported(gateway.sdk)
+        ? { connect: "optional", origin_change: "none" } : undefined);
+}
+/** The SDK executable dispatches these entry points by SCRIPT_NAME. */
+export function gatewayCgiPaths(gateway) {
+    return [GATEWAY_CGI_PATH, "ui/sso/open.cgi", ...(gatewayExternalAccess(gateway) ? [GATEWAY_SETTINGS_CGI_PATH] : [])];
+}
 const record = (v) => Boolean(v) && typeof v === "object" && !Array.isArray(v);
 const only = (v, keys) => Object.keys(v).every((k) => keys.includes(k));
 const port = (v) => Number.isInteger(v) && v > 0 && v < 65536;
@@ -125,6 +140,7 @@ export function readIdentityGateway(value, daemon, fail, packagedPayload = false
     if (!record(value) ||
         !only(value, [
             "sdk",
+            "external_access",
             "mode",
             "access",
             "upstream_access",
@@ -145,9 +161,20 @@ export function readIdentityGateway(value, daemon, fail, packagedPayload = false
             "token",
             "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.");
+        return invalid("accepts only sdk, external_access, mode, access, upstream_access, groups, upstream, listen, passthrough, optional_passthrough, redirects, email_domain, session_ttl, roles, headers, oidc, token and account.");
     }
     const v = value;
+    let externalAccess;
+    if (v.external_access !== undefined) {
+        const external = v.external_access;
+        if (!record(external) || !only(external, ["connect", "origin_change"]) ||
+            (external.connect !== undefined && external.connect !== "optional" && external.connect !== "none") ||
+            (external.origin_change !== undefined && external.origin_change !== "none" && external.origin_change !== "confirm")) {
+            fail({ code: "STANDALONE_IDENTITY_GATEWAY_EXTERNAL_INVALID", message: "identity_gateway.external_access accepts only connect (optional or none) and origin_change (none or confirm); required is not supported." });
+            return undefined;
+        }
+        externalAccess = { connect: external.connect ?? "optional", origin_change: external.origin_change ?? "none" };
+    }
     if (v.launch_path !== undefined) {
         try {
             const raw = v.launch_path;
@@ -187,6 +214,12 @@ export function readIdentityGateway(value, daemon, fail, packagedPayload = false
         return invalid("response_header_timeout_seconds must be 1–3600.");
     if (typeof v.sdk !== "string" || !/^\d+\.\d+\.\d+$/.test(v.sdk))
         return invalid("sdk must be the SDK release (x.y.z) to build the gateway from.");
+    if (externalAccess && !externalAccessSdkSupported(v.sdk)) {
+        fail({ code: "STANDALONE_IDENTITY_GATEWAY_EXTERNAL_SDK_REQUIRED", message: `identity_gateway.external_access requires SDK ${EXTERNAL_ACCESS_MIN_SDK} or later; SDK 0.28.0 provides the diagnostic ping only.` });
+        return undefined;
+    }
+    if (!externalAccess && externalAccessSdkSupported(v.sdk))
+        externalAccess = { connect: "optional", origin_change: "none" };
     if (v.mode !== "none" &&
         v.mode !== "oidc" &&
         v.mode !== "header" &&
@@ -262,6 +295,7 @@ export function readIdentityGateway(value, daemon, fail, packagedPayload = false
         return invalid("header mode needs headers.user.");
     const gateway = {
         sdk: v.sdk,
+        ...(externalAccess ? { external_access: externalAccess } : {}),
         mode: v.mode,
         ...(v.launch_path !== undefined ? { launch_path: v.launch_path } : {}),
         access,
@@ -405,6 +439,7 @@ export function identityGatewayConfig(m) {
     const g = m.identityGateway;
     return (JSON.stringify({
         package: m.package,
+        ...(gatewayExternalAccess(g) ? { external: gatewayExternalAccess(g) } : {}),
         ...(nativeGatewaySupported(m) ? { native_ingress: true } : {}),
         ...(runtimeBudgetSdkSupported(g.sdk) ? {
             operation_seconds: operationBudgetSeconds(m),
@@ -490,6 +525,13 @@ export async function buildIdentityGateway(m, arch, work, run) {
         throw new StandaloneBuildError("SDK_DOWNLOAD_FAILED", error.message.replace(/^\[[A-Z_]+\] /, ""));
     }
     runtimeBudgetSource(sdk.goDir, m);
+    if (gatewayExternalAccess(m.identityGateway)) {
+        const config = join(sdk.goDir, "idgateway/config.go");
+        const main = join(sdk.goDir, "idgateway/cmd/gateway/main.go");
+        if (!existsSync(config) || !/`json:"external(?:,omitempty)?"`/.test(readFileSync(config, "utf8")) ||
+            !existsSync(main) || !/["']\/?settings\.cgi["']/.test(readFileSync(main, "utf8")))
+            throw new StandaloneBuildError("STANDALONE_IDENTITY_GATEWAY_EXTERNAL_SDK_REQUIRED", `The selected SDK source lacks external access or settings.cgi support; use SDK ${EXTERNAL_ACCESS_MIN_SDK} or later with matching sources.`);
+    }
     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")))

package/dist/standalone/inspect-spk.js

@@ -36,7 +36,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, gatewayAdmissionReport, gatewayAdmissionPolicy, readIdentityGateway, } from "./identity-gateway.js";
+import { identityGatewayConfig, gatewayCgiPaths, GATEWAY_SETTINGS_CGI_PATH, gatewayAdmissionReport, gatewayAdmissionPolicy, readIdentityGateway, } from "./identity-gateway.js";
 import { checkCgiBinary } from "./binary.js";
 import { matchesStandaloneScript, renderStandaloneScript, matchesStandaloneScriptPrefix } from "./lifecycle.js";
 import { listPortExposures, loadCompose } from "../compose/analyze.js";
@@ -133,6 +133,7 @@ export async function inspectSpk(spkPath, expectedKind) {
         if (metadata.daemon_restart !== undefined && (metadata.compose !== undefined || !paths.has("daemon/control")))
             findings.push("DAEMON_RESTART_INVALID daemon restart requires a native daemon controller, without Compose supervision");
         const identityGateway = await inspectProviderOnlyAdmission(dir, paths, metadata.provider_only_oidc, findings);
+        await inspectExternalGateway(dir, paths, payload, metadata.gateway_external, findings);
         const installSettings = await inspectInstallSettings(dir, payload, metadata, findings);
         if (metadata.compose !== undefined) {
             const result = await inspectUnifiedCompose(dir, payload, { ...metadata, installSettings }, findings);
@@ -801,8 +802,7 @@ async function inspectUnifiedCompose(dir, payload, metadata, findings) {
         const binaries = [
             "daemon/control",
             "daemon/payload/_sso/gateway",
-            "ui/sso/authorize.cgi",
-            "ui/sso/open.cgi",
+            ...(g ? gatewayCgiPaths(g) : []),
         ];
         for (const path of g ? binaries : []) {
             const problem = checkCgiBinary(root, join(root, path), arch);
@@ -1120,6 +1120,39 @@ async function inspectProviderOnlyAdmission(dir, paths, saved, findings) {
         return;
     }
 }
+/** External settings are the same package-account gateway binary as the existing CGI entries. */
+async function inspectExternalGateway(dir, paths, payload, saved, findings) {
+    if (!paths.has("sso/gateway.json") && saved === undefined && !paths.has(GATEWAY_SETTINGS_CGI_PATH))
+        return;
+    try {
+        const info = readInfo(join(dir, "INFO"), [], "binary");
+        const root = join(dir, "external-gateway-inspection");
+        mkdirSync(root);
+        const entries = ["sso/gateway.json", GATEWAY_SETTINGS_CGI_PATH, "ui/sso/open.cgi"];
+        await tar.x({ file: join(dir, "package.tgz"), cwd: root, filter: p => entries.includes(p.replace(/^\.\//, "")) });
+        const cfg = JSON.parse(readFileSync(join(root, "sso/gateway.json"), "utf8"));
+        if (saved === undefined && cfg.external === undefined && !paths.has(GATEWAY_SETTINGS_CGI_PATH))
+            return;
+        const external = saved;
+        if (!external || typeof external !== "object" || Array.isArray(external) ||
+            Object.keys(external).length !== 2 || (external.connect !== "optional" && external.connect !== "none") ||
+            (external.origin_change !== "none" && external.origin_change !== "confirm") ||
+            !isDeepStrictEqual(cfg.external, external) || cfg.package !== info.package)
+            throw new Error("external configuration differs from its package declaration");
+        const arch = info.arch.split(/\s+/).map(familyOfArchToken).find(Boolean) ?? "x86_64";
+        const path = join(root, GATEWAY_SETTINGS_CGI_PATH);
+        const problem = checkCgiBinary(root, path, arch);
+        if (problem)
+            throw new Error(problem.message);
+        if (payload.find(p => p.path === GATEWAY_SETTINGS_CGI_PATH)?.mode !== "0755")
+            throw new Error("settings.cgi must be executable");
+        if (!readFileSync(path).equals(readFileSync(join(root, "ui/sso/open.cgi"))))
+            throw new Error("settings.cgi must be the packaged gateway executable");
+    }
+    catch (e) {
+        findings.push(`GATEWAY_EXTERNAL_INVALID ${e.message}`);
+    }
+}
 async function recoverNativeGateway(dir, value, info, findings) {
     if (value === undefined)
         return undefined;

package/dist/standalone/oidc-resume.d.ts

@@ -1,2 +1,2 @@
-/** No caller-provided URL reaches location: only a transaction and a declared port. */
+/** Only the fixed DSM CGI receives a resume token; external origins are resolved by the SDK. */
 export declare function oidcResumeRuntime(pkg: string, ports: number[]): string;

package/dist/standalone/oidc-resume.js

@@ -1,4 +1,4 @@
-/** No caller-provided URL reaches location: only a transaction and a declared port. */
+/** Only the fixed DSM CGI receives a resume token; external origins are resolved by the SDK. */
 export function oidcResumeRuntime(pkg, ports) {
     return `(function(param) {
   if (typeof param === 'string') {
@@ -14,13 +14,18 @@ export function oidcResumeRuntime(pkg, ports) {
   }
   if (!param || typeof param !== 'object' || Array.isArray(param)) return false;
   var value = param && param.ssoResume;
-  if (typeof value !== 'string') return false;
+  if (typeof value !== 'string' || /\\s/.test(value)) return false;
+  var external = /^[A-Za-z0-9_-]{1,128}:x[01]:[0-9]{1,19}\\.[0-9]{1,19}$/.test(value);
   var parts = /^([A-Za-z0-9_-]{1,128}):([0-9]{1,5})$/.exec(value);
-  if (!parts || ${JSON.stringify(ports)}.indexOf(Number(parts[2])) < 0) return false;
+  if (!external && (!parts || ${JSON.stringify(ports)}.indexOf(Number(parts[2])) < 0)) return false;
   var target = new URL(${JSON.stringify(`/webman/3rdparty/${pkg}/sso/authorize.cgi`)},location.origin);
-  var app = new URL(location.origin); app.port = parts[2]; app.pathname = '/_sso/dsm-return';
-  target.searchParams.set('return',app.href);
-  target.searchParams.set('txn',parts[1]);
+  if (external) {
+    target.searchParams.set('resume',value);
+  } else {
+    var app = new URL(location.origin); app.port = parts[2]; app.pathname = '/_sso/dsm-return';
+    target.searchParams.set('return',app.href);
+    target.searchParams.set('txn',parts[1]);
+  }
   target.searchParams.set('login_attempt','1');
   location.replace(target.href);
   return true;

package/dist/standalone/spk.js

@@ -31,7 +31,7 @@ import { hostScriptName, renderHostAdapterScript } from "./host-adapter.js";
 import { writeComposePayload } from "./compose.js";
 import { copyDaemonPayload, daemonSdkVersion, nodeDependency } from "./daemon.js";
 import { DAEMON_INGRESS_CONFIG, renderDaemonIngressConfig } from "./daemon-ingress.js";
-import { GATEWAY_CGI_PATH, GATEWAY_CONFIG_PATH, GATEWAY_EXEC, identityGatewayConfig, identityGatewayDeclaration, } from "./identity-gateway.js";
+import { gatewayCgiPaths, gatewayExternalAccess, GATEWAY_CONFIG_PATH, GATEWAY_EXEC, identityGatewayConfig, identityGatewayDeclaration, } from "./identity-gateway.js";
 import { BACKGROUND_UNIT_DIR, BACKGROUND_WORKER_PAYLOAD, backgroundUnitName, renderBackgroundUnit, BRIDGE_WORKER_ARGS, } from "./background.js";
 import { renderStandaloneResource } from "./resource.js";
 import { nativePortal } from "./portal.js";
@@ -112,8 +112,7 @@ export async function assembleStandaloneSpk(options) {
             if (!options.identityGateway)
                 throw new StandaloneBuildError("STANDALONE_IDENTITY_GATEWAY_ARTIFACT_REQUIRED", "identity gateway artifact required.");
             for (const path of [
-                GATEWAY_CGI_PATH,
-                "ui/sso/open.cgi",
+                ...gatewayCgiPaths(manifest.identityGateway),
                 `daemon/payload/${GATEWAY_EXEC}`,
             ]) {
                 const target = join(staging, "package", path);
@@ -232,6 +231,8 @@ export async function assembleStandaloneSpk(options) {
             ...(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) } : {}),
+            ...(manifest.identityGateway && gatewayExternalAccess(manifest.identityGateway)
+                ? { gateway_external: gatewayExternalAccess(manifest.identityGateway) } : {}),
             ...(nativeGatewaySupported(manifest) ? { native_gateway: { sdk: manifest.identityGateway.sdk, listen: manifest.identityGateway.listen } } : {}),
             ...(manifest.daemon?.ingress ? { daemon_ingress: manifest.daemon.ingress } : {}),
             ...(manifest.daemon?.node ? { daemon_node: manifest.daemon.node } : {}),
@@ -410,7 +411,7 @@ function copyUiTree(source, target) {
                     throw new StandaloneBuildError("STANDALONE_UI_TOO_LARGE", "The UI directory exceeds 64 MiB.");
                 }
                 copyFileSync(src, join(to, name));
-                chmodSync(join(to, name), FILE_MODE);
+                chmodSync(join(to, name), name.endsWith(".cgi") ? EXEC_MODE : FILE_MODE);
             }
             else {
                 throw new StandaloneBuildError("STANDALONE_UI_SPECIAL_FILE", `The UI directory may contain only regular files and directories: ${src}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.27.1",
+  "version": "0.29.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.27.0",
+    "@synopackageland/templates": "~0.29.0",
     "ajv": "^8.17.1",
     "commander": "^13.1.0",
     "json-canonicalize": "^3.0.1",

package/skills/reference/compose.md

@@ -35,16 +35,31 @@ and `identity_gateway` for headless projects. Optional `compose.helpers` names
 architecture-specific native payloads for token/account adapters. All lifecycle
 scripts run as the package account; containers are managed by Container Manager.
 
+For external access, pin both `compose.sdk` and `identity_gateway.sdk` to
+0.29.0 or later and use the gateway's
+[`external_access` policy and DSM settings entry](identity-gateway.md#external-access).
+There are no installation-wizard URL fields or post-install state initialization.
+Manual URL configuration does not require Connect. The SDK resolves the public
+origin for Compose; restart the App after changing an origin used by its
+environment or a generated private snapshot.
+
 ## Startup budget
 
-Set `compose.startup_timeout_seconds: 600` for a slow cold start or migration.
-Omitting it uses 120 seconds; only integers from 2 through 900 are accepted.
+Omit `compose.startup_timeout_seconds`: the default of 900 seconds lets a loaded
+HDD NAS with 2 GB RAM start the App. Declare a shorter value only with device
+evidence; only integers from 2 through 900 are accepted.
 Lock waiting, status, readiness, stability and handoff share that deadline; there
 is no extra fixed handoff allowance. The cap is a policy bound, not a measured
 DSM lifecycle limit. `daemon: {timeouts: {stop: 120, status: 15, uninstall: 300}}`
 configures the other lifecycle phases without declaring a daemon payload.
-A transient health failure closes new ingress while the running App gets one
-operation-budget recovery window; authority or generation failures stop at once.
+One readiness probe may take 30 seconds. A health failure after startup closes
+new ingress and the gateway shows a localized, self-refreshing starting page
+(`app_starting` for API clients) while DSM status stays running; the App gets
+the startup budget to recover before its gateway stops. Authority or generation
+failures stop at once. The SDK raises stricter Compose healthcheck timing to
+timeout 30s, retries 3 and start_period equal to the startup budget; declare the
+health command only, without timing or short in-command limits such as
+`curl --max-time 2`.
 Use a matching SDK that implements the field and rebuild the App; older planners
 are rejected for explicit budgets. The SDK plan drives generated daemon start
 and supplies every container with `SYNOPKGLAND_STARTUP_BUDGET_SECONDS`, overriding
@@ -93,7 +108,7 @@ a build operator trust decision. `check`/`inspect` remain offline.
 
 | Feature | Current behavior |
 | --- | --- |
-| Files in one directory, profiles, anchors, depends_on, healthcheck | Reference-loader semantics retained; DSM worker compatibility needs device acceptance |
+| Files in one directory, profiles, anchors, depends_on, healthcheck | Reference-loader semantics retained; healthcheck timing receives the SDK slow-NAS floor; DSM worker compatibility needs device acceptance |
 | Named local volumes | Stable package namespace, retained across recreation; inspect inventory |
 | Private bind data | DSM build rejects COMPOSE_PRIVATE_BIND_TIMING_UNSUPPORTED: clean-install preinst precedes pkgvar creation, while worker acquire precedes postinst; no root initialization or automatic volume conversion |
 | Image VOLUME | Build inventories verified image config and assigns a stable named volume |

package/skills/reference/identity-gateway.md

@@ -1,5 +1,67 @@
 # Wrap an OSS app with DSM accounts
 
+## External access
+
+Use SDK 0.29.0 or later with matching gateway sources. Add this to the existing
+complete gateway declaration; keep the App's upstream, listener and auth policy:
+
+```yaml
+identity_gateway:
+  sdk: 0.29.0
+  external_access:
+    connect: optional    # optional | none
+    origin_change: none # none | confirm
+```
+
+Omitting the block or either member uses `connect: optional` and
+`origin_change: none`. `connect: required`, unknown members and other values
+are rejected. SDKs below 0.29.0 reject an explicit block, including an empty
+one. SDK 0.28.0 supplies the diagnostic ping without external access. On
+Compose Apps, `compose.sdk` and `identity_gateway.sdk` must name the same
+release. Build also rejects a development SDK override without the external
+configuration and settings CGI dispatch support.
+
+The generated `target/sso/gateway.json` uses
+`"external":{"connect":"optional","origin_change":"none"}`. Older SDK targets
+omit this member and the settings entry. The SPK packages the gateway
+executable as `ui/sso/settings.cgi` with mode 0755, alongside `open.cgi` and
+`authorize.cgi`; it runs as the package account. `inspect` checks the policy
+inventory, executable mode and matching gateway bytes.
+
+An administrator opens
+`https://<NAS>:<DSM port>/webman/3rdparty/<package>/sso/settings.cgi` to view the
+LAN, manual, Connect and private URLs. The initial GET only bootstraps the DSM
+token; protected data and writes require a token-bearing POST, a valid DSM
+session and administrator access. Manual configuration requires no Connect
+installation. It edits only `manual_origin` and `dsm_origin` in private
+`<StateDir>/external.json`; do not package initial state or installation-wizard
+URL fields.
+
+Public origins must use HTTPS and a DNS hostname. Port 443 is normalized;
+other ports, IP addresses, paths, queries and user information are rejected,
+as is an origin equal to the DSM origin. Manual takes precedence, then the
+Connect projection when `connect: optional`; the first effective origin is
+primary. `connect: none` ignores that projection. Private URLs are display-only.
+Use `origin_change: confirm` for an App that must confirm public-origin changes.
+
+Cold DSM login preserves external resume tokens
+`<txn>:x<n>:<r1>.<r2>` in the fixed `authorize.cgi?resume=<encoded token>`
+handoff. The transaction contains 1–128 ASCII letters, digits, underscores or
+hyphens; `n` is 0 or 1 and each revision is a 1–19 digit decimal string. The
+renderer never converts revisions through JavaScript Number or constructs an
+external URL. The SDK checks origin, browser binding and current revisions;
+stale revisions and unavailable indices fall back to LAN login. Local
+`<txn>:<declared port>` resume remains supported. The SDK's `open.cgi` owns
+resume handling for classless URL launchers, including Compose and `ui: false`.
+
+Connect forwards to an administrator-approved App name and port. The ping is
+a routing diagnostic; other services on that same listener may also be
+reachable. It does not prove that all content belongs to the App. Existing
+App authentication and passthrough policy still apply. Public provider limits
+also apply: Cloudflare edge enforces the zone's upload limit, and long
+responses need heartbeats within 60 seconds; use SSE or
+`Cache-Control: no-transform` for streaming.
+
 ## Per-request OIDC browser origins (development)
 
 `oidc.browser_redirect: {}` opts into per-request browser origins for SDK/CLI

package/skills/reference/lifecycle.md

@@ -115,7 +115,7 @@ Use existing `daemon.timeouts` for start/stop/status/uninstall (defaults
 30/30/5/60 seconds). Start/stop/uninstall accept 2–3600 seconds and status accepts
 1–3600. A `daemon` containing only `timeouts` declares budgets without an
 executable, including background and Compose Apps; Compose start still uses
-`compose.startup_timeout_seconds` (120, 2–900). Background user-manager recovery
+`compose.startup_timeout_seconds` (900, 2–900). Background user-manager recovery
 uses the start allowance and its generated package user unit uses the stop
 allowance with `KillMode=control-group`.