#LunaPack

#Features

• A bundle that is the program, not a wrapper around it
  The archive is appended to the LunaPack launcher, so the produced file is the launcher — and the launcher is the program the user starts. The arguments of the bundle are the arguments of the bundled program, the exit code is its exit code, the Windows subsystem is its subsystem (so a windowed program does not flash a console window), and the standard streams are the ones of the bundle. A copy of the executable would not do this; a plain archiver cannot do it at all.

• Every entry is checksummed, and every entry is fingerprinted
  The SHA-256 checksum of an entry is computed over the original content, so it validates the data the user actually gets and not the compressed form. The MD5 fingerprint of the same content is carried next to it, because the MD5 is what the platform tooling shows, and a user who wants to compare the file with what their file manager reports has nothing to compare against otherwise. The fingerprint of the produced file is reported as well, and it is computed while the file is written, so a 300 MB package is never read back for it.

• Compression that is a choice, not a default
  --compression-method picks none, gzip, lz4 or auto. auto compresses every entry with gzip but keeps the raw bytes when gzip would make the entry bigger. The LZ4 implementation lives in this package, because the MoonBit toolchain ships none, and what it produces is a standard .lz4 frame: the lz4 tool decompresses it and this package decompresses what that tool produces. The frames are checked against the values the format publishes, not against the tool — see Verification.

• Encryption to a public key, or to a passphrase
  The mechanism is the one of the reference implementation this package follows: a key is established with the recipient, HKDF-SHA512 turns it into the key of the package, and every entry is sealed on its own with ChaCha20-Poly1305 under a key and a nonce derived for it. The additional data of an entry holds its place in the package and its name, so neither can be changed without the seal breaking. A check in the manifest tells a wrong key from a damaged package.

• Every primitive is implemented here, and checked against its vector
  SHA-512, HMAC, HKDF, PBKDF2, ChaCha20, Poly1305, X25519 and Ed25519 — the toolchain ships none of them. Each one is checked against the vector that its standard publishes (FIPS 180-4, RFC 4231, RFC 5869, RFC 8439, RFC 7748, RFC 8032), and the derivation is checked against the reference implementation itself: the master key, the key and the nonce of a record, and the sealed record are compared byte for byte with the values the reference produces.

• A package that says what it is, and a host that can prove it
  The manifest of a package carries the SHA-256 of its own bytes, and a sealed package carries a MAC of it as well, so a manifest that was changed is refused instead of being obeyed. A damaged package is refused rather than taken for something else, the package is written in one piece so a crash cannot leave half of one behind, and the program of a bundle is checked before it is started.
  The one thing a package cannot settle by itself is whether it is the package the publisher meant, because the digest inside it is not a secret. The host settles it: lunapack sign writes a detached Ed25519 signature next to the package and lunapack verify --signature checks it, or the host publishes the digest and lunapack verify --expected-sha256 checks that.

• An icon that survives the round trip
  When the application carries an icon, the bundle gets it as well, so Explorer shows the application's own icon instead of the launcher's. The icon is read from the application executable with a small PE reader and written into the bundle with the Windows resource API, which creates the resource section the launcher does not have. All icon sizes are copied, so the bundle looks right at every zoom level.

• Install scripts that run on the platform they were written for
  The script body is stored verbatim in the manifest together with the platform it targets, which is inferred from the file extension. At unpack time the script matching the host platform runs and a script for a different platform is skipped, so one package can safely be unpacked anywhere.

• One format, two front ends
  The same library and the same container behind lunapack (a native binary) and moonx riantr/LunaPack@latest (the WebAssembly build on the registry). The archive is found from the tail of the file in both cases, so verify, info and unpack work on a bundle exactly as they work on a plain package.

#What you get

#Install

moon add riantr/LunaPack@0.1.11

import {
  "riantr/LunaPack@0.1.11",
}

///|
import {
  "riantr/LunaPack" @lib,
}

///|
import {
  "riantr/LunaPack" @lp,
}

#What the release was checked on

#What changed in 0.1.11

• The native build builds on every platform again. The Windows-only GetModuleFileNameW declaration was guarded with target="native", which is true on Linux and macOS as well, so the linker looked for a Windows symbol there and the release workflow could not build those two binaries. The declaration and its caller are guarded with all(target="native", platform="windows") now; on other platforms the launcher keeps the argv[0] fallback it had before 0.1.10. The Windows build and the Wasm build were never affected, and the container layout does not change.

#What changed in 0.1.10

• The command that was typed is the command that runs. --input-file and --output-file are names for --input-exe and --output-exe now, and a flag the tool does not know is refused instead of being dropped. An empty output path is refused as well. Without those three changes an unknown flag could scan a whole directory and then fail with a rename to an empty file name — which is exactly what a real moonx riantr/LunaPack@latest run with the two aliases did.
• A failure says that it failed. Every command that cannot do what it was asked now exits with 1 instead of 0. The VERIFY OK / VERIFY FAILED / error: ... markers on stdout stay, so a script that reads the output keeps working.
• A check that was asked for is a check that is made. verify --extracted no longer lets an intact extracted directory hide a damaged package, and unpack honours --signature, --public-key and --expected-sha256 before it writes a single file.
• On Windows the launcher knows which file it is. It locates itself with GetModuleFileNameW instead of argv[0], which a caller can forge. A bundle carries its own copy of the launcher, so a bundle made before this release has to be rebuilt to pick up the fix. On other platforms the launcher keeps the argv[0] fallback it had before.
• A package cannot turn off its own integrity. A format 6 package whose integrity marker is missing or damaged is refused rather than downgraded to "legacy"; real format 5 packages are still read, with a warning. A non-PE file can no longer dictate the subsystem of the bundle, because the PE signature and the header bounds are checked.
• Malformed input is damage, not a crash. The LZ4 decoder checks its bounds, caps the expansion of a hostile frame and reads the DictID flag from the bit the format assigns to it. Windows install scripts get their bare file name, so cmd does not read the path as a switch, LUNAPACK_DEST is absolute, and an unreadable --pre-install script fails the command instead of discarding every other option.

#What changed in 0.1.9

• The public key of a pair holds both of its public keys. A pair serves two purposes — the key a package is sealed to, and the key a signature is checked with — and the file held only the first of them. keygen writes both now, and the two are derived from the secret with a label of their own, so the key that opens a package is not the key that signs one.
• The signature of a package holds. In 0.1.8 the signature was checked against the encryption public key, so a signature made with the secret key of the pair never held: the feature was published and it did not work. The Linux end-to-end suite found it, and the chain that the command line walks is held by a unit test now, so it does not depend on a POSIX host to be checked.
• A damaged package says that it is damaged. verify on a file that carries the marker of a package but is not one says so, and a file that carries no marker at all says that it is not a package. The two are not the same thing, and the wording keeps them apart.

#What changed in 0.1.8

• The manifest carries its own integrity. Every package now holds a block with the SHA-256 of its manifest, and a sealed package holds a MAC of it as well. A manifest that was changed is refused, and the reason is named.
• A damaged package is refused instead of being taken for something else. A file that carries the marker of a package but is not one is an error, not a file that is not a package. A bundle that cannot be unpacked does not fall back to printing its usage.
• A package is written in one piece. The package is written into a file of its own, flushed to the disk and only then does it take the place of the target. A target that was a whole package is still a whole package after a crash, and a file that is written is never half-written.
• The cache of a bundle is checked on every start, and the program is checked before it runs. A payload that was changed after it was unpacked is unpacked again, and a program that does not match the package is not started.
• The paths of the entries are checked. A path that walks out of the destination with .. is refused before anything is written.
• Every checksum is computed twice, and the MD5 is computed as well, so that a fault in the machine is not mistaken for a fault in the package.
• The host can sign a package. lunapack sign writes a detached Ed25519 signature next to the package, and lunapack verify --signature checks it. lunapack verify --expected-sha256 checks a digest the host published. Both are checked before the package is opened.
• The Ed25519 implementation is new, and it is checked against vectors that another implementation produced, so a signature that is right here is right against every other implementation of RFC 8032.

#What changed in 0.1.7

• The short coordinate runs. moonx riantr/LunaPack@latest resolves and starts the tool. The root package riantr/LunaPack is now the executable as well as the library, so the registry stores the prebuilt WebAssembly module under the module's own name and there is no second package to name. Before this release the same coordinate failed with "Prebuilt wasm asset does not exist", because the entry point lived in a second package.
• The entry point left cmd/main. The CLI is cli.mbt in the root package and the cmd/ directory is gone. A consumer's import path does not change: import { "riantr/LunaPack" @lib } names the same API, and the generated pkg.generated.mbti is byte-identical to the one 0.1.6 published.
• The price of the short coordinate is named, not hidden. A main package's blackbox tests are on a deprecation path and a dependency that imports a main package is deprecated. Both are described under Packages and targets, with the alternative that avoids them.

#What changed in 0.1.6

• There is a logo. LunaPack.png is what the README shows and what the registry's docs page renders; LunaPack_Logo.png is the same artwork at 1024×1024, for anyone who wants the full-resolution file. Both are published with the module, and the README's image path is relative, so the registry rewrites it to the asset URL.
• A missing interpreter is named in the error. The runtime's spawn failure says "The system cannot find the file specified." and names no file, so a missing sh read like a defect. The error now says which interpreter was missing — cannot run the interpreter \sh`: …` — and the temporary script file is removed on that path too, instead of being left in the installation directory.
• The README was restructured to the shape the sibling riantr/tesseract uses — title, logo, intro, Features, What you get, Install, then the technical sections, Quick Start, Example, Gates and drift detectors, Used By and Attribution — because a reader who has seen one of those modules should not have to learn a second layout. The technical content is the same content; the sections around it are new.

#What changed in 0.1.5

• The single file behaves like the program it carries. The arguments, the exit code, the subsystem and the standard streams of the bundle are the ones of the bundled program, so a windowed application does not flash a console window and a program that asks a question gets an answer.
• The end-to-end suite covers the bundle subcommand and the named launcher. A bundle that is made with --launcher now starts with the launcher that was named — byte for byte — and a launcher that does not exist is refused instead of producing a bundle that cannot start.

#Packages and targets

#Releases

#Publishing to Mooncakes

moon login                 # once
moon publish --dry-run     # validate
moon publish               # publish riantr/LunaPack
moonx riantr/LunaPack@latest --input-exe=... --output-exe=... --Files=...

#The bundle

myapp.exe  =  [ LunaPack launcher ]  +  [ archive: myapp.exe, res/app.cfg, ... ]

$ ./myapp.exe
LunaPack: starting D:/apps/.lunapack/9c445884d23653fb/myapp.exe

#The launcher

# A bundle for Windows, made with the launcher of the release.
lunapack bundle -i ./myapp.exe -o ./myapp.exe \
  --Files=./build --launcher ./lunapack-windows-x86_64.exe

The bundle is self-extracting when the launcher is a native LunaPack binary. The one that runs on this machine is used by default, so a native LunaPack always produces a self-extracting file. A bundle produced through moonx runs on WebAssembly and has no native binary of its own, so it needs one named with --launcher — see above.

#A single file that behaves like the program

• The arguments of the bundle are the arguments of the bundled program.
• The exit code of the bundle is the exit code of the bundled program.
• The subsystem of the bundle is the subsystem of the bundled program, so a windowed program does not flash a console window when it is started.
• The standard input, output and error are the ones of the bundle, so a program that asks a question gets an answer.

$ ./myapp.exe --version
myapp 2.6.0
$ echo $?
0

#The icon

$ lunapack --input-exe=./myapp.exe --output-exe=./myapp.exe --Files=./build
  md5  6b1b1e1f0a2c3d4e5f60718293a4b5c6  myapp.exe
  ...
scanned 392 files
bundled 392 files -> ./myapp.exe (icon copied)
output md5  0f1e2d3c4b5a69788796a5b4c3d2e1f0  myapp.exe

lunapack verify  myapp.exe
lunapack info    myapp.exe
lunapack unpack  -i myapp.exe -o ./out

#The package

#The format

+--------------------+  offset 0
| magic "APPKGD02"   |  8 bytes
+--------------------+  offset 8
| entry payloads     |  stored back to back, raw, gzip, lz4 or sealed
+--------------------+
| integrity block    |  40 bytes, or 72 for a sealed package
+--------------------+
| manifest (UTF-8    |
| JSON)              |
+--------------------+
| magic "APPKGD02"   |  8 bytes
| manifest offset    |  8 bytes, little-endian int64
| manifest length    |  8 bytes, little-endian int64
+--------------------+  end of file

{
  "format_version": 6,
  "name": "myapp",
  "version": "1.4.0",
  "os": "linux",
  "arch": "x86_64",
  "checksum_algo": "sha256",
  "compression": "auto",
  "created_at": "2026-11-04T04:10:20Z",
  "main_program": "myapp.exe",
  "pre_install": { "platform": "posix", "body": "#!/bin/sh\n..." },
  "post_install": null,
  "entries": [
    {
      "path": "res/app.cfg",
      "mode": 420,
      "size": 22500,
      "stored_size": 913,
      "codec": "gzip",
      "checksum": "0a77c24c45d0c61f906862c4706f5dd739166985e8fc5c6344dadd9220507b28",
      "md5": "1520e796ba25554696b3cef6e913cc90",
      "offset": 8
    }
  ]
}

• size is the original file size, stored_size the space it occupies in the package.
• checksum is the SHA-256 of the original content, so it validates the data the user actually gets, not the compressed form.
• md5 is the MD5 fingerprint of the same content. It is a convenience for comparing against what the platform tooling shows, not the integrity guarantee.
• mode holds UNIX permission bits (0o644 / 0o755); they are ignored on Windows.
• main_program names the entry that is the application executable.
• encryption says how the package is sealed, and is null when it is not sealed at all.

#The integrity of a package

# The host signs the package with its secret key.
lunapack sign myapp.appkg --secret-key host.key --output myapp.appkg.sig

# Whoever holds the public key checks the signature.
lunapack verify myapp.appkg --signature myapp.appkg.sig --public-key host.pub

lunapack verify myapp.appkg --expected-sha256 <the digest the host published>

lunapack-public-key v1
x25519 751d2616ba1be8341b35f6cf2d73978e2cccecd1decd0f898b421a99618bc35f
ed25519 a8414c851959a5449aad50fe53b9d976028fd3122248cf87331bd0e0a8ea526e

• A package that was damaged is refused, not taken for a file that is not a package. A bundle that cannot be unpacked is not a program without arguments.
• A package whose manifest was changed is refused, with the reason named.
• A sealed package is refused when the key is wrong, when the manifest was changed, and when a key is given for a package that says it is not sealed. The key is the claim of the reader that the package is encrypted to them, and a package that says the opposite has been changed.
• A path in the manifest that walks out of the destination with .. is refused before anything is written.

#Compression

#Encryption

# Make a pair of keys. The public key goes to the machine that seals the
# packages, the secret key to the machine that opens them.
lunapack keygen --public-key recipient.pub --secret-key recipient.key

# Seal a package to the owner of the public key.
lunapack pack -i ./app -o app.appkg \
  --encryption-method x25519 --public-key recipient.pub

# Open it again with the secret key.
lunapack unpack -i app.appkg -o ./out --secret-key recipient.key

# Or with a passphrase.
lunapack pack -i ./app -o app.appkg \
  --encryption-method passphrase --passphrase-file passphrase.txt
lunapack unpack -i app.appkg -o ./out --passphrase-file passphrase.txt

lunapack-public-key v1
x25519 751d2616ba1be8341b35f6cf2d73978e2cccecd1decd0f898b421a99618bc35f
ed25519 a8414c851959a5449aad50fe53b9d976028fd3122248cf87331bd0e0a8ea526e

lunapack keygen --public-key recipient.pub --secret-key recipient.key \
  --passphrase-file passphrase.txt

#Install scripts

• LUNAPACK_DEST — absolute path of the destination directory
• LUNAPACK_PHASE — pre_install or post_install

#Running it

#Via moonx (published on Mooncakes)

moonx riantr/LunaPack@latest \
  --input-exe=[input-exe-path] \
  --output-exe=[output-exe-path] \
  --Files=[Pack-Folder]

moonx riantr/LunaPack@latest \
  --input-file="x64/Release/App.exe" \
  --output-file="App.exe" \
  --Files="x64/Release"

#The subcommands

lunapack pack   -i <input_dir> -o <output.appkg> [options]
lunapack bundle -i <exe> -o <output.exe> [--Files <dir>]... [options]
lunapack unpack -i <package>   -o <dest_dir>    [--skip-scripts]
lunapack verify <package>      [--extracted <dir>]
lunapack sign   <package>      --secret-key <file> [--output <file>]
lunapack info   <package>
lunapack keygen --public-key <file> --secret-key <file>

lunapack verify myapp.exe --extracted .lunapack\b7e21c9f4d0a8356

lunapack sign myapp.appkg --secret-key host.key --output myapp.appkg.sig

lunapack-signature v1
algorithm ed25519
package 0f2a...            <- the SHA-256 of the package
manifest 8c41...           <- the SHA-256 of the manifest
signature 3b90...          <- the Ed25519 signature of the two

verify: OK (392 files)
verify: OK (392 files in .lunapack/b7e21c9f4d0a8356)
VERIFY OK

verify: OK (392 files)
verify: md5 mismatch for appsettings.json: expected 86ff00ef... got 3ddcb685...
verify: FAILED (392 files checked)
VERIFY FAILED

#As a native binary

moon build --release
# -> _build/native/release/build/LunaPack.exe   (every platform)

#Options

#A worked example

# Bundle an application and its resources into one self-extracting file.
lunapack --input-exe=./build/myapp \
         --output-exe=./dist/myapp \
         --Files=./build

# Or produce a plain archive instead.
lunapack pack -i ./myapp -o myapp.appkg \
  --name myapp --version 1.4.0 \
  --pre-install setup.sh --post-install setup.sh

lunapack verify  myapp.appkg
lunapack unpack  -i myapp.appkg -o /opt/myapp

  md5  6f5902ac237024bdd0c176cb93063dc4  a.txt
  md5  3db2050fcf84bb631dcae417d3db518c  sub/b.txt
scanned 2 files
packed 2 files -> myapp.appkg
output md5  63da650c906fe3ab1446b121a4edd4ca  myapp.appkg

unpacked 2 files -> /opt/myapp
  md5  6f5902ac237024bdd0c176cb93063dc4  a.txt
  md5  3db2050fcf84bb631dcae417d3db518c  sub/b.txt
verified 2 files, 0 mismatches

lunapack ^
  --input-exe="D:/src/App/bin/Release/net10.0-windows/App.exe" ^
  --output-exe="D:/dist/App.exe" ^
  --Files="D:/src/App/bin/Release/net10.0-windows"

#Verification

#Every guard was taken out once

#What this is not

• The exit code of a command says whether it worked: 0 when it did, 1 when it did not. The status is on stdout as well (VERIFY OK / VERIFY FAILED / error: ...), so a script that reads the output still works. A single-file bundle reports the exit code of the program it carries, exactly.
• UNIX permission bits cannot be set on Windows, so they are only applied on POSIX hosts.
• The checksum is computed over the original content; verify therefore has to decompress every entry.
• The fingerprint of the produced file is computed while it is written, so the file is never read back for that. The launcher stub is the one exception: it is hashed after the icon was written into it, because writing the icon changes its bytes.
• The big integers of the core are not constant time, so the X25519 of this package is not either. The control flow of the ladder does not depend on the secret, but the time of the arithmetic does. For the use here — a key exchange on the machine that holds the secret key — that is not the threat, but it is a reason to look elsewhere when it is.
• The encryption protects the content of the entries. The names of the entries and their sizes are in the manifest, which is not encrypted.
• The launcher stub is the LunaPack executable of the machine that built the bundle, so a bundle runs on the platform it was created on. Under moonx (Wasm) no native stub exists, so the bundle falls back to carrying the payload inside the application executable — such a bundle holds the data but does not extract itself.
• The extraction cache lives next to the bundle (.lunapack/<hash>/). When that folder cannot be written, a temporary directory is used instead.
• Copying the icon is Windows only, because an icon is a Windows resource.
• Bundling writes the archive to a temporary file next to the output, so there must be enough free disk space for it.
• The package is built on moonbitlang/core/async, which the toolchain ships as an experimental package. The MoonBit developers have confirmed that the stable releases will use it, so the package follows the toolchain rather than pinning an older release of the runtime.

#Quick Start

moon add riantr/LunaPack

lunapack bundle -i ./build/myapp -o ./dist/myapp --Files ./build
./dist/myapp --version

lunapack pack   -i ./myapp -o myapp.appkg
lunapack verify myapp.appkg
lunapack unpack -i myapp.appkg -o /opt/myapp

moon test                                  # 127 tests
moon build --release --target native       # the binary
moon build --release --target wasm         # the WebAssembly module

#Example

///|
async fn main {
  // A plain archive: a directory, compressed per entry, checksummed per entry.
  let opts = @lp.new_pack_options(
    "myapp", // the name of the package
    "1.4.0", // the version of the package
    "linux", // the os tag
    "x86_64", // the arch tag
    None, // the pre-install script
    None, // the post-install script
    "auto", // the compression
  )
  @lp.pack("./myapp", "myapp.appkg", opts)

  // The same application as a single self-extracting file. The launcher is the
  // running program itself, and the main program is recorded by the bundle.
  @lp.bundle("./build/myapp", "./dist/myapp", ["./build"], opts, "")

  // Read the manifest back, and check the package.
  let m = @lp.read_package_manifest("myapp.appkg")
  let ok = @lp.verify("myapp.appkg", None)
  @lp.unpack("myapp.appkg", "/opt/myapp", true, None)
}

///|
async fn main {
  match @lp.probe_archive("./dist/myapp") {
    Some((offset, manifest)) => {
      println("the archive starts at " + offset.to_string())
      println("it holds " + manifest.entries.length().to_string() + " entries")
    }
    None => println("this file carries no LunaPack archive")
  }
}

///|
async fn main {
  let m = @lp.read_package_manifest("secret.appkg")
  match m.encryption {
    Some(info) => {
      let key = @lp.recover_encryption(info, "recipient.key", "")
      @lp.unpack("secret.appkg", "./out", true, Some(key))
    }
    None => ()
  }
}

#Gates and drift detectors

#Used By

• cli.mbt — the command line of this module, the front end over the library that lives in the same package.
• integrity.mbt — the integrity block: the digest and the MAC of the manifest, and the checksums that are computed twice.
• ed25519.mbt — the signature that the host publishes next to a package.
• signature.mbt — the signature file and the checks of the host material.
• scripts/test_linux.sh — the end-to-end suite, which drives the binary that the module builds.
• scripts/mutation_battery.ps1 — the development tool that takes every guard out of the code once and checks that the test covering it goes red.

#Attribution

• License: Apache-2.0 (see LICENSE).
• The mechanism of the encryption and the shape of the container follow the reference implementation this package follows. Every primitive it needs is implemented in this package, because the MoonBit toolchain ships none of them, and each one is checked against the vector that its standard publishes.
• The LZ4 codec is an implementation of the format, not a port of a library: what it produces is a standard .lz4 frame, and the test suite checks the frames against the values the format publishes.
• The Ed25519 signature is an implementation of RFC 8032, not a port of a library. It is checked against vectors that another implementation produced, so a signature that is right here is right against every other implementation of the standard.