@synopackageland/cli 0.34.0 → 0.36.0

package/dist/build-spk/install-wizard.d.ts

@@ -16,5 +16,7 @@ export interface InstallWizardFiles {
  * items, and only the dynamic one adds the reuse notice when data exists.
  */
 export declare function renderInstallWizardFiles(packageName: string, render: (t: Translate) => InstallWizardStep[]): InstallWizardFiles;
+/** Lists the App's unauthenticated service callbacks for the administrator. */
+export declare function integrationWizardSteps(t: Translate, methods?: readonly string[]): InstallWizardStep[];
 /** The native-go install step: no parameters, only the app-space consent. */
 export declare function renderNativeInstallWizard(t: Translate): InstallWizardStep[];

package/dist/build-spk/install-wizard.js

@@ -70,6 +70,10 @@ export function renderInstallWizardFiles(packageName, render) {
     }
     return { static: staticFiles, dynamic };
 }
+/** Lists the App's unauthenticated service callbacks for the administrator. */
+export function integrationWizardSteps(t, methods = []) {
+    return methods.length ? [{ step_title: t("integration.step"), items: [{ desc: t("integration.notice", { methods: methods.join(", ") }) }] }] : [];
+}
 /** The native-go install step: no parameters, only the app-space consent. */
 export function renderNativeInstallWizard(t) {
     return [{ step_title: t("install.step"), items: [{ desc: t("consent.appOwnSpace") }] }];

package/dist/build-spk/wizard-messages.d.ts

@@ -230,6 +230,28 @@ export declare const WIZARD_MESSAGES: {
         es: string;
         it: string;
     };
+    "integration.step": {
+        en: string;
+        "zh-TW": string;
+        "zh-CN": string;
+        ja: string;
+        ko: string;
+        de: string;
+        fr: string;
+        es: string;
+        it: string;
+    };
+    "integration.notice": {
+        en: string;
+        "zh-TW": string;
+        "zh-CN": string;
+        ja: string;
+        ko: string;
+        de: string;
+        fr: string;
+        es: string;
+        it: string;
+    };
     "install.reuseData": {
         en: string;
         "zh-TW": string;

package/dist/build-spk/wizard-messages.js

@@ -230,6 +230,28 @@ export const WIZARD_MESSAGES = {
         es: "Configuración de instalación",
         it: "Impostazioni di installazione",
     },
+    "integration.step": {
+        en: "Service callbacks",
+        "zh-TW": "服務回呼入口",
+        "zh-CN": "服务回调入口",
+        ja: "サービスコールバック",
+        ko: "서비스 콜백",
+        de: "Dienst-Callbacks",
+        fr: "Rappels de services",
+        es: "Devoluciones de llamada de servicios",
+        it: "Callback dei servizi",
+    },
+    "integration.notice": {
+        en: "These app entry points accept requests from other services without a DSM sign-in: {methods}. The app verifies each request with its own token, signature or key. It acts only for DSM accounts that are enabled and allowed by Application Privileges, and never with administrator rights.",
+        "zh-TW": "這些 App 入口接受其他服務在未登入 DSM 的情況下送來的請求：{methods}。App 會用自己的 token、簽章或金鑰驗證每個請求，只會代表已啟用且 Application Privileges 允許的 DSM 帳號執行，且一律不具管理員權限。",
+        "zh-CN": "这些应用入口接受其他服务在未登录 DSM 的情况下发送的请求：{methods}。应用会用自己的 token、签名或密钥验证每个请求，只会代表已启用且 Application Privileges 允许的 DSM 账号执行，且始终不具备管理员权限。",
+        ja: "次のアプリの入口は、DSM にサインインしていない他のサービスからの要求を受け付けます：{methods}。アプリは各要求を独自のトークン、署名、またはキーで検証します。有効で、アプリケーション権限で許可された DSM アカウントとしてのみ動作し、管理者権限は使いません。",
+        ko: "다음 앱 진입점은 DSM에 로그인하지 않은 다른 서비스의 요청을 받습니다: {methods}. 앱은 자체 토큰, 서명 또는 키로 각 요청을 확인합니다. 활성화되어 있고 애플리케이션 권한이 허용하는 DSM 계정으로만 동작하며, 관리자 권한은 사용하지 않습니다.",
+        de: "Diese App-Einstiegspunkte nehmen Anfragen anderer Dienste ohne DSM-Anmeldung an: {methods}. Die App prüft jede Anfrage mit eigenem Token, eigener Signatur oder eigenem Schlüssel. Sie handelt nur für aktivierte DSM-Konten, die die Anwendungsberechtigungen zulassen, und nie mit Administratorrechten.",
+        fr: "Ces points d'entrée de l'application acceptent des requêtes d'autres services sans connexion DSM : {methods}. L'application vérifie chaque requête avec son propre jeton, sa signature ou sa clé. Elle n'agit que pour des comptes DSM activés et autorisés par les privilèges d'application, et jamais avec des droits d'administrateur.",
+        es: "Estos puntos de entrada de la aplicación aceptan solicitudes de otros servicios sin iniciar sesión en DSM: {methods}. La aplicación verifica cada solicitud con su propio token, firma o clave. Solo actúa en nombre de cuentas de DSM habilitadas y permitidas por los privilegios de aplicación, y nunca con derechos de administrador.",
+        it: "Questi punti di ingresso dell'app accettano richieste da altri servizi senza accesso a DSM: {methods}. L'app verifica ogni richiesta con il proprio token, firma o chiave. Agisce solo per account DSM abilitati e consentiti dai privilegi delle applicazioni, mai con diritti di amministratore.",
+    },
     "install.reuseData": {
         en: "Data from an earlier installation is still on this NAS (@appdata/{package}), so this install reuses it: saved settings and generated secrets stay. To start empty, cancel and clear that data first — uninstall the app with “Also delete the app data listed above” ticked — then install again.",
         "zh-TW": "這台 NAS 還留有先前安裝的資料（@appdata/{package}），本次安裝會沿用：已存的設定與產生的 secrets 都會保留。若要從空白開始，請先取消並清除該資料——解除安裝時勾選「一併刪除上列 App 資料」——再重新安裝。",

package/dist/cli.js

@@ -39,6 +39,8 @@ import { checkReproducible } from "./reproducible.js";
 import { spkApprovalDiff, formatApprovalDiff } from "./runtime/approval-diff.js";
 import { inspectAnySpk } from "./spk/inspect.js";
 import { terminalSafe } from "./terminal-text.js";
+import { auditGoRoutes } from "./standalone/route-audit.js";
+import { parseApiPermissions } from "./standalone/api-permissions.js";
 function failure(code, message, hint = "Fix the configuration and retry; use --help to see command usage.") {
     return Object.assign(new Error(codedMessage(code, message)), { code, hint });
 }
@@ -335,6 +337,30 @@ async function runCliWithin(argv) {
         .option("--json", "Print a single JSON object")
         .action(async (id, options) => { const { uninstallPackage } = await import('./host/package-commands.js'); const result = await uninstallPackage(id, options); emit('uninstall', result, JSON.stringify(result, null, 2)); });
     program.command("ctl").description("Control registered NAS Apps using described AI commands (ctl --help)");
+    program.command("audit-entry <main>")
+        .description("Audit one custom Go payload's target import graph without executing it")
+        .option("--dir <dir>", "Go module directory", ".")
+        .option("--arch <arches>", "Comma-separated Go target architectures", "amd64,arm64,arm")
+        .option("--permissions <file>", "App permissions JSON, when the payload registers App methods")
+        .option("--json", "Print a single JSON object")
+        .action((main, options) => {
+        const arches = options.arch.split(",");
+        if (!arches.length || arches.some(arch => !["amd64", "arm64", "arm"].includes(arch))) {
+            throw new Error("audit-entry: --arch must contain amd64, arm64 or arm");
+        }
+        const dir = resolve(options.dir);
+        const policy = options.permissions
+            ? parseApiPermissions(readFileSync(resolve(dir, options.permissions)))
+            : { schema: 1, default: "administrators", methods: {} };
+        const audit = auditGoRoutes(dir, policy, {}, [main], arches);
+        const ok = audit.problems.length === 0;
+        if (json)
+            stdout(JSON.stringify({ ok, ...audit }));
+        else
+            stdout(terminalSafe(ok ? "Entry audit passed" : audit.problems.join("\n")));
+        if (!ok)
+            process.exitCode = 1;
+    });
     program
         .command("check")
         .description("Validate the manifest, capability combination and Compose")

package/dist/error-registry.js

@@ -843,6 +843,16 @@ export const ERROR_REGISTRY = {
             description: "The API policy is invalid.",
             suggestion: "Fix backend/internal/api/permissions.json.",
         },
+        STANDALONE_INTEGRATIONS_INVALID: {
+            code: "STANDALONE_INTEGRATIONS_INVALID",
+            description: "The integrations list in dsm-package.yaml is invalid or used where an integration callback cannot run.",
+            suggestion: "List each integration method once, sorted, as a string; integrations need a Go backend without compose.",
+        },
+        STANDALONE_INTEGRATIONS_MISMATCH: {
+            code: "STANDALONE_INTEGRATIONS_MISMATCH",
+            description: "The integrations list does not match the methods permissions.json marks integration.",
+            suggestion: "List exactly the integration methods from permissions.json in dsm-package.yaml integrations.",
+        },
         CLI_OPTION_UNKNOWN: {
             code: "CLI_OPTION_UNKNOWN",
             description: "Unknown CLI option.",

package/dist/standalone/api-description.js

@@ -33,6 +33,7 @@ export async function buildApiDescription(m, bridgeMethods, run) {
     if (!Array.isArray(methods) || methods.some(item => typeof item.method !== 'string' || typeof item.permission !== 'string'))
         throw new StandaloneBuildError('CTL_DESCRIBE_FAILED', 'Invalid registry snapshot.');
     const registry = new Map(methods.map(item => [item.method, item.permission]));
+    const rawHTTP = new Set(methods.filter(item => item.kind === 'http').map(item => item.method));
     // Identity transport routes are outside the business registry but have immutable SDK ownership.
     if (m.capabilities.identity) {
         registry.set('identity.session', 'public');
@@ -46,6 +47,8 @@ export async function buildApiDescription(m, bridgeMethods, run) {
         const names = flowMethods(command.flow);
         let permission = 'public';
         for (const name of names) {
+            if (rawHTTP.has(name))
+                throw new StandaloneBuildError('CTL_COMMAND_UNREGISTERED', `Command ${id} references raw HTTP route ${name}; ctl commands require RPC methods.`);
             if (!registry.has(name))
                 throw new StandaloneBuildError('CTL_COMMAND_UNREGISTERED', `Command ${id} references unregistered method ${name}.`);
             const effective = m.entry === 'admin-only' ? 'administrators' : registry.get(name);

package/dist/standalone/api-permissions.d.ts

@@ -5,7 +5,8 @@ export declare const API_PERMISSIONS_FILE: Record<SdkBackend["kind"], string>;
 type SdkPermissions = Record<string, Record<string, ApiPermission>>;
 export declare const MAX_PERMISSIONS_BYTES = 65536;
 export declare const MAX_PERMISSION_METHODS = 1024;
-export type ApiPermission = "administrators" | "authenticated" | "public";
+/** `integration` marks a Go `api.HandleIntegration` callback that arrives without a DSM session. */
+export type ApiPermission = "administrators" | "authenticated" | "public" | "integration";
 export interface ApiPermissions {
     schema: 1;
     default: "administrators";
@@ -30,4 +31,6 @@ export declare function floorAtAdministrators(policy: ApiPermissions, sdkPermiss
 };
 /** Launcher access is derived from the same API policy; no second setting. */
 export declare function permitsOrdinaryUsers(policy?: ApiPermissions): boolean;
+/** Methods declared with the `integration` permission, sorted. */
+export declare function integrationMethods(policy?: ApiPermissions): string[];
 export {};

package/dist/standalone/api-permissions.js

@@ -27,7 +27,7 @@ export function parseApiPermissions(raw) {
         throw new Error("too many permission methods");
     for (const [method, permission] of entries) {
         const matched = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/.exec(method);
-        if (method.length > 128 || matched?.[0] !== method || !["administrators", "authenticated", "public"].includes(permission)) {
+        if (method.length > 128 || matched?.[0] !== method || !["administrators", "authenticated", "public", "integration"].includes(permission)) {
             throw new Error(`invalid permission for method ${JSON.stringify(method)}`);
         }
     }
@@ -63,11 +63,17 @@ export function readApiPermissions(backend, capabilities = {}) {
 export function floorAtAdministrators(policy, sdkPermissions) {
     const sdk = new Set(Object.values(sdkPermissions).flatMap(methods => Object.keys(methods)));
     const methods = Object.fromEntries(Object.entries(policy.methods)
-        .map(([method, permission]) => [method, sdk.has(method) && permission === "public" ? permission : "administrators"]));
-    const widened = Object.entries(policy.methods).filter(([method, permission]) => !sdk.has(method) && permission !== "administrators").map(([method]) => method);
+        .map(([method, permission]) => [method, sdk.has(method) && permission === "public" || permission === "integration" ? permission : "administrators"]));
+    // An integration callback admits no DSM account by itself: api.ActAs refuses
+    // every account in an administrator-only App.
+    const widened = Object.entries(policy.methods).filter(([method, permission]) => !sdk.has(method) && permission !== "administrators" && permission !== "integration").map(([method]) => method);
     return { policy: { ...policy, methods }, widened };
 }
 /** Launcher access is derived from the same API policy; no second setting. */
 export function permitsOrdinaryUsers(policy) {
-    return policy !== undefined && Object.values(policy.methods).some(permission => permission !== "administrators");
+    return policy !== undefined && Object.values(policy.methods).some(permission => permission !== "administrators" && permission !== "integration");
+}
+/** Methods declared with the `integration` permission, sorted. */
+export function integrationMethods(policy) {
+    return Object.entries(policy?.methods ?? {}).filter(([, permission]) => permission === "integration").map(([method]) => method).sort();
 }

package/dist/standalone/build.js

@@ -1,5 +1,5 @@
 import { buildInstallSettings } from './install-settings.js';
-import { auditGoRoutes } from './route-audit.js';
+import { auditGoRoutes, httpRoutesDigest } from './route-audit.js';
 import { PORTAL_REQUIRES_EXECUTOR } from "../portal/alias.js";
 import { buildApiDescription } from "./api-description.js";
 import { goChildEnv } from "../runtime/go-env.js";
@@ -234,7 +234,7 @@ async function buildGoCgi(manifest, backend, arch, work, run) {
         throw new StandaloneBuildError("STANDALONE_API_PERMISSIONS_CHANGED", "API permissions changed during build; check and rebuild.");
     }
     const policy = readApiPermissions(backend, manifest.capabilities);
-    const audit = auditGoRoutes(backend.dir, policy.policy, policy.sdk);
+    const audit = auditGoRoutes(backend.dir, policy.policy, policy.sdk, [backend.main], [goBuildEnv(arch).GOARCH]);
     if (audit.problems.length || manifest.entry && !audit.entryGate) {
         throw new StandaloneBuildError("STANDALONE_API_REGISTRY_INVALID", audit.problems.join("\n") || "App entry gate was removed during build.");
     }
@@ -252,6 +252,9 @@ async function buildGoCgi(manifest, backend, arch, work, run) {
         `-X ${module}/internal/api.expectedPermissionsDigest=${manifest.apiPermissionsDigest}`,
         `-X ${SDK_MODULE}/api.expectedSDKPermissionsDigest=${manifest.apiSDKPermissionsDigest}`,
         `-X ${SDK_MODULE}/api.expectedPermissionsDigest=${manifest.apiPermissionsDigest}`,
+        `-X ${SDK_MODULE}/api.expectedHTTPRoutesDigest=${httpRoutesDigest(audit)}`,
+        `-X ${SDK_MODULE}/ipc.packageID=${manifest.package}`,
+        `-X ${SDK_MODULE}/ipc.executorTier=none`,
         ...(manifest.entry ? [`-X ${SDK_MODULE}/api.expectedEntryMode=${manifest.entry}`] : []),
         ...delegateBuildFlags(manifest),
         ...(manifest.executor
@@ -302,11 +305,21 @@ async function buildBackgroundWorker(manifest, arch, work, run) {
     if (!manifest.capabilities.jobs || manifest.backend.kind !== "go")
         return undefined;
     const out = join(work, `background-worker-${arch}`);
+    const policy = readApiPermissions(manifest.backend, manifest.capabilities);
+    const audit = auditGoRoutes(manifest.backend.dir, policy.policy, policy.sdk, [BACKGROUND_WORKER_MAIN], [goBuildEnv(arch).GOARCH]);
+    if (audit.problems.length)
+        throw new StandaloneBuildError("STANDALONE_API_REGISTRY_INVALID", audit.problems.join("\n"));
     const ldflags = [
         "-s",
         "-w",
         "-buildid=",
         `-X main.packageID=${manifest.package}`,
+        `-X ${SDK_MODULE}/ipc.packageID=${manifest.package}`,
+        `-X ${SDK_MODULE}/ipc.executorTier=none`,
+        `-X ${SDK_MODULE}/api.expectedHTTPRoutesDigest=${httpRoutesDigest(audit)}`,
+        `-X ${SDK_MODULE}/api.expectedPermissionsDigest=${manifest.apiPermissionsDigest}`,
+        `-X ${SDK_MODULE}/api.expectedSDKPermissionsDigest=${manifest.apiSDKPermissionsDigest}`,
+        ...(manifest.entry ? [`-X ${SDK_MODULE}/api.expectedEntryMode=${manifest.entry}`] : []),
         ...delegateBuildFlags(manifest),
         ...(manifest.executor
             ? [

package/dist/standalone/inspect-spk.d.ts

@@ -50,6 +50,8 @@ export interface SpkInspection {
     };
     /** Declared `entry` mode; `admin-only` is the administrator floor of every route. */
     entry?: EntryMode;
+    /** Service callbacks that skip the DSM session, as listed in the install and upgrade wizards. */
+    integrations?: string[];
     /** The declared launch mode verified against the built launcher. */
     launch?: WebLaunchMode;
     /** The App's own scripts/app/<DSM script name>, each called from the generated script of that name. */

package/dist/standalone/inspect-spk.js

@@ -31,8 +31,8 @@ import { readUninstallRecord, stateItemTexts } from "./uninstall.js";
 import { DSM_LANGS } from "./i18n.js";
 import { BACKGROUND_UNIT_DIR, BACKGROUND_WORKER_PAYLOAD, BRIDGE_WORKER_ARGS, backgroundUnitName, renderBackgroundUnit, } from "./background.js";
 import { renderStandaloneResource } from "./resource.js";
-import { recoverSharedFolder, renderSharedFolderUpgradeWizardFiles, sharedFolderInstallSteps, SHARED_FOLDER_MARKER, } from "./shared-folder.js";
-import { renderInstallWizardFiles, renderNativeInstallWizard, } from "../build-spk/install-wizard.js";
+import { recoverSharedFolder, renderUpgradeWizardFiles, sharedFolderInstallSteps, SHARED_FOLDER_MARKER, } from "./shared-folder.js";
+import { renderInstallWizardFiles, integrationWizardSteps, renderNativeInstallWizard, } from "../build-spk/install-wizard.js";
 import { renderDelegateScopeSteps, } from "../build-spk/delegate-scope.js";
 import { renderUninstallWizardFiles } from "../build-spk/uninstall-wizard.js";
 import { renderNativePrivilege } from "../build-spk/native-lifecycle.js";
@@ -125,6 +125,8 @@ export async function inspectSpk(spkPath, expectedKind) {
                     throw new Error();
                 if (raw.operationSeconds !== undefined && (!Number.isInteger(raw.operationSeconds) || raw.operationSeconds < 1 || raw.operationSeconds > 3600))
                     throw new Error();
+                if (raw.integrations !== undefined && (raw.backend !== 'go' || !Array.isArray(raw.integrations) || !raw.integrations.length || raw.integrations.length > 1024 || raw.integrations.some((m, i) => typeof m !== 'string' || m.length > 128 || !/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/.test(m) || i > 0 && raw.integrations[i - 1] >= m)))
+                    throw new Error();
                 metadata = raw;
             }
             catch {
@@ -138,6 +140,7 @@ export async function inspectSpk(spkPath, expectedKind) {
         const identityGateway = await inspectProviderOnlyAdmission(dir, paths, metadata.provider_only_oidc, findings);
         await inspectExternalGateway(dir, paths, payload, metadata.gateway_external, findings);
         const installSettings = await inspectInstallSettings(dir, payload, metadata, findings);
+        const integrations = metadata.integrations ?? [];
         if (metadata.compose !== undefined) {
             const result = await inspectUnifiedCompose(dir, payload, { ...metadata, installSettings }, findings);
             if (installSettings)
@@ -291,7 +294,7 @@ export async function inspectSpk(spkPath, expectedKind) {
             ? await inspectLoginStyle(dir, info.package, Boolean(portal || executor?.policy.portal), findings)
             : undefined;
         if (standalone)
-            checkSharedFolder(dir, findings, info.package, sharedFolder, executor?.policy.scope === "install-selected", portal, hasExecutor, nativeGateway, info.os_min_ver, installSettings);
+            checkSharedFolder(dir, findings, info.package, sharedFolder, executor?.policy.scope === "install-selected", portal, hasExecutor, nativeGateway, info.os_min_ver, installSettings, integrations);
         const icon = inspectPackageIcons(dir, findings);
         const cgiEntry = payload.find((entry) => entry.path === CGI_PAYLOAD_PATH);
         if (standalone && !cgiEntry) {
@@ -319,6 +322,7 @@ export async function inspectSpk(spkPath, expectedKind) {
                 }
                 : {}),
             ...(metadata.entry ? { entry: metadata.entry } : {}),
+            ...(integrations.length ? { integrations } : {}),
             ...(appScripts.length ? { appScripts } : {}),
             ...(loginStyle ? { loginStyle } : {}),
             ...(standalone
@@ -1365,7 +1369,7 @@ function checkBackground(dir, info, payload, findings, executor, daemon, bridge
  * declaration (without one, any present file must be the default native
  * install wizard), and no other install/upgrade wizard file may exist.
  */
-function checkSharedFolder(dir, findings, pkg, folder, selected = false, portal, executor = false, nativeGateway, osMinVer, installSettings) {
+function checkSharedFolder(dir, findings, pkg, folder, selected = false, portal, executor = false, nativeGateway, osMinVer, installSettings, integrations = []) {
     const wizardDir = join(dir, "WIZARD_UIFILES");
     const present = (existsSync(wizardDir) ? readdirSync(wizardDir) : [])
         .filter((name) => /^(install|upgrade)_uifile(_|\.|$)/.test(name))
@@ -1391,16 +1395,18 @@ function checkSharedFolder(dir, findings, pkg, folder, selected = false, portal,
             : {}),
         ...portalManifest(portal),
     };
-    const wizards = expectedWizardFiles(pkg, folder, selected, portal, installSettings);
+    const wizards = expectedWizardFiles(pkg, folder, selected, portal, installSettings, integrations);
     const source = selected
         ? "the install-selected policy"
         : folder
             ? "the install.sharedFolder declaration"
             : portal
                 ? "the portal declaration"
-                : "the native-go default install wizard";
+                : integrations.length
+                    ? "the integrations declaration"
+                    : "the native-go default install wizard";
     // The default native wizard is optional; a declared shared folder or portal needs all of its files.
-    for (const name of folder || selected || portal || installSettings
+    for (const name of folder || selected || portal || installSettings || integrations.length
         ? Object.keys(wizards)
         : present.filter((n) => n in wizards)) {
         if (readOptional(join(wizardDir, name)) !== wizards[name])
@@ -1461,7 +1467,7 @@ async function inspectInstallSettings(dir, payload, metadata, findings) {
     }
     return settings;
 }
-function expectedWizardFiles(pkg, folder, selected = false, portal, installSettings) {
+function expectedWizardFiles(pkg, folder, selected = false, portal, installSettings, integrations = []) {
     const steps = selected
         ? (t) => [
             ...renderDelegateScopeSteps(t),
@@ -1470,11 +1476,11 @@ function expectedWizardFiles(pkg, folder, selected = false, portal, installSetti
         : folder
             ? sharedFolderInstallSteps(pkg, folder)
             : renderNativeInstallWizard;
-    const install = renderInstallWizardFiles(pkg, t => [...steps(t), ...settingsInstallSteps(installSettings)(t), ...(portal ? [renderPortalWizardStep(t, portal.alias)] : [])]);
+    const install = renderInstallWizardFiles(pkg, t => [...steps(t), ...settingsInstallSteps(installSettings)(t), ...(portal ? [renderPortalWizardStep(t, portal.alias)] : []), ...integrationWizardSteps(t, integrations)]);
     return {
         ...install.static,
         ...install.dynamic,
-        ...(folder ? renderSharedFolderUpgradeWizardFiles(pkg, folder) : {}),
+        ...renderUpgradeWizardFiles(pkg, folder, integrations),
     };
 }
 function portalManifest(portal) {

package/dist/standalone/manifest.d.ts

@@ -98,6 +98,12 @@ export interface StandaloneManifest {
     installSettings?: InstallSettings;
     /** Who may use the app at all; absent keeps the route policy alone. */
     entry?: EntryMode;
+    /**
+     * `integrations`: Go `api.HandleIntegration` methods that arrive without a
+     * DSM session, sorted. Exactly the `integration` permissions; the install
+     * and upgrade wizards list them for the administrator.
+     */
+    integrations?: string[];
     /** `portal`: registers the DSM Application Portal entry; an administrator activates it. */
     portal?: PortalDeclaration;
     /**

package/dist/standalone/manifest.js

@@ -1,5 +1,6 @@
 import { readInstallSettings } from './install-settings.js';
 import { auditGoRoutes } from './route-audit.js';
+import { BACKGROUND_WORKER_MAIN } from './background.js';
 import { isWebLaunchMode } from "../contract/web-launch.js";
 import { validWebAPIProfiles, } from "../runtime/webapi-profile.js";
 import { validateMetadata } from "../package-metadata.js";
@@ -20,7 +21,7 @@ import { readAppScripts } from "./app-scripts.js";
 import { readBackground } from "./background.js";
 import { DEFAULT_MIN_DSM, isDsmAtLeast, PORTAL_EXECUTOR_MIN_DSM, portalByExecutor, portalMinDsmMessage, } from "../build-spk/dsm-version.js";
 import { readSharedFolder } from "./shared-folder.js";
-import { API_PERMISSIONS_FILE, floorAtAdministrators, permitsOrdinaryUsers, readApiPermissions, } from "./api-permissions.js";
+import { API_PERMISSIONS_FILE, floorAtAdministrators, integrationMethods, permitsOrdinaryUsers, readApiPermissions, } from "./api-permissions.js";
 import { PORTAL_REQUIRES_EXECUTOR, portalEntryProblem, readPortalDeclaration, } from "../portal/alias.js";
 import { renderPackageIcons } from "../build-spk/dsm-icons.js";
 import { LOGIN_COLOR, loginImageProblem, } from "../build-spk/login-style.js";
@@ -58,6 +59,7 @@ export const KNOWN_FIELDS = new Set([
     "install",
     "uninstall",
     "entry",
+    "integrations",
     "portal",
     "console",
     "icon",
@@ -222,9 +224,11 @@ function readManifest(raw, c) {
             c.fail("STANDALONE_REQUEST_TIMEOUT_SHORT", problem);
     }
     let permissions;
+    let integrations;
     if (backend && backend.kind !== "binary") {
         try {
             permissions = readApiPermissions(backend, capabilities);
+            integrations = readIntegrations(raw.integrations, backend, permissions.policy, raw.compose !== undefined, c);
         }
         catch (error) {
             // The SDK's own routes come from its module; a failed download or an
@@ -354,11 +358,18 @@ function readManifest(raw, c) {
     }
     if (backend?.kind === "go" && permissions && sdkVersionOrUndefined(backend) && (raw.entry === undefined || entry)) {
         try {
-            const audit = auditGoRoutes(backend.dir, permissions.policy, permissions.sdk);
-            for (const problem of audit.problems)
+            const problems = new Set();
+            for (const main of [backend.main, ...(capabilities.jobs ? [BACKGROUND_WORKER_MAIN] : [])]) {
+                for (const arch of arches ?? []) {
+                    const audit = auditGoRoutes(backend.dir, permissions.policy, permissions.sdk, [main], [({ x86_64: 'amd64', aarch64: 'arm64', armv7: 'arm' })[arch]]);
+                    for (const problem of audit.problems)
+                        problems.add(problem);
+                    if (main === backend.main && entry && !audit.entryGate)
+                        c.fail("STANDALONE_ENTRY_UNSUPPORTED", "App entry requires an actual dsm.NewEntryGate call; comments do not enforce admission.");
+                }
+            }
+            for (const problem of problems)
                 c.fail("STANDALONE_API_REGISTRY_INVALID", problem);
-            if (entry && !audit.entryGate)
-                c.fail("STANDALONE_ENTRY_UNSUPPORTED", "App entry requires an actual dsm.NewEntryGate call; comments do not enforce admission.");
         }
         catch (error) {
             c.fail("STANDALONE_API_REGISTRY_INVALID", error.message);
@@ -500,6 +511,7 @@ function readManifest(raw, c) {
         ...(sharedFolder ? { sharedFolder } : {}),
         ...(installSettings ? { installSettings } : {}),
         ...(entry ? { entry } : {}),
+        ...(integrations?.length ? { integrations } : {}),
         ...(portal ? { portal } : {}),
         ...(dsmConsole ? { console: dsmConsole } : {}),
         ...(noWindow ? { sdkWindow: false } : {}),
@@ -659,6 +671,29 @@ function sdkVersionOrUndefined(backend) {
  * SDK gate and main wires it; `-X main.entry` on an older main would be
  * silently dropped and leave a registered app ungated.
  */
+/**
+ * `integrations` repeats, in dsm-package.yaml, every permissions.json method
+ * declared `integration`, so a callback that skips the DSM session is never
+ * added by the policy file alone. Only Go SDK servers implement it.
+ */
+function readIntegrations(value, backend, policy, compose, c) {
+    const declared = integrationMethods(policy);
+    if (value === undefined && declared.length === 0)
+        return undefined;
+    if (value === undefined)
+        value = [];
+    if (!Array.isArray(value) || value.some((v) => typeof v !== "string") || new Set(value).size !== value.length) {
+        return c.fail("STANDALONE_INTEGRATIONS_INVALID", "integrations must be a list of unique permissions.json method names.");
+    }
+    const listed = [...value].sort();
+    if (backend.kind !== "go" || compose) {
+        return c.fail("STANDALONE_INTEGRATIONS_INVALID", "integrations need a Go backend built with api.HandleIntegration.");
+    }
+    if (listed.join("\n") !== declared.join("\n")) {
+        return c.fail("STANDALONE_INTEGRATIONS_MISMATCH", `integrations must list exactly the permissions.json methods declared "integration" (${declared.join(", ") || "none"}); found ${listed.join(", ") || "none"}.`);
+    }
+    return listed;
+}
 function readEntry(value, backend, policy, c) {
     if (value !== "admin-only" && value !== "app-privilege") {
         return c.fail("STANDALONE_ENTRY_INVALID", "entry must be admin-only or app-privilege; omit it to keep the existing permissions.json behavior.");

package/dist/standalone/route-audit.d.ts

@@ -1,6 +1,12 @@
 import type { ApiPermissions } from './api-permissions.js';
-/** Parse Go syntax without executing an App's main, init functions or --describe. */
-export declare function auditGoRoutes(dir: string, policy: ApiPermissions, sdk: Record<string, Record<string, string>>): {
+export interface RouteAudit {
     problems: string[];
     entryGate: boolean;
-};
+    httpRoutes: {
+        prefix: string;
+        method: string;
+    }[];
+}
+export declare function httpRoutesDigest(audit: RouteAudit): string;
+/** Parse Go syntax without executing an App's main, init functions or --describe. */
+export declare function auditGoRoutes(dir: string, policy: ApiPermissions, sdk: Record<string, Record<string, string>>, roots?: string[], arches?: string[]): RouteAudit;

package/dist/standalone/route-audit.js

@@ -1,12 +1,16 @@
 import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { mkdtempSync, rmSync, realpathSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { goChildEnv } from '../runtime/go-env.js';
 let binary;
+export function httpRoutesDigest(audit) {
+    return createHash('sha256').update(JSON.stringify(audit.httpRoutes)).digest('hex');
+}
 /** Parse Go syntax without executing an App's main, init functions or --describe. */
-export function auditGoRoutes(dir, policy, sdk) {
+export function auditGoRoutes(dir, policy, sdk, roots = ['.'], arches = ['amd64', 'arm64', 'arm']) {
     const env = goChildEnv({ ...process.env, GOOS: undefined, GOARCH: undefined, GOARM: undefined, GOWORK: 'off', CGO_ENABLED: '0' });
     if (!binary) {
         const work = mkdtempSync(join(tmpdir(), 'synopkgland-route-audit-'));
@@ -18,7 +22,7 @@ export function auditGoRoutes(dir, policy, sdk) {
             throw new Error('Cannot build the Go route auditor; install Go and retry.');
         binary = out;
     }
-    const result = spawnSync(binary, [], { env, input: JSON.stringify({ Dir: realpathSync(dir), Permissions: policy.methods, SDK: sdk }), encoding: 'utf8', timeout: 30_000, maxBuffer: 4 << 20 });
+    const result = spawnSync(binary, [], { env, input: JSON.stringify({ Dir: realpathSync(dir), Roots: roots, Arches: arches, Permissions: policy.methods, SDK: sdk }), encoding: 'utf8', timeout: 120_000, maxBuffer: 4 << 20 });
     if (result.error || result.status !== 0)
         throw new Error(`Cannot audit Go routes: ${result.stderr?.trim() || 'auditor unavailable'}`);
     return JSON.parse(result.stdout);

package/dist/standalone/shared-folder.d.ts

@@ -1,6 +1,6 @@
 import type { StandaloneError } from "./manifest.js";
 import { type Translate } from "../build-spk/wizard-i18n.js";
-import type { InstallWizardStep } from "../build-spk/install-wizard.js";
+import { type InstallWizardStep } from "../build-spk/install-wizard.js";
 /**
  * `install.sharedFolder`: the Shared Folder a package keeps its files in.
  *
@@ -33,6 +33,11 @@ export declare function renderSharedFolderWizardFiles(pkg: string, folder: Share
 export declare function sharedFolderInstallSteps(pkg: string, folder: SharedFolder): (t: Translate) => InstallWizardStep[];
 /** The upgrade wizard files that let the administrator keep or change the shared folder. */
 export declare function renderSharedFolderUpgradeWizardFiles(pkg: string, folder: SharedFolder): Record<string, string>;
+/**
+ * The upgrade wizard: the shared folder choice, then the service callbacks an
+ * administrator re-approves on every upgrade. Empty without either.
+ */
+export declare function renderUpgradeWizardFiles(pkg: string, folder: SharedFolder | undefined, integrations?: readonly string[]): Record<string, string>;
 /** `conf/resource` `data-share` entry: create mode only; DSM never deletes the share on uninstall. */
 export declare function sharedFolderResource(pkg: string, folder: SharedFolder): Record<string, unknown> | undefined;
 /** The declaration an SPK's postinst carries, or undefined when it has none or it is no longer valid. */

package/dist/standalone/shared-folder.js

@@ -1,5 +1,6 @@
 import { sharedFolderCombobox } from "../build-spk/share-combobox.js";
 import { renderWizardFiles } from "../build-spk/wizard-i18n.js";
+import { integrationWizardSteps } from "../build-spk/install-wizard.js";
 const FIELDS = new Set(["mode", "key", "name", "permission"]);
 const KEY = /^[a-z][a-z0-9_]{0,31}$/;
 const RESERVED_KEY = /^(pkgwizard_|synopkg|change_)/;
@@ -123,6 +124,18 @@ export function sharedFolderInstallSteps(pkg, folder) {
 export function renderSharedFolderUpgradeWizardFiles(pkg, folder) {
     return renderWizardFiles("upgrade_uifile", t => [{ step_title: t("upgrade.step"), items: upgradeItems(t, pkg, folder) }]);
 }
+/**
+ * The upgrade wizard: the shared folder choice, then the service callbacks an
+ * administrator re-approves on every upgrade. Empty without either.
+ */
+export function renderUpgradeWizardFiles(pkg, folder, integrations = []) {
+    if (!folder && !integrations.length)
+        return {};
+    return renderWizardFiles("upgrade_uifile", t => [
+        ...(folder ? [{ step_title: t("upgrade.step"), items: upgradeItems(t, pkg, folder) }] : []),
+        ...integrationWizardSteps(t, integrations),
+    ]);
+}
 /** `conf/resource` `data-share` entry: create mode only; DSM never deletes the share on uninstall. */
 export function sharedFolderResource(pkg, folder) {
     if (folder.mode !== "create")

package/dist/standalone/spk.js

@@ -13,7 +13,7 @@ import { infoArchValue } from "../build-spk/dsm-arch.js";
 import { packageIcons, writeDsmWindowIcons, writePackageCenterIcons, } from "../build-spk/dsm-icons.js";
 import { renderNativePrivilege } from "../build-spk/native-lifecycle.js";
 import { renderUninstallWizardFiles } from "../build-spk/uninstall-wizard.js";
-import { renderInstallWizardFiles, renderNativeInstallWizard, } from "../build-spk/install-wizard.js";
+import { renderInstallWizardFiles, integrationWizardSteps, renderNativeInstallWizard, } from "../build-spk/install-wizard.js";
 import { writeWizardUiFiles, } from "../build-spk/wizard-i18n.js";
 import { renderDelegateScopeSteps } from "../build-spk/delegate-scope.js";
 import { createReproducibleTar } from "../build-spk/reproducible-archive.js";
@@ -40,7 +40,7 @@ import { portalByExecutor } from "../build-spk/dsm-version.js";
 import { PORTAL_JSON_RELPATH, PORTAL_MUSTACHE_RELPATH, renderPortalJson, renderPortalMustache, renderPortalWizardStep, } from "../portal/package.js";
 import { executorPlan, } from "../runtime/executor-build.js";
 import { EXECUTOR_ANCHOR } from "../runtime/executor-inspect.js";
-import { renderSharedFolderUpgradeWizardFiles, sharedFolderInstallSteps, } from "./shared-folder.js";
+import { renderUpgradeWizardFiles, sharedFolderInstallSteps, } from "./shared-folder.js";
 import { stateItemTexts, uninstallExecProblem, uninstallRecord, } from "./uninstall.js";
 const FILE_MODE = 0o644;
 const EXEC_MODE = 0o755;
@@ -237,6 +237,7 @@ export async function assembleStandaloneSpk(options) {
             schema: 2,
             ...(moduleVersion ? { ui_module: moduleVersion } : {}),
             ...(manifest.installSettings ? { installSettings: manifest.installSettings } : {}),
+            ...(manifest.integrations ? { integrations: manifest.integrations } : {}),
             ...(manifest.lifecycleTimeouts ? { lifecycleTimeouts: manifest.lifecycleTimeouts } : {}),
             ...("timeoutSeconds" in manifest.backend && manifest.backend.timeoutSeconds ? { operationSeconds: manifest.backend.timeoutSeconds } : {}),
             ...(options.apiDescription ? { ctl: { hash: options.apiDescription.sha256, registry: options.apiRegistry } } : {}),
@@ -295,13 +296,11 @@ export async function assembleStandaloneSpk(options) {
             : folder
                 ? sharedFolderInstallSteps(manifest.package, folder)
                 : renderNativeInstallWizard;
-        const install = renderInstallWizardFiles(manifest.package, (t) => [...steps(t), ...settingsInstallSteps(manifest.installSettings)(t), ...(portal ? [renderPortalWizardStep(t, portal.alias)] : [])]);
+        const install = renderInstallWizardFiles(manifest.package, (t) => [...steps(t), ...settingsInstallSteps(manifest.installSettings)(t), ...(portal ? [renderPortalWizardStep(t, portal.alias)] : []), ...integrationWizardSteps(t, manifest.integrations)]);
         writeWizardUiFiles(staging, {
             ...install.static,
             ...install.dynamic,
-            ...(folder
-                ? renderSharedFolderUpgradeWizardFiles(manifest.package, folder)
-                : {}),
+            ...renderUpgradeWizardFiles(manifest.package, folder, manifest.integrations),
             ...renderUninstallWizardFiles(manifest.package, "native", {
                 composeData: manifest.compose?.plan.app_data,
                 executor: Boolean(options.executor),

package/package.json

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