# kavach 中文文档

规范地址：https://npmcn.com/package/kavach/

版本：1\.3\.2
npm 元数据更新时间：2026-11-03T22:05:20.674Z
中文译文更新时间：2026-11-04T00:31:37.390Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/kavach
原文对照：https://npmcn.com/package/kavach/?lang=original
项目主页：https://kavach.sensei-hq.com/
源码仓库：https://github.com/sensei-hq/kavach

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

- 包体积（解压后）：117 kB，38 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：7 个
- 首次发布：2023-07-14T04:35:28.458Z
- 最新版本发布：2026-11-03T22:05:20.342Z
- 已发布版本数：19（近 12 个月 16 个）

## 中文简介

降低web应用程序的安全性。

## 安装

```sh
npm install kavach
```

也可以使用：`pnpm add kavach`、`yarn add kavach`、`bun add kavach`

## README

# kavach

> 卡瓦奇-防护盔甲。SvelteKit应用程序的插入式安全性。

## 安装

```bash
bun add kavach @kavach/adapter-supabase
# pick the adapter for your backend
```

## 快速启动

```bash
bun add kavach @kavach/vite @kavach/adapter-supabase
# pick the adapter for your backend
```

创建 `kavach.config.js` 在你的项目根目录下：

```js
export default {
  adapter: 'supabase',
  providers: [
    { name: 'google', label: 'Continue with Google' },
    { name: 'magic', mode: 'otp', label: 'Magic Link' }
  ],
  rules: [
    { path: '/', public: true },
    { path: '/auth', public: true },
    { path: '/dashboard', roles: '*' }
  ],
  env: {
    url: 'PUBLIC_SUPABASE_URL',
    anonKey: 'PUBLIC_SUPABASE_ANON_KEY'
  }
}
```

将Kavach插件添加到 `vite.config.js` ——它必须来得更早 `sveltekit()`：

```js
import { kavach } from '@kavach/vite'
import { sveltekit } from '@sveltejs/kit/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [kavach(), sveltekit()]
})
```

注册服务器钩子 `src/hooks.server.js`：

```js
import { kavach } from '$kavach/auth'
export const handle = kavach.handle
```

```svelte
<!-- src/routes/+layout.svelte -->
<script>
  import { setContext, onMount } from 'svelte'
  import { page } from '$app/stores'

  const kavach = $state({})
  setContext('kavach', kavach)

  onMount(async () => {
    const { createKavach } = await import('kavach')
    const { adapter, logger } = await import('$kavach/auth')
    const { invalidateAll } = await import('$app/navigation')
    const instance = createKavach(adapter, { logger, invalidateAll })
    Object.assign(kavach, instance)
    instance.onAuthChange($page.url)
  })
</script>
```

## 它是做什么的

-   **线路保护** -缺省情况下，所有路由都是私有的；定义公共和角色作用域的路由 `kavach.config.js`
-   **会话管理** -在服务器端读写会话cookie，并同步到客户端
-   **身份验证适配器** -将登录、注销和令牌刷新委托给您选择的后端
-   **日志记录** -结构化JSON日志通过 `@kavach/logger`

## 配置

使用 `kavach init` 脚手架配置，或创建 `kavach.config.js` 手动:

```js
export default {
  adapter: 'supabase',
  providers: [
    { name: 'google', label: 'Continue with Google' },
    { mode: 'otp', name: 'magic', label: 'Email Magic Link' }
  ],
  routes: {
    auth: '(public)/auth',
    logout: '/logout',
    // per-role landing after login — string or async (session) => path
    home: async (session) => (session.user.role === 'admin' ? '/admin' : '/dashboard')
  },
  rules: [
    { path: '/', public: true },
    { path: '/auth', public: true },
    { path: '/dashboard', roles: '*' }, // any authenticated user
    { path: '/admin', roles: ['admin'] } // only the 'admin' role
  ]
}
```

路由保护用flat表示 `rules[]` 数组, `public: true` 对于开放路线， `roles: '*'` 对于任何经过身份验证的用户， `roles: ['role', …]` 对于特定的角色。每个角色 方法解析着陆页 `routes.home` 函数;逐路重定向覆盖使用 规则的 `fallback` （数字覆盖状态，字符串重定向）。看到 [哨兵](https://npmcn.com/package/sentry/README.md) 查看完整的路由规则引用。

## 适配器

| 包 | 后端 |
| --- | --- |
| `@kavach/adapter-supabase` | Supabase |
| `@kavach/adapter-firebase` | 重火力点身份验证 |
| `@kavach/adapter-auth0` | Auth0 |
| `@kavach/adapter-amplify` | AWS Amplify / Cognito |
| `@kavach/adapter-convex` | 凸 |

## API

### `createKavach(adapter, options?)`

返回一个Kavach实例，带有：

-   `handle` - SvelteKit服务器钩子
-   `signIn(credentials)` -使用配置的适配器登录
-   `signOut()` -退出并清除会话
-   `onAuthChange(url)` -处理OAuth回调url
-   `user` -当前用户（客户端响应）
-   `session` -当前会话

## 常见问题

### kavach 是什么？

降低web应用程序的安全性。

### 如何安装 kavach？

在项目目录运行 npm install kavach，或使用 pnpm add / yarn add / bun add。

### kavach 支持 TypeScript 吗？

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

### kavach 支持 ESM 还是 CommonJS？

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

### kavach 可以商用吗？

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

### kavach 还在维护吗？

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