json-seal 0.11.0 → 0.11.1

package/README.md

@@ -28,9 +28,9 @@ json‑seal fills that gap. It lets you:
 - 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’s built for **offline‑first apps**, **local backups**, and **portable integrity checks**, where JSON must remain human‑readable and self‑verifying.
 
 ---
 
@@ -197,16 +197,41 @@ Full RFC 8785 Canonical JSON implementation.
 
 ---
 
-## **Prior Art**
+## Prior Art
 
-json‑seal builds on ideas from:
+### JSON Web Signature (JWS)
 
-- **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  
+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**.
 
-json‑seal combines **canonicalization + signing + verification** into a single, zero‑dependency library designed for **offline‑first, portable JSON integrity**.
+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 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.
 
 ---
 
@@ -228,7 +253,6 @@ Run tests:
 ```bash
 npm test
 ```
-
 ---
 
 Pull Requests are welcome.
@@ -237,4 +261,4 @@ Pull Requests are welcome.
 
 MIT
 
----
+---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "json-seal",
-  "version": "0.11.0",
+  "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",

package/dist/canonicalize.d.ts

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

package/dist/canonicalize.js

@@ -1,122 +0,0 @@
-/**
- * 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}`);
-    }
-}
-/* -------------------------------------------------------------------------- */
-/*  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;
-    }
-    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/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
-    };
-}