@synopackageland/cli 0.28.0 → 0.30.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.30.0 (2026-10-24)
+
+- Package and forward `identity_gateway.external_access.single_origin`; use SDK 0.30.0 for one-URL Apps, provider-aware DSM menu launches and launch probes.
+- Pin templates 0.30.x and its SDK/App 0.30.0 defaults; keep immutable executor/v0.27.0.
+
+## Unreleased
+
+- Accept and package `identity_gateway.external_access.single_origin` (boolean) for one-URL upstreams. Build requires SDK sources with `single_origin` support, and inspect accepts the packaged `single_origin: true` declaration.
+
+## 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.

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.28.0 depends on `~0.28.0`: npm installation or
-update can select the latest templates patch in the 0.28 minor line. Templates
+`@synopackageland/templates`. CLI 0.30.0 depends on `~0.30.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,17 @@ 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, and `single_origin: true` (SDK 0.30.0+) for an upstream that
+works on one URL only. `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, origin_change to none or confirm, and single_origin to a boolean; 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/identity-gateway.d.ts

@@ -7,11 +7,24 @@ 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";
+    /** One-URL upstream: DSM launch and local navigations go to the primary external origin. */
+    single_origin?: true;
+}
+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 +47,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,21 @@ 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", "single_origin"]) ||
+            (external.connect !== undefined && external.connect !== "optional" && external.connect !== "none") ||
+            (external.origin_change !== undefined && external.origin_change !== "none" && external.origin_change !== "confirm") ||
+            (external.single_origin !== undefined && typeof external.single_origin !== "boolean")) {
+            fail({ code: "STANDALONE_IDENTITY_GATEWAY_EXTERNAL_INVALID", message: "identity_gateway.external_access accepts only connect (optional or none), origin_change (none or confirm) and single_origin (boolean); required is not supported." });
+            return undefined;
+        }
+        externalAccess = { connect: external.connect ?? "optional", origin_change: external.origin_change ?? "none", ...(external.single_origin ? { single_origin: true } : {}) };
+    }
     if (v.launch_path !== undefined) {
         try {
             const raw = v.launch_path;
@@ -187,6 +215,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 +296,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 +440,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 +526,17 @@ 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.`);
+        const external = join(sdk.goDir, "idgateway/external.go");
+        if (gatewayExternalAccess(m.identityGateway)?.single_origin &&
+            (!existsSync(external) || !/`json:"single_origin(?:,omitempty)?"`/.test(readFileSync(external, "utf8"))))
+            throw new StandaloneBuildError("STANDALONE_IDENTITY_GATEWAY_EXTERNAL_SDK_REQUIRED", "The selected SDK source lacks external_access.single_origin support; use a matching SDK release or an explicit development source override.");
+    }
     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,40 @@ 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 !== (external.single_origin === undefined ? 2 : 3) || (external.connect !== "optional" && external.connect !== "none") ||
+            (external.origin_change !== "none" && external.origin_change !== "confirm") ||
+            (external.single_origin !== undefined && external.single_origin !== true) ||
+            !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/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 } : {}),

package/package.json

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

package/skills/reference/compose.md

@@ -35,6 +35,14 @@ 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
 
 Omit `compose.startup_timeout_seconds`: the default of 900 seconds lets a loaded

package/skills/reference/identity-gateway.md

@@ -1,5 +1,75 @@
 # Wrap an OSS app with DSM accounts
 
+## External access
+
+Use SDK 0.30.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.30.0
+  external_access:
+    connect: optional    # optional | none
+    origin_change: none # none | confirm
+    single_origin: false # true for an upstream that works on one URL only
+```
+
+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 (except a single-origin App's `manual_origin`), 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.
+Declare `single_origin: true` (with `origin_change: confirm`) for an App whose
+upstream sign-in works on one fixed URL, such as Vaultwarden's `DOMAIN`. While
+an external origin is set, the DSM launcher opens the primary origin and local
+browser navigations redirect to it; the settings page says that only that
+address can sign in. Without an external origin nothing changes. The generated
+`external` object then carries `"single_origin":true`, and build rejects a
+development SDK source without `single_origin` support.
+
+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
@@ -198,3 +268,5 @@ 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.
+
+Single-origin Apps require SDK 0.30.0 or later. Their `manual_origin` may include an explicit HTTPS port (for example, `https://example.ts.net:29443`). The DSM launcher resolves the destination for the provider used to open DSM, probes `/_spl/ping` for up to eight seconds, and offers **Open anyway** if the probe fails. A single-origin App always uses its configured primary origin. Other Apps and the `external-origin` install setting continue to require HTTPS DNS origins on port 443.