For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/backend-development/login.md.

登录接入(服务端)

提示

本文面向负责后端、MCP Server 和账号系统的开发者,说明如何将自有账号体系接入豆包应用插件。接入完成后,平台能够在用户授权后代表用户调用 MCP 工具,业务服务端也可以通过平台提供的 OpenAPI 获取用户标识或已加密的用户信息。

接入目标

登录接入同时解决两类问题:

  1. MCP 用户授权:当豆包应用插件调用一个需要登录的 MCP 工具时,平台发起用户授权。业务服务端完成账号登录,签发一次性授权 Code,平台再通过 OAuth2.0 Token 接口换取用户级 access_token 和 refresh_token。后续 MCP 请求会透传用户 OpenID 和业务方签发的访问凭证。

  2. Server2Server 服务端调用: 在登录流程中,需要业务服务端调用平台 OpenAPI 换取用户身份信息:

    1. 用 app_id 和 app_secret 获取应用级 access_token;
    2. 使用应用端上送的一次性 login_code 换取 OpenID;
    3. 使用应用端上送的一次性 phone_code 换取已加密的手机号。

名词解释

对象谁签发谁消费用途关键特性
open_id平台业务服务端标识用户在当前应用下的唯一身份需与业务账号建立稳定绑定;不同应用下的值不同
授权 Code业务服务端平台OAuth2.0 授权完成后换取用户 Token短时、一次性、不可重放
用户 access_token业务服务端平台与 MCP Server表示某个用户已授予的调用权限与用户、应用和 Scope 绑定;必须设置过期时间
refresh_token业务服务端平台在无需用户重新交互的情况下刷新用户 Token有效期应长于用户 Token;建议旋转且可撤销
应用级 access_token平台业务服务端鉴别服务端应用身份,调用部分 OpenAPI有效期为 2 小时。刷新后,旧 Token 仅有 5 分钟有效期,因此建议将应用级 access_token 收口至一处统一管理。
login_code平台业务服务端换取 open_id短时、一次性,收到后立即交换
phone_code平台业务服务端换取加密过的手机号短时、一次性;调用时还需应用级 Token

前置准备工作

顺序阶段开发者要完成的动作关键产出
1平台与资料准备完成开发者入驻、豆包应用插件基础信息、服务协议、隐私协议、登录文案、OAuth 回调地址、通用信息删除回调地址配置。可进入审核;登录相关配置项齐备。
2证书与版本配置按照 关于证书 完成开发者证书配置dev_priv、dev_cert、证书序列号、版本配置、MCP 工具列表。
3服务端接口开发实现 FetchTokenURL、RefreshTokenURL、DeleteUserInfoURL;服务端按需调用豆包 OpenAPI 获取 OpenID、手机号、应用级 AccessToken。三方 Token 体系、OpenID 绑定关系、隐私删除处理能力。
4端侧登录页开发在 src/auth 下实现登录、隐私协议、自定义登录页,并在登录完成后调用 MCP 登录结果回传。login.ts、privacy.ts、mcp-login-page/index.tsx。
5联调与验收覆盖对话内链路、豆包应用插件内回访链路、拒绝登录、拒绝隐私、Token 过期刷新、数据删除、多端登录等场景。可上线的三方登录闭环。
  1. 在开发者平台完成开发者入驻和豆包应用插件基础信息录入,包括图标、名称、简介等。
  2. 准备并确认业务侧 服务协议、隐私协议、登录文案和隐私文案,协议需要是业务自己提供的 H5 链接。
  3. 准备三方 OAuth Endpoint,用于后续标准 OAuth2.0 能力接入。
  4. 准备宿主通用信息删除回调地址,作为 DeleteUserInfoURL 配置到开发平台。
  5. 声明 MCP 工具的登录与鉴权配置:哪些工具需要登录、需要哪些 Scope、是否需要向用户展示索权文案。
提示

注意:平台基础设置和开发配置需要提交审核;版本管理中的 MCP Server 地址、Scope、工具登录配置和三类 URL 配置建议在同一轮联调前全部确认,避免链路中途缺配置。

平台配置

  • 填写【基础设置】栏后,点击【提交审核】按钮,由豆包侧相关同学完成审核。

  • 【开发配置】栏 上传应用证书,完成证书配置步骤完成应用证书配置。证书生成与上传、平台证书获取、私钥保管、证书序列号、签名验签及加密解密统一参见 关于证书,本页不重复展开

  • 【版本管理】栏 完成版本创建

    • 创建并上传卡片资源(参考 IDE 使用说明)

    • 配置 MCP Server 地址,自动解析对应工具列表

    • 勾选当前豆包应用插件所需的全部 scope 权限信息。【可选】可为具体 scope 信息配置使用文案

    • 完成工具是否需要登录和索权的配置

    • 完成登录关键配置: FetchTokenURL / RefreshTokenURL / DeleteUserInfoURL

      • FetchTokenURL

      图片展示的是登录配置中的FetchTokenURL相关内容。上方有“登录配置”标题及一个信息图标,下方文字说明“用于获取登录态的URL”。该图片与文档中“完成登录关键配置:FetchTokenURL/RefreshTokenURL/DeleteUserInfoURL”部分内容相关,具体解释了FetchTokenURL的作用,即登录过程中通过三方颁发的code请求该地址,换取表明登录身份的access_token,是登录接入服务端需完成的登录关键配置之一。

      登录过程中通过三方颁发的 code 请求该地址,换取表明登录身份的 access_token「三方颁发」

      • RefreshTokenURL

      这张图片内容为用于刷新登录态的URL相关说明,对应服务端登录接入配置中的RefreshTokenURL配置环节,该配置的作用是在登录过程中,通过三方颁发的access_token请求该地址,以此换取续期有效的access_token和refresh_token,属于登录关键配置的组成部分,需完成该URL的配置以满足登录流程的续期需求。

      登录过程中通过三方颁发的 access_token 请求该地址,换取续期有效的 access_token 和 refresh_token「三方颁发」

      • DeleteUserInfoURL

      图片展示的是用于删除登录过程中获取到的用户信息URL。该图片位于文档中“DeleteUserInfoURL”部分,是对该URL用途的说明。上下文提到DeleteUserInfoURL是宿主通用信息删除回调地址,用于满足隐私数据删除和平台策略要求(仅通知删除,非解除登录态),而图片则直观地呈现了URL的具体内容,帮助理解其在登录接入服务端配置中的作用。

      宿主通用信息删除回调地址,用于满足隐私数据删除和平台策略要求(仅通知删除,非解除登录态)

      这张图片展示的是与隐私数据删除相关的内容,核心为手机号188******58的标识信息,右侧有红色的“删除”操作按钮。图片下方标注提示,将在24小时内通知开发者删除该手机号对应的相关信息。结合上下文,该内容对应文档中提及的DeleteUserInfoURL相关功能,该地址用于接收宿主的通用信息删除回调,满足隐私数据删除和平台策略要求,且仅为通知删除,不解除登录态。

OAuth 能力、通用信息删除能力的开发

标准 OAuth2.0 能力

能力 参考
授权 Code 发放RFC6749 https://datatracker.ietf.org/doc/html/rfc6749
token 兑换/刷新
获取 Token 接口
接口 token 获取接口
调用形式 服务端调用
需要加签验签 否
流程说明
  • 使用三方短期授权 Code 获取 access_token
参数说明 {
"app_id": "xxx", // 应用 id
"code": "xxxxx", // 三方短期授权 code
}
调用时机 授权登录完成之后,三方颁发 MCP 调用授权 token 给豆包
返回
{
"code": 0,
"msg": "success",
"data": {
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxxxx",
"expires_in": 7200,
"refresh_token": "def50200a1b2c3d4e5f6xxxxx",
"refresh_token_expires_in": 2592000
}
}
Token 刷新接口
接口 Token 刷新接口
调用形式 服务端调用
需要加签验签 否
流程说明
  • 刷新或返回新的 AccessToken
参数说明 {
"app_id": "xxx", // 应用 id
"refresh_token": "xxxxx", // 三方颁发的刷新 token
}
调用时机 AccessToken 过期,静默刷新时调用
返回
{
"code": 0,
"msg": "success",
"data": {
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxxxx",
"expires_in": 7200,
"refresh_token": "def50200a1b2c3d4e5f6xxxxx",
"refresh_token_expires_in": 2592000
}
}

豆包通用信息删除能力

接口 通用信息删除接口
调用形式 服务端调用
接口说明
  • 用户在宿主平台发生 隐私数据删除操作 时,开放平台会向第三方服务发送 用户数据删除通知。用于满足:
    • 用户隐私数据删除请求
    • 平台策略要求的数据清理
    • 仅仅作为通知删除使用,不涉及账号退登、账号解绑等操作
需要加签验签 否
请求方式
  • Method:POST
  • Content-Type: application/json
  • Url: 开发者后台配置的通用信息删除地址
参数说明 (必选)
  • request_id(string) 请求唯一 ID,用于幂等控制
  • open_id(string) 用户在宿主平台的唯一标识
  • event_time(string) 从 Unix epoch 1970-01-01T00:00:00Z 算起的毫秒数
  • fields(array) 需要删除的数据字段列表
    • field_name(string) 删除字段类型,如"PHONE"、"NICKNAME"、"AVATAR"等
    • hard_delete(bool) 是否需要物理删除

(可选)
  • third_party_user_id(string) 用户在第三方系统中的用户 ID
  • reason(int32) 删除原因 0:未指定 1:用户主动删除 2:平台策略删除 ……
  • data_source(int32) 数据来源标识 1:手机号授权 2:用户信息授权 ……
调用时机 用户主动要求删除手机号或隐私数据、平台因合规或策略要求删除数据时
返回
{
"success": true,
"error_code": 0,
"error_message": ""
}

登录流程结合开发步骤详细说明

在豆包应用插件场景中,用户可以通过两种方式使用三方豆包应用插件的相关功能

  • 对话内链路:用户在对话框内通过 Query 触发
  • 豆包应用插件内回访:用户通过卡片进入豆包应用插件

在对话链路中,豆包需要调用三方提供的 MCP 工具来获取数据。三方可以通过 OAuth 方式来授权豆包访问三方 MCP。

登录流程简要说明

当用户在对话中触发需要登录的应用插件工具时,豆包将依次通过登录引导卡片、隐私协议提示、登录方式选择三个环节,引导用户完成登录授权。具体流程如下:

步骤一:登录引导卡片

豆包调用需登录的应用插件工具时,会在对话内拉起登录引导卡片,向用户说明登录后可获得的服务能力,并提供"登录"与"暂不登录"选项。

步骤二:隐私协议提示

用户点击"登录"后,页面将展示隐私协议提示,明确告知用户豆包与三方应用插件之间的信息访问与共享范围。用户须需点击"同意并继续"后方可进入后续登录环节。

步骤三:登录方式选择

用户同意隐私协议后,将进入登录方式选择卡片,提供以下两种登录途径:

  1. 豆包绑定号码登录:用户选择使用豆包绑定的手机号进行登录时,授权流程在豆包前端直接完成,豆包将用户手机号传递给三方开发者。此场景下,三方开发者无需再弹出任何额外的登录或授权页面。
  2. 其他登录方式:用户选择其他登录方式时,三方开发者需自行拉起自有登录页面供用户完成登录,并将登录结果回传至豆包。三方开发者可自定义登录页面的界面与文案,但页面中不得包含任何豆包相关的文字、图标或视觉元素。

这张图片是豆包应用的登录引导卡片,顶部显示时间为9:41,界面上方是豆包生成的内容,介绍观光廊与东方明珠广播电视塔相关信息,下方有输入框已触发“查一下周六上海去北京的机票”的查询指令,页面中部明确提示“需登录后才可以继续使用”,并设置了“暂不登录”“登录”两个操作选项,底部则配有“快速”“AI创作”“拍题”“研究”等功能入口,符合三方开发者接入豆包登录的相关界面要求。

图1:登录引导卡片

这张图片是图2隐私协议提示页,属于8.2登录接入(服务端)相关内容。页面顶部显示了豆包生成的内容,介绍了东方明珠的观光廊、文化娱乐设施与时代意义。页面下方弹出隐私协议提示弹窗,明确告知用户当点击同意开始使用产品服务时即表示理解并同意相关条款,还说明豆包会访问用户相关信息以提供必要服务,以及共享必要信息并提供了详情说明,弹窗底部设有“同意并继续”和“暂不同意”两个操作按钮。

图2:隐私协议提示

这张图片展示的是豆包服务端登录接入流程中的登录引导界面,界面顶部显示当前时间为9:41,豆包页面标注内容由AI生成,展示了上海东方明珠的相关介绍内容。界面下方的登录弹窗核心是申请获取并验证手机号以用于登录或注册账户,突出显示的蓝色区域明确呈现已绑定的手机号为155 **** 7788;弹窗下方还设有两个功能按钮,分别是“其他登录方式”和“暂不登录”,整体界面符合服务端登录接入中豆包绑定号码登录的相关要求。

图3:登录方式选择

提示

三方开发者登录页面要求

  • 采用豆包绑定号码登录时,授权交互在豆包侧完成,三方开发者不得叠加任何中间页面。
  • 采用其他登录方式时,三方自有登录页面须保持品牌独立性,禁止使用豆包品牌元素(包括但不限于"豆包"文字、豆包Logo、豆包视觉风格等),避免造成用户混淆或误认。

工具配置登录

在开发者平台注册 MCP 工具时,选择需要登录,并填写三方 Auth 服务器 Endpoint。

配置个人信息使用说明

提交前必须配置

只要 manifest.yaml 中任一 MCP 工具标记为需要登录,项目根目录的 business-templates.yaml 就必须包含 personal_information。未配置或配置未通过校验时,CLI 会阻止提交,应用插件版本无法提交。

personal_information 用于向用户说明:登录后,服务方会向豆包提供哪些个人信息,以及每类信息的使用目的。

personal_information.items 可以包含多个 PersonalInformationItem。登录授权页面会按配置顺序展示这些项目,每个项目对应一条“name:description”说明。例如,下列配置会生成图中红框内的三条说明:

personal_information:
  need_config: true
  items:
    - name: 账号信息
      description: 完成服务内下单
    - name: 订单信息
      description: 在豆包内展示、查询订单
    - name: 权益和优惠信息
      description: 查询、使用优惠权益
字段类型说明
personal_information.need_configboolean是否需要声明登录后涉及的个人信息。需要声明时设为 true 并配置 items;业务不涉及个人信息时,显式设为 false。
personal_information.itemsPersonalInformationItem[]个人信息说明列表。需要展示多类信息时,按展示顺序配置多个项目。
PersonalInformationItem.namestring信息类型名称,展示在冒号前,例如“账号信息”。
PersonalInformationItem.descriptionstring该类信息的具体用途,展示在冒号后,例如“完成服务内下单”。

登录授权页面中的个人信息使用说明。红框内依次展示账号信息、订单信息、权益和优惠信息及其用途。

personal_information 是应用级配置,对应用的所有版本生效。新版本默认继承上一版本的配置。如果个人信息类型或使用目的发生变化,请同步更新 items,确保页面展示内容与实际处理方式一致。

上传或提交应用插件版本时,CLI 会校验该配置。如果 manifest.yaml 中存在需要登录的工具,但 personal_information 缺失或格式错误,校验会失败并阻止提交。补充或修正配置后,才能提交应用插件版本。

对话内链路登录时序图

这是一张服务端登录接入相关的对话内链路登录时序图,图中包含用户、三方工具、三大服务端三个参与角色,以箭头为核心展示各角色间的交互步骤。从起始的用户调用豆包拉起对应MCP工具的登录流程,到用户选择登录方式后的鉴权、三方获取豆包用户信息,再到三方完成自身登录后生成兑换Code回调至对应接口,最终完成登录相关的交互,清晰呈现了服务端侧登录接入的全链路时序及对应操作节点。

  1. 豆包调用需要登录的 MCP 工具时,会拉起登录流程
  2. 用户同意登录后,若选择“豆包绑定号码登录”,则会完成鉴权流程;若选择“其他登录方式”,则会拉起三方自己的登录页面,并注册回调 callback。
  3. 三方豆包应用插件登录页中,开发者可以使用豆包应用插件 API 和 OpenAPI 获取用户在豆包内的信息。
  4. 三方完成自身登录流程后,需要生成三方短期兑换 Code 并回调至 callback,也可以通过端 API 读写三方登录态。
  5. 豆包会使用三方的短期登录 Code,换取三方颁发给豆包的 MCP 鉴权 Token。

登录步骤拆解(开发者视角)

提示
  1. 端侧触发登录或手机号授权,得到豆包一次性 login_code 和 phone_code。
  2. 端侧把一次性 code 传给三方服务端,不要在端侧保存长期 Token。
  3. 三方服务端调用豆包 OpenAPI 换取 open_id 或加密手机号。
  4. 三方服务端完成三方账号登录或绑定,并生成三方短期兑换 Code。
  5. 端侧调用 postLoginResult,把三方短期兑换 Code 回传给豆包 MCP Server。
  6. 豆包服务端随后调用 FetchTokenURL,用短期 Code 换取三方 MCP 调用授权 Token。
  1. 豆包侧发起对应 Query,豆包服务端下发对应豆包应用插件工具的登录卡片
  2. 用户点击登录,弹起对应隐私弹窗页面
功能说明:触发隐私交互弹窗,询问用户是否同意隐私协议
定义:
<button
open-type="agreePrivacyAuthorization"
bindagreeprivacyauthorization="handleAgree"
</button>
参数说明:无
回调结果:
success回调:已经同意过隐私/用户同意隐私
failed回调:用户拒绝隐私协议
代码示例:
<button
class="agree-btn doubao-agree-btn"
open-type="agreePrivacyAuthorization"
bindgetphonenumber="handleAgree"> <!-- 业务实现 -->
<text class="btn-icon">🔏</text>
<text>同意隐私协议</text>
</button>
  1. 用户点击同意隐私协议,弹出登录页面,用户选择使用豆包手机号一键登录:

    1. 三方前端开发者底层调用获取 OpenID 票据的 JSB:
    功能说明:触发登录弹窗,请求用户登录
    定义:
    function login(options: {
    timeout: number;
    }): Promise<{
    code: string;
    }>;
    参数说明:
    timeout: 超时时间, 单位ms
    回调结果:
    success回调:同意登录,获取登录凭证
    携带参数:
    code: 一次性登录凭证,可以获取openId
    failed回调:用户拒绝登录
    代码示例:
    import { login } from '@doubao-dev/framework';

    login({
    timeout: 10000,
    })
    .then((res) => {
    request({
    url: 'https://example.com/business',
    data: {
    token: res.code,
    }
    });
    })
    .catch(() => {
    // 用户拒绝登录或登录失败
    });
    1. 三方前端开发者底层调用获取手机号票据的 JSB:
    功能说明:触发登录弹窗,请求用户授权手机号登录
    定义:
    <button class="login-btn doubao-phone-btn"
    open-type="getPhoneNumber"
    bindgetphonenumber="handlePhoneLogin">
    </button>
    参数说明:
    timeout: 超时时间, 单位ms
    回调结果:
    success回调:同意登录,获取登录凭证
    携带参数:
    code: 一次性凭证,可以获取用户手机号码
    failed回调:用户拒绝登录
    代码示例:
    <button
    class="login-btn doubao-phone-btn"
    open-type="getPhoneNumber"
    bindgetphonenumber="handleDoubaoPhoneLogin"> <!-- 业务实现 -->
    <text class="btn-icon">📲</text>
    <text>授权手机号登录</text>
    </button>
    1. 三方前端开发者将获取到的 OpenID 票据和手机号票据传给三方服务端(均为一次性,时效为 5 分钟,过期或使用后均需重新获取)

    2. 三方服务端调用豆包服务端的 OpenAPI 获取用户的 OpenID 和加密手机号(需解密)

      1. 通过 appId 和 appSecret 获取应用级 accessToken(获取手机号接口需要)

        接口 /api/token/v1/developer/get_client_token
        形式 服务端 API
        需要加签验签 否
        流程说明
        • 通过 appId 和 appSecret 获取应用级 accessToken
        • accessToken 有效期为 2 小时,刷新 accessToken 会使上一个 accessToken 失效
        参数说明 (必选)
        • app_key
        • app_secret
        • grant_type 传 client_credential

        调用时机 调用部分需要鉴别应用身份的 OpenAPI 接口时,需要获取 accessToken 并传入
        返回
        {
        "code": 0, // 错误码,0 表示成功
        "msg": "成功", // 错误信息,描述操作结果
        "log_id": "20260211141547D42B0D74DDB3422D98DB",
        "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6Ik",
        "captcha": "",
        "desc_url": "",
        "description": "",
        "expires_in": 7200
        }
        }
        注意事项(重要)
        • client_token 的有效时间为 2 个小时,重复获取 client_token 后会使上次的 client_token 失效(但有 5 分钟的缓冲时间,连续多次获取 client_token 只会保留最新的两个 client_token)。
        • 禁止频繁调用 access-token 接口(频控规则:5 分钟内超过 500 次接口调用),建议在 token 过期前缓存复用。
        • 获取的 access_token 有有效期限制(以 expires_in 字段返回的秒数为准),过期后需重新获取。
        • 该接口作为应用级别凭证,多个业务模块之间均需要使用,因此建议仅将该接口获取 access_token 的逻辑收口在单一业务模块(推荐放在授权登录模块),避免多个模块之间互相刷新导致access-token 失效。
      2. 通过 getopenid 接口获取 OpenID

        接口 /api/login/v1/developer/get_openid
        形式 服务端 OpenAPI
        需要加签验签 否
        流程说明
        • 使用获取到的 OpenID 票据,换取用户 OpenID
        参数说明 (必选)
        • app_id
        • app_secret
        • login_code 获取到的 OpenID 票据
        • grant_type 填 authorization_code
        调用时机 登录流程中获取用户 OpenID
        返回
        {
        "code": 0, // 错误码,0 表示成功
        "msg": "成功", // 错误信息,描述操作结果
        "log_id": "20260211141547D42B0D74DDB3422D98DB",
        "data": {
        "open_id": "k100_openid_9f3b2a1c"
        }
        }
        注意事项该 OpenID 为豆包身份唯一标识,后续 MCP 对话链路均会在 Header 中以标识传入。
      3. 通过 getuserphonenumber 接口获取手机号

        接口 /api/login/v1/developer/get_user_phonenumber
        形式 服务端 OpenAPI
        需要加签验签 否
        流程说明
        • 使用获取到的手机号票据,换取用户加密手机号
        参数说明 (必选)
        请求头参数
        • x-DB-AccessToken 应用级别鉴权 Token(第一步里获取)

        请求体参数
        • phone_code 获取到的手机号票据
        调用时机 登录流程中获取用户加密手机号
        返回
        {
        "code": 0, // 错误码,0 表示成功
        "msg": "成功", // 错误信息,描述操作结果
        "log_id": "20260211141547D42B0D74DDB3422D98DB",
        "data": {
        "encrypt_phone_number": "U2FsdGVkX1+ABC123..."
        }
        }
      4. 根据应用私钥和加密手机号来解密手机号 (手机号属于敏感信息。接口返回 encrypt_phone_number 密文,业务服务端使用与平台登记的开发者证书配套的私钥完成解密。更详细的要求参见 关于证书)

      Step 1:解析返回字段

      blob = Base64URL_Decode(cipher_data)
      encrypted_data = TLV_Deserialize(blob)

      解析得到:

      • version
      • ephemeral_pub_key
      • data_key_cipher
      • data_cipher

      Step 2:解封装 dataKey

      开发者使用自己的 ECC P-256 私钥 dev_priv:

      1. 计算共享密钥:
      shared_secret = ECDH(dev_priv, ephemeral_pub_key)
      1. 对共享密钥进行 SHA-256 哈希,得到 KEK:
      kek = SHA256(shared_secret)
      1. 使用 KEK 解密 data_key_cipher,得到 dataKey

      Step 3:解密业务数据

      data_plain = AES256_GCM_Decrypt(
          key = dataKey,
          cipher = data_cipher
      )

      Step 4:解析 data JSON(可选,有些加密数据可能不是 Json 格式)

      data = JSON.parse(data_plain)

      即可获得解密后的明文手机号

      解密代码示例

      import javax.crypto.Cipher;
      import javax.crypto.KeyAgreement;
      import javax.crypto.SecretKey;
      import javax.crypto.spec.GCMParameterSpec;
      import javax.crypto.spec.SecretKeySpec;
      import java.io.IOException;
      import java.math.BigInteger;
      import java.nio.ByteBuffer;
      import java.nio.ByteOrder;
      import java.nio.charset.StandardCharsets;
      import java.nio.file.Files;
      import java.nio.file.Paths;
      import java.security.AlgorithmParameters;
      import java.security.KeyFactory;
      import java.security.MessageDigest;
      import java.security.PrivateKey;
      import java.security.PublicKey;
      import java.security.interfaces.ECPrivateKey;
      import java.security.spec.ECGenParameterSpec;
      import java.security.spec.ECParameterSpec;
      import java.security.spec.ECPoint;
      import java.security.spec.ECPublicKeySpec;
      import java.security.spec.PKCS8EncodedKeySpec;
      import java.util.Arrays;
      import java.util.Base64;
      import java.util.HashMap;
      import java.util.Map;
      
      /**
       * ECC + AES-GCM 解密工具类
       *
       * <p>
       * 与 Go 侧 EncryptWithCert 完全兼容:
       * <ul>
       *   <li>ECDH P-256(secp256r1)</li>
       *   <li>KEK = SHA256(sharedSecret)</li>
       *   <li>AES-256-GCM(iv || cipher || tag)</li>
       *   <li>TLV 编码</li>
       * </ul>
       *
       * <p><b>安全注意:</b>
       * <ul>
       *   <li>私钥必须安全保存(如 KMS / HSM / 加密文件系统)</li>
       *   <li>不要将私钥内容硬编码在代码中或提交到代码仓库</li>
       * </ul>
       */
      public final class ECCDecryptor {
      
          /** TLV 类型定义(需与加密端一致) */
          private static final int TLV_VERSION = 0x0001;
          private static final int TLV_EPHEMERAL_PUB_KEY = 0x0002;
          private static final int TLV_DATA_KEY_CIPHER = 0x0003;
          private static final int TLV_DATA_CIPHER = 0x0004;
      
          private ECCDecryptor() {
          }
      
          /**
           * 解密接口
           *
           * @param cipherDataBase64Url 平台返回的 Base64URL 编码密文
           * @param privateKeyPemPath   开发者 ECDSA P-256 私钥(PKCS#8 PEM 文件路径)
           * @return 解密后的业务数据明文(JSON 字节)
           * @throws Exception 解密失败
           */
          public static byte[] decrypt(
                  String cipherDataBase64Url,
                  String privateKeyPemPath
          ) throws Exception {
      
              // 1. Base64URL 解码
              byte[] blob = Base64.getUrlDecoder().decode(cipherDataBase64Url);
      
              // 2. TLV 解析
              Map<Integer, byte[]> tlvMap = parseTLV(blob);
      
              // 3. 校验协议版本
              int version = ByteBuffer.wrap(tlvMap.get(TLV_VERSION))
                      .order(ByteOrder.BIG_ENDIAN)
                      .getShort();
              if (version != 1) {
                  throw new IllegalArgumentException("Unsupported version: " + version);
              }
      
              byte[] ephemeralPubBytes = tlvMap.get(TLV_EPHEMERAL_PUB_KEY);
              byte[] dataKeyCipher = tlvMap.get(TLV_DATA_KEY_CIPHER);
              byte[] dataCipher = tlvMap.get(TLV_DATA_CIPHER);
      
              // 4. 加载开发者私钥(请确保私钥安全存储,不要硬编码)
              ECPrivateKey privateKey = loadECPrivateKey(privateKeyPemPath);
      
              // 5. 构造临时公钥
              PublicKey ephemeralPubKey = buildECPublicKey(ephemeralPubBytes);
      
              // 6. ECDH 计算共享密钥
              byte[] sharedSecret = ecdh(privateKey, ephemeralPubKey);
      
              // 7. KEK = SHA256(sharedSecret)
              MessageDigest sha256 = MessageDigest.getInstance("SHA-256");
              byte[] kek = sha256.digest(sharedSecret);
      
              // 8. 解密 DataKey
              byte[] dataKey = aesGcmDecrypt(kek, dataKeyCipher);
      
              // 9. 解密业务数据
              return aesGcmDecrypt(dataKey, dataCipher);
          }
      
          /**
           * TLV 解析
           *
           * <pre>
           * Type   uint16 (BigEndian)
           * Length uint32 (BigEndian)
           * Value  bytes
           * </pre>
           */
          private static Map<Integer, byte[]> parseTLV(byte[] data) {
              Map<Integer, byte[]> map = new HashMap<>();
              ByteBuffer buf = ByteBuffer.wrap(data).order(ByteOrder.BIG_ENDIAN);
      
              while (buf.remaining() > 0) {
                  int type = Short.toUnsignedInt(buf.getShort());
                  int length = buf.getInt();
                  byte[] value = new byte[length];
                  buf.get(value);
                  map.put(type, value);
              }
              return map;
          }
      
          /**
           * 从 PEM 文件加载 ECDSA P-256 私钥(PKCS#8)
           *
           * <p><b>安全提示:</b>
           * 私钥应存储在安全介质中(如 KMS / HSM / 加密文件系统),
           * 不应明文保存在代码仓库或配置文件中。
           */
          private static ECPrivateKey loadECPrivateKey(String pemPath) throws Exception {
              String pem = new String(Files.readAllBytes(Paths.get(pemPath)), StandardCharsets.UTF_8);
              pem = pem.replace("-----BEGIN PRIVATE KEY-----", "")
                       .replace("-----END PRIVATE KEY-----", "")
                       .replaceAll("\\s", "");
      
              byte[] der = Base64.getDecoder().decode(pem);
              PKCS8EncodedKeySpec spec = new PKCS8EncodedKeySpec(der);
              return (ECPrivateKey) KeyFactory.getInstance("EC").generatePrivate(spec);
          }
      
          /**
           * 构造 ECC P-256 公钥(X9.62 非压缩格式)
           *
           * <pre>
           * 04 || X(32 bytes) || Y(32 bytes)
           * </pre>
           */
          private static PublicKey buildECPublicKey(byte[] pubBytes) throws Exception {
              byte[] xBytes = Arrays.copyOfRange(pubBytes, 1, 33);
              byte[] yBytes = Arrays.copyOfRange(pubBytes, 33, 65);
      
              BigInteger x = new BigInteger(1, xBytes);
              BigInteger y = new BigInteger(1, yBytes);
      
              AlgorithmParameters parameters = AlgorithmParameters.getInstance("EC");
              parameters.init(new ECGenParameterSpec("secp256r1"));
              ECParameterSpec ecSpec = parameters.getParameterSpec(ECParameterSpec.class);
      
              ECPublicKeySpec pubSpec = new ECPublicKeySpec(new ECPoint(x, y), ecSpec);
              return KeyFactory.getInstance("EC").generatePublic(pubSpec);
          }
      
          /**
           * 执行 ECDH 密钥协商
           */
          private static byte[] ecdh(PrivateKey privateKey, PublicKey publicKey) throws Exception {
              KeyAgreement ka = KeyAgreement.getInstance("ECDH");
              ka.init(privateKey);
              ka.doPhase(publicKey, true);
              return ka.generateSecret();
          }
      
          /**
           * AES-256-GCM 解密
           *
           * <pre>
           * 输入格式:iv(12 bytes) || cipher || tag
           * </pre>
           */
          private static byte[] aesGcmDecrypt(byte[] key, byte[] cipherData) throws Exception {
              byte[] iv = Arrays.copyOfRange(cipherData, 0, 12);
              byte[] cipherTextWithTag = Arrays.copyOfRange(cipherData, 12, cipherData.length);
      
              Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
              GCMParameterSpec spec = new GCMParameterSpec(128, iv);
              SecretKey aesKey = new SecretKeySpec(key, "AES");
      
              cipher.init(Cipher.DECRYPT_MODE, aesKey, spec);
              return cipher.doFinal(cipherTextWithTag);
          }
      }
      import base64
      import struct
      from hashlib import sha256
      
      from cryptography.hazmat.primitives import serialization
      from cryptography.hazmat.primitives.asymmetric import ec
      from cryptography.hazmat.primitives.ciphers.aead import AESGCM
      
      
      TLV_VERSION = 0x0001
      TLV_EPHEMERAL_PUB_KEY = 0x0002
      TLV_DATA_KEY_CIPHER = 0x0003
      TLV_DATA_CIPHER = 0x0004
      
      
      def parse_tlv(data: bytes) -> dict[int, bytes]:
          result: dict[int, bytes] = {}
          offset = 0
          total = len(data)
      
          while offset < total:
              if offset + 6 > total:
                  raise ValueError("invalid TLV header")
      
              tlv_type = struct.unpack(">H", data[offset : offset + 2])[0]
              length = struct.unpack(">I", data[offset + 2 : offset + 6])[0]
              offset += 6
      
              if offset + length > total:
                  raise ValueError("invalid TLV length")
      
              result[tlv_type] = data[offset : offset + length]
              offset += length
      
          return result
      
      
      def load_ec_private_key(pem_path: str) -> ec.EllipticCurvePrivateKey:
          with open(pem_path, "rb") as fp:
              private_key = serialization.load_pem_private_key(fp.read(), password=None)
      
          if not isinstance(private_key, ec.EllipticCurvePrivateKey):
              raise TypeError("private key is not an EC private key")
      
          return private_key
      
      
      def aes_gcm_decrypt(key: bytes, cipher_data: bytes) -> bytes:
          if len(cipher_data) < 12:
              raise ValueError("cipher data too short")
      
          iv = cipher_data[:12]
          cipher_text_with_tag = cipher_data[12:]
          return AESGCM(key).decrypt(iv, cipher_text_with_tag, None)
      
      
      def decrypt(cipher_data_base64url: str, private_key_pem_path: str) -> bytes:
          blob = base64.urlsafe_b64decode(cipher_data_base64url)
          tlv_map = parse_tlv(blob)
      
          version = struct.unpack(">H", tlv_map[TLV_VERSION])[0]
          if version != 1:
              raise ValueError(f"unsupported version: {version}")
      
          ephemeral_pub_bytes = tlv_map[TLV_EPHEMERAL_PUB_KEY]
          data_key_cipher = tlv_map[TLV_DATA_KEY_CIPHER]
          data_cipher = tlv_map[TLV_DATA_CIPHER]
      
          private_key = load_ec_private_key(private_key_pem_path)
          ephemeral_public_key = ec.EllipticCurvePublicKey.from_encoded_point(ec.SECP256R1(), ephemeral_pub_bytes)
          shared_secret = private_key.exchange(ec.ECDH(), ephemeral_public_key)
      
          kek = sha256(shared_secret).digest()
          data_key = aes_gcm_decrypt(kek, data_key_cipher)
          return aes_gcm_decrypt(data_key, data_cipher)
      
      package main
      
      import (
              "crypto/aes"
              "crypto/cipher"
              "crypto/ecdsa"
              "crypto/elliptic"
              "crypto/sha256"
              "crypto/x509"
              "encoding/base64"
              "encoding/binary"
              "encoding/pem"
              "errors"
              "fmt"
              "math/big"
              "os"
      )
      
      const (
              tlvVersion         = 0x0001
              tlvEphemeralPubKey = 0x0002
              tlvDataKeyCipher   = 0x0003
              tlvDataCipher      = 0x0004
      )
      
      func parseTLV(data []byte) (map[uint16][]byte, error) {
              result := make(map[uint16][]byte)
              for offset := 0; offset < len(data); {
                      if offset+6 > len(data) {
                              return nil, errors.New("invalid TLV header")
                      }
      
                      typ := binary.BigEndian.Uint16(data[offset : offset+2])
                      length := int(binary.BigEndian.Uint32(data[offset+2 : offset+6]))
                      offset += 6
      
                      if offset+length > len(data) {
                              return nil, errors.New("invalid TLV length")
                      }
      
                      value := make([]byte, length)
                      copy(value, data[offset:offset+length])
                      result[typ] = value
                      offset += length
              }
      
              return result, nil
      }
      
      func loadECDSAPrivateScalar(pemPath string) (*big.Int, error) {
              pemBytes, err := os.ReadFile(pemPath)
              if err != nil {
                      return nil, err
              }
      
              block, _ := pem.Decode(pemBytes)
              if block == nil {
                      return nil, errors.New("failed to decode PEM private key")
              }
      
              privateKeyAny, err := x509.ParsePKCS8PrivateKey(block.Bytes)
              if err != nil {
                      return nil, err
              }
      
              privateKey, ok := privateKeyAny.(*ecdsa.PrivateKey)
              if !ok {
                      return nil, fmt.Errorf("private key is not ECDSA: %T", privateKeyAny)
              }
      
              return privateKey.D, nil
      }
      
      func aesGcmDecrypt(key []byte, cipherData []byte) ([]byte, error) {
              if len(cipherData) < 12 {
                      return nil, errors.New("cipher data too short")
              }
      
              block, err := aes.NewCipher(key)
              if err != nil {
                      return nil, err
              }
      
              gcm, err := cipher.NewGCM(block)
              if err != nil {
                      return nil, err
              }
      
              nonce := cipherData[:12]
              cipherTextWithTag := cipherData[12:]
              return gcm.Open(nil, nonce, cipherTextWithTag, nil)
      }
      
      func decrypt(cipherDataBase64URL string, privateKeyPemPath string) ([]byte, error) {
              blob, err := base64.URLEncoding.DecodeString(cipherDataBase64URL)
              if err != nil {
                      return nil, err
              }
      
              tlvMap, err := parseTLV(blob)
              if err != nil {
                      return nil, err
              }
      
              versionBytes, ok := tlvMap[tlvVersion]
              if !ok || len(versionBytes) != 2 {
                      return nil, errors.New("missing version field")
              }
              version := binary.BigEndian.Uint16(versionBytes)
              if version != 1 {
                      return nil, fmt.Errorf("unsupported version: %d", version)
              }
      
              ephemeralPubBytes, ok := tlvMap[tlvEphemeralPubKey]
              if !ok {
                      return nil, errors.New("missing ephemeral public key")
              }
              dataKeyCipher, ok := tlvMap[tlvDataKeyCipher]
              if !ok {
                      return nil, errors.New("missing data key cipher")
              }
              dataCipher, ok := tlvMap[tlvDataCipher]
              if !ok {
                      return nil, errors.New("missing data cipher")
              }
      
              privateScalar, err := loadECDSAPrivateScalar(privateKeyPemPath)
              if err != nil {
                      return nil, err
              }
      
              x, y := elliptic.Unmarshal(elliptic.P256(), ephemeralPubBytes)
              if x == nil || y == nil {
                      return nil, errors.New("invalid ephemeral public key")
              }
      
              sharedX, _ := elliptic.P256().ScalarMult(x, y, privateScalar.Bytes())
              if sharedX == nil {
                      return nil, errors.New("failed to derive shared secret")
              }
      
              sharedSecret := sharedX.FillBytes(make([]byte, 32))
              kek := sha256.Sum256(sharedSecret)
      
              dataKey, err := aesGcmDecrypt(kek[:], dataKeyCipher)
              if err != nil {
                      return nil, err
              }
      
              return aesGcmDecrypt(dataKey, dataCipher)
      }
      
      #include <openssl/core_names.h>
      #include <openssl/evp.h>
      #include <openssl/param_build.h>
      #include <openssl/pem.h>
      #include <openssl/sha.h>
      
      #include <cstdint>
      #include <cstdio>
      #include <fstream>
      #include <map>
      #include <memory>
      #include <stdexcept>
      #include <string>
      #include <vector>
      
      namespace ecc_decryptor {
      
      namespace {
      
      constexpr uint16_t kTLVVersion = 0x0001;
      constexpr uint16_t kTLVEphemeralPubKey = 0x0002;
      constexpr uint16_t kTLVDataKeyCipher = 0x0003;
      constexpr uint16_t kTLVDataCipher = 0x0004;
      
      using ByteVector = std::vector<unsigned char>;
      
      uint16_t ReadUint16BE(const unsigned char* data) {
          return static_cast<uint16_t>(data[0] << 8 | data[1]);
      }
      
      uint32_t ReadUint32BE(const unsigned char* data) {
          return (static_cast<uint32_t>(data[0]) << 24) |
                 (static_cast<uint32_t>(data[1]) << 16) |
                 (static_cast<uint32_t>(data[2]) << 8) |
                 static_cast<uint32_t>(data[3]);
      }
      
      ByteVector Base64UrlDecode(const std::string& input) {
          std::string normalized = input;
          for (char& ch : normalized) {
              if (ch == '-') {
                  ch = '+';
              } else if (ch == '_') {
                  ch = '/';
              }
          }
          while (normalized.size() % 4 != 0) {
              normalized.push_back('=');
          }
      
          ByteVector output((normalized.size() / 4) * 3);
          const int decodedLen = EVP_DecodeBlock(output.data(),
                                                 reinterpret_cast<const unsigned char*>(normalized.data()),
                                                 static_cast<int>(normalized.size()));
          if (decodedLen < 0) {
              throw std::runtime_error("base64url decode failed");
          }
      
          size_t padding = 0;
          if (!normalized.empty() && normalized[normalized.size() - 1] == '=') {
              padding++;
          }
          if (normalized.size() > 1 && normalized[normalized.size() - 2] == '=') {
              padding++;
          }
          output.resize(static_cast<size_t>(decodedLen) - padding);
          return output;
      }
      
      std::map<uint16_t, ByteVector> ParseTLV(const ByteVector& data) {
          std::map<uint16_t, ByteVector> result;
          size_t offset = 0;
      
          while (offset < data.size()) {
              if (offset + 6 > data.size()) {
                  throw std::runtime_error("invalid TLV header");
              }
      
              const auto type = ReadUint16BE(&data[offset]);
              const auto length = ReadUint32BE(&data[offset + 2]);
              offset += 6;
      
              if (offset + length > data.size()) {
                  throw std::runtime_error("invalid TLV length");
              }
      
              result[type] = ByteVector(data.begin() + static_cast<long>(offset),
                                        data.begin() + static_cast<long>(offset + length));
              offset += length;
          }
      
          return result;
      }
      
      using EVPKeyPtr = std::unique_ptr<EVP_PKEY, decltype(&EVP_PKEY_free)>;
      using EVPContextPtr = std::unique_ptr<EVP_PKEY_CTX, decltype(&EVP_PKEY_CTX_free)>;
      using ParamBuilderPtr = std::unique_ptr<OSSL_PARAM_BLD, decltype(&OSSL_PARAM_BLD_free)>;
      using ParamsPtr = std::unique_ptr<OSSL_PARAM, decltype(&OSSL_PARAM_free)>;
      using CipherContextPtr = std::unique_ptr<EVP_CIPHER_CTX, decltype(&EVP_CIPHER_CTX_free)>;
      
      EVPKeyPtr LoadPrivateKey(const std::string& pemPath) {
          FILE* file = std::fopen(pemPath.c_str(), "r");
          if (file == nullptr) {
              throw std::runtime_error("failed to open private key PEM file");
          }
      
          EVP_PKEY* raw = PEM_read_PrivateKey(file, nullptr, nullptr, nullptr);
          std::fclose(file);
          if (raw == nullptr) {
              throw std::runtime_error("failed to read private key PEM");
          }
      
          return EVPKeyPtr(raw, EVP_PKEY_free);
      }
      
      EVPKeyPtr BuildPublicKey(const ByteVector& publicKeyBytes) {
          EVPContextPtr ctx(EVP_PKEY_CTX_new_from_name(nullptr, "EC", nullptr), EVP_PKEY_CTX_free);
          if (!ctx) {
              throw std::runtime_error("failed to create EVP_PKEY context");
          }
      
          if (EVP_PKEY_fromdata_init(ctx.get()) != 1) {
              throw std::runtime_error("failed to init public key import");
          }
      
          ParamBuilderPtr builder(OSSL_PARAM_BLD_new(), OSSL_PARAM_BLD_free);
          if (!builder) {
              throw std::runtime_error("failed to create OSSL_PARAM_BLD");
          }
      
          if (OSSL_PARAM_BLD_push_utf8_string(builder.get(), OSSL_PKEY_PARAM_GROUP_NAME, "prime256v1", 0) != 1) {
              throw std::runtime_error("failed to set EC group name");
          }
          if (OSSL_PARAM_BLD_push_octet_string(builder.get(),
                                               OSSL_PKEY_PARAM_PUB_KEY,
                                               publicKeyBytes.data(),
                                               publicKeyBytes.size()) != 1) {
              throw std::runtime_error("failed to set EC public key bytes");
          }
      
          ParamsPtr params(OSSL_PARAM_BLD_to_param(builder.get()), OSSL_PARAM_free);
          if (!params) {
              throw std::runtime_error("failed to build OSSL params");
          }
      
          EVP_PKEY* pkey = nullptr;
          if (EVP_PKEY_fromdata(ctx.get(), &pkey, EVP_PKEY_PUBLIC_KEY, params.get()) != 1) {
              throw std::runtime_error("failed to import EC public key");
          }
      
          return EVPKeyPtr(pkey, EVP_PKEY_free);
      }
      
      ByteVector DeriveSharedSecret(EVP_PKEY* privateKey, EVP_PKEY* publicKey) {
          EVPContextPtr ctx(EVP_PKEY_CTX_new(privateKey, nullptr), EVP_PKEY_CTX_free);
          if (!ctx) {
              throw std::runtime_error("failed to create ECDH context");
          }
          if (EVP_PKEY_derive_init(ctx.get()) != 1) {
              throw std::runtime_error("failed to init ECDH derive");
          }
          if (EVP_PKEY_derive_set_peer(ctx.get(), publicKey) != 1) {
              throw std::runtime_error("failed to set ECDH peer key");
          }
      
          size_t secretLen = 0;
          if (EVP_PKEY_derive(ctx.get(), nullptr, &secretLen) != 1) {
              throw std::runtime_error("failed to query shared secret length");
          }
      
          ByteVector secret(secretLen);
          if (EVP_PKEY_derive(ctx.get(), secret.data(), &secretLen) != 1) {
              throw std::runtime_error("failed to derive shared secret");
          }
          secret.resize(secretLen);
          return secret;
      }
      
      ByteVector AesGcmDecrypt(const ByteVector& key, const ByteVector& cipherData) {
          if (key.size() != 32) {
              throw std::runtime_error("invalid AES-256-GCM key length");
          }
      
          if (cipherData.size() < 12 + 16) {
              throw std::runtime_error("cipher data too short");
          }
      
          const unsigned char* iv = cipherData.data();
          const size_t cipherTextWithTagLen = cipherData.size() - 12;
          const unsigned char* cipherTextWithTag = cipherData.data() + 12;
          const size_t cipherTextLen = cipherTextWithTagLen - 16;
          const unsigned char* tag = cipherTextWithTag + cipherTextLen;
      
          CipherContextPtr ctx(EVP_CIPHER_CTX_new(), EVP_CIPHER_CTX_free);
          if (!ctx) {
              throw std::runtime_error("failed to create cipher context");
          }
      
          if (EVP_DecryptInit_ex(ctx.get(), EVP_aes_256_gcm(), nullptr, nullptr, nullptr) != 1) {
              throw std::runtime_error("failed to init AES-GCM");
          }
          if (EVP_CIPHER_CTX_ctrl(ctx.get(), EVP_CTRL_GCM_SET_IVLEN, 12, nullptr) != 1) {
              throw std::runtime_error("failed to set GCM IV length");
          }
          if (EVP_DecryptInit_ex(ctx.get(), nullptr, nullptr, key.data(), iv) != 1) {
              throw std::runtime_error("failed to set AES-GCM key/iv");
          }
      
          ByteVector plain(cipherTextLen);
          int outLen = 0;
          if (EVP_DecryptUpdate(ctx.get(),
                                plain.data(),
                                &outLen,
                                cipherTextWithTag,
                                static_cast<int>(cipherTextLen)) != 1) {
              throw std::runtime_error("failed to decrypt AES-GCM payload");
          }
      
          if (EVP_CIPHER_CTX_ctrl(ctx.get(), EVP_CTRL_GCM_SET_TAG, 16, const_cast<unsigned char*>(tag)) != 1) {
              throw std::runtime_error("failed to set GCM tag");
          }
      
          int finalLen = 0;
          if (EVP_DecryptFinal_ex(ctx.get(), plain.data() + outLen, &finalLen) != 1) {
              throw std::runtime_error("AES-GCM authentication failed");
          }
      
          plain.resize(static_cast<size_t>(outLen + finalLen));
          return plain;
      }
      
      }  // namespace
      
      std::vector<unsigned char> decrypt(const std::string& cipherDataBase64Url,
                                         const std::string& privateKeyPemPath) {
          const auto blob = Base64UrlDecode(cipherDataBase64Url);
          const auto tlvMap = ParseTLV(blob);
      
          const auto versionIt = tlvMap.find(kTLVVersion);
          if (versionIt == tlvMap.end() || versionIt->second.size() != 2) {
              throw std::runtime_error("missing version field");
          }
          const auto version = ReadUint16BE(versionIt->second.data());
          if (version != 1) {
              throw std::runtime_error("unsupported version");
          }
      
          const auto ephemeralPubIt = tlvMap.find(kTLVEphemeralPubKey);
          const auto dataKeyCipherIt = tlvMap.find(kTLVDataKeyCipher);
          const auto dataCipherIt = tlvMap.find(kTLVDataCipher);
          if (ephemeralPubIt == tlvMap.end() || dataKeyCipherIt == tlvMap.end() || dataCipherIt == tlvMap.end()) {
              throw std::runtime_error("missing required TLV fields");
          }
      
          const auto privateKey = LoadPrivateKey(privateKeyPemPath);
          const auto publicKey = BuildPublicKey(ephemeralPubIt->second);
          const auto sharedSecret = DeriveSharedSecret(privateKey.get(), publicKey.get());
      
          unsigned char kek[SHA256_DIGEST_LENGTH];
          SHA256(sharedSecret.data(), sharedSecret.size(), kek);
      
          const ByteVector dataKey = AesGcmDecrypt(ByteVector(kek, kek + SHA256_DIGEST_LENGTH), dataKeyCipherIt->second);
          return AesGcmDecrypt(dataKey, dataCipherIt->second);
      }
      
      }  // namespace ecc_decryptor
      
  2. 三方服务端将颁发给豆包侧后续换取token的一次性code下发给三方前端

  3. 三方前端携带code调用postLoginResult JSB完成MCP登录结果回传

    功能说明:向豆包 MCP Server 回传登录结果及授权凭证
    定义:
    function postLoginResult(options: {
    success: boolean;
    code?: string;
    }): Promise<void>;
    参数说明:
    success:
    布尔值,表示登录是否成功
    code?:
    业务服务端发送给 MCP Server 的授权凭证
    success 为 true 时有效,false 时可空
    回调结果:无
    代码示例:
    import { postLoginResult } from '@byted-doubao-apps/framework';

    postLoginResult({
    success: true,
    code: "xxxxxxxx"
    })
    .then(() => {
    // 凭证回传成功
    })
    .catch((e) => {
    // 回传失败
    console.log("Failed to post:", e)
    });
  4. 豆包客户端框架将code传给豆包服务端,豆包服务端调用三方提供的oauth endpoint完成token的交换,返回success状态

  5. 豆包客户端框架收到 success 状态后,自动关闭 MCP 登录页,并重新发送 Query。

  6. 豆包服务端将三方服务端颁发的 access_token 和 OpenID 身份标识透传在 Header 中,调用三方 MCP 工具,并返回对应数据和卡片内容。

    字段透传方式透传字段含义
    OpenIDHeaderX-DB-OPENID用户 OpenID
    AccessTokenHeaderX-DB-ACCESS-TOKEN三方在登录过程中颁发给豆包的用户 access_token ,用于三方校验调用者身份

豆包应用插件全页内链路登录时序图

  • 整体流程跟对话内链路登录时序类似,仅仅少了前置的用户发自然语言的 Query 步骤和具体 MCP 工具调用的步骤

应用插件全页内链路登录时序图,展示用户、应用插件和服务端之间的登录授权流程

  1. 用户进入豆包应用插件之后,豆包应用插件如果判断需要三方登录(根据自定义登录态是否过期判断),可以调用拉起三方登录页
  2. 三方登录流程完成之后,需要将三方兑换 code 回调到豆包应用插件框架提供的默认 callback 上,完成对豆包的授权

运行时链路总结说明

完整时序说明

  1. 开发者在开发者平台为 MCP Server 选择“需要登录”,并配置业务方的 FetchTokenURL、RefreshTokenURL、DeleteUserInfoURL、服务协议、隐私政策和回调地址。
  2. 豆包应用插件准备调用需授权的 MCP 工具时,拉起登录授权流程。
  3. 用户同意后进入业务方登录页。业务服务端完成账号校验,以 open_id 为外部身份建立或查找本地账号绑定。
  4. 业务服务端签发一个短时、一次性授权 Code,并通过前端 JSB 调用透给平台侧服务端。
  5. 平台从业务 Token 获取地址用 Code 换取 access_token 和 refresh_token。
  6. 后续 MCP 请求通过 Header 透传身份和凭证:X-DB-OPENID 表示用户,X-DB-ACCESS-TOKEN 表示业务授权的凭证身份。
  7. 用户 Token 过期时,平台使用 refresh_token 调用刷新接口;刷新失败或用户已撤销授权或登录态失效时,重新进入交互式登录。

对话内链路

  1. 用户在豆包对话框内通过 Query 触发三方能力。
  2. 豆包调用需要登录的 MCP 工具时,如果没有可用授权,会拉起登录流程。
  3. 用户同意登录后,平台拉起三方登录页面,并注册回调。
  4. 三方登录页面通过容器 API 获取一次性登录凭证,并由三方服务端换取 OpenID、手机号等信息。
  5. 三方完成自己的账号登录后,生成三方短期兑换 Code,并通过 postLoginResult 或回调交给豆包。
  6. 豆包用短期 Code 调用三方 FetchTokenURL,换取 MCP 调用授权 Token。
  7. 后续豆包调用三方 MCP 工具时,会在请求 Header 中透传 X-DB-OPENID;三方工具的 inputSchema 不需要显式声明 OpenID 字段。

豆包应用插件内回访链路

  1. 用户通过卡片或其他入口进入三方豆包应用插件。
  2. 豆包应用插件根据三方自定义登录态判断是否需要重新登录。
  3. 如果需要登录,豆包应用插件调用登录页或 doubao.login(),完成三方登录。
  4. 三方登录完成后,把三方兑换 code 回调到豆包应用插件框架提供的默认 callback,完成对豆包的授权。
  5. 登录完成后刷新卡片或页面状态,确保用户看到最新业务数据。

用户身份标识与多端登录场景说明

身份标识

平台调用三方服务时,使用 OpenID 标识用户。三方需维护 OpenID 与三方账号的关联。

手机号给到三方起到一个账号对撞的作用,当前手机号在三方已经存在账号时,使用已有账号进行关联,否则新注册一个账号进行关联。

多端登录

豆包 APP 可以多端登录(即同一个账号可以同时登录多个设备)。在多端登录场景下:

  • 三方颁发给豆包的鉴权 Token 支持多端同步,即多个设备在主 Bot 对话内链路复用同一个鉴权 token
  • 豆包应用插件内登录态由三方开发者维护,平台不存储三方登录态,推荐开发者在豆包应用插件中使用 doubao.login() 来实现静默登录

应用插件、业务服务端与豆包之间的登录交互时序图,展示登录码校验和业务登录态建立流程

OpenID、Token 与登录态维护规则

开发者必须维护
  • OpenID 与三方账号的绑定关系。
  • 三方 MCP 授权 Token 与 RefreshToken 的生命周期。
  • 豆包应用插件内自定义登录态,平台不存储三方登录态。
平台会提供和透传
  • 登录、手机号、隐私授权相关容器能力。
  • 服务端 OpenAPI:获取 OpenID、手机号、应用级 AccessToken。
  • MCP 调用时通过 X-DB-OPENID 透传用户标识。
  • 多端登录场景下,豆包侧会复用同一 MCP 授权 Token。
提示

推荐:豆包应用插件内登录态由三方维护,建议在豆包应用插件中使用 doubao.login() 做静默登录或快速恢复,避免多端场景下出现用户重复授权。

异常情况处理

关于登录有效期

三方颁发给豆包的授权 Token 有效期与三方豆包应用插件内的自定义登录态有效期不一致会出现用户体验问题。对于这种异常场景的处理建议如下

情况梳理 用户体感 三方处理方式
授权 Token 有效期 > 自定义登录态
  1. 对话内链路 Query 可以正常下发卡片
  2. 进入豆包应用插件后无登录态
豆包应用插件内调用 doubao.login,换取 OpenID,重新下发登录态
授权 Token 有效期 < 自定义登录态
  1. 对话内链路判断无授权,进入登录流程
  2. 豆包应用插件内已登录
豆包应用插件向三方服务器申请短期兑换 Code,回传给豆包;豆包换取新的鉴权 Token。

所以这里推荐开发者尽量维持颁发给豆包的授权 Token 有效期与三方自定义登录态的有效期保持一致,否则可能出现 MCP 还能调用但豆包应用插件内已退出,或豆包应用插件仍登录但 MCP Token 已过期的体验不一致问题。

其他异常与边界场景

场景开发者处理方式验收标准
用户拒绝登录端侧走 onRefuseLogin 或失败回调,调用失败态回传,不继续请求用户数据。页面可恢复,MCP 工具不会拿到错误 Token。
用户拒绝隐私协议端侧走 onRefusePrivacy,停止手机号/隐私信息获取。不产生隐私数据读取调用。
AccessToken 过期豆包调用 RefreshTokenURL;三方返回新的 AccessToken 和 RefreshToken。用户无感刷新,失败时重新拉起登录。
RefreshToken 过期三方返回明确失败,平台重新触发登录授权。用户重新登录后恢复 MCP 调用。
多端登录三方颁发给豆包的 MCP Token 支持多端同步;豆包应用插件端自定义登录态自行维护。同一用户多设备访问时身份一致。
隐私删除按 request_id 幂等处理,删除指定 fields,必要时执行物理删除。重复通知不会重复造成异常,返回统一成功结构。

业务主动拉起登录场景

  • 由于豆包侧存储的 access_token 可能在以下场景调用到业务侧已经失效,此时需要有能够主动拉起应用插件重新登录流程的能力:
    • 时序问题到达业务方的 access_token 刚好到失效期
    • 命中安全策略(如 token 泄露等),业务方可主动失效掉已经颁发给豆包宿主的 access_token
  • 对于以上场景豆包侧的处理流程:
    • access_token 过期:
      • 需要业务侧返回 http status_code 状态码为 401 (内部 rpc 业务返回 50401),豆包侧识别到该状态码之后会主动强制拉起登录,让用户重新完成登录流程,获取业务方新颁发的 access_token (注意在其他返回状态码的场景中不要混用 401 以免服务报错)。
    • refresh_token 过期:
      • 对应刷新 token 的接口返回的 Code = 50401 && Msg = "token expired" (注意二者均需按照要求返回)

OpenAPI 接入流程

调试环境说明

真实 AppID 已支持在 Sandbox 中使用,但 AppID 类型不代表当前运行环境。登录流程中的应用凭证、login_code、phone_code、应用级 Access Token 和 OpenAPI 必须属于同一环境,不能混用。

调试方式可使用的 AppIDCode 和 Token 环境OpenAPI 环境
Web 模拟器 / SandboxSandbox AppID 或真实 AppIDSandboxSandbox
真机调试 / 预览版 / 线上真实 AppID正式环境正式环境

真实 AppID 在 Sandbox 中运行时,生成的仍是 Sandbox 环境的 login_code 和 phone_code,必须搭配 Sandbox 环境的应用级 Access Token 和 OpenAPI 使用。

调试阶段建议

建议开发者在调试版本中对登录各步骤增加显式错误提示,避免错误被页面吞掉,便于确认流程中断位置:

  1. 获取 login_code 或 phone_code。
  2. 使用 login_code 换取 OpenID。
  3. 使用 phone_code 换取加密手机号。
  4. 完成三方登录并生成短期兑换 Code。
  5. 调用 postLoginResult 回传登录结果。

错误提示建议包含当前步骤、接口返回的 code、msg 和 log_id。请勿展示或记录 AppSecret、完整 Access Token、完整 login_code、完整 phone_code 等敏感信息;详细错误提示仅用于调试版本。

获取应用级 Token

  • 需要调用应用级 OpenAPI 时,服务端调用 /api/token/v1/developer/get_client_token,传入 app_id、app_secret 和 grant_type=client_credential。获取后按 expires_in 缓存,不要在每个业务请求中重新获取。
  • 推荐将应用级 Token 收口到一个服务端 Token Provider:统一缓存、提前刷新、并发单飞(single-flight)、原子换新和失败重试。避免多实例同时刷新导致旧 Token 立即失效。

用 login_code 换取 OpenID

  • 豆包应用插件端完成用户登录授权后,获得一次性 login_code 并传给业务服务端。服务端立即调用 /api/login/v1/developer/get_openid,使用 app_id、app_secret、grant_type=authorization_code 和 login_code 换取 open_id。
  • 该接口直接使用应用密钥验证身份,不需要额外携带应用级 Token。交换成功后,以 app_id + open_id 为外部身份唯一键,不要用手机号或昵称代替。

用 phone_code 换取已加密手机号

  • 应用端在用户明确授权后获得一次性 phone_code,服务端调用 /api/login/v1/developer/get_user_phonenumber:
  • 请求头 x-DB-AccessToken 携带有效的应用级 Token。
  • 请求体携带 phone_code。
  • 返回的 encrypt_phone_number 是密文,业务服务端需使用与平台登记的开发者证书配套的私钥解密。具体加密格式、解密方法和安全要求参见 关于证书

服务端需要实现的能力

模块必须能力建议实现
OAuth 授权服务用户登录与同意、授权 Code 签发、Code 换 Token、Token 刷新符合 RFC 6749;回调白名单;state 校验;Code 一次性消费
账号绑定服务open_id 与业务账号绑定、查询和解绑唯一索引至少包含 app_id 和 open_id;绑定操作幂等
MCP 鉴权中间件校验 X-DB-OPENID、X-DB-ACCESS-TOKEN验证失败统一返回可观测错误;禁止工具层自行跳过鉴权
平台 API Client换取 OpenID、获取应用级 Token、换取已加密手机号超时、有界重试、Token 缓存、log_id 记录、敏感字段脱敏
密钥与证书服务保存 app_secret、开发者私钥和证书密钥托管、最小访问权限、轮换和到期预警;证书默认一年有效时要提前更换
授权状态服务记录用户授权、Scope、失效和撤销状态支持多端复用;用户业务会话与授权 Token 有效期尽量对齐

开发者平台的三个关键 URL

配置项调用方向用途实现要点
FetchTokenURL平台 -> 业务服务端用业务方一次性 Code 换取 MCP 用户 Token直接按协议接收请求;Code 必须短时且一次性
RefreshTokenURL平台 -> 业务服务端用 refresh_token 续期,返回新的 access_token 和 refresh_token刷新 Token 旋转、并发安全,失败时返回可判定的需重新登录状态
DeleteUserInfoURL平台 -> 业务服务端通知删除指定用户隐私数据使用 request_id 幂等,按 fields 处理;该回调是数据删除通知,不等同于自动解除登录态

Token 生命周期策略

  • 用户 Token。 访问 Token 过期前预留少量时钟偏差,尽量由平台使用 refresh_token 静默刷新。如果业务方返回新的 refresh_token,应使用新值原子替换旧值。用户退出、解绑或合规删除时,立即撤销相关 Token。
  • 平台应用级 Token。 按 expires_in 缓存,推荐在剩余 5%~10% 有效期时刷新,并加入小幅随机抖动避免集群同时刷新。当 OpenAPI 明确返回 Token 失效时,只允许强制刷新并重试一次,避免无限重试。
  • 业务会话对齐。 如果用户 Token 比业务会话更长,平台仍可以调用 MCP,但用户进入业务界面后可能需要重建会话;如果用户 Token 更短,用户尚处于业务会话中却可能被要求重新授权。建议在安全策略允许的前提下对齐两者有效期。

推荐实施顺序

  1. 完成平台配置。 准备应用基本信息、服务协议、隐私政策、FetchTokenURL、RefreshTokenURL、DeleteUserInfoURL、回调白名单和 MCP 工具鉴权声明。
  2. 打通账号映射。 先完成 login_code -> open_id -> 业务账号 闭环,并覆盖重试、重放和并发绑定。
  3. 实现 OAuth2.0 服务。 完成授权 Code 签发、Code 换 Token、刷新 Token、Scope 校验、撤销和审计。
  4. 接入 MCP 鉴权中间件。 对所有需登录工具强制执行统一校验,再开放联调。
  5. 完成应用级 OpenAPI Client。 实现 Token 缓存、OpenID 交换、已加密手机号获取和解密。
  6. 完成异常与合规链路。 覆盖 Token 过期、授权撤销、用户拒绝、通用信息删除、证书轮换和审计。