跳转至

公民 PKI 控制台 —— 面向 RP 的接口（仅 Go 侧扩展）

日期：2026-07-04。需求来源：template.gerege.mn/docs/EID_ENDPOINT_REQUESTS.md §B。 公民通过某个 RP 的控制台（例如 template.gerege.mn 的“我的系统”）查看自己的 PKI： 证书及其数量、限定于该 RP 的活动历史与计数、关联设备、控制台汇总数据。

隐私 —— 仅限特别授权的 RP

这些接口会返回公民的个人信息，因此并非对所有 RP 开放。调用方 RP 必须拥有 PKI_READ 权限 —— 由管理员逐个授予（管理控制台 → 依赖方（RP） → 编辑 RP → 勾选 “PKI_READ”）。未授权的 RP → 403。

  • first-party（运营方自有的 web/admin 演示）与 dev（""）—— 始终允许。
  • 活动范围限定于 RP：RP 只能看到自己创建的会话 （其他 RP 的登录 / 签名不会被暴露）。

身份认证：与 v3 一致，Authorization: Bearer <rp_sk_…>。

接口（全部需要 PKI_READ 权限）

GET /v3/certificates/etsi/{personEtsi}

公民的完整证书集合 + 各状态计数。 

{
  "personEtsi": "PNOMN-...",
  "counts": { "valid": 2, "revoked": 1, "expired": 0, "suspended": 1, "total": 4 },
  "certificates": [
    { "documentNumber":"…", "type":"AUTH|SIGN|SEAL", "serialNumber":"…",
      "certificateLevel":"ADVANCED|QUALIFIED|QSCD",
      "status":"VALID|REVOKED|EXPIRED|SUSPENDED",
      "notBefore":"RFC3339", "notAfter":"RFC3339", "issuerDn":"…" }
  ]
}
状态映射：certificates.status ACTIVE→（若 notAfter 已过则为 EXPIRED，否则为 VALID）、 SUPERSEDED→SUSPENDED、REVOKED→REVOKED。

GET /v3/devices/etsi/{personEtsi}

公民的关联设备（活跃 + 非活跃）。 

{
  "personEtsi":"PNOMN-...", "activeCount":1, "total":2,
  "devices":[ { "documentNumber":"…", "platform":"APNS|FCM",
                "enrolledAt":"RFC3339", "active":true, "deactivatedAt":null } ]
}

GET /v3/rp/activity/etsi/{personEtsi} —— 限定于 RP

仅返回由调用方 RP 创建的会话历史与计数。 查询参数：?flow=AUTHENTICATION|SIGNATURE&limit=20&offset=0 

{
  "personEtsi":"PNOMN-...",
  "counts": { "authentication": 42, "signature": 7 },
  "sessions": [ { "sessionId":"…", "flow":"AUTHENTICATION", "outcome":"OK",
                  "docText":"…", "timestamp":"RFC3339" } ],
  "total": 49, "limit": 20, "offset": 0
}
数据来源：audit_events（SESSION_AUTH/SESSION_SIGN，重启后仍持久保留）。 RP 范围限定通过审计明细中的 crp（创建方 RP 的 UUID）过滤实现。

GET /v3/person/summary/etsi/{personEtsi} —— 控制台汇总

一次调用返回控制台所需的汇总数据。 

{
  "personEtsi":"PNOMN-...", "givenName":"…", "surname":"…",
  "certificates": { "valid":2, "revoked":1, "expired":0, "suspended":1, "total":4 },
  "activity": { "authentication":42, "signature":7 },
  "devicesActive":1, "devicesTotal":2,
  "representationCount":1
}

Well-known

GET /.well-known/eid → endpoints.person.{certificates,devices,activity,summary}（标记为 PKI_READ）。

实现

  • 服务：service.PersonPKIService（server/internal/service/memory/person.go）。
  • 处理器：server/internal/httpapi/handlers_person.go（rpAuth + requirePKIRead 校验）。
  • 权限：RP.Permissions CSV 字段中的 PKI_READ（管理控制台 RP 表单中的复选框）。
  • 公民不存在 → 404；RP 未授权 → 403；缺少 Bearer → 401（RequireRPAuth）。