artifactproof README

The project's README from github.com/MaxHu-xuan/artifactproof. As one markdown file: README.md.

ArtifactProof（PPTX 交付物验真）

CI

中文导航：中文说明 · 中文项目资料

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。生成器不会覆盖已有路径； 若生成中途失败，它可能保留已经创建的纯合成文件，避免误删被并发进程替换的同名内容。

三个项目怎么选？

你要解决的问题 项目
确认最终 PPTX 及随附验收证据仍匹配结构检查后生成的 HMAC 签名收据 ArtifactProof（PPTX 交付物验真）
重启后核对卡住任务、超时与待投递状态，不把未知结果猜成成功 TaskStateGuard（任务状态守护）
分享或迁移聊天导出前，本地检查疑似秘密、个人信息形态、格式、SQLite 与扫描盲区 ChatArchiveGuard（聊天归档守护）

适用场景

它怎样工作？

  1. create 在检查前后分别计算 PPTX 的 SHA-256；如果检查过程中有其他进程修改文件， 收据不会创建。
  2. 内置检查器验证 PPTX 的 ZIP、OOXML 基本结构和关键关系。提供 --evidence 时，外部 报告也会计算 SHA-256 并写入收据。
  3. 收据记录文件摘要、字节大小、检查结果和证据摘要，再使用调用方提供的共享密钥生成 HMAC-SHA256 签名。
  4. 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 能验证什么，不能验证什么？

文件生成成功、基础结构检查通过、视觉验收通过、当前文件未被替换和文件真实送达，是 不同的结论。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?

How does it work?

  1. create calculates the PPTX SHA-256 before and after QA. If another process changes the file while QA is running, no receipt is created.
  2. 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.
  3. The receipt records digests, byte sizes, QA results, and evidence, then signs that payload with an HMAC-SHA256 key supplied by the caller.
  4. 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 (MaxHu-xuan/artifactproof)

Searching Database…

858 ·GitHub
Artifactproof
这是什么？ArtifactProof 是一款离线的本地命令行工具，它用 SHA-256 对最终 PPTX 计算哈希，执行基本的结构检查，并把调用方提供的 QA 证据绑定成一份具备防篡改能力的 HMAC-SHA256 回执，让你在交付前或收到后能重新验证内容没有被调包。
这是签名系统还是完整的 OOXML 校验器？都不是 —— 它是一个范围很窄的 CLI 工具，只检查 PPTX 的 ZIP/OOXML 结构和字节；它明确不是通用数字签名系统、完整的 OOXML 语义校验器，也不是视觉质量的评判者。
怎么为我的 PPTX 创建并验证回执？安装软件包（Python 3.11+），把共享签名密钥设置为环境变量，在 QA 结束后立即运行 'artifactproof create'，把 PPTX 和所有 --evidence 文件哈希成一份签名的回执，然后在交付前或收到后用同一个密钥运行 'artifactproof verify'。
运行它除了 Python 还需要别的东西吗？只需要 Python 3.11 或更新版本 —— 该工具的运行时代码只使用 Python 标准库，因此没有额外依赖，也不需要联网。
ArtifactProof 能告诉我 PPTX 真的送到了接收方手上或效果好看吗？不能。它只确认当前 PPTX 字节和证据仍与签名的回执相符；它不能取代代码签名、公钥签名或可信时间戳，也无法评判设计、排版、无障碍性，或文件是否真的被接收并打开。
回执在 Windows 上的工作方式与在 Linux 或 macOS 上一样吗？回执格式和验证结果在各平台上完全一致，但文件保护不同：Linux 和 macOS 上的回执会获得 0600 权限，而 Windows 没有等效的 POSIX 位，只能依赖目标文件夹的 ACL，因此回执应存放在受限目录中。
它会上传我的 PPTX 或通过网络发送任何数据吗？不会 —— 它不上传任何内容，PPTX、证据和回执都完全保存在本地存储中，运行时代码只使用 Python 标准库，没有网络客户端。
为什么用 HMAC 而不是单独保存一个 SHA-256 校验和？单独的校验和需要为参考值准备自己的可信存储，而 ArtifactProof 把 PPTX 摘要、证据摘要和 QA 结果打包进一份回执，并用共享的 HMAC-SHA256 密钥对整个载荷签名 —— 不过你仍需要一个安全通道来共享该密钥。
回执生成后如果有人篡改 PPTX 会怎样？'artifactproof verify' 会重新计算哈希并返回失败，而不是把文件当作已通过验证，项目的 60 秒演示就通过修改生成的演示文稿并展示验证失败证明了这一点。
我能在回执中隐藏真实的客户专属文件名吗？可以，在创建时通过 --artifact-name 传入一个中性的逻辑名称；该工具会拒绝路径分隔符和保留字符，但确保名称中不含敏感文本仍是你自己的责任。
它现在可以投入生产使用了吗？还不能完全 —— 0.1.0 是首个 alpha 版本；回执格式已基本定型，但 CLI 和 Python API 在 1.0 发布之前仍可能变化。
What are similar projects?bashka, turbocrypt, chat-archive-guard, GDecay, osv-scanner, Airsec, fireworks-open-eli5, vet
Which topics is it in?powerpoint, supply-chain-security, pptx, cryptography, ci, cli-tool, json, security-tools, offline, command-line-tool, security, apache-2.0
Creator
MaxHu-xuan
Size
0.1 MB
Stars
858
Updated
CommitAug 25Releasev0.1.0Aug 25
Age
1mo
Commits · 90 Days