json-seal 0.11.1 → 0.12.0

package/README.md

@@ -6,7 +6,6 @@
   <img src="https://img.shields.io/badge/Deterministic%20JSON-RFC%208785%20Compliant-success" alt="Deterministic JSON" />
   <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="dependencies" />
   <img src="https://img.shields.io/badge/types-TypeScript-blue" alt="types" />
-  <img src="https://img.shields.io/bundlephobia/minzip/json-seal" alt="bundle size" />
   <img src="https://img.shields.io/github/license/cmyers/json-seal" alt="license" />
 </p>
 
@@ -18,9 +17,9 @@
 
 ## **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:
+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.”**
+**“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:
 
@@ -45,7 +44,7 @@ It’s built for **offline‑first apps**, **local backups**, and **portable int
 - booleans  
 - null  
 
-Typed TypeScript interfaces work automatically as long as their fields are JSON‑compatible.
+TypeScript interfaces work automatically as long as their fields are JSON‑compatible.
 
 ### **Rejected values**
 
@@ -170,7 +169,7 @@ if (result.valid) {
 
 ## **Tamper Detection**
 
-Any modification — even deep inside nested objects — invalidates the signature.
+Any modification - even deep inside nested objects - invalidates the signature.
 
 ```ts
 const tampered = { ...backup, payload: { id: 1, data: "modified" } };
@@ -231,7 +230,7 @@ json‑seal focuses on a simpler, narrower goal:
 - **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.
+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.
 
 ---
 

package/dist/base64.d.ts

@@ -0,0 +1,2 @@
+export declare function arrayBufferToBase64(buf: ArrayBuffer): string;
+export declare function base64ToArrayBuffer(base64: string): ArrayBuffer;

package/dist/base64.js

@@ -0,0 +1,23 @@
+// Cross‑runtime base64 helpers (browser + Node 18+)
+const _atob = typeof atob === "function"
+    ? atob
+    : (b64) => Buffer.from(b64, "base64").toString("binary");
+const _btoa = typeof btoa === "function"
+    ? btoa
+    : (bin) => Buffer.from(bin, "binary").toString("base64");
+export function arrayBufferToBase64(buf) {
+    const bytes = new Uint8Array(buf);
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return _btoa(binary);
+}
+export function base64ToArrayBuffer(base64) {
+    const binary = _atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes.buffer;
+}

package/dist/canonicalize.d.ts

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

package/dist/canonicalize.js

@@ -0,0 +1,145 @@
+/**
+ * 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 defines canonicalization in terms of ECMAScript strings (UTF‑16),
+    // but the final canonical form must be encoded as UTF‑8 when serialized.
+    // Therefore we validate UTF‑16 correctness (surrogate pairs) here.
+    let out = '"';
+    for (let i = 0; i < str.length; i++) {
+        const c = str.charCodeAt(i);
+        // Surrogate handling (UTF‑16 correctness)
+        if (c >= 0xd800 && c <= 0xdbff) {
+            // High surrogate: must be followed by a low surrogate
+            if (i + 1 >= str.length) {
+                throw new Error("Invalid UTF‑16: isolated high surrogate");
+            }
+            const d = str.charCodeAt(i + 1);
+            if (d < 0xdc00 || d > 0xdfff) {
+                throw new Error("Invalid UTF‑16: high surrogate not followed by low surrogate");
+            }
+            // Valid surrogate pair → append both as-is
+            out += str[i] + str[i + 1];
+            i++; // skip the low surrogate
+            continue;
+        }
+        else if (c >= 0xdc00 && c <= 0xdfff) {
+            // Low surrogate without preceding high surrogate
+            throw new Error("Invalid UTF‑16: isolated low surrogate");
+        }
+        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 if present.
+    // JS already produces minimal mantissa/decimal representation.
+    let s = n.toString();
+    // Normalize exponent to RFC 8785 rules
+    const eIndex = s.indexOf("e");
+    if (eIndex !== -1) {
+        const mantissa = s.slice(0, eIndex);
+        let exp = s.slice(eIndex + 1); // after 'e'
+        const negative = exp.startsWith("-");
+        exp = exp.replace(/^[+-]/, "");
+        // Remove leading zeros in exponent
+        exp = exp.replace(/^0+/, "");
+        if (exp === "")
+            exp = "0";
+        // RFC 8785: exponent must not include "+"
+        s = `${mantissa}E${negative ? "-" : ""}${exp}`;
+    }
+    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), as required by RFC 8785
+    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/crypto-sign.d.ts

@@ -0,0 +1 @@
+export declare function signCanonical(canonical: string, privateKey: CryptoKey): Promise<ArrayBuffer>;

package/dist/crypto-sign.js

@@ -0,0 +1,8 @@
+const encoder = new TextEncoder();
+export async function signCanonical(canonical, privateKey) {
+    const bytes = encoder.encode(canonical);
+    return crypto.subtle.sign({
+        name: "RSA-PSS",
+        saltLength: 32
+    }, privateKey, bytes);
+}

package/dist/crypto-verify.d.ts

@@ -0,0 +1 @@
+export declare function verifyCanonical(canonical: string, signature: ArrayBuffer, publicKey: CryptoKey): Promise<boolean>;

package/dist/crypto-verify.js

@@ -0,0 +1,8 @@
+const encoder = new TextEncoder();
+export async function verifyCanonical(canonical, signature, publicKey) {
+    const bytes = encoder.encode(canonical);
+    return crypto.subtle.verify({
+        name: "RSA-PSS",
+        saltLength: 32
+    }, publicKey, signature, bytes);
+}

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/isJsonValue.d.ts

@@ -0,0 +1,4 @@
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare function isJsonValue(value: unknown): value is JsonValue;

package/dist/isJsonValue.js

@@ -0,0 +1,25 @@
+export function isJsonValue(value) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean") {
+        return true;
+    }
+    if (Array.isArray(value)) {
+        return value.every(isJsonValue);
+    }
+    // Objects (but not class instances, Dates, Maps, Sets, etc.)
+    if (typeof value === "object") {
+        const proto = Object.getPrototypeOf(value);
+        if (proto !== Object.prototype && proto !== null) {
+            return false;
+        }
+        for (const key of Object.keys(value)) {
+            if (!isJsonValue(value[key])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    return false;
+}

package/dist/keys.d.ts

@@ -0,0 +1,6 @@
+export declare function generateKeyPair(): Promise<{
+    privateKey: string;
+    publicKey: string;
+}>;
+export declare function importPrivateKey(privateKeyPem: string): Promise<CryptoKey>;
+export declare function importPublicKey(publicKeyPem: string): Promise<CryptoKey>;

package/dist/keys.js

@@ -0,0 +1,29 @@
+import { pemToArrayBuffer, arrayBufferToPem } from "./pem.js";
+export async function generateKeyPair() {
+    const { publicKey, privateKey } = await crypto.subtle.generateKey({
+        name: "RSA-PSS",
+        modulusLength: 2048,
+        publicExponent: new Uint8Array([1, 0, 1]),
+        hash: "SHA-256"
+    }, true, ["sign", "verify"]);
+    const pkcs8 = await crypto.subtle.exportKey("pkcs8", privateKey);
+    const spki = await crypto.subtle.exportKey("spki", publicKey);
+    return {
+        privateKey: arrayBufferToPem(pkcs8, "private"),
+        publicKey: arrayBufferToPem(spki, "public")
+    };
+}
+export async function importPrivateKey(privateKeyPem) {
+    const pkcs8 = pemToArrayBuffer(privateKeyPem);
+    return crypto.subtle.importKey("pkcs8", pkcs8, {
+        name: "RSA-PSS",
+        hash: "SHA-256"
+    }, false, ["sign"]);
+}
+export async function importPublicKey(publicKeyPem) {
+    const spki = pemToArrayBuffer(publicKeyPem);
+    return crypto.subtle.importKey("spki", spki, {
+        name: "RSA-PSS",
+        hash: "SHA-256"
+    }, false, ["verify"]);
+}

package/dist/pem.d.ts

@@ -0,0 +1,2 @@
+export declare function pemToArrayBuffer(pem: string): ArrayBuffer;
+export declare function arrayBufferToPem(buf: ArrayBuffer, type: "private" | "public"): string;

package/dist/pem.js

@@ -0,0 +1,19 @@
+import { arrayBufferToBase64, base64ToArrayBuffer } from "./base64.js";
+// strip header/footer + whitespace
+function pemBody(pem) {
+    return pem
+        .replace(/-----BEGIN [^-]+-----/, "")
+        .replace(/-----END [^-]+-----/, "")
+        .replace(/\s+/g, "");
+}
+export function pemToArrayBuffer(pem) {
+    const base64 = pemBody(pem);
+    return base64ToArrayBuffer(base64);
+}
+export function arrayBufferToPem(buf, type) {
+    const base64 = arrayBufferToBase64(buf);
+    if (type === "private") {
+        return `-----BEGIN PRIVATE KEY-----\n${base64}\n-----END PRIVATE KEY-----`;
+    }
+    return `-----BEGIN PUBLIC KEY-----\n${base64}\n-----END PUBLIC KEY-----`;
+}

package/dist/sign.d.ts

@@ -0,0 +1,10 @@
+export declare function signPayload(payload: any, privateKeyPem: string, publicKeyPem: string): Promise<{
+    version: number;
+    timestamp: string;
+    payload: import("./isJsonValue.js").JsonValue;
+    signature: {
+        algorithm: string;
+        publicKey: string;
+        value: string;
+    };
+}>;

package/dist/sign.js

@@ -0,0 +1,23 @@
+import { canonicalize } from "./canonicalize.js";
+import { importPrivateKey } from "./keys.js";
+import { signCanonical } from "./crypto-sign.js";
+import { arrayBufferToBase64 } from "./base64.js";
+import { isJsonValue } from "./isJsonValue.js";
+export async function signPayload(payload, privateKeyPem, publicKeyPem) {
+    if (!isJsonValue(payload))
+        throw new Error("signPayload only accepts JSON-compatible values");
+    const canonical = canonicalize(payload);
+    const privateKey = await importPrivateKey(privateKeyPem);
+    const signatureBytes = await signCanonical(canonical, privateKey);
+    const signature = arrayBufferToBase64(signatureBytes);
+    return {
+        version: 1,
+        timestamp: new Date().toISOString(),
+        payload,
+        signature: {
+            algorithm: "RSA-PSS-SHA256",
+            publicKey: publicKeyPem,
+            value: signature
+        }
+    };
+}

package/dist/verify.d.ts

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

package/dist/verify.js

@@ -0,0 +1,15 @@
+import { canonicalize } from "./canonicalize.js";
+import { importPublicKey } from "./keys.js";
+import { verifyCanonical } from "./crypto-verify.js";
+import { base64ToArrayBuffer } from "./base64.js";
+export async function verifyBackup(backup) {
+    const { payload, signature } = backup;
+    const canonical = canonicalize(payload);
+    const publicKey = await importPublicKey(signature.publicKey);
+    const signatureBytes = base64ToArrayBuffer(signature.value);
+    const valid = await verifyCanonical(canonical, signatureBytes, publicKey);
+    return {
+        valid,
+        payload: valid ? payload : undefined
+    };
+}

package/package.json

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