A lightweight, zero‑dependency library for creating cryptographically signed, tamper‑proof JSON backups.
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.
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.
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.
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.
json‑seal signs values, not JSON text.
signPayload('{"a":1}') // ❌ signs the string literally
signPayload({ a: 1 }) // ✔ signs the objectDeterministic, cross‑runtime canonicalization:
- sorted keys
- strict number formatting
- ECMAScript string escaping
- duplicate‑key rejection
- stable UTF‑8 output
Modern asymmetric signing using WebCrypto.
No shared secrets. No servers. No dependencies.
Everything needed for verification is embedded:
- payload
- timestamp
- signature
- public key
Browsers, PWAs, Node 18+, Bun, Deno, and mobile runtimes.
json‑seal follows the WebCrypto RSA‑PSS specification (SHA‑256, saltLength = 32). Environments built directly on OpenSSL defaults may not verify signatures unless configured to match WebCrypto’s parameters
Uses the built‑in WebCrypto API (no polyfills, no external crypto libraries). Small, auditable, and safe for long‑term use.
npm install json-sealimport { generateKeyPair } from "json-seal";
const { privateKey, publicKey } = await generateKeyPair();import { signPayload } from "json-seal";
const payload = { id: 1, data: "hello" };
const backup = await signPayload(payload, privateKey, publicKey);import { verifyBackup } from "json-seal";
const result = await verifyBackup(backup);
if (result.valid) {
console.log("Payload:", result.payload);
}{
"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"
}
}Any modification - even deep inside nested objects - invalidates the signature.
const tampered = { ...backup, payload: { id: 1, data: "modified" } };
verifyBackup(tampered).valid; // falseGenerates a 2048‑bit RSA‑PSS keypair.
Canonicalizes the payload, signs it, and returns a sealed backup object.
The payload must be JSON‑compatible (see “What json‑seal accepts”).
Verifies the signature and returns { valid, payload? }.
Full RFC 8785 Canonical JSON implementation.
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.
json‑seal focuses on a simpler, narrower goal:
- Pure JSON in, pure JSON out
- Deterministic canonicalization
- WebCrypto‑based RSA‑PSS 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.
The test suite covers:
- RFC 8785 canonicalization
- Unicode and number edge cases
- Valid signatures
- Shallow and deep tampering
- Missing / wrong / corrupted signatures
- Large payloads
- Arrays and primitives
- RSA‑PSS non‑determinism
Run tests:
npm testPull Requests are welcome.
MIT