# @crvouga/mockingbird-service-cognito 中文文档

规范地址：https://npmcn.com/package/%40crvouga/mockingbird-service-cognito/

版本：3\.11\.0
npm 元数据更新时间：2026-11-11T02:04:10.082Z
中文译文更新时间：2026-11-11T02:37:00.738Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40crvouga/mockingbird-service-cognito
原文对照：https://npmcn.com/package/%40crvouga/mockingbird-service-cognito/?lang=original
项目主页：https://github.com/crvouga/mockingbird/tree/main/packages/service/cognito#readme
源码仓库：https://github.com/crvouga/mockingbird

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

- 包体积（解压后）：4.3 MB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-09-22T23:53:04.889Z
- 最新版本发布：2026-11-11T02:04:09.715Z
- 近 30 天下载量：15733（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：43（近 12 个月 43 个）

## 中文简介

用于 AWS SDK 和浏览器认证测试的 Stateful Amazon Cognitto User Pools 模拟器.

## 安装

```sh
npm install @crvouga/mockingbird-service-cognito
```

也可以使用：`pnpm add @crvouga/mockingbird-service-cognito`、`yarn add @crvouga/mockingbird-service-cognito`、`bun add @crvouga/mockingbird-service-cognito`

## README

# @crvouga/mockingbird-service-cognitto (中文(简体) )

> 本地模拟器。 真正的API合同. 部分 [嘲笑鸟](https://github.com/crvouga/mockingbird)。 。 。 .

AWS SDK 亚马逊通用用户池的国有本地模拟器 `amazon-cognito-identity-js`它执行认证、用户管理、团体、联邦、恢复、JWT、发现、以及JWKS在不与AWS联系的情况下对消费者应用软件进行表面检测.

## 安装

```bash
npm install -D @crvouga/mockingbird-service-cognito
```

仅限无害环境管理。 节点22+或Bun 1.2+.

## 使用量

点 `COGNITO_ENDPOINT` 或 AWS SDK 软件 `endpoint` 选项。 Fixture SigV4证书被接受用于行政管理业务. 公共用户集操作在没有IAM认证的情况下工作,匹配了Cognitto的客户端-造型API.

```ts
import {
  CognitoIdentityProviderClient,
  InitiateAuthCommand,
} from "@aws-sdk/client-cognito-identity-provider"
import { createServer } from "@crvouga/mockingbird-service-cognito/server"

// Test setup: seed the emulator and point the AWS SDK client your application uses at it.
const emulator = await createServer({
  poolId: "us-east-1_mockingbird",
  clientId: "mockingbird-client",
  users: [
    {
      username: "ada@example.test",
      password: "Password1",
      confirmed: true,
      attributes: [{ Name: "email", Value: "ada@example.test" }],
    },
  ],
})
const cognito = new CognitoIdentityProviderClient({
  endpoint: emulator.url,
  region: "us-east-1",
  credentials: { accessKeyId: "fixture", secretAccessKey: "fixture" },
})

// Application code: ordinary SDK calls.
const { AuthenticationResult } = await cognito.send(
  new InitiateAuthCommand({
    AuthFlow: "USER_PASSWORD_AUTH",
    ClientId: "mockingbird-client",
    AuthParameters: { USERNAME: "ada@example.test", PASSWORD: "Password1" },
  }),
)
// AuthenticationResult: { AccessToken, IdToken, RefreshToken, ExpiresIn, TokenType }

await emulator.close() // after the test
```

`createServer()` 从 `./server` 是节点适配器; `createRuntime()` 使用相同的选项。 CLI是: 校对: `npx mockingbird-cognito serve --port 8811 --pool-id us-east-1_mockingbird --client-id mockingbird-client`。 。 。 .

### AWS JSON业务

`POST /` 发送日期: `X-Amz-Target` 并支持签名、 确认签名、 重发确认代码、 启动 Auth( S)`USER_PASSWORD_AUTH`, (中文(简体) ), `REFRESH_TOKEN_AUTH`),"被遗忘","被遗忘","被遗忘","被遗忘","被改变","被使用者","被删除","被管理者","被管理者","被管理者","被管理者","被管理者","被管理者","被管理者","被管理者","被管理者","被管理者","被管理者","被管理者"等.

答复中包含SDK消耗的Cognitto字段和AWS形状的例外(`__type`, (中文(简体) ), `message`,HTTP状态, `x-amzn-requestid`) (中文(简体) ). 托肯斯是RS256 JWT 与 Cognito 发行者,主题, `token_use`时间戳和团体。 标识符加了 `aud`, (中文(简体) ), `cognito:username`,电子邮件和链接身份;访问符添加 `client_id`, (中文(简体) ), `username` 财务报告和审定财务报表 `scope`,没有用户属性,如Cognitto。 发现和JWKS在 `/<poolId>/.well-known/openid-configuration` 财务报告和审定财务报表 `/<poolId>/.well-known/jwks.json`。 。 。 .

### 管理和确定性控制

-   `GET/POST /__admin/users` 列出编辑过的用户或种子 1。 密码和信使从不归还.
-   `GET /__admin/codes?username=…` 返回本地确认/重置代码而不发送邮件.
-   `POST /__admin/sessions/revoke {"username":"…"}` 取消访问并刷新会话.
-   `POST /__admin/keys/rotate {"retainPrevious":true}` 旋转签名密钥,最多保留两个前键。 和Cognitto一样,ID和访问令牌用不同的密钥签名,所以JWKS列出每代每类一个密钥,并旋转来取代两者(响应命名它们) `kid` 财务报告和审定财务报表 `accessKid`) (中文(简体) ). 每个新密钥都收到新的随机 UUID `kid`,独立于虚拟时钟。 重置启动新密钥环 .
-   错误预设 : `throttled`, (中文(简体) ), `unavailable`。 。 。 .

共享运行时供给重设,时钟,快照,日记,度量衡,断层,分支,和名空间隔离. 通过选择命名空间 `x-mockingbird-namespace`, (中文(简体) ), `/__admin/ns/<name>`,或SigV4存取键映射.

### 车队固定装置和公共身份端点

使用 `fixtures: { users: [...] }` 在车队服务条目中,或 `options: { fixtures: "./synthetic-users.json" }` 用于包含同一对象的清晰 JSON 文件。 独立的CLI接受 `--fixtures ./synthetic-users.json`。每个用户需要 `username` 财务报告和审定财务报表 `password`; 可选 `sub`, (中文(简体) ), `confirmed`, (中文(简体) ), `enabled`, (中文(简体) ), `status`, (中文(简体) ), `createdAt`,属性,组,关联身份和检查代码相匹配的在进程种子字段. 无效的字段, 重复的用户名/ 主题/ 电子邮件别名和相冲突的身份在准备前与字段路径失败 。 诊断省略了数值。 Fixture身份对象接受Cognito身份要求字段和被支持的提供方-链接字段,而不是任意嵌入对象.

Fixtures构成每个独立命名空间的重置基线. 导入快照替换已保存状态, 包括已删除的固定用户, 而无需重播 。 合成密码保存在私人状态/档案中;用户管理员回复编辑密码,会话数据和检查码. 代码仅存于 `/__admin/codes`。 。 。 .

| 表面 | 公共来源和路径前缀 | 命名空间隔离 |
| --- | --- | --- |
| 未签名 `InitiateAuth` / 用户集 JSON 操作 | 支助 | 标题和路径载体 |
| RS256 发行、发现和JWKS | 得到支助; `publicOrigin` + 键 `publicPath` 配置权威基础 | 广告 URL 包含选定的命名空间, 包括标题选中的请求 |
| SigV4 签名的 AWS 管理员操作 | 仅直接私人收听者; 通过代理签名验证未验证 | 固定签名仍然是当地测试合同 |
| 鸟类管理员控制/ 私人签名材料 | 仅限私人听众 | 从未被引用的公众入侵中 |
| 托管授权/用户界面 | 未执行 | 发现元数据并不意味着托管 OAuth 流量支持 |

进程内呼叫器可以设置 `baseUrl`,而CLI接受 `--base-url`。固定配置决定了已公布的身份 URL;主机和转发信头永远不会覆盖它。 没有明确的配置,直接请求/挂载的URL会提供来源. 在稳定的公用端点后取而代之的是车队,即使在私人收听器端口改变时仍保留发行者.

现有和保留的合成签名密钥在命名空间存储中进行直播,因此命名空间快照,全放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放放 随后自转读取还原的环. 在签署-状态持久性之前创建的档案没有可收回的私人密钥;它们加载了新的环并需要重新校正. 将便携式档案作为私人合成证书加以保护;诊断和用户控制反应从来不包括关键材料.

### 故意不模拟

文件分集以外的业务、生产配额、电子邮件/短信发送、外交部、Lambda触发器、设备跟踪、认知识别池、AWS计费、仪表板和外出供应商呼叫都未执行。 托管的UI联合会在关联身份申述中被代表;这种WIP级不使Cognitto的主机登录页面.

## API 密码

-   `CognitoAPI`, (中文(简体) ), `CognitoAPIOptions`AWS JSON 处理器和选项.
-   `createRuntime`, (中文(简体) ), `CognitoRuntime`, (中文(简体) ), `CognitoRuntimeOptions`:满口口口鸟服务运行时间.
-   `COGNITO_NAMESPACE`, (中文(简体) ), `COGNITO_PRESETS`, (中文(简体) ), `accessKeyCredential`:服务常数和控制.
-   `CognitoAttribute`, (中文(简体) ), `CognitoSeedUser`, (中文(简体) ), `CognitoUser`, (中文(简体) ), `CognitoFixtures`: 状态和固定类型.
-   `document`, (中文(简体) ), `operationIds`, (中文(简体) ), `supportedOperationIds`: 生成了 OpenAPI 元数据.
-   `createServer`, (中文(简体) ), `CognitoServerOptions`, (中文(简体) ), `DEFAULT_PORT`, (中文(简体) ), `serveTarget` 从 `./server`:节点HTTP适配器和CLI集成.

官方预言: [Amazon Cognitto 用户池 API 参考文献](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/Welcome.html) 财务报告和审定财务报表 [身份标识索赔](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-id-token.html)。 。 。 .

## 常见问题

### @crvouga/mockingbird-service-cognito 是什么？

用于 AWS SDK 和浏览器认证测试的 Stateful Amazon Cognitto User Pools 模拟器\.

### 如何安装 @crvouga/mockingbird-service-cognito？

在项目目录运行 npm install @crvouga/mockingbird-service-cognito，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mockingbird-cognito，可以用 npx mockingbird-cognito 直接运行。

### @crvouga/mockingbird-service-cognito 支持 TypeScript 吗？

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

### @crvouga/mockingbird-service-cognito 支持 ESM 还是 CommonJS？

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

### @crvouga/mockingbird-service-cognito 可以商用吗？

@crvouga/mockingbird-service-cognito 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @crvouga/mockingbird-service-cognito 的下载量有多少？

根据 npm 官方下载统计，@crvouga/mockingbird-service-cognito 在 2026/10/11 – 2026/11/09 这 30 天内被下载 15,733 次，日均约 524 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @crvouga/mockingbird-service-cognito 还在维护吗？

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