# P3 — Checkpoint persistence round trip (Phase-0 proof harness)

> **THESE ARE PHASE-0 PROOF HARNESSES, NOT SHIPPED CODE.** Nothing here is imported by
> `matrx_scraper`, wired into a service, or intended to run in production. It exists to
> answer one question with real measurements before WS-2/WS-3 build the real thing.
>
> **🚨 THE KMS WRAPPER IS A LOCAL STAND-IN, NOT AWS KMS.** This machine has no `aws`
> CLI and no KMS access. `envelope.LocalKmsSubstitute` keeps the AWS KMS *interface*
> (`generate_data_key` / `decrypt`, both taking an encryption context bound as AAD) so
> WS-3 swaps in boto3 KMS by replacing ONE class — but it provides **none** of KMS's
> security properties: the master key is a local file, so there is no HSM, no key
> policy, no CloudTrail, and no cryptographic erasure by key deletion. Every manifest
> this harness writes carries `"kms_is_real": false`.
>
> **No real providers are ever used**, per PLAN.md. `testapp.py` is a synthetic local
> site bound to `127.0.0.1`.

## The claim under test

PLAN.md §Secure profile storage + §Stop + §Start: a **cleanly closed** Chromium profile
can be archived, AES-256-GCM encrypted under a per-checkpoint data key, have its
directory destroyed, and be restored elsewhere **still authenticated** — while tamper,
wrong encryption context, truncation, and manifest mismatch **fail closed**.

## Files

| File | What it is |
|---|---|
| `testapp.py` | Synthetic provider: httpOnly session cookie + localStorage + IndexedDB + a `/api/whoami` the server answers from the cookie. `127.0.0.1` only. Port **8731 is pinned** — localStorage/IndexedDB origins include the port, so restoring on a different port would invalidate the proof. |
| `envelope.py` | The PLAN.md envelope flow: random 256-bit DEK, AES-256-GCM with a fresh 96-bit nonce, encryption context `{profile_id, key_version, purpose}` bound as AAD on **both** the DEK wrap and the payload, and a manifest (nonce, wrapped DEK, content hash, ciphertext hash, byte counts, format version, Chromium version). Plaintext DEK is never persisted. `decrypt_checkpoint` verifies before it writes — every failure raises `CheckpointVerificationError` **before** any output file exists. |
| `run_proof.py` | The whole experiment: establish state → live-copy probe → clean close → archive → encrypt → `rmtree` the original → restore to a NEW path → relaunch and assert → 9 negative tests → measurements. Chromium's SQLite artifact is read only through matrx-orm's validated local-artifact projection boundary. |
| `inspect_cookie_crypto.py` | Addendum: reports which Chromium cookie-encryption scheme the profile used and, for `v10`, decrypts a cookie with the public constant `peanuts` to show what the inner layer is actually worth. Its cookie projection uses the same read-only matrx-orm boundary. |
| `out/results.json`, `out/run.log` | Machine- and human-readable output of the last run (gitignore-able; regenerated every run). |

## Re-run

```bash
cd aidream/packages/matrx-scraper/proofs/cloud_browser/p3_checkpoint_persistence
xvfb-run -a python3 run_proof.py          # exit 0 = every sub-claim PASS
python3 inspect_cookie_crypto.py          # addendum, run after the above
cat out/results.json
```

Requirements actually used on the proof machine: Python 3.11.15, `playwright` 1.62.0
(Python), Chromium **141.0.7390.37** from `/opt/pw-browsers/chromium-1194`,
`cryptography` 41.0.7 (needed `pip install cffi` first — the Debian `cryptography` in
`/usr/lib/python3/dist-packages` panics with `ModuleNotFoundError: _cffi_backend`
until `cffi` is present), `xvfb-run`. The browser runs **headed on Xvfb**, matching
PLAN.md's `handoff_capable` worker mode.

`run_proof.py` deletes and recreates `out/` on every run, and destroys the profile
directory it created. It touches nothing outside this folder except `/tmp` scratch
copies of SQLite files it reads.

## Result (2026-08-17, 3 identical runs)

All seven sub-claims PASS; all nine negative tests fail closed with no plaintext
written. Full numbers, the live-copy failure mechanism, and the two findings that go
beyond PLAN.md are in
`common-docs/projects/persistent-cloud-browser/reports/WS-0-proofs.md`.
