enigma-memory 0.1.17 → 0.1.22

package/packages/sdk/src/federation/capability-grant.js

@@ -0,0 +1,389 @@
+// Enigma Blinded Memory Capability Grants.
+// Issues and validates cryptographically signed capability grants for
+// selective, privacy-preserving cross-agent memory federation.
+import crypto from 'node:crypto';
+import { normalizeMemoryType, VALID_MEMORY_TYPES } from '../intelligence/ontology.js';
+
+export const BLINDED_GRANT_SCHEMA = 'enigma.blinded_grant.v1';
+export const FEDERATED_QUERY_REQUEST_SCHEMA = 'enigma.federated_query_request.v1';
+
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+const ED25519_PKCS8_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex');
+
+/**
+ * Computes canonical signable string for a capability grant.
+ * @param {Object} grant
+ * @returns {string}
+ */
+export function getGrantSignablePayload(grant) {
+  return JSON.stringify({
+    schema: grant.schema || BLINDED_GRANT_SCHEMA,
+    version: grant.version || 1,
+    grant_id: grant.grant_id,
+    granter_agent_id: grant.granter_agent_id,
+    granter_pubkey: grant.granter_pubkey,
+    grantee_pubkey: grant.grantee_pubkey,
+    scope: grant.scope,
+    allowed_types: (grant.allowed_types || []).slice().sort(),
+    max_access_count: grant.max_access_count,
+    valid_until: grant.valid_until,
+    issued_at: grant.issued_at,
+    metadata: grant.metadata || {},
+  });
+}
+
+/**
+ * Creates and cryptographically signs a BlindedMemoryGrant.
+ * @param {Object} params
+ * @param {string} params.granterAgentId - Sovereign agent identifier
+ * @param {Buffer|string} params.granterSecretKey - 32-byte Ed25519 private key
+ * @param {Buffer|string} params.granterPublicKey - 32-byte Ed25519 public key
+ * @param {Buffer|string} params.granteePublicKey - 32-byte Ed25519 public key of receiving agent
+ * @param {string} [params.scope='enigma.global'] - Scope allowed for extraction
+ * @param {string[]} [params.allowedTypes] - Allowed ontology types ('policy', 'preference', etc.)
+ * @param {number} [params.maxAccessCount=100] - Usage limit (0 = unlimited)
+ * @param {number|string|Date} [params.validUntil] - Expiration timestamp
+ * @param {Object} [params.metadata={}]
+ * @returns {Object} Signed BlindedMemoryGrant
+ */
+export function createBlindedMemoryGrant(params) {
+  if (!params.granterAgentId) throw new Error('granterAgentId is required');
+  if (!params.granterSecretKey || !params.granterPublicKey) {
+    throw new Error('granterSecretKey and granterPublicKey are required');
+  }
+  if (!params.granteePublicKey) throw new Error('granteePublicKey is required');
+
+  const granterPubHex = Buffer.isBuffer(params.granterPublicKey)
+    ? params.granterPublicKey.toString('hex')
+    : String(params.granterPublicKey).toLowerCase();
+  const granteePubHex = Buffer.isBuffer(params.granteePublicKey)
+    ? params.granteePublicKey.toString('hex')
+    : String(params.granteePublicKey).toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(granterPubHex)) throw new Error('granterPublicKey must be exactly 32 bytes');
+  if (!/^[0-9a-f]{64}$/.test(granteePubHex)) throw new Error('granteePublicKey must be exactly 32 bytes');
+  const privBuf = Buffer.isBuffer(params.granterSecretKey)
+    ? params.granterSecretKey
+    : Buffer.from(params.granterSecretKey, 'hex');
+  if (privBuf.length !== 32) throw new Error('granterSecretKey must be exactly 32 bytes');
+
+  const maxAccessCount = params.maxAccessCount === undefined ? 100 : params.maxAccessCount;
+  if (!Number.isSafeInteger(maxAccessCount) || maxAccessCount < 0) {
+    throw new Error('maxAccessCount must be a finite non-negative safe integer');
+  }
+
+  const grantId = `grnt_${Date.now()}_${crypto.randomBytes(4).toString('hex')}`;
+  let allowedTypes = [];
+  if (params.allowedTypes !== undefined) {
+    if (!Array.isArray(params.allowedTypes)) throw new Error('allowedTypes must be an array');
+    allowedTypes = params.allowedTypes.map((type) => {
+      if (typeof type !== 'string' || !VALID_MEMORY_TYPES.has(type.trim().toLowerCase())) {
+        throw new Error(`Unknown allowed memory type: ${type}`);
+      }
+      return normalizeMemoryType(type);
+    });
+    if (new Set(allowedTypes).size !== allowedTypes.length) {
+      throw new Error('allowedTypes must not contain duplicates');
+    }
+  }
+
+  let validUntil;
+  try {
+    validUntil = params.validUntil === undefined
+      ? new Date(Date.now() + 86400000 * 30).toISOString()
+      : new Date(params.validUntil).toISOString();
+  } catch {
+    throw new Error('validUntil must be a valid date');
+  }
+
+  const unsignedGrant = {
+    schema: BLINDED_GRANT_SCHEMA,
+    version: 1,
+    grant_id: grantId,
+    granter_agent_id: params.granterAgentId,
+    granter_pubkey: granterPubHex,
+    grantee_pubkey: granteePubHex,
+    scope: params.scope || 'enigma.global',
+    allowed_types: allowedTypes,
+    max_access_count: maxAccessCount,
+    valid_until: validUntil,
+    issued_at: new Date().toISOString(),
+    metadata: params.metadata || {},
+  };
+
+  const signable = getGrantSignablePayload(unsignedGrant);
+  const der = Buffer.concat([ED25519_PKCS8_PREFIX, privBuf]);
+  const privKeyObj = crypto.createPrivateKey({ key: der, format: 'der', type: 'pkcs8' });
+  const signature = crypto.sign(null, Buffer.from(signable, 'utf8'), privKeyObj);
+
+  return {
+    ...unsignedGrant,
+    signature: signature.toString('hex'),
+  };
+}
+
+/**
+ * Validates a BlindedMemoryGrant offline.
+ * @param {Object} grant
+ * @param {Object} [options]
+ * @param {string} [options.expectedGranteePubkey]
+ * @param {number} [options.asOfTime=Date.now()]
+ * @returns {{ ok: boolean, valid: boolean, grant_id: string, granter_agent_id: string, signatureValid: boolean, expired: boolean, errors: string[] }}
+ */
+export function verifyBlindedMemoryGrant(grant, options = {}) {
+  const errors = [];
+  if (!grant || typeof grant !== 'object') {
+    return { ok: false, valid: false, grant_id: '', granter_agent_id: '', signatureValid: false, expired: false, errors: ['Invalid grant object'] };
+  }
+
+  if (grant.schema !== BLINDED_GRANT_SCHEMA) {
+    errors.push(`Unrecognized capability grant schema: ${grant.schema}`);
+  }
+  if (!grant.grant_id) errors.push('Missing grant_id');
+  if (!grant.granter_agent_id) errors.push('Missing granter_agent_id');
+  if (!grant.granter_pubkey || !/^[0-9a-fA-F]{64}$/.test(grant.granter_pubkey)) {
+    errors.push('Invalid 64-hex granter_pubkey');
+  }
+  if (!grant.grantee_pubkey || !/^[0-9a-fA-F]{64}$/.test(grant.grantee_pubkey)) {
+    errors.push('Invalid 64-hex grantee_pubkey');
+  }
+  if (!grant.signature || !/^[0-9a-fA-F]{128}$/.test(grant.signature)) {
+    errors.push('Invalid 128-hex signature length');
+  }
+  if (typeof grant.scope !== 'string' || grant.scope.length === 0 || grant.scope.length > 256) {
+    errors.push('scope must be a non-empty string of at most 256 characters');
+  }
+  if (typeof grant.valid_until !== 'string') errors.push('Missing valid_until');
+  if (typeof grant.issued_at !== 'string' || !Number.isFinite(new Date(grant.issued_at).getTime())) {
+    errors.push('Invalid issued_at timestamp');
+  }
+
+  if (!Number.isSafeInteger(grant.max_access_count) || grant.max_access_count < 0) {
+    errors.push('max_access_count must be a finite non-negative safe integer');
+  }
+  if (!Array.isArray(grant.allowed_types)) {
+    errors.push('allowed_types must be an array');
+  } else {
+    const normalizedTypes = [];
+    for (const type of grant.allowed_types) {
+      if (typeof type !== 'string' || !VALID_MEMORY_TYPES.has(type.trim().toLowerCase())) {
+        errors.push(`Unknown allowed memory type: ${type}`);
+      } else {
+        normalizedTypes.push(type.trim().toLowerCase());
+      }
+    }
+    if (new Set(normalizedTypes).size !== normalizedTypes.length) {
+      errors.push('allowed_types must not contain duplicates');
+    }
+  }
+
+  // Check expected grantee
+  if (options.expectedGranteePubkey &&
+      grant.grantee_pubkey?.toLowerCase() !== String(options.expectedGranteePubkey).toLowerCase()) {
+    errors.push(`grantee_pubkey mismatch: expected ${options.expectedGranteePubkey}, got ${grant.grantee_pubkey}`);
+  }
+
+  // Check expiration
+  let expired = false;
+  if (grant.valid_until) {
+    const expiresAt = new Date(grant.valid_until).getTime();
+    if (!Number.isFinite(expiresAt)) {
+      errors.push(`Invalid valid_until timestamp format: ${grant.valid_until}`);
+    } else {
+      const checkTime = options.asOfTime || Date.now();
+      if (checkTime > expiresAt) {
+        expired = true;
+        errors.push(`Capability grant expired at ${grant.valid_until}`);
+      }
+    }
+  }
+
+  // Verify Ed25519 signature of granter
+  let signatureValid = false;
+  try {
+    const signable = getGrantSignablePayload(grant);
+    const pubBuf = Buffer.from(grant.granter_pubkey, 'hex');
+    const der = Buffer.concat([ED25519_SPKI_PREFIX, pubBuf]);
+    const pubKeyObj = crypto.createPublicKey({ key: der, format: 'der', type: 'spki' });
+    const sigBuf = Buffer.from(grant.signature, 'hex');
+
+    signatureValid = crypto.verify(null, Buffer.from(signable, 'utf8'), pubKeyObj, sigBuf);
+    if (!signatureValid) errors.push('Cryptographic Ed25519 signature verification failed');
+  } catch (err) {
+    errors.push(`Signature verification exception: ${err.message}`);
+  }
+
+  const ok = errors.length === 0 && signatureValid && !expired;
+  return {
+    ok,
+    valid: ok,
+    grant_id: grant.grant_id || '',
+    granter_agent_id: grant.granter_agent_id || '',
+    signatureValid,
+    expired,
+    errors,
+  };
+}
+
+/**
+ * Canonical payload for a grantee-signed federated query authorization.
+ * @param {Object} req
+ * @returns {string}
+ */
+export function getFederatedQuerySignablePayload(req) {
+  const grantId = req.grant && typeof req.grant === 'object' && req.grant.grant_id
+    ? req.grant.grant_id
+    : req.grant_id;
+  return JSON.stringify({
+    schema: req.schema || FEDERATED_QUERY_REQUEST_SCHEMA,
+    grant_id: grantId,
+    query: req.query,
+    requester_pubkey: req.requester_pubkey,
+    nonce: req.nonce,
+    timestamp: req.timestamp,
+  });
+}
+
+/**
+ * Creates and cryptographically signs a proof-of-possession federated query request.
+ */
+export function createFederatedQueryRequest(params) {
+  if (!params.grant || !params.grant.grant_id) throw new Error('grant is required');
+  if (typeof params.query !== 'string' || params.query.trim().length === 0) {
+    throw new Error('query must be a non-empty string');
+  }
+  if (!params.requesterSecretKey) throw new Error('requesterSecretKey is required');
+
+  const privBuf = Buffer.isBuffer(params.requesterSecretKey)
+    ? params.requesterSecretKey
+    : Buffer.from(params.requesterSecretKey, 'hex');
+  if (privBuf.length !== 32) throw new Error('requesterSecretKey must be exactly 32 bytes');
+
+  let pubHex;
+  if (params.requesterPublicKey) {
+    pubHex = Buffer.isBuffer(params.requesterPublicKey)
+      ? params.requesterPublicKey.toString('hex')
+      : String(params.requesterPublicKey).toLowerCase();
+  } else {
+    const der = Buffer.concat([ED25519_PKCS8_PREFIX, privBuf]);
+    const privKeyObj = crypto.createPrivateKey({ key: der, format: 'der', type: 'pkcs8' });
+    const pubKeyObj = crypto.createPublicKey(privKeyObj);
+    const spkiDer = pubKeyObj.export({ format: 'der', type: 'spki' });
+    pubHex = spkiDer.subarray(ED25519_SPKI_PREFIX.length).toString('hex');
+  }
+  if (!/^[0-9a-f]{64}$/.test(pubHex)) throw new Error('requesterPublicKey must be exactly 32 bytes');
+
+  const nonce = params.nonce || crypto.randomBytes(16).toString('hex');
+  if (!/^[0-9a-f]{32}$/.test(nonce)) {
+    throw new Error('nonce must be exactly 16 bytes encoded as lowercase hex');
+  }
+  const timestamp = params.timestamp || new Date().toISOString();
+  if (typeof timestamp !== 'string') throw new Error('timestamp must be a string');
+  const unsigned = {
+    schema: FEDERATED_QUERY_REQUEST_SCHEMA,
+    version: 1,
+    grant: params.grant,
+    grant_id: params.grant.grant_id,
+    query: params.query,
+    requester_pubkey: pubHex,
+    nonce,
+    timestamp,
+  };
+
+  const signable = getFederatedQuerySignablePayload(unsigned);
+  const der = Buffer.concat([ED25519_PKCS8_PREFIX, privBuf]);
+  const privKeyObj = crypto.createPrivateKey({ key: der, format: 'der', type: 'pkcs8' });
+  const signature = crypto.sign(null, Buffer.from(signable, 'utf8'), privKeyObj);
+
+  return {
+    ...unsigned,
+    signature: signature.toString('hex'),
+  };
+}
+
+/**
+ * Validates a grantee's proof-of-possession federated query request.
+ * @param {Object} request
+ * @param {Object} [options]
+ * @param {number} [options.maxClockSkewMs=300000]
+ * @param {number} [options.asOfTime=Date.now()]
+ */
+export function verifyFederatedQueryRequest(request, options = {}) {
+  const errors = [];
+  if (!request || typeof request !== 'object') {
+    return { ok: false, valid: false, signatureValid: false, errors: ['Invalid request object'] };
+  }
+
+  if (request.schema !== FEDERATED_QUERY_REQUEST_SCHEMA || request.version !== 1) {
+    errors.push(`Unrecognized federated query request schema or version: ${request.schema}`);
+  }
+  if (!request.grant || typeof request.grant !== 'object') {
+    errors.push('Missing grant in query request');
+  }
+  if (!request.grant_id) {
+    errors.push('Missing grant_id in query request');
+  } else if (request.grant?.grant_id && request.grant_id !== request.grant.grant_id) {
+    errors.push(`grant_id mismatch: outer grant_id ${request.grant_id} does not match embedded grant ${request.grant.grant_id}`);
+  }
+  if (typeof request.query !== 'string' || request.query.trim().length === 0) {
+    errors.push('Missing query string in request');
+  }
+  if (!request.requester_pubkey || !/^[0-9a-f]{64}$/.test(request.requester_pubkey)) {
+    errors.push('Invalid lowercase 64-hex requester_pubkey');
+  }
+  if (!request.nonce || !/^[0-9a-f]{32}$/.test(request.nonce)) {
+    errors.push('Invalid nonce: expected 32 lowercase hex characters');
+  }
+  if (!request.signature || !/^[0-9a-fA-F]{128}$/.test(request.signature)) {
+    errors.push('Invalid 128-hex signature length');
+  }
+
+  if (request.grant) {
+    const grantVerdict = verifyBlindedMemoryGrant(request.grant, {
+      expectedGranteePubkey: request.requester_pubkey,
+      asOfTime: options.asOfTime,
+    });
+    if (!grantVerdict.ok) {
+      errors.push(`Grant verification failed: ${grantVerdict.errors.join('; ')}`);
+    }
+  }
+
+  if (typeof request.timestamp !== 'string') {
+    errors.push(request.timestamp === undefined
+      ? 'Missing timestamp in request'
+      : 'Invalid timestamp type: expected string');
+  } else {
+    const reqDate = new Date(request.timestamp);
+    const reqTime = reqDate.getTime();
+    if (!Number.isFinite(reqTime) || reqDate.toISOString() !== request.timestamp) {
+      errors.push(`Invalid timestamp format in request: ${request.timestamp}`);
+    } else {
+      const maxSkew = options.maxClockSkewMs === undefined ? 300000 : options.maxClockSkewMs;
+      if (!Number.isSafeInteger(maxSkew) || maxSkew < 0) {
+        errors.push('maxClockSkewMs must be a finite non-negative safe integer');
+      } else {
+        const asOfTime = options.asOfTime === undefined ? Date.now() : options.asOfTime;
+        if (!Number.isFinite(asOfTime)) {
+          errors.push('asOfTime must be a finite timestamp');
+        } else if (Math.abs(asOfTime - reqTime) > maxSkew) {
+          errors.push(`Query request timestamp expired or out of allowed clock skew: ${request.timestamp}`);
+        }
+      }
+    }
+  }
+
+  let signatureValid = false;
+  try {
+    const signable = getFederatedQuerySignablePayload(request);
+    const pubBuf = Buffer.from(request.requester_pubkey, 'hex');
+    const der = Buffer.concat([ED25519_SPKI_PREFIX, pubBuf]);
+    const pubKeyObj = crypto.createPublicKey({ key: der, format: 'der', type: 'spki' });
+    const sigBuf = Buffer.from(request.signature, 'hex');
+    signatureValid = crypto.verify(null, Buffer.from(signable, 'utf8'), pubKeyObj, sigBuf);
+    if (!signatureValid) errors.push('Requester proof-of-possession Ed25519 signature failed');
+  } catch (err) {
+    errors.push(`Requester signature verification exception: ${err.message}`);
+  }
+
+  const ok = errors.length === 0 && signatureValid;
+  return { ok, valid: ok, signatureValid, errors };
+}