# jws 中文文档

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

版本：4\.0\.1
npm 元数据更新时间：2026-06-26T15:04:00.860Z
中文译文更新时间：2026-11-05T15:15:20.839Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/jws
原文对照：https://npmcn.com/package/jws/?lang=original
项目主页：https://github.com/brianloveswords/node-jws#readme
源码仓库：https://github.com/brianloveswords/node-jws

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

- 包体积（解压后）：18.8 kB，10 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：2 个
- 首次发布：2013-01-16T20:17:38.850Z
- 最新版本发布：2025-12-04T08:52:29.218Z
- 近 30 天下载量：376485235（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 2 个）

## 中文简介

JSON网络签名的实施情况

## 安装

```sh
npm install jws
```

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

## README

# 节点-jws [![Build Status](https://secure.travis-ci.org/brianloveswords/node-jws.svg)](http://travis-ci.org/brianloveswords/node-jws)

执行 [JSON 网络签名](http://self-issued.info/docs/draft-ietf-jose-json-web-signature.html)。 。 。 .

这是针对 `draft-ietf-jose-json-web-signature-08` 财务报告和审定财务报表 执行整个光谱 **除外** X.509 证书链 签署/核查(欢迎出票).

两者兼有同步( S)`jws.sign`, (中文(简体) ), `jws.verify`)和流线 (单位:千美元)`jws.createSign`, (中文(简体) ), `jws.createVerify`APIs (英语).

# 安装

```bash
$ npm install jws
```

# 使用量

## jws.ALGOTHIMS (英语)

支持的算法阵列 。 目前支持以下算法.

| 参数值 | 数字签名或MAC算法 |
| --- | --- |
| 第256条 | HMAC 使用 SHA-256 散列算法 |
| HS384 (韩语) | HMAC 使用 SHA-384 散列算法 |
| HS512 (韩语) | HMAC 使用 SHA-512 散列算法 |
| RS256号卫星 | 使用 SHA-256 散列算法的RSASA |
| RS384 软件 | 使用 SHA-384 散列算法的RSASA |
| 登记册512 | RSASA 使用 SHA-512 散列算法 |
| 页:1 | 使用 SHA-256 散列算法的RSASA- PSS |
| 第384条 | 使用 SHA-384 散列算法的RSSSA- PSS |
| PS512 (英语) | 使用 SHA-512 散列算法的RSASA- PSS |
| ES256 (英语) | 使用P-256曲线和SHA-256散列算法的ECDSA |
| ES384 (英语) | 使用 P-384 曲线和 SHA-384 散列算法的 ECDSA |
| ES512 (英语) | 使用P-521曲线和SHA-512散列算法的ECDSA |
| 无 | 未包括数字签字或MAC值 |

## jws. sign( 选项)

(Synchronous)返回一个JSON网络签名,用于一个头和有效载荷.

选项 :

-   `header`
-   `payload`
-   `secret` 或者说 `privateKey`
-   `encoding` (可选,默认为"utf8")

`header` 必须是带有 `alg` 属性. `header.alg` 必须是 一个值 `jws.ALGORITHMS`。见上文表格 支持的算法.

若为 `payload` 不是一个缓冲器或字符串,它将被强制变成字符串 使用 `JSON.stringify`。 。 。 .

示例

```js
const signature = jws.sign({
  header: { alg: 'HS256' },
  payload: 'h. jon benjamin',
  secret: 'has a van',
});
```

## jws.验证(签名、算法、密钥)

(同步)回返 `true` 或者说 `false` 签名是否与 密钥.

`signature` 是 JWS 签名. `header.alg` 必须是在 `jws.ALGORITHMS`。 。 。 . 见上文所支持的算法表. `secretOrKey` 是一个字符串或 包含 HMAC 算法或 PEM 密钥的缓冲器 为RSA和ECDSA编码了公钥.

注意 `"alg"` 来自签名头的值被忽略.

## jws.decode( 签名)

(韵出. 返回已解码头、已解码的有效载荷和签名 jWS签名的部分内容.

返回具有三个属性的对象,例如:.

```js
{ header: { alg: 'HS256' },
  payload: 'h. jon benjamin',
  signature: 'YOWPewyGHKu4Y_0M_vtlEnNlqmFOclqp4Hy6hVHfFT4'
}
```

## jws.create Sign( 选项)

返回一个新的 SignStream 对象.

选项 :

-   `header` (必须)
-   `payload`
-   `key` || `privateKey` || `secret`
-   `encoding` (可选,默认为"utf8")

除外 `header`,所有选项都期望在 数值在时间之前已知,或为方便而流出. `key`编号 :`privateKey`编号 :`secret` 使用加密时也可能是对象 私钥,看 [加密文档](https://nodejs.org/api/crypto.html#crypto_sign_sign_private_key_output_format)。 。 。 .

示例

```js

// This...
jws.createSign({
  header: { alg: 'RS256' },
  privateKey: privateKeyStream,
  payload: payloadStream,
}).on('done', function(signature) {
  // ...
});

// is equivalent to this:
const signer = jws.createSign({
  header: { alg: 'RS256' },
});
privateKeyStream.pipe(signer.privateKey);
payloadStream.pipe(signer.payload);
signer.on('done', function(signature) {
  // ...
});
```

## jws.create 验证( 选项)

返回一个新的验证结构对象.

选项 :

-   `signature`
-   `algorithm`
-   `key` || `publicKey` || `secret`
-   `encoding` (可选,默认为"utf8")

当值在前面已知时, 所有选项都期望有字符串或缓冲 时间,或一条溪来方便.

示例

```js

// This...
jws.createVerify({
  publicKey: pubKeyStream,
  signature: sigStream,
}).on('done', function(verified, obj) {
  // ...
});

// is equivilant to this:
const verifier = jws.createVerify();
pubKeyStream.pipe(verifier.publicKey);
sigStream.pipe(verifier.signature);
verifier.on('done', function(verified, obj) {
  // ...
});
```

## 类: 符号结构

A 类 `Readable Stream` 发出单个数据事件(计算) 签名)完成后.

### 活动: "去"

`function (signature) { }`

### 签名人. 负载

A 类 `Writable Stream` 预想着JWS的有效载荷 这样做 _没有_ 使用时使用 通过了一个 `payload` 选项.

示例

```js
payloadStream.pipe(signer.payload);
```

### 签名人 秘密  
签名者. key  
签名者。 私人 Key

A 类 `Writable Stream`。期待为 HMAC 或私人 Key 提供 JWS 秘密 用于ECDSA和RSA. 这样做 _没有_ 如果你通过了一个 `secret` 或者说 `key` 选项 给建筑师.

示例

```js
privateKeyStream.pipe(signer.privateKey);
```

## 类: 校验结构

这是一个 `Readable Stream` 发出单个数据事件,结果 该签名是否有效.

### 活动: "去"

`function (valid, obj) { }`

`valid` 表示签名是否有效.

### 核查人. 签字

A 类 `Writable Stream` 需要JWS签名。 这样做 _没有_ 使用时使用 通过了一个 `signature` 选项.

### 核查员 机密  
校验器. key  
校验器 公用钥匙

A 类 `Writable Stream` 需要公用钥匙或秘密 这样做 _没有_ 使用时使用 通过了一个 `key` 或者说 `secret` 选项.

# 开始

-   感觉应该有一些便利选项/AP是用于 定义算法而不是需要定义标题对象 与 `{ alg: 'ES512' }` 或任何时间.
    
-   X.509支持, ugh
    

# 许可证

麻省理工学院

```
Copyright (c) 2013-2015 Brian J. Brennan

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
```

## 常见问题

### jws 是什么？

JSON网络签名的实施情况

### 如何安装 jws？

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

### jws 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/jws 是否存在。

### jws 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### jws 可以商用吗？

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

### jws 的下载量有多少？

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

### jws 还在维护吗？

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