native-packages 0.6.0 → 0.7.0

data/docs/platforms.md

@@ -1,34 +1,5 @@
-# Platform and distribution coverage
+# Supported platforms
 
-All seven nFPM 2.47.0 packagers are exposed by the v0.2 CLI. Each target explicitly declares suitable inputs; enabling an output format does not port an application or guarantee acceptance by a distribution.
+This guide is now part of the documentation site:
 
-| Output/destination | Shared implementation | Application responsibility |
-| --- | --- | --- |
-| DEB | nFPM, ELF inspection, known dependency inference, release upload | Supported distro baseline, runtime-loaded libraries, services/assets and installation testing |
-| RPM | Same, with RPM dependency names | Distribution-specific dependencies and compatibility |
-| Arch package | nFPM `archlinux`, native filename, ELF inspection | Arch-compatible files and explicit dependencies |
-| Alpine APK | nFPM `apk`, ELF/libc checks | Suitable musl/static inputs and Alpine dependencies |
-| IPK | nFPM `ipk`, ELF checks, explicit ABI label | Device/distribution ABI, architecture and dependencies |
-| MSIX | nFPM `msix`, PE architecture checks, `after_package` hook for native signing | Windows executables/DLLs, application identity, assets, capabilities and signing certificate |
-| SRPM | nFPM `srpm`, source/spec input validation | A correct spec and sources, native rebuild testing |
-| AUR | Template rendering, `.SRCINFO`, staged Git publication | Native PKGBUILD source/bin/git variants and build checks |
-| Homebrew | Hash/render supplied formulae or casks and publish a tap | Completed macOS assets, native recipe logic |
-| Nixpkgs/Gentoo/Void and similar repositories | Template rendering and configured Git/PR/MR publication | Native recipes, dependency hashes, distro checks and review |
-| Flatpak | No build/publication adapter yet | Use flatpak-builder and native manifests/runtime/sandbox settings |
-| Inno Setup | Native command adapter, PE inspection, copied input and final output hashes | Inno recipe/compiler, application version mapping, signing and installation tests |
-| macOS DMG | Native command adapter, Mach-O inspection, automatic Developer ID signing/notarization with Apple credentials, final stapled hashes | Bundle, hdiutil recipe, Apple credentials/entitlements, update/rollback testing |
-| Other Windows installers | No adapter for NSIS/WiX yet | Existing native tools and WinGet/Scoop integrations |
-
-The IPK acceptance fixture targets OpenWrt 24.10.8. OpenWrt 25.12 switched to APK, so IPK is not the package format for every OpenWrt release. [OpenWrt 25.12 release notes](https://openwrt.org/releases/25.12/notes-25.12.0)
-
-nFPM ends at constructing the package file, including its supported signing operations. It does not compile the application or host package indexes. [nFPM configuration](https://nfpm.goreleaser.com/docs/configuration/)
-
-The Windows acceptance test uses Windows SDK SignTool through `after_package`. Windows rejected nFPM 2.47.0's built-in signature with `0x80096010` in the initial acceptance run; do not assume its signing configuration alone produces a Windows-installable result.
-
-The CLI uses known ELF machine/class/endianness mappings and PE machine mappings. Unsupported inspection architectures fail explicitly. Data and source targets do not require an executable. The small DEB/RPM dependency table can be extended in configuration; other formats require explicit runtime dependencies. These checks do not detect every dynamically loaded library or establish compatibility with every version of a distribution.
-
-CI builds fixtures in every format and defines native Linux install/upgrade/remove checks, an SRPM rebuild and a signed MSIX installation on Windows. A build manifest reports `installation: not-tested` unless such testing was actually performed for that application output. Fixture coverage is separate from app-specific validation.
-
-The [acceptance run for v0.2 development](https://github.com/crmne/native-packages/actions/runs/34748247545) passed on Debian trixie, Fedora 41, Arch's base image, Alpine 3.24.0, OpenWrt 24.10.8 and the GitHub Windows runner. Linux binary tests use a small static executable; the SRPM rebuilds its C source, and the Windows package contains a compiled Windows executable. These fixtures test package construction and lifecycle, not the compatibility of every application's GUI or device integrations.
-
-Version 0.1 and its pinned workflow retain their DEB/RPM behavior. The new formats are enabled through the v0.2 single-file configuration and `build` command. Existing v0.1 application configurations do not silently gain more output formats.
+[Supported platforms](_reference/platforms.md).

data/docs/releasing.md

@@ -23,7 +23,7 @@ Update the gemspec, `NativePackages::VERSION`, example/version references and ch
 Create a GitHub release for that commit:
 
 ```sh
-gh release create v0.6.0 --target main --title 'native-packages 0.6.0' --notes-file release-notes.md
+gh release create v0.7.0 --target main --title 'native-packages 0.7.0' --notes-file release-notes.md
 ```
 
 Adding `--draft` permits review before publication and does not trigger the publisher. The tag must match the exact gem version and point to a commit on `main`. Set `--prerelease` only for a prerelease gem version.

data/examples/native-packages-all-formats.yaml

@@ -1,7 +1,7 @@
 # Supply the listed build outputs before running this example.
 schema: 1
 tool:
-  version: '0.6.0'
+  version: '0.7.0'
   nfpm: '2.47.0'
 nfpm:
   name: example-app

data/examples/native-packages.yaml

@@ -1,6 +1,6 @@
 schema: 1
 tool:
-  version: '0.6.0'
+  version: '0.7.0'
   nfpm: '2.47.0'
 nfpm:
   name: example-app

data/lib/native_packages/cli.rb

@@ -2,6 +2,7 @@
 
 require_relative "build"
 require_relative "scaffold"
+require_relative "release_signing"
 
 module NativePackages
   module CLI
@@ -15,6 +16,10 @@ module NativePackages
           [--output DIRECTORY] [--dry-run]         Choose output or inspect the plan
           [--defer-recipes]                        Build targets without recipe assets/tools
         notarize-macos DIRECTORY --output DIRECTORY Copy, sign and notarize portable Mac code
+        release-checksums DIRECTORY --output FILE  Hash a flat directory of release artifacts
+        sign-checksums FILE --public-key HEX_FILE   Sign verified checksums with Ed25519
+          [--key-env VARIABLE]                    Default: NATIVE_PACKAGES_SIGNING_KEY
+        verify-checksums FILE --public-key HEX_FILE Verify signature and artifact hashes
         aggregate DIR... --output DIRECTORY        Combine target builds before publishing
           [--finalize-recipes]                    Generate recipes from deferred builds
         publish --from DIRECTORY --to github,aur   Publish a complete, verified build
@@ -50,6 +55,11 @@ module NativePackages
         flags.on("--help", "-h") { puts HELP; return }
         flags.on("--output DIRECTORY") { |value| options[:output] = Pathname.new(value).expand_path(root) } if %w[build aggregate artifacts prepare notarize-macos].include?(command)
         flags.on("--body-file FILE") { |value| options[:body_file] = Pathname.new(value).expand_path(root) } if command == "publish"
+        flags.on("--output FILE") { |value| options[:output] = Pathname.new(value).expand_path(root) } if command == "release-checksums"
+        if %w[sign-checksums verify-checksums].include?(command)
+          flags.on("--public-key FILE") { |value| options[:public_key] = Pathname.new(value).expand_path(root) }
+        end
+        flags.on("--key-env VARIABLE") { |value| options[:key_env] = value } if command == "sign-checksums"
         flags.on("--target ID") { |value| options[:ids] << value } if %w[build doctor publish].include?(command)
         if %w[build doctor].include?(command)
           flags.on("--format FORMAT") { |value| options[:formats] << value }
@@ -80,10 +90,21 @@ module NativePackages
       parser.parse!(arguments)
       raise Error, "publish --target requires --from" if command == "publish" && !options[:from] && !options[:ids].empty?
       arity = { "init" => 0..0, "migrate" => 0..0, "build" => 0..0, "doctor" => 0..0, "aggregate" => 1..,
+        "release-checksums" => 1..1, "sign-checksums" => 1..1, "verify-checksums" => 1..1,
         "prepare" => 1..1, "check" => 1..1, "artifacts" => 1..1, "publish-release" => 2..2,
         "notarize-macos" => 1..1, "repositories" => 0..0, "stage" => 2..2, "diff" => 1..1, "publish" => options[:from] ? 0..0 : 1..1,
         "publish-aur" => 1..1, "status" => 0..1, "check-version" => 1..1, "validate" => 0..0 }[command]
       raise Error, HELP unless arity&.cover?(arguments.length)
+      if %w[release-checksums sign-checksums verify-checksums].include?(command)
+        path = Pathname.new(arguments.first).expand_path(root)
+        if command == "release-checksums"
+          raise Error, "release-checksums requires --output" unless options[:output]
+          return ReleaseSigning.checksums(path, output: options.fetch(:output))
+        end
+        raise Error, "#{command} requires --public-key" unless options[:public_key]
+        return ReleaseSigning.sign(path, **options.slice(:public_key, :key_env)) if command == "sign-checksums"
+        return ReleaseSigning.verify(path, public_key: options.fetch(:public_key))
+      end
       if command == "init"
         raise Error, "init writes native-packages.yaml in the current directory" if config_path
         return Scaffold.new(root).init(**options.slice(:interactive, :name, :input).merge(formats: options[:init_formats]))

data/lib/native_packages/release_signing.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module NativePackages
+  # Portable release manifests, independent of package format or CI provider.
+  # Ed25519 signs the exact file bytes (no prehash, encoding or canonicalization).
+  module ReleaseSigning
+    LIMIT = 1024 * 1024
+    PUBLIC_PREFIX = ["302a300506032b6570032100"].pack("H*").freeze
+    FILENAME = /\A[A-Za-z0-9][A-Za-z0-9._+\-]*\z/
+    module_function
+
+    def checksums(directory, output:)
+      directory = Pathname.new(directory).realpath
+      output = Pathname.new(output).expand_path
+      raise Error, "invalid checksum filename" unless FILENAME.match?(output.basename.to_s)
+      raise Error, "checksum output must be inside the artifact directory" unless output.dirname.realpath == directory
+      raise Error, "refusing to overwrite checksum output" if output.exist? || output.symlink?
+      entries = directory.children.sort
+      raise Error, "no release artifacts" if entries.empty?
+      names = entries.map { |path| path.basename.to_s }
+      raise Error, "ambiguous artifact filenames" unless names.map(&:downcase).uniq.length == names.length
+      manifest = entries.map do |path|
+        name = path.basename.to_s
+        raise Error, "invalid artifact filename" unless FILENAME.match?(name)
+        raise Error, "signature already exists" if name == "#{output.basename}.sig"
+        regular_file!(path)
+        "#{Digest::SHA256.file(path).hexdigest}  #{name}\n"
+      end.join
+      raise Error, "release manifest exceeds 1 MiB" if manifest.bytesize > LIMIT
+      write_new(output, manifest)
+    end
+
+    def sign(manifest, public_key:, key_env: "NATIVE_PACKAGES_SIGNING_KEY")
+      raise Error, "invalid signing key variable name" unless /\A[A-Z][A-Z0-9_]*\z/.match?(key_env)
+      pem = ENV.delete(key_env)
+      raise Error, "missing signing key environment variable" if pem.nil? || pem.empty?
+      # No subprocess receives the private key, and no private file is created.
+      key = OpenSSL::PKey.read(pem, "")
+      trusted = read_public_key(public_key)
+      raise Error, "signing key does not match trusted Ed25519 public key" unless key.oid == "ED25519" && key.public_to_der == trusted.public_to_der
+      manifest = Pathname.new(manifest)
+      bytes = bounded_read(manifest, LIMIT)
+      verify_files(manifest, bytes)
+      signature = key.sign(nil, bytes)
+      raise Error, "could not verify generated signature" unless signature.bytesize == 64 && trusted.verify(nil, signature, bytes)
+      write_new(Pathname.new("#{manifest}.sig"), signature)
+    rescue OpenSSL::OpenSSLError
+      # Do not expose parser diagnostics from secret input.
+      raise Error, "could not use Ed25519 signing key"
+    end
+
+    def verify(manifest, public_key:)
+      manifest = Pathname.new(manifest)
+      bytes = bounded_read(manifest, LIMIT)
+      signature = bounded_read(Pathname.new("#{manifest}.sig"), 64)
+      trusted = read_public_key(public_key)
+      raise Error, "invalid release signature" unless signature.bytesize == 64 && trusted.verify(nil, signature, bytes)
+      verify_files(manifest, bytes)
+      true
+    rescue OpenSSL::OpenSSLError
+      raise Error, "invalid Ed25519 public key or release signature"
+    end
+
+    def read_public_key(path)
+      hex = bounded_read(Pathname.new(path), 128).strip
+      raise Error, "public key must be 32 bytes encoded as hex" unless /\A[0-9a-fA-F]{64}\z/.match?(hex)
+      OpenSSL::PKey.read(PUBLIC_PREFIX + [hex].pack("H*"))
+    end
+
+    def verify_files(manifest, bytes)
+      raise Error, "empty release manifest" if bytes.empty?
+      seen = {}
+      bytes.each_line do |line|
+        match = /\A([0-9a-fA-F]{64})  ([A-Za-z0-9][A-Za-z0-9._+\-]*)\n\z/.match(line)
+        raise Error, "invalid release checksum entry" unless match
+        digest, name = match.captures
+        raise Error, "duplicate or self-referencing checksum entry" if seen[name.downcase] || [manifest.basename.to_s.downcase, "#{manifest.basename}.sig".downcase].include?(name.downcase)
+        seen[name.downcase] = true
+        path = manifest.dirname / name
+        regular_file!(path)
+        raise Error, "release artifact checksum mismatch: #{name}" unless Digest::SHA256.file(path).hexdigest == digest.downcase
+      end
+    end
+
+    def regular_file!(path)
+      raise Error, "release input must be a regular file: #{path.basename}" unless path.lstat.file?
+    end
+
+    def bounded_read(path, limit)
+      regular_file!(path)
+      bytes = File.binread(path, limit + 1) || "".b
+      raise Error, "release metadata exceeds size limit" if bytes.bytesize > limit
+      bytes
+    end
+
+    def write_new(path, bytes)
+      File.open(path, File::WRONLY | File::CREAT | File::EXCL, 0o644) do |file|
+        file.binmode
+        file.write(bytes)
+      end
+      path
+    end
+  end
+end

data/lib/native_packages/support.rb

@@ -12,7 +12,7 @@ require "tmpdir"
 require "yaml"
 
 module NativePackages
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
   class Error < StandardError; end
 
   module Support

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: native-packages
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Carmine Paolino
@@ -16,12 +16,30 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- CONTRIBUTING.md
 - LICENSE
 - README.md
+- docs/404.md
+- docs/_guides/apple-notarization.md
+- docs/_guides/building-packages.md
+- docs/_guides/distribution-recipes.md
+- docs/_guides/getting-started.md
+- docs/_guides/github-actions.md
+- docs/_guides/multi-platform.md
+- docs/_guides/native-recipes.md
+- docs/_guides/prereleases.md
+- docs/_guides/publishing.md
+- docs/_guides/release-signing.md
+- docs/_reference/commands.md
+- docs/_reference/configuration.md
+- docs/_reference/platforms.md
+- docs/_reference/troubleshooting.md
 - docs/acceptance/0.5.0-notarization.md
 - docs/apple-notarization.md
+- docs/assets/images/logo.svg
 - docs/cli-design.md
 - docs/configuration.md
+- docs/index.md
 - docs/legacy.md
 - docs/native-recipes.md
 - docs/platforms.md
@@ -41,6 +59,7 @@ files:
 - lib/native_packages/macos_signing.rb
 - lib/native_packages/native_recipe.rb
 - lib/native_packages/project.rb
+- lib/native_packages/release_signing.rb
 - lib/native_packages/repositories.rb
 - lib/native_packages/scaffold.rb
 - lib/native_packages/support.rb
@@ -64,7 +83,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
-summary: Shared release packaging and downstream recipe updates with nFPM
+summary: Build native application packages and publish release updates
 test_files: []