EgorKhaklin/polaris-id

## 它是什么 美国人目前携带着六到八种互不相通的凭证：驾驶证、护照、社会保障卡、Real ID、选民登记、健康保险卡，以及越来越厚的一摞特定机构颁发的身份标识。每一种都是不同的凭证，由不同的权威机构签署，采用不同的安全标准，没有共享的吊销路径，也没有共享的审计追踪。 Polaris 将它们整合为**每人一个物理令牌**，在后量子密码学下进行签名，并具备**按上下文划分的验证机制**（银行、投票与医疗保健是不同的事件，具有不同的披露规则）和**零知识默认设置**（典型的验证过程根本不存储任何令牌标识符）。 本代码库是一个**可运行的参考实现**：包含 28 个模式表、11 个存储过程、一个包含 70 个路由的 Flask 应用程序（涵盖了所有用例）、一个用 Rust 编写并带有独立第二见证者的 Plonky2 ZK-SNARK 证明器、WebAuthn-MFA 操作员身份验证、一个带有实时地球仪的操作地图、一个位于后量子 TLS 边缘之后的生产级容器栈，以及一个只需双击即可启动所有组件的自修复 macOS 启动器。 它不是一份演示幻灯片。它是切实可运行的；每次代码提交时，CI 都会端到端地启动整个生产栈。 该系统存在于 [`polaris_sql`](polaris_sql/)、[`polaris_web`](polaris_web/)、[`polaris_cli`](polaris_cli/)、[`polaris_zk`](polaris_zk/) 中。其 C1-C10 不变量由 [`polaris_checks`](polaris_checks/) 进行机器检查，这是一个包含纯粹检查函数的扁平层级。 ## 核心难点 整合各类卡片只是简单的那一半。有趣的一半在于当对手出现时会发生什么。Polaris 在构造上就解决了其中六种威胁。 | 威胁 | 实践中的表现形式 | Polaris 的应对方式 | 位置 | |---|---|---|---| | **密码学胁迫** | “签署这笔交易，否则我打断你的手指。”持有人无法不受伤害地拒绝。 | 第二个秘密会产生一个难以区分的验证结果，并静默记录一条 DuressEvent。操作员的屏幕上不会显示任何异常。 | [duress-codes](DEVNOTES/ships/duress-codes.md) ‎ ‎ ‎ UC-12 | | **灾难性丢失** | 令牌丢失，持有人身份不明，没有凭证就无法证明自己是谁。 | 两阶段恢复仪式（发起然后完成）由四个 CHECK 约束和仅限管理员使用的第二密钥进行控制。 | [recovery-ceremony](DEVNOTES/ships/recovery-ceremony.md) UC-9 | | **量子迁移** | 当量子计算机到来时，如今的签名算法会在一夜之间被破解。 | 多签名过渡状态：一个令牌可以同时由经典算法和后量子算法签名，并有一条硬性规定，即只能有一个处于活跃状态。 | [multi-sig-migration](DEVNOTES/ships/multi-sig-migration.md) UC-6 | | **签发机构集中化** | 某个机构能够签发伪装成其他任何机构的令牌。 | 仅显式联邦：没有传递性信任。每一次跨机构验证都取决于一条活跃的 AgencyTrustAttestation 行。 | [federation](DEVNOTES/ships/federation.md) UC-10 | | **在不损失隐私的情况下实现公开可审计性** | “证明这个令牌在账本中”，但不透露具体是哪一个。 | 基于 Merkle 承诺的 Plonky2 ZK-SNARK。该证明不会泄露关于叶子节点的任何信息。 | [zk-snark](DEVNOTES/ships/zk-snark.md) ‎ UC-11 | | **签发机构越权** | 某机构超出策略范围进行工业规模的令牌吊销。 | 由触发器强制执行的按机构吊销率上限。受 IssuerDiscretionPolicy 行约束，并由 `pg_advisory_xact_lock` 审计。 | [issuer-discretion](DEVNOTES/ships/issuer-discretion.md) UC-8 | 每一行都包含防御者的声明、攻击者的最优策略、均衡分析、有记录的次优攻击，以及在模式级别的强制执行轨迹。 ## 令牌模型 IdentityToken 是 Postgres 中的一行记录。物理卡片承载着密码学序列号；而该行承载着其他所有信息。 ``` IdentityToken ├── token_value VARCHAR(128) UNIQUE canonical cryptographic serial ├── physical_serial VARCHAR(64) UNIQUE hardware serial of the card ├── hardware_model VARCHAR(50) manufacturer / model ├── biometric_binding_type enum NONE · FINGERPRINT · FACE · IRIS ├── liveness_check_type enum PASSIVE · ACTIVE_CHALLENGE · MULTI_MODAL ├── individual_id → Individual the person ├── issuing_agency_id → Agency who issued it ├── algorithm_id → CryptographicAlgorithm ML-DSA-65 by default ├── predecessor_token_id → IdentityToken (self) the succession chain ├── activation_sequence INTEGER ≥ 1 which token in the lineage ├── status enum ACTIVE · RESERVE · DORMANT · REVOKED · LOST · EXPIRED ├── issued_date · activated_date · expiration_date └── duress_code_hash VARCHAR(255) NULL the second secret (optional) ``` 其形态承载着策略。有四个值得命名的不变量： - **每个个体只有一条 ACTIVE 记录。** 由 `(individual_id) WHERE status = 'ACTIVE'` 上的部分唯一索引强制执行，而不是由应用程序逻辑强制执行。替换令牌意味着沿着血统链向前推进，而不是打开第二行记录。这是章程中的约束 **C3**，并且它能在每次从备份中恢复后依然存活，因为它存在于索引中，而不是代码中。 - **算法是按引用而非字面值。** 签名算法是指向 `CryptographicAlgorithm` 的外键，这是一个包含 `quantum_resistant`、`nist_standard` 和 `deprecation_date` 的一等实体。代码库中任何地方都没有硬编码的密码学。明天要添加 ML-DSA-87 只需 `INSERT INTO`，而无需 `git push`。这就是约束 **C7**。 - **继承是一条链，而不是一个事件。** `predecessor_token_id` 是自引用的；从一个人首次签发到其当前令牌的完整血统是一个递归 CTE。恢复、替换和后量子迁移都会添加一个指向前置令牌的新行；没有任何东西会被覆盖。 - **胁迫仅对审计追踪可见。** 如果持有人在胁迫下输入了胁迫代码，在操作员可见的每个表面上，验证看起来与正常验证完全相同。审计记录中会出现一个 `DuressEvent` 行；操作员的屏幕不会透露任何信息。这是约束 **C6** 加上反胁迫机制协同工作的结果。 `CREATE TABLE` 位于 [`polaris_sql/01_schema.sql`](polaris_sql/01_schema.sql)。每一列都有文档说明；每一个 CHECK 约束都有一个配对的测试。 ## 架构 共四层。检查层只读取而不写入操作层。ZK 证明器是一个子进程，而不是一个服务。对于人类操作员来说，WebAuthn FIDO2 是唯一的身份验证路径；仅凭密码无法访问 admin 或 auditor 角色。 ``` ┌─────────────────────────────────────────────────────────────┐ │ CHECK LAYER │ │ polaris_checks — 67 flat invariant checks │ │ (C1-C10 · CSP · secrets posture · PQC wiring · CI proof │ │ pins · doc/schema drift · ZK two-witness · …) │ │ plain check_*(repo_root) functions; `run` gates CI │ └─────────────────────────┬───────────────────────────────────┘ │ reads (no writes) ┌─────────────────────────▼───────────────────────────────────┐ │ APPLICATION │ │ Flask (70 routes) · Atlas globe · WebAuthn MFA │ │ Dashboard · /sql console · structured /api/health │ └──────────┬──────────────────────────┬───────────────────────┘ │ │ ┌──────────▼─────────┐ ┌───────────▼──────────────────────┐ │ SCHEMA (Pg 16) │ │ ZK PROVER (Rust nightly) │ │ 28 tables │ │ Plonky2 SNARK · Merkle-incl. │ │ 11 stored procs │ │ + independent second witness │ │ 9 AoR by trigger │ │ /api/zk/epoch/close · /verify │ └──────────┬─────────┘ └──────────────────────────────────┘ │ signs with ┌──────────▼──────────────────────────────────────────────────┐ │ POST-QUANTUM SIGNATURES │ │ ML-DSA-65 (FIPS 204, default) · SLH-DSA (FIPS 205) │ │ ML-DSA-87 (high-assurance) · ECDSA-P256 (legacy/audit) │ └─────────────────────────────────────────────────────────────┘ ``` 每一层都可以独立构建。模式针对空的 Postgres 从 `00_load_all.sql` 加载。应用程序针对加载的模式从 `app.py` 启动。ZK 证明器在同一台机器上通过 `cargo +nightly build --release` 编译。检查层是一组纯函数的只读集合，用于控制 CI；它能在任何操作重启后保持不变。 将这一切维系在一起的约束是 **C1：审计记录**。十个实例（九个模式级，一个文件系统级）在事件发生的那一刻记录下每一个有意义的操作。系统中没有任何东西会在事后重建历史；如果在发生时没有被记录下来，它就不存在。 ## 密码学 签名算法注册表预置了五行。操作默认值是 **ML-DSA-65**：NIST 标准化的模块格数字签名算法，FIPS 204，3 级安全，于 2024 年定稿。 ``` algorithm family PQ NIST sec public-key signature ───────────────────────────────────────────────────────────────────────────── ML-DSA-65 ML-DSA ✓ FIPS 204 192 1,952 B 3,309 B ◀ default ML-DSA-87 ML-DSA ✓ FIPS 204 256 2,592 B 4,627 B high-assurance SLH-DSA-128s SLH-DSA ✓ FIPS 205 128 32 B 7,856 B hash-based hedge SLH-DSA-256s SLH-DSA ✓ FIPS 205 256 64 B 29,792 B hash-based, max ECDSA-P256 ECDSA FIPS 186-4 128 64 B 72 B LEGACY · sunsets 2027-12-31 ``` 有四点值得注意： - **默认算法已经是后量子的。** ML-DSA-65 是新令牌在第一天签发时所使用的算法。不存在“等量子计算时代到来时我们再迁移”的拖延；迁移目标就是当前的默认值。真实的 ML-DSA-65 签名字节通过 [liboqs](https://github.com/open-quantum-safe/liboqs) 并设置 `POLARIS_USE_REAL_PQC=1` 生成；如果关闭该标志，默认构建会记录一个确定性的占位符，以便在未安装 liboqs 的情况下属性测试仍可重现。保留 ECDSA-P256 仅仅是因为前 PQ（后量子）时代的审计查询需要通过外键解析该算法。 - **两个独立的见证者验证每一个真实签名。** 自 v9.133 起，通过 liboqs 验证的 ML-DSA-65 签名会由第二个独立的实现（通过 `cryptography` 实现的 OpenSSL 3.5）进行交叉检查。只有当两个见证者一致时，签名才会被接受；不单独信任任何一个密码学库。同样的原则也适用于 ZK 纪元根，一个单独的 Python 实现会将其与 Rust 证明器进行逐位比对重新计算。 - **TLS 边缘协商后量子密钥交换。** 公共边缘（使用限速插件自建的 Caddy）与支持该功能的客户端协商 **X25519MLKEM768** 混合 KEX；`caddy-edge` CI 任务在每次推送时针对真实证书证明握手成功。关于什么是和不是后量子的完整真实情况映射（令牌签名和哈希是；证书和 WebAuthn 在 NIST 时间表确定之前仍为经典算法）位于 [PQC-POSTURE.md](docs/reference/PQC-POSTURE.md)。 - **SLH-DSA 是一种多样性对冲。** ML-DSA 依赖于格问题，而 SLH-DSA 仅依赖于哈希函数的安全性。如果其中一个家族被破解，另一个则是独立的。这种对冲的代价是签名大小：SLH-DSA-256s 为 29.8 KB，而 ML-DSA-65 为 3.3 KB。Polaris 将后量子签名大小视为凭证的固有属性，而不是一个需要优化掉的问题。 **迁移 (UC-6 · `/uc6/migrate-algorithm`)** 是一种多签名过渡状态。在切换期间，一个令牌可以同时携带经典签名和后量子签名，并通过数据库强制实行一条规则：确切只有一个在操作上是活跃的。切换操作会写入一条审计轨迹可以重放的 `KeyMigration` 记录。 零知识表面独立于签名算法。[`polaris_zk/src/lib.rs`](polaris_zk/src/lib.rs) 中的 **Plonky2** 证明针对发布在 `/epochs` 的纪元承诺进行 Merkle 树包含证明。该证明不会泄露关于叶子节点的任何信息；它只回答“这个令牌在纪元 N 是否在账本中”。Rust 二进制文件是一个由 [`polaris_web/zk.py`](polaris_web/zk.py) 调用的子进程；Flask 应用程序在没有它的情况下也能优雅降级（每个页面正常提供服务，每个 UC-1..UC-12 流程正常工作；只有 `/api/zk/epoch/close` 和 `/api/zk/verify` 会静默）。 ## 生产环境状态 Arc B（2026 年 5 月至 6 月）弥合了架构复杂性与操作现实之间的差距。完整的生产栈随代码库一同发布，并且 **CI每次推送时都会端到端启动它**；这项任务在上线当天就暴露了四个导致生产环境停机的 bug，这正是其目的所在。 ``` client ── TLS 1.3 (X25519MLKEM768 hybrid KEX) ──▶ caddy (self-built edge) │ rate limiting · HSTS ▼ gunicorn/Flask (non-root, all capabilities dropped) ─▶ pgbouncer ── verify-ca TLS ──▶ postgres 16 │ streaming replication ─▶ standby └ pgBackRest WAL archiving ─▶ DR restore ``` 这在具体意义上意味着： - **在所有可能的地方使用 TLS。** 边缘使用带有自动配置的 Let's Encrypt；在 pgbouncer 到 postgres 的链路上使用证书固定（`verify-ca`）的 TLS。在 OpenSSL 3.5 扩展到这些镜像之前，内部链路将保持经典加密；[PQC-POSTURE.md](docs/reference/PQC-POSTURE.md) 如实地记录了这一差距。 - **加固的容器。** 每个生产服务都以非 root 用户身份运行，并丢弃了所有 Linux capabilities；镜像通过 apt/apk-upgrade 升级了它们的基础镜像，并且 **Trivy 在依赖项和镜像扫描中阻断了所有可修复的 CRITICAL 级别 CVE**。 - **经过演练的备份和灾难恢复，而非纸上谈兵。** pgBackRest WAL 归档、脚本化恢复以及一个运行完整备份/恢复往返的 CI 任务。操作手册：[DR.md](docs/operator/DR.md)、[FAILOVER.md](docs/operator/FAILOVER.md)、[RUNBOOKS.md](docs/operator/RUNBOOKS.md)、[SLOS.md](docs/operator/SLOS.md)。 - **可观测性。** 带有关联 ID 的结构化 JSON 日志、Prometheus 指标、[`deploy/observability/`](deploy/) 中的告警规则，以及一个报告每个组件状态的结构化 `/api/health` 接口。 - **隐私机制。** 通过经过审计的假名化实现被遗忘权（审计记录保持完整；但从其中看不出具体个人）、保留/归档工具，以及从一开始就不存储链接的 ZK 验证。 诚实的差距记录位于 [docs/PRODUCTION-READINESS.md](docs/PRODUCTION-READINESS.md)：哪些已完成，哪些受操作员限制（S3 异地存储库、备用主机、HSM 托管、寻呼机后端、法律审查），哪些受第三方限制。 ## 与现有身份系统的差异 世界上并不缺乏身份基础设施。问题在于 Polaris 做到了哪些现有已部署系统没有做到的事情。 | 系统 | 国家级签发 | 后量子操作默认值 | 零知识默认值 | 抗胁迫原语 | 模式层面的只追加审计记录 | |---|:---:|:---:|:---:|:---:|:---:| | **Real ID** (美国，2005年法案，2025年全面执行) | ✓ | ✗ | ✗ | ✗ | ✗ | | **mDL / ISO 18013-5** (移动驾驶证) | ✓ | ✗ | 部分 | ✗ | ✗ | | **Aadhaar** (印度，13亿+注册用户) | ✓ | ✗ | ✗ | ✗ | 部分 | | **e-Estonia** (电子身份证 + 电子居民) | ✓ | ✗ | ✗ | ✗ | 部分 | | **W3C DIDs / VCs** (规范，去中心化) | ✗ | 取决于方法 | ✓ | ✗ | 不适用 | | **Polaris** (本代码库) | ✓ | ✓ ML-DSA-65 | ✓ Plonky2 + R6 脱敏 | ✓ DuressEvent | ✓ 9 个模式实例 | 其中几个对比值得用文字叙述，而不是仅仅列表。 **Real ID** 标准化了证件和真实性检查。它没有标准化验证协议；卡片是由打印机签名的，而不是由密钥签名的。它根本没有密码学身份，没有共享的吊销路径，也没有超出各个 DMV 自愿保留范围的审计追踪。 **mDL (ISO/IEC 18013-5)** 是在精神上最接近的已部署系统。它已经实现了选择性披露（“证明持有人超过 21 岁而不透露其地址”）并进行了密码学签名。mDL 目前没有做到的是后量子签名、正式的胁迫防御原语，或者一个管理签发机构自身随时间推移如何行事的章程层。 **Aadhaar** 拥有国家级规模的生物特征绑定；它的优势也是它的弱点。生物特征模板存在于一个集中的权威机构中，并且可以被该机构查询。Polaris 将生物特征绑定视为具有明确注册见证机构的每令牌属性，而不是一个人口规模的生物特征数据库。该系统可以回答“这个令牌是否绑定了指纹”，而无需将指纹保留在持有人设备之外。 **W3C DIDs 和 Verifiable Credentials** 是规范，而不是系统。它们支持 Polaris 使用的验证模型（密码学标识符、选择性披露、基于证明的联邦），但它们没有解决国家级签发、生物特征绑定或签发机构实际运行所需的基础操作底座问题。Polaris 填补了这一底座；原则上，它可以以 VCs 作为表示格式进行输出。 **e-Estonia** 是现有部署的系统中最具相似抱负的。其密码学是经典的（电子身份证上使用 ECDSA，旧基础设施中使用 RSA）；尚未指定向后量子迁移的平台级路径。该系统在协议层面上没有抗胁迫原语。 Polaris 的贡献不在于任何单一原语的新颖性。它在于**集成**：一个国家级的签发模型、一个后量子的操作默认值、验证上的零知识默认值、内置于验证流程中的胁迫代码原语，以及一个在数据库触发器级别强制执行的只追加审计记录；其中每一项都在模式级别进行了机器检查，而不是仅仅停留在书面声明上。 ## 快速入门 **本地环境 (macOS)。** 您需要 [Docker Desktop](https://www.docker.com/products/docker-desktop)。这是唯一的先决条件。 ``` git clone https://github.com/EgorKhaklin/polaris-id.git polaris cd polaris ./Polaris.command # or: ./polaris_mac_launch.sh up ``` 首次运行会拉取 Postgres 16，构建 Flask 镜像，加载模式，运行 SQL 自检，并在 `http://localhost:2222` 打开您的浏览器。随后的启动大约需要十秒钟。关闭浏览器标签页即可停止；启动器会监视页面并自动拆除技术栈。 使用三个预置角色之一登录（仅为示例数据）： ``` admin · Admin@123! full access + SQL console operator · Operator@123! issue / activate / bind tokens auditor · Auditor@123! read-only + warrant audits + duress dashboard ``` **生产环境 (Linux，任何 Docker 主机)。** ``` ./scripts/polaris-generate-secrets.sh export POLARIS_DOMAIN=polaris.example.com ./scripts/polaris-deploy.sh prod curl -fsS https://$POLARIS_DOMAIN/api/health ``` 大约九十秒内，Caddy 将配置 Let's Encrypt TLS，Postgres + pgbouncer + gunicorn 将以非 root 用户身份并删除 capabilities 启动，并且 `/api/health` 将返回结构化的各组件状态。操作员手册位于 [OPERATIONS.md](docs/operator/OPERATIONS.md)；机密入门位于 [SECRETS.md](docs/operator/SECRETS.md)；安装详细信息位于 [INSTALL.md](docs/operator/INSTALL.md)。 如果发现任何问题，启动器带有一个只读诊断功能：`./polaris_mac_launch.sh doctor`。 ## 您将获得什么 ``` ┌──────────────────────────────────────────────────┐ │ Polaris in numbers │ │ (current as of v9.142) │ ├──────────────────────────────────────────────────┤ │ 28 schema tables · 11 stored procedures │ │ 70 HTTP routes (incl. /auth/webauthn/*) │ │ 67 machine-checked invariants (C1-C10 + pins) │ │ 562 product tests · 10 property suites │ │ Plonky2 ZK + an independent second witness │ │ 7 CI jobs, incl. full prod-stack boot │ │ 1 double-click to launch │ └──────────────────────────────────────────────────┘ ``` 登录后，应用程序将停留在 **Dashboard（仪表盘）** 上，由此展开八个分析面板，涵盖模式统计、令牌状态、授权矩阵、后量子迁移率、按上下文划分的验证活动、披露姿态、继承血统和审计追踪。 **Atlas（地图集）** (`/atlas`) 是操作调查界面：一个带有每个验证和生命周期事件十字准线的实时地球仪，一个四位数抬头显示器（活跃令牌、异常、后量子百分比、零知识百分比），一个基于游标分页的事件流，以及可点击深入查看任何令牌完整记录（包括其前置链）的功能。 每个用例的路由：`/uc1/issue`、`/uc4/activate-reserve`、`/uc5/bind-device`、`/uc6/migrate-algorithm`、`/uc7/warrant-audit`、`/uc8/revoke-token`、`/uc9/queue`、`/duress`、`/anchors`、`/epochs`、`/federation` 和 `/sql`（仅限管理员/审计员）。 ## 核心技巧 大多数身份系统的参考实现将其规则放在应用程序代码中，下一个调用者可以绕过这些规则。Polaris 将它们放在 **数据库** 中，Postgres 会在那里强制执行它们，而无论连接的是哪个客户端： - **每人一个 ACTIVE 令牌** 是 `(individual_id) WHERE status = 'ACTIVE'` 上的部分唯一索引，而不是一个 `if` 语句。它能在每次从备份中恢复后依然存活。 - **审计记录** 是一个在任何生命周期事件表的 `UPDATE`/`DELETE` 操作上引发 `insufficient_privilege` 的触发器，而不是一种日志记录约定。 - **零知识** 是一个拒绝在 `ZERO_KNOWLEDGE` 验证上存储令牌 ID 的 CHECK 约束，而不是一项应用程序策略。 这些规则随后由 [`polaris_checks`](polaris_checks/) 进行机器检查：67 个普通的 `check_*(repo_root)` 函数，涵盖 C1-C10 约束以及生产环境姿态固定（CSP、机密权限、PQC 接线、CI 证明时效性、文档/模式偏差），每一项都具备 *经过测试的检测正确性*。每个检查在被破坏的固件上都能证明会失败；`python3 -m polaris_checks.run` 直接控制着 CI。检查就是检查：没有框架，没有神秘化。 ## 向导 从与您的目标相符的文件开始探索。 | | | | |---|---|---| | **[架构](docs/ARCHITECTURE-OVERVIEW.md)** | **[系统地图](docs/reference/SYSTEM-MAP.md)** | **[原则](docs/story/PRINCIPLES.md)** | | 四个层级及其连接方式：模式、应用程序、检查层和 ZK 证明器。阅读此文以了解各个部分是如何组合的。 | 一个单独的页面，命名了代码库中每个有意义的工件及其用途。当您不知道从哪里开始时，请使用此页面。 | 维系系统的核心原则，经过提炼。在更改任何承重组件之前，请先阅读此文。 | | **[模式](polaris_sql/01_schema.sql)** | **[章程](MISSION.md)** | **[代理操作手册](CLAUDE.md)** | | 28 个表。从 `IdentityToken` 开始并遵循外键。其中九个在触发器级别强制执行只追加不变量。 | C1 到 C10。系统必须永不违反复的十个硬性约束，每一项都在模式级别强制执行，而不是在应用程序代码中。 | 如果您是正在启动此项目的 AI 代理，这是您的起点。 | | **[地图集](polaris_web/static/atlas-globe.js)** | **[ZK 证明器](polaris_zk/src/lib.rs)** | **[CHANGELOG](CHANGELOG.md)** | | 操作级地球仪：D3 + 自定义正射投影、视口感知聚类、基于游标分页的信息流。 | 基于 Rust 的 Plonky2 Merkle 包含电路。由 `polaris_web/zk.py` 调用的子进程 CLI，并由第二见证者交叉检查。 | 完整的审计记录。精选的最新 10 个发布版本的索引位于 `CHANGELOG.md`；v9.24 之前的存档位于其旁边。 | 有关操作员和架构师文档的详尽索引，请参见 [`docs/README.md`](docs/README.md)。 ## 测试 四层验证。CI 在每次推送时都会通过七个任务运行所有这些测试。 ``` ┌──────────────────────────────┬─────────┬──────────────────────────────────────────────┐ │ Layer │ Count │ What it covers │ ├──────────────────────────────┼─────────┼──────────────────────────────────────────────┤ │ Product tests (DB-backed) │ 562 │ CHECK constraints, every use case, every │ │ test_app · test_cli · │ │ Flask route + form, the rate limiter, the │ │ test_check_constraints │ │ atlas API, R6 anti-revealing posture, ZK. │ │ Property tests (Hypothesis) │ 10 │ Adversarial inputs against C1, C2, C3 and │ │ │ │ the M2-12 redaction proof. │ │ polaris_checks │ 67 │ C1-C10 + production-posture pins; tested │ │ │ │ detection correctness; `run` gates CI. │ │ CI jobs │ 7 │ test · docker-image · caddy-edge (PQ KEX │ │ │ │ proof) · pqc-real · cve-scan · │ │ │ │ image-cve-scan · prod-stack-boot. │ └──────────────────────────────┴─────────┴──────────────────────────────────────────────┘ ``` ``` ./polaris_mac_launch.sh test # full suite, ~60 s ./scripts/ai-test.sh quick # skip the slow concurrency + property tests ./scripts/ai-done.sh # pre-ship gate (checks + link integrity) ``` 只有当每一层都通过并且 `ai-done` 报告 `READY` 时，发布版本才可交付。 ## 子命令参考 ``` ./polaris_mac_launch.sh # default; same as 'up' ./polaris_mac_launch.sh up # bring up, watch the browser, open it ./polaris_mac_launch.sh up --detach # bring up in background and return ./polaris_mac_launch.sh rebuild # force clean rebuild (no cache) ./polaris_mac_launch.sh stop # graceful shutdown ./polaris_mac_launch.sh status # what is running, where ./polaris_mac_launch.sh doctor # read-only diagnostic ./polaris_mac_launch.sh logs # tail Flask log (default) ./polaris_mac_launch.sh logs db # tail Postgres log ./polaris_mac_launch.sh test # run the test suite ./polaris_mac_launch.sh reset # drop pgdata, keep image ./polaris_mac_launch.sh nuke # total wipe: containers + image + volume ./polaris_mac_launch.sh --port 5050 # alternate host port ./polaris_mac_launch.sh --native # native path; Homebrew, no Docker ./polaris_mac_launch.sh --help # full help ``` ## 构建 ZK 证明器（可选） Plonky2 证明器的 Rust 源代码位于 `polaris_zk/` 中；但不包含编译好的二进制文件。Flask 应用程序在没有它的情况下也能优雅降级：每个页面正常提供服务，每个 UC-1..UC-12 流程正常工作，`/epochs` 会根据种子数据渲染历史纪元。该二进制文件仅用于 **证明或验证新的纪元闭合**（`/api/zk/epoch/close`、`/api/zk/verify`）。 ``` curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh rustup install nightly cd polaris_zk && cargo +nightly build --release ``` 构建后，`polaris_zk/target/release/polaris-zk` 将存在；Flask 应用程序会通过默认路径找到它。如果您在其他地方构建，请使用 `POLARIS_ZK_BINARY=/your/path/polaris-zk` 进行覆盖。 ## 许可证 Polaris 在 [Apache 许可证，版本 2.0](LICENSE) 下发布。 ``` Copyright 2026 Egor Khaklin Licensed under the Apache License, Version 2.0. ``` 该许可证包含明确的 **专利授权**（第 3 节）和 **归属保留**（第 4 节）。如果您基于 Polaris 进行构建（包括代码、模式或架构模式：审计记录准则、模式级约束网格、扁平的不变量检查层），请根据第 4 节保留 `LICENSE` 和 `NOTICE` 以及作者归属。Plonky2、D3、TopoJSON 和 Flask 的组件级归属声明位于 [NOTICE](NOTICE) 中。 学术项目报告（[docs/paper/polaris_project_report.pdf](docs/paper/polaris_project_report.pdf) 及其 TeX 源码）是同一版本的一部分，受同一许可证约束。 致谢 这是 **Seton Hill University** 2026 年春季的教育项目。仅为示例数据；并非真实的身份系统。所有密码学算法选择均反映了当前 NIST PQC 标准化（FIPS 204、FIPS 205）以确保学术准确性。 章程位于 [MISSION.md](MISSION.md)。发布历史位于 [CHANGELOG.md](CHANGELOG.md)。 如果在阅读完本文档后您只能再读一份文档，请阅读 [MISSION.md](MISSION.md)。

标签：MFA, Plonky2, PostgreSQL, Python, Rust, WebAuthn, X25519MLKEM768, ZK-SNARKs, 公钥基础设施, 去中心化身份, 参考实现, 可视化界面, 后量子TLS, 国家级数字身份, 多因素认证, 子域名枚举, 抗胁迫设计, 抗量子密码学, 无后门, 测试用例, 系统安全, 网络安全, 网络流量审计, 请求拦截, 身份与访问管理, 身份认证基础设施, 逆向工具, 隐私保护, 零知识证明