enigma-memory 0.1.17 → 0.1.22

package/packages/enclave-runtime/session-manager.mjs

@@ -0,0 +1,253 @@
+import {
+  generateKeyPairSync,
+  hkdfSync,
+  randomBytes,
+  randomFillSync,
+  randomUUID,
+  timingSafeEqual,
+} from 'node:crypto';
+import { createAttestation, sha256Hex } from './attestation.mjs';
+import { createZeroizationReceipt } from './zeroization-proof.mjs';
+
+export const VOLATILE_OVERWRITE_PROFILE = Object.freeze({
+  name: 'ENIGMA_THREE_PASS_VOLATILE_BUFFER_V1',
+  passes: Object.freeze(['cryptographic-random', '0xff', '0x00']),
+  standards_compliance_claimed: false,
+  hardware_ram_zeroization_proved: false,
+});
+
+export function generateEphemeralSessionKey(length = 32) {
+  if (!Number.isSafeInteger(length) || length < 16 || length > 1024) {
+    throw new RangeError('Ephemeral key length must be an integer between 16 and 1024 bytes.');
+  }
+  return randomBytes(length);
+}
+
+export function isZeroFilled(buffer) {
+  const view = asBufferView(buffer);
+  let aggregate = 0;
+  for (let index = 0; index < view.length; index += 1) aggregate |= view[index];
+  return aggregate === 0;
+}
+
+export function overwriteVolatileBuffer(buffer) {
+  const view = asBufferView(buffer);
+  if (view.length === 0) throw new RangeError('Cannot zeroize an empty buffer.');
+  const overwritePasses = [];
+
+  randomFillSync(view);
+  overwritePasses.push({
+    pass: 1,
+    pattern: 'cryptographic-random',
+    post_pass_commitment: `sha256:${sha256Hex(view)}`,
+  });
+
+  view.fill(0xff);
+  overwritePasses.push({
+    pass: 2,
+    pattern: '0xff',
+    post_pass_commitment: `sha256:${sha256Hex(view)}`,
+  });
+
+  view.fill(0x00);
+  overwritePasses.push({
+    pass: 3,
+    pattern: '0x00',
+    post_pass_commitment: `sha256:${sha256Hex(view)}`,
+  });
+
+  const postWipeZeroCheck = isZeroFilled(view);
+  if (!postWipeZeroCheck) throw new Error('VOLATILE_BUFFER_POST_WIPE_CHECK_FAILED');
+  return {
+    profile: VOLATILE_OVERWRITE_PROFILE,
+    byte_length: view.length,
+    overwrite_passes: overwritePasses,
+    post_wipe_commitment: `sha256:${sha256Hex(view)}`,
+    post_wipe_zero_check: true,
+    claim_boundary: {
+      retained_buffer_instance_only: true,
+      hardware_ram_zeroization_proved: false,
+      runtime_copies_gc_caches_in_scope: false,
+    },
+  };
+}
+
+export const zeroizeBuffer = overwriteVolatileBuffer;
+
+export class EnclaveSessionManager {
+  #activeSessions = new Map();
+  #tombstones = new Map();
+  #privateKey;
+  #publicKey;
+
+  constructor({ signingKeyPair } = {}) {
+    const pair = signingKeyPair ?? generateKeyPairSync('ed25519');
+    if (!pair.privateKey || !pair.publicKey) throw new TypeError('An Ed25519 signing key pair is required.');
+    this.#privateKey = pair.privateKey;
+    this.#publicKey = pair.publicKey;
+  }
+
+  get publicKeySpkiBase64() {
+    return this.#publicKey.export({ type: 'spki', format: 'der' }).toString('base64');
+  }
+
+  initializeSession({ bundle, bundleHash, sessionId = randomUUID(), now = new Date().toISOString(), metadata = {} } = {}) {
+    if (this.#activeSessions.has(sessionId) || this.#tombstones.has(sessionId)) {
+      throw new Error(`SESSION_ID_ALREADY_USED: ${sessionId}`);
+    }
+    const masterKey = generateEphemeralSessionKey(32);
+    const attestation = createAttestation({ bundle, bundleHash, now, nonce: sessionId });
+    const session = {
+      sessionId,
+      createdAt: now,
+      status: 'active',
+      masterKey,
+      derivedKeys: new Map(),
+      attestation,
+      metadata: sanitizeMetadata(metadata),
+    };
+    this.#activeSessions.set(sessionId, session);
+    return this.#snapshot(session);
+  }
+
+  createSession(options) {
+    return this.initializeSession(options);
+  }
+
+  hasActiveSession(sessionId) {
+    return this.#activeSessions.has(String(sessionId));
+  }
+
+  listActiveSessions() {
+    return [...this.#activeSessions.values()].map((session) => this.#snapshot(session));
+  }
+
+  getSession(sessionId) {
+    const session = this.#activeSessions.get(String(sessionId));
+    if (session) return this.#snapshot(session);
+    const tombstone = this.#tombstones.get(String(sessionId));
+    return tombstone ? structuredClone(tombstone) : null;
+  }
+
+  deriveSessionKey(sessionId, purpose, { length = 32, context = '' } = {}) {
+    const session = this.#requireActive(sessionId);
+    const purposeString = String(purpose ?? '').trim();
+    if (!purposeString) throw new TypeError('A non-empty derivation purpose is required.');
+    if (!Number.isSafeInteger(length) || length < 16 || length > 1024) {
+      throw new RangeError('Derived key length must be an integer between 16 and 1024 bytes.');
+    }
+    const handle = `${purposeString}:${String(context)}:${length}`;
+    const existing = session.derivedKeys.get(handle);
+    if (existing) return existing;
+    const salt = Buffer.from(session.attestation.measurement_hash.slice(7), 'hex');
+    const info = Buffer.from(`enigma-session-key-v1\0${purposeString}\0${String(context)}`);
+    const derived = Buffer.from(hkdfSync('sha256', session.masterKey, salt, info, length));
+    session.derivedKeys.set(handle, derived);
+    return derived;
+  }
+
+  withDerivedSessionKey(sessionId, purpose, options, callback) {
+    if (typeof options === 'function') return this.withDerivedSessionKey(sessionId, purpose, {}, options);
+    if (typeof callback !== 'function') throw new TypeError('A callback is required.');
+    const key = this.deriveSessionKey(sessionId, purpose, options);
+    return callback(key);
+  }
+
+  attestSession(sessionId) {
+    return structuredClone(this.#requireActive(sessionId).attestation);
+  }
+
+  zeroizeSession(sessionId, { now = new Date().toISOString() } = {}) {
+    const session = this.#requireActive(sessionId);
+    const buffers = [
+      ['master', session.masterKey],
+      ...[...session.derivedKeys.entries()].map(([handle, key]) => [`derived:${handle}`, key]),
+    ];
+    const entries = buffers.map(([keyRef, buffer]) => {
+      const preWipeCommitment = `sha256:${sha256Hex(buffer)}`;
+      const result = overwriteVolatileBuffer(buffer);
+      return {
+        key_ref: keyRef,
+        byte_length: result.byte_length,
+        pre_wipe_commitment: preWipeCommitment,
+        post_wipe_commitment: result.post_wipe_commitment,
+        overwrite_passes: result.overwrite_passes,
+        post_wipe_zero_check: result.post_wipe_zero_check,
+      };
+    });
+
+    session.status = 'zeroized';
+    session.derivedKeys.clear();
+    this.#activeSessions.delete(session.sessionId);
+    const tombstone = {
+      session_id: session.sessionId,
+      status: 'zeroized',
+      created_at: session.createdAt,
+      zeroized_at: now,
+      attestation_measurement_hash: session.attestation.measurement_hash,
+      active_session_removed: true,
+      enigma_key_handles_invalidated: true,
+    };
+    this.#tombstones.set(session.sessionId, tombstone);
+
+    const receipt = createZeroizationReceipt({
+      sessionId: session.sessionId,
+      entries,
+      attestation: session.attestation,
+      privateKey: this.#privateKey,
+      publicKey: this.#publicKey,
+      sessionRemovedFromActiveSet: !this.#activeSessions.has(session.sessionId),
+      now,
+    });
+    tombstone.receipt_hash = receipt.receipt_hash;
+    return receipt;
+  }
+
+  zeroizeAll({ now = new Date().toISOString() } = {}) {
+    return [...this.#activeSessions.keys()].map((sessionId) => this.zeroizeSession(sessionId, { now }));
+  }
+
+  #requireActive(sessionId) {
+    const normalized = String(sessionId ?? '');
+    const session = this.#activeSessions.get(normalized);
+    if (!session) throw new Error(`SESSION_NOT_ACTIVE: ${normalized || '<missing>'}`);
+    return session;
+  }
+
+  #snapshot(session) {
+    return {
+      schema: 'enigma.enclave.session.v1',
+      session_id: session.sessionId,
+      status: session.status,
+      created_at: session.createdAt,
+      derived_key_count: session.derivedKeys.size,
+      attestation: structuredClone(session.attestation),
+      metadata: structuredClone(session.metadata),
+      claim_boundary: {
+        keys_process_local: true,
+        key_material_exported: false,
+        hardware_enclave_claimed: false,
+      },
+    };
+  }
+}
+
+export const SessionManager = EnclaveSessionManager;
+export const defaultSessionManager = new EnclaveSessionManager();
+
+function asBufferView(value) {
+  if (Buffer.isBuffer(value)) return value;
+  if (value instanceof Uint8Array) return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+  throw new TypeError('Expected a Buffer or Uint8Array.');
+}
+
+function sanitizeMetadata(metadata) {
+  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) return {};
+  return Object.fromEntries(Object.entries(metadata).map(([key, value]) => [String(key), String(value)]));
+}
+
+export function buffersEqual(left, right) {
+  const a = asBufferView(left);
+  const b = asBufferView(right);
+  return a.length === b.length && timingSafeEqual(a, b);
+}

package/packages/enclave-runtime/zeroization-proof.mjs

@@ -0,0 +1,227 @@
+import { randomUUID, sign, verify, timingSafeEqual } from 'node:crypto';
+import { canonicalJson, sha256Hex, verifyAttestation } from './attestation.mjs';
+
+const HEX_COMMITMENT = /^sha256:[a-f0-9]{64}$/;
+
+function normalizeCommitment(value) {
+  const normalized = String(value).startsWith('sha256:') ? String(value) : `sha256:${value}`;
+  if (!HEX_COMMITMENT.test(normalized)) throw new TypeError('Expected a SHA-256 commitment.');
+  return normalized;
+}
+
+export function merkleRoot(commitments) {
+  let level = commitments.map((value) => Buffer.from(normalizeCommitment(value).slice(7), 'hex'));
+  if (level.length === 0) return `sha256:${sha256Hex('enigma-empty-merkle-tree-v1')}`;
+  while (level.length > 1) {
+    if (level.length % 2 === 1) level.push(level[level.length - 1]);
+    const next = [];
+    for (let index = 0; index < level.length; index += 2) {
+      next.push(Buffer.from(sha256Hex(Buffer.concat([level[index], level[index + 1]])), 'hex'));
+    }
+    level = next;
+  }
+  return `sha256:${level[0].toString('hex')}`;
+}
+
+export function createZeroizationReceipt({
+  sessionId,
+  entries,
+  attestation,
+  privateKey,
+  publicKey,
+  sessionRemovedFromActiveSet,
+  now = new Date().toISOString(),
+  receiptId = randomUUID(),
+}) {
+  if (!sessionId) throw new TypeError('sessionId is required.');
+  if (!Array.isArray(entries) || entries.length === 0) throw new TypeError('At least one zeroization entry is required.');
+  if (!privateKey || !publicKey) throw new TypeError('An Ed25519 signing key pair is required.');
+
+  const normalizedEntries = entries.map((entry, index) => ({
+    key_ref: String(entry.key_ref ?? `key-${index}`),
+    byte_length: Number(entry.byte_length),
+    pre_wipe_commitment: normalizeCommitment(entry.pre_wipe_commitment),
+    post_wipe_commitment: normalizeCommitment(entry.post_wipe_commitment),
+    overwrite_passes: Array.isArray(entry.overwrite_passes) ? entry.overwrite_passes.map((pass) => ({
+      pass: Number(pass.pass),
+      pattern: String(pass.pattern),
+      post_pass_commitment: normalizeCommitment(pass.post_pass_commitment),
+    })) : [],
+    post_wipe_zero_check: entry.post_wipe_zero_check === true,
+  }));
+  const allZero = normalizedEntries.every((entry) => entry.post_wipe_zero_check);
+  const removed = sessionRemovedFromActiveSet === true;
+  const payload = {
+    schema: 'enigma.enclave.zeroization-receipt.v1',
+    receipt_id: receiptId,
+    session_id: String(sessionId),
+    created_at: now,
+    operation: 'BEST_EFFORT_VOLATILE_BUFFER_OVERWRITE',
+    overwrite_profile: {
+      name: 'ENIGMA_THREE_PASS_VOLATILE_BUFFER_V1',
+      patterns: ['cryptographic-random', '0xff', '0x00'],
+      standards_compliance_claimed: false,
+    },
+    pre_wipe_merkle_root: merkleRoot(normalizedEntries.map((entry) => entry.pre_wipe_commitment)),
+    post_wipe_merkle_root: merkleRoot(normalizedEntries.map((entry) => entry.post_wipe_commitment)),
+    entries: normalizedEntries,
+    attestation,
+    state_nullification: {
+      active_session_removed: removed,
+      retained_buffers_zero_checked: allZero,
+      enigma_key_handles_invalidated: removed && allZero,
+      all_external_copies_unrecoverable: false,
+      proved: removed && allZero,
+    },
+    claim_boundary: {
+      proof_scope: 'Enigma-managed session state and retained Buffer instances only.',
+      hardware_ram_zeroization_proved: false,
+      external_buffer_copies_proved: false,
+      runtime_copies_gc_caches_in_scope: false,
+      physical_ram_in_scope: false,
+    },
+  };
+  const canonical = canonicalJson(payload);
+  const receiptHash = `sha256:${sha256Hex(canonical)}`;
+  const signature = sign(null, Buffer.from(canonical), privateKey).toString('base64');
+  const publicKeyDer = publicKey.export({ type: 'spki', format: 'der' }).toString('base64');
+  return {
+    ...payload,
+    receipt_hash: receiptHash,
+    signature: {
+      algorithm: 'Ed25519',
+      public_key_spki_base64: publicKeyDer,
+      value_base64: signature,
+    },
+  };
+}
+
+export function verifyZeroizationReceipt(receipt, { expectedSessionId, expectedPublicKey } = {}) {
+  const errors = [];
+  if (!receipt || typeof receipt !== 'object') return invalid(['RECEIPT_REQUIRED']);
+  if (receipt.schema !== 'enigma.enclave.zeroization-receipt.v1') errors.push('INVALID_SCHEMA');
+  if (expectedSessionId && !safeStringEqual(receipt.session_id, expectedSessionId)) errors.push('SESSION_ID_MISMATCH');
+  if (receipt.operation !== 'BEST_EFFORT_VOLATILE_BUFFER_OVERWRITE') errors.push('INVALID_OPERATION');
+  if (receipt.overwrite_profile?.standards_compliance_claimed !== false) errors.push('INVALID_COMPLIANCE_CLAIM');
+
+  const entries = receipt.entries;
+  if (!Array.isArray(entries) || entries.length === 0) {
+    errors.push('ZEROIZATION_ENTRIES_REQUIRED');
+  } else {
+    for (const entry of entries) {
+      const validLength = Number.isSafeInteger(entry.byte_length)
+        && entry.byte_length > 0
+        && entry.byte_length <= 1024;
+      if (!validLength) errors.push('INVALID_BUFFER_LENGTH');
+      if (!HEX_COMMITMENT.test(String(entry.pre_wipe_commitment ?? ''))) errors.push('INVALID_PRE_WIPE_COMMITMENT');
+      if (!HEX_COMMITMENT.test(String(entry.post_wipe_commitment ?? ''))) errors.push('INVALID_POST_WIPE_COMMITMENT');
+      if (entry.post_wipe_zero_check !== true) errors.push('POST_WIPE_ZERO_CHECK_FAILED');
+      const passes = entry.overwrite_passes;
+      const validPassShape = Array.isArray(passes) && passes.length === 3
+        && passes[0]?.pass === 1 && passes[0]?.pattern === 'cryptographic-random'
+        && passes[1]?.pass === 2 && passes[1]?.pattern === '0xff'
+        && passes[2]?.pass === 3 && passes[2]?.pattern === '0x00';
+      if (!validPassShape) errors.push('INVALID_OVERWRITE_TRANSCRIPT');
+      if (validLength) {
+        const zeroDigest = `sha256:${sha256Hex(Buffer.alloc(entry.byte_length))}`;
+        const ffDigest = `sha256:${sha256Hex(Buffer.alloc(entry.byte_length, 0xff))}`;
+        if (!safeStringEqual(zeroDigest, entry.post_wipe_commitment)) errors.push('POST_WIPE_COMMITMENT_NOT_ZERO');
+        if (validPassShape && (!safeStringEqual(ffDigest, passes[1].post_pass_commitment)
+          || !safeStringEqual(zeroDigest, passes[2].post_pass_commitment)
+          || !safeStringEqual(passes[2].post_pass_commitment, entry.post_wipe_commitment))) {
+          errors.push('OVERWRITE_TRANSCRIPT_COMMITMENT_MISMATCH');
+        }
+      }
+    }
+    try {
+      if (!safeStringEqual(receipt.pre_wipe_merkle_root, merkleRoot(entries.map((entry) => entry.pre_wipe_commitment)))) {
+        errors.push('PRE_WIPE_ROOT_MISMATCH');
+      }
+      if (!safeStringEqual(receipt.post_wipe_merkle_root, merkleRoot(entries.map((entry) => entry.post_wipe_commitment)))) {
+        errors.push('POST_WIPE_ROOT_MISMATCH');
+      }
+    } catch {
+      errors.push('INVALID_MERKLE_COMMITMENT');
+    }
+  }
+
+  const state = receipt.state_nullification;
+  if (state?.active_session_removed !== true
+    || state?.retained_buffers_zero_checked !== true
+    || state?.enigma_key_handles_invalidated !== true
+    || state?.all_external_copies_unrecoverable !== false
+    || state?.proved !== true) {
+    errors.push('STATE_NULLIFICATION_NOT_PROVED');
+  }
+  const boundary = receipt.claim_boundary;
+  if (boundary?.hardware_ram_zeroization_proved !== false
+    || boundary?.external_buffer_copies_proved !== false
+    || boundary?.runtime_copies_gc_caches_in_scope !== false
+    || boundary?.physical_ram_in_scope !== false) {
+    errors.push('INVALID_CLAIM_BOUNDARY');
+  }
+
+  const attestationResult = verifyAttestation(receipt.attestation);
+  if (!attestationResult.valid) errors.push(...attestationResult.errors.map((error) => `ATTESTATION_${error}`));
+
+  const { receipt_hash: claimedHash, signature, ...payload } = receipt;
+  const canonical = canonicalJson(payload);
+  const computedHash = `sha256:${sha256Hex(canonical)}`;
+  if (!safeStringEqual(claimedHash, computedHash)) errors.push('RECEIPT_HASH_MISMATCH');
+  if (signature?.algorithm !== 'Ed25519' || !signature.public_key_spki_base64 || !signature.value_base64) {
+    errors.push('SIGNATURE_REQUIRED');
+  } else {
+    if (expectedPublicKey) {
+      const expectedDer = typeof expectedPublicKey === 'string'
+        ? expectedPublicKey
+        : expectedPublicKey.export({ type: 'spki', format: 'der' }).toString('base64');
+      if (!safeStringEqual(signature.public_key_spki_base64, expectedDer)) errors.push('UNTRUSTED_SIGNER');
+    }
+    try {
+      const validSignature = verify(
+        null,
+        Buffer.from(canonical),
+        { key: Buffer.from(signature.public_key_spki_base64, 'base64'), type: 'spki', format: 'der' },
+        Buffer.from(signature.value_base64, 'base64'),
+      );
+      if (!validSignature) errors.push('INVALID_SIGNATURE');
+    } catch {
+      errors.push('INVALID_SIGNATURE');
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors: [...new Set(errors)],
+    receipt_hash: computedHash,
+    session_id: receipt.session_id,
+    state_nullification_proved: errors.length === 0 && state?.proved === true,
+    state_nullification_scope: 'Enigma-managed session state and retained Buffer instances only.',
+    claim_boundary: boundary,
+    attestation: attestationResult,
+  };
+}
+
+export function verifyStateNullification(receipt, options) {
+  const verification = verifyZeroizationReceipt(receipt, options);
+  return {
+    ...verification,
+    proved: verification.valid && verification.state_nullification_proved,
+    scope: 'Enigma-managed session state and retained Buffer instances only.',
+  };
+}
+
+function invalid(errors) {
+  return {
+    valid: false,
+    errors,
+    state_nullification_proved: false,
+    state_nullification_scope: 'Enigma-managed session state and retained Buffer instances only.',
+  };
+}
+
+function safeStringEqual(left, right) {
+  const a = Buffer.from(String(left ?? ''));
+  const b = Buffer.from(String(right ?? ''));
+  return a.length === b.length && timingSafeEqual(a, b);
+}

package/packages/enigma-reflex/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@enigma/cortex-reflex",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Agent recovery supervisor, stateful benchmark, and LoRA training infrastructure for Enigma Cortex.",
+  "license": "Apache-2.0",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}