@nwutils/packager 0.3.0 → 0.5.0

package/README.md

@@ -21,8 +21,7 @@ Supported output formats, selected via `format`:
 
 ## Usage
 
-This composes with `@nwutils/builder`: run it against the `outDir` (and `app.name`)
-that `@nwutils/builder` produced.
+Build the application.
 
 ```js
 import build from "@nwutils/builder";
@@ -41,33 +40,71 @@ await build({
     categories: "Utility;",
   },
 });
+```
+
+### AppImage
 
+```js
 const appImagePath = await packager({
   format: "AppImage",
   appDir: "./out",
   appName: "Demo",
   cacheDir: "./cache",
   outDir: "./dist",
+  sign: true,
+  signKey: "ABCDEF1234567890",
 });
 
 console.log(`AppImage written to ${appImagePath}`);
 ```
 
-`packager({ format, ...options })` dispatches to the packager for `format` -
-`options` is whatever that packager expects (see `appImage(options)` below).
-Passing a `format` that isn't `"AppImage"` yet throws a clear "not implemented
-yet" error rather than doing nothing. `appImage` is also exported directly, if
-you'd rather skip the dispatch and know you only ever target AppImage.
+Signing needs `gpg` installed on the host and the secret key imported into its
+keyring. If the key is protected by a passphrase, set it in the
+`APPIMAGETOOL_SIGN_PASSPHRASE` environment variable
+
+### Self updating AppImages
+
+Set `publish` to where releases are uploaded, and `version` to the app's
+version. This follows electron-builder's approach:
+
+- an `app-update.yml` describing `publish` is embedded next to the NW.js
+  executable inside the AppImage, so the running app knows where to look
+- a `latest-linux.yml` update info file (`latest-linux-<arch>.yml` for
+  architectures other than `x64`) with the version, file name, size and SHA-512
+  of the AppImage is written next to it in `outDir`
+
+Upload both the AppImage and the update info file to every release.
+[`@nwutils/updater`](https://www.npmjs.com/package/@nwutils/updater) reads them
+at runtime to check for, download and install updates.
+
+```js
+await packager({
+  format: "AppImage",
+  appDir: "./out",
+  appName: "Demo",
+  outDir: "./dist",
+  version: "1.2.0",
+  publish: { provider: "github", owner: "nwutils", repo: "demo" },
+  // Optional: also support zsync based updaters, see below.
+  updateInformation: true,
+});
+// ./dist/Demo-x86_64.AppImage
+// ./dist/latest-linux.yml
+// ./dist/Demo-x86_64.AppImage.zsync (only with updateInformation)
+```
 
-The first time it runs for a given architecture, `appImage()` downloads
-[`appimagetool`](https://github.com/AppImage/appimagetool) into `cacheDir` and
-reuses it on subsequent calls. `appimagetool` is a native Linux binary, so
-`appImage()` only runs on a Linux host, targeting the host's own architecture
-by default.
+| `publish.provider` | Other keys      | The latest release is looked up at                               |
+| ------------------ | --------------- | ---------------------------------------------------------------- |
+| `"github"`         | `owner`, `repo` | The latest (non draft, non prerelease) GitHub release's assets   |
+| `"generic"`        | `url`           | `<url>/latest-linux.yml`, with the AppImage served from `<url>/` |
 
-`appimagetool` is invoked with `APPIMAGE_EXTRACT_AND_RUN=1`, so a FUSE mount is
-never required - useful in containers, CI runners and other sandboxes where
-FUSE is typically unavailable.
+`updateInformation` additionally embeds AppImage update information, for zsync
+based updaters such as AppImageUpdate, `appimageupdatetool` and AppImage
+managers. `true` derives it from `publish`
+(`gh-releases-zsync|<owner>|<repo>|latest|<AppImage>.zsync` or
+`zsync|<url>/<AppImage>.zsync`); a string is embedded as-is. It needs
+`zsyncmake` (usually packaged as `zsync`) installed on the host, and the
+`.zsync` file must be uploaded alongside the AppImage.
 
 ## API Reference
 
@@ -84,25 +121,24 @@ Resolves with the path to the resulting packaged artifact.
 
 Options
 
-| Name            | Type                         | Description                                                                                                              |
-| --------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| appDir          | `string`                     | Path to a built NW.js Linux application, ie. the `outDir` produced by `@nwutils/builder` for `platform: "linux"`         |
-| appName         | `string`                     | Name of the application. Must match the `app.name` value used to build `appDir`                                          |
-| icon            | `string`                     | Path to a `.png` or `.svg` icon. Defaults to the `Icon` value read from `<appDir>/<appName>.desktop`                     |
-| arch            | `"ia32" \| "x64" \| "arm64"` | Target architecture. Defaults to the host architecture                                                                   |
-| outDir          | `string`                     | Directory the resulting `.AppImage` file is written to. Defaults to the parent directory of `appDir`                     |
-| cacheDir        | `string`                     | Directory used to cache the downloaded `appimagetool` binary. Defaults to `"./cache"`                                    |
-| cache           | `boolean`                    | If true, reuse a cached `appimagetool` binary. Otherwise redownload it. Defaults to `true`                               |
-| appImageToolUrl | `string`                     | Base URL `appimagetool-<arch>.AppImage` is downloaded from. Defaults to the `AppImage/appimagetool` "continuous" release |
+| Name              | Type                         | Description                                                                                                                                                   |
+| ----------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| appDir            | `string`                     | Path to a built NW.js Linux application, ie. the `outDir` produced by `@nwutils/builder` for `platform: "linux"`                                              |
+| appName           | `string`                     | Name of the application. Must match the `app.name` value used to build `appDir`. Must not contain `/` or control characters                                   |
+| icon              | `string`                     | Path to a `.png` or `.svg` icon. Defaults to the `Icon` value read from `<appDir>/<appName>.desktop`                                                          |
+| arch              | `"ia32" \| "x64" \| "arm64"` | Target architecture. Defaults to the host architecture                                                                                                        |
+| outDir            | `string`                     | Directory the resulting `.AppImage` file is written to. Defaults to the parent directory of `appDir`                                                          |
+| cacheDir          | `string`                     | Directory used to cache the downloaded `appimagetool` binary. Defaults to `"./cache"`                                                                         |
+| cache             | `boolean`                    | If true, reuse a cached `appimagetool` binary. Otherwise redownload it. Defaults to `true`                                                                    |
+| appImageToolUrl   | `string`                     | Base URL `appimagetool-<arch>.AppImage` is downloaded from. Defaults to the `AppImage/appimagetool` "continuous" release. Must be https, except for localhost |
+| sign              | `boolean`                    | If true, embed a GPG signature in the AppImage. Defaults to `false`                                                                                           |
+| signKey           | `string`                     | ID of the GPG key to sign with. Defaults to `gpg`'s default secret key. Requires `sign: true`                                                                 |
+| version           | `string`                     | Version of the application. Required with `publish`                                                                                                           |
+| publish           | `PublishOptions`             | Where releases are published. Embeds `app-update.yml` and writes `latest-linux[-<arch>].yml` to `outDir`                                                      |
+| updateInformation | `boolean \| string`          | AppImage zsync update information. `true` derives it from `publish`. Requires `zsyncmake` on the host                                                         |
 
 Resolves with the path to the resulting `.AppImage` file.
 
-The application's desktop entry file (`<appDir>/<appName>.desktop`, as written
-by `@nwutils/builder`) is copied into the AppImage with its `Exec` and `Icon`
-keys rewritten to match the AppImage's own layout, and a `Categories` key
-added (defaulting to `Utility;`) if one isn't already present, since
-`appimagetool` refuses to build an AppImage without one.
-
 ## Contributing
 
 ### External contributor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nwutils/packager",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Package NW.js applications for Linux, MacOS and Windows.",
   "keywords": [
     "NW.js",
@@ -47,5 +47,16 @@
     "test:real": "node --test \"../../tests/specs/packager/appImage.real.test.js\""
   },
   "dependencies": {},
-  "devDependencies": {}
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": "26.7.0",
+      "onFail": "warn"
+    },
+    "packageManager": {
+      "name": "npm",
+      "version": "12.0.2",
+      "onFail": "warn"
+    }
+  }
 }

package/src/appImage.js

@@ -19,13 +19,40 @@ const APPIMAGETOOL_URL =
 /**
  * @typedef  {object}                       AppImageOptions
  * @property {string}                       appDir             Path to a built NW.js Linux application, ie. the `outDir` produced by `@nwutils/builder` for `platform: "linux"`.
- * @property {string}                       appName            Name of the application. Must match the `app.name` value used to build `appDir` - the executable and desktop entry are expected at `<appDir>/<appName>` and `<appDir>/<appName>.desktop`.
+ * @property {string}                       appName            Name of the application. Must match the `app.name` value used to build `appDir` - the executable and desktop entry are expected at `<appDir>/<appName>` and `<appDir>/<appName>.desktop`. Must not contain `/` or control characters.
  * @property {string}                       [icon]             Path to a `.png` or `.svg` icon. Defaults to the `Icon` value read from `<appDir>/<appName>.desktop`.
  * @property {"ia32" | "x64" | "arm64"}     [arch]             Target architecture. Defaults to the host architecture. `appimagetool` runs as a native binary, so this must match the host unless the host has emulation (eg. QEMU/binfmt) configured for the target architecture.
  * @property {string}                       [outDir]           Directory the resulting `.AppImage` file is written to. Defaults to the parent directory of `appDir`.
  * @property {string}                       [cacheDir="./cache"] Directory used to cache the downloaded `appimagetool` binary.
  * @property {boolean}                      [cache=true]       If true, reuse a cached `appimagetool` binary. Otherwise redownload it.
- * @property {string}                       [appImageToolUrl]  Base URL `appimagetool-<arch>.AppImage` is downloaded from. Defaults to the `AppImage/appimagetool` "continuous" GitHub release.
+ * @property {string}                       [appImageToolUrl]  Base URL `appimagetool-<arch>.AppImage` is downloaded from. Defaults to the `AppImage/appimagetool` "continuous" GitHub release. Must be https, except for localhost.
+ * @property {boolean}                      [sign=false]       If true, embed a GPG signature in the AppImage. Requires `gpg` and a usable secret key on the host. A passphrase-protected key reads its passphrase from the `APPIMAGETOOL_SIGN_PASSPHRASE` environment variable.
+ * @property {string}                       [signKey]          ID of the GPG key to sign with. Defaults to `gpg`'s default secret key. Requires `sign` to be true.
+ * @property {string}                       [version]          Version of the application, eg. `"1.2.0"`. Required when `publish` is set: it is written to the update info file `@nwutils/updater` compares against.
+ * @property {PublishOptions}               [publish]          Where releases are published. When set, an `app-update.yml` pointing at it is embedded in the AppImage and a `latest-linux[-<arch>].yml` update info file is written next to it, for `@nwutils/updater` to self update from.
+ * @property {string | boolean}             [updateInformation] AppImage update information for zsync based updaters (eg. AppImageUpdate, `appimageupdatetool`, AppImage managers). `true` derives it from `publish`. A string is embedded as-is, eg. `"gh-releases-zsync|owner|repo|latest|Demo-x86_64.AppImage.zsync"`. Requires `zsyncmake` on the host to produce the `.zsync` file.
+ */
+
+/**
+ * Publish to a GitHub repository's releases. The AppImage and update info
+ * file must be uploaded as assets of the latest (non draft, non prerelease)
+ * release.
+ * @typedef  {object}   GitHubPublishOptions
+ * @property {"github"} provider
+ * @property {string}   owner     Owner of the GitHub repository.
+ * @property {string}   repo      Name of the GitHub repository.
+ */
+
+/**
+ * Publish to any static file server. The AppImage and update info file must
+ * be served from `url`.
+ * @typedef  {object}    GenericPublishOptions
+ * @property {"generic"} provider
+ * @property {string}    url       Base URL the latest release's files are served from.
+ */
+
+/**
+ * @typedef {GitHubPublishOptions | GenericPublishOptions} PublishOptions
  */
 
 /**
@@ -47,6 +74,11 @@ async function appImage({
   cacheDir = "./cache",
   cache = true,
   appImageToolUrl = APPIMAGETOOL_URL,
+  sign = false,
+  signKey,
+  version,
+  publish,
+  updateInformation,
 }) {
   if (process.platform !== "linux") {
     throw new Error(
@@ -69,6 +101,68 @@ async function appImage({
       `Expected "options.appName" to be a non-empty string. Received: ${JSON.stringify(appName)}`,
     );
   }
+  /*
+   * `appName` names files inside `appDir` and `outDir`, and is written into
+   * the desktop entry and `AppRun`: a path separator or `..` would reach
+   * outside those directories, and a line break would inject desktop entries.
+   */
+  const hasControlCharacter = [...appName].some((character) => {
+    const code = character.charCodeAt(0);
+    return code < 0x20 || code === 0x7f;
+  });
+  if (
+    appName.includes("/") ||
+    hasControlCharacter ||
+    appName === "." ||
+    appName === ".."
+  ) {
+    throw new Error(
+      `Expected "options.appName" to be a file name without "/" or control characters. Received: ${JSON.stringify(appName)}`,
+    );
+  }
+
+  if (typeof sign !== "boolean") {
+    throw new Error(
+      `Expected "options.sign" to be a boolean. Received: ${JSON.stringify(sign)}`,
+    );
+  }
+
+  if (signKey !== undefined) {
+    if (typeof signKey !== "string" || signKey === "") {
+      throw new Error(
+        `Expected "options.signKey" to be a non-empty string. Received: ${JSON.stringify(signKey)}`,
+      );
+    }
+    if (sign === false) {
+      throw new Error(
+        '"options.signKey" was passed but "options.sign" is false. Set "options.sign" to true to sign the AppImage.',
+      );
+    }
+  }
+
+  if (publish !== undefined) {
+    validatePublish(publish);
+    if (typeof version !== "string" || version === "") {
+      throw new Error(
+        `Expected "options.version" to be a non-empty string when "options.publish" is set. Received: ${JSON.stringify(version)}`,
+      );
+    }
+  }
+
+  if (
+    updateInformation !== undefined &&
+    typeof updateInformation !== "boolean" &&
+    (typeof updateInformation !== "string" || updateInformation === "")
+  ) {
+    throw new Error(
+      `Expected "options.updateInformation" to be a boolean or a non-empty string. Received: ${JSON.stringify(updateInformation)}`,
+    );
+  }
+  if (updateInformation === true && publish === undefined) {
+    throw new Error(
+      '"options.updateInformation" is true but "options.publish" is not set. Set "options.publish" to derive it, or pass the update information string directly.',
+    );
+  }
 
   const resolvedArch =
     /** @type {"ia32" | "x64" | "arm64" | undefined} */ (arch) ??
@@ -76,7 +170,10 @@ async function appImage({
       /** @type {unknown} */ (process.arch)
     );
 
-  const appImageToolArch = util.APPIMAGE_ARCH_KV[resolvedArch];
+  /* `Object.hasOwn` so inherited keys such as "constructor" aren't mistaken for architectures. */
+  const appImageToolArch = Object.hasOwn(util.APPIMAGE_ARCH_KV, resolvedArch)
+    ? util.APPIMAGE_ARCH_KV[resolvedArch]
+    : undefined;
   if (appImageToolArch === undefined) {
     throw new Error(
       `Expected "options.arch" to be "ia32", "x64" or "arm64". Received: ${JSON.stringify(arch)}`,
@@ -153,7 +250,7 @@ async function appImage({
     const appImageDesktopEntry = {
       ...desktopEntry,
       Name: desktopEntry.Name ?? appName,
-      Exec: appName,
+      Exec: util.desktopExecArg(appName),
       Icon: path.basename(iconFileName, path.extname(iconFileName)),
       Categories: desktopEntry.Categories || "Utility;",
     };
@@ -168,21 +265,79 @@ async function appImage({
       [
         "#!/bin/sh",
         'HERE="$(dirname "$(readlink -f "${0}")")"',
-        `exec "\${HERE}/${appName}" "$@"`,
+        /* Single quoted, so the app name is never expanded or run by the shell. */
+        `exec "\${HERE}"/${util.shellQuote(appName)} "$@"`,
         "",
       ].join("\n"),
     );
     await fs.promises.chmod(appRunPath, 0o755);
 
-    const appImageFilePath = path.resolve(
-      resolvedOutDir,
-      `${appName}-${appImageToolArch}.AppImage`,
-    );
+    /*
+     * Sits next to the NW.js executable, ie. at
+     * `path.dirname(process.execPath)` at runtime, which is where
+     * `@nwutils/updater` looks for it.
+     */
+    if (publish !== undefined) {
+      await fs.promises.writeFile(
+        path.resolve(appImageDir, "app-update.yml"),
+        util.stringifyYaml(
+          publish.provider === "github"
+            ? {
+                provider: publish.provider,
+                owner: publish.owner,
+                repo: publish.repo,
+              }
+            : { provider: publish.provider, url: publish.url },
+        ),
+      );
+    }
+
+    const appImageFileName = `${appName}-${appImageToolArch}.AppImage`;
+    const appImageFilePath = path.resolve(resolvedOutDir, appImageFileName);
+    const zsyncFilePath = `${appImageFilePath}.zsync`;
+
+    const resolvedUpdateInformation =
+      updateInformation === true
+        ? deriveUpdateInformation(
+            /** @type {PublishOptions} */ (publish),
+            path.basename(zsyncFilePath),
+          )
+        : updateInformation || undefined;
+
+    /*
+     * Signing happens inside the same `appimagetool` run that builds the
+     * file: an embedded signature can't be added to an existing AppImage.
+     */
+    const signArgs = sign
+      ? ["--sign", ...(signKey === undefined ? [] : ["--sign-key", signKey])]
+      : [];
+
+    const updateInformationArgs =
+      resolvedUpdateInformation === undefined
+        ? []
+        : ["--updateinformation", resolvedUpdateInformation];
+
+    if (resolvedUpdateInformation !== undefined) {
+      /* Don't let a `.zsync` file left over from a previous build pass the check below. */
+      await fs.promises.rm(zsyncFilePath, { force: true });
+    }
 
     child_process.execFileSync(
       appImageToolPath,
-      ["--no-appstream", appImageDir, appImageFilePath],
+      [
+        "--no-appstream",
+        ...signArgs,
+        ...updateInformationArgs,
+        appImageDir,
+        appImageFilePath,
+      ],
       {
+        /*
+         * `appimagetool` runs `zsyncmake` without an output path, which
+         * writes the `.zsync` file to the working directory - run from
+         * `outDir` so it lands next to the AppImage.
+         */
+        cwd: resolvedOutDir,
         env: {
           ...process.env,
           ARCH: appImageToolArch,
@@ -197,12 +352,152 @@ async function appImage({
       },
     );
 
+    /*
+     * `appimagetool` only warns, and still exits successfully, when it
+     * can't find `zsyncmake` - leaving an AppImage that advertises a
+     * `.zsync` file which was never produced.
+     */
+    if (
+      resolvedUpdateInformation !== undefined &&
+      (await util.fileExists(zsyncFilePath)) === false
+    ) {
+      throw new Error(
+        `"appimagetool" did not produce ${zsyncFilePath}. Install "zsyncmake" (usually packaged as "zsync") on the host to build AppImages with "options.updateInformation".`,
+      );
+    }
+
+    if (publish !== undefined) {
+      const appImageSha512 = await util.sha512(appImageFilePath);
+      const { size } = await fs.promises.stat(appImageFilePath);
+      await fs.promises.writeFile(
+        path.resolve(resolvedOutDir, util.updateInfoFileName(resolvedArch)),
+        util.stringifyYaml({
+          version: /** @type {string} */ (version),
+          files: [{ url: appImageFileName, sha512: appImageSha512, size }],
+          path: appImageFileName,
+          sha512: appImageSha512,
+          releaseDate: new Date().toISOString(),
+        }),
+      );
+    }
+
     return appImageFilePath;
   } finally {
     await fs.promises.rm(appImageDir, { recursive: true, force: true });
   }
 }
 
+/**
+ * Throw if `publish` isn't a valid `PublishOptions` object.
+ * @param {unknown} publish
+ * @returns {asserts publish is PublishOptions}
+ */
+function validatePublish(publish) {
+  if (typeof publish !== "object" || publish === null) {
+    throw new Error(
+      `Expected "options.publish" to be an object. Received: ${JSON.stringify(publish)}`,
+    );
+  }
+
+  const { provider } = /** @type {{provider?: unknown}} */ (publish);
+  /** @type {string[]} */
+  let requiredKeys;
+  if (provider === "github") {
+    requiredKeys = ["owner", "repo"];
+  } else if (provider === "generic") {
+    requiredKeys = ["url"];
+  } else {
+    throw new Error(
+      `Expected "options.publish.provider" to be "github" or "generic". Received: ${JSON.stringify(provider)}`,
+    );
+  }
+
+  for (const key of requiredKeys) {
+    const value = /** @type {Record<string, unknown>} */ (publish)[key];
+    if (typeof value !== "string" || value === "") {
+      throw new Error(
+        `Expected "options.publish.${key}" to be a non-empty string for provider "${provider}". Received: ${JSON.stringify(value)}`,
+      );
+    }
+  }
+
+  if (provider === "github") {
+    /*
+     * The characters GitHub allows in owner and repository names. Anything
+     * else - eg. "|", the update information's field separator - is rejected.
+     */
+    for (const key of requiredKeys) {
+      const value = /** @type {Record<string, string>} */ (publish)[key];
+      if (/^[A-Za-z0-9._-]+$/.test(value) === false) {
+        throw new Error(
+          `Expected "options.publish.${key}" to be a GitHub ${key} name (letters, digits, ".", "-" and "_"). Received: ${JSON.stringify(value)}`,
+        );
+      }
+    }
+  }
+
+  if (provider === "generic") {
+    const { url } = /** @type {GenericPublishOptions} */ (publish);
+    let protocol;
+    try {
+      protocol = new URL(url).protocol;
+    } catch {
+      protocol = undefined;
+    }
+    if (protocol !== "https:" && protocol !== "http:") {
+      throw new Error(
+        `Expected "options.publish.url" to be an http(s) URL. Received: ${JSON.stringify(url)}`,
+      );
+    }
+  }
+}
+
+/**
+ * Build the AppImage update information string for `publish`, in the format
+ * zsync based AppImage updaters understand.
+ * @param {PublishOptions} publish
+ * @param {string} zsyncFileName  Name the `.zsync` file is published under.
+ * @returns {string}
+ */
+function deriveUpdateInformation(publish, zsyncFileName) {
+  if (publish.provider === "github") {
+    return `gh-releases-zsync|${publish.owner}|${publish.repo}|latest|${zsyncFileName}`;
+  }
+  /* Trim trailing slashes with a linear scan rather than a backtracking regular expression. */
+  let end = publish.url.length;
+  while (end > 0 && publish.url[end - 1] === "/") {
+    end--;
+  }
+  return `zsync|${publish.url.slice(0, end)}/${zsyncFileName}`;
+}
+
+/**
+ * Throw unless `appImageToolUrl` is an https URL. The downloaded binary is
+ * executed, so a plain http download would let anyone on the network path
+ * replace it. http is only accepted for loopback hosts, eg. a local mirror.
+ * @param {string} appImageToolUrl
+ * @returns {void}
+ */
+function validateAppImageToolUrl(appImageToolUrl) {
+  let url;
+  try {
+    url = new URL(appImageToolUrl);
+  } catch {
+    url = undefined;
+  }
+  const isLoopback =
+    url !== undefined &&
+    ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if (
+    url === undefined ||
+    (url.protocol !== "https:" && (url.protocol !== "http:" || !isLoopback))
+  ) {
+    throw new Error(
+      `Expected "options.appImageToolUrl" to be an https URL (http is only allowed for localhost). Received: ${JSON.stringify(appImageToolUrl)}`,
+    );
+  }
+}
+
 /**
  * Download (or reuse a cached) `appimagetool` binary for `appImageToolArch`.
  * @async
@@ -220,6 +515,8 @@ async function getAppImageTool({
   cacheDir,
   cache,
 }) {
+  validateAppImageToolUrl(appImageToolUrl);
+
   const appImageToolPath = path.resolve(
     cacheDir,
     `appimagetool-${appImageToolArch}.AppImage`,

package/src/index.js

@@ -10,6 +10,11 @@ import appImage from "./appImage.js";
  * @typedef {"AppImage" | "deb" | "rpm" | "msix" | "nsis" | "dmg"} PackageFormat
  */
 
+/**
+ * Where releases are published, for packagers that support self updating.
+ * @typedef {import("./appImage.js").PublishOptions} PublishOptions
+ */
+
 /**
  * Package a built NW.js application.
  * @async

package/src/util.js

@@ -1,3 +1,4 @@
+import crypto from "node:crypto";
 import fs from "node:fs";
 
 /**
@@ -71,16 +72,122 @@ function parseDesktopEntry(contents) {
 function stringifyDesktopEntry(entries) {
   let fileContent = "[Desktop Entry]\n";
   for (const key of Object.keys(entries)) {
-    if (entries[key] !== undefined) {
-      fileContent += `${key}=${entries[key]}\n`;
+    const value = entries[key];
+    if (value !== undefined) {
+      /* A line break would let the key or value inject further entries, eg. a second `Exec`. */
+      if (/[\r\n]/.test(key) || /[\r\n]/.test(value)) {
+        throw new Error(
+          `Desktop entry keys and values must not contain line breaks. Received: ${JSON.stringify(`${key}=${value}`)}`,
+        );
+      }
+      fileContent += `${key}=${value}\n`;
     }
   }
   return fileContent;
 }
 
+/**
+ * Quote `value` as a single POSIX shell word. Inside single quotes nothing is
+ * expanded, so only single quotes themselves need escaping.
+ * @param {string} value
+ * @returns {string}
+ */
+function shellQuote(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+/**
+ * Quote `value` as a single argument of a desktop entry's `Exec` key, per the
+ * Desktop Entry Specification: `%` is doubled so it isn't read as a field
+ * code, an argument with reserved characters is double quoted with `"`, `` ` ``,
+ * `$` and `\` backslash-escaped, and finally backslashes are escaped again as
+ * required for every string value.
+ * @param {string} value
+ * @returns {string}
+ */
+function desktopExecArg(value) {
+  let arg = value.replaceAll("%", "%%");
+  if (/[\s"'\\><~|&;$*?#()`]/.test(arg)) {
+    arg = `"${arg.replace(/["`$\\]/g, "\\$&")}"`;
+  }
+  return arg.replaceAll("\\", "\\\\");
+}
+
+/**
+ * Name of the update info file `@nwutils/updater` downloads to find the
+ * latest release, following electron-builder's naming: `x64` gets the bare
+ * `latest-linux.yml`, every other architecture gets an `-<arch>` suffix.
+ * @param {"ia32" | "x64" | "arm64"} arch
+ * @returns {string}
+ */
+function updateInfoFileName(arch) {
+  return arch === "x64" ? "latest-linux.yml" : `latest-linux-${arch}.yml`;
+}
+
+/**
+ * Serialise `value` as a YAML scalar. Strings are written double-quoted via
+ * `JSON.stringify` - a JSON string literal is also a valid YAML double-quoted
+ * scalar, so this never needs YAML-specific escaping rules.
+ * @param {string | number | boolean} value
+ * @returns {string}
+ */
+function stringifyYamlScalar(value) {
+  return typeof value === "string" ? JSON.stringify(value) : String(value);
+}
+
+/**
+ * Serialise a map of scalars, and lists of maps of scalars, as YAML. This is
+ * the only shape the update info and `app-update.yml` files use, so it avoids
+ * pulling in a YAML library for a handful of lines.
+ * @param {Record<string, string | number | boolean | Record<string, string | number | boolean>[] | undefined>} entries
+ * @returns {string}
+ */
+function stringifyYaml(entries) {
+  let fileContent = "";
+  for (const [key, value] of Object.entries(entries)) {
+    if (value === undefined) {
+      continue;
+    }
+    if (Array.isArray(value)) {
+      fileContent += `${key}:\n`;
+      for (const item of value) {
+        let prefix = "  - ";
+        for (const [itemKey, itemValue] of Object.entries(item)) {
+          fileContent += `${prefix}${itemKey}: ${stringifyYamlScalar(itemValue)}\n`;
+          prefix = "    ";
+        }
+      }
+    } else {
+      fileContent += `${key}: ${stringifyYamlScalar(value)}\n`;
+    }
+  }
+  return fileContent;
+}
+
+/**
+ * Compute the base64 encoded SHA-512 digest of the file at `filePath`, the
+ * same encoding electron-builder writes into its update info files.
+ * @async
+ * @function
+ * @param {string} filePath
+ * @returns {Promise<string>}
+ */
+async function sha512(filePath) {
+  const hash = crypto.createHash("sha512");
+  for await (const chunk of fs.createReadStream(filePath)) {
+    hash.update(chunk);
+  }
+  return hash.digest("base64");
+}
+
 export default {
   APPIMAGE_ARCH_KV,
+  desktopExecArg,
   fileExists,
   parseDesktopEntry,
+  sha512,
+  shellQuote,
   stringifyDesktopEntry,
+  stringifyYaml,
+  updateInfoFileName,
 };

package/types/appImage.d.ts

@@ -4,7 +4,7 @@ export type AppImageOptions = {
      */
     appDir: string;
     /**
-     * Name of the application. Must match the `app.name` value used to build `appDir` - the executable and desktop entry are expected at `<appDir>/<appName>` and `<appDir>/<appName>.desktop`.
+     * Name of the application. Must match the `app.name` value used to build `appDir` - the executable and desktop entry are expected at `<appDir>/<appName>` and `<appDir>/<appName>.desktop`. Must not contain `/` or control characters.
      */
     appName: string;
     /**
@@ -28,20 +28,83 @@ export type AppImageOptions = {
      */
     cache?: boolean;
     /**
-     * Base URL `appimagetool-<arch>.AppImage` is downloaded from. Defaults to the `AppImage/appimagetool` "continuous" GitHub release.
+     * Base URL `appimagetool-<arch>.AppImage` is downloaded from. Defaults to the `AppImage/appimagetool` "continuous" GitHub release. Must be https, except for localhost.
      */
     appImageToolUrl?: string;
+    /**
+     * If true, embed a GPG signature in the AppImage. Requires `gpg` and a usable secret key on the host. A passphrase-protected key reads its passphrase from the `APPIMAGETOOL_SIGN_PASSPHRASE` environment variable.
+     */
+    sign?: boolean;
+    /**
+     * ID of the GPG key to sign with. Defaults to `gpg`'s default secret key. Requires `sign` to be true.
+     */
+    signKey?: string;
+    /**
+     * Version of the application, eg. `"1.2.0"`. Required when `publish` is set: it is written to the update info file `@nwutils/updater` compares against.
+     */
+    version?: string;
+    /**
+     * Where releases are published. When set, an `app-update.yml` pointing at it is embedded in the AppImage and a `latest-linux[-<arch>].yml` update info file is written next to it, for `@nwutils/updater` to self update from.
+     */
+    publish?: PublishOptions;
+    /**
+     * AppImage update information for zsync based updaters (eg. AppImageUpdate, `appimageupdatetool`, AppImage managers). `true` derives it from `publish`. A string is embedded as-is, eg. `"gh-releases-zsync|owner|repo|latest|Demo-x86_64.AppImage.zsync"`. Requires `zsyncmake` on the host to produce the `.zsync` file.
+     */
+    updateInformation?: string | boolean;
+};
+export type GitHubPublishOptions = {
+    provider: "github";
+    /**
+     * Owner of the GitHub repository.
+     */
+    owner: string;
+    /**
+     * Name of the GitHub repository.
+     */
+    repo: string;
+};
+export type GenericPublishOptions = {
+    provider: "generic";
+    /**
+     * Base URL the latest release's files are served from.
+     */
+    url: string;
 };
+export type PublishOptions = GitHubPublishOptions | GenericPublishOptions;
 /**
  * @typedef  {object}                       AppImageOptions
  * @property {string}                       appDir             Path to a built NW.js Linux application, ie. the `outDir` produced by `@nwutils/builder` for `platform: "linux"`.
- * @property {string}                       appName            Name of the application. Must match the `app.name` value used to build `appDir` - the executable and desktop entry are expected at `<appDir>/<appName>` and `<appDir>/<appName>.desktop`.
+ * @property {string}                       appName            Name of the application. Must match the `app.name` value used to build `appDir` - the executable and desktop entry are expected at `<appDir>/<appName>` and `<appDir>/<appName>.desktop`. Must not contain `/` or control characters.
  * @property {string}                       [icon]             Path to a `.png` or `.svg` icon. Defaults to the `Icon` value read from `<appDir>/<appName>.desktop`.
  * @property {"ia32" | "x64" | "arm64"}     [arch]             Target architecture. Defaults to the host architecture. `appimagetool` runs as a native binary, so this must match the host unless the host has emulation (eg. QEMU/binfmt) configured for the target architecture.
  * @property {string}                       [outDir]           Directory the resulting `.AppImage` file is written to. Defaults to the parent directory of `appDir`.
  * @property {string}                       [cacheDir="./cache"] Directory used to cache the downloaded `appimagetool` binary.
  * @property {boolean}                      [cache=true]       If true, reuse a cached `appimagetool` binary. Otherwise redownload it.
- * @property {string}                       [appImageToolUrl]  Base URL `appimagetool-<arch>.AppImage` is downloaded from. Defaults to the `AppImage/appimagetool` "continuous" GitHub release.
+ * @property {string}                       [appImageToolUrl]  Base URL `appimagetool-<arch>.AppImage` is downloaded from. Defaults to the `AppImage/appimagetool` "continuous" GitHub release. Must be https, except for localhost.
+ * @property {boolean}                      [sign=false]       If true, embed a GPG signature in the AppImage. Requires `gpg` and a usable secret key on the host. A passphrase-protected key reads its passphrase from the `APPIMAGETOOL_SIGN_PASSPHRASE` environment variable.
+ * @property {string}                       [signKey]          ID of the GPG key to sign with. Defaults to `gpg`'s default secret key. Requires `sign` to be true.
+ * @property {string}                       [version]          Version of the application, eg. `"1.2.0"`. Required when `publish` is set: it is written to the update info file `@nwutils/updater` compares against.
+ * @property {PublishOptions}               [publish]          Where releases are published. When set, an `app-update.yml` pointing at it is embedded in the AppImage and a `latest-linux[-<arch>].yml` update info file is written next to it, for `@nwutils/updater` to self update from.
+ * @property {string | boolean}             [updateInformation] AppImage update information for zsync based updaters (eg. AppImageUpdate, `appimageupdatetool`, AppImage managers). `true` derives it from `publish`. A string is embedded as-is, eg. `"gh-releases-zsync|owner|repo|latest|Demo-x86_64.AppImage.zsync"`. Requires `zsyncmake` on the host to produce the `.zsync` file.
+ */
+/**
+ * Publish to a GitHub repository's releases. The AppImage and update info
+ * file must be uploaded as assets of the latest (non draft, non prerelease)
+ * release.
+ * @typedef  {object}   GitHubPublishOptions
+ * @property {"github"} provider
+ * @property {string}   owner     Owner of the GitHub repository.
+ * @property {string}   repo      Name of the GitHub repository.
+ */
+/**
+ * Publish to any static file server. The AppImage and update info file must
+ * be served from `url`.
+ * @typedef  {object}    GenericPublishOptions
+ * @property {"generic"} provider
+ * @property {string}    url       Base URL the latest release's files are served from.
+ */
+/**
+ * @typedef {GitHubPublishOptions | GenericPublishOptions} PublishOptions
  */
 /**
  * Package a built NW.js Linux application as an AppImage.
@@ -53,7 +116,7 @@ export type AppImageOptions = {
  * @param  {AppImageOptions}  options
  * @returns {Promise<string>}  Path to the resulting `.AppImage` file.
  */
-declare function appImage({ appDir, appName, icon, arch, outDir, cacheDir, cache, appImageToolUrl, }: AppImageOptions): Promise<string>;
+declare function appImage({ appDir, appName, icon, arch, outDir, cacheDir, cache, appImageToolUrl, sign, signKey, version, publish, updateInformation, }: AppImageOptions): Promise<string>;
 /**
  * Download (or reuse a cached) `appimagetool` binary for `appImageToolArch`.
  * @async

package/types/index.d.ts

@@ -1,4 +1,5 @@
 export type PackageFormat = "AppImage" | "deb" | "rpm" | "msix" | "nsis" | "dmg";
+export type PublishOptions = import("./appImage.js").PublishOptions;
 /**
  * Supported packaged output formats.
  *
@@ -8,6 +9,10 @@ export type PackageFormat = "AppImage" | "deb" | "rpm" | "msix" | "nsis" | "dmg"
  * land.
  * @typedef {"AppImage" | "deb" | "rpm" | "msix" | "nsis" | "dmg"} PackageFormat
  */
+/**
+ * Where releases are published, for packagers that support self updating.
+ * @typedef {import("./appImage.js").PublishOptions} PublishOptions
+ */
 /**
  * Package a built NW.js application.
  * @async

package/types/util.d.ts

@@ -19,10 +19,57 @@ declare function parseDesktopEntry(contents: string): Record<string, string>;
  * @returns {string}
  */
 declare function stringifyDesktopEntry(entries: Record<string, string | undefined>): string;
+/**
+ * Quote `value` as a single POSIX shell word. Inside single quotes nothing is
+ * expanded, so only single quotes themselves need escaping.
+ * @param {string} value
+ * @returns {string}
+ */
+declare function shellQuote(value: string): string;
+/**
+ * Quote `value` as a single argument of a desktop entry's `Exec` key, per the
+ * Desktop Entry Specification: `%` is doubled so it isn't read as a field
+ * code, an argument with reserved characters is double quoted with `"`, `` ` ``,
+ * `$` and `\` backslash-escaped, and finally backslashes are escaped again as
+ * required for every string value.
+ * @param {string} value
+ * @returns {string}
+ */
+declare function desktopExecArg(value: string): string;
+/**
+ * Name of the update info file `@nwutils/updater` downloads to find the
+ * latest release, following electron-builder's naming: `x64` gets the bare
+ * `latest-linux.yml`, every other architecture gets an `-<arch>` suffix.
+ * @param {"ia32" | "x64" | "arm64"} arch
+ * @returns {string}
+ */
+declare function updateInfoFileName(arch: "ia32" | "x64" | "arm64"): string;
+/**
+ * Serialise a map of scalars, and lists of maps of scalars, as YAML. This is
+ * the only shape the update info and `app-update.yml` files use, so it avoids
+ * pulling in a YAML library for a handful of lines.
+ * @param {Record<string, string | number | boolean | Record<string, string | number | boolean>[] | undefined>} entries
+ * @returns {string}
+ */
+declare function stringifyYaml(entries: Record<string, string | number | boolean | Record<string, string | number | boolean>[] | undefined>): string;
+/**
+ * Compute the base64 encoded SHA-512 digest of the file at `filePath`, the
+ * same encoding electron-builder writes into its update info files.
+ * @async
+ * @function
+ * @param {string} filePath
+ * @returns {Promise<string>}
+ */
+declare function sha512(filePath: string): Promise<string>;
 declare const _default: {
     APPIMAGE_ARCH_KV: Record<"arm64" | "ia32" | "x64", string>;
+    desktopExecArg: typeof desktopExecArg;
     fileExists: typeof fileExists;
     parseDesktopEntry: typeof parseDesktopEntry;
+    sha512: typeof sha512;
+    shellQuote: typeof shellQuote;
     stringifyDesktopEntry: typeof stringifyDesktopEntry;
+    stringifyYaml: typeof stringifyYaml;
+    updateInfoFileName: typeof updateInfoFileName;
 };
 export default _default;