ArtifactProof: HMAC-signed receipts for a PPTX that passed QA

The gap ArtifactProof fills between QA approval and delivery

A deck can pass review and still arrive wrong. Between approval and the moment someone opens the file, it may be renamed, uploaded, downloaded, forwarded or replaced. The filename stays the same while the bytes change, or a correct QA report travels alongside the wrong revision. ArtifactProof targets exactly that window. It computes SHA-256 over the final PPTX, runs basic structure checks, optionally binds external QA reports, and writes a small JSON receipt signed with HMAC-SHA256 using a shared key supplied by the caller. Verification later re-reads the file and the evidence and compares digests, signature and key_id. The README is explicit about scope: no upload, no reliance on filename or modification time, no full OOXML semantic validation, no judgement about design. It is aimed at teams whose decks are generated by AI tools or automation, reviewed, archived and sent, and who want a stable file-integrity check inside CI or an air-gapped network.

How create and verify actually work

The create path hashes the PPTX before and after the structural checks. If another process modifies the file during that window, no receipt is written, which closes the obvious race where a file is hashed and then changed. The built-in checker validates the PPTX ZIP container, required OOXML parts, XML well-formedness and key relationships. When --evidence is passed, each external report is hashed too and its digest goes into the receipt. The receipt then records the file digest, byte size, check results and evidence digests, and is signed with HMAC-SHA256 under the caller's shared key, with a key_id attached. The verify path re-reads the PPTX and evidence, then checks digests, signature and expected key_id. Any mismatch produces a failure result rather than silently treating the file as the approved version. The receipt holds no PPTX body and no evidence body, only digests and metadata, so it stays small and readable by automation. Note the asymmetry: verification compares SHA-256 and byte size, so the file may be renamed locally, but the logical artifact name and evidence names written into the receipt are part of the signed content and cannot be changed at verify time.

Install ArtifactProof and create your first receipt

The README requires Python 3.11 or higher and recommends a dedicated virtual environment for the PyPI release. The signing key is read from the ARTIFACTPROOF_SIGNING_KEY environment variable and must be at least 32 random bytes, base64-encoded with the base64: prefix. Do not put a real key in code, receipts or command arguments.

python3 -m venv .venv
. .venv/bin/activate
python -m pip install artifactproof
export ARTIFACTPROOF_SIGNING_KEY='base64:REPLACE_WITH_BASE64_KEY'

For an offline install, the README says to download the wheel and SHA256SUMS from the same GitHub Release, verify the wheel first, then install with --no-index --no-deps. On Linux that check is a grep piped into sha256sum --check. Once installed, create a receipt for a deck and bind one external QA report:

artifactproof create deck.pptx \
  --artifact-name approved-deck.pptx \
  --evidence render=render-manifest.json \
  --receipt deck.receipt.json \
  --key-id local-ci

--artifact-name only controls the public logical name stored in the receipt; it does not change which file is read and is not used for path matching. Omit --evidence when there is no external report. Before delivery or after receipt, verify with the same key:

artifactproof verify deck.pptx \
  --evidence render=render-manifest.json \
  --receipt deck.receipt.json \
  --expected-key-id local-ci

Success prints short JSON. If you bound evidence at create time, you must supply a file with the same logical name and identical content at verify time. The README also ships a demo that needs no installation, no network and no access to your PPTX or key; it writes a one-page synthetic deck into a temporary directory and runs the real create and verify commands. On Linux or macOS run python3 examples/run_demo.py, on Windows PowerShell run py -3 examples\run_demo.py. The expected output includes a tamper-check line where detected is true, meaning the modification was caught, not that the synthetic deck passed visual review.

Where ArtifactProof stops being the right tool

HMAC is symmetric. Everyone holding the shared key can produce a valid receipt, so the scheme cannot distinguish between members of the same team, offers no public verification and provides no non-repudiation. If you need a third party to check a deck without holding your secret, or you need per-person attribution, this design cannot give it to you. The README also lists what the tool cannot replace: code signing, public-key signatures, trusted timestamps, and general file-security or release systems. It does not judge design, layout, accessibility, factual accuracy, content quality or malicious content, and it cannot confirm that a recipient actually received and opened the file. External visual acceptance reports can be bound as evidence, but ArtifactProof does not independently prove the report's contents are true. There is a concrete operational cost too: the README warns that conservative ZIP safety limits may reject legitimately large PPTX files, so a deck that opens fine in PowerPoint can still fail the structural check. The receipt is also only as trustworthy as the channel that delivered the shared key; the tool does not establish that trust for you. Version 0.1.0 is the first alpha, and the README states the command line and Python API may still change before 1.0.

ArtifactProof versus a plain SHA-256 checksum file

The obvious alternative is publishing or storing a SHA-256 checksum next to the deck. That works, and it is simpler. The difference is where the reference value lives and what it covers. A bare checksum needs a separate trusted place to hold it, and it covers only the PPTX bytes. ArtifactProof puts the PPTX digest, the evidence digests and the check results into one structured receipt, then signs that receipt with HMAC-SHA256. So a single receipt covers both the file and the QA artifacts bound to it, and tampering with the receipt itself is detectable. The trade-off is that you now manage a shared secret and a key_id, and verification requires the same key that created the receipt. A checksum file has no key to lose and no key to leak. If your only question is whether one file changed, a checksum is enough. If your question is whether this deck and these QA reports still match what was approved, the signed receipt carries more of the answer.

Receipt confidentiality, file permissions and the licence

Receipts are designed not to carry sensitive payloads: no PPTX body, no evidence body. By default the receipt stores the PPTX source filename, which may contain a client name or internal identifier. The README offers --artifact-name to substitute a neutral logical name, and notes that the tool validates the name format but the caller must still ensure the name holds nothing sensitive. Evidence logical names and key_id also go into the receipt and should be chosen with the same care. On Linux and macOS new receipts are written with 0600 permissions. Windows has no equivalent POSIX mode, so receipts inherit the target directory's DACL and should be saved into a directory only the intended accounts can read. Path separators are used for command input only; the receipt structure stores no source path. The project is licensed Apache-2.0, with the licence file listed in pyproject.toml and the package metadata declaring license = "Apache-2.0". That is a permissive licence with an explicit patent grant, but this is not legal advice; if you redistribute the wheel or embed the CLI in a product, read the LICENSE and RELEASING.md in the repository yourself. Maintenance signals are thin: the repository is not archived, and the last push was on 2026-08-25, the same day v0.1.0 was released.

Editorial conclusion

Adopt ArtifactProof if a PPTX passes QA, then travels through approval, renaming, upload and forwarding before it is actually delivered, and you already share a secret key inside one team. Skip it if you need public verifiability, non-repudiation, trusted timestamps or per-person attribution, because HMAC cannot separate holders of the same key. Before relying on it, run the demo, then create and verify one receipt against a real deck and deliberately modify one byte to confirm the failure path behaves as the README describes. Also check whether the conservative ZIP limits reject any legitimately large deck you produce.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. MaxHu-xuan/artifactproof on GitHub
4. README
5. Releases