https://github.com/toramanomer/json-web-signature
RFC 7515 JSON Web Signature (JWS) implementation for NodeJS in TypeScript
https://github.com/toramanomer/json-web-signature
json-web-signature jws node nodejs rfc7515
Last synced: 7 months ago
JSON representation
RFC 7515 JSON Web Signature (JWS) implementation for NodeJS in TypeScript
- Host: GitHub
- URL: https://github.com/toramanomer/json-web-signature
- Owner: toramanomer
- License: mit
- Created: 2025-02-25T00:29:09.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-03-04T21:22:50.000Z (7 months ago)
- Last Synced: 2025-03-04T21:31:27.511Z (7 months ago)
- Topics: json-web-signature, jws, node, nodejs, rfc7515
- Language: TypeScript
- Homepage:
- Size: 116 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
README
# JSON Web Signature (JWS)
Implementation of JSON Web Signature (JWS) according to [RFC 7515](https://tools.ietf.org/html/rfc7515).
> **Zero Dependencies**: This project relies solely on Node.js built-in modules and has no production dependencies.
## Serialization Formats
| Feature | JWS Compact Serialization | General JWS JSON Serialization | Flattened JWS JSON Serialization |
| -------------------------------- | ----------------------------- | --------------------------------------- | -------------------------------- |
| **Compact Format** | ✅ Yes | ❌ No | ❌ No |
| **URL-Safe** | ✅ Yes (Base64url encoding) | ❌ No (Uses standard JSON) | ❌ No (Uses standard JSON) |
| **Readability** | ❌ Not human-readable | ✅ More human-readable | ✅ More human-readable |
| **Supports Multiple Signatures** | ❌ No (Single signature only) | ✅ Yes (Multiple signatures) | ❌ No (Single signature only) |
| **JOSE Header** | Protected only | Protected & Unprotected (per signature) | Protected & Unprotected |
## Key Requirements
The keys for signing and/or verification **must be an instance of [`KeyObject`](https://nodejs.org/docs/latest-v22.x/api/crypto.html#class-keyobject)**. The following subsections describe the required properties for the key used in signing and verification operations for each supported algorithm.
### HMAC with SHA-2 Functions (`HS256`, `HS384`, `HS512`)
HMAC-based algorithms use a **symmetric key**, meaning the **same key** is used for both **signing** and **verification**.
The key **must be at least as long as the hash output size**.
#### **Example: Creating a 256-bit Secret Key for HS256**
```typescript
import { generateKeySync } from 'node:crypto'
const key = generateKeySync('hmac', { length: 256 })
console.log(key.type) // "secret"
console.log(key.symmetricKeySize) // 32 (256 bits)
```
| `"alg"` Param Value | Key Type (`keyObject.type`) | Minimum Key Size | Signing Key | Verification Key |
| ------------------- | --------------------------- | ------------------- | ----------- | ---------------- |
| `HS256` | `"secret"` | 32 bytes (256 bits) | Same key | Same key |
| `HS384` | `"secret"` | 48 bytes (384 bits) | Same key | Same key |
| `HS512` | `"secret"` | 64 bytes (512 bits) | Same key | Same key |
### Digital Signature with RSASSA-PKCS1-v1_5 (`RS256`, `RS384`, `RS512`)
These algorithms use **asymmetric RSA keys** with **PKCS#1 v1.5 padding** for digital signatures.
A **private key** is required for signing, while the corresponding **public key** is used for verification.
#### **Example: Generating an RSA Key Pair for RS256**
```typescript
import { generateKeyPairSync } from 'node:crypto'
const { privateKey, publicKey } = generateKeyPairSync('rsa', {
modulusLength: 2048
})
console.log(privateKey.type) // "private"
console.log(publicKey.type) // "public"
console.log(privateKey.asymmetricKeyType) // "rsa"
console.log(publicKey.asymmetricKeyType) // "rsa"
```
| `"alg"` Param Value | Key Type (`keyObject.type`) | Asymmetric Key Type (`keyObject.asymmetricKeyType`) | Minimum Key Size |
| ------------------- | ------------------------------------------------- | --------------------------------------------------- | ---------------- |
| `RS256` | `"private"` (signing) / `"public"` (verification) | `"rsa"` | 2048 bits |
| `RS384` | `"private"` (signing) / `"public"` (verification) | `"rsa"` | 2048 bits |
| `RS512` | `"private"` (signing) / `"public"` (verification) | `"rsa"` | 2048 bits |
### Digital Signature with ECDSA (`ES256`, `ES384`, `ES512`)
These algorithms use **Elliptic Curve Digital Signature Algorithm (ECDSA)** for digital signatures.
A **private key** is required for signing, while the corresponding **public key** is used for verification.
#### **Example: Generating an EC Key Pair for ES256**
```typescript
import { generateKeyPairSync } from 'node:crypto'
const { privateKey, publicKey } = generateKeyPairSync('ec', {
namedCurve: 'P-256'
})
console.log(privateKey.type) // "private"
console.log(publicKey.type) // "public"
console.log(privateKey.asymmetricKeyType) // "ec"
console.log(publicKey.asymmetricKeyType) // "ec"
```
| `"alg"` Param Value | Key Type (`keyObject.type`) | Asymmetric Key Type (`keyObject.asymmetricKeyType`) | Required Curve |
| ------------------- | ------------------------------------------------- | --------------------------------------------------- | -------------------- |
| `ES256` | `"private"` (signing) / `"public"` (verification) | `"ec"` | `P-256` (prime256v1) |
| `ES384` | `"private"` (signing) / `"public"` (verification) | `"ec"` | `P-384` (secp384r1) |
| `ES512` | `"private"` (signing) / `"public"` (verification) | `"ec"` | `P-521` (secp521r1) |
### Digital Signature with RSASSA-PSS (`PS256`, `PS384`, `PS512`)
These algorithms use **RSA Probabilistic Signature Scheme (RSASSA-PSS)**.
A **private key** is required for signing, while the corresponding **public key** is used for verification.
#### **Example: Generating an RSA Key Pair for PS256**
```typescript
import { generateKeyPairSync } from 'node:crypto'
const { privateKey, publicKey } = generateKeyPairSync('rsa', {
modulusLength: 2048
})
console.log(privateKey.type) // "private"
console.log(publicKey.type) // "public"
console.log(privateKey.asymmetricKeyType) // "rsa-pss"
console.log(publicKey.asymmetricKeyType) // "rsa-pss"
```
| `"alg"` Param Value | Key Type (`keyObject.type`) | Asymmetric Key Type (`keyObject.asymmetricKeyType`) | Minimum Key Size |
| ------------------- | ------------------------------------------------- | --------------------------------------------------- | ---------------- |
| `PS256` | `"private"` (signing) / `"public"` (verification) | `"rsa-pss"` | 2048 bits |
| `PS384` | `"private"` (signing) / `"public"` (verification) | `"rsa-pss"` | 2048 bits |
| `PS512` | `"private"` (signing) / `"public"` (verification) | `"rsa-pss"` | 2048 bits |