dignity.js 0.2.0 → 0.4.0

package/README.md

@@ -11,12 +11,13 @@
 </p>
 
 <p align="center">
+  <a href="https://jose-compu.github.io/dignity.js/"><img src="https://img.shields.io/badge/docs-online-5B7FFF" alt="documentation"></a>
   <a href="https://www.npmjs.com/package/dignity.js"><img src="https://img.shields.io/npm/v/dignity.js?color=cb3837&label=npm" alt="npm version"></a>
   <a href="https://www.npmjs.com/package/dignity.js"><img src="https://img.shields.io/npm/dm/dignity.js?color=blue" alt="npm downloads"></a>
-  <img src="https://img.shields.io/badge/tests-29%20passing-brightgreen" alt="tests passing">
-  <img src="https://img.shields.io/badge/coverage-88%25-brightgreen" alt="coverage">
-  <img src="https://img.shields.io/badge/license-MIT-black" alt="license">
-  <img src="https://img.shields.io/badge/minified-51KB-purple" alt="bundle size">
+  <a href="https://github.com/jose-compu/dignity.js/actions/workflows/ci.yml"><img src="https://github.com/jose-compu/dignity.js/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/badge/tests-150%2B%20passing-brightgreen" alt="tests passing">
+  <img src="https://img.shields.io/badge/coverage-99%25-brightgreen" alt="coverage">
+  <img src="https://img.shields.io/badge/license-Apache%202.0-black" alt="license">
 </p>
 
 REST-like P2P object API for decentralized JavaScript applications.
@@ -35,7 +36,10 @@ REST-like P2P object API for decentralized JavaScript applications.
   - default `powSteps: 22` (calibrated on this machine to about 1000ms)
   - automatic peer ban on invalid signature/PoW (`48h` default)
 - Team/subapp scoped broadcast passwords (`broadcastScope` + `broadcastPasswords`)
-- Browser-first distribution with minified build (`dist/dignity.min.js`)
+- Optimistic concurrency helpers (`expectedVersion`, `updateWithRetry`, `conflict` events)
+- Optional IndexedDB persistence for browser reload survival
+- Optional React hooks via `dignity.js/react`
+- Browser-first: published npm package includes IIFE, ESM, and CJS builds
 
 ## Install
 
@@ -146,15 +150,60 @@ bob.registerPeerPublicKey('alice', alice.getPublicKey());
 await alice.sendDirectMessage('bob', 'dm', { text: 'private payload' });
 ```
 
-## Browser Builds
+## Optimistic Concurrency
 
-Generated artifacts:
+Updates carry a monotonic `version`. Remote peers reject stale operations when `baseVersion` does not match.
 
-- `dist/dignity.min.js` (IIFE, global `DignityJS`)
-- `dist/dignity.esm.js` (ESM)
-- `dist/dignity.cjs.js` (CommonJS)
+```js
+node.on('conflict', (event) => {
+  console.log('conflict', event.phase, event.expectedVersion, event.currentVersion);
+});
+
+await node.update('games', 'g1', { score: 10 }, { expectedVersion: 3 });
+
+await node.updateWithRetry('games', 'g1', (current) => ({
+  score: current.data.score + 1
+}));
+```
+
+Use `expectedVersion` for fail-fast local writes. Use `updateWithRetry` for read-modify-write loops in fast multiplayer state.
+
+## IndexedDB Persistence
+
+Persist replicated collections across page reloads:
 
-Example with CDN:
+```js
+const { DignityP2P, IndexedDBPersistence } = require('dignity.js');
+
+const node = new DignityP2P({ nodeId, networkAdapter, security });
+const persistence = new IndexedDBPersistence({
+  dbName: 'my-app',
+  collections: ['games', 'matches']
+});
+
+await node.start();
+await persistence.attach(node);
+```
+
+## React Hooks
+
+Optional React integration (`react >= 18` peer dependency):
+
+```js
+import { useDignity, useCollection, usePeers } from 'dignity.js/react';
+
+function Room() {
+  const { node, status } = useDignity(config);
+  const games = useCollection(node, 'games');
+  const peers = usePeers(node, 'room:chess', { includeSelf: false });
+
+  return <pre>{JSON.stringify({ status, games, peers }, null, 2)}</pre>;
+}
+```
+
+## Browser Usage
+
+The published npm package includes pre-built bundles (IIFE, ESM, CJS) generated at publish time. The `dist/` folder is not checked into the repository.
 
 ```html
 <script src="https://unpkg.com/dignity.js/dist/dignity.min.js"></script>
@@ -163,6 +212,19 @@ Example with CDN:
 </script>
 ```
 
+## Security Model
+
+`dignity.js` provides two encryption modes:
+
+- **Direct mode** (`targetId` set): true end-to-end encryption using X25519 key exchange between sender and recipient. Only the intended recipient can decrypt.
+- **Broadcast mode** (no `targetId`): symmetric encryption using a shared password. All peers that know the password can decrypt all broadcast traffic in that scope. This is a **group shared-secret cipher**, not end-to-end encryption.
+
+Broadcast encryption uses PBKDF2-SHA256 (default 100,000 iterations) with a random salt per message to derive the symmetric key. This protects against offline brute-force of weak passwords. The iteration count is configurable via `kdfIterations`.
+
+Messages from peers running older versions that used the legacy single-hash KDF are still accepted and decrypted automatically (backward compatible).
+
+**Important:** if the broadcast password leaks, all past captured traffic for that scope is retroactively decryptable. For sensitive data, use direct mode with per-peer public keys.
+
 ## Signaling Servers
 
 Default signaling URLs include PeerJS-compatible public endpoints:
@@ -189,7 +251,8 @@ npm run test:pow-calibrate
 
 ## Docs and Examples
 
-- Docs site source: `docs/index.html`
+- **Documentation:** [jose-compu.github.io/dignity.js](https://jose-compu.github.io/dignity.js/)
+- Docs site source: `docs/index.html` (serve locally with `npm run docs:serve`)
 - API metadata: `docs/openapi-like.json`
 - Minimal demos:
   - `examples/decentralized-tictactoe.js`
@@ -198,11 +261,11 @@ npm run test:pow-calibrate
 ## Publish
 
 ```bash
-npm test
-npm run build
 npm publish --access public
 ```
 
+The `prepublishOnly` script runs tests and build automatically.
+
 ## License
 
-Apache 2.0
+Apache 2.0 — see [LICENSE](LICENSE).

package/dist/dignity.cjs.js

@@ -2434,7 +2434,8 @@ var require_message_security_service = __commonJS({
       broadcastPasswords: {},
       resolveBroadcastPassword: null,
       powSteps: 22,
-      trustedPeerKeys: {}
+      trustedPeerKeys: {},
+      kdfIterations: 1e5
     };
     function stableStringify(value) {
       if (value === null || typeof value !== "object") {
@@ -2461,6 +2462,33 @@ var require_message_security_service = __commonJS({
     function utf8ToBytes(value) {
       return naclUtil.decodeUTF8(value);
     }
+    async function deriveBroadcastKey(password, salt, iterations) {
+      const subtle = globalThis.crypto && globalThis.crypto.subtle;
+      if (subtle) {
+        const keyMaterial = await subtle.importKey(
+          "raw",
+          utf8ToBytes(password),
+          "PBKDF2",
+          false,
+          ["deriveBits"]
+        );
+        const bits = await subtle.deriveBits(
+          { name: "PBKDF2", salt, iterations, hash: "SHA-256" },
+          keyMaterial,
+          256
+        );
+        return new Uint8Array(bits);
+      }
+      try {
+        const { pbkdf2Sync } = require("crypto");
+        return new Uint8Array(pbkdf2Sync(password, Buffer.from(salt), iterations, 32, "sha256"));
+      } catch (_ignored) {
+        return hash32(concatBytes(utf8ToBytes(password), salt));
+      }
+    }
+    function legacyBroadcastKey(password, salt) {
+      return hash32(concatBytes(utf8ToBytes(password), salt));
+    }
     function normalizePeerPublicKey(publicKey) {
       if (!publicKey || typeof publicKey !== "object") {
         throw new Error("Public key must be an object with signingPublicKey and encryptionPublicKey");
@@ -2621,7 +2649,7 @@ var require_message_security_service = __commonJS({
         if (envelope.security && envelope.security.signing && envelope.security.signing.enabled && this.options.signingEnabled) {
           this.verifySignature(envelope);
         }
-        const payload = this.decryptPayload(envelope);
+        const payload = await this.decryptPayload(envelope);
         return {
           ignored: false,
           messageType: envelope.messageType,
@@ -2686,7 +2714,8 @@ var require_message_security_service = __commonJS({
         const nonce = nacl.randomBytes(nacl.secretbox.nonceLength);
         const salt = nacl.randomBytes(16);
         const password = this.resolveBroadcastPassword(scope);
-        const key = hash32(concatBytes(utf8ToBytes(password), salt));
+        const iterations = this.options.kdfIterations || DEFAULT_SECURITY_OPTIONS2.kdfIterations;
+        const key = await deriveBroadcastKey(password, salt, iterations);
         const encrypted = nacl.secretbox(plainText, nonce, key);
         return {
           payload: naclUtil.encodeBase64(encrypted),
@@ -2695,11 +2724,13 @@ var require_message_security_service = __commonJS({
             mode: "broadcast",
             scope,
             nonce: naclUtil.encodeBase64(nonce),
-            salt: naclUtil.encodeBase64(salt)
+            salt: naclUtil.encodeBase64(salt),
+            kdf: "pbkdf2",
+            kdfIterations: iterations
           }
         };
       }
-      decryptPayload(envelope) {
+      async decryptPayload(envelope) {
         const encryption = envelope.security ? envelope.security.encryption : null;
         if (!encryption || !encryption.enabled || !this.options.encryptionEnabled) {
           return envelope.payload;
@@ -2710,7 +2741,13 @@ var require_message_security_service = __commonJS({
           const password = this.resolveBroadcastPassword(scope);
           const salt = naclUtil.decodeBase64(encryption.salt);
           const nonce = naclUtil.decodeBase64(encryption.nonce);
-          const key = hash32(concatBytes(utf8ToBytes(password), salt));
+          let key;
+          if (encryption.kdf === "pbkdf2") {
+            const iterations = encryption.kdfIterations || DEFAULT_SECURITY_OPTIONS2.kdfIterations;
+            key = await deriveBroadcastKey(password, salt, iterations);
+          } else {
+            key = legacyBroadcastKey(password, salt);
+          }
           const decrypted = nacl.secretbox.open(encryptedBuffer, nonce, key);
           if (!decrypted) {
             throw new Error("Unable to decrypt broadcast payload");
@@ -2804,6 +2841,8 @@ var require_message_security_service = __commonJS({
     module2.exports = {
       MessageSecurityService: MessageSecurityService2,
       stableStringify,
+      deriveBroadcastKey,
+      legacyBroadcastKey,
       DEFAULT_SECURITY_OPTIONS: DEFAULT_SECURITY_OPTIONS2
     };
   }
@@ -2941,6 +2980,21 @@ var require_dignity_p2p = __commonJS({
         if (existing.ownerId !== this.nodeId) {
           throw new Error(`Only owner ${existing.ownerId} can update object ${id}`);
         }
+        if (typeof options.expectedVersion === "number" && existing.version !== options.expectedVersion) {
+          this.emitConflict({
+            kind: "update",
+            collection: collectionName,
+            id,
+            expectedVersion: options.expectedVersion,
+            currentVersion: existing.version,
+            phase: "local"
+          });
+          const error = new Error(
+            `Version conflict on ${collectionName}/${id}: expected ${options.expectedVersion}, current ${existing.version}`
+          );
+          error.code = "VERSION_CONFLICT";
+          throw error;
+        }
         const operation = {
           opId: this.idGenerator(),
           kind: "update",
@@ -2961,6 +3015,27 @@ var require_dignity_p2p = __commonJS({
         });
         return this.read(collectionName, id);
       }
+      async updateWithRetry(collectionName, id, patchFn, options = {}) {
+        const maxAttempts = typeof options.maxAttempts === "number" ? options.maxAttempts : 5;
+        for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+          const current = this.read(collectionName, id);
+          if (!current) {
+            throw new Error(`Object ${id} does not exist in ${collectionName}`);
+          }
+          const patch = await patchFn(current);
+          try {
+            return await this.update(collectionName, id, patch, {
+              ...options,
+              expectedVersion: current.version
+            });
+          } catch (error) {
+            if (error.code !== "VERSION_CONFLICT" || attempt === maxAttempts - 1) {
+              throw error;
+            }
+          }
+        }
+        throw new Error(`Unable to update ${collectionName}/${id} after ${maxAttempts} attempts`);
+      }
       async remove(collectionName, id, options = {}) {
         const existing = this.getCollection(collectionName).get(id);
         if (!existing || existing.deletedAt) {
@@ -3238,6 +3313,29 @@ var require_dignity_p2p = __commonJS({
       isPeerBanned(peerId) {
         return this.getBanInfo(peerId) !== null;
       }
+      emitConflict(details) {
+        this.emit("conflict", details);
+      }
+      restoreRecord(collectionName, record) {
+        if (!record || !record.id) {
+          return false;
+        }
+        const collection = this.getCollection(collectionName);
+        const current = collection.get(record.id);
+        if (current && current.version >= record.version) {
+          return false;
+        }
+        collection.set(record.id, {
+          id: record.id,
+          ownerId: record.ownerId,
+          data: { ...record.data || {} },
+          createdAt: record.createdAt,
+          updatedAt: record.updatedAt,
+          deletedAt: record.deletedAt || null,
+          version: record.version
+        });
+        return true;
+      }
       applyOperation(operation) {
         if (!operation || !operation.opId || this.appliedOperations.has(operation.opId)) {
           return false;
@@ -3268,6 +3366,15 @@ var require_dignity_p2p = __commonJS({
           return false;
         }
         if (typeof operation.baseVersion === "number" && operation.baseVersion !== current.version) {
+          this.emitConflict({
+            kind: operation.kind,
+            collection: operation.collectionName,
+            id: operation.id,
+            expectedVersion: operation.baseVersion,
+            currentVersion: current.version,
+            phase: "remote",
+            operation
+          });
           return false;
         }
         if (operation.kind === "update") {
@@ -10345,6 +10452,163 @@ var require_in_memory_network = __commonJS({
   }
 });
 
+// src/persistence/indexeddb-persistence.js
+var require_indexeddb_persistence = __commonJS({
+  "src/persistence/indexeddb-persistence.js"(exports2, module2) {
+    var IndexedDBPersistence2 = class {
+      constructor({
+        dbName = "dignity",
+        storeName = "records",
+        collections = null,
+        indexedDB = typeof globalThis !== "undefined" ? globalThis.indexedDB : null
+      } = {}) {
+        this.dbName = dbName;
+        this.storeName = storeName;
+        this.collections = collections;
+        this.indexedDB = indexedDB;
+        this.node = null;
+        this.changeHandler = null;
+      }
+      recordKey(collection, id) {
+        return `${collection}:${id}`;
+      }
+      shouldPersist(collection) {
+        if (!this.collections) {
+          return true;
+        }
+        return this.collections.includes(collection);
+      }
+      openDb() {
+        if (!this.indexedDB) {
+          return Promise.reject(new Error("IndexedDB is not available"));
+        }
+        return new Promise((resolve, reject) => {
+          const request = this.indexedDB.open(this.dbName, 1);
+          request.onupgradeneeded = () => {
+            const db = request.result;
+            if (!db.objectStoreNames.contains(this.storeName)) {
+              db.createObjectStore(this.storeName, { keyPath: "key" });
+            }
+          };
+          request.onsuccess = () => resolve(request.result);
+          request.onerror = () => reject(request.error || new Error("Unable to open IndexedDB"));
+        });
+      }
+      runTransaction(mode, handler) {
+        return this.openDb().then((db) => new Promise((resolve, reject) => {
+          const transaction = db.transaction(this.storeName, mode);
+          const store = transaction.objectStore(this.storeName);
+          Promise.resolve(handler(store)).then(resolve).catch(reject);
+          transaction.oncomplete = () => db.close();
+          transaction.onerror = () => reject(transaction.error || new Error("IndexedDB transaction failed"));
+          transaction.onabort = () => reject(transaction.error || new Error("IndexedDB transaction aborted"));
+        }));
+      }
+      serializeRecord(collection, id) {
+        const record = this.node.getCollection(collection).get(id);
+        if (!record) {
+          return null;
+        }
+        return {
+          key: this.recordKey(collection, id),
+          collection,
+          id,
+          ownerId: record.ownerId,
+          data: { ...record.data },
+          createdAt: record.createdAt,
+          updatedAt: record.updatedAt,
+          deletedAt: record.deletedAt,
+          version: record.version
+        };
+      }
+      async persistRecord(collection, id) {
+        if (!this.node || !this.shouldPersist(collection)) {
+          return;
+        }
+        const serialized = this.serializeRecord(collection, id);
+        const key = this.recordKey(collection, id);
+        if (!serialized) {
+          await this.runTransaction("readwrite", (store) => new Promise((resolve, reject) => {
+            const request = store.delete(key);
+            request.onsuccess = () => resolve();
+            request.onerror = () => reject(request.error);
+          }));
+          return;
+        }
+        await this.runTransaction("readwrite", (store) => new Promise((resolve, reject) => {
+          const request = store.put(serialized);
+          request.onsuccess = () => resolve();
+          request.onerror = () => reject(request.error);
+        }));
+      }
+      persistChange(event) {
+        if (!event || !event.collection || !event.id) {
+          return;
+        }
+        this.persistRecord(event.collection, event.id).catch((error) => {
+          this.node.emit("warning", {
+            type: "persistence-failed",
+            collection: event.collection,
+            id: event.id,
+            error
+          });
+        });
+      }
+      async loadAllRecords() {
+        return this.runTransaction("readonly", (store) => new Promise((resolve, reject) => {
+          const request = store.getAll();
+          request.onsuccess = () => resolve(request.result || []);
+          request.onerror = () => reject(request.error);
+        }));
+      }
+      async hydrate() {
+        if (!this.node) {
+          throw new Error("IndexedDBPersistence requires an attached node before hydrate");
+        }
+        const storedRecords = await this.loadAllRecords();
+        for (const stored of storedRecords) {
+          if (!this.shouldPersist(stored.collection)) {
+            continue;
+          }
+          this.node.restoreRecord(stored.collection, {
+            id: stored.id,
+            ownerId: stored.ownerId,
+            data: stored.data,
+            createdAt: stored.createdAt,
+            updatedAt: stored.updatedAt,
+            deletedAt: stored.deletedAt,
+            version: stored.version
+          });
+        }
+      }
+      async attach(node) {
+        if (!node) {
+          throw new Error("IndexedDBPersistence.attach requires a DignityP2P node");
+        }
+        this.node = node;
+        await this.hydrate();
+        this.changeHandler = (event) => this.persistChange(event);
+        node.on("change", this.changeHandler);
+      }
+      async detach() {
+        if (this.node && this.changeHandler) {
+          this.node.off("change", this.changeHandler);
+        }
+        this.changeHandler = null;
+        this.node = null;
+      }
+      async clear() {
+        await this.runTransaction("readwrite", (store) => new Promise((resolve, reject) => {
+          const request = store.clear();
+          request.onsuccess = () => resolve();
+          request.onerror = () => reject(request.error);
+        }));
+      }
+    };
+    module2.exports = IndexedDBPersistence2;
+  }
+});
+
 // src/index.js
 var DignityP2P = require_dignity_p2p();
 var createDefaultSignalingPool = require_create_default_signaling_pool();
@@ -10355,6 +10619,7 @@ var {
   InMemoryNetworkHub,
   InMemoryNetworkAdapter
 } = require_in_memory_network();
+var IndexedDBPersistence = require_indexeddb_persistence();
 var {
   DEFAULT_CLOUDFLARE_SIGNALING_URLS,
   DEFAULT_SIGNALING_FALLBACK_URLS
@@ -10373,6 +10638,7 @@ module.exports = {
   PeerJSSignalingProvider,
   InMemoryNetworkHub,
   InMemoryNetworkAdapter,
+  IndexedDBPersistence,
   DEFAULT_CLOUDFLARE_SIGNALING_URLS,
   DEFAULT_SIGNALING_FALLBACK_URLS,
   VDF,