@yeaft/webchat-agent 1.0.373 → 1.0.375

package/local-runtime/server/db/user-db.js

@@ -1,4 +1,50 @@
-import { stmts, generateUserId, generateAgentSecret, transaction } from './connection.js';
+import { createHash, randomUUID } from 'crypto';
+import db, { stmts, generateUserId, generateAgentSecret, transaction } from './connection.js';
+
+function deletionRequestDigest() {
+  return createHash('sha256').update(JSON.stringify({ kind: 'remove' })).digest('hex');
+}
+
+function ensureDeletionRemoval(userId, deletionId, now = Date.now()) {
+  const sandbox = db.prepare('SELECT * FROM sandboxes WHERE user_id = ? AND reservation_held = 1').get(userId);
+  if (!sandbox) return null;
+  const baseKey = `account-delete:${deletionId}`;
+  const attempts = db.prepare(`
+    SELECT * FROM sandbox_operations
+    WHERE user_id = ? AND (idempotency_key = ? OR idempotency_key LIKE ?)
+    ORDER BY created_at DESC, rowid DESC
+  `).all(userId, baseKey, `${baseKey}:attempt:%`);
+  const latest = attempts[0];
+  if (latest && latest.status !== 'failed') return latest;
+  const key = attempts.length === 0 ? baseKey : `${baseKey}:attempt:${attempts.length + 1}`;
+  const existing = db.prepare('SELECT * FROM sandbox_operations WHERE user_id = ? AND idempotency_key = ?')
+    .get(userId, key);
+  if (existing) return existing;
+  db.prepare(`
+    UPDATE sandbox_operations SET status = 'failed', error_code = 'ACCOUNT_DELETION_REQUESTED', updated_at = ?
+    WHERE sandbox_id = ? AND status IN ('pending', 'running')
+  `).run(now, sandbox.id);
+  db.prepare('UPDATE sandbox_credentials SET revoked_at = ? WHERE sandbox_id = ? AND revoked_at IS NULL')
+    .run(now, sandbox.id);
+  const host = db.prepare('SELECT epoch FROM sandbox_hosts WHERE id = ?').get(sandbox.host_id);
+  const hostEpoch = host?.epoch || sandbox.host_epoch;
+  const generation = sandbox.generation + 1;
+  db.prepare(`
+    UPDATE sandboxes SET desired_state = 'removed', observed_state = CASE
+      WHEN observed_state = 'removed' THEN observed_state ELSE 'recovery_required' END,
+      generation = ?, host_epoch = ?, last_error_code = NULL, updated_at = ?
+    WHERE id = ? AND reservation_held = 1
+  `).run(generation, hostEpoch, now, sandbox.id);
+  const operationId = `sandbox_op_${randomUUID()}`;
+  db.prepare(`
+    INSERT INTO sandbox_operations (
+      id, sandbox_id, user_id, idempotency_key, request_digest, kind, status,
+      stage, generation, host_epoch, deadline_at, created_at, updated_at
+    ) VALUES (?, ?, ?, ?, ?, 'remove', 'pending', 'removing', ?, ?, ?, ?, ?)
+  `).run(operationId, sandbox.id, userId, key, deletionRequestDigest(), generation,
+    hostEpoch, now + 10 * 60_000, now, now);
+  return db.prepare('SELECT * FROM sandbox_operations WHERE id = ?').get(operationId);
+}
 
 export const userDb = {
   getOrCreate(username, displayName = null) {
@@ -21,9 +67,10 @@ export const userDb = {
   },
 
   migrateUser(username, passwordHash, email, role = 'admin') {
+    if (this.isDeletionTombstoned(username)) return null;
     const existing = stmts.getUserByUsername.get(username);
     if (existing) {
-      if (existing.password_hash) {
+      if ((existing.deletion_state && existing.deletion_state !== 'active') || existing.password_hash) {
         return existing;
       }
       const newSecret = generateAgentSecret();
@@ -41,6 +88,10 @@ export const userDb = {
     return stmts.getUserByUsername.get(username);
   },
 
+  isDeletionTombstoned(username) {
+    return stmts.getUserDeletionTombstone.get(username) !== undefined;
+  },
+
   getUserByAgentSecret(secret) {
     if (!secret) return null;
     return stmts.getUserByAgentSecret.get(secret) || null;
@@ -50,6 +101,63 @@ export const userDb = {
     return stmts.getAllUsers.all();
   },
 
+  isActive(userId) {
+    return db.prepare("SELECT 1 FROM users WHERE id = ? AND deletion_state = 'active'").get(userId) !== undefined;
+  },
+
+  beginDeletion(userId, now = Date.now()) {
+    return transaction(() => {
+      const user = stmts.getUserById.get(userId);
+      if (!user) return null;
+      const deletionId = user.deletion_id || `deletion_${randomUUID()}`;
+      if (user.deletion_state !== 'pending') {
+        const changed = db.prepare(`
+          UPDATE users SET deletion_state = 'pending', deletion_requested_at = ?, deletion_id = ?,
+            password_hash = NULL, agent_secret = NULL, totp_secret = NULL, totp_enabled = 0
+          WHERE id = ? AND deletion_state = 'active'
+        `).run(now, deletionId, userId);
+        if (changed.changes !== 1) {
+          throw new Error('ACCOUNT_DELETION_STATE_CONFLICT');
+        }
+      }
+      db.prepare('UPDATE sandbox_entitlements SET enabled = 0, updated_at = ? WHERE user_id = ?')
+        .run(now, userId);
+      const operation = ensureDeletionRemoval(userId, deletionId, now);
+      return { deletionId, status: 'pending', operationId: operation?.id || null };
+    })();
+  },
+
+  reconcilePendingDeletions(now = Date.now()) {
+    const pending = db.prepare("SELECT id, deletion_id FROM users WHERE deletion_state = 'pending'").all();
+    let finalized = 0;
+    for (const user of pending) {
+      if (stmts.getReservedSandboxForUser.get(user.id)) {
+        transaction(() => ensureDeletionRemoval(user.id, user.deletion_id, now))();
+        continue;
+      }
+      const unsettled = db.prepare(`
+        SELECT 1 FROM sandboxes s
+        WHERE s.user_id = ? AND (
+          s.observed_state != 'removed' OR s.removed_at IS NULL
+          OR EXISTS (
+            SELECT 1 FROM sandbox_operations o
+            WHERE o.sandbox_id = s.id AND o.status IN ('pending', 'running')
+          )
+          OR NOT EXISTS (
+            SELECT 1 FROM sandbox_operations o
+            WHERE o.sandbox_id = s.id AND o.kind = 'remove' AND o.status = 'succeeded'
+          )
+          OR EXISTS (
+            SELECT 1 FROM sandbox_credentials c
+            WHERE c.sandbox_id = s.id AND c.revoked_at IS NULL
+          )
+        ) LIMIT 1
+      `).get(user.id);
+      if (!unsettled && this.deleteUser(user.id, { requirePending: true })) finalized++;
+    }
+    return finalized;
+  },
+
   updateLogin(id) {
     stmts.updateUserLogin.run(Date.now(), id);
   },
@@ -106,7 +214,8 @@ export const userDb = {
 
   getByAadOid(aadOid) {
     if (!aadOid) return null;
-    return stmts.getUserByAadOid.get(aadOid) || null;
+    const user = stmts.getUserByAadOid.get(aadOid) || null;
+    return user?.deletion_state === 'active' ? user : null;
   },
 
   updateAadOid(userId, aadOid) {
@@ -145,18 +254,39 @@ export const userDb = {
    * Caller is responsible for revoking JWT sessions (we don't import the
    * session store from here to keep this layer pure).
    */
-  deleteUser(userId) {
-    // No inner try/catch — any failure must bubble out so the transaction
-    // rolls back. A partial delete (e.g. users row gone but daily_stats
-    // orphaned) is worse than the operation failing outright.
+  deleteUser(userId, { requirePending = false } = {}) {
+    // Final erasure is allowed only after every Sandbox reservation has settled.
     const run = transaction((id) => {
+      const user = stmts.getUserById.get(id);
+      if (!user || (requirePending && user.deletion_state !== 'pending')) return false;
+      if (stmts.getReservedSandboxForUser.get(id)) {
+        const error = new Error('SANDBOX_REMOVE_REQUIRED');
+        error.code = 'SANDBOX_REMOVE_REQUIRED';
+        throw error;
+      }
+      if (requirePending) {
+        const unsettled = db.prepare(`
+          SELECT 1 FROM sandboxes s WHERE s.user_id = ? AND (
+            s.observed_state != 'removed' OR s.removed_at IS NULL
+            OR EXISTS (SELECT 1 FROM sandbox_operations o WHERE o.sandbox_id = s.id AND o.status IN ('pending', 'running'))
+            OR NOT EXISTS (SELECT 1 FROM sandbox_operations o WHERE o.sandbox_id = s.id AND o.kind = 'remove' AND o.status = 'succeeded')
+            OR EXISTS (SELECT 1 FROM sandbox_credentials c WHERE c.sandbox_id = s.id AND c.revoked_at IS NULL)
+          ) LIMIT 1
+        `).get(id);
+        if (unsettled) return false;
+      }
+      stmts.deleteReleasedSandboxesForUser.run(id);
       stmts.deleteIdentitiesForUser.run(id);
       stmts.deleteUserSessionsByUser.run(id);
+      stmts.deleteYeaftSessionsByUserCascade.run(id);
       stmts.deleteUserStats.run(id);
       stmts.deleteDailyStatsForUser.run(id);
       stmts.deleteCustomExpertRolesForUser.run(id);
       stmts.deleteInvitationsCreatedBy.run(id);
       stmts.clearInvitationUsedBy.run(id);
+      if (requirePending) {
+        stmts.insertUserDeletionTombstone.run(user.username, user.deletion_id, Date.now());
+      }
       const result = stmts.deleteUserById.run(id);
       return result.changes > 0;
     });

package/local-runtime/server/index.js

@@ -9,13 +9,18 @@ import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import { CONFIG, isEmailConfigured, validateProductionConfig } from './config.js';
 import { agents, webClients, userFileTabs, userStatsDeltas } from './context.js';
-import { invitationDb, userStatsDb, closeDb } from './database.js';
+import { invitationDb, userDb, userStatsDb, closeDb } from './database.js';
 import { registerApiRoutes } from './api.js';
 import { registerProxyRoutes, handleProxyWebSocketUpgrade } from './proxy.js';
 import { handleAgentConnection } from './ws-agent.js';
 import { handleWebConnection } from './ws-client.js';
 import { sendToWebClient } from './ws-utils.js';
 import { markAgentHeartbeatPing, markAgentHeartbeatStall, shouldTerminateAgentHeartbeat } from './heartbeat-policy.js';
+import { createSandboxReconciler } from './sandbox-reconciler.js';
+import {
+  closeSandboxAttestationListener,
+  startSandboxAttestationListener
+} from './sandbox-attestation-listener.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -62,6 +67,7 @@ const wss = new WebSocketServer({
 // =====================
 const AGENT_HEARTBEAT_INTERVAL = 30000;
 const CLIENT_HEARTBEAT_INTERVAL = 90000;
+const ACCOUNT_DELETION_RECONCILE_INTERVAL = 5000;
 
 let lastAgentHeartbeatTickAt = Date.now();
 setInterval(() => {
@@ -221,13 +227,57 @@ if (configValidation.warnings) {
   console.warn('');
 }
 
-server.listen(CONFIG.port, CONFIG.host, () => {
+let sandboxReconcileTimer = null;
+let sandboxAttestationListener = null;
+const accountDeletionTimer = setInterval(() => {
+  try {
+    userDb.reconcilePendingDeletions();
+  } catch (error) {
+    console.error('[AccountDeletion] Reconcile failed:', error.message);
+  }
+}, ACCOUNT_DELETION_RECONCILE_INTERVAL);
+accountDeletionTimer.unref?.();
+userDb.reconcilePendingDeletions();
+
+async function startServers() {
+  sandboxAttestationListener = await startSandboxAttestationListener({ config: CONFIG.sandbox });
+  if (sandboxAttestationListener) {
+    console.log(`Sandbox Host attestation listener running on https://${CONFIG.sandbox.hostAttestationListenerHost}:${CONFIG.sandbox.hostAttestationListenerPort}`);
+  }
+
+  try {
+    await new Promise((resolve, reject) => {
+      const onError = (err) => {
+        server.off('listening', onListening);
+        reject(err);
+      };
+      const onListening = () => {
+        server.off('error', onError);
+        resolve();
+      };
+      server.once('error', onError);
+      server.once('listening', onListening);
+      server.listen(CONFIG.port, CONFIG.host);
+    });
+  } catch (err) {
+    await closeSandboxAttestationListener(sandboxAttestationListener);
+    sandboxAttestationListener = null;
+    throw err;
+  }
+
+  sandboxReconcileTimer = createSandboxReconciler({ config: CONFIG.sandbox }).start();
   console.log(`Server running on http://${CONFIG.host || '0.0.0.0'}:${CONFIG.port}`);
   console.log(`Auth mode: ${CONFIG.skipAuth ? 'SKIP (development)' : 'ENABLED'}`);
   if (!CONFIG.skipAuth) {
     console.log(`Users configured: ${CONFIG.users.length}`);
     console.log(`Email verification: ${isEmailConfigured() ? 'ENABLED' : 'DISABLED'}`);
   }
+}
+
+startServers().catch(err => {
+  console.error('[Startup] Failed to start server:', err);
+  if (sandboxReconcileTimer) clearInterval(sandboxReconcileTimer);
+  process.exit(1);
 });
 
 // =====================
@@ -235,6 +285,14 @@ server.listen(CONFIG.port, CONFIG.host, () => {
 // =====================
 async function gracefulShutdown(signal) {
   console.log(`\n[Shutdown] Received ${signal}, starting graceful shutdown...`);
+  if (sandboxReconcileTimer) clearInterval(sandboxReconcileTimer);
+  clearInterval(accountDeletionTimer);
+  try {
+    await closeSandboxAttestationListener(sandboxAttestationListener);
+    if (sandboxAttestationListener) console.log('[Shutdown] Sandbox attestation listener closed');
+  } catch (err) {
+    console.error('[Shutdown] Failed to close Sandbox attestation listener:', err.message);
+  }
 
   // 1. 通知所有 web client 服务即将更新
   const updateMsg = { type: 'server_updating' };

package/local-runtime/server/routes/sandbox-routes.js

@@ -0,0 +1,124 @@
+import { timingSafeEqual } from 'crypto';
+import { CONFIG } from '../config.js';
+import { sandboxDb, userDb } from '../database.js';
+import { SandboxConflictError } from '../db/sandbox-db.js';
+import {
+  registerSandboxHostAttestation,
+  SandboxHostAttestationError
+} from '../sandbox-host-attestation.js';
+
+function loadUser(req) {
+  let user = userDb.getByUsername(req.user.username);
+  if (!user && CONFIG.skipAuth) user = userDb.getOrCreate(req.user.username, req.user.username);
+  return user;
+}
+
+function sendError(res, err) {
+  if (err instanceof SandboxConflictError) {
+    return res.status(409).json({ code: err.code });
+  }
+  console.error('Sandbox API error:', err);
+  return res.status(500).json({ code: 'SANDBOX_INTERNAL_ERROR' });
+}
+
+function normalizedFingerprint(value) {
+  return String(value || '').replaceAll(':', '').trim().toLowerCase();
+}
+
+export function authenticateSandboxController(request, expectedFingerprint) {
+  if (!request?.socket?.authorized) return false;
+  const expected = Buffer.from(normalizedFingerprint(expectedFingerprint));
+  const certificate = request.socket.getPeerCertificate?.();
+  const actual = Buffer.from(normalizedFingerprint(certificate?.fingerprint256));
+  return expected.length > 0 && expected.length === actual.length
+    && timingSafeEqual(expected, actual);
+}
+
+export function handleSandboxHostAttestation(req, res, config = CONFIG.sandbox) {
+  if (!authenticateSandboxController(req, config.controllerAttestationFingerprint)) {
+    return res.status(401).json({ code: 'SANDBOX_CONTROLLER_IDENTITY_REJECTED' });
+  }
+  try {
+    registerSandboxHostAttestation(req.body, config);
+    return res.status(202).json({ accepted: true });
+  } catch (err) {
+    if (err instanceof SandboxHostAttestationError) {
+      return res.status(401).json({ code: 'SANDBOX_HOST_ATTESTATION_REJECTED' });
+    }
+    return sendError(res, err);
+  }
+}
+
+export function registerSandboxRoutes(app, { requireAuth, requireAdmin }) {
+  // The managed runtime has no user Agent secret. Its one-time bootstrap token
+  // is itself the scoped authorization for obtaining a revocable credential.
+  app.post('/api/sandbox/bootstrap/exchange', (req, res) => {
+    try {
+      const result = sandboxDb.exchangeBootstrap(req.body?.token, req.body?.claims);
+      return res.json(result);
+    } catch (err) {
+      if (err instanceof SandboxConflictError) {
+        return res.status(401).json({ code: 'SANDBOX_BOOTSTRAP_INVALID' });
+      }
+      return sendError(res, err);
+    }
+  });
+
+  app.put('/api/admin/sandbox/entitlements/:userId', requireAuth, requireAdmin, (req, res) => {
+    try {
+      const entitlement = sandboxDb.setEntitlement(
+        req.params.userId,
+        req.body?.enabled,
+        req.user?.username
+      );
+      return res.json({ entitlement });
+    } catch (err) {
+      if (err instanceof SandboxConflictError && err.code === 'SANDBOX_USER_NOT_FOUND') {
+        return res.status(404).json({ code: err.code });
+      }
+      return sendError(res, err);
+    }
+  });
+
+  app.get('/api/sandbox/capability', requireAuth, (req, res) => {
+    const user = loadUser(req);
+    if (!user) return res.status(404).json({ code: 'USER_NOT_FOUND' });
+    res.json(sandboxDb.capability(user.id, CONFIG.sandbox));
+  });
+
+  app.get('/api/sandbox', requireAuth, (req, res) => {
+    const user = loadUser(req);
+    if (!user) return res.status(404).json({ code: 'USER_NOT_FOUND' });
+    res.json({ sandbox: sandboxDb.snapshot(user.id) });
+  });
+
+  app.post('/api/sandbox', requireAuth, (req, res) => {
+    const user = loadUser(req);
+    if (!user) return res.status(404).json({ code: 'USER_NOT_FOUND' });
+    try {
+      const result = sandboxDb.create(user.id, {
+        agentName: req.body?.agentName,
+        sizeId: req.body?.sizeId,
+        idempotencyKey: req.get('Idempotency-Key')
+      }, CONFIG.sandbox);
+      return res.status(result.replayed ? 200 : 202).json(result);
+    } catch (err) {
+      return sendError(res, err);
+    }
+  });
+
+  for (const action of ['start', 'stop', 'retry', 'remove']) {
+    app.post(`/api/sandbox/${action}`, requireAuth, (req, res) => {
+      const user = loadUser(req);
+      if (!user) return res.status(404).json({ code: 'USER_NOT_FOUND' });
+      try {
+        const result = sandboxDb.requestAction(
+          user.id, action, req.get('Idempotency-Key'), CONFIG.sandbox
+        );
+        return res.status(result.replayed ? 200 : 202).json(result);
+      } catch (err) {
+        return sendError(res, err);
+      }
+    });
+  }
+}

package/local-runtime/server/routes/user-routes.js

@@ -1,7 +1,12 @@
 import { CONFIG } from '../config.js';
 import { hashPassword } from '../auth.js';
 import { userDb, sessionDb } from '../database.js';
-import { activeSessions, revokedTokens } from '../auth/session-store.js';
+import {
+  activeSessions, pendingVerifications, pendingTotpVerifications, pendingTotpSetup,
+  revokedTokens
+} from '../auth/session-store.js';
+import { clearSessionCookie } from '../auth/request-auth.js';
+import { agents, webClients, userStatsDeltas } from '../context.js';
 
 // 过滤用户敏感字段
 function sanitizeUser(user) {
@@ -149,21 +154,31 @@ export function registerUserRoutes(app, { requireAuth, requireAdmin }) {
         }
       }
 
-      const removed = userDb.deleteUser(user.id);
-      if (!removed) return res.status(404).json({ error: 'User not found or already deleted' });
-
-      // Best-effort: revoke every active JWT belonging to this user so any
-      // open tabs can't keep talking to the API.
-      try {
-        for (const [token, info] of activeSessions.entries()) {
-          if (info && info.username === user.username) {
-            activeSessions.delete(token);
-            revokedTokens.add(token);
-          }
-        }
-      } catch {}
+      const deletion = userDb.beginDeletion(user.id);
+      if (!deletion) return res.status(404).json({ error: 'User not found or already deleted' });
 
-      res.json({ success: true });
+      // Durable eligibility is enforced from the user row. These sweeps close
+      // already-open channels immediately rather than waiting for their next use.
+      for (const [token, info] of activeSessions.entries()) {
+        if (info?.username === user.username) {
+          activeSessions.delete(token);
+          revokedTokens.add(token);
+        }
+      }
+      for (const pending of [pendingVerifications, pendingTotpVerifications, pendingTotpSetup]) {
+        for (const [token, info] of pending) {
+          if (info?.username === user.username) pending.delete(token);
+        }
+      }
+      for (const [, client] of webClients) {
+        if (client.userId === user.id) client.ws.close(1008, 'Account disabled');
+      }
+      for (const [, agent] of agents) {
+        if (agent.ownerId === user.id) agent.ws.close(1008, 'Account disabled');
+      }
+      userStatsDeltas.delete(user.id);
+      clearSessionCookie(req, res);
+      res.status(202).json(deletion);
     } catch (err) {
       console.error('Delete user error:', err);
       res.status(500).json({ error: 'Failed to delete account' });

package/local-runtime/server/sandbox-agent-auth.js

@@ -0,0 +1,66 @@
+import { sandboxDb } from './database.js';
+import { agents } from './context.js';
+
+function readClaims(message) {
+  const claims = message?.sandboxClaims;
+  if (!claims || typeof claims !== 'object') return null;
+  if (typeof claims.sandboxId !== 'string' || typeof claims.instanceId !== 'string'
+    || !Number.isInteger(claims.generation) || typeof claims.imageDigest !== 'string') {
+    return null;
+  }
+  return claims;
+}
+
+/**
+ * Authenticate a managed Sandbox Agent without accepting the user's general
+ * Agent secret. URL identity and credential scope must describe the same
+ * immutable Sandbox instance.
+ */
+export function authenticateSandboxAgent(message, pending, store = sandboxDb) {
+  if (message?.authKind !== 'sandbox' || typeof message.credentialId !== 'string'
+    || typeof message.secret !== 'string') {
+    return null;
+  }
+  const claims = readClaims(message);
+  if (!claims || pending.instanceId !== claims.instanceId || pending.agentId !== claims.sandboxId) {
+    return null;
+  }
+  try {
+    const authenticated = store.authenticateCredential(message.credentialId, message.secret, claims);
+    if (authenticated.sandboxId !== claims.sandboxId) return null;
+    return {
+      ...authenticated,
+      instanceId: claims.instanceId,
+      generation: claims.generation,
+      imageDigest: claims.imageDigest,
+      sessionKey: message.secret
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve readiness from the authenticated managed Agent connection. Controller
+ * booleans are inspection evidence, but cannot prove that the scoped Agent has
+ * completed its end-to-end Server sync.
+ */
+export function canForceReadyAfterSyncTimeout(agent) {
+  return !agent?.sandboxIdentity;
+}
+
+export function isSandboxAgentReady(identity, connectedAgents = agents) {
+  if (!identity) return false;
+  for (const agent of connectedAgents.values()) {
+    const current = agent.sandboxIdentity;
+    if (agent.status === 'ready' && agent.isAlive && current
+      && current.sandboxId === identity.sandboxId
+      && agent.instanceId === identity.instanceId
+      && current.generation === identity.generation
+      && current.imageDigest === identity.imageDigest
+      && agent.capabilities?.includes('managed-sandbox')) {
+      return true;
+    }
+  }
+  return false;
+}

package/local-runtime/server/sandbox-attestation-listener.js

@@ -0,0 +1,128 @@
+import express from 'express';
+import { createServer } from 'https';
+import { CONFIG } from './config.js';
+import {
+  authenticateSandboxController,
+  handleSandboxHostAttestation
+} from './routes/sandbox-routes.js';
+
+export const SANDBOX_HOST_ATTESTATION_PATH = '/api/sandbox/hosts/attest';
+
+function authenticatePeer(req, res, next, config) {
+  if (!authenticateSandboxController(req, config.controllerAttestationFingerprint)) {
+    return res.status(401).json({ code: 'SANDBOX_CONTROLLER_IDENTITY_REJECTED' });
+  }
+  return next();
+}
+
+function parseStrictJson(req, res, next) {
+  try {
+    const body = JSON.parse(req.body.toString('utf8'));
+    if (!body || typeof body !== 'object') {
+      return res.status(400).json({ code: 'SANDBOX_ATTESTATION_BODY_INVALID' });
+    }
+    req.body = body;
+    return next();
+  } catch {
+    return res.status(400).json({ code: 'SANDBOX_ATTESTATION_BODY_INVALID' });
+  }
+}
+
+function bodyErrorHandler(err, req, res, next) {
+  if (!err) return next();
+  if (err.type === 'entity.too.large') {
+    return res.status(413).json({ code: 'SANDBOX_ATTESTATION_BODY_TOO_LARGE' });
+  }
+  return next(err);
+}
+
+/**
+ * Create the dedicated HTTPS server used only for Controller Host attestation.
+ * TLS chain authorization occurs before Express, while the route also pins the
+ * leaf certificate fingerprint before consuming the signed payload.
+ *
+ * @param {{ config?: object, handler?: Function }} options
+ * @returns {import('https').Server}
+ */
+export function createSandboxAttestationListener({
+  config = CONFIG.sandbox,
+  handler = handleSandboxHostAttestation
+} = {}) {
+  const app = express();
+  app.disable('x-powered-by');
+
+  app.post(
+    SANDBOX_HOST_ATTESTATION_PATH,
+    (req, res, next) => authenticatePeer(req, res, next, config),
+    express.raw({ limit: config.hostAttestationBodyLimitBytes, type: () => true }),
+    parseStrictJson,
+    (req, res) => handler(req, res, config)
+  );
+  app.use(bodyErrorHandler);
+
+  const listener = createServer({
+    cert: config.hostAttestationServerCert,
+    key: config.hostAttestationServerKey,
+    ca: config.hostAttestationClientCa,
+    requestCert: true,
+    rejectUnauthorized: true,
+    minVersion: 'TLSv1.2'
+  }, app);
+  const sockets = new Set();
+  listener.on('connection', socket => {
+    sockets.add(socket);
+    socket.once('close', () => sockets.delete(socket));
+  });
+  listener.sandboxAttestationSockets = sockets;
+  listener.sandboxAttestationShutdownTimeoutMs = config.hostAttestationShutdownTimeoutMs;
+  return listener;
+}
+
+/**
+ * Start the attestation listener when Managed Sandbox is enabled.
+ * @param {{ config?: object, handler?: Function }} options
+ * @returns {Promise<import('https').Server|null>}
+ */
+export async function startSandboxAttestationListener({
+  config = CONFIG.sandbox,
+  handler = handleSandboxHostAttestation
+} = {}) {
+  if (!config.enabled) return null;
+  const listener = createSandboxAttestationListener({ config, handler });
+  await new Promise((resolve, reject) => {
+    const onError = (err) => {
+      listener.off('listening', onListening);
+      reject(err);
+    };
+    const onListening = () => {
+      listener.off('error', onError);
+      resolve();
+    };
+    listener.once('error', onError);
+    listener.once('listening', onListening);
+    listener.listen(config.hostAttestationListenerPort, config.hostAttestationListenerHost);
+  });
+  return listener;
+}
+
+export async function closeSandboxAttestationListener(listener) {
+  if (!listener) return;
+  const sockets = listener.sandboxAttestationSockets || new Set();
+  const timeoutMs = listener.sandboxAttestationShutdownTimeoutMs || 1_000;
+  await new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = err => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (err && err.code !== 'ERR_SERVER_NOT_RUNNING') reject(err);
+      else resolve();
+    };
+    const timer = setTimeout(() => {
+      for (const socket of sockets) socket.destroy();
+    }, timeoutMs);
+    timer.unref?.();
+    listener.close(finish);
+    listener.closeIdleConnections?.();
+  });
+}