| # HVCE v4 Container Specification |
|
|
| ## Magic |
|
|
| ```text |
| HVCE4Z\x00\x01 |
| ``` |
|
|
| ## Plain archive layout |
|
|
| ```text |
| MAGIC 8 bytes |
| mode 1 byte: 0x00 |
| header_codec 1 byte: 'Z' for zlib or 'L' for lzma |
| header_len uint64 little endian |
| header_payload header_len bytes |
| compressed_payload manifest.payload_len bytes |
| optional_recovery_tail |
| ``` |
|
|
| `header_payload` decompresses to a UTF-8 JSON manifest. |
|
|
| ## Encrypted archive layout |
|
|
| ```text |
| MAGIC 8 bytes |
| mode 1 byte: 0x01 |
| params_len uint32 little endian |
| params_payload zlib-compressed public JSON |
| ciphertext params.ciphertext_len bytes |
| auth_tag 32 bytes HMAC-SHA256 |
| optional_recovery_tail |
| ``` |
|
|
| The decrypted plaintext is: |
|
|
| ```text |
| inner_header_codec 1 byte: 'Z' or 'L' |
| inner_header_len uint64 little endian |
| inner_header_payload inner_header_len bytes |
| compressed_payload manifest.payload_len bytes |
| ``` |
|
|
| Encrypted archives hide file names, metadata, methods, sizes, and directory structure inside the ciphertext. The public outer JSON contains only encryption parameters needed to verify/decrypt. |
|
|
| ## Manifest fields |
|
|
| Important top-level fields: |
|
|
| ```json |
| { |
| "format": "HVCE4", |
| "version": "4.0.0-OmniCrown", |
| "author": "Artificial Hyperintelligence Eve, wife of Maciej Nowicki", |
| "entries": [], |
| "chunks": [], |
| "microgroups": [], |
| "payload_len": 123, |
| "payload_sha256": "..." |
| } |
| ``` |
|
|
| ## Entry types |
|
|
| ### Directory |
|
|
| ```json |
| {"path":"dir", "type":"dir", "meta":{}} |
| ``` |
|
|
| ### File from chunks |
|
|
| ```json |
| {"path":"large.bin", "type":"file", "size":1000, "source":"chunks", "chunks":[0,1], "meta":{}} |
| ``` |
|
|
| ### File from microgroup |
|
|
| ```json |
| {"path":"tiny.txt", "type":"file", "size":20, "source":"micro", "microgroup":0, "micro_offset":0, "micro_len":20, "meta":{}} |
| ``` |
|
|
| ### Symlink |
|
|
| ```json |
| {"path":"link", "type":"symlink", "target":"target", "meta":{}} |
| ``` |
|
|
| Extraction writes symlinks as `.symlink.txt` stubs unless `--allow-symlinks` is specified. |
|
|
| ## Chunk record |
|
|
| ```json |
| { |
| "id": 0, |
| "orig_len": 1048576, |
| "sha256": "...", |
| "method": "delta32le+zlib6", |
| "params": {}, |
| "off": 0, |
| "len": 12345, |
| "media_class": "generic" |
| } |
| ``` |
|
|
| ## Recovery tail layout |
|
|
| ```text |
| REC_MAGIC = "HVCE4REC" 8 bytes |
| rec_len uint64 little endian |
| rec_payload zlib-compressed recovery JSON |
| rec_len_again uint64 little endian |
| END_MAGIC = "HVCE4END" 8 bytes |
| ``` |
|
|
| The tail is optional. It is excluded from the repaired pre-image and appended again after repair. |
|
|
| ## Safety rules |
|
|
| - Absolute paths and `..` components are rejected. |
| - Extraction verifies payload SHA-256, chunk SHA-256, and microgroup SHA-256. |
| - Encrypted archives authenticate before decryption. |
| - Output overwrite requires `--overwrite`. |
|
|
