enigma-memory 0.1.18 → 0.1.22

package/apps/relay/src/server.mjs

@@ -23,6 +23,18 @@ import {
   normalizeDependencyEvidence,
   readinessEvidenceRefs,
 } from '../../../packages/adapters/src/index.js';
+import { attachFederationServeMode } from './federation-runtime.mjs';
+export {
+  AuthenticatedWebSocketFederationTransport,
+  FEDERATION_SERVE_PATH,
+  FEDERATION_STORAGE_ADAPTER_SCHEMA,
+  FederationServeRuntime,
+  FederationServeTransport,
+  MemoryFederationStorageAdapter,
+  attachFederationServeMode,
+  createMemoryFederationStorageAdapter,
+  validateFederationStorageAdapter,
+} from './federation-runtime.mjs';
 
 const SERVICE_SCHEMA = 'enigma.relay_service.v1';
 const PAIRING_CHALLENGE_SCHEMA = 'enigma.pairing_challenge.v1';
@@ -30,6 +42,7 @@ const PAIRING_COMPLETION_SCHEMA = 'enigma.pairing_completion.v1';
 const CLIENT_AUTH_SCHEMA = 'enigma.relay_client_authorization.v1';
 const RELAY_STATE_SCHEMA = 'enigma.relay_state.v1';
 const RELAY_STATE_VERSION = 1;
+export const RELAY_STATE_ADAPTER_SCHEMA = 'enigma.relay_state_adapter.v1';
 const DEFAULT_NOW = '1970-01-01T00:00:00.000Z';
 const DEFAULT_CHALLENGE_TTL_MS = 5 * 60 * 1000;
 const MAX_JSON_BODY_BYTES = 64 * 1024;
@@ -182,6 +195,7 @@ const RELAY_STATE_KEYS = new Set([
   'relay_store',
   'relay_records',
   'witness_log',
+  'pending_pairing_challenges',
   'completed_pairings',
   'authorization'
 ]);
@@ -218,6 +232,16 @@ const RELAY_STATE_PAIRING_KEYS = new Set([
   'issued_at',
   'signature'
 ]);
+const RELAY_STATE_CHALLENGE_KEYS = new Set([
+  'schema',
+  'challenge_id',
+  'relay_node_id',
+  'client_public_key',
+  'client_public_key_hash',
+  'nonce',
+  'issued_at',
+  'expires_at'
+]);
 const SIGNATURE_KEYS = new Set(['alg', 'key_id', 'value']);
 
 function isPlainRecord(value) {
@@ -554,7 +578,7 @@ function relayProductionReadinessFromOptions(options) {
       options.storage,
       options.storage_ref,
       options.storageRef,
-      envValue('ENIGMA_EXTERNAL_STORAGE_DSN', 'ENIGMA_EXTERNAL_STORAGE_DSN_FILE', 'ENIGMA_EXTERNAL_STORAGE_REF', 'ENIGMA_RELAY_STORAGE_REF', 'ENIGMA_DURABLE_STORAGE_REF')
+      envValue('ENIGMA_EXTERNAL_STORAGE_DSN', 'ENIGMA_EXTERNAL_STORAGE_REF', 'ENIGMA_RELAY_STORAGE_REF', 'ENIGMA_DURABLE_STORAGE_REF')
     ),
     kms_or_secret_custody: firstDefined(
       options.kms_or_secret_custody,
@@ -578,7 +602,7 @@ function relayProductionReadinessFromOptions(options) {
       options.auditSink,
       options.log_sink,
       options.logSink,
-      envValue('ENIGMA_SIEM_EXPORT_ENDPOINT', 'ENIGMA_SIEM_EXPORT_ENDPOINT_FILE', 'ENIGMA_SIEM_REF', 'ENIGMA_AUDIT_SINK_REF', 'ENIGMA_LOG_SINK_REF')
+      envValue('ENIGMA_SIEM_EXPORT_ENDPOINT', 'ENIGMA_SIEM_REF', 'ENIGMA_AUDIT_SINK_REF', 'ENIGMA_LOG_SINK_REF')
     ),
     backup_restore: firstDefined(
       options.backup_restore,
@@ -588,7 +612,7 @@ function relayProductionReadinessFromOptions(options) {
       options.backupTarget,
       options.restore_target,
       options.restoreTarget,
-      envValue('ENIGMA_BACKUP_TARGET_URI', 'ENIGMA_BACKUP_TARGET_URI_FILE', 'ENIGMA_BACKUP_TARGET_REF', 'ENIGMA_RESTORE_TARGET_REF')
+      envValue('ENIGMA_BACKUP_TARGET_URI', 'ENIGMA_BACKUP_TARGET_REF', 'ENIGMA_RESTORE_TARGET_REF')
     ),
     monitoring: firstDefined(
       options.monitoring,
@@ -839,6 +863,22 @@ function relayReadiness(state) {
     : [
       relayReadinessCheck('non_production_local_mode', localMode, 'relay readiness is only green for non-production local mode')
     ];
+  const federationStatus = state.federationRuntime?.status();
+  if (federationStatus) {
+    checks.push(...federationStatus.checks.map((check) => relayReadinessCheck(
+      check.check,
+      check.ok,
+      `${check.check.replaceAll('_', ' ')} is not ready`
+    )));
+  }
+  const persistenceStatus = state.relayStatePersistence?.status();
+  if (persistenceStatus) {
+    checks.push(...persistenceStatus.checks.map((check) => relayReadinessCheck(
+      check.check,
+      check.ok,
+      `${check.check.replaceAll('_', ' ')} is not ready`
+    )));
+  }
   const missingChecks = checks.filter((check) => check.ok !== true).map((check) => check.check);
   const ready = checks.every((check) => check.ok === true);
   return {
@@ -1046,7 +1086,8 @@ function serviceHealth(state) {
     authorization: {
       mode: state.allowUnauthenticated === true ? 'unauthenticated_local_demo' : 'paired_client_signature_required',
       endpoints: ['/relay/push', '/relay/pull', '/witness/checkpoint']
-    }
+    },
+    federation: state.federationRuntime?.status() ?? { enabled: false, ready: false }
   };
 }
 
@@ -1201,6 +1242,25 @@ function hydrateRelayStoreState(storeState, recordsState, node) {
   }
   return relayStore;
 }
+function validatePendingPairingChallenge(challengeState, node) {
+  const challenge = assertPlainRecord(cloneJson(challengeState, 'pending pairing challenge state'), 'pending pairing challenge state');
+  assertOnlyKeys(challenge, RELAY_STATE_CHALLENGE_KEYS, 'pending pairing challenge state');
+  if (challenge.schema !== PAIRING_CHALLENGE_SCHEMA) throw new Error('pending pairing challenge schema mismatch');
+  if (challenge.relay_node_id !== node.node_id) throw new Error('pending pairing challenge relay_node_id mismatch');
+  assertString(challenge.client_public_key, 'pending pairing challenge client_public_key');
+  if (challenge.client_public_key_hash !== `sha256:${sha256Hex(challenge.client_public_key)}`) {
+    throw new Error('pending pairing challenge client_public_key_hash mismatch');
+  }
+  assertString(challenge.nonce, 'pending pairing challenge nonce');
+  assertIsoDate(challenge.issued_at, 'pending pairing challenge issued_at');
+  assertIsoDate(challenge.expires_at, 'pending pairing challenge expires_at');
+  const expectedChallengeId = `pch_${sha256Hex(canonicalize({
+    clientPublicKey: challenge.client_public_key,
+    nonce: challenge.nonce
+  })).slice(0, 32)}`;
+  if (challenge.challenge_id !== expectedChallengeId) throw new Error('pending pairing challenge challenge_id mismatch');
+  return Object.freeze({ challenge: Object.freeze(challenge), publicKey: challenge.client_public_key });
+}
 
 function authorizationFromSnapshot(authorization) {
   const record = assertPlainRecord(authorization, 'relay authorization state');
@@ -1221,6 +1281,9 @@ export function serializeRelayState(state) {
   const records = [...state.relayStore.records.values()].map((record) => cloneJson(record, 'relay record state'));
   const witnessLog = state.witnessLog.map((checkpoint) => cloneJson(checkpoint, 'witness checkpoint state'));
   const completedPairings = [...state.pairings.values()].map((pairing) => cloneJson(pairing, 'completed pairing state'));
+  const pendingPairingChallenges = state.persistPendingPairingChallenges === true
+    ? [...state.pairingChallenges.values()].map((pending) => cloneJson(pending.challenge, 'pending pairing challenge state'))
+    : null;
   const snapshot = {
     schema: RELAY_STATE_SCHEMA,
     version: RELAY_STATE_VERSION,
@@ -1237,6 +1300,7 @@ export function serializeRelayState(state) {
     },
     relay_records: records,
     witness_log: witnessLog,
+    ...(pendingPairingChallenges ? { pending_pairing_challenges: pendingPairingChallenges } : {}),
     completed_pairings: completedPairings,
     authorization: {
       mode: relayAuthorizationMode(state),
@@ -1260,6 +1324,14 @@ export function hydrateRelayState(snapshot, options = {}) {
   const node = hydrateNodeState(record.node);
   const relayStore = hydrateRelayStoreState(record.relay_store, record.relay_records, node);
   const witnessLog = validateWitnessLog(record.witness_log, node);
+  const pendingChallengeStates = record.pending_pairing_challenges ?? [];
+  if (!Array.isArray(pendingChallengeStates)) throw new TypeError('pending_pairing_challenges must be an array');
+  const pairingChallenges = new Map();
+  for (const challengeState of pendingChallengeStates) {
+    const pending = validatePendingPairingChallenge(challengeState, node);
+    if (pairingChallenges.has(pending.challenge.challenge_id)) throw new Error('duplicate pending pairing challenge_id in state');
+    pairingChallenges.set(pending.challenge.challenge_id, pending);
+  }
   if (!Array.isArray(record.completed_pairings)) throw new TypeError('completed_pairings must be an array');
   const pairings = new Map();
   for (const pairingState of record.completed_pairings) {
@@ -1269,6 +1341,7 @@ export function hydrateRelayState(snapshot, options = {}) {
   }
 
   const state = createRelayState({
+    ...options,
     node,
     relayStore,
     witnessLog,
@@ -1277,7 +1350,7 @@ export function hydrateRelayState(snapshot, options = {}) {
     allowUnauthenticated: authorization.allow_unauthenticated
   });
   state.pairings = pairings;
-  state.pairingChallenges = new Map();
+  state.pairingChallenges = pairingChallenges;
   return state;
 }
 
@@ -1360,19 +1433,246 @@ export function createRelayState(options = {}) {
       value: relayProductionReadinessFromOptions(options),
       writable: true,
       configurable: true
+    },
+    persistPendingPairingChallenges: {
+      value: options.persistPendingPairingChallenges === true || options.persist_pending_pairing_challenges === true,
+      writable: false,
+      configurable: true
     }
   });
   return state;
 }
 
+function relayFederationOptions(options, state) {
+  const configured = options.federation ?? options.federationServe;
+  if (!configured) return null;
+  const readiness = state.production_readiness ?? {};
+  return {
+    ...configured,
+    mode: configured.mode ?? state.mode,
+    authRef: configured.authRef ?? readiness.runtime_auth,
+    kmsRef: configured.kmsRef ?? readiness.kms_or_secret_custody,
+  };
+}
+
+function relayReplicaCount(options) {
+  const value = firstDefined(
+    options.replicaCount,
+    options.replica_count,
+    envValue('ENIGMA_RELAY_REPLICA_COUNT', 'ENIGMA_REPLICA_COUNT')
+  );
+  if (value === undefined) return 1;
+  const count = Number(value);
+  if (!Number.isSafeInteger(count) || count < 1) throw new TypeError('relay replica count must be a positive safe integer');
+  return count;
+}
+
+export function validateRelayStateAdapter(adapter, { production = false, replicaCount = 1 } = {}) {
+  if (!isPlainRecord(adapter)) throw new TypeError('relay state adapter is required');
+  if (adapter.schema !== RELAY_STATE_ADAPTER_SCHEMA) {
+    throw new TypeError(`relay state adapter schema must be ${RELAY_STATE_ADAPTER_SCHEMA}`);
+  }
+  if (!nonEmptyString(adapter.ref)) throw new TypeError('relay state adapter ref is required');
+  if (typeof adapter.isReady !== 'function' || typeof adapter.transaction !== 'function') {
+    throw new TypeError('relay state adapter must implement isReady() and transaction(operation, options)');
+  }
+  if (production && (adapter.durable !== true || adapter.encryptedAtRest !== true)) {
+    throw new TypeError('production relay state adapter must be durable and encrypted at rest');
+  }
+  if (replicaCount > 1 && adapter.supportsMultiReplica !== true) {
+    throw new TypeError('multiple relay replicas require an atomic multi-replica relay state adapter');
+  }
+  return adapter;
+}
+
+function createBufferedRelayResponse() {
+  const response = {
+    statusCode: 200,
+    headers: {},
+    body: '',
+    writeHead(statusCode, headers = {}) {
+      response.statusCode = statusCode;
+      response.headers = { ...headers };
+      return response;
+    },
+    end(body = '') {
+      response.body = body === undefined ? '' : Buffer.isBuffer(body) ? Buffer.from(body) : String(body);
+      response.ended = true;
+      return response;
+    }
+  };
+  return response;
+}
+
+function flushBufferedRelayResponse(buffered, response) {
+  if (!buffered?.ended || !Number.isInteger(buffered.statusCode)) {
+    throw new Error('relay state transaction completed without an HTTP response');
+  }
+  response.writeHead(buffered.statusCode, buffered.headers);
+  response.end(buffered.body);
+}
+
+class RelayStatePersistenceCoordinator {
+  constructor(adapter, initialState, options, replicaCount) {
+    this.adapter = adapter;
+    Object.defineProperty(initialState, 'persistPendingPairingChallenges', {
+      value: true,
+      writable: false,
+      configurable: true
+    });
+    this.options = { ...options, persistPendingPairingChallenges: true };
+    this.initialSnapshot = serializeRelayState(initialState);
+    this.replicaCount = replicaCount;
+    this.ready = false;
+    this.lastError = null;
+    this.state = initialState;
+  }
+
+  async refresh() {
+    try {
+      this.ready = await this.adapter.isReady() === true;
+      if (!this.ready) throw new Error('relay state adapter is not ready');
+      this.lastError = null;
+    } catch (error) {
+      this.ready = false;
+      this.lastError = error instanceof Error ? error.message : 'relay state adapter failed';
+    }
+    return this.ready;
+  }
+
+  status() {
+    return {
+      ready: this.ready,
+      ref: this.adapter.ref,
+      durable: this.adapter.durable === true,
+      encrypted_at_rest: this.adapter.encryptedAtRest === true,
+      supports_multi_replica: this.adapter.supportsMultiReplica === true,
+      replica_count: this.replicaCount,
+      last_error: this.lastError,
+      checks: [
+        { check: 'relay_state_adapter', ok: this.ready === true },
+        { check: 'relay_state_durable', ok: this.adapter.durable === true },
+        { check: 'relay_state_encrypted_at_rest', ok: this.adapter.encryptedAtRest === true },
+        { check: 'relay_state_replica_safety', ok: this.replicaCount === 1 || this.adapter.supportsMultiReplica === true }
+      ]
+    };
+  }
+
+  decorate(state, federationRuntime) {
+    Object.defineProperties(state, {
+      relayStatePersistence: {
+        value: this,
+        writable: false,
+        configurable: true
+      },
+      ...(federationRuntime ? {
+        federationRuntime: {
+          value: federationRuntime,
+          writable: false,
+          configurable: true
+        }
+      } : {})
+    });
+    return state;
+  }
+
+  async handle(request, response, federationRuntime) {
+    const path = new URL(request.url ?? '/', 'http://enigma.local').pathname;
+    if (path === '/livez') {
+      await handleRelayRequest(this.decorate(this.state, federationRuntime), request, response);
+      return;
+    }
+    if (!await this.refresh()) {
+      jsonResponse(response, 503, fail('relay durable state dependency is unavailable'));
+      return;
+    }
+    try {
+      const value = await this.adapter.transaction(async (storedSnapshot) => {
+        const state = storedSnapshot
+          ? hydrateRelayState(storedSnapshot, this.options)
+          : hydrateRelayState(this.initialSnapshot, this.options);
+        this.decorate(state, federationRuntime);
+        const buffered = createBufferedRelayResponse();
+        await handleRelayRequest(state, request, buffered);
+        return {
+          snapshot: serializeRelayState(state),
+          value: { state, response: buffered }
+        };
+      }, { initialSnapshot: this.initialSnapshot });
+      if (!value?.state || !value?.response) throw new Error('relay state adapter transaction returned an invalid result');
+      this.state = value.state;
+      flushBufferedRelayResponse(value.response, response);
+    } catch (error) {
+      this.ready = false;
+      this.lastError = error instanceof Error ? error.message : 'relay state transaction failed';
+      jsonResponse(response, 503, fail('relay durable state transaction failed'));
+    }
+  }
+}
+
 export function createRelayServer(options = {}) {
-  const state = options.state ?? createRelayState(options);
+  const initialState = options.state ?? createRelayState(options);
+  const production = isProductionLikeState(initialState);
+  const replicaCount = relayReplicaCount(options);
+  const configuredAdapter = options.relayStateAdapter ?? options.relay_state_adapter;
+  if (production && !configuredAdapter) {
+    throw new TypeError('production relay serve mode requires a durable relay state adapter');
+  }
+  const stateAdapter = configuredAdapter
+    ? validateRelayStateAdapter(configuredAdapter, { production, replicaCount })
+    : null;
+  let persistence = null;
+  let federationRuntime = null;
+  const localStateFile = !production && !stateAdapter && typeof options.stateFile === 'string' && options.stateFile
+    ? options.stateFile
+    : null;
+  const saveLocalState = typeof options.saveRelayState === 'function'
+    ? options.saveRelayState
+    : saveRelayStateToFile;
+  let localSaveQueue = Promise.resolve();
   const server = createServer((req, res) => {
-    handleRelayRequest(state, req, res).catch((error) => {
-      jsonResponse(res, 500, fail(error instanceof Error ? error.message : 'relay request failed'));
+    let durableTask;
+    if (persistence) {
+      durableTask = persistence.handle(req, res, federationRuntime);
+    } else if (localStateFile) {
+      const buffered = createBufferedRelayResponse();
+      durableTask = handleRelayRequest(initialState, req, buffered).then(async () => {
+        localSaveQueue = localSaveQueue.then(() => saveLocalState(initialState, localStateFile));
+        await localSaveQueue;
+        flushBufferedRelayResponse(buffered, res);
+      });
+    } else {
+      durableTask = handleRelayRequest(initialState, req, res);
+    }
+    durableTask.catch((error) => {
+      server.emit('statePersistenceError', error);
+      if (!res.headersSent) jsonResponse(res, 500, fail(error instanceof Error ? error.message : 'relay request failed'));
+    });
+  });
+  const federationOptions = relayFederationOptions(options, initialState);
+  if (production && !federationOptions) {
+    throw new TypeError('production relay serve mode requires federation bridge configuration');
+  }
+  if (federationOptions) {
+    federationRuntime = attachFederationServeMode(server, federationOptions);
+    Object.defineProperty(initialState, 'federationRuntime', {
+      value: federationRuntime,
+      writable: false,
+      configurable: true,
     });
+    server.federationRuntime = federationRuntime;
+  }
+  if (stateAdapter) {
+    persistence = new RelayStatePersistenceCoordinator(stateAdapter, initialState, options, replicaCount);
+    persistence.decorate(initialState, federationRuntime);
+    server.relayStatePersistence = persistence;
+    server.once('listening', () => void persistence.refresh());
+  }
+  Object.defineProperty(server, 'relayState', {
+    configurable: true,
+    get: () => persistence?.state ?? initialState,
   });
-  server.relayState = state;
+  server.waitForLocalPersistence = () => localSaveQueue;
   return server;
 }
 
@@ -1396,6 +1696,7 @@ export async function handleRelayRequest(state, req, res) {
     }
 
     if (method === 'GET' && url.pathname === '/readyz') {
+      if (state.federationRuntime) await state.federationRuntime.refreshDependencies();
       const readiness = relayReadiness(state);
       jsonResponse(res, readiness.statusCode, readiness.body);
       return;