Initial secure packer CLI

docs/format.md

@@ -0,0 +1,65 @@
+# Format
+
+`m2pack-secure` uses a single-file archive format optimized for runtime loading.
+
+## Header
+
+Fixed-size header at the start of the archive:
+
+- magic: `M2PACK2`
+- format version
+- manifest offset
+- manifest size
+- manifest hash: `BLAKE2b-256`
+- manifest signature: `Ed25519`
+
+The header is intentionally tiny and stable so the loader can validate it before
+touching asset payloads.
+
+## Manifest
+
+The manifest stores:
+
+- normalized relative path
+- data offset
+- original size
+- stored size
+- compression algorithm
+- per-file nonce
+- plaintext hash
+
+The manifest is signed as a whole. Runtime validation should always happen in
+this order:
+
+1. read header
+2. read manifest
+3. compare manifest hash
+4. verify manifest signature
+5. resolve entry by path
+6. decrypt and decompress asset
+7. optionally hash plaintext for debug or strict mode
+
+## Data
+
+Each file payload is:
+
+1. compressed with `zstd`
+2. encrypted with `XChaCha20-Poly1305`
+3. stored in-place in the archive
+
+The file path is used as associated data so path tampering invalidates the
+payload authentication tag.
+
+## Security model
+
+This format is designed to prevent trivial unpacking and silent tampering. It is
+not a claim of absolute secrecy, because the client still contains the runtime
+key path and loader logic.
+
+Recommended production posture:
+
+- do not hardcode the final master key as a trivial static array
+- derive a session key in the launcher when possible
+- keep the signing public key in the client
+- keep the signing secret key only in CI or the release workstation
+- rotate the master content key on format-breaking releases