json-seal 0.10.1 → 0.11.1

package/README.md

@@ -14,6 +14,8 @@
   A lightweight, zero‑dependency library for creating cryptographically signed, tamper‑proof JSON backups.
 </h3>
 
+---
+
 ## **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:
@@ -22,13 +24,53 @@ Apps often need to store or transmit JSON in a way that guarantees it hasn’t b
 
 json‑seal fills that gap. It lets you:
 
-- Canonicalize any JSON value  
+- 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 — even a single character  
+- Detect any tampering
 
-It’s like JWS, but for **arbitrary JSON documents**, without JWT complexity, and designed for **offline‑first apps**, **local backups**, and **portable integrity checks**. It turns any JSON value into a **portable, human‑readable, cryptographically signed artifact** that can be verified anywhere, on any device, with no external dependencies.
+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  
+
+Typed 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.
+
+```ts
+signPayload('{"a":1}') // ❌ signs the string literally
+signPayload({ a: 1 })  // ✔ signs the object
+```
 
 ---
 
@@ -55,11 +97,15 @@ Everything needed for verification is embedded:
 - signature  
 - public key  
 
-### **Works Everywhere**
+### **Works with any JavaScript platform**
 Browsers, PWAs, Node 18+, Bun, Deno, and mobile runtimes.
 
+### **Interoperability**
+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
+
 ### **Zero Dependencies**
-Small, auditable, and safe for long‑term use.
+Uses the built‑in WebCrypto API (no polyfills, no external crypto libraries). Small, auditable, and safe for long‑term use.
 
 ---
 
@@ -127,7 +173,7 @@ if (result.valid) {
 Any modification — even deep inside nested objects — invalidates the signature.
 
 ```ts
-const tampered = { ...backup, payload: { id: 1, data: "hacked" } };
+const tampered = { ...backup, payload: { id: 1, data: "modified" } };
 
 verifyBackup(tampered).valid; // false
 ```
@@ -140,7 +186,8 @@ verifyBackup(tampered).valid; // false
 Generates a 2048‑bit RSA‑PSS keypair.
 
 ### **`signPayload(payload, privateKey, publicKey)`**  
-Canonicalizes the payload, signs it, and returns a sealed backup object.
+Canonicalizes the payload, signs it, and returns a sealed backup object.  
+The payload must be **JSON‑compatible** (see “What json‑seal accepts”).
 
 ### **`verifyBackup(backup)`**  
 Verifies the signature and returns `{ valid, payload? }`.
@@ -150,16 +197,41 @@ Full RFC 8785 Canonical JSON implementation.
 
 ---
 
-## **Prior Art**
+## 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).
 
-json‑seal builds on ideas from:
+- **Not offline‑first**  
+  JWS is built for network protocols. json‑seal is built for sealed backups, hash chains, and local integrity.
 
-- **json-canonicalize** — RFC 8785 canonicalization (no signing or backup format)  
-- **rfc8785 (Python)** — pure Python canonicalizer  
-- **jcs (Elixir)** — Elixir implementation of JCS  
-- **JOSE / JWS / JWT** — signing standards focused on tokens, not arbitrary JSON  
+- **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 combines **canonicalization + signing + verification** into a single, zero‑dependency library designed for **offline‑first, portable JSON integrity**.
+### In contrast
+
+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.
 
 ---
 
@@ -181,11 +253,12 @@ Run tests:
 ```bash
 npm test
 ```
-
 ---
+
 Pull Requests are welcome.
+
 ## **License**
 
 MIT
 
----
+---

package/package.json

@@ -1,57 +1,58 @@
-{
-  "name": "json-seal",
-  "version": "0.10.1",
-  "description": "Create cryptographically signed, tamper‑proof JSON backups with zero dependencies.",
-  "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
-  },
-  "sideEffects": false,
-  "engines": {
-    "node": ">=18"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "keywords": [
-    "cryptography",
-    "digital-signature",
-    "tamper-detection",
-    "data-integrity",
-    "rsa-pss",
-    "json",
-    "json-security",
-    "json-signing",
-    "canonicalization",
-    "typescript",
-    "nodejs"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/cmyers/json-seal.git"
-  },
-  "homepage": "https://github.com/cmyers/json-seal#readme",
-  "bugs": {
-    "url": "https://github.com/cmyers/json-seal/issues"
-  },
-  "scripts": {
-    "build": "tsc",
-    "test": "vitest",
-    "test:watch": "vitest --watch"
-  },
-  "license": "MIT",
-  "devDependencies": {
-    "@types/node": "^25.0.6",
-    "tsx": "^4.21.0",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.16"
-  }
-}
+{
+  "name": "json-seal",
+  "version": "0.11.1",
+  "author": "Chris Myers <cmyers2015@outlook.com> (https://www.npmjs.com/~cmyers-dev)",
+  "description": "Create cryptographically signed, tamper‑proof JSON backups with zero dependencies.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "cryptography",
+    "digital-signature",
+    "tamper-detection",
+    "data-integrity",
+    "rsa-pss",
+    "json",
+    "json-security",
+    "json-signing",
+    "canonicalization",
+    "typescript",
+    "nodejs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cmyers/json-seal.git"
+  },
+  "homepage": "https://github.com/cmyers/json-seal#readme",
+  "bugs": {
+    "url": "https://github.com/cmyers/json-seal/issues"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest",
+    "test:watch": "vitest --watch"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.0.6",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  }
+}

package/dist/canonicalize.d.ts

@@ -1 +0,0 @@
-export declare function canonicalize(obj: any): string;

package/dist/canonicalize.js

@@ -1,11 +0,0 @@
-export function canonicalize(obj) {
-    if (obj === null || typeof obj !== "object") {
-        return JSON.stringify(obj);
-    }
-    if (Array.isArray(obj)) {
-        return `[${obj.map(canonicalize).join(",")}]`;
-    }
-    const keys = Object.keys(obj).sort();
-    const entries = keys.map(k => `"${k}":${canonicalize(obj[k])}`);
-    return `{${entries.join(",")}}`;
-}

package/dist/index.d.ts

@@ -1,3 +0,0 @@
-export * from "./canonicalize.js";
-export * from "./sign.js";
-export * from "./verify.js";

package/dist/index.js

@@ -1,3 +0,0 @@
-export * from "./canonicalize.js";
-export * from "./sign.js";
-export * from "./verify.js";

package/dist/sign.d.ts

@@ -1,14 +0,0 @@
-export declare function generateKeyPair(): {
-    privateKey: string;
-    publicKey: string;
-};
-export declare function signPayload(payload: any, privateKeyPem: string, publicKeyPem: string): {
-    version: number;
-    timestamp: string;
-    payload: any;
-    signature: {
-        algorithm: string;
-        publicKey: string;
-        value: string;
-    };
-};

package/dist/sign.js

@@ -1,33 +0,0 @@
-import { generateKeyPairSync, createSign, constants } from "crypto";
-import { canonicalize } from "./canonicalize.js";
-export function generateKeyPair() {
-    const { privateKey, publicKey } = generateKeyPairSync("rsa", {
-        modulusLength: 2048
-    });
-    return {
-        privateKey: privateKey.export({ type: "pkcs1", format: "pem" }),
-        publicKey: publicKey.export({ type: "spki", format: "pem" })
-    };
-}
-export function signPayload(payload, privateKeyPem, publicKeyPem) {
-    const canonical = canonicalize(payload);
-    const bytes = Buffer.from(canonical, "utf8");
-    const signer = createSign("RSA-SHA256");
-    signer.update(bytes);
-    signer.end();
-    const signature = signer.sign({
-        key: privateKeyPem,
-        padding: constants.RSA_PKCS1_PSS_PADDING,
-        saltLength: 32
-    }).toString("base64");
-    return {
-        version: 1,
-        timestamp: new Date().toISOString(),
-        payload,
-        signature: {
-            algorithm: "RSA-PSS-SHA256",
-            publicKey: publicKeyPem,
-            value: signature
-        }
-    };
-}

package/dist/verify.d.ts

@@ -1,4 +0,0 @@
-export declare function verifyBackup(backup: any): {
-    valid: boolean;
-    payload: any;
-};

package/dist/verify.js

@@ -1,19 +0,0 @@
-import { createVerify, constants } from "crypto";
-import { canonicalize } from "./canonicalize.js";
-export function verifyBackup(backup) {
-    const { payload, signature } = backup;
-    const canonical = canonicalize(payload);
-    const bytes = Buffer.from(canonical, "utf8");
-    const verifier = createVerify("RSA-SHA256");
-    verifier.update(bytes);
-    verifier.end();
-    const valid = verifier.verify({
-        key: signature.publicKey,
-        padding: constants.RSA_PKCS1_PSS_PADDING,
-        saltLength: 32
-    }, Buffer.from(signature.value, "base64"));
-    return {
-        valid,
-        payload: valid ? payload : undefined
-    };
-}