enigma-memory 0.1.18 → 0.1.22

package/packages/sdk/src/federation/ghostmesh-bridge.js

@@ -0,0 +1,497 @@
+import { EventEmitter } from 'node:events';
+import {
+  FEDERATION_PACKET_KINDS,
+  createFederationPacket,
+  deriveDestination,
+  hashFederationValue,
+  openFederationPacket,
+} from '../../../mesh/src/index.js';
+import {
+  createFederatedQueryRequest,
+  verifyBlindedMemoryGrant,
+} from './capability-grant.js';
+
+function publicKeyHex(value) {
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) return Buffer.from(value).toString('hex');
+  return String(value || '').toLowerCase();
+}
+
+function keyBuffer(value, name) {
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    const buffer = Buffer.from(value);
+    if (buffer.length === 32) return buffer;
+  } else if (typeof value === 'string' && /^[0-9a-fA-F]{64}$/.test(value)) {
+    return Buffer.from(value, 'hex');
+  }
+  throw new Error(`${name} must be exactly 32 bytes`);
+}
+
+function samePublicKey(left, right) {
+  return publicKeyHex(left) === publicKeyHex(right);
+}
+
+function peerDescriptor(peerId, peer) {
+  if (!peer || typeof peer !== 'object') throw new Error('peer descriptor is required');
+  if (typeof peerId !== 'string' || peerId.length === 0) throw new Error('peerId is required');
+  const publicKey = keyBuffer(peer.publicKey ?? peer.public_key, 'peer.publicKey');
+  const encryptionPublicKey = keyBuffer(
+    peer.encryptionPublicKey ?? peer.encryption_public_key,
+    'peer.encryptionPublicKey'
+  );
+  if (typeof peer.scope !== 'string' || peer.scope.length === 0) throw new Error('peer.scope is required');
+  const destination = deriveDestination(publicKey, encryptionPublicKey, peer.scope);
+  const declaredDestination = peer.destination ?? peer.destinationHex ?? peer.destination_hex;
+  if (declaredDestination !== undefined &&
+      !destination.equals(keyBuffer(declaredDestination, 'peer.destination'))) {
+    throw new Error('peer.destination does not match its signing key, encryption key, and scope');
+  }
+  return {
+    peerId,
+    publicKey,
+    encryptionPublicKey,
+    destination,
+    scope: peer.scope,
+    allowGrants: peer.allowGrants !== false,
+  };
+}
+const MAX_FEDERATION_BRIDGE_PEERS = 1_024;
+const MAX_FEDERATION_BRIDGE_PENDING_QUERIES = 256;
+const MAX_FEDERATION_BRIDGE_REPLAYS = 10_000;
+const FEDERATION_BRIDGE_REPLAY_TTL_MS = 120_000;
+
+/**
+ * Transport-neutral bridge between SDK federation authorization and encrypted,
+ * signed GhostMesh frames. Any EventEmitter-compatible GhostMesh transport with
+ * start(), stop(), and send(buffer, peerId) works, including in-memory and WS.
+ */
+export class GhostMeshFederationBridge extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    if (!options.enigma) throw new Error('enigma SDK instance is required');
+    if (!options.transport || typeof options.transport.send !== 'function' ||
+        typeof options.transport.on !== 'function') {
+      throw new Error('GhostMesh transport with send() and on() is required');
+    }
+
+    this.enigma = options.enigma;
+    this.router = options.router || options.enigma.federation;
+    this.identity = options.identity || options.enigma.mesh?.identity;
+    if (!this.identity) throw new Error('mesh identity is required');
+    this.scope = options.scope || this.identity.scope || options.enigma.scope;
+    if (!this.scope) throw new Error('mesh identity scope is required');
+    this.transport = options.transport;
+    this.manageTransport = options.manageTransport !== false;
+    this.requestTimeoutMs = options.requestTimeoutMs === undefined ? 5000 : options.requestTimeoutMs;
+    if (!Number.isSafeInteger(this.requestTimeoutMs) || this.requestTimeoutMs < 1) {
+      throw new Error('requestTimeoutMs must be a positive safe integer');
+    }
+
+    this.peers = new Map();
+    this.pendingQueries = new Map();
+    this.knownGrants = new Map();
+    this.seenPackets = new Map();
+    this.started = false;
+    this._packetHandler = ({ packetBuffer, fromPeerId, transportId }) => {
+      this.handlePacket(packetBuffer, fromPeerId, transportId).catch((error) => {
+        this.emit('rejected', { error, fromPeerId, transportId });
+      });
+    };
+
+    if (options.state !== undefined) this.importState(options.state);
+    for (const [grantId, record] of this.router.activeGrants) {
+      this.knownGrants.set(grantId, record.grant);
+    }
+  }
+
+  get localEndpoint() {
+    return { ...this.identity, scope: this.scope };
+  }
+
+  // Registration is the bridge's explicit peer-admission step. Callers may set
+  // allowGrants:false to admit query traffic without consenting to grants.
+  registerPeer(peerId, peer) {
+    if (!this.peers.has(peerId) && this.peers.size >= MAX_FEDERATION_BRIDGE_PEERS) {
+      throw new Error(`Federation peer capacity ${MAX_FEDERATION_BRIDGE_PEERS} reached`);
+    }
+    const descriptor = peerDescriptor(peerId, peer);
+    this.peers.set(peerId, descriptor);
+    return descriptor;
+  }
+
+  unregisterPeer(peerId) {
+    return this.peers.delete(peerId);
+  }
+
+  resolvePeer(target) {
+    if (typeof target === 'string') {
+      const peer = this.peers.get(target);
+      if (!peer) throw new Error(`Unknown federation peer: ${target}`);
+      return peer;
+    }
+    if (!target || typeof target !== 'object') throw new Error('Federation peer target is required');
+    const peerId = target.peerId ?? target.peer_id;
+    return peerDescriptor(peerId, target);
+  }
+
+  async start() {
+    if (this.started) return this;
+    this.transport.on('packet', this._packetHandler);
+    if (this.manageTransport && !this.transport.running) await this.transport.start();
+    this.started = true;
+    return this;
+  }
+
+  async stop() {
+    if (!this.started) return;
+    this.transport.off('packet', this._packetHandler);
+    for (const [packetId, pending] of this.pendingQueries) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error(`Federation bridge stopped before response to ${packetId}`));
+    }
+    this.pendingQueries.clear();
+    this.started = false;
+    if (this.manageTransport && this.transport.running) await this.transport.stop();
+  }
+
+  exportState() {
+    return this.router.exportState();
+  }
+
+  importState(state) {
+    this.router.importState(state);
+    this.knownGrants.clear();
+    for (const [grantId, record] of this.router.activeGrants) {
+      this.knownGrants.set(grantId, record.grant);
+    }
+    return this;
+  }
+
+  getGrant(grantId) {
+    return this.knownGrants.get(grantId) || this.router.activeGrants.get(grantId)?.grant || null;
+  }
+
+  async sendFrame(frame, peerId) {
+    if (!this.started) throw new Error('Federation bridge must be started before sending');
+    const sent = await this.transport.send(frame.packetBuffer, peerId);
+    if (!sent) throw new Error(`GhostMesh transport could not send federation packet to ${peerId}`);
+    return frame;
+  }
+
+  async persistRouterMutation(snapshot) {
+    try {
+      await this.router.persistStateMutation();
+    } catch (error) {
+      this.router.importState(snapshot);
+      this.knownGrants.clear();
+      for (const [grantId, record] of this.router.activeGrants) {
+        this.knownGrants.set(grantId, record.grant);
+      }
+      throw error;
+    }
+  }
+
+  async distributeGrant(grant, target) {
+    const peer = this.resolvePeer(target);
+    const verdict = verifyBlindedMemoryGrant(grant, { expectedGranteePubkey: publicKeyHex(peer.publicKey) });
+    if (!verdict.ok) throw new Error(`Cannot distribute invalid capability grant: ${verdict.errors.join('; ')}`);
+    if (!samePublicKey(grant.granter_pubkey, this.identity.publicKey)) {
+      throw new Error('Only the grant granter may distribute a capability grant');
+    }
+
+    const priorState = this.router.exportState();
+    this.router.registerGrant(grant);
+    this.knownGrants.set(grant.grant_id, grant);
+    await this.persistRouterMutation(priorState);
+    const frame = createFederationPacket({
+      kind: FEDERATION_PACKET_KINDS.CAPABILITY_GRANT,
+      senderIdentity: this.localEndpoint,
+      senderScope: this.scope,
+      recipient: peer,
+      body: { grant },
+    });
+    await this.sendFrame(frame, peer.peerId);
+    return { ok: true, grant_id: grant.grant_id, packet_id: frame.packetId };
+  }
+
+  async query(grantOrId, query, target, options = {}) {
+    const grant = typeof grantOrId === 'string' ? this.getGrant(grantOrId) : grantOrId;
+    if (!grant) throw new Error(`Unknown capability grant: ${grantOrId}`);
+    if (this.router.revokedGrantIds.has(grant.grant_id)) {
+      throw new Error(`Capability grant ${grant.grant_id} has been revoked by granter`);
+    }
+    const verdict = verifyBlindedMemoryGrant(grant, {
+      expectedGranteePubkey: publicKeyHex(this.identity.publicKey),
+    });
+    if (!verdict.ok) throw new Error(`Cannot query with invalid capability grant: ${verdict.errors.join('; ')}`);
+
+    const peer = this.resolvePeer(target);
+    if (!samePublicKey(grant.granter_pubkey, peer.publicKey)) {
+      throw new Error('Federated query destination does not match the grant granter');
+    }
+    const topK = options.topK === undefined ? 5 : options.topK;
+    if (!Number.isSafeInteger(topK) || topK < 1 || topK > 100) {
+      throw new Error('topK must be an integer between 1 and 100');
+    }
+
+    const request = createFederatedQueryRequest({
+      grant,
+      query,
+      requesterSecretKey: this.identity.secretKey,
+      requesterPublicKey: this.identity.publicKey,
+      nonce: options.nonce,
+      timestamp: options.timestamp,
+    });
+    const body = { request, top_k: topK };
+    const requestHash = hashFederationValue(body);
+    const frame = createFederationPacket({
+      kind: FEDERATION_PACKET_KINDS.QUERY_REQUEST,
+      senderIdentity: this.localEndpoint,
+      senderScope: this.scope,
+      recipient: peer,
+      body,
+      hopTtl: options.hopTtl,
+    });
+
+    if (this.pendingQueries.size >= MAX_FEDERATION_BRIDGE_PENDING_QUERIES) {
+      throw new Error(`Federation pending query capacity ${MAX_FEDERATION_BRIDGE_PENDING_QUERIES} reached`);
+    }
+    const responsePromise = new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingQueries.delete(frame.packetId);
+        reject(new Error(`Timed out waiting for federated query response ${frame.packetId}`));
+      }, options.timeoutMs ?? this.requestTimeoutMs);
+      timer.unref?.();
+      this.pendingQueries.set(frame.packetId, {
+        grant,
+        requestHash,
+        expectedSenderPublicKey: peer.publicKey,
+        resolve,
+        reject,
+        timer,
+      });
+    });
+
+    try {
+      await this.sendFrame(frame, peer.peerId);
+    } catch (error) {
+      const pending = this.pendingQueries.get(frame.packetId);
+      if (pending) {
+        clearTimeout(pending.timer);
+        this.pendingQueries.delete(frame.packetId);
+        pending.reject(error);
+      }
+    }
+    return await responsePromise;
+  }
+
+  async revoke(grantOrId, target, options = {}) {
+    const grant = typeof grantOrId === 'string' ? this.getGrant(grantOrId) : grantOrId;
+    if (!grant) throw new Error(`Unknown capability grant: ${grantOrId}`);
+    if (!samePublicKey(grant.granter_pubkey, this.identity.publicKey)) {
+      throw new Error('Only the grant granter may revoke a capability grant');
+    }
+    const peer = this.resolvePeer(target);
+    if (!samePublicKey(grant.grantee_pubkey, peer.publicKey)) {
+      throw new Error('Capability revocation destination does not match the grant grantee');
+    }
+    const revokedAt = options.revokedAt || new Date().toISOString();
+    const frame = createFederationPacket({
+      kind: FEDERATION_PACKET_KINDS.CAPABILITY_REVOCATION,
+      senderIdentity: this.localEndpoint,
+      senderScope: this.scope,
+      recipient: peer,
+      body: { grant_id: grant.grant_id, revoked_at: revokedAt },
+    });
+
+    const priorState = this.router.exportState();
+    this.router.revokeGrant(grant.grant_id);
+    this.knownGrants.delete(grant.grant_id);
+    await this.persistRouterMutation(priorState);
+    await this.sendFrame(frame, peer.peerId);
+    return { ok: true, grant_id: grant.grant_id, packet_id: frame.packetId, revoked_at: revokedAt };
+  }
+
+  async handlePacket(packetBuffer, fromPeerId, transportId = this.transport.id) {
+    const opened = openFederationPacket(packetBuffer, {
+      recipientIdentity: this.localEndpoint,
+      recipientScope: this.scope,
+    });
+    let resolvedPeerId = fromPeerId;
+    let peer = this.peers.get(resolvedPeerId);
+    if (!peer) {
+      const matches = Array.from(this.peers.entries())
+        .filter(([, candidate]) => samePublicKey(opened.sender.publicKey, candidate.publicKey));
+      if (matches.length !== 1) {
+        throw new Error(`Federation packet arrived from unregistered peer: ${fromPeerId}`);
+      }
+      [[resolvedPeerId, peer]] = matches;
+    }
+    if (!samePublicKey(opened.sender.publicKey, peer.publicKey)) {
+      throw new Error('Federation packet sender does not match the registered transport peer');
+    }
+    fromPeerId = resolvedPeerId;
+    const now = Date.now();
+    for (const [identity, seenAt] of this.seenPackets) {
+      if (now - seenAt > FEDERATION_BRIDGE_REPLAY_TTL_MS) this.seenPackets.delete(identity);
+    }
+    if (this.seenPackets.has(opened.replayIdentity)) {
+      throw new Error(`GhostMesh federation replay rejected: ${opened.replayIdentity}`);
+    }
+    if (this.seenPackets.size >= MAX_FEDERATION_BRIDGE_REPLAYS) {
+      throw new Error(`Federation packet replay cache capacity ${MAX_FEDERATION_BRIDGE_REPLAYS} reached`);
+    }
+    this.seenPackets.set(opened.replayIdentity, now);
+
+    try {
+      switch (opened.kind) {
+        case FEDERATION_PACKET_KINDS.CAPABILITY_GRANT:
+          return await this.handleGrant(opened, fromPeerId, transportId, peer);
+        case FEDERATION_PACKET_KINDS.QUERY_REQUEST:
+          return await this.handleQuery(opened, fromPeerId, transportId);
+        case FEDERATION_PACKET_KINDS.QUERY_RESPONSE:
+          return this.handleResponse(opened, fromPeerId, transportId);
+        case FEDERATION_PACKET_KINDS.CAPABILITY_REVOCATION:
+          return await this.handleRevocation(opened, fromPeerId, transportId);
+        default:
+          throw new Error(`Unsupported federation packet kind: ${opened.kind}`);
+      }
+    } catch (error) {
+      this.seenPackets.delete(opened.replayIdentity);
+      throw error;
+    }
+  }
+
+  async handleGrant(opened, fromPeerId, transportId, peer) {
+    if (!peer.allowGrants) {
+      throw new Error(`Federation peer ${fromPeerId} is not admitted to send capability grants`);
+    }
+    const grant = opened.body.grant;
+    if (!samePublicKey(opened.sender.publicKey, grant.granter_pubkey)) {
+      throw new Error('Capability grant packet sender does not match grant granter');
+    }
+    const verdict = verifyBlindedMemoryGrant(grant, {
+      expectedGranteePubkey: publicKeyHex(this.identity.publicKey),
+    });
+    if (!verdict.ok) throw new Error(`Received invalid capability grant: ${verdict.errors.join('; ')}`);
+    const priorState = this.router.exportState();
+    this.router.registerGrant(grant);
+    this.knownGrants.set(grant.grant_id, grant);
+    await this.persistRouterMutation(priorState);
+    const event = { grant, packet_id: opened.packetId, fromPeerId, transportId };
+    this.emit('grant', event);
+    return { action: 'GRANT_REGISTERED', ...event };
+  }
+
+  async handleQuery(opened, fromPeerId, transportId) {
+    const request = opened.body.request;
+    const grant = request.grant;
+    if (!samePublicKey(opened.sender.publicKey, request.requester_pubkey)) {
+      throw new Error('Federated query packet sender does not match request proof-of-possession key');
+    }
+    if (!samePublicKey(grant.granter_pubkey, this.identity.publicKey)) {
+      throw new Error('Federated query grant is not addressed to this granter');
+    }
+
+    const requestHash = hashFederationValue(opened.body);
+    let responseBody;
+    try {
+      const result = await this.router.queryFederatedCluster(request, undefined, { topK: opened.body.top_k });
+      const unlimitedAccess = !Number.isFinite(result.remainingAccess);
+      responseBody = {
+        ok: true,
+        result: {
+          ...result,
+          remainingAccess: unlimitedAccess ? null : result.remainingAccess,
+          unlimitedAccess,
+        },
+        error: null,
+        request_hash: requestHash,
+      };
+    } catch (error) {
+      responseBody = {
+        ok: false,
+        result: null,
+        error: error.message,
+        request_hash: requestHash,
+      };
+    }
+
+    const responseFrame = createFederationPacket({
+      kind: FEDERATION_PACKET_KINDS.QUERY_RESPONSE,
+      senderIdentity: this.localEndpoint,
+      senderScope: this.scope,
+      recipient: opened.sender,
+      correlationId: opened.packetId,
+      body: responseBody,
+    });
+    await this.sendFrame(responseFrame, fromPeerId);
+    const event = {
+      request,
+      response: responseBody,
+      packet_id: opened.packetId,
+      response_packet_id: responseFrame.packetId,
+      fromPeerId,
+      transportId,
+    };
+    this.emit('query', event);
+    return { action: 'QUERY_RESPONDED', ...event, responsePacket: responseFrame.packetBuffer };
+  }
+
+  handleResponse(opened, fromPeerId, transportId) {
+    const pending = this.pendingQueries.get(opened.correlationId);
+    if (!pending) {
+      throw new Error(`Federated response correlation is unknown or already settled: ${opened.correlationId}`);
+    }
+    if (!samePublicKey(opened.sender.publicKey, pending.expectedSenderPublicKey)) {
+      throw new Error('Federated response sender does not match query destination');
+    }
+    if (opened.body.request_hash !== pending.requestHash) {
+      throw new Error('Federated response request hash does not match the correlated query');
+    }
+    if (opened.body.ok && (opened.body.result.grant_id !== pending.grant.grant_id ||
+        opened.body.result.scope !== pending.grant.scope)) {
+      throw new Error('Federated response result does not match the capability grant');
+    }
+
+    clearTimeout(pending.timer);
+    this.pendingQueries.delete(opened.correlationId);
+    if (opened.body.ok) {
+      pending.resolve({
+        ...opened.body.result,
+        request_packet_id: opened.correlationId,
+        response_packet_id: opened.packetId,
+      });
+    } else {
+      pending.reject(new Error(`Federated query rejected: ${opened.body.error}`));
+    }
+    const event = { response: opened.body, packet_id: opened.packetId, fromPeerId, transportId };
+    this.emit('response', event);
+    return { action: 'RESPONSE_CORRELATED', ...event };
+  }
+
+  async handleRevocation(opened, fromPeerId, transportId) {
+    const grantId = opened.body.grant_id;
+    const grant = this.getGrant(grantId);
+    if (!grant) throw new Error(`Received revocation for unknown capability grant: ${grantId}`);
+    if (!samePublicKey(opened.sender.publicKey, grant.granter_pubkey)) {
+      throw new Error('Capability revocation packet sender does not match grant granter');
+    }
+    const priorState = this.router.exportState();
+    this.router.revokeGrant(grantId);
+    this.knownGrants.delete(grantId);
+    await this.persistRouterMutation(priorState);
+    const event = {
+      grant_id: grantId,
+      revoked_at: opened.body.revoked_at,
+      packet_id: opened.packetId,
+      fromPeerId,
+      transportId,
+    };
+    this.emit('revocation', event);
+    return { action: 'GRANT_REVOKED', ...event };
+  }
+}
+
+export function createGhostMeshFederationBridge(options) {
+  return new GhostMeshFederationBridge(options);
+}

package/packages/sdk/src/federation/index.js

@@ -0,0 +1,3 @@
+export * from './capability-grant.js';
+export * from './federation-router.js';
+export * from './ghostmesh-bridge.js';