enigma-memory 0.1.17 → 0.1.22

package/packages/mesh/src/gossip.js

@@ -0,0 +1,311 @@
+// Enigma Encrypted Mesh Protocol ("GhostMesh") — Epidemic Gossip & Node Coordinator.
+// Connects transports, routers, and cryptographic envelopes into an autonomous AI memory mesh node.
+import { EventEmitter } from 'node:events';
+import { PACKET_TYPES, encodePacket, decodePacket, deriveDestination } from './protocol.js';
+import { generateMeshIdentity, sealPayload, unsealPayload, signPacket, verifyPacketSignature } from './crypto.js';
+import { PacketRouter } from './router.js';
+const MAX_DISCOVERED_PEERS = 1_024;
+
+export class MeshGossipNode extends EventEmitter {
+  /**
+   * @param {Object} options
+   * @param {Object} [options.identity] - Ed25519 identity keypair
+   * @param {string} [options.nodeId] - Node identifier label
+   * @param {string} [options.scope='enigma.global']
+   * @param {Array<import('./transport.js').AbstractTransport>} [options.transports]
+   */
+  constructor(options = {}) {
+    super();
+    this.scope = options.scope || 'enigma.global';
+    this.identity = options.identity || generateMeshIdentity(this.scope);
+    this.nodeId = options.nodeId || this.identity.destinationHex.slice(0, 12);
+    this.router = new PacketRouter({
+      nodeIdentity: this.identity,
+      nodeId: this.nodeId,
+    });
+
+    this.transports = new Map();
+    this.discoveredPeers = new Map();
+    if (Array.isArray(options.transports)) {
+      for (const t of options.transports) this.addTransport(t);
+    }
+
+    // Bind router events
+    this.router.on('delivered', (evt) => this.handleDeliveredPacket(evt));
+    this.router.on('routed', (evt) => this.forwardPacket(evt));
+    this.router.on('announce', (evt) => this.handleAnnounce(evt));
+  }
+
+  addTransport(transport) {
+    if ('identity' in transport && !transport.running) transport.identity = this.identity;
+    this.transports.set(transport.id, transport);
+    transport.on('packet', async ({ packetBuffer, fromPeerId, transportId }) => {
+      const admitted = this.router.registerPeer(fromPeerId, { transportId });
+      const result = admitted
+        ? await this.router.handleIncomingPacket(packetBuffer, fromPeerId, transportId)
+        : { action: 'DROPPED', reason: 'peer_capacity_reached' };
+      this.emit('packet:handled', { result, fromPeerId, transportId });
+    });
+
+    transport.on('peer:connect', ({ peerId, publicKey, address }) => {
+      const admitted = this.router.registerPeer(peerId, { transportId: transport.id, publicKey, address });
+      if (!admitted) return;
+      this.emit('peer:connect', { peerId, publicKey, address, transportId: transport.id });
+      // Announce immediately to the newly connected peer
+      this.announce().catch(() => {});
+    });
+
+    transport.on('peer:disconnect', ({ peerId }) => {
+      this.router.unregisterPeer(peerId);
+      this.emit('peer:disconnect', { peerId, transportId: transport.id });
+    });
+  }
+
+  async start() {
+    for (const t of this.transports.values()) {
+      if (!t.running) await t.start();
+    }
+    await this.announce();
+  }
+
+  async stop() {
+    for (const t of this.transports.values()) {
+      if (t.running) await t.stop();
+    }
+  }
+
+  /**
+   * Broadcasts a signed Announce beacon to all connected peers across all transports.
+   * @param {Object} [metadata] - Optional public node metadata (e.g. supported scopes, note root)
+   * @returns {Promise<Buffer>} The signed announce packet buffer
+   */
+  async announce(metadata = {}) {
+    const metaJson = JSON.stringify({
+      nodeId: this.nodeId,
+      scope: this.scope,
+      destinationHex: this.identity.destinationHex,
+      encryptionPublicKeyHex: this.identity.encryptionPublicKey ? this.identity.encryptionPublicKey.toString('hex') : null,
+      timestamp: Date.now(),
+      ...metadata,
+    });
+
+    const unsigned = encodePacket({
+      type: PACKET_TYPES.ANNOUNCE,
+      destination: this.identity.destination,
+      senderPubkey: this.identity.publicKey,
+      payload: Buffer.from(metaJson, 'utf8'),
+      hopTtl: 5,
+    });
+
+    const signed = signPacket(unsigned, this.identity.secretKey);
+    for (const t of this.transports.values()) {
+      await t.broadcast(signed);
+    }
+    return signed;
+  }
+
+  /**
+   * Sends an end-to-end encrypted memory capsule to a target destination.
+   * @param {Buffer|string} destination - 32-byte destination hash or hex
+   * @param {Buffer} recipientEd25519Pub - Recipient's 32-byte Ed25519 public key
+   * @param {string|Object} memoryContent - Confidential memory payload
+   * @param {Object} [opts]
+   * @returns {Promise<{packetId: string, deliveredLocally: boolean, routed: boolean}>}
+   */
+  async sendEncryptedCapsule(destination, recipientEd25519Pub, memoryContent, opts = {}) {
+    const destBuf = Buffer.isBuffer(destination) ? destination : Buffer.from(destination, 'hex');
+    const plainJson = typeof memoryContent === 'string' ? memoryContent : JSON.stringify(memoryContent);
+
+    // 1. Seal payload with ephemeral X25519 ECDH + AES-GCM and bind destination AAD
+    const { ciphertext, authTag, ephemeralPubkey } = sealPayload(plainJson, recipientEd25519Pub, {
+      ...opts,
+      aad: destBuf,
+    });
+    // 2. Encode packet
+    const unsigned = encodePacket({
+      type: PACKET_TYPES.MEMORY_CAPSULE,
+      destination: destBuf,
+      senderPubkey: this.identity.publicKey,
+      ephemeralPubkey,
+      payload: ciphertext,
+      authTag,
+      hopTtl: opts.hopTtl || 7,
+    });
+
+    // 3. Sign packet with sender's Ed25519 key
+    const signed = signPacket(unsigned, this.identity.secretKey);
+
+    // 4. Check if destination is self
+    if (destBuf.equals(this.identity.destination)) {
+      const decrypted = unsealPayload(ciphertext, authTag, ephemeralPubkey, this.identity.encryptionSecretKey, {
+        ...opts,
+        aad: destBuf,
+      });
+      this.emit('capsule', {
+        plaintext: decrypted.toString('utf8'),
+        senderPubkey: this.identity.publicKey,
+        destination: destBuf,
+      });
+      return { packetId: signed.subarray(signed.length - 16).toString('hex'), deliveredLocally: true, routed: false };
+    }
+
+    // 5. Route through best transport
+    const route = this.router.getBestRoute(destBuf.toString('hex'));
+    if (route) {
+      const transport = this.transports.get(route.transportId);
+      if (transport) {
+        await transport.send(signed, route.peerId);
+        return { packetId: signed.subarray(signed.length - 16).toString('hex'), deliveredLocally: false, routed: true };
+      }
+    }
+
+    // Fallback: broadcast across all active transports
+    let broadcastSent = false;
+    for (const t of this.transports.values()) {
+      const ok = await t.broadcast(signed);
+      if (ok) broadcastSent = true;
+    }
+
+    return { packetId: signed.subarray(signed.length - 16).toString('hex'), deliveredLocally: false, routed: broadcastSent };
+  }
+  handleAnnounce({ packet, metadata, fromPeerId }) {
+    const destinationHex = packet.destinationHex;
+    const publicKeyHex = packet.senderPubkey.toString('hex');
+    const encryptionPublicKeyHex = metadata.encryptionPublicKeyHex;
+    if (!this.discoveredPeers.has(destinationHex) && this.discoveredPeers.size >= MAX_DISCOVERED_PEERS) {
+      const oldest = this.discoveredPeers.keys().next().value;
+      this.discoveredPeers.delete(oldest);
+    }
+    this.discoveredPeers.set(destinationHex, {
+      destinationHex,
+      publicKeyHex,
+      encryptionPublicKeyHex,
+      agentName: metadata.agentName || metadata.name || `Node ${destinationHex.slice(0, 8)}`,
+      nodeId: metadata.nodeId || destinationHex.slice(0, 8),
+      scope: metadata.scope,
+      lastSeenAt: new Date().toISOString(),
+      metadata,
+    });
+    this.emit('peer:announce', { destinationHex, publicKeyHex, encryptionPublicKeyHex, metadata, fromPeerId });
+  }
+
+  getPeers() {
+    return Array.from(this.discoveredPeers.values());
+  }
+
+  /**
+   * Gossips a pre-signed Solana ZK proof or transaction to mesh gateway nodes.
+   * @param {Object} proofPayload - { signature, publicInputs, proofBytes, txBase64 }
+   * @returns {Promise<Buffer>}
+   */
+  async broadcastZkProof(proofPayload) {
+    const payloadJson = JSON.stringify(proofPayload);
+    const unsigned = encodePacket({
+      type: PACKET_TYPES.ZK_PROOF_GOSSIP,
+      destination: Buffer.alloc(32, 0xff), // Broadcast destination
+      senderPubkey: this.identity.publicKey,
+      payload: Buffer.from(payloadJson, 'utf8'),
+      hopTtl: 6,
+    });
+
+    const signed = signPacket(unsigned, this.identity.secretKey);
+    for (const t of this.transports.values()) {
+      await t.broadcast(signed);
+    }
+    return signed;
+  }
+
+  /**
+   * Gossips a Sealed Sale offer across the mesh for zero-trust buyer discovery.
+   * @param {Object} saleListing - Standard Sealed Sale listing JSON
+   * @returns {Promise<Buffer>}
+   */
+  async broadcastSealedSaleOffer(saleListing) {
+    const listingJson = JSON.stringify(saleListing);
+    const unsigned = encodePacket({
+      type: PACKET_TYPES.SEALED_SALE_OFFER,
+      destination: Buffer.alloc(32, 0xff),
+      senderPubkey: this.identity.publicKey,
+      payload: Buffer.from(listingJson, 'utf8'),
+      hopTtl: 6,
+    });
+
+    const signed = signPacket(unsigned, this.identity.secretKey);
+    for (const t of this.transports.values()) {
+      await t.broadcast(signed);
+    }
+    return signed;
+  }
+
+  handleDeliveredPacket({ packet, fromPeerId }) {
+    switch (packet.type) {
+      case PACKET_TYPES.MEMORY_CAPSULE: {
+        try {
+          const decrypted = unsealPayload(
+            packet.payload,
+            packet.authTag,
+            packet.ephemeralPubkey,
+            this.identity.encryptionSecretKey,
+            { aad: packet.destination }
+          );
+          this.emit('capsule', {
+            plaintext: decrypted.toString('utf8'),
+            senderPubkey: packet.senderPubkey,
+            senderPubkeyHex: packet.senderPubkeyHex,
+            destinationHex: packet.destinationHex,
+            fromPeerId,
+          });
+        } catch (err) {
+          this.emit('capsule:error', { error: err.message, fromPeerId });
+        }
+        break;
+      }
+      case PACKET_TYPES.ZK_PROOF_GOSSIP: {
+        try {
+          const data = JSON.parse(packet.payload.toString('utf8'));
+          this.emit('zk:proof', { proof: data, senderPubkey: packet.senderPubkeyHex, fromPeerId });
+        } catch {}
+        break;
+      }
+      case PACKET_TYPES.SEALED_SALE_OFFER: {
+        try {
+          const data = JSON.parse(packet.payload.toString('utf8'));
+          this.emit('sale:offer', { listing: data, senderPubkey: packet.senderPubkeyHex, fromPeerId });
+        } catch {}
+        break;
+      }
+      case PACKET_TYPES.ANNOUNCE: {
+        try {
+          const data = JSON.parse(packet.payload.toString('utf8'));
+          this.emit('announce', { metadata: data, senderPubkey: packet.senderPubkeyHex, fromPeerId });
+        } catch {}
+        break;
+      }
+      default:
+        this.emit('packet', { packet, fromPeerId });
+    }
+  }
+
+  async forwardPacket({ packet, nextHopPeerId, transportId, forwardBuffer }) {
+    const transport = this.transports.get(transportId);
+    if (transport) {
+      await transport.send(forwardBuffer, nextHopPeerId);
+    }
+  }
+
+  getStatus() {
+    const stats = this.router.getRoutingStats();
+    const transportStats = Array.from(this.transports.values()).map((t) => (t.getStats ? t.getStats() : { id: t.id }));
+
+    return {
+      ok: true,
+      nodeId: this.nodeId,
+      scope: this.scope,
+      destinationHex: this.identity.destinationHex,
+      publicKeyHex: this.identity.publicKey.toString('hex'),
+      encryptionPublicKeyHex: this.identity.encryptionPublicKey ? this.identity.encryptionPublicKey.toString('hex') : null,
+      router: stats,
+      transports: transportStats,
+    };
+  }
+}

package/packages/mesh/src/index.js

@@ -529,3 +529,9 @@ export default {
   verifyFederationGrant,
   runMeshDemo
 };
+export * from './protocol.js';
+export * from './crypto.js';
+export * from './router.js';
+export * from './transport.js';
+export * from './gossip.js';
+export * from './federation-packets.js';

package/packages/mesh/src/protocol.js

@@ -0,0 +1,255 @@
+// Enigma Encrypted Mesh Protocol ("GhostMesh") — Binary Packet Framing & Codec.
+// Implements identity-based destination derivation, binary packet serialization,
+// and zero-copy header parsing for low-bandwidth BLE / LoRa / WebRTC transports.
+import crypto from 'node:crypto';
+export const PROTOCOL_MAGIC = 0x454e; // 'EN'
+export const PROTOCOL_VERSION = 1;
+export const HEADER_SIZE = 112; // Fixed header bytes before variable payload
+export const MAX_PACKET_SIZE = 65535; // 64KB max packet size
+export const DEFAULT_HOP_TTL = 7;
+
+export const PACKET_TYPES = Object.freeze({
+  ANNOUNCE: 0x01,
+  MEMORY_CAPSULE: 0x02,
+  ZK_PROOF_GOSSIP: 0x03,
+  SEALED_SALE_OFFER: 0x04,
+  TREE_SYNC_REQ: 0x05,
+  TREE_SYNC_RESP: 0x06,
+  STORE_FORWARD_CHUNK: 0x07,
+  ACK: 0x08,
+  CAPABILITY_GRANT: 0x09,
+  FEDERATED_QUERY_REQUEST: 0x0a,
+  FEDERATED_QUERY_RESPONSE: 0x0b,
+  CAPABILITY_REVOCATION: 0x0c,
+});
+
+export const PACKET_TYPE_NAMES = Object.freeze(
+  Object.fromEntries(Object.entries(PACKET_TYPES).map(([k, v]) => [v, k]))
+);
+
+/**
+ * Derives a 32-byte cryptographic destination hash from an agent's signing key, encryption key, and scope.
+ * @param {Buffer|Uint8Array|string} ed25519PublicKey - 32-byte Ed25519 public key
+ * @param {Buffer|Uint8Array|string|{x: string|bigint, y: string|bigint}|null} [encryptionPublicKey] - 32-byte X25519 public key or BabyJub point
+ * @param {string} [scope='enigma.global']
+ * @returns {Buffer} 32-byte destination hash
+ */
+export function deriveDestination(ed25519PublicKey, encryptionPublicKey = null, scope = 'enigma.global') {
+  const h = crypto.createHash('sha256');
+  const pubBuf = Buffer.isBuffer(ed25519PublicKey)
+    ? ed25519PublicKey
+    : typeof ed25519PublicKey === 'string'
+      ? Buffer.from(ed25519PublicKey, 'hex')
+      : Buffer.from(ed25519PublicKey);
+  h.update(pubBuf);
+
+  if (encryptionPublicKey) {
+    if (Buffer.isBuffer(encryptionPublicKey)) {
+      h.update(encryptionPublicKey);
+    } else if (typeof encryptionPublicKey === 'string') {
+      h.update(Buffer.from(encryptionPublicKey, 'hex'));
+    } else if (encryptionPublicKey instanceof Uint8Array) {
+      h.update(Buffer.from(encryptionPublicKey));
+    } else if (encryptionPublicKey.x && encryptionPublicKey.y) {
+      const xHex = BigInt(encryptionPublicKey.x).toString(16).padStart(64, '0');
+      const yHex = BigInt(encryptionPublicKey.y).toString(16).padStart(64, '0');
+      h.update(Buffer.from(xHex, 'hex'));
+      h.update(Buffer.from(yHex, 'hex'));
+    }
+  }
+
+  h.update(Buffer.from(scope, 'utf8'));
+  return h.digest();
+}
+
+/**
+ * Encodes a structured GhostMesh packet into a raw binary buffer.
+ * @param {Object} p
+ * @param {number} p.type - Packet type (PACKET_TYPES)
+ * @param {Buffer} p.destination - 32-byte destination hash
+ * @param {Buffer} p.senderPubkey - 32-byte Ed25519 sender public key
+ * @param {Buffer} [p.ephemeralPubkey] - 32-byte X25519 / BabyJub ephemeral key or IV
+ * @param {Buffer} p.payload - Raw or encrypted payload buffer
+ * @param {Buffer} [p.authTag] - 16-byte Poly1305 / GCM authentication tag
+ * @param {Buffer} [p.signature] - 64-byte Ed25519 signature
+ * @param {number} [p.hopTtl=DEFAULT_HOP_TTL]
+ * @param {number} [p.seqId=0]
+ * @param {number} [p.chunkIndex=0]
+ * @param {number} [p.chunkTotal=1]
+ * @param {number} [p.flags=0]
+ * @returns {Buffer}
+ */
+export function encodePacket(p) {
+  if (!p || typeof p !== 'object') throw new Error('Packet must be an object');
+  const payload = Buffer.isBuffer(p.payload) ? p.payload : Buffer.from(p.payload || []);
+  if (payload.length > MAX_PACKET_SIZE - HEADER_SIZE - 64 - 16) {
+    throw new Error(`Payload size (${payload.length}B) exceeds max packet limit`);
+  }
+
+  const type = p.type === undefined ? PACKET_TYPES.MEMORY_CAPSULE : p.type;
+  if (!Number.isInteger(type) || !PACKET_TYPE_NAMES[type]) {
+    throw new Error(`Unknown packet type: ${type}`);
+  }
+
+  const byteField = (value, fallback, name) => {
+    const normalized = value === undefined ? fallback : value;
+    if (!Number.isInteger(normalized) || normalized < 0 || normalized > 0xff) {
+      throw new Error(`${name} must be an integer between 0 and 255`);
+    }
+    return normalized;
+  };
+  const uint16Field = (value, fallback, name) => {
+    const normalized = value === undefined ? fallback : value;
+    if (!Number.isInteger(normalized) || normalized < 0 || normalized > 0xffff) {
+      throw new Error(`${name} must be an integer between 0 and 65535`);
+    }
+    return normalized;
+  };
+
+  const flags = byteField(p.flags, 0, 'flags');
+  const hopTtl = byteField(p.hopTtl, DEFAULT_HOP_TTL, 'hopTtl');
+  const seqId = uint16Field(p.seqId, 0, 'seqId');
+  const chunkIndex = uint16Field(p.chunkIndex, 0, 'chunkIndex');
+  const chunkTotal = uint16Field(p.chunkTotal, 1, 'chunkTotal');
+  if (chunkTotal === 0) throw new Error('chunkTotal must be at least 1');
+  if (chunkIndex >= chunkTotal) {
+    throw new Error(`chunkIndex ${chunkIndex} must be less than chunkTotal ${chunkTotal}`);
+  }
+
+  const destination = Buffer.from(p.destination || []);
+  if (destination.length !== 32) throw new Error('Destination must be a 32-byte buffer');
+
+  const senderPubkey = Buffer.from(p.senderPubkey || []);
+  if (senderPubkey.length !== 32) throw new Error('Sender public key must be a 32-byte buffer');
+
+  const ephemeralPubkey = p.ephemeralPubkey ? Buffer.from(p.ephemeralPubkey) : Buffer.alloc(32, 0);
+  if (ephemeralPubkey.length !== 32) throw new Error('Ephemeral public key must be 32 bytes');
+
+  const authTag = p.authTag ? Buffer.from(p.authTag) : Buffer.alloc(16, 0);
+  if (authTag.length !== 16) throw new Error('Auth tag must be 16 bytes');
+
+  const signature = p.signature ? Buffer.from(p.signature) : Buffer.alloc(64, 0);
+  if (signature.length !== 64) throw new Error('Signature must be 64 bytes');
+
+  const totalLength = HEADER_SIZE + payload.length + 16 + 64;
+  if (totalLength > MAX_PACKET_SIZE) throw new Error(`Packet size (${totalLength}B) exceeds max packet limit`);
+  const buf = Buffer.alloc(totalLength);
+
+  let offset = 0;
+  buf.writeUInt16BE(PROTOCOL_MAGIC, offset); offset += 2;
+  buf.writeUInt8(PROTOCOL_VERSION, offset); offset += 1;
+  buf.writeUInt8(type, offset); offset += 1;
+  buf.writeUInt8(flags, offset); offset += 1;
+  buf.writeUInt8(hopTtl, offset); offset += 1;
+  buf.writeUInt16BE(seqId, offset); offset += 2;
+
+  destination.copy(buf, offset); offset += 32;
+  senderPubkey.copy(buf, offset); offset += 32;
+  ephemeralPubkey.copy(buf, offset); offset += 32;
+
+  buf.writeUInt32BE(payload.length, offset); offset += 4;
+  buf.writeUInt16BE(chunkIndex, offset); offset += 2;
+  buf.writeUInt16BE(chunkTotal, offset); offset += 2;
+
+  payload.copy(buf, offset); offset += payload.length;
+  authTag.copy(buf, offset); offset += 16;
+  signature.copy(buf, offset);
+
+  return buf;
+}
+
+/**
+ * Decodes a raw binary buffer into a structured GhostMesh packet object.
+ * @param {Buffer|Uint8Array} rawBuffer
+ * @returns {Object} Decoded packet structure
+ */
+export function decodePacket(rawBuffer) {
+  const buf = Buffer.isBuffer(rawBuffer) ? rawBuffer : Buffer.from(rawBuffer);
+  if (buf.length < HEADER_SIZE + 16 + 64) {
+    throw new Error(`Packet buffer too short (${buf.length} bytes; minimum is ${HEADER_SIZE + 80} bytes)`);
+  }
+  if (buf.length > MAX_PACKET_SIZE) {
+    throw new Error(`Packet buffer too large (${buf.length} bytes; maximum is ${MAX_PACKET_SIZE} bytes)`);
+  }
+
+  let offset = 0;
+  const magic = buf.readUInt16BE(offset); offset += 2;
+  if (magic !== PROTOCOL_MAGIC) {
+    throw new Error(`Invalid protocol magic: 0x${magic.toString(16)} (expected 0x${PROTOCOL_MAGIC.toString(16)})`);
+  }
+
+  const version = buf.readUInt8(offset); offset += 1;
+  if (version !== PROTOCOL_VERSION) {
+    throw new Error(`Unsupported protocol version: ${version} (expected ${PROTOCOL_VERSION})`);
+  }
+
+  const type = buf.readUInt8(offset); offset += 1;
+  if (!PACKET_TYPE_NAMES[type]) throw new Error(`Unknown packet type: ${type}`);
+  const flags = buf.readUInt8(offset); offset += 1;
+  const hopTtl = buf.readUInt8(offset); offset += 1;
+  const seqId = buf.readUInt16BE(offset); offset += 2;
+
+  const destination = buf.subarray(offset, offset + 32); offset += 32;
+  const senderPubkey = buf.subarray(offset, offset + 32); offset += 32;
+  const ephemeralPubkey = buf.subarray(offset, offset + 32); offset += 32;
+
+  const payloadLength = buf.readUInt32BE(offset); offset += 4;
+  const chunkIndex = buf.readUInt16BE(offset); offset += 2;
+  const chunkTotal = buf.readUInt16BE(offset); offset += 2;
+  if (chunkTotal === 0) throw new Error('Invalid packet chunks: chunkTotal must be at least 1');
+  if (chunkIndex >= chunkTotal) {
+    throw new Error(`Invalid packet chunks: chunkIndex ${chunkIndex} must be less than chunkTotal ${chunkTotal}`);
+  }
+
+  const expectedLength = HEADER_SIZE + payloadLength + 16 + 64;
+  if (expectedLength !== buf.length) {
+    if (expectedLength > buf.length) {
+      throw new Error(`Packet payload truncated (expected exactly ${expectedLength} bytes, got ${buf.length})`);
+    }
+    throw new Error(`Packet frame has trailing bytes (expected exactly ${expectedLength} bytes, got ${buf.length})`);
+  }
+
+  const payload = buf.subarray(offset, offset + payloadLength); offset += payloadLength;
+  const authTag = buf.subarray(offset, offset + 16); offset += 16;
+  const signature = buf.subarray(offset, offset + 64);
+
+  return {
+    magic,
+    version,
+    type,
+    typeName: PACKET_TYPE_NAMES[type],
+    flags,
+    hopTtl,
+    seqId,
+    destination,
+    destinationHex: destination.toString('hex'),
+    senderPubkey,
+    senderPubkeyHex: senderPubkey.toString('hex'),
+    ephemeralPubkey,
+    ephemeralPubkeyHex: ephemeralPubkey.toString('hex'),
+    payloadLength,
+    chunkIndex,
+    chunkTotal,
+    payload,
+    authTag,
+    signature,
+    rawBytes: buf,
+  };
+}
+export function getSignableBytes(packetBuffer) {
+  const decoded = decodePacket(packetBuffer);
+  const buf = decoded.rawBytes;
+  // TTL is the only mutable field. Relays may decrement it without invalidating
+  // the end-to-end signature; every other frame byte is immutable.
+  const prefix = buf.subarray(0, 5);
+  const remainder = buf.subarray(6, buf.length - 64);
+  return Buffer.concat([prefix, remainder]);
+}
+
+/**
+ * Stable replay identity for a packet. It excludes the mutable hop TTL and the
+ * signature bytes, so decrementing TTL cannot turn a replay into a new packet.
+ */
+export function getPacketReplayIdentity(packetBuffer) {
+  return crypto.createHash('sha256').update(getSignableBytes(packetBuffer)).digest('hex');
+}