m2pack-secure/docs/launcher-contract.md

Launcher contract

m2pack can export a runtime key payload for the Windows client loader.

That payload is meant for a launcher, bootstrapper, or CI handoff step that delivers the active release key material at runtime.

Command

./build/m2pack export-runtime-key \
  --key keys/master.key \
  --public-key keys/signing.pub \
  --key-id 1 \
  --format json \
  --output out/runtime-key.json \
  --json

Options:

• --key
• --public-key
• --key-id optional, defaults to 1
• --format json|blob optional, defaults to json
• --output

JSON format

Use this for CI, scripts, and launcher preprocessing:

{
  "version": 1,
  "mapping_name": "Local\\M2PackSharedKeys",
  "key_id": 1,
  "master_key_hex": "<64 hex chars>",
  "sign_public_key_hex": "<64 hex chars>"
}

Binary format

Use this when a launcher wants to write the exact shared-memory payload expected by the client:

struct M2PackSharedKeys {
  char magic[8];           // "M2KEYS1\0"
  uint32_t version;        // 1
  uint32_t flags;          // reserved
  uint32_t key_id;         // runtime master key slot
  uint8_t master_key[32];
  uint8_t sign_public_key[32];
};

The client currently expects:

• magic = "M2KEYS1\0"
• version = 1
• flags = 0
• key_id matching the archive header key_id

Recommended flow

1. Linux CI builds .m2p with m2pack build --key-id <n>.
2. Linux CI exports M2PackKeys.h with m2pack export-client-config.
3. Linux CI exports a runtime key payload with m2pack export-runtime-key.
4. The Windows launcher creates Local\\M2PackSharedKeys.
5. The launcher writes the blob and starts the client with --m2pack-key-map.
6. The client rejects .m2p loading if the runtime key is missing or the key_id does not match.