json-seal 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Myers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,280 @@
+# **json‑seal**
+
+Cryptographically signed, tamper‑proof JSON backups for apps - zero dependencies and a tiny footprint under 5 kB.
+
+json‑seal lets you:
+
+- Canonicalize any JSON object  
+- 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**.
+
+---
+
+## **Why json‑seal exists**
+
+Most security libraries focus on:
+
+- encrypted blobs (iron‑webcrypto)  
+- authentication tokens (JOSE/JWS/JWT)  
+- low‑level primitives (WebCrypto, libsodium)  
+
+None of these solves the problem of:
+
+**“I need to store or transmit JSON in a way that guarantees it hasn’t been tampered with - while keeping it readable, portable, and framework‑agnostic.”**
+
+json‑seal fills that gap.
+
+It turns any JSON object into a **sealed artifact** that can be verified anywhere, on any device, without servers, shared secrets, or opaque binary formats. The result is a portable, human‑readable, cryptographically signed JSON document that remains trustworthy for years.
+
+---
+
+## **Features**
+
+### **Deterministic canonicalization**  
+Stable, cross‑platform byte representation of JSON for reliable signatures.  
+If the JSON changes - even whitespace - verification fails.
+
+### **RSA‑PSS digital signatures**  
+Modern, secure, asymmetric signing using the WebCrypto API.
+No shared passwords, no symmetric secrets, no server dependency.
+
+### **Pure JSON seal format**
+Human‑readable, portable, and easy to store, sync, export, or transmit.  
+Everything needed for verification is embedded.
+
+### **Browser + Node support**
+Works anywhere `crypto.subtle` is available - modern browsers, PWAs, Node 18+, Bun, Deno, and edge runtimes.
+
+### **Framework‑agnostic**
+Angular, React, Vue, Svelte, Ionic, Capacitor, PWAs, Node, Bun, Deno - json‑seal fits everywhere.
+
+### **Zero dependencies** 
+Small, auditable, and safe for long‑term use.
+No polyfills, no crypto libraries, no runtime baggage.
+
+### **Perfect for offline‑first apps**
+Protects:
+
+- Local storage
+- IndexedDB
+- Sync engines
+- User‑exported backups
+- Cross‑device data portability
+
+json‑seal is built for apps that need **trustworthy, tamper‑proof JSON**, not tokens or encrypted blobs.
+
+---
+
+## **Installation**
+
+```bash
+npm install json-seal
+```
+
+---
+
+## **Quick Start**
+
+### **Generate a keypair**
+
+```ts
+import { generateKeyPair } from "json-seal";
+
+const { privateKey, publicKey } = await generateKeyPair();
+```
+
+### **Sign a payload**
+
+```ts
+import { signPayload } from "json-seal";
+
+const payload = { id: 1, data: "hello" };
+
+const backup = await signPayload(payload, privateKey, publicKey);
+```
+
+### **Verify a backup**
+
+```ts
+import { verifyBackup } from "json-seal";
+
+const result = await verifyBackup(backup);
+
+if (result.valid) {
+  console.log("Payload:", result.payload);
+}
+```
+
+---
+
+## **What a signed backup looks like**
+
+```json
+{
+  "version": 1,
+  "timestamp": "2026-01-11T18:24:55.402Z",
+  "payload": { "id": 1, "data": "hello" },
+  "signature": {
+    "algorithm": "RSA-PSS-SHA256",
+    "publicKey": "-----BEGIN PUBLIC KEY----- ...",
+    "value": "base64-signature"
+  }
+}
+```
+
+Everything needed to verify the backup is embedded.
+
+---
+
+## **Tamper Detection**
+
+Any modification - even deep inside nested objects - invalidates the signature.
+
+```ts
+const tampered = { ...backup, payload: { id: 1, data: "hacked" } };
+
+verifyBackup(tampered).valid; // false
+```
+
+---
+
+## **Key Management**
+
+`generateKeyPair()` should be called **once**, not on every backup.  
+Apps are expected to generate or receive a keypair during onboarding and store it securely.
+
+---
+
+### **App‑generated keys**
+
+Most offline‑first apps generate a keypair on first launch:
+
+```ts
+import { generateKeyPair } from "json-seal";
+
+const { privateKey, publicKey } = await generateKeyPair();
+
+secureStore.set("privateKey", privateKey);
+secureStore.set("publicKey", publicKey);
+```
+
+On subsequent runs:
+
+```ts
+const privateKey = secureStore.get("privateKey");
+const publicKey = secureStore.get("publicKey");
+
+const backup = await signPayload(data, privateKey, publicKey);
+```
+
+---
+
+### **Where to store keys**
+
+Storage depends on the platform:
+
+- iOS → Keychain  
+- Android → Keystore  
+- Web → IndexedDB + WebCrypto  
+- Desktop → OS keyring or encrypted local file  
+- Node → environment variables or encrypted file  
+
+json‑seal intentionally does **not** handle storage so it can remain environment‑agnostic.
+
+---
+
+### **Server‑generated keys**
+
+Some architectures prefer the backend to generate and manage keys:
+
+1. Server generates keypair  
+2. Server stores private key  
+3. Server sends public key to the app  
+4. App signs backups using the server’s public key  
+5. Server verifies integrity later  
+
+Useful for multi‑device accounts or enterprise systems.
+
+---
+
+### **Key rotation**
+
+json‑seal embeds the public key inside each backup, so old backups remain verifiable even after rotation.
+
+Typical strategy:
+
+- generate a new keypair yearly  
+- store the new private key  
+- keep old public keys for verification  
+- continue verifying old backups without breaking anything  
+
+---
+
+### **Importing and exporting keys**
+
+Keys are standard PEM strings, so they can be:
+
+- backed up  
+- migrated  
+- synced  
+- exported/imported  
+
+Perfect for long‑term, portable backup formats.
+
+---
+
+## **API**
+
+### **`generateKeyPair()`**
+Generates a 2048‑bit RSA‑PSS keypair using WebCrypto.
+
+### **`signPayload(payload, privateKey, publicKey)`**
+- Canonicalizes the JSON  
+- Signs it using RSA‑PSS SHA‑256  
+- Embeds the public key  
+- Returns a portable backup object  
+
+### **`verifyBackup(backup)`**
+- Re‑canonicalizes the payload  
+- Verifies the signature  
+- Returns `{ valid: boolean, payload?: any }`  
+
+### **`canonicalize(obj)`**
+Deterministic JSON serializer with sorted keys.
+
+---
+
+## **Testing**
+
+json‑seal ships with a full Vitest suite covering:
+
+- Valid signatures  
+- Shallow tampering  
+- Deep tampering  
+- Missing signature  
+- Wrong public key  
+- Corrupted signature  
+- Canonicalization stability  
+- Large payloads  
+- Arrays and primitives  
+- RSA‑PSS non‑determinism  
+
+Run tests:
+
+```bash
+npm test
+```
+
+---
+
+Pull Requests welcome.
+
+## **License**
+
+MIT
+
+---

package/dist/canonicalize.d.ts

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

package/dist/canonicalize.js

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

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

package/dist/index.js

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

package/dist/sign.d.ts

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

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

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

package/dist/verify.js

@@ -0,0 +1,19 @@
+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
+    };
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "json-seal",
+  "version": "0.9.0",
+  "description": "Cryptographically signed, tamper‑proof JSON backups with deterministic canonicalization and RSA‑PSS signatures.",
+  "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"
+  }
+}