@synopackageland/cli 0.35.0 → 0.37.0

package/dist/standalone/build.js

@@ -1,4 +1,5 @@
 import { buildInstallSettings } from './install-settings.js';
+import { buildAppBackup } from './hyper-backup.js';
 import { auditGoRoutes, httpRoutesDigest } from './route-audit.js';
 import { PORTAL_REQUIRES_EXECUTOR } from "../portal/alias.js";
 import { buildApiDescription } from "./api-description.js";
@@ -156,6 +157,7 @@ export async function buildStandalone(options) {
             const identityGateway = await buildIdentityGateway(manifest, arch, archWork, run);
             const composeControl = await buildComposeControl(manifest, arch, archWork, run);
             const installSettingsControl = await buildInstallSettings(manifest, arch, archWork, run);
+            const appBackupControl = await buildAppBackup(manifest, arch, archWork, run, (w) => warnings.add(w));
             const composeStorageInit = await buildComposeStorageInit(manifest, arch, archWork, run);
             // A portal needs the executor, so the executor's SDK carries the panel text.
             const portalText = manifest.portal && executor
@@ -171,6 +173,7 @@ export async function buildStandalone(options) {
                 composeControl,
                 composeStorageInit,
                 installSettingsControl,
+                appBackupControl,
                 backgroundWorker,
                 executor,
                 app,
@@ -254,6 +257,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 +318,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/hyper-backup.d.ts

@@ -0,0 +1,59 @@
+import type { StandaloneError, StandaloneManifest } from './manifest.js';
+import type { NativeArchFamily } from '../build-spk/dsm-arch.js';
+import type { CommandRunner } from './build.js';
+/**
+ * `backup`: Hyper Backup application backup. On by default for native Apps.
+ * Hyper Backup runs a package's backup scripts as root, so the scripts are a
+ * fixed template that only switches to the package account and moves one
+ * archive; the SDK control does the rest as the package account.
+ */
+export interface HyperBackup {
+    /** Export while the App runs; SQLite databases are then snapshotted. */
+    online: boolean;
+    /** "major.minor"; a backup restores into the same major and an equal or newer minor. */
+    dataVersion: string;
+    /** A package-relative executable run as `<hook> freeze` and `<hook> thaw` around an export. */
+    hook?: string;
+    /** The App declared `backup`; an SDK without the control is then an error, not a skip. */
+    explicit?: true;
+}
+export declare const DEFAULT_HYPER_BACKUP: HyperBackup;
+/** Hyper Backup's plugin folder inside the SPK. */
+export declare const BACKUP_SCRIPTS_DIR = "scripts/backup";
+/** The SDK control and its config inside the package payload. */
+export declare const BACKUP_PAYLOAD_DIR = "backup";
+export declare function readHyperBackup(value: unknown, context: {
+    compose?: boolean;
+}, fail: (e: StandaloneError) => void): HyperBackup | undefined;
+/** scripts/backup: framework 1.0, the offline/online choice and the two fixed scripts. */
+export declare function renderBackupScripts(b: Pick<HyperBackup, 'online' | 'dataVersion' | 'hook'>): {
+    version: string;
+    info: string;
+    export: string;
+    import: string;
+};
+export declare const BACKUP_SCRIPT_MODES: Record<string, number>;
+export declare function backupConfig(pkg: string, b: HyperBackup): string;
+/** What sdk-package.json records, without the build-only `explicit`. */
+export declare function backupRecord(b: HyperBackup): HyperBackup;
+export declare function readBackupRecord(value: unknown): HyperBackup | undefined;
+/**
+ * Builds the SDK backup control. An SDK release without it skips the default
+ * with a warning; an explicit `backup` declaration then fails.
+ */
+/** The Go package of the SDK backup control; tests use it to tell its build apart. */
+export declare const APP_BACKUP_CONTROL_PACKAGE = "./appbackup/cmd/control";
+export declare function buildAppBackup(m: StandaloneManifest, arch: NativeArchFamily, work: string, run: CommandRunner, warn: (w: string) => void): Promise<string | undefined>;
+/** The hook must be a packaged executable. */
+export declare function backupHookProblem(payload: string, b: HyperBackup): string | undefined;
+/**
+ * Inspect: the record, scripts/backup and payload backup/ must be exactly
+ * what build writes, or all absent. Any other file in scripts/backup — such
+ * as can_export or info.dynamic, which Hyper Backup runs as root while it only
+ * lists applications — is refused. The extracted scripts/backup is removed
+ * afterwards so later script checks see the lifecycle scripts alone.
+ */
+export declare function inspectHyperBackup(dir: string, payloadDir: () => Promise<string>, payload: Array<{
+    path: string;
+    mode: string;
+}>, raw: unknown, pkg: string, arch: NativeArchFamily, findings: string[]): Promise<HyperBackup | undefined>;

package/dist/standalone/hyper-backup.js

@@ -0,0 +1,180 @@
+import { existsSync, lstatSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { sdkSource } from '../runtime/sdk-source.js';
+import { goChildEnv } from '../runtime/go-env.js';
+import { pinnedGoBuildEnv, pinnedGoProblem } from '../build-spk/go-toolchain.js';
+import { checkCgiBinary } from './binary.js';
+import { StandaloneBuildError } from './spk.js';
+import { daemonSdkVersion, relativeExec } from './daemon.js';
+export const DEFAULT_HYPER_BACKUP = Object.freeze({ online: false, dataVersion: '1.0' });
+/** Hyper Backup's plugin folder inside the SPK. */
+export const BACKUP_SCRIPTS_DIR = 'scripts/backup';
+/** The SDK control and its config inside the package payload. */
+export const BACKUP_PAYLOAD_DIR = 'backup';
+const FIELDS = new Set(['hyper_backup', 'online', 'data_version', 'hook']);
+const DATA_VERSION = /^(0|[1-9][0-9]{0,3})\.(0|[1-9][0-9]{0,3})$/;
+const INVALID = 'backup accepts hyper_backup: false (opt out) or online (boolean), data_version ("major.minor", default "1.0") and hook (a fixed executable inside the package).';
+const record = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+export function readHyperBackup(value, context, fail) {
+    const bad = () => { fail({ code: 'BACKUP_INVALID', message: INVALID }); return undefined; };
+    if (value === undefined)
+        return context.compose ? undefined : DEFAULT_HYPER_BACKUP;
+    if (!record(value) || Object.keys(value).some(k => !FIELDS.has(k)))
+        return bad();
+    if (value.hyper_backup !== undefined && typeof value.hyper_backup !== 'boolean')
+        return bad();
+    if (value.hyper_backup === false)
+        return Object.keys(value).length === 1 ? undefined : bad();
+    if ((value.online !== undefined && typeof value.online !== 'boolean') ||
+        (value.data_version !== undefined && (typeof value.data_version !== 'string' || !DATA_VERSION.test(value.data_version))) ||
+        (value.hook !== undefined && !relativeExec(value.hook)))
+        return bad();
+    if (context.compose) {
+        fail({ code: 'BACKUP_COMPOSE_UNSUPPORTED', message: 'Hyper Backup application backup covers the package data folder; Compose App data lives in container volumes, so remove backup or set hyper_backup: false.' });
+        return undefined;
+    }
+    return { online: value.online === true, dataVersion: value.data_version ?? '1.0', ...(value.hook ? { hook: value.hook } : {}), explicit: true };
+}
+/**
+ * The root-run part. It reads Hyper Backup's temporary folder, refuses a
+ * root-owned data folder, switches to the data folder's owner (the package
+ * account) and lets that account write or read one archive. It never runs
+ * package content as root and never looks inside the archive. When Hyper
+ * Backup already runs it as another account, it skips the switch.
+ */
+function shim(action) {
+    const io = action === 'export' ? '> "$T/payload.tar"' : '< "$T/payload.tar"';
+    return `#!/bin/sh
+# Generated by synopkgland. Hyper Backup runs this as root. It only switches
+# to the package account and moves one archive; it never reads the archive.
+T=$(printf '%s' "$SYNOPKG_BKP_INPUT" | /usr/bin/jq -er .temp_path) || exit 1
+U=$(/usr/bin/stat -c %u:%g "$SYNOPKG_PKGVAR") || exit 1
+case $U in 0:*|*:0) exit 1 ;; esac
+if [ "$(/usr/bin/id -u)" = 0 ]; then RUN="/usr/bin/chroot --userspec=$U /"; else RUN=; fi
+$RUN /bin/sh -c 'exec "$SYNOPKG_PKGDEST/backup/control" ${action}' ${io} || exit 1
+printf '{"app_data_version":"1.0"}' > "$SYNOPKG_BKP_OUTPUT_PATH"
+`;
+}
+/** scripts/backup: framework 1.0, the offline/online choice and the two fixed scripts. */
+export function renderBackupScripts(b) {
+    return { version: '1.0\n', info: `{"online_backup":${b.online}}\n`, export: shim('export'), import: shim('import') };
+}
+export const BACKUP_SCRIPT_MODES = { version: 0o644, info: 0o644, export: 0o755, import: 0o755 };
+export function backupConfig(pkg, b) {
+    return JSON.stringify({ schema: 1, package: pkg, dataVersion: b.dataVersion, ...(b.online ? { online: true } : {}), ...(b.hook ? { hook: b.hook } : {}) }, null, 2) + '\n';
+}
+/** What sdk-package.json records, without the build-only `explicit`. */
+export function backupRecord(b) {
+    return { online: b.online, dataVersion: b.dataVersion, ...(b.hook ? { hook: b.hook } : {}) };
+}
+export function readBackupRecord(value) {
+    if (!record(value) || Object.keys(value).some(k => !['online', 'dataVersion', 'hook'].includes(k)) || typeof value.online !== 'boolean' ||
+        typeof value.dataVersion !== 'string' || !DATA_VERSION.test(value.dataVersion) || (value.hook !== undefined && !relativeExec(value.hook)))
+        return undefined;
+    return backupRecord(value);
+}
+/**
+ * Builds the SDK backup control. An SDK release without it skips the default
+ * with a warning; an explicit `backup` declaration then fails.
+ */
+/** The Go package of the SDK backup control; tests use it to tell its build apart. */
+export const APP_BACKUP_CONTROL_PACKAGE = './appbackup/cmd/control';
+export async function buildAppBackup(m, arch, work, run, warn) {
+    if (!m.hyperBackup)
+        return;
+    const source = sdkSource(daemonSdkVersion(m));
+    if (!existsSync(join(source.goDir, 'appbackup/cmd/control/main.go'))) {
+        const message = 'The selected SDK has no Hyper Backup application backup; use an SDK release with appbackup.';
+        if (m.hyperBackup.explicit)
+            throw new StandaloneBuildError('SDK_APP_BACKUP_UNSUPPORTED', message);
+        warn(`SDK_APP_BACKUP_UNSUPPORTED ${message} The package is built without application backup.`);
+        return;
+    }
+    const out = join(work, `app-backup-${arch}`);
+    const result = await run('go', ['build', '-trimpath', '-buildvcs=false', '-ldflags', '-s -w -buildid=', '-o', out, APP_BACKUP_CONTROL_PACKAGE], { cwd: source.goDir, env: goChildEnv({ ...process.env, ...pinnedGoBuildEnv(arch) }) });
+    if (result.missing && !m.hyperBackup.explicit) {
+        warn('SDK_APP_BACKUP_BUILD_FAILED Go was not found, so the package is built without application backup; install Go to include it.');
+        return;
+    }
+    if (result.status !== 0)
+        throw new StandaloneBuildError('SDK_APP_BACKUP_BUILD_FAILED', `Cannot build the SDK backup control: ${result.stderr}`);
+    const error = checkCgiBinary(work, out, arch), toolchain = pinnedGoProblem(out);
+    if (error || toolchain)
+        throw new StandaloneBuildError('SDK_APP_BACKUP_BUILD_FAILED', error?.message ?? toolchain);
+    return out;
+}
+/** The hook must be a packaged executable. */
+export function backupHookProblem(payload, b) {
+    if (!b.hook)
+        return;
+    const path = join(payload, b.hook);
+    try {
+        const s = lstatSync(path);
+        if (s.isFile() && (s.mode & 0o111) !== 0)
+            return;
+    }
+    catch { /* reported below */ }
+    return `backup.hook ${b.hook} is not an executable file in the package.`;
+}
+/**
+ * Inspect: the record, scripts/backup and payload backup/ must be exactly
+ * what build writes, or all absent. Any other file in scripts/backup — such
+ * as can_export or info.dynamic, which Hyper Backup runs as root while it only
+ * lists applications — is refused. The extracted scripts/backup is removed
+ * afterwards so later script checks see the lifecycle scripts alone.
+ */
+export async function inspectHyperBackup(dir, payloadDir, payload, raw, pkg, arch, findings) {
+    const fail = (m) => { findings.push(`BACKUP_INVALID ${m}`); };
+    const scripts = join(dir, BACKUP_SCRIPTS_DIR);
+    const present = payload.filter(p => p.path.startsWith(`${BACKUP_PAYLOAD_DIR}/`));
+    const b = raw === undefined ? undefined : readBackupRecord(raw);
+    if (raw !== undefined && !b)
+        fail('the hyperBackup record in sdk-package.json is not the one synopkgland build writes');
+    if (!b) {
+        if (lstatExists(scripts))
+            fail('scripts/backup is present without a backup declaration');
+        if (present.length)
+            fail('the payload has a backup folder without a backup declaration');
+        rmSync(scripts, { recursive: true, force: true });
+        return undefined;
+    }
+    const expected = renderBackupScripts(b);
+    const names = lstatExists(scripts) && lstatSync(scripts).isDirectory() ? readdirSync(scripts).sort() : [];
+    if (names.join() !== Object.keys(expected).sort().join())
+        fail(`scripts/backup must hold exactly export, import, info and version, found: ${names.join(', ') || 'none'}`);
+    for (const [name, text] of Object.entries(expected)) {
+        const path = join(scripts, name);
+        let s;
+        try {
+            s = lstatSync(path);
+        }
+        catch {
+            continue;
+        }
+        if (!s.isFile() || (s.mode & 0o777) !== BACKUP_SCRIPT_MODES[name] || readFileSync(path, 'utf8') !== text)
+            fail(`scripts/backup/${name} differs from the fixed script synopkgland build writes`);
+    }
+    const files = present.map(p => `${p.path}:${p.mode}`).sort();
+    const wanted = [`${BACKUP_PAYLOAD_DIR}/config.json:0644`, `${BACKUP_PAYLOAD_DIR}/control:0755`];
+    if (files.join() !== wanted.join())
+        fail('the payload backup folder must hold exactly the SDK control and config.json');
+    else {
+        const root = await payloadDir();
+        if (readFileSync(join(root, BACKUP_PAYLOAD_DIR, 'config.json'), 'utf8') !== backupConfig(pkg, b))
+            fail('backup/config.json differs from the backup declaration');
+        const error = checkCgiBinary(root, join(root, BACKUP_PAYLOAD_DIR, 'control'), arch);
+        if (error)
+            fail(error.message);
+    }
+    rmSync(scripts, { recursive: true, force: true });
+    return b;
+}
+function lstatExists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -3,12 +3,15 @@ import { type WebLaunchMode } from "../contract/web-launch.js";
 import { type ComposeApp } from "./compose.js";
 import { type ExecutorInspection } from "../runtime/executor-inspect.js";
 import { type AppScriptName } from "./app-scripts.js";
+import { type HyperBackup } from "./hyper-backup.js";
 import { type GatewayAdmissionReport } from "./identity-gateway.js";
 import type { EntryMode } from "./manifest.js";
 import { type UninstallCleanupItem } from "../runtime/uninstall-cleanup.js";
 export type SpkKind = "native-go" | "native-python" | "native-node" | "native-rust" | "binary" | "container" | "native-layout";
 export interface SpkInspection {
     installSettings?: InstallSettings;
+    /** Hyper Backup application backup, as sdk-package.json records it. */
+    hyperBackup?: HyperBackup;
     identityGateway?: GatewayAdmissionReport;
     kind?: SpkKind;
     package?: string;
@@ -50,6 +53,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

@@ -15,6 +15,7 @@ import { checkBridgeApp, checkBridgeExecutor } from "./inspect-bridge.js";
 import { inspectExecutor, inspectExecutorAnchor, } from "../runtime/executor-inspect.js";
 import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
 import { sdkScriptOf, unwrapAppScripts } from "./app-scripts.js";
+import { inspectHyperBackup } from "./hyper-backup.js";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import * as tar from "tar";
@@ -31,8 +32,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 +126,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,10 +141,21 @@ 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 hyperBackup = metadataText === undefined ? undefined : await inspectHyperBackup(dir, async () => {
+            const root = join(dir, "backup-inspection");
+            if (!existsSync(root)) {
+                mkdirSync(root);
+                await tar.x({ file: join(dir, "package.tgz"), cwd: root });
+            }
+            return root;
+        }, payload, metadata.hyperBackup, /^package="([^"]*)"$/m.exec(readOptional(join(dir, "INFO")) ?? "")?.[1] ?? "", familyOfArchToken(/^arch="([^"]*)"$/m.exec(readOptional(join(dir, "INFO")) ?? "")?.[1]?.split(/\s+/)[0] ?? "") ?? "x86_64", findings);
+        const integrations = metadata.integrations ?? [];
         if (metadata.compose !== undefined) {
             const result = await inspectUnifiedCompose(dir, payload, { ...metadata, installSettings }, findings);
             if (installSettings)
                 result.installSettings = installSettings;
+            if (hyperBackup)
+                result.hyperBackup = hyperBackup;
             if (identityGateway)
                 result.identityGateway = identityGateway;
             result.icon = inspectPackageIcons(dir, findings);
@@ -291,7 +305,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) {
@@ -304,6 +318,7 @@ export async function inspectSpk(spkPath, expectedKind) {
             kind,
             ...(identityGateway ? { identityGateway } : {}),
             ...(installSettings ? { installSettings } : {}),
+            ...(hyperBackup ? { hyperBackup } : {}),
             ...(launch ? { launch } : {}),
             icon,
             ...(executor ? { executor } : {}),
@@ -319,6 +334,7 @@ export async function inspectSpk(spkPath, expectedKind) {
                 }
                 : {}),
             ...(metadata.entry ? { entry: metadata.entry } : {}),
+            ...(integrations.length ? { integrations } : {}),
             ...(appScripts.length ? { appScripts } : {}),
             ...(loginStyle ? { loginStyle } : {}),
             ...(standalone
@@ -1365,7 +1381,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 +1407,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 +1479,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 +1488,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

@@ -13,6 +13,7 @@ import { type ComposeApp } from "./compose.js";
 import { type Daemon } from "./daemon.js";
 import { type IdentityGateway } from "./identity-gateway.js";
 import { type Uninstall } from "./uninstall.js";
+import { type HyperBackup } from "./hyper-backup.js";
 import { type AppScriptName } from "./app-scripts.js";
 import { type Background } from "./background.js";
 import { type SharedFolder } from "./shared-folder.js";
@@ -96,8 +97,16 @@ export interface StandaloneManifest {
     /** `install.sharedFolder`: the Shared Folder the install wizard selects or `data-share` creates. */
     sharedFolder?: SharedFolder;
     installSettings?: InstallSettings;
+    /** `backup`: Hyper Backup application backup; on by default for native Apps, absent when opted out. */
+    hyperBackup?: HyperBackup;
     /** 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

@@ -17,11 +17,12 @@ import { daemonRestartSdkProblem } from "./daemon-restart.js";
 import { daemonIngressMinDsmProblem } from "./daemon-ingress.js";
 import { readIdentityGateway, } from "./identity-gateway.js";
 import { readUninstall } from "./uninstall.js";
+import { readHyperBackup } from "./hyper-backup.js";
 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,7 +59,9 @@ export const KNOWN_FIELDS = new Set([
     "compose",
     "install",
     "uninstall",
+    "backup",
     "entry",
+    "integrations",
     "portal",
     "console",
     "icon",
@@ -223,9 +226,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
@@ -251,6 +256,7 @@ function readManifest(raw, c) {
         ? undefined
         : readSharedFolder(raw.install, (e) => c.fail(e.code, e.message));
     const installSettings = readInstallSettings(isRecord(raw.install) ? raw.install.settings : undefined, e => c.fail(e.code, e.message));
+    const hyperBackup = readHyperBackup(raw.backup, { compose: raw.compose !== undefined }, e => c.fail(e.code, e.message));
     const compose = arches &&
         readComposeApp(raw.compose, c.root, arches, (e) => c.fail(e.code, e.message), {
             package: packageId,
@@ -507,7 +513,9 @@ function readManifest(raw, c) {
         ...(uninstall ? { uninstall } : {}),
         ...(sharedFolder ? { sharedFolder } : {}),
         ...(installSettings ? { installSettings } : {}),
+        ...(hyperBackup ? { hyperBackup } : {}),
         ...(entry ? { entry } : {}),
+        ...(integrations?.length ? { integrations } : {}),
         ...(portal ? { portal } : {}),
         ...(dsmConsole ? { console: dsmConsole } : {}),
         ...(noWindow ? { sdkWindow: false } : {}),
@@ -667,6 +675,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.d.ts

@@ -18,6 +18,8 @@ export interface AssembleOptions {
     composeControl?: string;
     composeStorageInit?: string;
     installSettingsControl?: string;
+    /** The SDK backup control; absent builds without Hyper Backup application backup. */
+    appBackupControl?: string;
     /** The SDK identity gateway, required exactly when the manifest declares identity_gateway. */
     identityGateway?: string;
     /** The compiled background worker, required exactly when capabilities.jobs is enabled. */