import hashlib import io import json import struct import unittest from external_session import ( ArchiveFrameWriter, CHUNK_BYTES, read_ack, read_challenge, read_header, read_request, read_result, receive_archive, write_ack, write_challenge, write_header, write_request, write_result, ) from external_session import ACK_MAGIC, MAGIC class ExternalSessionTests(unittest.TestCase): def setUp(self): self.nonce = "a" * 64 self.backup_id = "backup-20261031T120000Z" self.manifest = {"format": 1, "git_revision": "b" * 40, "images": {}} def make_stream(self, payload=b"tar\x00bytes" * 100): stream = io.BytesIO() manifest_sha = write_header( stream, session_nonce=self.nonce, backup_id=self.backup_id, manifest=self.manifest ) framed = ArchiveFrameWriter(stream, maximum=4096) framed.write(payload[:37]) framed.write(payload[37:]) size, digest = framed.finish() stream.seek(0) return stream, payload, manifest_sha, size, digest def test_binary_archive_round_trip_and_live_ack_binding(self): stream, payload, manifest_sha, size, digest = self.make_stream() header = read_header(stream) target = io.BytesIO() self.assertEqual(receive_archive(stream, target, maximum=4096), (size, digest)) self.assertEqual(target.getvalue(), payload) self.assertEqual(hashlib.sha256(payload).hexdigest(), digest) ack = io.BytesIO() write_ack(ack, session_nonce=self.nonce, backup_id=self.backup_id, size=size, archive_sha256=digest, manifest_sha256=manifest_sha, verified=True) ack.seek(0) self.assertEqual(read_ack( ack, session_nonce=header["nonce"], backup_id=header["backup_id"], size=size, archive_sha256=digest, manifest_sha256=manifest_sha, )["verified"], True) def test_single_large_write_is_split_into_bounded_frames(self): payload = b"x" * (CHUNK_BYTES * 2 + 13) stream = io.BytesIO() writer = ArchiveFrameWriter(stream) writer.write(payload) size, digest = writer.finish() stream.seek(0) target = io.BytesIO() self.assertEqual(receive_archive(stream, target), (size, digest)) self.assertEqual(target.getvalue(), payload) def test_rejects_wrong_nonce_replay_and_unverified_ack(self): stream, _payload, manifest_sha, size, digest = self.make_stream() ack = io.BytesIO() write_ack(ack, session_nonce="c" * 64, backup_id=self.backup_id, size=size, archive_sha256=digest, manifest_sha256=manifest_sha, verified=True) ack.seek(0) with self.assertRaisesRegex(ValueError, "does not match"): read_ack(ack, session_nonce=self.nonce, backup_id=self.backup_id, size=size, archive_sha256=digest, manifest_sha256=manifest_sha) def test_rejects_corrupt_digest_truncated_stream_and_oversized_chunk(self): stream, _payload, _manifest_sha, _size, _digest = self.make_stream() read_header(stream) corrupted = bytearray(stream.getvalue()) corrupted[-1] ^= 1 corrupted_stream = io.BytesIO(corrupted) read_header(corrupted_stream) with self.assertRaisesRegex(ValueError, "SHA-256"): receive_archive(corrupted_stream, io.BytesIO(), maximum=4096) truncated = io.BytesIO(stream.getvalue()[:-3]) read_header(truncated) with self.assertRaisesRegex(ValueError, "ended before"): receive_archive(truncated, io.BytesIO(), maximum=4096) with self.assertRaisesRegex(ValueError, "size limit"): receive_archive(io.BytesIO(b"\x00\x10\x00\x01"), io.BytesIO(), maximum=4096) def test_final_result_is_bounded_and_typed(self): stream = io.BytesIO() write_result(stream, status="error", message="backup verification failed") stream.seek(0) self.assertEqual(read_result(stream)["status"], "error") with self.assertRaisesRegex(ValueError, "invalid"): write_result(io.BytesIO(), status="maybe") def test_rollback_challenge_pins_external_archive_identity(self): identity = { "backup_id": self.backup_id, "size": 128, "archive_sha256": "c" * 64, "manifest_sha256": hashlib.sha256( json.dumps(self.manifest, sort_keys=True, separators=(",", ":")).encode() ).hexdigest(), "manifest": self.manifest, } stream = io.BytesIO() write_challenge(stream, identity, session_nonce=self.nonce) stream.seek(0) self.assertEqual(read_challenge(stream), {"version": 1, "nonce": self.nonce, **identity}) identity["size"] = 0 with self.assertRaisesRegex(ValueError, "identity"): write_challenge(io.BytesIO(), identity, session_nonce=self.nonce) def test_release_request_is_strictly_typed_and_rejects_extra_commands(self): request = { "version": 1, "action": "release", "run_id": "301", "commit": "b" * 40, "descriptor_sha256": "c" * 64, } stream = io.BytesIO() write_request(stream, request) stream.seek(0) self.assertEqual(read_request(stream), request) with self.assertRaisesRegex(ValueError, "unexpected fields"): write_request(io.BytesIO(), request | {"shell": "id"}) def test_protocol_rejects_boolean_integers_and_non_boolean_ack(self): payload = json.dumps({"version": True, "action": "rollback", "data_compatible": True}).encode() request = io.BytesIO(MAGIC + struct.pack("!I", len(payload)) + payload) with self.assertRaisesRegex(ValueError, "unsupported version"): read_request(request) ack_value = { "version": 1, "nonce": self.nonce, "backup_id": self.backup_id, "size": 128, "archive_sha256": "c" * 64, "manifest_sha256": "d" * 64, "verified": 1, } payload = json.dumps(ack_value).encode() ack = io.BytesIO(ACK_MAGIC + struct.pack("!I", len(payload)) + payload) with self.assertRaisesRegex(ValueError, "acknowledgement is invalid"): read_ack(ack, session_nonce=self.nonce, backup_id=self.backup_id, size=128, archive_sha256="c" * 64, manifest_sha256="d" * 64) if __name__ == "__main__": unittest.main()