pakstr 0.29.1 → 0.31.0

package/dist/desktop/linux.js

@@ -0,0 +1,425 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LINUX_ELECTRON_EXECUTABLES = exports.APPIMAGE_RUNTIME = exports.LINUX_PACKAGE_FORMATS = exports.LINUX_X64_TARGET = void 0;
+exports.linuxExecutableName = linuxExecutableName;
+exports.assertLinuxBuildHost = assertLinuxBuildHost;
+exports.linuxOutputPaths = linuxOutputPaths;
+exports.linuxPackagerOptions = linuxPackagerOptions;
+exports.packageLinuxApp = packageLinuxApp;
+exports.assertSquashfsTools = assertSquashfsTools;
+exports.pakstrCacheDir = pakstrCacheDir;
+exports.fetchAppImageRuntime = fetchAppImageRuntime;
+exports.linuxAppFiles = linuxAppFiles;
+exports.normalizeLinuxModes = normalizeLinuxModes;
+exports.expectedLinuxMode = expectedLinuxMode;
+exports.linuxDesktopEntry = linuxDesktopEntry;
+exports.verifyLinuxApp = verifyLinuxApp;
+exports.assertElfX64 = assertElfX64;
+exports.appImageOffset = appImageOffset;
+exports.validateLinuxZip = validateLinuxZip;
+exports.parseSquashfsListing = parseSquashfsListing;
+exports.assertSquashfsListing = assertSquashfsListing;
+exports.validateAppImage = validateAppImage;
+const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const promises_1 = require("stream/promises");
+const sharp_1 = __importDefault(require("sharp"));
+const unzipper_1 = __importDefault(require("unzipper"));
+const iconResolver_1 = require("../core/iconResolver");
+const process_1 = require("../runners/process");
+const artifacts_1 = require("./common/artifacts");
+const asar_1 = require("./common/asar");
+const electron_1 = require("./common/electron");
+const files_1 = require("./common/files");
+const fuses_1 = require("./common/fuses");
+const packager_1 = require("./common/packager");
+const stage_1 = require("./stage");
+const zip_1 = require("./zip");
+exports.LINUX_X64_TARGET = "linux-x64";
+/** Package formats a linux-x64 build writes. DEB and RPM would be added here. */
+exports.LINUX_PACKAGE_FORMATS = ["appimage", "zip"];
+/**
+ * The AppImage type 2 runtime: a static x86-64 ELF that mounts the appended
+ * squashfs with FUSE 3 and runs its AppRun. Pinned to a tagged release
+ * (GPG-signed upstream) by SHA-256.
+ */
+exports.APPIMAGE_RUNTIME = {
+    release: "20251108",
+    url: "https://github.com/AppImage/type2-runtime/releases/download/20251108/runtime-x86_64",
+    sha256: "2fca8b443c92510f1483a883f60061ad09b46b978b2631c807cd873a47ec260d",
+};
+/**
+ * Files of the pinned Electron that ship executable (0755); every other file
+ * is 0644. The app executable replaces `electron`. chrome-sandbox is never
+ * setuid: AppImage mounts and unpacked ZIPs cannot carry a root-owned setuid
+ * helper, so Chromium's sandbox relies on unprivileged user namespaces.
+ */
+exports.LINUX_ELECTRON_EXECUTABLES = ["chrome-sandbox", "chrome_crashpad_handler", "libffmpeg.so", "libvk_swiftshader.so", "libvulkan.so.1"];
+const SQUASHFS_OPTIONS = {
+    timeoutMs: 20 * 60_000,
+    timeoutHint: "mksquashfs or unsquashfs stopped responding; try again.",
+};
+// -quiet, -exit-on-error, zstd, and unsquashfs -offset are all in 4.5.
+const MIN_SQUASHFS_TOOLS = [4, 5];
+// 1980-01-01, the fixed time ZIP entries use: squashfs inode times are clamped to it.
+const SOURCE_DATE_EPOCH = "315532800";
+const ICON_SIZE = 256;
+const DEFAULT_ICON_PATH = path_1.default.resolve(__dirname, "../../assets/logo.png");
+/** The executable, desktop entry, and icon are named after the appId: unique, stable, and shell-safe. */
+function linuxExecutableName(app) {
+    return app.appId;
+}
+/** Symlinks and Unix modes are written on the build host, so Windows hosts are refused. */
+function assertLinuxBuildHost(platform = process.platform) {
+    if (platform === "win32") {
+        throw new Error("Linux desktop packages must be built on macOS or Linux (they need Unix file modes and symlinks)");
+    }
+}
+/** AppImage and portable ZIP next to build.out, named like the APK. */
+function linuxOutputPaths(buildOut, appId) {
+    const dir = (0, artifacts_1.desktopOutputDir)(buildOut);
+    return {
+        appimage: (0, artifacts_1.desktopArtifactPath)(dir, appId, exports.LINUX_X64_TARGET, ".AppImage"),
+        zip: (0, artifacts_1.desktopArtifactPath)(dir, appId, exports.LINUX_X64_TARGET, ".zip"),
+    };
+}
+/** @electron/packager options: the shared base (with the allowlist `ignore`) plus the appId-named executable. */
+function linuxPackagerOptions(options) {
+    const { stagingDir, outDir, electronZipDir, app } = options;
+    return {
+        ...(0, packager_1.basePackagerOptions)({ stagingDir, outDir, electronZipDir }),
+        platform: "linux",
+        arch: "x64",
+        name: app.appName,
+        executableName: linuxExecutableName(app),
+        appVersion: app.versionName,
+    };
+}
+/**
+ * Package the staged app as `<appId>` plus Electron's files, flip fuses,
+ * normalize modes, and validate it. Then write the portable ZIP and the
+ * AppImage, each validated from a fresh extraction. Returns paths in `workDir`.
+ */
+async function packageLinuxApp(options) {
+    const { stagingDir, workDir, app, configDir } = options;
+    assertLinuxBuildHost();
+    (0, stage_1.assertDesktopAppName)(app.appName);
+    for (const tool of ["mksquashfs", "unsquashfs"]) {
+        // unsquashfs -version exits with status 1, so only the output is checked.
+        const probe = (0, child_process_1.spawnSync)(tool, ["-version"], { encoding: "utf8", timeout: 30_000, stdio: ["ignore", "pipe", "pipe"] });
+        if (probe.error) {
+            throw new Error(`AppImages need squashfs-tools >= ${MIN_SQUASHFS_TOOLS.join(".")} (${tool}) on PATH: ` +
+                `brew install squashfs, or apt/dnf install squashfs-tools. ${probe.error.message}`);
+        }
+        assertSquashfsTools(probe.stdout, tool);
+    }
+    const runtime = await fetchAppImageRuntime();
+    const electronZip = await (0, electron_1.fetchElectronZip)(electron_1.LINUX_ELECTRON_ZIP);
+    const expectedFiles = linuxAppFiles((await unzipper_1.default.Open.file(electronZip)).files.map((file) => file.path), app);
+    const { appDir, productPath: exePath } = await (0, packager_1.runPackager)(linuxPackagerOptions({ stagingDir, outDir: path_1.default.join(workDir, "out"), electronZipDir: path_1.default.dirname(electronZip), app }), { name: linuxExecutableName(app), type: "file" });
+    await (0, fuses_1.flipDesktopFuses)(exePath);
+    normalizeLinuxModes(appDir);
+    await verifyLinuxApp(appDir, app, expectedFiles);
+    const zip = (0, artifacts_1.desktopArtifactPath)(workDir, app.appId, exports.LINUX_X64_TARGET, ".zip");
+    await (0, zip_1.zipDirectory)(appDir, zip, app.appName, { unixModes: true });
+    await validateLinuxZip(zip, app, expectedFiles, path_1.default.join(workDir, "verify-zip"));
+    // The validated folder becomes the AppDir root, with AppRun, the desktop entry, and the icon beside it.
+    const appDirRoot = path_1.default.join(workDir, "AppDir");
+    fs_1.default.renameSync(appDir, appDirRoot);
+    await writeAppDirMetadata(appDirRoot, app, configDir);
+    const squashfs = path_1.default.join(workDir, "app.squashfs");
+    (0, process_1.runProcess)("mksquashfs", [appDirRoot, squashfs, "-root-owned", "-noappend", "-no-xattrs", "-comp", "zstd", "-quiet", "-no-progress", "-exit-on-error"], { ...SQUASHFS_OPTIONS, env: { ...process.env, SOURCE_DATE_EPOCH } });
+    const appImage = (0, artifacts_1.desktopArtifactPath)(workDir, app.appId, exports.LINUX_X64_TARGET, ".AppImage");
+    fs_1.default.writeFileSync(appImage, runtime, { flag: "wx", mode: 0o755 });
+    await (0, promises_1.pipeline)(fs_1.default.createReadStream(squashfs), fs_1.default.createWriteStream(appImage, { flags: "a" }));
+    fs_1.default.chmodSync(appImage, 0o755);
+    await validateAppImage(appImage, app, expectedFiles, path_1.default.join(workDir, "verify-appimage"));
+    return { appimage: appImage, zip };
+}
+/** `mksquashfs -version` / `unsquashfs -version` print e.g. "mksquashfs version 4.6.1 (2023/03/25)". */
+function assertSquashfsTools(versionOutput, tool) {
+    const match = new RegExp(`^${tool} version (\\d+)\\.(\\d+)`).exec(versionOutput.trim());
+    const [major, minor] = match ? [Number(match[1]), Number(match[2])] : [0, 0];
+    const [minMajor, minMinor] = MIN_SQUASHFS_TOOLS;
+    if (major < minMajor || (major === minMajor && minor < minMinor)) {
+        throw new Error(`AppImages need squashfs-tools >= ${MIN_SQUASHFS_TOOLS.join(".")}, found ${JSON.stringify(versionOutput.trim().split("\n")[0])}`);
+    }
+}
+/** Per-user cache: $XDG_CACHE_HOME/pakstr, ~/Library/Caches/pakstr, or ~/.cache/pakstr. */
+function pakstrCacheDir(env = process.env, platform = process.platform) {
+    if (env.XDG_CACHE_HOME && path_1.default.isAbsolute(env.XDG_CACHE_HOME))
+        return path_1.default.join(env.XDG_CACHE_HOME, "pakstr");
+    return platform === "darwin" ? path_1.default.join(os_1.default.homedir(), "Library", "Caches", "pakstr") : path_1.default.join(os_1.default.homedir(), ".cache", "pakstr");
+}
+/** Download (or reuse the cached) pinned AppImage runtime and verify its SHA-256. */
+async function fetchAppImageRuntime(cacheDir = pakstrCacheDir()) {
+    const file = path_1.default.join(cacheDir, "appimage-runtime", exports.APPIMAGE_RUNTIME.release, "runtime-x86_64");
+    const cached = fs_1.default.lstatSync(file, { throwIfNoEntry: false })?.isFile() ? fs_1.default.readFileSync(file) : null;
+    if (cached && (0, files_1.sha256)(cached) === exports.APPIMAGE_RUNTIME.sha256)
+        return cached;
+    const response = await fetch(exports.APPIMAGE_RUNTIME.url, { signal: AbortSignal.timeout(120_000) });
+    if (!response.ok)
+        throw new Error(`Failed to download the AppImage runtime (HTTP ${response.status}): ${exports.APPIMAGE_RUNTIME.url}`);
+    const data = Buffer.from(await response.arrayBuffer());
+    if ((0, files_1.sha256)(data) !== exports.APPIMAGE_RUNTIME.sha256) {
+        throw new Error(`AppImage runtime download does not match the pinned checksum: ${exports.APPIMAGE_RUNTIME.url}`);
+    }
+    fs_1.default.mkdirSync(path_1.default.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs_1.default.writeFileSync(tmp, data);
+    fs_1.default.renameSync(tmp, file);
+    return data;
+}
+/** The packaged app's files: Electron's, with the renamed executable and app.asar for default_app.asar. */
+function linuxAppFiles(electronZipEntries, app) {
+    const files = electronZipEntries
+        .filter((entry) => !entry.endsWith("/"))
+        .map((entry) => (entry === "electron" ? linuxExecutableName(app) : entry === "resources/default_app.asar" ? "resources/app.asar" : entry));
+    for (const required of [linuxExecutableName(app), "resources/app.asar", ...exports.LINUX_ELECTRON_EXECUTABLES]) {
+        if (!files.includes(required))
+            throw new Error(`The Electron Linux release does not provide ${required}`);
+    }
+    return files.sort();
+}
+function listTree(root, relative = "") {
+    const entries = [];
+    for (const name of fs_1.default.readdirSync(path_1.default.join(root, relative)).sort()) {
+        const rel = relative ? `${relative}/${name}` : name;
+        const full = path_1.default.join(root, rel);
+        const stat = fs_1.default.lstatSync(full);
+        const mode = stat.mode & 0o7777;
+        if (stat.isDirectory()) {
+            entries.push({ path: rel, type: "dir", mode }, ...listTree(root, rel));
+        }
+        else if (stat.isFile()) {
+            entries.push({ path: rel, type: "file", mode });
+        }
+        else if (stat.isSymbolicLink()) {
+            entries.push({ path: rel, type: "symlink", mode, target: fs_1.default.readlinkSync(full) });
+        }
+        else {
+            entries.push({ path: rel, type: "other", mode });
+        }
+    }
+    return entries;
+}
+/** Directories (the app folder itself too) 0755; files 0755 if they were executable, else 0644. Nothing else is allowed. */
+function normalizeLinuxModes(appDir) {
+    // @electron/packager creates the app folder 0700.
+    fs_1.default.chmodSync(appDir, 0o755);
+    for (const entry of listTree(appDir)) {
+        if (entry.type !== "file" && entry.type !== "dir") {
+            throw new Error(`Unexpected ${entry.type} in the packaged app: ${entry.path}`);
+        }
+        fs_1.default.chmodSync(path_1.default.join(appDir, ...entry.path.split("/")), entry.type === "dir" || entry.mode & 0o111 ? 0o755 : 0o644);
+    }
+}
+/** The mode every packaged file must have. */
+function expectedLinuxMode(file, app) {
+    const executables = [linuxExecutableName(app), ...exports.LINUX_ELECTRON_EXECUTABLES];
+    return executables.includes(file) ? 0o755 : 0o644;
+}
+/**
+ * The AppDir root around the app files: AppRun -> the executable, the
+ * desktop entry, and the icon (.DirIcon -> it).
+ */
+async function writeAppDirMetadata(appDirRoot, app, configDir) {
+    const id = linuxExecutableName(app);
+    fs_1.default.symlinkSync(id, path_1.default.join(appDirRoot, "AppRun"));
+    fs_1.default.writeFileSync(path_1.default.join(appDirRoot, `${id}.desktop`), linuxDesktopEntry(app), { flag: "wx", mode: 0o644 });
+    const icon = await (0, iconResolver_1.resolveAppIcon)({ configDir, configuredIcon: app.icon, defaultIcon: DEFAULT_ICON_PATH });
+    console.log(`🖼️ Desktop icon source: ${icon.source} (${icon.path})`);
+    const iconFile = path_1.default.join(appDirRoot, `${id}.png`);
+    await (0, sharp_1.default)(icon.path)
+        .resize(ICON_SIZE, ICON_SIZE, { fit: "contain", background: { r: 0, g: 0, b: 0, alpha: 0 } })
+        .png()
+        .toFile(iconFile);
+    fs_1.default.chmodSync(iconFile, 0o644);
+    fs_1.default.symlinkSync(`${id}.png`, path_1.default.join(appDirRoot, ".DirIcon"));
+}
+/** Desktop entry string value: backslashes and a leading space escaped (no control characters reach it). */
+function desktopEntryString(value) {
+    return value.replace(/\\/g, "\\\\").replace(/^ /, "\\s");
+}
+/**
+ * The AppImage's desktop entry. StartupWMClass is the appId because the
+ * runtime names the Electron app after it (appConfig.applyAppIdentity), and
+ * Electron uses that name for the window class. No --no-sandbox in Exec:
+ * Chromium's sandbox stays on.
+ */
+function linuxDesktopEntry(app) {
+    const id = linuxExecutableName(app);
+    const comment = app.description?.replace(/[\s\u0000-\u001f\u007f]+/g, " ").trim();
+    return [
+        "[Desktop Entry]",
+        "Type=Application",
+        `Name=${desktopEntryString(app.appName)}`,
+        ...(comment ? [`Comment=${desktopEntryString(comment)}`] : []),
+        `Exec=${id}`,
+        `Icon=${id}`,
+        "Terminal=false",
+        "Categories=Utility;",
+        `StartupWMClass=${id}`,
+        `X-AppImage-Version=${desktopEntryString(app.versionName.replace(/[\s\u0000-\u001f\u007f]+/g, " "))}`,
+        "",
+    ].join("\n");
+}
+/**
+ * Executable, file set, modes, fuses, and packaged files of an app folder.
+ * `appImage` also expects the AppDir root entries next to the app files.
+ */
+async function verifyLinuxApp(appDir, app, expectedFiles, options = {}) {
+    const id = linuxExecutableName(app);
+    const tree = listTree(appDir);
+    const files = tree.filter((entry) => entry.type === "file").map((entry) => entry.path).sort();
+    const expected = [...expectedFiles, ...(options.appImage ? [`${id}.desktop`, `${id}.png`] : [])].sort();
+    const unexpected = files.filter((file) => !expected.includes(file));
+    const missing = expected.filter((file) => !files.includes(file));
+    if (unexpected.length > 0 || missing.length > 0) {
+        throw new Error(`Packaged Linux app files differ from Electron's: unexpected ${JSON.stringify(unexpected)}, missing ${JSON.stringify(missing)}`);
+    }
+    const expectedLinks = options.appImage ? { AppRun: id, ".DirIcon": `${id}.png` } : {};
+    const rootMode = fs_1.default.statSync(appDir).mode & 0o7777;
+    if (rootMode !== 0o755)
+        throw new Error(`The app folder has mode ${rootMode.toString(8)}, expected 755`);
+    for (const entry of tree) {
+        const actual = entry.mode.toString(8);
+        if (entry.type === "dir" && entry.mode !== 0o755)
+            throw new Error(`Directory ${entry.path} has mode ${actual}, expected 755`);
+        if (entry.type === "file") {
+            const mode = expectedLinuxMode(entry.path, app);
+            if (entry.mode !== mode)
+                throw new Error(`${entry.path} has mode ${actual}, expected ${mode.toString(8)}`);
+        }
+        if (entry.type === "symlink" && expectedLinks[entry.path] !== entry.target) {
+            throw new Error(`Unexpected symlink ${entry.path} -> ${entry.target}`);
+        }
+        if (entry.type === "other")
+            throw new Error(`Unexpected special file ${entry.path}`);
+    }
+    for (const [link, target] of Object.entries(expectedLinks)) {
+        if (!tree.some((entry) => entry.type === "symlink" && entry.path === link && entry.target === target)) {
+            throw new Error(`Missing symlink ${link} -> ${target}`);
+        }
+    }
+    const exePath = path_1.default.join(appDir, id);
+    assertElfX64((0, files_1.readHead)(exePath, 64), id);
+    await (0, fuses_1.verifyDesktopFuses)(exePath);
+    const asarPath = path_1.default.join(appDir, "resources", "app.asar");
+    await (0, asar_1.verifyAppAsar)(asarPath, app);
+    // Electron does not validate asar integrity on Linux; check the archive's own hashes at build time.
+    await (0, asar_1.assertAsarFileIntegrity)(asarPath);
+}
+/** A little-endian 64-bit x86-64 ELF. */
+function assertElfX64(head, name) {
+    const ok = head.length >= 64 &&
+        head.subarray(0, 4).equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46])) &&
+        head[4] === 2 &&
+        head[5] === 1 &&
+        head.readUInt16LE(18) === 0x3e;
+    if (!ok)
+        throw new Error(`${name} is not an x86-64 ELF executable`);
+}
+/**
+ * The squashfs offset of a type 2 AppImage: the runtime ELF ends where its
+ * section header table ends (the runtime computes it the same way), and the
+ * ELF identification carries the "AI" type-2 magic.
+ */
+function appImageOffset(head) {
+    assertElfX64(head, "AppImage");
+    if (head.toString("latin1", 8, 11) !== "AI\x02")
+        throw new Error("Not a type 2 AppImage (missing AI\\x02 magic)");
+    const sectionHeaders = Number(head.readBigUInt64LE(0x28));
+    return sectionHeaders + head.readUInt16LE(0x3a) * head.readUInt16LE(0x3c);
+}
+/** Extract the portable ZIP and check it holds exactly `<appName>/` with the validated app and its modes. */
+async function validateLinuxZip(zipPath, app, expectedFiles, extractDir) {
+    const extracted = await (0, zip_1.verifyPortableZip)(zipPath, extractDir, app.appName, expectedFiles);
+    await verifyLinuxApp(extracted, app, expectedFiles);
+}
+/** Parse `unsquashfs -lln` lines: "-rwxr-xr-x 0/0 15216 1980-01-01 00:00 squashfs-root/chrome-sandbox". */
+function parseSquashfsListing(output) {
+    const entries = [];
+    for (const line of output.split("\n")) {
+        const match = /^([-dlbcps][-rwxsStT]{9}) (\d+)\/(\d+) +\d+ \S+ \S+ squashfs-root(\/.*?)?(?: -> (.*))?$/.exec(line);
+        if (!match)
+            continue;
+        entries.push({ mode: match[1], uid: Number(match[2]), gid: Number(match[3]), path: (match[4] ?? "/").slice(1), target: match[5] });
+    }
+    return entries;
+}
+/** Root-owned, the expected modes, and only the AppDir symlinks: what the AppImage mounts. */
+function assertSquashfsListing(entries, app, expectedFiles) {
+    const id = linuxExecutableName(app);
+    const links = { AppRun: id, ".DirIcon": `${id}.png` };
+    const files = [...expectedFiles, `${id}.desktop`, `${id}.png`];
+    if (entries.length === 0)
+        throw new Error("The AppImage filesystem listing is empty");
+    for (const entry of entries) {
+        const where = entry.path || "/";
+        if (entry.uid !== 0 || entry.gid !== 0)
+            throw new Error(`AppImage entry ${where} is owned by ${entry.uid}:${entry.gid}, expected root`);
+        let expected;
+        if (entry.path in links) {
+            if (!entry.mode.startsWith("l") || entry.target !== links[entry.path]) {
+                throw new Error(`AppImage ${entry.path} must be a symlink to ${links[entry.path]}`);
+            }
+            // Symlink permission bits are host-dependent and ignored by Linux.
+            continue;
+        }
+        else if (files.includes(entry.path)) {
+            expected = expectedLinuxMode(entry.path, app) === 0o755 ? "-rwxr-xr-x" : "-rw-r--r--";
+        }
+        else if (entry.mode.startsWith("d")) {
+            expected = "drwxr-xr-x";
+        }
+        else {
+            throw new Error(`Unexpected AppImage entry ${where}`);
+        }
+        if (entry.mode !== expected)
+            throw new Error(`AppImage entry ${where} has mode ${entry.mode}, expected ${expected}`);
+    }
+    for (const required of [...Object.keys(links), ...files]) {
+        if (!entries.some((entry) => entry.path === required))
+            throw new Error(`AppImage is missing ${required}`);
+    }
+}
+/**
+ * The AppImage is the pinned runtime followed by a squashfs whose listing
+ * and fresh extraction match the validated app plus the AppDir metadata.
+ */
+async function validateAppImage(appImagePath, app, expectedFiles, extractDir) {
+    if ((fs_1.default.statSync(appImagePath).mode & 0o777) !== 0o755)
+        throw new Error("The AppImage must be mode 755");
+    const head = (0, files_1.readHead)(appImagePath, 64);
+    const offset = appImageOffset(head);
+    const prefix = Buffer.alloc(offset + 4);
+    const fd = fs_1.default.openSync(appImagePath, "r");
+    try {
+        fs_1.default.readSync(fd, prefix, 0, prefix.length, 0);
+    }
+    finally {
+        fs_1.default.closeSync(fd);
+    }
+    if ((0, files_1.sha256)(prefix.subarray(0, offset)) !== exports.APPIMAGE_RUNTIME.sha256)
+        throw new Error("The AppImage runtime is not the pinned type 2 runtime");
+    if (prefix.toString("latin1", offset, offset + 4) !== "hsqs")
+        throw new Error("No squashfs filesystem after the AppImage runtime");
+    const listing = (0, process_1.runProcess)("unsquashfs", ["-lln", "-o", String(offset), appImagePath], SQUASHFS_OPTIONS).stdout;
+    assertSquashfsListing(parseSquashfsListing(listing), app, expectedFiles);
+    (0, process_1.runProcess)("unsquashfs", ["-o", String(offset), "-d", extractDir, "-no-xattrs", "-quiet", "-no-progress", appImagePath], SQUASHFS_OPTIONS);
+    const id = linuxExecutableName(app);
+    if (fs_1.default.readFileSync(path_1.default.join(extractDir, `${id}.desktop`), "utf8") !== linuxDesktopEntry(app)) {
+        throw new Error("The AppImage desktop entry does not match the app");
+    }
+    const icon = await (0, sharp_1.default)(path_1.default.join(extractDir, `${id}.png`)).metadata();
+    if (icon.format !== "png" || icon.width !== ICON_SIZE || icon.height !== ICON_SIZE) {
+        throw new Error(`The AppImage icon must be a ${ICON_SIZE}x${ICON_SIZE} PNG`);
+    }
+    await verifyLinuxApp(extractDir, app, expectedFiles, { appImage: true });
+}

package/dist/desktop/macos.js

@@ -0,0 +1,125 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MACOS_ARM64_TARGET = void 0;
+exports.macosBundleId = macosBundleId;
+exports.macosPackagerOptions = macosPackagerOptions;
+exports.packageMacosApp = packageMacosApp;
+exports.validateMacosZip = validateMacosZip;
+exports.verifyMacosApp = verifyMacosApp;
+exports.assertAdHocSignature = assertAdHocSignature;
+exports.assertInfoPlist = assertInfoPlist;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const process_1 = require("../runners/process");
+const artifacts_1 = require("./common/artifacts");
+const asar_1 = require("./common/asar");
+const electron_1 = require("./common/electron");
+const fuses_1 = require("./common/fuses");
+const packager_1 = require("./common/packager");
+exports.MACOS_ARM64_TARGET = "macos-arm64";
+/**
+ * macOS CFBundleIdentifier for an appId. Bundle identifiers allow only
+ * letters, digits, hyphens, and periods; appIds cannot contain hyphens, so
+ * mapping `_` to `-` is reversible and never collides.
+ */
+function macosBundleId(appId) {
+    return appId.replace(/_/g, "-");
+}
+const MACOS_TOOL_OPTIONS = {
+    timeoutMs: 10 * 60_000,
+    timeoutHint: "codesign or ditto stopped responding; try again.",
+};
+/**
+ * @electron/packager options: the shared base (with the allowlist `ignore`)
+ * plus the bundle identity. No signing here: fuses are flipped first, then
+ * the whole bundle is ad-hoc signed.
+ */
+function macosPackagerOptions(options) {
+    const { stagingDir, outDir, electronZipDir, app } = options;
+    return {
+        ...(0, packager_1.basePackagerOptions)({ stagingDir, outDir, electronZipDir }),
+        platform: "darwin",
+        arch: "arm64",
+        name: app.appName,
+        appBundleId: macosBundleId(app.appId),
+        appVersion: app.versionName,
+        buildVersion: String(app.versionCode),
+    };
+}
+/**
+ * Package the staged app as `<appName>.app`, flip fuses, ad-hoc sign, zip
+ * with ditto (which keeps the framework symlinks and signatures intact), and
+ * validate a fresh extraction of the ZIP. Returns the ZIP path in `workDir`.
+ */
+async function packageMacosApp(options) {
+    const { stagingDir, workDir, app } = options;
+    const electronZip = await (0, electron_1.fetchElectronZip)(electron_1.MACOS_ELECTRON_ZIP);
+    const { productPath: appPath } = await (0, packager_1.runPackager)(macosPackagerOptions({ stagingDir, outDir: path_1.default.join(workDir, "out"), electronZipDir: path_1.default.dirname(electronZip), app }), { name: `${app.appName}.app`, type: "directory" });
+    await (0, fuses_1.flipDesktopFuses)(appPath);
+    (0, process_1.runProcess)("codesign", ["--force", "--deep", "--sign", "-", appPath], MACOS_TOOL_OPTIONS);
+    const zipPath = (0, artifacts_1.desktopArtifactPath)(workDir, app.appId, exports.MACOS_ARM64_TARGET, ".zip");
+    (0, process_1.runProcess)("ditto", ["-c", "-k", "--sequesterRsrc", "--keepParent", appPath, zipPath], MACOS_TOOL_OPTIONS);
+    await validateMacosZip(zipPath, app, path_1.default.join(workDir, "verify"));
+    return zipPath;
+}
+/** Extract the ZIP and check it holds exactly the expected, intact app bundle. */
+async function validateMacosZip(zipPath, app, extractDir) {
+    fs_1.default.mkdirSync(extractDir);
+    (0, process_1.runProcess)("ditto", ["-x", "-k", zipPath, extractDir], MACOS_TOOL_OPTIONS);
+    const entries = fs_1.default.readdirSync(extractDir);
+    if (entries.length !== 1 || entries[0] !== `${app.appName}.app`) {
+        throw new Error(`macOS package must contain only ${app.appName}.app, found: ${entries.join(", ")}`);
+    }
+    await verifyMacosApp(path_1.default.join(extractDir, entries[0]), app);
+}
+/** Signature, Info.plist, fuses, and packaged files of an app bundle. */
+async function verifyMacosApp(appPath, app) {
+    (0, process_1.runProcess)("codesign", ["--verify", "--deep", "--strict", appPath], MACOS_TOOL_OPTIONS);
+    const display = (0, process_1.runProcess)("codesign", ["--display", "--verbose=2", appPath], MACOS_TOOL_OPTIONS);
+    assertAdHocSignature(`${display.stderr}\n${display.stdout}`, macosBundleId(app.appId));
+    const infoPlist = (0, process_1.runProcess)("plutil", ["-convert", "json", "-o", "-", path_1.default.join(appPath, "Contents", "Info.plist")], MACOS_TOOL_OPTIONS);
+    assertInfoPlist(JSON.parse(infoPlist.stdout), app);
+    await (0, fuses_1.verifyDesktopFuses)(appPath);
+    const resources = path_1.default.join(appPath, "Contents", "Resources");
+    for (const unpacked of ["app", "app.asar.unpacked"]) {
+        if (fs_1.default.existsSync(path_1.default.join(resources, unpacked)))
+            throw new Error(`Unexpected ${unpacked} next to app.asar`);
+    }
+    await (0, asar_1.verifyAppAsar)(path_1.default.join(resources, "app.asar"), app);
+}
+/** Parse `codesign --display --verbose=2`: an ad-hoc, arm64, resource-sealed signature for the bundle id. */
+function assertAdHocSignature(display, bundleId) {
+    const lines = display.split("\n").map((line) => line.trim());
+    const value = (key) => lines.find((line) => line.startsWith(`${key}=`))?.slice(key.length + 1);
+    const problems = [
+        value("Identifier") === bundleId ? null : `identifier is ${value("Identifier") ?? "missing"}, expected ${bundleId}`,
+        value("Signature") === "adhoc" ? null : "signature is not ad-hoc",
+        value("Format")?.includes("arm64") ? null : "binary is not arm64",
+        value("TeamIdentifier") === "not set" ? null : "unexpected team identifier",
+        // An unsealed bundle prints "Sealed Resources=none".
+        lines.some((line) => /^Sealed Resources version=\d+ /.test(line)) ? null : "resources are not sealed",
+    ].filter(Boolean);
+    if (problems.length > 0)
+        throw new Error(`Invalid macOS code signature: ${problems.join("; ")}`);
+}
+function assertInfoPlist(plist, app) {
+    const expected = {
+        CFBundleIdentifier: macosBundleId(app.appId),
+        CFBundleExecutable: app.appName,
+        CFBundleName: app.appName,
+        CFBundleShortVersionString: app.versionName,
+        CFBundleVersion: String(app.versionCode),
+    };
+    for (const [key, value] of Object.entries(expected)) {
+        if (plist[key] !== value)
+            throw new Error(`Info.plist ${key} is ${JSON.stringify(plist[key])}, expected ${JSON.stringify(value)}`);
+    }
+    const integrity = plist.ElectronAsarIntegrity;
+    const entry = integrity?.["Resources/app.asar"];
+    if (!integrity || Object.keys(integrity).length !== 1 || entry?.algorithm !== "SHA256" || typeof entry.hash !== "string" || !entry.hash) {
+        throw new Error("Info.plist lacks ElectronAsarIntegrity for Resources/app.asar");
+    }
+}

package/dist/desktop/stage.js

@@ -0,0 +1,117 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DESKTOP_RUNTIME_DIST = exports.DESKTOP_RUNTIME_FILES = exports.DESKTOP_DESCRIPTOR_FILE = void 0;
+exports.isAllowedAppPath = isAllowedAppPath;
+exports.assertDesktopAppName = assertDesktopAppName;
+exports.desktopOutputPath = desktopOutputPath;
+exports.stageDesktopApp = stageDesktopApp;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const androidProject_1 = require("../core/androidProject");
+const artifacts_1 = require("./common/artifacts");
+/**
+ * Desktop app layout shared with desktop-runtime/src/appConfig.js:
+ *
+ *   package.json          "main" -> runtime/main.js
+ *   pakstr-desktop.json   { appId, appName } (the runtime derives userData from appId)
+ *   runtime/              the bundled runtime (main.js, preload.js)
+ *   web/                  the built web app plus generated runtime config
+ *
+ * Nothing else is ever staged or packaged.
+ */
+exports.DESKTOP_DESCRIPTOR_FILE = "pakstr-desktop.json";
+exports.DESKTOP_RUNTIME_FILES = ["main.js", "preload.js"];
+const ALLOWED_FILES = new Set([
+    "/package.json",
+    `/${exports.DESKTOP_DESCRIPTOR_FILE}`,
+    "/runtime",
+    ...exports.DESKTOP_RUNTIME_FILES.map((file) => `/runtime/${file}`),
+    "/web",
+]);
+/** Runtime bundle built by the CLI's `npm run build` and shipped in the npm package. */
+exports.DESKTOP_RUNTIME_DIST = path_1.default.resolve(__dirname, "../../desktop-runtime/dist");
+/** OS metadata files that are skipped rather than packaged. */
+const JUNK_FILES = new Set([".DS_Store", "Thumbs.db", "desktop.ini"]);
+/** Names that look like credentials or repository data: refuse to package them. */
+const FORBIDDEN_WEB_ENTRY = /^(\.env(\..*)?|\.git|\.npmrc|\.netrc|\.ssh|.*\.(pem|key|p12|pfx|jks|keystore))$/i;
+/**
+ * Whether an app-relative POSIX path (leading "/") belongs to the layout. Used
+ * as the packager ignore filter and to validate the packaged asar.
+ */
+function isAllowedAppPath(appPath) {
+    return ALLOWED_FILES.has(appPath) || appPath.startsWith("/web/");
+}
+/** The appName becomes the .app and executable file names. */
+function assertDesktopAppName(appName) {
+    if (appName !== appName.trim() ||
+        appName.length === 0 ||
+        appName.length > 200 ||
+        appName.startsWith(".") ||
+        /[/\\:\u0000-\u001f\u007f]/.test(appName)) {
+        throw new Error(`app.appName "${appName}" cannot be used as a desktop app name: it must not be blank, ` +
+            "start with '.', or contain '/', '\\', ':' or control characters");
+    }
+}
+/** Output ZIP next to build.out, named like the APK: <appId>-<target>.zip. */
+function desktopOutputPath(buildOut, appId, target) {
+    return (0, artifacts_1.desktopArtifactPath)((0, artifacts_1.desktopOutputDir)(buildOut), appId, target, ".zip");
+}
+/** Write the allowlisted app layout into an empty `stagingDir`. */
+function stageDesktopApp(options) {
+    const { stagingDir, webDir, app, runtime = {}, runtimeDistDir = exports.DESKTOP_RUNTIME_DIST } = options;
+    assertDesktopAppName(app.appName);
+    if (fs_1.default.readdirSync(stagingDir).length > 0)
+        throw new Error(`Desktop staging directory is not empty: ${stagingDir}`);
+    const runtimeDir = path_1.default.join(stagingDir, "runtime");
+    fs_1.default.mkdirSync(runtimeDir);
+    for (const file of exports.DESKTOP_RUNTIME_FILES) {
+        const source = path_1.default.join(runtimeDistDir, file);
+        const stat = fs_1.default.lstatSync(source, { throwIfNoEntry: false });
+        if (!stat?.isFile()) {
+            throw new Error(`Desktop runtime bundle not found: ${source}. ` +
+                "This pakstr installation is incomplete; from a source checkout, run `npm --prefix packages/cli run build`.");
+        }
+        fs_1.default.copyFileSync(source, path_1.default.join(runtimeDir, file));
+    }
+    const webTarget = path_1.default.join(stagingDir, "web");
+    fs_1.default.mkdirSync(webTarget);
+    copyWebAssets(path_1.default.resolve(webDir), webTarget, "");
+    (0, androidProject_1.generateRuntimeConfig)(webTarget, runtime);
+    writeJson(path_1.default.join(stagingDir, exports.DESKTOP_DESCRIPTOR_FILE), { appId: app.appId, appName: app.appName });
+    writeJson(path_1.default.join(stagingDir, "package.json"), {
+        name: app.appId,
+        productName: app.appName,
+        version: app.versionName,
+        private: true,
+        main: "runtime/main.js",
+    });
+}
+/** Copy regular files and directories only; never follow or package symlinks. */
+function copyWebAssets(source, target, relative) {
+    for (const entry of fs_1.default.readdirSync(source, { withFileTypes: true })) {
+        const entryRelative = relative ? `${relative}/${entry.name}` : entry.name;
+        if (JUNK_FILES.has(entry.name))
+            continue;
+        if (FORBIDDEN_WEB_ENTRY.test(entry.name)) {
+            throw new Error(`Refusing to package web/${entryRelative}: it looks like a secret or repository file`);
+        }
+        const from = path_1.default.join(source, entry.name);
+        const to = path_1.default.join(target, entry.name);
+        if (entry.isDirectory()) {
+            fs_1.default.mkdirSync(to);
+            copyWebAssets(from, to, entryRelative);
+        }
+        else if (entry.isFile()) {
+            fs_1.default.copyFileSync(from, to, fs_1.default.constants.COPYFILE_EXCL);
+        }
+        else {
+            throw new Error(`Refusing to package web/${entryRelative}: only regular files and directories are allowed`);
+        }
+    }
+}
+function writeJson(file, value) {
+    fs_1.default.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`, { flag: "wx" });
+}