godot-save-checksum-canonicalization

Answer

Root cause (ED-GAP-024): the save side built save_data, hashed it without save_info, then appended save_info and checksum before writing. The load side parsed the file (which now contains save_info) and hashed with save_info minus checksum. The two payloads could never be byte-identical, so the checksum always mismatched.

Fix: insert save_info into the save data before signing. Both sides then hash the same canonical payload: deep-duplicate → erase checksum → compact JSON.stringify(copy, "", false). Godot 4 Dictionary preserves insertion order through JSON.parse/JSON.stringify, and JSON.parse ignores on-disk whitespace, so save-side and load-side payloads are byte-identical.

# SaveManager.gd  (Godot 4.x)
extends Node

const SAVE_PATH := "user://savegame.json"
const CHECKSUM_KEY := "checksum"
const SAVE_INFO_KEY := "save_info"

func _hash_sha256(payload: String) -> String:
    var ctx := HashingContext.new()
    ctx.start(HashingContext.HASH_SHA256)
    ctx.update(payload.to_utf8_buffer())
    return ctx.finish().hex_encode()

# The canonical payload BOTH sides agree on:
# deep-duplicate -> erase checksum -> compact JSON, insertion order preserved.
# NOTE: JSON.stringify's default sort_keys is TRUE; we pass false explicitly so
# both sides hash in insertion order (Godot 4 dicts keep it through parse/stringify).
func _canonical_string(save_data: Dictionary) -> String:
    var copy: Dictionary = save_data.duplicate(true)
    copy.erase(CHECKSUM_KEY)
    return JSON.stringify(copy, "", false)

func _checksum(save_data: Dictionary) -> String:
    return _hash_sha256(_canonical_string(save_data))

func save_game(data: Dictionary) -> Error:
    # 1. Deep-duplicate: caller's dict is never mutated.
    var save_data: Dictionary = data.duplicate(true)

    # 2. Insert save_info BEFORE hashing (the actual fix). Old code added it
    #    after hashing, so save hashed WITHOUT it and load hashed WITH it.
    save_data[SAVE_INFO_KEY] = {
        "version": ProjectSettings.get_setting("application/config/version", "0.0.0"),
        "schema": 1,
        "timestamp": Time.get_datetime_string_from_system(),
    }

    # 3. Sign (checksum excluded from the hashed payload), then attach it.
    save_data[CHECKSUM_KEY] = _checksum(save_data)

    # 4. Persist. Pretty-printing is cosmetic: parse() ignores whitespace,
    #    so on-disk formatting never affects the hash.
    var file := FileAccess.open(SAVE_PATH, FileAccess.WRITE)
    if file == null:
        return FileAccess.get_open_error()
    file.store_string(JSON.stringify(save_data, "  ", false))
    file.close()
    return OK

func load_game() -> Dictionary:
    if not FileAccess.file_exists(SAVE_PATH):
        return {}
    var file := FileAccess.open(SAVE_PATH, FileAccess.READ)
    if file == null:
        return {}
    var parsed: Variant = JSON.parse_string(file.get_as_text())
    file.close()
    if not (parsed is Dictionary):
        push_error("Save file is not a JSON object")
        return {}

    var save_data: Dictionary = parsed
    # Load side hashes the SAME canonical payload (duplicate minus checksum).
    var expected: String = save_data.get(CHECKSUM_KEY, "")
    if expected.is_empty() or not _constant_time_eq(expected, _checksum(save_data)):
        push_error("Checksum mismatch: save file corrupt or tampered with")
        return {}
    return save_data

static func _constant_time_eq(a: String, b: String) -> bool:
    if a.length() != b.length():
        return false
    var diff := 0
    for i in a.length():
        diff |= a.unicode_at(i) ^ b.unicode_at(i)
    return diff == 0

Notes for your Godot environment: - JSON.stringify(data, "", false) — the third arg is sort_keys; the default is true. Passing false deliberately relies on Godot 4's ordered dicts (per the fix spec). If you ever need order-independence instead, pass true on both sides — the invariant is that both sides use identical settings. - Use identical full_precision (default false) on both sides so float round-trips are stable; both sides call the same _canonical_string, so this is automatic. - Key order on save: caller's keys → save_info → checksum. On load after erasing checksum: caller's keys → save_info. Byte-identical.