@todesktop/create-release-metadata

Create signed release metadata files for ToDesktop Installer.

Prerequisites

Install minisign (required)

This tool requires the native minisign command to generate keys and sign files:

# View installation instructions
npx @todesktop/create-release-metadata --install-minisign

# On macOS
brew install minisign

# On Ubuntu/Debian
apt install minisign

# On Windows
# Download from https://jedisct1.github.io/minisign/

Generate signing key pair with minisign

Generate a new signing key pair using minisign:

# Generate a new signing key pair
minisign -G
# This will create minisign.key (secret key) and minisign.pub (public key)

# or
minisign -G -p minisign.pub -s minisign.key

Usage

CLI

# Basic usage
npx @todesktop/create-release-metadata \
  --secret-key minisign.key \
  MyApp-1.2.3-arm64.zip MyApp-1.2.3-x64.zip

# With release notes
npx @todesktop/create-release-metadata \
  --secret-key minisign.key \
  --release-notes-file release-notes.md \
  MyApp-1.2.3-arm64.zip MyApp-1.2.3-x64.zip

# With expiration date
npx @todesktop/create-release-metadata \
  --secret-key minisign.key \
  --expires "2099-12-31T23:59:59Z" \
  MyApp-1.2.3-arm64.zip MyApp-1.2.3-x64.zip

# For a beta release
npx @todesktop/create-release-metadata \
  --secret-key minisign.key \
  --stage beta \
  MyApp-1.2.3-arm64.zip MyApp-1.2.3-x64.zip

# Custom output filename (overrides default manifest-{stage}-{platform}.json)
npx @todesktop/create-release-metadata \
  --secret-key minisign.key \
  --output-filename "release.json" \
  MyApp-1.2.3-arm64.zip MyApp-1.2.3-x64.zip

# Provide password for the minisign key (for automation)
npx @todesktop/create-release-metadata \
  --secret-key minisign.key \
  --password "my-secure-key-password" \
  MyApp-1.2.3-arm64.zip MyApp-1.2.3-x64.zip

# Show detailed progress information
npx @todesktop/create-release-metadata \
  --secret-key minisign.key \
  --verbose \
  MyApp-1.2.3-arm64.zip MyApp-1.2.3-x64.zip

If you don't provide a password via the --password option, the tool will allow you to enter it interactively when minisign prompts for it.

Verifying signatures

Verify the generated manifest signature using the minisign utility:

# Verify the manifest file
minisign -Vm manifest-latest-mac.json -p minisign.pub

Example output of successful verification:

Signature and comment signature verified
Trusted comment: timestamp:1655234567 filename:manifest-latest-mac.json

API

import { createReleaseMetadata } from "@todesktop/create-release-metadata";

async function createRelease() {
	const manifestPath = await createReleaseMetadata({
		distributables: ["MyApp-1.2.3-arm64.zip", "MyApp-1.2.3-x64.zip"],
		secretKeyPath: "path/to/minisign.key",
		releaseNotes: "What's new in this release:\n- Feature A\n- Bug fix B",
		expires: "2099-12-31T23:59:59Z",
		// Optional: provide password for the minisign key
		password: "my-secure-key-password",
		// Optional: show detailed progress information
		verbose: true,
	});

	console.log(`Created manifest at ${manifestPath}`);
}

Manifest Format

The manifest is output as JSON with a nested artifacts structure, organized by artifact type (zip/dmg) and architecture:

{
	"version": "1.2.3",
	"schemaVersion": 1,
	"releaseDate": "2024-03-20T10:00:00.000Z",
	"expires": "2099-12-31T23:59:59Z",
	"artifacts": {
		"zip": {
			"arm64": {
				"path": "MyApp-1.2.3-arm64.zip",
				"sha512": "abcdef1234567890...",
				"size": 123456789
			},
			"x64": {
				"path": "MyApp-1.2.3-x64.zip",
				"sha512": "0987654321fedcba...",
				"size": 123456789
			}
		}
	},
	"releaseNotes": "What's new in this release:\n- Feature A\n- Bug fix B"
}

Signatures are stored as external .minisig files alongside each artifact (e.g., MyApp-1.2.3-arm64.zip.minisig).

Important:

• Version is automatically extracted from the filename (e.g., MyApp-1.2.3-arm64.zip → 1.2.3). This includes prerelease tags like 1.2.3-beta.1. Use --app-version only if you need to override the detected version.
• Architecture must be detectable from the filename. Include one of: arm64, aarch64, x64, x86_64, amd64, x86, ia32, i386, or universal.
• Artifact type is determined by the file extension. Supported types: .zip, .dmg.

Options

Option	CLI	API	Description
--secret-key <path>	-k	secretKeyPath	Path to the minisign secret key
--release-notes <text>	-n	releaseNotes	Release notes in Markdown format
--release-notes-file <path>		releaseNotesPath	Path to a file containing release notes
--app-version <version>		appVersion	Version of the application (auto-detected from filename by default)
--platform <platform>		platform	Platform to create metadata for (default: mac)
--stage <stage>		stage	Release stage, e.g., latest, beta, stable (default: latest)
--output-dir <path>	-o	outputDir	Directory where metadata files will be written
--output-filename <name>		outputFilename	Output filename (default: manifest-{stage}-{platform}.json)
--expires <timestamp>		expires	Expiration date in ISO 8601 format
--password <password>		password	Password for the minisign secret key (optional)
--verbose		verbose	Show detailed progress information during execution
--install-minisign		N/A	Show instructions for installing minisign

License

MIT