@dmsdc-ai/aigentry-telepty 0.5.8 → 0.6.0

package/daemon.js

@@ -2,6 +2,7 @@ const express = require('express');
 const cors = require('cors');
 const pty = require('node-pty');
 const os = require('os');
+const path = require('path');
 const crypto = require('crypto');
 const { getConfig } = require('./auth');
 const pkg = require('./package.json');
@@ -22,6 +23,7 @@ const lifecycle = require('./src/lifecycle');
 const { SURFACE_ORPHAN_SECONDS, SURFACE_MISMATCH_SECONDS, decideSurfaceGc, applySurfaceMismatchProbe } = lifecycle;
 const { loadTeleptyConfig } = require('./src/config-file');
 const sessionPersistence = require('./src/session-store/persistence');
+const { createAuditWriter, readInjectLog } = require('./src/audit/inject-log');
 
 const config = getConfig();
 const EXPECTED_TOKEN = config.authToken;
@@ -134,6 +136,18 @@ function loadPersistedSessions() {
 
 const app = express();
 app.use(cors());
+
+// #42 broker MVP (W3/T5) — broker-mode HTTP surface (spec §2F, §5). DEFAULT-OFF:
+// only when TELEPTY_BROKER_MODE is set does the daemon mount the broker-server at
+// /broker/*. Mounted BEFORE express.json so the broker reads the raw request stream
+// itself (it has its own per-node JWT gate); the existing /api/* auth path is untouched.
+// Fail-fast (loud throw) if a required broker env is missing. The HTTPS listener that
+// serves this handler is created in the boot block below (TLS mandatory, §4.4).
+let brokerServer = null;
+if (brokerEnv().mode) {
+  brokerServer = mountBrokerMode(app);
+}
+
 app.use(express.json());
 
 // Peer allowlist: comma-separated IPs/CIDRs in TELEPTY_PEER_ALLOWLIST env
@@ -146,6 +160,67 @@ const PEER_ALLOWLIST = (process.env.TELEPTY_PEER_ALLOWLIST || '').split(',').map
 const ORCHESTRATOR_SIDS = (process.env.AIGENTRY_ORCHESTRATOR_SIDS || 'orchestrator aigentry-orchestrator-claude')
   .split(/\s+/).map(s => s.trim()).filter(Boolean);
 
+// #45 — defense-in-depth blast-radius cap for operator-lane fan-out (broadcast/
+// multicast). Even legitimate operator fan-out is bounded so a single compromised
+// fan-out call cannot hit an unbounded number of sessions in one hop. Generous
+// default (operator broadcasts hit only the live mesh); tune via env.
+const FANOUT_MAX_TARGETS = Math.max(1, Number(process.env.TELEPTY_FANOUT_MAX_TARGETS || 100));
+
+// #43 — inject audit spine (spec §5/§8). One JSONL line per delivery into
+// ~/.telepty/logs/injects.jsonl (0600). Defaults locked (hash-only preview, 30d / 50MB × 5);
+// env-overridable. The writer is off the delivery hot path: auditAppend() never blocks or
+// throws into a handler. P1 records claimed_from only (verified_sender_sid wired in P2).
+const AUDIT_LOG_PATH = path.join(os.homedir(), '.telepty', 'logs', 'injects.jsonl');
+const auditWriter = createAuditWriter({
+  path: AUDIT_LOG_PATH,
+  preview: process.env.TELEPTY_AUDIT_PREVIEW === '1',
+  previewBytes: Number(process.env.TELEPTY_AUDIT_PREVIEW_BYTES) || 200,
+  flushMs: Number(process.env.TELEPTY_AUDIT_FLUSH_MS) || 250,
+  queueMax: Number(process.env.TELEPTY_AUDIT_QUEUE_MAX) || 10000,
+  maxBytes: Number(process.env.TELEPTY_AUDIT_MAX_BYTES) || 50 * 1024 * 1024,
+  maxFiles: Number(process.env.TELEPTY_AUDIT_MAX_FILES) || 5,
+  maxAgeDays: Number(process.env.TELEPTY_AUDIT_MAX_AGE_DAYS) || 30
+});
+// Overflow is visible, never silent: surface a single bus event per drop (spec §8 T4).
+auditWriter.on('audit_overflow', (info) => {
+  try {
+    broadcastBusEvent({ type: 'audit_overflow', sender: 'daemon', dropped: info.dropped, queue_max: info.queueMax, timestamp: new Date().toISOString() });
+  } catch { /* bus best-effort */ }
+});
+auditWriter.on('audit_error', (err) => {
+  console.warn(`[AUDIT] write error: ${err && err.message ? err.message : err}`);
+});
+// Fire-and-forget append — swallow any sync error so the audit log can never break delivery.
+function auditAppend(record) {
+  try { auditWriter.append(record); } catch { /* audit must never throw into a handler */ }
+}
+
+// #43 P2 — per-session verified-sender tokens (spec §4, ADR D1). The daemon mints a random
+// token at /api/sessions/register and maps token→sid; the `allow` wrapper carries it in the
+// parent-hijack-protected env beside TELEPTY_SESSION_ID; `inject` presents x-telepty-session-token.
+// `verified_sender_sid` = the mapped sid (the daemon's own truth) or null when unverifiable.
+// Issuance is idempotent per sid so the periodic metadata re-register (cli.js
+// updateDaemonProcessMetadata) does NOT rotate the token out from under the carried env.
+const sessionTokens = new Map(); // token → sid
+const sidTokens = new Map();     // sid → token
+function mintSessionToken(sid) {
+  const existing = sidTokens.get(sid);
+  if (existing) return existing;
+  const token = crypto.randomBytes(32).toString('base64url');
+  sessionTokens.set(token, sid);
+  sidTokens.set(sid, token);
+  return token;
+}
+function resolveVerifiedSender(token) {
+  if (!token) return null;
+  return sessionTokens.get(token) || null;
+}
+// Extract the presented session token from an inject request (header only — never the body,
+// which is attacker-controlled). Returns the daemon-verified sid or null.
+function verifiedSenderFromReq(req) {
+  return resolveVerifiedSender(req.headers && req.headers['x-telepty-session-token']);
+}
+
 // Cross-machine bus relay: forward bus events to peer daemons
 const relayToPeers = createPeerRelay({
   relayPeers: relayPeersFromEnv(process.env),
@@ -681,9 +756,15 @@ async function executeBootstrapInject(sessionId, session, op) {
 
 function parseSubmitRetryOptions(body = {}, injectedBody = null) {
   const hasExplicitRetries = body && body.retries !== undefined && body.retries !== null;
-  const retries = Math.min(Math.max(Number(hasExplicitRetries ? body.retries : (injectedBody ? 1 : 0)) || 0, 0), 3);
-  const retryDelayMs = Math.min(Math.max(Number(body?.retry_delay_ms) || 500, 100), 2000);
-  const verifyTimeoutMs = Math.min(Math.max(Number(body?.verify_timeout_ms) || 1500, 200), 5000);
+  // #568: raise the retry-budget ceiling so a momentarily-busy CLI still gets a
+  // render-gated CR before we return 504 (each retry re-gates on input-ready, so
+  // more attempts = more quiet-window chances to land). Ceilings only — the
+  // default stays 1 for the injected case (behavior-preserving common path);
+  // heavier callers opt into the bigger budget via retries/retry_delay_ms/
+  // verify_timeout_ms. Total worst-case budget stays bounded (~10 attempts).
+  const retries = Math.min(Math.max(Number(hasExplicitRetries ? body.retries : (injectedBody ? 1 : 0)) || 0, 0), 10);
+  const retryDelayMs = Math.min(Math.max(Number(body?.retry_delay_ms) || 500, 100), 3000);
+  const verifyTimeoutMs = Math.min(Math.max(Number(body?.verify_timeout_ms) || 1500, 200), 8000);
   return { retries, retryDelayMs, verifyTimeoutMs };
 }
 
@@ -716,6 +797,29 @@ async function confirmSubmitAfterDispatch(id, session, injectedBody, submittedAt
   return submitGate.confirmSubmitAccepted(session, injectedBody, buildSubmitConfirmOptions(id, session, submittedAtMs, verifyTimeoutMs));
 }
 
+// #568 — render-gate the submit CR. Before writing the bare 0x0D, wait (bounded)
+// until the injected body is echoed in the PTY outputRing AND the render has gone
+// quiet, so the CR does not land mid-render and get dropped (FM1; same gate before
+// each retry CR, FM2). Best-effort + bounded: on timeout / no body / no ring we
+// fall through and still write the CR — never worse than the pre-gate behavior.
+// pty_cr stays the ONLY write path (terminalLevelSubmit); this only times WHEN.
+// Per-request opt-out via `input_settle_gate: false` (rollback/parity escape hatch).
+async function gatedTerminalSubmit(id, session, injectedBody, settleEnabled) {
+  if (injectedBody && injectedBody.length > 0 && settleEnabled !== false) {
+    const settle = await submitGate.awaitInputSettled(session, injectedBody, {
+      timeoutMs: 1200,
+      quietWindowMs: 100,
+      echoGraceMs: 400,
+      pollIntervalMs: 30,
+      stripAnsi: stripAnsiState,
+    });
+    if (!settle.ready) {
+      console.log(`[SUBMIT] input-settle gate timed out for ${id} (${settle.waited_ms}ms, echoed=${settle.echoed}) — sending CR best-effort`);
+    }
+  }
+  return terminalLevelSubmit(id, session);
+}
+
 async function executeBootstrapSubmit(sessionId, session, op) {
   const body = op.body || {};
   const injectedBody = typeof body.injected_body === 'string' ? body.injected_body : null;
@@ -724,8 +828,9 @@ async function executeBootstrapSubmit(sessionId, session, op) {
     markPendingReportSubmitStarted(sessionId, injectedBody);
   }
 
+  const settleEnabled = body.input_settle_gate !== false;
+  let strategy = await gatedTerminalSubmit(sessionId, session, injectedBody, settleEnabled);
   const submittedAtMs = Date.now();
-  let strategy = terminalLevelSubmit(sessionId, session);
   if (!strategy) {
     if (injectedBody) {
       markPendingReportSubmitUnconfirmed(sessionId, { reason: 'strategy_failed', attempts: 0, retryable: false });
@@ -745,8 +850,8 @@ async function executeBootstrapSubmit(sessionId, session, op) {
   let confirm = await confirmSubmitAfterDispatch(sessionId, session, injectedBody, submittedAtMs, verifyTimeoutMs);
   while (confirm && !confirm.accepted && confirm.retryable && attempts <= retries) {
     await sleep(retryDelayMs);
+    const retryStrategy = await gatedTerminalSubmit(sessionId, session, injectedBody, settleEnabled);
     const retrySubmittedAtMs = Date.now();
-    const retryStrategy = terminalLevelSubmit(sessionId, session);
     if (!retryStrategy) break;
     strategy = retryStrategy;
     attempts++;
@@ -1776,7 +1881,7 @@ app.post('/api/sessions/register', (req, res) => {
     applyTimestampMetadata(existing, req.body);
     initializeBootstrapState(existing);
     console.log(`[REGISTER] Re-registered session ${session_id} (type: ${existing.type}, updated metadata)`);
-    return res.status(200).json({ session_id, type: existing.type, command: existing.command, cwd: existing.cwd, reregistered: true });
+    return res.status(200).json({ session_id, type: existing.type, command: existing.command, cwd: existing.cwd, reregistered: true, session_token: mintSessionToken(session_id) });
   }
 
   const { delivery_type, delivery_endpoint, delivery } = req.body;
@@ -1849,7 +1954,7 @@ app.post('/api/sessions/register', (req, res) => {
 
   console.log(`[REGISTER] Registered wrapped session ${session_id}`);
   persistSessions();
-  res.status(201).json({ session_id, type: 'wrapped', command: sessionRecord.command, cwd });
+  res.status(201).json({ session_id, type: 'wrapped', command: sessionRecord.command, cwd, session_token: mintSessionToken(session_id) });
 });
 
 app.get('/api/sessions', (req, res) => {
@@ -1862,6 +1967,27 @@ app.get('/api/sessions', (req, res) => {
   res.json(list);
 });
 
+// #43 P3 — token-gated historical inject audit query (spec §7). Behind the SAME shared auth
+// middleware as every /api/* route (app.use(createAuthMiddleware) above), so it is 401 for an
+// unauthorized non-local request and open to localhost/allowlisted peers. Filters: since/until,
+// to (alias-resolved), from (claimed OR verified), spoof; pagination via limit/cursor (newest
+// first). Reads the live injects.jsonl (one write path, file-backed) — separate lifecycle from
+// the ephemeral /api/events live bus, so the two are not conflated.
+app.get('/api/injects', (req, res) => {
+  const q = req.query || {};
+  const to = q.to ? (resolveSessionAlias(q.to) || q.to) : undefined;
+  const result = readInjectLog(AUDIT_LOG_PATH, {
+    since: q.since,
+    until: q.until,
+    to,
+    from: q.from,
+    spoof: q.spoof === '1' || q.spoof === 'true',
+    limit: q.limit,
+    cursor: q.cursor
+  });
+  res.json(result);
+});
+
 app.get('/api/sessions/:id', (req, res) => {
   const requestedId = req.params.id;
   const resolvedId = resolveSessionAlias(requestedId);
@@ -1991,12 +2117,66 @@ app.get('/api/peers', (req, res) => {
   }
 });
 
+// #45 — fan-out (broadcast/multicast) is OPERATOR/ORCHESTRATOR-ONLY. The single-inject
+// path hard-blocks off-policy peer→peer traffic via classifyPeerLaneInject; fan-out
+// one→many is strictly more dangerous (a worm/fan-out primitive), so the peer lane is
+// blocked OUTRIGHT here — even a sanctioned ask-envelope may not fan out. We reuse the
+// SAME classifier (DRY, no second policy) and gate on the LANE, not the per-target
+// decision: classify by SENDER (`to: null`) so the verdict is the sender's lane,
+// independent of any individual target. This is what makes broadcast all-or-nothing on
+// the lane — a peer cannot earn fan-out rights by listing the orchestrator as one
+// target. Operator lane (no `from`, or `from` ∈ orchestrator sids) and the fail-open
+// `disabled` lane proceed to delivery, exactly as single-inject allows them. #533 Phase 2.
+function isPeerLaneFanout(from, prompt) {
+  return classifyPeerLaneInject({ from, to: null, prompt, orchestratorSids: ORCHESTRATOR_SIDS });
+}
+
+// Reject a peer-lane fan-out: emit a per-target peer_inject_blocked bus event for every
+// intended target (mirrors the single-inject block event for reporting parity) and return
+// the same 403 PEER_INJECT_BLOCKED shape, reaching ZERO sessions. `targetIds` is the full
+// intended target set (broadcast = all sessions, multicast = requested session_ids).
+function rejectPeerLaneFanout(res, { from, reason, targetIds, source }) {
+  const inject_id = crypto.randomUUID();
+  const failed = [];
+  for (const id of targetIds) {
+    broadcastSessionEvent('peer_inject_blocked', id, sessions[id] || null, {
+      extra: {
+        target_agent: id,
+        from: from || null,
+        reason,
+        source,
+        inject_id
+      }
+    });
+    failed.push({ id, code: 'PEER_INJECT_BLOCKED', error: 'Peer-lane fan-out blocked' });
+  }
+  console.warn(`[PEER-GUARD] blocked peer-lane ${source} from ${from || '(none)'} → ${targetIds.length} target(s) (${reason})`);
+  return respondWithError(res, 403, 'PEER_INJECT_BLOCKED',
+    'Peer-lane fan-out blocked: broadcast/multicast is operator-only. Use bin/ask.sh for peer→peer.',
+    { reason, sanctioned_channel: 'bin/ask.sh', results: { successful: [], failed } });
+}
+
 app.post('/api/sessions/multicast/inject', async (req, res) => {
-  const { session_ids, prompt } = req.body;
+  const { session_ids, prompt, from } = req.body;
   if (typeof prompt !== 'string' || prompt.length === 0) return respondWithError(res, 400, 'INVALID_REQUEST', 'prompt is required');
   if (!Array.isArray(session_ids)) return res.status(400).json({ error: 'session_ids must be an array' });
 
+  // #45 — operator-only fan-out gate (peer lane blocked outright, before any delivery).
+  const verdict = isPeerLaneFanout(from, prompt);
+  if (verdict.lane === 'peer') {
+    return rejectPeerLaneFanout(res, { from, reason: verdict.reason, targetIds: session_ids, source: 'multicast' });
+  }
+  // #45 — defense-in-depth blast-radius cap (operator lane too).
+  if (session_ids.length > FANOUT_MAX_TARGETS) {
+    return respondWithError(res, 429, 'FANOUT_TARGET_CAP',
+      `multicast target count ${session_ids.length} exceeds cap ${FANOUT_MAX_TARGETS}`,
+      { cap: FANOUT_MAX_TARGETS, requested: session_ids.length });
+  }
+
   const results = { successful: [], failed: [] };
+  // #43 — one inject_id for the whole fan-out; one audit line per target (group by inject_id).
+  const inject_id = crypto.randomUUID();
+  const verifiedSenderSid = verifiedSenderFromReq(req);
 
   for (const id of session_ids) {
     const session = sessions[id];
@@ -2007,10 +2187,12 @@ app.post('/api/sessions/multicast/inject', async (req, res) => {
         });
         if (!delivery.success) {
           results.failed.push({ id, code: delivery.code, error: delivery.error });
+          auditMulticastTarget(inject_id, 'multicast', from, verifiedSenderSid, id, prompt, `failed:${delivery.code || 'DELIVERY_FAILED'}`);
           continue;
         }
 
         results.successful.push({ id, strategy: delivery.strategy });
+        auditMulticastTarget(inject_id, 'multicast', from, verifiedSenderSid, id, prompt, 'success');
 
         // Broadcast injection to bus
         broadcastBusEvent({
@@ -2022,22 +2204,52 @@ app.post('/api/sessions/multicast/inject', async (req, res) => {
         });
       } catch (err) {
         results.failed.push({ id, code: 'DELIVERY_FAILED', error: err.message });
+        auditMulticastTarget(inject_id, 'multicast', from, verifiedSenderSid, id, prompt, 'failed:DELIVERY_FAILED');
       }
     } else {
       results.failed.push({ id, code: 'SESSION_NOT_FOUND', error: 'Session not found' });
+      auditMulticastTarget(inject_id, 'multicast', from, verifiedSenderSid, id, prompt, 'failed:SESSION_NOT_FOUND');
     }
   }
 
   res.json({ success: true, results });
 });
 
+// #43 — shared per-target audit helper for the fan-out handlers (multicast/broadcast). One
+// JSONL line per target so blast-radius is queryable per session; all share `inject_id`.
+function auditMulticastTarget(inject_id, kind, from, verifiedSenderSid, id, prompt, delivery_result) {
+  auditAppend({
+    ts: new Date().toISOString(), inject_id, kind, source: kind,
+    claimed_from: from || null, verified_sender_sid: verifiedSenderSid,
+    to: id, to_alias: null, origin: 'trusted-local', origin_host: MACHINE_ID,
+    payload: prompt, delivery_result
+  });
+}
+
 app.post('/api/sessions/broadcast/inject', async (req, res) => {
-  const { prompt } = req.body;
+  const { prompt, from } = req.body;
   if (typeof prompt !== 'string' || prompt.length === 0) return respondWithError(res, 400, 'INVALID_REQUEST', 'prompt is required');
 
+  // #45 — operator-only fan-out gate (peer lane blocked outright, before any delivery).
+  // Broadcast is all-or-nothing on the lane: a peer-lane sender reaches ZERO sessions.
+  const targetIds = Object.keys(sessions);
+  const verdict = isPeerLaneFanout(from, prompt);
+  if (verdict.lane === 'peer') {
+    return rejectPeerLaneFanout(res, { from, reason: verdict.reason, targetIds, source: 'broadcast' });
+  }
+  // #45 — defense-in-depth blast-radius cap (operator lane too).
+  if (targetIds.length > FANOUT_MAX_TARGETS) {
+    return respondWithError(res, 429, 'FANOUT_TARGET_CAP',
+      `broadcast target count ${targetIds.length} exceeds cap ${FANOUT_MAX_TARGETS}`,
+      { cap: FANOUT_MAX_TARGETS, requested: targetIds.length });
+  }
+
   const results = { successful: [], failed: [] };
+  // #43 — one inject_id for the whole broadcast; one audit line per target.
+  const inject_id = crypto.randomUUID();
+  const verifiedSenderSid = verifiedSenderFromReq(req);
 
-  for (const id of Object.keys(sessions)) {
+  for (const id of targetIds) {
     const session = sessions[id];
     try {
       const delivery = await deliverInjectionToSession(id, session, prompt, {
@@ -2045,12 +2257,15 @@ app.post('/api/sessions/broadcast/inject', async (req, res) => {
       });
       if (!delivery.success) {
         results.failed.push({ id, code: delivery.code, error: delivery.error });
+        auditMulticastTarget(inject_id, 'broadcast', from, verifiedSenderSid, id, prompt, `failed:${delivery.code || 'DELIVERY_FAILED'}`);
         continue;
       }
 
       results.successful.push({ id, strategy: delivery.strategy });
+      auditMulticastTarget(inject_id, 'broadcast', from, verifiedSenderSid, id, prompt, 'success');
     } catch (err) {
       results.failed.push({ id, code: 'DELIVERY_FAILED', error: err.message });
+      auditMulticastTarget(inject_id, 'broadcast', from, verifiedSenderSid, id, prompt, 'failed:DELIVERY_FAILED');
     }
   }
 
@@ -2391,12 +2606,13 @@ app.post('/api/sessions/:id/submit', async (req, res) => {
     console.log(`[SUBMIT] gate timeout ${id}: dispatching anyway (last_state=${gateResult.last_state})`);
   }
 
-  // Step 2: dispatch Enter via existing kitty → cmux → PTY chain.
+  // Step 2: dispatch Enter via the PTY/context path, render-gated (#568).
   if (injectedBody) {
     markPendingReportSubmitStarted(id, injectedBody);
   }
+  const settleEnabled = req.body?.input_settle_gate !== false;
+  let strategy = await gatedTerminalSubmit(id, session, injectedBody, settleEnabled);
   let submittedAtMs = Date.now();
-  let strategy = terminalLevelSubmit(id, session);
   let attempts = strategy ? 1 : 0;
   if (!strategy) {
     if (injectedBody) {
@@ -2422,8 +2638,8 @@ app.post('/api/sessions/:id/submit', async (req, res) => {
     confirm = await confirmSubmitAfterDispatch(id, session, injectedBody, submittedAtMs, verifyTimeoutMs);
     while (confirm && !confirm.accepted && confirm.retryable && attempts <= retries) {
       await new Promise(resolve => setTimeout(resolve, retryDelayMs));
+      const retryStrategy = await gatedTerminalSubmit(id, session, injectedBody, settleEnabled);
       submittedAtMs = Date.now();
-      const retryStrategy = terminalLevelSubmit(id, session);
       if (!retryStrategy) break;
       strategy = retryStrategy;
       attempts++;
@@ -2522,6 +2738,8 @@ app.post('/api/sessions/:id/inject', async (req, res) => {
   // Routing metadata stays in session/bus state, not in the visible prompt text.
   const finalPrompt = prompt;
   const inject_id = crypto.randomUUID();
+  // #43 P2 — daemon-verified sender identity (from the presented token, never body.from).
+  const verifiedSenderSid = verifiedSenderFromReq(req);
 
   // #533 Phase 2 — peer-lane inject guardrail (in-band hard block, before delivery).
   // Out-of-policy peer→peer injects (no sanctioned ask-request/ask-reply envelope)
@@ -2560,6 +2778,13 @@ app.post('/api/sessions/:id/inject', async (req, res) => {
         from: from || null,
         reply_to: reply_to || null
       }, session);
+      auditAppend({
+        ts: new Date().toISOString(), inject_id, kind: 'inject', source: 'inject',
+        claimed_from: from || null, verified_sender_sid: verifiedSenderSid,
+        to: id, to_alias: requestedId !== resolvedId ? requestedId : null,
+        origin: 'trusted-local', origin_host: MACHINE_ID, ref_path: req.body.ref_path || null,
+        payload: finalPrompt, delivery_result: `failed:${delivery.code || 'DELIVERY_FAILED'}`
+      });
       return respondWithError(res, delivery.httpStatus || 500, delivery.code || 'DELIVERY_FAILED', delivery.error);
     }
 
@@ -2570,6 +2795,14 @@ app.post('/api/sessions/:id/inject', async (req, res) => {
     console.log(`[INJECT] Wrote to session ${id} (inject_id: ${inject_id})`);
 
     const injectTimestamp = new Date().toISOString();
+    // #43 P1/P2 — one audit line per delivery (claimed + daemon-verified sender, hash-only).
+    auditAppend({
+      ts: injectTimestamp, inject_id, kind: 'inject', source: 'inject',
+      claimed_from: from || null, verified_sender_sid: verifiedSenderSid,
+      to: id, to_alias: requestedId !== resolvedId ? requestedId : null,
+      origin: 'trusted-local', origin_host: MACHINE_ID, ref_path: req.body.ref_path || null,
+      payload: finalPrompt, delivery_result: 'success'
+    });
     broadcastSessionEvent('inject_written', id, session, {
       timestamp: injectTimestamp,
       extra: {
@@ -2577,6 +2810,10 @@ app.post('/api/sessions/:id/inject', async (req, res) => {
         target_agent: id,
         content: prompt,
         from: from || null,
+        // #43 — live bus event enriched with daemon-verified provenance (spec §7).
+        verified_sender_sid: verifiedSenderSid,
+        spoof_suspected: !!(from && verifiedSenderSid && from !== verifiedSenderSid),
+        origin: 'trusted-local',
         reply_to: reply_to || null,
         thread_id: thread_id || null,
         reply_expected: !!reply_expected
@@ -3244,17 +3481,165 @@ app.patch('/api/threads/:id', (req, res) => {
   res.json({ success: true, thread_id: thread.id, status: thread.status });
 });
 
+// === #42 broker MVP (W3/T5) — broker wiring helpers (spec §2F, §4.3, §5) =========
+// Additive + default-OFF. Factored as DI-seamed helpers (deps override factories /
+// env / readFile) so the wiring is unit-testable without booting the daemon or
+// touching the network. The broker-server / broker-client factories are REUSED
+// verbatim — no reimplementation here.
+
+// Resolve broker config from the environment (all knobs default-OFF when absent).
+function brokerEnv(env = process.env) {
+  const home = os.homedir();
+  return {
+    mode: env.TELEPTY_BROKER_MODE === '1' || env.TELEPTY_BROKER_MODE === 'true',
+    jwtSecret: env.TELEPTY_JWT_SECRET || null,
+    enrollSecret: env.TELEPTY_ENROLL_SECRET || null,
+    tlsCert: env.TELEPTY_TLS_CERT || null,
+    tlsKey: env.TELEPTY_TLS_KEY || null,
+    aclPath: env.TELEPTY_BROKER_ACL || path.join(home, '.telepty', 'broker-acl.json'),
+    revokedPath: env.TELEPTY_BROKER_REVOKED || path.join(home, '.telepty', 'broker-revoked.json'),
+    configPath: env.TELEPTY_BROKER_CONFIG || path.join(home, '.telepty', 'broker.json'),
+    maxNodes: Number(env.TELEPTY_ENROLL_MAX_NODES) || 256,
+    url: env.TELEPTY_BROKER_URL || null,
+    jwt: env.TELEPTY_BROKER_JWT || null,
+    node: env.TELEPTY_BROKER_NODE || null,
+    pin: env.TELEPTY_BROKER_PIN || null,
+  };
+}
+
+function readJsonFileSafe(filePath, readFile = fs.readFileSync) {
+  try {
+    return JSON.parse(readFile(filePath, 'utf8'));
+  } catch {
+    return null; // missing/invalid file ⇒ default (caller decides)
+  }
+}
+
+// Broker host: mount createBrokerServer at /broker/* (spec §2F-i). Loads the ACL +
+// revocation tables from disk (the broker-server is pure — the daemon owns the file
+// I/O and the TLS listener, per the module contract). Fail-fast loud if a required
+// broker env is missing (§5). Returns the broker instance (handler/close).
+function mountBrokerMode(app, deps = {}) {
+  const env = deps.env || brokerEnv();
+  const createServer = deps.createBrokerServer
+    || require('./src/transport/broker-server').createBrokerServer;
+  const readFile = deps.readFile || fs.readFileSync;
+  const bus = deps.broadcastBusEvent || broadcastBusEvent;
+  const requireTls = deps.requireTls !== undefined ? deps.requireTls : true;
+
+  const missing = [];
+  if (!env.jwtSecret) missing.push('TELEPTY_JWT_SECRET');
+  if (!env.enrollSecret) missing.push('TELEPTY_ENROLL_SECRET');
+  if (!env.tlsCert) missing.push('TELEPTY_TLS_CERT');
+  if (!env.tlsKey) missing.push('TELEPTY_TLS_KEY');
+  if (missing.length) {
+    throw new Error(`[BROKER] broker mode requires env: ${missing.join(', ')}`);
+  }
+
+  const aclTable = readJsonFileSafe(env.aclPath, readFile) || {};
+  const revokedRaw = readJsonFileSafe(env.revokedPath, readFile);
+  const revokedNodes = new Set(
+    Array.isArray(revokedRaw) ? revokedRaw : (revokedRaw && revokedRaw.revoked) || []
+  );
+
+  const broker = createServer({
+    jwtSecret: env.jwtSecret,
+    enrollSecret: env.enrollSecret,
+    aclTable,
+    revokedNodes,
+    maxNodes: env.maxNodes,
+    requireTls,
+    broadcastBusEvent: bus,
+  });
+
+  // Mount the raw handler at /broker/* (full path preserved so the broker router
+  // matches, spec §3.0). Placed before express.json/auth by the call site above.
+  app.use((req, res, next) => {
+    if ((req.url || '').split('?')[0].startsWith('/broker/')) return broker.handler(req, res);
+    return next();
+  });
+  return broker;
+}
+
+// Node side: resolve broker connection config. Env (TELEPTY_BROKER_URL +
+// TELEPTY_BROKER_JWT) wins; else ~/.telepty/broker.json; else null (default-OFF).
+function loadNodeBrokerConfig(deps = {}) {
+  const env = deps.env || brokerEnv();
+  const readFile = deps.readFile || fs.readFileSync;
+  if (env.url && env.jwt) {
+    return { url: env.url, jwt: env.jwt, node: env.node || MACHINE_ID, pin: env.pin || null, accept_from: null };
+  }
+  const cfg = readJsonFileSafe(env.configPath, readFile);
+  if (cfg && cfg.url && cfg.jwt) {
+    return {
+      url: cfg.url,
+      jwt: cfg.jwt,
+      node: cfg.node || MACHINE_ID,
+      pin: cfg.pin || null,
+      accept_from: cfg.accept_from === undefined ? null : cfg.accept_from,
+    };
+  }
+  return null;
+}
+
+// Node side: start the broker-client when broker config is present (spec §2F-ii).
+// No config ⇒ returns null and starts nothing (§5 default-OFF, zero new behavior).
+// CREDENTIAL BOUNDARY (§4.3): delivery is in-process via deliverInjectionToSession —
+// the local daemon token (EXPECTED_TOKEN) is NEVER passed to the client / on the wire.
+function startNodeBrokerClient(deps = {}) {
+  const cfg = deps.config || loadNodeBrokerConfig(deps);
+  if (!cfg) return null;
+  const createClient = deps.createBrokerClient
+    || require('./src/transport/broker-client').createBrokerClient;
+  const deliver = deps.deliver || deliverInjectionToSession;
+  const sessionMap = deps.sessions || sessions;
+
+  const client = createClient({
+    url: cfg.url,
+    node: cfg.node || MACHINE_ID,
+    nodeJwt: cfg.jwt,
+    pin: cfg.pin || null,
+    acceptFrom: cfg.accept_from,
+    deliver, // in-process delivery — §4.3 (no daemon token on the wire)
+    getSession: (id) => sessionMap[id] || null,
+    getSessions: () => Object.keys(sessionMap).map((id) => ({ id, peerName: MACHINE_ID, host: MACHINE_ID })),
+  });
+
+  if (deps.autostart !== false && typeof client.start === 'function') {
+    Promise.resolve(client.start()).catch((err) => {
+      console.error(`[BROKER] node-mode client start failed: ${err && err.message ? err.message : err}`);
+    });
+  }
+  return client;
+}
+
 // Bind the port when launched as the daemon. A test can `require('./daemon.js')` to reach the
 // exported decision functions WITHOUT starting the daemon — it just must not set the env below.
 // The production CLI reaches daemon.js via require() (cli.js `cmd==='daemon'`), so require.main is
 // cli.js, never this module — hence the explicit AIGENTRY_TELEPTY_DAEMON_MAIN signal. Guarding on
 // require.main ALONE (0.5.0 regression) meant app.listen never ran in production → daemon exited 0.
 let server;
+let nodeBrokerClient = null;
 if (require.main === module || process.env.AIGENTRY_TELEPTY_DAEMON_MAIN === '1') {
-  server = app.listen(PORT, HOST, () => {
-    console.log(`🚀 aigentry-telepty daemon listening on http://${HOST}:${PORT}`);
-    runStartupBootstrapRestore();
-  });
+  if (brokerServer) {
+    // Broker mode (§4.4): TLS mandatory — serve the express app (with /broker/*
+    // mounted) over HTTPS using the configured self-signed cert/key.
+    const https = require('https');
+    const benv = brokerEnv();
+    const tlsOptions = { cert: fs.readFileSync(benv.tlsCert), key: fs.readFileSync(benv.tlsKey) };
+    server = https.createServer(tlsOptions, app).listen(PORT, HOST, () => {
+      console.log(`🔐 aigentry-telepty broker listening on https://${HOST}:${PORT} (/broker/*)`);
+      runStartupBootstrapRestore();
+    });
+  } else {
+    server = app.listen(PORT, HOST, () => {
+      console.log(`🚀 aigentry-telepty daemon listening on http://${HOST}:${PORT}`);
+      runStartupBootstrapRestore();
+      // #42 node-mode (§2F-ii): start the broker-client if broker config is present.
+      // Absent ⇒ no-op (default-OFF). Started after listen so sessions/delivery are live.
+      nodeBrokerClient = startNodeBrokerClient();
+    });
+  }
 }
 
 // #470 (0.4.5): when the daemon restarts under existing telepty allow workers,
@@ -3589,6 +3974,13 @@ installWebSocketTransport({
 function shutdown(code) {
   mailboxDelivery.stop();
   mailboxNotifier.cancelAll();
+  // #42: stop the node-mode broker-client (closes the held SSE) + the broker-server.
+  if (nodeBrokerClient && typeof nodeBrokerClient.stop === 'function') {
+    try { nodeBrokerClient.stop(); } catch { /* best-effort */ }
+  }
+  if (brokerServer && typeof brokerServer.close === 'function') {
+    try { brokerServer.close(); } catch { /* best-effort */ }
+  }
   clearDaemonState(process.pid);
   process.exit(code);
 }
@@ -3618,4 +4010,10 @@ module.exports = {
   decideSurfaceGc,                // #17: surface-liveness verdict→action (incl. INV-17 unknown→skip)
   applySurfaceMismatchProbe,      // surface_mismatched debounce + payload helper (deps DI: emit/clock)
   classifyPeerLaneInject,         // #533 Phase 2: pure peer-lane inject policy verdict
+  // #42 broker MVP (W3/T5): DI-seamed broker wiring (deps override factories/env/readFile).
+  brokerEnv,                      // env→broker config resolver (default-OFF when absent)
+  mountBrokerMode,                // broker-mode: mount createBrokerServer at /broker/* + fail-fast
+  loadNodeBrokerConfig,           // node-mode: resolve broker.json / env config (or null)
+  startNodeBrokerClient,          // node-mode: start createBrokerClient (default-OFF; in-process deliver)
+  deliverInjectionToSession,      // §4.3: the in-process delivery wired into the broker-client
 };