dignity.js 0.5.2 → 0.5.4

package/README.md

@@ -1,24 +1,14 @@
 # dignity.js
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/jose-compu/dignity.js/refs/heads/main/docs/assets/dignity-logo.svg" alt="dignity.js logo" width="860" />
-</p>
-
-<p align="center">
-  <img src="https://img.shields.io/badge/dignity.js-decentralized%20object%20api-5B7FFF?style=for-the-badge" alt="dignity.js" />
-  <img src="https://img.shields.io/badge/browser-first-00C2A8?style=for-the-badge" alt="browser-first" />
-  <img src="https://img.shields.io/badge/security-default%20on-111827?style=for-the-badge" alt="security default on" />
-</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>
-  <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>
+![dignity.js logo](https://raw.githubusercontent.com/jose-compu/dignity.js/refs/heads/main/docs/assets/dignity-logo.png)
+
+[![docs](https://img.shields.io/badge/docs-online-5B7FFF)](https://jose-compu.github.io/dignity.js/)
+[![npm version](https://img.shields.io/npm/v/dignity.js?color=cb3837&label=npm)](https://www.npmjs.com/package/dignity.js)
+[![npm downloads](https://img.shields.io/npm/dm/dignity.js?color=blue)](https://www.npmjs.com/package/dignity.js)
+[![CI](https://github.com/jose-compu/dignity.js/actions/workflows/ci.yml/badge.svg)](https://github.com/jose-compu/dignity.js/actions/workflows/ci.yml)
+![tests](https://img.shields.io/badge/tests-150%2B%20passing-brightgreen)
+![coverage](https://img.shields.io/badge/coverage-99%25-brightgreen)
+![license](https://img.shields.io/badge/license-Apache%202.0-black)
 
 REST-like P2P object API for decentralized JavaScript applications.
 
@@ -39,6 +29,7 @@ REST-like P2P object API for decentralized JavaScript applications.
 - Optimistic concurrency helpers (`expectedVersion`, `updateWithRetry`, `conflict` events)
 - PeerJS mesh bootstrap: connect before announce/broadcast, auto `publicKey` in presence
 - Late-joiner sync via `pushRecordSnapshot` (full record catch-up when create was missed)
+- Content hashes on active records via `record.hash` (`sha512:` over canonicalized `data`)
 - Auto `connectToPeers` on create/update/delete replication (owner + collaborators)
 - Optional IndexedDB persistence for browser reload survival
 - Optional React hooks via `dignity.js/react`
@@ -171,6 +162,23 @@ await node.updateWithRetry('games', 'g1', (current) => ({
 
 Use `expectedVersion` for fail-fast local writes. Use `updateWithRetry` for read-modify-write loops in fast multiplayer state.
 
+## Record Content Hashes
+
+Active records returned by `create`, `read`, `list`, `update`, and `pushRecordSnapshot` include a `hash` field:
+
+```js
+const record = await node.create('notes', { title: 'hello' }, { id: 'n1' });
+console.log(record.hash); // sha512:...
+```
+
+Hash details:
+
+- The algorithm is `sha512`, matching `tweetnacl.hash` in both browser and Node builds.
+- The digest covers only `record.data`, not `id`, `ownerId`, timestamps, collaborators, or version.
+- Data is canonicalized with `stableStringify`, so object key order does not affect the hash.
+- Snapshot restore recomputes the digest locally and emits a `warning` with type `content-hash-mismatch` if a remote advertised hash does not match the received `data`.
+- Deleted tombstones returned by `list(collection, { includeDeleted: true })` intentionally omit `hash`.
+
 ## IndexedDB Persistence
 
 Persist replicated collections across page reloads:
@@ -193,6 +201,7 @@ await persistence.attach(node);
 Optional React integration (`react >= 18` peer dependency):
 
 ```js
+import { createElement } from 'react';
 import { useDignity, useCollection, usePeers } from 'dignity.js/react';
 
 function Room() {
@@ -200,7 +209,7 @@ function Room() {
   const games = useCollection(node, 'games');
   const peers = usePeers(node, 'room:chess', { includeSelf: false });
 
-  return <pre>{JSON.stringify({ status, games, peers }, null, 2)}</pre>;
+  return createElement('pre', null, JSON.stringify({ status, games, peers }, null, 2));
 }
 ```
 
@@ -208,7 +217,7 @@ function Room() {
 
 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
+```text
 <script src="https://unpkg.com/dignity.js/dist/dignity.min.js"></script>
 <script>
   const { DignityP2P } = DignityJS;
@@ -300,6 +309,24 @@ The joiner applies the snapshot via `restoreRecord`, then subsequent move update
 
 ## Development
 
+| Script | Purpose | Notes |
+| --- | --- | --- |
+| `npm test` | Run the full Jest suite with coverage. | Standard local validation before opening a PR or publishing. |
+| `npm run test:unit` | Run the unit-test subset only. | Useful for faster local iteration. |
+| `npm run test:cloudflare-live` | Run the live Cloudflare signaling integration test. | Opt-in; set `RUN_CLOUDFLARE_LIVE_TESTS=1`. |
+| `npm run test:pow-calibrate` | Run the Sloth VDF timing calibration test without coverage. | Opt-in; set `RUN_POW_CALIBRATE=1`. |
+| `npm run build` | Build the published package bundles into `dist/`. | Run after changing library source files. |
+| `npm run build:chess` | Rebuild the browser chess demo bundle only. | Used by the docs site and local chess demo. |
+| `npm run docs:favicon` | Regenerate the docs favicon assets. | Docs maintenance helper. |
+| `npm run docs:build` | Build the docs-specific assets. | Currently rebuilds the chess demo bundle. |
+| `npm run docs:dev` | Start the local docs server. | Serves the main docs and chess demo; auto-builds chess if needed. |
+| `npm run docs:serve` | Start the same local docs server via an alias. | Equivalent to `docs:dev`. |
+| `npm run docs:stop` | Stop the background docs server from a previous run. | Useful if port `4173` is stuck. |
+| `npm run docs:check` | Verify the generated docs assets exist. | Good quick check after docs asset generation. |
+| `npm run example:tictactoe` | Run the Node tic-tac-toe example. | Demonstrates a minimal replicated game flow. |
+| `npm run example:chess` | Run the Node chess example. | Demonstrates the lighter-weight chess sample. |
+| `npm run prepublishOnly` | Run the publish gate locally. | Publish/CI-oriented hook; runs tests and build before `npm publish`. |
+
 ```bash
 npm test
 npm run build

package/dist/dignity.cjs.js

@@ -3,43 +3,6 @@ var __commonJS = (cb, mod) => function __require() {
   return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
 };
 
-// src/utils/event-emitter.js
-var require_event_emitter = __commonJS({
-  "src/utils/event-emitter.js"(exports2, module2) {
-    var EventEmitter = class {
-      constructor() {
-        this.handlers = /* @__PURE__ */ new Map();
-      }
-      on(eventName, handler) {
-        if (!this.handlers.has(eventName)) {
-          this.handlers.set(eventName, /* @__PURE__ */ new Set());
-        }
-        this.handlers.get(eventName).add(handler);
-      }
-      off(eventName, handler) {
-        const eventHandlers = this.handlers.get(eventName);
-        if (!eventHandlers) {
-          return;
-        }
-        eventHandlers.delete(handler);
-        if (eventHandlers.size === 0) {
-          this.handlers.delete(eventName);
-        }
-      }
-      emit(eventName, payload) {
-        const eventHandlers = this.handlers.get(eventName);
-        if (!eventHandlers) {
-          return;
-        }
-        for (const handler of eventHandlers) {
-          handler(payload);
-        }
-      }
-    };
-    module2.exports = EventEmitter;
-  }
-});
-
 // node_modules/tweetnacl/nacl-fast.js
 var require_nacl_fast = __commonJS({
   "node_modules/tweetnacl/nacl-fast.js"(exports2, module2) {
@@ -2330,6 +2293,43 @@ var require_nacl_util = __commonJS({
   }
 });
 
+// src/utils/event-emitter.js
+var require_event_emitter = __commonJS({
+  "src/utils/event-emitter.js"(exports2, module2) {
+    var EventEmitter = class {
+      constructor() {
+        this.handlers = /* @__PURE__ */ new Map();
+      }
+      on(eventName, handler) {
+        if (!this.handlers.has(eventName)) {
+          this.handlers.set(eventName, /* @__PURE__ */ new Set());
+        }
+        this.handlers.get(eventName).add(handler);
+      }
+      off(eventName, handler) {
+        const eventHandlers = this.handlers.get(eventName);
+        if (!eventHandlers) {
+          return;
+        }
+        eventHandlers.delete(handler);
+        if (eventHandlers.size === 0) {
+          this.handlers.delete(eventName);
+        }
+      }
+      emit(eventName, payload) {
+        const eventHandlers = this.handlers.get(eventName);
+        if (!eventHandlers) {
+          return;
+        }
+        for (const handler of eventHandlers) {
+          handler(payload);
+        }
+      }
+    };
+    module2.exports = EventEmitter;
+  }
+});
+
 // src/security/sloth-vdf.js
 var require_sloth_vdf = __commonJS({
   "src/security/sloth-vdf.js"(exports2, module2) {
@@ -2337,6 +2337,12 @@ var require_sloth_vdf = __commonJS({
       static p = BigInt(
         "170082004324204494273811327264862981553264701145937538369570764779791492622392118654022654452947093285873855529044371650895045691292912712699015605832276411308653107069798639938826015099738961427172366594187783204437869906954750443653318078358839409699824714551430573905637228307966826784684174483831608534979"
       );
+      // precompute values for optimization:
+      // (p - 1) / 2
+      static pHalf = _SlothPermutation.p - BigInt(1) >> BigInt(1);
+      // (p + 1) / 4
+      // p ≡ 3 (mod 4) ⇒ (p+1) divisible by 4
+      static pQuarter = _SlothPermutation.p + BigInt(1) >> BigInt(2);
       fastPow(base, exponent, modulus) {
         if (modulus === BigInt(1)) {
           return BigInt(0);
@@ -2345,25 +2351,25 @@ var require_sloth_vdf = __commonJS({
         let powBase = base % modulus;
         let powExponent = exponent;
         while (powExponent > 0) {
-          if (powExponent % BigInt(2) === BigInt(1)) {
+          if ((powExponent & BigInt(1)) === BigInt(1)) {
             result = result * powBase % modulus;
           }
-          powExponent = powExponent / BigInt(2);
+          powExponent = powExponent >> BigInt(1);
           powBase = powBase * powBase % modulus;
         }
         return result;
       }
       quadRes(x) {
-        return this.fastPow(x, (_SlothPermutation.p - BigInt(1)) / BigInt(2), _SlothPermutation.p) === BigInt(1);
+        return this.fastPow(x, _SlothPermutation.pHalf, _SlothPermutation.p) === BigInt(1);
       }
       modSqrtOp(x) {
         let y;
         let value = x;
         if (this.quadRes(value)) {
-          y = this.fastPow(value, (_SlothPermutation.p + BigInt(1)) / BigInt(4), _SlothPermutation.p);
+          y = this.fastPow(value, _SlothPermutation.pQuarter, _SlothPermutation.p);
         } else {
           value = (-value + _SlothPermutation.p) % _SlothPermutation.p;
-          y = this.fastPow(value, (_SlothPermutation.p + BigInt(1)) / BigInt(4), _SlothPermutation.p);
+          y = this.fastPow(value, _SlothPermutation.pQuarter, _SlothPermutation.p);
         }
         return y;
       }
@@ -2851,8 +2857,17 @@ var require_message_security_service = __commonJS({
 // src/core/dignity-p2p.js
 var require_dignity_p2p = __commonJS({
   "src/core/dignity-p2p.js"(exports2, module2) {
+    var nacl = require_nacl_fast();
+    var naclUtil = require_nacl_util();
     var EventEmitter = require_event_emitter();
-    var { MessageSecurityService: MessageSecurityService2 } = require_message_security_service();
+    var { MessageSecurityService: MessageSecurityService2, stableStringify } = require_message_security_service();
+    function computeContentHash(data) {
+      const canonical = stableStringify(data || {});
+      const bytes = naclUtil.decodeUTF8(canonical);
+      const hash = nacl.hash(bytes);
+      const hex = Array.from(hash, (b) => b.toString(16).padStart(2, "0")).join("");
+      return `sha512:${hex}`;
+    }
     var DignityP2P2 = class extends EventEmitter {
       constructor({ nodeId, networkAdapter, idGenerator, now, security } = {}) {
         super();
@@ -2911,6 +2926,7 @@ var require_dignity_p2p = __commonJS({
         if (!record || record.deletedAt) {
           return null;
         }
+        const normalizedData = { ...record.data || {} };
         return {
           id: record.id,
           ownerId: record.ownerId,
@@ -2918,7 +2934,8 @@ var require_dignity_p2p = __commonJS({
           createdAt: record.createdAt,
           updatedAt: record.updatedAt,
           version: record.version,
-          data: { ...record.data }
+          hash: record.hash || computeContentHash(normalizedData),
+          data: normalizedData
         };
       }
       canUpdateRecord(record, actorId) {
@@ -2996,7 +3013,7 @@ var require_dignity_p2p = __commonJS({
           ownerId: this.nodeId,
           collaboratorIds,
           timestamp,
-          payload: { ...data }
+          payload: { ...data || {} }
         };
         this.applyOperation(operation);
         await this.broadcastMessage("operation", operation, {
@@ -3529,11 +3546,23 @@ var require_dignity_p2p = __commonJS({
         if (current && current.version >= record.version) {
           return false;
         }
+        const restoredData = { ...record.data || {} };
+        const computedHash = computeContentHash(restoredData);
+        if (record.hash && record.hash !== computedHash) {
+          this.emit("warning", {
+            type: "content-hash-mismatch",
+            collection: collectionName,
+            id: record.id,
+            advertisedHash: record.hash,
+            computedHash
+          });
+        }
         collection.set(record.id, {
           id: record.id,
           ownerId: record.ownerId,
           collaboratorIds: this.normalizeCollaboratorIds(record.collaboratorIds),
-          data: { ...record.data || {} },
+          data: restoredData,
+          hash: computedHash,
           createdAt: record.createdAt,
           updatedAt: record.updatedAt,
           deletedAt: record.deletedAt || null,
@@ -3551,7 +3580,8 @@ var require_dignity_p2p = __commonJS({
           id: raw.id,
           ownerId: raw.ownerId,
           collaboratorIds: Array.isArray(raw.collaboratorIds) ? [...raw.collaboratorIds] : [],
-          data: { ...raw.data },
+          data: { ...raw.data || {} },
+          hash: raw.hash || computeContentHash(raw.data || {}),
           createdAt: raw.createdAt,
           updatedAt: raw.updatedAt,
           deletedAt: raw.deletedAt || null,
@@ -3581,7 +3611,8 @@ var require_dignity_p2p = __commonJS({
             id: operation.id,
             ownerId: operation.ownerId,
             collaboratorIds: this.normalizeCollaboratorIds(operation.collaboratorIds),
-            data: { ...operation.payload },
+            data: { ...operation.payload || {} },
+            hash: computeContentHash(operation.payload || {}),
             createdAt: operation.timestamp,
             updatedAt: operation.timestamp,
             deletedAt: null,
@@ -3684,6 +3715,7 @@ var require_dignity_p2p = __commonJS({
             ...current.data,
             ...operation.payload
           };
+          current.hash = computeContentHash(current.data);
           if (Array.isArray(operation.collaboratorIds) && operation.actorId === current.ownerId) {
             current.collaboratorIds = this.normalizeCollaboratorIds(operation.collaboratorIds);
           }
@@ -3769,6 +3801,14 @@ var require_signaling_pool = __commonJS({
 // src/signaling/websocket-signaling-provider.js
 var require_websocket_signaling_provider = __commonJS({
   "src/signaling/websocket-signaling-provider.js"(exports2, module2) {
+    function randomBase36(length) {
+      let value = "";
+      while (value.length < length) {
+        const chunk = Math.random().toString(36).slice(2);
+        value += chunk.length > 0 ? chunk : "0";
+      }
+      return value.slice(0, length);
+    }
     var WebSocketSignalingProvider2 = class {
       constructor({ id, url, WebSocketImpl, priority = 0 }) {
         if (!url) {
@@ -3812,8 +3852,8 @@ var require_websocket_signaling_provider = __commonJS({
         if (!peerJsHostPattern.test(this.url)) {
           return this.url;
         }
-        const connectionId = `dignityjs_${Math.random().toString(36).slice(2, 12)}`;
-        const token = Math.random().toString(36).slice(2, 12);
+        const connectionId = `dignityjs_${randomBase36(10)}`;
+        const token = randomBase36(10);
         const hasQuery = this.url.includes("?");
         const hasId = /[?&]id=/.test(this.url);
         const hasToken = /[?&]token=/.test(this.url);
@@ -11029,6 +11069,7 @@ var require_indexeddb_persistence = __commonJS({
           ownerId: record.ownerId,
           collaboratorIds: Array.isArray(record.collaboratorIds) ? [...record.collaboratorIds] : [],
           data: { ...record.data },
+          hash: record.hash || null,
           createdAt: record.createdAt,
           updatedAt: record.updatedAt,
           deletedAt: record.deletedAt,
@@ -11089,6 +11130,7 @@ var require_indexeddb_persistence = __commonJS({
             ownerId: stored.ownerId,
             collaboratorIds: stored.collaboratorIds,
             data: stored.data,
+            hash: stored.hash || null,
             createdAt: stored.createdAt,
             updatedAt: stored.updatedAt,
             deletedAt: stored.deletedAt,