@synopackageland/cli 0.3.1 → 0.3.3

package/dist/attestation/app-package.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { SignJWT, exportJWK, generateKeyPair, importJWK } from "jose";
+import { CURATED_BUILD_OFFSET } from "@synopackageland/package-source/index-manifest";
 export const PLATFORM_ATTESTATION_ISSUER = "synopkgland-curated";
 export const APP_PACKAGE_ATTESTATION_TYP = "app-package-attestation";
 export const APP_PACKAGE_ATTESTATION_VERSION = 2;
@@ -141,8 +142,14 @@ export function assertPackageVersionBinding(packageVersion, packageBuild) {
     if (typeof packageVersion !== "string" || packageVersion.length === 0) {
         throw new Error("packageVersion must be a non-empty string");
     }
+    if (!Number.isSafeInteger(packageBuild) ||
+        packageBuild < 1 ||
+        packageBuild >= CURATED_BUILD_OFFSET) {
+        throw new Error("packageBuild must be a positive safe integer below the Curated offset");
+    }
     const match = /-(\d+)$/.exec(packageVersion);
-    if (!match || Number(match[1]) !== packageBuild) {
+    const parsed = match ? Number(match[1]) : NaN;
+    if (parsed !== packageBuild && parsed !== packageBuild + CURATED_BUILD_OFFSET) {
         throw new Error("packageVersion and packageBuild must agree");
     }
 }

package/dist/attestation/platform-service.d.ts

@@ -0,0 +1,70 @@
+import { type JWK } from "jose";
+import type { AppPackageSigningKey } from "./app-package.js";
+/**
+ * Trust contract for releasing the platform service (the Broker SPK) itself.
+ * This is deliberately a separate issuer, typ and keyring from the curated App
+ * chain: the Broker carries the curated trust root as *data*, so that root can
+ * never double as the authority that signs the Broker's own releases.
+ */
+export declare const PLATFORM_ATTESTATION_ISSUER = "synopkgland-platform";
+export declare const PLATFORM_SERVICE_RELEASE_ATTESTATION_TYP = "platform-service-release-attestation";
+export declare const PLATFORM_SERVICE_RELEASE_ATTESTATION_VERSION: 1;
+export declare const PLATFORM_SERVICE_PACKAGE_IDENTITY = "SynoPkgLandService";
+export declare const PLATFORM_KEYRING_PURPOSE = "platform-service-release";
+export declare const PLATFORM_ATTESTATION_PRIVATE_JWK_ENV = "SYNOPKGLAND_PLATFORM_ATTESTATION_PRIVATE_JWK";
+export declare const PLATFORM_ATTESTATION_KID_ENV = "SYNOPKGLAND_PLATFORM_ATTESTATION_KID";
+export declare const PLATFORM_ATTESTATION_KEYRING_PATH_ENV = "SYNOPKGLAND_PLATFORM_ATTESTATION_KEYRING_PATH";
+export type PlatformServiceReleaseErrorCode = "PLATFORM_KEYRING_INVALID" | "PLATFORM_KEYRING_PURPOSE_MISMATCH" | "PLATFORM_KEYRING_PRIVATE_MATERIAL" | "PLATFORM_KEYRING_NO_ACTIVE_KEY" | "PLATFORM_SIGNING_MATERIAL_MISSING" | "PLATFORM_SIGNING_MATERIAL_INVALID" | "PLATFORM_SIGNING_KEY_UNKNOWN" | "PLATFORM_ATTESTATION_INPUT_INVALID" | "PLATFORM_ATTESTATION_INVALID";
+export declare class PlatformServiceReleaseError extends Error {
+    readonly code: PlatformServiceReleaseErrorCode;
+    constructor(code: PlatformServiceReleaseErrorCode, detail?: string);
+}
+export interface PlatformServiceReleaseAttestationInput {
+    packageIdentity: string;
+    /** Source version without any Build suffix; the constants file keeps it. */
+    sourceVersion: string;
+    packageBuild: number;
+    /** `${sourceVersion}-<zero-padded Build>`; must agree with packageBuild. */
+    packageVersion: string;
+    /** SHA-256 of the final SPK bytes. */
+    artifactDigest: string;
+    /** Git commit the trusted workflow checked out and built. */
+    sourceRevision: string;
+    osMinVer: string;
+    arch: "noarch";
+}
+export interface PlatformServiceReleaseAttestationClaims extends PlatformServiceReleaseAttestationInput {
+    typ: typeof PLATFORM_SERVICE_RELEASE_ATTESTATION_TYP;
+    version: typeof PLATFORM_SERVICE_RELEASE_ATTESTATION_VERSION;
+    issuedAt: string;
+}
+export type PlatformKeyStatus = "active" | "verify-only" | "revoked";
+export interface PlatformKeyringDocument {
+    version: 1;
+    purpose: typeof PLATFORM_KEYRING_PURPOSE;
+    keys: Array<{
+        kid: string;
+        status: PlatformKeyStatus;
+        publicJwk: JWK;
+    }>;
+}
+export interface PlatformAttestationSigner {
+    sign(input: PlatformServiceReleaseAttestationInput): Promise<{
+        token: string;
+        attestationDigest: string;
+        claims: PlatformServiceReleaseAttestationClaims;
+    }>;
+    verify(token: string): Promise<PlatformServiceReleaseAttestationClaims>;
+    verificationJwk: JWK;
+}
+export declare function parsePlatformKeyringDocument(raw: unknown): PlatformKeyringDocument;
+export declare function readPlatformKeyringFile(path: string): PlatformKeyringDocument;
+export declare function canonicalPlatformServiceReleaseClaims(claims: PlatformServiceReleaseAttestationClaims): string;
+export declare function digestPlatformServiceReleaseClaims(claims: PlatformServiceReleaseAttestationClaims): string;
+export declare function signPlatformServiceReleaseAttestationToken(input: PlatformServiceReleaseAttestationInput, key: AppPackageSigningKey): Promise<{
+    token: string;
+    attestationDigest: string;
+    claims: PlatformServiceReleaseAttestationClaims;
+}>;
+export declare function verifyPlatformServiceReleaseAttestationToken(token: string, keyring: PlatformKeyringDocument): Promise<PlatformServiceReleaseAttestationClaims>;
+export declare function createPlatformAttestationSignerFromEnv(env?: NodeJS.Dict<string>): Promise<PlatformAttestationSigner>;

package/dist/attestation/platform-service.js

@@ -0,0 +1,250 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { SignJWT, importJWK, jwtVerify } from "jose";
+/**
+ * Trust contract for releasing the platform service (the Broker SPK) itself.
+ * This is deliberately a separate issuer, typ and keyring from the curated App
+ * chain: the Broker carries the curated trust root as *data*, so that root can
+ * never double as the authority that signs the Broker's own releases.
+ */
+export const PLATFORM_ATTESTATION_ISSUER = "synopkgland-platform";
+export const PLATFORM_SERVICE_RELEASE_ATTESTATION_TYP = "platform-service-release-attestation";
+export const PLATFORM_SERVICE_RELEASE_ATTESTATION_VERSION = 1;
+export const PLATFORM_SERVICE_PACKAGE_IDENTITY = "SynoPkgLandService";
+export const PLATFORM_KEYRING_PURPOSE = "platform-service-release";
+export const PLATFORM_ATTESTATION_PRIVATE_JWK_ENV = "SYNOPKGLAND_PLATFORM_ATTESTATION_PRIVATE_JWK";
+export const PLATFORM_ATTESTATION_KID_ENV = "SYNOPKGLAND_PLATFORM_ATTESTATION_KID";
+export const PLATFORM_ATTESTATION_KEYRING_PATH_ENV = "SYNOPKGLAND_PLATFORM_ATTESTATION_KEYRING_PATH";
+export class PlatformServiceReleaseError extends Error {
+    code;
+    constructor(code, detail) {
+        super(detail ? `${code}: ${detail}` : code);
+        this.code = code;
+        this.name = "PlatformServiceReleaseError";
+    }
+}
+const PRIVATE_JWK_FIELDS = ["d", "p", "q", "dp", "dq", "qi", "oth", "k"];
+const KEY_STATUSES = new Set(["active", "verify-only", "revoked"]);
+export function parsePlatformKeyringDocument(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new PlatformServiceReleaseError("PLATFORM_KEYRING_INVALID", "not an object");
+    }
+    const document = raw;
+    if (document.version !== 1 || !Array.isArray(document.keys)) {
+        throw new PlatformServiceReleaseError("PLATFORM_KEYRING_INVALID", "unsupported document shape");
+    }
+    if (document.purpose !== PLATFORM_KEYRING_PURPOSE) {
+        // A curated keyring document has no purpose field at all; refusing here is
+        // what keeps the Broker's bundled trust root from signing the Broker.
+        throw new PlatformServiceReleaseError("PLATFORM_KEYRING_PURPOSE_MISMATCH");
+    }
+    for (const entry of document.keys) {
+        if (!entry ||
+            typeof entry.kid !== "string" ||
+            entry.kid.length === 0 ||
+            !KEY_STATUSES.has(entry.status) ||
+            !entry.publicJwk ||
+            typeof entry.publicJwk !== "object") {
+            throw new PlatformServiceReleaseError("PLATFORM_KEYRING_INVALID", "invalid key entry");
+        }
+        if (PRIVATE_JWK_FIELDS.some((field) => field in entry.publicJwk)) {
+            throw new PlatformServiceReleaseError("PLATFORM_KEYRING_PRIVATE_MATERIAL");
+        }
+        if (entry.publicJwk.kty !== "RSA" || typeof entry.publicJwk.n !== "string") {
+            throw new PlatformServiceReleaseError("PLATFORM_KEYRING_INVALID", "not a public RSA key");
+        }
+    }
+    if (!document.keys.some((entry) => entry.status === "active")) {
+        throw new PlatformServiceReleaseError("PLATFORM_KEYRING_NO_ACTIVE_KEY");
+    }
+    return document;
+}
+export function readPlatformKeyringFile(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        throw new PlatformServiceReleaseError("PLATFORM_KEYRING_INVALID", `unable to read keyring: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new PlatformServiceReleaseError("PLATFORM_KEYRING_INVALID", "keyring is not valid JSON");
+    }
+    return parsePlatformKeyringDocument(parsed);
+}
+export function canonicalPlatformServiceReleaseClaims(claims) {
+    return JSON.stringify({
+        arch: claims.arch,
+        artifactDigest: claims.artifactDigest,
+        issuedAt: claims.issuedAt,
+        osMinVer: claims.osMinVer,
+        packageBuild: claims.packageBuild,
+        packageIdentity: claims.packageIdentity,
+        packageVersion: claims.packageVersion,
+        sourceRevision: claims.sourceRevision,
+        sourceVersion: claims.sourceVersion,
+        typ: claims.typ,
+        version: claims.version,
+    });
+}
+export function digestPlatformServiceReleaseClaims(claims) {
+    return createHash("sha256").update(canonicalPlatformServiceReleaseClaims(claims)).digest("hex");
+}
+export async function signPlatformServiceReleaseAttestationToken(input, key) {
+    assertPlatformInput(input);
+    if (typeof key.kid !== "string" || key.kid.length === 0) {
+        throw new PlatformServiceReleaseError("PLATFORM_SIGNING_MATERIAL_INVALID", "kid required");
+    }
+    const claims = {
+        typ: PLATFORM_SERVICE_RELEASE_ATTESTATION_TYP,
+        version: PLATFORM_SERVICE_RELEASE_ATTESTATION_VERSION,
+        packageIdentity: input.packageIdentity,
+        sourceVersion: input.sourceVersion,
+        packageBuild: input.packageBuild,
+        packageVersion: input.packageVersion,
+        artifactDigest: input.artifactDigest,
+        sourceRevision: input.sourceRevision,
+        osMinVer: input.osMinVer,
+        arch: input.arch,
+        issuedAt: new Date().toISOString(),
+    };
+    const attestationDigest = digestPlatformServiceReleaseClaims(claims);
+    const token = await new SignJWT({ ...claims })
+        .setProtectedHeader({ alg: "RS256", kid: key.kid, typ: "JWT" })
+        .setIssuer(PLATFORM_ATTESTATION_ISSUER)
+        .setSubject(claims.packageIdentity)
+        .setJti(attestationDigest)
+        .sign(key.privateKey);
+    return { token, attestationDigest, claims };
+}
+export async function verifyPlatformServiceReleaseAttestationToken(token, keyring) {
+    parsePlatformKeyringDocument(keyring);
+    try {
+        const header = decodeHeader(token);
+        const entry = keyring.keys.find((candidate) => candidate.kid === header.kid && candidate.status !== "revoked");
+        if (!entry) {
+            throw new Error("unknown or revoked kid");
+        }
+        const publicKey = (await importJWK(entry.publicJwk, "RS256"));
+        const result = await jwtVerify(token, publicKey, {
+            algorithms: ["RS256"],
+            issuer: PLATFORM_ATTESTATION_ISSUER,
+        });
+        if (result.protectedHeader.alg !== "RS256" ||
+            result.protectedHeader.typ !== "JWT" ||
+            result.protectedHeader.kid !== entry.kid) {
+            throw new Error("token header mismatch");
+        }
+        const payload = result.payload;
+        if (payload.typ !== PLATFORM_SERVICE_RELEASE_ATTESTATION_TYP ||
+            payload.version !== PLATFORM_SERVICE_RELEASE_ATTESTATION_VERSION) {
+            throw new Error("token typ mismatch");
+        }
+        const claims = {
+            typ: payload.typ,
+            version: payload.version,
+            packageIdentity: payload.packageIdentity,
+            sourceVersion: payload.sourceVersion,
+            packageBuild: payload.packageBuild,
+            packageVersion: payload.packageVersion,
+            artifactDigest: payload.artifactDigest,
+            sourceRevision: payload.sourceRevision,
+            osMinVer: payload.osMinVer,
+            arch: payload.arch,
+            issuedAt: payload.issuedAt,
+        };
+        assertPlatformInput(claims);
+        if (typeof claims.issuedAt !== "string" || Number.isNaN(Date.parse(claims.issuedAt))) {
+            throw new Error("issuedAt is not a timestamp");
+        }
+        if (result.payload.jti !== digestPlatformServiceReleaseClaims(claims)) {
+            throw new Error("jti does not bind the claims");
+        }
+        return claims;
+    }
+    catch (error) {
+        if (error instanceof PlatformServiceReleaseError) {
+            throw new PlatformServiceReleaseError("PLATFORM_ATTESTATION_INVALID", error.message);
+        }
+        throw new PlatformServiceReleaseError("PLATFORM_ATTESTATION_INVALID", error instanceof Error ? error.message : String(error));
+    }
+}
+export async function createPlatformAttestationSignerFromEnv(env = process.env) {
+    const jwkRaw = env[PLATFORM_ATTESTATION_PRIVATE_JWK_ENV]?.trim();
+    const kidFromEnv = env[PLATFORM_ATTESTATION_KID_ENV]?.trim();
+    const keyringPath = env[PLATFORM_ATTESTATION_KEYRING_PATH_ENV]?.trim();
+    if (!jwkRaw) {
+        throw new PlatformServiceReleaseError("PLATFORM_SIGNING_MATERIAL_MISSING");
+    }
+    if (!keyringPath) {
+        throw new PlatformServiceReleaseError("PLATFORM_KEYRING_INVALID", `${PLATFORM_ATTESTATION_KEYRING_PATH_ENV} is required`);
+    }
+    const keyring = readPlatformKeyringFile(keyringPath);
+    let privateJwk;
+    let privateKey;
+    try {
+        privateJwk = JSON.parse(jwkRaw);
+        privateKey = (await importJWK(privateJwk, "RS256"));
+    }
+    catch {
+        throw new PlatformServiceReleaseError("PLATFORM_SIGNING_MATERIAL_INVALID");
+    }
+    const kid = kidFromEnv || (typeof privateJwk.kid === "string" ? privateJwk.kid : "");
+    if (!kid) {
+        throw new PlatformServiceReleaseError("PLATFORM_SIGNING_MATERIAL_INVALID", "kid required");
+    }
+    const trustEntry = keyring.keys.find((entry) => entry.kid === kid && entry.status === "active");
+    if (!trustEntry) {
+        throw new PlatformServiceReleaseError("PLATFORM_SIGNING_KEY_UNKNOWN");
+    }
+    const signingKey = { kid, privateKey };
+    return {
+        sign: (input) => signPlatformServiceReleaseAttestationToken(input, signingKey),
+        verify: (token) => verifyPlatformServiceReleaseAttestationToken(token, keyring),
+        verificationJwk: trustEntry.publicJwk,
+    };
+}
+function assertPlatformInput(input) {
+    const fail = (detail) => {
+        throw new PlatformServiceReleaseError("PLATFORM_ATTESTATION_INPUT_INVALID", detail);
+    };
+    if (input.packageIdentity !== PLATFORM_SERVICE_PACKAGE_IDENTITY) {
+        fail("packageIdentity must be the platform service identity");
+    }
+    if (!/^\d+\.\d+\.\d+$/.test(input.sourceVersion)) {
+        fail("sourceVersion must be plain semver without a Build suffix");
+    }
+    if (!Number.isSafeInteger(input.packageBuild) || input.packageBuild < 1) {
+        fail("packageBuild must be a positive safe integer");
+    }
+    if (input.packageVersion !== `${input.sourceVersion}-${String(input.packageBuild).padStart(4, "0")}`) {
+        fail("packageVersion must be sourceVersion plus the zero-padded Build");
+    }
+    if (!/^[a-f0-9]{64}$/.test(input.artifactDigest)) {
+        fail("artifactDigest must be a lowercase SHA-256 digest");
+    }
+    if (!/^[a-f0-9]{40}$/.test(input.sourceRevision)) {
+        fail("sourceRevision must be a full git commit SHA");
+    }
+    if (!/^\d+\.\d+-\d+$/.test(input.osMinVer)) {
+        fail("osMinVer must look like 7.2-69057");
+    }
+    if (input.arch !== "noarch") {
+        fail("the platform service is noarch");
+    }
+}
+function decodeHeader(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3 || parts.some((part) => part.length === 0)) {
+        throw new Error("not a compact JWT");
+    }
+    const header = JSON.parse(Buffer.from(parts[0], "base64url").toString("utf8"));
+    if (!header || typeof header !== "object" || Array.isArray(header)) {
+        throw new Error("invalid JWT header");
+    }
+    return header;
+}

package/dist/build-spk/generator.js

@@ -5,7 +5,7 @@ import { createHash } from "node:crypto";
 import * as tar from "tar";
 import { loadContract, collectInstallParameters } from "../contract/load.js";
 import { renderDsmWindowConfig, resolvedWebLaunch, trustedAppEntryPath, } from "../contract/web-launch.js";
-import { loadCompose } from "../compose/analyze.js";
+import { classifyComposeRoute, loadCompose } from "../compose/analyze.js";
 import { scanComposePrivilege } from "../compose/privilege.js";
 import { validateProject } from "../validate.js";
 import { writeDsmWindowIcons, writePackageCenterIcons } from "./dsm-icons.js";
@@ -16,6 +16,7 @@ import { BROKER_INSTALLER_VARS, BROKER_SOCKET_REQUIRED_SCRIPT, renderBrokerStatu
 import { loadNative } from "../native/load.js";
 import { materializeNativePayload } from "./native-payload.js";
 import { renderNativePrivilege, renderNativeStartStopStatus, renderNativePostuninst, } from "./native-lifecycle.js";
+import { renderResourceConfig, renderResourceWorkerStartStopStatus } from "./resource-worker.js";
 const FILE_MODE = 0o644;
 const SCRIPT_MODE = 0o755;
 const INSTALL_UIFILE = "install_uifile";
@@ -129,30 +130,54 @@ export async function buildSpk(options) {
             rmSync(staging, { recursive: true, force: true });
         }
     }
+    const parsedCompose = loadCompose(options.project.composePath);
+    const route = parsedCompose?.compose
+        ? classifyComposeRoute(contract, parsedCompose)
+        : undefined;
+    if (route && route.errors.length > 0) {
+        return { ok: false, errors: route.errors.map((error) => error.code) };
+    }
+    const rwEligibility = route?.eligibility;
+    const isDynamicRoute = route?.route === "dynamic";
+    const isResourceWorkerRoute = route?.route === "static-zero-config" ||
+        isDynamicRoute;
     const staging = mkdtempSync(join(tmpdir(), "syno-spk-"));
     try {
-        writeFileSync(join(staging, "INFO"), renderInfo(contract, options.archFamily), "utf8");
+        writeFileSync(join(staging, "INFO"), renderInfo(contract, options.archFamily, isResourceWorkerRoute), "utf8");
         writePackageCenterIcons(staging);
         mkdirSync(join(staging, "conf"), { recursive: true });
         writeFileSync(join(staging, "conf", "privilege"), renderPrivilege(), "utf8");
         writeFileSync(join(staging, "privilege"), renderPrivilege(), "utf8");
+        if (isResourceWorkerRoute) {
+            const resourceConfig = renderResourceConfig(contract, rwEligibility);
+            writeFileSync(join(staging, "conf", "resource"), resourceConfig, "utf8");
+            chmodSync(join(staging, "conf", "resource"), FILE_MODE);
+        }
         mkdirSync(join(staging, "WIZARD_UIFILES"), { recursive: true });
-        const parsedCompose = loadCompose(options.project.composePath);
         writeFileSync(join(staging, "WIZARD_UIFILES", INSTALL_UIFILE), JSON.stringify(renderInstallWizard(contract, parsedCompose?.compose), null, 2), "utf8");
         writeFileSync(join(staging, "WIZARD_UIFILES", UPGRADE_UIFILE), JSON.stringify(renderUpgradeWizard(contract, parsedCompose?.compose), null, 2), "utf8");
         writeFileSync(join(staging, "WIZARD_UIFILES", UNINSTALL_UIFILE), JSON.stringify(renderUninstallWizard(), null, 2), "utf8");
         mkdirSync(join(staging, "scripts"), { recursive: true });
         for (const name of SCRIPT_NAMES) {
             const scriptPath = join(staging, "scripts", name);
-            writeFileSync(scriptPath, renderManagedScript(name, contract), "utf8");
+            writeFileSync(scriptPath, renderManagedScript(name, contract, undefined, isResourceWorkerRoute, rwEligibility?.adminport, isDynamicRoute), "utf8");
             chmodSync(scriptPath, SCRIPT_MODE);
         }
         mkdirSync(join(staging, "package"), { recursive: true });
         copyFileSync(options.project.composePath, join(staging, "package", "compose.yaml"));
         copyFileSync(options.project.contractPath, join(staging, "package", "synology-app.yaml"));
+        if (isResourceWorkerRoute) {
+            const resourceProjectDir = join(staging, "package", "compose");
+            mkdirSync(resourceProjectDir, { recursive: true });
+            copyFileSync(options.project.composePath, join(resourceProjectDir, "docker-compose.yml"));
+            chmodSync(join(resourceProjectDir, "docker-compose.yml"), FILE_MODE);
+        }
         const htmlDir = join(options.project.root, "html");
         if (existsSync(htmlDir)) {
             cpSync(htmlDir, join(staging, "package", "html"), { recursive: true });
+            if (isResourceWorkerRoute) {
+                cpSync(htmlDir, join(staging, "package", "compose", "html"), { recursive: true });
+            }
         }
         if (options.embeddedAttestationToken !== undefined) {
             const attestationPath = join(staging, "package", EMBEDDED_ATTESTATION_RELATIVE_PATH);
@@ -190,7 +215,7 @@ function quoteInfo(value) {
 function spkVersion(version) {
     return /-\d+$/.test(version) ? version : `${version}-0001`;
 }
-function renderInfo(contract, archFamily) {
+function renderInfo(contract, archFamily, isResourceWorker = false) {
     const lines = [];
     const add = (key, value) => {
         lines.push(`${key}=${quoteInfo(String(value))}`);
@@ -202,10 +227,22 @@ function renderInfo(contract, archFamily) {
     add("maintainer", String(contract.maintainer));
     add("arch", archFamily === undefined ? "noarch" : infoArchValue(archFamily));
     add("os_min_ver", String(contract.os_min_ver));
-    // synopkg's Container Manager dep gate reports "not ready" even when CM is
-    // running. Depend on Broker only; Broker's adapter.probe() checks CM at
-    // App install time (CM_CAPABILITY_MISSING).
-    add("install_dep_packages", "SynoPkgLandService>=0.1.0-0016");
+    if (isResourceWorker) {
+        // DSM reports Container Manager as "not ready" through the package
+        // dependency gate even while pkgctl-ContainerManager is running. The
+        // docker-project worker itself remains the authoritative live prerequisite
+        // (ContainerManager >= 1432); keep only the reliable Web Station package
+        // dependency here so a valid resource-worker SPK can reach acquisition.
+        if (contract.adminport !== undefined) {
+            add("install_dep_packages", "WebStation");
+        }
+    }
+    else {
+        // synopkg's Container Manager dep gate reports "not ready" even when CM is
+        // running. Depend on Broker only; Broker's adapter.probe() checks CM at
+        // App install time (CM_CAPABILITY_MISSING).
+        add("install_dep_packages", "SynoPkgLandService>=0.1.0-0016");
+    }
     add("startable", "yes");
     const launch = resolvedWebLaunch(contract);
     if (contract.adminprotocol) {
@@ -243,6 +280,7 @@ function renderPrivilege() {
     }, null, 2)}\n`;
 }
 const SHARED_FOLDER_MOUNT_CONSENT = "此 App 會用你在這台 NAS 選的資料夾；整顆應用都看得到。Shared Folder Mount 是整個 App Instance 的 container access：能打開這個 App 的使用者，容器裡的程式都看得到該 Share，即使該使用者在 File Station 看不到。這不是逐使用者 DSM ACL。要依登入者權限讀寫 NAS 檔案，必須另外核准廣域 files.* 並走 File Gateway。";
+const HOMES_MOUNT_CONSENT = "此 App 會使用這台 NAS 已啟用的 User Home；整顆應用的容器都看得到，容器路徑由 Compose 決定。這不是逐使用者 DSM ACL；要依登入者權限讀寫 NAS 檔案，必須另外核准廣域 files.* 並走 File Gateway。";
 const DSM_USER_RUN_AS_CONSENT = "寫進 Share 的新檔在 File Station 顯示為你選的那位 DSM 使用者。點開此 App 的人共用這個磁碟身分，不是逐登入 ACL。";
 const DSM_USER_UPGRADE_CONSENT = "升級時更換 Container Run-as 不會 chown Share 上的舊檔；只有升級後寫入的新檔才會使用新的磁碟身分。";
 const SHARED_FOLDER_RW_UPGRADE_CONSENT = "此版本把 Share 掛載改為讀寫；容器可讀取並寫入你選的 Share，不再是唯讀。";
@@ -328,6 +366,7 @@ function renderInstallWizard(contract, compose) {
     const items = [];
     const params = collectInstallParameters(contract);
     const hasSharedFolder = params.some((item) => item.param.type === "shared_folder");
+    const hasHomes = params.some((item) => item.param.type === "homes");
     const hasDsmUser = params.some((item) => item.param.type === "dsm_user");
     const capabilityText = renderFilesCapability(contract);
     if (compose && scanComposePrivilege(compose).length > 0) {
@@ -345,6 +384,11 @@ function renderInstallWizard(contract, compose) {
             desc: SHARED_FOLDER_MOUNT_CONSENT,
         });
     }
+    if (hasHomes) {
+        items.push({
+            desc: HOMES_MOUNT_CONSENT,
+        });
+    }
     if (hasDsmUser) {
         items.push({
             desc: DSM_USER_RUN_AS_CONSENT,
@@ -515,7 +559,128 @@ function renderUninstallWizard() {
             ],
         }];
 }
-function renderManagedScript(name, contract, nativeContext) {
+function renderDynamicPreinstMaterializer(contract) {
+    const params = collectInstallParameters(contract).filter(({ param }) => param.type === "string" || param.type === "boolean");
+    const lines = [
+        "#!/bin/sh",
+        "set -eu",
+        "umask 077",
+        "# D3 package-only carrier; values are wizard answers, canonical values, or defaults.",
+        "die() { echo \"dynamic route materialization failed: $1\" >&2; exit 1; }",
+        'T="${SYNOPKG_PKGINST_TEMP_DIR:?}"',
+        'STATUS="${SYNOPKG_PKG_STATUS:?}"',
+        'PROJECT="$T/compose"',
+        'RUNTIME_ENV="$PROJECT/.env"',
+        'CANONICAL_ENV="${SYNOPKG_PKGDEST_VOL:?}/@appdata/${SYNOPKG_PKGNAME:?}/.env"',
+        'PLATFORM_PKGVAR="${SYNOPKG_PKGDEST_VOL:?}/@appdata/${SYNOPKG_PKGNAME:?}"',
+        'PLATFORM_SECRETS="${SYNOPKG_PKGDEST_VOL:?}/@apphome/${SYNOPKG_PKGNAME:?}/secrets"',
+        '[ -d "$PROJECT" ] || die "compose directory is missing"',
+        '[ ! -L "$PROJECT" ] || die "compose directory is a symlink"',
+        '[ "$(stat -c %u "$PROJECT")" = "$(id -u)" ] || die "compose directory owner is not the package user"',
+        '[ ! -L "$RUNTIME_ENV" ] || die "runtime file is a symlink"',
+        'if [ -e "$RUNTIME_ENV" ] && [ ! -f "$RUNTIME_ENV" ]; then die "runtime path is not a regular file"; fi',
+        "read_env_value() {",
+        "  file=\"$1\"",
+        "  key=\"$2\"",
+        "  awk -F= -v key=\"$key\" '$1 == key { value=substr($0, index($0,\"=\")+1); if (value ~ /^\".*\"$/) value=substr(value,2,length(value)-2); print value; found=1; exit } END { if (!found) exit 1 }' \"$file\"",
+        "}",
+        "append_env() {",
+        "  key=\"$1\"",
+        "  value=\"$2\"",
+        "  type=\"${3:-string}\"",
+        "  if printf '%s' \"$value\" | LC_ALL=C grep -q '[[:cntrl:]]'; then",
+        "    die \"control character in environment value $key\"",
+        "  fi",
+        "  case \"$value\" in",
+        "    *[[:cntrl:]]*) die \"control character in environment value $key\" ;;",
+        "  esac",
+        "  if [ \"$type\" = \"boolean\" ]; then",
+        "    normalized=\"$(printf '%s' \"$value\" | LC_ALL=C tr '[:upper:]' '[:lower:]')\"",
+        "    case \"$normalized\" in",
+        "      true|false) value=\"$normalized\" ;;",
+        "      *) die \"invalid boolean value $key\" ;;",
+        "    esac",
+        "  fi",
+        "  case \"$value\" in",
+        "    *[!A-Za-z0-9_./:@-]*)",
+        "      escaped=\"$(printf '%s' \"$value\" | sed 's/\\\\/\\\\\\\\/g; s/\"/\\\\\"/g')\"",
+        "      printf '%s=\"%s\"\\n' \"$key\" \"$escaped\"",
+        "      ;;",
+        "    *) printf '%s=%s\\n' \"$key\" \"$value\" ;;",
+        "  esac",
+        "}",
+        'tmp="$(mktemp "$PROJECT/.env.tmp.XXXXXX")"',
+        'chmod 600 "$tmp"',
+        '[ "$(stat -c %a "$tmp")" = "600" ] || die "temporary env mode is not 0600"',
+        '[ "$(stat -c %u "$tmp")" = "$(id -u)" ] || die "temporary env owner is not the package user"',
+        "trap 'rm -f \"$tmp\"' EXIT HUP INT TERM",
+        "{",
+    ];
+    const valueVars = [];
+    for (const { name, param } of params) {
+        const type = param.type;
+        const valueVar = "D3_VALUE_" + name;
+        valueVars.push({ name, valueVar, type });
+        const fallback = param.default !== undefined
+            ? String(param.default)
+            : type === "boolean"
+                ? "false"
+                : "";
+        lines.push(`  if [ "\${${name}+x}" = x ]; then`, `    ${valueVar}="\${${name}}"`, '  elif [ "$STATUS" = "UPGRADE" ] && [ -f "$CANONICAL_ENV" ] && [ ! -L "$CANONICAL_ENV" ] && ' +
+            `${valueVar}="$(read_env_value "$CANONICAL_ENV" "${name}")"; then`, "    :", "  else", "    " + valueVar + "=" + shellQuote(fallback), "  fi");
+    }
+    lines.push('  append_env "SYNOPKG_PKGVAR" "$PLATFORM_PKGVAR"', '  append_env "SYNO_APP_SECRETS_DIR" "$PLATFORM_SECRETS"');
+    for (const { name, valueVar, type } of valueVars) {
+        lines.push(`  append_env "${name}" "$${valueVar}" "${type}"`);
+    }
+    lines.push("  } > \"$tmp\"", "  mv \"$tmp\" \"$RUNTIME_ENV\"", "  trap - EXIT HUP INT TERM", "  [ ! -L \"$RUNTIME_ENV\" ] || die \"runtime file became a symlink\"", "  [ \"$(stat -c %a \"$RUNTIME_ENV\")\" = \"600\" ] || die \"runtime env mode is not 0600\"", "exit 0");
+    return lines.join("\n") + "\n";
+}
+function renderDynamicCanonicalMirror() {
+    const lines = [
+        "#!/bin/sh",
+        "set -eu",
+        "umask 077",
+        "# D3 post-worker mirror; the runtime .env is the only source of truth here.",
+        "die() { echo \"dynamic route canonical mirror failed: $1\" >&2; exit 1; }",
+        'PKGVAR="${SYNOPKG_PKGVAR:?}"',
+        'PKGHOME="${SYNOPKG_PKGHOME:?}"',
+        'PKGDEST="${SYNOPKG_PKGDEST:?}"',
+        'PROJECT="${PKGDEST}/compose"',
+        'RUNTIME_ENV="${PROJECT}/.env"',
+        'CANONICAL_ENV="${PKGVAR}/.env"',
+        'SECRETS="${PKGHOME}/secrets"',
+        'mkdir -p "$PKGVAR"',
+        '[ -d "$PKGVAR" ] || die "PKGVAR is not a directory"',
+        'if [ -L "$SECRETS" ]; then die "secret root is a symlink"; fi',
+        'mkdir -p "$SECRETS"',
+        '[ -d "$SECRETS" ] || die "secret root is not a directory"',
+        'chmod 700 "$SECRETS"',
+        '[ "$(stat -c %a "$SECRETS")" = "700" ] || die "secret root mode is not 0700"',
+        '[ -d "$PROJECT" ] || die "project directory is missing"',
+        '[ ! -L "$PROJECT" ] || die "project directory is a symlink"',
+        '[ ! -L "$RUNTIME_ENV" ] || die "runtime file is a symlink"',
+        '[ -f "$RUNTIME_ENV" ] || die "runtime file is not a regular file"',
+        '[ ! -L "$CANONICAL_ENV" ] || die "canonical file is a symlink"',
+        'if [ -e "$CANONICAL_ENV" ] && [ ! -f "$CANONICAL_ENV" ]; then die "canonical path is not a regular file"; fi',
+        'tmp="$(mktemp "$PKGVAR/.env.tmp.XXXXXX")"',
+        'chmod 600 "$tmp"',
+        '[ "$(stat -c %a "$tmp")" = "600" ] || die "temporary env mode is not 0600"',
+        'trap \'rm -f "$tmp"\' EXIT HUP INT TERM',
+        'cp "$RUNTIME_ENV" "$tmp"',
+        'chmod 600 "$tmp"',
+        'mv "$tmp" "$CANONICAL_ENV"',
+        'trap - EXIT HUP INT TERM',
+        '[ ! -L "$CANONICAL_ENV" ] || die "canonical file became a symlink"',
+        '[ "$(stat -c %a "$CANONICAL_ENV")" = "600" ] || die "canonical env mode is not 0600"',
+        "exit 0",
+    ];
+    return lines.join("\n") + "\n";
+}
+function shellQuote(value) {
+    return "'" + value.replace(/'/g, "'\\''") + "'";
+}
+function renderManagedScript(name, contract, nativeContext, isResourceWorker = false, resourceWorkerAdminport, isDynamicRoute = false) {
     if (nativeContext) {
         const lifecycleInput = {
             packageIdentity: String(contract.package),
@@ -553,6 +718,31 @@ fi
         }
         return `#!/bin/sh\nexit 0\n`;
     }
+    if (isResourceWorker) {
+        if (name === "start-stop-status") {
+            return renderResourceWorkerStartStopStatus(resourceWorkerAdminport);
+        }
+        if (isDynamicRoute && name === "preinst") {
+            return renderDynamicPreinstMaterializer(contract);
+        }
+        if (isDynamicRoute && (name === "postinst" || name === "postupgrade")) {
+            return renderDynamicCanonicalMirror();
+        }
+        if (name === "postuninst") {
+            const projectRoot = isDynamicRoute ? 'PROJECT="${SYNOPKG_PKGDEST}/compose"\n' : "";
+            const deleteRoots = isDynamicRoute
+                ? ["PKGVAR", "PROJECT", "SECRETS"]
+                : ["PKGVAR", "SECRETS"];
+            return `#!/bin/sh
+set -eu
+PKGVAR="\${SYNOPKG_PKGVAR}"
+PKGHOME="\${SYNOPKG_PKGHOME}"
+SECRETS="\${PKGHOME}/secrets"
+${projectRoot}${renderDeleteAppDataBlock(deleteRoots)}exit 0
+`;
+        }
+        return `#!/bin/sh\nexit 0\n`;
+    }
     if (name === "start-stop-status") {
         return `#!/bin/sh
 ${BROKER_INSTALLER_VARS}

package/dist/build-spk/resource-worker.d.ts

@@ -0,0 +1,14 @@
+import type { AppContract } from "../types.js";
+import type { ResourceWorkerEligibility } from "../compose/analyze.js";
+export { classifyComposeRoute, resourceWorkerEligibility, type ComposeRoute, type ComposeRouteClassification, type ResourceWorkerEligibility, type ResourceWorkerIneligibleReason, } from "../compose/analyze.js";
+export declare function composeProjectName(packageId: string): string;
+export declare function renderDockerProjectResource(packageId: string, projectPath?: string): Record<string, unknown>;
+export declare function renderWebserviceResource(contract: AppContract, adminport: number): Record<string, unknown>;
+export declare function renderResourceConfig(contract: AppContract, eligibility: ResourceWorkerEligibility): string;
+/**
+ * Renders the lifecycle control script for the Docker Project resource-worker
+ * route. ContainerManager owns the actual project start/stop operation through
+ * the worker timing hooks; the package script must wait for that operation to
+ * leave a reachable service and must not claim running unconditionally.
+ */
+export declare function renderResourceWorkerStartStopStatus(adminport?: number): string;