# 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 runtime delivery:
   - 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:

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

That keeps loader constants aligned with the archive builder.

Important:

- the generated client header no longer embeds the real master key
- `.m2p` loading now requires a runtime master key
- the runtime master key must match the archive `key_id`
- if a `.m2p` file exists and fails validation or runtime key resolution, the client should not silently fall back to `.pck`

## 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

## Launcher key delivery

The client now supports runtime key overrides and no longer has to rely only on
the compiled fallback key.

Supported inputs, highest priority last:

1. shared memory mapping
2. environment variables
3. command line arguments

### Command line

```text
--m2pack-key-hex <64-hex-master-key>
--m2pack-pubkey-hex <64-hex-public-key>
--m2pack-key-map <mapping-name>
--m2pack-key-id <integer>
```

### Environment

```text
M2PACK_MASTER_KEY_HEX
M2PACK_SIGN_PUBKEY_HEX
M2PACK_KEY_MAP
M2PACK_KEY_ID
```

### Shared memory

Default mapping name:

```text
Local\M2PackSharedKeys
```

Binary layout:

```c
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];
};
```

Recommended production path:

- launcher fetches or unwraps the current content key
- launcher creates the shared mapping
- launcher starts the client with `--m2pack-key-map Local\\M2PackSharedKeys`
- client reads runtime keys during startup
- client rejects `.m2p` loading if the runtime master key is missing

## 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.