组织（法人）—— 接入指南¶

日期：2026-07-04。范围：在 eID 平台上注册组织、管理代表权、使用 e-Seal（组织印章）以及 RP（电子服务）侧集成。设计说明：docs/ORG_AUTH_SIGN_PLAN.md；标准依据： SK ID Solutions SK-CPR-ORG v13.0、ETSI EN 319 412-1/-3/-5。

核心原则（爱沙尼亚模式）： 组织没有应用账户、手机、PIN 码或门限密钥。组织的所有操作均通过以下三种机制完成： 1. 以组织身份登录 = 自然人使用本人 eID 登录，RP 实时对照代表权登记册核验其权限（权限不在证书中 —— 而在登记册中）。 2. 代表组织签名 = 代表人的个人 PIN2 证书 + 会话上的 onBehalfOf 标记（服务端已校验过其权限）。 3. e-Seal（印章） = 基于服务端 HSM 密钥的自动印章，使用 NTRMN- 证书 —— 非交互式（发票、对账单等可由系统直接盖章）。

1. 标识符¶

项目	取值
ETSI 标识符	`NTRMN-<国家登记号>`（ETSI EN 319 412-1 §5.1.4，NTR 语义）
证书 subject	`SERIALNUMBER=<登记号>, CN/O=<名称>, organizationIdentifier(2.5.4.97)=NTRMN-<号码>, C=MN`
签发 CA	Gerege Organization Issuing CA（L2）—— 由 `SubjectTypeForEtsi` 自动选择

2. 注册组织（运营方 / 管理员）¶

在管理控制台的组织标签页，或通过 API：

POST /v3/admin/organizations            (org:write)
  {"orgRegister":"1234567","name":"Тест ХХК","nameLatin":"TEST LLC","activate":false}

activate:false → 以 PENDING 状态创建；核验完成后由管理员按状态机推进。
状态机：PENDING → VERIFIED → ACTIVE → SUSPENDED/REVOKED（可从 SUSPENDED 恢复； REVOKED 为终态 —— 有效的印章证书会被自动吊销并写入 OCSP/CRL）。

PATCH /v3/admin/organizations/{etsi}    {"status":"ACTIVE"}

3. 代表权（representation）¶

每位授权代表都必须拥有本人的 eID（已完成注册）：

POST /v3/admin/organizations/{etsi}/representatives   (org:write)
  {"personEtsi":"PNOMN-…","role":"Гүйцэтгэх захирал","rightType":"ADMIN",
   "source":"MANUAL","evidenceRef":"тушаал №…","validTo":null}
DELETE /v3/admin/organizations/{etsi}/representatives/{id}

rightType：ADMIN（创建 / 关联了该组织 —— 可在其下添加或移除 MANAGER 签署人）| MANAGER（签署人 —— 不能在其下添加或移除任何人）。
source：REGISTRY（来自 УБЕГ/DAN —— 未来实现自动同步）| MANUAL（凭文件确认）。
若有效期（validTo）已过、权限已停用，或组织不处于 ACTIVE 状态，该权限不会出现在查询结果中。

4. RP 侧集成¶

4.1 以组织身份登录¶

先按常规的个人认证方式完成用户登录（/v3/authentication/...）。

然后：

GET /v3/organization/representations/etsi/{personEtsi}     (RP auth)
→ {"personEtsi":"PNOMN-…","representations":[
     {"orgEtsi":"NTRMN-…","orgName":"…","rightType":"ADMIN","role":"…", …}]}

在界面上让用户选择“以哪个组织的身份继续”，并在所选组织的上下文中创建会话。权限可能逐日变化 —— 每次会话都应重新核验。

4.2 代表组织签名¶

在签名请求中加入 onBehalfOf：

POST /v3/signature/notification/etsi/{personEtsi}
  { …, "onBehalfOf":"NTRMN-1234567" }

- 服务端在创建会话时校验代表权：无权限 → 403；对未识别（匿名）用户 → 403。 - 手机确认界面会显示“您正在代表 X 进行签名”。 - 会话状态（GET /v3/session/{id}）中会增加 onBehalfOf: {orgEtsi, orgName} 区块；签名本身仍使用个人的 PIN2 证书（密码学层面无变化）。 - ADMIN 与 MANAGER 均可独立代表组织签名（密码学层面不强制会签）；如需收集多方签名，则属于 RP 自身的业务规则（与爱沙尼亚一致）。

4.3 e-Seal（组织印章）¶

RP 必须已被授予 SEAL 权限（在管理端注册 RP 时的 permissions 中，如 AUTH,SIGN,SEAL）； first-party（自有网站）不受限制。

POST /v3/seal/certificate/{orgEtsi}    — 签发印章密钥与证书（或通过管理端：
                                          POST /v3/admin/organizations/{etsi}/seal-certificate）
GET  /v3/seal/certificate/{orgEtsi}    — 当前有效证书（用于验证）
POST /v3/seal/{orgEtsi}                — 盖章：
  {"digest":"<base64 SHA-256/384/512>"} → {"signature":{"value","signatureAlgorithm"},
                                            "cert":{"value","certificateLevel"},"sealedAt"}

非交互、同步返回 —— 无需 PIN 或推送（SK 的 e-Seal 模型）。
若组织不处于 ACTIVE 状态，或证书已吊销 / 被取代 → 409（fail-closed）。
证书配置（SK-CPR-ORG）：KeyUsage 仅为 nonRepudiation；无 EKU； QCStatements = QcCompliance + QcType=eseal；策略为 QCP-l。当 SMARTID_SEAL_QSCD=true （真实 QSCD/HSM）时追加 QcSSCD，策略为 QCP-l-qscd，级别为 QSCD。

4.4 由 RP 侧管理签署人（自助）¶

拥有 ADMIN 权限的代表可以直接在 RP 的界面中为本组织添加 / 移除 MANAGER 签署人（无需使用管理控制台）。所有接口都需要 RP auth 与 ORG_LINK_WRITE 权限； {actingPersonEtsi} 必须是该组织的 ADMIN 代表（否则返回 403）。 {orgRegister} = 组织的国家登记号。

GET    /v3/organization/signers/{orgRegister}/etsi/{actingPersonEtsi}
       → 当前签署人（verified/pending 状态）
POST   /v3/organization/signers/{orgRegister}/etsi/{actingPersonEtsi}
       {"signerRegNo":"<待添加公民的 РД>","role":"Нягтлан бодогч"}
       — 添加的权限**始终**为 MANAGER（`rightType` 会被忽略）；系统会向该公民发送
         sign-push 请求确认。
DELETE /v3/organization/signers/{orgRegister}/etsi/{actingPersonEtsi}?signer=<РД>
POST   /v3/organization/signers/{orgRegister}/etsi/{actingPersonEtsi}/resend?signer=<РД>
       — 向尚未确认的签署人重新发送 sign-push。

组织的拉丁文名称（ICAO/latin，即写入证书的名称）只能由 ADMIN 修改：

PUT /v3/organization/name-latin/{orgRegister}/etsi/{actingPersonEtsi}
    {"nameLatin":"TEST LLC"}

РД（signerRegNo）即登记号，不区分大小写（按小写查找）； nameLatin 遵循 ICAO 规范，因此以大写存储（标识符）。

4.5 吊销状态检查¶

OCSP：POST /ocsp —— 单一接口；响应方会根据请求中的 issuer 哈希自行选择 Personal / Organization CA。
CRL：GET /crl（Personal CA）、GET /crl/org（Organization CA）。
服务发现：GET /.well-known/eid —— 其中列出了组织与印章相关接口。

5. 配置（服务端）¶

环境变量	说明
`SMARTID_HSMPROXY_ORG_KEY_LABEL`	Organization issuing CA 的 HSM 密钥标签（为空时回退到 Personal CA）
`SMARTID_HSMPROXY_ORG_ISSUING_CERT`	Organization issuing CA 证书（PEM 路径）
`SMARTID_SEAL_QSCD`	`true` = e-Seal 叶子密钥存放于 HSM（QSCD；QcSSCD+QCP-l-qscd）。需要 hsmproxy CA provider 与凭据（否则 fail-fast）。`false` = 软件印章密钥（QUALIFIED）。密钥仪式见：`docs/PKI_CA_ONBOARDING.md`
`SMARTID_SEAL_KEY_PREFIX`	HSM 印章密钥标签前缀（默认 `eseal-`；标签 = 前缀 + 登记号）

6. 审计¶

所有操作都会写入 audit_events：ORG_REGISTER、ORG_STATUS、ORG_REP_ADD/REMOVE、 ORG_REP_LOOKUP（哪个 RP 查询了谁的权限）、ORG_ONBEHALF（OK/DENIED）、 SEAL_CERT_ISSUE、ORG_SEAL（OK/DENIED）。

7. 限制 / 后续工作¶

УБЕГ/DAN 的法人登记 API 尚未接入 —— 代表权目前来源于 MANUAL（凭文件录入）；待 API 开放后将增加 REGISTRY 同步（阶段 0/1）。
若 staging 环境未配置组织 CA，印章证书将由 Personal CA 签发（caFor 回退）—— 生产环境必须使用 Organization CA（见 deploy/README.md 的切换清单）。
e-Seal 的法律地位（蒙古国法律中对应 eIDAS “电子印章”的概念）需与法律顾问进一步确认（ORG_AUTH_SIGN_PLAN §4）。