Usage

json‑seal exposes two primary operations: signPayload and verifyBackup, along with a helper for generating signing keys.

1. Generate a key pair

Signing requires an RSA‑PSS private key. Verification uses the embedded public key.

import { generateKeyPair } from "json-seal";

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

2. Signing a value

Sign any JSON‑serializable value into a tamper‑evident envelope. The envelope includes the original payload, a timestamp, the RSA‑PSS signature, and the embedded public key.

Internally, the payload is canonicalized using the RFC 8785 JSON Canonicalization Scheme. The canonical bytes are then signed using RSA‑PSS with SHA‑256.

import { signPayload } from "json-seal";

const sealed = await signPayload(
  { user: "chris", role: "admin" },
  privateKey,
  publicKey
);

// persist or transmit `sealed`

3. Verifying a signed value

Verification re‑canonicalizes the payload using RFC 8785 and validates the RSA‑PSS signature using the embedded public key. If the signature is valid, the document is authentic and unmodified.

import { verifyBackup } from "json-seal";

const result = await verifyBackup(sealed);

if (result.valid) {
  console.log("Document is authentic");
  console.log(result.payload); // original value
} else {
  console.error("Verification failed");
}

Error handling

Verification failures are returned through the result object rather than thrown, allowing you to route failures explicitly.

← Back