GlassOnTin/civic-kernel

# Civic Kernel [](https://github.com/GlassOnTin/civic-kernel/actions/workflows/test.yml) **一套任何人无法操纵、任何人皆可核查的投票规则 —— 小到无人能够掌控。** **初次了解？** 最清晰的入门途径是[正门](https://glassontin.github.io/civic-kernel/) —— 单页篇幅：它的用途、为何成立，以及你今天就能使用的工具。本 README 讲述的是同一个项目，但从源码视角出发。

单段落的技术版本

一套用于民主决策的轻量级、抗捕获协议 —— 十四种威胁、四项服务、四个动词、两种消息格式、一条底线、十二种拒绝。底线是《世界人权宣言》，重在衡量而非背诵。整个核心精简至单页篇幅：[`KERNEL.md`](KERNEL.md)。

## 它是什么 其主张是：**任何人皆可仅凭已公布的记录核查治理他们的流程。** 无需信任服务器。无需信任委员会。无需信任生成记录的软件。 运行中的原型是一个正在进行财务选举的六十人抽签社团。每张选票都是匿名的，但又能被证明由已登记的成员投出。选票永远不会被拆开：选票在加密状态下进行累加，且仅对该总和进行解密。一个与选举软件零代码共享的独立验证器，仅凭公布的文件就能确认结果。随后，它捕捉到了我们试图操纵选举的十二种手段，甚至包括委员会和两名见证人串谋篡改历史，以及最终试图抹去一张碍事选票的行为。当一切成立时，验证器的结束语是：*“没有人需要去信任那个小黑屋。”* 它的受众：无需任何人知晓其投票内容，即可看到自己选票被计入的成员。选举无法被任何人操纵的俱乐部或合作社。有朝一日——一场漫长的博弈——无需告诉任何人自己曾提出过询问，就能了解自己应得权益的家庭。 今天，它是一个处于村镇规模的研究原型，它对此直言不讳。每次部署都会发布一份机器可读的清单，说明其支持什么**以及忽略了什么** —— 允许存在弱点；但不允许隐瞒。 ## 它不是什么 它不是产品，不是平台，也不是区块链 —— 公民的任何环节中都不会出现 token。而且它从设计上就未“完工”：这个代码仓库像 Kernel 对待法律一样对待自己的文档。架构文章目前处于第 4 版，因为证据已经对其进行了三次修订——最近一次是根据原型所证明的结果——而第一批真实社区带来的经验将再次对其进行修订。 ## 为你提供的内容 - **你想知道自己享有什么权益。** [你享有什么权益？ →](https://glassontin.github.io/civic-kernel/owed.html) Pension Credit、Attendance Allowance 及其衍生权益——全部在你的设备上计算得出，所依据的规则引用了其编码的法律，并且不会向任何地方发送数据。更改一个答案，即可看到金额发生变化。据估计，英国每年有 240 亿英镑的支持资金无人认领；看看其中是否有属于你的部分，而且无需告诉任何人你曾查询过。 - **你即将进行一次投票——针对俱乐部、合作社或社团。** 在举手表决的同时进行一次影子投票：成员通过手机投下密封选票，决定权仍归举手表决，而事后任何人都可以通过公布的记录核查，确认没有人能够操纵选举。[委员会收到的邀请函](docs/shadow-agm-invitation.md) 说明了它的运作方式，包括诚实的限制说明；委员会的操作指南见 [`proto/README.md`](proto/README.md)。 - **你宁愿核查也不愿盲信。** [在你的浏览器中核查选举 →](https://glassontin.github.io/civic-kernel/verifier.html) 无需安装。每项核查都在你的机器上运行，针对已提交的选举记录或你拖拽到页面上的任何记录。通过标签查找选票。 - **你想试一试。** [亲自投出一票 →](https://glassontin.github.io/civic-kernel/cast.html) 面向投票者的浏览器端体验：生成注册密钥，密封选择，挑战执行密封操作的设备，构建匿名选票文件——然后[将其提交到验证页面](https://glassontin.github.io/civic-kernel/verifier.html#handpanel) 并观察计票变化，全程无需委员会参与。对于页面构建并统计的内容，独立的 Python 验证器必须接受并保持一致——CI 流程对此进行了严格约束。 - **一个俱乐部邀请你见证其选举。** [见证页面 →](https://glassontin.github.io/civic-kernel/witness.html) 只需五分钟，在浏览器中完成：只有当展示给你的历史记录延伸了你所记忆的历史记录时，才对俱乐部的检查点进行联签——这正是阻止篡改的手段。一个小巧的文件保存着你的密钥和记忆，而命令行见证工具读取的是同一个文件。 - **你遇到了一个专业术语。** *Receipt-free*、*ring signature*、*linking tag* —— [本仓库中的每一个术语，各有一句通俗解释](#the-words-in-plain-speech)。 - **你想了解你的权利目前处于什么位置。** [对比英国、德国、美国、欧盟宪章和中国的同样 30 项权利 →](https://glassontin.github.io/civic-kernel/scenarios.html#corpus) - **你想用通俗易懂的话了解它的用途。** [三个失效案例，已被核查 →](https://glassontin.github.io/civic-kernel/findings.html) Good Law Project 致力于应对的三个真实案例——未记录在案的决策、采购 VIP 通道、选民身份认证——以及一个任何人都可以核查的协议在应对每个情况时能做到什么、做不到什么，并附带了目前确实有帮助的实际措施。每个案例都链接到其完整的压力测试。 - **你想看理论论证。** [架构 →](https://glassontin.github.io/civic-kernel/architecture.html) 将民主重新定义为一个工程问题，并给出最小化的诚实解答。每个部分都以一句通俗的话开头；展开可查看完整的论证。然后观看 [真实场景与协议的碰撞 →](https://glassontin.github.io/civic-kernel/scenarios.html) —— 35 个压力测试故事，每个故事都根据 schema 进行了机器验证。 或者，只需大约一分钟，即可在本地运行一切——选举、验证过程以及十二种操纵选举的尝试：[`proto/test.sh`](proto/)。 ## 后续计划 在一个真实俱乐部的年度大会 (AGM) 期间进行影子模式运行——官方结果仍由举手表决决定——而在此背后，则是文章提到的更宏大愿景：*了解你应得的权益，而无需告诉任何人你曾开口询问*。

当前进展与未来路线图

在一个真实俱乐部的年度大会 (AGM) 期间进行影子模式运行，官方结果仍由举手表决决定。目前所有部分均已具备——面向投票者的 `cast.html`，面向相邻社团的 [`witness.html`](https://glassontin.github.io/civic-kernel/witness.html)（与 `clubvote.py witness` 相同的见证人：一个文件，适用两种工具），用于俱乐部注册的 `issuer`，用于持有密钥者的 `trustee`，用于报纸的 `anchor`，以及用于委员会的 `clubvote.py agm`，委员会仅持有一个密钥，即日志密钥：它负责发布、控制和组装，但其自身无法为任何事担保（操作指南见 [`proto/README.md`](proto/README.md)）。剩下缺的不是代码，而是一个真实的俱乐部、一个真实的季节，以及由此带来的经验教训。俱乐部实际收到的邀请函已经公开起草完成，包含了诚实的限制说明： [`docs/shadow-agm-invitation.md`](docs/shadow-agm-invitation.md)。 而在此背后，是文章本身称之为更宏大愿景的楔子——*了解你应得的权益，而无需告诉任何人你曾开口询问*。俱乐部投票是切入点；它在一群人的计票中验证了该机制，但其成员资格借助于俱乐部注册表，而不是赋予任何人新的资格。这个更大楔子的第一梯队现已运行： [`owed.html`](https://glassontin.github.io/civic-kernel/owed.html) 会在你的设备上计算出 Pension Credit、Attendance Allowance 及其衍生权益，每个问题都引用其规则，并在 CI 中受到独立评判程序的约束——它实现了 [`docs/wedge-one-v0.md`](docs/wedge-one-v0.md)，该文件以“成功测试驱动”的方式起草，并作为记录在案的计划。你的答案可以作为一个 *circumstances file* 导出——这是一个由你保管的文件，而不是一个账户——当规则发生变化时，只需一次拖拽即可重新导入；独立评判程序会原封不动地运行同一个文件。这条路线上的下一步是：丰富语料库，并且——当 attestation 生态系统发布时——实现“不透露信息即可证明”。

## 术语详解 本仓库中的每一个专业术语，各附一句解释。这些文档中出现的其他行话均可链接回此列表。 - **Transparency log** —— 公开记录：仅支持追加，每个条目通过哈希链与前一个条目相连，因此篡改昨天的记录会破坏今天所有的副本。 - **Witness** —— 对日志发布的指纹（即 *heads*）进行联签的独立方；篡改历史意味着要让每一个见证人重新对谎言进行签名。 - **Anchor** —— 将日志的最终指纹副本存放于所有签名方之外（想象一下报纸上的公开公告），从而确保历史记录在结束后无法被悄然删减。 - **Manifest** —— 一次部署中已签名的、机器可读的声明，说明其支持的内容和不支持的内容。 - **Subtraction** —— 完整设计中某次部署未实现的部分。这是允许的——但必须明确在 manifest 中大声声明出来。 - **The waist** —— 沙漏狭窄的中间部分，就像互联网也有其“腰部”（IP 数据包）：这是每次部署都必须共享的两种格式（一条日志条目和一份 manifest），刻意保持精简，以便任何内容都能与任何内容进行比较。 - **The lattice** —— 诚实的部分版本的阶梯：最顶端是完整设计，下方是每一个较弱的部署，每份 manifest 都准确说明自己在阶梯上的位置。 - **Ring signature** —— 证明*已发布名单中的某个成员*进行了签名，但隐藏了具体是谁。这就是选票如何在不泄露姓名的情况下证明其具有资格的方式。 - **Linking tag**（文献称之为 *nullifier*）—— 源自投票者密钥的单次选举专用标签：重复投票会导致标签匹配，从而暴露多次投票行为——但永远不会暴露姓名。这也是你在公共票箱中找到自己选票的方法。 - **Zero-knowledge proof** —— 证明某个陈述为真，且除该结论外不透露任何信息：系统只确认你在名单上，绝不知道你的名字。 - **Homomorphic tally** —— 选票在依然处于加密状态下进行累加；永远只对总数进行解密，绝不对单张选票解密。 - **Receipt-free** —— 你可以核查你的票是否被计入，但你无法向其他人证明你投给了谁。无物可卖；胁迫者事后也无从索要凭证。 - **Cast-or-audit** —— 在正式投票前，你可以挑战设备，要求其公开刚才生成的加密内容。作弊设备无法分辨这是测试还是真正的投票，因此作弊行为会被抓到。 - **Risk-limiting audit** —— 手工重新清点足够多随机抽取的纸质选票，以确认公布的获胜者——或者，如果未能确认，则触发全面重新计票。 - **Sortition** —— 通过抽签选择决策者，类似于陪审团的产生方式：一个随机且具有代表性的公民小组代表所有人进行审议。 - **Sybil attack** —— 一个人冒充许多人，以放大自己的声音。*Sybil resistance* 指的是系统对此行为设置的难度。 - **The floor** —— 《世界人权宣言》规定的三十项权利，被视为任何决策无论占多数都不得跨越的约束。 ## 布局 该代码仓库的逐个文件说明。

完整文件分布图

- **`KERNEL.md`** —— 提炼后的规范核心：目标、威胁、服务、动词、waist、拒绝、可衡量的状态。 - **`index.html`** —— 正门：一个论点与四扇门，根据访客的身份（通俗案例、理论论证、语料库或工具集）引导至相应区域。 - **`architecture.html`** —— 架构文档。 - **`findings.html`** —— 用通俗语言描述的三个真实案例：可核查的记录能做到什么以及在哪里止步，每个案例都链接到其完整的压力测试。 - **`proto/`** —— 第一批可运行代码：端到端的俱乐部投票选举（全部四个动词，真实的签名，真实的 Merkle log，独立的验证器，已提交的参考记录）。`proto/test.sh` 是成功通过的测试。 - **`verifier.html** + **`verifier.js`** —— 浏览器中的相同核查功能：加载或拖拽记录，观看每一项核查的运行，通过 linking tag 查找选票——而且仅限演示选举，你可以提交选票并观看计票变化（演示页面会公开其解密密钥；而真实选举的页面只能进行评判，绝不计数）。其引擎的判定结果受 `proto/verify.py` 约束，并由 CI 运行的 `tools/verify-parity.mjs` 和 `tools/collect-parity.mjs` 进行监控；其标准（选票组、两个 schema）固定在文件内部，绝不从外部获取。 - **`cast.html`** + **`cast.js`** —— 浏览器中的投票者端：生成注册密钥（绝不离开设备；issuer 仅对公钥进行认证），密封选择，在投票前挑战设备，通过花名册 ring 在选票上签名。`tools/cast-parity.mjs` (CI) 断言由页面构建、并通过 `clubvote.py collect` 处理的选票会被 `verify.py` 接受——并且会推动计票结果。 - **`owed.html`** + **`owed.js`** —— 楔子的第一梯队，v0 版：在你的设备上计算你应得的权益。表单是根据规则语料库生成的，因此无法引用其授权规则的问题根本无法存在；答案是一份 claim-trace —— 包含规则、所要求内容的每一步，以及刻意不问的内容。页面或其引擎中不存在任何网络 API，这一点已在 CI 中断言。 - **`entitlements/`** —— 其背后的规则语料库：`rules.schema.json`（记录格式），`uk/`（八个规则文件——Pension Credit Guarantee Credit、Housing Benefit、Council Tax Reduction、Attendance Allowance、Carer's Allowance、Winter Fuel Payment、Pension Age Disability Payment（第一个苏格兰条目）、75 岁以上老年人的电视许可证——以及作为数据的法定领取养老金年龄表格），`personas/`（22 个经过人工核查的家庭，来源标注日期），以及作为独立第二引擎的 `judge.py`。`tools/owed-parity.mjs` (CI) 确保页面与评判器在这一系列测试对象上得出完全一致的 claim-traces。 - **`witness.html`** + **`witness.js`** —— 浏览器中的见证社团端：生成见证密钥，锁定你所监督的对象（这是仪式的一部分——日志密钥通过带外传输，绝不能从请求中获取），对检查点进行联签，并拒绝任何不延伸至你记忆所锚定记录的历史记录。与 `clubvote.py witness` 可互换使用——相同的见证文件、相同的卡片、相同的联签、相同的拒绝——`tools/witness-parity.mjs` (CI) 通过在一次完整的选举中交替使用两个实现生成的文件来证明这一点。 - **`docs/`** —— 功能（动态）模型、英国发展轨迹的实际案例分析，以及用于选择下一个待测试危害的[分类流程](docs/triage.md)（`tools/triage.py` 作用于 `triage/cases.json`）。 - **`schema/`** —— waist：两种通用格式，体现为 JSON Schema (Draft 2020-12)。 - `log-entry.schema.json` —— 一次 transparency-log 事件（包含 `coercive.act` 和 `executive.act` 类型——分别代表国家的强制力及其资金——其主体必须各自引用一条授权规则）。 - `manifest.schema.json` —— 一个社区的 conformance manifest：它支持哪些服务、支持 30 项 UDHR 不变量中的哪几项、其 `decisions.coercion_resistance` 以及 `rights_guard.remedy`。 - **`scenarios/`** —— 设想的人类场景，每一个都走完了四个动词的流程。每一个内嵌的 manifest 和日志条目都根据 waist schema 进行了验证，并且每一个场景都必须为其攻击模式引用真实的现实先例（必填的 `precedents` 字段，截至 2026 年 7 月已核实 89 条引用）。 `scenario.schema.json` 是记录格式。 - **`corpus/`** —— 捕获在相同 schema 下的真实法律体系，共享 30 个不变量的核心主干： - `uk/` —— Human Rights Act 1998（通过 legislation.gov.uk 获取）+ 作为 `decision.closed` 条目的真实的下议院投票记录。 - `de/` —— Grundgesetz（通过 gesetze-im-internet.de 获取）。 - `us/` —— US Constitution 和 Bill of Rights。 - `eu/` —— EU Charter of Fundamental Rights（适用范围受第 51 条限制）。 - **`scenarios.html`** —— 一个自包含的可浏览站点，用于渲染场景和比较语料库。数据已内联，因此可作为静态文件提供（适配 GitHub Pages）；不进行任何运行时网络调用。 - **`tools/`** —— 验证器，同时也会重建 `scenarios.html` 中的内联数据。

## 构建 / 验证 需要 Python 3 和 `jsonschema`： ``` pip install -r requirements.txt python tools/validate.py # validate scenarios; rebuild scenario-data in scenarios.html python tools/validate-corpus.py # validate corpus; rebuild corpus-data in scenarios.html ``` 任何验证失败都会导致非零退出。该站点是预构建的（数据已内联），因此无需运行这些命令即可部署——只有在编辑了场景或语料库文件后需要重新生成数据时才运行它们。 ## 诚实的免责声明 - 这些场景是**基于事实的虚构**。人物和地点都是虚构的；每一种攻击模式都引用了记录在案的现实先例（在 2026 年 7 月添加时，每一条都对照其来源进行了核查）。它们是对架构的合理性测试，而非真实事件的记录，并且判定结论（`holds` / `strains` / `breaks`）是测试工具对架构文档自身声明和限制的解读——绝非背书。 - 对比权利地图比较**粗略**：即将 UDHR 条款映射到来自公开法律来源的国内宪法规定中。它指出了系统之间的差异所在。它不是法律意见或权威的比较法学术成果，某些单元格的内容有待商榷。 - `proto/` 是第一个也是唯一可运行的代码：这是一个刻意最小化的、由四个动词构成的循环，其 manifest 声明了自身的 subtraction——具体列表见 [`proto/README.md`](proto/README.md)，其中最重要的一点是：匿名集等同于花名册，且证明的工作量与其呈线性关系，这意味着它适用于一个村镇，而不是一个国家。其他一切都是规范、测试套件和语料库；*scenarios* 内嵌制品中的签名仍然是占位符。 ## 许可证 见 [`LICENSE`](LICENSE)。

标签：区块链, 后端开发, 多模态安全, 威胁建模, 密码学, 手动系统调用, 投票验证器, 数据可视化, 电子投票, 逆向工具, 隐私计算, 零知识证明