# @gyeonghokim/ky-digest-auth 中文文档

规范地址：https://npmcn.com/package/%40gyeonghokim/ky-digest-auth/

版本：1\.0\.0
npm 元数据更新时间：2026-11-01T05:43:11.197Z
中文译文更新时间：2026-11-01T07:16:07.232Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：24.3 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=26
- 运行依赖：1 个
- peer 依赖：ky \>=2\.0\.0
- 首次发布：2026-07-13T09:16:16.046Z
- 最新版本发布：2026-11-01T05:43:10.902Z
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

key的HTTP摘要身份验证。为CCTV， NVR和其他嵌入式设备而构建。

## 安装

```sh
npm install @gyeonghokim/ky-digest-auth
```

也可以使用：`pnpm add @gyeonghokim/ky-digest-auth`、`yarn add @gyeonghokim/ky-digest-auth`、`bun add @gyeonghokim/ky-digest-auth`

## README

# @gyeonghokim / ky-digest-auth

[![npm version](https://img.shields.io/npm/v/@gyeonghokim/ky-digest-auth?label=npm)](https://www.npmjs.com/package/@gyeonghokim/ky-digest-auth) [![CI](https://github.com/GyeongHoKim/ky-digest-auth/actions/workflows/ci.yml/badge.svg)](https://github.com/GyeongHoKim/ky-digest-auth/actions/workflows/ci.yml) [![license](https://img.shields.io/npm/l/@gyeonghokim/ky-digest-auth)](https://npmcn.com/package/%40gyeonghokim/ky-digest-auth/LICENSE)

HTTP摘要身份验证 [肯塔基州](https://github.com/sindresorhus/ky).

## 安装

```sh
npm install ky @gyeonghokim/ky-digest-auth
```

## 使用

```ts
import ky from 'ky';
import { digestAuth } from '@gyeonghokim/ky-digest-auth';

const api = ky.create({
  hooks: digestAuth({
    username: 'admin',
    password: 'password',
  }),
});

const data = await api.get('https://device.example.com/api/status').json();

console.log(data);
```

插件自动：

1.  接收 `401 Unauthorized` 响应。
2.  解析 `WWW-Authenticate: Digest` 挑战。
3.  计算摘要授权响应。
4.  重新尝试使用生成的 `Authorization` 头。

### 浏览器登录对话框

调用受摘要保护的API时 **自己的起源**,浏览器 拦截 `401` 并显示其本地登录对话框，保存请求 直到用户提交。这种回应从来没有打动过Ky。

为了防止这种情况，插件发送每个请求 `credentials: 'omit'`. 这将覆盖任何 `credentials` 你通过了这个选项，它就会关闭 浏览器管理的凭据：既不发送也不存储这些凭据的cookie 请求、缓存的HTTP身份验证和客户端证书不被使用。这个 `Authorization` 由插件计算的头仍然被发送。跨源 使用Ky的默认凭据的请求与以前完全一样。

## API

### `digestAuth(options)`

返回处理HTTP摘要身份验证的Ky hooks配置。

```ts
import ky from 'ky';
import { digestAuth } from '@gyeonghokim/ky-digest-auth';

const api = ky.create({
  hooks: digestAuth({
    username: 'admin',
    password: 'password',
  }),
});
```

### 选项

#### `username`

类型: `string`

用于摘要身份验证的用户名。

#### `password`

类型: `string`

用于摘要身份验证的密码。

#### `algorithms`

类型:

```ts
Array<'MD5' | 'MD5-sess' | 'SHA-256' | 'SHA-256-sess' | 'SHA-512-256' | 'SHA-512-256-sess'>;
```

允许的摘要算法的可选列表。

```ts
const api = ky.create({
  hooks: digestAuth({
    username: 'admin',
    password: 'password',
    algorithms: ['SHA-256', 'MD5'],
  }),
});
```

如果省略，则允许此包支持的所有算法。

许多嵌入式设备（CCTV、NVR和类似的系统）仍然存在问题 `MD5` 挑战。因为Web加密API没有实现 `MD5` 或者 `SHA-512-256`，此包计算每个Digest散列值 [`@noble/hashes`](https://github.com/paulmillr/noble-hashes)，经审计的； 零依赖，可摇树哈希库。所有列出的算法都在 任何支持的运行时，无需额外配置。看到 [支持环境](https://npmcn.com/package/%40gyeonghokim/ky-digest-auth/#readme-supported-environments) 获取详细信息。

#### `preemptive`

类型: `boolean` 默认值: `false`

重用以前接收到的Digest挑战，以应对对同一保护空间的后续请求。

```ts
const api = ky.create({
  hooks: digestAuth({
    username: 'admin',
    password: 'password',
    preemptive: true,
  }),
});
```

第一个请求仍然需要服务器挑战。

#### `cnonce`

类型: `() => string`

覆盖客户端随机数生成器。

```ts
const api = ky.create({
  hooks: digestAuth({
    username: 'admin',
    password: 'password',
    cnonce: () => 'custom-client-nonce',
  }),
});
```

这主要用于确定性测试。默认实现使用加密安全的随机值。

## 示例

### 类型化JSON响应

```ts
import ky from 'ky';
import { digestAuth } from '@gyeonghokim/ky-digest-auth';

type DeviceStatus = {
  online: boolean;
  firmwareVersion: string;
};

const api = ky.create({
  hooks: digestAuth({
    username: 'admin',
    password: 'password',
  }),
});

const status = await api.get('https://device.example.com/api/status').json<DeviceStatus>();

console.log(status.firmwareVersion);
```

### 创建一个可重用的客户机

```ts
const deviceApi = ky.create({
  baseUrl: 'https://device.example.com/api/',
  hooks: digestAuth({
    username: 'admin',
    password: 'password',
  }),
});

const status = await deviceApi.get('status').json();
const configuration = await deviceApi.get('configuration').json();
```

### 发送JSON

```ts
await deviceApi.put('configuration', {
  json: {
    enabled: true,
    quality: 'high',
  },
});
```

### 扩展现有的Ky实例

```ts
const baseApi = ky.create({
  timeout: 10_000,
  headers: {
    Accept: 'application/json',
  },
});

const deviceApi = baseApi.extend({
  hooks: digestAuth({
    username: 'admin',
    password: 'password',
  }),
});
```

### 与其他挂钩结合使用

当多个集成使用同一个生命周期钩子时，必须合并Ky钩子数组。

```ts
const digestHooks = digestAuth({
  username: 'admin',
  password: 'password',
});

const api = ky.create({
  hooks: {
    beforeRequest: [
      ({ request }) => {
        request.headers.set('X-Client-Version', '1.0.0');
      },
      ...(digestHooks.beforeRequest ?? []),
    ],
    afterResponse: [
      ({ response }) => {
        console.log(response.status);
      },
      ...(digestHooks.afterResponse ?? []),
    ],
  },
});
```

## 重试行为

摘要身份验证在收到初始质询后至少需要一个附加请求。

该插件使用Ky's `afterResponse` 钩子和强制重试机制，用生成的请求重试 `Authorization` 头。

不要完全禁用重试：

```ts
const api = ky.create({
  retry: {
    limit: 1,
  },
  hooks: digestAuth({
    username: 'admin',
    password: 'password',
  }),
});
```

以下配置会阻止Digest Authentication完成：

```ts
const api = ky.create({
  retry: {
    limit: 0,
  },
  hooks: digestAuth({
    username: 'admin',
    password: 'password',
  }),
});
```

该插件可防止身份验证挑战导致无限重试循环。

## 歌珥

HTTP摘要身份验证不绕过浏览器的同源策略。

对于跨域请求，服务器必须公开 `WWW-Authenticate` 响应头:

```http
Access-Control-Expose-Headers: WWW-Authenticate
```

它还必须允许 `Authorization` 请求头:

```http
Access-Control-Allow-Headers: Authorization, Content-Type
```

典型的CORS响应可能包括：

```http
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Expose-Headers: WWW-Authenticate
```

许多嵌入式设备不提供完整的CORS实现。当目标服务器不支持所需的CORS标头时，请使用同源后端或反向代理。

```text
Browser
   |
   | Application authentication
   v
Backend or reverse proxy
   |
   | Digest Authentication
   v
Device or legacy service
```

## 安全

不要在公开分发的浏览器代码中嵌入共享服务凭据。

当前用户可以检查浏览器JavaScript使用的凭据。浏览器端摘要身份验证适用于以下情况：

-   用户提供自己的凭据；
-   允许用户访问这些凭据；或
-   应用程序在具有适当威胁模型的受控环境中运行。

为固定或特权服务凭证使用可信后端。

摘要认证不加密HTTP流量。只要目标服务器支持HTTPS，就使用它。

## 支持环境

该包需要一个兼容fetch的运行时：

-   `fetch`
-   `Request`
-   `Response`
-   `Headers`
-   `crypto.getRandomValues` （对于默认客户端nonce）

node . js `>= 26` 在浏览器外运行时需要。

它适用于现代浏览器和Ky支持的其他运行时。

### 哈希

Web Crypto API只公开 `SHA-1`， `SHA-256`， `SHA-384`, `SHA-512`. 它 **不** 提供 `MD5` 或者 `SHA-512-256`，这两种情况在美国都很常见 摘要CCTV、NVR和其他嵌入式设备所面临的挑战。（`SHA-512-256` 一个不同的算法是从 `SHA-512`，而是使用不同的初始值 比一个简单的截断，所以一个原生 `SHA-512` 不能为它重用Digest。)

而不是依赖于Web加密的哈希，包计算每一个 算法通过 [`@noble/hashes`](https://github.com/paulmillr/noble-hashes)：

| 算法 | 模块 |
| --- | --- |
| `MD5`， `MD5-sess` | `@noble/hashes/legacy.js` |
| `SHA-256`， `SHA-256-sess` | `@noble/hashes/sha2.js` |
| `SHA-512-256`， `SHA-512-256-sess` | `@noble/hashes/sha2.js` |

`@noble/hashes` 是一个审计的、零依赖的、可摇树的库吗 您实际使用的算法包含在您的包中，并且每个都列出了 算法可以在任何与fetch兼容的开箱即用运行时中工作。已经安装好了 自动作为此包的依赖项。

## 支持身份验证

这个包处理HTTP摘要身份验证。

它没有规定：

-   基本身份验证
-   不记名的令牌
-   OAuth
-   NTLM
-   协商还是Kerberos
-   基于表单的认证
-   基于cookie的会话管理

## 开发

```sh
npm install
npx playwright install chromium # once, for the browser tests
npm test
```

`npm test` 运行Node测试和Chromium浏览器测试，包括 检查同源摘要请求永远不会触发浏览器登录 对话框。

## 许可证

麻省理工学院

## 常见问题

### @gyeonghokim/ky-digest-auth 是什么？

key的HTTP摘要身份验证。为CCTV， NVR和其他嵌入式设备而构建。

### 如何安装 @gyeonghokim/ky-digest-auth？

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

### @gyeonghokim/ky-digest-auth 支持 TypeScript 吗？

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

### @gyeonghokim/ky-digest-auth 支持 ESM 还是 CommonJS？

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

### @gyeonghokim/ky-digest-auth 需要什么版本的 Node\.js？

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

### @gyeonghokim/ky-digest-auth 可以商用吗？

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

### @gyeonghokim/ky-digest-auth 还在维护吗？

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