enigma-memory 0.1.18 → 0.1.22

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

@@ -0,0 +1,132 @@
+const MAX_BODY_BYTES = 64 * 1024;
+const KEY_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+class ApiKeyHttpError extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.name = 'ApiKeyHttpError';
+    this.status = status;
+    this.code = code;
+  }
+}
+
+function writeJson(response, status, payload) {
+  const body = JSON.stringify(payload);
+  response.statusCode = status;
+  response.setHeader('Cache-Control', 'no-store');
+  response.setHeader('Content-Type', 'application/json; charset=utf-8');
+  response.setHeader('Content-Length', Buffer.byteLength(body));
+  response.setHeader('X-Content-Type-Options', 'nosniff');
+  response.end(body);
+}
+
+async function readJson(request) {
+  const contentType = String(request.headers['content-type'] || '').split(';', 1)[0].trim().toLowerCase();
+  if (contentType !== 'application/json') throw new ApiKeyHttpError(415, 'unsupported_media_type', 'Content-Type must be application/json');
+  const chunks = [];
+  let bytes = 0;
+  let tooLarge = false;
+  for await (const chunk of request) {
+    bytes += chunk.length;
+    if (bytes > MAX_BODY_BYTES) tooLarge = true;
+    else chunks.push(chunk);
+  }
+  if (tooLarge) throw new ApiKeyHttpError(413, 'payload_too_large', 'request body exceeds 64 KiB');
+  try {
+    const value = JSON.parse(Buffer.concat(chunks, bytes).toString('utf8') || '{}');
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error();
+    return value;
+  } catch {
+    throw new ApiKeyHttpError(400, 'invalid_json', 'request body must be a JSON object');
+  }
+}
+
+function rejectUnknown(input, allowed) {
+  const unknown = Object.keys(input).find((key) => !allowed.has(key));
+  if (unknown) throw new ApiKeyHttpError(400, 'invalid_request', `unknown field: ${unknown}`);
+}
+
+function issueInput(input, principal) {
+  rejectUnknown(input, new Set(['label', 'scopes', 'ttlSeconds']));
+  return {
+    ownerId: principal.ownerId || principal.subject,
+    tenantId: principal.tenantId || 'default',
+    actorId: principal.subject || principal.ownerId,
+    label: input.label,
+    scopes: input.scopes,
+    ttlSeconds: input.ttlSeconds,
+  };
+}
+
+function operationStatus(error) {
+  if (error instanceof ApiKeyHttpError) return error;
+  if (error?.code === 'not_found') return new ApiKeyHttpError(404, 'not_found', 'API key not found');
+  if (error instanceof TypeError) return new ApiKeyHttpError(400, 'invalid_request', error.message);
+  if (/not found/i.test(error?.message || '')) return new ApiKeyHttpError(404, 'not_found', 'API key not found');
+  if (/limit|active API key|revoked API key/i.test(error?.message || '')) return new ApiKeyHttpError(409, 'conflict', error.message);
+  return new ApiKeyHttpError(500, 'internal_error', 'API key operation failed');
+}
+
+export function createApiKeyHttpHandler(options = {}) {
+  const apiKeys = options.apiKeys;
+  if (!apiKeys || typeof apiKeys.issue !== 'function' || typeof apiKeys.authenticate !== 'function') throw new TypeError('apiKeys service is required');
+  if (typeof options.authorizeAdmin !== 'function') throw new TypeError('authorizeAdmin is required');
+  const basePath = String(options.basePath || '/v1/api-keys').replace(/\/+$/, '');
+
+  return async function apiKeyHttpHandler(request, response) {
+    const url = new URL(request.url || '/', 'http://localhost');
+    if (url.pathname !== basePath && !url.pathname.startsWith(`${basePath}/`)) return false;
+    try {
+      let principal;
+      try { principal = await options.authorizeAdmin({ request, headers: request.headers }); } catch { principal = null; }
+      if (!principal?.subject && !principal?.ownerId) throw new ApiKeyHttpError(401, 'unauthorized', 'administrator authentication is required');
+      const identity = {
+        ownerId: principal.ownerId || principal.subject,
+        tenantId: principal.tenantId || 'default',
+        actorId: principal.subject || principal.ownerId,
+      };
+
+      if (request.method === 'GET' && url.pathname === `${basePath}/scopes`) {
+        writeJson(response, 200, { schema: 'enigma.api_key_scopes.v1', scopes: apiKeys.supportedScopes });
+        return true;
+      }
+      if (request.method === 'GET' && url.pathname === `${basePath}/audit`) {
+        const limitValue = url.searchParams.get('limit');
+        const limit = limitValue === null ? undefined : Number(limitValue);
+        writeJson(response, 200, { schema: 'enigma.api_key_audit.v1', events: await apiKeys.audit({ ...identity, limit }) });
+        return true;
+      }
+      if (request.method === 'GET' && url.pathname === basePath) {
+        writeJson(response, 200, { schema: 'enigma.api_key_list.v1', keys: await apiKeys.list(identity) });
+        return true;
+      }
+      if (request.method === 'POST' && url.pathname === basePath) {
+        const input = await readJson(request);
+        writeJson(response, 201, await apiKeys.issue(issueInput(input, identity)));
+        return true;
+      }
+
+      const suffix = url.pathname.slice(basePath.length + 1);
+      const [id, action, extra] = suffix.split('/');
+      if (!KEY_ID_PATTERN.test(id || '') || extra) throw new ApiKeyHttpError(404, 'not_found', 'API key endpoint not found');
+      if (request.method === 'POST' && action === 'rotate') {
+        const input = await readJson(request);
+        rejectUnknown(input, new Set(['label', 'scopes', 'ttlSeconds']));
+        writeJson(response, 201, await apiKeys.rotate(id, { ...issueInput(input, identity) }));
+        return true;
+      }
+      if (request.method === 'DELETE' && action === undefined) {
+        const input = await readJson(request);
+        rejectUnknown(input, new Set(['reason']));
+        writeJson(response, 200, await apiKeys.revoke(id, { ...identity, reason: input.reason }));
+        return true;
+      }
+      throw new ApiKeyHttpError(405, 'method_not_allowed', 'API key endpoint method is not allowed');
+    } catch (error) {
+      const normalized = operationStatus(error);
+      if (normalized.status === 401) response.setHeader('WWW-Authenticate', 'Bearer');
+      writeJson(response, normalized.status, { error: { code: normalized.code, message: normalized.message } });
+      return true;
+    }
+  };
+}

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

@@ -0,0 +1,4 @@
+export * from './access-credentials.js';
+export * from './http.js';
+export * from './usage.js';
+export * from './usage-http.js';

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

@@ -0,0 +1,60 @@
+function json(response, status, payload) {
+  const body = JSON.stringify(payload);
+  response.statusCode = status;
+  response.setHeader('Cache-Control', 'no-store');
+  response.setHeader('Content-Type', 'application/json; charset=utf-8');
+  response.setHeader('Content-Length', Buffer.byteLength(body));
+  response.setHeader('X-Content-Type-Options', 'nosniff');
+  response.end(body);
+}
+
+function queryInput(url, principal) {
+  const daysValue = url.searchParams.get('days');
+  const days = daysValue === null ? 30 : Number(daysValue);
+  if (!Number.isInteger(days) || days < 1 || days > 400) throw new TypeError('days must be an integer from 1 through 400');
+  const to = url.searchParams.get('to') || undefined;
+  const parsedTo = to === undefined ? Date.now() + 1 : Date.parse(to);
+  if (!Number.isFinite(parsedTo)) throw new TypeError('to must be an ISO timestamp');
+  const from = url.searchParams.get('from') || new Date(parsedTo - days * 24 * 60 * 60_000).toISOString();
+  if (!Number.isFinite(Date.parse(from))) throw new TypeError('from must be an ISO timestamp');
+  const limitValue = url.searchParams.get('limit');
+  const limit = limitValue === null ? undefined : Number(limitValue);
+  return { principal, from, to: new Date(parsedTo).toISOString(), limit };
+}
+
+export function createUsageHttpHandler(options = {}) {
+  const usage = options.usage;
+  if (!usage || typeof usage.aggregate !== 'function' || typeof usage.events !== 'function') throw new TypeError('usage service is required');
+  if (typeof options.authorize !== 'function') throw new TypeError('usage HTTP authorizer is required');
+  const basePath = String(options.basePath || '/v1/usage').replace(/\/+$/, '');
+
+  return async function usageHttpHandler(request, response) {
+    const url = new URL(request.url || '/', 'http://localhost');
+    if (url.pathname !== basePath && url.pathname !== `${basePath}/events`) return false;
+    try {
+      let principal;
+      try { principal = await options.authorize({ request, headers: request.headers, requiredScopes: ['usage:read'] }); } catch { principal = null; }
+      if (!principal) {
+        response.setHeader('WWW-Authenticate', 'Bearer scope="usage:read"');
+        json(response, 401, { error: { code: 'unauthorized', message: 'usage:read authorization is required' } });
+        return true;
+      }
+      if (request.method !== 'GET') {
+        response.setHeader('Allow', 'GET');
+        json(response, 405, { error: { code: 'method_not_allowed', message: 'usage endpoints are read-only' } });
+        return true;
+      }
+      const input = queryInput(url, principal);
+      if (url.pathname === `${basePath}/events`) {
+        json(response, 200, { schema: 'enigma.platform_usage_event_list.v1', events: await usage.events(input) });
+      } else {
+        json(response, 200, await usage.aggregate(input));
+      }
+      return true;
+    } catch (error) {
+      const status = error instanceof TypeError ? 400 : 500;
+      json(response, status, { error: { code: status === 400 ? 'invalid_request' : 'usage_error', message: error.message || 'usage query failed' } });
+      return true;
+    }
+  };
+}

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);
+}