ArtifactProof（PPTX 交付物验真）
中文导航：中文说明 · 中文项目资料
English navigation: English overview · Technical reference
ArtifactProof · TaskStateGuard · ChatArchiveGuard
中文说明
检查通过的 PPTX，交付时还是同一份吗？
一份 PPTX 通过检查后，可能还要经历审批、重命名、上传、下载和转发。到了真正交付时，
文件名可能没变，文件内容却已经被替换；也可能拿着正确的质检报告，发出的却是另一版。
ArtifactProof 在本地为最终 PPTX 计算 SHA-256，执行基础结构检查，并把调用方选择的外部
质检证据一起绑定到 HMAC-SHA256 收据。交付前或接收后再次验证，可以确认当前 PPTX 与
提供的证据字节是否仍和该收据记录一致。
它不上传文件，也不依赖文件名和修改时间。它不是通用数字签名系统，不做完整 OOXML 语义
验证，也不判断设计美感；它专注于补上 PPTX 基础结构检查、外部 QA 证据与最终交付文件
之间的完整性缺口。
60 秒试跑
需要 Python 3.11 或更高版本。演示不需要安装、不访问网络，也不读取你的 PPTX 或密钥；
它只在临时目录生成一页合成演示稿，运行真实的 create 和 verify 命令，再确认文件被
改动后验证会失败。
Linux 或 macOS：
python3 examples/run_demo.py
Windows PowerShell：
py -3 examples\run_demo.py
预期输出：
{"evidence":"synthetic-review.json","ok":true,"operation":"generate","pptx":"synthetic-deck.pptx"}
{"ok":true,"operation":"create","qa":"pass","receipt_written":true}
{"ok":true,"operation":"verify","verified":true}
{"detected":true,"ok":true,"operation":"tamper-check"}
最后一行表示篡改已被发现，不表示演示稿通过了视觉审查或已经真实送达。演示输入的生成
方式和数据边界见
examples/README.md。生成器不会覆盖已有路径；
若生成中途失败，它可能保留已经创建的纯合成文件，避免误删被并发进程替换的同名内容。
三个项目怎么选？
适用场景
- AI 工具或自动化流程生成 PPTX，需要在交付前检查基本结构，并保留可复验的结果。
- 演示文稿经过质检、审批、归档和发送，需要发现中途替换或误传。
- 渲染报告、可访问性报告、人工验收记录或其他证据需要对应到准确的 PPTX 文件。
- 团队希望在 CI、内网或无网络环境中增加一道稳定的文件完整性检查。
它怎样工作？
create 在检查前后分别计算 PPTX 的 SHA-256；如果检查过程中有其他进程修改文件，
收据不会创建。- 内置检查器验证 PPTX 的 ZIP、OOXML 基本结构和关键关系。提供
--evidence 时，外部
报告也会计算 SHA-256 并写入收据。
- 收据记录文件摘要、字节大小、检查结果和证据摘要，再使用调用方提供的共享密钥生成
HMAC-SHA256 签名。
verify 重新读取 PPTX 和证据，核对摘要、签名与 key_id。任何不一致都会得到失败
结果，而不是继续把文件当作已验证版本。
最终得到的是一份小型 JSON 收据和适合自动化读取的成功或失败结果。收据不包含 PPTX
正文或证据正文。默认情况下，它会保存 PPTX 的源文件名；如果该名称包含客户名称或内部
标识，可以用 --artifact-name 改为由调用方选择的中性逻辑名称。工具会检查名称格式，
但调用方仍须确保名称不含敏感信息。证据逻辑名称和 key_id 也会写入收据，同样不应包含
敏感信息。
用于你自己的 PPTX
1. 安装并设置签名密钥
需要 Python 3.11 或更高版本。对于已经发布到 PyPI 的版本，建议在独立虚拟环境中安装。
Linux 或 macOS：
python3 -m venv .venv
. .venv/bin/activate
python -m pip install artifactproof
export ARTIFACTPROOF_SIGNING_KEY='base64:REPLACE_WITH_BASE64_KEY'
Windows PowerShell：
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install artifactproof
$env:ARTIFACTPROOF_SIGNING_KEY = 'base64:REPLACE_WITH_BASE64_KEY'
如果要测试开发版，请从已经审核的源码 checkout 根目录安装：Linux 或 macOS 使用
python -m pip install .，Windows 使用
.\.venv\Scripts\python.exe -m pip install .。
离线使用时，请从同一个 GitHub Release 下载 wheel 与 SHA256SUMS，并先核验 wheel。
在包含这两个文件的目录中，运行与你的平台对应的命令。
Linux：
grep ' artifactproof-0.1.0-py3-none-any.whl$' SHA256SUMS | sha256sum --check -
macOS：
grep ' artifactproof-0.1.0-py3-none-any.whl$' SHA256SUMS | shasum -a 256 --check
Windows PowerShell：
$wheel = '.\artifactproof-0.1.0-py3-none-any.whl'
$entry = @(Get-Content .\SHA256SUMS | Where-Object {
$_ -match '^[0-9a-f]{64} artifactproof-0\.1\.0-py3-none-any\.whl$'
})
if ($entry.Count -ne 1) { throw 'wheel checksum entry missing or duplicated' }
$expected = ($entry[0] -split ' ', 2)[0]
$actual = (Get-FileHash $wheel -Algorithm SHA256).Hash.ToLowerInvariant()
if ($actual -ne $expected) { throw 'wheel SHA-256 mismatch' }
核验通过后，再使用 --no-index --no-deps 安装该 wheel；不要安装未经核验或来源不明的
同名文件。
请将占位值换成由至少 32 个随机字节生成的密钥，并保存在操作系统、CI 密钥库或团队使用
的密钥管理工具中。不要把真实密钥写进代码、收据或命令参数。
2. 检查 PPTX 并创建收据
Linux 或 macOS：
artifactproof create deck.pptx \
--artifact-name approved-deck.pptx \
--evidence render=render-manifest.json \
--receipt deck.receipt.json \
--key-id local-ci
Windows PowerShell：
.\.venv\Scripts\python.exe -m artifactproof create deck.pptx --artifact-name approved-deck.pptx --evidence render=render-manifest.json --receipt deck.receipt.json --key-id local-ci
没有外部报告时可以省略 --evidence。如果创建收据时绑定了证据，验证时必须提供逻辑名称
相同、内容也相同的文件。--artifact-name 只控制收据公开的逻辑名称，不改变读取哪个
文件，也不参与路径匹配；验证仍以 SHA-256 和字节大小为准，因此复验时文件可以换一个
本地名称。
3. 在交付前或接收后复验
Linux 或 macOS：
artifactproof verify deck.pptx \
--evidence render=render-manifest.json \
--receipt deck.receipt.json \
--expected-key-id local-ci
Windows PowerShell：
.\.venv\Scripts\python.exe -m artifactproof verify deck.pptx --evidence render=render-manifest.json --receipt deck.receipt.json --expected-key-id local-ci
创建与验证必须使用同一把签名密钥。成功时命令会返回简短的 JSON；PPTX、证据、签名或
预期的密钥标识不一致时会返回失败。
Linux、macOS 与 Windows 命令差异
收据格式和验证结论跨平台一致，主要差异在 Python 启动命令、虚拟环境激活、环境变量和
多行命令写法。
| 操作 |
Linux |
macOS |
Windows PowerShell |
| 启动 Python |
python3 |
python3 |
py -3 |
| 创建虚拟环境 |
python3 -m venv .venv |
python3 -m venv .venv |
py -3 -m venv .venv |
| 激活虚拟环境 |
source .venv/bin/activate |
source .venv/bin/activate |
.\.venv\Scripts\Activate.ps1 |
| 设置签名密钥 |
export ARTIFACTPROOF_SIGNING_KEY='…' |
export ARTIFACTPROOF_SIGNING_KEY='…' |
$env:ARTIFACTPROOF_SIGNING_KEY = '…' |
| 拆分长命令 |
行末使用 \ |
行末使用 \ |
行末使用反引号，或使用单行命令 |
Linux 和 macOS 上，新收据使用 0600 权限。Windows 没有相同的 POSIX 权限位，收据继承
目标目录的 DACL；应将它保存到只允许预期账户访问的目录。路径分隔符只用于命令输入，
收据结构本身不保存源路径。
ArtifactProof 能验证什么，不能验证什么？
- 能验证：当前 PPTX 和外部证据是否与签名收据记录的字节内容一致。
- 能检查：Transitional OOXML
.pptx 的 ZIP 安全边界、必要部件、XML 和基础关系。
- 能辅助：把 PPTX 质检证据与最终文件绑定，并在交付前后复核文件完整性。
- 不能代替：代码签名、公开密钥签名、可信时间戳或通用的文件安全与发布系统。
- 不能判断：设计美感、排版、可访问性、事实准确性、内容质量、恶意内容或收件人是否
已经收到并打开文件。
文件生成成功、基础结构检查通过、视觉验收通过、当前文件未被替换和文件真实送达，是
不同的结论。ArtifactProof 直接检查基础结构和当前字节是否匹配；外部视觉验收或交付报告
可以作为证据文件绑定，但 ArtifactProof 不会独立证明报告内容真实，也不会把报告存在
误写成已经交付。
HMAC 适合持有同一共享密钥的团队。它不能区分共享该密钥的不同成员，也不提供公开验证
或不可否认性。保守的 ZIP 安全限制可能拒绝体积异常大的合法 PPTX。0.1.0 是首个 alpha
版本，命令行和 Python API 在 1.0 前仍可能调整。
常见问题
如何确认交付的 PPTX 没有被替换？
在质检通过时运行 artifactproof create，保存 PPTX、收据和密钥；在发送前或接收后运行
artifactproof verify。验证通过表示当前文件、声明的证据和签名收据彼此一致。它不表示
文件永远不会再变化，因此应尽量在实际交付或使用前复验。
ArtifactProof 与单独保存 SHA-256 checksum 有什么区别？
单独的 checksum 需要另一个可信位置保存参考值。ArtifactProof 把 PPTX 摘要、证据摘要
和检查结果放进同一份结构化收据，并用 HMAC-SHA256 签名。验证方仍然需要通过安全渠道
获得正确的共享密钥；工具不会自动建立这层信任。
如何避免收据暴露原始 PPTX 文件名？
创建时加入 --artifact-name approved-deck.pptx。收据只保存这个逻辑名称，不保存源路径或
源文件名。逻辑名称会进入签名内容，验证时不能修改；但验证不要求本地文件继续使用
同一个名称。逻辑名称是公开元数据，不是文件路径；为减少跨平台误用，命令会拒绝路径
分隔符、首尾空格、结尾句点，以及 Windows 文件名保留字符和设备名。名称格式通过不代表
内容不敏感，因此不要填写客户名称、账号、项目代号或其他敏感信息。
文件会上传到网络吗？
不会。当前运行时代码只使用 Python 标准库，不包含网络客户端。PPTX、证据和收据都留在
调用方选择的本地存储位置。
Windows、macOS 和 Linux 都能使用吗？
可以，收据格式跨平台一致。Linux 和 macOS 上的新收据使用 0600 权限；Windows 上的
文件权限继承目标目录的 DACL，因此应把收据放在当前账户专用的目录中。
能直接检查 PDF、DOCX 或图片吗？
0.1.0 的内置检查器仅支持 PPTX。Python 调用方可以提供自定义 qa_runner，但其他格式
需要各自的威胁模型和测试，不能视为项目已经内置支持。
能判断 PPT 是否美观或内容是否正确吗？
不能。视觉审查、可访问性检查和事实核验需要其他工具或人工完成。可以把这些检查生成的
报告作为证据，让收据明确它们对应的是哪一份 PPTX。
中文项目资料
项目状态
0.1.0 是 ArtifactProof 的首个 alpha 版本。收据格式已有明确约定，但 Python API 与命令行
界面在 1.0 前仍可能调整。版本发布后可从 PyPI 安装；开发或离线使用时，请选择已经审核的
源码 checkout 或核验过的 Release wheel。
项目代码从头独立实现，测试夹具全部使用合成数据，并采用 Apache-2.0 许可证。项目来源
边界见
PROVENANCE.md，
许可正文见
LICENSE。
English Overview
Is the delivered PPTX still the file that passed review?
A PPTX may pass review and then move through approval, renaming, upload,
download, and delivery. The filename may stay the same while the bytes change,
or the correct QA report may be sent with a different revision.
ArtifactProof hashes the final PPTX locally, runs basic structural checks, and
binds caller-selected external QA evidence into an HMAC-SHA256 receipt. Verify
again before delivery or after receipt to confirm that the current PPTX and
supplied evidence bytes still match that receipt.
It uploads nothing and does not rely on filenames or modification times. It is
not a general digital-signature system, a complete OOXML semantic validator,
or a judge of visual quality. Its scope is the integrity gap between basic PPTX
structure checks, external QA evidence, and the final delivery file.
Try it in 60 seconds
Python 3.11 or newer is required. The demo needs no installation, network
access, real PPTX, or private key. It generates a one-slide synthetic deck in a
temporary directory, runs the real create and verify commands, changes the
temporary file, and confirms that verification fails.
Linux or macOS:
python3 examples/run_demo.py
Windows PowerShell:
py -3 examples\run_demo.py
Expected output:
{"evidence":"synthetic-review.json","ok":true,"operation":"generate","pptx":"synthetic-deck.pptx"}
{"ok":true,"operation":"create","qa":"pass","receipt_written":true}
{"ok":true,"operation":"verify","verified":true}
{"detected":true,"ok":true,"operation":"tamper-check"}
The last line means that the byte change was detected. It does not claim that
the demo deck passed visual review or reached a recipient. See
examples/README.md
for the generator and data boundary.
The generator never overwrites an existing path. If generation fails partway,
it may leave a synthetic output in place rather than risk deleting a path that
another process replaced concurrently.
Which project should I use?
| Your problem |
Project |
| Verify that a final PPTX and its supplied QA evidence still match the HMAC-signed receipt created after structural checks |
ArtifactProof |
| After a restart, reconcile stuck tasks, timeouts, and pending delivery without guessing success |
TaskStateGuard |
| Before sharing or migrating a chat export, locally audit potential secrets, personal-data patterns, format or SQLite issues, and scan gaps |
ChatArchiveGuard |
When should you use it?
- An AI tool or automation pipeline creates a PPTX that needs a basic structural
check and a result that can be verified later.
- A presentation passes through QA, approval, archival, and delivery, where an
accidental or deliberate replacement needs to be detected.
- Render output, accessibility reports, human review records, or other evidence
must stay associated with the exact PPTX that was checked.
- A team needs a deterministic file-integrity check in CI, on an internal
network, or in an offline environment.
How does it work?
create calculates the PPTX SHA-256 before and after QA. If another process
changes the file while QA is running, no receipt is created.- The built-in checker validates the PPTX ZIP package, basic OOXML structure,
and key relationships. Each
--evidence file is hashed and added to the
receipt.
- The receipt records digests, byte sizes, QA results, and evidence, then signs
that payload with an HMAC-SHA256 key supplied by the caller.
verify reads the PPTX and evidence again and checks their digests, the
receipt signature, and key_id. Any mismatch produces a failure instead of
treating the file as verified.
The output is a small JSON receipt plus stable success or failure results for
automation. It does not contain the presentation or evidence contents. By
default, it stores the PPTX basename. Use --artifact-name to replace a source
filename that contains a customer name or internal identifier with a neutral
logical name chosen by the caller. The tool validates the name's format, but
the caller remains responsible for keeping it non-sensitive. Logical evidence
names and key_id are also stored in the receipt and should not contain
sensitive information.
Use it with your own PPTX
1. Install and set a signing key
Python 3.11 or newer is required. After a release is published to PyPI, install
it in an isolated virtual environment.
Linux or macOS:
python3 -m venv .venv
. .venv/bin/activate
python -m pip install artifactproof
export ARTIFACTPROOF_SIGNING_KEY='base64:REPLACE_WITH_BASE64_KEY'
Windows PowerShell:
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install artifactproof
$env:ARTIFACTPROOF_SIGNING_KEY = 'base64:REPLACE_WITH_BASE64_KEY'
To test a development version, install from the root of a reviewed source
checkout: use python -m pip install . on Linux or macOS, or
.\.venv\Scripts\python.exe -m pip install . on Windows.
For offline use, download the wheel and SHA256SUMS from the same GitHub
Release. In the directory containing both files, verify the wheel with the
command for your platform.
Linux:
grep ' artifactproof-0.1.0-py3-none-any.whl$' SHA256SUMS | sha256sum --check -
macOS:
grep ' artifactproof-0.1.0-py3-none-any.whl$' SHA256SUMS | shasum -a 256 --check
Windows PowerShell:
$wheel = '.\artifactproof-0.1.0-py3-none-any.whl'
$entry = @(Get-Content .\SHA256SUMS | Where-Object {
$_ -match '^[0-9a-f]{64} artifactproof-0\.1\.0-py3-none-any\.whl$'
})
if ($entry.Count -ne 1) { throw 'wheel checksum entry missing or duplicated' }
$expected = ($entry[0] -split ' ', 2)[0]
$actual = (Get-FileHash $wheel -Algorithm SHA256).Hash.ToLowerInvariant()
if ($actual -ne $expected) { throw 'wheel SHA-256 mismatch' }
After verification succeeds, install the wheel with --no-index --no-deps.
Do not install an unverified file merely because it has the expected name.
Replace the placeholder with a key derived from at least 32 random bytes. Keep
the real key in an operating-system or CI secret store, or another secret
manager controlled by your team. Never place it in source cod
ArtifactProof is an offline, local command-line tool that hashes a final PPTX with SHA-256, runs basic structural checks, and binds caller-supplied QA evidence into a tamper-evident HMAC-SHA256 receipt, so you can reverify before delivery or after receipt that nothing was swapped.