json-signature-utils

A Node.js utility library for signing and verifying JSON objects using cryptographic signatures. This library provides both programmatic APIs and command-line tools for secure JSON data integrity verification.

Features

• JSON Signing: Sign JSON objects using private keys with SHA-256 hashing
• Signature Verification: Verify JSON signatures using public keys
• Canonical JSON: Uses canonical JSON serialization for consistent signatures
• Property Ignoring: Option to ignore specific properties during signing/verification
• CLI Support: Command-line interface for easy integration into scripts
• ESM Support: Modern ES modules with TypeScript-style JSDoc
• Cross-Platform: Works in both Node.js and browser environments using WebCrypto API

Installation

npm install json-signature-utils

Usage

import { sign, verify } from 'json-signature-utils';
import fs from 'fs';

// Load your keys
const privateKey = '-----BEGIN PRIVATE KEY-----...';
const publicKey = '-----BEGIN PUBLIC KEY-----...';

// Sign a JSON object
const data = { name: 'John Doe', age: 30, signature: 'some-old-signature' };
const signature = await sign(data, privateKey, { ignoredProperties: ['signature'] });

const signedData = { ...data, signature: signature };

// Verify the signature
const isValid = await verify(signedData, signature, publicKey, { ignoredProperties: ['signature'] });
console.log('Signature is valid:', isValid);

Command Line Interface

The CLI tool is automatically available as json-signature-utils when the package is installed using npm install -g:

Sign a JSON file

# Sign and output to console
json-signature-utils sign --input data.json --key private_key.pem

# Sign and save to file
json-signature-utils sign --input data.json --key private_key.pem --output signed_data.json

Verify a JSON file

json-signature-utils verify --input signed_data.json --key public_key.pem

Note: The CLI automatically ignores the signature property when signing/verifying, so you don't need to specify it manually.

CLI Examples

# Sign a JSON file
echo '{"name": "Alice", "age": 25}' > data.json
json-signature-utils sign --input data.json --key private_key.pem --output signed.json

# Verify the signed file
json-signature-utils verify --input signed.json --key public_key.pem
# Output: ✅ Signature is VALID

# Verify an invalid signature
json-signature-utils verify --input data.json --key public_key.pem
# Output: ❌ Signature is INVALID

API Reference

sign(json, privateKeyPem, options)

Signs a JSON object using a private key.

Parameters:

• json (string | object): JSON string or object to sign
• privateKeyPem (string): Private key in PEM format
• options (object, optional): Signing options
  • ignoredProperties (string[]): Array of property names to ignore when signing

Returns: Promise<string> - Base64-encoded signature

verify(json, signature, publicKeyPem, options)

Verifies a JSON object signature using a public key.

Parameters:

• json (string | object): JSON string or object to verify
• signature (string): Base64-encoded signature to verify
• publicKeyPem (string): Public key in PEM format
• options (object, optional): Verification options
  • ignoredProperties (string[]): Array of property names to ignore when verifying

Returns: Promise<boolean> - True if signature is valid, false otherwise

Key Generation

Generate new public and private keys for signing using WebCrypto-compatible formats:

# Generate private key directly in PKCS#8 format (required for WebCrypto)
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out private_key.pem

# Extract public key in SPKI format (required for WebCrypto)
openssl pkey -in private_key.pem -pubout -out public_key.pem

Note: The WebCrypto API requires keys in specific formats:

• Private keys must be in PKCS#8 format (-----BEGIN PRIVATE KEY-----)
• Public keys must be in SPKI format (-----BEGIN PUBLIC KEY-----)

Security Considerations

• Store private keys securely and never commit them to version control

License

MPL-2.0