enigma-memory 0.1.18 → 0.1.22

package/packages/mesh/src/crypto.js

@@ -0,0 +1,189 @@
+// Enigma Encrypted Mesh Protocol ("GhostMesh") — Cryptographic Engine.
+// Provides true X25519 ECDH session key agreement, AES-256-GCM authenticated
+// payload encryption with AAD binding, and Ed25519 envelope signing for opaque mesh relaying.
+import crypto from 'node:crypto';
+import { getSignableBytes, encodePacket, decodePacket, deriveDestination, HEADER_SIZE } from './protocol.js';
+
+// ASN.1 DER prefixes for raw 32-byte Ed25519 and X25519 keys in Node crypto
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+const ED25519_PKCS8_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex');
+const X25519_SPKI_PREFIX = Buffer.from('302a300506032b656e032100', 'hex');
+const X25519_PKCS8_PREFIX = Buffer.from('302e020100300506032b656e04220420', 'hex');
+
+export function exportRawEd25519PublicKey(keyObject) {
+  const der = keyObject.export({ type: 'spki', format: 'der' });
+  return der.subarray(der.length - 32);
+}
+
+export function exportRawEd25519PrivateKey(keyObject) {
+  const der = keyObject.export({ type: 'pkcs8', format: 'der' });
+  return der.subarray(der.length - 32);
+}
+
+export function importRawEd25519PublicKey(raw32) {
+  const buf = Buffer.isBuffer(raw32) ? raw32 : Buffer.from(raw32, 'hex');
+  if (buf.length !== 32) throw new RangeError(`Ed25519 public key must be exactly 32 bytes; got ${buf.length}`);
+  const der = Buffer.concat([ED25519_SPKI_PREFIX, buf]);
+  return crypto.createPublicKey({ key: der, format: 'der', type: 'spki' });
+}
+
+export function importRawEd25519PrivateKey(raw32) {
+  const buf = Buffer.isBuffer(raw32) ? raw32 : Buffer.from(raw32, 'hex');
+  if (buf.length !== 32) throw new RangeError(`Ed25519 private key must be exactly 32 bytes; got ${buf.length}`);
+  const der = Buffer.concat([ED25519_PKCS8_PREFIX, buf]);
+  return crypto.createPrivateKey({ key: der, format: 'der', type: 'pkcs8' });
+}
+
+export function exportRawX25519PublicKey(keyObject) {
+  const der = keyObject.export({ type: 'spki', format: 'der' });
+  return der.subarray(der.length - 32);
+}
+
+export function exportRawX25519PrivateKey(keyObject) {
+  const der = keyObject.export({ type: 'pkcs8', format: 'der' });
+  return der.subarray(der.length - 32);
+}
+
+export function importRawX25519PublicKey(raw32) {
+  const buf = Buffer.isBuffer(raw32) ? raw32 : Buffer.from(raw32, 'hex');
+  if (buf.length !== 32) throw new RangeError(`X25519 public key must be exactly 32 bytes; got ${buf.length}`);
+  const der = Buffer.concat([X25519_SPKI_PREFIX, buf]);
+  return crypto.createPublicKey({ key: der, format: 'der', type: 'spki' });
+}
+
+export function importRawX25519PrivateKey(raw32) {
+  const buf = Buffer.isBuffer(raw32) ? raw32 : Buffer.from(raw32, 'hex');
+  if (buf.length !== 32) throw new RangeError(`X25519 private key must be exactly 32 bytes; got ${buf.length}`);
+  const der = Buffer.concat([X25519_PKCS8_PREFIX, buf]);
+  return crypto.createPrivateKey({ key: der, format: 'der', type: 'pkcs8' });
+}
+
+/**
+ * Generates an Ed25519 signing identity and an X25519 encryption keypair.
+ * @returns {{publicKey: Buffer, secretKey: Buffer, encryptionPublicKey: Buffer, encryptionSecretKey: Buffer, destination: Buffer, destinationHex: string}}
+ */
+export function generateMeshIdentity(scope = 'enigma.global') {
+  const ed = crypto.generateKeyPairSync('ed25519');
+  const edPub = exportRawEd25519PublicKey(ed.publicKey);
+  const edPriv = exportRawEd25519PrivateKey(ed.privateKey);
+
+  const x = crypto.generateKeyPairSync('x25519');
+  const xPub = exportRawX25519PublicKey(x.publicKey);
+  const xPriv = exportRawX25519PrivateKey(x.privateKey);
+
+  const dest = deriveDestination(edPub, xPub, scope);
+
+  return {
+    publicKey: edPub,
+    secretKey: edPriv,
+    encryptionPublicKey: xPub,
+    encryptionSecretKey: xPriv,
+    destination: dest,
+    destinationHex: dest.toString('hex'),
+    scope,
+  };
+}
+export function deriveSymmetricKey(sharedSecret, salt, info = 'ghostmesh.e2ee.v1') {
+  const raw = crypto.hkdfSync('sha256', sharedSecret, salt, Buffer.from(info, 'utf8'), 32);
+  return Buffer.from(raw);
+}
+
+const GHOSTMESH_E2EE_SALT = Buffer.from('ghostmesh.e2ee.v1', 'utf8');
+
+export function sealPayload(plaintext, recipientX25519PubBytes, opts = {}) {
+  const plainBuf = Buffer.isBuffer(plaintext) ? plaintext : Buffer.from(plaintext, 'utf8');
+  const recipientPubObj = importRawX25519PublicKey(recipientX25519PubBytes);
+
+  // Generate ephemeral X25519 keypair
+  const eph = crypto.generateKeyPairSync('x25519');
+  const ephPubRaw = exportRawX25519PublicKey(eph.publicKey);
+
+  // Real X25519 ECDH Diffie-Hellman shared secret
+  const sharedSecret = crypto.diffieHellman({
+    privateKey: eph.privateKey,
+    publicKey: recipientPubObj,
+  });
+
+  const symKey = deriveSymmetricKey(sharedSecret, GHOSTMESH_E2EE_SALT, 'ghostmesh.key.v1');
+  const iv = Buffer.from(crypto.hkdfSync('sha256', sharedSecret, GHOSTMESH_E2EE_SALT, Buffer.from('ghostmesh.iv.v1', 'utf8'), 12));
+
+  const cipher = crypto.createCipheriv('aes-256-gcm', symKey, iv);
+  if (opts.aad) {
+    cipher.setAAD(Buffer.isBuffer(opts.aad) ? opts.aad : Buffer.from(opts.aad));
+  }
+
+  const ciphertext = Buffer.concat([cipher.update(plainBuf), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+
+  return {
+    ciphertext,
+    authTag,
+    ephemeralPubkey: ephPubRaw, // exactly 32 bytes
+  };
+}
+
+/**
+ * Unseals an opaque payload using the recipient's X25519 private key.
+ * Intermediate relay nodes without recipientX25519PrivBytes cannot compute the ECDH shared secret.
+ * @param {Buffer} ciphertext
+ * @param {Buffer} authTag - 16-byte GCM auth tag
+ * @param {Buffer} ephemeralPubkey - 32-byte header field (Ephemeral X25519 Pub)
+ * @param {Buffer} recipientX25519PrivBytes - Recipient's 32-byte X25519 private key
+ * @param {Object} [opts]
+ * @param {Buffer|string} [opts.aad]
+ * @returns {Buffer} Decrypted plaintext buffer
+ */
+export function unsealPayload(ciphertext, authTag, ephemeralPubkey, recipientX25519PrivBytes, opts = {}) {
+  const recipientPrivObj = importRawX25519PrivateKey(recipientX25519PrivBytes);
+  const ephPubObj = importRawX25519PublicKey(ephemeralPubkey);
+
+  // Real X25519 ECDH Diffie-Hellman shared secret
+  const sharedSecret = crypto.diffieHellman({
+    privateKey: recipientPrivObj,
+    publicKey: ephPubObj,
+  });
+
+  const symKey = deriveSymmetricKey(sharedSecret, GHOSTMESH_E2EE_SALT, 'ghostmesh.key.v1');
+  const iv = Buffer.from(crypto.hkdfSync('sha256', sharedSecret, GHOSTMESH_E2EE_SALT, Buffer.from('ghostmesh.iv.v1', 'utf8'), 12));
+
+  const decipher = crypto.createDecipheriv('aes-256-gcm', symKey, iv);
+  if (opts.aad) {
+    decipher.setAAD(Buffer.isBuffer(opts.aad) ? opts.aad : Buffer.from(opts.aad));
+  }
+  decipher.setAuthTag(authTag);
+
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+/**
+ * Signs signable packet bytes with an Ed25519 secret key.
+ * @param {Buffer} packetBuffer
+ * @param {Buffer} secretKey
+ * @returns {Buffer} Packet with signature appended
+ */
+export function signPacket(packetBuffer, secretKey) {
+  const privKeyObj = importRawEd25519PrivateKey(secretKey);
+  const signable = getSignableBytes(packetBuffer);
+  const signature = crypto.sign(null, signable, privKeyObj);
+  const out = Buffer.from(packetBuffer);
+  signature.copy(out, out.length - 64);
+  return out;
+}
+
+/**
+ * Verifies an Ed25519 signature over a signed packet buffer.
+ * @param {Buffer} signedPacketBuffer
+ * @returns {boolean}
+ */
+export function verifyPacketSignature(signedPacketBuffer) {
+  if (signedPacketBuffer.length < HEADER_SIZE + 16 + 64) return false;
+  const signature = signedPacketBuffer.subarray(signedPacketBuffer.length - 64);
+  const signable = getSignableBytes(signedPacketBuffer);
+
+  try {
+    const decoded = decodePacket(signedPacketBuffer);
+    const pubKeyObj = importRawEd25519PublicKey(decoded.senderPubkey);
+    return crypto.verify(null, signable, pubKeyObj, signature);
+  } catch {
+    return false;
+  }
+}

package/packages/mesh/src/federation-packets.js

@@ -0,0 +1,353 @@
+import crypto from 'node:crypto';
+import {
+  PACKET_TYPES,
+  decodePacket,
+  deriveDestination,
+  encodePacket,
+  getPacketReplayIdentity,
+} from './protocol.js';
+import { sealPayload, signPacket, unsealPayload, verifyPacketSignature } from './crypto.js';
+
+export const GHOSTMESH_FEDERATION_PACKET_SCHEMA = 'enigma.ghostmesh_federation_packet.v1';
+
+export const FEDERATION_PACKET_KINDS = Object.freeze({
+  CAPABILITY_GRANT: 'capability_grant',
+  QUERY_REQUEST: 'query_request',
+  QUERY_RESPONSE: 'query_response',
+  CAPABILITY_REVOCATION: 'capability_revocation',
+});
+
+const KIND_TO_TYPE = Object.freeze({
+  [FEDERATION_PACKET_KINDS.CAPABILITY_GRANT]: PACKET_TYPES.CAPABILITY_GRANT,
+  [FEDERATION_PACKET_KINDS.QUERY_REQUEST]: PACKET_TYPES.FEDERATED_QUERY_REQUEST,
+  [FEDERATION_PACKET_KINDS.QUERY_RESPONSE]: PACKET_TYPES.FEDERATED_QUERY_RESPONSE,
+  [FEDERATION_PACKET_KINDS.CAPABILITY_REVOCATION]: PACKET_TYPES.CAPABILITY_REVOCATION,
+});
+
+const TYPE_TO_KIND = Object.freeze(
+  Object.fromEntries(Object.entries(KIND_TO_TYPE).map(([kind, type]) => [type, kind]))
+);
+
+const HEX_32_RE = /^[0-9a-f]{64}$/;
+const PACKET_ID_RE = /^[0-9a-f]{32}$/;
+const ENVELOPE_KEYS = [
+  'body',
+  'correlation_id',
+  'created_at',
+  'kind',
+  'packet_id',
+  'recipient_destination',
+  'schema',
+  'sender',
+  'version',
+];
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) && !Buffer.isBuffer(value);
+}
+
+function assertExactKeys(value, expected, name) {
+  if (!isRecord(value)) throw new Error(`${name} must be an object`);
+  const actual = Object.keys(value).sort();
+  const wanted = expected.slice().sort();
+  if (actual.length !== wanted.length || actual.some((key, index) => key !== wanted[index])) {
+    throw new Error(`${name} fields must be exactly: ${wanted.join(', ')}`);
+  }
+}
+
+function toBuffer32(value, name) {
+  let buffer;
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    buffer = Buffer.from(value);
+  } else if (typeof value === 'string' && HEX_32_RE.test(value.toLowerCase())) {
+    buffer = Buffer.from(value, 'hex');
+  } else {
+    throw new Error(`${name} must be a 32-byte value`);
+  }
+  if (buffer.length !== 32) throw new Error(`${name} must be a 32-byte value`);
+  return buffer;
+}
+
+function canonicalize(value) {
+  if (value === null || typeof value === 'boolean' || typeof value === 'string') return JSON.stringify(value);
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new Error('Federation packet values must contain only finite numbers');
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) return `[${value.map(canonicalize).join(',')}]`;
+  if (!isRecord(value)) throw new Error('Federation packet values must be JSON-compatible objects');
+  return `{${Object.keys(value).sort().map((key) => {
+    if (value[key] === undefined) throw new Error(`Federation packet field ${key} cannot be undefined`);
+    return `${JSON.stringify(key)}:${canonicalize(value[key])}`;
+  }).join(',')}}`;
+}
+
+export function hashFederationValue(value) {
+  return crypto.createHash('sha256').update(canonicalize(value), 'utf8').digest('hex');
+}
+
+function assertIsoTimestamp(value, name) {
+  if (typeof value !== 'string') throw new Error(`${name} must be an ISO timestamp string`);
+  const date = new Date(value);
+  if (!Number.isFinite(date.getTime()) || date.toISOString() !== value) {
+    throw new Error(`${name} must be a canonical ISO timestamp`);
+  }
+}
+
+function normalizeEndpoint(endpoint, name, { requireSecret = false } = {}) {
+  if (!endpoint || typeof endpoint !== 'object') throw new Error(`${name} is required`);
+  const publicKey = toBuffer32(endpoint.publicKey ?? endpoint.public_key, `${name}.publicKey`);
+  const encryptionPublicKey = toBuffer32(
+    endpoint.encryptionPublicKey ?? endpoint.encryption_public_key,
+    `${name}.encryptionPublicKey`
+  );
+  const scope = endpoint.scope;
+  if (typeof scope !== 'string' || scope.length === 0 || scope.length > 256) {
+    throw new Error(`${name}.scope must be a non-empty string of at most 256 characters`);
+  }
+  const derivedDestination = deriveDestination(publicKey, encryptionPublicKey, scope);
+  const declaredDestination = endpoint.destination ?? endpoint.destinationHex ?? endpoint.destination_hex;
+  if (declaredDestination !== undefined && declaredDestination !== null) {
+    const destination = toBuffer32(declaredDestination, `${name}.destination`);
+    if (!destination.equals(derivedDestination)) {
+      throw new Error(`${name}.destination does not match its signing key, encryption key, and scope`);
+    }
+  }
+
+  let encryptionSecretKey;
+  if (requireSecret) {
+    encryptionSecretKey = toBuffer32(
+      endpoint.encryptionSecretKey ?? endpoint.encryption_secret_key,
+      `${name}.encryptionSecretKey`
+    );
+  }
+
+  return {
+    publicKey,
+    encryptionPublicKey,
+    encryptionSecretKey,
+    destination: derivedDestination,
+    destinationHex: derivedDestination.toString('hex'),
+    scope,
+  };
+}
+
+function validateBody(kind, body) {
+  switch (kind) {
+    case FEDERATION_PACKET_KINDS.CAPABILITY_GRANT:
+      assertExactKeys(body, ['grant'], 'capability grant body');
+      if (!isRecord(body.grant)) throw new Error('capability grant body.grant must be an object');
+      break;
+    case FEDERATION_PACKET_KINDS.QUERY_REQUEST:
+      assertExactKeys(body, ['request', 'top_k'], 'query request body');
+      if (!isRecord(body.request)) throw new Error('query request body.request must be an object');
+      if (!Number.isSafeInteger(body.top_k) || body.top_k < 1 || body.top_k > 100) {
+        throw new Error('query request body.top_k must be an integer between 1 and 100');
+      }
+      break;
+    case FEDERATION_PACKET_KINDS.QUERY_RESPONSE:
+      assertExactKeys(body, ['error', 'ok', 'request_hash', 'result'], 'query response body');
+      if (typeof body.ok !== 'boolean') throw new Error('query response body.ok must be boolean');
+      if (!HEX_32_RE.test(String(body.request_hash || ''))) {
+        throw new Error('query response body.request_hash must be a 64-hex SHA-256 hash');
+      }
+      if (body.ok) {
+        if (!isRecord(body.result) || body.error !== null) {
+          throw new Error('successful query response must contain an object result and null error');
+        }
+      } else if (body.result !== null || typeof body.error !== 'string' || body.error.length === 0) {
+        throw new Error('failed query response must contain null result and a non-empty error');
+      }
+      break;
+    case FEDERATION_PACKET_KINDS.CAPABILITY_REVOCATION:
+      assertExactKeys(body, ['grant_id', 'revoked_at'], 'capability revocation body');
+      if (typeof body.grant_id !== 'string' || body.grant_id.length === 0) {
+        throw new Error('capability revocation body.grant_id must be a non-empty string');
+      }
+      assertIsoTimestamp(body.revoked_at, 'capability revocation body.revoked_at');
+      break;
+    default:
+      throw new Error(`Unsupported federation packet kind: ${kind}`);
+  }
+  canonicalize(body);
+}
+
+function federationAad(type, destination, senderPublicKey) {
+  return Buffer.concat([
+    Buffer.from('ghostmesh.federation.aad.v1\0', 'utf8'),
+    Buffer.from([type]),
+    destination,
+    senderPublicKey,
+  ]);
+}
+
+/**
+ * Creates an encrypted and signed GhostMesh federation frame.
+ */
+export function createFederationPacket(options = {}) {
+  const kind = options.kind;
+  const type = KIND_TO_TYPE[kind];
+  if (!type) throw new Error(`Unsupported federation packet kind: ${kind}`);
+  validateBody(kind, options.body);
+
+  const sender = normalizeEndpoint(
+    { ...options.senderIdentity, scope: options.senderScope ?? options.senderIdentity?.scope },
+    'senderIdentity'
+  );
+  const senderSecretKey = toBuffer32(options.senderIdentity?.secretKey, 'senderIdentity.secretKey');
+  const recipient = normalizeEndpoint(options.recipient, 'recipient');
+  const packetId = options.packetId ?? crypto.randomBytes(16).toString('hex');
+  if (!PACKET_ID_RE.test(packetId)) throw new Error('packetId must be 32 lowercase hex characters');
+
+  const correlationId = options.correlationId ?? null;
+  if (correlationId !== null && !PACKET_ID_RE.test(correlationId)) {
+    throw new Error('correlationId must be null or 32 lowercase hex characters');
+  }
+  if (kind === FEDERATION_PACKET_KINDS.QUERY_RESPONSE && correlationId === null) {
+    throw new Error('query response packets require correlationId');
+  }
+
+  const createdAt = options.createdAt ?? new Date().toISOString();
+  assertIsoTimestamp(createdAt, 'createdAt');
+  const envelope = {
+    schema: GHOSTMESH_FEDERATION_PACKET_SCHEMA,
+    version: 1,
+    kind,
+    packet_id: packetId,
+    correlation_id: correlationId,
+    created_at: createdAt,
+    sender: {
+      destination: sender.destinationHex,
+      encryption_pubkey: sender.encryptionPublicKey.toString('hex'),
+      scope: sender.scope,
+    },
+    recipient_destination: recipient.destinationHex,
+    body: options.body,
+  };
+
+  const aad = federationAad(type, recipient.destination, sender.publicKey);
+  const sealed = sealPayload(Buffer.from(canonicalize(envelope), 'utf8'), recipient.encryptionPublicKey, { aad });
+  const unsigned = encodePacket({
+    type,
+    destination: recipient.destination,
+    senderPubkey: sender.publicKey,
+    ephemeralPubkey: sealed.ephemeralPubkey,
+    payload: sealed.ciphertext,
+    authTag: sealed.authTag,
+    hopTtl: options.hopTtl,
+    seqId: options.seqId,
+  });
+  const packetBuffer = signPacket(unsigned, senderSecretKey);
+
+  return {
+    packetId,
+    kind,
+    correlationId,
+    destinationHex: recipient.destinationHex,
+    packetBuffer,
+  };
+}
+
+/**
+ * Authenticates, recipient-binds, decrypts, and validates a federation frame.
+ */
+export function openFederationPacket(packetBuffer, options = {}) {
+  const decoded = decodePacket(packetBuffer);
+  const kind = TYPE_TO_KIND[decoded.type];
+  if (!kind) throw new Error(`Packet type ${decoded.typeName} is not a federation packet`);
+  if (!verifyPacketSignature(packetBuffer)) throw new Error('Federation packet signature is invalid');
+
+  const recipient = normalizeEndpoint(
+    { ...options.recipientIdentity, scope: options.recipientScope ?? options.recipientIdentity?.scope },
+    'recipientIdentity',
+    { requireSecret: true }
+  );
+  if (!decoded.destination.equals(recipient.destination)) {
+    throw new Error(`Federation packet recipient mismatch: expected ${recipient.destinationHex}, got ${decoded.destinationHex}`);
+  }
+
+  const aad = federationAad(decoded.type, decoded.destination, decoded.senderPubkey);
+  let plaintext;
+  try {
+    plaintext = unsealPayload(
+      decoded.payload,
+      decoded.authTag,
+      decoded.ephemeralPubkey,
+      recipient.encryptionSecretKey,
+      { aad }
+    );
+  } catch (error) {
+    throw new Error(`Federation packet decryption failed: ${error.message}`);
+  }
+
+  let envelope;
+  try {
+    const text = new TextDecoder('utf-8', { fatal: true }).decode(plaintext);
+    envelope = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`Federation packet payload is not canonical JSON: ${error.message}`);
+  }
+
+  assertExactKeys(envelope, ENVELOPE_KEYS, 'federation envelope');
+  if (envelope.schema !== GHOSTMESH_FEDERATION_PACKET_SCHEMA || envelope.version !== 1) {
+    throw new Error('Unsupported federation envelope schema or version');
+  }
+  if (envelope.kind !== kind) {
+    throw new Error(`Federation envelope kind ${envelope.kind} does not match frame type ${kind}`);
+  }
+  if (!PACKET_ID_RE.test(String(envelope.packet_id || ''))) {
+    throw new Error('Federation envelope packet_id must be 32 lowercase hex characters');
+  }
+  if (envelope.correlation_id !== null && !PACKET_ID_RE.test(String(envelope.correlation_id || ''))) {
+    throw new Error('Federation envelope correlation_id must be null or 32 lowercase hex characters');
+  }
+  if (kind === FEDERATION_PACKET_KINDS.QUERY_RESPONSE && envelope.correlation_id === null) {
+    throw new Error('Federation query response is missing correlation_id');
+  }
+  assertIsoTimestamp(envelope.created_at, 'federation envelope created_at');
+  if (envelope.recipient_destination !== decoded.destinationHex) {
+    throw new Error('Federation envelope recipient destination does not match frame destination');
+  }
+
+  assertExactKeys(envelope.sender, ['destination', 'encryption_pubkey', 'scope'], 'federation envelope sender');
+  const sender = normalizeEndpoint({
+    publicKey: decoded.senderPubkey,
+    encryptionPublicKey: envelope.sender.encryption_pubkey,
+    destination: envelope.sender.destination,
+    scope: envelope.sender.scope,
+  }, 'federation envelope sender');
+
+  if (options.expectedKind && options.expectedKind !== kind) {
+    throw new Error(`Expected federation packet kind ${options.expectedKind}, got ${kind}`);
+  }
+  if (options.expectedCorrelationId !== undefined && envelope.correlation_id !== options.expectedCorrelationId) {
+    throw new Error(`Federation response correlation mismatch: expected ${options.expectedCorrelationId}, got ${envelope.correlation_id}`);
+  }
+  if (options.expectedSenderPublicKey) {
+    const expectedSender = toBuffer32(options.expectedSenderPublicKey, 'expectedSenderPublicKey');
+    if (!decoded.senderPubkey.equals(expectedSender)) throw new Error('Federation packet sender mismatch');
+  }
+
+  validateBody(kind, envelope.body);
+  if (canonicalize(envelope) !== plaintext.toString('utf8')) {
+    throw new Error('Federation packet payload is not in canonical JSON form');
+  }
+
+  return {
+    packetId: envelope.packet_id,
+    correlationId: envelope.correlation_id,
+    kind,
+    body: envelope.body,
+    createdAt: envelope.created_at,
+    sender: {
+      publicKey: Buffer.from(decoded.senderPubkey),
+      encryptionPublicKey: sender.encryptionPublicKey,
+      destination: sender.destination,
+      destinationHex: sender.destinationHex,
+      scope: sender.scope,
+    },
+    recipientDestinationHex: decoded.destinationHex,
+    replayIdentity: getPacketReplayIdentity(packetBuffer),
+    decoded,
+  };
+}