@synopackageland/cli 0.35.0 → 0.36.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.36.0 (2026-10-29)
+
+- Stop treating `net.Listener` and `net.ListenConfig` types as listeners.
+  Actual constructors, aliases and declared listener/server methods remain
+  rejected. Accept SDK child-port reservation/probe, named private HTTP servers
+  and peer-credential executor transport as explicit boundaries.
+- Add `audit-entry` for every custom-hook Go payload's own target import graph.
+  It never executes the App. Keep all files of imported shared packages in scope.
+- Bind ordinary CGI/workers to IPC tier `none`; only separately approved root
+  helper builds may use executor-tier peer serving. Update the App skill for
+  SDK/App 0.34.0, named data planes, child ports and helper boundaries.
+
+- Audit `(*api.Server).InvokeAsAdministrator` calls: each must name a literal
+  method declared `administrators` in permissions.json. Package commands outside
+  CGI use it instead of calling `ServeHTTP` on a server in process, which the
+  audit still rejects. Requires the SDK release with `InvokeAsAdministrator`.
+- Accept the `integration` permission for Go `api.HandleIntegration` service
+  callbacks. `dsm-package.yaml` `integrations` must list exactly those methods.
+  The route audit requires the constructor and permission together, admits only
+  the callback's handler graph, and binds each `?method=` selector into the
+  HTTP route inventory. The install and upgrade wizards list the callbacks for
+  administrator approval; `inspect` verifies them. Requires the SDK release
+  with `api.HandleIntegration`.
+- Stop the route audit from following a handler's receiver or parameter to
+  its type. A method value such as `cfg.serve` used to admit every method of
+  that type, which could hide an unregistered `ServeHTTP` dispatch elsewhere
+  on it.
+
 ## 0.35.0 (2026-10-29)
 
 - Audit the target Linux import graphs of configured Go binaries rather than

package/assets/go/route-audit/main.go

@@ -178,6 +178,12 @@ func boundaryHandlers(sources []source) map[ast.Node]bool {
 			case *ast.Ident:
 				key = s.pkg + "." + v.Name
 				if v.Obj != nil {
+					// A parameter or receiver carries a value built elsewhere.
+					// Following its type would admit every method of that type,
+					// such as an App Config whose method value is the handler.
+					if _, param := v.Obj.Decl.(*ast.Field); param {
+						return true
+					}
 					if d, ok := v.Obj.Decl.(ast.Node); ok {
 						mark(d)
 					}
@@ -196,6 +202,13 @@ func boundaryHandlers(sources []source) map[ast.Node]bool {
 	for _, s := range sources {
 		ast.Inspect(s.file, func(n ast.Node) bool {
 			call, ok := n.(*ast.CallExpr)
+			if ok && len(call.Args) == 2 {
+				if sel, ok := call.Fun.(*ast.SelectorExpr); ok {
+					if id, ok := sel.X.(*ast.Ident); ok && s.imports[id.Name] == sdkModule+"/api" && sel.Sel.Name == "HandleIntegration" {
+						mark(call.Args[1])
+					}
+				}
+			}
 			if !ok || len(call.Args) != 3 {
 				return true
 			}
@@ -205,7 +218,7 @@ func boundaryHandlers(sources []source) map[ast.Node]bool {
 			}
 			id, ok := sel.X.(*ast.Ident)
 			if ok && (s.imports[id.Name] == sdkModule+"/api" && sel.Sel.Name == "HandleHTTP" ||
-				s.imports[id.Name] == sdkModule+"/ipc" && sel.Sel.Name == "ServeUnix") {
+				s.imports[id.Name] == sdkModule+"/ipc" && (sel.Sel.Name == "ServeUnix" || sel.Sel.Name == "StartUnix")) {
 				mark(call.Args[2])
 			}
 			return true
@@ -300,6 +313,127 @@ func reusesBoundary(expr ast.Node, owner source, sources []source, safe map[ast.
 	return found
 }
 
+// Resolve declared receiver types without executing the App or requiring a
+// successful type check (the audit also runs while projects are being edited).
+func receiverType(expr ast.Node, src source, sources []source, seen map[ast.Node]bool) string {
+	if expr == nil || seen[expr] {
+		return ""
+	}
+	seen[expr] = true
+	follow := func(n ast.Node) string { return receiverType(n, src, sources, seen) }
+	find := func(pkg, name string) (ast.Node, source) {
+		for _, s := range sources {
+			if s.pkg != pkg {
+				continue
+			}
+			for _, decl := range s.file.Decls {
+				if fn, ok := decl.(*ast.FuncDecl); ok && fn.Recv == nil && fn.Name.Name == name {
+					return fn, s
+				}
+				if gen, ok := decl.(*ast.GenDecl); ok {
+					for _, spec := range gen.Specs {
+						if typ, ok := spec.(*ast.TypeSpec); ok && typ.Name.Name == name {
+							return typ, s
+						}
+						if value, ok := spec.(*ast.ValueSpec); ok {
+							for _, id := range value.Names {
+								if id.Name == name {
+									return id, s
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+		return nil, src
+	}
+	switch v := expr.(type) {
+	case *ast.ParenExpr:
+		return follow(v.X)
+	case *ast.StarExpr:
+		return follow(v.X)
+	case *ast.UnaryExpr:
+		return follow(v.X)
+	case *ast.CompositeLit:
+		return follow(v.Type)
+	case *ast.SelectorExpr:
+		if id, ok := v.X.(*ast.Ident); ok && src.imports[id.Name] != "" {
+			return src.imports[id.Name] + "." + v.Sel.Name
+		}
+		typ := follow(v.X)
+		if dot := strings.LastIndex(typ, "."); dot > 0 {
+			decl, owner := find(typ[:dot], typ[dot+1:])
+			if d, ok := decl.(*ast.TypeSpec); ok {
+				if st, ok := d.Type.(*ast.StructType); ok {
+					for _, field := range st.Fields.List {
+						for _, name := range field.Names {
+							if name.Name == v.Sel.Name {
+								return receiverType(field.Type, owner, sources, seen)
+							}
+						}
+					}
+				}
+			}
+		}
+	case *ast.Ident:
+		if v.Obj != nil {
+			switch d := v.Obj.Decl.(type) {
+			case *ast.Field:
+				return follow(d.Type)
+			case *ast.ValueSpec:
+				if d.Type != nil {
+					return follow(d.Type)
+				}
+				for i, name := range d.Names {
+					if name.Name == v.Name && i < len(d.Values) {
+						return follow(d.Values[i])
+					}
+				}
+			case *ast.AssignStmt:
+				for i, lhs := range d.Lhs {
+					if id, ok := lhs.(*ast.Ident); ok && id.Name == v.Name && i < len(d.Rhs) {
+						return follow(d.Rhs[i])
+					}
+				}
+			case *ast.TypeSpec:
+				if _, ok := d.Type.(*ast.StructType); ok {
+					return src.pkg + "." + d.Name.Name
+				}
+				return follow(d.Type)
+			}
+		} else {
+			decl, owner := find(src.pkg, v.Name)
+			return receiverType(decl, owner, sources, seen)
+		}
+	case *ast.TypeSpec:
+		if _, ok := v.Type.(*ast.StructType); ok {
+			return src.pkg + "." + v.Name.Name
+		}
+		return follow(v.Type)
+	case *ast.FuncDecl:
+		if v.Type.Results != nil && len(v.Type.Results.List) > 0 {
+			return follow(v.Type.Results.List[0].Type)
+		}
+	case *ast.CallExpr:
+		if id, ok := v.Fun.(*ast.Ident); ok && id.Name == "new" && len(v.Args) == 1 {
+			return follow(v.Args[0])
+		}
+		pkg, name := src.pkg, ""
+		switch fun := v.Fun.(type) {
+		case *ast.Ident:
+			name = fun.Name
+		case *ast.SelectorExpr:
+			if id, ok := fun.X.(*ast.Ident); ok {
+				pkg, name = src.imports[id.Name], fun.Sel.Name
+			}
+		}
+		decl, owner := find(pkg, name)
+		return receiverType(decl, owner, sources, seen)
+	}
+	return ""
+}
+
 func main() {
 	var in input
 	if err := json.NewDecoder(os.Stdin).Decode(&in); err != nil {
@@ -390,7 +524,7 @@ func main() {
 		}
 		ast.Inspect(file, func(n ast.Node) bool {
 			if fn, ok := n.(*ast.FuncDecl); ok && fn.Recv != nil && fn.Name.Name == "ServeHTTP" && !safe[n] {
-				problem(fn.Pos(), "unregistered ServeHTTP; use api.HandleHTTP or ipc.ServeUnix")
+				problem(fn.Pos(), "unregistered ServeHTTP; use api.HandleHTTP, api.HandleIntegration or ipc.ServeUnix")
 			}
 			selector, ok := n.(*ast.SelectorExpr)
 			if !ok {
@@ -399,26 +533,37 @@ func main() {
 			if selector.Sel.Name == "ServeHTTP" && !safe[n] {
 				problem(selector.Pos(), "unregistered ServeHTTP dispatch")
 			}
+			receiver := receiverType(selector.X, src, sources, map[ast.Node]bool{})
+			if receiver == "net.ListenConfig" && (selector.Sel.Name == "Listen" || selector.Sel.Name == "ListenPacket") ||
+				receiver == "net/http.Server" && (selector.Sel.Name == "Serve" || selector.Sel.Name == "ServeTLS" ||
+					selector.Sel.Name == "ListenAndServe" || selector.Sel.Name == "ListenAndServeTLS") {
+				problem(selector.Pos(), "custom listener outside SDK boundaries: "+selector.Sel.Name)
+			}
 			pkg, ok := selector.X.(*ast.Ident)
 			if !ok {
 				return true
 			}
 			module := imports[pkg.Name]
 			name := selector.Sel.Name
-			if module == "net" && (strings.HasPrefix(name, "Listen") || name == "FileListener" || name == "FilePacketConn") ||
+			if module == "net" && (name == "Listen" || name == "ListenTCP" || name == "ListenUnix" ||
+				name == "ListenPacket" || name == "ListenUDP" || name == "ListenIP" || name == "ListenUnixgram" ||
+				name == "FileListener" || name == "FilePacketConn") ||
 				module == "crypto/tls" && name == "Listen" ||
 				(module == "syscall" || module == "golang.org/x/sys/unix") && (name == "Bind" || name == "Listen" || name == "Socket") {
 				problem(selector.Pos(), "custom listener outside SDK boundaries: "+name)
 			}
-			if module == sdkModule+"/ipc" && name == "ServeUnix" && !direct[selector] {
-				problem(selector.Pos(), "IPC constructor aliases cannot be audited")
+			if module == sdkModule+"/ipc" && !direct[selector] {
+				switch name {
+				case "ServeUnix", "StartUnix", "ServePeerUnix", "DialUnix", "DialPeerUnix", "ReserveLoopback", "ProbeLoopback":
+					problem(selector.Pos(), "IPC constructor aliases cannot be audited")
+				}
 			}
 			if module == "github.com/synopackageland/syno-pkg-land-sdk/idgateway" && (name == "NewFront" || name == "Build" || name == "Run") {
 				problem(selector.Pos(), "gateway listeners must use identity_gateway in the manifest; upstream_auth_paths never exempts SDK RPC or custom HTTP handlers")
 			}
 			if module == "github.com/synopackageland/syno-pkg-land-sdk/api" {
 				switch name {
-				case "Handle", "HandleRequest", "HandleResponse", "HandleStream", "HandleRequestBatch", "HandleHTTP":
+				case "Handle", "HandleRequest", "HandleResponse", "HandleStream", "HandleRequestBatch", "HandleHTTP", "HandleIntegration":
 					if !direct[selector] {
 						problem(selector.Pos(), "route constructor aliases cannot be audited; register methods directly")
 					}
@@ -426,7 +571,7 @@ func main() {
 			}
 			if module == "net/http" {
 				switch name {
-				case "Handle", "HandleFunc", "Server", "Serve", "ServeTLS", "ListenAndServe", "ListenAndServeTLS":
+				case "Handle", "HandleFunc", "Serve", "ServeTLS", "ListenAndServe", "ListenAndServeTLS":
 					problem(selector.Pos(), "HTTP handler outside the SDK registry: "+name)
 				case "HandlerFunc", "NewServeMux", "ServeMux", "FileServer", "FileServerFS", "StripPrefix", "TimeoutHandler", "NotFoundHandler", "RedirectHandler":
 					if !safe[n] {
@@ -453,6 +598,26 @@ func main() {
 			if !ok {
 				return true
 			}
+			// An in-process administrator call names one fixed route that
+			// already requires DSM administrators; the SDK verifies the account.
+			if selector.Sel.Name == "InvokeAsAdministrator" {
+				method := ""
+				if len(call.Args) == 4 {
+					switch arg := call.Args[2].(type) {
+					case *ast.BasicLit:
+						if arg.Kind == token.STRING {
+							method, _ = strconv.Unquote(arg.Value)
+						}
+					case *ast.Ident:
+						method = constants[arg.Name]
+					}
+				}
+				if method == "" {
+					problem(call.Pos(), "dynamic InvokeAsAdministrator method cannot be audited; name a literal method")
+				} else if in.Permissions[method] != "administrators" {
+					problem(call.Pos(), "InvokeAsAdministrator requires a method declared administrators in permissions.json: "+method)
+				}
+			}
 			pkg, ok := selector.X.(*ast.Ident)
 			if !ok {
 				return true
@@ -468,7 +633,7 @@ func main() {
 				return true
 			}
 			switch selector.Sel.Name {
-			case "Handle", "HandleRequest", "HandleResponse", "HandleStream", "HandleRequestBatch", "HandleHTTP":
+			case "Handle", "HandleRequest", "HandleResponse", "HandleStream", "HandleRequestBatch", "HandleHTTP", "HandleIntegration":
 			default:
 				return true
 			}
@@ -492,6 +657,14 @@ func main() {
 			} else if _, declared := in.Permissions[method]; !declared && !sdk[method] {
 				problem(call.Pos(), "registered method missing from permissions.json: "+method)
 			}
+			// Only HandleIntegration skips the DSM session; the permission
+			// value and the constructor must agree in both directions.
+			if (selector.Sel.Name == "HandleIntegration") != (in.Permissions[method] == "integration") {
+				problem(call.Pos(), "the integration permission requires api.HandleIntegration, and api.HandleIntegration requires the integration permission")
+			}
+			if selector.Sel.Name == "HandleIntegration" && method != "" {
+				out.HTTPRoutes = append(out.HTTPRoutes, httpRoute{"?method=" + method, method})
+			}
 			if selector.Sel.Name == "HandleHTTP" {
 				prefix := ""
 				if len(call.Args) > 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-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

@@ -254,6 +254,7 @@ async function buildGoCgi(manifest, backend, arch, work, run) {
         `-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
@@ -314,6 +315,7 @@ async function buildBackgroundWorker(manifest, arch, work, run) {
         "-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}`,

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

@@ -21,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";
@@ -59,6 +59,7 @@ export const KNOWN_FIELDS = new Set([
     "install",
     "uninstall",
     "entry",
+    "integrations",
     "portal",
     "console",
     "icon",
@@ -223,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
@@ -508,6 +511,7 @@ function readManifest(raw, c) {
         ...(sharedFolder ? { sharedFolder } : {}),
         ...(installSettings ? { installSettings } : {}),
         ...(entry ? { entry } : {}),
+        ...(integrations?.length ? { integrations } : {}),
         ...(portal ? { portal } : {}),
         ...(dsmConsole ? { console: dsmConsole } : {}),
         ...(noWindow ? { sdkWindow: false } : {}),
@@ -667,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/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.35.0",
+  "version": "0.36.0",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {

package/skills/SKILL.md

@@ -5,7 +5,7 @@ description: Initialize, extend, check, build, inspect, and deploy Synology appl
 
 # Independent Synology SPKs
 
-CLI 0.35.0 installs templates through `~0.32.0`. A templates patch needs only a
+CLI 0.36.0 installs templates through `~0.32.0`. A templates patch needs only a
 templates release; npm install/update selects a patch in that minor line. The CLI
 uses the locally installed templates and reads their SDK pin for defaults; it
 never downloads templates at runtime. Preserve the lockfile and use `npm ci` for
@@ -24,7 +24,7 @@ Use this guide to initialize, build and inspect own applications or upstream OSS
 
 For an existing open-source App, first read [reference/upstream-fork.md](reference/upstream-fork.md): upstream fork/history + untouched upstream files + all packaging in `synology/`, official container images pinned by tag/index digest, native official release binaries pinned by SHA-256 or a source build hook, and a single tag-merge upgrade command. Use `init --upstream-fork`; never rewrite the App as a component. Integrated upstream Apps require direct DSM administrator entry without a separate App password or an OIDC/SSO server: supported trusted headers first, disabling native login second; the shipped OpenList pattern uses the existing SDK 0.17.3 token adapter (`mode: token`, `access: dsm-admins`, `entry: admin-only`) with server-side Authorization injection. All DSM admins share one upstream admin; token reset requires package restart; WebDAV retains its native credentials.
 
-Use SDK 0.33.0 and CLI 0.35.0 for App entry enforcement. Declare every App method
+Use SDK/App 0.34.0 and CLI 0.36.0 for App entry enforcement. Declare every App method
 in the permissions table; dynamic names and unregistered HTTP dispatchers are rejected.
 Use fixed SDK routes and `identity_gateway.upstream_auth_paths` for client API
 paths that rely on upstream authentication. Read
@@ -41,6 +41,36 @@ cannot upgrade a connection; use an existing upgrade-capable deployment
 transport. The audit follows each configured Go binary's Linux import graph,
 including declared workers; unshipped dev commands are excluded.
 
+Use `ipc.StartUnix(ctx, path, handler)` for multiple private data-plane sockets.
+Each direct `.sock` child of the package `var/run` gets an independent handle
+with Close, Shutdown and Wait. Stop/revoke closes active streams and hijacked
+connections, including WebSocket; keep target approval and pin checks in the
+handler. A private socket may serve the upstream root path without CGI.
+For official supervised children use `ipc.ReserveLoopback(ctx, 0)` to hold a
+127.0.0.1 TCP port, read Port/Address and Release immediately before starting
+the child. `ipc.ProbeLoopback(ctx, port)` checks a specific port without
+retaining it. Check child readiness and retry bind conflicts: release-to-bind
+is inherently racy. Never replace these with custom listeners or fixed ports.
+
+An optional root helper is a separately approved executor payload.
+`ipc.ServePeerUnix(ctx, path, ipc.PeerPolicy{UID: uid, GID: gid}, handler)`
+supports a bounded raw JSON control protocol on a root-owned 0660 socket under
+`/var/run/synopkgland/<package>/`. The SDK authenticates exactly the selected
+UID with SO_PEERCRED; the handler validates bounded frames and current
+authorization. `ipc.DialPeerUnix` verifies root ownership, protected ancestors,
+mode and server UID zero. The server requires root AND the helper's explicit
+`ipc.executorTier=executor` linker binding. Bind packageID in custom builds.
+Generated CGI/workers bind tier `none`; never launch or install them as root.
+The transport does not provide installation, approval or privilege elevation.
+
+Audit every custom-hook Go payload with
+`synopkgland audit-entry ./cmd/helper --dir backend --arch amd64,arm64,arm --json`
+before packaging. Use `--permissions` when it registers App methods.
+Each entry is checked against its actual target import graph, including every
+file of shared packages. Unused server functions have no exemption. Use real
+client/server packages or supported SDK boundaries; no App allowlists, hidden
+directories, aliases or ABI workarounds.
+
 **If you package someone else's open-source project, set `maintainer` to the
 original project/owner (prefer the project's own team/org name, else the owner's
 display name, else login), `metadata.maintainer_url` to the upstream repository,