# @dbx-tools/auth-gate 中文文档

规范地址：https://npmcn.com/package/%40dbx-tools/auth-gate/

版本：0\.9\.206
npm 元数据更新时间：2026-11-10T19:19:45.801Z
中文译文更新时间：2026-11-11T17:52:15.879Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40dbx-tools/auth-gate
原文对照：https://npmcn.com/package/%40dbx-tools/auth-gate/?lang=original
项目主页：https://github.com/reggie-db/dbx-tools#readme
源码仓库：https://github.com/reggie-db/dbx-tools

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

- 包体积（解压后）：104 kB，13 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：8 个
- 首次发布：2026-09-05T13:39:47.704Z
- 最新版本发布：2026-11-10T19:19:45.429Z
- 近 30 天下载量：7926（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：170（近 12 个月 170 个）

## 中文简介

在Better Auth、电子邮件 OTP和密码上创建的无密码认证运行时间

## 安装

```sh
npm install @dbx-tools/auth-gate
```

也可以使用：`pnpm add @dbx-tools/auth-gate`、`yarn add @dbx-tools/auth-gate`、`bun add @dbx-tools/auth-gate`

## README

# @dbx-工具/自动门

用更好的 Auth 创建平台中立的无密码运行时间, 电子邮件 一次性密码、密码、呼叫人提供的身份政策以及持续性 存储.

对于公共地道后面的 Databricks App, 请使用高级 `authGate()` 插件从 `@dbx-tools/tunnel`数字 :

```ts
import { server } from "@databricks/appkit";
import { appkit } from "@dbx-tools/appkit";
import { email } from "@dbx-tools/email";
import { authGate, tunnelInterceptor } from "@dbx-tools/tunnel";

await appkit.createApp({
  plugins: [server(), email(), authGate({ allow: ["example.com"] })],
  interceptor: tunnelInterceptor(),
});
```

此构成门只请求配置的公共隧道主机 . Databricks Apps 前门和本地开发主机继续使用 应用程序身份 .

## 创建直接的无密码运行时间

当您拥有 HTTP 路由、 身份政策 时直接使用此软件包 代码传送 :

```ts
import { auth, authStorage, type AuthEmailOptions } from "@dbx-tools/auth-gate";

async function deliverCode(email: string, code: string, options: AuthEmailOptions): Promise<void> {
  const endpoint = process.env.CODE_DELIVERY_URL;
  if (!endpoint) {
    throw new Error("CODE_DELIVERY_URL is required");
  }
  const response = await fetch(endpoint, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ email, code, ...options }),
  });
  if (!response.ok) {
    throw new Error(`Code delivery failed with status ${response.status}`);
  }
}

const database = await authStorage.createAuthStorage({ storage: "sqlite" });
const secret = process.env.AUTH_SECRET;
if (!secret) {
  throw new Error("AUTH_SECRET is required");
}

const runtime = await auth.createPasswordlessAuth({
  storage: database,
  baseURL: "http://localhost:8000",
  trustedOrigins: ["https://overlay.example.com"],
  appName: "My app",
  passkeyNamePrefix: "My Company",
  secret,
  logoutRedirectPath: "/",
  sessionTtlSeconds: 2_592_000,
  codeTtlSeconds: 600,
  maxAttempts: 5,
  authorizeIdentity: (email) => email.endsWith("@example.com"),
  sendCode: (email, code, options) => deliverCode(email, code, options),
});
```

挂载 `runtime.handler(request)` 下级 `runtime.basePath`,默认为 `/api/auth`启用 `runtime.session(headers)` 当应用程序需要时 已核实的电子邮件地址 。 打电话 `runtime.close()` 服务器关机时,请 存储适配器可以释放其资源.

## 选择直接或隧道集成

对通过 Databricks 输入的流量使用 AppKit 执行上下文 Apps前门。 前门提供平台身份 并且可以提供 半个字.

使用 `@dbx-tools/tunnel` 当 AppKit 应用程序也有公共 Portr 或 FRP出入口. 内容 `authGate()` 插件 :

-   按配置的隧道流量进行分类 `Host` 头曰.
-   在 AppKit 服务器上挂载登录和兼容路线 .
-   离开站台前门站及地道通车.
-   通过注册发送代码 `@dbx-tools/email` 插件 .
-   删除未信任的转发身份和符号头 .
-   输入已验证的隧道电子邮件作为请求身份 .

使用 `@dbx-tools/auth-gate` 直接用于另一个 HTTP 堆栈或路径 不需要隧道的分类 直接运行时间不挂载 AppKit 中间软件,前方身份头,或发射地道.

密码或电子邮件编码会话仅证明配置的身份 。 这个 不薄荷 数据砖在半个标志.

## 配置存储

更好的Auth存储用户、会话、检察官办公室、费率限制和密码。 存储罐 使用 AppKit Lakebase 池或本地 SQLite :

```ts
import { authStorage } from "@dbx-tools/auth-gate";

const sqlite = await authStorage.createAuthStorage({
  storage: "sqlite",
  sqlitePath: "./data/auth.sqlite",
});
```

`storage: "auto"` 除非您请求 SQLite ,否则您会使用一个提供Lakebase 池。 若为 SQLite 不可用自动模式, 运行时使用内存 适配器. 明确 `storage: "sqlite"` 设置失败而不是选择 记忆。 内部用户、检察官办公室、会话和密码在 进程退出.

在 Lakebase 或 a 的 PostgreSQL 咨询锁定下运行更好的 Auth 迁移 sQLite 的文件锁定.

## 使用兼容路线

`POST <basePath>/logout` 返回时 `{ ok, redirectTo }`。 。 。 . `GET` 清除相同的 会话和有状态的重定向 `303`。重定向默认值为 `/` 已经 限于同源路径。 更好的 Auth 仅接受 `baseURL` 财务报告和审定财务报表 `trustedOrigins`拒绝任意请求来源或引用者。 内部a 数据砖 App, HTTPS `*.databricksapps.com` 来源自动被接受 为站台正门. WebAuthn 仍然使用配置 `baseURL` 东道主 其RPID和预期来源.

`GET <basePath>/status` 返回已核实的会话状态。 检察官办公室发送 校验使用 Better Auth 的本地电子邮件 OTP 路由 路径.

## 理解认证限制

-   `authorizeIdentity` 运行普通小写电子邮件地址。 一个 未经授权的代码请求不能显示地址是否被允许.
-   运行时间存储 OTP 值作为散列并限制代码尝试和请求 价格通过Better Auth.
-   `baseURL` 确定安全的- cookie 行为, WebAuthn 依赖 party ID, 和预期的密码来源。 依赖方的ID是确切的主机名, 所以兄弟会的隧道主机使用 单独的密码。 配置外部浏览器 来源,而不是生产中的私人回回地址.
-   `passkeyNamePrefix` 控制在 WebAuthn 显示名 。 默认为 `appName`。 。 。 .
-   `passkeys: false` 禁用 WebAuthn 路由并广告电子邮件 OTP 是唯一的 登录方法。 密码默认启用 .
-   `trustedOrigins` 扩展已接受的浏览器来源。 任意 `Origin` 财务报告和审定财务报表 `Referer` 价值观被拒绝.
-   运行时间是认证边界, 不是 Databricks 授权 客户端。 下游 Databricks 的通话仍然需要 AppKit 或其他证书 来源.

## 常见问题

### @dbx-tools/auth-gate 是什么？

在Better Auth、电子邮件 OTP和密码上创建的无密码认证运行时间

### 如何安装 @dbx-tools/auth-gate？

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

### @dbx-tools/auth-gate 支持 TypeScript 吗？

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

### @dbx-tools/auth-gate 支持 ESM 还是 CommonJS？

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

### @dbx-tools/auth-gate 可以商用吗？

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

### @dbx-tools/auth-gate 的下载量有多少？

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

### @dbx-tools/auth-gate 还在维护吗？

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