# m2pack-secure

CLI-first archive builder for a modern Metin2 client pack pipeline.

It is designed as a replacement for legacy EterPack tooling when you control the
client source and want a format that is easier to automate and harder to tamper
with.

## Goals

- CLI workflow first, no GUI dependency
- deterministic manifest layout for automation
- `zstd` compression
- `XChaCha20-Poly1305` authenticated encryption per file
- `Ed25519` signed manifest for tamper detection
- JSON output for AI agents and automation
- no real content master key embedded in the client header

## Current commands

- `m2pack keygen`
- `m2pack build`
- `m2pack diff`
- `m2pack list`
- `m2pack verify`
- `m2pack extract`
- `m2pack export-client-config`
- `m2pack export-runtime-key`

## MCP Server

The repository also ships a Linux-friendly MCP server that wraps the `m2pack`
CLI for AI agents and automation.

Files:

- `mcp_server.mjs`
- `package.json`

Install:

```bash
npm install
```

Run:

```bash
npm run mcp
```

If the `m2pack` binary is not at `build/m2pack`, set:

```bash
export M2PACK_BINARY=/absolute/path/to/m2pack
```

Exposed tools:

- `pack_keygen`
- `pack_build`
- `pack_diff`
- `pack_list`
- `pack_verify`
- `pack_extract`
- `pack_export_client_config`
- `pack_export_runtime_key`
- `pack_binary_info`

Smoke test:

```bash
npm run mcp:smoke
```

## Python MCP Server

If you prefer Python over Node for the MCP wrapper, the repository also ships a
Python FastMCP variant.

Setup:

```bash
python3 -m venv .venv-mcp
. .venv-mcp/bin/activate
pip install -r requirements-mcp.txt
```

Run:

```bash
python mcp_server.py
```

Python smoke test:

```bash
python scripts/mcp_smoke_test.py
```

Linux headless end-to-end test:

```bash
python scripts/headless_e2e.py
```

Runtime scenario gate against the real client runtime:

```bash
python3 scripts/validate_runtime_gate.py \
  --runtime-root /tmp/m2dev-client-runtime-http
```

Audio scenario validator:

```bash
python3 scripts/validate_audio_scenarios.py \
  --runtime-root /tmp/m2dev-client-runtime-http
```

Self-hosted runtime CI orchestration:

```bash
python3 scripts/self_hosted_runtime_ci.py --json
```

## Build

```bash
cmake -S . -B build
cmake --build build -j
```

## Quick start

Generate a master content key and signing keypair:

```bash
./build/m2pack keygen --out-dir keys --json
```

Build an archive from a client asset directory:

```bash
./build/m2pack build \
  --input /path/to/client/root \
  --output out/client.m2p \
  --key keys/master.key \
  --sign-secret-key keys/signing.key \
  --key-id 1 \
  --json
```

Verify the archive:

```bash
./build/m2pack verify \
  --archive out/client.m2p \
  --public-key keys/signing.pub \
  --key keys/master.key \
  --json
```

Extract:

```bash
./build/m2pack extract \
  --archive out/client.m2p \
  --output out/unpacked \
  --key keys/master.key
```

Export a client config header for `m2dev-client-src/src/PackLib/M2PackKeys.h`:

```bash
./build/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
```

Export a runtime key payload for a launcher or CI handoff:

```bash
./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
```

Diff a source tree against an archive:

```bash
./build/m2pack diff \
  --left /path/to/client/root \
  --right out/client.m2p \
  --json
```

## Format summary

- Single archive file with a fixed header
- Binary manifest near the end of the file
- Signed manifest hash in the header
- Per-file random nonce
- Per-file AEAD ciphertext, authenticated with the relative file path

See [docs/format.md](docs/format.md) and
[docs/client-integration.md](docs/client-integration.md).
For Codex and Claude Code MCP setup, see [docs/agent-setup.md](docs/agent-setup.md).
For the runtime key payload contract, see [docs/launcher-contract.md](docs/launcher-contract.md).
For release steps, see [docs/release-workflow.md](docs/release-workflow.md).
For key rotation policy, see [docs/key-rotation.md](docs/key-rotation.md).
For legacy pack migration, see [docs/migration.md](docs/migration.md).
For Linux headless and real client runtime testing, see [docs/testing.md](docs/testing.md).