# @haatlabs-core/nest-auth 中文文档

规范地址：https://npmcn.com/package/%40haatlabs-core/nest-auth/

版本：0\.18\.5
npm 元数据更新时间：2026-11-13T18:15:52.946Z
中文译文更新时间：2026-11-17T08:07:43.707Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40haatlabs-core/nest-auth
原文对照：https://npmcn.com/package/%40haatlabs-core/nest-auth/?lang=original
项目主页：https://haatlabs.shop/docs/packages/nest-auth/
源码仓库：https://github.com/Haatlabs/haatlabs-platform

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

- 包体积（解压后）：2.1 MB，220 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：10 个
- peer 依赖：zod ^4\.6\.5，rxjs ^7\.8\.2，argon2 ^0\.45\.1，fastify ^5\.12\.5，ioredis ^6\.0\.0，drizzle-orm ^0\.45\.3，@nestjs/core ^12\.1\.2，@nestjs/common ^12\.1\.2，@fastify/cookie ^11\.1\.2，reflect-metadata ^0\.2\.2，@nestjs/platform-fastify ^12\.1\.2
- 首次发布：2026-10-22T23:23:19.607Z
- 最新版本发布：2026-11-13T18:15:52.550Z
- 近 30 天下载量：5001（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 27 个）

## 中文简介

NestJS通过电子邮件的代码,会话,API密钥,角色和每条路线经过的守门员签名.

## 安装

```sh
npm install @haatlabs-core/nest-auth
```

也可以使用：`pnpm add @haatlabs-core/nest-auth`、`yarn add @haatlabs-core/nest-auth`、`bun add @haatlabs-core/nest-auth`

## README

# @haatlabs-core/nest-auth (英语)

签名到应用程序的 API: 电子邮件编码、 会话、 API 密钥和守护每一个路由 通过。 由应用配置;每个名字都出自应用的名称.

```
AuthModule.forRoot({
  appName: 'shop',                 // cookies shop_session / shop_csrf, keys shop_…, Redis shop:…
  displayName: 'Shop',             // email copy
  wholeOrganizationMessage: 'Lists are in the Shop dashboard: sign in there to use them',
  stores: {
    identity: { useFactory: (db) => new IdentityRepository(db.db, tables), inject: [SYSTEM_DB] },
    apiKeys: { useFactory: (sys, app) => new ApiKeyRepository(sys.db, app.db, tables), inject: [SYSTEM_DB, APP_DB] },
  },
  apiKeyAdmission: { useFactory: (features) => apiFeatureGate(features), inject: [FeatureRepository] }, // or 'allow'
  bearer: { useFactory: (embedded) => embedded, inject: [EmbeddedAuthService] },  // Shopify session tokens
  meExtras: { useFactory: (features) => meFeatures(features), inject: [FeatureRepository] },
});
```

-   **警卫** 默认否认: 除非 `@Public()`,每个 撰写需要成员,除非 `@MinRole(...)` 说不说,饼干写 需要CSRF 符号,每个请求都会再次读取角色,被拒绝的无记名符号永远不会掉落 回到饼干. `@StandaloneOnly()` 拒绝嵌入式应用程序; `@WholeOrganization()` 拒绝 **只存储** 校长(向某组织的商店工作人员提供 仪表板 应用软件 `wholeOrganizationMessage` 或路径本身的单词 (单位:千美元)`@WholeOrganization('...')`),并提前 `@StandaloneOnly()`拒绝.
-   **API 密钥** 根据应用程序的模式(从其逃出前缀所建)进行核对,以及, 除非 `'allow'`,反对 `apiKeyAdmission` 创造和各种用途.
-   **签名代码** 工作一次,10分钟,为电子邮件和目的发送 5个错误的猜测之后,他们就消失了。 带有固定代码( :`SIGN_IN_FIXED_CODE`页:1 邮件故障仍然在登录中 .
-   `EmailSignInController` (仅与 `bearer`从Shopify安装的商店 有一封邮件要签一次.
-   `@haatlabs-core/nest-auth/password`: 管理员密码的 argon2id(`argon2` 是一个 可选对等点).

需要应用程序的全球提供商来提供巢- 常见的 `CONFIG`, (中文(简体) ), `LOGGER`, (中文(简体) ), `REDIS`, (中文(简体) ), `RATE_LIMITER` (建造与 `keyPrefix: '<appName>:'`和 `MAILER`。 。 。 .

## 安装

```
pnpm add @haatlabs-core/nest-auth
```

这些软件包留给你的应用程序,所以应用程序持有一份: `@fastify/cookie`, (中文(简体) ), `@nestjs/common`, (中文(简体) ), `@nestjs/core`, (中文(简体) ), `@nestjs/platform-fastify`, (中文(简体) ), `drizzle-orm`, (中文(简体) ), `fastify`, (中文(简体) ), `ioredis`, (中文(简体) ), `reflect-metadata`, (中文(简体) ), `rxjs`, (中文(简体) ), `zod`, (中文(简体) ), `argon2`。 。 。 .

## `@haatlabs-core/nest-auth/admin`

平台管理员的登录,除了商家:自己的饼干(`<appName>_admin`, (中文(简体) ), `SameSite=Strict`,发送给 `/api/v1/admin` 仅限其一生)、届会和 警卫. `AdminAuthModule.forRoot({ appName, store })` 给 `POST /api/v1/admin/login`, (中文(简体) ), `POST /api/v1/admin/logout` 财务报告和审定财务报表 `GET /api/v1/admin/me`; 应用程序自己的管理员 路线使用 `@Public() @UseGuards(AdminGuard)` 财务报告和审定财务报表 `@CurrentAdmin()`。当 账户的密码或访问权限更改(`platform_admins.updated_at`),两个闲后 12小时,或者总共12小时;在别处签字,就别管了. `runAdminUserCommand(store, argv, { hashPassword })` 是运算符的 `admin-user` 命令. 它需要可选的对等点 `argon2`: 装入 `/admin` 使用一个假密码, 这样一个 未知地址需要像错误的密码一样长时间拒绝。 A 类 `cookiePath` 它必须 覆盖 `/api/v1/admin`,或 `forRoot` 拒绝.

## `@haatlabs-core/nest-auth/shopify`

通过 Shopify 的 OAuth 连接商店,以及嵌入式应用程序的登录.

```
ShopifyAuthModule.forRoot({
  appName: 'shop',
  stores: { useFactory: (repo) => repo, inject: [SystemStoreRepository] },  // ShopifyStores
  canConnect: { useFactory: (limits) => limits, inject: [StoreLimits] },   // or 'allow'
  afterInstall: { useFactory: (hooks) => (shop, token) => hooks.subscribe(shop, token), inject: [WebhookSubscriptions] },
});
AuthModule.forRoot({ ..., bearer: { useFactory: (e) => e, inject: [EmbeddedAuthService] } });
```

-   `GET /api/v1/auth/shopify/install` 财务报告和审定财务报表 `/callback`: 状态与浏览器绑定 页:1 `<appName>_oauth` 饼干 检查回音的签名 还有仪表盘 连接由启动的管理员完成,并有商店的空间 (单位:千美元)`canConnect`在两端。 拒绝是一页(`CONNECT_PROBLEM_PAGE`) (中文(简体) ).
-   `EmbeddedAuthService` 验证会话符号, 安装商店打开应用程序 第一次,替换一个需要它的迹象, 给工作人员在仪表板上的商店 组织只存储的校长.
-   没有Shopify配置,或者没有 `TOKEN_CIPHER`,路径回答 404 和会话 401号.

## 常见问题

### @haatlabs-core/nest-auth 是什么？

NestJS通过电子邮件的代码,会话,API密钥,角色和每条路线经过的守门员签名\.

### 如何安装 @haatlabs-core/nest-auth？

在项目目录运行 npm install @haatlabs-core/nest-auth，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^4\.6\.5）、rxjs（^7\.8\.2）、fastify（^5\.12\.5）、ioredis（^6\.0\.0）、drizzle-orm（^0\.45\.3）、@nestjs/core（^12\.1\.2）、@nestjs/common（^12\.1\.2）、@fastify/cookie（^11\.1\.2）、reflect-metadata（^0\.2\.2）、@nestjs/platform-fastify（^12\.1\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @haatlabs-core/nest-auth 支持 TypeScript 吗？

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

### @haatlabs-core/nest-auth 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @haatlabs-core/nest-auth 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @haatlabs-core/nest-auth 可以商用吗？

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

### @haatlabs-core/nest-auth 的下载量有多少？

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

### @haatlabs-core/nest-auth 还在维护吗？

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

