Corruption handling
What the framework treats as damaged, what it refuses before parsing, and the bounds that stop a hostile file.
Damaged is a decision, not a guess#
A save is trusted only after its integrity value is checked. Everything else follows from that:
| Check | Refuses when |
|---|---|
| Integrity value | The header, metadata or payload does not match the value recorded at write time. |
| Envelope structure | Trailing bytes exist after the declared end, or the declared lengths do not add up. |
| Container version | The file claims a format version the reader does not know. |
| Declared size | The payload is larger than Limits.MaxSaveSizeBytes. |
| Metadata size | The metadata block is larger than the configured ceiling. |
| Decompression bounds | Declared size, absolute ceiling or expansion ratio is exceeded — before and during decompression. |
The decompression checks matter because they run before memory is allocated for the expansion: a crafted file is stopped mid-expansion rather than allocated and then measured. Available
Detected damage versus "not readable here"#
Those are different situations and the framework treats them differently:
- Damaged: the integrity value does not match. The file is reported, and recovery can quarantine it and use the backup. See Recovery.
- Not readable here: the file is fine but this build cannot verify it — typically an encrypted save and no key. The code is
NF.PERSIST.SECURITY.KEY_UNAVAILABLE, and the file is left strictly alone rather than quarantined.
ISaveEncryptionProvider.TryVerify is what makes the difference decidable: it answers "could this payload be verified with the keys available", which is not the same question as "is this payload valid".
A checksum is not a tamper-proof seal#
Anyone who can edit a file can recompute a CRC32 or a SHA-256. Integrity detects accidental damage. Detecting an edit needs a keyed value (HMAC-SHA256) or authenticated encryption — see Integrity and Authentication. Neither is server authority.
Fuzzing and injected faults#
The pipeline is exercised against injected disk-full, permission, locking and partial-write faults, and against deliberately corrupted and malformed payloads. That is how the "either version intact" property is checked rather than asserted. Verified
Next#
- Integrity — the algorithms and what each one proves.
- Encryption — authenticated encryption and its bounds.
- Limitations — what none of this protects against.
Something wrong on this page? Every page here describes behaviour that is checked in the repository. If a page and the package disagree, the package wins.
Report a documentation problem · Frequently asked questions · Troubleshooting