json-seal 0.11.0 → 0.11.2

package/README.md

@@ -18,9 +18,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:
 
@@ -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.
 
 ---
 
@@ -45,7 +45,7 @@ It’s like JWS, but for **arbitrary JSON documents**, without JWT complexity, a
 - 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 +170,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" } };
@@ -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/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/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

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

package/dist/index.js

@@ -1,3 +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

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

package/dist/sign.js

@@ -1,25 +1,15 @@
-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) {
+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 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");
+    const privateKey = await importPrivateKey(privateKeyPem);
+    const signatureBytes = await signCanonical(canonical, privateKey);
+    const signature = arrayBufferToBase64(signatureBytes);
     return {
         version: 1,
         timestamp: new Date().toISOString(),

package/dist/verify.d.ts

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

package/dist/verify.js

@@ -1,17 +1,13 @@
-import { createVerify, constants } from "crypto";
 import { canonicalize } from "./canonicalize.js";
-export function verifyBackup(backup) {
+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 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"));
+    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.0",
+  "version": "0.11.2",
   "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",