# @frontmcp/auth 中文文档

规范地址：https://npmcn.com/package/%40frontmcp/auth/

版本：1\.12\.2
npm 元数据更新时间：2026-11-14T21:11:03.823Z
中文译文更新时间：2026-11-15T15:10:41.427Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40frontmcp/auth
原文对照：https://npmcn.com/package/%40frontmcp/auth/?lang=original
项目主页：https://frontmcp.dev/reference/auth
源码仓库：https://github.com/agentfront/frontmcp

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

- 包体积（解压后）：2.2 MB，422 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：3 个
- peer 依赖：ioredis ^5\.0\.0，@vercel/kv ^3\.0\.0，@frontmcp/lazy-zod 1\.12\.2，@frontmcp/storage-sqlite 1\.12\.2
- 首次发布：2026-01-26T10:57:08.220Z
- 最新版本发布：2026-11-14T21:11:03.430Z
- 近 30 天下载量：13013（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：109（近 12 个月 109 个）

## 中文简介

FrontMCP服务器的认证和授权:认证模式、OAuth 2.1(本地和远程)、JWT和会话检查、权限和证书金库

## 安装

```sh
npm install @frontmcp/auth
```

也可以使用：`pnpm add @frontmcp/auth`、`yarn add @frontmcp/auth`、`bun add @frontmcp/auth`

## README

# @ frontmcp/ auth (中文(简体) )

FrontMCP服务器的认证和授权:五台 `auth` 模式, OAuth 2.1 以 FrontMCP 作为它自己的授权服务器或者在您的身份提供者JSON Web Token(JWT)和会话检查,工具访问规则,以及内置的签名页面前登录. `@frontmcp/sdk` 取决于此软件包, 因此一个 FrontMCP 服务器已经拥有它, 您通过配置它 `@FrontMcp({ auth })`自己安装它只是为了导入 SDK 不再出口的东西 比如 `escapeHtml` 用于自定义签名页面或 `AuthorityDeniedError`。 。 。 .

[![npm](https://img.shields.io/npm/v/@frontmcp/auth.svg)](https://www.npmjs.com/package/@frontmcp/auth) [![License](https://img.shields.io/npm/l/@frontmcp/auth.svg)](https://github.com/agentfront/frontmcp/blob/main/LICENSE)

## 安装

FrontMCP服务器不需要这个步骤: `@frontmcp/sdk` 安装 `@frontmcp/auth`。直接从中导入:

```bash
npm install @frontmcp/auth
```

使用同样的版本 `@frontmcp/sdk`它需要节点24或以后.

| 同伴依赖关系 | 需求 | 是为了什么 |
| --- | --- | --- |
| `@frontmcp/lazy-zod` | 对 | 选择计划. `@frontmcp/sdk` 已经带来了,它需要 `zod` 4.四. |
| `ioredis` | 没有 | 重新支持的商店 : `tokenStorage: { redis }` 内 `local` 财务报告和审定财务报表 `remote` 模式, `RedisSessionStore`还有其他. |
| `@vercel/kv` | 没有 | `VercelKvSessionStore`。 。 。 . |
| `@frontmcp/storage-sqlite` | 没有 | `tokenStorage: { sqlite }`。 。 。 . |

## 使用量

设定 `auth` 打开 `@FrontMcp`;其方案来自这个包. 在此用户在您的身份提供者签名, FrontMCP 发布 MCP 客户端发送的符:

```ts
import { FrontMcp } from '@frontmcp/sdk';

import { DeskApp } from './desk.app';

@FrontMcp({
  info: { name: 'desk', version: '1.0.0' },
  apps: [DeskApp],
  auth: {
    mode: 'remote',
    provider: 'https://idp.example.com',
    clientId: 'desk-mcp',
    clientSecret: process.env.IDP_CLIENT_SECRET,
    scopes: ['openid', 'profile', 'email'],
  },
})
export default class Server {}
```

在生产中 `JWT_SECRET`:FrontMCP用它来标出其标志. [远程代理](https://frontmcp.dev/reference/auth/remote) 列出每个选项,并列出要在您的提供者注册的回调 URL. `mode` 这是:

| `mode` | 谁进来 |
| --- | --- |
| `'public'` | 诸人. 默认. |
| `'static'` | 请求发送你的钥匙. |
| `'transparent'` | 由您的身份提供者签署有效的JWT申请. |
| `'local'` | 在FrontMCP自己的页面上签名的用户. |
| `'remote'` | 用户通过FrontMCP在您的身份提供者注册. |

### 直接从软件包导入

单位 `local` 模式, `login.render` 替换登录页面。 FrontMCP不会逃避你打印的东西, 所以传递每一个值通过 `escapeHtml`数字 :

```ts
import { escapeHtml } from '@frontmcp/auth';
import { FrontMcp } from '@frontmcp/sdk';

import { DeskApp } from './desk.app';

@FrontMcp({
  info: { name: 'desk', version: '1.0.0' },
  apps: [DeskApp],
  auth: {
    mode: 'local',
    login: {
      fields: { deskKey: { type: 'password', label: 'Desk key', required: true } },
      render: (ctx) => `<!doctype html>
<html lang="en">
  <body>
    <p>${escapeHtml(ctx.clientName)} wants to connect to your desk.</p>
    ${ctx.error ? `<p role="alert">${escapeHtml(ctx.error)}</p>` : ''}
    <form method="POST" action="${escapeHtml(ctx.callbackPath)}">
      <input type="hidden" name="pending_auth_id" value="${escapeHtml(ctx.pendingAuthId)}">
      <label>Desk key <input type="password" name="deskKey" required></label>
      <button>Sign in</button>
    </form>
  </body>
</html>`,
    },
    authenticate: async ({ fields }) =>
      fields.deskKey === process.env.DESK_KEY
        ? { ok: true, sub: 'operator' }
        : { ok: false, message: 'Unknown desk key' },
  },
})
export default class Server {}
```

## 里面有什么东西

-   **Auth 模式**数字 : `authOptionsSchema` 和每个模式的选项类型。 见 [Auth 模式](https://frontmcp.dev/reference/auth/modes)。 。 。 .
-   **本地模式**:FrontMCP作为OAuth 2.1授权服务器,拥有PKCE(代码交换的Proof密钥),动态客户端注册和刷新令牌. 见 [本地认证](https://frontmcp.dev/reference/auth/local)。 。 。 .
-   **远程模式**: 用户在您的身份提供者签名, FrontMCP 发布符. 见 [远程代理](https://frontmcp.dev/reference/auth/remote)。 。 。 .
-   **上游供应商**: 几个 OAuth 供应商在一个登录、一个拾取页面或每个页面一个供应商中链接(`incrementalAuth.showAllAppsAtOnce: false`, (中文(简体) ), `buildFederatedStepPage`) (中文(简体) ). 见 [上游供应商](https://frontmcp.dev/reference/auth/upstream-providers)。 。 。 .
-   **打开检查**:JWT对照JSON网络密钥集(JWKS)进行核查,并检查受众和范围(`JwksService`, (中文(简体) ), `validateAudience`) (中文(简体) ). 见 [接头和会议](https://frontmcp.dev/reference/auth/tokens)。 。 。 .
-   **CIMD( 身份识别元数据文档)**客户: `client_id` 是元数据文档的 URL(`CimdService`) (中文(简体) ). 公开客户端声明 `token_endpoint_auth_method: 'none'`; 机密声明 `private_key_jwt` 并用客户端的密钥签名的客户端认证 `jwks` 编号 : `jwks_uri` (RFC 7523, `CimdService.verifyClientAssertion`) (中文(简体) ). 见 [客户身份元数据](https://frontmcp.dev/reference/auth/cimd)。 。 。 .
-   **当局**:关于工具,资源,提示,技巧和代理的规则,从角色,权限,符号要求,调用参数或你自己的代码(`AuthorityDeniedError`) (中文(简体) ). 见 [当局](https://frontmcp.dev/reference/auth/authorities)。 。 。 .
-   **证书金库**: 工具读取的每个用户证书 `this.credentials`,用户可以添加到会中。 见 [渐进认证](https://frontmcp.dev/reference/auth/progressive)。 。 。 .
-   **登录页面**:内置的签名、同意和出错页,以及 `escapeHtml`, (中文(简体) ), `buildLoginPage` 财务报告和审定财务报表 `baseLayout` 为了你自己 见 [自定义登录 UI](https://frontmcp.dev/reference/auth/login-ui)。 。 。 .
-   **存储**:内存,Redis,Vercel KV和SQLite商店用于会话,授权代码和令牌,并加密了秘密存储(`EncryptedTypedStorage`, (中文(简体) ), `TokenVault`) (中文(简体) ). 见 [本地认证存储](https://frontmcp.dev/reference/auth/local#storage)。 。 。 .

## 文档

-   [认证和授权](https://frontmcp.dev/reference/auth):概述,以及哪一页涵盖哪些任务
-   [生产代理](https://frontmcp.dev/reference/auth/production): 秘密、 HTTPS、 象征性支票和若干实例
-   [`this.auth`](https://frontmcp.dev/reference/sdk/auth):从工具内部呼叫谁
-   [认证客户端](https://frontmcp.dev/learn/authenticating-clients) 财务报告和审定财务报表 [授权通话](https://frontmcp.dev/learn/authorizing-calls):分步骤指南
-   [测试认证](https://frontmcp.dev/reference/testing/auth)

## 相关软件包

-   [`@frontmcp/sdk`](https://www.npmjs.com/package/@frontmcp/sdk): 框架。 它运行此包并再导出其选项类型 .
-   [`@frontmcp/utils`](https://www.npmjs.com/package/@frontmcp/utils):密码(PKCE,加密,密钥衍生)和存储适配器 此软件包所基于的.
-   [`@frontmcp/ui`](https://www.npmjs.com/package/@frontmcp/ui)数字 : `@frontmcp/ui/auth`,用于设定的对应签名页面 `auth.ui`。 。 。 .
-   [`@frontmcp/testing`](https://www.npmjs.com/package/@frontmcp/testing):指使工厂和模拟OAuth服务器进行测试.

## 捐款

资料来源: [`libs/auth`](https://github.com/agentfront/frontmcp/tree/main/libs/auth)欢迎提出问题和拉动请求;见 [捐款额](https://github.com/agentfront/frontmcp/blob/main/CONTRIBUTING.md)。 。 。 .

## 许可证

阿帕奇2.0 (英语). 见 [自由主义](https://github.com/agentfront/frontmcp/blob/main/LICENSE)。 。 。 .

## 常见问题

### @frontmcp/auth 是什么？

FrontMCP服务器的认证和授权:认证模式、OAuth 2\.1\(本地和远程\)、JWT和会话检查、权限和证书金库

### 如何安装 @frontmcp/auth？

在项目目录运行 npm install @frontmcp/auth，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@frontmcp/lazy-zod（1\.12\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @frontmcp/auth 支持 TypeScript 吗？

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

### @frontmcp/auth 支持 ESM 还是 CommonJS？

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

### @frontmcp/auth 需要什么版本的 Node\.js？

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

### @frontmcp/auth 可以商用吗？

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

### @frontmcp/auth 的下载量有多少？

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

### @frontmcp/auth 还在维护吗？

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