220 lines
4.3 KiB
Markdown
220 lines
4.3 KiB
Markdown
# 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).
|