enigma-memory 0.1.17 → 0.1.22

package/packages/developer-platform/src/usage.js

@@ -0,0 +1,295 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rename } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+
+export const ENIGMA_USAGE_STORE_SCHEMA = 'enigma.platform_usage_store.v1';
+export const ENIGMA_USAGE_EVENT_SCHEMA = 'enigma.platform_usage_event.v1';
+export const ENIGMA_USAGE_AGGREGATE_SCHEMA = 'enigma.platform_usage_aggregate.v1';
+const MODALITY_UNITS = Object.freeze({ text: 'tokens', image: 'images', video: 'videos', code: 'executions', browser: 'sessions' });
+const USAGE_INPUT_FIELDS = new Set([
+  'modality', 'operation', 'provider', 'model', 'inputTokens', 'inputUnits', 'outputTokens', 'outputUnits',
+  'totalTokens', 'units', 'durationMs', 'promptRef', 'routeReceiptId', 'occurredAt',
+]);
+
+function requiredString(value, name, maximum = 512) {
+  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${name} is required`);
+  const normalized = value.trim();
+  if (normalized.length > maximum) throw new TypeError(`${name} exceeds ${maximum} characters`);
+  return normalized;
+}
+
+function nonNegativeInteger(value, name, fallback = 0) {
+  const resolved = value === undefined ? fallback : value;
+  if (!Number.isSafeInteger(resolved) || resolved < 0) throw new TypeError(`${name} must be a non-negative integer`);
+  return resolved;
+}
+
+function boundedInteger(value, name, minimum, maximum, fallback) {
+  const resolved = value === undefined ? fallback : value;
+  if (!Number.isInteger(resolved) || resolved < minimum || resolved > maximum) throw new TypeError(`${name} must be from ${minimum} through ${maximum}`);
+  return resolved;
+}
+
+function timestamp(value, name) {
+  const milliseconds = value === undefined ? Date.now() : typeof value === 'number' ? value : Date.parse(value);
+  if (!Number.isFinite(milliseconds)) throw new TypeError(`${name} must be an ISO timestamp or epoch milliseconds`);
+  return milliseconds;
+}
+
+function emptyState() {
+  return { schema: ENIGMA_USAGE_STORE_SCHEMA, revision: 0, events: {} };
+}
+
+function normalizePrincipal(value = {}) {
+  return {
+    ownerId: requiredString(value.ownerId || value.subject, 'usage ownerId'),
+    tenantId: requiredString(value.tenantId || value.tenant_id || 'default', 'usage tenantId'),
+    keyId: value.keyId ? requiredString(value.keyId, 'usage keyId') : null,
+  };
+}
+
+function eventPublicView(event) {
+  return {
+    schema: event.schema,
+    id: event.id,
+    tenantId: event.tenantId,
+    ownerId: event.ownerId,
+    keyId: event.keyId,
+    modality: event.modality,
+    operation: event.operation,
+    provider: event.provider,
+    model: event.model,
+    unit: event.unit,
+    inputUnits: event.inputUnits,
+    outputUnits: event.outputUnits,
+    units: event.units,
+    estimatedCostMicrousd: event.estimatedCostMicrousd,
+    priced: event.estimatedCostMicrousd !== null,
+    occurredAt: event.occurredAt,
+    receiptRef: event.receiptRef,
+  };
+}
+
+function createStoreAdapter(load, save, { clock, retentionMs, maxEvents }) {
+  let queue = Promise.resolve();
+  const transaction = (operation) => {
+    const run = queue.then(async () => {
+      const state = await load();
+      const cutoff = clock() - retentionMs;
+      for (const [id, event] of Object.entries(state.events)) {
+        if (Date.parse(event.occurredAt) < cutoff) delete state.events[id];
+      }
+      const result = await operation(state);
+      const ordered = Object.values(state.events).sort((a, b) => a.occurredAt.localeCompare(b.occurredAt));
+      for (let index = 0; index < ordered.length - maxEvents; index += 1) delete state.events[ordered[index].id];
+      state.revision += 1;
+      await save(state);
+      return result;
+    });
+    queue = run.catch(() => undefined);
+    return run;
+  };
+  const view = async (operation) => {
+    await queue;
+    return operation(await load());
+  };
+  return Object.freeze({
+    async append(event) {
+      return transaction((state) => {
+        if (state.events[event.id]) return { inserted: false, event: structuredClone(state.events[event.id]) };
+        state.events[event.id] = structuredClone(event);
+        return { inserted: true, event: structuredClone(event) };
+      });
+    },
+    async query({ ownerId, tenantId, from, to, limit }) {
+      return transaction((state) => Object.values(state.events)
+        .filter((event) => event.ownerId === ownerId && event.tenantId === tenantId)
+        .filter((event) => {
+          const at = Date.parse(event.occurredAt);
+          return at >= from && at < to;
+        })
+        .sort((a, b) => b.occurredAt.localeCompare(a.occurredAt))
+        .slice(0, limit)
+        .map((event) => structuredClone(event)));
+    },
+  });
+}
+
+export function createEphemeralUsageStore(options = {}) {
+  const clock = options.clock || Date.now;
+  const retentionMs = boundedInteger(options.retentionDays, 'retentionDays', 1, 3660, 400) * 24 * 60 * 60_000;
+  const maxEvents = boundedInteger(options.maxEvents, 'maxEvents', 100, 10_000_000, 100_000);
+  let state = emptyState();
+  return createStoreAdapter(async () => structuredClone(state), async (next) => { state = structuredClone(next); }, { clock, retentionMs, maxEvents });
+}
+
+export function createFileUsageStore(options = {}) {
+  const path = resolve(String(options.path || '.enigma/usage.json'));
+  const clock = options.clock || Date.now;
+  const retentionMs = boundedInteger(options.retentionDays, 'retentionDays', 1, 3660, 400) * 24 * 60 * 60_000;
+  const maxEvents = boundedInteger(options.maxEvents, 'maxEvents', 100, 10_000_000, 100_000);
+  async function load() {
+    try {
+      const state = JSON.parse(await readFile(path, 'utf8'));
+      if (state?.schema !== ENIGMA_USAGE_STORE_SCHEMA) throw new Error('unsupported usage store schema');
+      return state;
+    } catch (error) {
+      if (error.code === 'ENOENT') return emptyState();
+      throw error;
+    }
+  }
+  async function save(state) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    const handle = await open(temporary, 'wx', 0o600);
+    try {
+      await handle.writeFile(JSON.stringify(state));
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await rename(temporary, path);
+  }
+  return createStoreAdapter(load, save, { clock, retentionMs, maxEvents });
+}
+
+function pricingCostMicrousd(input, pricing) {
+  if (!pricing) return null;
+  if (input.modality === 'text') {
+    if (!Number.isFinite(pricing.inputPerMillionMicrousd) || !Number.isFinite(pricing.outputPerMillionMicrousd)) return null;
+    return Math.round((input.inputUnits / 1_000_000) * pricing.inputPerMillionMicrousd
+      + (input.outputUnits / 1_000_000) * pricing.outputPerMillionMicrousd);
+  }
+  if (!Number.isFinite(pricing.perUnitMicrousd)) return null;
+  return Math.round(input.units * pricing.perUnitMicrousd);
+}
+
+function aggregateBucket(target, event) {
+  target.eventCount += 1;
+  target.inputUnits += event.inputUnits;
+  target.outputUnits += event.outputUnits;
+  target.units += event.units;
+  if (event.estimatedCostMicrousd === null) target.unpricedEvents += 1;
+  else target.knownCostMicrousd += event.estimatedCostMicrousd;
+}
+
+function emptyAggregateBucket(fields = {}) {
+  return { ...fields, eventCount: 0, inputUnits: 0, outputUnits: 0, units: 0, knownCostMicrousd: 0, unpricedEvents: 0 };
+}
+
+export function aggregatePlatformUsage(events, identity, { from, to } = {}) {
+  const totals = emptyAggregateBucket({ currency: 'USD' });
+  const byDay = new Map();
+  const byModel = new Map();
+  const byModality = new Map();
+  for (const event of events) {
+    aggregateBucket(totals, event);
+    const day = event.occurredAt.slice(0, 10);
+    if (!byDay.has(day)) byDay.set(day, emptyAggregateBucket({ day }));
+    aggregateBucket(byDay.get(day), event);
+    const modelKey = `${event.provider}\0${event.model}`;
+    if (!byModel.has(modelKey)) byModel.set(modelKey, emptyAggregateBucket({ provider: event.provider, model: event.model }));
+    aggregateBucket(byModel.get(modelKey), event);
+    if (!byModality.has(event.modality)) byModality.set(event.modality, emptyAggregateBucket({ modality: event.modality, unit: event.unit }));
+    aggregateBucket(byModality.get(event.modality), event);
+  }
+  return {
+    schema: ENIGMA_USAGE_AGGREGATE_SCHEMA,
+    generatedAt: new Date().toISOString(),
+    tenantId: identity.tenantId,
+    ownerId: identity.ownerId,
+    period: { from: new Date(from).toISOString(), to: new Date(to).toISOString() },
+    totals,
+    byDay: [...byDay.values()].sort((a, b) => a.day.localeCompare(b.day)),
+    byModel: [...byModel.values()].sort((a, b) => (a.provider + a.model).localeCompare(b.provider + b.model)),
+    byModality: [...byModality.values()].sort((a, b) => a.modality.localeCompare(b.modality)),
+    costBoundary: totals.unpricedEvents
+      ? 'knownCostMicrousd excludes unpriced events and is not a complete invoice total'
+      : 'knownCostMicrousd is an estimate from configured operator pricing, not a provider invoice',
+    contentStored: false,
+  };
+}
+
+export function createUsageService(options = {}) {
+  const store = options.store;
+  if (!store || typeof store.append !== 'function' || typeof store.query !== 'function') throw new TypeError('usage store is required');
+  const clock = options.clock || Date.now;
+  const context = new AsyncLocalStorage();
+  const defaultPrincipal = options.defaultPrincipal ? normalizePrincipal(options.defaultPrincipal) : null;
+  const pricing = options.pricing || {};
+  const maxQueryEvents = boundedInteger(options.maxQueryEvents, 'maxQueryEvents', 100, 1_000_000, 100_000);
+
+  function currentPrincipal(explicit) {
+    if (explicit) return normalizePrincipal(explicit);
+    const active = context.getStore()?.principal;
+    return active ? normalizePrincipal(active) : defaultPrincipal;
+  }
+
+  return Object.freeze({
+    run(requestContext, operation) {
+      if (typeof operation !== 'function') throw new TypeError('usage.run requires an operation');
+      return context.run({ principal: requestContext?.principal || null }, operation);
+    },
+    setPrincipal(principal) {
+      const active = context.getStore();
+      if (!active) return false;
+      active.principal = principal;
+      return true;
+    },
+    async record(input = {}, explicitPrincipal = null) {
+      const principal = currentPrincipal(explicitPrincipal);
+      if (!principal) throw new Error('usage event has no authenticated principal');
+      const modality = requiredString(input.modality, 'usage modality', 32);
+      if (!Object.hasOwn(MODALITY_UNITS, modality)) throw new TypeError('unsupported usage modality');
+      const inputUnits = nonNegativeInteger(input.inputTokens ?? input.inputUnits, 'input units');
+      const outputUnits = nonNegativeInteger(input.outputTokens ?? input.outputUnits, 'output units');
+      const units = nonNegativeInteger(input.units, 'units', modality === 'text' ? inputUnits + outputUnits : 1);
+      const provider = requiredString(input.provider || 'unknown', 'usage provider', 160);
+      const model = requiredString(input.model || 'unknown', 'usage model', 160);
+      const occurredAt = new Date(input.occurredAt ? timestamp(input.occurredAt, 'occurredAt') : clock()).toISOString();
+      const pricingRule = pricing[`${provider}/${model}`] || pricing[model] || pricing[modality] || null;
+      const normalized = { modality, inputUnits, outputUnits, units };
+      const forbiddenField = Object.keys(input).find((key) => !USAGE_INPUT_FIELDS.has(key));
+      if (forbiddenField) throw new TypeError(`usage input field ${forbiddenField} is not allowed`);
+      const event = {
+        schema: ENIGMA_USAGE_EVENT_SCHEMA,
+        id: randomUUID(),
+        tenantId: principal.tenantId,
+        ownerId: principal.ownerId,
+        keyId: principal.keyId,
+        modality,
+        operation: requiredString(input.operation || `${modality}.generate`, 'usage operation', 160),
+        provider,
+        model,
+        unit: MODALITY_UNITS[modality],
+        inputUnits,
+        outputUnits,
+        units,
+        estimatedCostMicrousd: pricingCostMicrousd(normalized, pricingRule),
+        occurredAt,
+        receiptRef: input.routeReceiptId ? requiredString(input.routeReceiptId, 'receiptRef', 512) : null,
+      };
+      const stored = await store.append(event);
+      return eventPublicView(stored.event);
+    },
+    async events(input = {}) {
+      const identity = currentPrincipal(input.principal || input);
+      if (!identity) throw new Error('usage query has no authenticated principal');
+      const to = input.to === undefined ? clock() + 1 : timestamp(input.to, 'to');
+      const from = input.from === undefined ? to - 30 * 24 * 60 * 60_000 : timestamp(input.from, 'from');
+      if (from >= to) throw new TypeError('usage from must be before to');
+      const limit = boundedInteger(input.limit, 'limit', 1, maxQueryEvents, Math.min(1000, maxQueryEvents));
+      return (await store.query({ ...identity, from, to, limit })).map(eventPublicView);
+    },
+    async aggregate(input = {}) {
+      const identity = currentPrincipal(input.principal || input);
+      if (!identity) throw new Error('usage aggregate has no authenticated principal');
+      const to = input.to === undefined ? clock() + 1 : timestamp(input.to, 'to');
+      const from = input.from === undefined ? to - 30 * 24 * 60 * 60_000 : timestamp(input.from, 'from');
+      if (from >= to) throw new TypeError('usage from must be before to');
+      const events = await store.query({ ...identity, from, to, limit: maxQueryEvents });
+      return aggregatePlatformUsage(events, identity, { from, to });
+    },
+  });
+}

package/packages/enclave-runtime/attestation.mjs

@@ -0,0 +1,159 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+
+const PCR_ZERO = Buffer.alloc(32);
+const HEX_256 = /^[a-f0-9]{64}$/;
+
+export const ENCLAVE_RUNTIME_MEASUREMENT = 'enigma-memory:enclave-runtime:v1';
+export const ZEROIZATION_POLICY_MEASUREMENT = 'best-effort-volatile-buffer:random-ff-zero:three-pass:v1';
+
+export function canonicalJson(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map((item) => canonicalJson(item)).join(',')}]`;
+  return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`;
+}
+
+export function sha256Hex(value) {
+  const input = Buffer.isBuffer(value) || value instanceof Uint8Array
+    ? value
+    : Buffer.from(typeof value === 'string' ? value : canonicalJson(value));
+  return createHash('sha256').update(input).digest('hex');
+}
+
+export function extendPcr(currentDigest, measurement) {
+  const current = currentDigest == null
+    ? PCR_ZERO
+    : Buffer.from(String(currentDigest).replace(/^sha256:/, ''), 'hex');
+  if (current.length !== 32) throw new TypeError('PCR digest must be a 32-byte SHA-256 value.');
+  const measured = Buffer.from(String(measurement).replace(/^sha256:/, ''), 'hex');
+  if (measured.length !== 32) throw new TypeError('Measurement must be a 32-byte SHA-256 value.');
+  return sha256Hex(Buffer.concat([current, measured]));
+}
+
+function measurePcr(input) {
+  return extendPcr(null, sha256Hex(input));
+}
+
+export function createAttestation({
+  bundle,
+  bundleHash,
+  nonce,
+  now = new Date().toISOString(),
+  runtimeMeasurement = ENCLAVE_RUNTIME_MEASUREMENT,
+  policyMeasurement = ZEROIZATION_POLICY_MEASUREMENT,
+  platform = `${process.platform}:${process.arch}:node-${process.versions.node.split('.')[0]}`,
+} = {}) {
+  const resolvedBundleHash = bundleHash
+    ? String(bundleHash).replace(/^sha256:/, '').toLowerCase()
+    : bundle === undefined
+      ? sha256Hex('no-bundle')
+      : sha256Hex(bundle);
+  if (!HEX_256.test(resolvedBundleHash)) throw new TypeError('bundleHash must be a SHA-256 digest.');
+
+  const pcrs = {
+    '0': measurePcr(runtimeMeasurement),
+    '1': measurePcr(policyMeasurement),
+    '2': measurePcr(platform),
+    '3': extendPcr(null, resolvedBundleHash),
+  };
+  const measurementHash = sha256Hex({ pcrs, runtimeMeasurement, policyMeasurement });
+
+  return {
+    schema: 'enigma.enclave.attestation.v1',
+    mode: 'simulated',
+    provider: 'enigma-local-pcr-simulator',
+    measured_at: now,
+    nonce: nonce ?? null,
+    runtime_measurement: runtimeMeasurement,
+    zeroization_policy_measurement: policyMeasurement,
+    platform_measurement: platform,
+    bundle_commitment: `sha256:${resolvedBundleHash}`,
+    pcr_bank: 'sha256',
+    pcrs,
+    measurement_hash: `sha256:${measurementHash}`,
+    claim_boundary: {
+      hardware_backed: false,
+      pcr_registers_simulated: true,
+      buffer_overwrite_best_effort: true,
+      hardware_ram_zeroization_proved: false,
+      runtime_copies_gc_caches_in_scope: false,
+      physical_media_sanitization_claimed: false,
+    },
+  };
+}
+
+export function verifyAttestation(attestation, { expectedBundleHash, expectedMeasurementHash } = {}) {
+  const errors = [];
+  if (!attestation || typeof attestation !== 'object') {
+    return { valid: false, errors: ['ATTESTATION_REQUIRED'] };
+  }
+  if (attestation.schema !== 'enigma.enclave.attestation.v1') errors.push('INVALID_SCHEMA');
+  if (attestation.mode !== 'simulated') errors.push('UNSUPPORTED_ATTESTATION_MODE');
+  if (attestation.pcr_bank !== 'sha256') errors.push('UNSUPPORTED_PCR_BANK');
+
+  const runtimeMeasurement = attestation.runtime_measurement;
+  const policyMeasurement = attestation.zeroization_policy_measurement;
+  const platformMeasurement = attestation.platform_measurement;
+  const bundleDigest = String(attestation.bundle_commitment ?? '').replace(/^sha256:/, '');
+  const declarationsValid = typeof runtimeMeasurement === 'string' && runtimeMeasurement.length > 0
+    && typeof policyMeasurement === 'string' && policyMeasurement.length > 0
+    && typeof platformMeasurement === 'string' && platformMeasurement.length > 0
+    && HEX_256.test(bundleDigest);
+  if (!declarationsValid) errors.push('INVALID_MEASUREMENT_DECLARATION');
+
+  const suppliedPcrs = attestation.pcrs;
+  const suppliedBankValid = suppliedPcrs
+    && ['0', '1', '2', '3'].every((index) => HEX_256.test(String(suppliedPcrs[index] ?? '')));
+  if (!suppliedBankValid) errors.push('INVALID_PCR_BANK');
+
+  let computedMeasurementHash;
+  if (declarationsValid) {
+    const expectedPcrs = {
+      '0': measurePcr(runtimeMeasurement),
+      '1': measurePcr(policyMeasurement),
+      '2': measurePcr(platformMeasurement),
+      '3': extendPcr(null, bundleDigest),
+    };
+    if (suppliedBankValid) {
+      for (const index of ['0', '1', '2', '3']) {
+        if (!safeStringEqual(expectedPcrs[index], suppliedPcrs[index])) errors.push(`PCR_${index}_MISMATCH`);
+      }
+    }
+    computedMeasurementHash = `sha256:${sha256Hex({
+      pcrs: expectedPcrs,
+      runtimeMeasurement,
+      policyMeasurement,
+    })}`;
+    if (!safeStringEqual(computedMeasurementHash, attestation.measurement_hash)) errors.push('MEASUREMENT_HASH_MISMATCH');
+  }
+
+  if (expectedBundleHash) {
+    const normalizedExpected = String(expectedBundleHash).replace(/^sha256:/, '').toLowerCase();
+    if (!HEX_256.test(normalizedExpected)
+      || !safeStringEqual(`sha256:${normalizedExpected}`, attestation.bundle_commitment)) {
+      errors.push('BUNDLE_COMMITMENT_MISMATCH');
+    }
+  }
+  if (expectedMeasurementHash
+    && !safeStringEqual(expectedMeasurementHash, computedMeasurementHash ?? attestation.measurement_hash)) {
+    errors.push('UNEXPECTED_MEASUREMENT');
+  }
+  const boundary = attestation.claim_boundary;
+  if (boundary?.hardware_backed !== false
+    || boundary?.pcr_registers_simulated !== true
+    || boundary?.hardware_ram_zeroization_proved !== false
+    || boundary?.runtime_copies_gc_caches_in_scope !== false) {
+    errors.push('INVALID_CLAIM_BOUNDARY');
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    measurement_hash: computedMeasurementHash ?? attestation.measurement_hash,
+    bundle_commitment: attestation.bundle_commitment,
+  };
+}
+
+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/enclave-runtime/index.mjs

@@ -0,0 +1,47 @@
+export {
+  ENCLAVE_RUNTIME_MEASUREMENT,
+  ZEROIZATION_POLICY_MEASUREMENT,
+  canonicalJson,
+  createAttestation,
+  extendPcr,
+  sha256Hex,
+  verifyAttestation,
+} from './attestation.mjs';
+
+export {
+  merkleRoot,
+  createZeroizationReceipt,
+  verifyZeroizationReceipt,
+  verifyStateNullification,
+} from './zeroization-proof.mjs';
+
+export {
+  VOLATILE_OVERWRITE_PROFILE,
+  EnclaveSessionManager,
+  SessionManager,
+  defaultSessionManager,
+  buffersEqual,
+  generateEphemeralSessionKey,
+  isZeroFilled,
+  overwriteVolatileBuffer,
+  zeroizeBuffer,
+} from './session-manager.mjs';
+
+import { createAttestation } from './attestation.mjs';
+import { defaultSessionManager } from './session-manager.mjs';
+
+export function initializeEnclaveSession(options) {
+  return defaultSessionManager.initializeSession(options);
+}
+
+export function deriveEnclaveSessionKey(sessionId, purpose, options) {
+  return defaultSessionManager.deriveSessionKey(sessionId, purpose, options);
+}
+
+export function zeroizeEnclaveSession(sessionId, options) {
+  return defaultSessionManager.zeroizeSession(sessionId, options);
+}
+
+export function attestEnclave(options) {
+  return createAttestation(options);
+}