dignity.js 0.6.0 → 0.7.1

package/docs/assets/playground-demos.js

@@ -0,0 +1,342 @@
+/**
+ * Live playground examples — browser-safe, in-memory mesh, PoW disabled for speed.
+ * User code receives: dignity (namespace), log (...args), helpers.
+ */
+export const PLAYGROUND_DEMOS = [
+  {
+    id: 'two-peers-crud',
+    title: 'Two peers — create & read',
+    description: 'Wire alice and bob through InMemoryNetworkHub; replicate one object.',
+    code: `const { DignityP2P, InMemoryNetworkHub, InMemoryNetworkAdapter } = dignity;
+
+const hub = new InMemoryNetworkHub();
+const security = helpers.fastSecurity();
+
+const alice = new DignityP2P({
+  nodeId: 'alice',
+  networkAdapter: new InMemoryNetworkAdapter(hub),
+  security
+});
+const bob = new DignityP2P({
+  nodeId: 'bob',
+  networkAdapter: new InMemoryNetworkAdapter(hub),
+  security
+});
+
+helpers.track(alice, bob);
+await alice.start();
+await bob.start();
+
+await alice.create('notes', { title: 'hello decentralized world' }, { id: 'note-1' });
+await helpers.sleep(30);
+
+const onBob = bob.read('notes', 'note-1');
+log('bob.read:', JSON.stringify(onBob?.data));
+
+await alice.stop();
+await bob.stop();`
+  },
+  {
+    id: 'room-discovery',
+    title: 'Room discovery — list peers',
+    description: 'joinDiscovery on a shared scope and list who is in the room.',
+    code: `const { DignityP2P, InMemoryNetworkHub, InMemoryNetworkAdapter } = dignity;
+
+const hub = new InMemoryNetworkHub();
+const security = helpers.fastSecurity();
+
+const alice = new DignityP2P({ nodeId: 'alice', networkAdapter: new InMemoryNetworkAdapter(hub), security });
+const bob = new DignityP2P({ nodeId: 'bob', networkAdapter: new InMemoryNetworkAdapter(hub), security });
+const carol = new DignityP2P({ nodeId: 'carol', networkAdapter: new InMemoryNetworkAdapter(hub), security });
+
+helpers.track(alice, bob, carol);
+await alice.start();
+await bob.start();
+await carol.start();
+
+await alice.joinDiscovery('lobby', { metadata: { nickname: 'Alice' } });
+await bob.joinDiscovery('lobby', { metadata: { nickname: 'Bob' } });
+await carol.joinDiscovery('lobby', { metadata: { nickname: 'Carol' } });
+await helpers.sleep(40);
+
+const peers = alice.listPeers('lobby', { includeSelf: false });
+log('Peers in lobby:', peers.map((p) => p.peerId).join(', '));
+log('Count:', peers.length);
+
+await alice.leaveDiscovery('lobby');
+await bob.leaveDiscovery('lobby');
+await carol.leaveDiscovery('lobby');
+await alice.stop();
+await bob.stop();
+await carol.stop();`
+  },
+  {
+    id: 'ownership',
+    title: 'Ownership — only owner updates',
+    description: 'Bob cannot update alice-owned record; alice can.',
+    code: `const { DignityP2P, InMemoryNetworkHub, InMemoryNetworkAdapter } = dignity;
+
+const hub = new InMemoryNetworkHub();
+const security = helpers.fastSecurity();
+
+const alice = new DignityP2P({ nodeId: 'alice', networkAdapter: new InMemoryNetworkAdapter(hub), security });
+const bob = new DignityP2P({ nodeId: 'bob', networkAdapter: new InMemoryNetworkAdapter(hub), security });
+helpers.track(alice, bob);
+await alice.start();
+await bob.start();
+
+await alice.create('games', { score: 0 }, { id: 'g1' });
+await helpers.sleep(20);
+
+let bobError = null;
+try {
+  await bob.update('games', 'g1', { score: 99 });
+} catch (err) {
+  bobError = err.message;
+}
+log('bob update rejected:', bobError || 'unexpected success');
+
+await alice.update('games', 'g1', { score: 10 });
+await helpers.sleep(20);
+log('after alice update:', bob.read('games', 'g1')?.data);
+
+await alice.stop();
+await bob.stop();`
+  },
+  {
+    id: 'collaborators',
+    title: 'Collaborators — shared edit rights',
+    description: 'Owner grants bob collaborator access on one record.',
+    code: `const { DignityP2P, InMemoryNetworkHub, InMemoryNetworkAdapter } = dignity;
+
+const hub = new InMemoryNetworkHub();
+const security = helpers.fastSecurity();
+
+const alice = new DignityP2P({ nodeId: 'alice', networkAdapter: new InMemoryNetworkAdapter(hub), security });
+const bob = new DignityP2P({ nodeId: 'bob', networkAdapter: new InMemoryNetworkAdapter(hub), security });
+helpers.track(alice, bob);
+await alice.start();
+await bob.start();
+
+await alice.create('docs', { body: 'draft' }, { id: 'd1', collaborators: ['bob'] });
+await helpers.sleep(20);
+
+await bob.update('docs', 'd1', { body: 'edited by bob' });
+await helpers.sleep(20);
+
+log('alice sees:', alice.read('docs', 'd1')?.data);
+log('bob sees:', bob.read('docs', 'd1')?.data);
+
+await alice.stop();
+await bob.stop();`
+  },
+  {
+    id: 'direct-message',
+    title: 'Direct messaging — encrypted DM',
+    description: 'Register peer keys and send a direct message.',
+    code: `const { DignityP2P, InMemoryNetworkHub, InMemoryNetworkAdapter } = dignity;
+
+const hub = new InMemoryNetworkHub();
+const security = helpers.fastSecurity({ signingEnabled: true, encryptionEnabled: true });
+
+const alice = new DignityP2P({ nodeId: 'alice', networkAdapter: new InMemoryNetworkAdapter(hub), security });
+const bob = new DignityP2P({ nodeId: 'bob', networkAdapter: new InMemoryNetworkAdapter(hub), security });
+helpers.track(alice, bob);
+
+let received = null;
+bob.on('message', (event) => {
+  if (event.senderId === 'alice' && event.type === 'chat') {
+    received = event.payload;
+  }
+});
+
+await alice.start();
+await bob.start();
+
+alice.registerPeerPublicKey('bob', bob.getPublicKey());
+bob.registerPeerPublicKey('alice', alice.getPublicKey());
+
+await alice.sendDirectMessage('bob', 'chat', { text: 'private hello' });
+await helpers.sleep(40);
+
+log('bob received:', received);
+
+await alice.stop();
+await bob.stop();`
+  },
+  {
+    id: 'content-hash',
+    title: 'Content hash — record.hash',
+    description: 'Each record exposes a sha512 digest over canonical data.',
+    code: `const { DignityP2P, InMemoryNetworkHub, InMemoryNetworkAdapter } = dignity;
+
+const hub = new InMemoryNetworkHub();
+const security = helpers.fastSecurity();
+
+const node = new DignityP2P({ nodeId: 'solo', networkAdapter: new InMemoryNetworkAdapter(hub), security });
+helpers.track(node);
+await node.start();
+
+const created = await node.create('notes', { title: 'hash me' }, { id: 'n1' });
+log('hash prefix:', created.hash?.slice(0, 12) + '...');
+log('full hash:', created.hash);
+
+const updated = await node.update('notes', 'n1', { title: 'hash me v2' });
+log('hash changed:', updated.hash !== created.hash);
+
+await node.stop();`
+  },
+  {
+    id: 'concurrency',
+    title: 'Concurrency — expectedVersion conflict',
+    description: 'Stale baseVersion is rejected; listen for conflict events.',
+    code: `const { DignityP2P, InMemoryNetworkHub, InMemoryNetworkAdapter } = dignity;
+
+const hub = new InMemoryNetworkHub();
+const security = helpers.fastSecurity();
+
+const alice = new DignityP2P({ nodeId: 'alice', networkAdapter: new InMemoryNetworkAdapter(hub), security });
+const bob = new DignityP2P({ nodeId: 'bob', networkAdapter: new InMemoryNetworkAdapter(hub), security });
+helpers.track(alice, bob);
+
+const conflicts = [];
+bob.on('conflict', (event) => conflicts.push(event));
+
+await alice.start();
+await bob.start();
+
+const record = await alice.create('scores', { points: 0 }, { id: 's1', collaborators: ['bob'] });
+await helpers.sleep(20);
+
+await bob.update('scores', 's1', { points: 5 });
+await helpers.sleep(20);
+
+let staleError = null;
+try {
+  await alice.update('scores', 's1', { points: 1 }, { expectedVersion: record.version });
+} catch (err) {
+  staleError = err.message;
+}
+
+log('stale write error:', staleError || 'none');
+log('conflict events on bob:', conflicts.length);
+log('final score:', bob.read('scores', 's1')?.data);
+
+await alice.stop();
+await bob.stop();`
+  },
+  {
+    id: 'scoped-passwords',
+    title: 'Scoped broadcast passwords',
+    description: 'Different broadcastScope values use different team passwords.',
+    code: `const { DignityP2P, InMemoryNetworkHub, InMemoryNetworkAdapter } = dignity;
+
+const hub = new InMemoryNetworkHub();
+
+const red = new DignityP2P({
+  nodeId: 'red-1',
+  networkAdapter: new InMemoryNetworkAdapter(hub),
+  security: helpers.fastSecurity({
+    appPassword: 'fallback',
+    broadcastPasswords: { 'team:red': 'red-secret', 'team:blue': 'blue-secret' }
+  })
+});
+const blue = new DignityP2P({
+  nodeId: 'blue-1',
+  networkAdapter: new InMemoryNetworkAdapter(hub),
+  security: helpers.fastSecurity({
+    appPassword: 'fallback',
+    broadcastPasswords: { 'team:red': 'red-secret', 'team:blue': 'blue-secret' }
+  })
+});
+helpers.track(red, blue);
+await red.start();
+await blue.start();
+
+await red.create('flags', { team: 'red' }, { id: 'f1', broadcastScope: 'team:red' });
+await blue.create('flags', { team: 'blue' }, { id: 'f2', broadcastScope: 'team:blue' });
+await helpers.sleep(40);
+
+log('red sees own:', !!red.read('flags', 'f1'));
+log('red sees blue flag:', !!red.read('flags', 'f2'));
+log('blue sees red flag:', !!blue.read('flags', 'f1'));
+
+await red.stop();
+await blue.stop();`
+  },
+  {
+    id: 'credential-keys',
+    title: 'Credential-derived keys',
+    description: 'Derive the same signing/encryption keys from username + password.',
+    code: `const { deriveKeyPairFromCredentials, keyPairToPublicBundle } = dignity;
+
+const opts = { username: 'alice', password: 'user-secret', kdfIterations: 1000 };
+
+const first = await deriveKeyPairFromCredentials(opts);
+const second = await deriveKeyPairFromCredentials(opts);
+
+const a = keyPairToPublicBundle(first);
+const b = keyPairToPublicBundle(second);
+
+log('same signing key:', a.signingPublicKey === b.signingPublicKey);
+log('same encryption key:', a.encryptionPublicKey === b.encryptionPublicKey);
+log('generation:', first.generation);
+
+const gen2 = await deriveKeyPairFromCredentials({ ...opts, generation: 2 });
+log('gen2 differs:', keyPairToPublicBundle(gen2).signingPublicKey !== a.signingPublicKey);`
+  },
+  {
+    id: 'identity-rotation',
+    title: 'Identity rotation — peer adopts new keys',
+    description: 'Rotate generation, adopt keys locally, broadcast to a peer.',
+    code: `const {
+  DignityP2P,
+  InMemoryNetworkHub,
+  InMemoryNetworkAdapter,
+  deriveKeyPairFromCredentials,
+  keyPairToPublicBundle,
+  revokeAndRotateIdentity
+} = dignity;
+
+const hub = new InMemoryNetworkHub();
+const security = helpers.fastSecurity({ signingEnabled: true, encryptionEnabled: true });
+
+const alice = new DignityP2P({ nodeId: 'alice', networkAdapter: new InMemoryNetworkAdapter(hub), security });
+const bob = new DignityP2P({ nodeId: 'bob', networkAdapter: new InMemoryNetworkAdapter(hub), security });
+helpers.track(alice, bob);
+
+const gen1 = await deriveKeyPairFromCredentials({
+  username: 'alice',
+  password: 'secret',
+  generation: 1,
+  kdfIterations: 1000
+});
+
+const rotationResult = await revokeAndRotateIdentity({
+  username: 'alice',
+  password: 'secret',
+  currentGeneration: 1,
+  kdfIterations: 1000,
+  reason: 'demo rotation'
+});
+
+await alice.start();
+await bob.start();
+
+await alice.adoptDerivedIdentityKeyPair(gen1, { generation: 1 });
+bob.registerPeerPublicKey('alice', keyPairToPublicBundle(gen1), { generation: 1 });
+log('bob gen before:', bob.getPeerIdentityGeneration('alice'));
+
+// Broadcast while alice still signs with gen-1 keys; then adopt gen-2 locally.
+await alice.broadcastIdentityRotation(rotationResult.rotation, { broadcastScope: 'identity:alice' });
+await alice.adoptDerivedIdentityKeyPair(rotationResult.nextKeyPair, { generation: 2 });
+await helpers.sleep(50);
+
+log('bob gen after:', bob.getPeerIdentityGeneration('alice'));
+log('keys upgraded:', bob.getPeerIdentityState('alice')?.publicKey?.signingPublicKey
+  === keyPairToPublicBundle(rotationResult.nextKeyPair).signingPublicKey);
+
+await alice.stop();
+await bob.stop();`
+  }
+];

package/docs/assets/playground.css

@@ -0,0 +1,277 @@
+.playground-page {
+  --playground-split: minmax(0, 1fr) minmax(0, 1fr);
+  display: flex;
+  flex-direction: column;
+  min-height: calc(100vh - var(--header-height));
+}
+
+.playground-intro {
+  padding: 20px 24px 0;
+  max-width: 1200px;
+}
+
+.playground-intro h1 {
+  margin: 0 0 8px;
+  font-size: 1.75rem;
+  color: var(--heading);
+}
+
+.playground-intro p {
+  margin: 0 0 16px;
+  color: var(--text-muted);
+  max-width: 72ch;
+}
+
+.playground-controls {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-end;
+  gap: 12px 20px;
+  padding: 0 24px 16px;
+  max-width: 1200px;
+}
+
+.playground-controls label {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  font-size: 0.8125rem;
+  font-weight: 600;
+  color: var(--text-muted);
+  min-width: 280px;
+  flex: 1;
+}
+
+.playground-controls select {
+  font: inherit;
+  font-weight: 500;
+  color: var(--text);
+  padding: 8px 12px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: var(--bg);
+}
+
+.playground-controls__hint {
+  flex: 1 1 100%;
+  margin: 0;
+  font-size: 0.875rem;
+  color: var(--text-muted);
+}
+
+.playground-split {
+  flex: 1;
+  display: grid;
+  grid-template-columns: var(--playground-split);
+  gap: 0;
+  min-height: 0;
+  border-top: 1px solid var(--border);
+}
+
+.playground-pane {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  min-width: 0;
+}
+
+.playground-pane + .playground-pane {
+  border-left: 1px solid var(--border);
+}
+
+.playground-pane__head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 10px 16px;
+  background: var(--bg-subtle);
+  border-bottom: 1px solid var(--border);
+  font-size: 0.8125rem;
+  font-weight: 600;
+  color: var(--text-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.playground-pane__actions {
+  display: flex;
+  gap: 8px;
+}
+
+.playground-btn {
+  font: inherit;
+  font-size: 0.8125rem;
+  font-weight: 600;
+  text-transform: none;
+  letter-spacing: 0;
+  padding: 6px 12px;
+  border-radius: var(--radius);
+  border: 1px solid var(--border);
+  background: var(--bg);
+  color: var(--text);
+  cursor: pointer;
+}
+
+.playground-btn:hover {
+  border-color: var(--accent);
+  color: var(--accent);
+}
+
+.playground-btn--primary {
+  background: var(--accent);
+  border-color: var(--accent);
+  color: #fff;
+}
+
+.playground-btn--primary:hover {
+  background: var(--accent-hover);
+  border-color: var(--accent-hover);
+  color: #fff;
+}
+
+.playground-btn:disabled {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+
+.playground-toolbar__status {
+  font-size: 0.75rem;
+  font-weight: 500;
+  text-transform: none;
+  letter-spacing: 0;
+  color: var(--text-muted);
+}
+
+.playground-toolbar__status.is-running {
+  color: var(--accent);
+}
+
+.playground-toolbar__status.is-ok {
+  color: var(--green);
+}
+
+.playground-toolbar__status.is-error {
+  color: #cf222e;
+}
+
+.playground-editor-wrap {
+  position: relative;
+  flex: 1;
+  min-height: 360px;
+  overflow: hidden;
+  display: grid;
+  background: var(--bg);
+}
+
+.playground-editor-highlight,
+#code-editor {
+  grid-area: 1 / 1;
+  width: 100%;
+  height: 100%;
+  min-height: 360px;
+  margin: 0;
+  padding: 16px;
+  border: 0;
+  font-family: var(--font-mono);
+  font-size: 0.875rem;
+  line-height: 1.55;
+  tab-size: 2;
+  overflow: auto;
+  white-space: pre;
+  word-wrap: normal;
+  overflow-wrap: normal;
+  box-sizing: border-box;
+}
+
+.playground-editor-highlight {
+  pointer-events: none;
+  z-index: 0;
+  background: var(--bg);
+  color: var(--text);
+}
+
+.playground-editor-highlight code {
+  display: block;
+  min-height: calc(100% - 32px);
+  padding: 0;
+  margin: 0;
+  font: inherit;
+  line-height: inherit;
+  background: transparent !important;
+  border: 0 !important;
+  border-radius: 0 !important;
+  color: inherit;
+}
+
+.playground-editor-highlight code.hljs {
+  padding: 0 !important;
+  border: 0 !important;
+  border-left: 0 !important;
+}
+
+#code-editor {
+  resize: none;
+  z-index: 1;
+  color: transparent !important;
+  -webkit-text-fill-color: transparent !important;
+  caret-color: var(--text);
+  background: transparent;
+}
+
+#code-editor:focus {
+  outline: none;
+  box-shadow: inset 0 0 0 2px var(--accent-soft);
+}
+
+#code-editor::selection {
+  background: rgba(91, 127, 255, 0.35);
+  color: transparent;
+  -webkit-text-fill-color: transparent;
+}
+
+@media (prefers-color-scheme: dark) {
+  .playground-editor-wrap,
+  .playground-editor-highlight {
+    background: #0d1117;
+    color: #e6edf3;
+  }
+
+  #code-editor {
+    caret-color: #e6edf3;
+  }
+}
+
+#output {
+  flex: 1;
+  min-height: 360px;
+  margin: 0;
+  padding: 16px;
+  overflow: auto;
+  font-family: var(--font-mono);
+  font-size: 0.875rem;
+  line-height: 1.55;
+  background: #0d1117;
+  color: #e6edf3;
+}
+
+.playground-output__line {
+  white-space: pre-wrap;
+  word-break: break-word;
+  padding: 2px 0;
+}
+
+.playground-output__line.is-error {
+  color: #ff7b72;
+}
+
+@media (max-width: 960px) {
+  .playground-split {
+    grid-template-columns: 1fr;
+  }
+
+  .playground-pane + .playground-pane {
+    border-left: 0;
+    border-top: 1px solid var(--border);
+  }
+}