systemslibrarian/zk-proof-lab

# ZK Proof 实验室 [](https://github.com/systemslibrarian/zk-proof-lab/actions/workflows/pages.yml) [在线演示](https://systemslibrarian.github.io/zk-proof-lab/) 一个交互式、静态优先的实验室，通过六个展品帮助理解零知识证明 (Zero-Knowledge Proofs)：从阿里巴巴洞穴思想实验到非交互式 Fiat-Shamir 证明、zk-SNARK 直观流程、真实的浏览器端 Schnorr 验证以及 SHA-256 承诺。 本项目旨在快速传授直观理解，诚实地界定概念性演示与真实密码学操作的区别，并在无框架的代码库中展示面向生产环境的工程思维。

Schnorr identification: 3 honest rounds then a cheat attempt, all with real modular arithmetic

## 为什么这很重要 零知识证明位于现代隐私保护系统的核心：身份验证、区块链、数字签名、身份认证，以及任何需要在验证某事的同时不暴露底层秘密的工作流程。 大多数解释要么过于抽象，要么直接跳入代数运算。本项目旨在弥合这一鸿沟。学习者从洞穴开始，通过通俗易懂的英语理解核心思想，进而过渡到浏览器中实际的算术运算和真实的哈希计算。 ## 演示内容 - 应用密码学：BigInt 模幂运算、挑战-响应协议以及 Web Crypto SHA-256。 - 产品思维：概念优先的学习流程、诚实的标签说明以及建立信心的交互式 UI。 - 前端工程：纯静态 HTML/CSS/JS，无需构建步骤，无运行时依赖，支持 GitHub Pages 部署。 - 系统判断：在概念模型与真实密码学原语之间进行审慎的分离。 - 可访问性与用户体验 (UX)：键盘焦点状态、移动端友好的布局、减少动画支持，以及针对动态协议状态的实时区域更新。 ## 使用场景 - 向学生、团队或面试候选人讲授零知识证明。 - 演示为什么在隐私保护系统中“验证但不透露”至关重要。 - 向招聘人员和面试官展示一个结合了密码学、前端执行和清晰技术沟通的项目。 - 作为更大型教育产品或协议可视化平台的静态基础。 ## 展品 | 展品 | 协议 | 真实 vs 模拟 | 用户以通俗语言学到的内容 | |---|---|---|---| | 01 | 阿里巴巴洞穴 (Ali Baba Cave) | 概念性 | 证明你知道秘密暗语，但不说出那个词 | | 02 | 图三色 ZKP (Graph 3-Coloring ZKP) | 简化的承诺 | 证明地图被正确上色，但不揭示整个答案 | | 03 | Schnorr 身份识别 | 真实模算术 | 证明你知道一个秘密数字，但不透露该数字 | | 04 | 哈希承诺-揭示 (Hash Commit-Reveal) | 真实 SHA-256 | 现在锁定一个隐藏的选择，并在稍后证明你没有更改它 | | 05 | Fiat-Shamir 变换 | 真实哈希派生挑战 | 将交互式挑战-响应转变为单个非交互式证明 | | 06 | zk-SNARK 直觉 | 教学 SNARK 模型 | 理解 setup/prove/verify 以及公开/私有输入的分离 | ## 架构 该站点在运行时刻意保持简单，且结构清晰明确。 ``` zk-proof-lab/ ├── index.html # museum lobby / entry point ├── exhibits/ │ ├── cave.html # conceptual ZKP thought experiment │ ├── graph-coloring.html # selective reveal + simplified commitments │ ├── schnorr.html # real browser-side modular arithmetic │ ├── fiat-shamir.html # non-interactive hash-derived challenge demo │ ├── commit-reveal.html # real browser-side SHA-256 commitment flow │ ├── snark.html # zk-SNARK pipeline intuition model │ ├── transcript-lab.html # replay and compare proof transcripts │ └── scenario-presets.html # one-click deterministic demo routes ├── css/ │ └── style.css # shared visual system, mobile, accessibility ├── js/ │ ├── cave.js # animation, soundness tracking, bluff mode │ ├── graph.js # challenge flow, permutations, commitment table │ ├── schnorr.js # BigInt modpow and transcript verification │ ├── commit.js # Web Crypto SHA-256 and commit/reveal logic │ ├── fiat-shamir.js # hash-derived challenge and NIZK verification │ ├── snark.js # setup/prove/verify toy SNARK pipeline │ ├── transcript-lab.js # transcript replay/compare controller │ ├── utils.js # shared helper entrypoint │ └── shared.js # reusable protocol helpers ├── tests/ │ ├── logic-smoke.html # no-dependency logic checks │ ├── logic-smoke.js # Schnorr/hash/probability smoke tests │ ├── quality-gates.html # accessibility + visual-token checks │ ├── quality-gates.js # quality gate runner │ ├── browser-quality.mjs # Playwright browser quality checks │ ├── accessibility-audit.mjs # axe-core accessibility audit │ ├── capture-visuals.mjs # screenshot capture automation │ ├── capture-videos.mjs # Playwright video artifact capture │ └── make-visual-gif.sh # best-effort GIF summary generation └── docs/ └── zkp-primer.md # protocol property mapping and accuracy notes ``` 设计选择： - 静态优先：即时加载，无构建管道，易于 GitHub Pages 托管，易于离线使用。 - 共享样式，逻辑隔离：每个协议均可独立理解和调试。 - 诚实的密码学边界：概念性展品会被明确标记；真实原语会被显式指出。 ## 快速开始 无需安装。无需框架。无需构建。 ``` python -m http.server 8000 ``` 然后打开 `http://localhost:8000`。 可选的无依赖检查： - `http://localhost:8000/tests/logic-smoke.html` - `http://localhost:8000/tests/quality-gates.html` 或使用在线部署：[https://systemslibrarian.github.io/zk-proof-lab/](https://systemslibrarian.github.io/zk-proof-lab/) ## 示例结果 - 洞穴：经过 10 轮成功的验证，欺骗者的通过概率降至 $0.5^{10} = 0.0977\%$。 - 图三色：经过 10 轮，未被发现的作弊概率降至 $(5/6)^{10} \approx 16.15\%$。 - Schnorr：验证者使用浏览器中真实的 BigInt 算术检查 $g^s \bmod p = R \cdot y^c \bmod p$。 - 承诺-揭示：在承诺后更改竞标者 A 的出价会产生不同的 64 字符 SHA-256 摘要，并立即导致验证失败。 ## 技术深度 ### 1. 在关键处使用真实的浏览器端算术 Schnorr 展品没有伪造代数运算。它使用 BigInt 模幂运算，并在浏览器中验证实际的识别等式。参数为了可读性特意设置得很小，但协议机制是真实的。 ### 2. 在关键处使用真实的哈希 承诺-揭示展品使用 `window.crypto.subtle.digest('SHA-256', ...)` 和来自 `crypto.getRandomValues` 的密码学安全随机性。这不是一个玩具字符串哈希。 ### 3. 在协议展示中保持刻意的诚实 洞穴和图展品被标记为概念性或简化版，因为它们教授的是证明结构，而非生产级的承诺方案。这种诚实很重要。它展示了对协议的理解，而非对加密品牌的盲目模仿。 ### 4. 对评审者友好的工程选择 - 不为不需要框架的站点引入框架开销。 - 每个展品对应小型、隔离的模块。 - 显式的控制锁定，以避免异步交互期间的竞争条件。 - 针对动态状态变化和键盘导航的可访问性改进。 ## 为什么展品 1 是洞穴 阿里巴巴洞穴是 Jean-Jacques Quisquater 和 Louis Guillou 在 1989 年的论文《如何向你的孩子解释零知识协议》中提出的经典 ZKP 思想实验。 它仍然是最佳的入门解释，因为它在没有数学的情况下让三个核心属性变得直观： - 完备性：如果你知道秘密词，你总能从要求的一侧出来。 - 可靠性：如果你在虚张声势，你有一半的时间会失败。 - 零知识：验证者永远看不到你走了哪条路。 这就是为什么本项目在进入 Schnorr 之前先从洞穴开始。学习者先建立心智模型，然后再接触代数。 ## 面试要点 - 为什么保持整个项目是静态的，而不是选用 React 或后端？ - 为什么显式地将某些展品标记为概念性，而将其他的标记为真实的？ - 如果将 Schnorr 参数升级到生产级曲线，会有什么变化？ - 如何将其从一个教育演示转变为可复用的协议演练场？ - 教学清晰度与密码学完整性之间有哪些权衡？ ## 局限性 - Schnorr 参数为了教学目的故意设置得很小，用于生产并不安全。 - 图三色承诺为了教学进行了简化，并非完整的承诺构造。 - 这是一个教育性前端，不是密码学库或形式化验证器。 - 浏览器执行方便且可检查，但不能替代经过审计的生产系统。 ## 未来改进 当前路线图待办事项已清空。之前计划的改进（JSON 差异比较、CI 视频捕获、一键种子场景预设以及浏览器自动化中的协议不变量检查）均已实现。 ## 部署 GitHub Pages 通过 `.github/workflows/pages.yml` 配置，并在推送到 `main` 分支时自动部署。 ## 致谢 systemslibrarian · 哥林多前书 10:31

标签：Ali Baba洞穴, Schnorr协议, SHA-256, Web3, Web Cryptography API, zk-SNARK, 交互式证明, 前端安全, 区块链隐私, 原声JavaScript, 后端开发, 多模态安全, 密码学, 手动系统调用, 承诺方案, 教育演示, 数据可视化, 模运算, 网络安全, 菲亚特-沙米尔变换, 隐私保护, 零知识证明, 静态HTML