@synopackageland/cli 0.12.2 → 0.13.0

package/dist/standalone/identity-gateway.js

@@ -0,0 +1,215 @@
+import { existsSync, lstatSync } 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";
+import { sdkSource } from "../runtime/sdk-source.js";
+import { checkCgiBinary } from "./binary.js";
+import { relativeExec, token } from "./daemon.js";
+import { StandaloneBuildError } from "./spk.js";
+/** The SDK's identity gateway: the daemon wrapper and the DSM-origin authorize CGI. */
+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";
+/** 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";
+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;
+/** An absolute local path without dot segments, backslashes or a query. */
+const localPath = (v) => typeof v === "string" && v.length <= 512 && /^\/[A-Za-z0-9._~!$&'()*+,;=:@%/-]*$/.test(v)
+    && !v.startsWith("//") && !v.split("/").some(p => p === "." || p === "..");
+const strings = (v, ok, max = 64) => Array.isArray(v) && v.length <= max && v.every(ok);
+const name = (v) => typeof v === "string" && /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/.test(v);
+const headerName = (v) => typeof v === "string" && /^[A-Za-z0-9][A-Za-z0-9-]{0,63}$/.test(v);
+const claimValue = (v) => typeof v === "string" && /^[A-Za-z0-9_.:-]{1,64}$/.test(v);
+/** A mobile app's custom-scheme redirect; web schemes are same-origin redirect_paths instead. */
+const nativeRedirect = (v) => typeof v === "string" && v.length <= 512 && /^[a-z][a-z0-9+.-]*:[^\s]*$/.test(v)
+    && !/^(https?|javascript|data|vbscript|file|blob|about):/.test(v);
+const DSM_PORTS = [5000, 5001];
+/** Only {uid} and {name}, which the gateway expands inside one argv element or path element. */
+const placeholders = (v) => (v.match(/\{[^{}]*\}/g) ?? []).every(p => p === "{uid}" || p === "{name}");
+/** A clean path under the package var directory that names the account, outside the gateway's sso/. */
+const removePath = (v) => typeof v === "string" && v.length <= 512 && placeholders(v)
+    && /^[A-Za-z0-9_{}][A-Za-z0-9_.{}-]*(\/[A-Za-z0-9_.{}-]+)*$/.test(v) && !v.split("/").some(p => p === "." || p === "..")
+    && v.split("/")[0] !== "sso" && /\{(uid|name)\}/.test(v);
+function readAccount(v, daemon) {
+    if (!record(v) || !only(v, ["on_delete"]) || !Array.isArray(v.on_delete) || v.on_delete.length > 16)
+        return "account accepts on_delete, a list of at most 16 actions.";
+    const actions = [];
+    for (const a of v.on_delete) {
+        if (record(a) && only(a, ["remove"]) && removePath(a.remove)) {
+            actions.push({ remove: a.remove });
+            continue;
+        }
+        if (!record(a) || !only(a, ["exec"]) || !Array.isArray(a.exec) || !relativeExec(a.exec[0]) || !strings(a.exec.slice(1), s => token(s) && placeholders(s))) {
+            return "each account.on_delete action is { remove: <path under the var directory naming {uid} or {name}> } or { exec: [<program in the daemon payload>, args...] }; {uid} and {name} are the only placeholders.";
+        }
+        const argv = a.exec;
+        if (!Object.values(daemon.targets).every(dir => existsSync(join(dir, argv[0]))))
+            return `account.on_delete exec ${argv[0]} is not in the daemon payload.`;
+        actions.push({ exec: argv });
+    }
+    return { on_delete: actions };
+}
+function readRoles(v) {
+    if (v === undefined)
+        return undefined;
+    if (!record(v) || !only(v, ["claim", "admin", "user"]))
+        return false;
+    const roles = { claim: v.claim ?? "groups", admin: v.admin ?? "admin", ...(v.user !== undefined ? { user: v.user } : {}) };
+    return claimValue(roles.claim) && claimValue(roles.admin) && (roles.user === undefined || claimValue(roles.user)) ? roles : false;
+}
+function readClient(v) {
+    if (!record(v) || !only(v, ["id", "redirect_paths", "native_redirects", "pkce", "roles"]))
+        return undefined;
+    const native = v.native_redirects ?? [], roles = readRoles(v.roles);
+    if (!name(v.id) || !strings(v.redirect_paths, localPath) || !strings(native, nativeRedirect) || (v.pkce !== undefined && typeof v.pkce !== "boolean") || roles === false)
+        return undefined;
+    if (!v.redirect_paths.length && !native.length)
+        return undefined;
+    return { id: v.id, redirect_paths: v.redirect_paths, native_redirects: native, require_pkce: v.pkce === true, ...(roles ? { roles } : {}) };
+}
+export function readIdentityGateway(value, daemon, fail) {
+    if (value === undefined)
+        return undefined;
+    const invalid = (why) => { fail({ code: "STANDALONE_IDENTITY_GATEWAY_INVALID", message: `identity_gateway: ${why}` }); return undefined; };
+    if (!daemon)
+        return invalid("needs daemon (native child) or compose (Container Manager upstream).");
+    if (!record(value) || !only(value, ["sdk", "mode", "upstream", "listen", "passthrough", "redirects", "email_domain", "session_ttl", "roles", "headers", "oidc", "token", "account"])) {
+        return invalid("accepts only sdk, mode, upstream, listen, passthrough, redirects, email_domain, session_ttl, roles, headers, oidc, token and account.");
+    }
+    const v = value;
+    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 (v.mode !== "oidc" && v.mode !== "header" && v.mode !== "token")
+        return invalid("mode must be oidc, header or token.");
+    if (!port(v.upstream))
+        return invalid("upstream must be the App's loopback port.");
+    const listen = v.listen;
+    if (!record(listen) || !only(listen, ["http", "https"]) || (listen.http === undefined && listen.https === undefined)
+        || ![listen.http, listen.https].every(p => p === undefined || port(p)))
+        return invalid("listen needs an http and/or https port.");
+    const issuer = record(v.oidc) ? v.oidc.issuer_port : undefined;
+    const ports = [listen.http, listen.https, v.upstream, issuer].filter(p => p !== undefined);
+    if (new Set(ports).size !== ports.length || ports.some(p => DSM_PORTS.includes(p)))
+        return invalid("listen, upstream and oidc.issuer_port must be distinct and not DSM's 5000/5001.");
+    const passthrough = v.passthrough ?? [];
+    if (!strings(passthrough, p => localPath(p) && p !== "/" && !/^\/_sso(\/|$)/.test(p)))
+        return invalid("passthrough must be path prefixes such as /share/, outside /_sso.");
+    const redirects = v.redirects ?? {};
+    if (!record(redirects) || Object.entries(redirects).some(([from, to]) => !localPath(from) || !localPath(to)))
+        return invalid("redirects maps local paths to local paths.");
+    if (v.email_domain !== undefined && (typeof v.email_domain !== "string" || !/^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/.test(v.email_domain)))
+        return invalid("email_domain must be a domain name.");
+    if (v.session_ttl !== undefined && (!Number.isInteger(v.session_ttl) || v.session_ttl < 60 || v.session_ttl > 86400))
+        return invalid("session_ttl must be 60-86400 seconds.");
+    const roles = readRoles(v.roles);
+    if (roles === false)
+        return invalid("roles accepts claim, admin and user values.");
+    const headers = v.headers;
+    if (headers !== undefined && (!record(headers) || !only(headers, ["user", "email", "name", "groups", "uid"]) || !Object.values(headers).every(headerName))) {
+        return invalid("headers maps user, email, name, groups and uid to header names.");
+    }
+    if (v.mode === "header" && !(record(headers) && headers.user))
+        return invalid("header mode needs headers.user.");
+    const gateway = {
+        sdk: v.sdk, mode: v.mode, upstream: v.upstream, listen: { ...(listen.http ? { http: listen.http } : {}), ...(listen.https ? { https: listen.https } : {}) },
+        passthrough: passthrough, redirects: redirects,
+        ...(v.email_domain ? { email_domain: v.email_domain } : {}), ...(v.session_ttl ? { session_ttl: v.session_ttl } : {}),
+        ...(roles ? { roles } : {}), ...(headers ? { headers: headers } : {}),
+    };
+    if (v.mode === "oidc") {
+        const o = v.oidc;
+        if (!record(o) || !only(o, ["issuer_port", "clients", "rewrite_json"]) || !port(o.issuer_port) || !Array.isArray(o.clients) || !o.clients.length || o.clients.length > 16) {
+            return invalid("oidc mode needs oidc.issuer_port and clients.");
+        }
+        const clients = o.clients.map(readClient);
+        if (clients.some(c => !c) || new Set(clients.map(c => c.id)).size !== clients.length)
+            return invalid("each oidc client needs a unique id and redirect_paths (local paths) or native_redirects (custom schemes).");
+        const rewrite = o.rewrite_json ?? [];
+        if (!Array.isArray(rewrite) || !rewrite.every(r => record(r) && only(r, ["method", "path", "field"]) && /^[A-Z]{3,7}$/.test(String(r.method)) && localPath(r.path) && name(r.field))) {
+            return invalid("oidc.rewrite_json entries are { method, path, field }.");
+        }
+        gateway.oidc = { issuer_port: o.issuer_port, clients: clients, rewrite_json: rewrite };
+    }
+    if (v.mode === "token") {
+        const t = v.token;
+        const args = record(t) ? t.args ?? [] : [];
+        if (!record(t) || !only(t, ["exec", "args"]) || !relativeExec(t.exec) || !strings(args, token))
+            return invalid("token mode needs token.exec, a program in the daemon payload.");
+        if (!Object.values(daemon.targets).every(dir => existsSync(join(dir, t.exec))))
+            return invalid(`token.exec ${t.exec} is not in the daemon payload.`);
+        gateway.token = { exec: t.exec, args: args };
+    }
+    if (v.account !== undefined) {
+        const account = readAccount(v.account, daemon);
+        if (typeof account === "string")
+            return invalid(account);
+        gateway.account = account;
+    }
+    if (Object.values(daemon.targets).some(dir => { try {
+        lstatSync(join(dir, GATEWAY_PAYLOAD_DIR));
+        return true;
+    }
+    catch {
+        return false;
+    } })) {
+        return invalid(`the daemon payload must not contain ${GATEWAY_PAYLOAD_DIR}/, where the gateway is installed.`);
+    }
+    return gateway;
+}
+const packageDest = (m) => `/var/packages/${m.package}/target`;
+/** target/sso/gateway.json, the SDK gateway's configuration (idgateway.Config). */
+export function identityGatewayConfig(m) {
+    const g = m.identityGateway;
+    return JSON.stringify({
+        package: m.package, mode: g.mode, upstream: `http://127.0.0.1:${g.upstream}`, listen: g.listen,
+        authorize_cgi: `/webman/3rdparty/${m.package}/sso/authorize.cgi`, state_dir: `/var/packages/${m.package}/var/sso`,
+        passthrough: g.passthrough, redirects: g.redirects,
+        ...(g.email_domain ? { email_domain: g.email_domain } : {}), ...(g.session_ttl ? { session_ttl_seconds: g.session_ttl } : {}),
+        ...(g.roles ? { roles: g.roles } : {}), ...(g.headers ? { headers: g.headers } : {}),
+        ...(g.oidc ? { oidc: g.oidc } : {}),
+        ...(g.token ? { token: { command: [`${packageDest(m)}/daemon/payload/${g.token.exec}`, ...g.token.args] } } : {}),
+        ...(g.account ? { account: {
+                var_dir: `/var/packages/${m.package}/var`,
+                on_delete: g.account.on_delete.map(a => "remove" in a ? a : { exec: [`${packageDest(m)}/daemon/payload/${a.exec[0]}`, ...a.exec.slice(1)] }),
+            } } : {}),
+    }) + "\n";
+}
+/** The daemon as the controller runs it: the gateway, with the App as its child. */
+export function gatewayDaemon(daemon) {
+    const app = `\${SYNOPKG_PKGDEST}/daemon/payload/${daemon.exec}`;
+    return {
+        ...daemon, exec: GATEWAY_EXEC, args: ["run", "--", app, ...daemon.args],
+        ...(daemon.uninstall_args ? { uninstall_args: ["exec", "--", app, ...daemon.uninstall_args] } : {}),
+    };
+}
+/** Builds the gateway from the declared SDK release with the pinned Go, binding its config path. */
+export async function buildIdentityGateway(m, arch, work, run) {
+    if (!m.identityGateway)
+        return undefined;
+    let sdk;
+    try {
+        sdk = sdkSource(m.identityGateway.sdk);
+    }
+    catch (error) {
+        throw new StandaloneBuildError("SDK_DOWNLOAD_FAILED", error.message.replace(/^\[[A-Z_]+\] /, ""));
+    }
+    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", ["build", "-trimpath", "-buildvcs=false", "-ldflags", ldflags, "-o", out, GATEWAY_MAIN], {
+        cwd: sdk.goDir, env: goChildEnv({ ...process.env, ...pinnedGoBuildEnv(arch) }),
+    });
+    if (result.missing || result.status !== 0) {
+        throw new StandaloneBuildError("STANDALONE_IDENTITY_GATEWAY_BUILD_FAILED", `identity gateway (SDK ${sdk.version} ${GATEWAY_MAIN}, ${arch}) build failed; that SDK version must contain the gateway. ${PINNED_GO_HINT}\n${result.stderr}`);
+    }
+    const problem = checkCgiBinary(work, out, arch);
+    if (problem)
+        throw new StandaloneBuildError(problem.code, problem.message);
+    const toolchain = pinnedGoProblem(out);
+    if (toolchain)
+        throw new StandaloneBuildError("STANDALONE_IDENTITY_GATEWAY_BUILD_FAILED", toolchain);
+    return out;
+}

package/dist/standalone/inspect-spk.js

@@ -1,3 +1,4 @@
+import { readComposeApp } from "./compose.js";
 import { createHash } from "node:crypto";
 import { inspectNativeLayout } from "./native-layout.js";
 import { checkBridgeApp, checkBridgeExecutor } from "./inspect-bridge.js";
@@ -79,7 +80,10 @@ export async function inspectSpk(spkPath, expectedKind) {
         const kind = (expectedKind === "native-go" ? compiled : expectedKind) ?? (paths.has("compose.yaml") ? "container" : binaryBackend ? "binary" : compiled);
         const compiledKind = Object.values(COMPILED_KIND).includes(kind);
         const standalone = compiledKind || kind === "binary";
-        const info = readInfo(join(dir, "INFO"), findings, kind);
+        const combined = metadata.compose === undefined ? undefined : await recoverCompose(dir, metadata.compose, findings);
+        const info = readInfo(join(dir, "INFO"), findings, kind, Boolean(combined));
+        if (combined && (!info.os_min_ver || !isDsmAtLeast(info.os_min_ver, CONTAINER_MIN_DSM)))
+            findings.push("compose identity_gateway requires DSM >= 7.2.1");
         await checkArch(dir, info, kind, paths.has(CGI_PAYLOAD_PATH), findings);
         const background = compiledKind && paths.has(BACKGROUND_WORKER_PAYLOAD);
         // Before any fixed-lifecycle comparison: those see the SDK steps alone.
@@ -90,7 +94,7 @@ export async function inspectSpk(spkPath, expectedKind) {
         if (portal && info.os_min_ver && OS_MIN_VER.test(info.os_min_ver) && !isDsmAtLeast(info.os_min_ver, PORTAL_MIN_DSM)) {
             findings.push(`INFO os_min_ver "${info.os_min_ver}" is below the DSM ${PORTAL_MIN_DSM} a portal needs; ${PORTAL_MIN_DSM_REASON}`);
         }
-        checkConf(dir, findings, kind, background, sharedFolder, info.package, portal);
+        checkConf(dir, findings, kind, background, sharedFolder, info.package, portal, combined?.compose);
         checkScripts(dir, findings);
         checkUninstall(dir, findings);
         if (kind === "container")
@@ -99,7 +103,7 @@ export async function inspectSpk(spkPath, expectedKind) {
         const hasExecutor = (metadata.capabilities ?? []).some(name => name === "rootOps" || name === "delegate" || name === "webapi") || paths.has("executor/executor");
         if (standalone && portal && !hasExecutor)
             findings.push("PORTAL_REQUIRES_EXECUTOR portal needs the executor level (rootOps or delegate): after uninstall only a root purge can stop nginx serving the alias");
-        const daemon = standalone ? await checkDaemon(dir, info, paths, payload, findings, hasExecutor, background) : undefined;
+        const daemon = standalone ? await checkDaemon(dir, info, paths, payload, findings, hasExecutor, background, combined) : undefined;
         if (background)
             checkBackground(dir, info, payload, findings, hasExecutor, daemon, kind !== "native-go");
         let executor;
@@ -295,7 +299,31 @@ async function checkArch(dir, info, kind, hasCgi, findings) {
         findings.push(`INFO arch declares ${declared}, but ${CGI_PAYLOAD_PATH} is a ${actual} executable`);
     }
 }
-async function checkDaemon(dir, info, paths, payload, findings, executor, background) {
+async function recoverCompose(dir, value, findings) {
+    try {
+        if (!value || typeof value !== 'object' || Object.keys(value).join() !== 'services')
+            throw new Error('invalid compose inventory');
+        const root = join(dir, 'compose-inspection');
+        mkdirSync(root);
+        await tar.x({ file: join(dir, 'package.tgz'), cwd: root, filter: p => ['compose/docker-compose.yml', 'sso/gateway.json'].includes(p.replace(/^\.\//, '')) });
+        const compose = readComposeApp({ file: 'compose/docker-compose.yml', targets: { x86_64: 'daemon/payload' }, services: value.services }, root, ['x86_64'], e => { throw new Error(e.message); });
+        if (!compose)
+            throw new Error('invalid compose');
+        const config = JSON.parse(readFileSync(join(root, 'sso/gateway.json'), 'utf8'));
+        const upstream = /^http:\/\/127\.0\.0\.1:(\d+)$/.exec(config.upstream)?.[1];
+        const listen = config.listen;
+        if (!upstream || !Object.values(compose.services).some(s => s.port === Number(upstream)) || !listen || !Object.keys(listen).length || Object.entries(listen).some(([key, port]) => !['http', 'https'].includes(key) || !Number.isInteger(port) || Number(port) < 1024 || Number(port) > 65535 || Object.values(compose.services).some(s => s.port === port)))
+            throw new Error('invalid gateway network');
+        if (config.package !== readInfo(join(dir, 'INFO'), [], 'container').package)
+            throw new Error('gateway package mismatch');
+        return { compose, identityGateway: { listen } };
+    }
+    catch (e) {
+        findings.push(`compose identity gateway contract: ${String(e)}`);
+        return undefined;
+    }
+}
+async function checkDaemon(dir, info, paths, payload, findings, executor, background, combined) {
     if (![...paths].some(path => path.startsWith("daemon/")))
         return;
     if (info.precheckstartstop !== "yes")
@@ -309,14 +337,16 @@ async function checkDaemon(dir, info, paths, payload, findings, executor, backgr
     await tar.x({ file: join(dir, "package.tgz"), cwd: unpacked, filter: path => path.replace(/^\.\//, "") === "daemon/config.json" });
     try {
         const config = JSON.parse(readFileSync(join(unpacked, "daemon/config.json"), "utf8"));
-        if (config.package !== info.package || Object.keys(config).some(key => !["package", "exec", "args", "env", "timeouts", "uninstall_args"].includes(key)))
+        if (config.package !== info.package || Object.keys(config).some(key => !["package", "exec", "args", "env", "timeouts", "uninstall_args", ...(combined ? ["network"] : [])].includes(key)))
             throw new Error("package/config mismatch");
         const daemon = readDaemon({ exec: config.exec, args: config.args, uninstall_args: config.uninstall_args, env: config.env, timeouts: config.timeouts, targets: { x86_64: "payload" } }, dir, ["x86_64"], () => { });
         if (!daemon)
             throw new Error("invalid config");
+        if (combined && (daemon.exec !== "_sso/gateway" || JSON.stringify(daemon.args) !== '["run"]' || daemon.uninstall_args))
+            throw new Error("compose gateway must run without a child");
         if (payload.find(p => p.path === `daemon/payload/${daemon.exec}`)?.mode !== "0755")
             throw new Error("missing executable");
-        const manifest = { package: info.package, daemon, capabilities: { ...(executor ? { rootOps: true } : {}), ...(background ? { jobs: { worker: 'sha256-v1' } } : {}) } };
+        const manifest = { package: info.package, daemon, ...combined, capabilities: { ...(executor ? { rootOps: true } : {}), ...(background ? { jobs: { worker: 'sha256-v1' } } : {}) } };
         // A config from before timeouts.uninstall pairs with a control that rejects the key.
         const legacy = typeof config.timeouts === "object" && config.timeouts !== null && !("uninstall" in config.timeouts);
         const { uninstall: _, ...legacyTimeouts } = daemon.timeouts;
@@ -333,7 +363,7 @@ async function checkDaemon(dir, info, paths, payload, findings, executor, backgr
         findings.push("daemon/config.json or the payload does not match the fixed daemon contract");
     }
 }
-function readInfo(path, findings, kind) {
+function readInfo(path, findings, kind, compose = false) {
     if (!existsSync(path)) {
         findings.push("INFO is missing");
         return {};
@@ -354,7 +384,7 @@ function readInfo(path, findings, kind) {
         findings.push("INFO must have thirdparty=\"yes\" and dsmuidir=\"ui\" for DSM to serve /webman/3rdparty/<package>/");
     }
     // A container needs Container Manager (and Web Station for a portal); a Node App the Node.js it runs on.
-    const allowed = kind === "container" ? /^(WebStation|ContainerManager)([><=].*)?$/ : kind === "native-node" ? /^Node\.js_v[0-9]{2}([><=].*)?$/ : undefined;
+    const allowed = compose ? /^ContainerManager$/ : kind === "container" ? /^(WebStation|ContainerManager)([><=].*)?$/ : kind === "native-node" ? /^Node\.js_v[0-9]{2}([><=].*)?$/ : undefined;
     if (info.install_dep_packages && !(allowed && info.install_dep_packages.split(":").every(dep => allowed.test(dep)))) {
         findings.push(`INFO depends on other packages: ${info.install_dep_packages}`);
     }
@@ -379,10 +409,10 @@ async function checkContainerExposure(dir, packageTgz, findings) {
 function readOptional(path) {
     return existsSync(path) ? readFileSync(path, "utf8") : undefined;
 }
-function checkConf(dir, findings, kind, background, sharedFolder, pkg, portal) {
+function checkConf(dir, findings, kind, background, sharedFolder, pkg, portal, compose) {
     const confDir = join(dir, "conf");
     const entries = existsSync(confDir) ? readdirSync(confDir) : [];
-    const nativeResource = kind !== "container" ? renderStandaloneResource({ package: pkg ?? "", capabilities: background ? { jobs: { worker: "sha256-v1" } } : {}, ...(sharedFolder ? { sharedFolder } : {}) }, portal) : undefined;
+    const nativeResource = kind !== "container" ? renderStandaloneResource({ package: pkg ?? "", ...(compose ? { compose } : {}), capabilities: background ? { jobs: { worker: "sha256-v1" } } : {}, ...(sharedFolder ? { sharedFolder } : {}) }, portal) : undefined;
     if (nativeResource !== undefined && readOptional(join(confDir, "resource")) !== nativeResource) {
         findings.push(`conf/resource must be ${nativeResource} (only the official data-share, systemd-user-unit and web-config, and consistent with the install.sharedFolder and portal declarations)`);
     }

package/dist/standalone/lifecycle.js

@@ -1,3 +1,4 @@
+import { composeDaemon, renderComposeInstall } from "./compose.js";
 import { renderBackgroundControl, renderBackgroundWorkerStart, renderBackgroundWorkerStop, renderUserManagerRecovery, backgroundUnitName } from "./background.js";
 import { renderPackagePostuninst } from "../build-spk/native-lifecycle.js";
 import { renderSharedFolderScript } from "./shared-folder.js";
@@ -9,6 +10,11 @@ import { composeAppScript } from "./app-scripts.js";
 const UNINSTALL_ONLY = '[ "${SYNOPKG_PKG_STATUS:-}" = UPGRADE ] || synopkgland_uninstall_hook\n';
 /** Package-account lifecycle hooks for CGI, daemon and background packages. */
 export function renderStandaloneScript(name, manifest) {
+    if (manifest.compose) {
+        const native = { ...manifest, compose: undefined, daemon: composeDaemon(manifest) };
+        const body = name === "preinst" ? renderComposeInstall(manifest.package) : renderStandaloneScript(name, { ...native, appScripts: undefined });
+        return manifest.appScripts?.some(app => app === name) ? composeAppScript(name, body) : body;
+    }
     const portal = nativePortal(manifest);
     const script = renderCapabilityScript(name, manifest);
     const sdk = portal ? script.replace("#!/bin/sh\n", () => `#!/bin/sh\n${renderPortalLifecycle(name, portal)}`) : script;

package/dist/standalone/manifest.d.ts

@@ -7,7 +7,9 @@ import { type Catalogs, type InfoTranslations } from "./i18n.js";
 export type { InfoText } from "./i18n.js";
 import { type RootOp } from "./root-ops.js";
 import type { RootSettings } from "../runtime/root-programs.js";
+import { type ComposeApp } from "./compose.js";
 import { type Daemon } from "./daemon.js";
+import { type IdentityGateway } from "./identity-gateway.js";
 import { type Uninstall } from "./uninstall.js";
 import { type AppScriptName } from "./app-scripts.js";
 import { type Background } from "./background.js";
@@ -76,6 +78,9 @@ export interface StandaloneManifest {
         tasks: ExecutorTask[];
     };
     daemon?: Daemon;
+    /** `identity_gateway`: signs DSM users in to the daemon's own web UI. */
+    identityGateway?: IdentityGateway;
+    compose?: ComposeApp;
     /** `uninstall`: the App's own purge hook and the state the wizard may delete. */
     uninstall?: Uninstall;
     /** `install.sharedFolder`: the Shared Folder the install wizard selects or `data-share` creates. */

package/dist/standalone/manifest.js

@@ -7,7 +7,9 @@ import { parse } from "yaml";
 import { isNativeArchFamily } from "../build-spk/dsm-arch.js";
 import { checkGlossary, loadCatalogs, readInfoTranslations } from "./i18n.js";
 import { loadRootOps, readRootSettings, rootBinaryProblem, ROOT_OPS_DIR } from "./root-ops.js";
+import { readComposeApp } from "./compose.js";
 import { readDaemon } from "./daemon.js";
+import { readIdentityGateway } from "./identity-gateway.js";
 import { readUninstall } from "./uninstall.js";
 import { readAppScripts } from "./app-scripts.js";
 import { readBackground } from "./background.js";
@@ -31,7 +33,7 @@ import { BRIDGE_RUNTIMES, isBridgeBackend, overlaps, readBridgeBackend } from ".
 export const STANDALONE_MANIFEST = "dsm-package.yaml";
 export const KNOWN_FIELDS = new Set([
     "schema", "package", "version", "build", "displayname", "description",
-    "metadata", "maintainer", "os_min_ver", "arches", "backend", "ui", "capabilities", "i18n", "daemon", "install", "uninstall", "entry", "portal", "icon", "reproducible", "root", "login_style",
+    "metadata", "maintainer", "os_min_ver", "arches", "backend", "ui", "capabilities", "i18n", "daemon", "identity_gateway", "compose", "install", "uninstall", "entry", "portal", "icon", "reproducible", "root", "login_style",
 ]);
 const I18N_FIELDS = new Set(["messages", "glossary", "info"]);
 const PACKAGE_ID = /^[A-Za-z][A-Za-z0-9]{1,63}$/;
@@ -83,7 +85,7 @@ export function loadStandaloneManifest(root) {
         return { ok: false, errors: [{ code: "STANDALONE_MANIFEST_YAML", message: String(error) }] };
     }
     const c = new Collector(root);
-    if (existsSync(join(root, "compose.yaml")))
+    if (existsSync(join(root, "compose.yaml")) && !(isRecord(raw) && isRecord(raw.compose) && raw.compose.file === "compose.yaml"))
         c.fail("PROJECT_RUNTIME_EXCLUSIVE", "compose.yaml and dsm-package.yaml are mutually exclusive; keep only one.");
     if (!isRecord(raw)) {
         c.fail("STANDALONE_MANIFEST_YAML", `${STANDALONE_MANIFEST} must be a YAML object.`);
@@ -170,6 +172,12 @@ function readManifest(raw, c) {
         }
     }
     const daemon = arches && readDaemon(raw.daemon, c.root, arches, e => c.fail(e.code, e.message));
+    const compose = arches && readComposeApp(raw.compose, c.root, arches, e => c.fail(e.code, e.message));
+    if (raw.compose !== undefined && (raw.daemon !== undefined || raw.identity_gateway === undefined || Object.keys(capabilities).length || !osMinVer || !isDsmAtLeast(osMinVer, "7.2.1-69057")))
+        c.fail("STANDALONE_IDENTITY_GATEWAY_INVALID", "compose requires identity_gateway, DSM >= 7.2.1, no daemon and no capabilities.");
+    const identityGateway = readIdentityGateway(raw.identity_gateway, daemon || (compose ? { targets: compose.targets } : undefined), e => c.fail(e.code, e.message));
+    if (compose && identityGateway && (!Object.values(compose.services).some(s => s.port === identityGateway.upstream) || Object.values(compose.services).some(s => Object.values(identityGateway.listen).includes(s.port) || s.port === identityGateway.oidc?.issuer_port)))
+        c.fail("STANDALONE_IDENTITY_GATEWAY_INVALID", "compose service ports must contain upstream and not overlap gateway or issuer ports.");
     if (capabilities.jobs && raw.daemon !== undefined && capabilities.delegate?.lifetime !== 'until-revoked') {
         c.fail("CAPABILITY_COMBINATION_INVALID", "daemon can only coexist with an explicit until-revoked delegate fixed worker; plain capabilities.jobs stays mutually exclusive.");
     }
@@ -261,6 +269,8 @@ function readManifest(raw, c) {
         ...(rootOps ? { rootOps } : {}),
         ...(rootPrograms ? { rootPrograms } : {}),
         ...(daemon ? { daemon } : {}),
+        ...(identityGateway ? { identityGateway } : {}),
+        ...(compose ? { compose } : {}),
         ...(uninstall ? { uninstall } : {}),
         ...(sharedFolder ? { sharedFolder } : {}),
         ...(entry ? { entry } : {}),

package/dist/standalone/resource.d.ts

@@ -1,3 +1,4 @@
+import type { ComposeApp } from "./compose.js";
 import type { Capabilities } from "./manifest.js";
 import { type SharedFolder } from "./shared-folder.js";
 import { type PortalPackage } from "../portal/package.js";
@@ -9,5 +10,6 @@ import { type PortalPackage } from "../portal/package.js";
 export declare function renderStandaloneResource(m: {
     package: string;
     capabilities: Capabilities;
+    compose?: ComposeApp;
     sharedFolder?: SharedFolder;
 }, portal?: PortalPackage): string | undefined;

package/dist/standalone/resource.js

@@ -1,3 +1,4 @@
+import { renderDockerProjectResource } from "../build-spk/resource-worker.js";
 import { sharedFolderResource } from "./shared-folder.js";
 import { portalResource } from "../portal/package.js";
 /**
@@ -8,6 +9,7 @@ import { portalResource } from "../portal/package.js";
 export function renderStandaloneResource(m, portal) {
     const dataShare = m.sharedFolder && sharedFolderResource(m.package, m.sharedFolder);
     const resource = {
+        ...(m.compose ? renderDockerProjectResource(m.package, "compose", false) : {}),
         ...(dataShare ? { "data-share": dataShare } : {}),
         ...(m.capabilities.jobs ? { "systemd-user-unit": {} } : {}),
         ...(portal ? portalResource() : {}),

package/dist/standalone/spk.d.ts

@@ -15,6 +15,8 @@ export interface AssembleOptions {
     outputPath: string;
     executor?: ExecutorArtifact;
     daemonControl?: 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. */
     backgroundWorker?: string;
     /** A Python, Node or Rust App's finished directory, installed as target/app. */

package/dist/standalone/spk.js

@@ -22,7 +22,9 @@ import { copyStandaloneNotices } from "../build-spk/notices.js";
 import { copyAppTree } from "./bridge-app.js";
 import { isBridgeBackend } from "./bridge-backend.js";
 import { hostScriptName, renderHostAdapterScript } from "./host-adapter.js";
+import { composeSource } from "./compose.js";
 import { copyDaemonPayload } from "./daemon.js";
+import { GATEWAY_CGI_PATH, GATEWAY_CONFIG_PATH, GATEWAY_EXEC, identityGatewayConfig } 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";
@@ -79,11 +81,22 @@ export async function assembleStandaloneSpk(options) {
         mkdirSync(dirname(cgiTarget), { recursive: true });
         copyFileSync(options.cgiPath, cgiTarget);
         chmodSync(cgiTarget, EXEC_MODE);
-        if (manifest.daemon) {
+        if (manifest.daemon || manifest.compose) {
             if (!options.daemonControl)
                 throw new StandaloneBuildError("STANDALONE_DAEMON_ARTIFACT_REQUIRED", "daemon controller artifact required.");
             copyDaemonPayload(manifest, options.arch, join(staging, "package", "daemon"), options.daemonControl);
         }
+        if (manifest.identityGateway) {
+            if (!options.identityGateway)
+                throw new StandaloneBuildError("STANDALONE_IDENTITY_GATEWAY_ARTIFACT_REQUIRED", "identity gateway artifact required.");
+            for (const path of [GATEWAY_CGI_PATH, `daemon/payload/${GATEWAY_EXEC}`]) {
+                const target = join(staging, "package", path);
+                mkdirSync(dirname(target), { recursive: true });
+                copyFileSync(options.identityGateway, target);
+                chmodSync(target, EXEC_MODE);
+            }
+            writeFile(join(staging, "package", GATEWAY_CONFIG_PATH), identityGatewayConfig(manifest));
+        }
         if (manifest.capabilities.jobs) {
             if (!options.backgroundWorker)
                 throw new StandaloneBuildError("STANDALONE_BACKGROUND_ARTIFACT_REQUIRED", "background worker artifact required.");
@@ -127,11 +140,13 @@ export async function assembleStandaloneSpk(options) {
         const hook = manifest.uninstall && uninstallExecProblem(join(staging, "package"), manifest.uninstall.purge);
         if (hook)
             throw new StandaloneBuildError(hook.code, hook.message);
+        if (manifest.compose)
+            writeFile(join(staging, "package/compose/docker-compose.yml"), composeSource(manifest.compose));
         const packageTgz = join(staging, "package.tgz");
         await createReproducibleTar(join(staging, "package"), packageTgz, { gzip: true });
         rmSync(join(staging, "package"), { recursive: true, force: true });
         const checksum = createHash("md5").update(readFileSync(packageTgz)).digest("hex");
-        writeFile(join(staging, "sdk-package.json"), JSON.stringify({ schema: 2, backend: manifest.backend.kind, capabilities: Object.keys(manifest.capabilities).sort(), ...(manifest.entry ? { entry: manifest.entry } : {}), ...(manifest.uninstall ? { uninstall: uninstallRecord(manifest.uninstall, manifest.i18n?.catalogs) } : {}) }));
+        writeFile(join(staging, "sdk-package.json"), JSON.stringify({ schema: 2, backend: manifest.backend.kind, capabilities: Object.keys(manifest.capabilities).sort(), ...(manifest.compose ? { compose: { services: manifest.compose.services } } : {}), ...(manifest.entry ? { entry: manifest.entry } : {}), ...(manifest.uninstall ? { uninstall: uninstallRecord(manifest.uninstall, manifest.i18n?.catalogs) } : {}) }));
         writeFile(join(staging, "INFO"), renderInfo(manifest, options.arch, checksum, options.executor?.executorDigest));
         mkdirSync(join(staging, "conf"));
         writeFile(join(staging, "conf", "privilege"), renderNativePrivilege());
@@ -203,12 +218,14 @@ function renderInfo(manifest, arch, checksum, executorDigest) {
     // Package Center writes INFO as root; root tasks accept only this executor.
     if (executorDigest)
         fields.push([EXECUTOR_ANCHOR, executorDigest]);
+    if (manifest.compose)
+        fields.push(["install_dep_packages", "ContainerManager"]);
     const backend = manifest.backend;
     if (isBridgeBackend(backend) && backend.node)
         fields.push(["install_dep_packages", backend.node.package]);
     fields.push(...metadataInfoFields(manifest.metadata));
     // Background packages need prestart: it runs before DSM's systemd-user-unit acquire.
-    if (manifest.daemon || manifest.capabilities.jobs)
+    if (manifest.daemon || manifest.compose || manifest.capabilities.jobs)
         fields.push(["precheckstartstop", "yes"]);
     for (const locale of LOCALES) {
         const text = manifest.i18n?.info[locale];

package/dist/validate.js

@@ -21,7 +21,7 @@ export function validateProject(project, options = {}) {
     const standalonePath = join(project.root, DSM_PACKAGE_FILENAME);
     const hasCompose = existsSync(project.composePath);
     const hasStandalone = existsSync(standalonePath);
-    if (hasCompose && hasStandalone) {
+    if (hasCompose && hasStandalone && isNativeLayout(project.root)) {
         return { ok: false, errors: [{
                     code: "PROJECT_RUNTIME_EXCLUSIVE",
                     span: { file: DSM_PACKAGE_FILENAME, line: 1, column: 1 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {
@@ -25,7 +25,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@synopackageland/templates": "0.12.2",
+    "@synopackageland/templates": "0.13.0",
     "ajv": "^8.17.1",
     "commander": "^13.1.0",
     "tar": "^7.4.3",

package/skills/SKILL.md

@@ -7,7 +7,7 @@ description: Initialize, extend, check, build, inspect, and deploy Synology appl
 
 Use this guide to initialize, build and inspect own applications or upstream OSS as independent packages. 依已實作能力區分 DSM session 檔案、私有 jobs 與 App 登入；delegate 已實作並隨 CLI 提供固定操作的離線委託（預設 `files.moveFromStaging`）；共用 delegate／rootOps executor 的完整裝置生命週期驗收仍待完成，不得宣稱已通過；支援邊界依 delegate guide／support matrix，禁止發明新的身分平台。
 
-Start with `synopkgland init -t native-go`, `synopkgland init -t binary`, or `synopkgland init -t compose`. Read reference/create.md or reference/wrap.md, then reference/deploy.md. Native CGI session checks belong to the package. Container authentication belongs to upstream; fixed service credentials govern mounted data access.
+Start with `synopkgland init -t native-go`, `synopkgland init -t binary`, or `synopkgland init -t compose`. Read reference/create.md or reference/wrap.md, then reference/deploy.md. Native CGI session checks belong to the package. For wrapping upstream OSS with DSM accounts, read [reference/identity-gateway.md](reference/identity-gateway.md) first. It covers native and host-network Compose upstreams, mode selection, isolation, account deletion and verification. Fixed package credentials govern container data access.
 
 Never install, uninstall, publish or modify NAS data without task authorization. Prefer check, inspect and deploy --dry-run for reviewable artifacts.
 

package/skills/reference/create.md

@@ -39,8 +39,8 @@ rootOps 與 delegate 已共用管理員 PasswordConfirm 核准的 protected exec
 backend 寫 `runtime: python|node|rust`（`runtime: go` 等同 `kind: go`）。CGI 是 SDK 的 Go runtime（`bridge/cmd/runtime`），它驗證 DSM session、entry 與 `permissions.json` 後，以套件帳號（不是 root）每個請求啟動一次 App。App 放在 ui 以外的目錄，打包成 `target/app/`，build 寫入 `bridge.json`（spec/bridge/v1）並把它與 `permissions.json` 的 sha256 編進 runtime。
 
 ```yaml
-backend: {runtime: python, dir: app, entry: main.py, sdk: X.Y.Z}
-backend: {runtime: node, dir: app, entry: main.mjs, sdk: X.Y.Z, node: {package: Node.js_v20}}
+backend: {runtime: python, dir: app, entry: main.py, sdk: 0.13.0}
+backend: {runtime: node, dir: app, entry: main.mjs, sdk: 0.13.0, node: {package: Node.js_v20}}
 backend: {runtime: rust, dir: app, entry: hello, methods: [hello.greet]}
 ```