json-seal

A lightweight, zero‑dependency library for creating cryptographically signed, tamper‑proof JSON backups.

---

What json-seal is for

json-seal signs structured JSON data. It canonicalizes a JavaScript value into deterministic JSON text, encodes it as UTF-8 bytes, and signs those bytes using WebCrypto.

It is not a generic byte-signing library. If you need to sign arbitrary bytes, use WebCrypto directly. json-seal is specifically for authenticity of JSON- compatible data.

---

Why json‑seal

Apps often need to store or transmit JSON in a way that guarantees it hasn’t been tampered with - without relying on servers, tokens, or opaque binary formats. Most security libraries focus on encrypted blobs, authentication tokens, or low‑level crypto primitives, but none solve the simple problem:

“I need to store JSON in a way that guarantees integrity - while keeping it readable, portable, and framework‑agnostic.”

json‑seal fills that gap. It lets you:

• Canonicalise any JSON‑compatible JavaScript value into deterministic JSON text
• Sign it with a private key
• Embed the public key
• Verify integrity later
• Detect any tampering

It’s built for offline‑first apps, local backups, and portable integrity checks, where JSON must remain human‑readable and self‑verifying.

---

What json‑seal accepts

signPayload() accepts any JSON‑compatible JavaScript value, including:

• objects
• arrays
• strings
• numbers
• booleans
• null

TypeScript interfaces work automatically as long as their fields are JSON‑compatible.

Rejected values

json‑seal does not accept values that cannot appear in JSON:

• undefined
• functions
• class instances
• Dates
• Maps / Sets
• Symbols
• BigInts
• circular references
• objects containing unsupported values

These are rejected at runtime with a clear error.

Important

json‑seal signs values, not JSON text.

signPayload('{"a":1}') // ❌ signs the string literally
signPayload({ a: 1 })  // ✔ signs the object

---

Features

RFC 8785 Canonical JSON

Deterministic, cross‑runtime canonicalization:

• sorted keys
• strict number formatting
• ECMAScript string escaping
• duplicate‑key rejection
• stable UTF‑8 output

RSA‑PSS and Ed25519 Signatures

Modern asymmetric signing using WebCrypto with your choice of algorithm:

• RSA‑PSS (default) — 2048‑bit, SHA‑256, saltLength 32
• Ed25519 - compact, fast, deterministic signatures

No shared secrets. No servers. No dependencies.

Algorithm Auto‑Detection

verifyBackup() reads the algorithm field embedded in the backup and selects the correct verification path automatically - no caller configuration needed.

Portable JSON Backup Format

Everything needed for verification is embedded:

• payload
• timestamp
• signature
• public key

Works with any JavaScript platform

Browsers, PWAs, Node 18+, Bun, Deno, and mobile runtimes.

Interoperability

For RSA-PSS, json‑seal follows the WebCrypto specification (SHA‑256, saltLength = 32). Environments built directly on OpenSSL defaults may not verify RSA-PSS signatures unless configured to match these parameters.
Ed25519 signatures follow the standard and interoperate with any compliant Ed25519 implementation.

Zero Dependencies

Uses the built‑in WebCrypto API (no polyfills, no external crypto libraries). Small, auditable, and safe for long‑term use.

---

Installation

npm install json-seal

---

Quick Start

Generate a keypair

import { generateKeyPair } from "json-seal";

// RSA-PSS (default)
const { privateKey, publicKey } = await generateKeyPair();

// Ed25519
const { privateKey, publicKey } = await generateKeyPair("Ed25519");

Sign a payload

import { signPayload } from "json-seal";

const payload = { id: 1, data: "hello" };

// RSA-PSS (default)
const backup = await signPayload(payload, privateKey, publicKey);

// Ed25519
const backup = await signPayload(payload, privateKey, publicKey, { algorithm: "Ed25519" });

Verify a backup

import { verifyBackup } from "json-seal";

const result = await verifyBackup(backup);

if (result.valid) {
  console.log("Payload:", result.payload);
}

---

Example Backup

RSA-PSS:

{
  "version": 1,
  "timestamp": "2026-01-11T18:24:55.402Z",
  "payload": { "id": 1, "data": "hello" },
  "signature": {
    "algorithm": "RSA-PSS-SHA256",
    "publicKey": "-----BEGIN PUBLIC KEY----- ...",
    "value": "base64-signature"
  }
}

Ed25519:

{
  "version": 1,
  "timestamp": "2026-01-11T18:24:55.402Z",
  "payload": { "id": 1, "data": "hello" },
  "signature": {
    "algorithm": "Ed25519",
    "publicKey": "-----BEGIN PUBLIC KEY----- ...",
    "value": "base64-signature"
  }
}

---

Tamper Detection

Any modification - even deep inside nested objects - invalidates the signature.

const tampered = { ...backup, payload: { id: 1, data: "modified" } };

verifyBackup(tampered).valid; // false

---

API

generateKeyPair(algorithm?)

Generates a keypair. algorithm is “RSA-PSS” (default, 2048‑bit SHA‑256) or “Ed25519”.

signPayload(payload, privateKey, publicKey, options?)

Canonicalizes the payload, signs it, and returns a sealed backup object.
The payload must be JSON‑compatible (see “What json‑seal accepts”).
Pass { algorithm: “Ed25519” } in options to use Ed25519; defaults to RSA‑PSS.

verifyBackup(backup)

Verifies the signature and returns { valid, payload? }.
The algorithm is read automatically from backup.signature.algorithm.

canonicalize(value)

Full RFC 8785 Canonical JSON implementation.

importPrivateKey(pem, algorithm?)

Imports a PEM private key. Defaults to “RSA-PSS”; pass “Ed25519” for Ed25519 keys.

importPublicKey(pem, algorithm?)

Imports a PEM public key. Defaults to “RSA-PSS”; pass “Ed25519” for Ed25519 keys.

---

Prior Art

JSON Web Signature (JWS)

JWS is the established IETF standard for signing JSON‑related data, but it solves a very different problem. JWS is designed for token exchange between untrusted parties (OAuth, OpenID Connect, identity providers), not for deterministic, portable, tamper‑evident JSON objects.

Key differences:

• JWS signs bytes, not JSON
  The payload must be base64url‑encoded. Two equivalent JSON objects can produce different signatures.

• No canonicalization
  JWS does not define how JSON should be normalized. json‑seal uses deterministic canonicalization so the same logical object always produces the same signature.

• Heavy structural overhead
  Protected headers, unprotected headers, algorithm identifiers, key IDs, and two serialization formats (compact and JSON).

• Not offline‑first
  JWS is built for network protocols. json‑seal is built for sealed backups, hash chains, and local integrity.

• Not WebView‑friendly
  Most JOSE libraries depend on Node’s crypto module. json‑seal uses WebCrypto and works in browsers, Ionic, Capacitor, and mobile WebViews.

In contrast

json‑seal focuses on a simpler, narrower goal:

• Pure JSON in, pure JSON out
• Deterministic canonicalization
• WebCrypto‑based RSA‑PSS and Ed25519 signatures
• Self‑contained sealed objects with embedded public keys
• Zero dependencies
• Portable across browsers, Node, Deno, Bun, and hybrid mobile apps

It’s not a replacement for JWS - it’s a lightweight alternative for cases where you simply need to seal JSON and verify it later, without the complexity of JOSE.

---

Testing

The test suite covers:

• RFC 8785 canonicalization
• Unicode and number edge cases
• Valid RSA‑PSS and Ed25519 signatures
• Shallow and deep tampering
• Missing / wrong / corrupted signatures
• Large payloads
• Arrays and primitives
• RSA‑PSS non‑determinism and Ed25519 determinism
• Algorithm mismatch and unknown algorithm rejection

Run tests:

npm test

---

Pull Requests are welcome.

License

MIT

---