feat(sanitize): materialize an approved derivative from its archive

[abrichr]

The gap

approve_derivative computes the approval over the archive's own SHA-256, so _write_deterministic_archive skips APPROVAL_NAME. That is correct, and it has a consequence: an archive unzipped anywhere else is a valid derivative carrying no approval.

ARCHIVE members           : ['.openadapt-sanitization.json', 'events.jsonl', 'frames/before.png', 'meta.json']
CLOUD load_valid_approval : FAILED: Sanitized artifact has not been approved

openadapt-cloud's requalification action does exactly that (unzip recording.approved.zip -d .../recording), so its production deploy has failed since 2026-08-18. compile hides the same gap one step earlier: it sets source_recording_sha256 only if (recording / ".openadapt-approval.json").is_file(), so the runner built a bundle with null provenance and only validate-hosted complained.

What this adds

openadapt-flow materialize-approved \
  --archive recording.approved.zip \
  --approval recording.approval.json \
  --out recording/ \
  --expect-archive-sha256 <digest the caller already trusts>

It extracts the archive into a new empty directory, places the reviewer's existing approval record beside it, and runs load_valid_approval unchanged. Nothing is auto-approved, no check is skipped, and load_valid_approval is not relaxed.

--approval takes either shape a real deployment has:

• the derivative's .openadapt-approval.json, used verbatim;
• the openadapt.sanitization/v1 ingest envelope, which is what a cloud deployment actually persists. Every field carrying authority comes from that stored envelope: archive SHA-256, archive size, reviewer, approval time, approval method. The two tree hashes are functions of the extracted bytes that the archive SHA-256 already binds, so they are recomputed rather than transported, and the envelope is cross-checked against the extracted manifest on kind, policy version, execution semantics, and coverage. A derivative whose manifest records no approval_verification rescan is refused: it was never approved.

An envelope recording an automatic approval must carry its policy key id and MAC. The MAC is verified wherever OPENADAPT_SANITIZATION_POLICY_KEY is configured, reusing the exact canonicalization build_ingest_manifest signs (factored into _policy_signature_message, one definition now instead of two).

Extraction trusts no member name. Absolute paths, .. segments, backslashes, directory entries, symlinks, and any member named .openadapt-approval.json are refused before a byte is written. A failure leaves no approval file behind.

On signing

The approval record is unsigned today and stays unsigned here. That is a deliberate call, not an oversight, and the docs say so plainly.

Signing buys something when the approval and the artifact it approves travel on different channels, so the verifier does not already trust whoever hands it the bundle. That is not this shape. The record moves on the same channel as the archive, under the same access control, and the caller pins the archive digest from a reviewed source. Anyone who could forge the record could equally swap the archive and its pin, which defeats the gate whether or not a signature exists.

The available key would also be the wrong key. The workflow's reviewer is ${GITHUB_ACTOR}@github-actions, and a signing key held in Actions secrets attests "CI had the secret", not "a named person reviewed this". A signature there would invite more trust than the fact deserves.

What changes the answer: the moment a record is accepted from a lower-trust source (a customer upload, an ingest request body, a bucket with wider write access, another org's runner), or the moment the reviewer name becomes evidence shown to a third party rather than a description. The codebase already draws this line correctly for automatic approvals, which cross into cloud ingest and therefore carry a MAC.

Tests

tests/test_sanitized_artifact.py, committed before the implementation (15d8e2d then 40dbccf). At the test-only commit the module cannot import and no test runs; the implementation commit turns all of them green. They cover the reproduction, the round trip, the envelope path, compile provenance (asserting null before and bound after), a tampered archive, an unexpected digest, an approval for another artifact, a traversing member, a member carrying its own approval, a non-empty destination, a policy envelope missing its signature, a bad MAC, and the CLI.

Paired with openadapt-cloud PR (linked below). Cloud needs a Flow release carrying this command — 1.34.0 does not have it, and cloud must not pin a version that does not exist.

[abrichr]

Paired with OpenAdaptAI/openadapt-cloud#340, which wires the requalification action to this command. Flow merges and releases first.