json-seal 0.10.1 → 0.11.0

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  
 
-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 like JWS, but for **arbitrary JSON documents**, without JWT complexity, and designed for **offline‑first apps**, **local backups**, and **portable integrity checks**.
+
+---
+
+## **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? }`.
@@ -154,7 +201,7 @@ Full RFC 8785 Canonical JSON implementation.
 
 json‑seal builds on ideas from:
 
-- **json-canonicalize** — RFC 8785 canonicalization (no signing or backup format)  
+- **json-canonicalize** — RFC 8785 canonicalization  
 - **rfc8785 (Python)** — pure Python canonicalizer  
 - **jcs (Elixir)** — Elixir implementation of JCS  
 - **JOSE / JWS / JWT** — signing standards focused on tokens, not arbitrary JSON  
@@ -183,7 +230,9 @@ npm test
 ```
 
 ---
+
 Pull Requests are welcome.
+
 ## **License**
 
 MIT

package/dist/canonicalize.d.ts

@@ -1 +1,5 @@
-export declare function canonicalize(obj: any): string;
+/**
+ * RFC 8785 Canonical JSON implementation
+ * Deterministic, strict, and cross‑runtime stable.
+ */
+export declare function canonicalize(value: any): string;

package/dist/canonicalize.js

@@ -1,11 +1,122 @@
-export function canonicalize(obj) {
-    if (obj === null || typeof obj !== "object") {
-        return JSON.stringify(obj);
+/**
+ * RFC 8785 Canonical JSON implementation
+ * Deterministic, strict, and cross‑runtime stable.
+ */
+export function canonicalize(value) {
+    switch (typeof value) {
+        case "string":
+            return escapeString(value);
+        case "number":
+            return serializeNumber(value);
+        case "boolean":
+            return value ? "true" : "false";
+        case "object":
+            if (value === null)
+                return "null";
+            if (Array.isArray(value))
+                return serializeArray(value);
+            return serializeObject(value);
+        default:
+            throw new Error(`Unsupported type in canonical JSON: ${typeof value}`);
     }
-    if (Array.isArray(obj)) {
-        return `[${obj.map(canonicalize).join(",")}]`;
+}
+/* -------------------------------------------------------------------------- */
+/*  Strings                                                                    */
+/* -------------------------------------------------------------------------- */
+function escapeString(str) {
+    // RFC 8785 uses ECMAScript string escaping rules.
+    let out = '"';
+    for (let i = 0; i < str.length; i++) {
+        const c = str.charCodeAt(i);
+        switch (c) {
+            case 0x22:
+                out += '\\"';
+                break; // "
+            case 0x5C:
+                out += '\\\\';
+                break; // \
+            case 0x08:
+                out += '\\b';
+                break;
+            case 0x0C:
+                out += '\\f';
+                break;
+            case 0x0A:
+                out += '\\n';
+                break;
+            case 0x0D:
+                out += '\\r';
+                break;
+            case 0x09:
+                out += '\\t';
+                break;
+            default:
+                if (c < 0x20) {
+                    // Control characters → \u00XX
+                    out += "\\u" + hex4(c);
+                }
+                else {
+                    out += str[i];
+                }
+        }
+    }
+    return out + '"';
+}
+function hex4(n) {
+    return n.toString(16).padStart(4, "0");
+}
+/* -------------------------------------------------------------------------- */
+/*  Numbers                                                                    */
+/* -------------------------------------------------------------------------- */
+function serializeNumber(n) {
+    if (!Number.isFinite(n)) {
+        throw new Error("Non‑finite numbers are not permitted in canonical JSON");
+    }
+    // RFC 8785: -0 must be serialized as 0
+    if (Object.is(n, -0))
+        return "0";
+    // Use JS number → string, then normalize exponent form
+    let s = n.toString();
+    // Normalize exponent to uppercase E
+    if (s.includes("e")) {
+        const [mantissa, exp] = s.split("e");
+        const sign = exp.startsWith("-") ? "-" : "+";
+        let digits = exp.replace(/^[+-]/, "");
+        // Remove leading zeros in exponent
+        digits = digits.replace(/^0+/, "");
+        if (digits === "")
+            digits = "0";
+        // RFC 8785: exponent must not include "+"
+        const normalized = `${mantissa}E${sign === "-" ? "-" : ""}${digits}`;
+        return normalized;
     }
-    const keys = Object.keys(obj).sort();
-    const entries = keys.map(k => `"${k}":${canonicalize(obj[k])}`);
+    return s;
+}
+/* -------------------------------------------------------------------------- */
+/*  Arrays                                                                     */
+/* -------------------------------------------------------------------------- */
+function serializeArray(arr) {
+    const items = arr.map(canonicalize);
+    return `[${items.join(",")}]`;
+}
+/* -------------------------------------------------------------------------- */
+/*  Objects                                                                    */
+/* -------------------------------------------------------------------------- */
+function serializeObject(obj) {
+    const keys = Object.keys(obj);
+    // RFC 8785: duplicate keys MUST be rejected
+    detectDuplicateKeys(keys);
+    // Sort by UTF‑16 code units (JS default)
+    keys.sort();
+    const entries = keys.map(k => `${escapeString(k)}:${canonicalize(obj[k])}`);
     return `{${entries.join(",")}}`;
 }
+function detectDuplicateKeys(keys) {
+    const seen = new Set();
+    for (const k of keys) {
+        if (seen.has(k)) {
+            throw new Error(`Duplicate key in object: ${k}`);
+        }
+        seen.add(k);
+    }
+}

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.0",
+  "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"
+  }
+}