# @tesouro/embedded-components-widget-token 中文文档

规范地址：https://npmcn.com/package/%40tesouro/embedded-components-widget-token/

版本：0\.11\.69
npm 元数据更新时间：2026-11-02T15:59:30.573Z
中文译文更新时间：2026-11-02T16:06:45.320Z
软件包许可：Apache-2\.0

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40tesouro/embedded-components-widget-token
原文对照：https://npmcn.com/package/%40tesouro/embedded-components-widget-token/?lang=original
项目主页：https://github.com/tesourohq/Tesouro.Payments.Frontends/tree/main/packages/embedded-components-widget-token#readme
源码仓库：https://github.com/tesourohq/Tesouro.Payments.Frontends

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：12.5 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-07-24T14:17:10.555Z
- 最新版本发布：2026-11-02T15:59:30.014Z
- 已发布版本数：192（近 12 个月 192 个）

## 中文简介

用于生成Tesouro嵌入组件使用的小部件令牌的服务器端帮助程序。薄荷糖的 [RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693) 令牌交换请求，并将其加密为JWE (`A256KW` + `A256GCM`)使用您共享的小部件秘密。

## 安装

```sh
npm install @tesouro/embedded-components-widget-token
```

也可以使用：`pnpm add @tesouro/embedded-components-widget-token`、`yarn add @tesouro/embedded-components-widget-token`、`bun add @tesouro/embedded-components-widget-token`

## README

# @tesouro / embedded-components-widget-token

用于铸造Tesouro嵌入的小部件令牌的服务器端帮助器 组件。薄荷糖 [RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693) 令牌交换请求，并将其加密为JWE (`A256KW` + `A256GCM`)使用 您共享的小部件的秘密。

> **服务器仅。** 这个包处理你的 `clientSecret` 和 `widgetSecret`， 所以把它放在服务器上，永远不要把它捆绑到客户端代码中。它运行在任何 服务器运行时——一个Next.js路由处理器，一个Express服务器，或者一个Lambda 处理程序。

## 安装

```bash
yarn add @tesouro/embedded-components-widget-token
# or
npm install @tesouro/embedded-components-widget-token
```

## 使用

### 只有一次的

```ts
import { createWidgetToken } from '@tesouro/embedded-components-widget-token';

const { widgetToken, exp } = await createWidgetToken({
  clientId: process.env.TESOURO_CLIENT_ID!,
  clientSecret: process.env.TESOURO_CLIENT_SECRET!,
  widgetSecret: process.env.TESOURO_WIDGET_SECRET!,
  userId: 'user_123',
  userEmail: 'user@example.com',
  organizationReference: 'partner-org-123',
});
```

`exp` 令牌的过期时间是自epoch以来的秒数吗 客户端，以便它可以在到期前刷新。

### 预先配置的工厂

当在多个请求中重用相同的凭据时，将它们绑定一次 `configureCreateWidgetToken`：

```ts
import { configureCreateWidgetToken } from '@tesouro/embedded-components-widget-token';

const mintWidgetToken = configureCreateWidgetToken({
  clientId: process.env.TESOURO_CLIENT_ID!,
  clientSecret: process.env.TESOURO_CLIENT_SECRET!,
  widgetSecret: process.env.TESOURO_WIDGET_SECRET!,
  organizationReference: 'partner-org-123',
});

const { widgetToken, exp } = await mintWidgetToken({
  userId: 'user_123',
  userEmail: 'user@example.com',
});
```

### 在路由处理程序中

从服务器上经过身份验证的路由调用工厂并返回 `{ widgetToken, exp }` 到浏览器。 [开始](https://components.tesouro.com/components/getting-started) 具有完整的Next.js路由处理程序和调用它的提供程序。

> **标识必须来自服务器，而不是调用者。** 解决 `userId`， `userEmail`, `organizationReference` 从您的认证会话中， 从不来自请求正文。 `organizationReference` 将业务命名为 用户属于，所以绑定一次在 `configureCreateWidgetToken` 只有当 该服务器的每个用户都属于同一业务。你的路线薄荷有效 令牌表示它接收到的任何标识，因此信任客户端提供的标识 允许任何呼叫者模拟另一个用户。

## API

### `createWidgetToken(params): Promise<WidgetTokenResult>`

| 参数 | 类型 | 要求 | 描述 |
| --- | --- | --- | --- |
| `clientId` | `string` | 是 | Tesouro发布的客户端标识符。用作JWE `kid` 和作为 `iss`/`client_id` 在载荷中。 |
| `clientSecret` | `string` | 是 | Tesouro发布的客户秘密。携带为 `client_secret` 在加密的有效负载中。 |
| `widgetSecret` | `string` | 是 | 用于加密JWE的共享对称密钥。 |
| `userId` | `string` | 是 | 主题(`sub`) 的内部标识令牌。 |
| `userEmail` | `string` | 是 | 内部标识令牌的电子邮件声明。 |
| `organizationReference` | `string` | 是 | 合作伙伴解决的组织/业务参考。进行, `organization_reference` 在外部加密负载中。解析服务器端，而不是从请求体输入。 |
| `expirationInSeconds` | `number` | 否 | Token TTL，单位为秒。默认为 `DEFAULT_EXPIRATION_IN_SECONDS` (480-8分钟)。 |

返回:

```ts
interface WidgetTokenResult {
  widgetToken: string; // compact-serialized JWE
  exp: number; // expiration in seconds since epoch (UTC)
}
```

如果扔 `clientId`， `clientSecret`， `widgetSecret`，或者 `organizationReference` 缺少或为空。

### `configureCreateWidgetToken(creds)`

结合 `clientId`， `clientSecret`， `widgetSecret`,以及可选的默认值 `organizationReference` 和 `expirationInSeconds`，并返回一个函数 只接受每个请求 `userId` / `userEmail` 加上可选的每次调用覆盖 用于 `organizationReference` 和 `expirationInSeconds`. `organizationReference` 仍然需要：返回的函数抛出，除非它被绑定在这里或 每次通话通过。

### `DEFAULT_EXPIRATION_IN_SECONDS`

`480` -默认令牌生存期 (以秒为单位) (8分钟)。

## 令牌格式

`createWidgetToken` 生成具有以下受保护标头的JWE:

```json
{
  "alg": "A256KW",
  "enc": "A256GCM",
  "kid": "<clientId>",
  "typ": "JWT",
  "cty": "JWT"
}
```

加密的有效负载是RFC 8693令牌交换请求，其 `subject_token` 是无符号标识JWT (`alg: none`)承载用户的 `sub`， `email`， `iss`， `aud`， `iat`, `exp` 索赔。 `organizationReference` 在外部加密有效负载级别生成为 `organization_reference`;它 未添加到内部 `subject_token`.

不运行节点的后端从小部件令牌构建相同的令牌 身份验证中的协议 › 用户令牌，在 [嵌入的银行](https://docs.tesouro.com/embedded-banking/guides/authentication/user-token) 或者 [财务运维](https://docs.tesouro.com/finops/guides/authentication/user-token) 文档。

## 许可证

apache - 2.0

## 常见问题

### @tesouro/embedded-components-widget-token 是什么？

用于生成Tesouro嵌入组件使用的小部件令牌的服务器端帮助程序。薄荷糖的 RFC 8693 令牌交换请求，并将其加密为JWE \(A256KW \+ A256GCM\)使用您共享的小部件秘密。

### 如何安装 @tesouro/embedded-components-widget-token？

在项目目录运行 npm install @tesouro/embedded-components-widget-token，或使用 pnpm add / yarn add / bun add。

### @tesouro/embedded-components-widget-token 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @tesouro/embedded-components-widget-token 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @tesouro/embedded-components-widget-token 可以商用吗？

@tesouro/embedded-components-widget-token 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @tesouro/embedded-components-widget-token 还在维护吗？

最新版本 0\.11\.69 发布于 2026/11/02（今天）；至今共发布 192 个版本，其中过去 12 个月发布了 192 个；首次发布于 2026/07/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。