dignity.js 0.1.0

package/src/security/message-security-service.js

@@ -0,0 +1,462 @@
+const nacl = require('tweetnacl');
+const naclUtil = require('tweetnacl-util');
+const VDF = require('./vdf');
+
+const DEFAULT_SECURITY_OPTIONS = {
+  enabled: true,
+  signingEnabled: true,
+  encryptionEnabled: true,
+  powEnabled: true,
+  powTargetMs: 1000,
+  appPassword: 'change-this-app-password',
+  broadcastPasswords: {},
+  resolveBroadcastPassword: null,
+  powSteps: 22,
+  trustedPeerKeys: {}
+};
+
+function stableStringify(value) {
+  if (value === null || typeof value !== 'object') {
+    return JSON.stringify(value);
+  }
+
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => stableStringify(entry)).join(',')}]`;
+  }
+
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+}
+
+function concatBytes(a, b) {
+  const result = new Uint8Array(a.length + b.length);
+  result.set(a, 0);
+  result.set(b, a.length);
+  return result;
+}
+
+function hash32(bytes) {
+  return nacl.hash(bytes).slice(0, 32);
+}
+
+function bytesToHex(bytes) {
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+
+function utf8ToBytes(value) {
+  return naclUtil.decodeUTF8(value);
+}
+
+function normalizePeerPublicKey(publicKey) {
+  if (!publicKey || typeof publicKey !== 'object') {
+    throw new Error('Public key must be an object with signingPublicKey and encryptionPublicKey');
+  }
+
+  if (!publicKey.signingPublicKey || !publicKey.encryptionPublicKey) {
+    throw new Error('Public key object is missing signingPublicKey or encryptionPublicKey');
+  }
+
+  return {
+    signingPublicKey: publicKey.signingPublicKey,
+    encryptionPublicKey: publicKey.encryptionPublicKey
+  };
+}
+
+class MessageSecurityService {
+  constructor({ nodeId, options = {}, now } = {}) {
+    if (!nodeId) {
+      throw new Error('MessageSecurityService requires nodeId');
+    }
+
+    this.nodeId = nodeId;
+    this.options = {
+      ...DEFAULT_SECURITY_OPTIONS,
+      ...options
+    };
+    this.now = now || (() => Date.now());
+
+    const keyPair = options.keyPair || {
+      signing: nacl.sign.keyPair(),
+      encryption: nacl.box.keyPair()
+    };
+
+    this.signingSecretKey = keyPair.signing.secretKey;
+    this.signingPublicKey = keyPair.signing.publicKey;
+    this.encryptionSecretKey = keyPair.encryption.secretKey;
+    this.encryptionPublicKey = keyPair.encryption.publicKey;
+
+    this.publicKeyBundle = {
+      signingPublicKey: naclUtil.encodeBase64(this.signingPublicKey),
+      encryptionPublicKey: naclUtil.encodeBase64(this.encryptionPublicKey)
+    };
+
+    this.peerPublicKeys = new Map();
+    for (const [peerId, peerKey] of Object.entries(this.options.trustedPeerKeys || {})) {
+      this.peerPublicKeys.set(peerId, normalizePeerPublicKey(peerKey));
+    }
+
+    this.calibratedPowSteps = this.options.powSteps;
+  }
+
+  getPublicKey() {
+    return { ...this.publicKeyBundle };
+  }
+
+  registerPeerPublicKey(peerId, publicKey) {
+    this.peerPublicKeys.set(peerId, normalizePeerPublicKey(publicKey));
+  }
+
+  resolvePeerPublicKey(peerId, fallbackPublicKey) {
+    const trusted = this.peerPublicKeys.get(peerId);
+    const fallback = fallbackPublicKey ? normalizePeerPublicKey(fallbackPublicKey) : null;
+
+    if (trusted && fallback) {
+      const mismatch =
+        trusted.signingPublicKey !== fallback.signingPublicKey ||
+        trusted.encryptionPublicKey !== fallback.encryptionPublicKey;
+
+      if (mismatch) {
+        throw new Error(`Public key mismatch for peer ${peerId}`);
+      }
+    }
+
+    return trusted || fallback || null;
+  }
+
+  buildEnvelopeBase({ messageType, payload, targetId = null }) {
+    return {
+      version: 1,
+      senderId: this.nodeId,
+      senderPublicKey: this.getPublicKey(),
+      targetId,
+      messageType,
+      timestamp: this.now(),
+      payload
+    };
+  }
+
+  async secureOutgoingMessage({ messageType, payload, targetId = null, securityContext = {} }) {
+    if (!this.options.enabled) {
+      return this.buildEnvelopeBase({ messageType, payload, targetId });
+    }
+
+    const envelope = this.buildEnvelopeBase({ messageType, payload, targetId });
+    const encryptionInfo = await this.encryptPayload({ payload, targetId, securityContext });
+    envelope.payload = encryptionInfo.payload;
+    envelope.security = {
+      encryption: encryptionInfo.security,
+      signing: { enabled: false },
+      pow: { enabled: false }
+    };
+
+    if (this.options.powEnabled) {
+      const pow = await this.generatePow(envelope);
+      envelope.security.pow = {
+        enabled: true,
+        challenge: pow.challenge,
+        proof: pow.proof,
+        steps: pow.steps,
+        durationMs: pow.durationMs
+      };
+    }
+
+    if (this.options.signingEnabled) {
+      const signatureBase = this.canonicalSigningInput(envelope);
+      const signature = nacl.sign.detached(
+        naclUtil.decodeUTF8(signatureBase),
+        this.signingSecretKey
+      );
+
+      envelope.security.signing = {
+        enabled: true,
+        algorithm: 'ed25519',
+        signature: naclUtil.encodeBase64(signature)
+      };
+    }
+
+    return envelope;
+  }
+
+  canonicalSigningInput(envelope) {
+    return stableStringify({
+      version: envelope.version,
+      senderId: envelope.senderId,
+      senderPublicKey: envelope.senderPublicKey,
+      targetId: envelope.targetId,
+      messageType: envelope.messageType,
+      timestamp: envelope.timestamp,
+      payload: envelope.payload,
+      security: {
+        encryption: envelope.security ? envelope.security.encryption : { enabled: false },
+        pow: envelope.security ? envelope.security.pow : { enabled: false }
+      }
+    });
+  }
+
+  canonicalPowInput(envelope) {
+    return stableStringify({
+      version: envelope.version,
+      senderId: envelope.senderId,
+      senderPublicKey: envelope.senderPublicKey,
+      targetId: envelope.targetId,
+      messageType: envelope.messageType,
+      timestamp: envelope.timestamp,
+      payload: envelope.payload,
+      security: {
+        encryption: envelope.security ? envelope.security.encryption : { enabled: false }
+      }
+    });
+  }
+
+  async decryptIncomingMessage(envelope) {
+    if (!this.options.enabled) {
+      return {
+        ignored: false,
+        messageType: envelope.messageType,
+        senderId: envelope.senderId,
+        targetId: envelope.targetId,
+        payload: envelope.payload
+      };
+    }
+
+    if (!envelope || typeof envelope !== 'object') {
+      throw new Error('Incoming message is invalid');
+    }
+
+    if (envelope.targetId && envelope.targetId !== this.nodeId) {
+      return { ignored: true };
+    }
+
+    if (envelope.security && envelope.security.pow && envelope.security.pow.enabled && this.options.powEnabled) {
+      await this.verifyPow(envelope);
+    }
+
+    if (envelope.security && envelope.security.signing && envelope.security.signing.enabled && this.options.signingEnabled) {
+      this.verifySignature(envelope);
+    }
+
+    const payload = this.decryptPayload(envelope);
+
+    return {
+      ignored: false,
+      messageType: envelope.messageType,
+      senderId: envelope.senderId,
+      targetId: envelope.targetId,
+      payload
+    };
+  }
+
+  resolveBroadcastPassword(scope) {
+    const normalizedScope = scope || 'default';
+
+    if (typeof this.options.resolveBroadcastPassword === 'function') {
+      const resolved = this.options.resolveBroadcastPassword({
+        scope: normalizedScope,
+        nodeId: this.nodeId,
+        defaultPassword: this.options.appPassword,
+        broadcastPasswords: this.options.broadcastPasswords || {}
+      });
+
+      if (typeof resolved === 'string' && resolved.length > 0) {
+        return resolved;
+      }
+    }
+
+    const scopePassword = this.options.broadcastPasswords
+      ? this.options.broadcastPasswords[normalizedScope]
+      : null;
+
+    if (typeof scopePassword === 'string' && scopePassword.length > 0) {
+      return scopePassword;
+    }
+
+    return this.options.appPassword;
+  }
+
+  async encryptPayload({ payload, targetId, securityContext = {} }) {
+    if (!this.options.encryptionEnabled) {
+      return {
+        payload,
+        security: {
+          enabled: false,
+          mode: 'none'
+        }
+      };
+    }
+
+    const plainText = naclUtil.decodeUTF8(JSON.stringify(payload));
+
+    if (targetId) {
+      const recipientPublicKey = this.resolvePeerPublicKey(targetId, null);
+      if (!recipientPublicKey) {
+        throw new Error(`Missing public key for target peer ${targetId}`);
+      }
+
+      const nonce = nacl.randomBytes(nacl.box.nonceLength);
+      const encrypted = nacl.box(
+        plainText,
+        nonce,
+        naclUtil.decodeBase64(recipientPublicKey.encryptionPublicKey),
+        this.encryptionSecretKey
+      );
+
+      return {
+        payload: naclUtil.encodeBase64(encrypted),
+        security: {
+          enabled: true,
+          mode: 'direct',
+          nonce: naclUtil.encodeBase64(nonce),
+          senderEncryptionPublicKey: this.publicKeyBundle.encryptionPublicKey
+        }
+      };
+    }
+
+    const scope = securityContext.broadcastScope || 'default';
+    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 encrypted = nacl.secretbox(plainText, nonce, key);
+
+    return {
+      payload: naclUtil.encodeBase64(encrypted),
+      security: {
+        enabled: true,
+        mode: 'broadcast',
+        scope,
+        nonce: naclUtil.encodeBase64(nonce),
+        salt: naclUtil.encodeBase64(salt)
+      }
+    };
+  }
+
+  decryptPayload(envelope) {
+    const encryption = envelope.security ? envelope.security.encryption : null;
+
+    if (!encryption || !encryption.enabled || !this.options.encryptionEnabled) {
+      return envelope.payload;
+    }
+
+    const encryptedBuffer = naclUtil.decodeBase64(envelope.payload);
+
+    if (encryption.mode === 'broadcast') {
+      const scope = encryption.scope || 'default';
+      const password = this.resolveBroadcastPassword(scope);
+      const salt = naclUtil.decodeBase64(encryption.salt);
+      const nonce = naclUtil.decodeBase64(encryption.nonce);
+      const key = hash32(concatBytes(utf8ToBytes(password), salt));
+      const decrypted = nacl.secretbox.open(encryptedBuffer, nonce, key);
+
+      if (!decrypted) {
+        throw new Error('Unable to decrypt broadcast payload');
+      }
+
+      return JSON.parse(naclUtil.encodeUTF8(decrypted));
+    }
+
+    if (encryption.mode === 'direct') {
+      const senderPublicKey = naclUtil.decodeBase64(encryption.senderEncryptionPublicKey);
+      const nonce = naclUtil.decodeBase64(encryption.nonce);
+      const decrypted = nacl.box.open(
+        encryptedBuffer,
+        nonce,
+        senderPublicKey,
+        this.encryptionSecretKey
+      );
+
+      if (!decrypted) {
+        throw new Error('Unable to decrypt direct payload');
+      }
+
+      return JSON.parse(naclUtil.encodeUTF8(decrypted));
+    }
+
+    throw new Error(`Unsupported encryption mode: ${encryption.mode}`);
+  }
+
+  verifySignature(envelope) {
+    const senderPublicKey = this.resolvePeerPublicKey(envelope.senderId, envelope.senderPublicKey);
+    if (!senderPublicKey) {
+      throw new Error(`Missing public key for sender ${envelope.senderId}`);
+    }
+
+    const signatureBase = this.canonicalSigningInput(envelope);
+    const isValid = nacl.sign.detached.verify(
+      naclUtil.decodeUTF8(signatureBase),
+      naclUtil.decodeBase64(envelope.security.signing.signature),
+      naclUtil.decodeBase64(senderPublicKey.signingPublicKey)
+    );
+
+    if (!isValid) {
+      const error = new Error(`Invalid signature for sender ${envelope.senderId}`);
+      error.code = 'INVALID_SIGNATURE';
+      throw error;
+    }
+
+    return true;
+  }
+
+  async determinePowSteps() {
+    if (typeof this.calibratedPowSteps === 'bigint') {
+      return this.calibratedPowSteps;
+    }
+
+    if (typeof this.options.powSteps === 'number') {
+      this.calibratedPowSteps = BigInt(Math.max(1, this.options.powSteps));
+      return this.calibratedPowSteps;
+    }
+
+    const targetMs = Math.max(1, Number(this.options.powTargetMs || 1));
+    const probeChallenge = bytesToHex(hash32(utf8ToBytes(`probe:${this.nodeId}:${this.now()}`)));
+    const probeSteps = BigInt(2);
+
+    const start = this.now();
+    await VDF.compute(probeChallenge, probeSteps);
+    const elapsedMs = Math.max(1, this.now() - start);
+
+    const scaled = Math.max(1, Math.round((targetMs / elapsedMs) * Number(probeSteps)));
+    this.calibratedPowSteps = BigInt(scaled);
+    return this.calibratedPowSteps;
+  }
+
+  async generatePow(envelope) {
+    const challenge = bytesToHex(hash32(utf8ToBytes(this.canonicalPowInput(envelope))));
+    const steps = await this.determinePowSteps();
+    const start = this.now();
+    const proof = await VDF.compute(challenge, steps);
+    const durationMs = this.now() - start;
+
+    return {
+      challenge,
+      proof,
+      steps: steps.toString(),
+      durationMs
+    };
+  }
+
+  async verifyPow(envelope) {
+    const expectedChallenge = bytesToHex(hash32(utf8ToBytes(this.canonicalPowInput(envelope))));
+    const pow = envelope.security.pow;
+
+    if (!pow || pow.challenge !== expectedChallenge) {
+      const error = new Error('PoW challenge mismatch');
+      error.code = 'INVALID_POW';
+      throw error;
+    }
+
+    const verified = await VDF.verify(pow.challenge, BigInt(pow.steps), pow.proof);
+    if (!verified) {
+      const error = new Error('PoW verification failed');
+      error.code = 'INVALID_POW';
+      throw error;
+    }
+
+    return true;
+  }
+}
+
+module.exports = {
+  MessageSecurityService,
+  stableStringify,
+  DEFAULT_SECURITY_OPTIONS
+};

package/src/security/sloth-vdf.js

@@ -0,0 +1,83 @@
+/*
+ * Sloth permutation adaptation based on:
+ * https://github.com/hyperhyperspace/pulsar/blob/main/src/model/SlothVDF.ts
+ */
+class SlothPermutation {
+  static p = BigInt(
+    '170082004324204494273811327264862981553264701145937538369570764779791492622392118654022654452947093285873855529044371650895045691292912712699015605832276411308653107069798639938826015099738961427172366594187783204437869906954750443653318078358839409699824714551430573905637228307966826784684174483831608534979'
+  );
+
+  fastPow(base, exponent, modulus) {
+    if (modulus === BigInt(1)) {
+      return BigInt(0);
+    }
+
+    let result = BigInt(1);
+    let powBase = base % modulus;
+    let powExponent = exponent;
+
+    while (powExponent > 0) {
+      if (powExponent % BigInt(2) === BigInt(1)) {
+        result = (result * powBase) % modulus;
+      }
+
+      powExponent = powExponent / BigInt(2);
+      powBase = (powBase * powBase) % modulus;
+    }
+
+    return result;
+  }
+
+  quadRes(x) {
+    return this.fastPow(x, (SlothPermutation.p - BigInt(1)) / BigInt(2), 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);
+    } else {
+      value = (-value + SlothPermutation.p) % SlothPermutation.p;
+      y = this.fastPow(value, (SlothPermutation.p + BigInt(1)) / BigInt(4), SlothPermutation.p);
+    }
+
+    return y;
+  }
+
+  modOp(x, t) {
+    let value = x % SlothPermutation.p;
+
+    for (let i = BigInt(0); i < t; i += BigInt(1)) {
+      value = this.modSqrtOp(value);
+    }
+
+    return value;
+  }
+
+  modVerif(y, x, t) {
+    const input = x % SlothPermutation.p;
+    let value = y;
+
+    for (let i = BigInt(0); i < t; i += BigInt(1)) {
+      value = (value ** BigInt(2)) % SlothPermutation.p;
+    }
+
+    if (!this.quadRes(value)) {
+      value = (-value + SlothPermutation.p) % SlothPermutation.p;
+    }
+
+    return input === value || ((-input + SlothPermutation.p) % SlothPermutation.p) === value;
+  }
+
+  generateProofVDF(t, x) {
+    return this.modOp(x, t);
+  }
+
+  verifyProofVDF(t, x, y) {
+    return this.modVerif(y, x, t);
+  }
+}
+
+module.exports = SlothPermutation;

package/src/security/vdf.js

@@ -0,0 +1,23 @@
+/*
+ * VDF wrapper adaptation based on:
+ * https://github.com/hyperhyperspace/pulsar/blob/main/src/model/VDF.ts
+ */
+const SlothPermutation = require('./sloth-vdf');
+
+class VDF {
+  static async compute(challengeHex, steps) {
+    const vdfInstance = new SlothPermutation();
+    const challengeBigInt = BigInt(`0x${challengeHex}`);
+    const result = vdfInstance.generateProofVDF(steps, challengeBigInt);
+    return result.toString(16);
+  }
+
+  static async verify(challengeHex, steps, resultHex) {
+    const vdfInstance = new SlothPermutation();
+    const challengeBigInt = BigInt(`0x${challengeHex}`);
+    const resultBigInt = BigInt(`0x${resultHex}`);
+    return vdfInstance.verifyProofVDF(steps, challengeBigInt, resultBigInt);
+  }
+}
+
+module.exports = VDF;

package/src/signaling/create-default-signaling-pool.js

@@ -0,0 +1,44 @@
+const SignalingPool = require('./signaling-pool');
+const WebSocketSignalingProvider = require('./websocket-signaling-provider');
+const {
+  DEFAULT_CLOUDFLARE_SIGNALING_URLS,
+  DEFAULT_SIGNALING_FALLBACK_URLS
+} = require('./default-signaling-config');
+
+function createDefaultSignalingPool(options = {}) {
+  const cloudflareUrls = options.cloudflareUrls || DEFAULT_CLOUDFLARE_SIGNALING_URLS;
+  const fallbackUrls = options.fallbackUrls || DEFAULT_SIGNALING_FALLBACK_URLS;
+  const WebSocketImpl = options.WebSocketImpl;
+
+  const providers = [];
+
+  cloudflareUrls.forEach((url, index) => {
+    providers.push(
+      new WebSocketSignalingProvider({
+        id: `cloudflare-${index + 1}`,
+        url,
+        WebSocketImpl,
+        priority: index
+      })
+    );
+  });
+
+  fallbackUrls.forEach((url, index) => {
+    providers.push(
+      new WebSocketSignalingProvider({
+        id: `fallback-${index + 1}`,
+        url,
+        WebSocketImpl,
+        priority: cloudflareUrls.length + index
+      })
+    );
+  });
+
+  if (Array.isArray(options.customProviders)) {
+    providers.push(...options.customProviders);
+  }
+
+  return new SignalingPool(providers);
+}
+
+module.exports = createDefaultSignalingPool;

package/src/signaling/default-signaling-config.js

@@ -0,0 +1,15 @@
+const DEFAULT_CLOUDFLARE_SIGNALING_URLS = [
+  'wss://signaling.cloudflare.com',
+  'wss://cloudflare-webrtc-signaling.example',
+  'wss://trycloudflare-signaling.example'
+];
+
+const DEFAULT_SIGNALING_FALLBACK_URLS = [
+  'wss://relay.dignity.dev/signaling',
+  'wss://backup-relay.dignity.dev/signaling'
+];
+
+module.exports = {
+  DEFAULT_CLOUDFLARE_SIGNALING_URLS,
+  DEFAULT_SIGNALING_FALLBACK_URLS
+};

package/src/signaling/signaling-pool.js

@@ -0,0 +1,75 @@
+class SignalingPool {
+  constructor(providers = []) {
+    this.providers = [...providers];
+    this.activeProvider = null;
+  }
+
+  registerProvider(provider) {
+    this.providers.push(provider);
+  }
+
+  getProvidersByPriority() {
+    return [...this.providers].sort((a, b) => (a.priority || 0) - (b.priority || 0));
+  }
+
+  async connect(excludedProviderIds = new Set()) {
+    const providers = this.getProvidersByPriority().filter(
+      (provider) => !excludedProviderIds.has(provider.id)
+    );
+    let lastError;
+
+    for (const provider of providers) {
+      try {
+        await provider.connect();
+        this.activeProvider = provider;
+        return provider;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+
+    throw lastError || new Error('No signaling provider could connect');
+  }
+
+  async send(message) {
+    if (!this.activeProvider) {
+      await this.connect();
+    }
+
+    try {
+      await this.activeProvider.send(message);
+    } catch (error) {
+      if (this.activeProvider && typeof this.activeProvider.disconnect === 'function') {
+        await this.activeProvider.disconnect();
+      }
+
+      const failedProviderId = this.activeProvider ? this.activeProvider.id : null;
+      this.activeProvider = null;
+      const excludedProviderIds = failedProviderId ? new Set([failedProviderId]) : new Set();
+      await this.connect(excludedProviderIds);
+      await this.activeProvider.send(message);
+      return error;
+    }
+
+    return null;
+  }
+
+  onMessage(handler) {
+    for (const provider of this.providers) {
+      if (typeof provider.onMessage === 'function') {
+        provider.onMessage(handler);
+      }
+    }
+  }
+
+  async disconnect() {
+    const disconnections = this.providers
+      .filter((provider) => typeof provider.disconnect === 'function')
+      .map((provider) => provider.disconnect());
+
+    await Promise.all(disconnections);
+    this.activeProvider = null;
+  }
+}
+
+module.exports = SignalingPool;