服务商接口（provider）开发指南

1. 新建插件，类型选 provider。
2. 生成一对 Ed25519 响应签名密钥，公钥（base64url，无填充，43 字符）写进 provider_response_key；私钥只留在你的服务里。
3. 在 base_url 下实现 /cdnca-provider/v1/{kind}/{action}，先实现 verify，再实现本类型的动作。
4. 沙箱模式（请求体 sandbox=true）只用测试数据回答，不碰客户账户。
5. 签名 manifest，上传版本（带至少一个平台包）。客户安装后，主控先对你的沙箱跑一遍安装契约，全部通过管理员才能启用。

当前开放：dns、sms、mail、icp、payment。通知渠道（notify）即将开放：manifest 里可以声明、市场审核也接受，但主控目前不会启用 notify，声明后该协议会被忽略；第三方 CDN（cdn）只限官方。

签名与公钥登记见插件签名工具页。 签名工具与步骤 →

每次调用都是 POST {base_url}/cdnca-provider/v1/{kind}/{action}，请求体 JSON 带 "protocol": "cdnca.provider/v1" 和 "sandbox"，写操作带 idempotency_key（同一个 key 重复调用必须返回第一次的结果、不能重复执行）。请求体最大 256 KiB，应答最大 1 MiB，超时 15 秒。主控只连公网地址、不走代理、不跟随重定向。

request  = "cdnca-provider-request/v1\n" + installation_id + "\n" + plugin_id + "\n" + kind + "\n" + action + "\n" + timestamp + "\n" + nonce + "\n" + hex(sha256(body))
response = "cdnca-provider-response/v1\n" + plugin_id + "\n" + kind + "\n" + action + "\n" + nonce + "\n" + hex(sha256(response_body))复制

签名、时间戳或 nonce 不对时返回 HTTP 401。其余情况一律 HTTP 200 + 信封 {"protocol":"cdnca.provider/v1","ok":true,"data":{…}}，失败时 {"ok":false,"error":{"code":"…"}}；code 取 invalid_request、unauthorized、not_found、conflict、zone_not_found、rate_limited、quota_exceeded、unavailable、unsupported、provider_error、invalid_signature，其他值按 provider_error 处理。信封不允许多余字段。应答签名绑定了请求 nonce，抓到的应答不能用于别的调用。安装公钥由客户主控管理员在插件详情“安装签名公钥”处复制给你。

上传后审核 worker 先跑“校验”阶段（manifest、入口、权限、本类型专属检查），出现任何拒绝项就不再扫描；再跑“扫描”阶段。结论：有拒绝项 → 需修改（修好后点“重新提交”，每个版本最多 10 次扫描）；有隔离项 → 待人工审核；都没有 → 视下列条件直接通过或进入人工审核。

• 首个版本（该插件还没有任何已审核版本）
• 权限与上一个已审核版本不同（增加或减少）
• 高风险类型：module、engine_module、provider
• 入驻未满 90 天的卖家（市场默认值，运营可调）
• 扫描连续 3 次出错
• provider 是高风险类型，每个版本都人工审核

满足任一条即进入人工审核。完整规则表（规则 ID、级别、拒绝或隔离、是否试运行）见审核规则页。

• entrypoint.provides_invalid：provides 格式错、重复或协议版本不对（拒绝）；entrypoint.provides_official_only：声明了 cdn（拒绝）。
• package.*：压缩包损坏、zip 炸弹、路径穿越、符号链接、超出条目数（10000）或解压大小（单文件 32 MiB、合计 128 MiB）上限等（拒绝；setuid 位为隔离）。
• secrets.*：包里有私钥、云厂商或代码托管平台的令牌（拒绝）；JWT 与通用凭据赋值目前是试运行。
• malware.detected、dependencies.malicious：病毒或已知恶意依赖（拒绝）。

审核接受 notify，但主控暂不启用（见快速开始的说明）。

本类型相关的规则见审核规则清单： metadata.* entrypoint.* permissions.* package.* secrets.* dependencies.* malware.* diff.*

仓库里的 libs/entitlement/pluginprovider/fake.go（FakePlugin）就是协议服务端的参考实现：验签、时间窗、nonce、幂等、签名应答和沙箱行为都在里面。上面的协议节示例由它改写：

func (p *Plugin) ServeHTTP(w http.ResponseWriter, r *http.Request) {
	// {base_url}/cdnca-provider/v1/{kind}/{action}
	i := strings.Index(r.URL.Path, "/cdnca-provider/v1/")
	kind, action, _ := strings.Cut(r.URL.Path[i+len("/cdnca-provider/v1/"):], "/")
	nonce := r.Header.Get("X-Cdnca-Provider-Nonce")
	body, _ := io.ReadAll(io.LimitReader(r.Body, 256<<10))
	ts := r.Header.Get("X-Cdnca-Provider-Timestamp")
	unix, err := strconv.ParseInt(ts, 10, 64)
	sig, _ := base64.RawURLEncoding.DecodeString(r.Header.Get("X-Cdnca-Provider-Signature"))
	skew := time.Now().Unix() - unix
	msg := "cdnca-provider-request/v1\n" + r.Header.Get("X-Cdnca-Provider-Installation") + "\n" + p.PluginID +
		"\n" + kind + "\n" + action + "\n" + ts + "\n" + nonce + "\n" + sha256hex(body)
	if i < 0 || err != nil || len(nonce) != 32 || skew > 300 || skew < -300 || p.seen(nonce) ||
		!ed25519.Verify(p.InstallationKey, []byte(msg), sig) {
		p.reply(w, kind, action, nonce, 401, "unauthorized", nil)
		return
	}
	// … 按 kind/action 处理，写操作按 idempotency_key 去重 …
	p.reply(w, kind, action, nonce, 200, "", map[string]any{})
}

func (p *Plugin) reply(w http.ResponseWriter, kind, action, nonce string, status int, code string, data any) {
	env := map[string]any{"protocol": "cdnca.provider/v1", "ok": code == ""}
	if code != "" {
		env["error"] = map[string]string{"code": code}
	}
	if data != nil {
		env["data"] = data
	}
	body, _ := json.Marshal(env)
	msg := "cdnca-provider-response/v1\n" + p.PluginID + "\n" + kind + "\n" + action + "\n" + nonce + "\n" + sha256hex(body)
	w.Header().Set("Content-Type", "application/json")
	w.Header().Set("X-Cdnca-Provider-Response-Signature",
		base64.RawURLEncoding.EncodeToString(ed25519.Sign(p.ResponseKey, []byte(msg))))
	w.WriteHeader(status)
	w.Write(body)
}复制

主控安装时跑的契约用例（RunContract，contract.go）：所有 kind 都有 verify、rejects_bad_signature、rejects_tampered_body、rejects_stale_timestamp、rejects_replayed_nonce；dns 另有 create_a、list_created、create_idempotent、update_a、delete_a、delete_missing_not_found、txt_line、unknown_zone；sms 有 send、send_idempotent、invalid_number；mail 有 health、send、send_idempotent、invalid_recipient；icp 有 filed、unfiled、invalid_domain；payment 有 create_checkout、query_unpaid、sandbox_settle、query_paid、verify_callback、rejects_tampered_callback、refund_idempotent、refund_over_limit、reconcile、unknown_order。本地可以仿照 pluginprovider_test.go 的 newHarness，把 pluginprovider.NewClient 指向你的服务后调用 pluginprovider.RunContract，看到的结果与客户主控一致。