dignity.js 0.6.0 → 0.7.1

package/src/security/identity-rotation.js

@@ -0,0 +1,427 @@
+const nacl = require('tweetnacl');
+const naclUtil = require('tweetnacl-util');
+const { stableStringify } = require('./message-security-service');
+const {
+  deriveKeyPairFromCredentials,
+  deriveColdRecoverySigningKey,
+  keyPairToPublicBundle
+} = require('./derive-key-pair');
+
+const ROTATION_TYPES = new Set(['compromise-recovery', 'password-change']);
+
+function utf8ToBytes(value) {
+  return naclUtil.decodeUTF8(value);
+}
+
+function normalizePublicKeyBundle(publicKey) {
+  if (!publicKey || !publicKey.signingPublicKey || !publicKey.encryptionPublicKey) {
+    throw new Error('Public key bundle requires signingPublicKey and encryptionPublicKey');
+  }
+  return {
+    signingPublicKey: publicKey.signingPublicKey,
+    encryptionPublicKey: publicKey.encryptionPublicKey
+  };
+}
+
+function buildIdentityRotationPayload({
+  username,
+  fromGeneration,
+  toGeneration,
+  previousPublicKey,
+  nextPublicKey,
+  rotationKind,
+  reason,
+  timestamp
+}) {
+  if (!username) {
+    throw new Error('Identity rotation requires username');
+  }
+  if (!ROTATION_TYPES.has(rotationKind)) {
+    throw new Error(`Identity rotation kind must be one of: ${[...ROTATION_TYPES].join(', ')}`);
+  }
+  if (toGeneration !== fromGeneration + 1) {
+    throw new Error('Identity rotation must advance generation by exactly 1');
+  }
+
+  return {
+    version: 1,
+    type: 'identity:rotate',
+    username,
+    fromGeneration,
+    toGeneration,
+    previousPublicKey: normalizePublicKeyBundle(previousPublicKey),
+    nextPublicKey: normalizePublicKeyBundle(nextPublicKey),
+    rotationKind,
+    reason: reason || '',
+    timestamp: typeof timestamp === 'number' ? timestamp : Date.now()
+  };
+}
+
+function signIdentityRotationPayload(payload, signingSecretKey) {
+  const message = utf8ToBytes(stableStringify(payload));
+  const signature = nacl.sign.detached(message, signingSecretKey);
+  return naclUtil.encodeBase64(signature);
+}
+
+function verifyDetachedSignature(payload, signatureBase64, signingPublicKeyBase64) {
+  const message = utf8ToBytes(stableStringify(payload));
+  const signatureBytes = naclUtil.decodeBase64(signatureBase64);
+  const signingPublicKey = naclUtil.decodeBase64(signingPublicKeyBase64);
+  return nacl.sign.detached.verify(message, signatureBytes, signingPublicKey);
+}
+
+function createIdentityRotation({
+  username,
+  fromGeneration,
+  toGeneration,
+  previousPublicKey,
+  nextKeyPair,
+  rotationKind,
+  reason,
+  timestamp,
+  coldRecoverySigningSecretKey
+}) {
+  if (!nextKeyPair || !nextKeyPair.signing || !nextKeyPair.signing.secretKey) {
+    throw new Error('Identity rotation requires nextKeyPair with signing secret');
+  }
+
+  const payload = buildIdentityRotationPayload({
+    username,
+    fromGeneration,
+    toGeneration,
+    previousPublicKey,
+    nextPublicKey: keyPairToPublicBundle(nextKeyPair),
+    rotationKind,
+    reason,
+    timestamp
+  });
+
+  const rotation = {
+    ...payload,
+    signature: signIdentityRotationPayload(payload, nextKeyPair.signing.secretKey)
+  };
+
+  if (coldRecoverySigningSecretKey) {
+    rotation.recoverySignature = signIdentityRotationPayload(
+      payload,
+      coldRecoverySigningSecretKey
+    );
+  }
+
+  return rotation;
+}
+
+function buildColdRecoveryEnrollmentPayload({ username, recoveryPublicKey, timestamp }) {
+  if (!username) {
+    throw new Error('Cold recovery enrollment requires username');
+  }
+  if (!recoveryPublicKey) {
+    throw new Error('Cold recovery enrollment requires recoveryPublicKey');
+  }
+
+  return {
+    version: 1,
+    type: 'identity:cold-enroll',
+    username,
+    recoveryPublicKey,
+    timestamp: typeof timestamp === 'number' ? timestamp : Date.now()
+  };
+}
+
+function createColdRecoveryEnrollment({
+  username,
+  coldRecoverySigningSecretKey,
+  recoveryPublicKey,
+  timestamp
+}) {
+  if (!coldRecoverySigningSecretKey) {
+    throw new Error('Cold recovery enrollment requires cold recovery signing secret');
+  }
+  if (!recoveryPublicKey) {
+    throw new Error('Cold recovery enrollment requires recoveryPublicKey');
+  }
+
+  const payload = buildColdRecoveryEnrollmentPayload({
+    username,
+    recoveryPublicKey,
+    timestamp
+  });
+
+  return {
+    ...payload,
+    signature: signIdentityRotationPayload(payload, coldRecoverySigningSecretKey)
+  };
+}
+
+function verifyColdRecoveryEnrollment(enrollment) {
+  if (!enrollment || enrollment.type !== 'identity:cold-enroll' || enrollment.version !== 1) {
+    return { ok: false, error: 'invalid-enrollment-shape' };
+  }
+
+  if (!enrollment.signature || !enrollment.recoveryPublicKey) {
+    return { ok: false, error: 'missing-enrollment-fields' };
+  }
+
+  const { signature, ...payload } = enrollment;
+  const verified = verifyDetachedSignature(payload, signature, enrollment.recoveryPublicKey);
+
+  if (!verified) {
+    return { ok: false, error: 'invalid-enrollment-signature' };
+  }
+
+  return { ok: true, enrollment };
+}
+
+function verifyIdentityRotation(rotation, options = {}) {
+  if (!rotation || rotation.type !== 'identity:rotate' || rotation.version !== 1) {
+    return { ok: false, error: 'invalid-rotation-shape' };
+  }
+
+  if (!rotation.signature || !rotation.nextPublicKey || !rotation.previousPublicKey) {
+    return { ok: false, error: 'missing-rotation-fields' };
+  }
+
+  if (rotation.toGeneration !== rotation.fromGeneration + 1) {
+    return { ok: false, error: 'invalid-generation-step' };
+  }
+
+  if (!ROTATION_TYPES.has(rotation.rotationKind)) {
+    return { ok: false, error: 'invalid-rotation-kind' };
+  }
+
+  const { signature, recoverySignature, ...payload } = rotation;
+  const verified = verifyDetachedSignature(payload, signature, rotation.nextPublicKey.signingPublicKey);
+
+  if (!verified) {
+    return { ok: false, error: 'invalid-signature' };
+  }
+
+  const requiredRecoveryPublicKey = options.requiredRecoveryPublicKey || null;
+  if (requiredRecoveryPublicKey) {
+    if (!recoverySignature) {
+      return { ok: false, error: 'missing-recovery-signature' };
+    }
+
+    const recoveryVerified = verifyDetachedSignature(
+      payload,
+      recoverySignature,
+      requiredRecoveryPublicKey
+    );
+
+    if (!recoveryVerified) {
+      return { ok: false, error: 'invalid-recovery-signature' };
+    }
+  }
+
+  if (rotation.previousPublicKey.signingPublicKey === rotation.nextPublicKey.signingPublicKey) {
+    return { ok: false, error: 'unchanged-signing-key' };
+  }
+
+  return { ok: true, rotation };
+}
+
+async function resolveColdRecoverySigningSecretKey({
+  username,
+  coldPassword,
+  pepper,
+  kdfIterations
+}) {
+  if (!coldPassword) {
+    return null;
+  }
+
+  const coldRecovery = await deriveColdRecoverySigningKey({
+    username,
+    coldPassword,
+    pepper,
+    kdfIterations
+  });
+  return coldRecovery.signing.secretKey;
+}
+
+/**
+ * Same username + password, next generation (key #2, #3, …).
+ * Optional coldPassword co-signs the rotation so a stolen primary password
+ * cannot lock out the legitimate user after cold recovery is enrolled.
+ */
+async function revokeAndRotateIdentity({
+  username,
+  password,
+  coldPassword,
+  currentGeneration = 1,
+  reason = 'compromise-recovery',
+  pepper = '',
+  kdfIterations,
+  timestamp
+} = {}) {
+  const currentKeyPair = await deriveKeyPairFromCredentials({
+    username,
+    password,
+    generation: currentGeneration,
+    pepper,
+    kdfIterations
+  });
+  const nextGeneration = currentGeneration + 1;
+  const nextKeyPair = await deriveKeyPairFromCredentials({
+    username,
+    password,
+    generation: nextGeneration,
+    pepper,
+    kdfIterations
+  });
+
+  const coldRecoverySigningSecretKey = await resolveColdRecoverySigningSecretKey({
+    username,
+    coldPassword,
+    pepper,
+    kdfIterations
+  });
+
+  const rotation = createIdentityRotation({
+    username,
+    fromGeneration: currentGeneration,
+    toGeneration: nextGeneration,
+    previousPublicKey: keyPairToPublicBundle(currentKeyPair),
+    nextKeyPair,
+    rotationKind: 'compromise-recovery',
+    reason,
+    timestamp,
+    coldRecoverySigningSecretKey
+  });
+
+  return {
+    rotation,
+    currentKeyPair,
+    nextKeyPair,
+    nextGeneration,
+    coldRecoveryUsed: Boolean(coldRecoverySigningSecretKey)
+  };
+}
+
+/**
+ * Password change: signed with new-password gen N+1 keys.
+ * Optional coldPassword prevents an attacker who stole the old primary password
+ * from rotating the identity away from the legitimate user.
+ */
+async function rotateIdentityPassword({
+  username,
+  currentPassword,
+  newPassword,
+  coldPassword,
+  currentGeneration = 1,
+  reason = 'password-change',
+  pepper = '',
+  kdfIterations,
+  timestamp
+} = {}) {
+  const currentKeyPair = await deriveKeyPairFromCredentials({
+    username,
+    password: currentPassword,
+    generation: currentGeneration,
+    pepper,
+    kdfIterations
+  });
+  const nextGeneration = currentGeneration + 1;
+  const nextKeyPair = await deriveKeyPairFromCredentials({
+    username,
+    password: newPassword,
+    generation: nextGeneration,
+    pepper,
+    kdfIterations
+  });
+
+  const coldRecoverySigningSecretKey = await resolveColdRecoverySigningSecretKey({
+    username,
+    coldPassword,
+    pepper,
+    kdfIterations
+  });
+
+  const rotation = createIdentityRotation({
+    username,
+    fromGeneration: currentGeneration,
+    toGeneration: nextGeneration,
+    previousPublicKey: keyPairToPublicBundle(currentKeyPair),
+    nextKeyPair,
+    rotationKind: 'password-change',
+    reason,
+    timestamp,
+    coldRecoverySigningSecretKey
+  });
+
+  return {
+    rotation,
+    currentKeyPair,
+    nextKeyPair,
+    nextGeneration,
+    coldRecoveryUsed: Boolean(coldRecoverySigningSecretKey)
+  };
+}
+
+async function enrollColdRecoveryPassword({
+  username,
+  coldPassword,
+  pepper = '',
+  kdfIterations,
+  timestamp
+} = {}) {
+  const coldRecovery = await deriveColdRecoverySigningKey({
+    username,
+    coldPassword,
+    pepper,
+    kdfIterations
+  });
+
+  const enrollment = createColdRecoveryEnrollment({
+    username,
+    coldRecoverySigningSecretKey: coldRecovery.signing.secretKey,
+    recoveryPublicKey: coldRecovery.recoveryPublicKey,
+    timestamp
+  });
+
+  return {
+    enrollment,
+    recoveryPublicKey: coldRecovery.recoveryPublicKey,
+    coldRecovery
+  };
+}
+
+function shouldApplyIdentityRotation(currentState, rotation, options = {}) {
+  const requiredRecoveryPublicKey = options.enrolledRecoveryPublicKey
+    || (currentState && currentState.recoveryPublicKey)
+    || null;
+
+  const verified = verifyIdentityRotation(rotation, { requiredRecoveryPublicKey });
+  if (!verified.ok) {
+    return { apply: false, reason: verified.error };
+  }
+
+  if (currentState && rotation.toGeneration <= currentState.generation) {
+    return { apply: false, reason: 'stale-generation' };
+  }
+
+  if (
+    currentState
+    && currentState.publicKey
+    && currentState.publicKey.signingPublicKey !== rotation.previousPublicKey.signingPublicKey
+  ) {
+    return { apply: false, reason: 'previous-key-mismatch' };
+  }
+
+  return { apply: true, rotation: verified.rotation };
+}
+
+module.exports = {
+  createIdentityRotation,
+  createColdRecoveryEnrollment,
+  verifyIdentityRotation,
+  verifyColdRecoveryEnrollment,
+  revokeAndRotateIdentity,
+  rotateIdentityPassword,
+  enrollColdRecoveryPassword,
+  shouldApplyIdentityRotation,
+  keyPairToPublicBundle,
+  buildIdentityRotationPayload,
+  buildColdRecoveryEnrollmentPayload,
+  signIdentityRotationPayload
+};

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

@@ -2,13 +2,15 @@ const nacl = require('tweetnacl');
 const naclUtil = require('tweetnacl-util');
 const VDF = require('./vdf');
 
+const DEFAULT_APP_PASSWORD = 'change-this-app-password';
+
 const DEFAULT_SECURITY_OPTIONS = {
   enabled: true,
   signingEnabled: true,
   encryptionEnabled: true,
   powEnabled: true,
   powTargetMs: 1000,
-  appPassword: 'change-this-app-password',
+  appPassword: DEFAULT_APP_PASSWORD,
   broadcastPasswords: {},
   resolveBroadcastPassword: null,
   powSteps: 22,
@@ -123,8 +125,11 @@ class MessageSecurityService {
     };
 
     this.peerPublicKeys = new Map();
+    this.peerIdentityGenerations = new Map(); // peerId -> generation number
+    this.peerRecoveryPublicKeys = new Map(); // peerId -> cold recovery signing pubkey (base64)
     for (const [peerId, peerKey] of Object.entries(this.options.trustedPeerKeys || {})) {
       this.peerPublicKeys.set(peerId, normalizePeerPublicKey(peerKey));
+      this.peerIdentityGenerations.set(peerId, 1);
     }
 
     this.calibratedPowSteps = this.options.powSteps;
@@ -134,8 +139,92 @@ class MessageSecurityService {
     return { ...this.publicKeyBundle };
   }
 
-  registerPeerPublicKey(peerId, publicKey) {
-    this.peerPublicKeys.set(peerId, normalizePeerPublicKey(publicKey));
+  registerPeerPublicKey(peerId, publicKey, options = {}) {
+    const normalized = normalizePeerPublicKey(publicKey);
+    const generation = typeof options.generation === 'number' ? options.generation : 1;
+    const currentGeneration = this.peerIdentityGenerations.get(peerId) || 0;
+
+    if (generation < currentGeneration && options.allowDowngrade !== true) {
+      throw new Error(`Refusing older identity generation for peer ${peerId}`);
+    }
+
+    this.peerPublicKeys.set(peerId, normalized);
+    this.peerIdentityGenerations.set(peerId, Math.max(currentGeneration, generation));
+  }
+
+  getPeerIdentityGeneration(peerId) {
+    return this.peerIdentityGenerations.get(peerId) || 0;
+  }
+
+  getPeerIdentityState(peerId) {
+    const publicKey = this.peerPublicKeys.get(peerId);
+    const recoveryPublicKey = this.peerRecoveryPublicKeys.get(peerId) || null;
+
+    if (!publicKey && !recoveryPublicKey) {
+      return null;
+    }
+
+    return {
+      publicKey: publicKey ? { ...publicKey } : null,
+      generation: this.getPeerIdentityGeneration(peerId),
+      recoveryPublicKey
+    };
+  }
+
+  registerPeerRecoveryPublicKey(peerId, recoveryPublicKey) {
+    if (!peerId || !recoveryPublicKey) {
+      throw new Error('registerPeerRecoveryPublicKey requires peerId and recoveryPublicKey');
+    }
+    this.peerRecoveryPublicKeys.set(peerId, recoveryPublicKey);
+  }
+
+  getPeerRecoveryPublicKey(peerId) {
+    return this.peerRecoveryPublicKeys.get(peerId) || null;
+  }
+
+  applyColdRecoveryEnrollment(peerId, enrollment) {
+    const { verifyColdRecoveryEnrollment } = require('./identity-rotation');
+    const verified = verifyColdRecoveryEnrollment(enrollment);
+    if (!verified.ok) {
+      const error = new Error(`Invalid cold recovery enrollment: ${verified.error}`);
+      error.code = 'INVALID_COLD_RECOVERY_ENROLLMENT';
+      throw error;
+    }
+
+    this.registerPeerRecoveryPublicKey(peerId, enrollment.recoveryPublicKey);
+    return { applied: true, recoveryPublicKey: enrollment.recoveryPublicKey };
+  }
+
+  applyIdentityRotation(peerId, rotation) {
+    const { shouldApplyIdentityRotation } = require('./identity-rotation');
+
+    const currentState = this.getPeerIdentityState(peerId);
+    const decision = shouldApplyIdentityRotation(currentState, rotation, {
+      enrolledRecoveryPublicKey: this.getPeerRecoveryPublicKey(peerId)
+    });
+    if (!decision.apply) {
+      if (
+        decision.reason
+        && decision.reason !== 'stale-generation'
+        && decision.reason !== 'previous-key-mismatch'
+      ) {
+        const error = new Error(`Invalid identity rotation: ${decision.reason}`);
+        error.code = 'INVALID_IDENTITY_ROTATION';
+        throw error;
+      }
+      return { applied: false, reason: decision.reason };
+    }
+
+    this.registerPeerPublicKey(peerId, rotation.nextPublicKey, {
+      generation: rotation.toGeneration
+    });
+
+    return {
+      applied: true,
+      fromGeneration: rotation.fromGeneration,
+      toGeneration: rotation.toGeneration,
+      rotationKind: rotation.rotationKind
+    };
   }
 
   resolvePeerPublicKey(peerId, fallbackPublicKey) {
@@ -523,5 +612,6 @@ module.exports = {
   stableStringify,
   deriveBroadcastKey,
   legacyBroadcastKey,
-  DEFAULT_SECURITY_OPTIONS
+  DEFAULT_SECURITY_OPTIONS,
+  DEFAULT_APP_PASSWORD
 };