验证方 API

由本站同源提供。公布的策略文档是权威来源，集成前请先阅读。

base URL: https://gyid.geoyuan.com

GET /.well-known/verifier.json

验证方公钥与策略门槛

{
  "verifier": "trip-server",
  "verifier_pubkey": "<64 hex>",
  "protocol": "draft-ayerbe-trip-protocol-04",
  "validity_secs": 3600,
  "challenge_ttl_secs": 60,
  "policy": { "alpha_bio_range": [0.3, 0.8], "min_confidence": 0.1, "min_trust": 20.0 }
}

POST /v1/evidence

提交一批已签名面包屑（CBOR 帧流，body 为二进制）

{ "stored": 116, "unique_cells": 116, "chain_head": "<64 hex>" }

// 400 —— 违反链规则时
{ "error": "invalid breadcrumb chain: duplicate h3 cell ... at consecutive index 1" }

GET /v1/identity/:pubkey_hex

某 attester 的链状态；尚无证据时返回 404

{
  "attester": "<64 hex>",
  "breadcrumb_count": 116,
  "unique_cells": 116,
  "chain_head": "<64 hex>",
  "last_ts": 1790397900
}

POST /v1/verify

创建绑定 RP nonce 的挑战（主动验证第一步）

// 请求
{ "attester": "<64 hex>", "rp_nonce": "<32 hex>", "ttl_secs": 90 }

// 响应
{ "challenge_id": "<32 hex>", "expires_at": 1790397960, "delivered": true }

WS /v1/challenge?attester=<pubkey_hex>

实时通道：服务端下发 LivenessChallenge（二进制 CBOR 帧），Attester 回送 LivenessResponse

// 客户端连接后先发注册帧
{ "type": "hello", "attester": "<64 hex>" }

// 之后为二进制帧：challenge 下行 / response 上行
// 服务端回执（文本帧）示例：
{ "type": "poh_issued", "ok": true, "alpha": 0.441, "beta": 3.0,
  "confidence": 0.0597, "trust": 63.27, "meets_policy": false }

GET /v1/poh/:challenge_id

取回已签发的 PoH 证书（CBOR 二进制）；未就绪时 202

// 202 —— 尚未签发
{ "status": "pending", "expires_at": 1790397960 }

// 200 —— CBOR 证书（15 字段，见协议页）

GET /v1/explorer

本验证方已知全部 attester 的聚合视图（不含任何位置数据）

{ "attesters": [ { "pubkey": "<64 hex>", "breadcrumb_count": 116, "unique_cells": 116, "last_ts": 1790397900 } ] }

错误码

码	含义	处理
400	链规则违规（同 cell、间隔不足、index 不连续、prev hash 不匹配）	修正轨迹或丢弃违规面包屑后重试
404	/v1/verify 找不到该 attester：该身份尚未上传任何证据	先在 Collect/Import 页上传面包屑
404	/v1/identity/:hex：该身份在验证方处无记录	同上
202	/v1/poh/:id 尚未签发（Attester 还没应答挑战）	轮询直到 200 或超时
429	请求限流	退避后重试

同源与实时通道

本站的验证方与页面同源（https://gyid.geoyuan.com），因此前端无需配置后端地址，也不存在 CORS 或混合内容问题。WebSocket 走 wss://gyid.geoyuan.com/v1/challenge，由 nginx 升级连接并反代到本机 trip-server。

隐私边界

上述任何端点都不接受也不返回原始坐标。客户端送出的是已量化的 H3 网格与签名；服务端返回的是统计量与聚合计数。这不是策略约定，而是数据结构本身没有承载坐标的字段。