m2pack-secure/docs/client-integration.md

Client integration

Your current client already has a custom PackLib using zstd and XChaCha20. This project should become the next iteration, not a parallel dead tool.

Suggested migration

1. Keep the current PackManager interface stable.
2. Add a new loader beside the current pack code, for example:
   • src/PackLib/M2PackArchive.h
   • src/PackLib/M2PackArchive.cpp
3. Route CPackManager::AddPack() by extension:
   • legacy format for old .pack
   • new format for .m2p
4. Embed only the signing public key in the client.
5. Resolve the content decryption key from:
   • launcher-provided memory
   • machine-bound cache
   • or a derived release secret

Client key header

For the current implementation, the client expects:

• src/PackLib/M2PackKeys.h

Generate it from the release key material with:

m2pack export-client-config \
  --key keys/master.key \
  --public-key keys/signing.pub \
  --output /path/to/m2dev-client-src/src/PackLib/M2PackKeys.h

That keeps loader constants aligned with the archive builder.

Runtime validation

Minimum validation:

• verify header magic and version
• compare manifest hash
• verify manifest signature
• reject duplicate paths
• reject path traversal
• verify AEAD tag before decompression

Loader notes

• Use memory-mapped I/O for the archive.
• Keep a path-to-entry map in lowercase normalized form.
• Decrypt per request, not by unpacking the full archive.
• Keep a small decompression scratch buffer pool if the client reads in parallel.

Release model

• master.key: private content encryption key
• signing.key: private release signing key
• signing.pub: embedded client verifier key

The signing key belongs in CI or a secured release box. The public key belongs in the client binary or in a protected launcher manifest.