nx_save_file_format.nx

nx_save_file_format.nx -- NSAV save file format encoder + decoder. V-CLIENT-STORE-1 per NISHI_CLIENT_STORE_CHARTER §2.2 + §8 M1. CARDINAL CONTEXT: per CS-2 client-owned storage cardinal, game saves live on the user's OWN FILESYSTEM, NEVER on substrate servers. This module provides the canonical wire format so saves are: - portable across browsers / devices / save paths (Path A / B / C) - integrity-checked (HMAC-SHA-256 footer detects tampering) - versioned (forward-compat via header version field) - cross-game distinguishable (game_id field; SHA-256 of identifier) - sovereign substrate-canonical (no proprietary blob format) FILE LAYOUT (per charter §2.2): offset 0..4 magic ascii "NSAV" offset 4..6 version u16 BE (V1 = 0x0001) offset 6..8 flags u16 BE (bit 0: encrypted [V+1]; bits 1-15 reserved) offset 8..40 game_id SHA-256("site_id|||game_name") 32 bytes offset 40..48 created_at i64 BE unix seconds since epoch offset 48..56 payload_len i64 BE byte length of payload offset 56..56+payload_len payload (opaque to substrate; game-defined) offset (..)..(..)+32 hmac_sha256 over bytes[0..(end-32)] with file_key = SHA-256("nishi-save|||" || game_id || passphrase) FILE_KEY derivation: HMAC key = SHA-256("nishi-save|||" || game_id || user_passphrase). For unencrypted V1 saves, passphrase = "" (empty); the key still provides integrity binding to game_id so a save for game A cannot be passed off as a save for game B. COMPOSES (per "avoid duplicate primitives" cardinal): nx_hmac hmac_sha256 (RFC 2104) sha256 digest helper for game_id derivation nx_syscalls sys_mmap COMPOSED BY: hub/nx_client_storage_emit V-CLIENT-STORE-3/4 emits JS that serializes/deserializes NSAV via this bench/nx_client_store_smoke V-CLIENT-STORE-6 vector tests