@synopackageland/cli 0.3.0 → 0.3.2

package/dist/compose/analyze.d.ts

@@ -1,20 +1,60 @@
-import type { ComposeDocument, ComposeService, ValidationError } from "../types.js";
+import { type Document } from "yaml";
+import type { AppContract, ComposeDocument, ComposeService, ValidationError } from "../types.js";
 import { type PrivilegeFlag } from "./privilege.js";
 export interface ParsedCompose {
     compose: ComposeDocument;
     source: string;
+    document: Document;
 }
 export declare function loadCompose(composePath: string): ParsedCompose | null;
 export declare function listServiceNames(compose: ComposeDocument): string[];
 export declare function extractPublishedTcpPorts(service: ComposeService): number[];
 export declare function collectPublishedTcpPorts(compose: ComposeDocument): Map<number, string[]>;
+export type ResourceWorkerIneligibleReason = "HAS_INSTALL_PARAMETERS" | "HAS_COMPOSE_INTERPOLATION" | "HAS_COMPOSE_SECRETS_OR_CONFIGS" | "HAS_BUILD_STANZA" | "HAS_PRIVILEGED_CAPABILITY" | "WEB_APP_MISSING_OR_AMBIGUOUS_ADMINPORT";
+export interface ResourceWorkerEligibility {
+    eligible: boolean;
+    reasons: ResourceWorkerIneligibleReason[];
+    adminport?: number;
+}
+/**
+ * Checks if a Compose contract and document are eligible for the zero-config DSM resource-worker path.
+ * Zero-config slice rejects:
+ * - any install parameter
+ * - any ${...} interpolation anywhere in compose document
+ * - compose secrets or configs
+ * - build: stanzas
+ * - privileged / host network / device / root-like capabilities
+ * - any App without a unique literal published adminport status probe
+ */
+export declare function resourceWorkerEligibility(contract: AppContract, compose: ComposeDocument): ResourceWorkerEligibility;
+export type ComposeRoute = "static-zero-config" | "dynamic" | "reject";
+export interface ComposeRouteClassification {
+    route: ComposeRoute;
+    eligibility: ResourceWorkerEligibility;
+    errors: ValidationError[];
+}
+/**
+ * Chooses the local route D0 can safely emit. The first dynamic slice is
+ * deliberately small: only string/boolean wizard answers interpolated as
+ * ordinary Compose values. Secrets/configs remain rejected because the live
+ * DSM worker does not load docker-compose.override.yml, and no secret may be
+ * placed in the project .env.
+ */
+export declare function classifyComposeRoute(contract: AppContract, parsed: ParsedCompose, composeFile?: string): ComposeRouteClassification;
 export declare function collectComposeInterpolations(compose: ComposeDocument): Set<string>;
 export declare function validateComposeSecurity(compose: ComposeDocument, composeFile: string, options: {
     profile: "personal" | "listing";
     declaredPrivilege: ReadonlySet<PrivilegeFlag>;
 }): ValidationError[];
+/**
+ * DSM's Docker Project resource worker can lose YAML quotes while acquiring a
+ * project. A quoted numeric command argument can therefore become a number;
+ * reject that platform-invalid shape before it reaches the NAS.
+ */
+export declare function validateComposeNumericCommandArgs(compose: ComposeDocument, composeFile: string): ValidationError[];
 export interface HostBindContext {
     sharedFolderParams: ReadonlySet<string>;
+    homesParams?: ReadonlySet<string>;
     installParamNames: ReadonlySet<string>;
 }
 export declare function collectVolumeSourceInterpolations(compose: ComposeDocument): Set<string>;

package/dist/compose/analyze.js

@@ -1,14 +1,27 @@
-import { existsSync } from "node:fs";
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { parseDocument } from "yaml";
 import { composeSpan, makeError } from "../errors.js";
+import { collectInstallParameters, loadContract } from "../contract/load.js";
 import { undeclaredPrivilegeFindings } from "./privilege.js";
+import { scanComposePrivilege } from "./privilege.js";
 const DOCKER_SOCKET_PATHS = [
     "/var/run/docker.sock",
     "/var/run/docker.sock/",
     "/var/run/containers/container-manager.sock",
     "/var/run/containers/container-manager.sock/",
 ];
+const composeProjectRoots = new WeakMap();
+const composeSources = new WeakMap();
+const composeDocuments = new WeakMap();
+const composeContracts = new WeakMap();
+const HOST_BIND_ERROR_CODES = new Set([
+    "COMPOSE_BIND_SOURCE_FORBIDDEN",
+    "COMPOSE_BIND_SOURCE_UNDECLARED",
+    "COMPOSE_BIND_SUFFIX_INVALID",
+    "COMPOSE_HOST_BIND_FORBIDDEN",
+    "COMPOSE_NAMED_VOLUME_UNDECLARED",
+]);
 export function loadCompose(composePath) {
     if (!existsSync(composePath)) {
         return null;
@@ -16,7 +29,21 @@ export function loadCompose(composePath) {
     const source = readFileSync(composePath, "utf8");
     const doc = parseDocument(source);
     const compose = (doc.toJSON() ?? {});
-    return { compose, source };
+    if (compose && typeof compose === "object") {
+        composeProjectRoots.set(compose, dirname(resolve(composePath)));
+        composeSources.set(compose, source);
+        composeDocuments.set(compose, doc);
+        const contractPath = join(dirname(resolve(composePath)), "synology-app.yaml");
+        if (existsSync(contractPath)) {
+            try {
+                composeContracts.set(compose, loadContract(contractPath).contract);
+            }
+            catch {
+                // Contract validation reports malformed input; Compose analysis still returns its own findings.
+            }
+        }
+    }
+    return { compose, source, document: doc };
 }
 export function listServiceNames(compose) {
     if (!compose.services || typeof compose.services !== "object") {
@@ -77,6 +104,304 @@ export function collectPublishedTcpPorts(compose) {
     }
     return result;
 }
+/**
+ * Checks if a Compose contract and document are eligible for the zero-config DSM resource-worker path.
+ * Zero-config slice rejects:
+ * - any install parameter
+ * - any ${...} interpolation anywhere in compose document
+ * - compose secrets or configs
+ * - build: stanzas
+ * - privileged / host network / device / root-like capabilities
+ * - any App without a unique literal published adminport status probe
+ */
+export function resourceWorkerEligibility(contract, compose) {
+    const reasons = [];
+    if (contract.install && Object.keys(contract.install).length > 0) {
+        reasons.push("HAS_INSTALL_PARAMETERS");
+    }
+    if (hasInterpolation(compose)) {
+        reasons.push("HAS_COMPOSE_INTERPOLATION");
+    }
+    if ((compose.secrets && Object.keys(compose.secrets).length > 0) ||
+        (compose.configs && typeof compose.configs === "object" && Object.keys(compose.configs).length > 0)) {
+        reasons.push("HAS_COMPOSE_SECRETS_OR_CONFIGS");
+    }
+    if (hasBuildStanza(compose)) {
+        reasons.push("HAS_BUILD_STANZA");
+    }
+    if (scanComposePrivilege(compose).length > 0) {
+        reasons.push("HAS_PRIVILEGED_CAPABILITY");
+    }
+    let resolvedAdminport;
+    if (contract.adminport === undefined) {
+        reasons.push("WEB_APP_MISSING_OR_AMBIGUOUS_ADMINPORT");
+    }
+    else {
+        const rawPort = Number(contract.adminport);
+        if (!Number.isInteger(rawPort) || rawPort <= 0 || rawPort > 65535) {
+            reasons.push("WEB_APP_MISSING_OR_AMBIGUOUS_ADMINPORT");
+        }
+        else {
+            const published = collectPublishedTcpPorts(compose);
+            const services = published.get(rawPort) ?? [];
+            if (services.length !== 1) {
+                reasons.push("WEB_APP_MISSING_OR_AMBIGUOUS_ADMINPORT");
+            }
+            else {
+                resolvedAdminport = rawPort;
+            }
+        }
+    }
+    return {
+        eligible: reasons.length === 0,
+        reasons,
+        adminport: resolvedAdminport,
+    };
+}
+function hasInterpolation(value) {
+    if (typeof value === "string") {
+        return /\$\{([^}]+)\}/.test(value);
+    }
+    if (Array.isArray(value)) {
+        return value.some(hasInterpolation);
+    }
+    if (value && typeof value === "object") {
+        return Object.values(value).some(hasInterpolation);
+    }
+    return false;
+}
+function hasBuildStanza(compose) {
+    if (!compose.services) {
+        return false;
+    }
+    return Object.values(compose.services).some((service) => "build" in service && service.build !== undefined);
+}
+/**
+ * Chooses the local route D0 can safely emit. The first dynamic slice is
+ * deliberately small: only string/boolean wizard answers interpolated as
+ * ordinary Compose values. Secrets/configs remain rejected because the live
+ * DSM worker does not load docker-compose.override.yml, and no secret may be
+ * placed in the project .env.
+ */
+export function classifyComposeRoute(contract, parsed, composeFile = "compose.yaml") {
+    const eligibility = resourceWorkerEligibility(contract, parsed.compose);
+    const rejectErrors = contract.adminport !== undefined
+        ? collectRouteRejectErrors(contract, parsed, composeFile)
+        : [];
+    if (rejectErrors.length > 0) {
+        return { route: "reject", eligibility, errors: rejectErrors };
+    }
+    const dynamicError = contract.adminport !== undefined
+        ? collectDynamicRouteError(contract, parsed, composeFile)
+        : undefined;
+    if (dynamicError) {
+        return {
+            route: "reject",
+            eligibility,
+            errors: [dynamicError],
+        };
+    }
+    if (eligibility.eligible) {
+        return { route: "static-zero-config", eligibility, errors: [] };
+    }
+    return { route: "dynamic", eligibility, errors: [] };
+}
+function collectRouteRejectErrors(contract, parsed, composeFile) {
+    const { compose } = parsed;
+    const errors = collectPermanentRouteErrors(contract, parsed, composeFile);
+    const installParams = collectInstallParameters(contract);
+    const sharedFolderParams = new Set(installParams.filter(({ param }) => param.type === "shared_folder").map(({ name }) => name));
+    const homesParams = new Set(installParams.filter(({ param }) => param.type === "homes").map(({ name }) => name));
+    const installParamNames = new Set(installParams.map(({ name }) => name));
+    errors.push(...validateComposeHostBinds(compose, composeFile, {
+        sharedFolderParams,
+        homesParams,
+        installParamNames,
+    }));
+    return dedupeValidationErrors(errors);
+}
+function collectPermanentRouteErrors(contract, parsed, composeFile) {
+    if (contract.adminport === undefined) {
+        return [];
+    }
+    const { compose } = parsed;
+    const errors = [];
+    if (compose.services) {
+        for (const [serviceName, service] of Object.entries(compose.services)) {
+            const basePath = `services.${serviceName}`;
+            if ("build" in service && service.build !== undefined) {
+                const path = `${basePath}.build`;
+                errors.push(makeError("COMPOSE_BUILD_FORBIDDEN", composeSpanForPath(compose, composeFile, path), `service「${serviceName}」宣告 build:；D0 route 不支援 install-time build。`, "請移除 build:，改用已存在的 image（最好使用 image@sha256:... 固定 digest），再重新執行 validate。"));
+            }
+            errors.push(...validateSocketMounts(compose, service, composeFile, `${basePath}.volumes`));
+        }
+    }
+    for (const finding of scanComposePrivilege(compose)) {
+        errors.push(makeError(finding.code, composeSpanForPath(compose, composeFile, finding.path), `service「${finding.serviceName}」使用 ${finding.flag}；D0 route 永久拒收高權限 capability，即使 contract 已宣告也不會放行。`, "請移除 privileged、host network/PID/IPC、devices 或 cap_add，改用 package-only static-zero-config Compose。"));
+    }
+    return errors;
+}
+function collectDynamicRouteError(contract, parsed, composeFile) {
+    const { compose } = parsed;
+    const params = collectInstallParameters(contract);
+    const hasUnsupportedComposeFiles = hasComposeSecretsOrConfigs(compose);
+    const supportedParamNames = new Set(params
+        .filter(({ name, param }) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) &&
+        (param.type === "string" || param.type === "boolean"))
+        .map(({ name }) => name));
+    const unsupportedParam = params.find(({ name, param }) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) ||
+        (param.type !== "string" && param.type !== "boolean"));
+    const brokerOidcInterpolationNames = params.length === 0 && hasBrokerManagedOidc(contract)
+        ? BROKER_OIDC_INTERPOLATION_VARS
+        : [];
+    const supportedInterpolationNames = new Set([
+        ...supportedParamNames,
+        ...PLATFORM_BIND_VARS,
+        ...brokerOidcInterpolationNames,
+    ]);
+    const interpolations = collectComposeInterpolations(compose);
+    const hasComposeInterpolation = hasInterpolation(compose);
+    const unsupportedInterpolation = !hasComposeInterpolation
+        ? undefined
+        : interpolations.size === 0
+            ? "<unsupported interpolation syntax>"
+            : [...interpolations].find((name) => !supportedInterpolationNames.has(name));
+    const hasDynamicInputs = params.length > 0 ||
+        hasUnsupportedComposeFiles ||
+        unsupportedInterpolation !== undefined;
+    if (!hasDynamicInputs) {
+        return undefined;
+    }
+    if (!unsupportedParam && !unsupportedInterpolation && !hasUnsupportedComposeFiles) {
+        return undefined;
+    }
+    const reasons = [];
+    if (unsupportedParam) {
+        reasons.push("unsupported install parameter type: " + String(unsupportedParam.param.type ?? "unknown"));
+    }
+    if (unsupportedInterpolation) {
+        reasons.push("unsupported interpolation: " + unsupportedInterpolation);
+    }
+    if (hasUnsupportedComposeFiles) {
+        reasons.push("Compose secret/config (DSM override route is not loaded)");
+    }
+    const reasonText = reasons.join(", ");
+    const dynamicPath = findDynamicComposePath(compose);
+    const path = dynamicPath ?? (hasUnsupportedComposeFiles ? "secrets" : "services");
+    const undeclaredName = unsupportedInterpolation && !unsupportedInterpolation.startsWith("<")
+        ? unsupportedInterpolation
+        : undefined;
+    const interpolationSuggestion = undeclaredName
+        ? `請在 synology-app.yaml 的 install 宣告 ${undeclaredName}，type 為 string 或 boolean；或從 Compose 移除該引用。`
+        : "請只使用 ${NAME} 形式，並在 synology-app.yaml 的 install 宣告對應的 string 或 boolean parameter。";
+    return makeError("COMPOSE_DYNAMIC_ROUTE_UNSUPPORTED", composeSpanForPath(compose, composeFile, path), "Compose dynamic route 含有不在 D1/D2 白名單內的輸入（" +
+        reasonText +
+        "）；這條 route 會拒收，不會靜默落回 Broker fallback。", undeclaredName
+        ? interpolationSuggestion
+        : `${interpolationSuggestion} secret/config 因 DSM worker 不讀 docker-compose.override.yml 而拒收，請移除後重新執行 validate。`);
+}
+function parsedComposeForAnalysis(compose) {
+    const source = composeSources.get(compose) ?? "";
+    const document = composeDocuments.get(compose) ?? parseDocument(source);
+    return { compose, source, document };
+}
+function hasComposeSecretsOrConfigs(compose) {
+    return Boolean((compose.secrets && Object.keys(compose.secrets).length > 0) ||
+        (compose.configs && typeof compose.configs === "object" && Object.keys(compose.configs).length > 0));
+}
+function findDynamicComposePath(compose) {
+    const path = findInterpolationPath(compose, []);
+    if (!path || path.length === 0) {
+        return undefined;
+    }
+    if (path[0] === "services" && path.length >= 3) {
+        return path.slice(0, 3).join(".");
+    }
+    return path.join(".");
+}
+function findInterpolationPath(value, path) {
+    if (typeof value === "string" && /\$\{([^}]+)\}/.test(value)) {
+        return path;
+    }
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index++) {
+            const found = findInterpolationPath(value[index], [...path, String(index)]);
+            if (found) {
+                return found;
+            }
+        }
+        return undefined;
+    }
+    if (value && typeof value === "object") {
+        for (const [key, child] of Object.entries(value)) {
+            const found = findInterpolationPath(child, [...path, key]);
+            if (found) {
+                return found;
+            }
+        }
+    }
+    return undefined;
+}
+function composeSpanForPath(compose, composeFile, path) {
+    const fallback = composeSpan(composeFile, 1, 1, path);
+    const document = composeDocuments.get(compose);
+    const source = composeSources.get(compose);
+    if (!document || source === undefined) {
+        return fallback;
+    }
+    const offset = composeKeyOffset(document.contents, path.split("."));
+    if (offset === undefined) {
+        return fallback;
+    }
+    const position = lineColumnFromSource(source, offset);
+    return composeSpan(composeFile, position.line, position.column, path);
+}
+function composeKeyOffset(node, path) {
+    let current = node;
+    for (const segment of path) {
+        const items = current && Array.isArray(current.items) ? current.items : [];
+        const pair = items.find((item) => {
+            const key = item?.key;
+            return key && String(key.value) === segment;
+        });
+        if (!pair) {
+            return undefined;
+        }
+        if (segment === path[path.length - 1]) {
+            return pair.key?.range?.[0];
+        }
+        current = pair.value;
+    }
+    return undefined;
+}
+function lineColumnFromSource(source, offset) {
+    let line = 1;
+    let column = 1;
+    for (let index = 0; index < offset && index < source.length; index++) {
+        if (source[index] === "\n") {
+            line++;
+            column = 1;
+        }
+        else {
+            column++;
+        }
+    }
+    return { line, column };
+}
+function dedupeValidationErrors(errors) {
+    const seen = new Set();
+    return errors.filter((error) => {
+        const key = validationErrorKey(error);
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+}
+function validationErrorKey(error) {
+    return [error.code, error.span.file, error.span.line, error.span.column, error.span.path].join("\u0000");
+}
 export function collectComposeInterpolations(compose) {
     const names = new Set();
     walkForInterpolation(compose, names);
@@ -84,7 +409,7 @@ export function collectComposeInterpolations(compose) {
 }
 function walkForInterpolation(value, names) {
     if (typeof value === "string") {
-        for (const match of value.matchAll(/\$\{([A-Z0-9_]+)\}/g)) {
+        for (const match of value.matchAll(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g)) {
             names.add(match[1]);
         }
         return;
@@ -103,25 +428,67 @@ function walkForInterpolation(value, names) {
 }
 export function validateComposeSecurity(compose, composeFile, options) {
     const errors = [];
+    const contract = composeContracts.get(compose);
+    const routeErrors = contract
+        ? classifyComposeRoute(contract, parsedComposeForAnalysis(compose), composeFile).errors.filter((error) => !HOST_BIND_ERROR_CODES.has(error.code))
+        : [];
+    errors.push(...routeErrors);
+    const routeErrorKeys = new Set(routeErrors.map(validationErrorKey));
     if (!compose.services) {
         return errors;
     }
     const undeclaredSeverity = options.profile === "listing" ? "error" : "warning";
     for (const finding of undeclaredPrivilegeFindings(compose, options.declaredPrivilege)) {
-        errors.push(makeError(finding.code, composeSpan(composeFile, 1, 1, finding.path), finding.message, finding.suggestion, undeclaredSeverity));
+        const error = makeError(finding.code, composeSpanForPath(compose, composeFile, finding.path), finding.message, finding.suggestion, undeclaredSeverity);
+        if (!routeErrorKeys.has(validationErrorKey(error))) {
+            errors.push(error);
+        }
     }
     for (const [serviceName, service] of Object.entries(compose.services)) {
         const basePath = `services.${serviceName}`;
-        errors.push(...validateSocketMounts(service, composeFile, basePath));
+        for (const error of validateSocketMounts(compose, service, composeFile, basePath)) {
+            if (!routeErrorKeys.has(validationErrorKey(error))) {
+                errors.push(error);
+            }
+        }
         const dependsOn = normalizeDependsOn(service.depends_on);
         for (const dependency of dependsOn) {
             if (!compose.services?.[dependency]) {
-                errors.push(makeError("COMPOSE_SERVICE_NOT_FOUND", composeSpan(composeFile, 1, 1, `${basePath}.depends_on`), `Compose 引用了不存在的 service「${dependency}」。`, "請修正 depends_on，或補上對應的 service 定義。"));
+                errors.push(makeError("COMPOSE_SERVICE_NOT_FOUND", composeSpanForPath(compose, composeFile, `${basePath}.depends_on`), `Compose 引用了不存在的 service「${dependency}」。`, "請修正 depends_on，或補上對應的 service 定義。"));
             }
         }
     }
     return errors;
 }
+const COMMAND_ARGUMENT_FIELDS = ["command", "entrypoint"];
+const PURE_NUMERIC_STRING = /^[0-9]+$/;
+/**
+ * DSM's Docker Project resource worker can lose YAML quotes while acquiring a
+ * project. A quoted numeric command argument can therefore become a number;
+ * reject that platform-invalid shape before it reaches the NAS.
+ */
+export function validateComposeNumericCommandArgs(compose, composeFile) {
+    const errors = [];
+    if (!compose.services) {
+        return errors;
+    }
+    for (const [serviceName, service] of Object.entries(compose.services)) {
+        const basePath = `services.${serviceName}`;
+        for (const field of COMMAND_ARGUMENT_FIELDS) {
+            const value = service[field];
+            if (!Array.isArray(value)) {
+                continue;
+            }
+            const numericStrings = value.filter((item) => typeof item === "string" && PURE_NUMERIC_STRING.test(item));
+            if (numericStrings.length === 0) {
+                continue;
+            }
+            const quotedValues = numericStrings.map((item) => `「${item}」`).join("、");
+            errors.push(makeError("COMPOSE_NUMERIC_COMMAND_ARG_FORBIDDEN", composeSpanForPath(compose, composeFile, `${basePath}.${field}`), `${field} 陣列含純數字字串 ${quotedValues}。此 Compose 會走 DSM Docker Project resource worker；worker 可能在 YAML round-trip 時移除引號並將它轉成整數，導致 project acquire 失敗。`, `請把整個命令包成單一字串，例如 ${field}: ["sh", "-c", "httpd -f -p 8080 -h /srv"]，或與 flag 併寫成 "-p8080"。`));
+        }
+    }
+    return errors;
+}
 function normalizeDependsOn(value) {
     if (!value) {
         return [];
@@ -134,13 +501,13 @@ function normalizeDependsOn(value) {
     }
     return [String(value)];
 }
-function validateSocketMounts(service, composeFile, basePath) {
+function validateSocketMounts(compose, service, composeFile, basePath) {
     const errors = [];
     const volumes = normalizeVolumes(service.volumes);
     for (const mount of volumes) {
         const source = mount.split(":")[0]?.trim() ?? "";
         if (isForbiddenSocketMount(source)) {
-            errors.push(makeError("COMPOSE_SOCKET_MOUNT_FORBIDDEN", composeSpan(composeFile, 1, 1, `${basePath}.volumes`), "Managed Profile 不允許掛載 Docker 或 Container Manager socket。", "請移除 docker.sock／container-manager socket 的 volume mount。"));
+            errors.push(makeError("COMPOSE_SOCKET_MOUNT_FORBIDDEN", composeSpanForPath(compose, composeFile, `${basePath}.volumes`), "Managed Profile 不允許掛載 Docker 或 Container Manager socket。", "請移除 docker.sock／container-manager socket 的 volume mount。"));
         }
     }
     return errors;
@@ -166,7 +533,31 @@ function isForbiddenSocketMount(source) {
     const normalized = source.replace(/\/+$/, "");
     return DOCKER_SOCKET_PATHS.some((path) => normalized === path.replace(/\/+$/, "") || normalized.endsWith("/docker.sock"));
 }
+/**
+ * These are the only implicit interpolation names supplied by the platform.
+ * The package-only lifecycle materializer writes both paths; every other
+ * ${NAME} must be declared in contract.install as string or boolean.
+ */
 const PLATFORM_BIND_VARS = new Set(["SYNOPKG_PKGVAR", "SYNO_APP_SECRETS_DIR"]);
+/**
+ * Broker-managed OIDC compatibility injects these two names at install time.
+ * They are allowed only for an explicitly declared oidc_compat legacy route;
+ * the D1 package-only materializer does not write them.
+ */
+const BROKER_OIDC_INTERPOLATION_VARS = new Set([
+    "SYNOPKGLAND_OIDC_ISSUER",
+    "SYNOPKGLAND_OIDC_CLIENT_ID",
+]);
+function hasBrokerManagedOidc(contract) {
+    if (!contract.integration || typeof contract.integration !== "object") {
+        return false;
+    }
+    const identity = contract.integration.identity;
+    if (!identity || typeof identity !== "object") {
+        return false;
+    }
+    return Boolean(identity.oidc_compat);
+}
 const INTERPOLATED_SOURCE = /^\$\{([A-Z0-9_]+)\}(.*)$/;
 const VALID_SUFFIX_SEGMENT = /^[A-Za-z0-9._-]+$/;
 function collectNamedVolumeNames(compose) {
@@ -192,10 +583,11 @@ export function validateComposeHostBinds(compose, composeFile, context) {
         return errors;
     }
     const namedVolumes = collectNamedVolumeNames(compose);
+    const projectRoot = composeProjectRoots.get(compose) ?? dirname(resolve(composeFile));
     for (const [serviceName, service] of Object.entries(compose.services)) {
         const spanPath = `services.${serviceName}.volumes`;
         for (const mount of parseVolumeMounts(service.volumes)) {
-            const error = classifyVolumeSource(mount, namedVolumes, context, composeFile, spanPath);
+            const error = classifyVolumeSource(compose, mount, namedVolumes, context, composeFile, spanPath, projectRoot);
             if (error) {
                 errors.push(error);
             }
@@ -251,12 +643,12 @@ function parseShortVolumeSource(entry) {
     }
     return trimmed.slice(0, colon).trim();
 }
-function classifyVolumeSource(mount, namedVolumes, context, composeFile, spanPath) {
+function classifyVolumeSource(compose, mount, namedVolumes, context, composeFile, spanPath, projectRoot) {
     const source = mount.source;
     if (!source || isForbiddenSocketMount(source)) {
         return null;
     }
-    const span = composeSpan(composeFile, 1, 1, spanPath);
+    const span = composeSpanForPath(compose, composeFile, spanPath);
     if (source.includes("$")) {
         const match = source.match(INTERPOLATED_SOURCE);
         const varName = match?.[1];
@@ -264,16 +656,21 @@ function classifyVolumeSource(mount, namedVolumes, context, composeFile, spanPat
         if (!varName || suffix === undefined || !isValidatedBindSuffix(suffix)) {
             return invalidBindSuffix(span);
         }
-        if (PLATFORM_BIND_VARS.has(varName) || context.sharedFolderParams.has(varName)) {
+        if (PLATFORM_BIND_VARS.has(varName) ||
+            context.sharedFolderParams.has(varName) ||
+            context.homesParams?.has(varName)) {
             return null;
         }
         if (context.installParamNames.has(varName)) {
-            return makeError("COMPOSE_BIND_SOURCE_FORBIDDEN", span, `參數「${varName}」不能作為 host bind source。`, "請改用 ${SYNOPKG_PKGVAR}、${SYNO_APP_SECRETS_DIR} 或 type 為 shared_folder 的 install 參數。");
+            return makeError("COMPOSE_BIND_SOURCE_FORBIDDEN", span, `參數「${varName}」不能作為 host bind source。`, "請改用 ${SYNOPKG_PKGVAR}、${SYNO_APP_SECRETS_DIR}、type 為 shared_folder 的 install 參數，或 type 為 homes 的平台解析槽。");
         }
-        return makeError("COMPOSE_BIND_SOURCE_UNDECLARED", span, `volume source 引用了未宣告的參數「${varName}」。`, `請在 synology-app.yaml 的 install 宣告 ${varName}，且 type 為 shared_folder。`);
+        return makeError("COMPOSE_BIND_SOURCE_UNDECLARED", span, `volume source 引用了未宣告的參數「${varName}」。`, `請在 synology-app.yaml 的 install 宣告 ${varName}，且 type 為 shared_folder 或 homes。`);
+    }
+    if (isProjectRelativePath(source, projectRoot)) {
+        return null;
     }
     if (isLiteralHostPath(source)) {
-        return makeError("COMPOSE_HOST_BIND_FORBIDDEN", span, "禁止將 /volume*、絕對路徑或開發者機器路徑寫成 Compose volume source。", "請改用 install 參數 type: shared_folder，並以 ${參數名} 作為 bind source。");
+        return makeError("COMPOSE_HOST_BIND_FORBIDDEN", span, "禁止將 /volume*、絕對路徑或開發者機器路徑寫成 Compose volume source。", "請改用 install 參數 type: shared_folder 或 homes，並以 ${參數名} 作為 bind source。");
     }
     if (mount.type === "tmpfs") {
         return null;
@@ -307,6 +704,49 @@ function isValidatedBindSuffix(suffix) {
 function isLiteralHostPath(source) {
     return source.startsWith("/") || source.startsWith(".") || source.startsWith("~");
 }
+function isProjectRelativePath(source, projectRoot) {
+    if (!source.startsWith("./")) {
+        return false;
+    }
+    const relativeSource = source.slice(2);
+    if (relativeSource.length === 0 ||
+        relativeSource.includes("\0") ||
+        relativeSource.split("/").some((segment) => segment.length === 0 || segment === "..")) {
+        return false;
+    }
+    const projectPath = resolve(projectRoot);
+    const candidatePath = resolve(projectPath, source);
+    if (!isStrictDescendant(candidatePath, projectPath)) {
+        return false;
+    }
+    const realProjectPath = existingRealPath(projectPath);
+    const realCandidatePath = existingRealPath(candidatePath);
+    return (realProjectPath !== undefined &&
+        realCandidatePath !== undefined &&
+        isStrictDescendant(realCandidatePath, realProjectPath));
+}
+function isStrictDescendant(candidatePath, projectPath) {
+    const rel = relative(projectPath, candidatePath);
+    return rel.length > 0 && rel !== ".." && !rel.startsWith(`..${sep}`) && !rel.startsWith(sep);
+}
+function existingRealPath(path) {
+    let current = path;
+    while (!existsSync(current)) {
+        const parent = dirname(current);
+        if (parent === current) {
+            return undefined;
+        }
+        current = parent;
+    }
+    try {
+        const realCurrent = realpathSync(current);
+        const missingSuffix = relative(current, path);
+        return resolve(realCurrent, missingSuffix || ".");
+    }
+    catch {
+        return undefined;
+    }
+}
 const NUMERIC_USER = /^(0|[1-9][0-9]*)(:(0|[1-9][0-9]*))?$/;
 const ROOT_USERS = new Set(["0", "0:0", "root"]);
 export function validateComposeRunAs(compose, composeFile, context) {
@@ -320,7 +760,7 @@ export function validateComposeRunAs(compose, composeFile, context) {
             continue;
         }
         const user = raw.trim();
-        const span = composeSpan(composeFile, 1, 1, `services.${serviceName}.user`);
+        const span = composeSpanForPath(compose, composeFile, `services.${serviceName}.user`);
         if (user.includes("${")) {
             continue;
         }
@@ -339,7 +779,7 @@ export function validateAdminPortMapping(adminport, compose, composeFile) {
     const services = published.get(adminport) ?? [];
     if (services.length !== 1) {
         return [
-            makeError("CONTRACT_ADMINPORT_UNMAPPED", composeSpan(composeFile, 1, 1, `adminport:${adminport}`), `adminport ${adminport} 必須對應 Compose 中恰好一個 published TCP port。`, "請在 compose.yaml 發佈與 adminport 相同的 host port，並確認只有一個 service 使用它。"),
+            makeError("CONTRACT_ADMINPORT_UNMAPPED", composeSpanForPath(compose, composeFile, `adminport:${adminport}`), `adminport ${adminport} 必須對應 Compose 中恰好一個 published TCP port。`, "請在 compose.yaml 發佈與 adminport 相同的 host port，並確認只有一個 service 使用它。"),
         ];
     }
     return [];

package/dist/contract/load.d.ts

@@ -3,6 +3,7 @@ import type { AppContract, InstallParameter } from "../types.js";
 export interface ParsedContract {
     contract: AppContract;
     doc: Document;
+    contractPath?: string;
 }
 export declare function loadContract(contractPath: string): ParsedContract;
 export declare function getScalarPosition(doc: Document, keyPath: string[]): {