@synopackageland/cli 0.3.5 → 0.3.7

package/dist/build-spk/generator.js

@@ -20,9 +20,23 @@ import { renderNativePrivilege, renderNativeStartStopStatus, renderNativePostuni
 import { renderHeadlessResourceMarker, renderResourceConfig, renderResourceWorkerStartStopStatus, } from "./resource-worker.js";
 const FILE_MODE = 0o644;
 const SCRIPT_MODE = 0o755;
+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;
+}
 const INSTALL_UIFILE = "install_uifile";
 const UPGRADE_UIFILE = "upgrade_uifile";
 const UNINSTALL_UIFILE = "uninstall_uifile";
+const HEADLESS_PROBE_VOLUME = "./.synopkgland:/run/synopkgland:ro";
+const HEADLESS_PROBE_README = "Reserved bind target for package-user headless status probing.\n";
 export const EMBEDDED_ATTESTATION_RELATIVE_PATH = ".synopkgland/attestation.jwt";
 const SCRIPT_NAMES = [
     "preinst",
@@ -171,11 +185,11 @@ export async function buildSpk(options) {
             const resourceProjectDir = join(staging, "package", "compose");
             mkdirSync(resourceProjectDir, { recursive: true });
             const dsmUserParam = collectInstallParameters(contract).find((p) => p.param.type === "dsm_user");
-            if (dsmUserParam) {
+            if (dsmUserParam || rwEligibility?.headless === true || hasOidcCompat(contract)) {
                 const rawYaml = readFileSync(options.project.composePath, "utf8");
                 const doc = parseDocument(rawYaml);
                 const services = doc.get("services");
-                if (services && typeof services === "object" && typeof services.toJSON === "function") {
+                if (dsmUserParam && services && typeof services === "object" && typeof services.toJSON === "function") {
                     const serviceNames = Object.keys(services.toJSON());
                     for (const sName of serviceNames) {
                         const userVal = new Scalar(`\${${dsmUserParam.name}_UID}:\${${dsmUserParam.name}_GID}`);
@@ -183,15 +197,53 @@ export async function buildSpk(options) {
                         doc.setIn(["services", sName, "user"], userVal);
                     }
                 }
+                if (hasOidcCompat(contract) && services && typeof services === "object" && typeof services.toJSON === "function") {
+                    const rawServices = services.toJSON();
+                    for (const [sName, sValue] of Object.entries(rawServices)) {
+                        if (sValue && typeof sValue === "object" && hasInterpolation(sValue)) {
+                            const str = JSON.stringify(sValue);
+                            if (str.includes("SYNOPKGLAND_OIDC_ISSUER")) {
+                                const serviceDoc = doc.getIn(["services", sName]);
+                                const existingExtraHosts = serviceDoc?.get?.("extra_hosts");
+                                const hostGatewayMapping = "${SYNOPKGLAND_OIDC_ISSUER_HOST}:host-gateway";
+                                if (!existingExtraHosts) {
+                                    doc.setIn(["services", sName, "extra_hosts"], [hostGatewayMapping]);
+                                }
+                                else if (Array.isArray(existingExtraHosts.toJSON?.())) {
+                                    const arr = existingExtraHosts.toJSON();
+                                    if (!arr.includes(hostGatewayMapping)) {
+                                        doc.setIn(["services", sName, "extra_hosts"], [...arr, hostGatewayMapping]);
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+                if (rwEligibility?.headless === true) {
+                    injectHeadlessProbeVolume(doc);
+                }
                 let composeContent = doc.toString();
-                const escaped = `\\$\\{${dsmUserParam.name}_UID\\}:\\$\\{${dsmUserParam.name}_GID\\}`;
-                composeContent = composeContent.replace(new RegExp(`^([ \\t]*)user:\\s*"${escaped}"`, "gm"), `$1user: "\${${dsmUserParam.name}_UID}:\${${dsmUserParam.name}_GID}"\n$1# synopkgland:group_add ${dsmUserParam.name}`);
+                if (dsmUserParam) {
+                    const escaped = `\\$\\{${dsmUserParam.name}_UID\\}:\\$\\{${dsmUserParam.name}_GID\\}`;
+                    composeContent = composeContent.replace(new RegExp(`^([ \\t]*)user:\\s*"${escaped}"`, "gm"), `$1user: "\${${dsmUserParam.name}_UID}:\${${dsmUserParam.name}_GID}"\n$1# synopkgland:group_add ${dsmUserParam.name}`);
+                }
                 writeFileSync(join(resourceProjectDir, "docker-compose.yml"), composeContent, "utf8");
             }
             else {
                 copyFileSync(options.project.composePath, join(resourceProjectDir, "docker-compose.yml"));
             }
             chmodSync(join(resourceProjectDir, "docker-compose.yml"), FILE_MODE);
+            if (rwEligibility?.headless === true) {
+                const probePayloadDir = join(resourceProjectDir, ".synopkgland");
+                mkdirSync(probePayloadDir, { recursive: true });
+                writeFileSync(join(probePayloadDir, "README"), HEADLESS_PROBE_README, "utf8");
+                chmodSync(join(probePayloadDir, "README"), FILE_MODE);
+            }
+            const routeMarkerDir = join(staging, "package", ".synopkgland");
+            mkdirSync(routeMarkerDir, { recursive: true });
+            const routeMarker = join(routeMarkerDir, "route");
+            writeFileSync(routeMarker, "package-only", "utf8");
+            chmodSync(routeMarker, FILE_MODE);
         }
         const htmlDir = join(options.project.root, "html");
         if (existsSync(htmlDir)) {
@@ -382,6 +434,23 @@ function composeUsesOnlyAppSpace(compose) {
     const sources = volumeSources(compose);
     return sources.every((source) => source.startsWith("${SYNOPKG_PKGVAR}") || source.startsWith("${SYNO_APP_SECRETS_DIR}"));
 }
+function injectHeadlessProbeVolume(doc) {
+    const compose = (doc.toJSON() ?? {});
+    const serviceName = Object.keys(compose.services ?? {})[0];
+    if (!serviceName) {
+        return;
+    }
+    const existingVolumes = compose.services?.[serviceName]?.volumes;
+    const volumes = existingVolumes == null
+        ? []
+        : Array.isArray(existingVolumes)
+            ? [...existingVolumes]
+            : [existingVolumes];
+    if (!volumes.some((volume) => volume === HEADLESS_PROBE_VOLUME)) {
+        volumes.push(HEADLESS_PROBE_VOLUME);
+    }
+    doc.setIn(["services", serviceName, "volumes"], volumes);
+}
 const PRIVILEGE_MAX_WARNING = "此 App 的容器有高權限，接近這台 NAS 的 root、幾乎整台機器。是否安裝由你這位管理員決定。";
 function renderInstallWizard(contract, compose) {
     const items = [];
@@ -653,6 +722,14 @@ function renderDynamicPreinstMaterializer(contract) {
     if (dsmUserParam) {
         lines.push("resolve_dsm_user() {", "  user_name=\"$1\"", "  case \"$user_name\" in", "    */*|*..*|*[[:cntrl:]]*) die \"invalid user name $user_name\" ;;", "    '') die \"user name is empty\" ;;", "  esac", "  u_uid=\"$(id -u -- \"$user_name\" 2>/dev/null || true)\"", "  case \"$u_uid\" in", "    ''|*[!0-9]*) die \"resolved uid for $user_name is not a valid integer\" ;;", "    0) die \"resolved uid for $user_name cannot be 0 (root)\" ;;", "  esac", "  u_gid=\"$(id -g -- \"$user_name\" 2>/dev/null || true)\"", "  case \"$u_gid\" in", "    ''|*[!0-9]*) die \"resolved gid for $user_name is not a valid integer\" ;;", "  esac", "  # id -G returns all group ids including primary", "  raw_groups=\"$(id -G -- \"$user_name\" 2>/dev/null || true)\"", "  # filter out primary gid, deduplicate, keep numeric only", "  supp_groups=\"\"", "  for g in $raw_groups; do", "    case \"$g\" in", "      ''|*[!0-9]*) continue ;;", "    esac", "    if [ \"$g\" != \"$u_gid\" ]; then", "      already=0", "      for sg in $supp_groups; do", "        if [ \"$sg\" = \"$g\" ]; then", "          already=1", "          break", "        fi", "      done", "      if [ \"$already\" -eq 0 ]; then", "        supp_groups=\"${supp_groups}${supp_groups:+ }$g\"", "      fi", "    fi", "  done", "  printf '%s %s %s' \"$u_uid\" \"$u_gid\" \"$supp_groups\"", "}", "rewrite_group_add() {", "  p_name=\"$1\"", "  g_list=\"$2\"", "  compose_file=\"$3\"", "  [ -f \"$compose_file\" ] || die \"compose file missing at $compose_file\"", "  [ ! -L \"$compose_file\" ] || die \"compose file is a symlink\"", "  tmp_compose=\"$(mktemp \"${compose_file}.tmp.XXXXXX\")\"", "  awk -v param=\"$p_name\" -v g_list=\"$g_list\" '", "    BEGIN {", "      n = split(g_list, g_arr, \" \")", "    }", "    {", "      regex = \"^[ \\t]*# synopkgland:group_add \" param \"$\"", "      if ($0 ~ regex) {", "        match($0, /^[ \\t]*/)", "        indent = substr($0, RSTART, RLENGTH)", "        if (n > 0) {", "          print indent \"group_add:\"", "          for (i = 1; i <= n; i++) {", "            print indent \"  - ${\" param \"_GROUP_\" i \"}\"", "          }", "        }", "      } else {", "        print $0", "      }", "    }", "  ' \"$compose_file\" > \"$tmp_compose\" || die \"failed to rewrite group_add in $compose_file\"", "  mv \"$tmp_compose\" \"$compose_file\" || die \"failed to replace $compose_file\"", "}");
     }
+    if (hasOidcCompat(contract)) {
+        const identity = contract.integration?.identity;
+        const redirectPath = identity?.oidc_compat?.redirect_path ?? "";
+        const adminProtocol = contract.adminprotocol ?? "http";
+        const adminPort = Number(contract.adminport ?? 0);
+        const escapedRedirectPath = redirectPath.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+        lines.push("oidc_register() {", "  # DSM compose does not create missing bind sources: the secrets dir must exist even when compat is off.", "  (umask 077 && mkdir -p \"$PROJECT/secrets\" && chmod 700 \"$PROJECT/secrets\") || die \"failed to create $PROJECT/secrets\"", "  OIDC_ISSUER=\"\"", "  OIDC_ISSUER_HOST=\"oidc.invalid\"", "  OIDC_CLIENT_ID=\"\"", "  OIDC_CLIENT_SECRET=\"\"", "  identity_file=\"${SYNOPKGLAND_IDENTITY_FILE:-/var/packages/SynoPkgLandService/var/identity.json}\"", "  if [ ! -r \"$identity_file\" ]; then", "    identity_file=\"/volume1/@appdata/SynoPkgLandService/identity.json\"", "  fi", "  if [ ! -r \"$identity_file\" ]; then", "    # Identity endpoint not found -> Broker not installed -> skip as 404", "    rm -f \"$PROJECT/secrets/SYNOPKGLAND_OIDC_CLIENT_SECRET\"", "    return 0", "  fi", "  base_url=\"$(python3 -c 'import json, sys; data=json.load(open(sys.argv[1])); print(data.get(\"baseUrl\", \"\"))' \"$identity_file\" 2>/dev/null || true)\"", "  if [ -z \"$base_url\" ]; then", "    rm -f \"$PROJECT/secrets/SYNOPKGLAND_OIDC_CLIENT_SECRET\"", "    return 0", "  fi", "  attestation_file=\"$T/.synopkgland/attestation.jwt\"", "  if [ ! -f \"$attestation_file\" ]; then", "    rm -f \"$PROJECT/secrets/SYNOPKGLAND_OIDC_CLIENT_SECRET\"", "    return 0", "  fi", "  attestation_token=\"$(cat \"$attestation_file\")\"", "  phase=\"install\"", "  case \"$STATUS\" in", "    UPGRADE) phase=\"upgrade\" ;;", "    *) phase=\"install\" ;;", "  esac", "  req_body=\"$(python3 -c 'import json, sys; print(json.dumps({\"protocolVersion\": 1, \"attestation\": sys.argv[1], \"packageIdentity\": sys.argv[2], \"packageVersion\": sys.argv[3], \"redirectPath\": sys.argv[4], \"adminProtocol\": sys.argv[5], \"adminPort\": int(sys.argv[6]), \"phase\": sys.argv[7]}))' \"$attestation_token\" \"${SYNOPKG_PKGNAME:?}\" \"${SYNOPKG_PKGVER:?}\" \"" + escapedRedirectPath + "\" \"" + String(adminProtocol) + "\" \"" + String(adminPort) + "\" \"$phase\")\"", "  resp_file=\"$(mktemp \"$T/oidc_resp.XXXXXX\")\"", "  http_code=\"$(curl -s -S --connect-timeout 5 --max-time 30 -o \"$resp_file\" -w '%{http_code}' -X POST -H 'Content-Type: application/json' --data-binary \"$req_body\" \"${base_url}/internal/v1/oidc/register\" 2>/dev/null || true)\"", "  case \"$http_code\" in [0-9][0-9][0-9]) ;; *) http_code=\"000\" ;; esac", "  if [ \"$http_code\" = \"200\" ]; then", "    parsed_res=\"$(python3 -c 'import json, sys; d=json.load(open(sys.argv[1])); print(d.get(\"issuer\", \"\")); print(d.get(\"issuerHost\", \"\")); print(d.get(\"clientId\", \"\")); print(d.get(\"clientSecret\", \"\"))' \"$resp_file\" 2>/dev/null || true)\"", "    rm -f \"$resp_file\"", "    OIDC_ISSUER=\"$(printf '%s\\n' \"$parsed_res\" | sed -n '1p')\"", "    OIDC_ISSUER_HOST=\"$(printf '%s\\n' \"$parsed_res\" | sed -n '2p')\"", "    OIDC_CLIENT_ID=\"$(printf '%s\\n' \"$parsed_res\" | sed -n '3p')\"", "    OIDC_CLIENT_SECRET=\"$(printf '%s\\n' \"$parsed_res\" | sed -n '4p')\"", "    (umask 077 && mkdir -p \"$PROJECT/secrets\" && printf '%s' \"$OIDC_CLIENT_SECRET\" > \"$PROJECT/secrets/SYNOPKGLAND_OIDC_CLIENT_SECRET\")", "  elif [ \"$http_code\" = \"404\" ] || [ \"$http_code\" = \"000\" ]; then", "    rm -f \"$resp_file\"", "    rm -f \"$PROJECT/secrets/SYNOPKGLAND_OIDC_CLIENT_SECRET\"", "    OIDC_ISSUER=\"\"", "    OIDC_ISSUER_HOST=\"oidc.invalid\"", "    OIDC_CLIENT_ID=\"\"", "  else", "    rm -f \"$resp_file\"", "    die \"OIDC_REGISTER_FAILED $http_code\"", "  fi", "}", "oidc_register");
+    }
     lines.push('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 scalarParams) {
@@ -681,7 +758,12 @@ function renderDynamicPreinstMaterializer(contract) {
         lines.push(`  if [ "\${${name}+x}" = x ]; then`, `    ${rawUserVar}="\${${name}}"`, '  elif [ "$STATUS" = "UPGRADE" ] && [ -f "$CANONICAL_ENV" ] && [ ! -L "$CANONICAL_ENV" ] && ' +
             `${rawUserVar}="$(read_env_value "$CANONICAL_ENV" "${name}")"; then`, "    :", "  else", `    die "missing required dsm user parameter ${name}"`, "  fi", `  resolved_user_info="$(resolve_dsm_user "$${rawUserVar}")"`, "  set -- $resolved_user_info", `  ${name}_UID="$1"`, `  ${name}_GID="$2"`, "  shift 2 || true", `  ${name}_GROUPS="$*"`, `  rewrite_group_add "${name}" "$${name}_GROUPS" "$PROJECT/docker-compose.yml"`);
     }
-    lines.push('  append_env "SYNOPKG_PKGVAR" "$PLATFORM_PKGVAR"', '  append_env "SYNO_APP_SECRETS_DIR" "$PLATFORM_SECRETS"');
+    if (hasOidcCompat(contract)) {
+        lines.push('  append_env "SYNOPKG_PKGVAR" "$PLATFORM_PKGVAR"', '  append_env "SYNO_APP_SECRETS_DIR" "${SYNOPKG_PKGDEST_VOL:?}/@appstore/${SYNOPKG_PKGNAME:?}/compose/secrets"', '  append_env "SYNOPKGLAND_OIDC_ISSUER" "$OIDC_ISSUER"', '  append_env "SYNOPKGLAND_OIDC_ISSUER_HOST" "$OIDC_ISSUER_HOST"', '  append_env "SYNOPKGLAND_OIDC_CLIENT_ID" "$OIDC_CLIENT_ID"');
+    }
+    else {
+        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}"`);
     }

package/dist/build-spk/resource-worker.js

@@ -79,44 +79,29 @@ export function renderResourceConfig(contract, eligibility) {
  */
 export function renderResourceWorkerStartStopStatus(packageId, adminport, headless = false) {
     if (headless) {
-        const projectName = composeProjectName(packageId);
         return `#!/bin/sh
-PKGVAR="\${SYNOPKG_PKGVAR:-/var/packages/${packageId}/var}"
-MARKER="$PKGVAR/.docker-project-managed"
-PROJECT_NAME="${projectName}"
+SYNOPKG_PKGNAME="\${SYNOPKG_PKGNAME:-${packageId}}"
+SYNOPKGLAND_PROC_ROOT="\${SYNOPKGLAND_PROC_ROOT:-/proc}"
 
-project_containers_running() {
-  command -v docker >/dev/null 2>&1 || return 2
-  containers="$(docker ps -aq --filter "label=com.docker.compose.project=$PROJECT_NAME" 2>/dev/null)" || return 2
-  [ -n "$containers" ] || return 1
-  for container in $containers; do
-    state="$(docker inspect --format '{{.State.Running}}' "$container" 2>/dev/null)" || return 2
-    [ "$state" = "true" ] || return 1
+probe_project_process() {
+  for p in "$SYNOPKGLAND_PROC_ROOT"/[0-9]*; do
+    [ -d "$p" ] || continue
+    if grep -q docker "$p/cgroup" 2>/dev/null &&
+      grep -q \\
+        "@appstore/\${SYNOPKG_PKGNAME}/compose/" \\
+        "$p/mountinfo" 2>/dev/null; then
+      return 0
+    fi
   done
-  return 0
-}
-
-marker_managed() {
-  [ -f "$MARKER" ] || return 1
-  [ ! -L "$MARKER" ] || return 1
-  [ "$(cat "$MARKER" 2>/dev/null || true)" = "managed" ]
+  return 1
 }
 
 case "$1" in
-  start|status)
-    project_containers_running
-    probe_status=$?
-    if [ "$probe_status" -eq 0 ]; then
-      exit 0
-    fi
-    # Package user may not have a usable Docker inspection path. DSM owns the
-    # docker-project lifecycle; the postinst marker records that ownership.
-    if [ "$probe_status" -eq 2 ] && marker_managed; then
-      exit 0
-    fi
-    exit 3
+  start|stop) exit 0 ;;
+  status)
+    probe_project_process
+    exit $?
     ;;
-  stop) exit 0 ;;
   *) exit 1 ;;
 esac
 `;

package/dist/compose/analyze.js

@@ -227,10 +227,10 @@ export function classifyComposeRoute(contract, parsed, composeFile = "compose.ya
     // Keep the route decision in one place. build-spk must not independently
     // reinterpret an ineligible Compose as D1: only a route with a resolved
     // published adminport or an eligible headless Compose, plus at least one
-    // declared install parameter, has a package-only materializer. Every other
-    // buildable fallback is Broker.
+    // declared install parameter (or oidc_compat declaration), has a package-only materializer.
+    // Every other buildable fallback is Broker.
     if ((eligibility.adminport !== undefined || headlessPackageOnly) &&
-        collectInstallParameters(contract).length > 0) {
+        (collectInstallParameters(contract).length > 0 || hasBrokerManagedOidc(contract))) {
         return { route: "dynamic", eligibility, errors: [] };
     }
     return { route: "broker-installer", eligibility, errors: [] };
@@ -311,7 +311,7 @@ function collectDynamicRouteError(contract, parsed, composeFile) {
             param.type !== "boolean" &&
             param.type !== "shared_folder" &&
             param.type !== "dsm_user"));
-    const brokerOidcInterpolationNames = params.length === 0 && hasBrokerManagedOidc(contract)
+    const brokerOidcInterpolationNames = hasBrokerManagedOidc(contract)
         ? BROKER_OIDC_INTERPOLATION_VARS
         : [];
     const supportedInterpolationNames = new Set([
@@ -614,6 +614,7 @@ const PLATFORM_BIND_VARS = new Set(["SYNOPKG_PKGVAR", "SYNO_APP_SECRETS_DIR"]);
 const BROKER_OIDC_INTERPOLATION_VARS = new Set([
     "SYNOPKGLAND_OIDC_ISSUER",
     "SYNOPKGLAND_OIDC_CLIENT_ID",
+    "SYNOPKGLAND_OIDC_ISSUER_HOST",
 ]);
 function hasBrokerManagedOidc(contract) {
     if (!contract.integration || typeof contract.integration !== "object") {

package/dist/deploy/deploy.js

@@ -129,8 +129,9 @@ export async function deployProject(options) {
             }
         }
     }
+    let attestationResult;
     try {
-        await options.host.requestAttestation({
+        attestationResult = await options.host.requestAttestation({
             packageIdentity: identity.packageId,
             contractDigest,
             bundleDigest,
@@ -185,6 +186,7 @@ export async function deployProject(options) {
         displayname: identity.displayname,
         spkVersion,
         archFamily,
+        embeddedAttestationToken: attestationResult.token,
     });
     if (!build.ok || !build.outputPath) {
         return { ok: false, code: "BUILD_SPK_FAILED", message: build.errors.join(", ") };

package/dist/doctor.js

@@ -6,6 +6,19 @@ import { loadContract } from "./contract/load.js";
 import { getErrorCode } from "./error-registry.js";
 import { dsmFetch } from "./host/dsm-http.js";
 import { appOriginFromContract } from "./host/open-url.js";
+function packageRouteFromDiagnostics(diagnostics) {
+    switch (diagnostics?.packageRoute) {
+        case "package-only":
+        case "broker-installer":
+        case "unknown":
+            return diagnostics.packageRoute;
+        default:
+            break;
+    }
+    // Keep compatibility with the boolean-only response emitted by older
+    // Brokers, but never infer broker-installer from missing evidence.
+    return diagnostics?.isPackageOnly === true ? "package-only" : "unknown";
+}
 const PROJECT_FOUR_FILES = ["synology-app.yaml", "README.md", "icon.png"];
 function packageFailureSummary(state) {
     const fields = [];
@@ -199,6 +212,11 @@ export async function runDoctor(options) {
                 message: "未指定 --host，略過 Trusted App Entry 檢查",
             });
         }
+        checks.push({
+            id: "host.oidc_origin",
+            status: "skip",
+            message: "未指定 --host，略過 OIDC origin 檢查",
+        });
     }
     else {
         const host = options.host;
@@ -240,6 +258,11 @@ export async function runDoctor(options) {
                 status: "skip",
                 message: "NAS 無法連線，略過 Attestation Trust Root 檢查",
             });
+            checks.push({
+                id: "host.oidc_origin",
+                status: "skip",
+                message: "NAS 無法連線，略過 OIDC origin 檢查",
+            });
             if (options.packageId) {
                 checks.push({
                     id: "host.package_binding",
@@ -382,6 +405,50 @@ export async function runDoctor(options) {
                     }
                 }
             }
+            // Check 2.3a: OIDC-compatible public origin. This is deliberately
+            // optional so a pre-A39 Broker remains a usable doctor target.
+            if (!isBrokerReady || !host.getOidcCompatSettings) {
+                checks.push({
+                    id: "host.oidc_origin",
+                    status: "skip",
+                    message: !isBrokerReady
+                        ? "Broker 未就緒，略過 OIDC origin 檢查"
+                        : "舊版 Broker 沒有 OIDC origin endpoint，略過",
+                });
+            }
+            else {
+                try {
+                    const oidc = await host.getOidcCompatSettings();
+                    if (!oidc) {
+                        checks.push({
+                            id: "host.oidc_origin",
+                            status: "skip",
+                            message: "舊版 Broker 沒有 OIDC origin endpoint，略過",
+                        });
+                    }
+                    else if (oidc.origin.ready && oidc.origin.hostname) {
+                        checks.push({
+                            id: "host.oidc_origin",
+                            status: "pass",
+                            message: `${oidc.origin.kind} ${oidc.origin.hostname}`,
+                        });
+                    }
+                    else {
+                        checks.push({
+                            id: "host.oidc_origin",
+                            status: "skip",
+                            message: `未就緒（${oidc.origin.kind}）：${oidc.origin.setupHint}`,
+                        });
+                    }
+                }
+                catch {
+                    checks.push({
+                        id: "host.oidc_origin",
+                        status: "skip",
+                        message: "OIDC origin endpoint 無法取得，略過",
+                    });
+                }
+            }
             // Check 2.3b: DSM Residue check (A29)
             if (isBrokerReady && host.getDsmDiagnostics) {
                 try {
@@ -472,26 +539,34 @@ export async function runDoctor(options) {
                             else {
                                 const info = await host.getAttestationInfo(targetPackageId);
                                 if (info.readiness === "NOT_INSTALLED") {
-                                    // Check if package is package-only route via Broker diagnostics
-                                    let isPackageOnly = false;
+                                    // Check the diagnosed route before treating a missing binding
+                                    // as a Broker-installer failure. Unknown is deliberately
+                                    // non-failing because the Broker may not be able to read the
+                                    // DSM package resource.
+                                    let packageRoute = "unknown";
                                     if (host.getDsmDiagnostics) {
                                         try {
                                             const diag = await host.getDsmDiagnostics(targetPackageId);
-                                            if (diag?.isPackageOnly === true || diag?.packageRoute === "package-only") {
-                                                isPackageOnly = true;
-                                            }
+                                            packageRoute = packageRouteFromDiagnostics(diag);
                                         }
                                         catch {
                                             // ignore
                                         }
                                     }
-                                    if (isPackageOnly) {
+                                    if (packageRoute === "package-only") {
                                         checks.push({
                                             id: "host.package_binding",
                                             status: "skip",
                                             message: "package-only 路線，無 Broker binding（略過）",
                                         });
                                     }
+                                    else if (packageRoute === "unknown") {
+                                        checks.push({
+                                            id: "host.package_binding",
+                                            status: "skip",
+                                            message: "Broker 無法判定套件路線，略過 Package Binding 檢查",
+                                        });
+                                    }
                                     else {
                                         const errorEntry = getErrorCode("PROJECT_BINDING_NOT_FOUND");
                                         checks.push({

package/dist/host/dsm-client.js

@@ -8,6 +8,7 @@ import { lookupSharePathWithSynoagentcli } from "./share-lookup.js";
 import { dsmFetch } from "./dsm-http.js";
 import { installPackageFromCatalog, installPackageFromLocalSpk, uninstallPackageFromDsm, fetchInstalledPackageState, packageStateFromRecord, } from "./catalog-install.js";
 import { resolveHostCredentials } from "./credentials.js";
+const OIDC_COMPAT_PATH = "/api/v1/inner-loop/oidc-compat";
 export function createNasHost(options = {}) {
     const credentials = options.credentials ?? resolveHostCredentials(options.host);
     if (!credentials) {
@@ -160,7 +161,12 @@ function createDsmNasHost(credentials, profileName) {
                 error.code = body.error?.code;
                 throw error;
             }
-            return { kind: "local", attestationDigest: body.attestationDigest ?? "" };
+            const token = typeof body.token === "string" && body.token.length > 0 ? body.token : undefined;
+            return {
+                kind: "local",
+                attestationDigest: body.attestationDigest ?? "",
+                ...(token !== undefined ? { token } : {}),
+            };
         },
         async ensurePackageSource(origin) {
             ensurePackageSourceFeed(origin);
@@ -343,6 +349,51 @@ function createDsmNasHost(credentials, profileName) {
                 return undefined;
             }
         },
+        async getOidcCompatSettings() {
+            try {
+                await ensureLogin();
+                const response = await dsmFetch(`${brokerBaseUrl}${OIDC_COMPAT_PATH}`, {
+                    headers: { cookie: cookieHeader ?? "" },
+                });
+                const text = await response.text();
+                if (response.status === 404 || text.trimStart().startsWith("<")) {
+                    return undefined;
+                }
+                if (!response.ok) {
+                    return undefined;
+                }
+                const payload = JSON.parse(text);
+                const settings = payload.settings;
+                if (!settings || typeof settings !== "object" || Array.isArray(settings)) {
+                    return undefined;
+                }
+                const record = settings;
+                const origin = record.origin;
+                if (!origin || typeof origin !== "object" || Array.isArray(origin)) {
+                    return undefined;
+                }
+                const originRecord = origin;
+                if (typeof record.enabled !== "boolean" ||
+                    typeof originRecord.ready !== "boolean" ||
+                    typeof originRecord.kind !== "string" ||
+                    typeof originRecord.setupHint !== "string") {
+                    return undefined;
+                }
+                return {
+                    enabled: record.enabled,
+                    origin: {
+                        ready: originRecord.ready,
+                        kind: originRecord.kind,
+                        hostname: typeof originRecord.hostname === "string" ? originRecord.hostname : undefined,
+                        issuerUrl: typeof originRecord.issuerUrl === "string" ? originRecord.issuerUrl : undefined,
+                        setupHint: originRecord.setupHint,
+                    },
+                };
+            }
+            catch {
+                return undefined;
+            }
+        },
         async smokeRequireLogin(input) {
             await ensureLogin();
             const info = await this.getAttestationInfo(input.packageIdentity);

package/dist/host/fake-nas.d.ts

@@ -1,4 +1,4 @@
-import type { AttestationKind, HostInstallRecord, NasHost } from "./types.js";
+import type { AttestationKind, HostInstallRecord, HostOidcCompatSettings, NasHost, PackageRoute } from "./types.js";
 export interface FakeNasHostOptions {
     curated?: string[];
     dsmOrigin?: string;
@@ -8,10 +8,12 @@ export interface FakeNasHostOptions {
     installedEnv?: Record<string, Record<string, string>>;
     diagnostics?: {
         dsmResidue?: import("./types.js").DsmResidueInventory;
-        packageRoute?: string;
+        packageRoute?: PackageRoute;
         isPackageOnly?: boolean;
         [key: string]: unknown;
     };
+    /** Omit to model an older Broker without the OIDC settings endpoint. */
+    oidcCompat?: HostOidcCompatSettings;
 }
 export declare function createFakeNasHost(options?: FakeNasHostOptions): NasHost & {
     installs: HostInstallRecord[];

package/dist/host/fake-nas.js

@@ -49,7 +49,11 @@ export function createFakeNasHost(options = {}) {
             }
             const digest = `${input.packageIdentity}:${input.bundleDigest}:${input.contractDigest}`;
             host.attestations.add(input.packageIdentity);
-            return { kind: "local", attestationDigest: digest };
+            return {
+                kind: "local",
+                attestationDigest: digest,
+                token: `fake-local-attestation.${input.packageIdentity}`,
+            };
         },
         async ensurePackageSource() { },
         async installFromCatalog(input) {
@@ -111,6 +115,15 @@ export function createFakeNasHost(options = {}) {
         async getDsmDiagnostics() {
             return options.diagnostics;
         },
+        async getOidcCompatSettings() {
+            if (!options.oidcCompat) {
+                return undefined;
+            }
+            return {
+                enabled: options.oidcCompat.enabled,
+                origin: { ...options.oidcCompat.origin },
+            };
+        },
         async smokeRequireLogin() {
             return { ok: true, username: "admin" };
         },

package/dist/host/types.d.ts

@@ -1,5 +1,18 @@
 import type { InstalledPackageState } from "./catalog-install.js";
 export type AttestationKind = "local" | "app-package" | "none";
+export type PackageRoute = "package-only" | "broker-installer" | "unknown";
+export type OidcOriginKind = "public-ca" | "quickconnect" | "lan-ip" | "self-signed" | "private-ca" | "http";
+export interface HostOidcOriginEvaluation {
+    ready: boolean;
+    kind: OidcOriginKind;
+    hostname?: string;
+    issuerUrl?: string;
+    setupHint: string;
+}
+export interface HostOidcCompatSettings {
+    enabled: boolean;
+    origin: HostOidcOriginEvaluation;
+}
 export interface DeployIdentity {
     packageId: string;
     displayname: string;
@@ -8,6 +21,7 @@ export interface DeployIdentity {
 export interface AttestationIssueResult {
     kind: "local";
     attestationDigest: string;
+    token?: string;
 }
 export interface ResidueItem {
     kind: "port_profile_sc" | "cm_project_config";
@@ -74,10 +88,12 @@ export interface NasHost {
     fetchContainerLogs(packageIdentity: string): Promise<string[]>;
     getDsmDiagnostics?(packageIdentity?: string): Promise<{
         dsmResidue?: DsmResidueInventory;
-        packageRoute?: "package-only" | "broker-installer" | string;
+        packageRoute?: PackageRoute;
         isPackageOnly?: boolean;
         [key: string]: unknown;
     } | undefined>;
+    /** Read the optional administrator OIDC compatibility settings endpoint. */
+    getOidcCompatSettings?(): Promise<HostOidcCompatSettings | undefined>;
     smokeRequireLogin(input: {
         packageIdentity: string;
         cookieHeader: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {

package/skills/reference/deploy.md

@@ -1,6 +1,6 @@
 # 部署（Deploy）
 
-Inner Loop：thin SPK、NAS Administrator DSM 授權、Local Attestation、經 Package Center 安裝。**不要 SSH**，不要把 Compose 貼進 Container Manager 手工裝。
+Inner Loop：thin SPK、NAS Administrator DSM 授權、Local Attestation、經 Package Center 安裝。Personal deploy 會把 Broker 簽發的 local attestation 內嵌到套件供 preinst 使用。**不要 SSH**，不要把 Compose 貼進 Container Manager 手工裝。
 
 ## 前置