tai/taicpp/docs/seal.md

seal parity (tai.py -> taicpp)

Namespace detz::seal, sources in src/seal/, one class per .h/.cpp pair, headers prefixed seal_. No dependency beyond the standard library: every primitive tai.py takes from hashlib/hmac/base64/os.urandom is written here.

Algorithm (must match byte for byte)

• master key: PBKDF2-HMAC-SHA256(passphrase utf-8, salt, 200000 rounds, 32 bytes).
• enc_key = HMAC(master, "tai-enc-1"), mac_key = HMAC(master, "tai-mac-1"), check = hex(HMAC(master, "tai-check-1")).
• <home>/.seal: json.dumps({"salt": b64(16 random bytes), "check": check}) (mode 0600), created on first use; later opens compare check, mismatch is SealError("wrong TAI_PASSPHRASE"), unreadable JSON or salt is SealError("seal file is corrupt"). An empty file counts as absent (python if raw).
• keystream: concatenated HMAC(enc_key, nonce || be32(counter)), counter from 0.
• envelope: tai1$ + b64(nonce16)$b64(cipher)$b64(HMAC(mac_key, nonce||cipher)). lock of an already sealed text or with a disabled seal returns the text unchanged.
• unlock errors: not sealed, sealed value is corrupt (not 4 $ pieces or bad base64), seal check failed (MAC mismatch, constant time compare).
• Empty passphrase: seal disabled, no .seal is read or written.

Parity table

tai.py	taicpp	status
SealError	store::SealError (store/errors.h, shared)	same messages
Seal (lock, unlock, safe_unlock, stream, enabled, default_key, load_master)	seal::Seal : store::SealPort	ported, safe_unlock inherited from SealPort
DEFAULT_PASSPHRASE	Seal::kDefaultPassphrase
resolve_passphrase	repl::Boot::resolve_passphrase (foundation)	not duplicated
rotate_seal(config, old_seal, new)	SealRotation::rotate(Paths, old, new)	events, secrets value+meta (with or without profile column), schedules, settings, mcp_servers, *.sys.md, *.session.json, *.bots.json; logs vault/seal_rotated
default-key upgrade in boot()	SealFactory::make(home, passphrase, default_key)	prints seal upgraded from default key to TAI_PASSPHRASE
hashlib sha256 / hmac / pbkdf2_hmac / base64	SealSha256, SealHmac, SealPbkdf2, SealBase64	RFC vectors in seal_test

Gaps (listed, not hidden): SealBase64::decode is strict about data after = where python silently discards it (never produced by either implementation). Invalid UTF-8 inside a sealed value is returned as bytes where python raises UnicodeDecodeError. Rotation paths are derived from the home (memory.db, profiles/) because the factory signature carries only the home. NULL values in events, secrets and schedules are not guarded in python either (python crashes, C++ re-seals an empty string).

Tests

make -f tests/seal.mk test from taicpp/:

• tests/seal_test.cpp: test_seal.py ported 1:1 (all 16 cases) against detz::store::Store, plus RFC 4231/7914/FIPS vectors, factory upgrade and corrupt .seal cases.
• tests/seal_diff.py with tests/seal_probe.cpp: master key and keystream equality, python seals / C++ opens and the reverse, .seal file written by C++ and opened by python, wrong passphrase, tamper, whole vaults written by one side and decrypted by the other, rotation in both directions, boot upgrade.