AuthiChain

AuthiChain Unified

AuthiChain 物理世界信任层的规范实现。

AuthiChain 将实体产品或资产转化为可验证的数字身份：符合标准的标识符解析为已签名声明，系统评估策略和溯源数据，并由独立验证方返回可审计的结果。

本仓库是以下项目的规范构建/部署入口：

• AuthiChain — 验证、证明、产品身份、API 和计费
• QRON — 美观、可编程的验证体验和 QR 工作室
• GovChain — 政府/承包商信任工作流和印章
• StrainChain — 受监管实体商品的溯源和产品验证
• AgentZ / MCP — Agent 式编排，以及面向机器的同一信任原语访问接口

核心主张： 一种验证协议，多种商业形态。各垂直产品不应分叉信任模型。

架构概览

                    PHYSICAL WORLD
                          │
                 product / asset / unit
                          │
                          ▼
                 GS1 Digital Link
              GTIN + serial / lot / qualifiers
                          │
                          ▼
                  ┌───────────────┐
                  │   RESOLUTION  │
                  │ identifier →  │
                  │ representation│
                  └───────┬───────┘
                          │
                          ▼
              ┌──────────────────────┐
              │ AUTHICHAIN VERIFY    │
              │ signed claims        │
              │ issuer / JWKS         │
              │ status / revocation   │
              │ provenance / policy   │
              │ scan-risk signals     │
              └──────────┬──────────┘
                         │
              ┌──────────┼──────────┐
              ▼          ▼          ▼
           Humans      Agents     Enterprise
           /verify     MCP/API    integrations
              │          │          │
              └──────────┼──────────┘
                         ▼
              QRON · GovChain · StrainChain
                         │
                         ▼
                billing / onboarding /
                audit / operational data

信任边界

解析不等于验证。 解析器回答的是正在寻址什么标识符/资源。AuthiChain 验证评估的是已签名声明是否有效、当前有效、可归因，并且与验证方可获取的证据一致。

因此，肯定状态的适用范围取决于所评估的证据和策略。例如，已注册的产品标识符本身不能证明制造质量，而缺少标识符本身也不能证明存在仿冒。

仓库结构

层级	位置	职责
Web / 客户端界面	client/、workers/	公共域名上的 QRON 和垂直领域用户体验
验证协议	protocol/	开源协议/参考实现
Agent 式运营	agentz/	工作流编排、试点项目、运营自动化
机器接口	mcp/	通过 MCP 访问 AuthiChain 功能
边缘/API	workers/*	Cloudflare Workers、路由、验证和集成
持久化	Supabase/Postgres + D1	运营状态、证明、事件和应用数据
架构文档	docs/ESTATE.md、docs/NETWORK.md	系统清单和部署拓扑

公共界面

• authichain.com — 协议、验证、证书、API 和计费
• qron.space — QRON 创建和可编程体验
• govchain.us — 政府/承包商信任工作流
• strainchain.io — 溯源和产品验证工作流

这些域名是在同一底层信任架构之上的商业和展示界面。规范的客户路径为 /onboard、/dapp 和 /verify。

标准与验证流程

1. 标识 — 用稳定标识符表示实体单元；适用时，使用 GS1 Digital Link 语法，例如 /01/{gtin}/21/{serial}。
2. 解析 — 将标识符解析为相应的表示形式或链接集。
3. 证明 — 由发行方对已标识对象的声明进行签名。
4. 验证 — 验证方检查签名、发行方密钥、状态/撤销信息及适用策略。
5. 解读 — 系统报告有证据支持的状态和任何风险信号，同时不将注册与实物检验混为一谈。
6. 采取行动 — 人员、Agent 或企业系统通过 Web、API 或 MCP 接口使用结果。

部署模型

Cloudflare 优先。 生产边缘运行于 Cloudflare Workers 和仓库的 Worker 部署配置中。仓库中可以保留用于兼容或迁移的旧框架代码，但它并非架构的核心。

• 边缘／运行时：Cloudflare Workers + Wrangler
• Web：Vite + React
• 数据：Supabase/Postgres 和 Cloudflare D1
• ORM：Drizzle
• 包管理器：pnpm
• Agent 运行时：Python / AgentZ
• 协议／API 组件：TypeScript、Hono 和标准加密库

部署拓扑请参阅 docs/NETWORK.md，系统清单请参阅 docs/ESTATE.md。

开始使用

cp .env.example .env
pnpm install
pnpm dev

GitHub Codespaces

精简版 Codespaces 配置位于 .devcontainer/。默认范围为 core（冻结的 pnpm 安装、不含浏览器二进制文件、不含 husky）。精简方法和扩展规则请参阅 .devcontainer/CONDENSING.md。

对于依赖数据库的脚本，切勿将凭据写入源代码。在本地环境或部署密钥存储中设置 DATABASE_URL。

示例：

export DATABASE_URL='postgresql://USER:PASSWORD@HOST:5432/DATABASE?sslmode=require'

AgentZ

python -m agentz.cli list
python -m agentz.cli run authichain_pilot_deploy --mode dry-run

试点就绪情况

标准就绪流程如下：

install → typecheck → lint → tests → production build → deploy smoke test → real product scan

请参阅：

• docs/operations/PILOT-READY-BASELINE.md
• docs/attestation/v0.1.md
• docs/ESTATE.md
• docs/NETWORK.md

安全

部署不变量

推送到 main（包括仅修改文档的提交）时，都会运行 deploy-cloudflare.yml 和 deploy-edge-worker.yml。不要添加 paths 或 paths-ignore。

密钥扫描（gitleaks 8.28.0，--no-git）会首先运行，且必须以失败关闭方式执行。部署权限保持为 contents: read。Git 中不得包含令牌值。

Wrangler 部署成功表示该提交的构建包已发布。这并非 SOC 2、FedRAMP、FDA、政府或大麻 COA 证书。验证器通过表示本次检出代码运行的检查已通过。

authichain-consensus-engine 存在身份冲突。在执行任何退役操作前，请先在 Cloudflare 中确认。本文件不会将其退役。

安全是协议呈现的一部分，而非事后补充。

• Git 中不得包含凭据。 运行时密钥应存放在环境或部署密钥存储中。
• 示例中不得包含有效密钥。 使用 sk_live_…、whsec_… 或 postgresql://USER:PASSWORD@HOST/DB 等占位符。
• 立即轮换已泄露的凭据。 从当前代码树中移除密钥，并不会使可能已存在于 Git 历史记录、缓存或日志中的凭据失效。
• 发布前进行验证。 合并前运行密钥扫描，并保持现有安全检查启用。
• 最小权限。 优先使用范围严格受限的凭据和服务绑定，而非权限宽泛的账户令牌。

如果凭据曾被提交过，在提供商确认已轮换或撤销之前，应将其视为已泄露。

项目原则

AuthiChain 本质上并非区块链 UI。其持久的产品是验证层：标准化身份 → 解析 → 签名证明 → 独立验证 → 基于证据的决策。

区块链锚定、NFT、QR 艺术、AI Agent 和垂直应用可以扩展这一层，但不应重新定义其信任边界。

许可证

请参阅 docs/project/LICENSE.md。