dignity.js 0.1.2 → 0.3.0

package/README.md

@@ -13,10 +13,9 @@
 <p align="center">
   <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">
+  <img src="https://img.shields.io/badge/tests-122%20passing-brightgreen" alt="tests passing">
+  <img src="https://img.shields.io/badge/coverage-97%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 +34,7 @@ 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`)
+- Browser-first: published npm package includes IIFE, ESM, and CJS builds
 
 ## Install
 
@@ -146,15 +145,9 @@ bob.registerPeerPublicKey('alice', alice.getPublicKey());
 await alice.sendDirectMessage('bob', 'dm', { text: 'private payload' });
 ```
 
-## Browser Builds
+## Browser Usage
 
-Generated artifacts:
-
-- `dist/dignity.min.js` (IIFE, global `DignityJS`)
-- `dist/dignity.esm.js` (ESM)
-- `dist/dignity.cjs.js` (CommonJS)
-
-Example with CDN:
+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 +156,32 @@ 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:
+
+- `wss://peerjs.92k.de/peerjs?key=peerjs`
+- `wss://0.peerjs.com/peerjs?key=peerjs`
+
+You can also deploy your own server with [peerjs-server](https://github.com/peers/peerjs-server) and point `createDefaultSignalingPool` (or `WebSocketSignalingProvider`) to your own `wss://.../peerjs?key=...` URL.
+
+Compatibility note:
+- `dignity.js` now includes a dedicated `PeerJSSignalingProvider` backed by the official `peerjs` client for PeerJS protocol compatibility.
+- In non-WebRTC runtimes (for example Node test runners), it automatically falls back to WebSocket transport checks for connectivity testing.
+
 ## Development
 
 ```bash
@@ -185,11 +204,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).