enigma-memory 0.1.18 → 0.1.22

package/packages/sdk/src/federation/federation-router.js

@@ -0,0 +1,360 @@
+// Enigma Cross-Agent Memory Federation Router.
+// Mediates selective capability-based queries across sovereign agent memory clusters
+// with cryptographic proof-of-possession, grantee identity binding, and nonce replay protection.
+import {
+  verifyBlindedMemoryGrant,
+  createFederatedQueryRequest,
+  verifyFederatedQueryRequest,
+  getGrantSignablePayload,
+  FEDERATED_QUERY_REQUEST_SCHEMA,
+} from './capability-grant.js';
+import { normalizeMemoryType } from '../intelligence/ontology.js';
+
+export const FEDERATION_ROUTER_STATE_SCHEMA = 'enigma.federation_router_state.v1';
+export const MAX_ACTIVE_FEDERATION_GRANTS = 1_024;
+export const MAX_REVOKED_FEDERATION_GRANTS = 4_096;
+export const MAX_SEEN_FEDERATION_NONCES = 10_000;
+
+export class EnigmaFederationRouter {
+  /**
+   * @param {Object} [options]
+   * @param {import('../index.js').Enigma} options.enigma - Sovereign agent instance
+   */
+  constructor(options = {}) {
+    if (!options.enigma) throw new Error('enigma SDK instance is required for federation router');
+    this.enigma = options.enigma;
+    /** @type {Map<string, { grant: Object, usedCount: number }>} */
+    this.activeGrants = new Map();
+    /** @type {Set<string>} */
+    this.revokedGrantIds = new Set();
+    /** @type {Map<string, number>} */
+    this.seenNonces = new Map();
+    this.onStateMutation = typeof options.onStateMutation === 'function'
+      ? options.onStateMutation
+      : null;
+    if (options.state !== undefined) this.importState(options.state);
+  }
+  setStateMutationHandler(handler) {
+    if (handler !== null && typeof handler !== 'function') {
+      throw new TypeError('federation state mutation handler must be a function or null');
+    }
+    this.onStateMutation = handler;
+    return this;
+  }
+
+  async persistStateMutation() {
+    if (this.onStateMutation) await this.onStateMutation(this.exportState());
+  }
+
+
+  /**
+   * Registers a valid BlindedMemoryGrant in the local router.
+   * @param {Object} grant
+   * @returns {{ ok: boolean, grant_id: string }}
+   */
+  registerGrant(grant) {
+    if (!grant || typeof grant !== 'object' || typeof grant.grant_id !== 'string') {
+      throw new Error('Cannot register invalid capability grant: grant object and grant_id are required');
+    }
+    if (this.revokedGrantIds.has(grant.grant_id)) {
+      throw new Error(`Cannot register revoked capability grant: ${grant.grant_id}`);
+    }
+
+    const verdict = verifyBlindedMemoryGrant(grant);
+    if (!verdict.ok) {
+      throw new Error(`Cannot register invalid capability grant: ${verdict.errors.join('; ')}`);
+    }
+    const myPubHex = this.enigma.mesh.identity?.publicKey?.toString('hex');
+    if (myPubHex && grant.granter_pubkey !== myPubHex && grant.grantee_pubkey !== myPubHex) {
+      throw new Error(`Cannot register capability grant ${grant.grant_id}: local agent is neither granter nor grantee`);
+    }
+    if (!this.activeGrants.has(grant.grant_id) && this.activeGrants.size >= MAX_ACTIVE_FEDERATION_GRANTS) {
+      throw new Error(`Cannot register capability grant: active grant capacity ${MAX_ACTIVE_FEDERATION_GRANTS} reached`);
+    }
+
+    const existing = this.activeGrants.get(grant.grant_id);
+    if (existing) {
+      const sameGrant = getGrantSignablePayload(existing.grant) === getGrantSignablePayload(grant) &&
+        existing.grant.signature === grant.signature;
+      if (!sameGrant) throw new Error(`Capability grant ID collision for ${grant.grant_id}`);
+      return { ok: true, grant_id: grant.grant_id };
+    }
+    this.activeGrants.set(grant.grant_id, { grant, usedCount: 0 });
+    return { ok: true, grant_id: grant.grant_id };
+  }
+
+  /**
+   * Revokes a capability grant, permanently denying subsequent queries.
+   * @param {string} grantId
+   * @returns {boolean}
+   */
+  revokeGrant(grantId) {
+    if (typeof grantId !== 'string' || grantId.length === 0) return false;
+    if (!this.revokedGrantIds.has(grantId) && this.revokedGrantIds.size >= MAX_REVOKED_FEDERATION_GRANTS) {
+      throw new Error(`Cannot revoke capability grant: revocation capacity ${MAX_REVOKED_FEDERATION_GRANTS} reached`);
+    }
+    this.revokedGrantIds.add(grantId);
+    return true;
+  }
+
+  /**
+   * Returns a JSON-safe snapshot of all authorization state needed to preserve
+   * replay protection, access counts, registered grants, and revocations.
+   */
+  exportState() {
+    return {
+      schema: FEDERATION_ROUTER_STATE_SCHEMA,
+      version: 1,
+      active_grants: Array.from(this.activeGrants.entries())
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([, record]) => ({
+          grant: JSON.parse(JSON.stringify(record.grant)),
+          used_count: record.usedCount,
+        })),
+      revoked_grant_ids: Array.from(this.revokedGrantIds).sort(),
+      seen_nonces: Array.from(this.seenNonces.entries())
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, seenAt]) => ({ key, seen_at: seenAt })),
+    };
+  }
+
+  /**
+   * Strictly restores a snapshot created by exportState(). Validation completes
+   * before any live authorization state is changed.
+   */
+  importState(state) {
+    if (!state || typeof state !== 'object' ||
+        state.schema !== FEDERATION_ROUTER_STATE_SCHEMA || state.version !== 1) {
+      throw new Error('Invalid federation router state schema or version');
+    }
+    if (!Array.isArray(state.active_grants) ||
+        !Array.isArray(state.revoked_grant_ids) ||
+        !Array.isArray(state.seen_nonces)) {
+      throw new Error('Federation router state arrays are required');
+    }
+    if (
+      state.active_grants.length > MAX_ACTIVE_FEDERATION_GRANTS
+      || state.revoked_grant_ids.length > MAX_REVOKED_FEDERATION_GRANTS
+      || state.seen_nonces.length > MAX_SEEN_FEDERATION_NONCES
+    ) {
+      throw new Error('Federation router state exceeds a safe authorization-state bound');
+    }
+
+    const nextActive = new Map();
+    const nextRevoked = new Set();
+    const nextNonces = new Map();
+    const myPubHex = this.enigma.mesh.identity?.publicKey?.toString('hex');
+
+    for (const entry of state.active_grants) {
+      if (!entry || typeof entry !== 'object' || !entry.grant ||
+          !Number.isSafeInteger(entry.used_count) || entry.used_count < 0) {
+        throw new Error('Invalid active grant state entry');
+      }
+      const verdict = verifyBlindedMemoryGrant(entry.grant, {
+        asOfTime: new Date(entry.grant.issued_at).getTime(),
+      });
+      if (!verdict.ok) {
+        throw new Error(`Invalid grant in federation router state: ${verdict.errors.join('; ')}`);
+      }
+      if (myPubHex && entry.grant.granter_pubkey !== myPubHex && entry.grant.grantee_pubkey !== myPubHex) {
+        throw new Error(`Federation router state grant ${entry.grant.grant_id} is not bound to the local agent`);
+      }
+      if (entry.grant.max_access_count > 0 && entry.used_count > entry.grant.max_access_count) {
+        throw new Error(`Federation router state usage exceeds grant ${entry.grant.grant_id} access limit`);
+      }
+      if (nextActive.has(entry.grant.grant_id)) {
+        throw new Error(`Duplicate active grant in federation router state: ${entry.grant.grant_id}`);
+      }
+      nextActive.set(entry.grant.grant_id, {
+        grant: JSON.parse(JSON.stringify(entry.grant)),
+        usedCount: entry.used_count,
+      });
+    }
+
+    for (const grantId of state.revoked_grant_ids) {
+      if (typeof grantId !== 'string' || grantId.length === 0 || nextRevoked.has(grantId)) {
+        throw new Error('Invalid or duplicate revoked grant ID in federation router state');
+      }
+      nextRevoked.add(grantId);
+    }
+
+    for (const entry of state.seen_nonces) {
+      if (!entry || typeof entry.key !== 'string' ||
+          !/^.+:[0-9a-f]{32}$/.test(entry.key) ||
+          !Number.isSafeInteger(entry.seen_at) || entry.seen_at < 0 ||
+          nextNonces.has(entry.key)) {
+        throw new Error('Invalid or duplicate nonce entry in federation router state');
+      }
+      nextNonces.set(entry.key, entry.seen_at);
+    }
+
+    this.activeGrants = nextActive;
+    this.revokedGrantIds = nextRevoked;
+    this.seenNonces = nextNonces;
+    return this;
+  }
+
+  /**
+   * Clean up expired seen nonces older than TTL.
+   * @param {number} [ttlMs=600000]
+   */
+  pruneSeenNonces(ttlMs = 600000) {
+    if (!Number.isSafeInteger(ttlMs) || ttlMs < 300000) {
+      throw new Error('Nonce replay TTL must be a safe integer of at least 300000ms');
+    }
+    const now = Date.now();
+    let pruned = 0;
+    for (const [key, ts] of this.seenNonces.entries()) {
+      if (now - ts > ttlMs) {
+        this.seenNonces.delete(key);
+        pruned++;
+      }
+    }
+    return pruned;
+  }
+
+  /**
+   * Executes a capability-gated federated memory query under a verified grant.
+   * Authenticates the requester via cryptographic proof-of-possession signature matching
+   * `grant.grantee_pubkey`, validates freshness/replay protection, and enforces ABAC ontology scoping.
+   *
+   * @param {Object} grantOrRequest - Signed BlindedMemoryGrant OR signed FederatedQueryRequest
+   * @param {string} [query] - Agent search prompt
+   * @param {Object} [options]
+   * @param {Buffer|string} [options.requesterSecretKey] - 32-byte private key of the grantee for inline signature
+   * @param {Buffer|string} [options.requesterPublicKey] - 32-byte public key of the grantee
+   * @param {import('../index.js').Enigma} [options.requesterAgent] - Grantee agent instance with mesh identity
+   * @param {Object} [options.authorization] - Explicit authorization envelope { requester_pubkey, nonce, timestamp, signature }
+   * @param {number} [options.topK=5]
+   * @returns {Promise<{ ok: boolean, grant_id: string, scope: string, items: Array<{ id: string, text: string, type: string, score: number }>, remainingAccess: number }>}
+   */
+  async queryFederatedCluster(grantOrRequest, query, options = {}) {
+    this.pruneSeenNonces();
+
+    let request;
+    let actualQuery = query;
+
+    if (grantOrRequest && grantOrRequest.schema === FEDERATED_QUERY_REQUEST_SCHEMA) {
+      request = grantOrRequest;
+      actualQuery = request.query;
+    } else {
+      const grant = grantOrRequest;
+      if (typeof actualQuery !== 'string' || actualQuery.trim().length === 0) {
+        throw new Error('Query string is required for federated cluster search');
+      }
+
+      let requesterSecretKey = options.requesterSecretKey;
+      let requesterPublicKey = options.requesterPublicKey;
+      if (!requesterSecretKey && options.requesterAgent?.mesh?.identity) {
+        requesterSecretKey = options.requesterAgent.mesh.identity.secretKey;
+        requesterPublicKey = options.requesterAgent.mesh.identity.publicKey;
+      }
+
+      if (requesterSecretKey) {
+        request = createFederatedQueryRequest({
+          grant,
+          query: actualQuery,
+          requesterSecretKey,
+          requesterPublicKey,
+        });
+      } else if (options.authorization) {
+        request = {
+          schema: FEDERATED_QUERY_REQUEST_SCHEMA,
+          version: 1,
+          grant,
+          grant_id: grant.grant_id,
+          query: actualQuery,
+          ...options.authorization,
+        };
+      } else {
+        throw new Error(
+          'Grantee proof-of-possession required: Provide requesterAgent, requesterSecretKey, or a signed query authorization envelope matching grant.grantee_pubkey'
+        );
+      }
+    }
+
+    const reqVerdict = verifyFederatedQueryRequest(request);
+    if (!reqVerdict.ok) {
+      throw new Error(`Federated query authorization rejected: ${reqVerdict.errors.join('; ')}`);
+    }
+
+    const grant = request.grant;
+    const grantId = grant.grant_id;
+    if (this.revokedGrantIds.has(grantId)) {
+      throw new Error(`Capability grant ${grantId} has been revoked by granter`);
+    }
+
+    const myPubHex = this.enigma.mesh.identity?.publicKey?.toString('hex');
+    if (myPubHex && grant.granter_pubkey !== myPubHex) {
+      throw new Error(`Granter public key mismatch: grant issued by ${grant.granter_pubkey}, local agent is ${myPubHex}`);
+    }
+
+    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 nonceKey = `${grantId}:${request.nonce}`;
+    if (this.seenNonces.has(nonceKey)) {
+      throw new Error(`Replay attack detected: nonce ${request.nonce} has already been consumed for grant ${grantId}`);
+    }
+    if (!this.seenNonces.has(nonceKey) && this.seenNonces.size >= MAX_SEEN_FEDERATION_NONCES) {
+      throw new Error(`Federation replay cache capacity ${MAX_SEEN_FEDERATION_NONCES} reached`);
+    }
+
+    let record = this.activeGrants.get(grantId);
+    const createdRecord = !record;
+    if (record) {
+      const sameGrant = getGrantSignablePayload(record.grant) === getGrantSignablePayload(grant) &&
+        record.grant.signature === grant.signature;
+      if (!sameGrant) throw new Error(`Capability grant ID collision for ${grantId}`);
+    } else {
+      if (this.activeGrants.size >= MAX_ACTIVE_FEDERATION_GRANTS) {
+        throw new Error(`Active federation grant capacity ${MAX_ACTIVE_FEDERATION_GRANTS} reached`);
+      }
+      record = { grant, usedCount: 0 };
+      this.activeGrants.set(grantId, record);
+    }
+
+    if (grant.max_access_count > 0 && record.usedCount >= grant.max_access_count) {
+      if (createdRecord) this.activeGrants.delete(grantId);
+      throw new Error(`Access limit exceeded: grant ${grantId} has exhausted its ${grant.max_access_count} queries limit`);
+    }
+
+    // Consume and durably commit authorization before recall so concurrent
+    // requests cannot race limits and a successful response cannot outlive the
+    // persisted replay/count state.
+    this.seenNonces.set(nonceKey, Date.now());
+    record.usedCount += 1;
+    try {
+      await this.persistStateMutation();
+    } catch (error) {
+      this.seenNonces.delete(nonceKey);
+      if (createdRecord) this.activeGrants.delete(grantId);
+      else record.usedCount -= 1;
+      throw new Error(`Federation authorization state persistence failed: ${error.message}`);
+    }
+    const allowedTypes = grant.allowed_types.length > 0
+      ? new Set(grant.allowed_types.map(normalizeMemoryType))
+      : null;
+    const rawRecalls = await this.enigma.recall(actualQuery, {
+      scope: grant.scope,
+      topK,
+    });
+    const filteredItems = rawRecalls.filter((item) =>
+      item.scope === grant.scope && (!allowedTypes || allowedTypes.has(item.type))
+    );
+
+    const remainingAccess = grant.max_access_count > 0
+      ? Math.max(0, grant.max_access_count - record.usedCount)
+      : Infinity;
+
+    return {
+      ok: true,
+      grant_id: grantId,
+      scope: grant.scope,
+      items: filteredItems,
+      remainingAccess,
+    };
+  }
+}