# @frigear-nu/auth 中文文档

规范地址：https://npmcn.com/package/%40frigear-nu/auth/

版本：0\.6\.0
npm 元数据更新时间：2026-11-12T17:12:23.608Z
中文译文更新时间：2026-11-15T14:18:14.376Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40frigear-nu/auth
原文对照：https://npmcn.com/package/%40frigear-nu/auth/?lang=original
项目主页：https://docs.frigear.dev/modules/identity/auth
源码仓库：https://github.com/Frigear-nu/frigear-nu

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

- 包体积（解压后）：524 kB，270 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：12 个
- peer 依赖：@nuxt/ui ^4\.12\.0，@nuxthub/core ^0\.10\.12，@capacitor/app \>=8\.0\.0，@capacitor/core \>=8\.0\.0，@frigear-nu/menu ^0\.4\.0，@capacitor/browser \>=8\.0\.0，@capacitor/preferences \>=8\.0\.0，@simplewebauthn/server ^13\.3\.2，@simplewebauthn/browser ^13\.0\.0，@frigear-nu/email-templates ^0\.1\.1，@aparajita/capacitor-secure-storage \>=8\.0\.0
- 首次发布：2026-10-14T11:23:42.838Z
- 最新版本发布：2026-11-12T17:12:23.229Z
- 近 30 天下载量：5595（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 24 个）

## 中文简介

Frigear生态系统的认证:服务器端的登录流量(密码,魔法链接,OAuth,密码),用户 API 令牌和有瞄准镜的共享需要 Auth,或用于SPA和Capacitor app的公用 PKCE客户端模式.

## 安装

```sh
npm install @frigear-nu/auth
```

也可以使用：`pnpm add @frigear-nu/auth`、`yarn add @frigear-nu/auth`、`bun add @frigear-nu/auth`

## README

# @frigear-nu/auth (英语)

认证可怕的生态系统. **签名于**: 电子邮件/密码、密码重置、魔法链接、电子邮件 校验,密码和OAuth提供商(包括"Log in with frigear.nu"),带有选择登录/注册页面. **识别呼叫者**页:1 `requireAuth` 对于每个呼叫者可以认证的方式: 饼干会话,静态 **用户 API 令牌** (单位:千美元)`fnu_…` 默认, `authentication.apiTokens.prefix`· ; `apiTokens: false` 关了它 **OAuth 访问符** 对申请发出的通知. **访问控制**页:1 `authorize(event, permission, record?)` 给每个打电话的人 范围狭小,一个标志可以做什么, 而主人公现在的角色依然适用.

```ts
// server/api/tickets.get.ts
const { user } = await authorize(event, 'tickets:read')

// Account-level routes never accept bearer credentials:
const owner = await requireAuth(event, { sessionOnly: true })
```

-   `requireAuth`, (中文(简体) ), `getAuth` 自动输入服务器代码; `@frigear-nu/users` 添加 `requireUser` 编号 : `getUser` 仅供用户使用.
-   模块注册权限 `addPermission`,带有 `addScope`,默认角色 `addRole`, (中文(简体) ), 政策 `addPolicies` 和证书类型 `addAuthResolver` (单位:千美元)`@frigear-nu/auth/utils`) (中文(简体) ). 服务器代码 检查访问权限 `authorize` 编号 : `allows` (自动进口) `definePolicy`和东道主 覆盖在 `authorization:before` 钩.
-   Auth 只能通过一个 `AuthUserStore`,哪个 `@frigear-nu/users` 登记册`setAuthUserStore`(三); `@frigear-nu/oauth-server` 提供访问脚本解析器.
-   签名配置于 `authentication.settings` (单位:千美元)`password`, (中文(简体) ), `magicLink`, (中文(简体) ), `webAuthn`, (中文(简体) ), `oauth`, (中文(简体) ), `pages`(中文(简体) ).
-   任何nuxt-auth-utils OAuth 供应商 (Auth0, Okta, Keycloak, `oidc`,...) 在 `/api/auth/<provider>` 一次 `NUXT_OAUTH_<PROVIDER>_*` (一) 证书的设定; `settings.oauth.<provider>` 只覆盖其标签、图标和注册.
-   配置密钥是 `authentication` (单位:千美元)`auth` 属于 nuxt-auth-utils).
-   与客户端模式相同的客户端 API : `useUserSession()`, (中文(简体) ), `useAuth()` (单位:千美元)`login` 登录页面 `?redirect=`, (中文(简体) ), `logout` 结束届会)和 `$api` 编号 : `useApi()`。 。 。 . `$api` 发送呼叫者的证书( 来信 Cookie 和授权信头在服务器渲染过程中) 仅针对此应用程序自己的路径和来源, 绝不针对另一个 URL 或外国 `baseURL`。来自此应用程序的401在清除会话并进入登录页面时签名。 一个 应用不能提供自己的 `$api`。 。 。 .

## 客户端模式

`authentication.mode: 'client'` 将 Auth 变成 SPA 的公共 OAuth 2.1 / OpenID 连接客户端 (PKCE) 和 在发行商签名的电容app:没有服务器,没有数据库,没有 nuxt-auth-utils,以及 `ssr: false`设置模式 在应用程序自己的配置.

```ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui', '@frigear-nu/auth'],
  authentication: {
    mode: 'client',
    // Issuer and API also from NUXT_PUBLIC_AUTHENTICATION_CLIENT_ISSUER / _API_BASE.
    client: { issuer: 'https://frigear.nu', clientId: 'my-app', scopes: ['openid', 'profile', 'offline_access'] },
  },
})
```

-   `useUserSession()` 服务器模式( i)`loggedIn`, (中文(简体) ), `user`,与 `user.id` 发行人 `sub`),加 (中文(简体) ) `useAuth()` (单位:千美元)`login`, (中文(简体) ), `completeLogin`, (中文(简体) ), `logout`, (中文(简体) ), `getAccessToken`, (中文(简体) ), `signingIn`,(......)和 `$api` 编号 : `useApi()`,发送 无记名标记 `client.apiBase` 财务报告和审定财务报表 `client.apiOrigins` 只有这个.
-   `scopes` 必须包含 `openid`:用户出自id token,一个没有失败的签入.
-   用户是 `{ id: sub, sub, name, email, avatar }` (不从符号读取: `@frigear-nu/authorization`, (中文(简体) ), `useAuthorization()` 问发行人 `/api/auth/me/access` 与无记名标志,或 掉回进入符号 `permissions` c. 索赔. `client.userinfo: true` 合并 `/userinfo`· ; `client.mapUser: './app/auth/map-user'` 自己地图`({ claims, userinfo, api }) => user`,可能为Aync. 直至 一个同步映射完成, 当它断线时, `user` 是索赔映射.
-   登录和回调页面(与 `@nuxt/ui`时 `settings.pages.login` 财务报告和审定财务报表 `client.callbackPath`; 品牌通过 `app.config.ts` → `authentication.login`。 。 。 .
-   警卫属于 `@frigear-nu/authorization` 并且只是UX:由API决定. 钩子: `auth:signed-in`, (中文(简体) ), `auth:signed-out`, (中文(简体) ), `auth:refresh-failed`, (中文(简体) ), `auth:user-failed`。 。 。 .
-   框架不可知的核心是: `@frigear-nu/auth/client-core`,电容适配器 `@frigear-nu/auth/capacitor`, (中文(简体) ), 类型 `@frigear-nu/auth/client-types`· ; `@frigear-nu/auth/mode` 已经 `resolveAuthMode` 财务报告和审定财务报表 `isSafeRedirect` 页:1 其他模块.

见 [文档](https://npmcn.com/package/apps/docs/content/3.modules/1.identity/1.auth/index.md) 用于完整的模型、安全属性和符号 API.

## 发展

```bash
pnpm --filter '@frigear-nu/auth' test
```

E2e套间使用 `test/fixtures/auth-db`他们的移民是承诺的。 改变计划后,把它重新生成 模块- kit 文档中描述。 客户端模式的定着是 `test/fixtures/client-*`· ; `--project unit` 运行 单是单位测试.

## 常见问题

### @frigear-nu/auth 是什么？

Frigear生态系统的认证:服务器端的登录流量\(密码,魔法链接,OAuth,密码\),用户 API 令牌和有瞄准镜的共享需要 Auth,或用于SPA和Capacitor app的公用 PKCE客户端模式\.

### 如何安装 @frigear-nu/auth？

在项目目录运行 npm install @frigear-nu/auth，或使用 pnpm add / yarn add / bun add。

### @frigear-nu/auth 支持 TypeScript 吗？

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

### @frigear-nu/auth 支持 ESM 还是 CommonJS？

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

### @frigear-nu/auth 可以商用吗？

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

### @frigear-nu/auth 的下载量有多少？

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

### @frigear-nu/auth 还在维护吗？

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